SuperAPI AI 工具集

release-announcement

写作与研究

查看项目

更新于 10-16 01:34

技能介绍

用途:为 ax 仓库撰写或修订发布公告、版本页与网站 changelog,把发布内容与其产生过程(智能体会话)结合成有依据的叙述。触发说法包括“write release notes”“draft release announcement”“prepare changelog”“update the website changelog”“release page”“version page”“SEO release page”“what changed in vX.Y.Z”“generate announcement for vX.Y.Z”“explain how we got to this release”。不适用于单条 commit message、普通 README 修改或非发布的特性文档。

主要能力:该技能负责 docs/releases/ 下的策展层,Release Please 仍负责 CHANGELOG.md。它会解析版本与范围、把 commit 与文件映射到智能体会话,并生成主题化叙事。已知版本时运行:bun run release:announcement -- X.Y.Z,会起草 docs/releases/vX.Y.Z.md,并在存在 Release Please 对比标题时嵌入上一发布标签(BASE_REF)、发布标签或 HEAD(HEAD_REF)、git diff --name-status 与 git log --reverse 结果。手动检查可用 BASE_REF、HEAD_REF 变量配合同样的 git diff 与 git log 命令。

会话映射使用 ax 查询:ax ingest here --since=30d、ax sessions here --days=30、ax sessions near <important-sha>、ax recall "<subsystem or decision>" --sources=turn,commit --scope=here。大型发布需检查每个主要主题一个 SHA、每个主要 schema/API/CLI 变更附近的 SHA、意外修复或反转相关 SHA,以及合并/发布 PR 附近的会话窗口。

写作要求:用有主题的叙述替换生成的草稿,内容包含“How we got here”(问题、决策树、取舍、最终形态为何胜出,并用行文引用会话/commit 证据)、“What changed”(按主题分组而非扁平 commit 列表)、“Example”(CLI 命令、配置片段、输出示例、schema 片段或前后工作流)、“Visual evidence”(UI、CLI、仪表盘、TUI 或工作流宜用截图/图示/输出)、“Why it matters”(日常实际影响)。不要编造动机;若缺少 ax 会话证据,只陈述 commit 与变更文件能证明的内容,并收窄叙事。

资产与渲染:网站可见发布图片放在 apps/site/public/releases/assets/,在 markdown 中以 Focused release screenshot 引用。网站发布渲染器支持标题、列表、链接、粗体 scope、围栏代码块与图片,应使用这些而非手写 HTML。

验证:运行 bun run typecheck 与 cd site && bun run build;若页面有变,预览并冒烟特定版本页:cd site,然后 bun run preview -- --host 127.0.0.1 --port 4175,检查 /changelog 与 /changelog/vX.Y.Z。

限制:假定 ax 在 PATH 中且本地 ax 数据库可达;若 ax 报 DB 连接错误,应提示用户启动仓库数据库,仅在用户要求时才仅凭 git 证据继续。