ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 工作流结果:WorkflowMeta、fatal 纪律与持久记录怎么产出

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness工作流WorkflowResultfatal
工作流跑完但结果字段不全,或一个子步骤失败后整条流程状态不对。本文讲 WorkflowStartRequest 的输入边界、WorkflowResult 的四个事实、WorkflowRun 的取消与释放,以及 fatal 与持久记录协议。

工作流结果不完整,通常不是脚本写错,而是调用方把“部分输出”当成了成功。 DSH plugin 的工作流 seam 明确规定:非 completed 的结果必须映射成 isError 工具结果,而不是上报半截内容。理解这条纪律,才能读懂 WorkflowResult 的每个字段。 DSH插件 写工作流脚本时,fatal 错误必须炸掉,别让组合器吞成 null。

启动请求:meta 与 args 是普通数据

引擎校验数据,绝不对脚本文本求值来拿参数。(来源)

WorkflowStartRequest 包含:script(纯 JS 脚本体,允许顶层 await,以 return <json-value> 结束)、meta、可选 args、可选 subagentProvider、可选 maxTotalAgents、必填 parent 与可选 signal。

普通工作流工具会根据模型的 { script, meta, args } 调用与发起调用的 agent 构建该请求。专用消费方还可以为本次运行选择引擎级 subagentProvider,并把 maxTotalAgents 调低,但脚本无法观察或替换这两项策略。

meta 与 args 是普通 JSON 数据;引擎会用 schema 校验 meta,并在任何工作开始前明确报错并拒绝无效数据。它绝不会通过对脚本文本求值来获取它们。

parent 是必填字段:脚本启动的每个子 agent 都归属于它,cwd、谱系与深度通过 subagent seam 传递。所以“这个子 agent 是谁派出来的”不是靠约定,而是结构上固定的。

WorkflowMeta 本身只做身份与展示:name 是短 kebab-case 名称(展示与持久化键)、description 是一行说明、可选 whenToUse 出现在列表里、可选 phases 仅用于进度展示——phase() 调用与标题匹配供观察者使用,不暗示任何执行结构。

WorkflowResult 的四个事实

value 只在 completed 时有意义,其余三种信息各管一段。(来源)

  • value — 脚本的物化返回值,纯宿主域 JSON 数据;脚本无返回值时为 null。
  • stopReason — 封闭联合,completed、cancelled 或 error。
  • error — 失败信息,当且仅当 stopReason 不是 completed 时存在。
  • agentsStarted — 整个生命周期内接受的 agent() 调用数。

agentsStarted 的口径有个细节:优雅结算时它是脚本侧计数,包含仍在排队等并发槽的调用;在终止路径(取消或进程失败)上,它退化为宿主观察到的计数——被终止脚本内部排队的调用此时不可知。

官方的映射要求很硬:非 completed 的原因要在 error 中携带失败信息,消费方将其映射为 isError 工具结果,而不是把部分输出当作成功上报。

WorkflowRun:result 绝不拒绝

取消与释放是持有者的责任,且必须覆盖每条路径。(来源)

WorkflowRun 提供 id、meta(脚本执行前就可用)、result、cancel(reason?) 与 dispose()。

三条契约:

  1. result 绝不拒绝——脚本失败以 stopReason: 'error' 兑现,取消以 'cancelled' 兑现;
  2. 消费方可以在执行期间调用 cancel,并且必须在每条路径上调用幂等的 dispose();
  3. PTC 引擎没有整体经过时间截止,取消时立即中止受管进程。

dispose() 会按各提供方约定等待进程与子 agent 清理,不另设工作流清理截止。这意味着“跑太久”不该靠工作流层超时解决,而应由调用方的取消或外层预算控制。

fatal 纪律:拼错选项必须炸掉

fatal: true 的错误不允许被组合器吞成 null。(来源)

脚本内部的钩子误用都会抛出带 fatal: true 的 WorkflowError:错误参数、未知或延迟的 agent() 选项、超出结构化输出子集的 schema、超出上限、seam 启动失败、取消。

parallel() 与 pipeline() 组合器对 fatal 错误直接重新抛出,而不是把该项映射为 null。官方的理由很直白:一个拼写错误的选项必须明确报错并终止脚本,绝不能消融为看似普通子 agent 失败的结果。

逐项的 null 保留给两类:子运行失败(非 completed 的 stop reason)与阶段内的普通脚本错误。所以读结果时先分“这是 fatal 还是可降级”,再决定要不要继续。

事件只做观察,给的是快照

订阅者拿到的是 id + meta,拿不到活跃句柄。(来源)

