pr-review-and-document

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Review and Document

PR审查与记录

Execute comprehensive PR review using pr-review-toolkit and post structured results as a PR comment.

通过pr-review-toolkit执行全面的PR审查，并将结构化结果作为PR评论发布。

When to Use

使用场景

Invoke this skill when:

A comprehensive PR review needs to be documented on the PR
A formal review record is required for a feature branch
Review findings need to be visible directly on the PR for team reference

在以下情况调用本Skill：

需要在PR上记录全面的审查内容时
功能分支需要正式的审查记录时
审查结果需要直接显示在PR上供团队参考时

Workflow

工作流程

Step 1: Get PR Number (Cache-Aware)

步骤1：获取PR编号（支持缓存）

bash

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

This uses the branch-to-PR-number cache (

branch-map.json

) with 1-hour TTL, falling back to GitHub API on cache miss.

If no PR exists for the current branch, inform the user and stop.

bash

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

这会使用分支到PR编号的缓存（branch-map.json），TTL为1小时，缓存未命中时回退到GitHub API。

如果当前分支没有对应的PR，告知用户并停止操作。

Step 2: Check Existing Review Comment (Cache-Aware)

步骤2：检查现有审查评论（支持缓存）

bash

EXISTING_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")

This uses the local cache if available, falling back to GitHub API on cache miss.

If content is returned:

Extract metadata from
```

```
block
Note the current
```
review_round
```
and issues status

bash

EXISTING_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")

如果本地缓存可用则使用，缓存未命中时回退到GitHub API。

如果返回内容：

从
```

```
块中提取元数据
记录当前的
```
review_round
```
（审查轮次）和问题状态

Step 3: Execute PR Review

步骤3：执行PR审查

Launch the pr-review-toolkit with opus model using the Skill tool:

Skill: pr-review-toolkit:review-pr
Args: all
Model: opus

Required agents (always run):

code-reviewer - General code quality and CLAUDE.md compliance
code-simplifier - Code simplification opportunities
silent-failure-hunter - Error handling and silent failure detection
type-design-analyzer - Type design quality analysis
pr-test-analyzer - Test coverage analysis
comment-analyzer - Comment accuracy and maintainability

Important: All agents are mandatory for every review to ensure comprehensive coverage.

通过Skill工具启动结合opus模型的pr-review-toolkit：

Skill: pr-review-toolkit:review-pr
Args: all
Model: opus

必须运行的Agent（始终执行）：

code-reviewer - 通用代码质量与CLAUDE.md合规性检查
code-simplifier - 代码简化机会分析
silent-failure-hunter - 错误处理与静默故障检测
type-design-analyzer - 类型设计质量分析
pr-test-analyzer - 测试覆盖率分析
comment-analyzer - 注释准确性与可维护性检查

重要提示： 为确保审查全面性，每次审查必须运行所有6个Agent。

Step 4: Format Review Comment

步骤4：格式化审查评论

Structure the review as a PR comment with hidden metadata and collapsible sections.

Character Limit: Keep total content under ~40K characters (GitHub limit is 65,536).

将审查内容整理为带有隐藏元数据和可折叠区块的PR评论格式。

字符限制： 总内容需控制在约40000字符以内（GitHub限制为65536字符）。

Metadata Block Format

元数据块格式

The metadata block uses HTML comment syntax with a specific marker for identification:

Opening:
```
<!-- pr-review-metadata
```
(marker on same line as opening)
Content: JSON object with review state
Closing:
```
-->
```
on its own line after the JSON

Important: The

find-review-comment.sh

script searches for

<!-- pr-review-metadata

to identify review comments. Do not modify this marker format.

元数据块使用HTML注释语法，并带有特定标识用于识别：

开头：
```
<!-- pr-review-metadata
```
（标识与开头在同一行）
内容：包含审查状态的JSON对象
结尾：
```
-->
```
单独一行放在JSON之后

重要提示：

find-review-comment.sh

脚本会搜索

<!-- pr-review-metadata

来识别审查评论，请勿修改该标识格式。

Comment Template

评论模板

markdown

