build-train

build-train

将多个 issue 批量执行到同一个构建分支中。阶段 01 规划依赖顺序； 阶段 02 按批次启动并行构建子 Agent——构建相互独立时并发执行， 一个构建依赖另一个构建的输出时则按顺序执行。阶段 03 将所有 PR 合并到构建 分支，阶段 04 向默认分支发起一个最终 PR（只运行一次评审流水线）。

目的

将单体的 build-train 技能转换为 ICM 流程。单体流程在一个长期会话中分派工作进程；到了合并阶段，其上下文已包含每个工作进程的提示词和日志，导致冲突解决判断能力下降。此流程将每个阶段隔离到专注于该阶段的子 Agent 中，并且——关键的是——用依赖图批次调度器取代串行的“启动一个工作进程、等待、再启动下一个”循环：没有未满足依赖项的构建会作为并发 Task 子 Agent 运行；有依赖关系的构建则等待其前置项交接。

参数

参数	必填	默认值	备注
repo	是	—	org/repo，第一个位置参数
--issues	是	—	以逗号分隔的 issue 编号，例如 10,14,15,16
--branch	否	build/YYYY-MM-DD	构建分支名称；如果已存在，则追加 -2 后缀

从 $ARGUMENTS 解析。

功能

6 阶段 ICM 流程：

阶段	模式	说明
00-setup	内联	默认分支，创建构建分支和标签，读取所有 issue
01-plan-order	子 Agent	读取 issue 正文，推导依赖图，生成构建批次
02-build-fanout	子 Agent（并行）	按批次分派构建：批次内并行，依赖边之间按顺序执行。每个构建对应一个产出 PR 的 Task 工作进程；验证并修复目标分支/标签
03-merge-chain	子 Agent	将每个 build-train PR 合并到构建分支，解决冲突
04-final-pr	子 Agent	向默认分支发起一个最终 PR：构建分支 → 默认分支（不添加 build-train 标签）
05-report	内联	编写报告，输出结果标记

交接文件位置

.procedure-output/build-train/{stage}/handoff.md

阶段 02 还会为每个构建写入一个子交接文件：

.procedure-output/build-train/02-build-fanout/builds/{issue}.md

阶段 00 写入根上下文（仓库、默认分支、构建分支、issue 清单）。所有子 Agent 阶段只接收所需的交接文件——绝不接收完整的编排器上下文。

执行

阶段 00（内联）

由你自行运行。读取 CONTEXT.md：

.claude/skills/build-train/stages/00-setup/CONTEXT.md

将交接文件写入 .procedure-output/build-train/00-setup/handoff.md。

阶段 01（子 Agent）

启动一个 Task。只传入 00-setup 交接文件路径和阶段 CONTEXT.md 路径。

阶段 02（子 Agent——内部并行，批次调度器）

为分派阶段启动一个 Task。该阶段的 CONTEXT.md 驱动批次循环：它读取阶段 01 的构建顺序，然后逐批将该批次的所有构建作为并发 Task 工作进程在同一个响应中启动，并且不会在批次内部等待；待整个批次完成后再启动下一批次。由顺序依赖边连接的构建会进入后续批次。

Task 提示词模板（适用于每个子 Agent 阶段）：

You are running stage {NN}-{name} of the build-train procedure.

Read your stage instructions:
  .claude/skills/build-train/stages/{NN}-{name}/CONTEXT.md

Your inputs:
  {only the input handoff paths this stage's CONTEXT.md lists}

Write your output to:
  .procedure-output/build-train/{NN}-{name}/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

阶段 03 → 04（顺序子 Agent）

分别为每个阶段启动一个 Task。只传入该阶段 CONTEXT.md 列为输入的交接文件。在当前阶段完成前，不要启动下一阶段。如果阶段失败，则输出失败标记；仅当失败无法恢复时才停止（参见退出路径）。

阶段 05（内联）

由你自行运行。读取 CONTEXT.md，并由编排器输出 [pylot] outcome=... 标记（绝不由子 Agent 输出）。

阶段交接链

00 ─► 01 ─► 02 ─► 03 ─► 04 ─► 05 (inline, reads all)

02 internal wave fan-out:
   wave 1: [build A] [build B] [build C]   ← concurrent Task subagents
              │         │         │
              └────── all join ───┘
   wave 2: [build D depends on A] [build E depends on B,C]   ← concurrent
              │                        │
              └──────── all join ──────┘
   wave 3: [build F depends on D] ...

退出路径

• 成功：阶段 05 输出 [pylot] outcome="build-train complete: final PR #N (M/N issues)" status=success
• 失败：失败的阶段输出 [pylot] outcome="build-train failed at stage NN: {reason}" status=failed
• 受阻：阶段 00 发现已有正在进行的 build/* 构建列车 → [pylot] outcome="build-train blocked: existing build branch {name}" status=blocked

阶段 02 中单次构建失败不会导致构建列车失败——失败的问题会被跳过，构建列车继续运行（跳过而非中断）。只有在所有构建都失败时，构建列车才会失败。

硬性规则

1. 阶段 02 中同一波次的构建必须并行启动——在同一条回复中发起该波次的所有 Task 调用，中间不得等待。
2. 遵守顺序依赖边——尚未满足依赖条件的构建应延后到后续波次；在其前置任务的子交接文档存在之前，绝不能启动该构建。
3. Worker 提示词必须指定 --base $BUILD_BRANCH——这是首要指令，并且要在提示词中重复两次。
4. 每个构建 Worker 完成后都要验证并修复对应的 PR——如果 Worker 设置错误，应更改基础分支并添加 build-train 标签。
5. 最终 PR 不得带有 build-train 标签——它会进入常规审核流程。
6. 绝不强制推送构建分支。
7. 跳过而非中断——构建失败或 PR 无法合并时，应跳过并记录；构建列车继续运行。
8. 每个仓库同一时间只能运行一个构建列车——阶段 00 会在启动前检查是否存在 build/* 分支。
9. 范围锁定——每个 Worker 只能处理分配给自己的问题，不得处理其他内容。
10. 阶段 00 和 05 内联运行——[pylot] outcome=... 标记必须由编排器生成。
11. 不得将完整的编排器上下文传入子 Agent 的 Task 提示词——仅传入输入内容。
12. **每个阶段都必须先写入 handoff.md，下一阶段才能读取。**不得跳过任何阶段（即使操作是“无事可做”，也要执行）。

参考文件

• CONTEXT.md——架构概述
• stages/NN-name/CONTEXT.md——各阶段的输入、任务和输出约定