前言¶
在 DeepSeek Harness (DSH) 的插件化生态中，让 AI 编码代理精准理解一个陌生的代码库，并在审阅变更时保持严格的边界控制，是开发过程中的常见需求。dsh-repo-atlas 是为此设计的插件，它帮助代理基于证据分析仓库，并在有界生命周期内审阅变更提案。
这是什么¶
dsh-repo-atlas 是一个 DeepSeek Harness 插件，由 zhenkun26 维护。它旨在解决代码库理解缺乏结构化证据、变更审阅缺乏生命周期管理的问题。该插件通过提供证据优先的结论和有界的操作策略，让 AI 能够安全地进行仓库接手和变更审阅。
核心功能¶
仓库分析¶
插件扫描已确认的 workspace，遵循路径、内容、敏感文件和预算限制。它生成结构化证据、Markdown 报告、架构观察和推荐阅读顺序。具体包括：
* Onboarding 分析：识别技术栈、入口点、重要目录、测试、配置，并提供推荐阅读顺序。
* 证据优先的结论：将文件支持的观察与文本推断区分开，明确保留部分或未知状态。
* 有界语法确认：确认选定的 import、声明和关系，不执行仓库代码。
* Session 增量复用：仅在当前 Harness session 内复用兼容证据。
变更提案与生命周期¶
插件追踪仅限当前 session 的变更流程，包括：
* 定义明确的目标和意图。
* 审阅、导出和验证有界补丁。
* 检查 live worktree 状态、commit 就绪情况、landing 关系、recovery guidance 和 release readiness。
* 管理隔离 commit、landing preflight、recovery guidance 和 release preflight。
安全边界¶
为了确保安全，插件默认以只读模式运行，并严格限制操作范围：
* 默认只读：默认路径为只读，不静默生成或应用补丁、commit、merge、land、push、publish、安装依赖、访问网络或上传代码。
* 受控动作：受控动作默认禁用。启用时需要固定 recipe、显式审批、sandbox 强制和有界脱敏输出。
* Session 状态：证据缓存、提案注册表、事件历史和 preflight 评估仅限当前 session，并以 detached 观察返回。
* Git 生命周期：隔离本地操作是有界的，不提供自动冲突解决、远程访问、rollback 或 push。
安装与启用¶
加载此插件需要兼容的 DeepSeek Harness checkout。安装步骤如下：
- 构建插件源码。
- 将插件路径添加到 Harness profile。
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
在 Harness Web UI 的插件列表中查找 dsh-repo-atlas/harness。
本地检查¶
本地开发和检查需要 Node.js 22 或更高版本。开发者可以运行以下命令验证代码质量：
cd /absolute/path/to/dsh-repo-atlas
npm ci
npm test
npm run typecheck
npm run lint
npm run build
维护者可以运行完整仓库门禁：
npm run validate:openspec
npm run verify:release-preflight
git diff --check
适用场景与注意¶
该插件适合需要在 AI 代理环境中进行结构化仓库接手和受控变更审阅的场景。使用时需注意：
* 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
* 默认禁用受控动作，如需启用，必须配置固定 recipe、显式审批和 sandbox 检查。
* 插件仅提供状态观察和建议，不执行代码生成、提交或发布操作。
