zhenkun26/dsh-repo-atlas

dsh-repo-atlas / RepoAtlas 代码星图

一个帮助 AI coding agent 基于证据理解代码库，并在有界生命周期中审阅变更提案的 DeepSeek Harness 插件。
一个帮助 AI coding agent 基于证据理解代码库，并在有界生命周期中审阅变更提案的 DeepSeek Harness 插件。

CI
License: MIT
Node.js 22+

一分钟了解 / 一分钟了解

它是什么？ / 它是什么？

dsh-repo-atlas 是一个 DeepSeek Harness 插件，用于项目接手、基于证据的代码库分析和可审阅的变更提案。它帮助 agent 回答：“这个仓库有什么？”、“哪些结论有文件证据支持？”以及“一个变更提案目前处于什么状态？”
dsh-repo-atlas 是一个 DeepSeek Harness 插件，用于项目接手、基于证据的代码库分析和可审阅的变更提案。它帮助 agent 回答：“这个仓库有什么？”、“哪些结论有文件证据支持？”以及“一个变更提案目前处于什么状态？”

它做什么？ / 它做什么？

- 在路径、内容、敏感文件和预算限制下扫描已确认的 workspace。在路径、内容、敏感文件和预算限制下扫描已确认的 workspace。
- 生成结构化证据、Markdown 报告、架构观察和推荐阅读顺序。生成结构化证据、Markdown 报告、架构观察和推荐阅读顺序。
- 追踪仅限当前 session 的提案、补丁审阅/验证、隔离 commit、landing preflight、恢复建议和 release preflight。追踪仅限当前 session 的提案、补丁审阅/验证、隔离 commit、landing preflight、恢复建议和 release preflight。

它不会自动做什么？ / 它不会自动做什么？

默认路径是只读的。它不会静默生成或应用补丁、commit、merge、landing、push、publish、安装依赖、访问网络或上传代码。受控动作必须显式启用，并通过对应审批和 sandbox 检查。
默认路径是只读的。它不会静默生成或应用补丁、commit、merge、landing、push、publish、安装依赖、访问网络或上传代码。受控动作必须显式启用，并通过对应审批和 sandbox 检查。

提供什么 / 提供什么

理解陌生代码库 / 理解陌生代码库

- 项目接手分析：技术栈、入口、重要目录、测试、配置和推荐阅读顺序。项目接手分析：技术栈、入口、重要目录、测试、配置和推荐阅读顺序。
- 证据优先的结论：区分文件直接支持的观察和文本推断，并明确保留 partial/unknown 状态。证据优先的结论：区分文件直接支持的观察和文本推断，并明确保留 partial/unknown 状态。
- 有界 TypeScript/JavaScript 语法确认：确认选定的 import、声明和关系，但不执行仓库代码。有界 TypeScript/JavaScript 语法确认：确认选定的 import、声明和关系，但不执行仓库代码。
- 仅限 session 的增量复用：只在当前 Harness session 内复用兼容证据。仅限 session 的增量复用：只在当前 Harness session 内复用兼容证据。

审阅变更提案 / 审阅变更提案
- 为仅限当前 session 的提案定义明确目标和意图。为仅限当前 session 的提案定义明确目标和意图。
- 在生命周期到达对应状态后审阅、导出和验证有界补丁。在生命周期到达对应状态后审阅、导出和验证有界补丁。
- 分别观察 live worktree 状态、commit 就绪情况、landing 关系、恢复建议和 release 就绪情况。分别观察 live worktree 状态、commit 就绪情况、landing 关系、恢复建议和 release 就绪情况。
- 明确区分“准备审阅”和“已经应用”。明确区分“准备审阅”和“已经应用”。

现有 Harness 工具名保持稳定：repo_atlas_analyze、repo_atlas_change_proposal，以及 opt-in 的 repo_atlas_controlled_action。
现有 Harness 工具名保持稳定：repo_atlas_analyze、repo_atlas_change_proposal，以及 opt-in 的 repo_atlas_controlled_action。

快速开始 / 快速开始

环境要求 / 环境要求

- 本地开发和检查需要 Node.js 22 或更高版本。本地开发和检查需要 Node.js 22 或更高版本。
- 加载插件需要一个兼容的 DeepSeek Harness checkout。加载插件需要一个兼容的 DeepSeek Harness checkout。
- 经审阅的 live smoke 合同使用 Node.js 24.x、pnpm 11.7.0，以及 reference/harness-compatibility.json 中的 exact revision。经审阅的 live smoke 合同使用 Node.js 24.x、pnpm 11.7.0，以及 reference/harness-compatibility.json 中的 exact revision。

从源码 checkout 加载插件 / 从源码 checkout 加载插件

当前项目采用源码优先且保持 private。先构建本地 checkout，再将其添加到 Harness profile。GitHub 仓库名为 dsh-repo-atlas；产品品牌仍为 RepoAtlas，包名和 Harness 中显示的 bundle 名称分别是 dsh-repo-atlas 与 dsh-repo-atlas/harness。
当前项目采用源码优先且保持 private。先构建本地 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

在 Harness Web UI 的插件列表中，应看到 dsh-repo-atlas/harness。bundle patch 只负责加载适配器，不会修改 Harness 核心。
在 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

verify:built-artifact 会创建 task-owned tarball，在临时 consumer 中离线安装，并 import dsh-repo-atlas 与 dsh-repo-atlas/harness。它只是本地产物证据，不代表 npm 发布。
verify:built-artifact 会创建 task-owned tarball，在临时 consumer 中离线安装，并 import dsh-repo-atlas 与 dsh-repo-atlas/harness。它只是本地产物证据，不代表 npm 发布。
维护者可以运行完整仓库门禁：

