github-code-review-batch

name	github-code-review-batch
description	对 GitHub Pull Request 进行批量/调度式代码审查（一次性短会话，非监听模式）， pi-coding-agent 端。多 Agent 并行检查 CLAUDE.md / AGENTS.md 合规性、bug 和逻辑安全问题， 通过 issue 验证机制过滤误报。状态通过 PR 评论的 metadata 持久化， 供 PJob 调度器（zima daemon 或 webhook-server）触发 CR 审查流程。 Use when: 用户要求对指定 PR 进行一次性批量审查或调度式审查， 且不希望启动后台监听进程。 触发词: "batch review pr", "review pr batch", "scheduled review pr"

GitHub Code Review Batch (pi-coding-agent)

GitHub PR 批量/调度代码审查工具，非监听模式。

本 Skill 是 pi-coding-agent 单 agent 审查：每次调用独立审查 PR，结论通过 <!-- pi-cr-meta --> HTML metadata 持久化，供增量审查与外部调度器读取。历史 cc 版评论（cc-cr-meta / Generated with Claude Code）与 kimi 版评论（kimi-cr-meta）在增量解析时严格忽略——各 harness 的审查历史互不干扰。

与监听模式的区别：

• 每次调用都是独立短会话，执行完立即结束，不启动 background watcher
• 状态完全通过 PR 评论中的 HTML metadata 持久化，下次调用时恢复
• 适用于外部调度器交替调度 CR agent 和 fix agent 的场景
• 每次结束输出机器可读的【状态报告】，供调度器决策是否继续调度 fix agent

触发与 PR 编号提取

⚠️ 触发短语是外部契约：调度器（zima daemon 或 webhook-server）通过 skill 名 + 字面短语 "batch review pr" / "review pr batch" / "scheduled review pr" 调用本 skill。改动这些字面短语会破坏外部调度契约——优化 description 时务必保留这三个短语原文。

支持的调用方式：

batch review pr
batch review pr #123
review pr batch 456
scheduled review pr owner/repo#101

PR 编号提取规则（依次尝试）：

• #123 格式
• 直接数字 456
• owner/repo#123 格式
• 都未提供 → 使用 bash 执行 gh pr view --json number 获取当前分支关联的 PR
• 当前分支也无关联 PR → 提示用户明确提供 PR 编号

前置要求

1. GitHub CLI (gh) 已安装并认证：gh --version / gh auth status，需要对仓库的读取和评论权限
2. 当前目录在 Git 仓库中且有 GitHub remote（git remote -v 验证）
3. Python 3 可用（用于运行 scripts/ 下的辅助脚本）

主流程总览

执行流程是一个 11 步状态机。SKILL.md 仅给出骨架，遇到任何一步规则不清楚时，read 对应 reference 小节。

步骤	目的	详细规则
Step 0	检测 previous metadata，判断首次/增量审查	flow.md#step-0
Step 0.2a	解析 committer 对历史 issues 的回应（wontfix / resolved / clarified）	flow.md#step-0-2a
Step 1	PR 资格审查（closed/draft/trivial 检查）	flow.md#step-1
Step 2	收集 CLAUDE.md / AGENTS.md（含子目录）	flow.md#step-2
Step 3	summarizer 生成变更摘要	flow.md#step-3, subagent-prompts.md#summarizer
Step 3.5	diff 预处理（过滤测试文件 + 长度兜底）	scripts/compress_diff.py
Step 4	5 个并行审查 Agent	subagent-prompts.md
Step 5	issue-validator 并行验证	subagent-prompts.md#issue-validator
Step 6	过滤 + 去重 + 优先级排序	flow.md#step-6
Step 7	最终资格审查（防止给已关闭 PR 发评论）	flow.md#step-7
Step 8	终端输出 Markdown 报告	flow.md#step-8
Step 9	构建并发布 PR Review 评论（含 metadata）	scripts/build_review_body.py

增量审查分支：Step 0 检测到有新 commit 且存在上一轮 metadata 时，跳过 Step 3-5，改用单个 delta-reviewer agent。流程详见 delta-review.md。

关键约束（why 优先）

• bash 执行所有 gh 和 git 命令：保持环境无关性。gh CLI 是不依赖 MCP 的最大公约数，跨调度器/容器/裸机都能跑
• subagent 启动所有审查/验证 subagent：用 subagent 工具的 workflowScript + runs.all 并行 fanout（agent: "reviewer"、context: "fresh"），获得与独立上下文执行等价的语义；并行派发细节见 flow.md Step 4
• 不依赖任何 MCP 工具（如 pull_request_read、add_issue_comment）：保持 skill 在不同环境间可移植，避免对接环境时被 MCP 配置卡住
• 每轮发布新评论，不编辑旧评论：metadata 是审查历史的事实记录，覆写会丢失中间状态——下游 fix agent 与人类 reviewer 都依赖完整的轮次链
• Acknowledged issues 不计入 active open：尊重 committer 决策，避免跨轮反复打扰；调度器只对未 acknowledged/wontfix、status: open 且 effective blocking=true 的 findings 调度 fix agent
• Low 默认 advisory：下游确定性规范化 severity=low → blocking=false，其余 severity → blocking=true；只有显式 JSON boolean blocking 可覆盖，旧 metadata 缺字段时按 severity 派生（缺失/非法 severity 按 medium，因此 blocking）

输出契约

每次执行（除 Step 1/Step 7 提前终止外）必须产出三个产物：

