feat(linux): x86_64 预编译 AppImage —— CI 构建 + install.sh 下载即用

与 normal 分支同步：scripts/build-appimage.sh（jammy 内 linuxdeploy bundle GTK）、
.github/workflows/linux-appimage.yml（tag 触发 CI 构建 AppImage 附加到 release）、
cli/install.sh（Linux x86_64 默认下载 AppImage）、README 更新。

Author: Neo-Isshin

.github/workflows/linux-appimage.yml

@@ -0,0 +1,40 @@
+# 在 tag 推送时为 Linux x86_64 构建 AppImage 并附加到对应 release。
+#
+# 流程：release.sh（Mac）构建 macOS 双变体 + 建 release + 推 tag → 本 workflow 被 tag 触发 →
+# 在 swift:6.0-jammy 容器（glibc 2.35，覆盖 2022+ 发行版）里 checkout normal（含 Linux 源码）
+# → 跑 scripts/build-appimage.sh → 把 TokenClock-x86_64.AppImage + .sha256 附加到该 release。
+# 与 release.sh 之间是异步的（AppImage 约在发版后 5–10 分钟出现）；softprops/action-gh-release
+# 的 create-or-update 语义避免「release 还没建好」的竞态。
+name: linux-appimage
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:       # 允许手动触发，便于在不打 tag 时验证
+
+permissions:
+  contents: write          # 附加资产到 release 需要
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: swift:6.0-jammy
+    steps:
+      - name: Checkout normal branch (Linux sources + build script)
+        uses: actions/checkout@v4
+        with:
+          ref: normal
+
+      - name: Build AppImage
+        run: |
+          chmod +x scripts/build-appimage.sh
+          ./scripts/build-appimage.sh
+
+      - name: Attach AppImage + SHA256 to the release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          files: |
+            TokenClock-x86_64.AppImage
+            TokenClock-x86_64.AppImage.sha256

README.md

@@ -206,32 +206,38 @@ curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/inst
 
 ### Linux normal build
 
-Linux intentionally ships the **normal classic dial only**. It uses GTK3, keeps the existing 14 local usage parsers, stores history under XDG data directories, registers XDG autostart, and exposes the same loopback API on `127.0.0.1:9988`. Liquid Glass, the macOS theme editor, and weather/location UI are not part of the Linux build.
+Linux intentionally ships the **normal classic dial only** (GTK3). It keeps the existing 14 local usage parsers, stores history under XDG data directories, registers XDG autostart, and exposes the same loopback API on `127.0.0.1:9988`. Liquid Glass, the macOS theme editor, and weather/location UI are not part of the Linux build.
 
-Install [Swift 6](https://www.swift.org/install/linux/) first, then:
+**x86_64 — prebuilt AppImage (default):** the universal one-liner downloads a self-contained AppImage (GTK3 bundled, needs only glibc ≥ 2.35) — no Swift, no compilation, no dev headers:
 
 ```bash
-# Ubuntu / Debian build dependencies
-sudo apt install git pkg-config libcurl4 libgtk-3-dev libsqlite3-dev
-
-# same universal one-liner — detects Linux and builds the normal GTK3 build from source
+# the same universal one-liner — on x86_64 Linux it fetches the prebuilt AppImage
 curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bash
 ```
 
+The AppImage needs `libfuse2` at runtime (present on most desktop distros; if missing: `sudo apt install libfuse2`, or `libfuse2t64` on Ubuntu 24.04+).
+
+**Other arches / `--build-from-source`** — build from source (needs Swift 6 + GTK3/SQLite3 dev headers):
+
+```bash
+sudo apt install git pkg-config libcurl4 libgtk-3-dev libsqlite3-dev   # Ubuntu/Debian build deps
+curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bash -s -- --build-from-source
+```
+
 Or use the reproducible container build:
 
 ```bash
 docker build -f Dockerfile.linux -t tokenclock-linux .
 ```
 
-Options: `--normal` / `--glass` (pick the variant) / `--no-start` (don't auto-launch) / `--build-from-source` (force a local build) / `--check` (check only, don't install) / `--debug` (debug build).
+Options: `--normal` / `--glass` (pick the variant) / `--no-start` (don't auto-launch) / `--build-from-source` (force a local source build) / `--check` (check only, don't install) / `--debug` (debug build).
 
-> Or build manually from source below.
+> Note: on newer-glibc distros the AppImage may print a harmless `libgvfs … undefined symbol / Failed to load module` line to the terminal — TokenClock doesn't use gvfs; ignore it (it's invisible when launched from the desktop menu).
 
 ### Prerequisites
 - **macOS 12+** (normal build); **macOS 26+** (Liquid Glass build)
 - The precompiled install needs **no toolchain at all**; Swift 6 (Xcode 16+ / Command Line Tools) is only required for `--build-from-source` local builds
