DeepSeek Harness 工具执行流水线:一次工具调用的守卫、执行与定格
本文是
dsh官方参考「工具执行流水线」的导读。上一篇文章《Agent 生命周期》里,工具调用只是时序伪代码里的一行tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*;这一篇把它完整展开——一次工具调用如何被三组 waterfall(瀑布式事件)层层改写,最终定格为一条tool/result事件。
〇、先记住一句话
一次工具调用 = 三次 waterfall(pre-execute/execute/post-execute)+ 一次结果定格(快照 →finalizeContent→tools/result)。
- 前置瀑布(
tools/pre-execute)管"能不能跑":钩子、权限、沙箱、审批; - 执行瀑布(
tools/execute)管"怎么跑":超时、重试、指标包裹工具体; - 后置瀑布(
tools/post-execute)管"结果怎么用":接受、阻止、替换、添加上下文; - 结果定格:注册表对结果做无损快照,
finalizeContent执行最后的仅内容不变式,tools/result同步通知,最终冻结为唯一一份模型可见的权威事实。
理解这条主线,后面所有细节都是它的展开。
一、全景:一次工具调用的完整旅程
先看整体流程图,再逐段拆解。
graph TD A[Assistant message 含 tool-call 块] --> B[Session event: tool/call执行前记录] B --> C[UI pending cardpresentCall args] C --> D[”tools/pre-execute waterfallhooks · permission · sandbox”] D --> E{单调守卫 deny 或 abstain+ ctx.approval 一次性审批} E -- ”denied 或 审批被拒” --> F[工具体被跳过denied · rejected · cancelled] E -- allow --> G[”tools/execute waterfalltimeout · retry · metrics 环绕 dispatch”] G --> H[注册的工具 execute body] H --> I[Tool-owned 事件todo/write · fs/observed · hook/* · tool/code-dispatch] I --> J[”tools/post-execute waterfallaccept · block · replace · add context”] J --> K[Registry 外层规范化无损快照 pipeline/result] K --> L[ToolDefinition.finalizeContent最后仅内容不变式] L --> M[tools/result 同步通知冻结的权威结果] M --> N[Active-batch additionalContexts FIFO结果之后注入 user/message] N --> O[Session event: tool/result单一 model-facing 结果] O --> P[Tool batch settled 批次结算] P --> Q[UI completed cardpresentResult args result]
注意图里最关键的一句话:tools/pre-execute→ 单调守卫 →tools/execute→tools/post-execute这三个 waterfall 可以改写一次调用;而 finalizeContent 与 tools/result 在它们之后运行,由工具定义自身控制,不再参与改写。
二、起点:模型发出 tool-call
流水线从模型输出一个工具调用块开始:
- Assistant message 包含 tool-call 块——模型决定调用某个工具;
- Session event:
tool/call在执行之前就被记录下来(持久化事实,可回放); - UI pending card:界面立刻展示一张"进行中"卡片,调用
presentCall(args)把参数呈现给用户。
从这一刻起,调用进入流水线。注意顺序:先落tool/call事件、再进守卫——即使后面被拒绝,这次"试图调用"的事实也已经留档。
三、第一道闸门:tools/pre-execute waterfall
这是调用能否放行的第一道(也是最主要的一道)闸门。它承载三类关注点:钩子(hooks)、权限(permission)、沙箱(sandbox)。各种插件挂在这里,对调用做出裁决。
3.1 可能的裁决
瀑布式事件允许每个监听者对调用做出自己的决定:
| 裁决 | 含义 |
|---|---|
allow |
放行 |
deny |
拒绝… |