Workflow 默认应释放父 turn：与 Subagent 的后台生命周期合同对齐

[tt-a1i]

结论

当前 Workflow 的确会在默认调用中阻塞主会话当前 turn，直到整个 Workflow 完成。

这不是偶发 bug，而是现在明确设计的默认值；但它与 OpenPI 已经确立的 Subagent 后台生命周期合同不一致，也削弱了交互会话中“后台工作不占住用户”的体验。

当前行为

基于当前 main@22e77d6：

• extensions/workflows/prompt.ts:15-16 明确写明 background 默认 false，即 blocking with live progress；
• extensions/workflows/index.ts:745 使用 (params.background ?? false) && ctx.hasUI；
• extensions/workflows/index.ts:1693-1699 默认路径会 await completion，父工具调用直到 Workflow 完成才返回；
• 只有模型显式传 background: true 且 ctx.hasUI 时，才立即返回 run id，并在完成后回传消息；
• 非交互模式即使传 background: true 也会退回阻塞执行。

Subagent 的合同相反：

• subagent_spawn 始终 fire-and-forget；
• spawn 立即返回 id；
• 结果完成后自动送回并在需要时重新唤醒父 Agent；
• 只有用户明确要求当前回复等完，或非交互自动化必须在同一次调用返回结果时，才使用 subagent_wait。

为什么值得改

Workflow 通常比单个 Subagent 更长、更容易包含 fan-out、pipeline、barrier 和多阶段验证。越长的任务越不应该默认占住交互父 turn。

当前默认值会产生几个实际问题：

1. 用户在 Workflow 运行期间不能自然继续与主会话交互；
2. 模型必须记得主动设置 background: true，否则一个小的参数遗漏就把长任务变成前台等待；
3. Background Terminal、Subagent、Workflow 三类异步能力的默认心智模型不一致；
4. 已有 workflow_status、workflow_stop、完成 follow-up、dashboard indicator 等完整后台生命周期，却没有成为交互模式的默认路径；
5. “需要结果才能继续”会诱导模型保持当前 turn，而 Subagent 侧已经明确证明：依赖结果本身不是阻塞用户的理由，结果到达后重新唤醒即可。

建议合同

交互 Session

workflow(...)
→ 默认立即返回 run id
→ Workflow 后台运行
→ 父 Agent 可继续独立工作，或结束当前 turn
→ 完成后结果自动进入 Session，并按 idle/busy 规则重新唤醒

需要当前响应同步拿到结果时，应显式表达，例如：

• 保留兼容参数 background: false；或
• 将正向语义改成更清楚的 wait: true / mode: "blocking"。

不要因为父 Agent 的下一步依赖结果，就自动阻塞交互 turn。

非交互 / 自动化

非交互调用没有可靠的后续用户 turn，默认同步可能仍然合理。应单独定义，而不是机械地让所有环境都后台化：

interactive UI → 默认后台
print/RPC/automation → 默认阻塞，除非调用方明确具有结果接收合同

与 Subagent 保持一致，但不照搬实现

两者应共享以下原则：

• 默认不让长期子执行占住交互父 turn；
• 立即返回稳定 id；
• 状态可检查、可取消；
• 完成结果自动投递；
• 显式同步只用于用户要求或非交互同调用结果合同。

Workflow 仍保留自己的 artifact、replay、graph、acceptance 与多 Agent 生命周期，不需要改造成 Subagent。

与 #71 的关系

• 本 Issue 讨论默认前台/后台语义；
• Workflow：终态持久化失败与完成通知失败会留下不可恢复的不一致 #71 讨论后台结果与终态落盘的可靠性。

调整默认值前，应确保 #71 的投递恢复机制足够可靠；否则扩大后台使用会放大一次性 sendMessage 失败的影响。两项可以分阶段实施，但验收应联动。

验收标准

• 交互 Session 中省略参数的 Workflow 会立即返回，不再 await 全部执行；
• 完成后结果自动投递，并遵循 idle 时唤醒、busy 时 nextTurn 的现有规则；
• 用户可通过 workflow_status 查看、通过 workflow_stop 取消；
• 有显式 blocking/wait 入口，供用户明确要求当前回复等待；
• print/RPC/自动化模式的默认合同有明确测试和文档；
• Esc、session shutdown、reload 的行为分别有回归测试；
• README、Workflow Skill、工具 Schema 对默认行为的表述一致；
• 与 Workflow：终态持久化失败与完成通知失败会留下不可恢复的不一致 #71 联合测试一次投递失败后的恢复，避免“默认后台”扩大结果丢失风险。

