---

它是做什么的

大多数编码 Agent 会把每一个可用工具的 JSON Schema 都塞进提示词—— 包括模型最终根本不会用到的工具。dsh-lazy-tools 颠覆了这个模型：工具 默认被延迟（deferred），只有当模型主动请求时才进入上下文。

被延迟的工具会从模型可见的工具集中剔除，因此它们的 schema（乃至名字） 永远不会进入模型上下文。模型通过 tool_search 按需发现它们，激活后 即可直接调用。

这是一个纯粹的暴露控制层：

• 它不拥有、也不实现任何工具。
• 被延迟的工具是全局注册表里的工具（包括 MCP 等第三方工具）；本插件只持有 它们的 name / description / parameters 用于发现。
• 它不代理执行——tool_search / defer_execute_tool 只负责激活，激活后 模型直接调用该工具本身。

因为完全实现在 agent 层，它适用于任何模型与任何提供商（DeepSeek、 OpenAI、Anthropic、Gemini……），不依赖提供商原生的延迟工具协议（如 Anthropic tool_reference 或 OpenAI 的 deferred-tool input items）。

特性

• 🔍 按需发现 — tool_search 通过精确工具名（tool_names）或关键词 （queries，中英文均可）查找工具，命中即激活。
• ⚡ 懒激活 — 命中的工具加入该 agent 的可见集合，下一轮模型请求即可 直接调用。
• ⚡ 按名激活 — defer_execute_tool 按精确工具名直接激活一个已知工具。
• 🧭 无侵入 — 在 agent.ctx 上通过 ctx.tools.restrict() 过滤可见工具， 与父/子代理的既有限制天然取交集，绝不放宽其他策略。
• 🎛️ 灵活配置 — CodeBuddy 风格 Defer(...) / NoDefer(...) 模式，支持 * 通配符与全局 deferToolLoading 开关。
• 🛡️ 自保守卫 — tool_search 与 defer_execute_tool 注册在 agent 自身作用域， 永不被延迟，Defer(*) 无法把系统锁死。

安装

从 GitHub 仓库安装为外部 bundle：

dsh plugin --profile <profile> add git:github.com/studyzy/dsh-lazy-tools

也可以先 git clone 到本地，再从本地目录安装。该 bundle 通过 cordis.patch.yml 注入一个名为 lazy-tools 的插件。

配置

配置写在 profile 的 cordis.yml 中该插件的 config 字段下，使用 CodeBuddy 风格语法：

- id: lazy-tools
  name: '@deepseek-ai/dsh-lazy-tools'
  config:
    defer: ['glob', 'web_search', 'Defer(fetch_*)']
    noDefer: ['bash']
    deferToolLoading: true

键	类型	默认	说明
defer	string[]	[]	要延迟的工具名或 Defer(pattern) 条目。裸名等价于 Defer(name)。* 是唯一通配符——Defer(*) 延迟除守卫工具外的所有工具。
noDefer	string[]	[]	必须保持可直接调用的工具名或 NoDefer(pattern) 条目。裸名等价于 NoDefer(name)。始终优先于 defer。
deferToolLoading	boolean	true	全局开关。为 false 时不延迟任何工具。

修饰符大小写不敏感（defer(bash) ≡ Defer(bash)）。优先级（从高到低）： noDefer > defer > deferToolLoading。

示例

# 延迟所有 fetch_* / web_* 工具，始终保持 bash 可用
config:
  defer: ['Defer(fetch_*)', 'Defer(web_*)']
  noDefer: ['bash']

# 延迟除守卫工具对（tool_search / defer_execute_tool）之外的一切
config:
  defer: ['Defer(*)']

# 按前缀延迟 MCP 网关工具
config:
  defer: ['mcp*']

工作原理

组件	作用
tool_search	搜索当前不可见的工具。tool_names 精确查找，queries 关键词查找（中英文）。命中即把工具加入可见集合并返回匹配结果。
defer_execute_tool	按精确工具名激活一个延迟工具，使模型可直接调用。适合激活已知名字的工具。
拦截	tools/pre-execute 监听器会在模型直接调用未加载的延迟工具时返回 deny，提示先调用 tool_search 或 defer_execute_tool。
激活	命中的工具写入该 agent 的 restrict({ allow }) 集合，从下一轮模型请求开始对模型可见、可直接调用。

流程

Prompt: 只有 tool_search + defer_execute_tool 的 schema 可见
   │
   ▼
model: tool_search({ tool_names: ["glob"] })
   │  └─ 返回 glob 的匹配状态，并把它加入该 agent 的可见集合
   ▼
下一轮: model 直接调用 glob（完整 schema 已进入工具列表）

设计约束与已知限制

• 激活后下一轮生效。 tool_search 激活工具后，当前模型请求的工具列表 已经固定（schema 在下一轮请求头才更新），因此同一轮内直接调用仍会被 tools/pre-execute 拦截。请在结果返回后、下一轮再调用。
• 延迟工具在搜索前不可见。 模型看不到延迟工具的名字，只能依赖 tool_search 的检索来发现它们。
• 与其他限制取交集。 插件只挂自己的 allow 子集，绝不放宽其他 restrict （如父/子代理策略）。被其他策略拒绝的工具即使被搜索命中也会标记为 unavailable。
• 状态不跨会话持久化。 已加载的工具集仅在当前进程内生效；resume / fork 后新 agent 会重新按配置延迟。这是为了避免外部插件写入未在 KNOWN_SESSION_EVENT_TYPES 注册的自定义会话事件。
• 仅全局工具。 已注册在 agent 自身作用域的工具始终可见，不在延迟目录内。

开发

pnpm install
pnpm run typecheck   # TypeScript 类型检查
pnpm test            # vitest 单元 + 集成测试
pnpm run lint        # oxlint
pnpm run build       # tsc + tsdown 打包到 lib/

License

本项目以 MIT 许可证发布。