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

Find references to a deleted type or enum variant

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

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/

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

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

命令列表

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

规则说明

--smart
first. Never read all diffs blindly.
--smart-files
for diffs. One call, no manual file list.
Skip MECHANICAL. Don't read or comment on them.
NEVER use local files. Always use
```
pr file
```
,
```
pr grep
```
, or
```
pr ast-grep
```
.
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.
Search incrementally. PR files first →
```
--repo-wide
```
only if needed for additional context.
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.
Post only when asked. Present findings in chat; user decides when to post.

优先使用
--smart
参数。切勿盲目读取所有差异内容。
使用
--smart-files
获取差异。一次调用即可，无需手动指定文件列表。
跳过MECHANICAL类变更。无需读取或评论此类变更。
绝不使用本地文件。始终使用
```
pr file
```
、
```
pr grep
```
或
```
pr ast-grep
```
命令获取文件内容。
必须执行影响范围分析。查看差异后，对所有已删除/重命名的导出内容、已移除的类型和已更改的公共API执行
```
--repo-wide
```
搜索。这可以发现PR之外的损坏调用方。
逐步执行搜索。优先搜索PR文件 → 仅在需要补充上下文时才使用
```
--repo-wide
```
。
在工具内完成评审。不要将评审任务交给外部工具。需要生成总结、逐变更块评审、标记bug和过时引用，并按严重程度分类。
仅在用户要求时发布结果。在聊天中展示评审结果；由用户决定何时发布到GitHub。