/release

description: 正式发布：候选矩阵 → beta/main 同步 → annotated tag → 稳定 GitHub Release
argument-hint: "[version]"
allowed-tools: Bash(git fetch:*), Bash(git status:*), Bash(git branch --show-current:*), Bash(git rev-parse:*), Bash(git log:*), Bash(git diff:*), Bash(git show:*), Bash(git tag -l:*), Bash(git ls-remote:*), Bash(git merge-base:*), Bash(gh run list:*), Bash(gh run view:*), Bash(gh run watch:*), Bash(gh api:*), Bash(gh release view:*), Bash(gh repo view:*), Bash(python3 .github/scripts/check_project_version.py:*), Bash(test:*), Read, Grep, Glob, Edit, Write

Release Workflow — 候选矩阵 → main/tag → 正式 Release

你是 UnitySkills 项目的正式发布助手。发布必须遵守以下顺序：

版本一致性检查
  → beta 候选提交完整矩阵
  → 用户确认正式发布
  → beta/main 精确同步
  → 创建并推送 annotated tag
  → tag 自身完整矩阵
  → 创建稳定 GitHub Release
  → 核验 releases/latest 与 Release 跳转地址
  → 重新生成 main 的 Star History 图表

共享规则（`/updateversion` 引用本节，不另行复述）

1. **Tag 不可变**：已发布的 tag（本地或远端）绝不删除、移动或强制重推；用户靠 `#vX.Y.Z` 安装。版本号一旦创建过 tag 即视为占用（即使尚无 Release），修复须换用新的 patch 版本。 2. **Star History 豁免**：`beta` 与 `main` 是两条平行线，Star History 机器人的图表提交只落 `main`，`beta` 永远不接收，也不为此把 `main` 合并或变基进 `beta`。`origin/main` 相对 `beta` 只允许多出这些提交，以下两条检查必须均无输出，有输出即停止并列出提交：

   git log --format='%h %an %s' beta..origin/main | grep -v -E '^[0-9a-f]+ github-actions\[bot\] docs: update Star History charts$'
   git diff --name-only beta...origin/main | grep -v -x -E 'docs/star-history-(light|dark)\.svg'

发布时 `main` 被移动到候选提交，这些图表提交随之丢弃，阶段 10 再重新生成。 3. **`releases/latest` 是更新提醒的唯一来源**：Unity 更新提醒只读取它，因此正式 Release 创建成功之前，不能宣称用户已经收到更新通知。查询命令如下；`tag_name` 必须严格为 `vMAJOR.MINOR.PATCH`，且 `draft`、`prerelease` 均为 `false`：

   gh api 'repos/{owner}/{repo}/releases/latest' \
     --jq '{tag_name,html_url,draft,prerelease}'

输入

用户可提供不带 `v` 的版本号，例如 `/release 2.6.0`；未提供时从 `CHANGELOG.md` 顶部最新的 `## [x.y.z]` 解析。

• 版本必须严格为 `MAJOR.MINOR.PATCH`。
• tag 固定为 `v{VERSION}`。

阶段 1：只读预检查

1. 确认当前在 `beta` 分支。 2. 工作区必须完全干净：

   git status --porcelain

有任何修改或未跟踪文件都停止，提示先提交或处理。 3. 检查 GitHub CLI 登录状态并获取最新远端引用：

   gh auth status
   git fetch origin main beta --tags

任一失败都停止。 4. 将候选提交固定为变量并在整个流程中保持不变：

   RELEASE_SHA=$(git rev-parse beta)
   VERSION_TAG="v{VERSION}"
   REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)

5. 确认本地 `beta` 没有遗漏远端提交，并通过共享规则 2 的 Star History 豁免检查：

   git log beta..origin/beta --oneline

有输出即停止并列出提交；再执行共享规则 2 的两条检查。 6. 检查本地 `main` 是否存在未推送提交。后续会把本地 `main` 精确移动到候选提交；若存在必须先交给用户处理：

   git log origin/main..main --oneline

7. 验证项目版本锚点、CHANGELOG 顶部版本及 Release tag 格式一致：

   python3 .github/scripts/check_project_version.py . \
     --expected "{VERSION}" \
     --tag "${VERSION_TAG}"

8. 按共享规则 3 查询当前 GitHub 最新稳定 Release。候选版本必须严格高于它。 9. 同时确认本地 tag、远端 tag、GitHub Release 都不存在：

   git tag -l "${VERSION_TAG}"
   git ls-remote --tags origin \
     "refs/tags/${VERSION_TAG}" \
     "refs/tags/${VERSION_TAG}^{}"
   gh release view "${VERSION_TAG}"

任一已存在都停止（共享规则 1）。

阶段 2：生成并审阅 Release Note

