前言¶

在 DeepSeek Harness（DSH）里接陌生仓库时，成本往往落在两件事上：通读源码，以及建立对模块、路由和依赖关系的稳定认知。常见做法是反复让模型「扫一遍项目」，但结构描述容易漂移，API 与行为也缺少可核对出处。CodeMap 是社区维护者 cheng200606 发布的工作流类插件：扫描仓库、建索引，再生成一组结构化 Markdown 页面；每条结论附带 path:line 形式的源码引用，生成后逐条回查，失败则标记为 needs-review。整个过程不调用模型，可在离线环境复跑，结果可 diff、可手改。

这是什么¶

CodeMap（npm 包名 dsh-plugin-codemap，当前 npm 版本 0.12.1）面向 DSH 与需要可读、可校验仓库文档的开发者。它把代码仓库「编译」成代码地图资产：固定规划的概览/架构/流程等页面、显著模块的详情页，以及侧栏里的工程知识图谱与知识卡片。插件在 GitHub 上开源（MIT），兼容 DeepSeek Harness >=0.2.1-rc.5 <0.3.0-0，要求 Node.js >=22，运行时仅使用 node:* 内置模块，无额外 npm 运行时依赖。

核心功能¶

确定性生成与可校验引用¶

插件扫描仓库并建立模块、符号与路由索引，自动规划页面结构并渲染 Markdown。页面 frontmatter 可记录状态（如 fresh、needs-review）与置信度；正文中的结论绑定真实文件与行号，校验不通过不会 silently 通过。源码变更时，页面记录的输入哈希有助于定位需要重写的页面。

模型工具与斜杠命令¶

模型可主动调用的工具包括：

Harness 内还提供斜杠命令：/codemap status | plan | generate | update | export | import | help。

侧栏面板与产物目录¶

安装并重启 Harness 后，左侧栏可打开 CodeMap 面板：页面树、带状态过滤的搜索、可拖拽缩放的知识图谱（节点可下钻到文件级并跳转源码）、知识卡片库。生成物默认落在当前仓库的 .dsh/codemap/，为纯 Markdown 与 JSON，可纳入版本控制；支持导出为 .qoder/repowiki 以便与 Qoder 互操作。

安全边界（设计层面）¶

插件不执行仓库内脚本或构建命令，也不调用模型；扫描时会忽略 .git、node_modules 等目录，并硬性排除 .env、*.pem、*.key、secrets/** 等路径。写入范围限制在 <repo>/.dsh/codemap/；Web 面板仅访问已注册工作区。代码地图被明确视为派生文档而非可执行指令。

安装与启用¶

DSH 生态采用「一切皆插件」；社区插件目录（如 SkillHub 上的条目页）与 DeepSeek / 幻方无官方从属关系，安装前建议在 GitHub 阅读源码与 LICENSE。

下面三种方式均来自项目 README，任选其一即可。

从 Git 安装（README 标注为当前可用）：

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

dsh plugin add 会把依赖写入 profile 的 package.json，并追加到 dsh.profile.bundles；重启 Harness 后即可使用面板与 /codemap 命令。

插件市场（需先添加社区源）：

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

npm：

dsh plugin add dsh-plugin-codemap

或指定版本：

dsh plugin add dsh-plugin-codemap@0.12.1

包页：https://www.npmjs.com/package/dsh-plugin-codemap。

典型用法¶

在 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`）

点击引用或面板中的源码入口，可对照真实行号阅读实现。

适用场景与注意¶

适合： 需要在 DSH 内长期维护「可核对、可增量更新」的仓库说明；希望模型先查地图再读源码，减少无出处推断；希望在离线或零模型调用预算下批量刷新文档结构。

注意： 插件以当前 DSH 进程的权限读写工作区；安装第三方插件前请自行审查 cheng200606/dsh-plugin-codemap 的源码与 MIT 许可证。大型 monorepo 首次生成耗时取决于文件规模；引用校验失败的页面需人工或后续增量运行处理。README 提到 npm run check 可在约 3 秒内跑完插件自身回归，那是插件仓库内的开发命令，与你在业务仓库里执行 /codemap generate 不是同一回事。

结尾¶

CodeMap 把「读仓库」和「理解结构」做成可复用、带 path:line 证据的 Markdown 资产，并配套检索工具与可视化面板，适合作为 DSH 工作流里的离线代码 intelligence 层。

• 社区目录页：https://www.skillhub.cn/plugins/cheng200606/dsh-plugin-codemap
• 源码与完整文档：https://github.com/cheng200606/dsh-plugin-codemap