前言¶

DeepSeek Harness（DSH）的插件生態中，當工具目錄變得龐大（例如集成多個 MCP 服務器或大量插件工具）時，每個工具的 JSON 模式都會在每一輪對話中被注入到模型上下文中。這會導致大量無關的 token 消耗，降低推理效率。dsh-tool-search 旨在解決這一問題。它採用 Hermes Agent 的“漸進式披露”設計理念，將長尾工具摺疊在後臺，僅通過三個橋接工具按需加載，從而控制模型可見的清單規模。

安裝¶

安裝該插件需要使用 DSH 的命令行工具。在終端中執行以下命令：

dsh plugin --profile web add dsh-tool-search

核心能力¶

該插件的核心功能圍繞“按需可見”和“核心保留”展開：

1. 分級披露：根據當前上下文窗口預算和工具目錄大小，動態調整模型可見的工具列表。
2. 橋接工具：提供 tool_search、tool_describe 和 tool_call 三個橋接接口，用於替代原本冗長的工具清單。
3. 急切加載：文件操作、Shell 執行及核心必備工具始終直接可見，無需摺疊。
4. 動態注入：通過搜索或調用工具後，該工具會被注入到可見上下文中（受 LRU 限制），以便在後續輪次直接使用。

工作原理¶

插件通過監聽 system-prompt/assemble 事件來計算“分級”（Tier），並替換模型可見的工具列表。

分級邏輯取決於“預算”計算，公式爲 min(thresholdPct% × contextWindow, listingMaxTokens)，並在每一輪對話中重新計算：

• Tier 0：當目錄較小或無可摺疊工具時，所有工具直接可見。
• Tier 1：當分組後的清單適合預算時，顯示橋接工具以及分組標題和描述（## group）。
• Tier 2：當僅工具名稱適合預算時，僅顯示橋接工具和名稱列表。
• Tier 3：當名稱也溢出時，僅顯示橋接工具，每組一行（如 group_name: 5）。

動態執行：當 tool_call 被調用時，插件通過 ctx.tools.execute 執行真實的工具，而非橋接工具。這意味着審批機制、防護牆和會話事件仍然引用原始工具，而非橋接層。搜索功能默認使用配置的重排序匹配器，若失敗或未配置，則回退到關鍵詞匹配（精確名稱 > 名稱片段 > 描述片段）。

對話式設置¶

插件內置了 tool-slimmer-setup skill，支持通過對話完成配置。你可以直接向 Agent 提出以下請求來啓動設置流程：

幫我配置 dsh-tool-search 的工具分組

該 skill 會讀取目錄，提議分組方案，確認後引導你選擇全局或項目級配置，並協助配置重排序匹配器。

配置¶

配置分爲靜態配置（重啓生效）和運行時配置（熱重載）。

1. 靜態配置
靜態配置位於 profile 的 cordis.patch.yml 文件中：

- id: tool-search
  config:
    enabled: auto        # auto | on | off
    thresholdPct: 5      # 清單預算占上下文窗口的百分比
    listingMaxTokens: 4000
    configScope: auto    # user | project | auto (項目文件優先)
    core: [todo_write]   # 額外的始終急切工具
    maxWarmTools: 8      # 動態注入工具的 LRU 上限

2. 運行時配置
工具分組、匹配器和預加載配置位於運行時文件中。用戶級路徑爲 ~/.dsh/dsh-tool-search.json：

{
  "version": 1,
  "scope": "user",
  "groups": [
    { "name": "git", "tools": ["git_status", "git_diff"] },
    { "name": "mcp-github", "prefixes": ["mcp_github_"] }
  ],
  "matcher": {
    "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/rerank",
    "apiKey": "sk-...",
    "model": "qwen3-reranker",
    "topN": 20
  },
  "preload": { "enabled": false, "topK": 5 },
  "core": ["read_file", "write_file"]
}

• groups：精確工具名或前綴，匹配優先級取決於定義順序。
• matcher：必須是 OpenAI 兼容的 /v1/rerank 端點，否則搜索功能將不可用。
• preload：可選功能，啓用後會在首輪對話中預加載語義匹配度最高的 K 個工具。
• 文件支持 mtime 監聽，修改後下輪對話生效。

橋接工具¶

插件提供三個主要的橋接工具供模型調用：

適用場景與注意¶

該插件適合擁有大量第三方工具或 MCP 服務器的 DSH 項目。在使用前，請確認以下幾點：

1. 權限運行：插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證。
2. 註冊表完整性：精簡僅重寫模型可見的表面，底層註冊表保持完整，延遲工具仍可被正常執行。
3. 重排序優先：關鍵詞匹配僅作爲後備手段，核心搜索依賴重排序模型。
4. 上下文依賴：清單基於運行時上下文，可以適應完整的提示詞組合。

參考資料¶

• GitHub 倉庫
• DeepSeek Harness 官方文檔