非目标

• 不让父模型轮询 workflow_status；
• 不移除阻塞执行能力；
• 不把 Workflow 降级成单个 Subagent；
• 不依赖 Prompt 提醒模型每次手动写 background: true 来维持正确默认体验。

[tt-a1i]

Claude Code 专项调研后的设计收敛（2026-08-23）

本轮以 Claude Code / Claude Agent SDK 官方合同为主，并用当前 OpenPI、Pi RPC 合同和三套备选设计交叉验证。结论支持本 Issue 的方向，但需要补充两处关键修正。

1. Claude Code 真正值得学习的合同

Claude Dynamic Workflow 的核心不是更多 DSL，而是三个生命周期彼此分离：

启动：Workflow 工具接受脚本，立即返回 taskId/runId，父 Agent launch turn 释放
执行：Runtime 在后台运行；进度进入独立 task event stream / UI
完成：task notification 形成新的 completion turn，只把最终聚合结果交回父 Agent

Agent SDK 中 query() stream 持续在线，是消费端订阅进度和完成事件，不代表 Workflow 工具调用或父 Agent turn 一直阻塞。

官方资料：

• Claude Code Dynamic Workflows
• Claude Agent SDK Dynamic Workflows Cookbook

2. 对本 Issue 的模式修正：RPC 也应默认后台

Issue 原文把 RPC 与 print/automation 一起归入默认阻塞，这不准确。Pi RPC 是长连接，ctx.mode === "rpc" 且 ctx.hasUI === true，通知和扩展 UI 可以通过 JSON 子协议交付。

推荐策略：

调用面	省略 background	显式 true	显式 false
TUI	后台	后台	同步 barrier
RPC	后台	后台	同步 barrier
print/json	同步	明确报错当前 adapter 不支持延迟投递	同步

显式请求后台但宿主没有 completion sink 时，不应静默改成同步。

3. 默认翻转之前必须完成的正确性工作

可靠完成投递（#71）

当前 pi.sendMessage() 只尝试一次，异常被吞。建议使用 run-local outbox：

terminal artifacts 落盘
-> delivery=pending
-> 尝试投递
-> 成功后 delivery=delivered
-> 失败恢复 pending，之后按 runId 幂等重试

闭合 busy / 快速完成竞态

Workflow 如果在 launch turn settle 前快速完成，当前直接 nextTurn 可能不会自动唤醒。应复用 Subagent delivery coordinator 的语义：busy 时先 pending，父 turn agent_settled 后批量 drain，并恰好触发一次 follow-up。

Workflow 能力组保持 Schema 稳定

加载 workflow capability 后，应一次性开放：

workflow
workflow_status
workflow_stop

run 的启动、完成、停止只改变运行状态，不再改变模型工具集合。实例状态不是权限边界。

4. 最终推荐：最小 Pi-native 方案

explicit/adaptive 决定是否披露 Workflow capability
模型决定脚本拓扑、规模和综合策略
Runtime 强制权限、并发、取消、落盘和可靠投递
TUI/RPC 默认后台，print/json 默认同步
background:false 保留为显式 barrier

内部可把散落的 start/observe/stop、terminal persistence、delivery、busy/idle 竞态收进一个 WorkflowRunCoordinator 深模块，但不新增模型工具，也不建立第二套 Session/provider/runtime。

5. 本轮明确不做

• 不新增 workflow_wait；现有 background:false 足以表达显式同步。
• 暂不增加同义的 wait 参数，避免扩大 Schema 和兼容矩阵。
• 不建设通用 Execution handle、cursor、ack、quorum barrier 或跨进程 scheduler。
• 不复制 Ultracode、固定规模档、固定 Report Agent 或 Claude 专属 provider stack。
• 不承诺跨 Session durable execution；Claude Code 当前也只是 same-session resume。

如果后续真实使用或 benchmark 证明经常需要跨 Workflow/Subagent/后台进程同步，再单独评估最小的 await_events(all|any + timeout)；当前问题不需要它。

