前言¶
讓智能體讀懂一個陌生代碼庫，常見做法是 grep 關鍵詞、glob 找文件、再逐個 read——一輪下來工具調用十幾次，上下文塞滿文件片段，還不一定命中真正的調用鏈。
CodeGraph（@colbymchenry/codegraph）的思路不同：先把項目索引成代碼知識圖譜，之後按符號、按區域、按調用鏈查詢，一次調用就能拿到相關符號的逐行源碼和調用路徑。問題是，CLI 工具模型自己調不到，得有人把它包裝成模型可見的原生工具。
本文介紹的 dsh-codegraph 就是做這件事的 DSH 插件。
這是什麼¶
jiangzhenguo/dsh-codegraph 是一個可一鍵安裝的 DSH 插件（bundle），把 codegraph CLI 包裝成 13 個 codegraph_* 原生工具，讓 DSH 會話直接查詢預索引代碼知識圖譜，並支持自舉和維護索引（init/index/sync）。當前版本 1.1.0，許可證 MIT。
提供的工具¶
13 個工具與 codegraph CLI 命令一一對應，工具名與 CodeGraph 官方 MCP 工具同名：
| 工具 | 對應 CLI | 用途 |
|---|---|---|
codegraph_status |
status --json |
索引狀態（是否已初始化、文件/節點/邊數、待同步變更等） |
codegraph_init |
init |
初始化項目並建立初始索引（.codegraph/） |
codegraph_index |
index |
全量（重）索引 |
codegraph_sync |
sync |
增量同步索引 |
codegraph_uninit |
uninit -f |
刪除項目索引 |
codegraph_query |
query --json |
按名稱/子串搜索符號，返回結構化 JSON |
codegraph_node |
node |
單個符號源碼 + 調用/被調用軌跡 |
codegraph_explore |
explore |
自然語言探索一塊代碼區域，返回相關文件源碼與調用路徑 |
codegraph_files |
files --json |
索引內的項目文件結構 |
codegraph_callers |
callers --json |
誰調用了某個符號 |
codegraph_callees |
callees --json |
某個符號調用了什麼 |
codegraph_impact |
impact --json |
改動某個符號會波及哪些代碼 |
codegraph_affected |
affected --json |
改動若干源文件後應運行哪些測試文件 |
默認只註冊 4 個核心工具：codegraph_status / codegraph_init / codegraph_sync / codegraph_explore。這個裁剪借鑑了上游項目的實測結論——codegraph_explore 是唯一穩定贏得模型調用的工具，官方 MCP server 默認也只暴露 explore。工具列表精簡，引導才集中。需要全部 13 個工具時，配置 surface: 'full'。
裝上即生效的提示詞引導¶
只把工具放出來還不夠，模型可能仍走 grep 反射路徑。插件會在系統提示詞注入一條高優先級指引（tool:codegraph，order: 98），而 DSH 內置文件工具的指引集中在 order 100–104（read=100、write=101、edit=102、glob=103、grep=104）。指引放在 98，先於它們被模型看到。
指引內容採用上游驗證過的策略：命令式措辭（MUST use codegraph_explore INSTEAD of grep/glob/read）、反模式清單（不要先 grep「找文件」，不要用 grep 複覈 codegraph 結果——它來自完整 AST 解析），以及未索引項目的硬停止規則：不自行初始化時，本會話不再調用 codegraph 工具，索引與否是用戶的決定。
frontload：把上下文先送進當前 turn¶
提示詞指引仍是軟性的。所以插件實現了 frontload 前置注入——上游實測最有效的採用率手段：
- 插件監聽
agent/inbox/inserted事件，當真實用戶 prompt 進入 agent 的 next-turn 收件箱時做置信度分級門控：含結構性關鍵詞（如「調用 / 重構 / 依賴 / how does / who calls / refactor / trace」）直接觸發；含代碼形態 token（文件名、camelCase、PascalCase、snake_case）則先用codegraph query對照索引驗證是真實符號才觸發；其餘 prompt 零開銷靜默跳過。 - 觸發後在會話 cwd 向上找最近的
.codegraph/索引根，找不到就靜默跳過——插件不擅自 init。 - 預跑
codegraph_explore，把結果以<codegraph_context>包裹注入當前 turn，上限 12000 字符。模型反射性要 grep/read 的內容已經在上下文裏了。
安全性上有三條保證：所有失敗路徑（無索引、門控未命中、CLI 報錯）都是靜默 no-op，不會弄壞用戶 prompt；注入內容帶標記，不會觸發自身循環；同文 prompt 在 10 分鐘內重複進入收件箱（GUI 重發、step 被拒後重新入隊）只注入一次。可用 frontload: false 整體關閉。
和會話級 MCP server 的區別¶
codegraph 官方 MCP server 在工作區未建立索引時暴露 0 個工具，並提示模型不要自己索引。本插件始終暴露工具，包括模型自舉和維護索引所需的 init/index/sync，這是它選擇 bundle 形態而非 MCP 的原因。
安裝與啓用¶
前置要求兩項：已安裝 DSH（本插件爲 DSH bundle，隨 DSH web 應用裝載）；codegraph CLI 在 PATH 上且版本 ≥ 1.0：
npm i -g @colbymchenry/codegraph
codegraph --version # 確認可用（≥ 1.0）
然後在目標 profile（這裏是 web）一條命令安裝：
dsh plugin --profile web add github:jiangzhenguo/dsh-codegraph
這條命令做了什麼：dsh plugin 在 profile 目錄裏跑 pnpm add github:jiangzhenguo/dsh-codegraph；因爲本包的 package.json 聲明瞭 dsh.bundle.patch，DSH 的 plugin 管理器會把它自動加入 profile 的 dsh.profile.bundles 層棧，不需要手動改配置。重啓 DSH 應用後，任意會話裏模型即可看到 codegraph_* 工具（默認 core 面 4 個）。其他 profile 換成 --profile tui 等即可。README 另提到，若已發佈到 npm，可用包名替換命令開頭的 github:。
卸載：
dsh plugin --profile web remove dsh-codegraph
配置在組合層（如 cordis.patch.yml 的 insert 行）傳入：
- insert:
- id: dsh-codegraph
name: dsh-codegraph
require: dsh-codegraph
config:
guideSearch: true # 默認 true：注入系統提示指引；false 只註冊工具
surface: core # 默認 core（4 個工具）；設爲 full 註冊全部 13 個
frontload: true # 默認 true：結構化 prompt 自動前置注入
典型用法¶
- 在項目目錄（cwd = 項目根）開一個新的 DSH 會話。
- 讓模型先跑
codegraph_status：未初始化則跑codegraph_init。 - 之後用
codegraph_explore查代碼，一次調用返回相關符號源碼 + 調用鏈；surface: 'full'下還可用codegraph_query/codegraph_node/codegraph_callers/codegraph_callees/codegraph_impact做更細的查詢。 - 改動代碼後用
codegraph_sync，需要跑測試時用codegraph_affected（full surface）。
所有工具默認作用於調用方會話的 cwd，也可顯式傳 path 指向其他項目。
插件自帶運行時測試 harness（test/run-plugin-test.mjs，真實 codegraph CLI + 樁 cordis 服務），覆蓋提示詞注入順序、core/full surface 的工具註冊、frontload 的注入與去重等路徑。在裝好插件的 profile 裏運行：
CG_PROFILE_NM=<profile>/node_modules node test/run-plugin-test.mjs
適用場景與注意¶
適合的項目形態：代碼庫較大、模型頻繁需要按調用鏈理解代碼的 DSH 用戶；重構、改名前想確認波及面，或改動後想確定該跑哪些測試的場景。前提是願意爲項目建立並維護 .codegraph/ 索引。
幾個值得知道的點：
- 在本機
codegraph@1.0.1上，callers/callees返回空數組是 CLI 側的數據/索引特性（該版本調用圖邊未解析到），插件忠實返回 CLI 真實輸出；impact已能返回真實的受影響節點與邊。 - 未索引項目時插件不會擅自
init，是否索引由用戶決定，指引裏含對應的硬停止規則。 - frontload 的所有失敗路徑均爲靜默 no-op，不影響普通 prompt 的處理。
安全提示：插件以當前 dsh 進程的權限運行，安裝前建議檢查其源碼與許可證（本項目爲 MIT），確認可接受再裝入常用 profile。
結尾¶
dsh-codegraph 把「預索引、按調用鏈查代碼」這條路徑接進了 DSH：默認 4 個核心工具保持工具面精簡，order 98 的提示詞指引和 frontload 前置注入負責讓模型真的用起來，而不是多掛幾個無人問津的工具。
- 目錄頁：https://www.skillhub.cn/plugins/jiangzhenguo/dsh-codegraph
- GitHub：https://github.com/jiangzhenguo/dsh-codegraph