<!-- pr-review-metadata
{
  "schema_version": "1.0",
  "skill": "pr-review-and-document",
  "review_round": 1,
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "branch": "branch-name",
  "base": "main",
  "issues": {
    "critical": { "total": 0, "fixed": 0 },
    "important": { "total": 0, "fixed": 0 },
    "suggestions": { "total": 0, "fixed": 0 }
  },
  "agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"]
}
-->

markdown

<!-- pr-review-metadata
{
  "schema_version": "1.0",
  "skill": "pr-review-and-document",
  "review_round": 1,
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "branch": "branch-name",
  "base": "main",
  "issues": {
    "critical": { "total": 0, "fixed": 0 },
    "important": { "total": 0, "fixed": 0 },
    "suggestions": { "total": 0, "fixed": 0 }
  },
  "agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"]
}
-->

🤖 PR Review

🤖 PR审查

Branch:

branch-name

→

base-branch

Round: N | Updated: YYYY-MM-DD Reviewer: claude-opus-4-5 via pr-review-toolkit

分支：

branch-name

→

base-branch

轮次： N | 更新时间： YYYY-MM-DD 审查者： claude-opus-4-5 via pr-review-toolkit

📊 Summary

📊 审查摘要

Category	Total	Fixed	Remaining
🔴 Critical	X	X	X
🟡 Important	X	X	X
💡 Suggestions	X	X	X

Status: [✅ Ready to merge | ⚠️ Needs attention | 🔴 Blocking issues]

类别	总数	已修复	剩余
🔴 关键问题	X	X	X
🟡 重要问题	X	X	X
💡 优化建议	X	X	X

状态： [✅ 可合并 | ⚠️ 需要关注 | 🔴 存在阻塞问题]

🔴 Critical Issues

🔴 关键问题

<details open> <summary>1. [Status Emoji] Issue Title</summary>

File:

path/to/file.ts:line

Problem: Description of the issue.

Fix: Resolution or suggested fix.

</details>

[Repeat for each critical issue]

文件：

path/to/file.ts:line

问题描述： 问题的详细说明。

修复建议： 解决方案或建议修复方式。

</details>

[每个关键问题重复上述格式]

🟡 Important Issues

🟡 重要问题

<details> <summary>1. [Status Emoji] Issue Title</summary>

File:

path/to/file.ts:line

Problem: Description.

Fix: Resolution.

</details>

[Repeat for each important issue]

文件：

path/to/file.ts:line

问题描述： 问题说明。

修复建议： 解决方案。

</details>

[每个重要问题重复上述格式]

💡 Suggestions

💡 优化建议

<details> <summary>View N suggestions (M addressed)</summary>

#	Suggestion	Status
1	Description	✅ / ⏭️

</details>

<details> <summary>查看N条建议（其中M条已处理）</summary>

序号	建议内容	状态
1	建议描述	✅ / ⏭️

</details>

✨ Strengths

✨ 代码亮点

Positive observation 1
Positive observation 2

积极的观察点1
积极的观察点2

📋 Type Design Ratings

📋 类型设计评分

Type	Encap.	Express.	Useful.	Enforce.	Overall
TypeName	X/10	X/10	X/10	X/10	X/10

类型名称	封装性	表达性	实用性	强制性	总分
TypeName	X/10	X/10	X/10	X/10	X/10

🎯 Action Plan

🎯 行动计划

Before Merge:

Action item 1
Completed item

After Merge (Backlog):

Future improvement

Generated by pr-review-and-document skill | Round N | [View edit history](click edited)

undefined

合并前需完成：

行动项1
已完成项

合并后（待办）：

未来优化点

由pr-review-and-document Skill生成 | 第N轮审查 | 查看编辑历史

undefined

Step 5: Write Review Comment (Cache-Aware)

步骤5：写入审查评论（支持缓存）

Pipe the formatted content directly to

cache-write-comment.sh

via

--stdin

bash

echo "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"

The script will:

Update local cache (
```
.pr-review-cache/pr-{N}.json
```
)
Sync to GitHub via
```
upsert-review-comment.sh --stdin
```
（stdin pipe，不使用 temp file）
Return the comment URL

