前言¶

在 DeepSeek Harness（DSH） 裏接多個 MCP 服務器時，常見做法是每一輪模型請求都把全部工具定義原樣塞進上下文。工具一多，單步就要帶上成百上千條完整 schema，token 開銷大，模型在冗長列表裏選工具也容易變差。下面介紹社區插件 dsh-tool-index：把 MCP 工具收成緊湊索引，按需再拉完整 schema，同時保持會話內工具列表不變，便於 prompt cache 繼續生效。

這是什麼¶

dsh-tool-index 是面向 DSH 的插件（基於 DeepSeek Harness 構建，並非 DeepSeek 官方項目），維護者爲 GunjanPatel359，在插件目錄中歸類爲「模型推理」。它解決的核心問題是：重複發送完整 MCP 工具定義帶來的 token 成本，以及工具列表若在中途變化導致 prompt cache 失效。

未啓用時，上下文裏往往是 read、bash 以及大量 mcp__*__* 的完整 schema；啓用後，對外暴露的穩定工具集裏增加 tool_details 與 call_tool，MCP 側則以索引形式列出名稱、參數名與一行摘要（按服務器分組），需要時再查詳情並調用。

核心功能¶

按需加載，列表固定¶

• 每輪請求只發送短索引：每個 deferred 工具包含 name、parameters 與 one-line summary（具體展示風格由 indexStyle 控制）。
• 模型需要某工具時，先通過 tool_details 讀取完整定義，再用 call_tool 執行；權限策略、審批與 hooks 仍針對真實工具名與參數，不繞過 DSH 既有機制。
• 會話內對外可見的工具集合保持不變，加載某個 MCP 工具不會整段重寫工具列表，從而 prompt cache 可繼續使用。

名稱仍全覆蓋，錯名可糾¶

索引裏始終列出全部 deferred 工具名稱；若模型拼錯名或缺少 mcp__server__ 前綴，tool_details 會返回最接近的真實名稱（詳見倉庫內 docs/name-matching.md）。

實測 token 變化（README 基準）¶

README 給出「同一小任務、每格三次運行」及「單會話 5 輪對話（其中兩輪不需工具）」的彙總 token（各模型每步相加）。摘錄如下：

75 個 MCP 工具、單小任務場景下，README 開頭亦給出 183,274 → 79,838（約 56% 減少） 的對比。可自行用倉庫內 e2e/run.sh 復現。

兼容與模式¶

• Native tool calls：插件主要面向該模式。
• PTC 模式（run_code）：插件不改動這類 agent 的請求；DSH 已在代碼側列出全部工具。
• 子 agent 與 structured-output 子任務：各 agent 使用各自工具索引；子任務的 structured_output 仍爲普通工具。

文檔寫明面向 DSH 0.2.x；DSH 尚未 1.0，插件接口可能隨版本變化。運行環境要求 Node.js >= 22（見 package.json）。

安裝與啓用¶

作爲 profile bundle 安裝並啓動 TUI：

dsh plugin --profile tui add dsh-tool-index
dsh --profile tui

插件以當前 DSH 進程權限運行；安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的安全與合規要求。

配置要點¶

在 DSH 插件配置中啓用 dsh-tool-index 時，README 給出如下字段（patch 會替換整段 config，修改時需寫全你要保留的鍵）：

- id: dsh-tool-index
  name: dsh-tool-index
  config:
    match: ['mcp__']          # 要延遲完整 schema 的工具名前綴
    exclude: []               # 例外前綴，例如每輪都用的 ['mcp__mycore__']
    alwaysLoad: []            # 始終發送完整 schema 的精確工具名
    minTools: 10              # 匹配數量達到此值才啓用延遲
    indexStyle: signature     # names | summary | signature
    maxDetails: 10            # 單次 tool_details 最多返回的工具數
    summaryChars: 120         # 索引中每條摘要長度
    indexChars: 12000         # 超出後剩餘工具僅列名稱
    detailsToolName: tool_details
    callToolName: call_tool

使用注意：

1. 匹配工具數 少於 minTools 時不做延遲，避免爲少量工具多一步 tool_details。
2. 幾乎每輪都用的 MCP 工具應通過 exclude 或 alwaysLoad 排除出索引，否則多一次查詳情步驟。
3. match 按前綴匹配；不要把 harness 核心工具（如 read、bash）納入延遲——它們幾乎每輪都需要，延遲只會變差且無內置攔截。

典型用法與代價¶

典型調用鏈：

1. 模型在索引中看到目標 MCP 工具名與摘要。
2. 首次使用前調用 tool_details 獲取完整 schema。
3. 通過 call_tool 傳入真實工具名與參數執行。

權衡（README Trade-offs）：

• 某個 deferred 工具在對話中 首次使用前可能多一步 tool_details。
• 參數校驗由 工具自身 返回錯誤，而非 provider 在 schema 層攔截。
• 部分 UI 外層步驟顯示爲 call_tool，內層纔是真實 MCP 工具。

適用場景¶

適合在 DSH 中 長期掛載較多 MCP 服務器、且主要走 native tool call 的智能體開發場景；工具越多，每輪省略的完整定義越多。若 MCP 很少、或 agent 處於 PTC / run_code 主導模式，收益可能有限或插件自動讓路。

DSH 生態強調「一切皆插件」；SkillHub 插件目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-tool-index 把 MCP 工具定義從「每輪全量 schema」改爲「穩定工具表 + 緊湊索引 + 按需詳情」，在 README 基準下可明顯降低多 MCP 場景的 token，並儘量保持 prompt cache 有效。實現細節見倉庫 docs/how-it-works.md。

• 目錄頁：https://www.skillhub.cn/plugins/GunjanPatel359/dsh-tool-index
• 源碼與文檔：https://github.com/GunjanPatel359/dsh-tool-index