从 CHANGELOG 当前版本条目生成 `.releases/v{VERSION}.md`。该目录由 `.gitignore` 忽略。

格式：

# v{VERSION} — {一句话总结，提炼 2-4 个核心特性}

## ⭐ Highlights

- **{特性标题}**：{用户能获得的能力或修复}

## Added

{从 CHANGELOG Added 提炼}

## Changed

{从 CHANGELOG Changed 提炼}

## Fixed

{存在时加入}

## Docs

{存在时加入}

## Compatibility

{涉及 Unity 版本、可选包或破坏性变化时加入}

### 完整更改日志见 https://github.com/{owner}/{repo}/blob/main/CHANGELOG.md

Highlights 使用用户语言，突出“能做什么”，不要照搬内部实现；大量新增 Skill 可用详细版，基础设施更新用精简版。

显示完整 Release Note 给用户审阅。正式发布确认之前可以继续修改该临时文件，但不得修改已固定的 `RELEASE_SHA` 对应源码；若源码发生变化，必须从阶段 1 重新开始并重新跑矩阵。

阶段 3：推送 beta 并运行预发布完整矩阵

1. 将固定候选提交推送到远端 `beta`，然后验证远端精确一致：

   git push origin beta
   git fetch origin beta
   test "$(git rev-parse origin/beta)" = "${RELEASE_SHA}"

2. 记录当前最新的 workflow run ID，再从 `beta` 手动触发完整矩阵：

   BEFORE_RUN_ID=$(gh run list \
     --workflow unity-package-compile.yml \
     --limit 1 \
     --json databaseId \
     --jq '.[0].databaseId // 0')

   gh workflow run unity-package-compile.yml --ref beta

3. 轮询寻找同时满足以下条件的新运行，并赋值给 `PREFLIGHT_RUN_ID`：

• workflow 为 `unity-package-compile.yml`
• event 为 `workflow_dispatch`
• `headSha == RELEASE_SHA`
• `databaseId > BEFORE_RUN_ID`

   PREFLIGHT_RUN_ID=""
   for _ in $(seq 1 30); do
     PREFLIGHT_RUN_ID=$(gh run list \
       --workflow unity-package-compile.yml \
       --event workflow_dispatch \
       --branch beta \
       --limit 20 \
       --json databaseId,headSha \
       --jq "[.[] | select(.headSha == \"${RELEASE_SHA}\" and .databaseId > ${BEFORE_RUN_ID})] | sort_by(.databaseId) | last | .databaseId // empty")
     test -n "${PREFLIGHT_RUN_ID}" && break
     sleep 10
   done
   test -n "${PREFLIGHT_RUN_ID}" || { echo "未找到匹配的预发布运行" >&2; false; }

找不到、超时或 SHA 不一致时停止，不能误用旧的绿色运行。 4. 等待该运行完成：

   gh run watch "${PREFLIGHT_RUN_ID}" --exit-status

任一静态检查、Unity 版本或最终汇总失败都停止。修复后生成新提交，并从阶段 1 重新开始。

阶段 4：正式发布确认闸门

在执行任何 main 重写或 tag 创建前，向用户展示：

• `{VERSION}` 与 `RELEASE_SHA`
• Release Note 文件和完整内容
• 预发布矩阵的成功 URL
• `origin/main` 将从哪个 SHA 精确移动到哪个 SHA，以及随之丢弃的 Star History 图表提交数
• 接下来会创建不可复用的 `v{VERSION}` tag 并在检查成功后创建正式 GitHub Release

必须获得用户明确的“确认正式发布”后才能继续。普通的“看看”“准备一下”“生成说明”不构成授权。

阶段 5：安全同步 beta → main

用户确认可能跨越一个对话回合，不能假设之前的 shell 变量或远端状态仍然有效。继续前重新建立并核验固定值：

RELEASE_SHA="{阶段 4 展示并获确认的完整 SHA}"
VERSION_TAG="v{VERSION}"
PREFLIGHT_RUN_ID="{阶段 4 展示的预发布矩阵 run ID}"

git fetch origin main beta --tags
test -z "$(git status --porcelain)"
test "$(git branch --show-current)" = "beta"
test "$(git rev-parse beta)" = "${RELEASE_SHA}"
test "$(git rev-parse origin/beta)" = "${RELEASE_SHA}"
test -z "$(git tag -l "${VERSION_TAG}")"
test -z "$(git ls-remote --tags origin "refs/tags/${VERSION_TAG}" "refs/tags/${VERSION_TAG}^{}")"

再次执行共享规则 2 的两条检查（必须无输出），并通过 `gh run view "${PREFLIGHT_RUN_ID}" --json headSha,conclusion` 再次确认预发布矩阵仍是同一 `RELEASE_SHA` 且结