# Changelog

该 Skill 的变更记录遵循 Keep a Changelog 与语义化版本。

## [Unreleased]

### Changed（变更）
- 规范化 `SKILL.md` 正文骨架，补齐输入、输出、校验、失败恢复和安全边界；发布行为与 CLI 参数保持不变。
- 明确单独生成 Release Notes/历史总结仅输出预览，只有明确发布/创建请求或后续确认才执行远程发布；既有发布流程和 CLI 参数不变。

## [0.1.0] - 2026-09-05

### Added（新增）
- 初始化 GitHub Release 与 Release Notes 生成 Skill 治理元数据。

skill_info:
  name: git-publish-release
  version: "0.1.0"
  description: "当用户明确要求发布项目到 GitHub、创建 GitHub Release 或生成 Release Notes 时使用；明确发布/创建请求才执行远程发布，单独的 notes/历史总结请求仅生成预览，除非随后确认。"
  author: "Bensz Conan"
  category: 发布管理

release:
  default_prerelease: false
  # 明确的“发布项目/创建 Release”请求即视为确认；仅覆盖已有 Release 时再询问。
  require_confirmation: true
  notes_reference: references/release-notes-strategy.md

# GitHub Release 发布

智能分析项目历史变化并生成吸引人的 Release Notes；明确要求发布/创建 Release 时发布到 GitHub，单独请求 notes 或历史总结时仅生成预览，除非随后确认发布。

## ✨ 特性

- 🤖 **智能分析**：AI 驱动的 commit 历史分析，自动提炼核心价值
- 📝 **专业模板**：生成简洁、有效、有煽动性的 Release Notes
- 🚀 **一键发布**：明确要求发布/创建 Release 时自动创建 GitHub Release
- 🎯 **分类清晰**：自动分类新功能、Bug 修复、性能优化等
- 🌐 **联网验证**：与 GitHub API 集成，获取最新 release 信息

## 📋 使用场景

当你需要：
- 发布新版本到 GitHub
- 创建 GitHub Release 并生成 Release Notes
- 推送 tag 并自动创建 release
- 总结版本间的历史变化

## 🚀 快速开始

### 前置要求

1. **GitHub CLI**：需要安装并认证 `gh` CLI
   - 安装：`brew install gh`（macOS）或访问 https://cli.github.com
   - 认证：`gh auth login`

2. **Git 仓库**：项目必须是 Git 仓库，且有 GitHub remote

### 使用方式

在 Claude Code 中使用以下任一方式触发：

```
"帮我发布 v3.0.0 到 GitHub"
"创建一个 GitHub Release，tag 是 v2.5.0"
"发布当前项目到 GitHub，版本 v1.0.0"
"我要 release v4.0.0-beta.1"
```

明确要求发布/创建 Release 时，技能会自动：
1. 确认项目路径和 tag
2. 获取最新 release 信息
3. 分析历史变化
4. 生成专业的 Release Notes
5. 发布到 GitHub

如果只要求生成 Release Notes 或总结历史变化，技能只输出文案预览，不调用 `gh release create`；需要发布时再明确确认。

## 📖 使用示例

### 示例 1：首次发布

```
你：发布 v1.0.0 到 GitHub

技能：检测到这是首次发布，将创建项目第一个 Release。
[生成首次发布专用 Release Notes]
✅ Release 发布成功！
```

### 示例 2：常规版本发布

```
你：发布 v2.3.0

技能：将比较 v2.2.0 和 v2.3.0 之间的变化...
[分析 23 个 commits，生成分类 Release Notes]
✅ Release 发布成功！
```

### 示例 3：预发布版本

```
你：发布 v3.0.0-beta.1

技能：检测到这是预发布版本（beta），将标记为 prerelease。
[生成 Pre-release 专用 Release Notes]
✅ Release 发布成功！
```

### 示例 4：指定项目路径

```
你：为 /path/to/project 发布 v1.5.0

技能：正在处理 /path/to/project...
[在该项目下执行发布流程]
✅ Release 发布成功！
```

## 🎨 Release Notes 风格

生成的 Release Notes 具有以下特点：

### 结构清晰

