一次工具调用要过哪些关卡
核验于 2026-10-31dsh 0.2.1-rc.5版本说明
模型发出一句 tool call 之后,真正执行这次调用的是 ctx.tools 注册表,不是工具函数本身。注册表先给这次调用拍一张不可变的参数快照,然后按固定顺序执行后面八步:前置策略 tools/pre-execute、审批 serviceAsk()、单调守卫 guardReason()、环绕分发 tools/execute、工具正文 execute()、内容投影 projectContent()、后置策略 tools/post-execute、最终冻结 finalizeContent() 与 tools/result。
任何一步返回的拒绝或失败,都会变成一个模型能读到的工具结果,而不是以未捕获异常的形式中断 agent loop。这是 dsh 工具流水线最重要的设计选择:错误是数据,不是控制流异常。

源码坐标
tools/src/index.ts:1399-1492—createExecution():参数快照、token/callId、捕获 finalizertools/src/index.ts:1501-1548—prepareExecution():pre-execute、ask 解析、guard 检查tools/src/index.ts:1735-1775—serviceAsk():审批结果如何映射成 allow/denytools/src/index.ts:1144-1162—guard()与guardReason():单调守卫的注册与检查tools/src/index.ts:1609-1641—dispatchScheduledExecution():tools/execute环绕与结果规范化tools/src/index.ts:1572-1600—dispatchToolBody():调用注册的工具正文tools/src/index.ts:1649-1671—finalizeScheduledExecution():projectContent 在 post-execute 之前tools/src/index.ts:1789-1811—postExecute():accept、block、替换内容、附加上下文tools/src/index.ts:1677-1725—finishScheduledExecution()、applyFinalContent()、notifyResult()tool-calls.ts:60-113— agent loop 的工具调度:屏障、滚动池、模型顺序提交tool-calls.ts:264— 执行前写tool/calltool-calls.ts:282— 按模型顺序写tool/result
先看一张顺序表
| 顺序 | 阶段 | 代码入口 | 产出 |
|---|---|---|---|
| 1 | 拍参数快照 | createExecution() | 冻结的参数、callId、捕获的 finalizer |
| 2 | 前置策略 | tools/pre-execute | allow / deny / ask / cancel |
| 3 | 审批 | serviceAsk() | allowed-once / rejected / cancelled / unavailable |
| 4 | 单调守卫 | guardReason() | 拒绝理由或弃权 |
| 5 | 环绕分发 | tools/execute | 规范化结果,或取消 |
| 6 | 工具正文 | execute() | 工具自己的 canonical 值 |
| 7 | 内容投影 | projectContent() | 执行准备好的 content |
| 8 | 后置策略 | tools/post-execute | accept / block / 替换 / 附加上下文 |
| 9 | 最终冻结 | finalizeContent() → tools/result | 不可变结果 + 同步通知 |
九步的先后顺序固定在注册表里:各个事件只能改变某一步的决策或内容,不能改变步骤之间的先后。
createExecution:先冻结参数快照
createExecution() 做的第一件事,是对模型给的参数执行 snapshotJsonValue(),再执行 deepFreeze()。参数如果不能无损地 JSON 往返,createExecution() 就直接抛 TypeError,这次调用在进入前置策略之前就失败。先把参数冻结下来,后面每个监听器看到的才是同一份不可变参数,不会出现“审批时看到的参数”和“工具执行时收到的参数”不一致。
createExecution() 还在参数物化之前捕获 projectContent 和 finalizeContent 两个回调。原因是参数可能是一个 getter,读取 getter 的物化过程本身就能触发副作用,甚至换掉注册表里的回调;先捕获,才能保证这次调用用的是调用开始时的契约。callId 和 token 也在 createExecution() 里生成,作为这次调用的稳定身份。
PTC(Programmatic Tool Calling:让模型写一段代码、由这段代码通过生成的 SDK 去调用工具的模式)有一个例外:某个工具在当前 scope 里被折叠成只能从 run_code 程序里调用,而模型仍然直接发起这次调用时,注册表会在进入前置策略之前就拒绝。拒绝发生在 tools/pre-execute、审批和守卫之前,这三个环节都不会收到一个注定失败的调用。注册表给出的仍然是一个规范的错误结果,而不是异常。
pre-execute:唯一的扩展闸门
tools/pre-execute 是 waterfall。监听器收到 (exec, next),可以:
- 不调用
next(),直接返回deny、ask或cancel; - 调用
next()把这次调用交给后面的监听器处理,再对拿到的返回值做包装。
next() 的默认值是 allow。监听器如果只观察、不决策,就必须调用 next();否则监听器会静默短路整条流水线。这是 waterfall 与普通事件最容易混淆的地方。
异步监听器必须观察 exec.signal。注册表会等异步监听器返回的 Promise settle 之后再重新检查取消状态,但不会抛弃一个已经开始的 Promise;也就是说,取消不会中断同一进程里已经在运行的代码,只会让最终结果带上取消语义。
如果决策是 ask,注册表调用 serviceAsk()。如果决策是 deny,注册表不会立刻抛异常,而是生成一个 isError 的 post-result,交给后面的内容投影和后置策略继续处理。deny 跳过的是工具正文,不是内容投影、后置策略、最终冻结这几步收尾。
approval:ask 才进入
serviceAsk() 把审批结果映射成四种情况:
allowed-once:这一次调用放行。rejected:用户拒绝,转成deny。cancelled:审批取消,转成deny,并标记approvalCancelled。unavailable:没有审批通道,转成deny,理由是“需要审批但通道不可用”。
默认拒绝是审批环节的安全边界:没有审批通道时,ask 不会变成 allow。serviceAsk() 只解析一次,解析结果随后交给守卫;守卫仍然可以否决一个已经获批的调用。
guards:只能否决
guard() 注册的是同步函数:返回字符串表示拒绝理由,返回 undefined 表示弃权(不参与这次判断)。检查顺序是先看全局,再沿 scope 链从远到近逐个检查。任何一个 guard 返回拒绝理由,注册表就拒绝这次调用;没有任何 guard 能强制放行另一个 guard 已经拒绝的调用。
“单调”指的就是这条规则:guard 只能追加拒绝理由,不能把别的 guard 已经拒绝的调用改回放行。guard 保护的是不该被后续策略覆盖的不变量,例如“先读后编辑”这类所有者策略。pre-execute 是可扩展的、可以返回 ask 的;guards 在 pre-execute 之后运行,只做确定性检查,不参与审批,也不接受 next()。如果 pre-execute 已经返回 deny,guards 根本不会运行;只有拿到 allow 的调用才进入 guardReason()。
execute:环绕分发
tools/execute 是环绕 waterfall:监听器拿到 (exec, next),可以在真正的分发前后加上自己的处理。超时、重试、指标这类横切关注点适合由 tools/execute 监听器实现;工具 schema 里的 timeoutMs 就是由名为 dsh-tool-call-timeout-policy 的 tools/execute wrapper 执行的,而不是硬编码在注册表里。
wrapper 只能改 exec.signal,不能改调用身份。注册表会在进入工具正文之前,把调用方原始 signal 重新融合回来,所以 wrapper 换 signal 不能切断调用方的取消。wrapper 还必须让自己的工作在返回前达到静止;注册表不会抛弃已经开始的 Promise。
dispatchToolBody() 调用注册的 execute()。如果调用方在工具正文开始之后取消,正文仍会执行到静止;最终结果是 ABORTED 还是 ABORTED_BEFORE_DISPATCH,取决于注册表记录到的取消时点。区分两个状态,是为了让模型知道“工具没开始”还是“工具做了一半”。
projectContent:执行后的内容准备
结果从工具正文返回后,finalizeScheduledExecution() 先调用 projectContent,再调用 postExecute。先后顺序不能颠倒:投影给出的是工具自己声明的“执行准备好的内容”,后置策略要看到投影之后的结果。
projectContent 的返回值只替换 content,其他字段仍由注册表拥有。策略在 post-execute 里的替换仍然有最终决定权;如果管线失败、跳过了 post-execute,投影也不会运行。
projectContent 在调用开始时被快照,每次调用只运行一次。projectContent 不是通用的结果钩子,而是工具定义自己的内容准备步骤。
post-execute:接受、改写或阻止
tools/post-execute 也是 waterfall。监听器可以返回:
accept:保留成功结果,可以替换content或value,但不能同时替换两者;block:把结果变成isError,feedback成为模型看到的内容;additionalContexts:把额外的用户消息附加到结果上,供 agent loop 注入下一批。
工具抛出的错误同样会进入 post-execute。注册表先把异常收敛成规范的 isError 结果,再交给后置策略;所以后置策略既能修正成功结果,也能修正失败结果。
被 deny 拒绝的调用同样会进入 post-execute:工具正文没有运行,但内容投影和后置策略仍会收到带 isError 的结果。后置策略因此可以在同一个位置纠正或者补充拒绝理由。
additionalContexts 的生命周期有一个细节:工具正文通过 deferContext() 延迟的上下文,在结果被 accept 时会保留;如果外层调用被 block,延迟上下文会被丢弃,只保留 block 决策自己显式给出的上下文。这样 block 决策不会把一个失败调用的副作用带进下一轮。
finalizeContent 与 tools/result
finishScheduledExecution() 依次做四件事:
- 物化候选结果;
- 应用
finalizeContent; - 再物化一次;
notifyResult()发出tools/result。
finalizeContent 是工具定义的最后一道内容变换。注册表在调用开始时快照 finalizeContent;每次调用恰好运行一次,即使管线失败、跳过了 post-execute 也一样。契约要求 finalizeContent 同步执行、只改内容、不要抛异常;万一 finalizeContent 仍然抛出异常,注册表会把异常收敛成 isError,不会让观察者收到不完整的结果。
notifyResult() 先执行 Object.freeze(exec),再把冻结后的执行对象和结果一起发给 tools/result 观察者。tools/result 用的是 emit,不是 waterfall:观察者不能改写结果,观察者抛出的错误也只会被记录,不会影响最终返回的结果。遥测、日志和 UI 因此可以安全地做旁路观察。
注意区分两个名字:
tools/result:注册表发出的同步观察事件,参数是冻结后的执行对象和结果。tool/result:agent loop 追加到 Session 日志的持久事件,模型下一轮从日志里读到这条事件。
tools/result 是进程内的通知,tool/result 是模型可见的历史。
agent loop 记录的两条日志
executeToolCalls() 在 agent loop 这一侧调度工具。executeToolCalls() 先按 executionMode 分类:独占调用形成屏障,可并行的调用进入有界滚动池;每次启动一个调用之前都重新分类,所以注册表在运行中发生变化时,新出现的独占调用会形成一道新屏障。
startCall() 的顺序是:先用 appendToolCall() 写 tool/call,再调用 prepare(),再调用 dispatch()。也就是说,一次调用只要开始准备,日志里就先有一条 tool/call;即使这次调用随后被策略拒绝或者执行失败,模型也能从日志里看到调用发生过。
agent loop 按模型发出调用的先后顺序提交 tool/result,即使实际执行是并发完成的。某个 step 失败时,turn() 的恢复逻辑会把已经结算但还没提交的工具结果补写进日志,避免出现“工具已经执行、模型却没有看到结果”的缺口。
自己验证
下面的检查不需要模型 Key。第一步是确认 Web profile 的 tools 行确实被 web-app 重写过:
dsh --profile web --dump-config | grep -A6 "id: tools"
预期能看到:
- id: tools
name: '@deepseek-ai/dsh-tools'
config:
mode: !!js process.env.DSH_TOOLS_MODE
mode 来自 web-app 的 patch,!!js 表达式在 Loader 激活时求值;dump 里保留原文。
第二步是确认四个流水线事件的位置:
grep -n "'tools/pre-execute'\|'tools/execute'\|'tools/post-execute'\|'tools/result'" \
packages/core/tools/src/index.ts
在 dsh-v0.2.1-rc.5 上,预期是第 154、165、177、199 行。行号会随版本移动,函数名和事件名更稳定。
想要观察真实调用,你可以装一个只读的钩子插件:
# 需要 pnpm
dsh plugin --profile pipeline add ./examples/02-pipeline-hook
dsh --profile pipeline --dump-config | tail -4
预期输出:
# == dsh-plugin-pipeline-hook
- id: pipeline-hook
name: dsh-plugin-pipeline-hook
启动名为 pipeline 的 profile:
dsh --profile pipeline web --no-open
仍然不需要模型 Key,终端就会出现下面这一行:
[pipeline-hook] loaded; observing tools/pre-execute, tools/post-execute, tools/result
日志里出现这一行,说明 inject: ['tools'] 已经等到工具服务、插件挂载成功。配置了 Key 并触发一次工具调用时,终端还会依次出现 pre-execute、post-execute、result 三行;钩子只打印日志并调用 next(),不改写任何决策。本次核验只验证到 loaded 这一行,带 Key 的三行没有实跑,因此不算已观测。
想离线确认插件是否进入 profile,你可以执行 dsh --profile pipeline --dump-config,命令输出的末尾会出现 dsh-plugin-pipeline-hook。
四个常见误解
“deny 会抛异常。” 不会。deny 是一个正常的 isError 结果,仍会经过内容投影和后置策略,模型看得到、也能据此纠正。真正抛出异常的是监听器或者管线本身;注册表会把这类异常收敛成 isError,而不是让 agent loop 因未捕获的异常中断。
“post-execute 只看到成功的工具。” 不是。工具抛出的错误也会先被规范化成 isError 结果,再进入 post-execute;后置策略可以修正失败结果。
“finalizeContent 只在成功时跑。” 不是。每一次规范化结果在物化之前都会运行一次 finalizeContent,包括跳过 post-execute 的管线失败。finalizeContent 在调用开始时被快照,契约要求同步执行、只改内容、不抛异常。
“guard 可以放行被别的 guard 拒绝的调用。” 不能。guards 是单调的:任何一个 guard 返回拒绝理由,这次调用就被拒绝,没有哪个 guard 能强制放行。需要审批或者可以协商的策略,应该写成 pre-execute 监听器,而不是注册成 guard。
官方文档对应位置
- 工具执行流水线:策略、守卫、审批、结果重写与最终观察
- tools README:注册、调度、取消与结果契约
- 架构总览:事件:会话事件、Agent 事件与能力事件的分工
- 安全边界:沙箱、审批与信任模型
上一篇:一条消息怎样变成一个步骤。如果还没读插件树,建议先看一切皆插件,那一页解释了 ctx.tools 注册表是怎么被挂载出来的。
常见问题
deny 和工具抛错有什么区别?
deny 是策略给出的正常结果,会变成 isError 的工具结果,模型看得到并能纠正;工具抛错也会被收敛成 isError,但仍会进入 post-execute。两者都不会中断 agent loop。
guards 和 pre-execute 监听器有什么区别?
pre-execute 是可扩展的 waterfall,可以 allow、deny、ask 或 cancel;guards 在 pre-execute 之后运行,是单调检查,只能返回拒绝理由或弃权,不能强制放行别的 guard 已拒绝的调用。
finalizeContent 在什么情况下运行?
每次规范化结果在物化之前都会运行一次,包括 pre-execute 抛错等跳过 post-execute 的管线失败。finalizeContent 在调用开始时被快照,契约要求同步、只改内容、不要抛异常。
tools/result 和 tool/result 是同一个东西吗?
不是。tools/result 是注册表发出的同步观察事件,参数是冻结后的执行对象和结果;tool/result 是 agent loop 追加到 Session 日志的持久事件,模型在后续请求里从 Session 日志读到这条结果。