diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index 769c4460e..131afbae3 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -1,6 +1,6 @@ --- name: release -description: 准备或执行当前仓库发版，维护中文发布说明。用于“发版”“发个新版本”“准备 vX.Y.Z”“推荐版本号”“整理更新日志/发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing a repository release; not for deploying/restarting an instance, publishing application data, or authoring a release skill. +description: 准备或执行当前仓库的稳定版、实验版发版，维护中文发布说明。用于“发版”“发布实验版/exp 版本”“准备 vX.Y.Z”“推荐版本号”“整理发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing stable or experimental releases; not for deploying/restarting an instance or authoring a release skill. --- # 发版 @@ -12,12 +12,17 @@ description: 准备或执行当前仓库发版，维护中文发布说明。用 | 推荐版本号 | 根据本次变更与已有版本给出建议及理由 | | 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 | | 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 | +| 发布实验版、exp 版本 | 从目标实验分支发布，按下方实验版流程确定版本、文案和渠道隔离 | | 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 | -沿用当前会话明确的版本、范围与授权；用户已要求正式发版且条件满足时直接执行，不重复确认。 +沿用当前会话明确的版本、范围与授权；用户已授权发布目标版本且条件满足时直接执行，不重复确认。 “准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。 发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。 +稳定版从 `main` 发布。实验版从对应的 `experimental/<用途>` 分支发布，版本与 tag 采用 `vX.Y.Z-exp.N`， +展示标题包含分支用途名；先读 [实验版发布](references/experimental.md) 确定标题与编号，再复用本文的准备、执行与验收步骤。 +实验功能是否合入 `main` 是单独的维护决策，发布实验版不包含合并功能的授权。 + ## 读取当前流程 先读 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，再按任务检查： @@ -35,7 +40,7 @@ description: 准备或执行当前仓库发版，维护中文发布说明。用 ## 准备版本与说明 -1. 确认发布分支、upstream、目标仓库、工作区和完整待推送范围。本仓库沿用 `main`； +1. 确认发布类型、对应分支、upstream、目标仓库、工作区和完整待推送范围； 未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。 2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。 根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。 @@ -52,9 +57,9 @@ description: 准备或执行当前仓库发版，维护中文发布说明。用 跨大版本按项目部署约定判断，不默认支持在线升级。区分未发布迁移的整理、已执行这些迁移的源码部署实例， 以及 CI 实际采用的冻结基线。未发版不代表迁移从未被执行，CI 冻结检查失败也不等于正式版数据库升级失败； 按各自证据报告兼容性与检查结果，不因未发版而自动放宽现有冻结规则。 - 只修改说明时无需重建前后端；正式发版仍要跟踪发布工作流针对目标提交的检查与产物。 + 只修改说明时无需重建前后端；实际发版仍要跟踪发布工作流针对目标提交的检查与产物。 -## 执行正式发版 +## 执行发版 调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。 先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。 @@ -62,7 +67,7 @@ description: 准备或执行当前仓库发版，维护中文发布说明。用 不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。 本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。 -在准备完成且用户已授权正式发布后，将 `release_version` 设为已确定的版本，执行： +在准备完成且用户已授权发布后，将 `release_version` 设为已确定的版本，执行： ```bash release/publish "$release_version" @@ -71,6 +76,9 @@ release/publish "$release_version" 该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。 它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。 +只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对； +保持已有 tag、源码提交、附件和预发行状态，不重新执行发布入口。 + ## 恢复与验收 - 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。 diff --git a/.agents/skills/release/agents/openai.yaml b/.agents/skills/release/agents/openai.yaml index da7a53ad3..b9d4f030d 100644 --- a/.agents/skills/release/agents/openai.yaml +++ b/.agents/skills/release/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "release" - short_description: "按仓库流程整理中文发布说明、核对版本并完成发行与验证" - default_prompt: "使用 $release 准备下一个版本的中文发布说明，并核对发版条件。" + short_description: "按仓库流程准备稳定版或实验版的中文说明，完成发行与渠道验证" + default_prompt: "使用 $release 按指定的稳定版或实验版渠道准备中文发布说明，并核对发版条件。" diff --git a/.agents/skills/release/references/experimental.md b/.agents/skills/release/references/experimental.md new file mode 100644 index 000000000..1598db1af --- /dev/null +++ b/.agents/skills/release/references/experimental.md @@ -0,0 +1,64 @@ +# 实验版发布 + +适用于独立于主版本维护、供用户主动选择体验的实验功能。发布入口仍是仓库的 `release/publish`， +构建复用目标实验分支的 `.github/workflows/release.yml` 与 `release/platforms.yaml`。 + +## 分支与版本 + +- 从用户指定或会话已确定的 `experimental/<用途>` 分支发布，核对它的 upstream 和实验功能范围。 + 使用独立 worktree 时保留其他工作区内容；不把实验代码合入 `main`，也不顺带升级运行实例。 +- 版本采用 `vX.Y.Z-exp.N`：`X.Y.Z` 表示本轮采用的正式版基线，`N` 从 1 开始递增。 + 编号在仓库内唯一；多个实验分支共享 Git tag 命名空间，不能分别占用相同版本号。 + 后续只有实际同步了新的正式版基线，才调整 `X.Y.Z`。 +- 核对已有 tag、Release 与目标分支源码，先区分重试和新发行。已发布的旧命名版本保留， + 不为统一名称移动 tag 或替换原有产物。 +- GitHub Release 展示标题采用 `vX.Y.Z-<用途>.M`，`<用途>` 取实验分支名去掉 `experimental/` 前缀后的部分。 + 发布前通过 `gh api` 核对相同正式版基线与用途的已有 Release 标题和旧命名 tag，新发行取已有最大编号加 1，首次从 1 开始。 + 展示编号 `M` 独立于实际 tag 的 `exp.N`，旧命名发行也计入，不能因改用 `exp.N` 而重置；同一发行重试沿用已确定编号。 + 例如已有 `v3.10.0-codex-anti-degradation.1`，下一次 tag 即使是 `v3.10.0-exp.1`，标题也应为 `v3.10.0-codex-anti-degradation.2`。 +- tag 和产物继续使用 `exp.N`：镜像版本去掉 tag 开头的 `v`，安装包沿用项目的版本、系统和架构命名。 + 发布说明首行仍匹配实际 tag；关联 Issue 和试验目的写在正文中。新标题规则不自动改名已有 Release。 + +## 先核对发布能力 + +在目标实验分支读取实际工作流，确认以下行为；新实验分支若缺少支持，先在既有流程中补齐并验证： + +- `exp.N` 产生 `experimental` 构建类型，所有平台的二进制与镜像使用同一版本和源码提交。 + 本项目实验构建禁用应用内一键更新，用户按部署说明手动升级。 +- GitHub Release 标为 Pre-release，且不设为 Latest；Docker 发布版本标签，不覆盖稳定版 `latest`。 + 默认 `stable` 更新渠道忽略实验版；主动配置为 `preview` 的用户可能看到预发行。 +- 复用正式版平台清单、质量检查、完整安装包与多架构镜像，以及部署文件、校验和和现有产物证明。 + 对照本次清单确认平台，不以“实验版”为由仅发布单架构镜像。 +- 部署说明交代与稳定实例并存的目录、配置、端口和数据库要求；需要 Compose 隔离配置时， + 核对发布附件确实包含它，不能只在文案中承诺。 +- 实验版正文使用下方完整文案，不再由工作流重复追加安装章节或自动生成混入正式版基线的提交列表。 +- Release 的 `name` 使用上述展示标题。工作流若默认以 tag 为标题，发布成功后用 `gh release edit --title` 设置标题， + 再通过 `gh api` 回读核对；仅修改 `name`，保留 tag、产物、正文和预发行状态。 + +## 中文发布说明 + +在目标分支的 `release/notes.md` 编写，首行为 `# vX.Y.Z-exp.N`。后续内容按实际需要组织： + +1. **实验说明**：开头简述正式版基线、验证的问题与适用人群。效果尚未验证时明确说明， + 不把假设写成已解决的问题，不承诺实验功能一定进入主版本。 +2. **本次变化**：首次发行概括相对正式版基线新增的实验能力，关联 PR；后续发行只列相对上个实验版的变化。 + 同步主分支修复时说明它对实验用户的影响，不复制整份正式版更新记录。 +3. **安装与使用**：给出本版本真实镜像命令、支持平台、部署文件及实验部署文档链接。 + 交代功能是否默认启用和必要配置；保留工作流实际提供的校验与证明说明。 +4. **使用须知**：只写本次适用的已知限制、数据隔离、迁移与回退边界，以及手动更新方式。 +5. **反馈与致谢**：链接关联 Issue 或已有反馈入口，感谢实际贡献者。没有相应内容的章节可以省略。 + +用户要求先审核文案时，先展示完整正文；已批准的同一版本文案无需重复确认。 +正常新发行把说明纳入版本提交并从 tag 构建，不先创建公开空 Release 再回填附件。 + +## 执行与验收 + +按主技能准备说明和其他变更后，在实验分支执行 `release/publish `。 +入口创建版本提交和 tag，并从该分支 dispatch 发布工作流；不要从 `main` 发布实验代码。 + +发布前记录 GitHub Latest 的版本与 Docker `latest` 摘要；发布后核对二者仍对应稳定版。 +检查展示标题的分支用途与历史续号、它所对应的实际 tag，以及目标 tag 的源码提交、完整产物、校验和、多架构平台和 Pre-release 标记。 +同基线的 `X.Y.Z-exp.N` 按 SemVer 排序低于正式 `X.Y.Z`；渠道隔离仍以更新器过滤和发布标签规则为准。 + +失败时按主技能从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。 +仅维护已有页面文案时不重新构建；报告实际完成状态、发布链接及验证缺口。