Claude Code Workflow Research

Claude Code Workflow 实现原理：从抓包看动态多代理编排

本文基于一次 Claude Code workflow 的 Reqable 抓包和本地运行产物，拆解 Claude Code dynamic workflow 的实现原理、工作机制和 agent 交接方式。

一句话概括：Claude Code workflow 的本质不是“模型在一次请求里并发思考”，而是“主模型生成一段 JavaScript 编排脚本，Claude Code 本地 runtime 执行脚本并启动多个普通子代理会话”。子代理通过 StructuredOutput 返回结构化 JSON，本地 runtime 再把这些 JSON 作为普通 JavaScript 值传给后续阶段，最终把脚本的 return 值通过  回灌主会话。

证据范围

本仓库保留了同一次 workflow 运行的两类材料：

- 原始抓包: reqable/
- 整理后的证据: workflow-artifacts/

本次运行的关键 ID：

关键证据文件：

除非特别说明，下面的结论都来自这些抓包、提示词、JS 脚本和本地运行文件。无法从材料直接证明的内部实现细节，会明确标注为推断。

总体架构

Claude Code workflow 可以分成四层：

1. 主会话层：主模型看到一个名为 Workflow 的本地工具。
2. 编排脚本层：主模型生成一段 JavaScript DSL，描述 fan-out、pipeline、评审、聚合和最终返回。
3. 本地 runtime 层：Claude Code 持久化并执行这段 JS，负责并发、缓存、日志、schema 校验和恢复。
4. 子代理层：每个 agent() 变成一个普通 Messages API 子会话，子代理通过 StructuredOutput 工具返回结构化结果。

流程可以画成这样：

这个结构里，模型真正“设计”的是 workflow 脚本；并发执行、进度显示、子代理启动、结构化返回和最终通知，都是 Claude Code 本地 runtime 的职责。

Workflow 工具如何暴露给主模型

在主会话请求里，Claude Code 把 Workflow 当作一个普通工具交给主模型。它的 schema 见 workflow-tool-schema.json，核心输入字段包括：

提示词明确要求：首次调用通常通过 script 传入内联 JS，不要先写文件。Claude Code 会自动把脚本持久化到 session 目录，并在工具返回中给出路径。后续迭代可以编辑这个文件，再通过 scriptPath 运行。

本次主模型实际调用保存在 main-workflow-tool-use.json。调用后，工具没有同步返回最终设计稿，而是先返回后台任务信息，见 workflow-launch-tool-result.md：

这证明 Workflow 是后台任务模型：第一次工具结果只是“任务已启动”和“如何恢复”，最终业务结果会在完成后另行通知。

触发规则：为什么不是随便就能用 Workflow

Workflow 工具提示词对触发条件非常严格。主模型只能在用户明确 opt-in 时调用 workflow。有效 opt-in 包括：

- 用户消息包含 workflow 或 workflows，并且系统提醒确认。
- Ultracode 开启，并且系统提醒确认。
- 用户明确说要运行 workflow、多代理编排、fan out agents。
- 某个 skill 或 slash command 指示调用 Workflow。
- 用户要求运行特定命名 workflow。

提示词还强调：即使任务明显受益于并行，只要用户没有 opt-in，也不能擅自调用 Workflow。模型应该使用单个 Agent 工具，或者先解释 workflow 能做什么、预计成本，再询问用户是否运行。

这个设计说明 Claude Code 把 workflow 视为高成本、多代理的显式能力，而不是普通默认行为。

Workflow JS DSL：模型写出的不是 TypeScript，也不是 Node 程序

本次生成的…