context-mode 的 PR 审查工作流：GitHub CLI 驱动的并行 Agent 审查与“先合并后修复“实践

context-mode 的 PR 审查工作流：GitHub CLI 驱动的并行 Agent 审查与"先合并后修复"实践

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

导读

本文讲解开源项目 context-mode（一个通过 MCP + hooks 在 17 个 AI 编码平台间优化上下文窗口、持久化会话记忆的运行时）在 GitHub 上如何系统化地审查和合并社区 PR。核心工作流位于仓库的.claude/skills/context-mode-ops/review-pr.md：以ghCLI 一次性批量采集 PR 情报，按 diff 动态组建 10~20 个并行审查 Agent，用"先合并、后修复"的哲学保持社区贡献者积极性，并通过专门的 Validation Engineer 对抗 LLM 最常见的幻觉型提交（不存在的 ENV 变量、不存在的 hook 类型、伪造的配置路径）。读完本文，你将掌握一套可直接复用的多 Agent PR 审查决策矩阵、反幻觉验证协议与 TDD 后续修复流程，并能对照 context-mode 仓库的源码、测试与操作技能文件理解其落地方式。

一、触发条件与核心哲学

触发词

用户只需说出以下任一短语即可进入 PR 审查流程：

"review PR #N" "merge PR #N" "check PR #N"

核心哲学：Merge first, fix on top

review-pr.md开篇就给出了整个工作流的价值观：

Merge first, fix on top.Contributors ghost when you request changes. Merge their work (if not absurd), then fix issues in follow-up commits. This keeps momentum and respects their effort.

贡献者很可能在收到"请修改"的反馈后直接消失。因此只要 PR 不是荒谬的，就先合并，再用后续提交修复问题。唯一的例外是：

• 引入了安全漏洞；
• 破坏了无法修复的核心功能；
• 与项目完全无关。

这一哲学在技能根文件 .claude/skills/context-mode-ops/SKILL.md 中被进一步强化：项目所有者要求以"OSS 帽子"对待社区贡献者——贡献者获得署名、及时审查和尊重性的合并信息，其 PR 必须被逐行审查。而"先合并后修复"的落地规则是：后续修复必须走 TDD（先写失败测试），且修复推送到next分支而非创建新 PR。

二、Step 1：单次批量情报采集（ONE batch call）

所有情报收集必须压缩进一次并行调用，用ghCLI 一次性拉取 PR 的所有元数据、diff、评论、CI 状态与关联 issue：

commands: [ { label: "pr-body", command: "gh pr view {N} --json title,body,state,author,baseRefName,headRefName,additions,deletions,files,reviews,comments,labels" }, { label: "pr-diff", command: "gh pr diff {N}" }, { label: "pr-comments", command: "gh pr view {N} --comments" }, { label: "pr-checks", command: "gh pr checks {N}" }, { label: "pr-files", command: "gh pr view {N} --json files --jq '.files[].path'" }, { label: "related-issue", command: "gh pr view {N} --json body --jq '.body' | grep -oP '#\\d+' | head -5" } ], queries: [ "PR title description changes", "files modified adapter platform", "diff code changes additions deletions", "review comments feedback", "CI check status pass fail", "related issues referenced" ]

其中--jq '.files[].path'用于提取改动文件清单（供 Step 2 决定为哪些平台/领域派 Agent），grep -oP '#\d+'用于从 PR body 提取关联 issue 编号。为什么坚持ghCLI 而不是 raw git 或 curl？SKILL.md 中有明确强制约束：gh正确处理了鉴权、分页和 GitHub API 限流，所有 GitHub 操作必须走gh，包括gh pr view、gh pr diff、gh pr merge --squash、gh pr edit --base next。

三、Step 2：基于 diff 分类并组建 Agent 军队

分类逻辑

分类规则与 issue 分诊工作流 .claude/skills/context-mode-ops/triage-issue.md 的 Step 2 相同，但依据的是 PR 的 diff 而非 issue 文本：

