feat(ci): add AI-powered release notes generation

[XiaoSeS]

Summary

Add automated release notes generation using GitHub Models (GPT-4o-mini) with zero configuration required.

Features

• AI-powered content generation: Automatically extracts highlights, categorizes changes, and rewrites technical jargon into user-friendly language
• Zero configuration: Uses GitHub Models API by default (free, no API key needed)
• Bilingual support: English release notes
• Fallback mode: Falls back to conventional commit grouping if LLM unavailable
• Flexible triggers:
  • Automatic: Push tag (e.g., git push origin v0.3.0)
  • Manual: GitHub Actions workflow dispatch

Implementation

• .github/release-template.md - Release notes template
• .github/scripts/release-notes-generator.ts - Core logic (collect commits, LLM generation, fallback)
• .github/scripts/release-notes-config.ts - Configuration reader
• .github/scripts/release-notes.ts - Entry point
• .github/workflows/release-notes.yml - GitHub Actions workflow
• Extended github.ts and issue-llm-provider.ts with release-related methods

Testing

Local dry-run tested with v0.2.4:

deno run --allow-env --allow-net --allow-run --allow-read \
  .github/scripts/release-notes.ts \
  --owner iflytek --repo skillhub --tag v0.2.4 --dry-run

Output includes:

• ✅ Highlights section (2-4 key changes)
• ✅ Breaking Changes (with migration guide if applicable)
• ✅ Features, Bug Fixes, Performance, Documentation, Chore sections
• ✅ Contributors list
• ✅ Full changelog link

Next Steps

After merge, test cloud execution:

1. Go to Actions → AI Release Notes → Run workflow
2. Input tag: v0.2.4
3. Verify draft release is created with proper formatting
4. Delete test draft (v0.2.4 already has official release)

Future releases will trigger automatically on tag push.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[XiaoSeS]

整体原理

架构概览

Tag Push/Manual Trigger
         ↓
GitHub Actions Workflow
         ↓
    Deno Script
         ↓
   ┌─────┴─────┐
   ↓           ↓
Git Log    GitHub API
   ↓           ↓
Commits    PR Info
   ↓           ↓
   └─────┬─────┘
         ↓
  Change Analysis
         ↓
   GitHub Models
   (GPT-4o-mini)
         ↓
  Markdown Output
         ↓
 GitHub Draft Release

---

核心流程详解

1. 数据收集阶段

输入： v0.3.0 (新 tag) 和 v0.2.4 (上一个 tag)

操作：

# 获取两个 tag 之间的所有 commits
git log v0.2.4..v0.3.0 --format="%H|%s|%an"

输出示例：

abc123|feat(auth): add OAuth support|Alice
def456|fix(api): handle null response|Bob

去重逻辑：

• 排除 Revert "xxx" 及其对应的原始 commit
• 排除 Merge pull request / Merge branch 等合并 commit
• 通过 GitHub API 查询每个 commit 关联的 PR 号
• 同一个 PR 的多个 commits 合并为一条记录

---

2. 数据结构化

Conventional Commit 解析：

"feat(auth): add OAuth support" 
  → { type: "feat", scope: "auth", description: "add OAuth support" }

"fix: handle null response"
  → { type: "fix", scope: "", description: "handle null response" }

关联 PR 信息：

{
  type: "feat",
  scope: "auth",
  description: "add OAuth support",
  prNumber: 123,
  prTitle: "Add OAuth 2.0 authentication",  // 优先使用 PR 标题
  authors: ["Alice", "Bob"],
  commits: ["abc123", "def456"]
}

---

3. LLM 生成阶段

System Prompt（指令）：

你是产品经理和技术文档专家。
将技术变更列表改写为用户友好的 Release Notes。

要求：
1. 严格遵循模板结构
2. 空 section 删除
3. 技术术语 → 用户语言
4. 提取 2-4 条核心亮点
5. Breaking Changes 加迁移指南
...

User Prompt（数据）：

Version: v0.3.0
Previous version: v0.2.4
Repository: iflytek/skillhub

