# 代码质量看门人工作流 — 端到端示例

**场景**：项目维护者希望自动化 PR 审查流程：新 PR 自动触发代码审查、CI 检查，质量达标后自动合并。

## 前置条件

- `gitlink-cli` 已安装并登录
- 目标仓库已确认（示例使用 `z2_cc/gitlink-cli`）
- 本地已 clone 目标仓库

## 工作流步骤

### Step 1：采集待审 PR

```bash
# 1.1 获取所有打开的 PR
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state open --format json
```

**输出示例：**
```json
{
  "ok": true,
  "data": [
    {"id": 5, "title": "feat: 添加 Wiki 管理功能", "pull_request_status": 0, "created_at": "2026-06-20"},
    {"id": 6, "title": "fix: 修复 Issue 列表分页", "pull_request_status": 0, "created_at": "2026-06-22"}
  ]
}
```

### Step 2：深度代码审查

对每个 PR 执行深度审查：

```bash
# 2.1 获取 PR 详情
gitlink-cli pr +view --id 5 --format json

# 2.2 获取变更文件
gitlink-cli pr +files --id 5 --format json

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

# 2.4 检查已有评审（避免重复审查）
gitlink-cli pr +reviews --id 5 --format json
```

**输出示例（version-diff）：**
```json
{
  "ok": true,
  "data": {
    "files": [
      {"path": "shortcuts/wiki/wiki.go", "additions": 45, "deletions": 0, "status": "added"},
      {"path": "skills/gitlink-wiki/SKILL.md", "additions": 30, "deletions": 0, "status": "added"}
    ],
    "stat": "+75/-0"
  }
}
```

**AI 审查结果示例：**
```
CodeReview评分: 85/100
  - 代码结构清晰，命名规范 ✅
  - 错误处理完善 ✅
  - 建议添加更详细的注释 (-3)
  - 建议添加单元测试 (-15)

Critical: 0, Warning: 1, Suggestion: 2
```

### Step 3：CI 状态检查

```bash
# 3.1 获取 CI 构建列表
gitlink-cli ci +builds --owner z2_cc --repo gitlink-cli --format json

# 3.2 获取 CI 运行记录
gitlink-cli ci +runs --owner z2_cc --repo gitlink-cli --format json
```

**输出示例：**
```json
{
  "ok": true,
  "data": {
    "builds": [
      {"id": 101, "branch": "refs/pull/5/head", "status": "success", "commit_sha": "abc123"}
    ]
  }
}
```

### Step 4：质量门禁决策

**质量评分计算：**
```
CodeReview评分 = 85 (实际扣分后)
CI 状态 = 100 (全部通过)
设计一致性 = 80 (PR 描述与变更匹配良好)

质量总分 = 85 × 0.4 + 100 × 0.3 + 80 × 0.3
         = 34 + 30 + 24
         = 88

门槛 ≥ 70 且 CI 通过 → ✅ 通过门禁
```

```bash
# 4.1 （dry-run 模式）只输出决策，不实际执行
echo "[DRY-RUN] PR #5 质量评分: 88/100"
echo "[DRY-RUN] CI 状态: 全部通过"
echo "[DRY-RUN] 门禁决策：✅ 通过"
echo "[DRY-RUN] 将执行: pr +review --status approved + pr +merge --do squash"
```

**实际执行（DRY_RUN=false）：**
```bash
# 提交评审通过
gitlink-cli pr +review --id 5 --status approved --content "✅ 代码质量审查通过

评分：88/100（CodeReview 85 + CI 100 + 设计一致性 80）
无 Critical 问题，1 个 Warning 已确认无影响。

**建议后续改进：**
- 补充单元测试
- 完善函数注释"

# 自动合并
gitlink-cli pr +merge --id 5 --do squash
```

### Step 5：阻塞场景示例

如果质量评分不达标的 PR：

```bash
echo "[DRY-RUN] PR #X 质量评分: 45/100"
echo "[DRY-RUN] CI 状态: ❌ 失败"
echo "[DRY-RUN] 门禁决策：❌ 阻塞"
echo "[DRY-RUN] 将执行: pr +review --status common + 修改建议"

# 实际执行
gitlink-cli pr +review --id X --status common --content "❌ 质量门禁未通过

**问题清单：**
1. Critical: 存在空指针风险 (file.go:42)
2. CI 构建失败：单元测试未通过
3. 缺少必要测试覆盖

请修复以上问题后重新提交。"
```

## 完整命令速览

```bash
# 采集 PR
gitlink-cli pr +list --state open --format json

# 深度审查
gitlink-cli pr +view --id <id> --format json
gitlink-cli pr +files --id <id> --format json
gitlink-cli pr +versions --id <id> --format json
gitlink-cli pr +version-diff --id <id> --version-id <v> --format json

# CI 检查
gitlink-cli ci +builds --format json

# 门禁操作
gitlink-cli pr +review --id <id> --status approved --content "<msg>"
gitlink-cli pr +merge --id <id> --do squash
gitlink-cli pr +review --id <id> --status common --content "<fix_suggestions>"
```

## 注意事项

- 自动合并不适用于：安全修复、架构变更、大规模重构
- 建议先对小 PR 启用自动合并，逐步积累信任
- 每次自动合并后记录操作日志，便于回溯
