review-gitcode-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review GitCode PR

审查 GitCode PR

Run this skill when the review starts from a GitCode PR reference and must combine

oh-gc

artifacts with local repository inspection.

当审查从 GitCode PR 引用开始，且必须结合

oh-gc

产物与本地仓库检查时，运行此 skill。

Workflow

工作流

1. Resolve The PR

1. 解析 PR

Normalize the user input first.

If the user gave a PR number, use it directly.
If the user gave a URL, extract the PR number and, when possible, the
```
OWNER/REPO
```
.
If the normalized result does not include
```
OWNER/REPO
```
,
```
scripts/collect_pr_context.py
```
will try to infer it from the current repository's GitCode remote URLs.
If remote inference is ambiguous or the current checkout is not a GitCode clone, pass
```
--repo OWNER/REPO
```
explicitly.
Use
```
scripts/normalize_pr_ref.py
```
for this normalization step.

首先规范化用户输入。

如果用户提供了 PR 编号，直接使用。
如果用户提供了 URL，提取 PR 编号，并在可能的情况下提取
```
OWNER/REPO
```
。
如果规范化结果不包含
```
OWNER/REPO
```
，
```
scripts/collect_pr_context.py
```
将尝试根据当前仓库的 GitCode remote URL 推断。
如果 remote 推断存在歧义，或当前 checkout 不是 GitCode clone，请显式传入
```
--repo OWNER/REPO
```
。
使用
```
scripts/normalize_pr_ref.py
```
完成此规范化步骤。

2. Collect Remote Context

2. 收集远程上下文

Use

scripts/collect_pr_context.py

to fetch and save the PR context before reviewing code manually.

The script gathers:

