gh-pr-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gh Pr Review

Overview

概述

Generate an owner-grade PR review that is strict about correctness and safety, gentle with contributors, and scoped to the PR’s diff. Produce

review-<pr>.md

(Chinese narrative + English comment snippets ready to paste into GitHub).

生成所有者级别的PR审核报告，严格关注正确性与安全性，对贡献者保持友好，且仅针对PR的差异内容。输出文件为

review-<pr>.md

（中文叙述内容 + 可直接复制粘贴到GitHub的英文评论片段）。

Hard Gates (Stop Early)

硬性检查（提前终止条件）

If
```
gh
```
is missing: stop and tell the user to install/configure it.
If
```
gh auth status
```
fails or repo access is missing: stop and ask the user to fix auth/permissions.

若未安装
```
gh
```
：终止操作并告知用户需安装/配置
```
gh
```
。
若
```
gh auth status
```
验证失败或无仓库访问权限：终止操作并请用户修复认证/权限问题。

Workflow (v1.0)

工作流程（v1.0）

1) Collect PR Facts (gh-only)

1) 收集PR相关信息（仅通过gh）

Run

scripts/gh_pr_review.sh <PR_URL|PR_NUMBER>

This creates
```
.gh-pr-review/pr-<n>/
```
artifacts and a starter doc
```
review-<n>.md
```
in the current directory.

Artifacts you’ll use:

```
pr.json
```
: metadata (title, author, base/head, head SHA)
```
diff.patch
```
: unified diff
```
changed-lines.json
```
: per-file hunk + new-side line mapping
```
checks.txt
```
: checks summary
```
failed-logs.txt
```
: failed workflow logs (best-effort)

运行

scripts/gh_pr_review.sh <PR_URL|PR_NUMBER>

。

此操作会在当前目录下创建
```
.gh-pr-review/pr-<n>/
```
目录存储相关产物，并生成初始文档
```
review-<n>.md
```
。

将用到的产物：

```
pr.json
```
：元数据（标题、作者、基准/分支、分支SHA值）
```
diff.patch
```
：统一格式的差异文件
```
changed-lines.json
```
：按文件划分的代码块 + 新代码行映射
```
checks.txt
```
：CI检查摘要
```
failed-logs.txt
```
：失败的工作流日志（尽最大努力获取）

2) Understand What Module Changed (Owner Context)

2) 理解变更模块（所有者视角）

Use the file paths in
```
changed-lines.json
```
to identify the subsystem (e.g.
```
src/router/*
```
,
```
docs/*
```
,
```
tests/*
```
).
Read only the relevant code/docs around the changed hunks (enough to fully understand intent and behavior).
Do not review unrelated lines in the same file. You may mention best practices when they directly affect the changed code’s correctness, maintainability, or safety.

通过
```
changed-lines.json
```
中的文件路径识别子系统（例如
```
src/router/*
```
、
```
docs/*
```
、
```
tests/*
```
）。
仅阅读变更代码块周围的相关代码/文档（足以充分理解变更意图与行为即可）。
不要审核同一文件中无关的代码行。当最佳实践直接影响变更代码的正确性、可维护性或安全性时，可提及相关内容。

3) Check CI / Jobs and Attribute Failures

3) 检查CI/任务并定位失败原因

Read
```
checks.txt
```
and (if present)
```
failed-logs.txt
```
.
If failures are plausibly caused by the PR: point to the changed file(s)/line(s) and propose a concrete fix.
If failures are unrelated to the PR: say so explicitly and do not block merge on it.

阅读
```
checks.txt
```
及（若存在）
```
failed-logs.txt
```
。
若失败由PR变更导致：指向对应的变更文件/代码行，并提出具体修复方案。
若失败与PR变更无关：明确说明此情况，且不要以此阻止合并。

4) Apply “Current Version” Best Practices (Avoid Stale Advice)

4) 遵循“当前版本”最佳实践（避免过时建议）

Detect versions from the repo when possible (examples:
```
pyproject.toml
```
,
```
requirements*.txt
```
,
```
package.json
```
,
```
go.mod
```
,
```
Cargo.toml
```
, toolchain files).
When uncertain, prefer official docs for the exact major version in use.
Avoid recommending deprecated configs or APIs.

尽可能从仓库中检测使用的版本（例如
```
pyproject.toml
```
、
```
requirements*.txt
```
、
```
package.json
```
、
```
go.mod
```
、
```
Cargo.toml
```
、工具链文件）。
若不确定版本，优先参考对应主版本的官方文档。
避免推荐已弃用的配置或API。

5) Write the Review Document

5) 撰写审核文档

Edit
```
review-<n>.md
```
and complete the placeholders.
Narrative and rationale: Chinese.
Copy-paste GitHub comments: English, polite, actionable, and scoped to PR-introduced changes.
Default stance: accept unless there is a clear bug, security issue, unnecessary code, or meaningful regression risk.

编辑
```
review-<n>.md
```
并补全占位符内容。
叙述与理由部分：使用中文。
可复制粘贴的GitHub评论：使用英文，语气礼貌、内容可执行，且仅针对PR引入的变更。
默认立场：若无明显bug、安全问题、冗余代码或有意义的回归风险，则接受该PR。

Comment Style Guide (English, Copy-Paste Ready)

评论风格指南（英文，可直接复制粘贴）

Start with what you observed (specific line/hunk).
Explain impact (bug/risk/maintainability).
Offer a concrete fix or alternative (code-level suggestion).
Keep tone warm: assume good intent and help the contributor succeed.

开头说明观察到的内容（具体代码行/代码块）。
解释影响（bug/风险/可维护性）。
提供具体修复方案或替代方案（代码层面的建议）。
语气友好：假设贡献者初衷良好，助力其成功完成贡献。

Scripts

脚本说明

```
scripts/gh_pr_review.sh
```
: fetch PR metadata/diff/checks/logs and generate
```
review-<n>.md
```
skeleton.
```
scripts/parse_unified_diff.py
```
: map diff hunks to new-side line numbers (scope enforcement).
```
scripts/generate_review_md.py
```
: render the starter
```
review-<n>.md
```
from artifacts + template.

```
scripts/gh_pr_review.sh
```
：拉取PR元数据/差异/检查结果/日志，并生成
```
review-<n>.md
```
的初始框架。
```
scripts/parse_unified_diff.py
```
：将差异代码块映射到新代码行号（确保审核范围合规）。

scripts/generate_review_md.py

：根据产物与模板渲染初始的

review-<n>.md

。