Back to Details

reviewing-prs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Review with gh-agent

基于gh-agent的PR评审

Works from any directory — everything is fetched from GitHub API.
可在任意目录下使用——所有内容均从GitHub API获取。

Install gh-agent

安装gh-agent

bash
brew install ataraxy-labs/tap/gh-agent
Requires 
GITHUB_TOKEN
env var or GitHub CLI authenticated via 
gh auth login
.
bash
brew install ataraxy-labs/tap/gh-agent
需要配置
GITHUB_TOKEN
环境变量，或通过
gh auth login
完成GitHub CLI的身份验证。

Workflow

工作流程

1. Triage → 
gh-agent pr view --repo OWNER/REPO N --smart
Categorizes changes into MECHANICAL (skip), NEW LOGIC (read), BEHAVIORAL (verify inline).
2. Diffs → 
gh-agent pr diff --repo OWNER/REPO N --smart-files
Gets diffs for non-mechanical files only. Lock/generated/minified files excluded by default.
3. Impact analysis — after reading diffs, search for breakage outside the PR:
Identify removed/renamed exports, changed signatures, deleted types, or modified public APIs from the diff. Then search 
--repo-wide
for each:
bash
undefined
1. 分类筛选 → 
gh-agent pr view --repo OWNER/REPO N --smart
将变更分为MECHANICAL（可跳过）、NEW LOGIC（需阅读）、BEHAVIORAL（需行内验证）三类。
2. 查看差异 → 
gh-agent pr diff --repo OWNER/REPO N --smart-files
仅获取非机械性变更文件的差异内容。默认排除锁文件、自动生成文件和压缩文件。
3. 影响范围分析 —— 查看差异后，检查PR之外的代码是否存在损坏情况：
从差异中识别已移除/重命名的导出内容、已更改的签名、已删除的类型或已修改的公共API。然后针对每个内容执行全仓库搜索：
bash
undefined

Find callers of a removed/renamed symbol

查找已移除/重命名符号的调用方

gh-agent pr grep --repo OWNER/REPO N --pattern "removedFunction" --repo-wide
gh-agent pr grep --repo OWNER/REPO N --pattern "removedFunction" --repo-wide

Find references to a deleted type or enum variant

查找已删除类型或枚举变体的引用

gh-agent pr grep --repo OWNER/REPO N --pattern "DeletedTypeName" --repo-wide
gh-agent pr grep --repo OWNER/REPO N --pattern "DeletedTypeName" --repo-wide

Find consumers of a changed interface/config

查找已更改接口/配置的使用者

gh-agent pr grep --repo OWNER/REPO N --pattern "changedOption" --repo-wide --path src/
gh-agent pr grep --repo OWNER/REPO N --pattern "changedOption" --repo-wide --path src/

Structural search for removed prop usage

结构化搜索已移除属性的使用情况

gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'oldPropName={$$$}' --repo-wide

Search for:
- **Deleted exports/types** — still imported elsewhere?
- **Removed function parameters** — callers updated?
- **Changed constants/config** — validators, serializers, tests in sync?
- **Removed attributes/flags** — renderers, parsers, importers still reference them?

**4. Context** — when diffs or impact results need more detail:

```bash
gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'oldPropName={$$$}' --repo-wide

重点搜索以下内容：
- **已删除的导出/类型** —— 是否仍在其他地方被导入？
- **已移除的函数参数** —— 调用方是否已更新？
- **已更改的常量/配置** —— 验证器、序列化器和测试是否同步更新？
- **已移除的属性/标志** —— 渲染器、解析器和导入器是否仍在引用它们？

**4. 补充上下文** —— 当差异内容或影响分析结果需要更多细节时：

```bash

Read full file at PR branch

读取PR分支下的完整文件

gh-agent pr file --repo OWNER/REPO N --path PATH
gh-agent pr file --repo OWNER/REPO N --path PATH

Search PR changed files (fast, default)

仅搜索PR中已更改的文件（默认，速度快）

gh-agent pr grep --repo OWNER/REPO N --pattern "functionName" gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'useCallback($$$)'

`--repo-wide` uses GitHub Code Search + always includes PR files at head ref. PR results win on overlap. `--base` searches the base branch instead.

**5. Review** — you are an expert senior engineer with deep knowledge of software engineering best practices, security, performance, and maintainability. Perform a thorough code review of the collected diffs and impact results:

1. Generate a high-level summary of the changes in the diff.
2. Go file-by-file and review each changed hunk.
3. Comment on what changed in that hunk (including the line range) and how it relates to other changed hunks and code, reading any other relevant files. Also call out bugs, hackiness, unnecessary code, or too much shared mutable state.
4. Flag any `--repo-wide` hits from impact analysis that indicate broken callers, stale references, or missing updates outside the PR.
5. Categorize findings by severity: CRITICAL, HIGH, MEDIUM, LOW.

**6. Post** (only when user asks):