```
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

Review the generated artifact directory before making claims. Read artifacts in this order:

```
summary.json
```
to identify changed files, parsed hunks, commentable new-side lines, and existing normalized context.
```
pr-diff.txt
```
to verify exact diff text and hunk boundaries for any candidate finding.
```
pr-view.json
```
for title, description, branch, and high-level PR metadata.
```
pr-diff.json
```
or raw comments output only when the normalized summary is insufficient.

Do not load every artifact by default. Start from

summary.json

and only drill down when a finding needs more evidence.

使用

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

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

```
summary.json
```
：识别变更文件、已解析的 hunk、可评论的 new-side 行以及现有的规范化上下文。
```
pr-diff.txt
```
：验证候选发现对应的准确 diff 文本和 hunk 边界。
```
pr-view.json
```
：获取标题、描述、分支和高层 PR 元数据。
仅当规范化摘要不足以提供所需信息时，才读取
```
pr-diff.json
```
或原始评论输出。

默认不要加载每个产物。先从

summary.json

开始，仅在发现需要更多证据时再深入检查。

3. Read Local Code

3. 阅读本地代码

Do not review from the diff alone.

Use

references/deep-review-checklist.md

as the required checklist for depth, stopping conditions, and risk-specific review prompts.

For every changed file, assign exactly one review status before finishing:

```
reviewed
```
: the file and its relevant context were inspected deeply enough to support findings or a no-finding conclusion
```
mechanical-low-risk
```
: the change is demonstrably mechanical and low-risk after verification against the checklist
```
skipped-with-reason
```
: the file was not reviewed in depth, and the reason and residual risk are stated explicitly

Do not stop after finding one or two issues. Keep reviewing until every changed file has one of the statuses above.

For each changed file that matters:

Read the changed hunk.
Read surrounding local code in the current repository.
Follow imports, helpers, tests, and callers as far as needed to verify behavior, not just to form an initial suspicion.

Minimum depth rules:

For production code changes, inspect at least one of: direct callers, direct callees, or related tests.
For API, schema, persistence, concurrency, permission, cache, state-machine, or error-handling changes, inspect at least two of those areas and do not treat the diff in isolation as sufficient.
For deleted or moved logic, verify that the previous responsibility still exists somewhere valid or that callers were updated accordingly.
For new branches or new failure paths, verify whether tests cover both the success path and the new branch or explain why that verification was not possible.

Prioritize:

Correctness bugs
Behavior regressions
Broken assumptions at call sites
Missing or invalid tests
Security or data handling issues

Prefer high-signal findings over style commentary.

Depth expectations:

If a file appears low-risk, prove that with code context or tests instead of intuition.
If a file appears high-risk, increase inspection depth before deciding there is no finding.
If the repository context is insufficient, report that as a review limitation instead of silently reducing depth.

Use

references/review-rubric.md

when deciding whether a candidate issue is a real finding, assigning severity, or explaining residual risk when no findings are confirmed.

不要仅依据 diff 进行审查。

使用

references/deep-review-checklist.md

作为审查深度、停止条件和风险特定审查提示的必需 checklist。

结束前，为每个变更文件分配且仅分配一个审查状态：

```
reviewed
```
：已对文件及其相关上下文进行足够深入的检查，能够支持审查发现或无发现结论。
```
mechanical-low-risk
```
：根据 checklist 验证后，可以明确证明该变更是机械性且低风险的。
```
skipped-with-reason
```
：未对该文件进行深入审查，并且已明确说明原因和剩余风险。

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

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

阅读变更的 hunk。
阅读当前仓库中周围的本地代码。
根据需要跟进 imports、helpers、tests 和 callers，以验证行为，而不只是形成初步怀疑。

最低审查深度规则：

对于 production code 变更，至少检查 direct callers、direct callees 或 related tests 中的一项。
对于 API、schema、persistence、concurrency、permission、cache、state machine 或 error handling 变更，至少检查上述两个领域，并且不得将 diff 孤立看待就认为已充分。
对于删除或移动的逻辑，验证原有职责是否仍存在于某个有效位置，或者 callers 是否已相应更新。
对于新分支或新的 failure path，验证 tests 是否覆盖成功路径和新分支，或者解释为何无法进行这种验证。

优先检查：

正确性缺陷
行为回归
调用点处被破坏的假设
缺失或无效的 tests
安全性或数据处理问题

优先提供高信号发现，而不是风格评论。

审查深度要求：

如果某个文件看起来风险较低，应通过代码上下文或 tests 证明这一点，而不是凭直觉判断。
如果某个文件看起来风险较高，应在决定没有发现之前加大审查深度。
如果仓库上下文不足，应将其作为审查限制报告出来，而不是在未说明的情况下降低审查深度。

在判断候选问题是否构成真实发现、确定严重程度，或在没有确认发现时说明剩余风险，请使用

references/review-rubric.md

。

4. Produce Findings

4. 生成审查发现

Default output is issue-driven review, not a broad summary.

Use this template for each finding shown to the user:

Severity | Path:Line | Problem | Evidence | Fix

Include:

Severity:
```
high
```
,
```
medium
```
, or
```
low
```
Path
Best-effort line number on the new side of the diff
Problem: what is wrong and why it matters
Evidence: concrete code path, behavior, or missing test support
Fix: what change would address it

If a valid diff line cannot be supported, fall back in this order:

File-level comment with
```
path
```
General PR comment

Never invent a diff line number.

If no valid findings are discovered, state that explicitly and include:

the review status for each changed file or file group
the main code paths, callers, callees, or tests inspected
any checklist categories that could not be verified
residual uncertainty or testing gaps instead of padding with style feedback

Do not say "no actionable issues found" unless the file coverage and checklist pass were completed for the inspected scope.

Use

references/no-finding-template.md

as the default output shape when the inspected scope has no confirmed findings.

When drafting comments that may be submitted back to GitCode:

Write in Chinese by default unless the user explicitly asks for another language.
Use concise Markdown, not a single pipe-delimited sentence.
Separate conclusion, problem analysis, and suggested fix into short paragraphs or bullet points.
Wrap identifiers such as parameters, files, and status codes in backticks.

默认输出采用以问题为导向的审查，而不是宽泛的总结。

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

Severity | Path:Line | Problem | Evidence | Fix

（严重程度 | 路径:行号 | 问题 | 证据 | 修复）

包括：

Severity：
```
high
```
、
```
medium
```
或
```
low
```
Path
diff new side 上尽力确定的行号
Problem：问题是什么，以及它为什么重要。
Evidence：具体的代码路径、行为或缺失的 test 支持。
Fix：可以解决该问题的变更。

如果无法支持有效的 diff 行，请依次回退为：

带
```
path
```
的文件级评论。
PR 总体评论。

绝不要虚构 diff 行号。

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

每个变更文件或文件组的审查状态。
已检查的主要代码路径、callers、callees 或 tests。
无法验证的 checklist 类别。
剩余不确定性或测试缺口，而不是用风格反馈填充内容。

除非已完成检查范围内的文件覆盖和 checklist，否则不要声称“未发现可操作的问题”。

当检查范围中没有确认的发现时，使用

references/no-finding-template.md

作为默认输出结构。

起草可能需要提交回 GitCode 的评论时：

默认使用中文编写，除非用户明确要求使用其他语言。
使用简洁的 Markdown，不要写成单个由管道符分隔的句子。
将结论、问题分析和修复建议拆分为短段落或 bullet points。
使用反引号包裹参数、文件和状态码等 identifiers。

5. Prepare Submission Draft

5. 准备提交草稿

This skill uses a two-step submission flow.

Default behavior:

Review the PR
Produce findings for the user
If the user wants submission, create a structured draft first

Use

references/review-draft-schema.md

for the draft shape and

scripts/prepare_review_submission.py

to validate it against the collected context.

The draft may include:

One general PR summary comment
Zero or more diff comments with
```
path
```
and
```
line
```
Optional approval intent

Approval gate:

Set
```
approve: true
```
only when no blocking or high-severity findings remain and the user explicitly wants approval.
If the review contains blocking findings, submit comments only; do not call
```
oh-gc pr:review
```
.

Important:

oh-gc pr:review

only supports approval. It is not a general "submit review" endpoint.

For submitted comments, follow the Markdown and Chinese-writing rules in

references/review-draft-schema.md

此 skill 使用两步提交流程。

默认行为：

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

使用

references/review-draft-schema.md

定义草稿结构，并使用

scripts/prepare_review_submission.py

根据收集到的上下文验证草稿。

草稿可以包括：

一条 PR 总体摘要评论。
零条或多条带有
```
path
```
和
```
line
```
的 diff 评论。
可选的 approval intent。

Approval gate：

仅当没有剩余的 blocking 或 high-severity findings，并且用户明确希望 approval 时，才设置
```
approve: true
```
。
如果审查包含 blocking findings，则仅提交评论；不要调用
```
oh-gc pr:review
```
。

重要提示：

oh-gc pr:review

仅支持 approval。它不是通用的“提交审查” endpoint。

对于已提交的评论，请遵循

references/review-draft-schema.md

中的 Markdown 和中文编写规则。

6. Submit Only After Confirmation

6. 仅在确认后提交

Never submit to GitCode implicitly.

When the user explicitly asks to submit:

Build the draft JSON
Run
```
prepare_review_submission.py
```
without
```
--execute
```
to preview commands
Show the user the exact summary and comment count you plan to post
After confirmation, run the same command with
```
--execute
```

If execution fails partway through, report exactly which comments succeeded and which did not.

绝不要未经明确指示就提交到 GitCode。

当用户明确要求提交时：

构建草稿 JSON。
运行
```
prepare_review_submission.py
```
，但不要添加
```
--execute
```
，以预览命令。
向用户展示计划发布的准确摘要和评论数量。
获得确认后，运行同一命令并添加
```
--execute
```
。

如果执行到一半失败，请准确报告哪些评论已成功提交、哪些未成功提交。

Quick Flow

快速流程

Use these commands only as a compact reminder after reading the workflow above.

bash

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

Primary review artifacts:

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

Depth reminder:

Read
```
summary.json
```
Classify each changed file by risk using
```
references/deep-review-checklist.md
```
Review every file until it has a final status
Only then decide whether the review has zero findings

Preview a draft submission:

bash

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

Execute only after explicit user confirmation:

bash

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

阅读上述工作流后，仅将这些命令用作简短提醒。

bash

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

主要审查产物：

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

审查深度提醒：

读取
```
summary.json
```
。
使用
```
references/deep-review-checklist.md
```
按风险对每个变更文件进行分类。
审查每个文件，直至其获得最终状态。
只有完成上述步骤后，才能判断审查是否为零发现。

预览草稿提交：

bash

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

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

bash

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

Failure Handling

失败处理

Handle failures explicitly. For each blocker, report:

```
Blocker
```
: what failed and which command or assumption failed
```
Fallback
```
: what review scope remains possible
```
Next step
```
: what the user or agent should do next

显式处理失败。对于每个 blocker，请报告：

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

oh-gc

unavailable

oh-gc

不可用

Blocker:
```
oh-gc
```
is missing from
```
PATH
```
or cannot be executed.
Fallback: do not attempt GitCode fetch or submission. Only continue if a previously collected artifact directory already exists locally and is sufficient for a non-submitting review.
Next step: ask the user to install or expose
```
oh-gc
```
, or point to existing artifacts to review offline.

```
Blocker
```
：
```
oh-gc
```
不在
```
PATH
```
中或无法执行。
```
Fallback
```
：不要尝试获取或提交 GitCode 数据。仅当本地已存在先前收集的产物目录，且其内容足以完成不提交的审查时，才可继续。
```
Next step
```
：请用户安装
```
oh-gc
```
或将其暴露到可执行路径，或者指向已有产物以进行离线审查。

Authentication or permission failure

Authentication 或权限失败

Blocker:
```
oh-gc
```
returns authentication, authorization, or API permission errors for PR view, diff, or comments.
Fallback: keep any partial artifacts already collected. Continue only with successfully fetched diff/context that is sufficient for a non-submitting review. Do not attempt submission.
Next step: tell the user which command failed and that they need to re-authenticate or obtain access before remote review or submission can continue.

```
Blocker
```
：
```
oh-gc
```
在查看 PR、diff 或评论时返回 authentication、authorization 或 API permission 错误。
```
Fallback
```
：保留已经收集的部分产物。仅当成功获取的 diff/context 足以完成不提交的审查时才可继续。不要尝试提交。
```
Next step
```
：告知用户哪个命令失败，以及在继续远程审查或提交前需要重新进行身份验证或获得访问权限。

Local repository mismatch

本地仓库不匹配

Blocker: the current repository does not match the PR repository, branch layout, or file set closely enough to verify behavior in local code.
Fallback: do not claim code-level confidence from diff-only inspection. At most, provide a limited review explicitly labeled as diff-only if the user still wants that.
Next step: ask the user to switch to the matching repository checkout or provide the correct local workspace before continuing with a full review.

```
Blocker
```
：当前仓库与 PR 仓库、分支布局或文件集不够匹配，无法验证本地代码中的行为。
```
Fallback
```
：不要声称仅凭 diff 检查即可获得代码层面的信心。最多在用户仍需要时，提供明确标注为 diff-only 的有限审查。
```
Next step
```
：请用户切换到匹配的仓库 checkout，或提供正确的本地工作区，然后继续完整审查。

Diff JSON missing, malformed, or incomplete

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

Blocker:
```
pr:diff --json
```
changes shape, omits hunks, or cannot be parsed reliably enough for structured line mapping.
Fallback: use
```
pr-diff.txt
```
as the source of truth for diff reasoning. Only emit line comments when a new-side line can still be verified confidently from raw diff text; otherwise fall back to file-level or general comments.
Next step: tell the user that structured diff parsing degraded and that submission precision may be reduced until the JSON format is fixed.

```
Blocker
```
：
```
pr:diff --json
```
的结构发生变化、遗漏 hunk，或无法可靠解析以进行结构化行映射。
```
Fallback
```
：使用
```
pr-diff.txt
```
作为 diff 推理的事实来源。仅当仍能从原始 diff 文本中可靠确认 new-side 行时，才输出行评论；否则回退为文件级评论或总体评论。
```
Next step
```
：告知用户结构化 diff 解析能力已经降级，并且在 JSON 格式修复前，提交精度可能会降低。

Submission preview or execute failure

提交预览或执行失败

Blocker:
```
prepare_review_submission.py
```
validation fails, preview commands do not match the draft, or
```
--execute
```
fails for some comments.
Fallback: keep the validated draft and any successful partial submission results. Do not silently retry with changed semantics.
Next step: report the exact failed comment or command, which comments were already posted, and what must be corrected before retrying.

```
Blocker
```
：
```
prepare_review_submission.py
```
验证失败、预览命令与草稿不匹配，或
```
--execute
```
在提交部分评论时失败。
```
Fallback
```
：保留已验证的草稿和已成功提交的部分结果。不要在未说明的情况下使用改变语义的方式静默重试。
```
Next step
```
：准确报告失败的具体评论或命令、已经发布的评论，以及重试前需要修正的内容。

review-gitcode-pr

Original

Translation

Review GitCode PR

审查 GitCode PR

Workflow

工作流

1. Resolve The PR

1. 解析 PR

2. Collect Remote Context

2. 收集远程上下文

3. Read Local Code

3. 阅读本地代码

4. Produce Findings

4. 生成审查发现

5. Prepare Submission Draft

5. 准备提交草稿

6. Submit Only After Confirmation

6. 仅在确认后提交

Quick Flow

快速流程

Failure Handling

失败处理

`oh-gc`
unavailable

`oh-gc`
不可用

Authentication or permission failure

Authentication 或权限失败

Local repository mismatch

本地仓库不匹配

Diff JSON missing, malformed, or incomplete

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

Submission preview or execute failure

提交预览或执行失败