前言¶

在 DSH 的插件化場景裏，一個 live agent 可能會看到很多 global tools。工具越多，模型一次面對的工具列表越長；如果所有 eligible global tools 都持續可見，未實際使用的工具 schema 也會一直留在請求上下文中。

下面介紹一個實驗性 DSH 插件：@deepseek-ai/dsh-tool-search。它用於 per-agent tool discovery 和 progressive schema disclosure：每個 live agent 可以看到一個 scope-local 的 tool_search 工具，以及由 alwaysVisible 明確保留可見的 global tools；其他 eligible global tools 只在 tool_search 選擇後才變爲可執行。

這是什麼¶

@deepseek-ai/dsh-tool-search 是一個 experimental external Native Tool Mode plugin。它的核心目標不是替換所有工具，而是在 DSH profile 中增加一套按需發現和按需加載的工具可見性機制。

已覈實資料顯示，該包的包名爲 @deepseek-ai/dsh-tool-search，package.json 中標註爲 version: 0.0.1、private: true、license: MIT。該倉庫是插件源碼來源，但未發佈到 npm registry，並且處於 unreleased 狀態，沒有兼容性承諾。

本文使用的 GitHub 倉庫地址爲：

https://github.com/dsh-external/dsh-tool-search

核心功能¶

工具可見性¶

這個插件把 global tools 分成兩類處理：

• alwaysVisible 匹配到的 global tools，在搜索前保持可見。
• 其他 eligible global tools，默認不直接進入模型的初始可見集；當 tool_search 選擇它們後，才變爲可執行。

tool_search 本身是 scope-local 工具，每個 live agent 看到的是自己範圍內的 tool_search，以及該 agent 已經可見的 global tools。

搜索與選擇¶

tool_search 接受一個必填的 query，以及一個可選的整數 limit。

搜索規則包括：

• exact callable-name 優先。
• 名稱和描述匹配使用 deterministic BM25 matching。
• limit 可以從 1 到 maxResults，但不能超過部署配置給出的上限。

模型可以要求更小的 limit，但不能把上限提高到部署配置之外。

會話事件與不變量¶

一次成功擴展會寫入一個 tool-search/selection session event。插件還會加載 invariant companion，用於檢查事件形狀，並強制選擇集保持 monotonic cumulative selection。

換句話說，後續選擇不能隨意回退；它應表現爲累計可見集合的單調變化。

實現方式¶

該插件使用現有的 ctx.tools.restrict() seam 來限制可見工具集，不直接修改 agent-loop。

這意味着它是在 DSH 已有的工具可見性邊界上做進一步約束，而不是繞開既有權限和過濾機制。

配置項¶

插件可配置以下三項：

以下配置會在插件加載時失敗：

• 非法的 positive-integer bounds。
• 空 pattern。
• 帶空白 padding 的 pattern。
• 重複 pattern。

安裝與啓用¶

安裝要求¶

該倉庫是 private repository，包未發佈到 npm registry。安裝時需要：

• Git credentials。
• pnpm 11.7.0。
• 安裝一個 reviewed commit。
• 爲每個需要使用該插件的 profile 單獨安裝。

DSH profiles 是相互獨立的。安裝到 web profile，不會自動啓用 headless profile。

安裝到指定 profile¶

將 reviewed commit 安裝到 headless profile：

dsh plugin --profile headless add -w github:dsh-external/dsh-tool-search#<reviewed-commit>

將同一個 reviewed commit 安裝到 web profile：

dsh plugin --profile web add -w github:dsh-external/dsh-tool-search#<reviewed-commit>

其中 <reviewed-commit> 是佔位符，安裝時應替換爲實際審查過的 commit。

啓動前校驗¶

安裝到 web profile 後，先執行：

dsh --profile web --dump-config

在 boot profile 之前，應確認輸出中包含：

tool-search
tool-search-invariant

兩者都出現後，再啓動該 profile。

移除插件¶

從某個 profile 中移除該 bundle：

dsh plugin --profile <profile> remove -w @deepseek-ai/dsh-tool-search

典型用法¶

配置示例¶

下面是一個配置示例：

- id: tool-search
  name: '@deepseek-ai/dsh-tool-search'
  config:
    alwaysVisible: [read_file, todo_*]
    maxResults: 5
    maxQueryChars: 512

在這個配置裏：

• read_file 始終可見。
• todo_* 作爲字面量與通配符組合的 pattern 保持可見；只有 * 是通配符。
• 一次搜索最多返回 5 條結果。
• 模型提交的 trimmed query 最長爲 512 個 JavaScript characters。

模型調用 tool_search¶

模型可以這樣使用 tool_search：

• 提供必填的 query。
• 可選提供整數 limit。
• limit 的允許範圍是 1 到 maxResults。

如果 tool_search 返回選中工具，這些工具會在下一個模型請求中加載。模型應在搜索結果返回後，再調用這些新加載的工具。

搜索結果與選擇結果¶

成功搜索後，插件會寫入 tool-search/selection session event。invariant companion 會檢查事件形狀，並保證後續選擇保持 monotonic cumulative selection。

如果某個工具已經可見，它不會因爲再次搜索而進入新的 deferred 流程；如果它仍被其他 restriction 阻止，則不會因爲它被搜索到就自動可用。

適用場景與注意¶

適合場景¶

這個插件適合希望按 agent 控制 global tools 可見性的 DSH 使用場景，尤其是：

• 需要讓模型通過 tool_search 主動發現工具。
• 希望部分 global tools 始終保持可見。
• 希望其他 eligible global tools 在選中後再進入後續請求。
• 希望在 Native Tool Mode 下維護一套 scope-local 的工具發現接口。

限制¶

使用前需要注意以下限制：

• 僅支持 Native Tool Mode。嵌套在 run_code 下的調用會 fail loud。
• 搜索是 lexical search only。embeddings 和 provider-native search 仍被 deferred。
• 只處理 global tools。agent-scoped tools 本來就已經可見，不會進入 deferred catalog。
• 如果 agent 啓動時已經處於一個 restricted initial global view，eligible-name set 會被凍結；除非 alwaysVisible 明確命名了某個 late tool pattern。
• 插件不會放寬其他 filter。已有的 creation-time restrictions、parent/subagent policy、scoped shadows，以及其他 ctx.tools.restrict() 調用仍然會繼續 intersect。
• 該插件未發佈到 npm registry，處於 unreleased 狀態，沒有兼容性承諾。

安全檢查¶

該插件會加入 DSH 的插件加載鏈路，並以當前 dsh 進程權限運行。安裝前應檢查源碼、許可證以及 reviewed commit 的來源。

本次已覈實資料顯示其許可證爲 MIT，但仍建議在實際接入前自行審查代碼與依賴。

結尾¶

@deepseek-ai/dsh-tool-search 提供的是一個實驗性的工具發現層：它讓每個 live agent 擁有自己的 tool_search 入口，把 alwaysVisible 工具保留在初始可見集中，並把其他 eligible global tools 延後到搜索選擇後再加載。對於需要控制工具可見範圍、維護單調選擇集合，並在 DSH profile 中做漸進式工具披露的場景，它是一個可以進一步評估的插件方向。

相關鏈接：

• GitHub：https://github.com/dsh-external/dsh-tool-search
• 目錄頁：本次已覈實資料未包含有效目錄頁地址，暫不在此列出。