swarm-migrate

用途

swarm-migrate 用于把同一个变换批量落地到多个仓库。当同一变换需要在 3 个或更多仓库以相同形态落地时使用，例如工作流版本升级、依赖升级、codemod、引入 lint 规则、密钥轮换、runbook 头部统一。单仓库工作不使用它；探索性任务也不使用它。

主要能力

一个协调器加 N 个并行子代理，每个子代理对应一个目标仓库。
通过 YAML 规格文件（位于 swarm-specs/<name>.yaml）定义：仓库拓扑（repos 与 upstream 依赖顺序）、转换方式（transform，类型可为 codemod、regex、command）、校验条件（verify）、PR 形态（pr：branch_prefix、title、body_file、base、labels）、CI 门禁（ci_gate：required_checks、timeout_minutes、on_failure）、限制（max_parallel、abort_on_novel_failure）。
协调器按拓扑波次释放仓库：上游父仓库全部绿色合并后才进入下游仓库。
每个 worker 在隔离 worktree 中克隆分支、执行转换、校验、推送、创建 PR、等待 CI、汇报。
使用 .swarm-state.json 作为滚动账本，记录 {repo, status, pr_url, ci_state, last_action_at}。
支持冲突自动 rebase：下游 worker 遇到 rebase 冲突时重新获取上游合并提交 SHA 并尝试 git rebase origin/<base>；若仍有冲突则标记冲突文件，不自动解决，上报协调器。
支持推送式状态汇报：worker 通过 SendMessage 通知协调器状态变化（CI 绿色、CI 红色、新失败、跳过），账本仍是权威持久记录。
结束时输出 markdown 报告到 .swarm-logs/<spec-name>-report.md，包含各仓库状态、PR、CI、耗时以及升级的新失败。

使用方式

规格文件示例结构包括 name、description、repos（含 path 与 upstream）、transform（type 与 command）、verify（command 与 expect）、pr（branch_prefix、title、body_file、base、labels）、ci_gate（required_checks、timeout_minutes、on_failure）、limits（max_parallel、abort_on_novel_failure）。

执行流程分为六个阶段：

规格校验：检查每个 repos[].path 存在且为 git 仓库、transform.command 在 dry-run 下返回 0、upstream 引用均已声明、pr.body_file 存在且非空；任一失败即中止并打印失败表。
拓扑排序：根据 upstream 边构建 DAG，检测环并中止，按拓扑波次分组（wave 0 无依赖，wave 1 仅依赖 wave 0，依此类推），写入 .swarm-state.json。
派发波次：对当前波次中每个仓库并行执行（受 max_parallel 限制）：创建隔离 worktree、创建分支、执行转换、校验、推送并创建 PR、轮询 CI（每 45 秒一次，直到 ci_gate.timeout_minutes）。
波次门禁：全绿则释放下一波；有 CI 待定则继续轮询；有 CI 红色则按 ci_gate.on_failure 处理（pause 暂停并询问用户、skip 标记失败继续同级但阻塞下游、abort 终止且不合并）。
冲突自动 rebase：下游 worker 遇到 rebase 冲突时重新获取上游合并提交 SHA，尝试 git rebase origin/<base>；干净则推送并更新账本，有冲突则标记冲突文件并上报，不自动解决。
最终报告：所有波次完成或暂停/中止后，输出 markdown 报告。

示例调用：

# Dry-run：构建 DAG、校验规格，不推送、不创建 PR
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --dry-run

# Live：最多并行派发 4 个 worker
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --max-parallel=4

# 暂停后恢复：同一命令，账本会记住进度
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml

适用场景

同一变换需要落地到 3 个及以上仓库且形态相同。
需要按依赖顺序逐波推进、每步有 CI 门禁和人类可见账本的迁移。
需要跨仓库批量开 PR 并等待 CI 的场景。

限制

不发明规格：规格由用户编写，技能只执行。
不执行跨数据库的 schema 迁移。
不编排生产部署，只开 PR；部署是单独的门禁。
不绕过 create-pr 的 playground-gate 规则：若仓库强制要求，每个 PR 正文必须包含 playground 引用。
硬性规则：从不合并 PR（由人类合并）；从不强制推送（无法快进则暂停）；从不越出规格声明的 repos[]；始终隔离凭据（协调器只记录 URL，不记录 token）；始终尊重现有分支保护。
常见失败模式包括：陈旧 lockfile 导致依赖升级后 npm ci 失败、分支保护阻止 PR 创建、拓扑环、协调器中途崩溃（技能可恢复，重跑同一规格会读取账本并跳过已合并/绿色仓库）、worker 子代理挂起（超过 5 分钟无账本更新则超时并标记 worker-timeout）。
跨会话消息投递不保证，入站控制可能扣留或拒绝消息；.swarm-state.json 始终是权威持久记录。

技能介绍

用途

主要能力

使用方式

适用场景

限制

相关技能