docs: distill sparkle release rollout

Author: linhay

.agents/skills/gettokens-ops-governance/SKILL.md

@@ -34,10 +34,10 @@ This skill unifies the procedural rules for working on GetTokens, ensuring consi
 ## 5. Release Governance
 - **Scope**: Current release scope is macOS only.
 - **Assets**:
-  - `GetTokens_darwin_arm64.dmg`
-  - `GetTokens_darwin_arm64.tar.gz`
-  - `GetTokens_darwin_amd64.dmg`
-  - `GetTokens_darwin_amd64.tar.gz`
+  - `GetTokens_macOS_AppleSilicon.dmg`
+  - `GetTokens_macOS_AppleSilicon.tar.gz`
+  - `GetTokens_macOS_Intel.dmg`
+  - `GetTokens_macOS_Intel.tar.gz`
   - `checksums.txt`
 - **Versioning**:
   - If a release tag has already failed or been consumed, bump to the next patch tag instead of reusing it.
@@ -50,6 +50,10 @@ This skill unifies the procedural rules for working on GetTokens, ensuring consi
   - Build `arm64` and `amd64` as separate release jobs; do not collapse them back into a universal DMG workflow.
   - After `wails build`, explicitly copy the freshly built sidecar back into `GetTokens.app/Contents/MacOS/cli-proxy-api` before notarization.
   - Sign and notarize the `.app` first, then build/sign/notarize the `.dmg`.
+- **Sparkle Rule**:
+  - Sparkle feed must stay split by architecture; do not merge `arm64` and `amd64` DMGs into one appcast when bundle versions are equal.
+  - `SUFeedURL` must point to the matching per-arch feed: `appcast-arm64.xml` or `appcast-amd64.xml`.
+  - When `generate_appcast` is used in CI, write appcast output to an explicit staged file path instead of assuming it rewrites the staged seed file in place.
 - **CI Hygiene**:
   - Keep GitHub Actions dependencies on Node 24 compatible major versions to avoid Node 20 deprecation warnings.
   - When a release run fails, inspect the exact failed job logs before changing tag strategy or packaging assumptions.

docs-linhay/dev/20260426-release-prep-guide.md

@@ -84,17 +84,19 @@ CI release workflow 需要以下 secrets：
    App Store Connect API Key 的 issuer id
 6. `MACOS_NOTARY_API_KEY_BASE64`
    `AuthKey_<KEY_ID>.p8` 文件内容做 base64 后存入
-7. `SPARKLE_FEED_URL`（可选，Sparkle 实验链路）
-   推荐固定为 `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast.xml`
-8. `SPARKLE_PUBLIC_ED_KEY`（可选，Sparkle 实验链路）
-9. `SPARKLE_PRIVATE_ED_KEY`（可选，Sparkle 实验链路）
+7. `SPARKLE_PUBLIC_ED_KEY`（可选，Sparkle 实验链路）
+8. `SPARKLE_PRIVATE_ED_KEY`（可选，Sparkle 实验链路）
    用于 `generate_appcast` 在 CI 中对 `appcast.xml` 做 EdDSA 签名
+9. `SPARKLE_APPCAST_BRANCH`（GitHub Actions variable，推荐固定为 `sparkle-appcast`）
 
 补充：
 
-1. 只有在 GitHub Actions variable `SPARKLE_ENABLE=1` 时，release workflow 才会尝试写入 Sparkle metadata、嵌入 `Sparkle.framework`、生成并发布 `appcast.xml`
-2. `SPARKLE_APPCAST_BRANCH` 默认为 `sparkle-appcast`，workflow 会把最新 `appcast.xml` 推到该分支，再由 `raw.githubusercontent.com` 提供稳定 feed URL
-3. 未启用时，现有 GitHub Release + DMG 发布链路保持不变
+1. 只有在 GitHub Actions variable `SPARKLE_ENABLE=1` 时，release workflow 才会尝试写入 Sparkle metadata、嵌入 `Sparkle.framework`、生成并发布 Sparkle feed
+2. `SPARKLE_APPCAST_BRANCH` 默认为 `sparkle-appcast`，workflow 会把最新 feed 推到该分支，再由 `raw.githubusercontent.com` 提供稳定 feed URL
+3. Sparkle feed 当前按架构拆分：
+   - arm64: `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast-arm64.xml`
+   - amd64: `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast-amd64.xml`
+4. 未启用时，现有 GitHub Release + DMG 发布链路保持不变
 
 ## 原则
 1. 自动升级资产必须可直接解压出目标可执行文件，不能是安装器。
