为项目发布版本并撰写用户可读的发布说明（bump 版本、从…

当你需要为一个仓库端到端地准备一次发布（升版本号、写 release notes、开 release PR）时使用。

适用场景

解决思路

1. 读取 `package.json`；如果当前分支已经 bump 过 `version`，以它为准，不要再改；否则 bump patch 版本（如 `0.0.19` → `0.0.20`），只有明确要求时才 bump minor/major。
2. 找到最新 tag：`git tag --sort=-creatordate | head -1`；用 `git fetch origin main && git log HEAD..origin/main --oneline` 确认分支与 `origin/main` 同步（输出应为空，否则标记出来）。
3. 列出 commit：`git log <last-tag>..HEAD --oneline`；也可运行 `pnpm release:notes` 获取原始 commit 清单，但仅作为候选变更的检查清单，绝不能作为草稿结构（它的 Improved/Changed/Docs 分节不得出现在 notes 中）。
4. 对每个 commit 获取 PR 正文和作者：`gh pr view <num> --repo <repo> --json title,body,author`（squash commit 的标题可能已过时）；commit 标题里的 `(#NN)` 可能指向两个仓库之一：先试 `bensenescu/open-seo`（origin），失败再回退到 `every-app/open-seo`（public）——外部贡献者的 PR 及其 handle 在 public 仓库。没有 `(#NN)` 的 commit 也可能是外部贡献（`gh pr list --repo every-app/open-seo --state merged --author <login>`）；用 `git log --format=%an` 查作者。当 PR 正文与 commit 标题冲突时，以最终代码为准核实（功能可能在合并前被回滚）。
5. 记录每个变更对应的 PR 作者 GitHub handle，以便在 bullet 中致谢。
6. 撰写 `release-notes/v<version>.md`；以 `release-notes/v0.0.24.md` 为规范风格范本（v0.0.25 及之后同风格），v0.0.23 及更早是旧的冗长风格，绝不模仿。notes 是可扫读的摘要而非文档：整个文件控制在一屏内（含标题约 15 行），每行都要有价值。
7. 格式：首行用片段式短语点出本次发布的 2–3 个亮点（如 "GSC UI, improved app layout and beta in app agent."），不要写成 "This release brings…" 的句子。
8. 分节只用 `## What's new` 和 `## Fixed`；没有 "Improved" 分节——改进要么够格进 What's new，要么砍掉。
9. What's new 的 bullet 只点出功能名，不做推销：每条一行短句（如 "Redesigned the app layout"、"Get GSC Insights inside the app"）——不要用破折号展开功能导览，不要 "so you can…" 式收益文案，不要罗列功能涉及的一切；若功能名本身有歧义，最多加一个从句的平实上下文。
10. 每个功能最多一个子 bullet，一行短句：最有用的单一细节、一个前置要求（如 "Requires `OPENROUTER_API_KEY`"）或一句预期说明。
11. 对粗糙的功能标注 "(Beta)" 并诚实设定预期，包括指出目前更好的替代方案；预期说明跟在顶层行后以破折号相连（如 "(Beta) In app agent - MCP is still recommended, but we'll be working to improve this during the summer."），把子 bullet 位置留给要求或细节。
12. Fixed：3–5 条 bullet，每条一句平实的话，只写用户可能遇到且能认出的 bug（如 "Claude answers in AI search work again."）；不要错误码、状态码、schema/基础设施词汇或机制说明。若超过四条合格，优先保留核心流程（searches、audits、tracking、MCP answers）中会遇到的，先砍掉针对自造状态恢复的修复（重新添加、取消归档、刷新）。
13. 致谢贡献者：仅在外部贡献者的 bullet 末尾加 `— thanks @handle`，维护者自己的 PR（`bensenescu`）绝不加；致谢放在顶层 bullet 而非子 bullet；多位贡献者写 `— thanks @a, @b`。
14. 结尾写：`Full Changelog: https://github.com/every-app/open-seo/compare/v<prev>...v<version>`。
15. 策展（这是核心工作）：激进地砍，长尾交给 Full Changelog 链接。
16. 只保留对产品本身的变更——应用、MCP 工具、运行 OpenSEO 的人真正使用的 SEO 数据/功能；每条 bullet 的试金石：自托管者在使用产品时会注意到这个吗？仅在抽象层面在意（新的后端选项、提高的上限）不够。
17. 不要提及：营销网站（`web/`）变更——落地页、文案、定位、博客。
18. 不要提及：定价/套餐/订阅/计费——付费墙、免费试用/套餐变更、Autumn 配置；这些是托管商业关切，与自托管者无关。
19. 不要提及：仅限 onboarding 流程的变更——注册/引导对话、profiling 步骤、升级引导、邮箱验证 UX；即使规模不小，也不是产品能力。
20. 不要提及：托管应用内部与元信息——analytics、specs/ADRs、CI、重构、依赖升级。
21. 不要提及：用户不可见的工作，即使与产品相关——安全加固、提高上限/限额、稳定性/内存/性能修复、数据库/后端选项与迁移；用户读 notes 时应能从使用产品中认出每一行，若只能在配置文件或已不再发生的事故中注意到，就砍掉。
22. 在收录与砍掉之间犹豫时，砍掉；4 条会被读完的 What's new 胜过 10 条没人读的。
23. 绝不编造功能——每个说法都必须能追溯到某个 commit。
24. bullet 里的数字通常是推销，砍掉；若某个数字确实关键，引用保守的典型值，绝不用挑出来的最佳值。
25. 评审与验证：启动一个 reviewer 子代理，提供草稿、上述准则、你收集的逐 commit 事实和仓库访问权限；它返回带编号的评审意见，指出每条违反了哪条准则；其职责包括冗长度：标出任何推销而非点名的 bullet、任何第二个子 bullet、任何含机制词汇的 Fixed bullet，以及任何让文件超过一屏的内容。
26. 对每条实质性意见，并行启动一个验证子代理，对抗性地对照实际 commit/代码核查该意见，给出 APPLY / APPLY-MODIFIED / REJECT 裁决。
27. 只应用已验证的意见。
28. 在名为 `claude/v<version>` 的分支上提交版本 bump、release notes 及任何 skill 变更（若当前分支已符合该模式则直接使用）。
29. 推送到 `origin` 并开一个针对 `main` 的 PR，标题精确为 `release: v<version>`；PR 正文为 release notes 内容。
30. 不要打 tag 或发布 GitHub release——那在合并后进行；合并后运行 `pnpm release:publish`，它从 `package.json` 读取版本并把对应的 `release-notes/v<version>.md` 发布到 `every-app/open-seo`。
31. 等价命令为：`gh release create v<version> --repo every-app/open-seo --title v<version> --notes-file release-notes/v<version>.md`。

适用边界 · 注意事项

• 不适用于非 OpenSEO 仓库或没有 `release-notes/` 规范范本的项目。
• 不适用于需要打 tag 或发布 GitHub release 的场景——本流程只到开 PR，发布在合并后另行进行。
• 不适用于没有 GitHub CLI（`gh`）或无法访问对应仓库的环境。