arinhub-submit-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Submit Code Review

提交代码评审

Submit a structured code review with line-specific comments to a GitHub pull request. Identifies issues in the current chat session or review file, checks for duplicate comments, and submits the review.

向GitHub拉取请求（pull request）提交带有行级特定注释的结构化代码评审。识别当前聊天会话或评审文件中的问题，检查重复注释，然后提交评审。

Input

输入

PR number or URL (required): The pull request identifier. Accepts:
- Number:
```
123
```
- Hash-prefixed:
```
#123
```
- Full URL:
```
https://github.com/owner/repo/pull/123
```
Review file path (optional): Path to a review file produced by
```
arinhub-code-reviewer
```
(e.g.,
```
~/.agents/arinhub/code-reviews/pr-code-review-my-app-123.md
```
). If provided, issues are extracted from this file instead of the current chat session.

PR编号或URL（必填）：拉取请求的标识符。支持：
- 编号：
```
123
```
- 带#前缀：
```
#123
```
- 完整URL：
```
https://github.com/owner/repo/pull/123
```
评审文件路径（可选）：由
```
arinhub-code-reviewer
```
生成的评审文件路径（例如
```
~/.agents/arinhub/code-reviews/pr-code-review-my-app-123.md
```
）。如果提供此参数，将从该文件中提取问题，而非当前聊天会话。

Procedure

流程

1. Resolve PR Identifier

1. 解析PR标识符

Extract the PR number from the user input. Strip any

prefix or parse the number from a URL.

PR_NUMBER=<extracted number>

从用户输入中提取PR编号。去除

前缀或从URL中解析编号。

PR_NUMBER=<extracted number>

2. Fetch PR Metadata

2. 获取PR元数据

Gather PR details:

bash

gh pr view $PR_NUMBER --json number,title,body,baseRefName,headRefName,files,url

收集PR详细信息：

bash

gh pr view $PR_NUMBER --json number,title,body,baseRefName,headRefName,files,url

3. Fetch Existing Review Comments

3. 获取现有评审注释

Retrieve all existing review comments to prevent duplication:

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --paginate --jq '.[] | {id, path, line, body, user: .user.login}'

Also fetch top-level review bodies:

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews --paginate --jq '.[] | {id, body, state, user: .user.login}'

检索所有现有评审注释以避免重复：

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --paginate --jq '.[] | {id, path, line, body, user: .user.login}'

同时获取顶级评审内容：

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews --paginate --jq '.[] | {id, body, state, user: .user.login}'

4. Get Issue List

4. 获取问题列表

Get a list of issues from one of these sources (in priority order):

Review file: If a review file path is provided (e.g., from
```
arinhub-code-reviewer
```
orchestrator), read the file and extract all issues from the
```
## Issues
```
section.
Current chat session: If no review file is specified, collect issues identified during the code review in the current chat session.

For each issue found, record:

```
path
```
: The relative file path
```
line
```
: The specific line number in the new version of the file (must be within the diff hunk). For multi-line issues, this is the last line of the range.
```
start_line
```
(optional): The first line of a multi-line range. Only set when the issue spans more than one line.
```
body
```
: A concise, actionable comment explaining the issue
```
suggestion
```
(optional): The replacement code that should replace the line(s) from
```
start_line
```
(or
```
line
```
) through
```
line
```
. Include this whenever you can propose a concrete fix. The suggestion content is the exact code that will replace the selected lines -- do not include
```
```suggestion
```
fences here, they are added automatically in Step 7.

从以下来源之一获取问题列表（按优先级排序）：

评审文件：如果提供了评审文件路径（例如来自
```
arinhub-code-reviewer
```
编排器），读取文件并从
```
## Issues
```
部分提取所有问题。
当前聊天会话：如果未指定评审文件，收集当前聊天会话中代码评审过程中识别的问题。

对于每个找到的问题，记录：

```
path
```
：相对文件路径
```
line
```
：文件新版本中的特定行号（必须在差异块范围内）。对于多行问题，这是范围的最后一行。
```
start_line
```
（可选）：多行范围的第一行。仅当问题跨越多行时设置。
```
body
```
：简洁、可操作的问题说明注释
```
suggestion
```
（可选）：应替换从
```
start_line
```
（或
```
line
```
）到
```
line
```
的代码。只要能提出具体修复方案就包含此内容。建议内容是将替换选定行的精确代码——此处不要包含
```
```suggestion
```
标记，它们会在步骤7中自动添加。

