feat(build): add mirror-first sidecar supply

Author: Jacobinwwey

.gitattributes

@@ -43,9 +43,6 @@
 *.aab binary
 *.keystore binary
 *.jks binary
-src/frontend/graph_data.json filter=lfs diff=lfs merge=lfs -text
-src/frontend/data.js filter=lfs diff=lfs merge=lfs -text
-src-tauri/bin/node-x86_64-pc-windows-msvc.exe filter=lfs diff=lfs merge=lfs -text
 src-tauri/bin/server-x86_64-pc-windows-msvc.exe filter=lfs diff=lfs merge=lfs -text
 src-tauri/bin/godot-x86_64-pc-windows-msvc.exe filter=lfs diff=lfs merge=lfs -text
 src-tauri/bin/server-x86_64-unknown-linux-gnu filter=lfs diff=lfs merge=lfs -text

.github/workflows/release-desktop-multi-os.yml

@@ -20,6 +20,11 @@ permissions:
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  GODOT_MIRROR_TAG: "godot-mirror-v4.3-stable"
+  GODOT_UPSTREAM_BASE_URL: "https://github.com/godotengine/godot/releases/download/4.3-stable"
+  GODOT_WINDOWS_ARCHIVE_NAME: "Godot_v4.3-stable_win64.exe.zip"
+  GODOT_LINUX_ARCHIVE_NAME: "Godot_v4.3-stable_linux.x86_64.zip"
+  GODOT_MACOS_ARCHIVE_NAME: "Godot_v4.3-stable_macos.universal.zip"
 
 jobs:
   ensure-release:
@@ -61,9 +66,64 @@ jobs:
             gh release create "$TAG_NAME" --title "$TAG_NAME" --notes "Automated desktop multi-OS release assets."
           fi
 
+  ensure-godot-mirror-assets:
+    name: Ensure Godot Mirror Assets
+    needs: ensure-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Ensure Godot mirror release exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          if gh release view "$GODOT_MIRROR_TAG" >/dev/null 2>&1; then
+            echo "Godot mirror release already exists: $GODOT_MIRROR_TAG"
+          else
+            gh release create "$GODOT_MIRROR_TAG" \
+              --title "$GODOT_MIRROR_TAG" \
+              --notes "Project-controlled mirror for Godot desktop bootstrap archives."
+          fi
+
+      - name: Seed Godot mirror assets from upstream when missing
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p build/godot-mirror
+          mapfile -t EXISTING_ASSETS < <(gh release view "$GODOT_MIRROR_TAG" --json assets --jq '.assets[].name')
+
+          has_asset() {
+            local needle="$1"
+            local asset
+            for asset in "${EXISTING_ASSETS[@]}"; do
+              if [ "$asset" = "$needle" ]; then
+                return 0
+              fi
+            done
+            return 1
+          }
+
+          for ASSET_NAME in \
+            "$GODOT_WINDOWS_ARCHIVE_NAME" \
+            "$GODOT_LINUX_ARCHIVE_NAME" \
+            "$GODOT_MACOS_ARCHIVE_NAME"
+          do
+            if has_asset "$ASSET_NAME"; then
+              echo "Mirror asset already present: $ASSET_NAME"
+              continue
+            fi
+
+            ARCHIVE_PATH="build/godot-mirror/$ASSET_NAME"
+            curl -fsSL "${GODOT_UPSTREAM_BASE_URL}/${ASSET_NAME}" -o "$ARCHIVE_PATH"
+            gh release upload "$GODOT_MIRROR_TAG" "$ARCHIVE_PATH" --clobber
+            echo "Uploaded mirror asset: $ASSET_NAME"
+          done
+
   build-and-upload:
     name: Build and Upload (${{ matrix.platform_label }})
-    needs: ensure-release
+    needs: [ensure-release, ensure-godot-mirror-assets]
     runs-on: ${{ matrix.runner }}
     strategy:
       fail-fast: false
@@ -135,7 +195,16 @@ jobs:
           $ErrorActionPreference = "Stop"
           New-Item -ItemType Directory -Path "build\godot" -Force | Out-Null
           $archive = "build\godot\godot-win64.zip"
