read-only-gh-pr-review

PR 审查（后端，GitHub CLI）

概述

使用本地代码分析和 GitHub CLI API 调用，端到端审查后端拉取请求。仅报告可采取行动且信号明确的问题。

工具限制

• 仅使用：SemanticSearch、WebSearch、Grep、LS、Glob、Read、Shell、GitHub CLI。
• 运行任何 gh 命令前，先加载只读环境脚本以启用安全强制措施：

  source "<SKILL_DIR>/scripts/activate-gh-readonly.sh"
  

  将 <SKILL_DIR> 替换为此技能目录的绝对路径。
• 加载后，直接使用 gh 命令——它们会由只读包装器拦截。
• 首先验证 CLI 身份验证状态：运行 gh auth status。如果尚未通过身份验证，请让用户运行 gh auth login。
• 始终严格遵守只读模式。
• 绝不尝试任何写入操作，包括评论、审查、编辑、分配、合并、关闭、重新打开或 API 变更。
• 如果请求的命令被包装器拦截，不要尝试可能更改状态的替代方案。
• 只读包装器会拦截 command gh 和其他绕过尝试。

工作流

1. 启用只读环境。
   • 加载环境脚本：source "<SKILL_DIR>/scripts/activate-gh-readonly.sh"
   • 此 Shell 会话中之后的所有 gh 命令都会受到保护。
2. 准备审查上下文。
   • 确认身份和身份验证状态：gh auth status、gh api user。
   • 从当前仓库解析所有者/名称，或传入 -R <OWNER>/<REPO>。
3. 确定目标 PR。
   • 已知 PR 编号时，使用 gh pr view <PR_NUMBER> [--json <fields>]。
   • 否则，使用 gh pr list [flags] 缩小范围并选定目标 PR。
4. 将本地仓库同步到 PR 分支的最新代码。
   • 审查代码前，获取 PR 头部分支的最新远程状态。
   • 示例流程：
     • 从 PR 元数据（headRefName）获取头部分支名称。
     • 运行 git fetch --prune origin <HEAD_BRANCH>。
     • 审查 FETCH_HEAD 中的文件，或从中检出本地审查分支。
5. 在做出判断前收集完整的 PR 证据。
   • 元数据：gh pr view <PR_NUMBER> [--json <fields>]
   • 差异：gh pr diff <PR_NUMBER> [--patch|--name-only]
   • 已更改文件：gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/files --paginate
   • 审查：gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews --paginate
   • 检查：gh pr checks <PR_NUMBER> [--json <fields>]
   • 评论：
     • gh pr view <PR_NUMBER> --comments
     • gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments --paginate
     • gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments --paginate
6. 深入检查已更改的后端代码。
   • 在本地读取所有高风险的已更改文件（Read、Grep），并结合差异代码块进行核对。
   • 优先检查请求处理器/控制器、业务服务、授权逻辑、数据库查询、迁移、后台任务以及队列/事件处理器。
   • 验证幂等性、事务安全性、并发行为、重试行为，以及公共 API 契约的向后兼容性。
   • 需要精确远程内容时，使用 gh api repos/<OWNER>/<REPO>/contents/<PATH>?ref=<REF>（.content 中通常是 base64 编码的内容）。
7. 按风险优先顺序应用审查清单。
   • 使用 references/review-checklist.md。
   • 先检查安全性、正确性、数据完整性、API 兼容性、性能和测试充分性，再关注代码风格问题。
8. 生成可采取行动的审查结果。
   • 仅报告可能属于缺陷、回归或可维护性风险的问题。
   • 每个问题在报告前都必须符合下方的证据和验证规则。
   • 包含精确的 file:line、影响以及具体的修复建议。
   • 结尾说明残余风险以及缺失的验证/测试假设。
   • 仅在聊天中返回问题；不要向 GitHub 写入任何评论或审查。

证据与验证

每项报告的问题都必须区分已验证的事实与假设。绝不能把假设说成事实。

• 事实：通过阅读实际代码、差异或命令输出验证的行为。每项事实都要引用 file:line。
• 假设：任何未经验证的推断——运行时行为、未查看的配置、外部服务行为、数据量、部署拓扑、调用方在差异之外的行为。

规则：

• 报告问题前，追踪完整的代码路径：调用方、依赖项和现有防护。不要报告已被其他位置的防护或验证阻止的问题；先找到并阅读相关代码。
• 如果可以查看周边文件或调用方，不要只依据差异代码块报告问题。
• 标明每项发现所依赖的所有假设，并说明如何确认。
• 如果无法根据现有证据验证某项疑虑，要么将其作为问题提出并明确标注假设，要么舍弃。不要将其报告为缺陷。
• 绝不要编造行号、符号、代码片段或行为。只引用真实代码。
• 如果证据不完整（文件被截断、命令失败、引用不可用），要在发现中说明，不要用猜测填补空白。

响应格式

按以下顺序使用这些章节：

1. 严重问题（必须修复）
2. 重要问题（应当修复）
3. 建议（可考虑）

每项问题使用：

Issue: <brief description>
Location: <file:line>
Severity: <Critical|High|Medium|Low>
Facts: <verified behavior with file:line evidence>
Assumptions: <unverified inferences this finding depends on, and how to confirm them; "None" if fully verified>
Problematic Code: <snippet quoted from the actual code>
Suggestion: <specific fix>
Example: <optional patch-style snippet>

Assumptions: None 表示已确认的缺陷。依赖假设的发现必须采用条件式表述（例如，“如果上游未强制执行 X，那么……”）。

GitHub CLI API 对应项

使用 references/github-cli-map.md 中的命令映射。

评审语气

• 提供有建设性且具体的反馈。
• 说明影响和理由。
• 假定对方出于善意。
• 优先给出简洁且有充分把握的反馈。
• 明确说明不确定性；标注假设胜过自信地猜测。