SuperAPI AI 工具集

release-notes

写作与研究

查看项目

更新于 10-15 07:43

技能介绍

用途

该技能用于在用户需要撰写发布说明(release notes)、变更日志(changelog)或记录某次发布中变更内容时提供写作指导。其定位是技术写作者,目标是向不同受众清晰传达变更:想知道有什么新内容的用户、需要迁移指引的开发者,以及需要执行摘要的利益相关者。

主要能力

技能围绕发布文档的撰写流程组织,包含以下环节:

1. 收集变更

通过 git 命令分析变更内容:

# Get commits since last release
git log --oneline v$(previous)..HEAD

# Get changed files for scope assessment
git diff --stat v$(previous)..HEAD

并将每项变更归类为:

  • Added — 新功能
  • Changed — 对现有行为的修改
  • Fixed — 缺陷修复
  • Deprecated — 标记为待移除的功能
  • Removed — 已移除的功能
  • Security — 漏洞修复
  • Performance — 速度/效率改进

2. 面向受众写作

针对三类受众给出不同的写作要点:

  • 面向用户的发布说明(博客/邮件):以最令人兴奋的变更开头;视觉变更使用截图/GIF;解释收益而非实现细节;保持可扫读,标题加 1-2 句描述。
  • 开发者变更日志(CHANGELOG.md):遵循 Keep a Changelog 格式;破坏性变更置于顶部显著位置;链接相关 PR/issue;为破坏性变更提供迁移说明。
  • 内部发布摘要(Slack/团队):一段执行摘要;关键变更的项目符号列表;已知问题或后续事项;贡献者致谢。

3. 格式

给出变更日志的格式示例:

## [1.2.0] - 2025-03-15

### Added
- Feature X: one-sentence description (#123)

### Changed
- **BREAKING**: API endpoint `/v1/foo` renamed to `/v2/foo`. See migration guide below.

### Fixed
- Fixed crash when input contained unicode characters (#456)

### Migration Guide
If you used `/v1/foo`, update to `/v2/foo`. The request format is unchanged.

使用方式

当用户表达“write release notes”“changelog”“what changed”等意图时触发该技能。技能按上述流程引导:先收集并分类变更,再根据目标受众选择写作风格,最后按给定格式输出。

规则

  • 绝不说“various bug fixes”——要具体。
  • 破坏性变更单独成节,并附迁移说明。
  • 安全修复在适用时引用 CVE 编号。
  • 性能改进在可用时包含前后对比数字。
  • 按姓名或 handle 致谢贡献者。

适用场景

适用于需要产出发布说明、变更日志或版本变更文档的场景,覆盖面向用户、面向开发者和面向内部团队三类输出。

限制

资料未提供该技能的具体安装方式、运行环境、收费模式或平台支持信息,暂未提供。