惰性工具路由 residenthiago2011/DSH-Tool-Router

DSH Tool Router

为 DSH 提供惰性工具发现：把所有工具 schema 从模型的 prefill 中隐藏，按需通过决策模型 API 只揭示一个工具。

- Prefill 开销： 只保留一个小巧的 find_tool schema，替代所有已挂载工具（默认 Standard 配置档上有 26 个 schema——见为什么？）。
- Stage 0——全量发送：所有已挂载工具（≤ 24 个）各带一条 160 字符的判定标准，按过滤停用词后的词法排名排序（排名只用于约束病态挂载——d1-omni 不会随候选数量增长而饱和；见为什么？）。
- Stage 1——向决策模型 API 发一次 POST /v1/systemone：返回一个 bestTool 选择，外加一个 usable 问题，仅作遥测保留（约 235–500 token，设备上约 6–7 秒）。
- Stage 2——仅当 confidence >= 0.70 时接受：返回胜出者的 JSON Schema，并且只揭示那一个工具；否则返回按概率排序的候选清单，其理由中写明最接近的匹配，让模型可以用那个确切的工具名重试（或发送空请求以获取完整目录）。请求中给出确切工具名时跳过决策调用，立即揭示。

为什么？

全新会话、第一条消息、服务端上报的 usage.prompt_tokens——DSH Standard 预设（平台默认）对比本插件的 no-prefill 预设：

| 说出第一个字之前的开销 | Standard | no-prefill |
| Prefill token | 6,559 | 283 |
| 系统提示词 | 5,816 字符 | 372 字符 |
| 预先发送的工具 schema | 26 个 schema（21,417 B） | 1 个 schema（697 B） |

Standard 让模型在说出第一个字之前先消化 5.8k 字符的系统提示词，外加每一个已挂载工具的 schema——共 6,559 token——而且之后每一轮都要再付一次。no-prefill 只消化 283 token（少 23 倍，prefill 缩小 96%）：一个精简人设，加上单个 find_tool schema。在实测后端上，这个差异意味着首条回复的提示词评估耗时约 40 秒，对比约 14 分钟。

这带来什么：

- 延迟——首字时间如今随整个工具架伸缩。按需揭示让它随你实际调用的工具伸缩。
- 上下文预算——6.5k token 的常驻前言，就是 6.5k token 你没法用于代码、对话和结果。在 32k 窗口上，这意味着开工之前就花掉了模型世界约 20%。
- 小模型上的可靠性——读 26 个 schema 的模型，行为就像在读 26 条绝不能违反的指令。一次一个 schema，就只需遵循一个 schema；架子上其余部分对它不存在。
- 用多少付多少——不调用任何工具的一轮花 283 token，而不是 6,559。调用一个工具的一轮只揭示那一个 schema 一次；其余 25 个从不发送。

如果一次会话最终用上了大部分工具，差距会缩小——但架子上没用到的另一半，正是默认配置档从第一个字起就在收费的部分。

捆绑补丁声明了什么

cordis.patch.yml（选中捆绑包时应用）：
1. preset-no-prefill —— 一个智能体预设，组成只有 persona + dsh-tool-router。persona 告诉模型：没有声明任何工具；先调用 find_tool——如果结果不带 schema，就用精确的工具名或空请求重试，不要放弃。
2. 启用宿主工具行 —— tool-bash、tool-fs、tool-fs-search、tool-todo、tool-web 翻转为 disabled: false，并插入一行 present。发现机制需要工具在某个地方存在；预设作用域的注册会遮蔽宿主注册，所以其他预设保持各自行为。精简预设让 Agent Presets 页面只显示 find_tool。

前置条件

- DSH 0.2.0-rc.2（用 dsh.bundle.patch 打包机制）。
- 一个运行中的决策模型 API，支持 POST /v1/systemone（路由器默认指向 http://127.0.0.1:8081/v1/systemone；改 index.js 里的 ROUTER_BASE 可指向别的主机或端口）。
- 运行 DSH 的主机 PATH 上有 pnpm（插件管理器通过 pnpm 安装；命令行转发 pnpm 参数）。

安装

从 GitHub 安装（推荐）： Plugins → install → spec

git+https://github.com/residenthiago2011/DSH-Tool-Router.git

或用命令行：

dsh plugin --profile <profile> add git+https://github.com/residenthiago2011/DSH-Tool-Router.git

从预构建 tarball 安装： 从 Releases 下载 dsh-tool-router.tgz，再从本地路径安装（也接受：绝对路径、git URL，或发布后的 npm registry 名称）：

dsh plugin --profile <profile> add /path/to/dsh-tool-router.tgz

然后在 Plugins 页面选中 bundle（安装时默认启用）；如果配置档运行时不带 HMR，重启 DSH。

卸载

在 Plugins 页面取消选中或移除 bundle。预设行和宿主工具翻转随 bundle 补丁一起消失；其他预设不受影响。

文件

| 文件 | 用途 |
| index.js | 路由器插件：注册 find_tool，按智能体遮蔽其他所有工具，运行 3 阶段决策。 |
| cordis.patch.yml | bundle 补丁：预设声明 + 宿主工具启用。 |
| tool-registry.json | Stage-0 标签和 Stage-1 判据（25 个工具，两个 shell 含 bash）。 |

测试

node router-import-test.mjs # module shape (no dependencies)
node rank-sim.mjs # Stage-0 ranking on sample queries (needs tool-registry.json)
node router-e2e-test.mjs # full flow: arm/deny-set/live reveal — requires the decision endpoint at 127.0.0.1:8081

router-e2e-test.mjs 用一个桩 DSH 上下文，同步发出 tools/change（最坏情况，曾导致约 970 倍反馈循环），然后对着实时决策端点驱动真实的 find_tool：armed-once、deny-set 去重、延迟注册、reveal 重新 arm、空请求目录提示，以及精确名称快速路径。预期输出 ALL_PASS。

说明

- find_tool 用标准 JSON Schema 注册（type/properties/required/additionalProperties）。如果直接用作者风格的参数裸注册，LLM 收到的就是无约束的 schema，模型随后会拿 {} 来调用。务必先编译。
- 空请求时的目录提示和精确名称快速路径是为小模型准备的；见 index.js 里的 execute()。