/updateversion

description: 安全更新项目版本锚点并生成 CHANGELOG（只准备候选，不发布）
argument-hint: "<MAJOR.MINOR.PATCH>"
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 api:*), Bash(gh release view:*), Bash(python3 .github/scripts/check_project_version.py:*), Bash(python3 .github/scripts/check_meta_files.py:*), Bash(python3 .github/scripts/check_locales.py:*), Bash(python3 -m json.tool:*), Read, Grep, Glob, Edit

Update Version — 安全更新项目版本 + 生成 CHANGELOG

你是 UnitySkills 项目的版本更新助手。此命令只负责准备一个可发布的版本候选；它不会创建 tag 或 GitHub Release，也不会立即向已安装用户发送更新提醒。

Unity 内的更新提醒使用 `SkillsLogger.Version` 与 GitHub `releases/latest` 的稳定 Release 比较。只有正式发布新的非 draft、非 prerelease GitHub Release 后，用户才会看到更新横幅，并跳转到该版本的 `/releases/tag/v{VERSION}` 页面。

输入

用户必须提供不带 `v` 的稳定语义版本号，例如 `/updateversion 2.6.0`。

• 只接受严格的 `MAJOR.MINOR.PATCH`。
• 不接受 `v2.6.0`、`2.6`、`2.6.0-beta.1` 或四段版本号。
• 未提供或格式不合法时停止，并提示：`/updateversion <新版本号>`。

步骤 1：远端与版本线预检查

1. 确认当前在 `beta` 分支；不在则停止。 2. 确认 GitHub CLI 已登录：

   gh auth status

3. 获取最新远端引用。任何 fetch 失败都必须停止，不能用过期的本地引用继续判断：

   git fetch origin main beta --tags

4. 检查工作区：

   git status --porcelain

有未提交改动时明确警告，但不阻止，因为这些改动可能正是本次待发布内容。后续只修改约定的版本锚点，不覆盖其他改动。 5. 确认 `beta` 没有遗漏远端提交：

   git log beta..origin/beta --oneline

有输出即停止：本地 `beta` 落后于远端，必须先同步或处理分歧。`origin/main` 相对 `beta` 的检查与 `/release` 完全相同：执行 `.claude/commands/release.md`「共享规则」第 2 条的两条 Star History 豁免检查，均须无输出。 6. 从 `origin/main` 的 `SkillsLogger.Version` 读取当前稳定版本 `{OLD_VER}`，不要依赖可能过期的本地 `main`：

   git show origin/main:SkillsForUnity/Editor/Skills/SkillsLogger.cs

7. 按 `release.md`「共享规则」第 3 条查询 GitHub 当前最新稳定 Release：

• 正常情况下其版本应等于 `{OLD_VER}`；若不一致，停止并报告“main 当前版本与 latest Release 已错位”，不要猜测基准版本。

8. 验证当前工作树内的所有项目版本锚点仍等于 `{OLD_VER}`：

   python3 .github/scripts/check_project_version.py . --expected "{OLD_VER}"

不一致时先修复已有漂移，不得继续批量升版。 9. 用数值元组比较语义版本。`{NEW_VER}` 必须严格高于 `{OLD_VER}`，也必须严格高于 GitHub latest Release 的版本；禁止使用字符串字典序比较。 10. 判定本次更迭级别 `{BUMP_LEVEL}` 并记录下来，步骤 4 与步骤 5 都依赖它：

• 把 `{OLD_VER}` 与 `{NEW_VER}` 各自拆成 `MAJOR.MINOR.PATCH` 三段整数后逐段比较，不做字符串比较。
• `MAJOR` 段不同 → `major`；`MAJOR` 相同而 `MINOR` 段不同 → `minor`；只有 `PATCH` 段不同 → `patch`。
• 例：`2.9.1 → 3.0.0` 是 `major`；`2.6.3 → 2.7.0` 是 `minor`；`2.3.1 → 2.3.2` 是 `patch`。
• 只有 `major` / `minor` 会让 `.github/SECURITY.md` 进入本次改动范围（见步骤 4）。

步骤 2：版本号占用检查

同时检查本地 tag、远端 tag 和 GitHub Release；任一已存在都停止，版本号不可复用：

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

• `gh release view` 返回“未找到”才表示该检查通过。
• tag 规则见 `release.md`「共享规则」第 1 条（含“已创建 tag 但无 Release 同样视为占用”）。

步骤 3：分析 beta 相对稳定版的变更

统一以 `origin/main` 为稳定基线，不使用本地 `main`：

git log origin/main..beta --oneline
git diff origin/main --stat
git status --short

`git diff origin/main` 会同时覆盖 `beta` 已提交差异及当前已跟踪的工作区改动。还要单独审阅 `git status` 中的未跟踪文件。

如果既没有提交差异，也没有实质性工作区差异，停止并询问用户是否确实要创建仅含版本号的空版本。