ALWAYS spawn: ├── Context Mode Architect (reviews all changes) ├── QA Engineer (tests everything) ├── DX Engineer (output quality check) BASED ON FILES CHANGED: ├── {Platform} Architect (for each affected adapter) ├── Validation Engineer (verify ENV vars, hooks, configs via websearch) BASED ON CONTENT: ├── {Domain} Architect (database, security, OS, hooks, session, etc.)

从 .claude/skills/context-mode-ops/agent-teams.md 可以看到完整的名册：核心 Agent（Context Mode Architect、QA Engineer、DX Engineer、Git Archaeologist）每次必派；平台 Agent 按受影响的适配器成对派出（如 Claude Code Architect/Staff Engineer、Gemini CLI、OpenCode、OpenClaw、Kilo、Codex、VS Code Copilot、Cursor、Antigravity、Kiro、Pi、Zed）；领域 Agent 按关键词命中派出（Database/Security/OS Compatibility/Hooks/Session/Executor/Web/Performance/Release 等）。context-mode 当前共有 17 个适配器，均需平等对待——SKILL.md 的 MUST-3 明确列出 claude-code、codex、cursor、gemini-cli、opencode、openclaw、pi、omp、vscode-copilot、jetbrains-copilot、qwen-code、kilo、kiro、zed、antigravity、copilot-cli、antigravity-cli，不允许偏袒任何一个。

PR 审查的关键新增角色：Validation Engineer

这是 PR 审查流程区别于 issue 分诊的关键增量。该 Agent 专门核实 PR 中的每一项声明：

• ENV 变量在目标平台是否真实存在；
• hook 格式是否匹配平台的实际 API；
• 配置路径是否真实（而非 LLM 幻觉）；
• 被引用的功能是否真的存在于平台代码库中。

验证手段是 WebSearch + Context7（MCP 工具resolve-library-id→query-docs）。

四、Step 3：并行验证阶段

所有 Agent 同时运行，各自承担明确职责。

Context Mode Architect

检查变更是否与项目架构一致、是否遵循既有模式、作者是否遗漏了边界情况、会话连续性（session continuity）是否被保持，以及TDD 合规性：

• PR 是否包含测试？
• 测试是否验证行为而非实现细节？
• 若无测试：标记为CHANGES_NEEDED（但仍先合并，测试在后续提交中补上）；
• 若测试 mock 了内部协作者：标记——测试应使用公共接口，依据 .claude/skills/context-mode-ops/tdd.md。

tdd.md 进一步解释：好测试是集成风格的，通过公共 API 走真实代码路径，描述"系统做了什么"而非"怎么做的"；坏测试 mock 内部协作者、测试私有方法、断言调用次数/顺序——重构后行为未变但测试破碎，就是测试耦合了实现。

QA Engineer

本地检出 PR 并运行测试矩阵：

# Checkout PR locally gh pr checkout {N} # Run affected adapter tests npx vitest run tests/adapters/{affected}.test.ts # Run full suite npm test # TypeScript npm run typecheck

这些命令与仓库 package.json 中的脚本完全对应：test是vitest run，typecheck是tsc --noEmit。tests/adapters/ 目录下存在每个适配器的独立测试文件（claude-code.test.ts、gemini-cli.test.ts、opencode.test.ts、openclaw.test.ts、kilo.test.ts、codex.test.ts、cursor.test.ts、antigravity.test.ts、kiro.test.ts、zed.test.ts 等），可精确定位受影响适配器的测试范围。注意 tdd.md 中的一条硬性规则：不要运行npm run build或 bundle——server.bundle.mjs、cli.bundle.mjs由 GitHub CI 自动生成，本地只跑npm test和npm run typecheck。

Validation Engineer

针对 PR 中提到的每个 ENV 变量执行三步验证：

// For each ENV var mentioned in the PR: // 1. Grep for it in context-mode source // 2. WebSearch: "{PLATFORM_NAME} {ENV_VAR} environment variable" // 3. Context7: resolve-library-id for the platform, then query-docs // Example: PR adds OPENCODE_CONFIG_PATH // → Search OpenCode source: does this env var exist? // → If not: flag as potential LLM hallucination