```
🎉 版本号 - 吸引人的标题
一句话价值定位

🚀 核心亮点
• 亮点1
• 亮点2

✨ 主要更新（分类）
• 更新内容
• 更新内容

📋 完整变更日志
[链接]
```

### 语言风格

- **简洁有力**：每个要点不超过一行
- **价值导向**：强调"为什么"而非仅仅"是什么"
- **情感化表达**：使用"革命性"、"突破性"等词汇
- **数字量化**：用具体数字说明改进幅度
- **用户视角**：用用户能理解的语言

### 自动分类

| 类别 | 图标 | 关键词 |
|------|------|--------|
| 新功能 | ✨ | feat, feature, add, new |
| Bug 修复 | 🐛 | fix, bugfix, resolve |
| 性能优化 | ⚡ | perf, performance, optimize |
| 技术改进 | 🔧 | refactor, improve |
| 文档更新 | 📝 | docs, document, readme |
| 安全更新 | 🔐 | security, fix vulnerability |

## ⚙️ 配置选项

### 认证

通过 `gh auth login` 管理，无需手动配置 token。运行以下命令检查认证状态：

```bash
gh auth status
```

### Git Remote 格式支持

- HTTPS: `https://github.com/owner/repo.git`
- SSH: `git@github.com:owner/repo.git`

## 🛠️ 故障排查

### 问题：gh 未认证

**解决方案**：
```bash
gh auth login
```

### 问题：Tag 不存在

**解决方案**：先创建 tag
```bash
git tag v1.0.0
git push origin v1.0.0
```

### 问题：权限不足

**解决方案**：运行 `gh auth status` 检查认证状态及仓库权限

### 问题：Release 已存在

**解决方案**：技能会询问是否覆盖，选择更新现有 release

## 📚 相关资源

