kb-skills/pr-review-gate/SKILL.md

---
name: pr-review-gate
description: "PR 审查门禁技能。当 PR 创建后自动触发，启动 3 个审查子代理并行审查。"
---

# pr-review-gate - PR 审查门禁

## 什么时候使用

- PR 创建后自动触发
- 用户说"审查 PR #xxx"
- 用户说"开始审查"

## 环境变量

| 变量名 | 用途 | 必需 |
|--------|------|------|
| `GITEA_TOKEN` | Gitea API Token | 是 |
| `GITEA_URL` | Gitea 服务地址 | 否 |
| `GITEA_REPO` | 仓库路径 | 否 |

## 工作流程

```
PR 创建
    ↓
┌─────────────────────────────────────────────────────┐
│  并行启动 3 个审查子代理                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │  Security   │ │   Quality   │ │    Logic    │    │
│  │  Reviewer   │ │   Reviewer  │ │   Reviewer  │    │
│  │  (安全)     │ │   (质量)    │ │   (逻辑)    │    │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘    │
│         │               │               │           │
│         ▼               ▼               ▼           │
│      approve?       approve?       approve?         │
│         │               │               │           │
└─────────┼───────────────┼───────────────┼───────────┘
          │               │               │
          └───────────────┼───────────────┘
                          ▼
              ┌───────────────────────┐
              │  收集审查结果          │
              └───────────┬───────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
    全部 approve     有 reject       CI 失败
          │               │               │
          ▼               ▼               ▼
    ┌───────────┐   ┌───────────┐   ┌───────────┐
    │ 自动合并   │   │ 修复循环  │   │ 等待修复  │
    │ 到 main    │   │ (最多3次) │   │           │
    └───────────┘   └───────────┘   └───────────┘
```

## 审查者角色

### 1. Security Reviewer (安全审查者)

**关注点：**
- 输入验证
- SQL 注入 / XSS / CSRF
- 敏感数据处理
- 权限检查
- 依赖安全

**审查清单：**
- [ ] 所有用户输入都经过验证和清理
- [ ] 没有硬编码的密钥或凭据
- [ ] 文件操作有路径检查
- [ ] API 调用有适当的认证

### 2. Quality Reviewer (代码质量审查者)

**关注点：**
- 代码可读性
- 命名规范
- 代码结构
- 测试覆盖
- 文档完整性

**审查清单：**
- [ ] 函数/变量命名清晰
- [ ] 代码有适当的注释
- [ ] 复杂逻辑有文档说明
- [ ] 有单元测试覆盖
- [ ] SKILL.md 已更新（如适用）

### 3. Logic Reviewer (业务逻辑审查者)

**关注点：**
- 需求是否满足
- 边界条件处理
- 错误处理
- 与现有功能的兼容性
- 性能影响

**审查清单：**
- [ ] 实现符合 spec 描述
- [ ] 边界条件已处理
- [ ] 错误情况有适当的处理
- [ ] 不会破坏现有功能
- [ ] 性能可接受

## 执行步骤

### Step 1: 获取 PR 信息

```bash
python3 pr_gate.py --get-pr --number 123
```

获取 PR 的：
- 标题和描述
- 变更文件列表
- diff 内容

### Step 2: 启动审查子代理

使用 `sessions_spawn` 并行启动 3 个审查子代理：

```
# Security Reviewer
sessions_spawn(
  task="审查 PR #xxx 的安全性",
  label="security-reviewer",
  runtime="subagent"
)

# Quality Reviewer
sessions_spawn(
  task="审查 PR #xxx 的代码质量",
  label="quality-reviewer",
  runtime="subagent"
)

# Logic Reviewer
sessions_spawn(
  task="审查 PR #xxx 的业务逻辑",
  label="logic-reviewer",
  runtime="subagent"
)
```

### Step 3: 收集审查结果

等待所有子代理完成，收集结果：

```json
{
  "security": {
    "reviewer": "security",
    "result": "approve|reject",
    "comments": ["..."],
    "issues": []
  },
  "quality": {
    "reviewer": "quality",
    "result": "approve",
    "comments": ["..."],
    "issues": []
  },
  "logic": {
    "reviewer": "logic",
    "result": "approve",
    "comments": ["..."],
    "issues": []
  }
}
```

### Step 4: 决策

**全部 approve + CI 通过：**
```bash
python3 pr_gate.py --merge-pr --number 123
```

**有 reject：**
```bash
python3 pr_gate.py --fix-loop --number 123 --attempt 1
```

### Step 5: 修复循环（最多 3 次）

1. 汇总所有问题
2. 启动修复子代理
3. 修复后重新审查
4. 3 次后仍有问题 → 汇报失败

## CLI 命令

```bash
# 获取 PR 信息
python3 pr_gate.py --get-pr --number 123

# 启动审查
python3 pr_gate.py --review --number 123

# 检查审查结果
python3 pr_gate.py --check-results --number 123

# 合并 PR
python3 pr_gate.py --merge-pr --number 123

# 修复循环
python3 pr_gate.py --fix-loop --number 123 --attempt 1

# 完整流程
python3 pr_gate.py --full-pipeline --number 123
```

## 输出格式

### 审查通过

```
✅ PR #123 审查通过

**审查结果：**
| 审查者 | 结果 | 评论数 |
|--------|------|--------|
| Security | ✅ approve | 0 |
| Quality | ✅ approve | 2 |
| Logic | ✅ approve | 1 |

**CI 状态:** ✅ 通过

正在合并到 main...
```

### 需要修复

```
⚠️ PR #123 需要修复

**问题汇总：**
| 审查者 | 问题 |
|--------|------|
| Security | 输入验证缺失 (HIGH) |
| Quality | 缺少单元测试 (MEDIUM) |

启动修复流程 (尝试 1/3)...
```

### 最终失败

```
❌ PR #123 修复失败

经过 3 次修复尝试，以下问题仍未解决：

1. [Security] 输入验证缺失
   - 位置: dev_workflow.py:45
   - 描述: 用户输入未经过验证直接使用

请人工介入处理。
```

## 与其他技能的协作

| 技能 | 协作方式 |
|------|----------|
| **dev-workflow** | PR 创建后触发审查 |
| **Gitea CI** | 等待 CI 通过后才合并 |

## 注意事项

1. 审查子代理必须独立运行，互不干扰
2. 修复循环有明确的上限（3 次）
3. 最终失败必须汇报详细问题
4. 合并前必须确认 CI 通过