一次工具调用要过哪些关卡

核验于 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 工具流水线最重要的设计选择:错误是数据,不是控制流异常。

dsh 工具流水线流程图:tool call 进入 createExecution,经过 pre-execute、approval、monotonic guards、execute 与工具正文,再经过 project 与 post-execute、finalizeContent,最后写入 tool/result 日志
图 1:一次工具调用在主路径上的关卡顺序;红色是拒绝分支,紫色是写入 Session 日志的事件。打开交互版(图可点开看大图)

源码坐标

先看一张顺序表

顺序阶段代码入口产出
1拍参数快照createExecution()冻结的参数、callId、捕获的 finalizer
2前置策略tools/pre-executeallow / deny / ask / cancel
3审批serviceAsk()allowed-once / rejected / cancelled / unavailable
4单调守卫guardReason()拒绝理由或弃权
5环绕分发tools/execute规范化结果,或取消
6工具正文execute()工具自己的 canonical 值
7内容投影projectContent()执行准备好的 content
8后置策略tools/post-executeaccept / 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() 依次做四件事:

  1. 物化候选结果;
  2. 应用 finalizeContent;
  3. 再物化一次;
  4. 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。

官方文档对应位置

上一篇:一条消息怎样变成一个步骤。如果还没读插件树,建议先看一切皆插件,那一页解释了 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 日志读到这条结果。