-- **Linux normal:** Swift 6, GTK3 development headers, SQLite3 development headers, `libcurl4`, and `pkg-config`
+- **Linux normal:** x86_64 uses the prebuilt AppImage (needs only `libfuse2` + glibc ≥ 2.35, both standard on desktop distros); other arches / `--build-from-source` need Swift 6, GTK3/SQLite3 dev headers, `libcurl4`, and `pkg-config`
 
 ### Build & run from source
 

README.zh-CN.md

@@ -207,30 +207,36 @@ curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/inst
 
 Linux 仅适配 **normal 经典不透明表盘**：使用 GTK3，复用现有 14 个本地用量解析器，历史数据按 XDG 目录保存，支持 XDG 登录自启动，并在 `127.0.0.1:9988` 提供同构 API。Linux 版不包含 Liquid Glass、macOS 主题编辑器和天气/定位界面。
 
-先安装 [Swift 6](https://www.swift.org/install/linux/)，然后执行：
+**x86_64 —— 预编译 AppImage（默认）：** 通用一键命令会下载一个自带 GTK3 的 AppImage（仅要求 glibc ≥ 2.35），无需 Swift、无需编译、无需开发头文件：
 
 ```bash
-# Ubuntu / Debian 构建依赖
-sudo apt install git pkg-config libcurl4 libgtk-3-dev libsqlite3-dev
-
-# 同一条通用安装命令 —— 自动识别 Linux 并从源码编译 normal GTK3 版
+# 同一条通用安装命令 —— 在 x86_64 Linux 上自动下载预编译 AppImage
 curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bash
 ```
 
+AppImage 运行期需要 `libfuse2`（多数桌面发行版自带；缺失时：`sudo apt install libfuse2`，Ubuntu 24.04+ 为 `libfuse2t64`）。
+
+**其它架构 / `--build-from-source`** —— 从源码编译（需要 Swift 6 + GTK3/SQLite3 开发头文件）：
+
+```bash
+sudo apt install git pkg-config libcurl4 libgtk-3-dev libsqlite3-dev   # Ubuntu/Debian 构建依赖
+curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh | bash -s -- --build-from-source
+```
+
 也可以使用可复现的容器构建：
 
 ```bash
 docker build -f Dockerfile.linux -t tokenclock-linux .
 ```
 
-可选参数：`--normal` / `--glass`（指定变体）/ `--no-start`（装完不自动启动）/ `--build-from-source`（强制本地编译）/ `--check`（仅检查不安装）/ `--debug`（debug 构建）。
+可选参数：`--normal` / `--glass`（指定变体）/ `--no-start`（装完不自动启动）/ `--build-from-source`（强制本地源码编译）/ `--check`（仅检查不安装）/ `--debug`（debug 构建）。
 
-> 也可手动从源码构建，见下方。
+> 注：在较新 glibc 的发行版上，AppImage 启动时终端可能打印一行无害的 `libgvfs … undefined symbol / Failed to load module` —— TokenClock 不使用 gvfs，可忽略（从桌面菜单启动时看不到）。
 
 ### 前置要求
 - **macOS 12+**（普通版）；**macOS 26+**（Liquid Glass 版）
 - 预编译安装**无需任何工具链**；仅 `--build-from-source` 本地编译时需要 Swift 6（Xcode 16+ / Command Line Tools）
-- **Linux normal**：Swift 6、GTK3/SQLite3 开发头文件、`libcurl4` 与 `pkg-config`
+- **Linux normal**：x86_64 走预编译 AppImage（仅需 `libfuse2` + glibc ≥ 2.35，桌面发行版均自带）；其它架构 / `--build-from-source` 需 Swift 6、GTK3/SQLite3 开发头文件、`libcurl4` 与 `pkg-config`
 
 ### 从源码构建运行
 

cli/install.sh

@@ -41,6 +41,7 @@ FORCE=0             # --force: bypass the "no change" short-circuit and redeploy
 DEPLOYED_ANYTHING=0 # whether anything was actually deployed this run (reported to tokenclock update to decide whether to restart)
 BUILT_BINS=()       # collected build-artifact paths, as path:variant
 BUILD_FROM_SOURCE=0 # --build-from-source: skip the prebuilt download and force a local swift build
+LINUX_APPIMAGE=0    # Linux x86_64 默认走预编译 AppImage（置 1 后由 download_appimage 处理）
 
 say()  { printf '%s\n' "$*"; }
 step() { printf '\n🛠  %s\n' "$*"; }
@@ -97,16 +98,28 @@ case "$KERNEL" in
   Linux)
     PLATFORM=linux
     OS_MAJOR=0
