feat: add self-contained offline development resources

docs/offline-development.zh-CN.md

@@ -0,0 +1,91 @@
+# 本机离线资源库
+
+本项目的统一资源库默认位于：
+
+```text
+/home/mes123456/resource-library/web-freecad-bitbybit
+```
+
+可通过 `WEB_FREECAD_RESOURCE_LIBRARY` 或各命令的 `--library=PATH` 改为其他位置。资源库不进入项目 Git；仓库保存资源定义，资源库自己的 `manifest.json` 保存每个归档和镜像的字节数、文件数、SHA-256、上游提交及工作树状态。
+
+## 资源范围
+
+`config/offline-resources.json` 固定以下资源：
+
+- Node 22.23.2 原始发行包、两个 `package-lock.json` 对应的最小 npm 内容缓存，以及当前项目 `node_modules` 快照；
+- FreeCAD 1.1.1（含 GSL、OndselSolver、AddonManager、测试子模块）、bitbybit、OCCT 8、OpenCAMLib、CAMotics/C! 和 LinuxCNC Web 工作树；
+- FreeCAD headless/desktop Oracle、FreeCAD sysroot、OCCT/PlaneGCS 原生 Worker 制品和可选增量构建目录；
+- Playwright Chromium/Firefox/WebKit、Boost/Eigen 头文件，以及本机 `/var/cache/apt/archives` 中的 Debian 安装包池。
+
+LinuxCNC 和 CAMotics 存在尚未合入各自上游提交的本地适配，因此保存完整工作树快照。`working_ocl/` 是上述源码的历史重复副本，不作为规范资源；构建入口实际使用的 `OpenCAMLib/`、`CAMotics/` 和 `.cache/bitbybit/bitbybit` 才进入资源库。
+
+OCCT 增量构建缓存固定恢复到 `.cache/bitbybit/occt-history-build-offline`，其 CMake 缓存引用项目内 `.cache/occt/occt`，不包含旧工作区的绝对源码路径。
+
+## 同步与校验
+
+```bash
+./npmw run offline:inventory
+./npmw run offline:sync
+./npmw run offline:check
+./npmw run offline:smoke
+```
+
+`offline:sync` 只读取现有本机资源，不从互联网下载。首次同步会压缩数 GB 的源码和构建缓存；后续在上游提交、本地适配、工具链或 lockfile 变化后重新执行。
+
+`offline:check` 逐项重新计算 SHA-256。`offline:smoke` 先在临时空目录用资源库 npm 缓存执行 `npm ci --offline`，再运行运行时/FreeCAD 源码/原生 Worker 检查和生产构建。npm 的 `--offline` 为强制模式，缺包时直接失败，不会访问 registry。资源库保持只读；离线 shell 按 manifest 哈希把 npm 内容初始化到项目 `.cache/offline-npm`，npm 的访问索引只写入这份工作缓存。
+
+## 从资源库恢复
+
+恢复操作必须显式限定资源，且默认拒绝覆盖现有目录：
+
+```bash
+./npmw run offline:restore -- --only=project-node-modules,freecad-source,occt-source
+```
+
+确认目标可替换后使用：
+
+```bash
+./npmw run offline:restore -- --only=project-node-modules --force
+```
+
+也可验证到独立临时工作目录：
+
+```bash
+target_dir="$(mktemp -d)"
+./npmw run offline:restore -- --target="$target_dir" --only=freecad-source
+```
+
+不要对工作区根目录使用递归删除；恢复工具会检查每个目标必须位于指定 `--target` 下。
+
+## 离线开发环境
+
+以下命令启动一个明确禁止 npm 网络回退的 shell：
+
+```bash
+./scripts/offline-shell.sh
+```
+
+也可以直接运行单条命令：
+
+```bash
+./scripts/offline-shell.sh ./npmw run dev
+./scripts/offline-shell.sh ./npmw run build
+./scripts/offline-shell.sh ./npmw run ci:real -- --lane=wasm
+```
+
+环境中会设置 `npm_config_offline=true`、`PLAYWRIGHT_BROWSERS_PATH`、`FIREFOX_BIN`、`WEBKIT_BIN`、`FREECAD_SOURCE_OFFLINE=1`、项目内 `OCCT_SOURCE_DIR` 和固定 Chrome 路径。Firefox/WebKit 使用 manifest 中实际归档的可执行 revision，不要求它恰好等于当前 Playwright 包的默认下载 revision。Node bootstrap 在项目 `.runtime/downloads` 缺少发行包时也会先查资源库；设置 `WEB_FREECAD_OFFLINE=1` 后若资源库仍缺包，会直接失败而不调用 `curl`。
+
+## 系统包恢复边界
+
+源码、npm、Node、浏览器缓存和项目制品可以直接恢复到普通用户目录。CMake、Ninja、Emscripten、Chrome、Firefox、Qt、V8 和 FreeCAD 原生依赖属于 Debian 系统包；资源库保留了本机 apt 包池，并生成标准 `Packages`/`Packages.gz` 索引。安装系统包仍需要管理员权限。例如先把两个本地目录登记成仅本机 apt 源：
+
+```bash
+printf '%s\n' \
+  'deb [trusted=yes] file:/home/mes123456/resource-library/web-freecad-bitbybit/system/debian13-amd64/packages ./' \
+  'deb [trusted=yes] file:/home/mes123456/resource-library/web-freecad-bitbybit/system/debian13-amd64/freecad-packages ./' \
+  | sudo tee /etc/apt/sources.list.d/web-freecad-offline.list
+sudo apt-get update -o Dir::Etc::sourcelist=/etc/apt/sources.list.d/web-freecad-offline.list -o Dir::Etc::sourceparts=-
+sudo apt-get --no-download install emscripten cmake ninja-build
+```
+
+这一步只在系统工具被卸载或重装主机时需要。日常断网开发直接使用当前已安装工具链。

