gitlink-cli/skills/gitlink-pr/examples/pr-workflow.md

# 示例：Pull Request 完整生命周期（真实数据）

> 本示例基于 `chroe/gitlink-cli` 项目于 2026-06-13 在 Claude Code 中实际执行。
> 展示完整的 PR 工作流：创建分支 → 推送 → 创建 PR → 查看详情 → 评论 → 合并。

---

## Step 1：创建特性分支并提交

```bash
# 从最新 master 创建分支
git checkout -b test/pr-workflow-demo

# 做一个小改动
echo "> This line is for PR workflow testing." >> README.md
git add README.md
git commit -m "test: PR workflow demo for skill documentation"
```

### Step 2：推送分支到远程

```bash
git push origin test/pr-workflow-demo
```

### Step 3：创建 PR

```bash
gitlink-cli pr +create \
  --owner chroe --repo gitlink-cli \
  --title "test: PR workflow demo for skill documentation" \
  --body "## 目的\n\n创建测试 PR，用于 gitlink-pr Skill 的 examples 文档编写。\n\n## 改动\n\n在 README.md 末尾添加一行测试文本。" \
  --head test/pr-workflow-demo \
  --base master \
  --format json
```

**真实输出：**

```json
{
  "ok": true,
  "data": {
    "id": 144232,
    "pull_request_number": 1,
    "pull_request_id": 15694,
    "name": "test: PR workflow demo for skill documentation",
    "pull_request_status": 0,
    "pull_request_staus": "open",
    "pull_request_base": "master",
    "pull_request_head": "test/pr-workflow-demo",
    "author_login": "caoweiqiong",
    "author_name": "CWQ",
    "pr_time": "1分钟前"
  }
}
```

**关键字段：**
- `pull_request_number`: 1 — 即网页 URL 中的序号（`/pulls/1`）
- `pull_request_status`: 0=Open, 1=Merged, 2=Closed

### Step 4：查看 PR 详情

```bash
gitlink-cli pr +view --owner chroe --repo gitlink-cli --id 1 --format json
```

**真实输出摘要：**

```json
{
  "ok": true,
  "data": {
    "author": {
      "id": 141645,
      "login": "caoweiqiong",
      "name": "CWQ"
    },
    "commits_count": 1,
    "files_count": 1,
    "comments_count": 0,
    "issue": {
      "subject": "test: PR workflow demo for skill documentation",
      "description": "## 目的\n\n创建测试 PR...",
      "created_at": "2026-06-13 10:15",
      "issue_status": "新增"
    },
    "pull_request": {
      "base": "master",
      "head": "test/pr-workflow-demo",
      "mergeable": true,
      "merged": false,
      "merged_at": null,
      "merge_commit_sha": null,
      "pull_request_staus": "open",
      "status": 0
    }
  }
}
```

### Step 5：查看变更文件

```bash
gitlink-cli pr +files --owner chroe --repo gitlink-cli --id 1
```

**真实输出摘要：**

```json
{
  "ok": true,
  "data": {
    "total_addition": 2,
    "total_deletion": 0,
    "files_count": 1,
    "files": [
      {
        "name": "README.md",
        "addition": 2,
        "deletion": 0,
        "sha": "60cb293913b8051cd9456457d93165ac1b2ff3ce"
      }
    ]
  }
}
```

### Step 6：添加评论

```bash
gitlink-cli pr +comment --owner chroe --repo gitlink-cli --id 1 \
  --body "LGTM — 测试 PR，准备合并以采集 Skill 文档所需的真实数据。"
```

**真实输出：**

```json
{
  "ok": true,
  "data": {
    "id": 475956,
    "notes": "LGTM — 测试 PR，准备合并以采集 Skill 文档所需的真实数据。",
    "created_at": "2026-06-13 10:15",
    "user": { "login": "caoweiqiong", "name": "CWQ" }
  }
}
```

### Step 7：合并 PR

```bash
gitlink-cli pr +merge --owner chroe --repo gitlink-cli --id 1
```

**真实输出：**

```json
{
  "ok": true,
  "data": {
    "message": "合并成功",
    "status": 1
  }
}
```

### Step 8：确认合并后状态

```bash
gitlink-cli pr +view --owner chroe --repo gitlink-cli --id 1 --format json
```

**合并后关键字段变化：**

```json
{
  "pull_request": {
    "merged": true,
    "merged_at": "2026-06-13T10:17:07+08:00",
    "merge_commit_sha": "5bec1e5bf140915162baa65f3fb3a53f725e7c0c",
    "pull_request_staus": "merged",
    "status": 1
  }
}
```

---

## PR 状态值映射

| `pull_request_status` | `pull_request_staus` | 含义 |
|:---:|---|---|
| 0 | open | 开放中 |
| 1 | merged | 已合并 |
| 2 | closed | 已关闭（未合并） |

## 关键注意事项

1. **`--id` 参数**：使用 `pull_request_number`（网页 URL `/pulls/N` 中的序号），不是数据库内部 ID
2. **`--head` 格式**：同仓库内直接用分支名（如 `test/pr-workflow-demo`）；跨仓库 Fork PR 用 `用户名:分支名`
3. **`--base` 默认分支**：GitLink 通常用 `master`，不是 `main`
4. **PR 必须有代码差异**：源分支和目标分支内容相同时无法创建
5. **合并前建议**：先用 `pr +view` 确认 `mergeable: true`