wave-executor

Wave Executor

概述

Wave Executor 通过 Claude Agent SDK 为每个波次启动一个全新的 Claude Code 进程，以运行 EPIC 级批处理流水线。每个波次都会获得一个干净的 Bun 运行时，不会累积任何 spawn() 或 abort_signal 状态，从而避免 JSC 垃圾回收器使用后释放崩溃（oven-sh/bun、anthropics/claude-code#21875、#27003）。当单个 Bun 进程处理数千个并发子 Agent 启动时，就会发生此类崩溃。

这是该框架对 Ralph Wiggum 模式的实现：通过文件协调，在全新的进程中迭代运行。

适用场景

在以下情况下使用此技能：

• EPIC 级批处理工作：超过 10 个产物、超过 5 个波次
• 多波次技能更新、资源包生成或大规模重构
• 任何预计会在并行子 Agent 下运行超过 30 分钟的流水线
• 之前因 Bun 段错误而崩溃的工作

请勿用于：

• 简单的 1–3 个技能更新（直接使用 skill-updater）
• 单技能工作（使用 Task() 子 Agent）
• 可在一个上下文窗口内完成的工作（直接在当前上下文中完成）

工作原理

Router invokes wave-executor via Bash
  │
  └─ node .claude/tools/cli/wave-executor.mjs --plan <path>
       │  (runs on system Node.js — NOT Bun)
       │
       ├─ Reads plan.json with wave definitions
       ├─ Reads inventory.json for resume state
       │
       ├─ For each pending wave:
       │    ├─ SDK query() → NEW Bun process (fresh GC)
       │    ├─ Claude executes wave tasks
       │    ├─ Streams output to stdout
       │    ├─ Bun process exits → memory freed
       │    ├─ Updates inventory.json
       │    └─ Sleeps → next wave
       │
       └─ Returns JSON summary

关键不变量：单个 Bun 进程累积的启动次数不得超过约 100 次。

调用方式

通过 Bash 调用（Agent）：

node .claude/tools/cli/wave-executor.mjs --plan <path> --json

通过斜杠命令调用（用户）：

/wave-executor --plan .claude/context/plans/my-plan.json

CLI 标志：

标志	默认值	描述
--plan <path>	必需	波次计划 JSON 的路径
--model <model>	claude-sonnet-4-6	执行波次所用的模型
--max-turns <n>	50	每个波次的最大对话轮数
--start-from <n>	1	从第 N 个波次恢复
--dry-run	false	预览而不执行
--json	false	机器可读输出

计划文件格式

{
  "name": "enterprise-bundle-generation",
  "waves": [
    {
      "id": 1,
      "skills": ["rust-expert", "python-backend-expert", "typescript-expert"],
      "domain": "language",
      "promptTemplate": "Update enterprise bundle files for skills: {skills}. Read each SKILL.md and .claude/rules/ file. Do 3-5 WebSearch queries for current {domain} tools and patterns. Generate domain-specific bundle files (append-only, never overwrite non-stubs). Validate JSON schemas and Node.js syntax. Commit results."
    },
    {
      "id": 2,
      "skills": ["nextjs-expert", "react-expert", "svelte-expert"],
      "domain": "web-framework"
    }
  ],
  "config": {
    "model": "claude-sonnet-4-6",
    "maxTurnsPerWave": 50,
    "sleepBetweenWaves": 3000,
    "inventoryPath": ".claude/context/runtime/wave-inventory.json"
  }
}

每个波次都必须包含 id（数字）和 skills（非空数组）。可选字段：domain、promptTemplate。

清单跟踪

执行器会在配置的路径维护清单文件（默认路径为 .claude/context/runtime/wave-inventory.json）。该文件支持：

• 从崩溃处恢复： --start-from N 会从失败的运行停止处继续
• 监控进度： 读取清单文件以查看已完成的波次
• 跟踪成本： 每个波次都会记录其成本

与 Router 集成

当规划器将工作分类为 EPIC 级时，Router 应使用此技能：

1. 规划器创建包含波次定义的计划文件
2. Router 调用：Skill({ skill: 'wave-executor' })
3. Agent 运行：node .claude/tools/cli/wave-executor.mjs --plan <path> --json
4. Router 读取 JSON 结果，判断成功或失败

执行期间，Router 的 Bun 进程会保持空闲（仅进行一次 Bash 调用）——不启动子 Agent，也不会累积钩子。

铁律

1. 始终在全新的 Bun 进程中启动每个波次，以防止长时间运行的会话发生与 GC 相关的崩溃
2. 绝不批量运行超过已配置 MAX_PARALLEL_WAVES 限制的并发波次
3. 始终等待波次完成确认后，再启动下一个波次
4. 绝不在当前波次存在任何失败或未完成的 Agent 时进入下一个波次
5. 始终记录波次元数据（波次编号、Agent 数量、持续时间），以便观察流水线运行情况

反模式

反模式	失败原因	正确做法
在多个波次中重复使用同一进程	GC 压力会导致长流水线崩溃	每个波次启动一个全新的 Bun 进程
超出 MAX_PARALLEL_WAVES	资源耗尽并导致不稳定的失败	遵守配置的并发限制
当前波次完成前就启动下一波次	发生竞态条件，流水线状态不完整	等待波次完成信号后再继续
忽略波次中失败的 Agent	部分状态会传播错误数据	继续之前先停止并报告失败
不记录波次元数据	无法诊断是哪个波次导致了问题	在上下文中记录波次编号、Agent 和持续时间

记忆协议（强制）

开始前：

• 阅读 .claude/context/memory/learnings.md，了解之前执行波次时的经验
• 检查清单文件，确认恢复状态

完成后：

• 将波次执行摘要追加到 .claude/context/memory/learnings.md
• 将任何错误记录到 .claude/context/memory/issues.md
• 将架构决策记录到 .claude/context/memory/decisions.md

假设会发生中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。