pr-review-comments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Review Comments

PR评审评论

Publish a JSON array of review findings as inline comments on a GitHub Pull Request, each anchored to its file and line. Uses the GitHub API through the authenticated

gh

CLI, so no token handling is needed.

将JSON格式的评审结果数组作为内联评论发布到GitHub拉取请求（Pull Request）中，每条评论锚定到对应的文件和行号。通过已认证的

gh

CLI调用GitHub API，无需手动处理令牌。

Prerequisites

前提条件

```
gh
```
CLI installed and authenticated (
```
gh auth status
```
). The script auto-detects the repo with
```
gh repo view
```
; pass
```
--repo OWNER/REPO
```
to override.
The PR number to comment on.
A JSON file: an array of objects. Required keys per object:
```
file
```
,
```
line
```
. Message comes from
```
summary
```
and/or
```
failure_scenario
```
(combined into the body), or an explicit
```
body
```
. See references/json-schema.md for the full schema and a sample.

已安装并认证
```
gh
```
CLI（可通过
```
gh auth status
```
检查）。脚本会通过
```
gh repo view
```
自动检测仓库；可传入
```
--repo OWNER/REPO
```
来覆盖自动检测结果。
要添加评论的PR编号。
一个JSON文件：格式为对象数组。每个对象必须包含
```
file
```
、
```
line
```
键。评论内容来自
```
summary
```
和/或
```
failure_scenario
```
（合并为评论正文），或显式指定的
```
body
```
。完整的Schema和示例可查看references/json-schema.md。

Key constraint: only diff lines are commentable

关键限制：仅差异行可添加评论

GitHub only accepts an inline comment if the target line is part of the PR's diff.

line

is the line number in the new file (use

side: "LEFT"

for removed lines). The script fetches the PR diff, validates every finding against the actual hunks, and skips any whose line is outside the diff — reporting them at the end so nothing is lost silently. There is no way to attach a line comment to an unchanged, undiffed line.

GitHub仅接受针对PR差异中包含的行的内联评论。

line

指的是新文件中的行号（若针对已删除的行，需使用

side: "LEFT"

）。脚本会获取PR的差异内容，验证每条评审结果是否对应实际的差异块，跳过所有不在差异范围内的结果——并在最后报告这些结果，避免内容无声丢失。无法为未变更、未出现在差异中的行添加行内评论。

Workflow

工作流程

Confirm the JSON path and the PR number. If the repo isn't obvious, run
```
gh repo view
```
.
Dry-run first to see what will be posted and what gets skipped:
bash
```
scripts/post_pr_comments.py --pr <N> --json <path> --dry-run
```
Review the "Postable" / "Skipped" counts with the user. If lines were skipped because the diff moved, the line numbers in the JSON may be stale — reconcile before posting.

Post for real, choosing the mode (see below):

bash

# Grouped (default): one PR review bundling all comments
scripts/post_pr_comments.py --pr <N> --json <path> --event COMMENT

# Individual: one separate inline comment per finding
scripts/post_pr_comments.py --pr <N> --json <path> --mode individual

Report back the created review/comment URLs and the list of any skipped findings.

确认JSON文件路径和PR编号。若仓库不明确，可运行
```
gh repo view
```
查看。
先执行试运行，查看将发布的内容和会被跳过的结果：
bash
```
scripts/post_pr_comments.py --pr <N> --json <path> --dry-run
```
与用户核对“可发布”/“已跳过”的数量。若因差异变动导致行号被跳过，JSON中的行号可能已过时——发布前需先调整一致。

正式发布，选择合适的模式（见下文）：

bash

# 分组模式（默认）：将所有评论打包为一个PR评审
scripts/post_pr_comments.py --pr <N> --json <path> --event COMMENT

# 独立模式：每条评审结果对应一条单独的内联评论
scripts/post_pr_comments.py --pr <N> --json <path> --mode individual

返回已创建的评审/评论URL，以及所有被跳过的结果列表。

Choosing the mode

模式选择

Mode	Endpoint	Use when
`grouped` (default)	`POST /pulls/{n}/reviews`	Publishing a set of findings as one review. One notification; can set `--event APPROVE \| REQUEST_CHANGES \| COMMENT` .
`individual`	`POST /pulls/{n}/comments`	Adding standalone comments incrementally, or when each finding should be its own thread/notification.

Default to

grouped

with

--event COMMENT

unless the user wants a verdict or separate threads.

模式	接口	使用场景
`grouped` （默认）	`POST /pulls/{n}/reviews`	将一组评审结果作为一个评审发布。仅发送一次通知；可设置 `--event APPROVE \| REQUEST_CHANGES \| COMMENT` 。
`individual`	`POST /pulls/{n}/comments`	增量添加独立评论，或当每条评审结果需要单独的讨论线程/通知时使用。

除非用户需要给出评审结论或单独的讨论线程，否则默认使用

grouped

模式并搭配

--event COMMENT

。

Options reference

选项参考

--pr N              PR number (required)
--json PATH         JSON array of findings (required)
--repo OWNER/REPO   Override auto-detected repo
--mode grouped|individual   Default: grouped
--event COMMENT|APPROVE|REQUEST_CHANGES   Grouped-mode verdict (default COMMENT)
--review-body TEXT  Top-level summary body for the grouped review
--commit SHA        Commit to anchor to (default: PR head SHA)
--dry-run           Validate and print payloads without posting

--pr N              PR编号（必填）
--json PATH         评审结果的JSON数组（必填）
--repo OWNER/REPO   覆盖自动检测的仓库
--mode grouped|individual   默认值：grouped
--event COMMENT|APPROVE|REQUEST_CHANGES   分组模式下的评审结论（默认值COMMENT）
--review-body TEXT  分组评审的顶部摘要正文
--commit SHA        锚定的提交哈希（默认值：PR头部提交的SHA）
--dry-run           验证并打印请求内容，但不实际发布

Notes

注意事项

Multi-line range comments: include
```
start_line
```
(and optional
```
start_side
```
) in the JSON object alongside
```
line
```
; the script passes them through.
Always
```
--dry-run
```
before a real post on an unfamiliar PR — stale line numbers are the most common failure and the dry-run surfaces them as "skipped" without side effects.
The script is the reliable path; don't hand-roll
```
gh api
```
calls for this — it handles diff validation, repo/commit detection, and body assembly consistently.

多行范围评论：在JSON对象中除
```
line
```
外，还需包含
```
start_line
```
（可选
```
start_side
```
）；脚本会直接传递这些参数。
在不熟悉的PR上正式发布前，务必先执行
```
--dry-run
```
——过时的行号是最常见的问题，试运行会将这些问题标记为“已跳过”且不会产生任何副作用。
该脚本是可靠的实现方式；请勿手动编写
```
gh api
```
调用来完成此操作——它能一致地处理差异验证、仓库/提交检测以及正文组装。