-    BUILD_FROM_SOURCE=1
     [ "$VARIANT" != glass ] || die "Linux supports the normal variant only; remove --glass."
-    command -v git >/dev/null 2>&1 || die "git is required on Linux."
-    command -v swift >/dev/null 2>&1 || die "Swift 6 is required on Linux (https://www.swift.org/install/linux/)."
-    command -v pkg-config >/dev/null 2>&1 || die "pkg-config is required on Linux."
-    pkg-config --exists gtk+-3.0 || die "GTK3 development files are required (Ubuntu/Debian: sudo apt install libgtk-3-dev)."
-    pkg-config --exists sqlite3 || die "SQLite development files are required (Ubuntu/Debian: sudo apt install libsqlite3-dev)."
+    if [ "$(uname -m)" = x86_64 ] && [ "$BUILD_FROM_SOURCE" -eq 0 ]; then
+      # x86_64 默认走预编译 AppImage：无需 Swift/GTK 工具链，下载即用。
+      # AppImage 运行期需要 libfuse2（多数桌面发行版自带；缺失时给一行安装提示）。
+      LINUX_APPIMAGE=1
+      if ! ldconfig -p 2>/dev/null | grep -q 'libfuse.so.2'; then
+        say "  ⚠ 未检测到 libfuse2（AppImage 运行所需）。如启动失败请安装："
+        say "      Ubuntu/Debian: sudo apt install libfuse2    (24.04+ 为 libfuse2t64)"
+      fi
+      say "  Linux $(uname -m) · 预编译 AppImage（--build-from-source 可改走源码编译）"
+    else
+      # 其它架构（如 aarch64）或 --build-from-source：源码编译，需 Swift6 + GTK/SQLite 开发头文件。
+      BUILD_FROM_SOURCE=1
+      command -v git >/dev/null 2>&1 || die "git is required on Linux."
+      command -v swift >/dev/null 2>&1 || die "Swift 6 is required on Linux (https://www.swift.org/install/linux/)."
+      command -v pkg-config >/dev/null 2>&1 || die "pkg-config is required on Linux."
+      pkg-config --exists gtk+-3.0 || die "GTK3 development files are required (Ubuntu/Debian: sudo apt install libgtk-3-dev)."
+      pkg-config --exists sqlite3 || die "SQLite development files are required (Ubuntu/Debian: sudo apt install libsqlite3-dev)."
+      say "  Linux $(uname -r) · normal GTK3 build · source build"
+    fi
     [ "$INSTALL_URL" != "https://raw.githubusercontent.com/Neo-Isshin/TokenClock/main/cli/install.sh" ] \
       || INSTALL_URL="https://raw.githubusercontent.com/Neo-Isshin/TokenClock/normal/cli/install.sh"
-    say "  Linux $(uname -r) · normal GTK3 build · source build"
     ;;
   *)
     die "Unsupported platform: $KERNEL (TokenClock supports macOS and Linux)."
@@ -245,6 +258,36 @@ download_variant() {
   return 0
 }
 