1. 终端 Markdown review 报告（Step 8）
2. PR 评论（Step 9）：由 scripts/build_review_body.py 生成，包含 <!-- pi-cr-meta ... --> 机器可读 header + 人类可读 Round-N 部分。metadata 保留所有 findings 与事实计数 total_issues / new_count，并含 blocking_open_count / blocking_new_count / advisory_open_count / advisory_new_count；每个 finding 都有规范化后的 boolean blocking。Part B 正常列出 blocking findings，并把 advisory findings 完整放在折叠的 Advisory / non-blocking findings 小节。完整样例见 output-examples.md
3. 终端状态报告（Step 10）：由 scripts/render_status_report.py 生成，Total/New 保持全量事实计数，新增 blocking/advisory 计数；三态名称和 Status: 行契约不变：
   • NEEDS_FIX — 仍有 open blocking findings 需要修复
   • PASS — 无 open blocking findings（可能仍有 advisory 或 acknowledged findings）
   • NO_NEW_COMMITS — Step 0 检测到无新 commit，本轮跳过
   • 新 payload 的 Status、Verdict: 与 XML verdict 均由 blocking open count 驱动；完全缺少 blocking 字段的旧 caller 回退到原 open_count / new_count 语义
   • 状态报告还含 blocking Critical issues: 计数与派生的 Verdict:（#119：SKIP / BLOCK_MERGE / READY_TO_MERGE / MERGE_WITH_CAUTION），均追加在 Status: 行之后，不影响 grep
   • 分隔线之后追加 <zima-review><verdict>...</verdict><summary>...</summary></zima-review> XML trailer（#176）：zima executor 靠它驱动 postExec 标签流转，pi 型 agent 的 CR PJob 必需

PJob 调度器（zima daemon 或 webhook-server）通过 grep Status: <state> 决策下一步动作（可选消费 Verdict: 优先处理含 blocking critical 的 PR）；fix agent 只消费 open blocking findings。

SubAgent 概览

Agent	职责	并发数
summarizer	摘要 PR 变更意图	1
claude-compliance-checker	检查 CLAUDE.md 合规（显式规则 + 隐含约定两种 framing）	2（差异化，#122）
agents-compliance-checker	检查 AGENTS.md 合规	1
bug-scanner	扫描 bug（导入/引用由 tool-layer 覆盖，#121）	1
logic-analyzer	逻辑/安全分析、资源泄漏、竞态	1
issue-validator	验证 issue 是否值得保留	每个候选 issue 1 个
delta-reviewer	增量审查（替代上述 Step 3-5）	1（仅增量模式）

此外，Step 4 先运行脚本 run_tool_layer.py（ruff/mypy/tsc/eslint，确定性、零误报、缺失降级，#121），产出 lint/typecheck 类 issue 与 agent 结果合并。

每个 agent 的输入契约、输出 schema、prompt 模板：subagent-prompts.md。

边界情况与故障排除

完整边界情况表（22 条）+ 故障排除（4 类）+ 常见误报类型（6 种）见 edge-cases.md。

几条最容易遇到的：

• 无新 commit 时：Step 0 直接输出状态报告 NO_NEW_COMMITS 退出
• Metadata 完全无法解析：报错并停止，不静默 fallback 到 Round-1（避免破坏调度器状态机）
• 审查中途 PR 被关闭：Step 7 拦截，不发布评论
• 所有 issues 都被 committer acknowledged：状态报告输出 PASS

常用 gh 命令

gh pr view --json number                                        # 当前分支关联 PR
gh pr view <PR>                                                 # PR 详情
gh pr view <PR> --comments                                      # 所有评论（用于 Step 0.2a）
gh pr view <PR> --json reviews                                  # review 评论（喂给 parse_metadata.py）
gh pr view <PR> --json state                                    # PR 状态（Step 7 二次检查）
gh pr view <PR> --json headRefOid --jq '.headRefOid'            # head SHA（40 字符）
gh pr view <PR> --json headRepositoryOwner,headRepository       # 仓库信息（构建链接）
gh pr diff <PR>                                                 # 完整 diff
gh pr diff <PR> --name-only                                     # 变更文件列表（Step 2）
gh pr review <PR> --comment --body-file /tmp/cc-cr-{pr}.md      # 发布 review 评论

限制说明

1. 仅支持 GitHub 仓库（不支持 GitLab、Bitbucket）
2. 依赖 gh CLI 与 Python 3
3. 大 PR 审查可能不够全面：diff 经 compress_diff.py 按 agent 职责使用 20K（规范 checker）/12K（bug/logic scanner）预算，超长会截断尾部；自 #120 起截断通过状态报告的 Diff truncated / Coverage 行显式提示（不再静默）
4. 不能替代完整的测试套件和人工代码审查
5. 非代码文件变更（图片、二进制）无法有效审查
6. 静态分析为主；#121 起 tool-layer 会运行仓库自带的 linter/typecheck（确定性、零误报、缺失降级），但仍不运行完整测试套件/build
7. 非监听模式：多轮修复依赖外部调度器交替调度 CR agent 和 fix agent

设计原理

1. 多 Agent 并行：从不同角度独立审查，避免单一视角的盲区
2. 冗余检查：两个 CLAUDE.md checker 用不同 framing（显式规则 + 隐含约定）互补运行（#122）
3. Issue 验证：每个发现的问题都经过独立验证，大幅降低误报率
4. HIGH SIGNAL：只报告高置信度的问题，避免噪音淹没真正重要的问题
5. 终端与 PR 同步：终端输出和 PR 评论完全一致，确保透明性
6. 进阶披露：SKILL.md 只载骨架，详细规则在 references/，确定性逻辑在 scripts/