pr-review-and-document

PR 评审与文档

使用 pr-review-toolkit 执行全面的 PR 评审，并以 PR 评论的形式发布结构化结果。

适用场景

在以下情况下调用此技能：

• 需要将全面的 PR 评审记录到 PR 中
• 功能分支需要正式的评审记录
• 评审结果需要直接显示在 PR 中，供团队参考

工作流

步骤 1：获取 PR 编号（使用缓存）

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

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

如果当前分支不存在 PR，请告知用户并停止。

步骤 2：检查是否已有评审评论（使用缓存）

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

此步骤会在本地缓存可用时使用缓存；缓存未命中时则回退到 GitHub API。

如果返回了内容：

• 从 `` 块中提取元数据
• 记录当前的 review_round 和问题状态
• 读取 .pr-review-cache/pr-${PR_NUMBER}.json，并将 .content_hash 保存为 EXPECTED_CONTENT_HASH
• 写入下一轮评审时，保留任何现有的 [Gemini] 和 [Codex] 问题及 review_sources 元数据

步骤 3：执行 PR 评审

使用 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 - 注释准确性和可维护性

重要： 每次评审都必须运行所有 Agent，以确保覆盖全面。

步骤 4：格式化评审评论

将评审整理为包含隐藏元数据和可折叠分区的 PR 评论。

字符数限制： 总内容保持在约 40K 个字符以内（GitHub 限制为 65,536 个字符）。

多来源兼容性： 如果已有评审评论，不要直接重新生成整条评论。将新的 Claude 评审结果合并到现有结构中：

• 写入前将元数据升级到 schema 1.1。优先使用共享辅助工具：

  METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-and-document)
  

• 编辑元数据 JSON（例如通过 jq）后，使用共享辅助工具替换隐藏块：

  # Set up a temp file for the modified metadata JSON.
  # (If this code block already declares its own trap, extend it instead of adding a second line.)
  METADATA_FILE=$(mktemp)
  trap 'rm -f "$METADATA_FILE"' EXIT
  
  # Write the edited metadata JSON to the temp file.
  printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
  
  # Replace the metadata block in the comment.
  UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
  

• 保留 review_sources.gemini、review_sources.codex、[Gemini] 问题和 [Codex] 问题
• 保留现有问题状态（✅、⏭️、⚠️、🔴），除非新的 Claude 评审证明状态已发生变化
• 将未标记的问题视为 Claude 问题
• 只有本次评审新增问题时才递增 PR 全局的 review_round；若仅刷新且没有新增问题，则只更新 review_sources.claude.last_reviewed_*

元数据块格式

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

• 开始标记：单独占一行，位于 JSON 之后的 ``

重要： find-review-comment.sh 脚本会搜索 `

🤖 PR 评审

分支： branch-name → base-branch 轮次： N | 更新时间： YYYY-MM-DD 评审来源： Claude

---

📊 概要

类别	总数	已修复	未解决
🔴 严重	X	X	X
🟡 重要	X	X	X
💡 建议	X	X	X

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

---

🔴 严重问题

1. [状态表情符号] 问题标题

文件： path/to/file.ts:line

问题： 问题描述。

修复： 解决方案或建议的修复方法。

[对每个严重问题重复此结构]

---

🟡 重要问题

1. [状态表情符号] 问题标题

文件： path/to/file.ts:line

问题： 描述。

修复： 解决方案。

[对每个重要问题重复此结构]

---

💡 建议

查看 N 条建议（已处理 M 条）

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

---

✨ 优势

• 正面观察 1
• 正面观察 2

---

📋 类型设计评分

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

---

🎯 行动计划

合并前：

• 行动项 1
• 已完成项

合并后（待办）：

• 后续改进

---

_{由 pr-review-and-document skill 生成 | 第 N 轮 | [查看编辑历史](click edited)}

### Step 5: Write Review Comment (Cache-Aware)

Pipe the formatted content directly to `cache-write-comment.sh` via `--stdin`:

```bash
if [ -n "${EXPECTED_CONTENT_HASH:-}" ]; then
  printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER" --expected-content-hash "$EXPECTED_CONTENT_HASH"
else
  printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"
fi

此脚本将：

• 更新本地缓存（.pr-review-cache/pr-{N}.json）
• 通过 upsert-review-comment.sh --stdin 同步到 GitHub（stdin 管道，不使用临时文件）
• 返回评论 URL
• 如果其他工具在此技能读取缓存后更新了缓存，则退出 4；重新读取，将你的更改合并到较新的评论中，然后重试一次

第 6 步：验证

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

状态指示器

使用一致的状态指示器：

指示器	含义
✅	已修复 / 已解决
⏭️	已延期 / 有意跳过
⚠️	需要关注
🔴	阻塞 / 严重

多轮审查

更新现有审查时：

1. 根据本轮是否有新发现，更新 review_round 和时间戳：
   • 有新发现： 增加 review_round，更新 updated_at、问题计数和状态。
   • 空刷新（没有新发现）： 保持 review_round 不变；仅更新 review_sources.claude.last_reviewed_head 和 review_sources.claude.last_reviewed_at。不要修改现有问题的状态或计数。
2. 保留 review_sources 元数据和现有的非 Claude 问题部分。
3. 保留同一条评论（GitHub 会跟踪编辑历史）。

之前的审查内容会保存在 GitHub 的“edited”下拉菜单中，提供完整的审计记录。

元数据迁移

读取较旧的 schema_version: "1.0" 元数据时，应在写入前在内存中升级：

1.0 字段	1.1 字段
skill	如果缺失则设为 created_by、保留为旧版字段 skill，并设为当前的 last_writer
agents_run	review_sources.claude.agents_run，兼容期内同时保留顶层 agents_run
gemini_integrated_ids	review_sources.gemini.consumed_comment_ids
gemini_integration_date	review_sources.gemini.last_integrated_at

不要降级。新的写入应使用评论元数据架构 1.1；缓存封装仍保持 schema_version: "1.0"。

如果可能，使用 ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh 执行此迁移，然后使用 ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh 将返回的 JSON 合并回 `` 块中，且不触及问题部分。

集成说明

与 pr-review-toolkit 配合使用

此技能封装了 pr-review-toolkit:review-pr 命令，并且：

1. 强制使用 opus 模型进行全面分析
2. 始终运行全部 6 个审查 Agent（必须执行）
3. 将输出格式化为结构化 PR 评论
4. 直接发布到 PR

字符数限制处理

如果审查内容超过约 40K 个字符：

1. 使用 <details> 折叠更多部分
2. 概述冗长的描述
3. 将详细代码示例移至折叠部分

没有可用的 PR

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

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

验证清单

发布审查评论前：

• 已正确识别 PR 编号
• 已运行全部 6 个审查 Agent
• 元数据 JSON 有效
• 问题计数与内容一致
• 状态指示器一致
• 内容少于 40K 个字符
• 已成功发布/更新评论