---
name: gitlink-quality-gate
version: 1.0.0
description: "代码质量看门人：PR 提交 → 深度审查 → CI 检查 → 质量评分 → 自动合并/反馈建议。串联 pr-deep-review 与 CI 检查，实现代码质量自动化门禁。"
metadata:
  requires:
    bins: ["gitlink-cli", "jq"]
  cliHelp: "gitlink-cli pr --help / gitlink-cli ci --help"
---

# gitlink-quality-gate（代码质量看门人）

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证、全局参数和 API 注意事项。
>
> **CRITICAL — 所有 GitLink 操作必须使用 `gitlink-cli`，禁止使用 `gh`（GitHub CLI）操作 GitLink 资源。**

## 说明

本 Skill 实现 PR 的自动化质量门禁，串联 **深度代码审查** 与 **CI 状态检查**，对每个 PR 进行量化评分，根据评分结果决定是否自动合并。

### 质量门禁流程

```mermaid
flowchart LR
    A[新 PR 提交] --> B[Phase 1: PR 采集]
    B --> C[Phase 2: 深度审查]
    C --> D[Phase 3: CI 检查]
    D --> E[Phase 4: 门禁决策]
    E --> F{评分 ≥ 70 且 CI 通过?}
    F -->|是| G[自动合并]
    F -->|否| H[反馈修改建议]
```

### 质量评分模型

```
质量总分 = CodeReview 评分 × 40% + CI 状态 × 30% + 设计一致性 × 30%

评分细则：
- CodeReview 评分（0-100）：根据 Critical/Warning/Suggestion 数量综合计算
  - 每个 Critical -20 分，每个 Warning -10 分，每个 Suggestion -3 分
  - 起始 100 分，扣减后为最终得分
- CI 状态（0 或 100）：全部通过 = 100，有失败 = 0
- 设计一致性（0-100）：PR 描述与代码变更的匹配度，AI 评估

门槛：
- ≥ 70 分 + CI 通过 → 自动合并（需最终确认）
- < 70 分 或 CI 失败 → 阻塞并给出具体修改建议
```

---

## Phase 1：PR 采集

**参考 Skill：** [`../gitlink-pr/SKILL.md`](../gitlink-pr/SKILL.md)

```bash
# 1. 列出所有打开的 PR
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --format json

# 2. 筛选出真实 PR（pull_request_status=0）
# 3. 按创建时间排序，优先处理最早的 PR
```

---

## Phase 2：深度审查

**参考 Skill：** [`../gitlink-pr-deep-review/SKILL.md`](../gitlink-pr-deep-review/SKILL.md)

```bash
# 1. 获取 PR 详情
gitlink-cli pr +view --id <pr_id> --format json

# 2. 获取变更文件列表
gitlink-cli pr +files --id <pr_id> --format json

# 3. 获取补丁版本差异
gitlink-cli pr +versions --id <pr_id> --format json
gitlink-cli pr +version-diff --id <pr_id> --version-id <version_id> --format json

# 4. 查看已有评审（避免重复）
gitlink-cli pr +reviews --id <pr_id> --format json
```

### AI 审查维度

| 维度 | 检查项 | 权重 |
|------|--------|------|
| 代码质量 | 命名规范、错误处理、空指针、资源泄漏、并发安全 | 40% |
| 功能正确性 | 逻辑正确性、边界条件、异常路径覆盖 | 30% |
| 代码风格 | 与项目现有风格一致性、格式化 | 15% |
| 测试覆盖 | 是否包含测试、测试覆盖率、测试质量 | 15% |

---

## Phase 3：CI 状态检查

**参考 Skill：** [`../gitlink-ci/SKILL.md`](../gitlink-ci/SKILL.md)

```bash
# 1. 获取 CI 构建列表
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json

# 2. 获取 CI 运行记录
gitlink-cli ci +runs --owner <owner> --repo <repo> --format json

# 3. 筛选与 PR 分支相关的构建
# 4. 判断 CI 是否全部通过
```

### CI 状态判定

| CI 状态 | 评分 | 说明 |
|---------|------|------|
| 全部通过 | 100 | 所有构建步骤成功 |
| 部分通过 | 50 | 部分步骤成功（需人工判断） |
| 有失败 | 0 | 存在失败步骤，阻塞合并 |

---

## Phase 4：门禁决策

### 决策逻辑

```
输入：
  - code_review_score    (0-100)
  - ci_passing           (true/false)
  - design_consistency   (0-100)

计算：
  quality_score = code_review_score × 0.4 
                + (ci_passing ? 100 : 0) × 0.3 
                + design_consistency × 0.3

决策：
  if quality_score >= 70 AND ci_passing == true:
    → 通过门禁，可自动合并
  else:
    → 阻塞门禁，生成修改建议
```

### 命令示例

```bash
# 通过门禁 — 提交评审 + 合并
gitlink-cli pr +review --id <pr_id> --status approved --content "<review_summary>"
gitlink-cli pr +merge --id <pr_id> --do squash

# 阻塞门禁 — 提交评审含修改建议
gitlink-cli pr +review --id <pr_id> --status common --content "<fix_suggestions>"
```

---

## 可复现脚本

本 Skill 提供可直接执行的 Bash 脚本，位于 `scripts/` 目录：

| 脚本 | 功能 | 使用方式 |
|------|------|----------|
| `01-collect-prs.sh` | Phase 1 PR 采集 | `bash 01-collect-prs.sh <owner> <repo>` |
| `02-deep-review.sh` | Phase 2 深度审查 | `bash 02-deep-review.sh <owner> <repo> <pr_id>` |
| `03-ci-check.sh` | Phase 3 CI 检查 | `bash 03-ci-check.sh <owner> <repo> <pr_id>` |
| `04-quality-gate-decision.sh` | Phase 4 门禁决策 | `bash 04-quality-gate-decision.sh <owner> <repo> <pr_id>` |
| `quality-gate-full.sh` | 全流程串联（遍历所有 PR） | `bash quality-gate-full.sh <owner> <repo>` |

**所有脚本默认 dry-run 模式**，确认后切换：

```bash
# Dry-run（默认，安全）
DRY_RUN=true bash scripts/quality-gate-full.sh z2_cc gitlink-cli

# 实际执行
DRY_RUN=false bash scripts/quality-gate-full.sh z2_cc gitlink-cli
```

---

## 注意事项

1. **dry-run 优先**：`pr +merge` 和 `pr +review` 默认不实际执行
2. **避免重复评审**：检查 `pr +reviews` 输出，跳过已评审的 PR
3. **CI 超时**：如果 CI 仍在运行中，标记为 pending 并等待下次检查
4. **关键 PR 例外**：涉及安全修复、架构变更的 PR 建议跳过自动合并
5. **合并方式**：默认使用 squash 合并，保持提交历史整洁
