feat: add sparkle updater pipeline

Author: linhay

.github/workflows/release.yml

@@ -13,6 +13,11 @@ env:
   MACOS_SIGNING_IDENTITY: ${{ secrets.MACOS_SIGNING_IDENTITY }}
   MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
   MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
+  SPARKLE_ENABLE: ${{ vars.SPARKLE_ENABLE }}
+  SPARKLE_APPCAST_BRANCH: ${{ vars.SPARKLE_APPCAST_BRANCH }}
+  SPARKLE_FEED_URL: ${{ secrets.SPARKLE_FEED_URL }}
+  SPARKLE_PRIVATE_ED_KEY: ${{ secrets.SPARKLE_PRIVATE_ED_KEY }}
+  SPARKLE_PUBLIC_ED_KEY: ${{ secrets.SPARKLE_PUBLIC_ED_KEY }}
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
@@ -53,17 +58,17 @@ jobs:
             goarch: arm64
             wails-platform: darwin/arm64
             package-ext: dmg
-            asset-name: GetTokens_darwin_arm64.dmg
-            updater-asset-name: GetTokens_darwin_arm64.tar.gz
+            asset-name: GetTokens_macOS_AppleSilicon.dmg
+            updater-asset-name: GetTokens_macOS_AppleSilicon.tar.gz
 
           - runner: macos-15-intel
             os-name: macOS amd64
             goos: darwin
             goarch: amd64
             wails-platform: darwin/amd64
             package-ext: dmg
-            asset-name: GetTokens_darwin_amd64.dmg
-            updater-asset-name: GetTokens_darwin_amd64.tar.gz
+            asset-name: GetTokens_macOS_Intel.dmg
+            updater-asset-name: GetTokens_macOS_Intel.tar.gz
 
     steps:
       - uses: actions/checkout@v5
@@ -158,6 +163,20 @@ jobs:
           chmod +x build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api
           file build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api
 
+      - name: Configure Sparkle metadata
+        if: runner.os == 'macOS' && env.SPARKLE_ENABLE == '1'
+        shell: bash
+        run: |
+          chmod +x scripts/configure-sparkle-macos.sh
+          scripts/configure-sparkle-macos.sh "build/bin/GetTokens.app"
+
+      - name: Embed Sparkle framework
+        if: runner.os == 'macOS' && env.SPARKLE_ENABLE == '1'
+        shell: bash
+        run: |
+          chmod +x scripts/prepare-sparkle-framework.sh scripts/embed-sparkle-framework.sh
+          scripts/embed-sparkle-framework.sh "build/bin/GetTokens.app"
+
       # ── Package ───────────────────────────────────────────────────────────
       - name: Sign and notarize macOS app
         if: runner.os == 'macOS'
@@ -198,10 +217,83 @@ jobs:
           fi
           rm -f "$RUNNER_TEMP/developer-id.p12" "${MACOS_NOTARY_KEY_PATH:-}"
 
+  sparkle-appcast:
+    name: Publish Sparkle appcast
+    if: vars.SPARKLE_ENABLE == '1'
+    needs: build
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@v5
+        with:
+          path: dist/release/
+          merge-multiple: true
+
+      - name: Restore previous appcast
+        shell: bash
+        run: |
+          mkdir -p dist/sparkle-feed
+          APPCAST_BRANCH="${SPARKLE_APPCAST_BRANCH:-sparkle-appcast}"
+          if git ls-remote --exit-code origin "refs/heads/${APPCAST_BRANCH}" >/dev/null 2>&1; then
+            git fetch origin "${APPCAST_BRANCH}:${APPCAST_BRANCH}"
+            if git cat-file -e "${APPCAST_BRANCH}:appcast.xml" 2>/dev/null; then
+              git show "${APPCAST_BRANCH}:appcast.xml" > dist/sparkle-feed/appcast.xml
+            fi
+          fi
+
+      - name: Generate Sparkle appcast
+        shell: bash
+        run: |
+          chmod +x scripts/prepare-sparkle-framework.sh scripts/generate-sparkle-appcast.sh
+          scripts/generate-sparkle-appcast.sh dist/release dist/sparkle-feed
+        env:
+          SPARKLE_RELEASE_BASE_URL: https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}
+          SPARKLE_FULL_RELEASE_NOTES_URL: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
+          SPARKLE_PRODUCT_URL: https://github.com/${{ github.repository }}
+
+      - name: Publish Sparkle appcast branch
+        shell: bash
+        run: |
+          APPCAST_BRANCH="${SPARKLE_APPCAST_BRANCH:-sparkle-appcast}"
+          PUBLISH_DIR="$RUNNER_TEMP/sparkle-appcast-publish"
+          REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+          rm -rf "${PUBLISH_DIR}"
+          if git ls-remote --exit-code origin "refs/heads/${APPCAST_BRANCH}" >/dev/null 2>&1; then
+            git clone --branch "${APPCAST_BRANCH}" --single-branch "${REPO_URL}" "${PUBLISH_DIR}"
+          else
+            git clone --single-branch "${REPO_URL}" "${PUBLISH_DIR}"
+            (
+              cd "${PUBLISH_DIR}"
+              git checkout --orphan "${APPCAST_BRANCH}"
+            )
+          fi
+
+          (
+            cd "${PUBLISH_DIR}"
+            find . -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+            cp "${GITHUB_WORKSPACE}/dist/sparkle-feed/appcast.xml" ./appcast.xml
+            git add appcast.xml
+            if git diff --cached --quiet; then
+              echo "Sparkle appcast unchanged; skipping commit."
+              exit 0
+            fi
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git commit -m "chore: update Sparkle appcast for ${GITHUB_REF_NAME}"
+            git push origin HEAD:"${APPCAST_BRANCH}"
+          )
+
   # ── Publish GitHub Release ────────────────────────────────────────────────
   release:
     name: Publish Release
