# 收集变更数据

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。

收集 Release Notes 所需的三类数据：版本范围、commits、PRs 和 Issues。

## 命令

### 步骤 1：确定版本范围

```bash
# 获取已有 release 列表，找到上一个版本 tag
gitlink-cli release +list --format json
# 从返回的 releases 中提取最后一个 tag_name 作为 PREV_VERSION
# 用户指定或 AI 推断新版本号 NEW_VERSION
```

### 步骤 2：获取 commits（平台 compare API）

```bash
# 获取两个 tag 之间的 commit 比较
gitlink-cli api GET /:owner/:repo/compare/{PREV_VERSION}...{NEW_VERSION} --format json

# 也可用查询参数格式
gitlink-cli api GET /v1/:owner/:repo/compare.json --query "from={PREV_VERSION}&to={NEW_VERSION}" --format json
```

返回数据包含：`commits`（提交列表含 message/author/date/sha）、`total_commits`（提交总数）、`files`（变更文件）等。

### 步骤 3：获取已合并的 PR

```bash
# 获取已合并的 PR 列表
gitlink-cli pr +list --state merged --format json

# 从返回的 PRs 中按 merged_at 时间筛选：
# 只保留 merged_at >= 上一个版本发布时间的 PR
```

返回数据包含：每个 PR 的 `title`、`number`、`author`、`merged_at`、`pull_request_number` 等。

### 步骤 4：获取已关闭的 Issue

```bash
# 获取已关闭的 Issue 列表
gitlink-cli issue +list --state closed --format json

# 从返回的 Issues 中按 closed_at 时间筛选：
# 只保留 closed_at >= 上一个版本发布时间的 Issue
```

返回数据包含：每个 Issue 的 `subject`、`project_issues_index`、`issue_tags`（标签）、`author`、`closed_at` 等。

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--format` | 否 | 始终建议 `json`，便于 AI 解析 |
| `--state` | 否 | PR: `merged`；Issue: `closed` |
| `--page` | 否 | 大量数据时分页获取 |
| `--limit` | 否 | 每页条数 |

## 数据整合

收集完成后，AI 整合三类数据：

1. **Commits** → 提取 commit message 第一行作为变更摘要，附作者名
2. **PRs** → 用 `title`、`number`、`author.login` 生成条目：`- 功能描述 (#PR编号) (@作者)`
3. **Issues** → 用 `subject`、`project_issues_index`、`author.login` 生成条目：`- Issue 描述 (#编号) (@作者)`

时间筛选逻辑：从 `release +list` 获取上一个版本的发布时间，只取该时间之后的 PR/Issue。

## 注意事项

- 如果是**第一个版本**（无上一版本），只收集当前版本时间范围内的 PR/Issue，commits 用全量最近提交
- `compare` API 的 tag 需要真实存在，否则返回 404
- PR 和 Issue 的返回可能超过单页，注意分页获取全部数据
- `--owner` / `--repo` 在仓库目录下可自动解析

## References

- [classify-rules](classify-rules.md) — 收集完成后对变更进行分类
- [generate-and-publish](generate-and-publish.md) — 生成 Notes 并发布
- [gitlink-release](../gitlink-release/SKILL.md) — Release 操作
