工具抽屉 · dsh-tool-drawer

中文 | English

装上两百来个工具之后，问题会变得很明显：模型每一轮都要把这些工具的说明读一遍——哪怕这次只需要改一个错别字。一晚上下来，真正被调用过的工具往往不到一半。

工具抽屉处理的就是这件事：平时用不上的工具组收起来，要用的时候再放出来。

状态：0.11.0。 在一台机器上日常使用。配置面仍可能变化。Issue 和 PR 都欢迎，维护是尽力而为；需要稳定保证请自行 fork。DSH 若实现原生按需加载，这个项目应当退场。

---

省了多少

实测：本机 181 个工具，四组共收起 92 个。

92 × 220 ≈ 每轮约 2 万 token。

220 的来源：一份 140 个工具的清单实测约 31.1k token，折算每个工具约 220 token，再按比例外推到 92 个。属于外推值，可作量级参考，不宜当精确账目。

省下来的是上下文占用和首字延迟。账单收益受前缀缓存影响：工具表稳定时大部分内容本来就命中缓存，实际省下的钱远小于 2 万 token 的名义值。

怎么做到「不读」

DSH 的工具注册表支持按 agent 隐藏全局工具，接口是 restrict({ deny: [...] })。

每个 agent 创建时，把配置组内的工具填进 deny，它们就从模型可见的工具表里消失；解除这条限制即恢复。

整个过程不引入：

• 代理进程（调用不经过中间层）；
• 向量检索（不额外跑模型判断意图）；
• 包装器（真实调用仍是原生调用，参数校验不变）。

不用向量路由的原因：路由错一次，需要的工具会被静默藏掉，模型只会回「没有这个能力」；另外为省 token 引入一个 90MB 编码器并不划算。

装法

这是一个 bundle：宿主半边加一个设置页的客户端半边。clone 到任意位置，用插件管理器安装：

plugin_manager install_bundle  target: /你的路径/dsh-tool-drawer

不建议手改 cordis.patch.yml——手写也能运行，但只有宿主半边，没有设置页。

bundle 自带的 patch 已配好四组：

组	收起数量	保留（永不收起）
桌面·看	19	无
桌面·点	37	无
浏览器·重	28	open / content / a11y / click / type / wait
视觉·重	8	describe / ocr / crop / bootstrap / materialize / present

改组成员改 checkout 里的 cordis.patch.yml。配置改动重载生效；改宿主代码需要重启进程。

组怎么配

字段	说明
id	组 id，工具调用时使用
match	匹配式数组。普通字符串按 glob 处理（* 通配、整串锚定）；re: 开头按正则处理
keep	有意保留可见的工具名，不会被判定为「漏网」
expect	该组应有的工具数量；对不上时 health 会警告
defaultOn	false 表示默认收起
autoHints	关键词表；用户消息中出现这些词时，在模型读取消息之前打开该组
title / hint	供 status 展示的标签

autoHints 采用子串匹配，需要注意变体：配置 截图 时，用户输入「截个图」匹配不到。常见写法都应列入，例如 截图、截个图、截屏、看窗口。

八个工具

工具	作用
lazy_tools_status	查看每组状态：开关、模式、匹配数量、可见数量、是否热、上次使用时间
lazy_tools_enable	打开一组；only: ['名字'] 只放指定工具，其余保持收起；groups: [...] 批量打开
lazy_tools_disable	收起一组，同时清除 only 白名单
lazy_tools_list	列出组内工具，包含当前被隐藏的
lazy_tools_resolve	只知工具名时使用：按名称或片段定位所属组，只放出该工具
lazy_tools_mode	仅修改当前会话策略；reset 回全局，collapse 立即清空
lazy_tools_scan	按名字前缀对可见工具分桶，便于编写新的组匹配式
lazy_tools_health	自检四个宿主契约，并输出 warnings、漏网工具、自动打开次数、自愈次数

healthy: true 表示：四个契约均通过，无错误，无警告。

设置页

lib/config.js 导出 schema，DSH 设置页据此渲染字段：

字段	默认	说明
level	medium	收敛力度：低 14 天、中 7 天、高 3 天
presets	{14,7,3}	三档各自的天数，可修改
idleDays	跟随 level	手动指定天数；0 表示不按时间收敛
minTools	3	工具数量少于此值的组不处理
showDock	false	在输入框上方显示档位按钮
showClear	false	在输入框上方显示独立的「立刻清空」按钮

两个界面开关互相独立。控件按对话挂载，勾选后需切换一次对话（或刷新页面）才会出现。

组定义保留在 bundle 的 patch 中：写一次后很少改动，且嵌套数组在表单中可读性差。

schema 在运行时解析：扫描 %USERPROFILE%\.dsh\profiles\*\ 查找 DSH 自带的 @deepseek-ai/schemastery，只使用 Node 内置模块。未找到时 Config 为 undefined——没有设置页，插件本身正常运行。

设置页写入的策略保存在 ~/.dsh/lazy-tools.policy.json，优先级高于 YAML 默认值；删除该文件即回到默认。

为什么它表现得像会自己判断

它不判断，只按证据触发。三个机制都不包含猜测：

