起底 Claude Code Dynamic workflow工作流的上下文管理艺术

┌─────────────────────────────────────────────────┐
│              主会话上下文（越来越臃肿）              │
│                                                 │
│  用户提问                                        │
│  ├─ 主 Agent 派生指令 → 子 Agent                  │
│  │   ├─ 子 Agent 翻了 10 个文件                   │
│  │   ├─ 编译报错 5 次 × 每次日志 60 行             │
│  │   ├─ 跑测试 3 次 × 每次输出 40 行              │
│  │   └─ 终于修好了！                              │
│  │                                               │
│  ◄── 💥 子 Agent 结束，180+ 行垃圾全部塞回 ────── │
│  │                                               │
│  ├─ 主 Agent 又派生另一个子 Agent                  │
│  │   ├─ 又是 100+ 行日志...                       │
│  │   └─ 又全部塞回来...                           │
│  │                                               │
│  ⚠️ 上下文像滚雪球，越来越大，主模型智商直线下降    │
└─────────────────────────────────────────────────┘

                    ┌──────────────────┐
                    │   100% 干净的     │
                    │   主会话 Session   │
                    │                  │
                    │   只有：          │
                    │   · 用户需求      │
                    │   · 最终结果      │
                    └────────┬─────────┘
                             │
                    ① 动态生成控制流
                             │
                    ┌────────▼─────────┐
                    │                  │
                    │   Harness        │
                    │   (运行时控制)    │
                    │                  │
                    └───┬──────────┬───┘
                        │          │
              ② Fork    │          │  ② Fork
              (干净分身) │          │  (干净分身)
                   ┌────▼───┐  ┌───▼────┐
                   │ 子Agent │  │ 子Agent │
                   │   A     │  │   B     │
                   │         │  │         │
                   │ 翻文件  │  │ 翻文件  │
                   │ 报错!   │  │ 报错!   │
                   │ 再改    │  │ 再改    │
                   │ 改好了! │  │ 改好了! │
                   └────┬───┘  └───┬────┘
                        │          │
              ③ Drop   │          │  ③ Drop
              (销毁垃圾)│          │  (销毁垃圾)
                   ┌────▼───┐  ┌───▼────┐
                   │只返回   │  │只返回   │
                   │Git Diff │  │Git Diff │
                   └────┬───┘  └───┬────┘
                        │          │
                        └────┬─────┘
                             │
                    ④ Fan-In 收敛
                             │
                    ┌────────▼─────────┐
                    │  主会话只收到：    │
                    │  ✅ A 的 Git Diff │
                    │  ✅ B 的 Git Diff │
                    │  垃圾日志？不存在的│
                    └──────────────────┘

时间 ─────────────────────────────────────────────►

主 Agent: [改 auth.ts ──── 报错日志塞回 ────] [改 payment.ts ──── 报错日志塞回 ────] [改 logger.ts]
                 │         上下文膨胀            │         上下文爆了             │
                 └── 50行垃圾 ──────────────────┘── 50行垃圾 ───────────────────┘

时间 ─────────────────────────────────────────────►

子 Agent A: [改 auth.ts ──── 报错 ──── 修好 ────] 🗑️ → 只返回 Diff
子 Agent B: [改 payment.ts ─ 报错 ──── 修好 ────] 🗑️ → 只返回 Diff
子 Agent C: [改 logger.ts ── 报错 ──── 修好 ────] 🗑️ → 只返回 Diff
            └─────────── 同时并行 ───────────────┘

主 Session: [干净] ──────────────────────── [收到 3 个 Diff，合并完成]
                                             上下文始终干净！

┌──────────────┐
│  Agent A     │    上下文 = CLAUDE.md + auth.ts + 任务说明
│  重构代码     │
│              │
│  · 修改函数签名 ×
│  · 编译报错   ×
│  · 再改       ×
│  · 又报错     ×
│  · 终于通过！  ✓
│              │
└──────┬───────┘
       │ 🗑️ 销毁所有报错日志
       │ ✅ 只保留 Git Diff
       ▼
┌──────────────┐
│  Agent B     │    上下文 = CLAUDE.md + A 的 Diff + "写测试"
│  写测试       │
│              │    ⚠️ B 完全看不到 A 的 4 次失败！
│  · 看到干净的  │    B 眼里的世界：
│    代码变更   │    "哦，A 把函数签名改成了这样，
│  · 直接写测试  │     那我就按新签名写测试呗"
│  · 一次通过！  ✓
│              │
└──────┬───────┘
       │ 🗑️ 销毁中间过程
       │ ✅ 只保留测试代码的 Diff
       ▼
┌──────────────┐
│  Agent C     │    上下文 = CLAUDE.md + A 的 Diff + B 的 Diff + "Review"
│  Code Review │
│              │    ⚠️ C 看到的只有成品，没有过程
│  · 审查代码   │    "这个命名不太规范"
│  · 审查测试   │    "这里缺个边界测试"
│  · 给出建议   │
│              │
└──────┬───────┘
       │ 🗑️ 销毁中间过程
       │ ✅ 只返回 Review 报告
       ▼
  ┌──────────┐
  │ 主会话    │   总共只增加了 3 份高密度成果
  │ 收到：    │   · A 的代码 Diff
  │ 最终成果  │   · B 的测试 Diff
  └──────────┘   · C 的 Review 报告

