---
name: release
description: 发布 movieclaw 新版本。当用户要求发版、发布新版本、打 tag、看看哪些该发，或发布服务器、NER 模型、Docker 镜像、各客户端（iPhone、Apple TV、Mac 版、Mac 转码器、Android、Android TV、Windows），或打包上传 iOS App 到 TestFlight / App Store、补传发版附件时使用。涵盖产品与 tag 总览、改动检查脚本、通用发版流程、各产品要点、changelog、失败补救与检查清单。
---

# movieclaw 发布规范

服务器、模型和每个客户端都**各自单独发 GitHub Release**，互不搭车：发哪个由人决定，一个 tag 只发一个
产品。机制背景见 `docs/design/in-app-update.md`、`docs/design/android-release.md`、`docs/design/ios-release.md`。

## 一、先判定要发什么

### 产品与 tag

| 产品 | tag | 版本号在哪 | 工作流 | Release 标题 | 用户怎么拿到 |
|---|---|---|---|---|---|
| 服务器 | `vX.Y.Z` | `pyproject.toml` + `src/movieclaw_api/__init__.py` | `release.yml` | MovieClaw Server X.Y.Z | 设置页一键更新 / Docker 镜像 |
| iPhone / iPad | `ios-vX.Y.Z` | `apps/apple/project.yml` 的 `MARKETING_VERSION` | `apple-release.yml` | MovieClaw for iPhone and iPad X.Y.Z | TestFlight；未签名 IPA 侧载 |
| Apple TV | `tvos-vX.Y.Z` | 同上 | `apple-release.yml`（只建说明，无附件） | MovieClaw for Apple TV X.Y.Z | TestFlight |
| Mac 版 | `macos-vX.Y.Z` | 同上 | `apple-release.yml` | MovieClaw for Mac X.Y.Z | 官网下载公证 zip |
| Mac 转码器 | `transcoder-vX.Y.Z` | `macos/MovieClawTranscoder/Resources/Info.plist` | `apple-release.yml` | MovieClaw Transcoder X.Y.Z | 官网下载公证 zip |
| Android | `android-vX.Y.Z` | `apps/android/version.properties` | `android-release.yml` | MovieClaw for Android X.Y.Z | `movieclaw.io/download/android.apk` |
| Android TV | `androidtv-vX.Y.Z` | `apps/android-tv/version.properties` | `android-release.yml` | MovieClaw for Android TV X.Y.Z | `movieclaw.io/download/androidtv.apk` |
| Windows | `windows-vX.Y.Z` | `apps/desktop/src-tauri/Cargo.toml` + `apps/desktop/package.json` | `windows-release.yml` | MovieClaw for Windows X.Y.Z | 客户端内检查更新 |
| NER 模型 | `torrent-ner-vN` | 训练产物 | 手动（第五节） | MovieClaw NER Model N | 设置页一键更新模型 |

硬规则：

- **tag 命名**：服务器是主产品，用不带前缀的 `vX.Y.Z`；客户端一律「产品前缀-vX.Y.Z」；模型用整数。
  已部署的服务器只认 `v` 与 `torrent-ner-v` 两种前缀找更新，**这两个前缀不能改**；Windows 更新器只认
  `windows-v` 与 `MovieClaw-Windows-*` 安装包名，要改须先发一版同时认新旧名字。
- **只有服务器 Release 标 latest**：其余一律 `--latest=false`（流水线已带）。install-cli.sh 从
  `releases/latest/download` 取 mclaw，别的 Release 成了 latest 安装立刻 404。
- **tag 必须等于代码里的版本号**，同一版本发过就不能再发（流水线会拦）。发新版先递增版本号。
- Apple 三端共用 `MARKETING_VERSION`：同一版本每个平台只能发一次。某个平台要发而它已发过这个版本，
  先递增补丁号，其他平台下次随之用新版本号，跳号无妨。

### 看哪些该发

```bash
python3 scripts/release-status.py --ref origin/main
```

对每个产品列出上次发布的 tag、代码里的版本号、该产品目录下自上次发布改了多少文件（不算 `.md`）和
最近几条提交，结论是以下之一：「无改动，不用发」「有改动，但版本号还没递增」「有改动，版本号已递增，
可以发」「从未单独发布」。脚本只给事实，发不发由人定：只改了打包脚本、注释的「有改动」不一定值得发。