5. Deduplicate Comments

5. 去重注释

For each issue identified in Step 4, compare against existing comments from Step 3:

Skip if an existing comment on the same
```
path
```
and
```
line
```
(or nearby range +/- 3 lines) already addresses the same concern
Skip if the issue is already mentioned in any top-level review body
Use semantic comparison, not exact string matching -- if the existing comment covers the same problem, even with different wording, skip the new comment

对于步骤4中识别的每个问题，与步骤3中的现有注释进行比较：

如果同一
```
path
```
和
```
line
```
（或附近±3行范围）的现有注释已解决相同问题，则跳过
如果问题已在任何顶级评审内容中提及，则跳过
使用语义比较，而非精确字符串匹配——如果现有注释涵盖相同问题，即使措辞不同，也跳过新注释

6. Decision Gate

6. 决策节点

If no new issues remain after deduplication: Do not submit a review. Inform the user that no new issues were found beyond existing review comments.
If new issues exist: Proceed to Step 7.

去重后无新问题：不要提交评审。告知用户除现有评审注释外未发现新问题。
存在新问题：继续执行步骤7。

7. Submit the Review

7. 提交评审

Submit a single review via the GitHub API. The review consists of one main comment (

body

) with individual inline comments (

comments

) that appear as conversation threads anchored to specific lines in the diff.

Preflight validation checklist (run before submission):

Validate JSON payload before sending (e.g., pipe the heredoc through
```
jq . >/dev/null
```
to check syntax)
Ensure each comment has valid
```
path
```
,
```
line
```
, and
```
side: "RIGHT"
```
For multi-line comments, include
```
start_line
```
and
```
start_side: "RIGHT"
```
together with
```
line
```
Confirm
```
line
```
(and
```
start_line
```
for ranges) is inside the PR diff hunk for that file
If a suggestion is included, append it in
```
body
```
using
```
```suggestion
```
fences (do not pre-wrap suggestion content in fences earlier)
Ensure suggestion replacement code preserves indentation and exact intended final content
Use an empty suggestion block (
```
```suggestion\n```
```
) only when the intent is to delete selected lines

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews \
  --method POST \
  --input - <<'EOF'
{
  "event": "APPROVE or COMMENT",
  "body": "<main-review-comment>",
  "comments": [
    {
      "path": "<file-path>",
      "line": <line-number>,
      "side": "RIGHT",
      "body": "<thread-comment>\n\n```suggestion\n<replacement-code>\n```"
    }
  ]
}
EOF

For multi-line suggestions, add

start_line

and

start_side

json

{
  "path": "<file-path>",
  "start_line": <first-line>,
  "line": <last-line>,
  "start_side": "RIGHT",
  "side": "RIGHT",
  "body": "<thread-comment>\n\n```suggestion\n<replacement-code>\n```"
}

If a comment has no suggestion (pure observation), omit the

```suggestion ```

block from the body. Still include

"side": "RIGHT"

so that all comments are anchored to the new version of the file.

Main review comment (

body

): See main-review-comment.md for the full template and examples.

Thread comments (

comments[].body

): See thread-comment.md for the full template and examples.

通过GitHub API提交单个评审。评审包含一个主注释(

body

)和多个行内注释(

comments

)，这些行内注释会作为对话线程锚定到差异中的特定行。

提交前验证清单（提交前运行）：

发送前验证JSON负载（例如通过
```
jq . >/dev/null
```
检查语法）
确保每个注释都有有效的
```
path
```
、
```
line
```
和
```
side: "RIGHT"
```
对于多行注释，将
```
start_line
```
和
```
start_side: "RIGHT"
```
与
```
line
```
一起包含
确认
```
line
```
（以及多行范围的
```
start_line
```
）在该文件的PR差异块内
如果包含建议，在
```
body
```
中使用
```
```suggestion
```
标记包裹（不要提前在建议内容外添加标记）
确保建议替换代码保留缩进和预期的最终内容
仅当意图是删除选定行时，使用空建议块(
```
```suggestion\n```
```
)

bash

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews \
  --method POST \
  --input - <<'EOF'
{
  "event": "APPROVE or COMMENT",
  "body": "<main-review-comment>",
  "comments": [
    {
      "path": "<file-path>",
      "line": <line-number>,
      "side": "RIGHT",
      "body": "<thread-comment>\n\n```suggestion\n<replacement-code>\n```"
    }
  ]
}
EOF