```bash
gh-agent pr grep --repo OWNER/REPO N --pattern "functionName" gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'useCallback($$$)'

`--repo-wide`参数会使用GitHub代码搜索，并且始终包含PR分支头部的文件。如果PR文件与仓库其他文件有重叠，优先显示PR结果。`--base`参数则搜索基准分支的内容。

**5. 执行评审** —— 你是一名资深工程师，精通软件工程最佳实践、安全、性能和可维护性。请基于收集到的差异内容和影响分析结果进行全面的代码评审：

1. 生成差异内容的高层级总结。
2. 逐文件评审每个变更块。
3. 评论该变更块的内容（包括行号范围），以及它与其他变更块和代码的关联，同时阅读相关的其他文件。还要指出bug、不规范写法、冗余代码或过多的共享可变状态。
4. 标记影响分析中`--repo-wide`搜索结果里的所有问题，比如PR之外存在损坏的调用方、过时引用或缺失的更新。
5. 按严重程度对发现的问题进行分类：CRITICAL（严重）、HIGH（高）、MEDIUM（中）、LOW（低）。

**6. 发布评审结果**（仅在用户要求时执行）：

```bash

Post comments (line must appear in diff — use --json to check)

发布评论（评论行必须存在于差异中——使用--json参数检查）

gh-agent pr review --repo OWNER/REPO N --comments-file /tmp/review.json gh-agent pr diff --repo OWNER/REPO N --json # commentable lines map
gh-agent pr review --repo OWNER/REPO N --comments-file /tmp/review.json gh-agent pr diff --repo OWNER/REPO N --json # 可评论行映射表

Post suggestion

发布建议

gh-agent pr suggest --repo OWNER/REPO N --file F --line-start S --line-end E --replacement "code"
undefined
gh-agent pr suggest --repo OWNER/REPO N --file F --line-start S --line-end E --replacement "code"
undefined

Commands

命令列表

CommandPurpose
pr view --repo R N --smart
Smart triage — always start here
pr view --repo R N --json
PR metadata as JSON
pr diff --repo R N --smart-files
Diffs for non-mechanical files only
pr diff --repo R N --file F
Diff for specific file(s) (substring match, repeatable)
pr diff --repo R N --stat
File stat table
pr diff --repo R N --json
Commentable lines map
pr file --repo R N --path P
Read file at PR branch
pr grep --repo R N -p PAT
Text search PR changed files
pr grep --repo R N -p PAT --repo-wide
Text search full codebase
pr ast-grep --repo R N -p PAT
Structural search PR changed files
pr ast-grep --repo R N -p PAT --repo-wide
Structural search full codebase
pr review --repo R N -c F
Post review from JSON
pr suggest --repo R N ...
Post suggestion comment
命令用途
pr view --repo R N --smart
智能分类筛选 —— 始终从该命令开始
pr view --repo R N --json
以JSON格式输出PR元数据
pr diff --repo R N --smart-files
仅获取非机械性变更文件的差异
pr diff --repo R N --file F
获取指定文件的差异内容（支持子字符串匹配，可重复使用）
pr diff --repo R N --stat
输出文件变更统计表格
pr diff --repo R N --json
输出可评论行的映射表
pr file --repo R N --path P
读取PR分支下的指定文件
pr grep --repo R N -p PAT
在PR已更改文件中执行文本搜索
pr grep --repo R N -p PAT --repo-wide
在整个代码库中执行文本搜索
pr ast-grep --repo R N -p PAT
在PR已更改文件中执行结构化搜索
pr ast-grep --repo R N -p PAT --repo-wide
在整个代码库中执行结构化搜索
pr review --repo R N -c F
从JSON文件发布评审结果
pr suggest --repo R N ...
发布建议类评论

Rules

规则说明

  1. --smart
    first    . Never read all diffs blindly.
  2. --smart-files
    for diffs    . One call, no manual file list.
  3. Skip MECHANICAL. Don't read or comment on them.
  4. NEVER use local files. Always use 
    pr file
    , 
    pr grep
    , or 
    pr ast-grep
    .
  5. Always do impact analysis. After reading diffs, 
    --repo-wide
    grep for every deleted/renamed export, removed type, and changed public API. This catches broken callers outside the PR.
  6. Search incrementally. PR files first → 
    --repo-wide
    only if needed for additional context.
  7. Review in-skill. Do not hand off to external review tools. Summarize, go hunk-by-hunk, flag bugs and stale references, and categorize by severity.
  8. Post only when asked. Present findings in chat; user decides when to post.
  1. 优先使用
    --smart
    参数    。切勿盲目读取所有差异内容。
  2. 使用
    --smart-files
    获取差异    。一次调用即可，无需手动指定文件列表。
  3. 跳过MECHANICAL类变更。无需读取或评论此类变更。
  4. 绝不使用本地文件。始终使用
    pr file
    、
    pr grep
    或
    pr ast-grep
    命令获取文件内容。
  5. 必须执行影响范围分析。查看差异后，对所有已删除/重命名的导出内容、已移除的类型和已更改的公共API执行
    --repo-wide
    搜索。这可以发现PR之外的损坏调用方。
  6. 逐步执行搜索。优先搜索PR文件 → 仅在需要补充上下文时才使用
    --repo-wide
    。
  7. 在工具内完成评审。不要将评审任务交给外部工具。需要生成总结、逐变更块评审、标记bug和过时引用，并按严重程度分类。
  8. 仅在用户要求时发布结果。在聊天中展示评审结果；由用户决定何时发布到GitHub。