dsh-repo-atlas
DeepSeek Harness 插件，用于基于证据的代码仓库分析以及可审查、有边界的变更提案。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:zhenkun26/dsh-repo-atlas#b8b4d21c6ba687aa8354d77da419921c97e0088dRepo Atlas 以 dsh-repo-atlas 发布，当前版本为 0.1.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A DeepSeek Harness plugin that helps an AI coding agent understand a repository from evidence, then review proposed changes through a bounded lifecycle.
一个帮助 AI coding agent 基于证据理解代码库，并在有界生命周期中审阅变更提案的 DeepSeek Harness 插件。
What is it? / 它是什么？
dsh-repo-atlas is a DeepSeek Harness plugin for repository onboarding, evidence-backed codebase analysis, and reviewable change proposals. It helps an agent answer: “What is in this repository?”, “Which conclusions are directly supported by files?”, and “What is the current state of a proposed change?”
dsh-repo-atlas 是一个 DeepSeek Harness 插件，用于项目接手、基于证据的代码库分析和可审阅的变更提案。它帮助 agent 回答：“这个仓库有什么？”、“哪些结论有文件证据支持？”以及“一个变更提案目前处于什么状态？”
What does it do? / 它做什么？
What does it not do automatically? / 它不会自动做什么？
The default path is read-only. It does not silently generate or apply patches, commit, merge, land, push, publish, install dependencies, access the network, or upload code. Controlled actions are opt-in and require the relevant approval and sandbox checks.
默认路径是只读的。它不会静默生成或应用补丁、commit、merge、landing、push、publish、安装依赖、访问网络或上传代码。受控动作必须显式启用，并通过对应审批和 sandbox 检查。
The existing Harness tool names remain stable: repo_atlas_analyze, repo_atlas_change_proposal, and the opt-in repo_atlas_controlled_action.
现有 Harness 工具名保持稳定：repo_atlas_analyze、repo_atlas_change_proposal，以及 opt-in 的 repo_atlas_controlled_action。
After repo_atlas_analyze completes in a Harness session, use these native tools:
在 Harness 会话中完成 repo_atlas_analyze 后，可使用以下原生工具：
| Tool / 工具 | Example input / 输入示例 | Result / 结果 |
|---|---|---|
repo_atlas_search | {"query":"server","limit":10} | Ranked evidence ids, paths, locators and excerpts / 排序后的证据 ID、路径、定位和摘录 |
repo_atlas_impact | {"targets":["src/server.ts"],"maxDepth":3,"limit":50} | Possible dependents and evidence chains / 潜在依赖方与证据链 |
Queries read the latest retained snapshot in the exact calling session. They do not
refresh files. Rerun analysis after edits. Empty results do not prove no impact;
aliases, dynamic imports, runtime calls, and unobserved files remain outside this
file-level analysis.
查询只读取当前调用会话保留的最新分析快照，不刷新文件；修改后需重新分析。空结果不代表没有影响；别名、动态导入、运行时调用和未观察文件不在本轮文件级分析范围内。
The current Harness source review and implementation stages are documented in the
October plan. The reviewed 0.2.1-alpha.1 source is
experimentally verified on macOS through its native tool runtime and authenticated
Web startup; the historical accepted pin remains unchanged.
当前 Harness 源码审查和实施阶段见十月重规划。0.2.1-alpha.1 已在 macOS 通过原生工具运行和带认证的 Web 启动验证；历史正式兼容 pin 保持不变。
Analysis defaults to readerMode: "auto": use the configured Harness filesystem
when present, otherwise the local read-only reader. A selected provider failure
blocks analysis instead of falling back. Evidence paths stay repository-relative.
Provider evidence authorizes local Git/checks only when host mapping is explicitly
verified; older providers without that capability remain readable. Use explicit
readerMode: "local" for an intentionally local workflow.
分析默认使用 readerMode: "auto"：有 Harness 文件系统时使用该服务，否则使用本地只读读取器。
选定服务失败会阻止分析，不会退回本地读取。证据保留仓库相对路径；只有明确验证宿主映射后，
服务证据才能用于本地 Git 或检查。旧服务没有映射能力时仍可读取；有意使用本地工作流时可明确设置 readerMode: "local"。
Full redacted source is retained separately from display excerpts within the
20 MiB default source-material cap. Search ranks by lexical score, then prefers
distinct files. cacheValidation: "metadata" permits version/metadata reuse;
"content" rereads within the same budgets. Content hashes identify redacted
snapshots, not runtime correctness. Root .gitignore supports a bounded positive
pattern subset; negation, escapes, character classes, whitespace patterns and
nested rules remain explicit incomplete coverage. Sensitive-path policy and
configured exclusions still apply.
完整脱敏源码与展示摘要分开保存，默认材料上限为 20 MiB。搜索按词法分数排序，优先返回不同文件。
cacheValidation: "metadata" 允许版本或元数据复用；"content" 在同样预算内重新读取。
内容哈希标识脱敏快照，不证明运行正确性。根目录 .gitignore 仅支持有界正向模式；否定、转义、
字符类、含空白模式及嵌套规则会明确标注为覆盖不完整。敏感路径规则和配置排除项仍然生效。
Optional plugin configuration / 可选插件配置：
{
"readerMode": "auto",
"cacheValidation": "metadata",
"respectGitIgnore": true,
"symbols": { "enabled": true, "timeoutMs": 5000, "maxResults": 50 }
}
repo_atlas_symbols is registered only with symbols.enabled: true. It uses
Harness's configured LSP and installs no server. Example input:
{"operation":"findReferences","sourcePath":"src/server.ts","line":3,"character":8}.
Supported operations are goToDefinition, findReferences, goToImplementation
and hover. Coordinates are one-based UTF-16; returned ranges are half-open.
The query source must match retained material and have an unredacted cursor basis.
External, sensitive and unobserved results are filtered. Missing services, changed
source, cancellation and timeout return unavailable. Live LSP/UI acceptance is a
separate gate.
仅在 symbols.enabled: true 时注册 repo_atlas_symbols，使用 Harness 已配置的 LSP，不安装服务器。
输入示例与支持操作如上；坐标为从 1 开始的 UTF-16，返回区间为左闭右开。
查询源码须与保留材料一致，且脱敏不能改变定位坐标。外部、敏感和未观察路径会被过滤；
缺少服务、源码变化、取消或超时会返回不可用。真实 LSP 与界面验收仍是独立门禁。
The repository is public and distribution remains source-first. package.json keeps private: true to prevent npm publication. Build the local checkout, then add it to a Harness profile. The GitHub repository is named dsh-repo-atlas; the product brand remains RepoAtlas, and the package and visible Harness bundle are named dsh-repo-atlas and dsh-repo-atlas/harness.
仓库已公开，分发仍采用源码优先；package.json 保留 private: true 以防止 npm 发布。先构建本地 checkout，再将其添加到 Harness profile。GitHub 仓库名为 dsh-repo-atlas；产品品牌仍为 RepoAtlas，包名和 Harness 中显示的 bundle 名称分别是 dsh-repo-atlas 与 dsh-repo-atlas/harness。
git clone https://github.com/zhenkun26/dsh-repo-atlas.git
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm run build
cd /absolute/path/to/deepseek-harness
pnpm install
pnpm dsh plugin --profile web add /absolute/path/to/dsh-repo-atlas
pnpm dsh web
In the Harness Web UI, look for dsh-repo-atlas/harness in the plugin list. The bundle patch loads the adapter; it does not modify Harness core.
在 Harness Web UI 的插件列表中，应看到 dsh-repo-atlas/harness。bundle patch 只负责加载适配器，不会修改 Harness 核心。
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm test
npm run typecheck
npm run lint
npm run build
npm run verify:built-artifact
npm run evaluate:repository
Builds first create a fresh package under ignored .codex/artifacts/build-* and retain it on success or failure. Normal build then updates root dist/; unexpected prior files or symlinks stop that projection. Use npm run build -- --isolated to build a separate package without projecting root dist/; its printed package path can be loaded into Harness. Artifacts are retained for inspection and require user-managed cleanup.
构建先在 ignored .codex/artifacts/build-* 下生成独立 package，成功或失败均保留。普通构建随后更新根目录 dist/；发现不属于本次构建的旧文件或符号链接时会停止写入。可用 npm run build -- --isolated 生成独立 package，不更新根目录 dist/；输出的 package 路径可以加载到 Harness。产物保留供检查，清理需由用户管理。
verify:built-artifact packs only a fresh isolated package, installs it offline into a new consumer with lifecycle scripts disabled, and imports dsh-repo-atlas and dsh-repo-atlas/harness. It retains all outputs and provides local artifact evidence, not npm publication.
verify:built-artifact 仅打包新的独立 package，禁用 lifecycle scripts 后在全新 consumer 中离线安装，并 import dsh-repo-atlas 与 dsh-repo-atlas/harness。它保留全部产物，只提供本地产物证据，不代表 npm 发布。
evaluate:repository records default-budget precision/recall and coverage using a synthetic labelled corpus. Low-recall results remain visible; the labels are pending human review.
evaluate:repository 使用合成标注语料记录默认预算下的精确率、召回率和覆盖状态，保留低召回结果；标签仍待人工审阅。
Maintainers can run the full repository gates with:
维护者可以运行完整仓库门禁：
npm run validate:openspec
npm run verify:release-preflight
git diff --check
These checks are read-only candidate checks. They do not create patches, tags, releases, npm publications, pushes, deployments, or cleanup operations.
这些检查是只读的候选检查，不会创建补丁、tag、release、npm publication、push、deployment 或 cleanup。
The normal analysis path is deliberately explicit:
普通分析路径保持显式：
Goal → Clarify → Policy Gate → Bounded Read-only Analysis → Verify → Report
目标 → 澄清 → Policy Gate → 有界只读分析 → 验证 → 报告
For change-oriented work, the session can expose additional lifecycle observations:
对于变更相关工作，session 还可以提供额外的生命周期观察：
Proposal → Patch Review → Verification → Isolated Commit → Landing Preflight → Release Preflight
提案 → 补丁审阅 → 验证 → 隔离 Commit → Landing Preflight → Release Preflight
These names describe separate states. A proposal, preflight, or readiness assessment is not proof that code was generated, applied, committed, landed, released, or published.
这些名称描述的是相互独立的状态。proposal、preflight 或 readiness assessment 不代表代码已经生成、应用、commit、landing、release 或 publish。
| Area / 范围 | Behavior / 行为 |
|---|---|
| Core analysis 核心分析 | Read-only inspection with path, content, sensitive-file, and resource-budget policies. 遵守路径、内容、敏感文件和资源预算策略的只读检查。 |
| Session state Session 状态 | Evidence cache, proposal registry, event history, and preflight assessments are session-only and detached. evidence cache、proposal registry、event history 和 preflight assessment 仅限当前 session，并以 detached 观察返回。 |
| Controlled actions 受控动作 | Disabled by default; when enabled, fixed recipes, explicit approval, sandbox enforcement, and bounded redacted output are required. 默认关闭；启用后必须使用固定 recipe、显式审批、sandbox 强制和有界脱敏输出。 |
| Git lifecycle Git 生命周期 | Isolated local operations are bounded; automatic conflict resolution, remote access, rollback, and push are not provided. 隔离本地操作保持有界；不提供自动冲突解决、远程访问、rollback 或 push。 |
| Network and dependencies 网络与依赖 | The runtime does not fetch repositories, call remote services, install dependencies, or upload code. 运行时不抓取仓库、不调用远程服务、不安装依赖、不上传代码。 |
| Failure behavior 失败行为 | Missing capabilities, denied approval, invalid input, budget exhaustion, and uncertain postconditions fail closed or remain explicitly partial. 能力缺失、审批拒绝、输入无效、预算耗尽和不确定 postcondition 会故障关闭，或明确保留为 partial。 |
47f943859bef60e4160492346772ded9b24f765a.47f943859bef60e4160492346772ded9b24f765a。master branch is navigation context only; the exact manifest revision is the evidence contract.master 分支仅用于导航；manifest 中的 exact revision 才是证据合同。Read the support policy and Harness compatibility manifest before integrating the plugin into another workflow.
将插件集成到其他工作流前，请阅读 support policy 和 Harness compatibility manifest。
The package remains private: true and source-first. The local built tarball is useful for diagnosis and integration checks, but it is not a published npm package. Git tags, GitHub Releases, npm publication, and deployment are separate decisions.
包仍保持 private: true，并采用源码优先分发。本地 built tarball 可用于诊断和集成检查，但不是已发布的 npm 包。Git tag、GitHub Release、npm publication 和 deployment 是相互独立的决策。
The existing v0.1.1 GitHub Release remains an earlier source-first snapshot. The current checkout can produce a verified local tarball, but no npm package or new GitHub Release is implied; historical v0.1.0 and v0.1.1 tags remain immutable.
现有 v0.1.1 GitHub Release 仍是较早的 source-first 快照。当前 checkout 可以生成经验证的本地 tarball，但不代表存在 npm 包或新的 GitHub Release；历史 v0.1.0 和 v0.1.1 tag 保持不可移动。
RepoAtlas is released under the MIT License. Use, modification, and redistribution are allowed when the MIT copyright notice, license text, and disclaimer are retained.
RepoAtlas 使用 MIT License 发布。保留 MIT 版权声明、许可证文本和免责声明后，允许使用、修改和再分发。
When citing, integrating, documenting, or deriving from this project, please identify RepoAtlas / 代码星图 and link to https://github.com/zhenkun26/dsh-repo-atlas. This provenance request is recorded separately in NOTICE.md and does not add legal conditions to the MIT License.
在引用、集成、文档说明或基于本项目衍生时，请标注 RepoAtlas / 代码星图 并链接 https://github.com/zhenkun26/dsh-repo-atlas。这项来源说明单独记录在 NOTICE.md 中，不会向 MIT License 增加额外法律条件。
Dependency observations expose optional moduleSpecifierExact. Graph resolution requires true; older producers without the flag remain unresolved. Exact values preserve whitespace within the existing 160 UTF-16 code-unit bound, while summaries remain display text. Schema-3 caches are invalidated and reparsed under schema 4.
模块观察新增可选 moduleSpecifierExact；只有 true 才可用于依赖解析，旧 producer 没有此标记时保留为未解析。精确值在既有 160 个 UTF-16 单元上限内保留空白，摘要仅用于展示；schema-3 缓存失效后在 schema 4 下重新解析。
The core API can be used from a source checkout for experiments and tests:
核心 API 可以从源码 checkout 调用，用于实验和测试：
import { createGoalSpec, resolveStart, analyzeRepository, generateReport } from './src/index.ts'
const goal = resolveStart(createGoalSpec({ intent: 'onboarding' }), 'direct')
const session = await analyzeRepository(goal, '/path/to/workspace')
const report = generateReport(session)
console.log(report.markdown)
The same evidence, path, sensitive-content, and budget policies apply. Raw TypeScript package loading is not the built artifact contract.
这里仍遵守相同的证据、路径、敏感内容和预算策略。原始 TypeScript package loading 不属于 built artifact 合同。