SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场xerahs-release-bump-tag

xerahs-release-bump-tag

部署与运维

查看项目

更新于 10-16 04:07

技能介绍

用途

XerahS Release Bump Tag 用于按严格顺序编排 XerahS 的发布流程，确保发布步骤不跳序、不遗漏，并在标签推送后持续监控发布工作流直至成功。

主要能力

  • 按固定顺序执行发布步骤：维护杂项 → 更新变更日志（可选）→ 验证构建 → 版本号提升/提交/推送/打标签 → 监控 → 失败修复重试 → 确保标准发布说明 → 按需设为预发布。
  • 版本号提升（bump）：支持 major/minor/patch，未指定时默认 patch（z）；更新所有包含 <Version> 的已跟踪 Directory.Build.props 文件，并同步 build/windows/chocolatey/xerahs.nuspec 的 <version>。
  • 构建预检：执行 dotnet build src/desktop/XerahS.sln，构建失败则不继续。
  • 提交流程：暂存所有当前仓库更改，使用带版本前缀的提交信息提交，推送当前分支，创建并推送附注标签 vX.Y.Z。
  • 发布监控：查找 Release Build (All Platforms) 的标签运行，每 120 秒轮询状态直到完成。
  • 失败处理：检查失败作业日志、定位首个阻塞错误、在代码/工作流/脚本中修复根因、重跑本地预检构建，并使用下一个补丁版本重试发布，循环直至成功。
  • 发布说明：确保 GitHub Release 包含标准变更日志链接（https://xerahs.com/changelog.html）与 macOS 疑难解答（“App is damaged”）区块，含 Gatekeeper xattr -cr 指引。
  • 预发布：按请求将成功发布设为 pre-release。

使用方式

主命令（在仓库根目录执行）：

./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh

自动化监控加预发布（推荐）：

./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh --assume-changelog-done --monitor --set-prerelease --bump z --yes

非交互式示例：

  • 补丁提升、无提示：./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh --assume-changelog-done --bump z --yes
  • 补丁提升并启用内置 2 分钟监控：./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh --assume-changelog-done --monitor --monitor-interval 120 --bump z --yes
  • 次版本提升并自定义提交类型/摘要：./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh --assume-changelog-done --bump y --type CI --summary "Prepare release artifacts" --yes
  • 仅预览：./.ai/skills/xerahs-release-bump-tag/scripts/run-release-sequence.sh --assume-changelog-done --bump z --dry-run --yes

无 bash 环境（如 Windows PowerShell）时手动执行序列：

  1. 维护：git pull --recurse-submodules；git submodule update --init --recursive。
  2. 变更日志：运行 .ai/skills/update-changelog/SKILL.md；若无 CHANGELOG.md 或用户确认跳过则可省略。
  3. 提升、提交、推送、打标签：运行 dotnet build src/desktop/XerahS.sln，失败则中止；从根 Directory.Build.props 读取当前版本；计算下一个版本（patch Z+1，minor Y+1.0，major X+1.0.0）；确认标签 v<new-version> 在本地与 origin 均不存在；更新所有含 <Version> 的已跟踪 Directory.Build.props；更新 build/windows/chocolatey/xerahs.nuspec 的 <version> 以匹配；依次执行 git add -A、git commit -m "[v<new-version>] [CI] Release v<new-version>"、git push origin <current-branch>、git tag -a v<new-version> -m "v<new-version>"、git push origin v<new-version>。
  4. 每 2 分钟监控：查找运行 gh run list --limit 10 --json databaseId,workflowName,headBranch,status,conclusion,url；轮询 Start-Sleep -Seconds 120 后再执行 gh run view <run-id> --json status,conclusion,jobs,url。
  5. 失败修复重试：获取失败作业日志 gh run view <run-id> --job <job-id> --log；在仓库中修复根因；重跑 dotnet build src/desktop/XerahS.sln；以下一个补丁版本重复步骤 3。
  6. 确保标准发布说明：读取当前正文 gh release view v<new-version> --json body；若缺失则追加标准变更日志与 macOS 疑难解答区块；使用 gh release edit v<new-version> --notes-file <file> 写入。
  7. 按需设为预发布：gh release edit v<new-version> --prerelease；验证 gh release view v<new-version> --json isPrerelease,url,assets。

可选发布后 Chocolatey 维护：

  • 标签工作流应已生成并冒烟测试 xerahs.<new-version>.nupkg。
  • 手动重新打包/同步：powershell -File build/windows/chocolatey/Sync-ChocolateyPackage.ps1 -Version <new-version> -Pack。
  • 手动冒烟测试：powershell -File build/windows/chocolatey/Test-ChocolateyPackage.ps1 -Version <new-version> -SourceDirectory dist\chocolatey。
  • 审核后可选推送：powershell -File build/windows/chocolatey/Sync-ChocolateyPackage.ps1 -Version <new-version> -Pack -Push -ApiKey <key>。

默认行为：未指定时提升为 patch（z）；默认提交类型 token 为 CI。维护步骤默认自动执行，除非显式使用 --skip-maintenance（或旧别名 --assume-maintenance-done）。

适用场景

  • 需要在 XerahS 仓库中发起正式版本发布，并要求顺序与构建验证的场景。
  • 需要标签推送后持续监控发布工作流并在失败时自动修复重试的场景。
  • 需要统一更新版本号、nuspec 版本与发布说明区块的场景。
  • 需要将发布标记为预发布的场景。

限制与护栏

  • 除非用户显式请求绕过，否则不得跳过步骤顺序。
  • 除非用户显式请求绕过（--skip-maintenance），否则不得跳过维护步骤。
  • 在维护/变更日志步骤中不得提交或推送。
  • 在提升/打标签之前必须验证构建。
  • 标签推送后必须监控工作流，不得止于标签创建。
  • 失败时必须检查日志并在重试前修复根因。
  • 重试需新提交/新标签时必须使用新的补丁版本。
  • 遇到 detached HEAD 时中止。
  • 版本格式非 X.Y.Z 时中止。
  • 本地或远端已存在匹配标签时中止。
  • 需要部分流程时支持 --no-push 与 --no-tag。
  • Windows/PowerShell 下 bash 可能不可用，手动回退流程须为一等支持。
  • Chocolatey 社区发布的校验和属于发布后数据，因为 GitHub 发布资产在标签工作流完成前不存在；标签工作流会自动执行该同步，Sync-ChocolateyPackage.ps1 为手动回退路径。

具名使用（Cursor / Codex）

执行该技能时：按维护 → 变更日志 → 构建验证 → 提升/提交/推送/打标签的顺序运行；有 bash 则用 bash 脚本，否则使用 PowerShell/手动流程；未指定时默认 patch（z）；每 120 秒监控标签工作流直至完成；失败时检查日志、修复并以下一个补丁版本重试；确保发布说明包含变更日志链接与 macOS 疑难解答区块；按请求将最终成功发布设为预发布；报告最终版本、提交哈希、分支推送状态、标签推送状态、运行 URL 与预发布状态。