Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-21

DeepSeek Harness 工具执行流水线:一次工具调用的守卫、执行与定格

本文详解DeepSeek Harness工具执行流水线,拆解工具调用的三组瀑布式事件与结果定格,揭示工具调用完整生命周期。

核心内容:

  1. 前置瀑布(pre-execute):守卫机制(权限、沙箱、审批等)
  2. 执行瀑布(execute):执行机制(超时、重试、指标包裹等)
  3. 后置瀑布(post-execute):结果处理与结果定格(快照、替换、上下文添加等)

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)。

理解这条主线,后面所有细节都是它的展开。


一、全景:一次工具调用的完整旅程

先看整体流程图,再逐段拆解。

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

流水线从模型输出一个工具调用块开始:

  1. Assistant message 包含 tool-call 块——模型决定调用某个工具;
  2. Session event:tool/call 在执行之前就被记录下来(持久化事实,可回放);
  3. UI pending card:界面立刻展示一张"进行中"卡片,调用 presentCall(args) 把参数呈现给用户。

从这一刻起,调用进入流水线。注意顺序:先落tool/call事件、再进守卫——即使后面被拒绝,这次"试图调用"的事实也已经留档。


三、第一道闸门:tools/pre-execute waterfall

这是调用能否放行的第一道(也是最主要的一道)闸门。它承载三类关注点:钩子(hooks)、权限(permission)、沙箱(sandbox)。各种插件挂在这里,对调用做出裁决。

3.1 可能的裁决

瀑布式事件允许每个监听者对调用做出自己的决定:

裁决 含义
allow 放行
deny 拒绝…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/LargeLanguageModel/2026082194360.html