Dynamic Workflow 架构拆解
对 动态工作流 的机制深挖（2026-08-31 query 归档）：workflow 到底是什么、和 subagent 什么关系、runtime 住在哪、tool schema 长什么样。结论先行：Workflow 是一个 schema 平平、实现极重的 Claude Code 内建工具；模型吐 tool call，CLI 解析并执行工具代码，代码里再递归调模型。升级的不是 subagent 这个兵种，是指挥系统——编排从”主 agent 即兴逐轮委派”变成”一份确定性脚本”。
官方四件套对照：谁持有计划
| Subagents | Skills | Agent teams | Workflows | |
|---|---|---|---|---|
| 是什么 | Claude 起的 worker | Claude 遵循的指令 | lead agent 监督 peer 会话 | runtime 执行的脚本 |
| 谁定下一步 | Claude，逐轮 | Claude，按 prompt | lead agent，逐轮 | 脚本 |
| 中间结果在哪 | Claude 的 context | Claude 的 context | 共享任务列表 | 脚本变量 |
| 可复用的是什么 | worker 定义 | 指令 | 团队定义 | 编排本身 |
| 规模 | 每轮几次委派 | 同 subagent | 少数长时 peer | 每 run 数十~数百 agent |
| 中断 | 重来该轮 | 重来该轮 | 队友继续跑 | 同 session 可恢复 |
原文：“A workflow script holds the loop, the branching, and the intermediate results itself, so Claude’s context holds only the final answer.”——计划进了代码，主上下文只装最终答案。
分层：一次 workflow 调用的完整链路
① CLI 组请求（tools 清单含 Workflow + schema）→ ② 模型吐 tool_use {name:"Workflow", input:{script}} → ③ CLI 解析 tool call：权限评估 → 语法预检 → workflow runtime 沙箱执行 JS（注入 agent/parallel/pipeline/phase/log/args）→ 每个 agent() = CLI 再起一轮完整子 agent 会话（递归①②③）→ ④ 异步返回 async_launched + taskId，终值晚点作为任务完成事件送达。
要点：对模型来说 Workflow 毫不特殊（tools 清单里一条 名字+schema，与 Bash/Read 平级），所有魔法在 CLI 侧的工具实现；agent() 无神秘机制，就是同一台 CLI 递归跑子会话——CLI 身兼对话宿主与每个 subagent 的宿主，执行的是一棵 agent 会话树。
依赖方向：CLI 是原生宿主，SDK 是壳
Agent SDK 打包并 spawn Claude Code 二进制当引擎（“The SDK bundles a native Claude Code binary… SDK v0.3.191 bundles Claude Code v2.1.191”，版本同步）。所以”SDK 的 Workflow 工具”与”CLI 里的 dynamic workflow”是同一份实现、同一个 runtime；在 CLI 里用时根本不经过 SDK 层。一句话：不是 CLI 背后调 SDK，而是 SDK 背后调 CLI。
Workflow tool schema（Agent SDK ≥v0.3.149）
Input（script / name / scriptPath 至少给一个）：script（内联，必须以字面量 meta 块开头）· name（内建或已保存 workflow）· scriptPath（磁盘路径，优先级最高）· args（任意 JSON → 脚本全局 args）· resumeFromRunId（续跑：输入未变的 agent() 吃缓存，限同 session）· title/description（忽略，meta 块说了算）。
Output：status（async_launched 进程内 / remote_launched 派发远端 session）· taskId · runId（续跑句柄；remote run 改用 sessionUrl）· transcriptDir · scriptPath（本次脚本落盘路径）· warning / error（语法失败时 status 仍是 launched 但 error 非空——先查 error 再当已启动）。
两个闭环：脚本资产化（跑一次 → 拿 scriptPath → 手改 → 重调，不必重发脚本）与远端模式（remote_launched：协调态与执行面都可不在本机，呼应 Agent 状态分层）。
收敛判定：没有统一谓词
官方文档未定义 answers_converge 的通用判定；停止条件写在每次生成的脚本里，按任务从四种模式选：checker 转绿或停止进展 / 发现枯竭（新轮无新发现）/ 投票 + 交叉核查（deep-research 型）/ 对抗幸存（无人能推翻）。兜底：1000 agents/run 硬上限 + Large workflow 警告（>25 agents 或预计 >1.5M tokens，仅提示不拦截）。
与普通 subagent 委派的本质差
之前 = REPL 里手敲函数调用：每轮往返烧主上下文，任务大了会漂；现在 = 写个程序再运行：循环/分支/中间结果在脚本变量不进主上下文、确定性执行（runtime 禁 Date.now/Math.random 保证重放）、断点可续。质量模式（独立验证 / 对抗 / 收敛）是脚本让它们变便宜（parallel() + filter 几行即可），非 runtime 强制。边界：每个 agent 都是一次完整模型调用，是重武器——官方建议 scoped task 试水，size guideline 默认 medium（<15 agents）。
来源与相关页面
- raw/2026-08-31-claude-code-workflows-doc.md（官方 workflows 文档快照）· raw/2026-08-31-claude-agent-sdk-workflow-tool.md（TS SDK 参考 Workflow 章节节选）
- 动态工作流 · Claude Code · Claude Code - Dynamic Workflows · Agent 状态分层 · Agent Fleet 管理 · AI