Lesson 4 / 6

Workflow 编排

多 Agent 协奏曲

Mission 关联：前三课你学会了自动化（hooks）、复用（skills）、分工（subagents）。 这一课将教你指挥——用 JavaScript 脚本编排多个 subagent 协同工作，像指挥家一样调配合唱团。

什么是 Workflow？

Workflow 是 Claude Code 的多 agent 编排脚本。它是一个 JavaScript 文件，通过 agent()、parallel()、pipeline() 等 API 来控制和协调多个 subagent 的执行顺序和协作方式。

💡 类比一下

Workflow 的完整生命周期

  1. 构思——在 Claude Code 会话中用自然语言描述你想要什么
  2. 生成——Claude 根据你的描述生成 workflow 脚本
  3. 运行——通过 /workflows 运行，观察进度
  4. 保存——运行成功后，保存到 .claude/workflows/<name>.js
  5. 复用——以后直接 /workflow-name 调用

核心 API

Workflow 脚本中用到的 API：

函数 用途 类比
agent(prompt, opts?) 启动一个 subagent 执行任务 派一个员工干活
parallel(thunks) 并行启动多个任务，等全部完成 多个员工同时干
pipeline(items, stage1, stage2, ...) 流水线：每个 item 依次经过多个阶段 流水线作业
phase(title) 标记当前阶段（显示在进度树中） 贴进度标签
log(message) 输出进度消息 汇报进展

agent() 详解

// 基本用法 —— 返回文本
const result = await agent("Find all TODO comments in the codebase")

// 带选项 —— 结构化输出
const result = await agent("Find bugs", {
  label: "bug-finder",        // 在进度树中显示的标签
  phase: "Find",              // 归属阶段
  schema: {                   // JSON Schema 约束输出结构
    type: "object",
    properties: {
      bugs: { type: "array" }
    }
  },
  model: "sonnet",            // 模型覆盖
  effort: "high",             // 推理努力程度
  isolation: "worktree",      // 工作树隔离
  agentType: "code-reviewer"  // 使用特定 agent 类型
})

pipeline() 详解

流水线模式：多个 item 各自独立经过所有阶段。没有全局屏障——item A 可能已经到了 stage 3，而 item B 还在 stage 1。

const results = await pipeline(
  items,                                       // 要处理的数组
  item => stage1(item),                        // 第一阶段
  prevResult => stage2(prevResult),            // 第二阶段（接收上一阶段的输出）
  (prevResult, originalItem, index) => {       // 第三阶段和原始数据
    return stage3(prevResult, originalItem)
  }
)

parallel() 详解

并行模式：有全局屏障——所有任务启动，等全部完成后才继续。

const [result1, result2, result3] = await parallel([
  () => agent("Task 1"),
  () => agent("Task 2"),
  () => agent("Task 3"),
])

// 失败的 agent 返回 null，不会让 parallel 崩溃
// 所以用 .filter(Boolean) 过滤
const valid = results.filter(Boolean)
💡 何时用 barrier？
pipeline 是默认选择。barrier (parallel) 只在真正需要"等所有结果到齐"时才用：
—— 去重/合并需要全集
—— 提前退出（"0 个 bug 找到 → 跳过验证阶段"）
—— 比较/排序需要完整列表

脚本结构

每个 workflow 必须以 meta 开头，然后才是脚本体：

export const meta = {
  name: "audit-codebase",
  description: "Audit the codebase for bugs, security issues, and style problems",
  phases: [
    { title: "Find", detail: "Search for issues across dimensions" },
    { title: "Verify", detail: "Adversarially verify each finding" },
    { title: "Report", detail: "Generate final report" },
  ],
}

phase("Find")
const findings = await parallel([
  () => agent("Find bugs", {phase: "Find", schema: BUGS_SCHEMA}),
  () => agent("Find security issues", {phase: "Find", schema: SEC_SCHEMA}),
  () => agent("Find style problems", {phase: "Find", schema: STYLE_SCHEMA}),
])

phase("Verify")
const verified = await pipeline(
  findings.flat().filter(Boolean),
  finding => agent(`Verify: ${finding.title}`, {phase: "Verify", schema: VERDICT_SCHEMA}),
)

phase("Report")
const report = await agent("Write report", {phase: "Report"})

