前言¶
DeepSeek Harness (DSH) 插件生態旨在擴展智能體的代碼操作能力。在編寫代碼時，智能體需要回答三個結構化問題：符號在哪裏聲明、誰調用了它、修改它會產生什麼影響。傳統的文本搜索（如 grep）無法回答“誰調用它”這類關係問題，而 LSP 雖然精確，但依賴於光標位置且需要爲每種語言運行單獨的服務。dsh-plugin-codegraph 解決了這個問題，它通過在本地構建代碼符號圖，爲智能體提供了 codegraph 和 codegraph_index 兩個工具，使其能夠基於圖結構而非文本搜索來回答上述問題。
核心能力¶
該插件爲智能體提供兩個主要工具，它們在功能和設計上相互獨立。
codegraph：只讀查詢工具¶
codegraph 提供 10 個只讀操作，用於從預構建的索引中獲取信息：
search：查找符號在哪裏聲明。node：獲取某個符號及其直接調用者和被調用者。callers：列出調用當前符號的所有位置。callees：列出當前符號調用的所有目標。impact：分析修改當前符號可能產生的影響範圍。trace：追蹤兩個符號之間的路徑。files：列出被索引的文件，支持目錄或通配符。status：檢查索引的大小和新鮮度。explore：探索與查詢相關的多個聲明及其源碼。context：獲取與特定任務相關的所有上下文信息。
codegraph_index：索引構建工具¶
該工具負責構建或刷新代碼圖索引。索引過程與查詢過程分離，因爲構建大型工作區的索引需要數分鐘，而查詢僅需毫秒級。將兩者合併會導致超時預算配置困難：要麼太緊導致索引無法完成，要麼太鬆導致查詢無法感知卡頓。
安裝與啓用¶
安裝過程通過一條命令完成，它會自動獲取包並將插件配置到指定 Profile 中：
dsh plugin --profile <name> add dsh-plugin-codegraph
安裝後，智能體即可直接使用上述兩個工具。如果索引尚未構建，status 操作會明確告知索引不存在，並指出需要運行 codegraph_index。
典型用法¶
- 查找符號聲明：
codegraph search query
- 查看符號的調用關係：
codegraph node symbol
- 檢查修改影響：
codegraph impact symbol
- 追蹤路徑：
codegraph trace from to
- 列出索引文件：
codegraph files
- 構建或刷新索引：
codegraph_index
技術細節¶
- 語言支持：內置索引器支持 TypeScript、TSX、JavaScript、JSX、Python、Go、Java、C、C++、C#、PHP、Rust、Ruby、Zig、Kotlin、Swift、Dart 和 Scala。語法解析器按語言惰性加載，僅在使用匹配文件時加載對應的解析器。
- 存儲格式：插件與
codegraphCLI 共享磁盤格式（schema version 4），存儲路徑爲<projectRoot>/.codegraph/codegraph.db。這意味着既可以使用插件構建索引，也可以使用 CLI 構建，兩者可互操作。 - 調用解析邏輯：插件不會對未解決的調用進行猜測。解析順序遵循固定規則：首先匹配導入的文件，其次匹配全局唯一的名稱。如果都不匹配，該調用會被記錄爲
unresolved，而不是生成錯誤的邊。
注意事項¶
- 只讀與構建分離：
codegraph工具始終是隻讀的，codegraph_index是構建索引的專用工具。任何查詢都不會隱式觸發索引構建，這是爲了防止長時間運行的索引任務與查詢混淆。 - 未解決的記錄：未解析的調用被明確標記爲
unresolved。智能體不應依賴這些標記來假設調用的存在，而應將其視爲需要進一步確認的信息。
結語¶
dsh-plugin-codegraph 通過進程內索引和圖查詢，爲 DeepSeek Harness 提供了與 LSP 不同維度的代碼理解能力。它不猜測調用關係，而是基於明確的解析規則提供結構化數據。如需瞭解更多或貢獻代碼，請訪問項目倉庫。