npm run validate:openspec
npm run verify:release-preflight
git diff --check

这些检查是只读的候选检查，不会创建补丁、tag、release、npm publication、push、deployment 或 cleanup。

工作方式

普通分析路径保持显式：

目标 → 澄清 → Policy Gate → 有界只读分析 → 验证 → 报告

对于变更相关工作，session 还可以提供额外的生命周期观察：

提案 → 补丁审阅 → 验证 → 隔离 Commit → Landing Preflight → Release Preflight

这些名称描述的是相互独立的状态。proposal、preflight 或 readiness assessment 不代表代码已经生成、应用、commit、landing、release 或 publish。

安全边界

| 范围 | 行为 |
| --- | --- |
| 核心分析 | 遵守路径、内容、敏感文件和资源预算策略的只读检查。 |
| Session 状态 | evidence cache、proposal registry、event history 和 preflight assessment 仅限当前 session，并以 detached 观察返回。 |
| 受控动作 | 默认关闭；启用后必须使用固定 recipe、显式审批、sandbox 强制和有界脱敏输出。 |
| Git 生命周期 | 隔离本地操作保持有界；不提供自动冲突解决、远程访问、rollback 或 push。 |
| 网络与依赖 | 运行时不抓取仓库、不调用远程服务、不安装依赖、不上传代码。 |
| 失败行为 | 能力缺失、审批拒绝、输入无效、预算耗尽和不确定 postcondition 会故障关闭，或明确保留为 partial。 |

兼容性与支持

- 本地开发基线：Node.js 22+。
- 默认 CI 矩阵：Node.js 22.x 和 24.x。
- 已审阅的 live Harness smoke：Node.js 24.x、pnpm 11.7.0 和 revision 47f943859bef60e4160492346772ded9b24f765a。经审阅的 live Harness smoke：Node.js 24.x、pnpm 11.7.0 和 revision 47f943859bef60e4160492346772ded9b24f765a。
- 变化中的 master 分支仅用于导航；manifest 中的 exact revision 才是证据合同。变化中的 master 分支仅用于导航；manifest 中的 exact revision 才是证据合同。
- 支持为 best-effort，不提供 SLA；不声称兼容任意 Harness 版本。支持为 best-effort，不提供 SLA；不声称兼容任意 Harness 版本。

将插件集成到其他工作流前，请阅读 support policy 和 Harness compatibility manifest。
将插件集成到其他工作流前，请阅读 support policy 和 Harness compatibility manifest。

分发与许可证 / 分发与许可证

包仍保持 private: true，并采用源码优先分发。本地 built tarball 可用于诊断和集成检查，但不是已发布的 npm 包。Git tag、GitHub Release、npm publication 和 deployment 是相互独立的决策。
包仍保持 private: true，并采用源码优先分发。本地 built tarball 可用于诊断和集成检查，但不是已发布的 npm 包。Git tag、GitHub Release、npm publication 和 deployment 是相互独立的决策。

现有 v0.1.1 GitHub Release 仍是较早的 source-first 快照。当前 checkout 可以生成经验证的本地 tarball，但不代表存在 npm 包或新的 GitHub Release；历史 v0.1.0 和 v0.1.1 tag 保持不可移动。
现有 v0.1.1 GitHub Release 仍是较早的 source-first 快照。当前 checkout 可以生成经验证的本地 tarball，但不代表存在 npm 包或新的 GitHub Release；历史 v0.1.0 和 v0.1.1 tag 保持不可移动。

RepoAtlas 使用 MIT License 发布。保留 MIT 版权声明、许可证文本和免责声明后，允许使用、修改和再分发。
RepoAtlas 使用 MIT License 发布。保留 MIT 版权声明、许可证文本和免责声明后，允许使用、修改和再分发。

在引用、集成、文档说明或基于本项目衍生时，请标注 RepoAtlas / 代码星图 并链接 。这项来源说明单独记录在 NOTICE.md 中，不会向 MIT License 增加额外法律条件。
在引用、集成、文档说明或基于本项目衍生时，请标注 RepoAtlas / 代码星图 并链接 。这项来源说明单独记录在 NOTICE.md 中，不会向 MIT License 增加额外法律条件。

开发 API / 开发 API

核心 API 可以从源码 checkout 调用，用于实验和测试：
核心 API 可以从源码 checkout 调用，用于实验和测试：

import { createGoalSpec, resolveStart, analyzeRepository, generateReport } from './src/index.ts'

const goal = resolveStart(createGoalSpec({ intent: 'onboarding' }), 'direct')typescript
const session = await analyzeRepository(goal, '/path/to/workspace')
const report = generateReport(session)

console.log(report.markdown)

这里仍遵守相同的证据、路径、敏感内容和预算策略。原始 TypeScript package loading 不属于 built artifact 合同。
这里仍遵守相同的证据、路径、敏感内容和预算策略。原始 TypeScript package loading 不属于 built artifact 合同。

文档 / 文档导航

- Harness 集成 / Harness 集成
- 安全边界 / 安全边界
- 支持策略 / 支持策略
- 源码优先发布流程 / 源码优先发布流程
- 公开发布清单 / 公开发布清单
- 路线与限制 / 路线与限制
- v1 使用说明 / v1 使用说明
- 贡献指南 / 贡献指南
- 安全报告 / 安全报告
- 行为规范 / 行为规范
- 来源说明 / 来源说明