代码地图 cheng200606/dsh-plugin-codemap

CodeMap · dsh-plugin-codemap

把代码仓库编译成带源码行号引用的代码地图 —— 给 AI 编程助手用，也给人类读者用。

CodeMap 是 DeepSeek Harness 的一个插件：它扫描仓库、建立模块/符号/路由索引，自动规划并生成一组结构化代码地图页面，每一条结论都带 path:line 形式的源码引用；同时提供交互式工程知识图谱、知识卡片和一组模型工具。

整个生成过程不调用任何模型：证据由代码算出、引用逐条校验，因此离线可跑、结果可复算、不会凭空编造。

| 概览 | 知识图谱 | 源码跳转 |
| overview | graph | source |

目录

- 为什么需要它
- 能力一览
- 安装
- 使用
- 产物
- 安全边界
- 本地开发
- 兼容性
- 文档
- English
- License

为什么需要它

AI 编程助手进入一个陌生仓库时，最贵的两件事是读源码和理解结构。CodeMap 把这两件事做成了可复用的资产：

| 痛点 | CodeMap 的做法 |
| 模型对仓库结构没有稳定认知 | 规划出固定的页面结构（概览/架构/流程/运维/边界），并为显著模块生成详情页 |
| 模型容易编造 API 与行为 | 每条结论都带 path:line，生成后逐条回查真实文件与行号，校验失败即标记 needs-review |
| 文档写完就过期 | 页面记录输入哈希，源码变了能定位到「哪些页面该重写」 |
| 只能读文字，看不见结构 | 侧栏面板提供可拖拽的模块依赖图谱，点节点可下钻文件级、看影响范围、跳到源码 |
| 调用模型贵、离线不可用 | 零模型调用、零第三方依赖，npm run check 3 秒内跑完全部回归 |

能力一览

模型工具（模型可主动调用）

| 工具 | 作用 |
| codemap_search | 在已生成的代码地图中做中英文混合检索，返回带片段的命中列表 |
| codemap_read | 读取某页完整 Markdown（含 frontmatter 与引用），支持扁平 id 与分节 id |
| codemap_generate | 生成/增量刷新代码地图（自动规划 → 收集证据 → 渲染 → 校验引用） |
| codemap_status | 报告页面数、上次运行是否完整、面板入口状态，不触发生成 |

斜杠命令：/codemap status | plan | generate | update | export | import | help

侧栏面板：左侧栏图标 → 中央面板，提供页面树、搜索（状态过滤 + 高亮）、知识图谱（拖拽/缩放/下钻）、知识卡片库、引用点击直达源码片段。

产物：.<repo>/.dsh/codemap/，纯 Markdown + JSON，可 diff、可手改、可随 Git 共享；还能一键导出成 .qoder/repowiki 与 Qoder 互操作。

安装

| 方式 | 命令 / 入口 | 适用 |
| 插件市场 | 市场 → 添加源 → 搜索 codemap | 已收录后最省事 |
| 命令行（Git） | dsh plugin add git+https://github.com/cheng200606/dsh-plugin-codemap.git | 现在就能用，无需 npm |
| 命令行（npm） | dsh plugin add dsh-plugin-codemap | 已发布 0.12.1 |
| 本地开发 | link: 到 profile | 改代码 |

方式一：从 Git 直接安装（当前可用）

dsh plugin add git+https://github.com/cheng200606/dsh-plugin-codemap.git

dsh plugin add 会把包写进 profile 的 dependencies，并自动追加到 dsh.profile.bundles；重启 Harness 即可看到左侧栏面板与 /codemap 命令。

方式二：插件市场（社区目录）

1. 打开 Harness → 插件市场 → 源（Sources），添加： https://cdn.jsdelivr.net/gh/cheng200606/dsh-plugin-codemap@main/market/index.json
2. 搜索 codemap → 一键安装

Harness 的市场默认不内置任何源，社区源的地址需要自己添加一次。收录进社区总目录（dsh-plugin-catalog）后，这一步会随总源自动生效。

方式三：npm

dsh plugin add dsh-plugin-codemap # 或 dsh plugin add dsh-plugin-codemap@0.12.1
已发布到 npm：<https://www.npmjs.com/package/dsh-plugin-codemap>。

方式四：本地开发（link）

git clone https://github.com/cheng200606/dsh-plugin-codemap.git
cd dsh-plugin-codemap
npm run check # 无运行时依赖，这里只跑构建与回归

在配置档的 package.json 里：