一、用量账本。 每次真实调用记录一条时间戳到 ~/.dsh/lazy-tools.usage.json（只记时间与工具名，不记参数）。新会话开始时计算：某组在 idleDays 内被使用过，则默认打开；否则默认收起。

该决策仅在会话开始时执行一次，运行期间不改动。原因：中途修改工具表会使前缀缓存失效，省下的 token 不足以抵消损失。

二、关键词预开。 用户消息进入 inbox 时，宿主发出 agent/inbox/inserted 事件。此时检查文本，命中配置词即打开对应组。

关键在于时机：模型读取消息之前，工具已经在工具表中。

该机制从不自动关闭；每次自动打开都会计数（health.autoOpened），便于事后核查误开。

三、自愈。 当模型调用被隐藏的工具时，一个 dispatch 守卫会在调用被拒绝之前拦截：识别所属组，只放出该工具，并返回「已为你打开，请重新调用一次」。

模型重试即成功，用户侧无感知。次数记录在 health.selfHealed。

它防的是什么

漏网工具。 插件升级新增工具而组匹配式未覆盖时，该工具会重新变为可见并持续占用 token。health.stray 会推导每组的名字前缀，列出「看起来属于该族、但未被任何组匹配」的可见工具（keep 中的除外）。

数量漂移。 每组配置 expect（应有数量）；工具数量变化时 health 直接告警。

客户端没挂上。 health.client 记录浏览器那半边最后一次上报（seen / at / agoSeconds / 挂了哪些面板）。宿主一切正常不等于设置页挂上了：2026-10-24 就出现过「宿主四项契约全绿、客户端条目加载失败、Web 进恢复模式」的情况，这个字段把那类问题从「只能靠重启发现」变成一条能查的数据。

竞态。 子 agent 可能在限制建立过程中被销毁，此类失败记为「agent 已销毁」，不计入失败次数，避免污染体检结果。

孤儿限制。 解除函数挂在 ctx.effect 上，热重载时会被解除，不会残留限制导致 enable 假成功。

测试

node test/smoke.mjs

32 项断言，运行在假宿主上，不需要安装 DSH。

假宿主只实现本插件依赖的四个契约。宿主契约变化时，测试先失败，而不是会话先出问题。

要改这个插件？先读 MAINTAINING.md：改客户端半边必须冷启动验证，恢复模式下用户无法操作。

局限（请务必阅读）

1. 只能隐藏全局工具。 注册在 agent 作用域中的工具无法隐藏，宿主会拒绝。
2. 按名字分组。 DSH 的工具定义没有标签，只能对名字写 glob 或正则；改名会导致漏配。
3. 开关会打断前缀缓存。 打开一次后尽量保持；需要反复切换时优先使用 only:，不要整组开关。
4. 自动收敛只在会话开始。 运行期间不重排，理由同上。
5. 失败方向是放开。 契约异常或文件不可读时，工具全部回到可见状态：多花 token，但不会减少能力。
6. 自愈只对「存在但被隐藏」的工具有效。 拼写错误、尚未加载的插件无法修复，这类情况使用 resolve 按片段查找。
7. 界面双语，工具描述不是。 设置面板和输入框那一行跟随宿主语言服务；模型读取的工具描述在启动时注册一次，仍为中文——宿主进程无法感知界面语言。

退场条件

DSH 已带有 deferLoading 与工具增补消息。若其实现原生按需加载，这个项目应当退场，而不是继续并行维护。

借鉴与参考

这里没有原创机制，只有取舍。前三个项目阅读较深，其余主要参考 README：

项目	做法	取舍
tool-attention（论文）	每轮基于 embedding 的意图路由，两段式加载 schema	量化了「工具税」；未采用 embedding，因为路由错误会静默隐藏所需工具
mcp-lazy-load	MCP 代理，暴露 search_tools / execute_tool	证明可大幅缩减；选择保持原生调用，不经过通用执行器
dsh-mcp-loader	DSH 插件，按服务器加载并对 agent 施加 restrict 掩码	同一机制层；本实现不绑定命名空间，并增加 only:
lazy-mcp	代理层，按服务器分树	分组词汇参考
opencode-lazy-loading	请求层剥离	大幅缩减说法的参考
dsh-sieve	DSH 上下文过滤，带裁判模型	避免「模型在环」判断的理由
microsoft/agent-framework 的 progressive disclosure 示例	按需暴露 MCP 工具	术语参考

若相关作者认为描述有误，可开 Issue 指正。

它不是什么

• 不是代理、网关或 MCP 客户端。 不接触传输层，不增加跳跃。
• 不是自动路由。 不猜测用户意图，仅在明确请求时打开。
• 不是安全边界。 隐藏只是从模型列表中移除，不阻止执行；权限控制请使用宿主机制。

许可

MIT，见 LICENSE。

---

English summary

Tool Drawer for DeepSeek Harness: keeps heavy tool groups out of every request and restores them on demand (one call, a keyword, or a dispatch guard). 181 tools, 92 hidden, ≈20k tokens per request avoided on one machine (extrapolated). No proxy, no embeddings, no judge model — real calls stay native. Install with plugin_manager install_bundle; configure in the DSH settings page. MIT, best-effort maintenance.