// 每个工作流必须以 meta 开头
export const meta = {
  name: 'rename-user-to-account',
  description: '批量将 User 重命名为 Account',
  phases: [
    { title: 'Find', detail: '找出所有 User 引用' },
    { title: 'Rename', detail: '逐文件替换' },
    { title: 'Verify', detail: '验证修改正确性' },
  ],
}

// Phase 1: 找出所有需要改的文件
phase('Find')
const files = await agent(
  '在项目中搜索所有包含 "User" 的文件，返回文件路径列表',
  {
    schema: {
      type: 'object',
      properties: {
        files: {
          type: 'array',
          items: { type: 'string' },
        },
      },
    },
  }
)

// Phase 2: pipeline — 每个文件一个子 Agent，并行修改
//        每个子 Agent 拿到的是干净上下文，互不干扰
phase('Rename')
const results = await pipeline(
  files,
  (file) =>
    agent(`将 ${file} 中的 "User" 重命名为 "Account"`, {
      label: `rename:${file}`,
      phase: 'Rename',
      isolation: 'worktree', // 每个子 Agent 在独立工作区中修改
    }),
  // pipeline 让每个文件独立走完整个流程
  // 文件 A 在 Phase 2 时，文件 B 可能还在 Phase 1
  // 不需要等最慢的文件，先完成的先往下走
)

// Phase 3: 验证 — 对每个修改做对抗性审查
phase('Verify')
const verified = await parallel(
  results
    .filter(Boolean)
    .map((r) => () =>
      agent(`检查这次重命名是否遗漏了任何 User 引用`, {
        label: `verify:${r.file}`,
        phase: 'Verify',
      })
    )
)

// 返回最终结果
return {
  totalFiles: files.length,
  renamed: results.filter(Boolean).length,
  verified: verified.filter(Boolean).length,
}

// 要点 1：agent() 返回的是结构化结果，不是聊天记录
const files = await agent('搜索文件', { schema: FILES_SCHEMA })
// ^ 返回 { files: ['a.ts', 'b.ts', 'c.ts'] }
// 不是 "好的，我帮你搜索了文件，找到了以下..." + 200行日志

// 要点 2：isolation: 'worktree' 确保并行修改不会互相冲突
agent('修改文件', { isolation: 'worktree' })
// 每个子 Agent 在独立的 git worktree 中工作
// 就像给每个厨师分配了独立的厨房

// 要点 3：pipeline() 天然支持串行传递
// 上一步的输出自动成为下一步的输入
const results = await pipeline(
  items,
  stage1, // stage1(item) → result1
  stage2, // stage2(result1, item) → result2
  stage3, // stage3(result2, item) → result3
)

┌───────────────────────────────────────────────────────────────┐
│                    动态工作流经典模式                           │
├───────────────┬───────────────────────────────────────────────┤
│               │                                               │
│  Fan-Out      │  A ──► [子1, 子2, 子3] ──► 合并              │
│  并行分发      │  多个无关任务同时干，最后汇总                   │
│               │  适用：批量修改文件、多源搜索                    │
│               │                                               │
├───────────────┼───────────────────────────────────────────────┤
│               │                                               │
│  Pipeline     │  A ──► B ──► C                                │
│  串行流水线    │  上一步的成果是下一步的输入                      │
│               │  适用：改代码 → 写测试 → Review                 │
│               │                                               │
├───────────────┼───────────────────────────────────────────────┤
│               │                                               │
│  Tournament   │  [子1, 子2, 子3] ──► 对决 ──► 胜者            │
│  锦标赛       │  多个 Agent 竞争同一任务，选最优                 │
│               │  适用：方案比选、命名、设计决策                   │
│               │                                               │
├───────────────┼───────────────────────────────────────────────┤
│               │                                               │
│  Adversarial  │  A 产生 ──► B 对抗验证                         │
│  对抗验证      │  一个干活，一个专门挑刺                         │
│               │  适用：安全审查、代码审查、事实核查               │
│               │                                               │
├───────────────┼───────────────────────────────────────────────┤
│               │                                               │
│  Loop-Until   │  while (没搞定) { 派 Agent 去干 }              │
│  循环直到完成  │  不知道要干多少轮，直到满足停止条件               │
│               │  适用：修 Bug、深度搜索、根因分析                 │
│               │                                               │
└───────────────┴───────────────────────────────────────────────┘

# 触发并行修改
"用 workflow 把 User 重命名为 Account"

# 触发对抗验证
"用 workflow 审查这个 PR，对每个发现做对抗性验证"

# 触发深度搜索
"用 workflow 搜索过去 6 个月的 incident 报告，找出反复出现的根因"

# 触发锦标赛
"帮我给这个 CLI 工具起个名字，用 workflow 多方案竞争"

# 万能触发词
"ultracode"   # 加上这个词，Claude Code 就会创建 workflow

传统模式上下文变化：
│
█ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █  ← 爆了
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ └─ 子Agent 1 的 180 行日志 ─┘│└─ 子Agent 2 的日志 ─┘│
│                              │                        │
└── 用户提问 ──────────────────┴────────────────────────┘

动态工作流上下文变化：
│
█ █ █ █ █ █ █ █ ← 始终稳定
│ │ │ │ │ │ │ │
│ │ │ └─ Diff 1 (30 行) ──┘
│ │ └── Diff 2 (25 行) ────┘
│ └── 用户提问 ─────────────┘

图例：█ = 一个上下文 token