前言¶

在 DeepSeek Harness (DSH) 的開發實踐中，智能體有時需要在未獲取文件內容、未定位光標的情況下，僅通過符號名稱查找代碼結構（如類名、函數名）。傳統的 LSP 工具（如 goToDefinition）通常依賴上下文。dsh-workspace-intelligence 解決了這一需求，它爲 DSH 提供了一個獨立的 workspace_symbol 工具，允許 agent 利用標準 LSP 的 workspace/symbol 請求進行確定性搜索。

插件定位¶

dsh-workspace-intelligence 是一個獨立的 DSH/Cordis 插件。
它專注於確定性 LSP 工作區符號搜索。插件不修改 DeepSeek Harness 核心代碼，也不直接調用 ctx.lsp，而是通過公開的 ctx.fs、ctx.subprocess 和 ctx.tools 上下文與 LSP 通信。它兼容 SymbolInformation[]、WorkspaceSymbol[]、URI-only location、null 和空數組等多種返回格式，確保行爲可預測。

安裝與啓用¶

插件默認處於禁用狀態，因爲 Language Server 的啓動命令必須由部署方指定。

1. 安裝插件
   使用官方安裝命令添加插件到指定 Profile。

    dsh plugin --profile <name> add dsh-workspace-intelligence

2. 安裝依賴環境
   安裝 Node.js（要求 ^22.19.0 或 >=24）以及至少一個支持 stdio LSP 的語言服務器（示例）。

    pnpm add -g pyright typescript typescript-language-server

3. 配置 Language Server
   部署方需在 Profile 的 cordis.patch.yml 中配置語言服務器。根據操作系統執行以下步驟：

   • Windows
     運行 pnpm root -g 獲取全局目錄。將 examples/windows/cordis.patch.yml 合併到 Profile 配置中。將 C:/pnpm-global-root 替換爲實際輸出路徑（注意將分隔符改爲 /）。保留 node + JS 絕對路徑，不要使用 .cmd shim；ctx.subprocess 不經過 shell。

   • macOS/Linux
     將 examples/macos-linux/cordis.patch.yml 合併到 Profile 的 cordis.patch.yml。模板直接從 PATH 啓動語言服務器。

   • 驗證配置
     合併完成後，檢查合成結果以確保配置正確。

    dsh --profile <name> --dump-config

使用方法¶

調用該工具時，模型只需傳遞一個必填參數。

{ "query": "SessionManager" }

• 參數限制：空白 query 會被拒絕。模型不能選擇 provider、命令、workspace 或 timeout。
• 返回內容：結果包含符號名、可讀的 kind、canonical URI、可選的 range 以及 containerName。

配置說明¶

servers 配置項必填，且至少包含一項。Server ID 會按字典序排序，因此對象插入順序不影響行爲。

行爲與限制¶

• 併發與排序：查詢會 fan-out 到全部已配置的 server；同一 server 內串行。結果按 exact match、prefix match、其他結果、server id 和原始順序穩定排序。
• 去重規則：去重 key 爲 name + kind + URI + optional range。排序後的第一項保留。
• 錯誤處理：任一 provider 成功（包括空結果）即返回成功；失敗和不支持的 provider 只計數。全部不支持時報 WORKSPACE_SYMBOL_UNSUPPORTED，存在失敗且無成功結果時報 WORKSPACE_SYMBOL_PROVIDER_FAILED。
• 取消策略：caller 取消會發送 best-effort $/cancelRequest，並原樣拒絕，不會變成 partial success。
• 進程管理：每個 canonical workspace/server 惰性複用一個進程。卸載時先移除工具，再執行 shutdown、exit 和 process-tree 終止。
• 不支持的功能：不提供 grep fallback、document symbols、call hierarchy、embedding、raw JSON-RPC 或 cursor-based LSP 操作。

結語¶

dsh-workspace-intelligence 提供了一個確定性、無上下文依賴的符號搜索能力。它是 DSH 生態中“一切皆插件”理念的體現。該插件遵循 MIT 許可證，適合需要在 Agent 層面進行代碼結構查詢的開發場景。

• 項目目錄：https://www.skillhub.cn/plugins/shiki-dml/dsh-workspace-intelligence
• 源碼倉庫：https://github.com/shiki-dml/dsh-workspace-intelligence