PR Review Toolkit 全面 PR 审查工具包

PR Review Toolkit 提供 6 个专业审查 Agent，覆盖注释分析、测试覆盖、错误处理、类型设计、代码质量和代码简化，实现全方位的 Pull Request 审查。

概述

PR Review Toolkit 是一个全面的 PR 审查工具包，与 Code Review 插件不同，它提供了更细分的专业审查能力。每个 Agent 专注于代码质量的一个特定方面，可以单独或组合使用。

六大专业 Agent

Agent	颜色	专注领域
comment-analyzer	-	代码注释质量分析
pr-test-analyzer	-	测试覆盖和行为验证
silent-failure-hunter	-	静默失败和错误处理
type-design-analyzer	-	类型设计和不变式
code-reviewer	红色	代码质量和规范合规
code-simplifier	-	代码简化和可读性

与 Code Review 插件的区别

方面	Code Review	PR Review Toolkit
Agent 数量	4 个通用 Agent	6 个专业 Agent
使用方式	一键完整审查	可选择性使用
专业度	通用审查	深度专业审查
适用场景	快速 PR 审查	深入质量分析

安装与配置

插件安装

bash

# 安装 pr-review-toolkit 插件
/plugin install pr-review-toolkit@claude-plugins-official

目录结构

plugins/pr-review-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── README.md
├── commands/
│   └── review-pr.md              # PR 审查命令
└── agents/
    ├── comment-analyzer.md       # 注释分析器
    ├── pr-test-analyzer.md       # 测试分析器
    ├── silent-failure-hunter.md  # 静默失败检测器
    ├── type-design-analyzer.md   # 类型设计分析器
    ├── code-reviewer.md          # 代码审查器
    └── code-simplifier.md        # 代码简化器

配置文件 (plugin.json)

json

{
  "name": "pr-review-toolkit",
  "version": "1.0.0",
  "description": "Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification",
  "author": {
    "name": "Daisy",
    "email": "daisy@anthropic.com"
  }
}

核心命令

/review-pr

启动 PR 审查流程。

语法：

bash

/review-pr [选项]

工作流程：

mermaid

graph TD
    A[/review-pr] --> B[确定审查范围]
    B --> C[识别变更文件]
    C --> D[选择适用的审查]

    D --> E{执行模式}
    E -->|顺序| F[逐个 Agent 执行]
    E -->|并行| G[所有 Agent 同时执行]

    F --> H[聚合结果]
    G --> H

    H --> I[按优先级交付]

    style A fill:#e3f2fd
    style I fill:#c8e6c9

执行模式：

模式	说明	适用场景
顺序执行	逐个 Agent 运行，便于理解	学习和调试
并行执行	所有 Agent 同时运行，快速	生产使用

六大专业 Agent 详解

1. Comment Analyzer（注释分析器）

专注领域：代码注释的准确性和完整性

评估维度：

维度	说明
事实准确性	注释是否正确描述代码行为
完整性	是否涵盖所有重要细节
长期价值	注释是否有助于未来维护
误导因素	是否有可能误导读者的内容

使用场景：

大型文档更新后
PR 合并前验证
技术债评审

输出示例：

markdown

## Comment Analysis Report

### File: src/services/auth.ts

#### Issue 1: Outdated Comment (Line 45)
```javascript
// 使用 MD5 加密密码  ← 实际使用 bcrypt
const hash = await bcrypt.hash(password, 10);

问题：注释与代码不符，可能误导维护者

Issue 2: Missing Context (Line 78)

javascript

const TOKEN_EXPIRY = 3600;  // 缺少单位说明

建议：添加 // 秒 或使用更明确的命名

Summary

准确性: 7/10
完整性: 6/10
长期价值: 8/10
误导风险: 中


### 2. PR Test Analyzer（测试分析器）

**专注领域**：测试覆盖和行为验证

**核心原则**：

> 聚焦行为覆盖（Behavior Coverage）而非行覆盖率（Line Coverage）

**评估内容**：

| 类别 | 检查项 |
|------|--------|
| **关键路径** | 核心业务流程是否有测试 |
| **边界条件** | 边界值是否被测试 |
| **错误处理** | 错误路径是否被覆盖 |
| **并发/异步** | 异步行为是否被验证 |

**严重性评分**：

| 分数 | 含义 | 示例 |
|------|------|------|
| 9-10 | 数据丢失、安全问题 | 未测试的支付流程 |
| 7-8 | 用户面向的错误 | 未测试的表单验证 |
| 5-6 | 边界情况导致混淆 | 未测试的分页边界 |
| 3-4 | 完整性改进 | 缺少边缘情况测试 |
| 1-2 | 可选优化 | 额外的断言 |

**输出示例**：

```markdown
## Test Coverage Analysis

### Critical Missing Tests (Score: 9)

