feat: 基础更新实现

.github/scripts/prepare-release-assets.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * 整理 GitHub Release 待发布资源（CommonJS，便于用 NODE_PATH 引入隔离安装的 js-yaml）
+ *
+ * 背景：各平台/架构在独立 job 构建并各自上传 artifact。electron-builder 会为
+ * Windows / macOS 生成同名的 `latest.yml` / `latest-mac.yml`（分别只含本架构条目），
+ * 直接上传会互相覆盖，导致另一架构无法自动更新。Linux 则使用按架构区分的
+ * `latest-linux.yml` / `latest-linux-arm64.yml`，天然不冲突。
+ *
+ * 本脚本将所有 artifact 扁平化到输出目录：
+ *  - 合并 Windows / macOS 的 latest*.yml（合并 files 列表，path/sha512 优先指向 x64）
+ *  - 保留各架构 Linux 清单原样
+ *  - 剔除调试文件 builder-debug.yml
+ *  - 同名二进制去重（保留首个），避免 release 资源重名冲突
+ *
+ * 用法: node prepare-release-assets.cjs <artifactsDir> <outDir>
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const srcDir = process.argv[2];
+const outDir = process.argv[3];
+
+if (!srcDir || !outDir) {
+  console.error("用法: node prepare-release-assets.cjs <artifactsDir> <outDir>");
+  process.exit(1);
+}
+
+/** 需要跨架构合并的更新清单文件名 */
+const MERGE_MANIFESTS = new Set(["latest.yml", "latest-mac.yml"]);
+
+/** 不需要上传的文件 */
+const SKIP_FILES = new Set(["builder-debug.yml"]);
+
+/**
+ * 递归收集目录下的所有文件（跳过 *-unpacked 目录）
+ * @param {string} dir 起始目录
+ * @param {string[]} [out] 结果累加数组（递归内部使用）
+ * @returns {string[]} 收集到的文件路径列表
+ */
+const walk = (dir, out = []) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name.endsWith("-unpacked")) continue;
+      walk(full, out);
+    } else {
+      out.push(full);
+    }
+  }
+  return out;
+};
+
+/**
+ * 合并多份同名更新清单：合并各架构的 files 列表（按 url 去重）
+ * 基准 path/sha512 优先指向 x64
+ * @param {Array<Record<string, any>>} docs 同名清单的解析结果数组
+ * @returns {Record<string, any>} 合并后的清单对象
+ */
+const mergeManifests = (docs) => {
+  if (docs.length === 1) return docs[0];
+  const merged = { ...docs[0] };
+  const byUrl = new Map();
+  for (const doc of docs) {
+    for (const file of doc.files || []) {
+      if (!byUrl.has(file.url)) byUrl.set(file.url, file);
+    }
+  }
+  merged.files = [...byUrl.values()];
+  const x64 = merged.files.find((file) => /x64|x86_64/i.test(file.url));
+  if (x64) {
+    merged.path = x64.url;
+    merged.sha512 = x64.sha512;
+  }
+  return merged;
+};
+
+fs.mkdirSync(outDir, { recursive: true });
+
+/** @type {Map<string, Array<Record<string, any>>>} 清单名 -> 解析文档数组 */
+const manifestDocs = new Map();
+
+/** @type {Set<string>} 已写入输出目录的文件名 */
+const seen = new Set();
+
+for (const file of walk(srcDir)) {
+  const base = path.basename(file);
+  if (SKIP_FILES.has(base)) continue;
+
+  if (MERGE_MANIFESTS.has(base)) {
+    const doc = yaml.load(fs.readFileSync(file, "utf8"));
+    if (!manifestDocs.has(base)) manifestDocs.set(base, []);
+    manifestDocs.get(base).push(doc);
+    continue;
+  }
+
+  if (seen.has(base)) {
+    console.warn(`⚠️  跳过重复同名文件: ${base}`);
+    continue;
+  }
+  seen.add(base);
+  fs.copyFileSync(file, path.join(outDir, base));
+}
+
+for (const [name, docs] of manifestDocs) {
+  const merged = mergeManifests(docs);
+  fs.writeFileSync(path.join(outDir, name), yaml.dump(merged, { lineWidth: -1 }));
+  console.log(`✅ 合并清单 ${name}（files: ${(merged.files || []).length}）`);
+}
+
+console.log(`release-assets 准备完成，共 ${fs.readdirSync(outDir).length} 个文件`);