@@ -114,7 +116,7 @@ CI release workflow 需要以下 secrets：
    - 安装包资产存在
    - updater 资产存在
    - `checksums.txt` 包含全部资产
-   - 若启用 Sparkle：`sparkle-appcast` 分支上的 `appcast.xml` 已更新，且 `SUFeedURL` 指向固定 raw URL
+   - 若启用 Sparkle：`sparkle-appcast` 分支上的 `appcast-arm64.xml` / `appcast-amd64.xml` 已更新，且 `SUFeedURL` 指向对应架构的 raw URL
    - macOS DMG 已经 stapled，`xcrun stapler validate` 通过
 7. 使用非 dev 构建验证：
    - `CheckUpdate` 能发现新版本

docs-linhay/dev/20260427-macos-sparkle-updater-architecture.md

@@ -67,7 +67,7 @@ Sparkle 至少需要：
 2. bridge 现已改为动态加载 `Sparkle.framework`，不依赖编译期静态链接
 3. `wailsapp` 在检测到 Sparkle 可用时，会把 macOS 更新入口切到原生更新 UI 模式
 4. 前端设置页已能识别“原生更新 UI”模式，并在该模式下只保留单次“检查更新”入口
-5. release workflow 现已支持生成签名后的 `appcast.xml`，并推送到固定分支供 `raw.githubusercontent.com` 托管
+5. release workflow 现已支持生成签名后的 Sparkle appcast，并推送到固定分支供 `raw.githubusercontent.com` 托管
 
 当前仍未完成：
 
@@ -76,17 +76,21 @@ Sparkle 至少需要：
 
 ## Secrets / 环境变量建议
 
-1. `SPARKLE_FEED_URL`
-2. `SPARKLE_PUBLIC_ED_KEY`
-3. `SPARKLE_PRIVATE_ED_KEY`
-4. `SPARKLE_APPCAST_BRANCH`（推荐固定为 `sparkle-appcast`）
+1. `SPARKLE_PUBLIC_ED_KEY`
+2. `SPARKLE_PRIVATE_ED_KEY`
+3. `SPARKLE_APPCAST_BRANCH`（推荐固定为 `sparkle-appcast`）
 
 当前 appcast 发布策略：
 
 1. release 产物继续上传到 GitHub Release
 2. `generate_appcast` 只消费 notarized `.dmg`，不消费纯二进制 `.tar.gz`
-3. workflow 从既有 `appcast.xml` 增量生成新 feed，并把结果推送到 `sparkle-appcast` 分支
-4. `SUFeedURL` 固定指向 `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast.xml`
+3. workflow 从既有 feed 增量生成新内容，并把结果推送到 `sparkle-appcast` 分支
+4. Sparkle feed 按架构拆分：
+   - `appcast-arm64.xml`
+   - `appcast-amd64.xml`
+5. 构建时按目标架构写入对应 `SUFeedURL`：
+   - `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast-arm64.xml`
+   - `https://raw.githubusercontent.com/AxApp/GetTokens/sparkle-appcast/appcast-amd64.xml`
 
 ## 官方要求摘要
 
@@ -105,6 +109,6 @@ Sparkle 至少需要：
 ## 当前未完成项
 
 1. Sparkle framework 已支持通过脚本下载并嵌入 app bundle，运行时也已通过动态 bridge 接入，但缺少升级事件回流