将格式化后的内容通过

--stdin

直接传入

cache-write-comment.sh

：

bash

echo "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"

该脚本会执行以下操作：

更新本地缓存（
```
.pr-review-cache/pr-{N}.json
```
）
通过
```
upsert-review-comment.sh --stdin
```
同步到GitHub（使用stdin管道，不使用临时文件）
返回评论的URL

Step 6: Verify

步骤6：验证

Confirm the comment was posted successfully by checking the returned URL.

通过检查返回的URL，确认评论已成功发布。

Status Indicators

状态标识

Use consistent status indicators:

Indicator	Meaning
✅	Fixed / Resolved
⏭️	Deferred / Skipped intentionally
⚠️	Needs attention
🔴	Blocking / Critical

使用统一的状态标识：

标识	含义
✅	已修复/已解决
⏭️	已推迟/有意跳过
⚠️	需要关注
🔴	阻塞/关键问题

Multi-Round Reviews

多轮审查

When updating an existing review:

Increment
```
review_round
```
in metadata
Update
```
updated_at
```
timestamp
Update issue counts and statuses
Keep the same comment (GitHub tracks edit history)

Previous review content is preserved in GitHub's "edited" dropdown, providing full audit trail.

当更新现有审查时：

在元数据中递增
```
review_round
```
（审查轮次）
更新
```
updated_at
```
时间戳
更新问题数量和状态
保留原评论（GitHub会跟踪编辑历史）

之前的审查内容会保存在GitHub的「编辑记录」下拉菜单中，提供完整的审计轨迹。

Integration Notes

集成说明

Using with pr-review-toolkit

与pr-review-toolkit配合使用

This skill wraps the

pr-review-toolkit:review-pr

command and:

Forces opus model for comprehensive analysis
Always runs all 6 review agents (mandatory)
Formats output as structured PR comment
Posts directly to the PR

本Skill封装了

pr-review-toolkit:review-pr

命令，并：

强制使用opus模型以实现全面分析
始终运行全部6个审查Agent（必填）
将输出格式化为结构化PR评论
直接发布到PR中

Character Limit Handling

字符限制处理

If review content exceeds ~40K characters:

Collapse more sections with
```
<details>
```
Summarize verbose descriptions
Move detailed code examples to collapsed sections

如果审查内容超过约40000字符：

使用
```
<details>
```
折叠更多区块
简化冗长的描述
将详细的代码示例移至折叠区块中

No PR Available

无可用PR的情况

If the current branch has no open PR:

Inform the user
Suggest creating a PR first:
```
gh pr create
```

如果当前分支没有打开的PR：

告知用户
建议先创建PR：
```
gh pr create
```

pr-review-and-document

Original

Translation

PR Review and Document

PR审查与记录

When to Use

使用场景

Workflow

工作流程

Step 1: Get PR Number (Cache-Aware)

步骤1：获取PR编号（支持缓存）

Step 2: Check Existing Review Comment (Cache-Aware)

步骤2：检查现有审查评论（支持缓存）

Step 3: Execute PR Review

步骤3：执行PR审查

Step 4: Format Review Comment

步骤4：格式化审查评论

Metadata Block Format

元数据块格式

Comment Template

评论模板

🤖 PR Review

🤖 PR审查

📊 Summary

📊 审查摘要

🔴 Critical Issues

🔴 关键问题

🟡 Important Issues

🟡 重要问题

💡 Suggestions

💡 优化建议

✨ Strengths

✨ 代码亮点

📋 Type Design Ratings

📋 类型设计评分

🎯 Action Plan

🎯 行动计划

Step 5: Write Review Comment (Cache-Aware)

步骤5：写入审查评论（支持缓存）

Step 6: Verify

步骤6：验证

Status Indicators

状态标识

Multi-Round Reviews

多轮审查

Integration Notes

集成说明

Using with pr-review-toolkit

与pr-review-toolkit配合使用

Character Limit Handling

字符限制处理

No PR Available

无可用PR的情况

Validation Checklist

验证清单