前言¶

在 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
• 目录页：本次已核实资料未包含有效目录页地址，暂不在此列出。