return { confirmed: verified.filter(Boolean).filter(v => v.isReal) }

常见编排模式

模式一：并行发掘（多维度扫描）

const results = await parallel(DIMENSIONS.map(d => () =>
  agent(d.prompt, {schema: FINDINGS_SCHEMA})
))
const deduped = dedupe(results.flat().filter(Boolean))

模式二：流水线验证（边查边验）

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, {phase: "Review", schema: FINDINGS_SCHEMA}),
  review => parallel(review.findings.map(f => () =>
    agent(`Verify: ${f.title}`, {phase: "Verify", schema: VERDICT_SCHEMA})
  ))
)

模式三：循环直到枯竭（Loop-until-dry）

const seen = new Set()
let dry = 0
while (dry < 2) {
  const found = await agent("Find more bugs", {schema: BUGS_SCHEMA})
  const fresh = found.bugs.filter(b => !seen.has(key(b)))
  if (!fresh.length) { dry++; continue }
  dry = 0
  fresh.forEach(b => seen.add(key(b)))
  log(`Found ${fresh.length} new bugs (total: ${seen.size})`)
}

模式四：裁判评审（Judge Panel）

const attempts = await parallel([
  () => agent("Solve it with MVP-first approach"),
  () => agent("Solve it with security-first approach"),
  () => agent("Solve it with performance-first approach"),
])
const best = await agent(`Synthesize: pick best from: ${attempts.filter(Boolean).join("\n---\n")}`)

Token 预算管理

Workflow 支持 token 预算控制。当用户指定了预算（如 "+500k"），workflow 可以根据预算动态调整规模：

// budget.total = 用户指定的预算（null 表示无限制）
// budget.spent() = 已消耗的 token
// budget.remaining() = 剩余预算

while (budget.total && budget.remaining() > 50_000) {
  const result = await agent("Find bugs", {schema: BUGS_SCHEMA})
  bugs.push(...result.bugs)
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}

动手练习：创建你的第一个 Workflow

🎯 练习：创建代码审查 Workflow

场景：你希望有一个"一键审查"流程——对当前代码变更做安全性、性能、代码质量三个维度的审查。

步骤：

  1. 在 Claude Code 中描述你的需求

    在 Claude Code 会话中输入：

    帮我创建一个 workflow，对当前代码库做三方面审查：
1. 安全性检查
2. 性能检查
3. 代码质量检查
三个审查并行进行，结果汇总成一份报告
  2. 运行并调整

    Claude 会生成脚本并用 /workflows 运行。观察进度树，看三个 agent 是否并行执行。

  3. 保存为可复用命令

    运行成功后，保存到 .claude/workflows/audit.js。
    以后在任何项目中，输入 /audit 就能一键审查。

  4. 进阶改进

    加上 phase() 分阶段标记，再加一个"验证"阶段：

    phase("Review")
// 并行审查...
phase("Verify")
// 验证关键发现...
phase("Report")
// 生成报告...

meta 字段详解

字段 必填 说明 示例
name ✅ Workflow 名称，显示在进度树中 audit-codebase
description ✅ 一句话描述，出现在权限提示中 Audit the codebase
phases ❌ 阶段列表，每个有 title 和 detail [{title: "Find", detail: "..."}]
whenToUse ❌ 在 workflow 列表中显示的用途说明 When you need ...

重要注意事项

pipeline vs parallel 选择指南

场景 推荐 原因
多个独立任务，结果不互相依赖 parallel 同时跑，等全部完成
每个任务分多阶段，阶段间无依赖 pipeline 边查边验，不浪费等待时间
需要"全部到齐才能做下一步" parallel + 后续处理 全局 barrier，等全集
需要去重/排序/比较 parallel + barrier 必须全集到齐才能操作
先找 bug，找到后立即验证 pipeline 每个 bug 找到就验，不用等所有找完

先决条件

要运行 workflow，确保你的 Claude Code 版本支持（v2.1.154+）：

课后推荐阅读

📌 别忘了

Workflow 是 Claude Code 进阶的终极武器。学完这课后，你就能用脚本指挥多个 AI 员工协同工作了。

有任何问题随时问！特别是 pipeline 和 parallel 的选择逻辑——这是最容易搞混的地方。