Release

Release 流程

发布前置条件(缺一不发):工作树干净、改动已推送、真机 deploy-verify 已过。

发布完成标准:所有发布均须 GitHub Release / CI 成功、三个安装包抽验通过；正式版还必须将三个包传入 Steam Deck 的下载目录并通过远端 SHA-256 校验。只完成上传 GitHub 不算正式版完整交付。预发布版默认不要求设备交付，用户明确要求时才执行。

0. 判定发布类型

• full:player / provider(含 wire、QQMusicApi-rs、ncm-api-rs 依赖)代码或依赖有变 → 需重建二进制、更新指纹
• zip-only:只有 bridge(py_modules)/ 前端(src)/ 文档变 → 二进制沿用上个 tag 的资产, remote_binary 的 URL 和 sha256 保持指向旧 tag 不动(内容没变,不重复上传)

1. 版本号(三处 + 锁文件)

新版本号记为 X(如 1.0.0-beta.3),tag 为 vX:

sed -i 's/"version": "旧"/"version": "X"/' package.json
sed -i 's/^version = "旧"/version = "X"/' player/Cargo.toml provider/Cargo.toml
cargo update -p player -p provider --offline              # 同步 Cargo.lock

2. full 才做:重建二进制 + 指纹

bash scripts/build-rust.sh -p player -p provider
ldd target/release/player             # 命门:除基础 libc 外只允许 libasound(provider 一个都不许多)

资产名固定(Decky 按 remote_binary[].name 存文件):player-linux-x64、 provider-linux-x64。算 sha256 填回 package.json 的 remote_binary[].sha256hash,URL 改成 tag 钉死: releases/download/vX/<asset>(pre-release 不能用 latest,会 404)。

3. 提交、tag

git add -A && git commit -m "chore(release): vX ..."   # zip-only 在提交信息里注明二进制沿用哪个 tag
git push && git tag vX && git push origin vX

4. GitHub Release

# pre-release 加 --prerelease;full 上传两个二进制资产,zip-only 不带资产
gh release create vX [--prerelease] --title "vX" --notes-file <notes.md> [assets...]

发布说明只保留:

• 改动:从 git log v旧..HEAD --oneline 提炼用户可感知的要点,不要逐条抄 commit。
• 安装:普通版用 Decky.Music.zip;CN 版通过 Decky Manual Plugin Install 安装 https://dl.nvimer.org/decky_music/decky-music-cn.zip;网络受限时用自包含的 Decky.Music.full.zip。

不写体验、依赖、致谢或开发背景。

5. CI 出包 + 抽验(必做)

release.yml 监听 release published,用官方 Decky CLI 打 Decky.Music.zip 传回资产:

RUN=$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN --exit-status
gh release download vX -p "Decky.Music.zip" -D <tmpdir> && cd <tmpdir> && unzip -q Decky.Music.zip

抽验清单:

• package.json 里版本 = X;remote_binary 两条 URL 指向预期 tag、指纹与本地构建一致
• 无 dev_mode 文件(有 = 日志级别错,zip 不该含它)
• 本次发布的关键改动在包里(grep 一两个新符号)
• CN 版:R2 上 curl -fI https://dl.nvimer.org/decky_music/vX/<两个资产> 与 .../decky_music/decky-music-cn.zip 均 200;解包 Decky.Music.cn.zip,其 remote_binary 两条 URL 以 https://dl.nvimer.org/decky_music/vX/ 开头、sha256 与普通版逐一相等
• full 版:release 资产有 Decky.Music.full.zip;解包后 package.json 无 remote_binary; bin/player、bin/provider 两个文件都在,且 sha256 与普通版 remote_binary[].sha256hash 逐一相等(证明内置的就是校验过的那份)

6. 每次正式发布后强制交付三个包到 Steam Deck

仅正式版每次都必须执行，包括 full / zip-only 两种发布类型。 正式发版请求默认包含这一步，不再等待用户另行要求下载安装包。 pre-release / beta 默认不自动传到设备；用户明确要求时，再按下述步骤交付。

1. 等本次 tag 的 CI 成功、步骤 5 抽验通过后，从该 tag 的 GitHub Release 获取以下三个资产。 步骤 5 已下载并验证过的本次产物可直接复用；禁止拿旧 out/ 包或 latest 资产充数。
2. 复用本轮已确认的 SSH 目标与认证环境，DECK_HOST 不设硬编码默认值。通过 ssh -- "$DECK_HOST" xdg-user-dir DOWNLOAD 查询设备实际下载目录；不要写死 /home/deck/Downloads。查询失败、路径为空或目录无法确认时先解决，不能误放进 home 或插件目录。
3. 使用带版本号的文件名交付，保留设备上其他版本。若同名文件已存在，先核对内容； 相同则复用，不同则停止确认，不静默覆盖。

下载与传输示例（先设置本次 TAG、本地临时目录 work、已确认的 DECK_HOST 和 DECK_DOWNLOAD_DIR）：

gh release download "$TAG" \
  -p "Decky.Music.zip" -p "Decky.Music.full.zip" -p "Decky.Music.cn.zip" -D "$work"
mv "$work/Decky.Music.zip" "$work/Decky.Music.${TAG}.zip"
mv "$work/Decky.Music.full.zip" "$work/Decky.Music.${TAG}.full.zip"
mv "$work/Decky.Music.cn.zip" "$work/Decky.Music.${TAG}.cn.zip"
rsync -av --protect-args \
  "$work/Decky.Music.${TAG}.zip" \
  "$work/Decky.Music.${TAG}.full.zip" \
  "$work/Decky.Music.${TAG}.cn.zip" \
  "${DECK_HOST}:${DECK_DOWNLOAD_DIR}/"

4. 对设备上的三个实际文件分别计算 SHA-256，与本地已验证的发布产物逐一比较， 同时核对文件大小。不能仅凭 rsync/scp 返回成功或目录里有同名文件就算通过。
5. 回复三个包的实际完整路径、版本和校验结果；清理本轮临时文件、SSH 会话， 若开启过防休眠则解除。口令只用于认证，不写进代码、skill 或日志。

阻塞处理：需要设备交付时，若设备不在线或认证缺失，明确报告“GitHub 已发布，Deck 三包交付未完成”及缺失条件， 待用户补齐后继续；不得静默跳过或把整次正式发布描述为已全部完成。

仅交付文件，不自动安装、不重启 plugin_loader，也不删除下载目录里的旧版本。 只有实际安装才能覆盖安装器下载与 sha256 校验；文件交付和侧载都不能冒充安装验收。

国内用户仍可使用稳定入口： https://dl.nvimer.org/decky_music/decky-music-cn.zip。CN 版由 release.yml 生成并上传 R2。

已踩过的坑

• pre-release 的 releases/latest/... 404 → URL 必须钉 tag
• remote_binary 下载不解包:资产必须是可直接执行的单文件(曾经的 QQ Nuitka tar.gz 靠 bridge 首用自解, beta.2 事故;统一 Rust provider 后已无归档资产)
• dist/ 可能被 sudo 跑的 decky CLI 写成 root 属主 → pnpm build EACCES,chown 回来
• CN zip 的 mv 别硬编码 Decky.Music.zip:decky CLI 产物名 = plugin.json 的 name(含空格 Decky Music.zip), GitHub 只在上传资产时才把空格转点。用 out/$(jq -r .name plugin.json).zip(beta.7 CN 步首跑事故)