Platform Architects

• 审查针对各自平台的改动；
• 对照平台真实的 hook/配置格式验证；
• 检查向后兼容性。

五、Step 4：合并决策矩阵

所有 Agent 的结果汇入一个明确的决策树：

All tests pass + All architects APPROVE? ├── YES → Merge immediately │ ├── TESTS FAIL but fix is trivial? │ └── Merge → Fix on top in follow-up commit │ ├── ARCHITECT has minor concerns? │ └── Merge → Fix concerns in follow-up commit │ ├── VALIDATION catches hallucinated ENV/feature? │ └── Merge if core logic is sound → Remove hallucinated parts │ └── OR: Comment explaining the issue, give 48h, then merge+fix │ ├── SECURITY issue found? │ └── Do NOT merge. Comment with specific vulnerability. │ └── PR is completely off-base? └── Close with kind explanation. Rare — almost never do this.

要点：测试失败但修复微不足道、架构师只有小顾虑、甚至验证出幻觉内容但核心逻辑健全——都先合并再修复；只有安全漏洞会立刻阻止合并；完全跑题的 PR 几乎从不发生，万一发生也要以友善的解释关闭。

六、Step 5：合并到next分支与 TDD 修复流

合并操作

始终使用ghCLI，始终squash 合并到next分支：

# Change PR base to next if needed gh pr edit {N} --base next # Squash merge into next gh pr merge {N} --squash

后续修复

如需后续修复，直接推送到next：

git checkout next git pull origin next

后续修复强制走 TDD（依据 .claude/skills/context-mode-ops/tdd.md）：

# RED: Write failing test for the issue found during review npx vitest run tests/{file}.test.ts # verify FAILS # GREEN: Write minimal fix # ... edit files ... npx vitest run tests/{file}.test.ts # verify PASSES # REFACTOR: Clean up npm test # full suite still passes # Commit git add {files} git commit -m "fix: address review findings from #{N} - {fix 1} - {fix 2} Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>" git push origin next

tdd.md 强调垂直切片：一个测试 → 一个实现 → 重复，绝不横向（先写完所有测试再写所有代码）。同时遵循 CONTRIBUTING.md 的测试文件组织约定——不要新建测试文件，把测试加进覆盖同一领域的既有文件（如 tests/adapters/{adapter}.test.ts），找不到合适位置就先问维护者。

七、Step 6：合并后评论模板

标准合并评论

gh pr comment {N} --body "$(cat <<'EOF' Thanks for this contribution, @{author}! 🎉 Merged into `next` — this will ship in the next release. Could you please test it in your setup once the release is out? You know this area best, so your verification would be really valuable. 🙏 {IF follow-up fixes were made:} I made a small follow-up adjustment in {commit_sha}: - {what was adjusted and why} EOF )"

带顾虑合并的评论

gh pr comment {N} --body "$(cat <<'EOF' Thanks @{author}! Merged this into `next`. I made a few adjustments on top: - {change 1}: {reason} - {change 2}: {reason} These are in {commit_sha}. Could you review those changes and test the complete flow in your environment? The responsibility for verifying this works end-to-end is on you since you're closest to the use case. 🙏 This will ship in the next release! EOF )"

罕见的关闭评论

gh pr comment {N} --body "$(cat <<'EOF' Hey @{author}, thanks for taking the time to put this together! Unfortunately, we can't merge this as-is because: - {specific technical reason} {IF salvageable:} If you'd like to take another pass, here's what would need to change: - {specific guidance} {IF not salvageable:} The direction we're going with this area is {explanation}. I appreciate the effort though! EOF )" gh pr close {N}

这些模板与 .claude/skills/context-mode-ops/communication.md 保持一致的语气准则：以感谢开头、点名 @{author}、具体而专业、清晰给出下一步、克制使用 emoji（最多 👋 🎉 🙏）、把端到端验证的责任温和而明确地交给贡献者——他们最接近用例，验证最有价值。

