review-workflow

审核工作流（PR / Issue / 协作审核）

本 skill 面向任何 AI Agent：当需要审核一个 PR 或 issue（判断可合并性/可关闭性、多轮修改复核、参与协作审核）时使用。沉淀自本仓库维护方多轮真实审核实践，通用方法可直接复用于其他 GitHub 仓库。

权威定义：仓库 DEVELOPMENT.md（PR 硬性要求 §2、跨平台约束 §3）、AGENT-REVIEW.md（协作审核协议）、AGENTS.md（Agent 义务）。本 skill 是执行方法论，冲突以仓库文档为准。

触发条件

• 使用者说「审核这个 PR / 看看能否合并 / 他又提交了 / 处理下这个 PR」
• 使用者说「看看这个 issue / 处理下 issue / 这个需求实现了吗 / 能不能关」
• 协作审核（AGENT-REVIEW 协议）中认领了 PR/issue，需要执行审核
• 维护方需要复核自己或他人 PR 的多轮修改

核心原则

1. 审核只读，合并/关闭权归维护者：正式 review（APPROVE / REQUEST_CHANGES / COMMENT）与 issue 结论评论可提交，merge / push / close 必须先获得明确指令。「推荐合并」≠「授权合并」，选 review-only 就只提交意见。
2. REST-only：gh CLI 的 GraphQL 命令（gh pr list / gh pr view）对部分仓库会报 Could not resolve to a Repository，但 REST（gh api repos/O/R/...）正常。一律用 gh api（记得 --paginate 拿全量）。
3. 端到端实测：不止读 diff——把 PR 文件提取到工作区实际运行（语法检查 / dry-run / mock 数据驱动）。很多问题只有跑起来才暴露（历史实例：SqliteError: no such table、async IIFE 恒真值短路、删 return 的「语法合法但功能挂」）。
4. 反馈分级：🔴 阻断项（合并前必修）/ ⚠️ 警告 / 💡 建议 / ✅ 通过项也要列出。
5. 阻断项附实测证据：附报错输出/复现步骤，别只说理论——对方的 AI agent 会照做。自报「全部验证通过」≠ 可信，独立写验证脚本重跑。
6. Agent 口吻：review/评论文字以 Agent 口吻陈述（可署背后使用者的账号，但不得用人类第一人称「我要…我做了…」）。
7. 新贡献者身份独立判定：不默认贡献者是人或 agent。老账号+多个公开仓库+个人邮箱 commit = 人类特征；PR body null、工具化口吻 = agent 特征。身份存疑先 issues/N/comments 询问，技术审查照常完成，最终处置等身份确认。
8. 多轮 review 提交新评论，不编辑旧发言：R(n+1) 复核后提交新的 review（新 body + 新 inline），绝不 PATCH 编辑之前轮次的评论——review 链是历史记录。

审查流程

1. 收集上下文

gh api repos/O/R/pulls --jq '.[] | {number, title, user: .user.login, state, draft, created_at, updated_at}'
gh api repos/O/R/pulls/N --jq '{title, body, draft, state, head: .head.sha, head: .head.label, fork: .head.repo.fork, changed_files}'
gh api repos/O/R/pulls/N/files --paginate --jq '.[] | "\(.status) +\(.additions)/-\(.deletions)  \(.filename)"'
gh api repos/O/R/pulls/N/commits --jq '.[] | "\(.sha[0:7]) \(.commit.message | split("\n")[0])"'

• ⚠️ 先对 remote 再动手：git remote -v 拿真实仓库名（cron prompt/记忆里的名字可能过时、写错导致 404 绕圈）。
• draft PR：GitHub 禁合并，评论照发但合并讨论等作者转 Ready for review。
• 「看 issue」≠「看 PR」：使用者说「扫描一下/提交了个新的」时同时查 open issues 和 open PRs。