6. 建议拆分

1. PR A：Workflow：终态持久化失败与完成通知失败会留下不可恢复的不一致 #71 可靠 terminal + completion outbox；
2. PR B：Workflow capability 加载后工具组稳定；
3. PR C：TUI/RPC 默认后台，print/json 默认同步，并修复 busy completion race；
4. PR D：真实 Pi smoke + 固定模型 A/B，测 launch-to-idle、完成投递、父会话 turns/tokens、漏投/重复投递和大 fan-out 最终报告。

核心判断：

Workflow 内部可以有 barrier，但父 Agent 的启动 turn 不需要成为 barrier。OpenPI 不缺另一个 Workflow 框架，缺的是正确的默认 interface 和可靠的 completion seam。

[tt-a1i]

Workflow V2 最终方案与实施结果

实现 PR：PR #92

关联问题：可靠投递 #71、父 turn 释放 #74、动态 fan-out #75、大规模结果汇聚 #90。

一、问题到底在哪里

旧版 Workflow 的主要问题不是“agent 数量只有 3 个”，而是职责边界混在了一起：

1. 启动 workflow 的工具调用同时拥有底层 run，父 turn 会等完整 Workflow 结束；
2. 首个 run 创建后再显示管理工具，运行实例状态会改变模型看到的工具 Schema；
3. 结果投递只有一次机会，发送失败或进程恢复后缺少稳定身份与重试状态；
4. 大量子结果按输入顺序截断，前面的结果可能吃完预算，后面的结果完全消失；
5. 进程丢失后被误归类为 failed/aborted，Runtime 实际并不知道任务是否完成；
6. 示例容易把并发上限写成建议数量，模型倾向固定启动少量 agent，而不是根据任务结构动态拆解。

所以目标不是照搬 Claude Code 的 UI 或固定“几十个 agent”，而是让更强的模型可以安全地自由拆解：模型决定策略、数量、层级和综合方式；Runtime 只落实容量、生命周期、持久化、取消、恢复和有界上下文。

二、调研后采用的原则

Claude Code / Agent Teams

公开资料和本地真实 CLI 探索都没有发现一个“Workflow 固定启动 N 个 agent”的常量。更接近事实的机制是：模型根据独立工作面、依赖关系、任务难度和可并行性决定 fan-out；最终由 leader 或报告阶段综合。大规模任务适合分层汇聚，而不是把几十份原始长报告一次塞给父模型。

可借鉴之处：

• decomposition 是模型判断，不应被 Runtime 写死；
• 并发与调用次数是 ceiling，不是 target；
• 多阶段任务需要明确的 Report/aggregation 阶段；
• 各 agent 的完整结果应保留为资产，父上下文只接收有界投影。

详细记录：

• Claude Code Workflow runtime contract
• Claude Code Workflow fan-out policy

Cloudflare Workflows

Cloudflare 的关键启发不是前端形式，而是运行生命周期：长任务是独立、可恢复的执行，启动方不必一直占据交互调用；状态、事件和最终结果是不同投影。OpenPI 不需要引入它的外部调度器，但应该学习“run 独立于 waiter”的边界。

Maka

Maka 的能力组披露说明了另一个重要原则：工具集合跟能力边界变化，不跟资源实例状态变化。加载 Workflow 能力后，管理工具应该一次性稳定；创建第一个 run 不应该再次改变 Schema。

三、最终设计

1. 父 turn 默认释放，run 独立存活

交互式 TUI
  workflow() -> 立即返回 run id -> 父 turn 释放
  run 后台继续 -> 完成后可靠投递一条结果

print / 无后续投递宿主
  workflow() -> 默认等待并内联返回

显式 wait: true
  只用于真正需要同步结果的边界

父工具调用被中断时，只释放当前 waiter，不再取消底层 run。真正拥有取消权的是 workflow_stop 和 session shutdown。

2. 执行状态与投递状态分离

运行状态表达任务事实：running / done / failed / cancelled / uncertain。

投递状态单独表达结果有没有到达父会话：held-for-inline / pending / delivered / consumed-inline。

每个 run 有稳定 delivery id。发送失败会保留在 outbox，空闲时重试，恢复时继续；批量投递支持部分回执，只重试未确认项。

