ops-merge

运行时上下文

执行前，加载：

1. 偏好设置：cat ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json — 读取 owner、timezone、项目注册表
2. 守护进程健康状态：cat ${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json — 如果设置了 action_needed，向用户说明
3. 密钥：GitHub 令牌：环境变量 $GITHUB_TOKEN → Doppler MCP（mcp__doppler__*）→ doppler secrets get GITHUB_TOKEN --plain → 密码管理器

OPS ► 合并

CLI/API 参考

gh CLI（GitHub）

命令	用法	输出
gh pr list --repo <owner/repo> --json number,title,state,headRefName,statusCheckRollup,reviewDecision,mergeable,isDraft	列出 PR 及其状态	JSON 数组
gh pr view <n> --repo <repo> --json title,body,state,mergeable,reviews	PR 详情	JSON
gh pr checks <n> --repo <repo>	CI 检查状态	检查列表
gh pr merge <n> --repo <repo> --squash --admin	Squash 合并 PR	合并结果
gh pr create --repo <repo> --title "<t>" --body "<b>" --base dev	创建 PR	PR URL
gh run list --repo <repo> --limit 5 --json conclusion,name,headBranch	CI 运行记录	JSON 数组
gh run view <id> --repo <repo> --log-failed	失败的 CI 日志	日志输出
gh run watch <run-id> --repo <repo>	实时查看 CI 运行	实时输出（与 Monitor 配合使用）
gh api repos/<repo>/pulls/<n>/comments --jq '.[].body'	PR 审查评论	评论文本

---

Agent Teams 支持

如果设置了 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，则在 Phase 3 中使用 Agent Teams 来处理修复 Agent。这样可以：

• 在优先级变化时中途引导修复 Agent（例如，优先合并重要 PR）
• 修复 Agent 可以报告阻碍事项，你可以在它们完成前重新指派任务
• 共享上下文：如果 fixer-A 发现会影响 fixer-B 的 PR 的破坏性变更，你可以通知 B

团队设置（仅在启用标志时，于 Phase 3 执行）：

TeamCreate("merge-fixers")
Agent(team_name="merge-fixers", name="fixer-[repo]", ...)

使用 SendMessage(to="fixer-my-api", content="PR #2958 was just merged — rebase your branch") 进行协调。

如果未设置该标志，则回退到使用 isolation: "worktree" 的标准并行子 Agent。

预先收集的 PR 数据

${CLAUDE_PLUGIN_ROOT}/bin/ops-merge-scan 2>/dev/null || echo '{"prs":[],"error":"merge-scan failed"}'

你的任务

你是合并协调者。你的工作是合并所有者各个代码库中所有未关闭的 PR，并先修复阻碍合并的问题。

解析参数

从 $ARGUMENTS 中读取：

• --main → 将所有 PR 合并到 dev 后，也同步同时包含这两个分支的代码库中的 dev↔main
• --repo <slug> → 仅限一个代码库（例如，--repo Lifecycle-Innovations-Limited/my-api）
• --dry-run → 报告将执行的操作，不调度 Agent，也不合并任何内容
• --force → 合并前跳过确认提示
• （空）→ 处理所有代码库，仅合并到 dev

阶段 1 — 对 PR 队列分类

解析预先收集的 JSON。每个 PR 都已被分类为以下一种：

分类	含义	操作
ready	CI 通过、已获批准、无冲突	立即合并
needs-rebase	mergeable: CONFLICTING	派遣修复 Agent：基于目标分支执行变基
needs-ci-fix	statusCheckRollup 中存在 CI 失败	派遣修复 Agent：调查日志、修复并推送
needs-review-response	reviewDecision: CHANGES_REQUESTED	派遣修复 Agent：解决审查意见
blocked	mergeStateStatus: BLOCKED（分支保护、必需审查）	说明原因，跳过
draft	isDraft: true	跳过——尚未准备好合并

打印队列：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► MERGE — PR Queue
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Repo | PR | Title | Status | Action |
|------|----|-------|--------|--------|
| my-api | #2958 | fix(migration) | ready | merge |
| my-app | #4456 | feat(apple-04) | needs-ci-fix | dispatch fixer |
| ... | ... | ... | ... | ... |

Ready: N  |  Fix needed: N  |  Blocked: N  |  Draft: N
──────────────────────────────────────────────────────

如果指定了 --dry-run，则在此停止。打印队列并退出。

阶段 2 — 确认并合并已就绪的 PR

除非指定了 --force，否则使用 AskUserQuestion 在合并前进行确认：

Ready to merge N PRs:
  [repo]#[number] — [title] → [base]
  [repo]#[number] — [title] → [base]

  [Merge all N now]  [Let me pick which ones]  [Dry run — don't merge]

如果用户选择“让我选择”，则通过 AskUserQuestion 为每个 PR 显示 [Merge] / [Skip] 选项。

对每个已确认的 PR：

1. 确认 CI 仍然通过：gh pr checks <number> --repo <repo>
2. 如果通过：gh pr merge <number> --repo <repo> --squash --admin
3. 报告：✓ Merged <repo>#<number> to <base>

阶段 3 — 为需要处理的 PR 派遣修复 Agent

对于分类为 needs-rebase、needs-ci-fix 或 needs-review-response 的 PR：

并行派遣子 Agent（最多同时运行 5 个，每个 Agent 负责一个仓库）：

每个修复 Agent 都会获得一个 worktree 和以下任务说明：

Task: Fix PR #<number> in <repo> (<classification>)
Repo path: <path from registry>
Branch: <headRefName>

<classification-specific instructions>

For needs-rebase:
  1. Create worktree: `git worktree add /tmp/ops-rebase-<pr-number> <headRefName>`
  2. cd into worktree: `cd /tmp/ops-rebase-<pr-number>`
  3. Fetch latest: `git fetch origin`
  4. Attempt rebase: `git rebase origin/<baseBranchRef> 2>&1`
  5. If rebase SUCCEEDS (exit 0):
     - Push force-with-lease: `git push --force-with-lease origin <headRefName>`
     - Clean up worktree: `git worktree remove /tmp/ops-rebase-<pr-number> --force`
     - Report: `✓ Rebased <repo>#<number> — conflict resolved`
  6. If rebase FAILS (exit non-zero):
     - Capture the conflicting files: `git diff --name-only --diff-filter=U`
     - Show the diff: `git diff HEAD`
     - Abort the rebase: `git rebase --abort`
     - Clean up worktree: `git worktree remove /tmp/ops-rebase-<pr-number> --force`
     - Surface to orchestrator with the diff output and a structured conflict report:
       ```json
       {
         "pr": <number>,
         "repo": "<repo>",
         "status": "conflict",
         "conflicting_files": ["<file1>", "<file2>"],
         "diff_summary": "<first 500 chars of diff>"
       }
       ```

For needs-ci-fix:
  1. Get failed check logs: `gh run view <id> --repo <repo> --log-failed | tail -80`
  2. Diagnose the failure
  3. Fix the code in a worktree
  4. Commit + push --no-verify
  5. Wait for CI to re-run (or report what was fixed)

For needs-review-response:
  1. Read review comments: `gh api repos/<repo>/pulls/<number>/comments --jq '.[].body'`
  2. Address each comment in code
  3. Reply to each comment via gh api
  4. Push fixes
  5. Re-request review if needed

After fixing:
  - Report back: what was wrong, what was fixed, is CI green now?
  - Do NOT auto-merge after fixing. Report the fix and let Phase 4 handle confirmation.

所有修复 Agent 均使用 model: "sonnet"。

阶段 4 — 解决已发现的冲突

对于修复 Agent 返回的每个 status: "conflict" 的 PR：

1. 显示冲突摘要：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► MERGE — Conflict in <repo>#<number>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Branch: <headRefName> → <baseBranchRef>
 Conflicting files:
   - <file1>
   - <file2>

<diff_summary>
──────────────────────────────────────────────────────

2. 使用 AskUserQuestion（最多 4 个选项——CLAUDE.md 规则 1）：

[Accept incoming (theirs)]  [Keep current branch (ours)]  [Open manual resolution]  [Skip this PR]

3. 根据响应执行：
   • 接受传入更改（theirs）：创建 worktree，在变基时对每个冲突文件执行 git checkout --theirs .，然后执行 git add .、git rebase --continue，并使用 force-with-lease 推送
   • 保留当前分支（ours）：创建 worktree，在变基时对每个冲突文件执行 git checkout --ours .，然后执行 git add .、git rebase --continue，并使用 force-with-lease 推送
   • 手动解决：打印分步操作说明，指导操作人员手动解决，然后在继续合并流程前，确认是否执行 git push
   • 跳过此 PR：标记为 unresolved-conflict，并纳入最终报告

阶段 5 — 汇总结果并确认合并

修复 Agent 完成后：

1. 确认 PR 现在已通过：gh pr checks <number> --repo <repo>
2. 如果通过，使用 AskUserQuestion 确认（除非指定了 --force）：

   Fixer resolved [repo]#[number] — [what was fixed]. CI is now green.
     [Merge now]  [Skip — I'll review manually]
   

3. 如果仍未通过：报告仍存在的问题，不要合并

阶段 6 — --main 同步（仅在设置此标志时）

对于 dev 和 main 分支分开的每个仓库：

1. 检查 dev 是否领先于 main：git -C <path> log main..dev --oneline | head -5
2. 如果领先，显示提交并使用 AskUserQuestion：

   [repo]: dev is N commits ahead of main:
     [commit list]
   
     [Create sync PR and merge]  [Create PR only — I'll review]  [Skip this repo]
   

3. 如果确认：创建同步 PR：gh pr create --repo <repo> --base main --head dev --title "chore: sync dev → main"
4. 等待 CI：gh pr checks <sync-pr-number> --repo <repo> --watch（后台运行，最长 10 分钟）
5. 如果 CI 通过：gh pr merge <sync-pr-number> --repo <repo> --merge --admin（创建合并提交，而非压缩提交）
6. 将 main 合并回 dev：git -C <path> fetch origin && git -C <path> checkout dev && git -C <path> merge origin/main --no-edit

阶段 7 — 最终报告

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► MERGE COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Repo | PR | Result |
|------|----|--------|
| my-api | #2958 | ✓ merged to dev |
| my-app | #4456 | ✓ fixed CI + merged |
| mise | #10 | ✗ 3 critical bugs — skipped |

Merged: N PRs across M repos
Skipped: N (blocked/draft)
Failed: N (still need manual attention)

Main sync: N repos synced (dev → main → dev)
──────────────────────────────────────────────────────

---

安全防护栏（绝不可违反）

• 绝不可向 main/master 强制推送
• 绝不可在 CI 检查失败时合并——先修复根本原因
• 绝不可绕过涉及身份验证、支付、个人身份信息或机密信息的 PR 审查——这些 PR 在合并前必须由 security-reviewer 子 Agent 审计
• 绝不可在共享分支上运行 git reset --hard
• 修复时务必使用 worktree（可能有多个 Agent 同时工作）
• 仅在将更改压缩合并到 dev 时使用 --admin（除非使用 --main 标志，否则不可用于 main）
• 每次调用最多处理 10 个 PR，避免触发 GitHub API 限流
• 如果某个 PR 更改的文件超过 50 个，请将其标记为需要人工审查，而不是自动合并

---

原生工具用法

Monitor — 实时监控 CI

修复 Agent 推送更改后（第 3–4 阶段）等待 CI 时，使用 Monitor 流式查看 GitHub Actions 运行输出，而不是反复轮询：

Monitor(command: "gh run watch <run-id> --repo <repo>")

这样可以避免循环等待，并实时反馈 CI 进度。

Tasks — 进度跟踪

为整体合并流程创建一个 TaskCreate，并为每个 PR 单独创建任务。每当修复、合并或跳过一个 PR 时，使用 TaskUpdate 更新任务。这样用户就能实时查看检查清单。

WebSearch — CI 失败背景信息

修复 Agent 遇到不常见的 CI 失败时，使用 WebSearch 查找已知问题（例如 npm 注册表中断、GitHub Actions 事故、易出错的测试模式）。