- [SKILL.md](SKILL.md) - 技能核心逻辑
- [Release Notes 生成策略](references/release-notes-strategy.md)
- [Release Notes 模板示例](references/release-templates.md)
- [GitHub CLI 文档](https://cli.github.com/manual/gh_release_create)

## WHICHMODEL - 模型选择最佳实践

**最后更新**：2026-01-25

### 披露信息

- **覆盖厂商**：Anthropic, OpenAI（2/6 = 33%）
- **来源构成**：社区 70%, 官方 20%, 技术博客 10%
- **数据时效**：2024-10 至 2026-01
- **局限性**：未覆盖国产模型，未独立测试 Release Notes 生成质量

---

### 场景化建议

#### 场景 1：标准版本发布（最常见）

**触发条件**：常规版本发布，需要生成 Release Notes

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Haiku 4.5 或 Sonnet 4.5 |
| **推理强度** | low-medium |
| **预期成本** | ~$0.005-0.05/次 |

**理由**：
- Release Notes 生成主要是文本处理和模式匹配任务
- Haiku 成本最低，适合简单版本发布
- Sonnet 在 commit 分类和内容整理上表现更好
- [社区反馈](https://www.reddit.com/r/ClaudeAI/comments/1ocpoye/haiku_45_better_than_sonnet/) 显示 Haiku 在简单任务中表现优异

**避免**：复杂大规模版本（100+ commits）建议用 Sonnet

**来源**：[Haiku System Card](https://www.anthropic.com/claude-haiku-4-5-system-card) + Reddit 社区讨论

---

#### 场景 2：大规模版本发布

**触发条件**：
- 大规模版本（100+ commits）
- 跨越多个功能模块
- 需要深度理解业务价值

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Sonnet 4.5 |
| **推理强度** | medium |
| **预期成本** | ~$0.03-0.15/次 |

**理由**：
- Sonnet 在代码分析和内容整理上表现出色
- 更适合需要"中等复杂度理解"的场景
- [社区对比](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249) 显示 Sonnet 在复杂场景下的优势
- **大规模 commit 历史分析需要一定的推理能力**

**避免**：简单版本（<20 commits）不需要 Sonnet，用 Haiku 即可

**来源**：社区对比讨论 + 官方模型选择指南

---

#### 场景 3：首次发布

**触发条件**：
- 项目首次发布（v1.0.0）
- 需要生成完整的初始介绍
- 需要创造性撰写项目定位

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Sonnet 4.5 |
| **推理强度** | medium |
| **预期成本** | ~$0.05-0.20/次 |

**理由**：
- 首次发布需要理解和总结整个项目
- 需要创造性撰写吸引人的标题和价值定位
- Sonnet 在内容组织和语言表达上更有优势
- **首次发布是项目的"第一印象"，值得投入更多资源**

**避免**：如果不是首次发布，优先使用 Haiku

**来源**：社区反馈 + 官方文档

---

### 对比总结

| 模型 | 最适合 | 最不适合 | 相对成本 | 相对速度 | 推荐度 |
|------|-------|---------|---------|---------|-------|
| **Haiku 4.5** | 小版本发布、常规版本 | 大规模版本、首次发布 | $ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Sonnet 4.5** | 大规模版本、首次发布 | 小版本（浪费） | $$$ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Opus 4.5** | **不推荐** | 所有场景 | $$$$$ | ⭐⭐ | ⭐ |

**说明**：
- Haiku 覆盖 80% 的版本发布场景（小版本、常规版本）
- Sonnet 用于大规模版本（100+ commits）和首次发布
- Opus 对此任务**完全不必要**，成本过高且无性能提升

---

### 通用原则

1. **默认从 Haiku 开始**：80% 的版本发布任务 Haiku 足够，无需升级
2. **复杂度判断**：根据 commit 数量选择模型
   - <20 commits：Haiku
   - 20-100 commits：Haiku 或 Sonnet
   - >100 commits：Sonnet
   - 首次发布：Sonnet
3. **成本敏感**：版本发布是高频操作，Haiku 的成本优势明显
4. **速度优先**：Haiku 的 <1 秒响应时间明显优于 Sonnet 的 3-5 秒
5. **避免过度设计**：Release Notes 生成主要是模式匹配和文本整理，Haiku 完全胜任

---

### ⚠️ 争议点

#### Haiku vs Sonnet：Release Notes 生成真的可以用 Haiku 吗？

| 观点 | 支持者 | 理由 |
|------|-------|------|
| **Haiku 足够** | Reddit 社区 | Release Notes 生成是简单任务，Haiku 在文本处理任务中表现稳定 |
| **Sonnet 更保险** | 部分开发者 | 担心 Haiku 在大规模版本分析时出错 |

**数据支持**：
- [某用户测试](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)：Haiku 在编码任务中匹配 Sonnet 能力，成本降低 80%
- [官方文档](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)：Haiku 专为"高吞吐量、低延迟"场景设计

**建议**：
- **默认使用 Haiku**：小版本和常规版本发布，Haiku 完全胜任
- **仅在以下情况升级 Sonnet**：
  - 大规模版本（>100 commits）
  - 首次发布（需要项目理解和创造性撰写）
  - 跨多个功能模块的复杂版本
  - Haiku 出现理解错误时（极少见）

---

### 更新记录

- 2026-01-25：首次调研，覆盖 Anthropic/OpenAI
- 建议：2026-07 重新调研（6 个月后）

---

### 来源链接

**官方文档**：
- [Claude Tool Use Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)
- [Choosing the right model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)
- [Claude Haiku 4.5 System Card](https://www.anthropic.com/claude-haiku-4-5-system-card)

**社区讨论**：
- [Sonnet 4.5 vs Haiku 4.5 vs Opus 4.1](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249)
- [Haiku 4.5 better than Sonnet? (Reddit)](https://www.reddit.com/r/ClaudeAI/comments/1ocpoye/haiku_45_better_than_sonnet/)
- [Claude Haiku 4.5: Features, Testing Results, and Use Cases](https://www.datacamp.com/fr/blog/anthropic-claude-haiku-4-5)

**技术博客**：
- [Top Use Cases for Claude Haiku 4.5](https://chatlyai.app/blog/claude-haiku-4-5-use-cases)
- [Claude Haiku 4.5 matches Sonnet's coding skills at 80% less cost](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)

---

## 🤝 贡献

欢迎反馈和改进建议！请提交 issue 或 PR。

## 📄 许可

MIT License

---
name: git-publish-release
description: 当用户明确要求发布项目到 GitHub、创建 GitHub Release 或生成 Release Notes 时使用。根据版本历史整理发布说明；仅要求预览时不执行发布。

metadata:
  author: Bensz Conan
  short-description: GitHub Release 发布与 Release Notes 生成（按请求区分预览/发布）
  keywords:
    - git-publish-release
    - GitHub Release
    - release notes
    - version publish
---

# GitHub Release

## 目标

当用户明确要求"发布项目到 GitHub"、"创建 GitHub Release"或"生成 Release Notes"时使用。智能分析 tag 间历史变化并生成专业的 Release Notes；明确发布/创建请求时自动创建 GitHub Release，单独的 notes/历史总结请求仅生成预览，除非用户随后确认发布。支持首次发布、常规版本、预发布版本（alpha/beta/rc），自动识别 prerelease 标记。

## 流程

### 输入

#### 触发条件

用户需要：
- 发布项目的新版本到 GitHub
- 创建 GitHub Release 并自动生成 Release Notes
- 推送某个 tag 到 GitHub 并创建 release
- 总结版本间的历史变化

#### 你需要确认的输入

1. **目标 tag**（如 `v3.0.0`）
   - 如未指定，列出最近 tags 供选择
2. **项目路径**（可选，默认当前工作目录）

3. **任务输出目录**（宿主可设置 `TASK_OUTPUT_DIR`，指向本轮已声明的
   `./.bensz-api/task-.../git-publish-release/output/`；未设置时临时 notes 使用 OS 临时目录并立即清理）

> 认证通过 `gh auth login` 管理，无需手动配置 token。

明确要求“发布项目到 GitHub”或“创建 GitHub Release”时，按配置执行远程发布；仅要求“生成 Release Notes”或“总结版本间的历史变化”时只生成文案/预览，不调用 `gh release create`，除非用户随后明确确认发布。`release.require_confirmation` 的含义是：明确发布/创建请求可作为本次授权，覆盖已有 Release 仍按下方错误处理规则询问；不得把文案生成请求视为远程发布授权。

### 执行步骤

#### 工作流程

##### 确认项目信息

```bash
# 获取 owner/repo
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
```

##### 获取最新 Release 信息

```bash
# 获取最近一次 release 的 tag
PREVIOUS_TAG=$(gh release list --limit 1 --json tagName -q '.[0].tagName')
```

- 如果存在历史 release，比较范围为：`PREVIOUS_TAG..TARGET_TAG`
- 如果是首个 release，比较范围为：从初始 commit 到 `TARGET_TAG`

##### 分析历史变化

获取两个版本之间的 commit 历史：

```bash
# 如果有历史 release
git log ${PREVIOUS_TAG}..${TARGET_TAG} --pretty=format:"%h|%s|%an|%ad" --date=short

# 如果是首个 release
git log ${TARGET_TAG} --pretty=format:"%h|%s|%an|%ad" --date=short
```

##### 生成 Release Notes

根据 commit 历史和项目特点，智能生成 Release Notes。

###### Release Notes 结构

```
🎉 [版本号] - [吸引人的标题]
[一句话总结本次发布的核心价值/意义]

🚀 核心亮点：
• [亮点1]
• [亮点2]
• [亮点3]

✨ 主要更新：
[类别1]
• 更新内容1
• 更新内容2

[类别2]
• 更新内容3
• 更新内容4

🔧 技术改进：
• 技术改进1
• 技术改进2

📋 完整变更日志：
[简略说明获取方式或列出主要 commits]
```

###### 标题撰写原则

- **情感化表达**：使用"革命性"、"突破性"、"里程碑"等词汇
- **场景化描述**：说明这个版本解决什么问题、带来什么价值
- **时效性关联**：如"为 2026 年就绪"、"拥抱新范式"

###### 内容分类原则

根据 commit 信息自动分类：

| 类别图标 | 类别名称 | Commit 关键词示例 |
|---------|---------|-----------------|
| 🚀 | 核心亮点 | breakthrough, major, feature |
| ✨ | 新功能 | add, new, feature |
| 🐛 | Bug 修复 | fix, bugfix, resolve |
| 🔧 | 技术改进 | refactor, optimize, improve |
| 📝 | 文档更新 | docs, readme, guide |
| 🔐 | 安全更新 | security, fix vulnerability |
| 💥 | 破坏性变更 | breaking, deprecate |

###### 语言风格

- **简洁有力**：每个要点不超过一行
- **价值导向**：强调"为什么"而非仅仅"是什么"
- **用户视角**：用用户能理解的语言，避免技术术语堆砌
- **适当煽动**：使用感叹号、emoji 营造氛围，但不过度

##### 判断是否为 Prerelease

根据 tag 名称自动判断：
- 包含 `alpha`, `beta`, `rc`, `pre` 等标识 → `prerelease: true`
- 否则 → `prerelease: false`

##### 按授权创建 GitHub Release

仅在用户明确要求发布/创建 Release，或在预览后明确确认发布时执行以下命令；单独的 Release Notes/历史总结请求不得执行此步骤。

```bash
# 将 Release Notes 写入临时文件（避免 shell 转义问题）
# TASK_OUTPUT_DIR 可由宿主设置为本次任务已声明的
# ./.bensz-api/task-.../git-publish-release/output/ 目录；未注入时仅使用
# 一次性的 OS 临时目录，并在流程结束后清理，不把它当作任务产物。
NOTES_DIR="${TASK_OUTPUT_DIR:-${TMPDIR:-/tmp}}"
mkdir -p "$NOTES_DIR"
NOTES_FILE=$(mktemp "$NOTES_DIR/release-notes-XXXXXX.md")
cat > "$NOTES_FILE" << 'NOTES_EOF'
[生成的 Release Notes 内容]
NOTES_EOF

# 正式版
gh release create "$TARGET_TAG" \
  --title "$TARGET_TAG" \
  --notes-file "$NOTES_FILE"

# 预发布版（tag 含 alpha/beta/rc/pre 时）
gh release create "$TARGET_TAG" \
  --title "$TARGET_TAG" \
  --notes-file "$NOTES_FILE" \
  --prerelease

# 清理临时文件
rm -f "$NOTES_FILE"
```

#### 参考资源

- Release Notes 生成策略：[references/release-notes-strategy.md](references/release-notes-strategy.md)
- Release Notes 示例模板：[references/release-templates.md](references/release-templates.md)
- GitHub CLI 文档：https://cli.github.com/manual/gh_release_create

### 输出

#### 输出格式

完成发布后，向用户输出：

```
✅ Release 发布成功！

📍 Release URL: [release 链接]
🏷️ Tag: [tag 名称]
📅 发布时间: [时间]

📝 Release Notes 预览：
[生成的前 10 行 notes]
```

如果用户只要求 Release Notes 或历史总结，输出文案预览及对应的历史范围，不报告 Release URL，也不宣称已发布。

### 输出管理

#### BenszAPI 任务工作区


### 校验

#### 前置检查

确认 `gh` CLI 已安装并已认证：

```bash
gh auth status
```

如未认证，提示用户运行：

```bash
gh auth login
```

### 失败与恢复

#### 错误处理

| 场景 | 处理方式 |
|------|---------|
| `gh` 未安装 | 提示安装：`brew install gh` 或访问 https://cli.github.com |
| `gh` 未认证 | 提示运行 `gh auth login` |
| Tag 不存在 | 提示用户可用的 tags 列表 |
| 网络请求失败 | 重试 3 次，仍失败则报错并给出手动创建指南 |
| 权限不足 | 提示检查 `gh auth status` 及仓库权限 |
| Release 已存在 | 询问用户是否覆盖（使用 `gh release edit`） |

#### 实现注意事项

1. **跨平台兼容**：始终使用正斜杠 `/` 处理路径
2. **Notes 转义**：使用 `--notes-file` 传递临时文件，避免 shell 特殊字符转义问题
3. **Git 远程解析**：`gh repo view` 自动处理 HTTPS 和 SSH 两种 remote URL 格式
4. **认证管理**：`gh` CLI 使用系统 keychain 或 `~/.config/gh/hosts.yml` 存储凭证，无需手动管理 token


## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->