这里明确采用 at-least-once，不虚构 exactly-once：如果消息已经发出、但 receipt 持久化失败，恢复后可能用同一个 delivery id 重放。稳定 id 让 UI 或未来消费者可以去重。

3. 不知道就是 uncertain

恢复时发现旧进程的 owner 已不存在，只能证明“当前 Runtime 不再掌握它”，不能证明它失败或被取消。因此 V2 把 run 和仍在执行的 child 归为 uncertain，并在统计、UI、模型投影中单独显示。

这是执行证据的底线：不要用方便的状态名掩盖事实不完整。

4. 能力组一次稳定加载

未加载 workflow
  看不到 Workflow 工具

加载 workflow
  一次出现 workflow / workflow_status / workflow_stop

run 创建、结束、取消
  工具 Schema 不再变化

权限边界仍然是能力组；运行实例是否存在只影响工具执行结果。

5. 动态 fan-out，不规定 agent 数量

usage().limits 现在向脚本暴露已解析的并发和剩余调用容量。Skill 示例先发现独立工作面，再根据容量留出报告调用，选择本轮 fan-out：

selected + deferred = planned
covered + failed = selected

最终 Report 会显式收到失败项和延期项的名称以及全部计数，并被要求不得推断不存在的覆盖。

当剩余调用只有 1 次时，示例会 fail-closed：不启动无法收尾的 review fan-out，而是把发现项全部记为 deferred。

配置的并发/调用限制只定义安全上限。模型可以按任务启动 3 个、10 个或更多 agent；OpenPI 不人为增加成本限制，也不把上限变成目标。

6. 大规模结果公平汇聚

单次 handoff 共享 48 KiB 预算，最多公平投影 64 个结果：

• 使用 water-fill 分配，而不是前序优先；
• 每个被截断结果都保留 head + tail；
• 每个 child 的完整精确输出先写入 run 的 agent-results/agent-N.json；
• 父模型得到的是有界投影和恢复路径，不会把完整资产丢掉。

多个 Workflow 同时完成时，同一 completion batch 也共享一个 48 KiB 预算，避免每个 run 都向父上下文灌入 48 KiB。

公平出现不等于证据完整覆盖。几十个 agent 的 Workflow 应使用局部 Report -> 全局 Report 的分层汇聚，并在每层保留 planned/selected/covered/failed/deferred。当前 Runtime 没有机器可读 coverage manifest，因此文档没有夸大这项能力。

7. 最终结果按父上下文动态投影

Workflow 完整结果继续作为精确 artifact 保存；进入模型上下文的部分按父会话剩余空间动态调整，并使用 75% head + 25% tail 的 UTF-8 安全投影。这样既保留开头合同，也保留尾部结论和错误，同时避免长单行输出导致 head 丢失。

四、验证结果

确定性验证全部通过：

• format 通过；
• lint 通过；
• typecheck 通过（只保留仓库既有 Effect diagnostic）；
• Node 测试 859/859；
• Vitest 30/30；
• git diff --check 通过；
• 生命周期、架构、fan-out 三条独立评审均无 P0/P1 blocker。

真实模型 smoke 使用 seal/deepseek-v4-flash-0731-baidu 驱动 Workflow，子 agent 使用 gpt-5.6-luna：

• run wf_6664b8e3427d；
• 3/3 child 完成；
• 第一轮报告 2/3 PASS，并准确发现 stale recovery 没有持久化；
• 随后完成确定性修复和回归测试；修复后没有再次进行付费模型 smoke；
• provider 的 billing input/output/cache 字段返回 0，因此不编造 Token 总量或成本结论。

五、明确不做什么

• 不设置“默认 3 个”或“默认几十个”agent；
• 不引入固定 orchestration 状态机替代模型判断；
• 不增加第二套 provider/session/runtime；
• 不让普通状态变化反复修改工具 Schema；
• 不把 bounded projection 当作完整原始结果；
• 不承诺无法证明的 exactly-once；
• 不因为 benchmark 偏好冻结真实产品的动态能力。

完整设计：OpenPI Workflow V2 Design

这套设计的核心可以概括成一句话：

让模型自由决定如何组织工作，让 Runtime 对每个执行事实负责。