+# Linux x86_64: 下载预编译 AppImage + sidecar SHA256（由 CI 在发版后产出，故不写死在脚本里），
+# 校验通过则把 AppImage 路径写入全局 APPIMAGE_PATH 并返回 0；失败返回 1（调用方回退源码编译）。
+APPIMAGE_PATH=""
+download_appimage() {
+  local name="TokenClock-x86_64.AppImage" sha_name="$name.sha256" url tmp got expect
+  url="$RELEASE_URL_BASE/$name"
+  step "Downloading prebuilt AppImage (Linux x86_64 · $RELEASE_TAG)"
+  tmp="$(mktemp -d 2>/dev/null)" || return 1
+  if ! curl -fL --retry 6 --retry-delay 2 --retry-all-errors --connect-timeout 15 -o "$tmp/$name" "$url" 2>/dev/null; then
+    say "  ⚠ AppImage 下载失败（$url，可能 CI 尚未构建完成）→ 回退源码编译"
+    rm -rf "$tmp"; return 1
+  fi
+  if ! curl -fL --retry 6 --retry-delay 2 --retry-all-errors --connect-timeout 15 -o "$tmp/$sha_name" "$RELEASE_URL_BASE/$sha_name" 2>/dev/null; then
+    say "  ⚠ AppImage 的 SHA256 sidecar 下载失败 → 回退源码编译"
+    rm -rf "$tmp"; return 1
+  fi
+  expect="$(awk '{print $1}' "$tmp/$sha_name" 2>/dev/null)"
+  [ -n "$expect" ] || { say "  ⚠ SHA256 sidecar 为空 → 回退源码编译"; rm -rf "$tmp"; return 1; }
+  got="$(sha256_file "$tmp/$name")"
+  if [ "$got" != "$expect" ]; then
+    say "  ⚠ AppImage SHA256 不符（expected ${expect:0:12}… got ${got:0:12}…）→ 回退源码编译"
+    rm -rf "$tmp"; return 1
+  fi
+  chmod +x "$tmp/$name"
+  say "  ✓ AppImage 就绪（SHA256 ${got:0:12}…）"
+  APPIMAGE_PATH="$tmp/$name"
+  DOWNLOAD_TMPDIRS+=("$tmp")
+  return 0
+}
+
 # Local source build: on macOS 27 with only CLT, automatically pin to the 26 SDK (works around missing SwiftUIMacros).
 swift_build_fallback() {
   local subdir="$1"
@@ -263,13 +306,19 @@ for i in "${!VARIANTS[@]}"; do
   branch="${BRANCHES[$i]}"
   subdir="$BUILD_DIR/$branch"
 
-  # 4a. Prefer the prebuilt binary
-  if [ "$BUILD_FROM_SOURCE" -eq 0 ] && download_variant "$variant"; then
+  # 4a. Linux x86_64: 优先下载预编译 AppImage
+  if [ "${LINUX_APPIMAGE:-0}" = 1 ] && download_appimage; then
+    BUILT_BINS+=("$APPIMAGE_PATH:$variant")
+    continue
+  fi
+
+  # 4b. macOS: 优先下载预编译 universal 二进制（Linux 上不下载 macOS tarball）
+  if [ "$PLATFORM" != linux ] && [ "$BUILD_FROM_SOURCE" -eq 0 ] && download_variant "$variant"; then
     BUILT_BINS+=("$DL_DIR/TokenClock:$variant")
     continue
   fi
 
-  # 4b. Fallback: build from source locally (this is the only path that needs a clone)
+  # 4c. Fallback: build from source locally (this is the only path that needs a clone)
   ensure_source "$variant" "$branch"
   step "Building [$variant] (swift build -c $CONFIG · first run may take a few minutes)"
   swift_build_fallback "$subdir" \

scripts/build-appimage.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# build-appimage.sh —— 在 swift:6.0-jammy 容器内构建 Linux x86_64 AppImage。
+#
+# 产物（落在仓库根）：TokenClock-x86_64.AppImage + TokenClock-x86_64.AppImage.sha256
+#
+# 用法（在装有 Docker 的 Linux/x86_64 主机上，于仓库根执行）：
+#   docker run --rm -v "$PWD":/src -w /src swift:6.0-jammy bash scripts/build-appimage.sh
+#
+# 设计要点：
+#   * swift:6.0-jammy = Ubuntu 22.04 / glibc 2.35 → AppImage 兼容 2022+ 主流发行版。
+#   * -Xswiftc -static-stdlib：静态链 Swift 运行时，去掉对目标机 Swift 运行时的依赖。
+#   * linuxdeploy + GTK 插件：把 GTK3 及其依赖打进 AppDir，用户机无需装 GTK，
+#     只剩 glibc ≥ 2.35 一个运行期要求。
+#   * APPIMAGE_EXTRACT_AND_RUN=1：容器内通常无 /dev/fuse，让 linuxdeploy/appimagetool
+#     这俩 AppImage 工具自解压到 /tmp 运行，免 FUSE。
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+ARCH=x86_64
+APP=TokenClock
+APPIMAGE="$APP-$ARCH.AppImage"
+ICON_NAME=tokenclock
+
+step() { printf '\n🛠  %s\n' "$*"; }
+ok()   { printf '  ✓ %s\n' "$*"; }
+die()  { printf '\n❌ %s\n' "$*" >&2; exit 1; }
+
+# ── 1. 构建依赖 ──
+step "Installing build deps (apt)"
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y --no-install-recommends \
+  libgtk-3-dev libsqlite3-dev libcurl4-openssl-dev \
+  pkg-config file ca-certificates wget libfuse2 \
+  >/dev/null
+ok "deps installed"
+
+# ── 2. 编译 ──
+step "Building TokenClock (swift build -c release · x86_64 · static stdlib)"
+swift build -c release -Xswiftc -static-stdlib
+BIN="$ROOT/.build/release/$APP"
+[ -f "$BIN" ] || die "build artifact not found: $BIN"
+ok "binary: $BIN ($(du -h "$BIN" | cut -f1))"
+
+# ── 3. 组装 AppDir ──
+step "Assembling AppDir"
+APPDIR="$ROOT/AppDir"
+rm -rf "$APPDIR"
+mkdir -p "$APPDIR/usr/bin" "$APPDIR/usr/share/applications" "$APPDIR/usr/share/icons/hicolor/256x256/apps"
+
+cp "$BIN" "$APPDIR/usr/bin/$APP"
+chmod +x "$APPDIR/usr/bin/$APP"
+
+ICON_SRC="$ROOT/Sources/TokenClock/Resources/glass_disc.png"
+[ -f "$ICON_SRC" ] || die "icon source not found: $ICON_SRC"
+cp "$ICON_SRC" "$APPDIR/usr/share/icons/hicolor/256x256/apps/$ICON_NAME.png"
+ok "icon installed ($ICON_SRC)"
+
+cat > "$APPDIR/usr/share/applications/$APP.desktop" <<EOF
+[Desktop Entry]
+Name=TokenClock
+Comment=Token usage clock for AI coding tools
+Exec=$APP
+Icon=$ICON_NAME
+Type=Application
+Categories=Utility;
+Terminal=false
+StartupWMClass=TokenClock
+EOF
+ok "desktop entry written"
+
+# ── 4. linuxdeploy → bundle 全部动态依赖（含 GTK3 全家桶，经 ldd 发现），产出 AppImage ──
+# 注：官方 linuxdeploy-plugin-gtk 当前无预编译 release（仓库 releases 页为空），
+# 故改用 linuxdeploy 核心：它经 ldd 把二进制链接的全部 .so（含 libgtk-3/glib/pango/cairo/…）
+# 连同 gdk-pixbuf loaders、glib schemas 一起收进 AppDir，用户机无需装 GTK，只剩 glibc ≥ 2.35。
+step "Fetching linuxdeploy"
+TOOLS="$ROOT/.appimage-tools"
+mkdir -p "$TOOLS"
+LD="$TOOLS/linuxdeploy-$ARCH.AppImage"
+[ -f "$LD" ] || wget -q -O "$LD" "https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-$ARCH.AppImage"
+[ -s "$LD" ] || die "linuxdeploy download failed (empty file)"
+chmod +x "$LD"
+ok "linuxdeploy ready"
+
+# 容器内无 FUSE：让 linuxdeploy 这个 AppImage 自解压到 /tmp 运行
+export APPIMAGE_EXTRACT_AND_RUN=1
+export ARCH="$ARCH"
+export VERSION="${VERSION:-0.0.0}"          # linuxdeploy 要求 VERSION 环境变量
+export OUTPUT="$APPIMAGE"
+
+step "Packaging AppImage (linuxdeploy --output appimage)"
+"$LD" --appdir "$APPDIR" \
+      --desktop-file "$APPDIR/usr/share/applications/$APP.desktop" \
+      --icon-file    "$APPDIR/usr/share/icons/hicolor/256x256/apps/$ICON_NAME.png" \
+      --output appimage \
+  || die "linuxdeploy packaging failed"
+[ -f "$ROOT/$APPIMAGE" ] || die "AppImage not produced: $ROOT/$APPIMAGE"
+chmod +x "$ROOT/$APPIMAGE"
+ok "$APPIMAGE ($(du -h "$ROOT/$APPIMAGE" | cut -f1))"
+
+# ── 5. SHA256 sidecar ──
+step "SHA256 sidecar"
+( cd "$ROOT" && sha256sum "$APPIMAGE" > "$APPIMAGE.sha256" )
+ok "$APPIMAGE.sha256"
+
+# ── 6. 修产物/中间产物属主（容器内以 root 构建、挂载到主机时，把属主还给主机用户）──
+# CI 里 workspace 通常属 root → 守卫跳过；Debian 开发主机挂载属普通用户 → 还原，便于清理。
+HOST_OWNER="$(stat -c %u:%g "$ROOT" 2>/dev/null || true)"
+if [ -n "$HOST_OWNER" ] && [ "$(id -u)" = 0 ] && [ "${HOST_OWNER%%:*}" != 0 ]; then
+  chown -R "$HOST_OWNER" "$ROOT/.build" "$ROOT/AppDir" "$ROOT/.appimage-tools" \
+                            "$ROOT/$APPIMAGE" "$ROOT/$APPIMAGE.sha256" 2>/dev/null || true
+  ok "ownership → $HOST_OWNER"
+fi
+
+echo
+echo "Done: $ROOT/$APPIMAGE (+ $APPIMAGE.sha256)"