CodeMap · dsh-plugin-codemap

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

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

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

概览	知识图谱	源码跳转

---

目录

• 为什么需要它
• 能力一览
• 安装
• 使用
• 产物
• 安全边界
• 本地开发
• 兼容性
• 文档
• 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        # 无运行时依赖，这里只跑构建与回归

在 profile 的 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 插件上下文的可用接口

English

CodeMap (dsh-plugin-codemap) is a DeepSeek Harness plugin that compiles a code repository into a source-grounded code map: structured Markdown pages where every claim carries a verifiable path:line citation, plus an interactive dependency graph, knowledge cards, four model tools (codemap_search / codemap_read / codemap_generate / codemap_status) and the /codemap slash command.

Highlights:

• Deterministic — no model calls, no scripts executed, fully offline and reproducible.
• Verifiable — every citation is checked against the real file and line range; pages that fail verification are marked needs-review.
• Structured — a stable page plan (overview / architecture / flows / operations / boundaries) plus one detail page per significant module.
• Interactive — a Web panel with a pannable dependency graph, page tree, search with status filters and source peek.
• Zero dependencies — only node:* built-ins; installs in one step.

Install from the DeepSeek Harness plugin market, or npm install -g dsh-plugin-codemap.

License

MIT © 2026 程夏