| 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 编号
前置要求
- GitHub CLI (
gh) 已安装并认证：gh --version / gh auth status，需要对仓库的读取和评论权限
- 当前目录在 Git 仓库中且有 GitHub remote（
git remote -v 验证）
- Python 3 可用（用于运行
scripts/ 下的辅助脚本）
主流程总览
执行流程是一个 11 步状态机。SKILL.md 仅给出骨架，遇到任何一步规则不清楚时，read 对应 reference 小节。
增量审查分支：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 提前终止外）必须产出三个产物：
- 终端 Markdown review 报告（Step 8）
- 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
- 终端状态报告（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
gh pr view <PR>
gh pr view <PR> --comments
gh pr view <PR> --json reviews
gh pr view <PR> --json state
gh pr view <PR> --json headRefOid --jq '.headRefOid'
gh pr view <PR> --json headRepositoryOwner,headRepository
gh pr diff <PR>
gh pr diff <PR> --name-only
gh pr review <PR> --comment --body-file /tmp/cc-cr-{pr}.md
限制说明
- 仅支持 GitHub 仓库（不支持 GitLab、Bitbucket）
- 依赖
gh CLI 与 Python 3
- 大 PR 审查可能不够全面：diff 经
compress_diff.py 按 agent 职责使用 20K（规范 checker）/12K（bug/logic scanner）预算，超长会截断尾部；自 #120 起截断通过状态报告的 Diff truncated / Coverage 行显式提示（不再静默）
- 不能替代完整的测试套件和人工代码审查
- 非代码文件变更（图片、二进制）无法有效审查
- 静态分析为主；#121 起 tool-layer 会运行仓库自带的 linter/typecheck（确定性、零误报、缺失降级），但仍不运行完整测试套件/build
- 非监听模式：多轮修复依赖外部调度器交替调度 CR agent 和 fix agent
设计原理
- 多 Agent 并行：从不同角度独立审查，避免单一视角的盲区
- 冗余检查：两个 CLAUDE.md checker 用不同 framing（显式规则 + 隐含约定）互补运行（#122）
- Issue 验证：每个发现的问题都经过独立验证，大幅降低误报率
- HIGH SIGNAL：只报告高置信度的问题，避免噪音淹没真正重要的问题
- 终端与 PR 同步：终端输出和 PR 评论完全一致，确保透明性
- 进阶披露：SKILL.md 只载骨架，详细规则在 references/，确定性逻辑在 scripts/