八、ENV/Feature 验证协议：PR 审查最关键的一环

review-pr.md明确指出：这是 PR 审查中最关键的部分——LLM 频繁幻觉 ENV 变量、hook 和功能。

需要警惕的红旗

1. 新 ENV 变量—— 它在平台中真实存在吗？
2. 新 hook 类型—— 平台支持这个 hook 生命周期吗？
3. 配置路径—— 这是真实的配置位置吗？
4. API endpoint—— 这个 API 真实存在吗？
5. 功能开关—— 这是平台的真实功能吗？

每项声明的四步验证

对 PR 中的每一项声明：

1. Grep 源码：rg "{CLAIM}" src/—— 是否已被使用？
2. WebSearch：搜索该声明的官方文档；
3. Context7：resolve-library-id→query-docs查平台文档；
4. GitHub 源码：平台若开源，直接查其真实仓库。

仓库侧的证据锚点在 src/adapters/detect.ts 的文件头注释中——它列出了经源码审计验证过的各平台 ENV 变量（Claude Code 的CLAUDE_PROJECT_DIR/CLAUDE_SESSION_ID、Gemini CLI 的GEMINI_PROJECT_DIR/GEMINI_CLI、OpenCode 的OPENCODE/OPENCODE_PID、OpenClaw 的OPENCLAW_HOME/OPENCLAW_CLI、Kilo 的KILO/KILO_PID、Codex 的CODEX_CI/CODEX_THREAD_ID、VS Code Copilot 的VSCODE_PID/VSCODE_CWD、Cursor 的CURSOR_TRACE_ID/CURSOR_CLI等），凡不在此表中的变量必须走完整验证协议。SKILL.md 进一步给出了refs/platforms/机制——各上游平台的影子克隆构成反幻觉的"证据基座"，任何"平台支持 X"的声明必须附带refs/platforms/<name>/<file>:<line>的真实源码引用，缺失时禁止发表平台行为断言。

示例：假 ENV 检测

PR adds: process.env.OPENCODE_HOOK_PATH Step 1: rg "OPENCODE_HOOK_PATH" src/ → not found Step 2: WebSearch "OpenCode OPENCODE_HOOK_PATH environment variable" → no results Step 3: Context7 query OpenCode docs for "HOOK_PATH" → not documented Verdict: HALLUCINATED — flag to EM, remove from PR

SKILL.md 记录了这类事故的真实代价：曾因 LLM 断言"Claude Code 会剥离子进程环境变量"而仓促上线inheritEnvKeys（实为子虚乌有）、把 Codex marketplace 放进 Codex 根本不读的路径、把 TUI 展示字符串当成真实 ENV 变量CODEX_PLUGIN_ROOT——模式一模一样：LLM 自信断言 → 直接发布 → 被反噬。这也是为什么 .claude/skills/context-mode-ops/validation.md 把 CLAIM_VERDICT（CONFIRMED / UNCONFIRMED / DEBUNKED / HALLUCINATED）设为所有流程的第一道阻塞闸门。

九、处理陈旧 PR

PR 超过 7 天无任何活动时的处理策略：

1. 检查它是否仍然相关；
2. 若相关：合并，然后在上方修复（merge it, fix on top）；
3. 若不相关：用友善的解释关闭；
4. 永远不要让 PR 悬而未决。

十、从技能文档到仓库实现的证据闭环

这套工作流并非孤立的文档，而是与仓库中的其他操作技能和代码形成闭环：

这套体系把"人类维护者 + LLM Agent 军队"的协作变成了可复制的机械化流程：情报一次采齐、Agent 并行派发、架构师把关、验证工程师反幻觉、EM 用决策矩阵拍板、TDD 兜底修复、模板化评论维系社区温度。对于任何运行多平台、多适配器、高社区活跃度的开源项目，这套 PR 审查工作流都提供了可直接借鉴的工程模板。

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode