PR 评审文档化

技能文档

---
name: pr-review-comment
description: 把 PR 评审结果结构化地发布为 PR 评论并支持多轮更新。执行六维评审（代码质量、可简化点、静默失败、类型设计、测试覆盖、注释质量），生成带隐藏元数据、可折叠分节、问题计数与行动清单的评审评论，通过 GitHub CLI 直接发布或更新，多轮评审自动递增轮次并保留审计轨迹。当用户要求「评审这个 PR 并把结果发到 PR 上」「生成 PR 评审文档」「把评审意见发成 PR 评论」「多轮评审更新」时触发。触发词：PR 评审、评审评论、评审文档化、发布评审、代码审查记录。
title: PR 评审文档化
category: 开发工具
---

# PR 评审文档化

对 Pull Request 执行结构化评审，并把结果以格式化评论发布到 PR 上：带隐藏元数据（支持多轮更新）、可折叠分节、问题分级计数、类型设计评分与行动清单。评审内容直接在 PR 上对团队可见，历史轮次由平台编辑记录自动留存。

## 技能工作流

### 步骤1：确定 PR 编号

```bash
gh pr view --json number,headRefName,baseRefName
```

当前分支没有开启的 PR 时，告知用户并停止，建议先执行 `gh pr create`。

### 步骤2：检查既有评审评论

查找该 PR 上是否已有本技能发布的评审评论（通过 `<!-- pr-review-metadata` 标记识别）：

```bash
gh pr view --json comments --jq '.comments[] | select(.body | contains("pr-review-metadata"))'
```

命中时从元数据 JSON 中提取 `review_round` 与各类问题计数，作为本轮更新的基线。

### 步骤3：执行六维评审

对 PR diff 逐维度审查，六个维度全部执行、不可省略：

| 维度 | 关注点 |
|------|--------|
| 代码质量 | 逻辑正确性、边界条件、与项目规范一致性 |
| 可简化点 | 重复代码、过度设计、可提取的公共逻辑 |
| 静默失败 | 空 catch、被忽略的错误返回、无反馈的异常路径 |
| 类型设计 | 封装性、表达力、实用性、约束力（各 0-10 分） |
| 测试覆盖 | 测试是否存在且有意义、边界场景、断言质量 |
| 注释质量 | 注释是否准确、是否解释「为什么」、是否随代码过期 |

### 步骤4：格式化评审评论

评论模板（元数据标记格式不可改动，是后续轮次识别的依据）：

```markdown
<!-- pr-review-metadata
{
  "schema_version": "1.0",
  "skill": "pr-review-comment",
  "review_round": 1,
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "branch": "分支名",
  "base": "main",
  "issues": {
    "critical": { "total": 0, "fixed": 0 },
    "important": { "total": 0, "fixed": 0 },
    "suggestions": { "total": 0, "fixed": 0 }
  },
  "lenses_run": ["quality", "simplification", "silent-failure", "type-design", "tests", "comments"]
}
-->

## 🤖 PR Review

**Branch:** `分支名` → `目标分支`
**Round:** N | **Updated:** YYYY-MM-DD

---

### 📊 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]

---

### 🔴 Critical Issues

<details open>
<summary><b>1. [状态] 问题标题</b></summary>

**File:** `path/to/file.ts:行号`

**Problem:** 问题描述。

**Fix:** 修复方案。

</details>

---

### 🟡 Important Issues

[同上结构，默认折叠]

---

### 💡 Suggestions

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

| # | 建议 | 状态 |
|---|------|------|
| 1 | 描述 | ✅ / ⏭️ |

</details>

---

### ✨ Strengths

- 正面观察 1
- 正面观察 2

---

### 📋 Type Design Ratings

| Type | Encap. | Express. | Useful. | Enforce. | Overall |
|------|--------|----------|---------|----------|---------|
| TypeName | X/10 | X/10 | X/10 | X/10 | **X/10** |

---

### 🎯 Action Plan

**Before Merge:**
- [ ] 合并前待办
- [x] 已完成项

**After Merge (Backlog):**
- [ ] 后续改进
```

格式要求：

- 全文控制在 4 万字符以内（平台评论上限 65,536）：超限时多用 `<details>` 折叠、压缩描述、把长代码示例移入折叠区
- 问题必须带 `文件:行号` 引用与具体修复方案
- 状态指示符统一语义：✅ 已修复 / ⏭️ 有意跳过 / ⚠️ 需要关注 / 🔴 阻断性

### 步骤5：发布或更新评论

发布新评论：

```bash
gh pr comment <编号> --body-file review.md
```

更新既有评论（保持同一条评论、平台自动留存编辑历史）：

```bash
gh api repos/{owner}/{repo}/issues/comments/<评论ID> -X PATCH -F body=@review.md
```

多轮更新时：`review_round` 加一、刷新 `updated_at`、更新问题计数与各条状态，其余内容保持同一条评论。

### 步骤6：核验

确认返回的评论 URL 有效、内容渲染正常、元数据 JSON 合法、问题计数与正文一致。

## 发布前检查清单

- [ ] PR 编号正确
- [ ] 六个评审维度全部执行
- [ ] 元数据 JSON 合法（`pr-review-metadata` 标记格式未变）
- [ ] 问题计数与正文条目一致
- [ ] 状态指示符使用一致
- [ ] 全文 4 万字符以内
- [ ] 评论发布/更新成功

## 异常处理

| 场景 | 处理方式 |
|------|----------|
| 当前分支无 PR | 告知用户，建议先 `gh pr create` |
| 未安装 gh 或未登录 | 提示 `gh auth login`，无法降级为纯文本输出时停止 |
| 既有评论元数据损坏 | 视为新一轮第 1 轮评审，重新发布并说明 |
| 评论超长被拒 | 折叠更多分节、压缩描述后重试 |

使用说明

# PR 评审文档化

对 Pull Request 执行六维评审（代码质量、可简化点、静默失败、类型设计、测试覆盖、注释质量），并把结构化结果发布为 PR 评论：带隐藏元数据、可折叠分节、问题分级计数、类型设计评分与行动清单，多轮评审自动递增轮次并保留审计轨迹。

## 最简用法

```text
评审这个 PR，把结果发成 PR 评论
```

```text
更新上一轮 PR 评审，标记已修复的问题
```

## 特点

- 六维评审全覆盖，问题带文件行号与具体修复方案
- 单条评论多轮更新：轮次、计数、状态自动演进
- 隐藏元数据驱动，机器可读、可续审
- Critical/Important/Suggestions 三级分类 + 行动清单
- 基于 GitHub CLI，无需额外依赖

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。