Change list:
- feat(auth): add OAuth support (#123) by @Alice
- fix(api): handle null response (#124) by @Bob
- perf(db): optimize query performance (#125) by @Charlie
...

LLM 处理：

1. 分析变更类型和影响范围
2. 识别最重要的 2-4 个变更作为 Highlights
3. 检测是否有 Breaking Changes
4. 将技术描述改写为用户友好语言：
   • feat(auth): add OAuth support → "Added OAuth 2.0 authentication for secure third-party login"
   • perf(db): optimize query → "Improved database performance for faster page loads"
5. 按模板结构组织输出

输出（Markdown）：

# SkillHub v0.3.0

This release focuses on authentication improvements and performance optimizations.

## 🌟 Highlights
- Added OAuth 2.0 authentication for secure third-party login
- Improved database performance by 50%
...

## ✨ Features
- Added OAuth 2.0 authentication by @Alice in #123
...

---

4. Fallback 模式（无 LLM）

触发条件：

• 环境变量未配置
• LLM API 调用失败
• 使用 --skip-llm 参数

处理逻辑：

// 简单按 type 分组
{
  "feat": [change1, change2],
  "fix": [change3, change4],
  "docs": [change5]
}

// 生成基础 Markdown
## ✨ Features
- add OAuth support in #123 by @Alice
- add email verification in #124 by @Bob

## 🐛 Bug Fixes
- handle null response in #125 by @Charlie

缺点：

• 无 Highlights 提炼
• 无 Breaking Changes 识别
• 描述保持技术化
• 无智能分类优化

---

5. GitHub Release 创建

API 调用：

POST /repos/iflytek/skillhub/releases
{
  "tag_name": "v0.3.0",
  "name": "v0.3.0",
  "body": "# SkillHub v0.3.0\n\n...",
  "draft": true,        // 关键：创建为 draft
  "prerelease": false
}

Draft 状态的作用：

• ✅ 可以预览和修改
• ✅ 不触发 publish-images.yml
• ✅ 不发送通知给 watchers
• ✅ 可以随时删除重新生成

Publish 后：

• 触发 on: release: types: [published] 的 workflows
• 发送通知给 repository watchers
• 出现在 Releases 页面（非 draft 列表）

---

技术栈

组件	技术	作用
运行时	Deno	执行 TypeScript 脚本
Git 操作	git log	获取 commit 历史
GitHub API	REST API	查询 PR、创建 Release
LLM	GitHub Models (GPT-4o-mini)	生成用户友好内容
认证	github.token	免费、自动注入
模板	Markdown	定义输出结构

---

配置优先级

RELEASE_NOTES_LLM_* 环境变量
         ↓ (如果未设置)
ISSUE_TRIAGE_LLM_* 环境变量
         ↓ (如果未设置)
默认值（GitHub Models）

默认配置：

{
  baseUrl: "https://models.inference.ai.azure.com",
  apiKey: github.token,  // 自动注入
  model: "gpt-4o-mini",
  temperature: 0.2       // 低温度 = 更稳定输出
}

---

为什么这样设计

1. Draft 机制 → 允许人工审核和修改
2. LLM + Fallback → 保证可用性
3. GitHub Models → 零成本、零配置
4. Conventional Commits → 自动分类基础
5. PR 关联 → 去重 + 更好的描述
6. 模板驱动 → 输出格式一致

这就是整个系统的工作原理。

[XiaoSeS]

使用方法（精简版）

🚀 最常用：自动发布

# 1. 创建并推送 tag
git tag v0.3.0
git push origin v0.3.0

# 2. 等待 1-2 分钟，自动生成 draft release

# 3. 打开 GitHub 检查并发布
# https://github.com/iflytek/skillhub/releases
# 点击 "Publish release"

就这么简单！

---

🔍 提前预览（推送前先看看）

GUI 方式：

1. 本地创建 tag：git tag v0.3.0（不推送）
2. 打开 https://github.com/iflytek/skillhub/actions/workflows/release-notes.yml
3. 点击 "Run workflow" → 输入 v0.3.0 → 运行
4. 去 Releases 查看 draft
5. 满意后：git push origin v0.3.0

终端方式：

# 只预览，不创建 release
export RELEASE_NOTES_LLM_BASE_URL="https://models.inference.ai.azure.com"
export RELEASE_NOTES_LLM_API_KEY=$(gh auth token)
export RELEASE_NOTES_LLM_MODEL="gpt-4o-mini"
export GH_TOKEN=$(gh auth token)

deno run --allow-env --allow-net --allow-run --allow-read \
  .github/scripts/release-notes.ts \
  --owner iflytek --repo skillhub \
  --tag v0.3.0 --dry-run

---

⚙️ 配置（可选）

默认零配置，使用 GitHub Models 免费 API。

如需自定义，在 GitHub 仓库设置：

• Variables: RELEASE_NOTES_LLM_BASE_URL, RELEASE_NOTES_LLM_MODEL
• Secrets: RELEASE_NOTES_LLM_API_KEY

---

✅ 检查清单

Draft release 应包含：

• ✅ Highlights（2-4 条核心亮点）
• ✅ Breaking Changes（如果有）
• ✅ Features/Bug Fixes/Performance 分类清晰
• ✅ 用户友好的描述（非技术术语）
• ✅ PR 链接 (Feat 0315 #123) 和贡献者 (@username)

---

推荐流程： Push tag → 等待 → 检查 draft → Publish ✨

[XiaoSeS]

修改模板内容

📝 编辑模板文件

# 模板位置
.github/release-template.md

🎨 可以修改的内容

1. 调整 Section 顺序

# 把 Breaking Changes 放到最前面
## 🚨 Breaking Changes
## 🌟 Highlights
## ✨ Features
...

2. 添加新 Section

## 🔐 Security
- {{Security fixes}} by @author in #PR

## 🌍 Internationalization
- {{i18n changes}} by @author in #PR

3. 修改 Emoji 和标题

## 💡 New Features  # 改用灯泡
## 🐞 Fixes         # 改用瓢虫

4. 调整内容格式

# 改为表格格式
## ✨ Features
| Feature | PR | Author |
|---------|----|----|
| {{description}} | #PR | @author |

5. 添加固定内容

## 📦 Installation
\`\`\`bash
npm install @iflytek/skillhub@{{version}}
\`\`\`

## ⚠️ Known Issues
- Issue #123: ...

🔄 生效方式

方式 1: 直接修改（推荐）

# 1. 编辑模板
vim .github/release-template.md

# 2. 提交
git add .github/release-template.md
git commit -m "docs: update release notes template"
git push

# 3. 下次生成时自动使用新模板

方式 2: 测试后再提交

# 1. 修改模板
vim .github/release-template.md

# 2. 本地测试
deno run --allow-env --allow-net --allow-run --allow-read \
  .github/scripts/release-notes.ts \
  --owner iflytek --repo skillhub \
  --tag v0.2.4 --dry-run

# 3. 确认效果后提交
git add .github/release-template.md
git commit -m "docs: update release notes template"
git push

💡 模板变量

可用的占位符：

• {{version}} → 当前版本号（如 v0.3.0）
• {{prev_tag}} → 上一个版本号（如 v0.2.4）
• {{tag}} → 同 version

📋 示例：添加升级指南

# SkillHub {{version}}

{{One-line summary}}

## 🌟 Highlights
...

## 📖 Upgrade Guide

### From {{prev_tag}} to {{version}}

1. Update dependencies:
   \`\`\`bash
   npm update
   \`\`\`

2. Run migrations:
   \`\`\`bash
   npm run migrate
   \`\`\`

3. Update configuration:
   - Add `NEW_CONFIG=value` to `.env`

## 🚨 Breaking Changes
...

⚙️ 高级：修改 Prompt

如果想改变 AI 的生成风格，编辑：

.github/scripts/release-notes-generator.ts

找到 systemPrompt，修改指令：

const systemPrompt = `You are a senior product manager...

Requirements:
1. Use more technical language  // 改为技术化
2. Add code examples for each feature  // 添加代码示例
3. Include performance metrics  // 包含性能指标
...
`;

---

总结： 直接编辑 .github/release-template.md，提交后下次生成自动生效。