对关键功能文件查看具体 diff，重点关注：

• `SkillsForUnity/Editor/**/*.cs`
• `SkillsForUnity/Editor/**/*.uxml`、`*.uss`
• `SkillsForUnity/Editor/Locales/*.json`
• `SkillsForUnity/unity-skills~/skills/**/*.md`
• `SkillsForUnity/unity-skills~/scripts/unity_skills.py`
• `.github/workflows/**` 与 `.github/scripts/**`
• 用户可感知的 README、安装和兼容性变化

基于 commit message 与实际 diff 组织 CHANGELOG：

• **Added**：新增功能、新 Skill、新参数。
• **Changed**：行为、API、工作流或文档契约变化。
• **Fixed**：缺陷修复。
• **Docs**：纯文档变化，可选。

每条使用中文，以 `**粗体标题** — 描述` 编写；描述具体但不堆砌实现细节。

步骤 4：只更新明确的项目版本锚点

用 Edit 工具直接精确修改以下锚点文件（`.github/SECURITY.md` 是另列的条件锚点，只在 minor / major 更迭时纳入，见本步骤末尾）：

| 文件 | 唯一允许修改的版本锚点 | |------|------------------------| | `SkillsForUnity/Editor/Skills/SkillsLogger.cs` | `public const string Version = "{OLD_VER}";` | | `SkillsForUnity/package.json` | 顶层 `"version": "{OLD_VER}"` | | `SkillsForUnity/unity-skills~/scripts/unity_skills.py` | `__version__ = "{OLD_VER}"` | | `AGENTS.md` | 项目表格行 `| Version | {OLD_VER} |` | | `CHANGELOG.md` | 在原最新条目前插入 `## [{NEW_VER}] - {TODAY}` 与本次变更内容 |

> README×2 不再承载版本锚点，`check_project_version.py` 已同步；不要往 README 回加版本标记。

CHANGELOG 的 `Changed` 中追加：

- **版本号更新** — `SkillsLogger.Version` / `package.json` / Python helper `__version__` / `AGENTS.md` 同步提升到 `{NEW_VER}`。

`{BUMP_LEVEL}` 为 `minor` 或 `major` 时，同一条目末尾补一句：`受支持版本表（.github/SECURITY.md）同步到 {NEW_MAJOR}.{NEW_MINOR}.x。`

条件锚点：SECURITY.md 受支持版本表（仅 minor / major 更迭）

`.github/SECURITY.md` 的 “Supported Versions | 支持的版本” 表按版本线声明支持范围，因此只在版本线本身发生变化时才需要同步：

| `{BUMP_LEVEL}` | 示例 | `.github/SECURITY.md` | |----------------|------|------------------------| | `major` | `2.9.1 → 3.0.0` | 必须更新受支持版本表 | | `minor` | `2.6.3 → 2.7.0` | 必须更新受支持版本表 | | `patch` | `2.3.1 → 2.3.2` | 不修改，在步骤 6 摘要中注明“无需变更” |

需要更新时，沿用该表现有的两行结构与“只支持当前版本线”的策略，仅替换版本数字，不改列标题、不增删行：

| Version | Supported |
|---------|-----------|
| {NEW_MAJOR}.{NEW_MINOR}.x   | ✅ |
| < {NEW_MAJOR}.{NEW_MINOR}   | ❌ |

• 只改这张表。“Reporting a Vulnerability”“Response Timeline”等其它章节一律不动。
• 表下方的 Unity 维护基线说明只有在基线真的变化时才改，不随版本号机械改写。
• 不新增该表当前不存在的支持档位（如 LTS、多版本线并行支持）。若本次发布确实要继续支持上一条版本线，停下来询问用户，不要自行发明支持策略。
• `check_project_version.py` **不覆盖** SECURITY.md，这条改动只能靠人工核对 diff（见步骤 5）。

禁止宽泛替换

• 不得在 README、SKILL.md 或整个仓库里把所有 `{OLD_VER}` 替换成 `{NEW_VER}`。
• 第三方 SDK、NGO、PICO、Unity 包兼容性说明中的相同数字必须保留。
• `VersionCheckServiceTests` 中用于边界测试的旧版本字符串是测试数据，不随项目升版机械修改。
• 不修改 `docs/SETUP_GUIDE.md`、`docs/SETUP_GUIDE_CN.md` 中用户手动维护的 `#v...` 指定版本安装示例。
• `SkillsHttpServer.cs`、`SkillRouter.cs`、`FooterController.cs` 等运行时位置引用 `SkillsLogger.Version`，无需硬编码修改。

步骤 5：机器可验证的一致性检查

依次执行：

python3 .github/scripts/check_project_version.py . --expected "{NEW_VER}"
python3 .github/scripts/check_meta_files.py .
python3 .github/scripts/check_locales.py .
python3 -m json.tool SkillsForUnity/package.json >/dev/null
git