fix: build release sidecar from fork source

Author: linhay

.github/workflows/release.yml

@@ -97,23 +97,12 @@ jobs:
       - name: Install Wails
         run: go install github.com/wailsapp/wails/v2/cmd/wails@latest
 
-      # ── Fetch sidecar binary ──────────────────────────────────────────────
-      - name: Fetch CLIProxyAPI sidecar (macOS/Linux)
-        if: runner.os != 'Windows'
-        run: |
-          chmod +x scripts/fetch-sidecar.sh
-          ./scripts/fetch-sidecar.sh ${{ matrix.goos }} ${{ matrix.goarch == 'universal' && 'arm64' || matrix.goarch }} latest build/bin
-          # For darwin/universal also fetch amd64
-          if [ "${{ matrix.goos }}" = "darwin" ]; then
-            ./scripts/fetch-sidecar.sh darwin amd64 latest build/bin/amd64
-          fi
-
-      - name: Fetch CLIProxyAPI sidecar (Windows)
-        if: runner.os == 'Windows'
+      # ── Build sidecar from fork source ───────────────────────────────────
+      - name: Build CLIProxyAPI sidecar from source
         shell: bash
         run: |
-          chmod +x scripts/fetch-sidecar.sh
-          ./scripts/fetch-sidecar.sh windows amd64 latest build/bin
+          chmod +x scripts/build-sidecar.sh
+          ./scripts/build-sidecar.sh ${{ matrix.goos }} ${{ matrix.goarch }} build/bin
 
       # ── Platform-specific dependencies ───────────────────────────────────
       - name: Install macOS packaging tools
@@ -201,6 +190,14 @@ jobs:
             ${{ matrix.wails-extra || '' }} \
             -ldflags "-X main.Version=${{ github.ref_name }} -X main.ReleaseLabel=${RELEASE_LABEL}"
 
+      - name: Reinstall universal sidecar into macOS app bundle
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          cp build/bin/cli-proxy-api build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api
+          chmod +x build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api
+          lipo -info build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api
+
       - name: Package updater asset
         if: runner.os != 'macOS'
         shell: bash

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

@@ -24,18 +24,42 @@
 - macOS 保留 `tar.gz` 资产用于检测最新版本和统一校验链，但签名发布包不做 bundle 内原地替换，设置页会跳转到 release 页面安装。
 - 原因是 Apple 对签名 bundle 的 seal 有要求；修改 `.app` 主可执行文件会破坏签名边界。参见 Apple Technical Note TN2206。
 
+## sidecar 构建边界
+发布前必须先从仓库内维护的 `docs-linhay/references/CLIProxyAPI` 源码构建 sidecar，不能直接下载上游 release 二进制。
+
+原因：
+
+1. `CLIProxyAPI` 已经进入 fork 维护态，行为修复首先落在 fork 源码，而不是等 fork release。
+2. fork release 可能滞后，直接下载 release 无法保证包含本轮补丁。
+3. 对 `darwin/universal`，最终写入 `GetTokens.app` 的 `Contents/MacOS/cli-proxy-api` 必须是 universal binary；不能只塞一份 `arm64`。
+
+对应脚本：
+- `scripts/build-sidecar.sh <goos> <goarch> <output-dir>`
+
+示例：
+
+```bash
+./scripts/build-sidecar.sh darwin universal build/bin
+./scripts/build-sidecar.sh windows amd64 build/bin
+./scripts/build-sidecar.sh linux amd64 build/bin
+```
+
 ## macOS 签名与公证
 macOS release 现在按以下顺序处理：
 