对于多行建议，添加

start_line

和

start_side

：

json

{
  "path": "<file-path>",
  "start_line": <first-line>,
  "line": <last-line>,
  "start_side": "RIGHT",
  "side": "RIGHT",
  "body": "<thread-comment>\n\n```suggestion\n<replacement-code>\n```"
}

如果注释没有建议（仅观察），从body中省略

```suggestion ```

块。仍需包含

"side": "RIGHT"

，以便所有注释都锚定到文件的新版本。

主评审注释(

body

)：完整模板和示例请参见main-review-comment.md。

线程注释(

comments[].body

)：完整模板和示例请参见thread-comment.md。

8. Report Result

8. 报告结果

After submission, confirm to the user:

Number of review comments submitted
The PR URL for reference
Brief list of issues flagged

If no review was submitted (Step 6), explain that no new issues were found beyond existing review comments.

提交后，向用户确认：

提交的评审注释数量
供参考的PR URL
标记的问题简要列表

如果未提交评审（步骤6），说明除现有评审注释外未发现新问题。

9. Extract Requirements Coverage

9. 提取需求覆盖情况

Look for a Requirements Coverage section in the same source used in Step 4:

Review file: If a review file was used, look for a
```
## Requirements Coverage
```
section and extract its full content.
Current chat session: If no review file was used, look for any Requirements Coverage report or coverage summary produced during the current chat session.

If no Requirements Coverage is found, skip to the end -- this step is optional.

在步骤4使用的同一来源中查找需求覆盖部分：

评审文件：如果使用了评审文件，查找
```
## Requirements Coverage
```
部分并提取其全部内容。
当前聊天会话：如果未使用评审文件，查找当前聊天会话中生成的任何需求覆盖报告或覆盖摘要。

如果未找到需求覆盖情况，直接结束——此步骤为可选。

10. Post Requirements Coverage Comment

10. 发布需求覆盖注释

This step runs only if Requirements Coverage was found in Step 9. It must be the very last action -- execute it after all other steps (including the review submission and result report) are complete.

Post the coverage report as a standalone PR comment:

bash

gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
<coverage-content>
EOF
)"

Use the Requirements Coverage content exactly as found -- do not modify, summarize, or reformat it
This comment is independent of the review; post it even if no review was submitted in Step 6
This must be the very last API call in the entire procedure to ensure the coverage comment appears at the bottom of the PR conversation

仅当步骤9中找到需求覆盖情况时才执行此步骤。这必须是最后一个操作——在完成所有其他步骤（包括评审提交和结果报告）后执行。

将覆盖报告作为独立的PR注释发布：

bash

gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
<coverage-content>
EOF
)"

完全按原样使用需求覆盖内容——不要修改、总结或重新格式化
此注释独立于评审；即使步骤6中未提交评审，也要发布此注释
这必须是整个流程中的最后一个API调用，以确保覆盖注释显示在PR对话的底部

Important Notes

重要说明

Use
```
APPROVE
```
when no High Priority issues are found, otherwise use
```
COMMENT
```
. Never use
```
REQUEST_CHANGES
```
unless the user explicitly asks
The
```
line
```
field in review comments must reference a line that appears in the diff -- comments on unchanged lines will be rejected by the API
For multi-line suggestions, use
```
start_line
```
and
```
line
```
together to define the range being replaced; both must be within the diff hunk
An empty suggestion block (
```
```suggestion\n```
```
) means "delete these lines"
The content inside
```
```suggestion ```
```
replaces the selected line(s) verbatim -- ensure correct indentation and formatting
Never fabricate issues -- only flag genuine concerns backed by evidence in the code

当未发现高优先级问题时使用
```
APPROVE
```
，否则使用
```
COMMENT
```
。除非用户明确要求，否则永远不要使用
```
REQUEST_CHANGES
```
评审注释中的
```
line
```
字段必须引用差异中出现的行——对未更改行的注释会被API拒绝
对于多行建议，同时使用
```
start_line
```
和
```
line
```
定义要替换的范围；两者都必须在差异块内
空建议块(
```
```suggestion\n```
```
)表示“删除这些行”
```
```suggestion ```
```
内的内容会逐字替换选定行——确保缩进和格式正确
不要编造问题——仅标记有代码证据支持的真实问题