### 先后顺序

- 服务器新功能要配合新版 App：**先发 App 再发服务器**。服务器正文末尾的客户端一节取发布时各 App 的
  最新 Release，先发 App 它才列得出来；changelog 里写明需要的 App 版本。
- App 依赖新服务器接口：先发服务器，并上调 App 里的最低服务器版本（iPhone
  `AppModel.minimumServerVersion`、Android 手机 `SessionRepository` 的 `MIN_SERVER_VERSION`、
  Android TV `AppModel.MIN_SERVER_VERSION`），老服务器上 App 会在登录前提示先升级服务器。
- 改了转码器握手协议（`REMOTE_WORKER_PROTOCOL_VERSION` 与转码器 `BuildInfo.protocolVersion` 同步 +1）：
  旧转码器会被拒绝，先发新转码器，服务器 changelog 开头提示框写明「需要更新 Mac 转码器」。协议没变、
  只是新能力派给新版转码器（按自报能力派发）时，同样在提示框写明需要的转码器版本。

## 二、通用发版流程（所有产品）

1. **改版本号 + 写 changelog**（`docs/changelog/<tag>.md`，第四节），同一个 PR 合入 main。
   Android 的 `versionName` 与 `versionCode` 一起递增；Windows 的 Cargo.toml 与 package.json 一起改。
2. **推 tag**：`git tag <tag> && git push origin <tag>`，构建的就是 tag 所在的提交。
   推不了 tag 的环境（远程会话的 git 凭证只能推分支）走点火通道
   `git push origin main:refs/heads/release-kick/<tag>`：release-kick.yml 核对 main 上的版本号后
   触发对应工作流（在 main HEAD 上创建 tag），并删掉点火分支。人工兜底：Actions → 对应工作流 →
   Run workflow 输入 tag。
3. **流水线**：核对 tag 与版本号 → 建 draft → 构建 / 签名 / 测试 → 校验产物 → 转正。draft 期间对
   应用内更新、官网、install-cli.sh 都不可见。**任何一步失败 Release 停在 draft，修好后重跑整个
   工作流即可**（上传均带 `--clobber`，可安全重入）。
4. **验证**：Release 页附件齐全、标题对、正文是 changelog 而不是自动生成的 PR 清单、没有被标成 latest
   （服务器除外）。

changelog 晚于发版合入也没关系：release-notes.yml 会把 `docs/changelog/<tag>.md` 同步成对应
Release 的正文（服务器顺带重新生成 release.json 与客户端一节，Windows 顺带附上验证范围）。

## 三、各产品要点

### 服务器（`vX.Y.Z`）

- **版本号三处一致**（构建脚本强制校验）：`pyproject.toml` 的 version、`src/movieclaw_api/__init__.py`
  的 `__version__`、tag 去掉 `v`。bump 后跑 `scripts/export-spec.sh`（服务端与 Go CLI 两份 spec）；
  基线 `spec.json` 是构建产物，不入 git。
- **以发版 PR 的 CI 全绿为准**：改了 `__init__.py` 的版本号会触发全量检查（ruff / pytest / cli / web /
  Worker 加 iOS 编译），无需本地重跑全量——本地 pytest 要先下载 NER 模型，沙箱代理还会误报。
- **产物**：应用三件套（app-web.tar.gz / app-backend.tar.gz / manifest.json，启用签名时含
  manifest.json.sig）、mclaw 六平台归档 + checksums.txt、release.json（官网更新日志读它），同时
  发布多架构 Docker 镜像（movieclaw/movieclaw：正式版打 vX.Y.Z + runtime-N + latest，预发布只打
  vX.Y.Z-…）。不带任何客户端。
- **正文**：changelog 原文，末尾由 `scripts/publish-release-body.sh` 自动补「Apps / 客户端」一节——
  上一个服务器版本以来新发的 App（带链接），以及每个 App 的最新版本与安装方式。
