前言¶
在 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 通過。源碼變更時，頁面記錄的輸入哈希有助於定位需要重寫的頁面。
模型工具與斜槓命令¶
模型可主動調用的工具包括：
| 工具 | 作用 |
|---|---|
codemap_search |
在已生成的代碼地圖中做中英文混合檢索 |
codemap_read |
讀取某頁完整 Markdown（含 frontmatter 與引用） |
codemap_generate |
生成或增量刷新代碼地圖 |
codemap_status |
報告頁面數與上次運行狀態，不觸發生成 |
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 命令。
插件市場（需先添加社區源）：
- 打開 Harness → 插件市場 → 源（Sources），添加：
https://cdn.jsdelivr.net/gh/cheng200606/dsh-plugin-codemap@main/market/index.json - 搜索
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 層。
