208 lines
5.4 KiB
Markdown
208 lines
5.4 KiB
Markdown
# GitHub PR审查技能
|
||
|
||
`Claude Code` `GitHub` `代码审查` `PR` `gh CLI`
|
||
|
||
# Claude Code 的 GitHub PR 审查技能
|
||
|
||
一个 Claude Code 技能，通过 `gh` CLI 使用待处理审查和代码建议，确保 GitHub Pull Request 审查的一致性与专业性。
|
||
|
||
## 技能功能
|
||
|
||
本技能教会 Claude：
|
||
- **始终使用待处理审查**来批量提交评论（即使在时间压力下）
|
||
- **使用 ```suggestion 语法创建代码建议**
|
||
- **选择正确的事件类型**（COMMENT、APPROVE 或 REQUEST_CHANGES）
|
||
- **使用正确的 `gh api` 语法**，包括正确的引号和参数标志
|
||
|
||
## 安装
|
||
|
||
### 方式一：插件市场（推荐）
|
||
|
||
通过 Claude Code 直接从市场安装：
|
||
|
||
```bash
|
||
# 添加此市场
|
||
/plugin marketplace add aidankinzett/claude-git-pr-skill
|
||
|
||
# 安装插件
|
||
/plugin install github-pr-review
|
||
|
||
# 验证安装
|
||
/plugin list
|
||
```
|
||
|
||
**团队全局安装**，添加到 `.claude/settings.json`：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": [
|
||
{
|
||
"name": "github-pr-skills",
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "aidankinzett/claude-git-pr-skill"
|
||
}
|
||
}
|
||
],
|
||
"plugins": {
|
||
"github-pr-review": {
|
||
"enabled": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方式二：手动复制
|
||
|
||
直接将技能复制到技能目录：
|
||
|
||
```bash
|
||
# 个人使用（所有项目）
|
||
cp -r github-pr-review/skills/github-pr-review ~/.claude/skills/
|
||
|
||
# 项目专用
|
||
cp -r github-pr-review/skills/github-pr-review .claude/skills/
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
安装后，当你请求 Claude 审查 Pull Request 时，它会自动使用本技能。例如：
|
||
|
||
```
|
||
你："审查 PR #123 并提出改进建议"
|
||
Claude：*使用 github-pr-review 技能创建带批量评论的待处理审查*
|
||
```
|
||
|
||
## 本技能的独特之处
|
||
|
||
**没有本技能**，Claude 可能会：
|
||
- 未经确认直接发布评论
|
||
- 在时间压力下跳过待处理审查
|
||
- 使用错误的 `gh api` 语法
|
||
- 选择错误的事件类型
|
||
- 发布你未批准的评论
|
||
|
||
**使用本技能**，Claude 将：
|
||
- ✅ **发布前向你展示确切内容**
|
||
- ✅ **通过是/否问题请求明确批准**
|
||
- ✅ 始终先创建待处理审查
|
||
- ✅ 批量汇总所有评论
|
||
- ✅ 使用 ```suggestion 块提供代码建议
|
||
- ✅ 选择合适的事件类型（小建议用 APPROVE，阻塞性问题用 REQUEST_CHANGES）
|
||
- ✅ 使用正确语法（`comments[][]` 参数用单引号包裹）
|
||
|
||
## 工作流程
|
||
|
||
本技能强制执行以下工作流：
|
||
|
||
**1. 起草 → 2. 展示并批准 → 3. 发布**
|
||
|
||
### 第一步：起草审查
|
||
Claude 分析 PR 并准备包含代码建议的评论。
|
||
|
||
### 第二步：展示并获得批准
|
||
Claude 向你展示**确切将要发布的内容**：
|
||
- 每条评论及其文件和行号
|
||
- 已格式化的代码建议
|
||
- 事件类型（APPROVE / REQUEST_CHANGES / COMMENT）
|
||
- 整体审查摘要
|
||
|
||
你审阅后批准（或要求修改）。
|
||
|
||
### 第三步：发布审查（技术细节）
|
||
|
||
获得批准后，Claude 使用以下模式发布：
|
||
|
||
```bash
|
||
# 第一步：创建包含所有评论的 PENDING 审查
|
||
gh api repos/:owner/:repo/pulls/123/reviews \
|
||
-X POST \
|
||
-f commit_id="<SHA>" \
|
||
-f 'comments[][path]=file.ts' \
|
||
-F 'comments[][line]=42' \
|
||
-f 'comments[][side]=RIGHT' \
|
||
-f 'comments[][body]=带有 ```suggestion 块的评论...' \
|
||
--jq '{id, state}'
|
||
|
||
# 第二步：准备好后提交
|
||
gh api repos/:owner/:repo/pulls/123/reviews/<REVIEW_ID>/events \
|
||
-X POST \
|
||
-f event="APPROVE" \
|
||
-f body="整体审查摘要"
|
||
```
|
||
|
||
## 优势
|
||
|
||
- **一致的工作流**，适用于所有 PR 审查
|
||
- **专业的批量评论**，避免零散通知
|
||
- **每次使用正确语法**
|
||
- **更好的事件类型决策**
|
||
- **经过实践验证的模式**，在压力下同样有效
|
||
|
||
## 前提条件
|
||
|
||
- Claude Code
|
||
- 已安装并认证的 GitHub CLI（`gh`）
|
||
|
||
## 许可证
|
||
|
||
MIT（或指定你的许可证）
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
.claude-plugin/
|
||
marketplace.json # 插件市场定义
|
||
github-pr-review/ # 插件根目录
|
||
skills/ # 技能目录
|
||
github-pr-review/ # 技能本体
|
||
SKILL.md # 技能定义
|
||
CHANGELOG.md # 版本历史与变更记录
|
||
```
|
||
|
||
## 版本管理
|
||
|
||
本技能遵循[语义化版本规范](https://semver.org/)：
|
||
- **当前版本：** 1.0.0
|
||
- **版本位置：** `.claude-plugin/marketplace.json`
|
||
- **变更历史：** 参见 [CHANGELOG.md](CHANGELOG.md)
|
||
|
||
### 更新版本
|
||
|
||
进行变更时：
|
||
|
||
1. **更新 CHANGELOG.md** — 在 `[Unreleased]` 下添加条目
|
||
2. **发布时：**
|
||
- 将未发布条目移至 CHANGELOG.md 的新版本章节
|
||
- 更新 `.claude-plugin/marketplace.json` 中的 `version`
|
||
- 创建 git 标签：`git tag -a v1.0.1 -m "Release v1.0.1"`
|
||
- 连同标签推送：`git push --tags`
|
||
|
||
**版本号说明：**
|
||
- **PATCH**（1.0.1）— Bug 修复、错别字、小幅改进
|
||
- **MINOR**（1.1.0）— 新功能，向后兼容
|
||
- **MAJOR**（2.0.0）— 技能行为的破坏性变更
|
||
|
||
## 贡献
|
||
|
||
本技能采用测试驱动开发方式构建：
|
||
1. 基准测试识别出违规行为（在时间压力下立即发布、无用户批准）
|
||
2. 编写技能以解决这些违规问题
|
||
3. 测试验证技能正确运行
|
||
4. 测试并处理边界情况
|
||
5. 根据用户反馈添加批准工作流
|
||
|
||
如果发现技能无法正确处理的边界情况，欢迎提交 Issue！
|
||
|
||
## 开发
|
||
|
||
本地测试变更：
|
||
|
||
```bash
|
||
# 创建符号链接用于测试
|
||
ln -s $(pwd)/github-pr-review/skills/github-pr-review ~/.claude/skills/github-pr-review
|
||
|
||
# 或在本地使用插件市场
|
||
/plugin marketplace add file://$(pwd)
|
||
/plugin install github-pr-review
|
||
``` |