#### Auth Flow
```javascript
// 未测试：登录失败重试限制
loginService.login(user, password);
// 没有测试连续失败 5 次后的锁定行为

Important Missing Tests (Score: 7)

Error Messages

javascript

// 未测试：错误消息的本地化
catch (error) {
  showError(error.message);  // 是否正确显示中文消息？
}

Behavior Coverage Summary

核心流程: 80% covered
错误处理: 50% covered
边界条件: 30% covered


### 3. Silent Failure Hunter（静默失败检测器）

**专注领域**：错误处理缺陷和静默失败

**核心标准**：

| 标准 | 说明 |
|------|------|
| **错误必须抛出** | 不允许吞掉异常 |
| **用户反馈** | 错误必须有可操作的提示 |
| **显式回退** | 使用备用方案时必须记录 |
| **具体 catch** | catch 块必须处理特定错误类型 |
| **无 mock** | 生产代码不应有模拟实现 |

**严重级别**：

```mermaid
graph LR
    A[CRITICAL] --> A1[数据丢失风险<br/>安全漏洞]
    B[HIGH] --> B1[用户看到空白<br/>功能失效]
    C[MEDIUM] --> C1[降级行为<br/>日志不足]

    style A fill:#ffcdd2
    style B fill:#fff3e0
    style C fill:#e3f2fd

输出示例：

markdown

## Silent Failure Analysis

### CRITICAL: Swallowed Exception (Line 89)
```javascript
try {
  await saveUserData(data);
} catch (error) {
  // ❌ 静默失败！用户不知道保存失败了
}

修复：

javascript

try {
  await saveUserData(data);
} catch (error) {
  logger.error('Failed to save user data', { error, data });
  throw new SaveError('无法保存数据，请重试', error);
}

HIGH: Empty Catch Block (Line 156)

javascript

try {
  config = JSON.parse(rawConfig);
} catch (e) {
  config = {};  // ❌ 静默使用默认值
}

问题：配置错误被静默忽略，可能导致意外行为


### 4. Type Design Analyzer（类型设计分析器）

**专注领域**：类型系统设计和不变式

**核心原则**：

> "Types should make illegal states unrepresentable"
> — 类型应该让非法状态无法表示

**四维评分**（各 1-10 分）：

| 维度 | 说明 |
|------|------|
| **封装性** | 内部细节隐藏程度 |
| **不变式表达** | 规则通过类型结构表达的清晰度 |
| **不变式有用性** | 实际防止 bug 的程度 |
| **不变式执行** | 构造和变异时的保障 |

**输出示例**：

```markdown
## Type Design Analysis

### Overall Score: 7.2/10

### Encapsulation: 8/10
类很好地隐藏了内部实现

### Invariant Expression: 6/10

#### Issue: 可表示非法状态
```typescript
interface Order {
  status: 'pending' | 'paid' | 'shipped';
  shippedAt?: Date;  // ❌ 可以是 pending 但有 shippedAt
}

改进：

typescript

type Order =
  | { status: 'pending' }
  | { status: 'paid' }
  | { status: 'shipped'; shippedAt: Date };

Invariant Usefulness: 7/10

类型系统防止了大部分常见错误

Invariant Enforcement: 7/10

构造函数验证输入，但 setter 缺少验证


### 5. Code Reviewer（代码审查器）

**专注领域**：代码质量和项目规范

**与 Code Review 插件的 agent 类似**，但可单独使用。

**检查内容**：

| 类别 | 检查项 |
|------|--------|
| **项目指南** | CLAUDE.md 规则遵守 |
| **功能 Bug** | 逻辑错误、null 处理 |
| **代码重复** | DRY 原则违反 |
| **错误处理** | 异常处理完整性 |
| **测试覆盖** | 关键代码有测试 |

**信心度评分**：

| 分数 | 报告 |
|------|------|
| 90-100 | 严重 bug 或明确违规 |
| 80-89 | 重要问题需注意 |
| <80 | 不报告（可能误报） |

### 6. Code Simplifier（代码简化器）

**专注领域**：代码简化和可读性

**激活时机**：
- 完成编码任务后
- 实现新功能后
- 修复 bug 后
- 性能优化后

**核心原则**：

| 原则 | 说明 |
|------|------|
| **保持功能** | 简化不能改变行为 |
| **遵循规范** | 应用项目的编码标准 |
| **增强可读性** | 提高代码理解度 |

**简化方向**：

```mermaid
graph TD
    A[代码简化] --> B[消除复杂性]
    A --> C[改进命名]
    A --> D[合并逻辑]
    A --> E[移除冗余]

    B --> B1[避免嵌套三元运算符]
    B --> B2[使用早返回]

    C --> C1[更清晰的变量名]
    C --> C2[更准确的函数名]

    D --> D1[相关代码组织]
    D --> D2[减少重复]

    E --> E1[删除无用注释]
    E --> E2[移除死代码]

输出示例：

markdown

## Code Simplification Suggestions