-1. 使用 `Developer ID Application` 证书对 `GetTokens.app` 做 hardened runtime 签名
-2. 使用 `notarytool` 提交 `.app` 的 zip 包并等待公证完成
-3. 对 `.app` 执行 `stapler staple`
-4. 基于已 stapled 的 `.app` 生成 DMG
-5. 对 DMG 重新签名后再次提交 notarization
-6. 对 DMG 执行 `stapler staple`
-7. 最后再从签名后的 `.app` 中提取 updater 原始可执行文件，打成 `tar.gz`
+0. 从 `docs-linhay/references/CLIProxyAPI` 源码构建 universal sidecar，写入 `build/bin/cli-proxy-api`
+1. 执行 `wails build`
+2. 用 `build/bin/cli-proxy-api` 显式覆盖 `build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api`，确保 app bundle 内 sidecar 仍是 universal binary
+3. 使用 `Developer ID Application` 证书对 `GetTokens.app` 做 hardened runtime 签名
+4. 使用 `notarytool` 提交 `.app` 的 zip 包并等待公证完成
+5. 对 `.app` 执行 `stapler staple`
+6. 基于已 stapled 的 `.app` 生成 DMG
+7. 对 DMG 重新签名后再次提交 notarization
+8. 对 DMG 执行 `stapler staple`
+9. 最后再从签名后的 `.app` 中提取 updater 原始可执行文件，打成 `tar.gz`
 
 对应脚本：
+- [scripts/build-sidecar.sh](/Users/linhey/Desktop/linhay-open-sources/GetTokens/scripts/build-sidecar.sh)
 - [scripts/sign-notarize-macos-release.sh](/Users/linhey/Desktop/linhay-open-sources/GetTokens/scripts/sign-notarize-macos-release.sh)
 - [scripts/package-updater-asset.sh](/Users/linhey/Desktop/linhay-open-sources/GetTokens/scripts/package-updater-asset.sh)
 
@@ -65,20 +89,21 @@ CI release workflow 需要以下 secrets：
 3. UI 展示版本时间使用 `ReleaseLabel`，不和 `Version` 混用。
 4. Windows 安装包必须避开 `go-selfupdate` 的默认匹配规则，因此使用 `_installer.exe` 后缀。
 5. macOS universal updater 资产需要和 `UniversalArch=universal` 对齐。
-6. macOS release workflow 必须先 notarize `.app`，再从已 stapled 的 `.app` 生成 DMG，最后再 notarize DMG；不能先打 DMG 再签 app。
+6. macOS release workflow 必须先把源码构建出来的 universal sidecar 回填进 `.app`，再 notarize `.app`，然后从已 stapled 的 `.app` 生成 DMG，最后再 notarize DMG。
 7. 已签名 macOS `.app` 在当前框架下只支持“检查更新 + 跳转 release 页面”，不支持 bundle 内 `ApplyUpdate`。
 
 ## 建议发布步骤
 1. 确认工作区只包含本次准备发布的变更。
 2. 运行前端类型检查、Go 测试、文档校验。
-3. 合并到干净提交后创建 tag：`v0.1.0`。
-4. 推送 tag 触发 GitHub Actions release workflow。
-5. 在生成的 release 页面检查：
+3. 从 fork 源码构建 sidecar，并确认 macOS 场景下 `build/bin/cli-proxy-api` 为 universal binary。
+4. 合并到干净提交后创建 tag：`v0.1.0`。
+5. 推送 tag 触发 GitHub Actions release workflow。
+6. 在生成的 release 页面检查：
    - 安装包资产存在
    - updater 资产存在
    - `checksums.txt` 包含全部资产
    - macOS DMG 已经 stapled，`xcrun stapler validate` 通过
-6. 使用非 dev 构建验证：
+7. 使用非 dev 构建验证：
    - `CheckUpdate` 能发现新版本
    - Windows / Linux: `ApplyUpdate` 能下载并替换二进制，应用退出后重启进入新版本
    - macOS: 设置页能打开对应 release 页面，下载安装后进入新版本

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

@@ -146,3 +146,7 @@
   - 新增 `Feature / Page Boundary`
   - 新增 `Go Large-File Split Heuristics`
 - 本轮判断这些规则已稳定到项目级 skill / dev 文档，但还不需要上升为 `AGENTS.md` 的 repo-wide 硬约束。
+- 发布流程纠偏：GetTokens 打包前的 sidecar 不能再通过 `scripts/fetch-sidecar.sh` 拉上游 release 二进制；必须先从 `docs-linhay/references/CLIProxyAPI` 的 fork 源码构建。
+- 发布修复：新增 `scripts/build-sidecar.sh`，统一从本地 fork 源码构建 sidecar；`darwin/universal` 场景会先分别构建 `arm64/x86_64`，再用 `lipo` 合成为单一 universal `build/bin/cli-proxy-api`。
+- 发布治理：`.github/workflows/release.yml` 已切换为源码构建 sidecar，不再依赖上游 `router-for-me/CLIProxyAPI` release 资产。
+- 额外发现：Wails `darwin/universal` 打包后，`GetTokens.app/Contents/MacOS/cli-proxy-api` 会退回单架构副本；因此 workflow 需要在 `wails build` 之后显式把 `build/bin/cli-proxy-api` 覆盖回 app bundle，再进入签名与 DMG。

