前言¶
DeepSeek Harness (DSH) 允許通過插件擴展能力。在代碼輔助場景中，模型不僅需要文本匹配，更需要結構化的代碼上下文，如符號定義、調用關係和影響範圍。傳統的 grep 搜索往往效率低下且缺乏上下文。dsh-codegraph-plugin 通過將 codegraph CLI 封裝爲工具，爲 DSH 提供了結構化的代碼智能支持。
插件簡介¶
這是由 errrepe 維護的 DSH profile bundle。它將 codegraph 工具集暴露爲 8 個模型可調用的接口，並保持本地代碼庫索引的同步。插件在會話的當前工作目錄 (CWD) 中執行 codegraph 命令，利用 SQLite WAL 機制在受限工作空間內讀取索引數據。
先決條件¶
該插件依賴宿主機安裝的 codegraph CLI，並不負責安裝或管理該 CLI。
- 安裝
codegraphCLI（通過 cargo）：
cargo install codegraph
- 驗證安裝：
codegraph --version
- 確保
codegraph可執行文件在系統PATH中。
安裝¶
安裝爲指定的 DSH profile 添加 bundle：
dsh plugin --profile web add github:errrepe/dsh-codegraph-plugin
安裝後，需重啓該 profile 的 DSH 進程以使插件生效。
核心功能¶
插件提供以下 8 個工具接口，根據操作類型返回 JSON 或格式化文本：
codegraph_query：按名稱搜索符號（函數、類、方法），支持按類型過濾，返回 JSON。codegraph_callers：查詢調用指定符號的代碼位置，用於重構前的依賴分析，返回 JSON。codegraph_callees：查詢符號調用的目標，返回 JSON。codegraph_impact：分析修改符號可能產生的影響（依賴方及測試覆蓋情況），返回 JSON。codegraph_explore：對開放性問題進行探索，一次性返回相關符號、源碼、調用路徑及影響範圍，返回文本。codegraph_node：讀取符號的完整源碼或指定文件，包含行號及依賴關係，返回文本。codegraph_status：檢查索引狀態，顯示文件、節點、邊的統計信息，返回文本。codegraph_sync：將代碼變更同步到索引，返回文本。
配置¶
在 DSH 的 Settings > Plugins (Configurables) 中會註冊一個名爲 codegraph 的配置項：
- enabled（默認
true）：控制插件工具的註冊。關閉時工具返回錯誤提示，不會阻塞 DSH 啓動。 - injectPrompt（默認
true）：控制是否在 System Prompt 中注入codegraph-guidance指引。該指引位於 Prompt 組合的第 50 位，教導模型優先使用代碼圖而非grep。
配置持久化在 ~/.dsh/settings.yaml 的 codegraph 命名空間下。
典型用法¶
- 首次使用：在搜索前調用
codegraph_status檢查索引是否存在。若不存在，需在項目根目錄手動運行一次codegraph init。 - 開放性問題：優先使用
codegraph_explore，它能在一個調用中返回符號、源碼、調用路徑和影響範圍。 - 代碼修改後：編輯文件後調用
codegraph_sync，確保後續查詢反映最新代碼。 - 精確讀取：使用
codegraph_node讀取特定符號或文件的詳細源碼。
兼容性與降級¶
插件具備容錯能力：
* DSH 服務缺失：如果宿主機缺少 dsh-settings 等服務，插件會優雅降級（默認開啓且無 bridge），不阻斷 DSH 啓動。
* CLI 缺失或無索引：工具會直接透傳 codegraph CLI 的錯誤信息給模型。
* Headless 場景：在沒有會話 CWD 的環境下（如純腳本調用），工具會返回明確錯誤而非崩潰。
結尾¶
該插件通過統一接口將靜態分析能力注入 DSH 生態，適合需要深度理解代碼結構和依賴關係的場景。源碼與目錄可參考下方鏈接。