### 1. Nested Ternary → Switch (Line 45)
**Before**:
```javascript
const label = status === 'active' ? 'Active' :
              status === 'pending' ? 'Pending' :
              status === 'expired' ? 'Expired' : 'Unknown';

After:

javascript

const statusLabels = {
  active: 'Active',
  pending: 'Pending',
  expired: 'Expired'
};
const label = statusLabels[status] ?? 'Unknown';

2. Early Return Pattern (Line 78)

Before:

javascript

function process(data) {
  if (data) {
    if (data.valid) {
      // 20 lines of code
    }
  }
}

After:

javascript

function process(data) {
  if (!data?.valid) return;
  // 20 lines of code
}


---

## 使用示例

### 场景 1：全面审查

```bash
# 运行所有 6 个 Agent
/review-pr --all

场景 2：专项审查

bash

# 只关注测试覆盖
# 可以直接触发特定 agent
"请用 pr-test-analyzer 分析这个 PR 的测试覆盖"

场景 3：组合审查

bash

# 安全敏感的 PR：静默失败 + 类型设计
"请用 silent-failure-hunter 和 type-design-analyzer 审查这个 PR"

最佳实践

Agent 选择指南

场景	推荐 Agent
文档更新	comment-analyzer
新功能	pr-test-analyzer, code-reviewer
错误处理变更	silent-failure-hunter
类型重构	type-design-analyzer
代码清理	code-simplifier
合并前审查	全部

审查流程

mermaid

graph LR
    A[PR 提交] --> B[自动触发审查]
    B --> C{问题严重性}

    C -->|Critical| D[阻止合并]
    C -->|High| E[需要修复]
    C -->|Medium| F[建议修复]
    C -->|Low| G[可选修复]

    D --> H[修复后重新审查]
    E --> H
    H --> B

    style D fill:#ffcdd2
    style E fill:#fff3e0
    style F fill:#e3f2fd
    style G fill:#f5f5f5

常见问题

Q: 应该使用这个还是 Code Review 插件？

快速审查：使用 Code Review 插件
深入分析：使用 PR Review Toolkit
特定问题：使用 Toolkit 中的单个 Agent

Q: 可以自定义 Agent 行为吗？

A: 可以修改 agents/ 目录下的 md 文件来调整 Agent 的行为。

Q: 审查结果太多怎么办？

A: 关注高严重性问题，低严重性可以作为技术债记录。

总结

PR Review Toolkit 提供了专业的 PR 审查能力：

Agent	专注
comment-analyzer	注释质量
pr-test-analyzer	测试覆盖
silent-failure-hunter	错误处理
type-design-analyzer	类型设计
code-reviewer	代码质量
code-simplifier	代码简化

6 个专业 Agent 可以单独或组合使用，满足不同的审查需求。

参考资源

GitHub 源码 - 官方插件仓库
Code Review 插件 - 快速审查工具

本文档基于 pr-review-toolkit 插件 v1.0.0 编写

PR Review Toolkit 全面 PR 审查工具包 ​

概述 ​

六大专业 Agent ​

与 Code Review 插件的区别 ​

安装与配置 ​

插件安装 ​

目录结构 ​

配置文件 (plugin.json) ​

核心命令 ​

/review-pr ​

六大专业 Agent 详解 ​

1. Comment Analyzer（注释分析器） ​

Issue 2: Missing Context (Line 78) ​

Summary ​

Important Missing Tests (Score: 7) ​

Error Messages ​

Behavior Coverage Summary ​

HIGH: Empty Catch Block (Line 156) ​

Invariant Usefulness: 7/10 ​

Invariant Enforcement: 7/10 ​

2. Early Return Pattern (Line 78) ​

场景 2：专项审查 ​

场景 3：组合审查 ​

最佳实践 ​

Agent 选择指南 ​

审查流程 ​

常见问题 ​

Q: 应该使用这个还是 Code Review 插件？ ​

Q: 可以自定义 Agent 行为吗？ ​

Q: 审查结果太多怎么办？ ​

总结 ​

参考资源 ​

PR Review Toolkit 全面 PR 审查工具包

概述

六大专业 Agent

与 Code Review 插件的区别

安装与配置

插件安装

目录结构

配置文件 (plugin.json)

核心命令

/review-pr

六大专业 Agent 详解

1. Comment Analyzer（注释分析器）

Issue 2: Missing Context (Line 78)

Summary

Important Missing Tests (Score: 7)

Error Messages

Behavior Coverage Summary

HIGH: Empty Catch Block (Line 156)

Invariant Usefulness: 7/10

Invariant Enforcement: 7/10

2. Early Return Pattern (Line 78)

场景 2：专项审查

场景 3：组合审查

最佳实践

Agent 选择指南

审查流程

常见问题

Q: 应该使用这个还是 Code Review 插件？

Q: 可以自定义 Agent 行为吗？

Q: 审查结果太多怎么办？

总结

参考资源