工具系统：模型怎样把“想做”变成“真的做”？

假设你开发了一个“查询订单”工具。只写一个 queryOrder() 函数还不够，因为模型和系统还需要知道：

• 它叫什么；
• 什么时候应该使用；
• 参数有哪些、哪些必填；
• 成功后返回什么；
• 具体怎样执行；
• 在界面上怎样展示。

因此，一项 DSH 工具更像一份完整的岗位说明书：名字和参数给模型看，execute 是真正干活的人，输出声明负责验收结果，展示信息告诉 UI 怎样画卡片。

工具插件启动时，会把这份定义注册到 ctx.tools。多个插件可以各自注册工具，最终组成当前 Agent 可以看到的工具集合。

工具注册表不是一张所有 Agent 完全共享的平面清单。它会结合 Cordis 作用域计算可见性：

• Host 层注册公共工具；
• Preset 层加入某类 Agent 专属的工具；
• Agent 层还可以进一步限制或增加工具。

例如，代码 Agent 可以看到文件、终端与 LSP；客服 Agent 只看到订单查询和退款申请；审计 Agent 可能只保留只读工具。

这也是为什么“给 Agent 增加工具”通常应该放在 Preset 中装配，而不是修改 Agent Loop。Loop 只向 ctx.tools 索要“当前作用域最终可见的工具”。

下面这张表依据源码生成的 docs/tool-catalog.zh.md 整理，覆盖当前仓库中已发布产品工具包提供的全部模型可见名称，包括按需启用和实验性工具。它不包含示例项目里的演示工具、外部 MCP Server 带来的工具，也不包含用户通过插件动态注册的新工具。

需要特别注意，表里的“内置”只表示 DSH 仓库已经提供了相应工具插件，并不表示每个 Agent 会一次性看到它们。标准模式、极简模式和创造模式会装配不同的工具；某些工具还要求 Host 先提供 LSP、Web、Schedule 或 Terminal 等底层服务。这样既能保持核心 Loop 稳定，也避免把与当前任务无关的大量工具说明全部交给模型。

bash 与 pwsh 还有一次性执行和持久执行两套插件实现，但它们对模型暴露的是同一个工具名。实验性的 Agent Teams 插件则会复用 list_agents、send_message 和 interrupt_agent 三个名称，把目标从普通后台子 Agent 换成持久 teammate，因此表中不再重复列出。

每个 Step 的 preStep() 会向 ctx.tools 获取当前 Agent 的工具说明，然后放进模型请求。

普通 Native 模式下，模型看到的是工具名、说明和 JSON Schema。它并没有拿到 execute 函数，只得到一份“可以怎样申请调用”的菜单。

模型返回 Tool Call 时，也不是直接运行本地代码，而是返回类似下面的结构化意图：

tool = "query_order"
arguments = { "order_id": "A1024" }

Agent Loop 收到这个请求后，才把它交给工具注册表。

工具注册表不会找到函数以后立刻执行。每次调用都会经过一条统一路线：

可以把它想成公司采购：提交申请以后，先检查表单，再走权限审批，随后由采购员执行，最后验收并归档。所有部门都走同一套流程，安全规则就不需要复制到每个工具里。

上一课介绍的四种工作模式，最直接的区别之一，就是当前 Agent 能看到哪些工具，以及这些工具以普通 Tool Call 还是 Code Mode SDK 的形式呈现。至于某一次工具调用能否真正执行，还要经过这一课介绍的审批与安全检查。

工具进入 pre-execute 后，审批插件可以返回三种决定：允许、拒绝或询问用户。随后，文件沙箱和其他 Guard 还会检查这项调用是否越过不可突破的限制。

这两层作用不同：

• 审批解决“这一次要不要征求用户同意”；
• Guard 与 Sandbox 解决“即使有人同意，也绝不能越过什么边界”。

业务插件同样可以参与。例如公司内部 Agent 可以在退款工具执行前检查金额，在发布工具执行前要求工单编号，在查询客户数据前验证当前租户。

这些策略都挂在工具流水线上，不必修改工具函数，也不必修改 Agent Loop。

工具 execute 返回以后，系统会检查结果是否符合工具声明的输出结构。随后 post-execute 可以补充、替换或拒绝结果，工具自己的最终内容转换再生成模型真正看到的文字、图片或其他内容块。

为什么不把任意 JavaScript 对象直接扔给模型？因为工具结果还要被记录、重放、通过 API 传输，并在不同 UI 中展示。统一的 JSON 结果与内容格式，让后续环节不必猜测一个工具返回了什么。

最终的 tool/result 会写入 SessionEvent。下一次模型请求通过历史看到它，于是 Agent 才能根据真实执行结果继续思考。

DSH 还允许工具以三种形式呈现给模型。这不是上一课的权限模式，而是模型“怎样看见工具”的选择：

Code Mode 并不是绕过工具流水线。程序里的每次工具调用仍会重新进入参数校验、审批、Guard、执行和结果处理。变化的只是模型组织调用的方式，安全和日志主线没有消失。

可以，但必须由工具明确声明自己适合并行。

只读搜索、互不影响的查询通常可以组成并行调用；文件修改、终端命令和共享状态操作默认按独占方式执行。Agent Loop 会把连续的并行安全调用放进受限并发池，遇到独占工具就先排空前面的任务，再单独执行。

这不是单纯追求速度。并行工具必须保证相互交换顺序不会改变结果，否则日志顺序与真实副作用就可能对不上。

工具定义还可以提供纯展示函数，根据调用参数和已经持久化的结果，告诉 UI 应该画通用卡片、终端输出、文件 Diff、搜索结果或网页结果。

展示函数不能依赖只存在于当时内存里的状态，因为页面刷新或 Session 重放时，UI 仍要画出同一张卡片。

因此 DSH 把三个责任分开：execute 负责做事，模型内容负责告诉模型结果，presentation 负责告诉人类怎样看。

以“查询订单”为例：

• Tool Definition：名称、参数、输出和执行逻辑；
• Provider：真正连接订单数据库或远程 API；
• pre-execute 插件：租户、权限和审批策略；
• Preset：决定哪些 Agent 能看见这个工具；
• UI presentation：把结果画成订单卡片；
• SessionEvent：保存调用与结果事实。

这样划分以后，你可以换数据库 Provider、调整审批规则或把工具交给另一种 Agent，而不用重写整个工具调用流程。

下一课，我们把工具系统放回 Agent Loop：一条用户消息怎样触发模型请求、工具调用和下一次 Step，直到这一轮真正结束？