review-gitcode-pr

Review GitCode PR

当评审从 GitCode PR 引用开始，且需要结合 oh-gc 产物与本地仓库检查时，运行此技能。

工作流

1. 解析 PR

首先规范化用户输入。

• 如果用户提供了 PR 编号，直接使用。
• 如果用户提供了 URL，提取 PR 编号，并在可能时提取 OWNER/REPO。
• 如果规范化后的结果不包含 OWNER/REPO，scripts/collect_pr_context.py 会尝试从当前仓库的 GitCode 远程 URL 推断。
• 如果远程推断存在歧义，或当前检出目录不是 GitCode 克隆，显式传入 --repo OWNER/REPO。
• 使用 scripts/normalize_pr_ref.py 执行此规范化步骤。

2. 收集远程上下文

使用 scripts/collect_pr_context.py 获取并保存 PR 上下文，然后再手动评审代码。

该脚本会收集：

• oh-gc pr:view NUMBER --json
• oh-gc pr:diff NUMBER --json
• oh-gc pr:diff NUMBER --name-only
• oh-gc pr:diff NUMBER --color never
• oh-gc pr:comments NUMBER --json --comment-type pr_comment
• oh-gc pr:comments NUMBER --json --comment-type diff_comment

提出结论前，先检查生成的产物目录。按以下顺序读取产物：

1. summary.json，用于识别变更文件、解析后的代码块、可评论的新版本行以及已有的规范化上下文。
2. pr-diff.txt，用于核实任何候选问题的确切差异文本和代码块边界。
3. pr-view.json，用于查看标题、描述、分支和 PR 的高级元数据。
4. 仅当规范化摘要不足以支撑判断时，才查看 pr-diff.json 或原始评论输出。

默认不要加载所有产物。先从 summary.json 开始，仅在某项发现需要更多依据时再深入查看。

3. 阅读本地代码

不要只依据差异进行审查。

使用 references/deep-review-checklist.md 作为深度、停止条件和针对特定风险的审查提示的必备清单。

完成前，为每个变更文件指定且仅指定一种审查状态：

• reviewed：已深入检查文件及其相关上下文，足以支持审查结论或确认未发现问题
• mechanical-low-risk：依据清单核验后，可以证明该变更属于机械式且低风险的修改
• skipped-with-reason：未深入审查该文件，并明确说明原因和剩余风险

不要发现一两个问题后就停止。持续审查，直到每个变更文件都具有上述一种状态。

对于每个重要的变更文件：

• 阅读变更的代码块。
• 阅读当前仓库中的相关本地代码。
• 根据需要追踪导入项、辅助函数、测试和调用方，以核实行为，而不只是形成初步怀疑。

最低深度要求：

• 对于生产代码变更，至少检查以下一项：直接调用方、直接被调用方或相关测试。
• 对于 API、架构、持久化、并发、权限、缓存、状态机或错误处理变更，至少检查其中两项，不能只孤立地看差异。
• 对于删除或移动的逻辑，确认其原有职责仍在适当位置实现，或调用方已相应更新。
• 对于新增分支或新的失败路径，确认测试是否覆盖成功路径和新分支；若无法核实，请说明原因。

优先关注：

• 正确性缺陷
• 行为回归
• 调用点的假设不成立
• 缺失或无效的测试
• 安全或数据处理问题

优先报告高价值问题，避免评论风格问题。

深度要求：

• 如果文件看似低风险，应通过代码上下文或测试证明，而不是凭直觉判断。
• 如果文件看似高风险，应加深检查后再决定是否存在问题。
• 如果仓库上下文不足，应将其报告为审查限制，而不是默默降低审查深度。

在判断候选问题是否成立、分配严重性，或解释未确认问题时的剩余风险时，使用 references/review-rubric.md。

4. 提交审查发现

默认输出以问题为导向，不提供宽泛总结。

每条展示给用户的发现使用以下模板：

严重性 | 路径:行号 | 问题 | 证据 | 修复方案

包括：

• 严重性：high、medium 或 low
• 路径
• 尽可能提供差异新增侧的行号
• 问题：说明哪里有问题以及为什么重要
• 证据：具体代码路径、行为或缺失的测试支持
• 修复方案：说明如何解决

如果无法提供有效的差异行号，按以下顺序处理：

1. 在文件级评论中注明 path
2. 添加一般 PR 评论

切勿编造差异行号。

如果没有发现有效问题，请明确说明，并包括：

• 每个变更文件或文件组的审查状态
• 检查过的主要代码路径、调用方、被调用方或测试
• 无法核实的清单类别
• 剩余的不确定性或测试缺口，不要用风格反馈充数

除非已完成所审查范围的文件覆盖和清单检查，否则不要声称“未发现可处理的问题”。

当所审查范围内没有确认的问题时，默认使用 references/no-finding-template.md 的输出格式。