-2. `appcast.xml` 生成与分支发布链路已接入 workflow，但还没有在真实 release 上启用验证
+2. 分架构 appcast 生成与 `sparkle-appcast` 分支发布链路已在真实 release `v0.1.10` 上验证通过
 3. 前端设置页已切到“原生更新 UI”识别模式，但仍缺少 Sparkle 状态反馈
-4. 还没有真实的 Sparkle 升级回归
+4. 真实的 Sparkle 自动升级安装回归还没有做，只验证到了 release / appcast 发布闭环

docs-linhay/memory/2026-04-27.md

@@ -97,6 +97,8 @@
 - Sparkle 接入推进（三）：新增 `scripts/generate-sparkle-appcast.sh` 与对应测试，release workflow 现在可在 `SPARKLE_ENABLE=1` 时用 Sparkle 官方 `generate_appcast` 基于 notarized `.dmg` 生成签名后的 `appcast.xml`，并推送到 `sparkle-appcast` 分支供 `raw.githubusercontent.com` 托管稳定 feed。
 - Sparkle 正式 release 首次回归（`v0.1.7`）失败点已定位：仅 `macOS amd64` 在 `Embed Sparkle framework` 阶段拿到损坏的 Sparkle zip（约 55 KB HTML/错误页），不是 framework 集成本身失败；已把 `scripts/prepare-sparkle-framework.sh` 改成 `curl --fail --retry --retry-all-errors` 并在下载后执行 `unzip -tq` 校验，不合法则重试。
 - Sparkle 正式 release 第二次回归（`v0.1.8`）失败点已定位：`Publish Sparkle appcast` 不能把 `arm64` 与 `amd64` 两个同版本 DMG 放进同一个 appcast，Sparkle 会判定为 duplicate updates；发布链已改成分架构 feed，分别生成 `appcast-arm64.xml` 与 `appcast-amd64.xml`，构建时按目标架构写入对应 `SUFeedURL`。
+- Sparkle 正式 release 第三次回归（`v0.1.9`）失败点已定位：`generate_appcast` 实际把输出写到了 `-o` 指定路径，但脚本仍按旧假设去临时目录里 `cp` staged appcast，导致 `Publish Sparkle appcast` 因 `No such file or directory` 失败；已在 `scripts/generate-sparkle-appcast.sh` 中把输出改成显式写入 staged 绝对路径，并补了测试。
+- Sparkle 正式 release 第四次回归（`v0.1.10`，run `24979794016`）已全绿完成：两条 macOS 构建、分架构 appcast 发布和 GitHub Release 均成功，正式资产为 `GetTokens_macOS_AppleSilicon.*`、`GetTokens_macOS_Intel.*` 与 `checksums.txt`，`sparkle-appcast` 分支已落地 `appcast-arm64.xml` / `appcast-amd64.xml`。
 
 ## Wails Window Drag Region
 - 当前窗口拖不动的根因已确认：`main.go` 启用了 `mac.TitleBarHiddenInset()`，但前端此前没有任何 `--wails-draggable` 区域，导致 macOS 将整个壳层视为普通 Web 内容。

docs-linhay/spaces/20260427-macos-sparkle-updater/README.md

@@ -81,4 +81,4 @@ Sparkle 是 macOS 上成熟的原生更新框架，更适合 GetTokens 当前的
 ## 当前状态
 - 状态：in-progress
 - 最近更新：2026-04-27
-- 最近变更：已完成 Sparkle space / 架构文档 / plist 注入脚本 / framework 下载与嵌入脚本 / darwin bridge / 设置页原生更新入口适配；release workflow 现已支持通过 `SPARKLE_ENABLE=1` 生成并发布签名后的 `appcast.xml` 到 `sparkle-appcast` 分支，但还没有做真实 release 回归。
+- 最近变更：已完成 Sparkle space / 架构文档 / plist 注入脚本 / framework 下载与嵌入脚本 / darwin bridge / 设置页原生更新入口适配；`v0.1.10` 已完成首轮真实 Sparkle release 回归，release workflow 可在 `SPARKLE_ENABLE=1` 时生成并发布分架构 feed `appcast-arm64.xml` / `appcast-amd64.xml` 到 `sparkle-appcast` 分支。