verified: true lastVerifiedAt: 2026-02-19T22:00:00.000Z name: wave-executor description: EPIC级批处理流水线的新进程编排。通过Claude Agent SDK为每个波次生成一个新的Bun进程，防止长时间运行会话中的垃圾回收相关崩溃。 version: 1.0 model: sonnet invoked_by: both user_invocable: true tools: [Read, Write, Bash, Glob, Grep] aliases: [batch-executor, ralph-loop] agents:

router
master-orchestrator
planner category: Planning & Architecture tags:
wave
orchestration
batch
pipeline
epic best_practices:
用于EPIC级批处理工作（>10个工件，>5个波次）
始终提供包含波次定义的计划文件
优先使用追加写入以防止回归
监控库存文件以跟踪波次之间的进度 error_handling: strict streaming: supported

波浪执行器

概述

波浪执行器通过为每个波次生成一个新的Claude Code进程来运行EPIC级批处理流水线，使用Claude Agent SDK。每个波次获得一个干净的Bun运行时，没有积累的spawn()或abort_signal状态，防止了当单个Bun进程处理数千个并发子代理生成时发生的JSC垃圾回收器使用后释放崩溃（oven-sh/bun, anthropics/claude-code#21875, #27003）。

这是框架对Ralph Wiggum模式的实现：使用基于文件的协调在新鲜进程上进行迭代。

何时使用

使用此技能当：

EPIC级批处理工作：>10个工件，>5个波次
多波次技能更新、捆绑生成或大规模重构
任何预计运行>30分钟且包含并行子代理的流水线
先前因Bun段错误而崩溃的工作

不要用于：

简单的1-3个技能更新（直接使用skill-updater）
单技能工作（使用Task()子代理）
适合一个上下文窗口的工作（只需内联完成）

工作原理

路由器通过Bash调用波浪执行器
  │
  └─ node .claude/tools/cli/wave-executor.mjs --plan <path>
       │  （在系统Node.js上运行 — 不是Bun）
       │
       ├─ 读取包含波次定义的plan.json
       ├─ 读取inventory.json以获取恢复状态
       │
       ├─ 对于每个待处理波次：
       │    ├─ SDK query() → 新的Bun进程（新鲜GC）
       │    ├─ Claude执行波次任务
       │    ├─ 将输出流式传输到stdout
       │    ├─ Bun进程退出 → 内存释放
       │    ├─ 更新inventory.json
       │    └─ 休眠 → 下一个波次
       │
       └─ 返回JSON摘要

关键不变性：单个Bun进程积累不超过约100个生成。

调用方式

通过Bash（代理）：

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 在失败运行中断处继续
进度监控： 读取库存文件以查看完成的波次
成本跟踪： 每个波次记录其成本

与路由器集成

路由器应在规划器将工作分类为EPIC级时使用此技能：

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

路由器的Bun进程在执行期间保持空闲（单个Bash调用） — 没有子代理生成，没有钩子积累。

内存协议（强制性）

开始前：

阅读.claude/context/memory/learnings.md获取先前波浪执行的学习
检查库存文件以获取恢复状态

完成后：

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

假设中断：您的上下文可能重置。如果不在内存中，它就没有发生。