- **预发布**：tag 带后缀（`v0.3.0-beta.1`）自动标 prerelease，应用内更新跳过它；后缀数字按数值比较。
- **Docker 镜像与 runtime 契约**：`docker/runtime-version` 是运行时依赖集合的版本代号。改了
  `pyproject.toml` 的 dependencies、Node 大版本、Dockerfile 的系统包（ffmpeg 等）或基础镜像、
  `docker/entrypoint.sh` 的行为契约（重启约定码、目录约定），必须 +1（runtime-guard.yml 会拦漏 bump
  的 PR）。之后发的 Release 声明新的 `requires_runtime`，旧镜像用户会看到「需升级 Docker 镜像」。
  镜像随发版自动发布；单独补发到 Actions → docker-image 输入标签；本地构建
  `TMDB_API_KEY=xxx ./scripts/build-image.sh`（启用清单签名时带
  `--build-arg UPDATE_MANIFEST_PUBKEY=<公钥>`）。
- 改了播放/转码 → 发版前做第七节的硬件转码人工验收。

### Apple 平台（`ios-v` / `tvos-v` / `macos-v` / `transcoder-v`）

- 一个工作流 `apple-release.yml` 按 tag 前缀分别构建：iPhone 编未签名 IPA；Apple TV 不构建，只建一条带
  说明的 Release；Mac 版与转码器在 xcode-27 / macos-26 上编译，Developer ID 签名并公证，生成
  `downloads.json` 供官网下载页读取（macOS runner 上复核签名与公证）。
- 转码器版本只在它自己的 `Info.plist`，不跟服务器走。
- TestFlight / App Store 的上传与 GitHub Release 互不依赖，见第六节。

### Android（`android-v` / `androidtv-v`）

- `android-release.yml` 正式签名构建 APK，附 `.json` 元数据与 `downloads.json`。正式包要求完整原生
  播放器依赖与固定签名证书，禁止用 debug 证书或 Exo-only 包替代。两个 App 共用一组 Secrets：
  `ANDROID_KEYSTORE_BASE64`、`ANDROID_KEYSTORE_PASSWORD`、`ANDROID_KEY_ALIAS`、`ANDROID_KEY_PASSWORD`；
  已有官方签名密钥必须沿用，不能因构建失败而重新生成；密钥不入 git、不贴聊天。
- 本地验证：配置签名环境变量后 `bash apps/android/scripts/package-release.sh`（TV 为
  `apps/android-tv/scripts/package-release.sh`）。全景见 `docs/design/android-release.md`。

### Windows（`windows-v`）

- `windows-release.yml` 调用 Desktop CI 跑完整测试并打包（单测、浏览器端到端、Rust 测试、安装冒烟），
  再用 `apps/desktop/scripts/check-release-evidence.py --policy ci-verified` 校验安装包就是测试过的那份、
  版本与提交都对得上，然后上传安装包、便携 ZIP、带构建号的两个 ZIP、`SHA256SUMS.txt`、
  `release-manifest.json` 并转正。
- 正文 = `docs/changelog/windows-vX.Y.Z.md` + `apps/desktop/release/ci-verified-scope.md`（说明托管 CI
  覆盖不到的硬件项，带 `ci-verified` 标记，校验脚本要求有它）。changelog 里不用再写这段。
- 安装包未签名：用户更新时会被要求确认；实际签名状态记录在 `release-manifest.json`。

## 四、changelog

**动笔前必读 `changelog-guide.md`**（本目录下）。一句话：changelog 是写给用户的产品更新说明，不是
变更清单——先用 `git log` 盘点保证不漏，再挑 1～3 个亮点按「痛点 → 现在 → 入口」写，修复只写用户能
认出的症状，其余交给文末的 compare 链接。样板见 `docs/changelog/v0.27.0.md`。

- 文件名与 tag 同名：`docs/changelog/<tag>.md`。英文在前、完整中文在后，中间 `---` + `## 简体中文`。
- 服务器标题行写 `## vX.Y.Z: 主题`（release.json 按它解析）；客户端写 `## <产品名> X.Y.Z: 主题`，
  只写这个 App 自己的变化。
- **服务器 changelog 不写客户端版本号**（客户端一节自动生成）；「需不需要更新某个 App」写在正文里。

## 五、NER 模型（`torrent-ner-vN`）

1. 训练产出三件套：`model.int8.onnx`、`tokenizer.json`、`labels.json`
2. 生成更新清单（tag 必须与将要创建的 Release 一致，后端强校验）：
   `./scripts/build-model-manifest.sh <模型目录> torrent-ner-vN`
