---
name: alcomd3-release
description: 执行或审计 ALCOMD3 发布流程。用于准备、验证、记录或修复 ALCOMD3 stable/beta 发布，包括版本一致性、Windows artifact 构建、updater 签名、GitHub Release assets、updater JSON 和网站发布。
---

# ALCOMD3 Release Skill

从仓库根目录使用此 skill。先阅读 `AGENTS.md`。如果修改网站文件，也要阅读
`website/AGENTS.md`。

完整人类发布手册默认入口是 `docs/RELEASE.md`，中文版本是
`docs/RELEASE.zh-CN.md`。本文件是给 Agent 使用的单语执行清单。

## 触发条件

用户任务涉及以下任一内容时使用此 skill：

- stable/beta 发布；
- 发布审计或发布状态检查；
- 版本准备、版本号同步或 release notes；
- Windows release artifacts 构建、签名、校验或上传；
- GitHub Release draft/prerelease/release；
- updater JSON、public updater endpoint 或 website deployment 后检查。

## 核心模型

发布由 `xtask` 驱动，分为三个阶段、两个提交：

1. Source release commit：版本 metadata 和 release notes。GitHub Release tag 指向这个提交。
2. GitHub Release：签名后的 Windows installer artifacts。
3. Updater metadata commit：GitHub Release assets 公开后，提交 generated updater JSON。

不要把 updater JSON 和 source release commit 混在一起提交。

## 不可违反的规则

- 使用 ALCOMD3 release automation、secrets、updater metadata 和 release names。
- 不手改所有版本文件；使用 `cargo xtask release-prepare`。
- Rust 发布版本源是 root `Cargo.toml` 的 `[workspace.package].version`。
- Rust workspace members 必须使用 `version.workspace = true`。
- 不使用 `TAURI_SIGNING_*` 变量。只使用：
    - `ALCOMD3_UPDATER_PRIVATE_KEY`
    - `ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD`
- `release-build` 在变量未设置时会自动加载 `artifacts/alcomd3-updater-key/`：
    - 优先 `private-key.ps1`
    - 否则 `private-key.env`
- 未明确要求时，不要同时更新 stable 和 beta updater JSON。
- 匹配的 GitHub Release asset 公开且可下载前，不发布 website updater JSON。
- 不编辑、stage 或提交 `artifacts/`、`target/` 下的文件。
- 用户只要求 audit 时，不发布、不上传、不改外部状态。

## 必须确定的输入

- `Version`：例如 `2.0.1` 或 `2.1.0-beta.1`。
- `Channel`：`stable` 或 `beta`。
- 任务类型：audit-only、prepare-only，还是实际 release。
- 是否授权 GitHub Release 创建、上传、发布。
- 是否授权 `git commit` / `git push`。
- Website hosting 是自动部署 `origin/main`，还是需要外部 UI/CLI 手动部署 `website/dist`。

## 关键路径

- 人类发布手册：`docs/RELEASE.md`；中文版本：`docs/RELEASE.zh-CN.md`
- Updater 签名指南：`docs/ALCOMD3_UPDATER.md`；中文版本：`docs/ALCOMD3_UPDATER.zh-CN.md`
- Stable updater JSON：`website/public/api/gui/tauri-updater.json`
- Beta updater JSON：`website/public/api/gui/tauri-updater-beta.json`
- Release notes：`release-notes/ALCOMD3_{version}.md`
- Release artifacts：`artifacts/release/v{version}/`
- Public installer check：`artifacts/release-check/v{version}/`
- Website static output：`website/dist`

Channel mapping：

```text
stable -> website/public/api/gui/tauri-updater.json -> GitHub normal release
beta   -> website/public/api/gui/tauri-updater-beta.json -> GitHub prerelease
```

## Audit workflow

1. 检查本地状态：

    ```powershell
    git status --short
    gh auth status --hostname github.com
    ```

2. 检查版本源：

    ```powershell
    cargo metadata --no-deps --format-version 1
    ```

    确认 root `Cargo.toml` 有 `[workspace.package].version`，release-facing Rust packages 继承该版本。

3. 如果 GitHub Release 在范围内，检查 release state：

    ```powershell
    gh release view "v$Version" --repo CQMHV/ALCOMD3 --json tagName,isDraft,isPrerelease,targetCommitish,publishedAt,assets
    ```

4. 如果 updater JSON 和 installer 可用，验证：

    ```powershell
    cargo xtask verify-alcom-updater-json --installer $Installer --json $UpdaterJson
    ```

修改 release state 前先报告 blocker。

## Release workflow

1. 从 clean main 开始：

    ```powershell
    git checkout main
    git pull --ff-only
    git status --short
    gh auth status --hostname github.com
    ```

2. 准备 source release files：

    ```powershell
    cargo xtask release-prepare --version $Version --channel $Channel
    ```

    然后编辑 `release-notes/ALCOMD3_$Version.md`，删除 placeholder text。

3. 提交并推送 source release commit。只有用户授权时才执行 commit/push：

    ```powershell
    git add Cargo.toml Cargo.lock
    git add vrc-get-gui/package.json vrc-get-gui/package-lock.json
    git add website/package.json website/package-lock.json
    git add "release-notes/ALCOMD3_$Version.md"
    git status --short
    git commit -m "release: prepare ALCOMD3 $Version"
    git push origin main
    ```

4. 构建、签名并验证 artifacts：

    ```powershell
    cargo xtask release-build --version $Version --channel $Channel
    ```

    Dry-run：

    ```powershell
    cargo xtask release-build --version $Version --channel $Channel --dry-run
    ```

5. 创建 GitHub Release draft。只有用户授权时才执行：

    ```powershell
    cargo xtask release-publish --version $Version --channel $Channel
    ```

    如果 draft 已存在且明确要替换 assets：

    ```powershell
    cargo xtask release-publish --version $Version --channel $Channel --replace-assets
    ```

6. 发布 GitHub Release。只有用户授权时才执行：

    ```powershell
    cargo xtask release-publish --version $Version --channel $Channel --replace-assets --publish
    ```

7. GitHub Release 公开后，提交 updater metadata。只有用户授权时才执行 commit/push：

    ```powershell
    cargo xtask release-updater --version $Version --channel $Channel --commit --push
    ```

8. Website deployment 完成后检查 public endpoint：

    ```powershell
    cargo xtask release-updater --version $Version --channel $Channel --skip-website-build --check-public
    ```

## 最终报告要求

至少报告：

- version 和 channel；
- source release commit；
- GitHub Release state；
- updater metadata commit；
- 修改的 updater JSON path；
- release artifacts path；
- public updater endpoint check 结果；
- 已运行的 validation/build/sign/verify commands 及结果；
- 未运行的 commands 及原因。

## Failure handling

如果 release notes 缺失或仍含 placeholder、signing variables/signing key loader 缺失、版本不一致、validation 失败、
updater verification 失败、GitHub Release assets 缺失或命名不同、worktree 包含重叠的 unrelated changes，或 publishing 需要用户未授权的权限，则停止并请求指示。
