SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场release-note-writer

release-note-writer

写作与研究

查看项目

更新于 10-16 10:33

技能介绍

用途

Release Note Writer 用于把 git 历史、changelogithub 输出、GitHub releases、PR 列表或原始 commit 日志，转换成按受众分组、面向用户的发布说明。核心规则是：只用英文撰写；把技术历史转换为面向读者的变更，按受众和结果分组；不要直接照搬 commit scope。

主要能力

  • 起草前收集发布上下文：检查当前仓库版本与标签、仓库中已有的 package/version 文件；用 git tag --sort=-v:refname 查看近期标签；确定上一发布标签。
  • 运行 changelogithub 干跑输出：pnpm dlx changelogithub --dry --from <previous-version>。若命令因沙箱需要网络而失败，请求批准后重跑。
  • 检查生成的 commit 结构，并直接检查 commit，例如 git show --stat --oneline <sha> 或等效的定向命令。
  • 当 chore/internal commit 影响贡献者工作流、工具、构建、CI、本地开发、文档生成、测试基础设施或内部包时，将其纳入。
  • 若版本边界不明确，起草前先问一个简洁的问题。

受众结构与使用方式

采用紧凑的聚合结构，优先用较少的几个主要小节配合有用的子标题，而不是许多基于 scope 的小节；当能让受众或产品面更清晰时，可使用多级标题。推荐顺序：

  1. 面向最终用户的产品相关小节。
  2. ### To developers 靠近末尾。
  3. ### To contributors 最后。
  4. 仅当需要行动时才写 ### Upgrade notes。

产品相关小节可按产品面嵌套，例如 ### Product updates 下分 #### Local、#### Cloud、#### New providers、#### Chat and settings。不必强行套用这些确切标题，选择便于扫描的标题。

当修复涉及关键回归、阻塞主要工作流或用户会特意查看说明确认的问题时，使用专门的 bug-fix 小节。关键 bug 应用平实、具体的语言，因为用户可能在检查自己的阻塞是否已修复。次要的视觉、措辞和低影响清理可归为 polish，但不要把重要修复埋在宽泛的产品更新里。

To developers 用于外部开发者影响：Plugin SDK、plugin manifest、gamelet、widget、extension、公共包 API、自托管部署行为、server-runtime、Docker 镜像行为、集成契约；包含影响外部运维者的部署行为变更。除非 AIRI Cloud 用户或外部运维者需要采取行动，否则不要包含纯内部 apps/server 业务逻辑。

To contributors 用于内部项目工作：vishot、cap-vite、CI、开发脚本、仓库构建/测试/lint 工作流、文档生成、仅内部包、发布自动化、测试脚手架、截图、评测工具；即使 changelogithub 未突出显示相关 chore commit，也应纳入。

面向最终用户的写作

对于 UI、apps/stage-、packages/stage- 和 packages/ui 的变更，强调用户现在能做什么、去除了什么烦扰。可用句式：

  • “You can now ...”
  • “Previously, ... could ... . We fixed this so ...”
  • “We added ... to help you ...”
  • “Some ... cases could ... . We cleaned this up so ...”

除非是用户可见的产品名或提供商名，否则避免暴露实现名称；能用平实描述时，就不要在最终用户小节保留技术术语。发布说明应从用户体验出发，而不是从实现出发。对于修复，写用户看到了什么、哪个工作流被阻塞或降级、现在什么又能用了。除非术语是面向用户产品的一部分，否则不要描述诸如生命周期顺序、handler 注册、IPC 时序、过期 store 或运行时管道等内部原因。关键修复应平实具体，不要淡化为含糊的 polish。

如果 commit 标题、diff、测试和周边文件无法让面向用户的效应变得清晰，不要编造；就先问用户一个简洁的问题，了解发生了什么、如何影响用户。

示例（好）：

  • “You can now retry a failed message directly from the chat.”
  • “Some provider lists were hard to reach on smaller screens. They now scroll correctly.”

示例（避免）：

  • “Refactored stage-ui chat action menu state.”
  • “Fixed provider list CSS overflow in stage-pages.”

Provider 小节

存在 provider 变更时创建 provider 小节，保持简洁并按能力分组。当发布有多个产品面时，优先放在面向产品的父级下，例如 ### Product updates -> #### Local -> ##### New providers。示例：

Product updates

Local

New providers
  • You can now use Amazon Bedrock as a chat provider.
  • You can now use MiniMax Speech as a TTS provider.
  • Artistry now supports image providers such as ComfyUI, Replicate, and Nano Banana.

Cloud 与商业功能

当账户、计费、credits、Flux、Stripe、付费 TTS 和商业使用变更影响用户时，把它们放在一起。仅当发布说明本身能让 Cloud 上下文可理解时，才使用与 cloud 相关的标题。例如优先写：“AIRI Cloud now supports server-side TTS with per-character Flux billing.”、“We improved billing reliability for TTS usage, especially when usage needs to be recorded before payment is fully settled.”。不要假设 AIRI Cloud 对每位读者都是自明的顶级小节；需要时拆成 Account、Billing、Cloud TTS 等更清晰的子主题。不要为内部服务器细节创建宽泛的 self-hoster 小节；仅当有要求行动或外部可见的部署变更时才提及自托管。

语气

清晰、温暖、略带趣味。说明可以有性格，但信息必须精确。

应做：使用自然句子；解释用户收益；当单个 bug 较次要时把相关修复归为 “polish”；少量俏皮措辞以减少生硬。

不应做：过度玩笑；没有行为支撑的营销套话；列名每个内部包；直接复制 commit 标题；过度贴合过去发布的某一个示例。

反馈处理

当用户在草稿后给出措辞、语法、结构或语气反馈时，询问是否用底层规则更新该技能。不要添加“永远不要写这个具体句子”这类狭窄规则，而应推断持久原因：受众不匹配、实现细节太多、缺少用户行动、小节过于碎片化、过于生硬或过于随意、在产品/开发者/贡献者/cloud/升级说明之间放置错误。然后提出一条简洁的抽象规则，并在编辑技能前询问。

起草工作流

  1. 从 changelogithub 和直接 commit 检查构建事实列表。
  2. 按受众对每项分类：最终用户、provider、cloud/account、开发者、贡献者、升级说明。
  3. 将相关 commit 合并为一条可读要点。
  4. 用用户视角写要点：什么变了、为什么重要、读者现在能做什么。
  5. 除非用户要求可追溯版本，否则主草稿中不要放 commit 链接。
  6. 仅当有必须行动时，以升级说明结尾。

可追溯脚注

当用户要求 commit 可追溯性时，优先使用 Markdown 脚注而非行内 commit 链接。将脚注标记放在它支持的发布说明要点旁，然后在说明下方列出 commit 链接和作者归属。使用脚注在保持发布说明可读性的同时，声明每条主张来自哪里、由谁贡献。多个 commit 可支持一条要点；仅当每个 commit 增加不同上下文时，才为该要点附加多个脚注。格式示例：

  • User-facing release note sentence.[^1]

[^1]: Commit abcdef123 by @contributor.

当可用时，使用来自 changelogithub、PR 元数据或 commit 元数据的 GitHub handle。如果 commit 作者名与 GitHub handle 不同且 handle 未知，使用可用的作者名，不要编造 handle。

输出

除非用户要求其他格式，否则返回 Markdown。示例形态（非必需模板，按实际发布调整小节名称与标题深度，不要输出空小节）：

vX.Y.Z Highlights

Product updates

Account

  • ...

Local

New providers
  • ...
Experience improvements
  • ...

Cloud

Billing

To developers

  • ...

To contributors

  • ...

Upgrade notes

  • ...