3. 创建 Release（N 递增），**必须 `--latest=false`**：
   `gh release create torrent-ner-vN --latest=false --title "MovieClaw NER Model N" …`，
   上传三件套 + `manifest.json`（启用签名时含 `manifest.json.sig`），正文用 `docs/changelog/torrent-ner-vN.md`
4. 没带 manifest.json 的模型 Release 无法应用内安装，只能作为镜像构建的 `NER_MODEL_BASE` 来源

## 六、TestFlight / App Store

与 GitHub Release 相互独立；同一个构建既进内部 / 对外 TestFlight 也用于提审。完整说明见
`docs/design/ios-release.md`，账号持有人的一次性准备与对外测试步骤见 `docs/design/ios-release-checklist.md`。

1. 打包机准备（每台新 Mac 一次）：本机签名配置 `Signing.local.xcconfig` 写团队 ID；
   App Store Connect API 密钥**必须「管理」角色**（「App 管理」用不了云端发布证书，
   Xcode 27 的命令行又读不到 Xcode 里登录的账号）；密钥 ID / Issuer ID 放仓库外的本机 env 文件，
   `.p8` 放 `~/.appstoreconnect/private_keys/`，全部不入库、不贴进聊天。
   新证书首次打包前让账号持有人自己执行一次钥匙串分区授权
   （`security set-key-partition-list …`，要输 Mac 登录密码），否则会弹出几十个授权框。
2. 从 main 打包上传：`source <本机 env> && apps/apple/scripts/release.sh --upload`
   （不带 `--upload` 只导出，用于先验证签名）。构建号取 UTC 时间自动递增。
   Apple TV 版加 `--tv`、Mac 版加 `--mac`（同一条 App 记录、各自一条构建序列），几端都要发就各跑一次。
   TestFlight 的审核账号、备注与「Beta 版 App 描述」三端共用，提审前按 `docs/design/ios-release.md` §4 核对；
   各端的「测试内容」只写那一端真有的功能。
3. 上传后 5～30 分钟处理完；可用 ASC API 查 `processingState` / `buildAudienceType`。
   开了自动分发的内部测试组会自动收到；对外测试组按 checklist §5 加构建、提审。
4. 看 Apple 邮件：ITMS-91053 等警告按邮件补隐私清单。

## 七、硬件转码矩阵人工验收（改动播放/转码时必做）

CI 里没有显卡，`-m "not integration"` 的门禁**完全覆盖不到硬件转码**——
装配参数有单测、软件转码有集成测试，但「这块显卡上真能不能转」只有人能验。
凡是改了 `services/playback/`（尤其 `ffmpeg_args.py` / `hwprobe.py`）或换了
ffmpeg 版本，发版前按下表逐项过一遍。

每种硬件重复这几步：

1. 打开「设置 → 播放 → 查看检测详情」，确认该后端显示为可用；若不可用，
   照它给的中文提示改配置后按「重新检测」——这条提示本身也是被验收对象。
2. 播一部 **HEVC + DTS 的 MKV**（走档 2 音频单转）与一部 **4K HDR**
   （走档 3 硬件转码 + 色调映射），各拖几次进度条。
3. 记录「播放诊断」面板里的档位、是否硬件加速、掉帧数。
4. 播放中在宿主机确认 GPU 真的在动（`intel_gpu_top` / `nvidia-smi` /
   `radeontop`），别被「软件转码也能出画」骗过去。

| 硬件 | 自检可用 | 档 2 直通 | 档 3 转码 | HDR 转 SDR | 掉帧 <1% |
|---|---|---|---|---|---|
| Intel 核显（VAAPI/QSV） | ☐ | ☐ | ☐ | ☐ | ☐ |
| NVIDIA（NVENC） | ☐ | ☐ | ☐ | ☐ | ☐ |
| AMD（VAAPI） | ☐ | ☐ | ☐ | ☐ | ☐ |
| 无显卡（软件兜底） | — | ☐ | ☐ | 应明确拒绝 | ☐ |

另外三项与硬件无关但同样只能人验：

- [ ] **播放器真机走查**：内封 ASS 番剧（字体、特效、时间轴微调）、内封 SRT、
      外挂字幕、切下一集、续播点、进度条缩略图预览
