openseo-release-notes

OpenSEO 发布说明

为此仓库完成端到端的发布。交付内容包括更新 package.json 中的版本、新建 docs/release-notes/v<version>.md，以及向 origin/main 提交一个标题为 release: v<version> 的 PR。

1. 更新版本

• 阅读 package.json。如果分支已更新 version，则以该版本为准，不要更改。
• 否则，递增补丁版本（例如，0.0.19 → 0.0.20）。仅在明确要求时递增次版本或主版本。

2. 收集自上次发布以来的更改

• 查找最新标签：git tag --sort=-creatordate | head -1。确认分支与 origin/main 同步（git fetch origin main && git log HEAD..origin/main --oneline 的结果应为空；如果不是，请标记出来）。
• 列出提交：git log <last-tag>..HEAD --oneline。也可以运行 pnpm release:notes，获取原始提交清单——仅将其用作候选更改的检查清单，不能用作草稿结构（说明中不得出现其 Improved/Changed/Docs 分类）。
• 对每个提交，获取 PR 正文和作者（gh pr view <num> --repo <repo> --json title,body,author）——压缩提交的主题可能已过时。提交主题中的 (#NN) 可能指向任一仓库：先尝试 bensenescu/open-seo（origin），失败后再尝试 every-app/open-seo（公开仓库）——外部贡献者的 PR 及其账号名位于公开仓库。没有 (#NN) 的提交也可能是通过公开仓库提交的外部贡献（gh pr list --repo every-app/open-seo --state merged --author <login>）；请通过 git log --format=%an 检查作者。如果 PR 正文与提交主题不一致，请根据最终代码核实相关说法（功能可能在合并前被撤回）。
• 记录每项更改对应的 PR 作者 GitHub 账号名，以便在项目符号条目中致谢。

3. 起草更新说明

编写 docs/release-notes/v<version>.md。docs/release-notes/v0.0.24.md 是规范的风格范例——请与其保持一致（v0.0.25 及之后的版本也遵循相同风格）；v0.0.23 及更早版本采用旧的冗长风格，切勿模仿。更新说明应是便于浏览的摘要，而非文档：整份文件控制在一屏内（标题也算在内，大约 15 行），每一行都必须有价值。

格式：

• 首行：用片段形式点出本次发布的 2–3 个亮点（“GSC UI，改进后的应用布局和 beta in app agent。”）。不要写成 “This release brings…” 这样的句子。
• 章节：仅使用 ## What's new 和 ## Fixed。不要设置 “Improved” 章节——改进要么足以成为亮点（What's new），要么就删掉。
• What's new 的项目符号应写出功能名称，不要推销功能。 每条简短一行（“重新设计应用布局”“在应用中获取 GSC 洞察”）——不要用破折号详细介绍功能，不要写“这样你就能……”之类的好处，也不要列出功能涉及的所有内容。如果仅凭名称难以理解，最多补充一句通俗说明。
• 每项功能最多添加 一条子项目符号，简短一行：最有用的细节、要求（“需要 OPENROUTER_API_KEY”）或预期说明。
• 粗糙的功能要标注“(Beta)”，并如实说明预期，包括指出目前更好的替代方案。预期说明放在顶层项目符号的破折号后（“(Beta) In app agent - MCP 仍是推荐选择，但我们会在夏季持续改进。”），将子项目符号留给要求或细节。
• Fixed：写 3–5 条，每条用一个朴素的句子，只列用户可能遇到且能识别的问题（“AI 搜索中的 Claude 答案恢复正常。”）。不要写错误代码、状态码、架构或基础设施术语，也不要描述实现机制。如果符合条件的修复超过四项，优先保留核心流程（搜索、审计、跟踪、MCP 答案）中的问题，首先删去需要用户恢复自身操作状态的修复（重新添加、取消归档、刷新）。
• 注明贡献者。 仅对外部贡献者在项目符号末尾添加 — thanks @handle；维护者自己的 PR（bensenescu）不要致谢。致谢应放在顶层项目符号上，而非子项目符号。多位贡献者写作：— thanks @a, @b。
• 末尾添加：Full Changelog: https://github.com/every-app/open-seo/compare/v<prev>...v<version>

筛选——这才是重点。大胆删减；完整变更日志链接会涵盖其他内容：

• 只写产品本身的变更——应用、MCP 工具，以及 OpenSEO 用户实际使用的 SEO 数据和功能。逐条检验：自托管用户使用产品时会注意到这项变化吗？ 仅仅在抽象层面有意义（新增后端选项、提高上限）还不够。
• 不要提及：
  • 营销网站（web/）变更——落地页、文案、定位、博客。
  • 定价 / 套餐 / 订阅 / 账单——付费墙、免费试用或套餐变更、Autumn 配置。这些与托管商业服务相关，自托管用户并不关心。
  • 仅涉及引导流程的变更——注册 / 引导聊天、用户画像步骤、升级入口、邮箱验证体验。这些不属于产品能力，即使改动很大也不例外。
  • 托管应用内部实现和杂项——分析、规格 / ADR、CI、重构、依赖升级。
  • 用户看不到的工作，即使与产品相关也不例外——安全加固、提高上限 / 限制、稳定性 / 内存 / 性能修复、数据库 / 后端选项和迁移。阅读更新说明的用户应该能从实际使用产品的体验中识别出每一行；如果他们只能在配置文件中发现，或只能从不再发生的故障中察觉，就删掉。
• 在是否保留之间犹豫时，删掉。读者愿意看完的 4 条 What's new，胜过无人阅读的 10 条。
• 切勿虚构功能——每项描述都必须有对应的提交记录。
• 项目符号中的数字通常是在推销——删掉；如果某个数字确实不可或缺，就使用保守的典型值，绝不要挑选最佳案例。

4. 审查和验证

1. 启动一位审查子 Agent，并提供草稿、上述指南、你收集的每次提交的事实，以及仓库访问权限。它会返回编号审查意见，并指出每条意见违反了哪项指南。审查范围还包括冗长问题：标出任何推销而非陈述内容的条目、任何第二级子条目、任何使用机制术语的 Fixed 条目，以及任何导致文件超过一屏的内容。
2. 针对每条实质性意见，并行启动一位验证子 Agent，根据实际提交和代码对意见进行对抗性核查，并给出 APPLY / APPLY-MODIFIED / REJECT 的判定。
3. 仅应用已验证的意见。

5. 开启 PR

• 将版本更新、发行说明和任何技能变更提交到名为 claude/v<version> 的分支（如果当前分支已符合此命名模式，则使用当前分支）。

• 推送到 origin，并向 main 开启 PR，标题必须为 release: v<version>。PR 正文使用发行说明内容。

• 不要标记版本或发布 GitHub Release——这些操作将在合并后进行。合并后，运行 pnpm release:publish。该命令会从 package.json 读取版本，并将匹配的 docs/release-notes/v<version>.md 发布到 every-app/open-seo。

• 等效命令为：

  gh release create v<version> \
    --repo every-app/open-seo \
    --title v<version> \
    --notes-file docs/release-notes/v<version>.md