From 7b18937df0a6678d66e5fed6667b35f8156d5c3e Mon Sep 17 00:00:00 2001
From: dijunkun <junkun.di@hotmail.com>
Date: Fri, 30 Oct 2026 16:32:46 +0800
Subject: [PATCH] [build] cache CLI toolchain and native dependencies

---
 .github/workflows/build-cli.yml   | 43 +++++++++++++++++++++++++++++--
 apps/cli/docs/npm-distribution.md |  4 +++
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/build-cli.yml b/.github/workflows/build-cli.yml
index ed93a4e2..72f325c9 100644
--- a/.github/workflows/build-cli.yml
+++ b/.github/workflows/build-cli.yml
@@ -31,6 +31,8 @@ jobs:
             arch: x64
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 120
+    env:
+      XMAKE_VERSION: "3.1.1"
     steps:
       - uses: actions/checkout@v4
         with:
@@ -38,18 +40,47 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
+      # A runner label can receive compiler/SDK updates without changing its name.
+      - name: Set cache environment
+        id: runner-image
+        shell: bash
+        run: |
+          printf 'version=%s\n' "${ImageVersion:?Missing GitHub runner image version}" >> "$GITHUB_OUTPUT"
+          # Keep installed packages separate from the project's build/config state.
+          printf 'XMAKE_PKG_INSTALLDIR=%s/crossdesk-cli-packages\n' "$RUNNER_TEMP" >> "$GITHUB_ENV"
       - uses: xmake-io/github-action-setup-xmake@v1
         with:
-          xmake-version: 3.1.1
+          xmake-version: ${{ env.XMAKE_VERSION }}
+          actions-cache-folder: ${{ runner.temp }}/crossdesk-cli-xmake-toolchain
+          actions-cache-key: cli-${{ matrix.runner }}-${{ matrix.target }}-image${{ steps.runner-image.outputs.version }}-xmake${{ env.XMAKE_VERSION }}
       - uses: ilammy/msvc-dev-cmd@v1
         if: runner.os == 'Windows'
         with:
           arch: ${{ matrix.arch }}
       - name: Linux build tools
         if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y build-essential pkg-config autoconf automake libtool nasm yasm zlib1g-dev python3-pip
+        shell: bash
+        run: |
+          missing=()
+          for package in build-essential pkg-config autoconf automake libtool nasm yasm zlib1g-dev python3-pip; do
+            if [[ "$(dpkg-query -W -f='${Status}' "$package" 2>/dev/null || true)" != "install ok installed" ]]; then
+              missing+=("$package")
+            fi
+          done
+          if (( ${#missing[@]} )); then
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends "${missing[@]}"
+          fi
       - name: Prepare pinned dependency
         run: sh apps/cli/scripts/prepare-deps.sh
+      # Exact matches only: changed local recipes/patches must not reuse old libraries.
+      # Source, README and npm metadata edits do not change this key.
+      - name: Restore native dependencies
+        id: native-cache
+        uses: actions/cache/restore@v5
+        with:
+          path: ${{ env.XMAKE_PKG_INSTALLDIR }}
+          key: cli-deps-v1-${{ matrix.runner }}-${{ matrix.target }}-image${{ steps.runner-image.outputs.version }}-xmake${{ env.XMAKE_VERSION }}-${{ hashFiles('xmake.lua', 'apps/cli/xmake.lua', 'apps/desktop/xmake/options.lua', 'deps/thirdparty/openssl/**', 'deps/submodules/minirtc/xmake.lua', 'deps/submodules/minirtc/thirdparty/**', 'deps/patches/**', '.github/workflows/build-cli.yml') }}
       - name: Configure macOS
         if: runner.os == 'macOS'
         run: xmake f -y -p macosx -a ${{ matrix.arch }} -m release --target_minver=13.0 --CROSSDESK_BUILD_DESKTOP=n --CROSSDESK_BUILD_CLI=y --USE_CUDA=n
@@ -59,6 +90,14 @@ jobs:
       - name: Configure Windows
         if: runner.os == 'Windows'
         run: xmake f -y -p windows -a ${{ matrix.arch }} -m release --CROSSDESK_BUILD_DESKTOP=n --CROSSDESK_BUILD_CLI=y --USE_CUDA=n
+      # xmake f installs required packages. Save before compiling or packaging the CLI,
+      # so failures in those later steps do not discard successfully installed dependencies.
+      - name: Save native dependencies
+        if: steps.native-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: ${{ env.XMAKE_PKG_INSTALLDIR }}
+          key: ${{ steps.native-cache.outputs.cache-primary-key }}
       - name: Build
         run: xmake build crossdesk-cli
       - name: Sign macOS CLI
diff --git a/apps/cli/docs/npm-distribution.md b/apps/cli/docs/npm-distribution.md
index 391add5f..2512a80a 100644
--- a/apps/cli/docs/npm-distribution.md
+++ b/apps/cli/docs/npm-distribution.md
@@ -80,6 +80,10 @@ Pi 等宿主应直接启动原生程序以可靠控制进程和专用密码描
 
 `.github/workflows/build-cli.yml` 配置五个平台的原生 release 构建、doctor 和打包，并上传 tarball；该工作流不执行 npm publish。更新 MiniRTC 引用时，必须先将对应提交推送到子模块远端，再推送 CrossDesk，否则全新检出和 CI 会在拉取子模块时失败。
 
+CLI 构建分别缓存 Xmake 工具和已安装的原生依赖。原生依赖使用 `XMAKE_PKG_INSTALLDIR` 指定的 runner 临时目录，不缓存工程的 `.xmake` 配置或 `build` 产物。缓存 key 包含 runner 类型、目标架构、镜像版本、Xmake 版本以及构建配置、依赖配方和补丁的内容；不包含运行编号，也不因 CLI C++ 源码、README 或 npm 元数据修改而失效。镜像更新可能包含编译器／SDK 更新，因此会重新生成缓存；依赖配置变化时只接受新的完整 key，不回退使用旧配方的库。
+
+`Restore native dependencies` 会显示缓存是否命中。各平台的 `xmake f` 成功安装依赖后立即执行 `Save native dependencies`，后续 CLI 编译、签名或打包失败也能在下一次复用；依赖安装失败时不会保存不完整缓存。Linux 仅对镜像中缺失的系统工具执行 APT 更新和安装。首次运行、缓存被清理、镜像或依赖配置变化仍需下载／编译依赖；缓存命中不代表跳过 CLI 自身构建和打包。
+
 首次使用 `@chunkdash` 前，确认当前 npm 账号属于该组织且有目标包的发布权限。本地发布需要已启用的 2FA 或符合 npm 要求的发布凭据；组织 owner 身份不代替发布认证。
 
 ```sh