docs/project-runtime.zh-CN.md

@@ -4,7 +4,7 @@
 
 本项目的 `package.json` 声明 Node.js `>=22`，而原开发环境实际使用系统 `/usr/bin/node v20.19.2` 与 `/usr/bin/npm 9.2.0`。npm 的 `EBADENGINE` 是运行 npm 的解释器版本不满足依赖声明所产生的警告；仅修改 `engines`、PATH 文档或 Vite 配置都不会改变当前解释器。
 
-项目现在锁定 Node.js `22.23.2` 与 npm `10.9.8`，并把官方归档下载到被 Git 忽略的 `.runtime/`。`./npmw`、`./nodew` 和 `scripts/bootstrap-node.sh` 是项目运行时的唯一启动路径，系统 Node 不会被替换或修改。
+项目现在锁定 Node.js `22.23.2` 与 npm `10.9.8`，并把官方归档恢复或下载到被 Git 忽略的 `.runtime/`。启动器优先读取本机统一资源库，在线模式仅在资源库缺失时访问官方发行目录。`./npmw`、`./nodew` 和 `scripts/bootstrap-node.sh` 是项目运行时的唯一启动路径，系统 Node 不会被替换或修改。
 
 版本与校验值来源：
 
@@ -51,7 +51,7 @@
 ./npmw --version
 ```
 
-期望输出分别为 `v22.23.2` 和 `10.9.8`。第一次运行会下载约 30 MB 的 Node Linux x64 归档，后续运行复用校验通过的缓存。
+期望输出分别为 `v22.23.2` 和 `10.9.8`。第一次运行会优先从 `~/resource-library/web-freecad-bitbybit` 恢复约 30 MB 的 Node Linux x64 归档；在线且资源库缺失时才下载，后续运行复用校验通过的缓存。
 
 ## 4. 启动器的安全行为
 
@@ -73,7 +73,7 @@
 
 **仍出现 `EBADENGINE`**：检查命令是否以 `./npmw` 开头；检查 `./nodew --version`。直接执行系统 `npm` 在 `.npmrc` 的 `engine-strict=true` 下应失败，这是故意的防误用信号。
 
-**下载失败**：确认能访问 `https://nodejs.org`，删除确定的 `.runtime/downloads/node-v22.23.2-*` 缓存后重新执行 `./npmw install`。不要手工替换归档或跳过校验。
+**归档不可用**：先执行 `./npmw run offline:check` 检查统一资源库。在线模式可确认能访问 `https://nodejs.org`，删除确定的 `.runtime/downloads/node-v22.23.2-*` 缓存后重新执行 `./npmw install`。不要手工替换归档或跳过校验。
 
 **架构不支持**：在当前开发机使用 Linux x64；新增平台时必须先把官方归档和 SHA-256 加入 `config/node-runtime.env`，并增加对应 CI job。