# Release Notes 完整生成示例

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **适用场景：** AI Agent 端到端生成 Release Notes，从数据收集到发布。

以 `zzx-coder/gitlink-cli` 项目从 `v1.0.0` 到 `v1.1.0` 为例。

## 完整流程

### 第一步：确定版本范围

```bash
# 获取已有 release
gitlink-cli release +list --format json

# 返回示例（截取关键字段）：
# {
#   "ok": true,
#   "data": {
#     "releases": [
#       { "tag_name": "v1.0.0", "created_at": "2026-05-01", ... },
#       ...
#     ]
#   }
# }

# AI 据此确定：PREV_VERSION = "v1.0.0"，NEW_VERSION = "v1.1.0"
```

### 第二步：收集 commits

```bash
gitlink-cli api GET /:owner/:repo/compare/v1.0.0...v1.1.0 --format json

# 从返回中提取 commits 列表，每个 commit 含：
# - commit.message (提交信息)
# - commit.author.name (作者)
# - sha (提交 SHA)
```

### 第三步：收集已合并 PR

```bash
gitlink-cli pr +list --state merged --format json

# AI 筛选 merged_at >= "2026-05-01"（v1.0.0 发布时间）的 PR
# 提取每个 PR 的 title、number、author.login
```

### 第四步：收集已关闭 Issue

```bash
gitlink-cli issue +list --state closed --format json

# AI 筛选 closed_at >= "2026-05-01" 的 Issue
# 提取每个 Issue 的 subject、project_issues_index、issue_tags
```

### 第五步：AI 分类

AI 根据 [分类规则](../references/classify-rules.md) 对收集到的数据分类：

```
新功能:
  - 支持批量 Issue 操作 (#12) (@zhangsan)
  - 新增 uninstall 命令 (#11) (@lisi)

Bug 修复:
  - 修复 URL 解析异常 (#10) (@wangwu)

功能改进:
  - 重构自动部署配置 (camelliamc)

文档:
  - 更新分支映射说明 (camelliamc)
```

### 第六步：生成 Notes 并确认

AI 套用标准模板生成草稿并展示给用户：

```markdown
# 🎉 Release v1.1.0

## 📊 变更统计
- **新功能**: 2 个
- **Bug 修复**: 1 个
- **功能改进**: 1 个
- **破坏性变更**: 0 个

## ✨ 新功能
- 支持批量 Issue 操作 (#12) (@zhangsan)
- 新增 uninstall 命令 (#11) (@lisi)

## 🐛 Bug 修复
- 修复 URL 解析异常 (#10) (@wangwu)

## 🔧 功能改进
- 重构自动部署配置 (camelliamc)

## 🙏 贡献者
zzx-coder, camelliamc

---
**完整变更日志**: https://www.gitlink.org.cn/zzx-coder/gitlink-cli/compare/v1.0.0...v1.1.0
```

### 第七步：用户确认后发布

```bash
gitlink-cli release +create \
  --tag v1.1.0 \
  --name "v1.1.0" \
  --body "# 🎉 Release v1.1.0

## 📊 变更统计
- **新功能**: 2 个
- **Bug 修复**: 1 个
- **功能改进**: 1 个
- **破坏性变更**: 0 个

## ✨ 新功能
- 支持批量 Issue 操作 (#12) (@zhangsan)
- 新增 uninstall 命令 (#11) (@lisi)

## 🐛 Bug 修复
- 修复 URL 解析异常 (#10) (@wangwu)

## 🔧 功能改进
- 重构自动部署配置 (camelliamc)

## 🙏 贡献者
zhangsan, lisi, wangwu, camelliamc

---
**完整变更日志**: https://www.gitlink.org.cn/zzx-coder/gitlink-cli/compare/v1.0.0...v1.1.0"
```

## AI Agent 执行要点

1. **自动解析 `--owner` / `--repo`**：在仓库目录下执行，CLI 自动从 git remote 解析
2. **始终使用 `--format json`**：所有命令加此参数，便于 AI 解析返回值
3. **时间筛选**：用上一个 Release 的 `created_at` 作为 PR/Issue 的时间筛选基线
4. **去重**：PR 和 Issue 描述同一变更时合并为一条
5. **确认优先**：生成 Notes 后必须展示给用户，收到确认才执行 `release +create`

## References

- [SKILL.md](../SKILL.md) — 工作流和模板总览
- [collect-data](../references/collect-data.md) — 数据收集详细说明
- [classify-rules](../references/classify-rules.md) — 分类规则
- [generate-and-publish](../references/generate-and-publish.md) — 生成和发布
