# Claude Code Dynamic Workflows：把Agent编排从“黑箱”搬到“代码”里 本文先阐述几个核心判断。Claude Code 推出的 Dynamic Workflows，本质上只做了一件事：将多Agent的编排逻辑，从LLM的上下文窗口中解放出来，迁移到JavaScript脚本中。一次运行可调度数百个Subagent，支持暂停恢复、交叉验证、保存复用。它并非全新的Agent框架，而是一种让Agent系统真正实现规模化运营的工程思路。 直接讲一个真实的场景。前段时间在做代码库的全局安全审计，大约200多个API端点，每个都需要检查鉴权、参数校验、错误处理。一开始用了Subagent并行跑，结果很快就撞墙了——每个Subagent的结果都回传至主对话的上下文窗口，十几个之后上下文就几乎满了，后续Agent的结果开始被压缩丢失。 后来又尝试了Agent Teams，十几个人机协作，Lead Agent的上下文也撑不住了。 说实话，那会儿确实很沮丧。模型能力明明够用，Agent也能干活，但“协调”这件事本身变成了瓶颈。 直到Claude Code v2.1.154发布了Dynamic Workflows，才真正意识到问题出在哪：我们一直让LLM既干活又管协调，但协调这件事，本来就不应该住在上下文窗口里。 *Claude Code Dynamic Workflows 系统架构* ## 一. 先搞清楚：Workflow到底是什么 Dynamic Workflow说白了就是一段JavaScript脚本。你用自然语言描述任务，Claude帮你写脚本，然后在隔离环境里执行它。脚本本身不直接访问文件系统或Shell，它通过调度Subagent来干活，每个Subagent有自己的上下文窗口，结果回到脚本变量里，只有最终报告回到你的对话。 跟之前的方案比，本质区别在哪？看这张对比图： *Subagents、Skills、Workflows、Agent Teams 四种方案对比* 核心差异只有一个维度：谁持有编排计划，中间结果存在哪。 | | Subagents | Skills | Workflows | Agent Teams | |---|---|---|---|---| | 谁决定下一步 | Claude逐轮决策 | Claude按指令执行 | 脚本 | Lead Agent | | 中间结果存在哪 | 上下文窗口 | 上下文窗口 | 脚本变量 | 各Agent上下文 | | 规模 | 几个 | 几个 | 数十~数百 | 十几个 | | 可暂停恢复 | 否 | 否 | 是 | 否 | | 可复现 | 仅worker定义 | 仅指令 | 脚本即编排 | 否 | 一句话概括：Subagents是委派，Skills是模板，Agent Teams是协作，而Workflows是编排代码化。 当编排逻辑变成代码，就获得了一种之前没有的能力——可复现的质量模式。比如让两组独立的Agent互相审查对方的结论，或者从三个角度独立设计方案然后投票选优。这种“交叉验证”在上下文窗口里是做不了的，因为你没法让同一个Claude实例同时扮演审计者和被审计者。 ## 二. 什么时候该用Workflow 不是所有任务都需要Workflow。说实话，大部分日常编码任务，直接对话就够了。判断标准其实很简单： *多Agent方案选型决策树* 适合用Workflow的场景： 代码库全局审计——扫描所有路由的鉴权、所有API的错误处理、所有模块的安全漏洞。规模大、模式重复、需要交叉验证，这类任务天然适合。 大规模迁移——500个文件从CommonJS改ESM、全量API版本升级。模式固定，可以用脚本编码编排逻辑。 交叉验证研究——从多个独立角度调查问题，Agent之间互审结论。这是Workflow独有的优势，其他方案做不了。 多角度方案对比——从性能、安全、可维护性三个角度各自设计方案，然后投票选优。 不适合的场景： 简单的几步操作，直接对话或一两个Subagent就能搞定。不需要杀鸡用牛刀。 需要频繁人工介入的阶段间决策——Workflow运行中不支持用户输入，只能暂停。如果每步都得确认，不如拆成多个Workflow分段跑。 成本敏感的场景——16个并发Agent意味着16倍的Token消耗，后面会详细聊。 ## 三. 怎么用：三种触发方式 ### 最快上手：`/deep-research` 直接输入： `/deep-research Node.js v20 到 v22 的权限模型有什么变化？` 这是Claude Code内置的Workflow命令。工作流程很清晰： */deep-research 四阶段工作流* 1. 多角度搜索：从技术原理、社区讨论、官方文档、竞品对比、实际案例等角度并行搜索 2. 抓取与交叉验证：Agent们抓取来源，互相验证每个声明 3. 投票筛选：未通过交叉验证的声明被过滤掉 4. 报告生成：输出带引用的最终报告 运行期间你的对话保持可用，不受阻塞。可以继续做其他事。 ### 在prompt中触发 任意提示词里包含 `workflow` 关键字即可： `Run a workflow to audit every API endpoint under src/routes/ for missing auth checks` Claude会高亮 `workflow` 这个词，自动编写Workflow脚本。如果不小心触发了，按 `alt+w` 忽略。 ### 全自动模式：Ultracode `/effort ultracode` Ultracode等于 `xhigh` 推理强度加上自动Workflow编排。开启后，Claude会对每个实质性任务自动规划Workflow。一个请求可能触发多个Workflow串联：一个理解代码、一个做改动、一个做验证。 但说实话，不建议日常开着Ultracode。Token消耗非常猛，适合那种“这个任务我必须一次搞定”的场景。日常编码用 `/effort high` 就够了，遇到真正的大任务再手动触发Workflow。 注意，Ultracode是session级别的，退出或新开会话后重置。仅支持 `xhigh` effort的模型（目前是Opus 4.8和Opus 4.7）。 ## 四. 运行管理：审批、监控、暂停恢复 ### 审批机制 第一次运行时，CLI会展示计划的阶段列表，可以选择： - **Yes, run it** — 开始运行 - **Yes, and don't ask again** — 跳过该Workflow的后续审批 - **View raw script** — 先看脚本再决定 - **No** — 取消 强烈建议第一次运行时选View raw script。理解Claude编排了什么，比盲目信任重要得多。`Ctrl+G` 可以在编辑器中查看脚本，`Tab` 可以在运行前调整prompt。 不同权限模式下审批行为不一样： | 权限模式 | 是否弹出审批 | |---|---| | Default / Accept Edits | 每次都弹 | | Auto | 仅首次；Ultracode下跳过 | | Bypass / `-p` / Agent SDK | 从不弹出 | 还有一个细节值得注意：Workflow的Subagent固定运行在 `acceptEdits` 模式，继承你的tool allowlist，文件编辑自动批准。Shell命令、Web请求、不在allowlist里的MCP工具仍然会中途弹提示。长时间运行前，最好把这些命令提前加到allowlist里。 ### 监控运行 `/workflows` 进度视图展示每个阶段的Agent数量、Token消耗和耗时。操作键： | 键 | 功能 | |---|---| | `↑/↓` | 选择阶段或Agent | | `Enter/→` | 钻入详情 | | `p` | 暂停/恢复 | | `x` | 停止单个Agent或整个Workflow | | `r` | 重启选中的Agent | | `s` | 保存脚本为命令 | ### 暂停与恢复 这是Workflow相比其他方案的独特优势。停止后可以恢复——已完成的Agent返回缓存结果，剩余的继续运行。注意，这只在同一Claude Code会话内有效，退出后重开会从头跑。 这个设计很务实。想象一下，跑了一个200个Agent的审计任务，到第150个发现需要调整——如果是Subagent就得全部重来，Workflow只需要恢复然后从151继续。 ## 五. 保存与复用：从一次性到可重复 当一次Workflow运行产出了满意的结果，在 `/workflows` 里选中它按 `s` 即可保存。保存位置有两个： - **项目级** `.claude/workflows/` — 随仓库共享给团队 - **用户级** `~/.claude/workflows/` — 仅自己可见，所有项目可用 保存后，该Workflow变成 `/` 命令，出现在 `/` 自动补全中。同名时项目级优先。 这个功能特别适合这些场景： 每个分支都要跑的代码审查流程——保存成 `/security-audit`，以后一个命令搞定。 定期执行的迁移检查——保存成 `/migration-check`，不用每次重新描述任务。 团队共享的标准化流程——提交到 `.claude/workflows/`，clone仓库就能用。 ## 六. 运行时约束与设计哲学 Workflow运行时有几个硬约束，理解它们很重要： | 约束 | 原因 | |---|---| | 不允许运行中用户输入 | 只有权限提示可以暂停 | | 脚本无直接文件系统/Shell访问 | Agent负责读写，脚本只负责协调 | | 最多16个并发Agent | 限制本地资源 | | 单次运行最多1000个Agent | 防止失控循环 | 这些约束体现了一个设计哲学：**脚本是编排者，不是执行者。** 它只决定“谁做什么、谁先谁后、结果怎么交叉验证”，具体的读写和计算全部交给Agent。 不允许运行中用户输入这个约束，看起来是个限制，但其实是正确的工程取舍。如果需要阶段间审批，就把大任务拆成多个Workflow，每个阶段跑一个。这比让一个Workflow等待用户输入要清晰得多——每个Workflow的输入输出是确定的，更容易调试和复现。 ## 七. 成本：必须认真对待 Workflow会大量调度Agent，Token消耗远超逐步处理同一任务。 *不同方案的Token消耗对比* 举一个直观的例子：一个16并发的Workflow，每个Agent平均消耗50K Token，一轮就是800K Token。如果跑5轮，就是4M Token。这个消耗在Opus 4.8上相当可观。 成本控制策略： **模型分级**：对只读扫描类阶段用Haiku或Sonnet，只在需要深度推理的阶段用Opus。描述任务时可以指定，比如“对简单阶段用Haiku”。 **opusplan的妙用**：规划阶段用Opus深度推理，执行阶段自动切到Sonnet。这是性价比最高的模式。 **随时可停**：`/workflows` 中按 `x` 停止，已完成的工作不丢失。 **不要Ultracode日常用**：Ultracode对每个任务都自动规划Workflow，Token消耗会爆炸。只在“这个任务我必须一次搞定”的时候开。 **运行前检查 `/model`**：如果日常会用更便宜的模型，大运行前确认当前模型。 还有一个容易被忽略的点：所有Workflow Agent默认使用你的会话模型。如果当前是Opus 4.8，16个并发Agent都用Opus 4.8，成本会非常惊人。大任务前切到Sonnet，或者让Claude在脚本里对不需要深度推理的阶段指定更小的模型。 ## 八. 与竞品的本质差异 这不是Claude Code第一次做多Agent。Cursor有Agent模式，Codex CLI支持并行任务，Amp也在做类似的事。但Workflow的思路跟它们有一个根本区别。 Cursor和Codex的多Agent本质上都是“并行执行”——同时跑多个任务，各自独立完成。这解决的是速度问题。 Workflow解决的是另一个问题：**编排的可复现性和质量保证。** 当你把编排逻辑编码为脚本，获得的不只是“更快”，还有： **可审查**：脚本可以在运行前检查，看到每个阶段做什么、Agent之间怎么交互。 **可复现**：同样的脚本，同样的输入，产出同样的编排逻辑。不是每次都依赖LLM的“灵光一现”。 **可交叉验证**：让两组独立Agent互审结论，这种质量模式可以编码到脚本里，而不是靠提示词祈祷。 **可暂停恢复**：大任务跑到一半发现需要调整，不需要从头来过。 这些能力是“编排代码化”带来的，不是“多Agent并行”带来的。并行只是手段，代码化编排才是核心。 ## 九. 实战建议 如果准备开始用Workflow，建议是这样的： **先用 `/deep-research` 感受。** 最零成本的理解方式。问一个真正关心的问题，观察Agent怎么分阶段工作、怎么交叉验证。这个过程比看任何文档都直观。 **从具体任务入手。** 别上来就Ultracode。先用 `workflow` 关键字触发单次任务，比如“workflow audit all API endpoints for auth checks”。确认效果后再考虑保存复用。 **第一次运行时选View raw script。** 理解Claude编排了什么，这比盲目信任更安全。脚本就是普通JavaScript，完全可以看懂。 **保存有效的Workflow。** 一旦某次运行产出了满意的结果，立刻按 `s` 保存。下次不用重新描述任务，一个命令搞定。 **大任务前清理上下文。** `/clear` 开新会话再跑大Workflow，减少无关Token消耗。主对话的上下文窗口应该留给最终报告，不是留给之前的闲聊。 **合理选择模型。** 对只读扫描类阶段指定Haiku/Sonnet，只在需要深度推理的阶段用Opus。这是成本控制最直接的手段。 **注意权限配置。** 长时间运行的Workflow如果中途弹出Shell权限提示而人不在旁边，会卡住。提前把需要的命令加到allowlist里。 ## 十. 局限性与期待 坦率地说，Workflow目前还有几个明显的局限。 **Research Preview状态。** 行为可能变化，API不稳定，不建议在生产环境强依赖。 **同会话内才能恢复。** 暂停后可以恢复，但只限同一Claude Code会话。退出后重开会从头跑。如果能在跨会话间恢复，对长时间运行的任务会友好得多。 **不支持运行中交互。** 如果需要阶段间审批决策，只能拆成多个Workflow。这在某些场景下不够灵活。 **脚本对用户不可编辑（目前）。** Claude写完脚本就只能看，不能直接改。如果想调整编排逻辑，只能通过修改prompt重新生成。 **Token消耗不低。** 16并发Opus的成本不是开玩笑的。期待未来能支持在脚本层面更细粒度地控制每个阶段的模型选择。 但话说回来，这些局限都不影响Workflow的核心价值——把编排逻辑从LLM的上下文窗口搬到代码里。这个方向是正确的。 当系统复杂度上升，协调成本会指数级增长。这不是靠更强的模型能解决的，因为问题不在模型能力，而在架构。Workflow做的事，本质上就是把“谁来做什么、谁先谁后、结果怎么验证”这件事从LLM的黑箱推理变成可审查的代码逻辑。 这让人想起分布式系统里的一个经典教训：**协调逻辑应该是显式的，不是隐式的。** 你不会把服务编排逻辑藏在某个微服务的大脑里，你会用Kubernetes manifest或者DAG配置来声明。Workflow对Agent编排做的，是同样的事。 回到开头那个问题——为什么Agent总是协调不好？ 现在看来，问题不在Agent能力不够，而在一直让LLM同时干两件事：执行任务和协调任务。当任务规模超过一定阈值，这两件事就开始互相干扰。 Workflow的答案是：执行交给Agent，协调交给代码。 如果也在做多Agent系统，这个思路值得认真想想。至少对文章开头那个案例而言，200个API端点的安全审计，从“跑了十几个就上下文爆炸”变成了一次Workflow搞定，结果还比之前更可靠——因为两组Agent交叉验证了每个发现。 有时候解决复杂问题的方法不是更复杂的推理，而是更简单的架构。 ## 参考资料 - Claude Code 官方文档 - Dynamic Workflows - Claude Code 官方文档 - Run Agents in Parallel - Claude Code 官方文档 - Create Custom Subagents - Claude Code 官方文档 - Model Configuration - Claude Code 官方文档 - Manage Costs - Claude Code Changelog - v2.1.154 话题标签：#ClaudeCode #Agent #Workflow #AI工程 #多Agent编排