scripts/build-sidecar.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -ne 3 ]]; then
+  echo "Usage: $0 <goos> <goarch> <output-dir>" >&2
+  exit 1
+fi
+
+GOOS="$1"
+GOARCH="$2"
+OUTPUT_DIR="$3"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+SOURCE_DIR="${CLI_PROXY_SOURCE_DIR:-${ROOT_DIR}/docs-linhay/references/CLIProxyAPI}"
+BINARY_NAME="cli-proxy-api"
+
+if [[ "$GOOS" == "windows" ]]; then
+  BINARY_NAME="${BINARY_NAME}.exe"
+fi
+
+if [[ ! -d "${SOURCE_DIR}" ]]; then
+  echo "CLIProxyAPI source dir not found: ${SOURCE_DIR}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${SOURCE_DIR}/go.mod" ]]; then
+  echo "CLIProxyAPI source dir is missing go.mod: ${SOURCE_DIR}" >&2
+  exit 1
+fi
+
+resolve_git_value() {
+  local cmd="$1"
+  if git -C "${SOURCE_DIR}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git -C "${SOURCE_DIR}" ${cmd} 2>/dev/null || true
+  fi
+}
+
+VERSION="${CLI_PROXY_VERSION:-$(resolve_git_value "describe --tags --always --dirty")}"
+COMMIT="${CLI_PROXY_COMMIT:-$(resolve_git_value "rev-parse --short HEAD")}"
+BUILD_DATE="${CLI_PROXY_BUILD_DATE:-$(date -u +'%Y-%m-%dT%H:%M:%SZ')}"
+
+VERSION="${VERSION:-fork-source}"
+COMMIT="${COMMIT:-unknown}"
+
+LDFLAGS="-s -w -X main.Version=${VERSION} -X main.Commit=${COMMIT} -X main.BuildDate=${BUILD_DATE}"
+
+mkdir -p "${OUTPUT_DIR}"
+
+build_single() {
+  local target_goarch="$1"
+  local output_path="$2"
+
+  (
+    cd "${SOURCE_DIR}"
+    CGO_ENABLED=0 GOOS="${GOOS}" GOARCH="${target_goarch}" \
+      go build -trimpath -ldflags "${LDFLAGS}" -o "${output_path}" ./cmd/server
+  )
+}
+
+case "${GOOS}:${GOARCH}" in
+  darwin:universal)
+    if ! command -v lipo >/dev/null 2>&1; then
+      echo "lipo is required for darwin/universal sidecar builds" >&2
+      exit 1
+    fi
+
+    STAGE_DIR="$(mktemp -d)"
+    trap 'rm -rf "${STAGE_DIR}"' EXIT
+
+    ARM64_PATH="${STAGE_DIR}/cli-proxy-api-arm64"
+    AMD64_PATH="${STAGE_DIR}/cli-proxy-api-amd64"
+    UNIVERSAL_PATH="${OUTPUT_DIR}/cli-proxy-api"
+
+    build_single arm64 "${ARM64_PATH}"
+    build_single amd64 "${AMD64_PATH}"
+    lipo -create -output "${UNIVERSAL_PATH}" "${ARM64_PATH}" "${AMD64_PATH}"
+    chmod +x "${UNIVERSAL_PATH}"
+    ;;
+  darwin:arm64 | darwin:amd64 | linux:amd64 | linux:arm64 | windows:amd64 | windows:arm64)
+    build_single "${GOARCH}" "${OUTPUT_DIR}/${BINARY_NAME}"
+    chmod +x "${OUTPUT_DIR}/${BINARY_NAME}"
+    ;;
+  *)
+    echo "Unsupported sidecar target: ${GOOS}:${GOARCH}" >&2
+    exit 1
+    ;;
+esac
+
+echo "✓ Built CLIProxyAPI from source: ${OUTPUT_DIR}/${BINARY_NAME}"