workflow/* 事件(start、phase、log、agent-start、agent-end、end)是仅供观察的 emit,携带数据快照:每个 payload 以 WorkflowRunInfo(id + meta)开头,而不是活跃的 WorkflowRun,因此订阅者无法获得 cancel 或 dispose。

workflow/end 刻意省略 result value——观察结果的监听器不得收到调用方 result 的可变别名。这条设计防止观察者顺手改掉调用方要用的数据。

每次 emit 对每个监听器隔离:订阅者抛出的异常会被记录到日志中而不传播,也不会阻止后续注册的监听器收到事件;每个监听器收到自己的 payload 克隆。这套隔离与 subagent/start、subagent/end 一致。

配对关系也要记住:workflow/agent-end 与 workflow/agent-start 按 agent.seq 配对,每个已开始的调用在每条停止路径上都恰好出现一次;在引擎终止路径上,end 由引擎合成,outcome 为 'cancelled'。

持久 Chat 记录的四条协议

记录只投影展示事实,不改变执行所有权。(来源)

顶层 dsh-tool-workflow 消费方把展示事实投影到调用它的父 Session,同时不改变执行所有权。运行接受后写 tool-workflow/run-start,以 runId 加 seq 配对成员开始与结束,并且只在结果已取得且 dispose 完全停稳后写 tool-workflow/run-end。嵌套 transport 调用不写记录。

四条记录协议:每个运行只有一个 start;成员序号为正且唯一;成员 end 必须配对;仍有开放成员时不能结束运行,运行结束后不能继续更新。

第一次 append 失败会禁用本运行后续写入,因此日志保持为空或合法连续前缀,工具结果不变。日志尾部缺少成员 end 或 run end 是有效的中断证据,不是损坏——这条判定让“崩溃后看到半条记录”不必当成数据问题。

客户端侧,dsh-client-ui-workflow-run 通过 Conversation Node 引擎把四类事件折叠为一个 workflow-run Chat 节点,以 run-start 序号锚定在原工作流工具节点之后。阶段组只来自真正开始过的成员,并保留精确字符串,包括字段缺省与空串的区别;Location 关闭时,缺失终点会显示为已中断。

验证:可恢复失败与 fatal 失败

验证要区分“子运行失败可降级”和“fatal 必须终止”,两者表现完全不同。(来源) 六步:

  1. 提交一个 meta 缺 name 的请求,断言在任何工作开始前就被拒绝。
  2. 让一个 agent() 子运行失败,断言结果里有逐项 null,整条脚本仍可继续。
  3. 给 agent() 传一个拼错的选项,断言抛 fatal: true 且 parallel() 没有把它变成 null。
  4. 在脚本里 return { ok: true },断言 stopReason 是 completed 且 value 是宿主 JSON。
  5. 运行中调 cancel(),断言 result 以 cancelled 兑现而不是 reject,随后 dispose() 等到子 agent 清理完成。
  6. 检查事件监听器:一个监听器抛错,断言其他监听器仍收到各自克隆的 payload,且 workflow/end 不含 value。

如果第 3 步被降级成 null,说明组合器把 fatal 当成了普通子运行失败,那会让拼写错误在生产里静默。

工作流不触发的排查,可以对照工作流未触发;脚本导出与画布的衔接见工作流 YAML 导出。

一句话收束: meta 是数据不是代码、result 永不拒绝、fatal 必须炸、事件只给快照、记录只在结果与释放之后收尾。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的脚本能改 subagentProvider 吗?

不能,DSH plugin 把引擎级 subagentProvider 与 maxTotalAgents 留给消费方。DSH plugin 的脚本无法观察或替换这两项策略,只能使用调用方给的配置。

DSH plugin 的脚本异常会让 result 拒绝吗?

不会,DSH plugin 的 result 绝不拒绝。DSH plugin 把脚本失败兑现为 stopReason 为 error 的结果,取消兑现为 cancelled,消费方再自行映射成 isError 工具结果。

DSH plugin 的 parallel 会把 fatal 错误变成 null 吗?

不会,DSH plugin 对 fatal 错误直接重新抛出。DSH plugin 的逐项 null 只留给子运行失败与阶段内普通脚本错误,拼错的选项必须终止脚本。

DSH plugin 的工作流事件能拿到 cancel 吗?

不能,DSH plugin 的事件载荷以 WorkflowRunInfo 开头。DSH plugin 只给订阅者 id 与 meta 的快照,不给活跃运行句柄,因此拿不到 cancel 与 dispose。

相关术语

WorkflowStartRequest
WorkflowStartRequest 是启动一次工作流的请求,含脚本、meta、可选 args、父 agent 与取消信号。— packages/workflow/workflow/src/runtime-types.ts
WorkflowResult
WorkflowResult 是一次运行的终态结果,含 value、stopReason、可选 error 与 agentsStarted。— packages/workflow/workflow/src/runtime-types.ts
WorkflowRun
WorkflowRun 是持有者拥有的活跃运行,提供 id、meta、result、cancel 与幂等 dispose。— packages/workflow/workflow/src/runtime-types.ts
WorkflowError.fatal
WorkflowError 的 fatal 标记表示必须终止脚本的错误,例如钩子误用、选项拼错或超出上限。— DeepSeek Harness 官方参考 - 工作流

来源