-    needs: build
+    needs:
+      - build
+      - sparkle-appcast
+    if: ${{ always() && needs.build.result == 'success' && (needs.sparkle-appcast.result == 'success' || needs.sparkle-appcast.result == 'skipped') }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -220,9 +312,9 @@ jobs:
         uses: softprops/action-gh-release@v3
         with:
           files: |
-            dist/release/GetTokens_darwin_arm64.dmg
-            dist/release/GetTokens_darwin_arm64.tar.gz
-            dist/release/GetTokens_darwin_amd64.dmg
-            dist/release/GetTokens_darwin_amd64.tar.gz
+            dist/release/GetTokens_macOS_AppleSilicon.dmg
+            dist/release/GetTokens_macOS_AppleSilicon.tar.gz
+            dist/release/GetTokens_macOS_Intel.dmg
+            dist/release/GetTokens_macOS_Intel.tar.gz
             dist/release/checksums.txt
           generate_release_notes: true

.gitignore

@@ -9,3 +9,4 @@ dist/
 frontend/dist
 frontend/node_modules
 .playwright-cli
+.local/

README.md

@@ -82,16 +82,17 @@ Releases are published on GitHub Releases:
 
 The current release workflow produces the following asset types:
 
-- macOS Apple Silicon：`GetTokens_darwin_arm64.dmg`
-- macOS Apple Silicon updater asset：`GetTokens_darwin_arm64.tar.gz`
-- macOS Intel：`GetTokens_darwin_amd64.dmg`
-- macOS Intel updater asset：`GetTokens_darwin_amd64.tar.gz`
+- macOS Apple Silicon：`GetTokens_macOS_AppleSilicon.dmg`
+- macOS Apple Silicon updater asset：`GetTokens_macOS_AppleSilicon.tar.gz`
+- macOS Intel：`GetTokens_macOS_Intel.dmg`
+- macOS Intel updater asset：`GetTokens_macOS_Intel.tar.gz`
 - Checksums：`checksums.txt`
 
 ## 自动更新说明 | Auto Update Notes
 
 - macOS 出于已签名 `.app` bundle 完整性约束，只执行“检查更新 + 打开 release 页面下载 DMG”。
 - On macOS, due to signed `.app` bundle integrity constraints, the app uses “check update + open release page for DMG download” instead of in-place bundle replacement.
+- 实验链路：当 release workflow 启用 `SPARKLE_ENABLE=1` 且提供 Sparkle feed / public key 后，macOS 构建会预埋 Sparkle 所需 metadata 与 framework，为后续原生更新切换做准备。
 
 ## 项目结构 | Project Layout
 

app.go

@@ -188,6 +188,10 @@ func (a *App) CanApplyUpdate() bool {
 	return a.core.CanApplyUpdate()
 }
 
+func (a *App) UsesNativeUpdaterUI() bool {
+	return a.core.UsesNativeUpdaterUI()
+}
+
 func (a *App) CheckUpdate() (*updater.ReleaseInfo, error) {
 	return a.core.CheckUpdate()
 }

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

@@ -11,11 +11,11 @@
 当前阶段先只支持 macOS release，资产分成两类：
 
 1. 用户下载安装包
-   - macOS Apple Silicon: `GetTokens_darwin_arm64.dmg`
-   - macOS Intel: `GetTokens_darwin_amd64.dmg`
+   - macOS Apple Silicon: `GetTokens_macOS_AppleSilicon.dmg`
+   - macOS Intel: `GetTokens_macOS_Intel.dmg`
 2. 自动升级资产
-   - macOS Apple Silicon: `GetTokens_darwin_arm64.tar.gz`
-   - macOS Intel: `GetTokens_darwin_amd64.tar.gz`
+   - macOS Apple Silicon: `GetTokens_macOS_AppleSilicon.tar.gz`
+   - macOS Intel: `GetTokens_macOS_Intel.tar.gz`
 
 说明：
 - macOS 保留 `tar.gz` 资产用于检测最新版本和统一校验链，但签名发布包不做 bundle 内原地替换，设置页会跳转到 release 页面安装。
@@ -84,14 +84,25 @@ 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 实验链路）
+   用于 `generate_appcast` 在 CI 中对 `appcast.xml` 做 EdDSA 签名
+
+补充：
+
+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. 自动升级资产必须可直接解压出目标可执行文件，不能是安装器。
 2. 自动升级比较继续使用语义化版本 tag，例如 `v0.1.0`。
 3. UI 展示版本时间使用 `ReleaseLabel`，不和 `Version` 混用。
 4. macOS updater 资产名称必须按目标架构区分，避免 `arm64` / `amd64` 互相误命中。
 5. macOS release workflow 必须先把源码构建出来的目标架构 sidecar 回填进 `.app`，再 notarize `.app`，然后从已 stapled 的 `.app` 生成 DMG，最后再 notarize DMG。
-6. 已签名 macOS `.app` 在当前框架下只支持“检查更新 + 跳转 release 页面”，不支持 bundle 内 `ApplyUpdate`。
+6. 未启用 Sparkle 时，已签名 macOS `.app` 只支持“检查更新 + 跳转 release 页面”；启用 Sparkle 后，更新入口会切到原生更新 UI。
 
 ## 建议发布步骤
 1. 确认工作区只包含本次准备发布的变更。
@@ -103,6 +114,7 @@ CI release workflow 需要以下 secrets：
    - 安装包资产存在
    - updater 资产存在
    - `checksums.txt` 包含全部资产
+   - 若启用 Sparkle：`sparkle-appcast` 分支上的 `appcast.xml` 已更新，且 `SUFeedURL` 指向固定 raw URL
    - macOS DMG 已经 stapled，`xcrun stapler validate` 通过
 7. 使用非 dev 构建验证：
    - `CheckUpdate` 能发现新版本

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

@@ -0,0 +1,110 @@
+# macOS Sparkle Updater 接入方案
+
+## 背景
+
+GetTokens 当前在 macOS 上使用 `go-selfupdate` 做“检查更新”，但不执行 bundle 内原地替换，只打开 GitHub Release 页面让用户手动下载 DMG。
+
+原因不是更新检测能力不足，而是：
+
+1. macOS signed / notarized `.app` bundle 不适合直接用当前方式做二进制替换
+2. 现有发布产物和 updater 校验链更偏跨平台统一方案，不是 macOS 原生升级方案
+
+## 目标
+
+对 macOS 引入 Sparkle，同时保留：
+
+1. GitHub Release 作为最终公开发布源
+2. 现有 DMG / updater 资产分发链
+3. 非 macOS 平台继续沿用当前 updater 逻辑
+
+## 分层设计
+
+### 1. 前端层
+
+前端不直接理解 Sparkle framework，只消费一个更抽象的“macOS 可原生更新”能力。
+
+建议边界：
+
+1. `CanApplyUpdate()` 不再仅以 `runtime.GOOS != "darwin"` 判定
+2. macOS 在 Sparkle 可用后可返回 `true`
+3. 前端按钮语义可保持“检查更新 / 安装更新”，但实际走 Sparkle 原生流程
+
+### 2. Go / Wails 层
+
+建议新增一个 macOS 专属 updater bridge：
+
+1. 负责启动 Sparkle updater
+2. 暴露“用户触发检查更新”入口
+3. 暴露“应用启动时自动检查”策略
+
+当前阶段先不落 framework 联编，只先把发布基础设施补齐。
+
+### 3. Bundle / 发布层
+
+Sparkle 至少需要：
+
+1. `SUFeedURL`
+2. `SUPublicEDKey`
+3. 正确递增的 `CFBundleVersion`
+4. app bundle 内可加载 Sparkle framework
+
+当前阶段先完成第 1、2、3 项的预留；第 4 项放到下一阶段。
+
+## 第一阶段落地内容
+
+1. 新增脚本：`scripts/configure-sparkle-macos.sh`
+2. 新增脚本：`scripts/prepare-sparkle-framework.sh`
+3. 新增脚本：`scripts/embed-sparkle-framework.sh`
+4. `configure-sparkle-macos.sh` 负责把 Sparkle 元数据写入 `GetTokens.app/Contents/Info.plist`
+5. `embed-sparkle-framework.sh` 负责把官方 release 中的 `Sparkle.framework` 拷入 app bundle
+6. release workflow 在 secrets 就绪时可选调用 plist 注入；framework 嵌入在下一阶段切换为正式启用
+
+## 第二阶段当前进度
+
+当前已额外完成：
+
+1. 新增 `internal/sparkle/` darwin bridge skeleton
+2. bridge 现已改为动态加载 `Sparkle.framework`，不依赖编译期静态链接
+3. `wailsapp` 在检测到 Sparkle 可用时，会把 macOS 更新入口切到原生更新 UI 模式
+4. 前端设置页已能识别“原生更新 UI”模式，并在该模式下只保留单次“检查更新”入口
+5. release workflow 现已支持生成签名后的 `appcast.xml`，并推送到固定分支供 `raw.githubusercontent.com` 托管
+
+当前仍未完成：
+
+1. Sparkle API 的回调事件还没有回流到前端状态栏
+2. 还没有用真实 feed 完成端到端升级回归
+
+## Secrets / 环境变量建议
+
+1. `SPARKLE_FEED_URL`
+2. `SPARKLE_PUBLIC_ED_KEY`
+3. `SPARKLE_PRIVATE_ED_KEY`
+4. `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`
+
+## 官方要求摘要
+
+根据 Sparkle 官方文档：
+
+1. 外部构建系统需要自己负责 link framework、拷贝到 `Contents/Frameworks/`、设置 rpath
+2. `Info.plist` 需要包含 `SUFeedURL` 与 `SUPublicEDKey`
+3. `CFBundleVersion` 必须可递增
+4. appcast 推荐使用 `generate_appcast` 生成并签名
+
+参考：
+
+1. https://sparkle-project.org/documentation/programmatic-setup/
+2. https://sparkle-project.org/documentation/publishing/
+
+## 当前未完成项
+
+1. Sparkle framework 已支持通过脚本下载并嵌入 app bundle，运行时也已通过动态 bridge 接入，但缺少升级事件回流
+2. `appcast.xml` 生成与分支发布链路已接入 workflow，但还没有在真实 release 上启用验证
+3. 前端设置页已切到“原生更新 UI”识别模式，但仍缺少 Sparkle 状态反馈
+4. 还没有真实的 Sparkle 升级回归

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

@@ -164,7 +164,7 @@
 - 发布版本继续上调到 `v0.1.3`，避免复用已失败的 `v0.1.1` / `v0.1.2` tag。
 - 产品发布范围调整：当前阶段先只支持 macOS，release workflow 暂时移除 Windows / Linux 构建与资产发布，只保留 `GetTokens_darwin_universal.dmg`、`GetTokens_darwin_universal.tar.gz` 与 `checksums.txt`。
 - 发布治理：为消除 GitHub Actions 的 Node 20 deprecation 警告，release workflow 已升级到 Node 24 运行时对应的大版本：`actions/checkout@v5`、`actions/setup-node@v6`、`actions/setup-go@v6`、`actions/download-artifact@v5`、`actions/upload-artifact@v6`、`softprops/action-gh-release@v3`。
-- 发布策略调整：macOS 不再使用单一 `universal` DMG / updater 资产，改为按架构拆分为 `GetTokens_darwin_arm64.*` 与 `GetTokens_darwin_amd64.*` 两套产物。
+- 发布策略调整：macOS 不再使用单一 `universal` DMG / updater 资产，改为按架构拆分为 `GetTokens_macOS_AppleSilicon.*` 与 `GetTokens_macOS_Intel.*` 两套对外产物；内部构建与平台判断仍沿用 `arm64/amd64`。
 - 实现同步：release workflow 已切为两个 macOS job，分别在 `macos-latest`（arm64）和 `macos-15-intel`（amd64）上构建、签名、公证并发布；`internal/updater` 也移除了 `UniversalArch=universal` 绑定，改为让 `go-selfupdate` 按实际架构匹配资产。
 
 ## Account Rotation Controls