撰写可能提交回 GitCode 的评论时：

• 除非用户明确要求使用其他语言，否则默认使用中文。
• 使用简洁的 Markdown，不要写成单句的竖线分隔格式。
• 将结论、问题分析和建议的修复方案分成简短段落或项目符号。
• 用反引号括起参数、文件和状态码等标识符。

5. 准备提交草稿

此技能采用两步提交流程。

默认行为：

• 审查 PR
• 向用户提供审查结果
• 如果用户希望提交，先创建结构化草稿

使用 references/review-draft-schema.md 获取草稿格式，并使用 scripts/prepare_review_submission.py 根据收集到的上下文验证草稿。

草稿可以包含：

• 一条 PR 总结评论
• 零条或多条包含 path 和 line 的差异评论
• 可选的批准意向

批准门槛：

• 仅当没有剩余阻塞性或高严重性问题，且用户明确希望批准时，才设置 approve: true。
• 如果审查发现阻塞性问题，只提交评论；不要调用 oh-gc pr:review。

重要提示：oh-gc pr:review 仅支持批准。它不是通用的“提交审查”接口。

提交评论时，请遵循 references/review-draft-schema.md 中的 Markdown 和中文写作规则。

6. 仅在确认后提交

切勿在未明确告知的情况下向 GitCode 提交。

当用户明确要求提交时：

1. 构建草稿 JSON
2. 运行 prepare_review_submission.py，不带 --execute，以预览命令
3. 向用户展示计划发布的确切总结和评论数量
4. 获得确认后，使用 --execute 运行相同的命令

如果执行过程中失败，请准确报告哪些评论已成功发布，哪些未成功。

快速流程

阅读上述工作流后，仅将以下命令作为简要提醒。

python3 skills/review-gitcode-pr/scripts/collect_pr_context.py 123

主要审查产物：

• summary.json
• pr-diff.txt
• pr-view.json

深度审查提醒：

1. 阅读 summary.json
2. 使用 references/deep-review-checklist.md 按风险对每个变更文件进行分类
3. 审查每个文件，直至其状态最终确定
4. 仅在此之后判断审查是否没有发现任何问题

预览提交草稿：

python3 skills/review-gitcode-pr/scripts/prepare_review_submission.py \
  --context-dir .review-gitcode-pr/pr-123 \
  --draft review-draft.json

仅在用户明确确认后执行：

python3 skills/review-gitcode-pr/scripts/prepare_review_submission.py \
  --context-dir .review-gitcode-pr/pr-123 \
  --draft review-draft.json \
  --execute

故障处理

明确处理故障。对于每个阻碍事项，请报告：

• Blocker：失败的内容，以及失败的命令或假设
• Fallback：仍可进行的审查范围
• Next step：用户或 Agent 接下来应采取的操作

oh-gc 不可用

• Blocker：oh-gc 未安装在 PATH 中，或无法执行。
• Fallback：不要尝试获取 GitCode 内容或提交。只有在本地已存在先前收集的产物目录，且其足以支持不提交的审查时，才继续。
• Next step：请用户安装或公开 oh-gc，或者提供现有产物，以便离线审查。

身份验证或权限失败

• Blocker：oh-gc 在查看 PR、差异或评论时返回身份验证、授权或 API 权限错误。
• Fallback：保留已收集的任何部分产物。仅当成功获取的差异和上下文足以支持不提交的审查时，才继续。不要尝试提交。
• Next step：告知用户失败的命令，并说明他们需要重新进行身份验证或获取访问权限，之后才能继续远程审查或提交。

本地仓库不匹配

• Blocker：当前仓库与 PR 仓库、分支布局或文件集不够匹配，无法通过本地代码验证行为。
• Fallback：不要声称仅通过检查差异就对代码有充分把握。如果用户仍希望继续，最多提供明确标注为仅基于差异的有限审查。
• Next step：请用户切换到匹配的仓库检出版本，或提供正确的本地工作区，然后再继续完整审查。

Diff JSON 缺失、格式错误或不完整

• 阻碍：pr:diff --json 的结构发生变化、缺少代码块，或无法可靠解析到足以进行结构化行映射。
• 回退方案：使用 pr-diff.txt 作为差异分析的事实来源。只有在仍能从原始差异文本中有把握地验证新侧行号时，才生成行内评论；否则改为文件级或通用评论。
• 后续步骤：告知用户，结构化差异解析已降级，且在修复 JSON 格式之前，提交精度可能会降低。

提交预览或执行失败

• 阻碍：prepare_review_submission.py 验证失败，预览命令与草稿不匹配，或部分评论的 --execute 执行失败。
• 回退方案：保留已验证的草稿和任何已成功提交的部分结果。不要在不说明的情况下更改语义并重试。
• 后续步骤：报告确切失败的评论或命令、已发布的评论，以及重试前必须修正的内容。