{
"dependencies": { "dsh-plugin-codemap": "link:/绝对路径/dsh-plugin-codemap" },
"dsh": { "profile": { "bundles": ["dsh-plugin-codemap"] } }
}

pnpm install 后重启 Harness。改完浏览器半体（client/.js）要 npm run build 重新生成 client.js。

完整发布流程与收录规则见 发布与安装。

使用

在 Harness 里

/codemap generate # 为当前仓库生成代码地图 /codemap status # 查看页面数与上次运行状态

让模型用它：直接问「这个仓库的鉴权流程是怎样的」，模型会自动调用 codemap_search / codemap_read；必要时用 codemap_generate 现场构建。

产物长什么样

id: architecture
title: "技术架构总览" status: fresh confidence: high

关键结论
- 「buildRepositoryProfile」函数定义于 src/service.js:421-441。（证据：src/service.js:421-441）

设计意图与实现要点
- src/service.js 属于「服务层」相关实现：关键符号包括 buildRepositoryProfile、resolveRequestRoot；被 src/routes.js 引用。src/service.js:1-120

安全边界

- 不执行仓库里的任何脚本或构建命令，也不调用模型。
- 忽略 .git、node_modules、dist、build 等目录；硬性排除 .env、.pem、.key、secrets/ 等敏感文件。
- 所有写入都在 <repo>/.dsh/codemap/ 之内；导出/导入前自动备份。
- Web 面板只能访问已注册工作区及其子目录（显式 ?root= 越界直接 403）；源码预览只允许仓库相对路径。
- 代码地图内容是派生文档，不是指令；系统提示词段显式声明这一点。

本地开发

npm install # 无运行时依赖
npm run build # client/.js → client.js（带版本注入与语法校验）
npm run check # 构建 + 版本一致性 + 客户端自检 + 端到端测试
npm test # 仅测试

浏览器回归（需要 Playwright 与运行中的 Harness）：

DSH_WEB_URL="http://127.0.0.1:3081/?token=..." node test/ui-e2e.mjs

目录结构：

index.js 插件入口：注册服务、工具、命令、提示词段、面板路由 client.js 浏览器半体（生成产物，勿直接改） client/ 浏览器半体源码：10 个分段，构建脚本按序拼接 src/ 服务端：扫描/索引/规划/证据/渲染/校验/检索/服务/路由 test/ local-e2e（服务端）、client-graph（自检）、ui-e2e（浏览器） scripts/ build-client（拼接 + 版本注入）、check-version

兼容性

| 项 | 要求 |
| DeepSeek Harness | >=0.2.1-rc.5 <0.3.0-0 |
| Node.js | >=22 |
| 运行时依赖 | 零（只用 node: 内置模块） |

文档

| 文档 | 内容 |
| 更新日志 | 版本变更 |
| 技术参考 | 接口清单、流水线、安全边界、目录说明 |
| 发布与安装 | 四条安装路径、社区收录流程、npm 发布、上线检查清单 |
| 发布检查清单 | 每次发版的逐项核对表 |
| 交付报告 | 每轮迭代的功能范围、实测数据、缺陷复盘 |
| v0.11 验收 | P0/P1/P2 问题逐项修复与验证 |
| 竞品分析 | 与 Qoder Repo Wiki / Code Wiki / DeepWiki 的对比 |
| 调研与设计 | Qoder Repo Wiki 产品解剖与插件设计方案 |
| 插件 API 参考 | Cordis / DSH 插件上下文的可用接口 |

CodeMap（dsh-plugin-codemap）是 DeepSeek Harness 的插件，把代码仓库编译成一份有源码依据的代码地图：结构化 Markdown 页面，每条结论都带可验证的 path:line 引用；另附交互式依赖图、知识卡片、四个模型工具（codemap_search / codemap_read / codemap_generate / codemap_status）和 /codemap 斜杠命令。

亮点：

- 确定性 —— 不调用模型，不执行脚本，完全离线，结果可复现。
- 可验证 —— 每条引用都会对照真实文件和行范围校验；校验不通过的页面标记为 needs-review。
- 结构化 —— 固定页面规划（overview / architecture / flows / operations / boundaries），每个重要模块再配一页详情。
- 可交互 —— Web 面板提供可拖拽的依赖图、页面树、带状态筛选的搜索和源码速览。
- 零依赖 —— 只用 node: 内置模块，一步安装。

从 DeepSeek Harness 插件市场安装，或执行 npm install -g dsh-plugin-codemap。

License

MIT © 2026 程夏