- [ ] **iOS**：同局域网 iPhone 打开播放页，确认走原生 HLS 且全屏可用
- [ ] **Safari**：HEVC 直通不黑屏（`hvc1` 标签那条陷阱只有 Safari 能验）

## 八、失败补救

- **服务器**：cli 或镜像作业失败时 Release 停在 draft，修好后到 Actions 重跑 release 工作流。
- **ios-ipa / mac-app 编译失败**：多半是 CI 的 Xcode 比本机旧（见 ios-release.md §5，PR 上的 `ios`
  检查能复现），开 PR 修 CI 兼容后重跑 apple-release。急用时本机 `git checkout <tag>` 后跑
  `apps/apple/scripts/build-unsigned-ipa.sh` 或
  `MOVIECLAW_SIGNING_IDENTITY="Developer ID Application: …" MOVIECLAW_NOTARY_PROFILE=<凭证名> apps/apple/scripts/package-mac-app.sh`，
  再 `gh release upload <tag> <产物> --clobber` 补传，并手动转正（`gh release edit <tag> --draft=false --latest=false`）。
  人工补传 Mac 版或转码器 ZIP 后，在 macOS 上运行 `bash scripts/publish-download-manifest.sh <tag>` 刷新官网清单。
- **mac-app / transcoder 公证失败**，按报错对仓库密钥：
  - `--issuer … must be a valid UUID` → `APPLE_API_ISSUER_ID` 值不对（常见多带空格 / 换行）
  - `HTTP status code: 401` → `APPLE_API_KEY_ID` 与 `APPLE_API_KEY_P8` 不是同一把，或密钥已撤销
  - 「没有 Developer ID Application 证书」→ `.p12` 导出的是别的证书
  `.p8` / `.p12` 属于凭证，由账号持有人自己 `gh secret set`（从本机文件重定向输入，不经聊天）。
  改好后重跑 apple-release；可下载产物本机 `spctl -a -vv` 看到 `Notarized Developer ID` 即成功。
- **Android 构建失败**：见 `docs/design/android-release.md`；不以无签名包或 Exo-only 包绕过。
- **Windows**：Desktop CI 失败就先修 CI（PR 上的 Desktop CI 能复现）；校验失败说明安装包与测试过的不是
  同一份、或版本 / 提交对不上，重跑整个 windows-release，不要手动拼附件。

## 九、清单签名（可选，防 Release/加速镜像被篡改）

- 首次启用：`./scripts/gen-release-signing-key.sh` 生成密钥对；私钥配成
  仓库 Actions 机密 `RELEASE_SIGNING_KEY`（绝不入库），公钥烧进镜像
  （`UPDATE_MANIFEST_PUBKEY` 构建参数）或让用户配同名环境变量
- 启用后：服务器发版自动签名；模型清单脚本在有 `RELEASE_SIGNING_KEY`
  环境变量时也会生成签名
- 注意：部署侧配置了公钥后，**所有**更新清单必须携带有效签名，包括
  模型 Release——启用后发的每个 Release 都不能漏传 `.sig`

## 十、发版检查清单

服务器：

- [ ] 版本号三处一致，已跑 `scripts/export-spec.sh`
- [ ] 需要配合新版 App 的功能，对应 App 已先发布，changelog 写明了所需版本
- [ ] 触碰运行时依赖 → `docker/runtime-version` +1
- [ ] 改了转码器握手协议或新能力只派给新版转码器 → 新转码器已先发，提示框写明
- [ ] 数据库迁移向前兼容（alembic 迁移是单向的，用户回退靠自动备份）
- [ ] release 工作流全绿、Release 已转正且是 latest，正文末尾的客户端一节版本正确
- [ ] changelog 已按 `changelog-guide.md` 自检过第一屏（应用内更新界面原文展示）
- [ ] 改动了播放/转码 → 第七节的硬件矩阵人工验收已过

客户端：

- [ ] `python3 scripts/release-status.py` 看过，版本号已递增
- [ ] App 依赖新服务器接口 → 最低服务器版本已上调，服务器已先发
- [ ] 对应工作流全绿，Release 已转正、没有标成 latest，附件齐全
- [ ] Mac 版 / 转码器 / Android：官网下载页显示了新版本（缓存最多 1 小时）