-          Invoke-WebRequest -Uri "https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_win64.exe.zip" -OutFile $archive
+          $mirrorBaseUrl = "https://github.com/Jacobinwwey/NoteConnection/releases/download/$env:GODOT_MIRROR_TAG"
+          $mirrorUrl = "$mirrorBaseUrl/$env:GODOT_WINDOWS_ARCHIVE_NAME"
+          $upstreamUrl = "$env:GODOT_UPSTREAM_BASE_URL/$env:GODOT_WINDOWS_ARCHIVE_NAME"
+          try {
+            Invoke-WebRequest -Uri $mirrorUrl -OutFile $archive
+            Write-Host "Downloaded Godot archive from project mirror: $mirrorUrl"
+          } catch {
+            Write-Warning "Project mirror download failed, falling back to upstream: $upstreamUrl"
+            Invoke-WebRequest -Uri $upstreamUrl -OutFile $archive
+          }
           Expand-Archive -Path $archive -DestinationPath "build\godot\extract" -Force
           $godotExe = Get-ChildItem -Path "build\godot\extract" -Filter "Godot_v4.3-stable_win64.exe" -Recurse | Select-Object -First 1
           if (-not $godotExe) {
@@ -155,7 +224,11 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p build/godot
-          curl -fsSL "https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip" -o build/godot/godot-linux.zip
+          MIRROR_BASE_URL="https://github.com/Jacobinwwey/NoteConnection/releases/download/${GODOT_MIRROR_TAG}"
+          if ! curl -fsSL "${MIRROR_BASE_URL}/${GODOT_LINUX_ARCHIVE_NAME}" -o build/godot/godot-linux.zip; then
+            echo "Project mirror download failed, falling back to upstream."
+            curl -fsSL "${GODOT_UPSTREAM_BASE_URL}/${GODOT_LINUX_ARCHIVE_NAME}" -o build/godot/godot-linux.zip
+          fi
           unzip -q -o build/godot/godot-linux.zip -d build/godot/extract
           GODOT_BIN="$(find build/godot/extract -maxdepth 2 -type f -name 'Godot_v4.3-stable_linux.x86_64' | head -n 1)"
           if [ -z "${GODOT_BIN}" ]; then
@@ -171,7 +244,11 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p build/godot
-          curl -fsSL "https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_macos.universal.zip" -o build/godot/godot-macos.zip
+          MIRROR_BASE_URL="https://github.com/Jacobinwwey/NoteConnection/releases/download/${GODOT_MIRROR_TAG}"
+          if ! curl -fsSL "${MIRROR_BASE_URL}/${GODOT_MACOS_ARCHIVE_NAME}" -o build/godot/godot-macos.zip; then
+            echo "Project mirror download failed, falling back to upstream."
+            curl -fsSL "${GODOT_UPSTREAM_BASE_URL}/${GODOT_MACOS_ARCHIVE_NAME}" -o build/godot/godot-macos.zip
+          fi
           unzip -q -o build/godot/godot-macos.zip -d build/godot/extract
           GODOT_BIN="$(find build/godot/extract -type f -path '*Godot.app/Contents/MacOS/Godot' | head -n 1)"
           if [ -z "${GODOT_BIN}" ]; then

.gitignore

@@ -69,3 +69,4 @@ tmp
 # Local docs deploy/build artifacts
 .edgeone/
 build/mkdocs-site/
+.venv-mkdocs/

README.md

@@ -1,4 +1,4 @@
-# 2026-03-31 v1.7.0
+# 2026-04-07 v1.7.0
 
 # NoteConnection Knowledge Graph
 
@@ -166,10 +166,15 @@ NoteConnection now supports **two Android generation paths**:
 1. **Capacitor APK path** (web-asset runtime, stable for reader/visualization workflows).
 2. **Tauri Android path** (native shell pipeline aligned with `docs/tauri_brainstorming.md`).
 
+Build/release/runtime details are audited in:
+
+- `docs/en/multi_platform_build_flow_audit.md`
+- `docs/zh/multi_platform_build_flow_audit.md`
+
 #### Prerequisites
 
 - **Node.js** (LTS)
-- **Java JDK** (17 or higher)
+- **Java JDK** (21 or higher)
 - **Android SDK** (Configured in `ANDROID_HOME` or via Android Studio)
 
 #### Method A: Capacitor Build (Stable)
@@ -224,8 +229,8 @@ npm run tauri:android:build
 
 #### Mobile Capability Boundary
 
-- Capacitor path currently packages web assets and does not embed the local Node sidecar workflow (`/api/build`, `/api/folders`, `/api/content`).
-- Tauri Android path is provided as the native-shell migration route and should be used when mobile-side parity with the Tauri architecture is required.
+- Capacitor packaging path does not embed the desktop Node sidecar workflow, but native Capacitor runtime can still build graph payloads locally when Filesystem APIs are available and the dataset stays within mobile limits.
+- Tauri Android path provides the native-shell runtime route and uses Android-native `build_graph_runtime` when mobile-side parity with the Tauri architecture is required.
 
 ### 3. Usage Guide
 
@@ -327,12 +332,19 @@ max_doc_bytes = 100663296
 
 ## 🏗️ Build & Deployment
 
-For developers building from source, NoteConnection offers two build modes:
+For developers building from source, NoteConnection now defaults to the runtime-first path:
 
 - **Electron desktop pipeline was removed on 2026-03-01 (deprecated and decommissioned).**
 
-- **Tauri Full Build (`npm run tauri:build`)**: Builds desktop package with full frontend assets.
-- **Tauri Mini Build (`npm run tauri:build:mini`)**: Builds desktop package excluding large pre-generated graph data files.
+- **Tauri Build (`npm run tauri:build`)**: Default desktop package path. Uses runtime-first assets and excludes pre-generated graph payloads.
+- **Tauri Mini Build (`npm run tauri:build:mini`)**: Legacy-compatible alias of the same runtime-first packaging path.
+- **Tauri Full Graph Build (`npm run tauri:build:full`)**: Explicit opt-in path for including generated graph assets when real files are present locally.
+- **Build (`npm run build`)**: Default runtime-first frontend build.
+- **Build Full Graph Assets (`npm run build:full`)**: Explicit opt-in frontend build for local/demo scenarios that need pre-generated graph assets.
+- **Godot Bootstrap** (`npm run prepare:godot:bin`): materializes the host Godot sidecar from local overrides/search paths, cache, or a pinned download URL.
+- **Desktop Release Godot Mirror**: release CI now seeds a project-controlled GitHub Releases mirror tag for Godot archives, then downloads mirror-first with upstream fallback.
+- **LFS Policy Guard** (`npm run verify:lfs:policy`): blocks new Git LFS drift under `src/frontend/` and `src-tauri/bin/` while migration still carries legacy exemptions. Future strict mode is available via `npm run verify:lfs:policy:strict`.
+- **Sidecar Supply Readiness** (`npm run verify:sidecar:supply`): reports whether the current desktop host is offline-ready or still network-dependent before shrinking the remaining sidecar LFS bridge.
 - **GPU Dev Start (`npm run tauri:dev:mini:gpu`)**: Recommended GPU-enabled Tauri development command.
 - **Do not use** `npm run tauri:dev:mini --gpu` because npm treats `--gpu` as config and prints warnings.
 
@@ -349,6 +361,8 @@ For developers building from source, NoteConnection offers two build modes:
 - Recommended lookup entry points:
   - Users: `/diataxis/zh/tutorials/first-run/` or `/diataxis/en/tutorials/first-run/`
   - Developers: `/diataxis/en/reference/interfaces-and-runtime/` and `/diataxis/en/reference/release-and-governance/`
+  - Maintainers assessing LFS / desktop bootstrap risk: `/en/sidecar_supply_strategy/` or `/zh/sidecar_supply_strategy/`
+  - Maintainers comparing mirror cost / user friction / maintenance burden: `/diataxis/en/explanation/sidecar-supply-feasibility/` or `/diataxis/zh/explanation/sidecar-supply-feasibility/`
 - CI auto publish workflow (GitHub Pages): `.github/workflows/docs-github-pages-publish.yml`.
 - Manual rollback entry: run workflow dispatch and set `git_ref` to a stable tag/commit.
 - MkDocs base/path can be overridden by environment variables: `MKDOCS_SITE_URL`, `MKDOCS_BASE_PATH`.
@@ -972,7 +986,7 @@ For optimal performance with "GPU Optimised Rendering", especially on AMD RDNA c
 ## 中文文档
 
 
-# 2026-03-31 v1.7.0
+# 2026-04-07 v1.7.0
 # NoteConnection: 层级知识图谱可视化系统
 
 <img width="606" height="309" alt="banner" src="https://github.com/user-attachments/assets/92e90de5-2b1a-4398-8e8b-6e142c92b6a2" />
@@ -1131,10 +1145,15 @@ NoteConnection 现支持 **两条 Android 生成路径**：
 1. **Capacitor APK 路径**（Web 资产运行时，适合阅读与可视化流程）。
 2. **Tauri Android 路径**（原生壳流程，对齐 `docs/tauri_brainstorming.md`）。
 
+与构建/release/运行时边界相关的完整审计文档见：
+
+- `docs/en/multi_platform_build_flow_audit.md`
+- `docs/zh/multi_platform_build_flow_audit.md`
+
 #### 先决条件
 
 - **Node.js** (LTS)
-- **Java JDK** (17 或更高版本)
+- **Java JDK** (21 或更高版本)
 - **Android SDK** (配置在 `ANDROID_HOME` 或通过 Android Studio 安装)
 
 #### 方法 A: Capacitor 构建（稳定）
@@ -1189,8 +1208,8 @@ npm run tauri:android:build
 
 #### 移动端能力边界
 
-- Capacitor 路径当前是 Web 资产打包，不内置桌面端本地 Node sidecar 流程（`/api/build`、`/api/folders`、`/api/content`）。
-- 若需要与 Tauri 架构一致的移动端原生壳路线，请使用 Tauri Android 路径。
+- Capacitor 打包路径本身不内置桌面 Node sidecar，但在具备 Filesystem API 且数据量不超过移动端限制时，Capacitor 原生运行时仍可本地图谱构建。
+- 如果需要与 Tauri 架构一致的移动端原生壳能力，请使用 Tauri Android 路径；该路径会通过 Android 原生命令 `build_graph_runtime` 构图。
 
 ---
 
@@ -1286,12 +1305,18 @@ max_doc_bytes = 100663296
 
 ## 🏗️ 构建与部署 (Build & Deployment)
 
-对于从源码构建的开发者，NoteConnection 提供两种构建模式：
+对于从源码构建的开发者，NoteConnection 现在默认采用 runtime-first 路径：
 
 - **Electron 桌面构建链路已于 2026-03-01 下线（弃用并完成清退）。**
-
-- **Tauri 完整构建** (`npm run tauri:build`): 构建带完整前端资源的桌面安装包。
-- **Tauri 精简构建** (`npm run tauri:build:mini`): 构建排除大型预生成图谱数据的桌面安装包。
+- **Tauri 构建** (`npm run tauri:build`)：默认桌面打包路径，采用 runtime-first 资产流，不默认打入预生成图谱载荷。
+- **Tauri 精简构建** (`npm run tauri:build:mini`)：与当前默认 runtime-first 打包路径保持兼容的旧别名。
+- **Tauri 完整图谱构建** (`npm run tauri:build:full`)：仅在本地存在真实图谱文件时，显式选择把生成型图谱资产打入包中。
+- **Build (`npm run build`)**：默认 runtime-first 前端构建。
+- **完整图谱前端构建** (`npm run build:full`)：仅供本地 / demo 场景显式选择预生成图谱资产。
+- **Godot Bootstrap** (`npm run prepare:godot:bin`)：可从本地覆盖路径 / 搜索目录 / 缓存 / 固定下载 URL 物化当前主机所需的 Godot sidecar。
+- **桌面 Release Godot 镜像**：release CI 现在会先在项目 GitHub Releases 中维护 Godot 镜像 tag，并以“镜像优先、上游回退”方式下载。
+- **LFS Policy Guard** (`npm run verify:lfs:policy`)：在迁移仍保留历史豁免项时，阻止新的 Git LFS 路径再次进入 `src/frontend/` 与 `src-tauri/bin/`。未来严格模式可通过 `npm run verify:lfs:policy:strict` 启用。
+- **Sidecar 供给就绪度** (`npm run verify:sidecar:supply`)：在继续缩减桌面 sidecar 的 LFS 桥接之前，显式报告当前主机是否已具备离线 bootstrap 能力，还是仍依赖网络。
 - **GPU 开发启动（推荐）** (`npm run tauri:dev:mini:gpu`)。
 - **不要使用** `npm run tauri:dev:mini --gpu`，该写法会被 npm 当作配置参数并触发告警。
 
@@ -1308,6 +1333,8 @@ max_doc_bytes = 100663296
 - 推荐查询入口：
   - 用户文档：`/diataxis/zh/tutorials/first-run/` 或 `/diataxis/en/tutorials/first-run/`
   - 开发文档：`/diataxis/en/reference/interfaces-and-runtime/` 与 `/diataxis/en/reference/release-and-governance/`
+  - 维护者评估 LFS / 桌面 bootstrap 风险：`/en/sidecar_supply_strategy/` 或 `/zh/sidecar_supply_strategy/`
+  - 维护者比较镜像成本 / 用户门槛 / 维护负担：`/diataxis/en/explanation/sidecar-supply-feasibility/` 或 `/diataxis/zh/explanation/sidecar-supply-feasibility/`
 - CI 自动发布工作流（GitHub Pages）：`.github/workflows/docs-github-pages-publish.yml`。
 - 手动回滚入口：运行 workflow_dispatch 并设置 `git_ref` 为稳定 tag/commit。
 - MkDocs base/path 可通过环境变量覆盖：`MKDOCS_SITE_URL`、`MKDOCS_BASE_PATH`。

docs/BILINGUAL_INDEX.md

@@ -1,17 +1,17 @@
-# 2026-03-25 v1.6.0 - Bilingual Docs Pair Index
+# 2026-04-07 v1.7.0 - Bilingual Docs Pair Index
 
 ## English Document
 
 ### Scope
 
 - Canonical pairing index for `docs/en` and `docs/zh`.
-- Built from current repository state after `v1.3.0..v1.6.0` doc compare audit.
+- Updated against the current repository state after the `v1.7.0` migration-plan doc sync.
 
 ### Summary
 
-- English files: `19`
-- Chinese files: `18`
-- Bilingual pairs: `18`
+- English files: `22`
+- Chinese files: `21`
+- Bilingual pairs: `21`
 - English-only files: `1`
 - Chinese-only files: `0`
 
@@ -37,6 +37,9 @@
 | 16 | `User_Manual.md` | `docs/en/User_Manual.md` | `docs/zh/User_Manual.md` | Paired |
 | 17 | `walkthrough.md` | `docs/en/walkthrough.md` | `docs/zh/walkthrough.md` | Paired |
 | 18 | `app_config.toml_guide.md` | `docs/en/app_config.toml_guide.md` | `docs/zh/app_config.toml_guide.md` | Paired |
+| 19 | `lfs_asset_migration_plan.md` | `docs/en/lfs_asset_migration_plan.md` | `docs/zh/lfs_asset_migration_plan.md` | Paired |
+| 20 | `multi_platform_build_flow_audit.md` | `docs/en/multi_platform_build_flow_audit.md` | `docs/zh/multi_platform_build_flow_audit.md` | Paired |
+| 21 | `sidecar_supply_strategy.md` | `docs/en/sidecar_supply_strategy.md` | `docs/zh/sidecar_supply_strategy.md` | Paired |
 
 ### Unmatched Files
 
@@ -52,13 +55,13 @@
 ### 范围
 
 - `docs/en` 与 `docs/zh` 的当前双语配对索引。
-- 基于 `v1.3.0..v1.6.0` 文档审计后的仓库现状生成。
+- 已根据 `v1.7.0` 迁移方案文档同步后的仓库现状更新。
 
 ### 汇总
 
-- 英文文件数：`19`
-- 中文文件数：`18`
-- 中英配对数：`18`
+- 英文文件数：`22`
+- 中文文件数：`21`
+- 中英配对数：`21`
 - 仅英文文件数：`1`
 - 仅中文文件数：`0`
 
@@ -84,6 +87,9 @@
 | 16 | `User_Manual.md` | `docs/en/User_Manual.md` | `docs/zh/User_Manual.md` | 已配对 |
 | 17 | `walkthrough.md` | `docs/en/walkthrough.md` | `docs/zh/walkthrough.md` | 已配对 |
 | 18 | `app_config.toml_guide.md` | `docs/en/app_config.toml_guide.md` | `docs/zh/app_config.toml_guide.md` | 已配对 |
+| 19 | `lfs_asset_migration_plan.md` | `docs/en/lfs_asset_migration_plan.md` | `docs/zh/lfs_asset_migration_plan.md` | 已配对 |
+| 20 | `multi_platform_build_flow_audit.md` | `docs/en/multi_platform_build_flow_audit.md` | `docs/zh/multi_platform_build_flow_audit.md` | 已配对 |
+| 21 | `sidecar_supply_strategy.md` | `docs/en/sidecar_supply_strategy.md` | `docs/zh/sidecar_supply_strategy.md` | 已配对 |
 
 ### 未配对文件