.github/workflows/release.yml

@@ -0,0 +1,209 @@
+# tag（v*）触发
+# 各架构原生 runner 构建 → 合并清单 → 创建 GitHub 草稿 Release
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+env:
+  NODE_VERSION: 22.x
+
+# 同一个 tag 的发布串行执行，避免并发上传资源产生竞态
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # 各平台/架构在对应的原生 runner 上独立构建
+  build:
+    name: Build on ${{ matrix.name }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Windows x64
+            runner: windows-latest
+            target: windows-x64
+          - name: Windows arm64
+            runner: windows-11-arm
+            target: windows-arm64
+          - name: macOS x64
+            runner: macos-15-intel
+            target: macos-x64
+          - name: macOS arm64
+            runner: macos-latest
+            target: macos-arm64
+          - name: Linux x64
+            runner: ubuntu-latest
+            target: linux-x64
+          - name: Linux arm64
+            runner: ubuntu-24.04-arm
+            target: linux-arm64
+    steps:
+      - name: Check out git repository
+        uses: actions/checkout@v5
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "native/audio-engine -> target\nnative/media-ctrl -> target"
+
+      # 校验 tag 与 package.json 版本一致
+      - name: Verify tag matches version
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          PKG_VERSION="v$(node -p "require('./package.json').version")"
+          if [ "$PKG_VERSION" != "$GITHUB_REF_NAME" ]; then
+            echo "标签 $GITHUB_REF_NAME 与 package.json 版本 $PKG_VERSION 不一致"
+            exit 1
+          fi
+
+      # Linux: 安装系统构建/打包依赖
+      - name: 安装系统依赖 (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y \
+            libasound2-dev libdbus-1-dev pkg-config clang \
+            rpm libarchive-tools
+
+      # 清理旧构建产物
+      - name: Clean workspace on Windows
+        if: runner.os == 'Windows'
+        run: |
+          if (Test-Path dist) { Remove-Item -Recurse -Force dist }
+          if (Test-Path out) { Remove-Item -Recurse -Force out }
+
+      - name: Clean workspace on macOS & Linux
+        if: runner.os != 'Windows'
+        run: rm -rf dist out
+
+      # CI 不需要国内镜像
+      - name: 移除 .npmrc
+        shell: bash
+        run: rm -f .npmrc
+
+      # 安装项目依赖
+      - name: Install dependencies
+        run: pnpm install
+
+      # 仅构建本机架构
+      - name: Build ${{ matrix.name }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_IDENTITY_AUTO_DISCOVERY: false
+        run: |
+          case "${{ matrix.target }}" in
+            windows-x64)
+              pnpm build:win -- --x64 --publish never
+              ;;
+            windows-arm64)
+              pnpm build:win -- --arm64 --publish never
+              ;;
+            macos-x64)
+              pnpm build:mac -- --x64 --publish never
+              ;;
+            macos-arm64)
+              pnpm build:mac -- --arm64 --publish never
+              ;;
+            linux-x64)
+              pnpm build:linux -- --x64 --publish never
+              ;;
+            linux-arm64)
+              pnpm build:linux -- --arm64 --publish never
+              ;;
+            *)
+              echo "Unsupported target: ${{ matrix.target }}"
+              exit 1
+              ;;
+          esac
+
+      # 修复 Linux arm64 自动更新清单命名
+      # electron-builder 单独构建 arm64 时仍命名为 latest-linux.yml，会与 x64 撞名，
+      # 显式重命名为 latest-linux-arm64.yml（electron-updater 在 arm64 上据此查找）
+      - name: Rename Linux arm64 update manifest
+        if: matrix.target == 'linux-arm64'
+        shell: bash
+        run: |
+          if [ -f dist/latest-linux.yml ]; then
+            mv dist/latest-linux.yml dist/latest-linux-arm64.yml
+            echo "Renamed latest-linux.yml -> latest-linux-arm64.yml"
+          else
+            echo "dist/latest-linux.yml not found, skipping"
+          fi
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: SPlayer-Next-${{ matrix.name }}
+          path: dist/*.*
+
+  # 合并多架构更新清单并创建 GitHub 草稿 Release
+  release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+
+      # 整理待发布资源
+      - name: Prepare release assets
+        shell: bash
+        run: |
+          npm install --no-save --prefix "$RUNNER_TEMP/jsyaml" js-yaml@4.1.0
+          NODE_PATH="$RUNNER_TEMP/jsyaml/node_modules" \
+            node .github/scripts/prepare-release-assets.cjs artifacts release-assets
+          echo "待发布资源："
+          ls -1 release-assets
+
+      # 用官方 gh CLI 确定性创建草稿 Release
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          # 重跑场景：若同名 release 已存在则先删除，避免脏状态（保留 tag）
+          if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release delete "$TAG" --repo "$GITHUB_REPOSITORY" --yes
+          fi
+          gh release create "$TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$TAG" \
+            --generate-notes \
+            --verify-tag \
+            --draft \
+            release-assets/*

CLAUDE.md

@@ -65,7 +65,7 @@ Server protocol clients live in renderer (`src/services/streaming/`): subsonic /
 - `services/streaming/transform.ts` — Server response → unified `Track / Album / Artist / Playlist`. Trusts server's artist field; no client-side splitting.
 - `services/streaming/session.ts` — Jellyfin/Emby `/Sessions/Playing` heartbeat + PlaySessionId state machine; called from `core/player.ts`.
 - `stores/streaming.ts` — Server list, active state, connection, browse cache (IndexedDB via localforage `streaming-cache`). `fetchSongs` returns first batch then keeps fetching in background.
-- Credentials — main process `electron/main/ipc/streaming.ts` encrypts via Electron `safeStorage` to `{userData}/streaming.json`. `accessToken / userId` not persisted; re-acquired on connect.
+- Credentials — main process `electron/main/ipc/streaming.ts` encrypts via Electron `safeStorage` to `{userData}/app-data/config/streaming.json`. `accessToken / userId` not persisted; re-acquired on connect.
 
 ### Lyric Windows
 
@@ -93,23 +93,28 @@ Declarative — defined in `src/settings/schema.ts`, types in `src/types/setting
 ### Data Storage
 
 ```
-{userData}/
-├── settings.json          # Main config (electron/main/store/)
-├── streaming.json         # Streaming credentials (safeStorage encrypted)
-├── app-cache/covers/      # Cover thumbnails (cover:// protocol)
-├── Database/library.db    # Music library (better-sqlite3, WAL)
-└── logs/
+{userData}/app-data/        # 统一数据目录（与 Chromium 的 Cache/ 等隔开，便携版整体迁移此目录）
+├── config/
+│   ├── settings.json       # Main config (electron/main/store/)
+│   ├── streaming.json      # Streaming credentials (safeStorage encrypted)
+│   └── lastfm.json         # Last.fm credentials (safeStorage encrypted)
+├── database/library.db     # Music library (better-sqlite3, WAL)
+├── cache/                  # covers/ (cover:// protocol) + artists/ backgrounds/ songs/
+├── logs/                   # App logs + native/
+└── plugins/                # scripts/ data/ logs/
+
+# 全部路径集中定义于 electron/main/utils/paths.ts，改一处即可整体迁移
 ```
 
 Renderer IndexedDB (localforage): `splayer/library`, `splayer/queue`, `splayer/playlists`, `splayer/streaming-cache`.
 
 ### Cover Image
 
-Rust extracts 300x300 JPEG thumbnail to `{userData}/app-cache/covers/` during decode; renderer reads via `cover://{filename}` protocol. Original via `getCoverRaw()` for SMTC, never cached. Streaming covers use remote URLs directly (browser cache).
+Rust extracts 300x300 JPEG thumbnail to `{userData}/app-data/cache/covers/` during decode; renderer reads via `cover://{filename}` protocol. Original via `getCoverRaw()` for SMTC, never cached. Streaming covers use remote URLs directly (browser cache).
 
 ### Config Store (Main)
 
-`electron/main/store/` is custom (not electron-store). Reads/writes `{userData}/settings.json`, merges with defaults from `shared/defaults/settings.ts`. Supports dot-path access (`store.get("system.taskbarProgress")`), atomic writes, schema migrations.
+`electron/main/store/` is custom (not electron-store). Reads/writes `{userData}/app-data/config/settings.json` (path via `electron/main/utils/paths.ts`), merges with defaults from `shared/defaults/settings.ts`. Supports dot-path access (`store.get("system.taskbarProgress")`), atomic writes, schema migrations.
 
 ### i18n
 

dev-app-update.yml

@@ -1,3 +1,4 @@
-provider: generic
-url: https://example.com/auto-updates
+provider: github
+owner: SPlayer-Dev
+repo: SPlayer-Next
 updaterCacheDirName: splayer-next-updater