reverse-skills-max: initial public release (restored, redacted, hardened)

vendor-new/xbsReverseSkill/web-js-env-patcher/references/node-version-recovery.md

@@ -0,0 +1,128 @@
+# Node 版本兼容恢复、nvm 检测与用户确认流程
+
+当 `addon.node`、随包魔改 `xbs isolated-vm` 或其他 native 产物因为 Node ABI 不兼容无法加载时读取本文件。原则是先让用户确认是否安装 / 切换兼容 Node，再决定是否降级；不得在用户未同意前直接改全局 Node 环境。
+
+## 兼容版本表
+
+| native 组件 | 兼容 Node.js 版本 | 失败后的默认处理 |
+|---|---:|---|
+| `assets/native-addon/<platform>-<arch>/addon.node` | `v25.8.2` | 先询问是否通过 nvm 安装 / 切换到 `v25.8.2`，用户拒绝后才允许 NativeProtect / JS fallback |
+| `assets/runtime-frameworks/xbs-isolated-vm/<platform>-<arch>/isolated_vm.node` | `v26.3.1` | 先询问是否通过 nvm 安装 / 切换到 `v26.3.1`，用户拒绝后才允许改选框架或提供匹配构建产物；不得退回 npm 原版 isolated-vm |
+
+## 触发条件
+
+遇到以下任一情况时启动本流程：
+
+- Node 报错包含 `NODE_MODULE_VERSION`、`was compiled against a different Node.js version`、`Module did not self-register`、`The module was compiled against`。
+- `scripts/load_native_addon.js --json` 输出 `abiMismatch: true`。
+- `scripts/check_xbs_isolated_vm.js --json` 输出 `status: "abi-mismatch"` 或 `abiMismatch: true`。
+- 当前 Node 版本不是对应兼容版本，且 native 组件加载失败。
+
+## 先检测当前 Node 与 nvm
+
+```bash
+node scripts/check_node_runtime_compat.js --target addon --markdown
+node scripts/check_node_runtime_compat.js --target isolated-vm --markdown
+```
+
+也可以手动检测：
+
+```bash
+node -v
+node -p "process.versions.modules"
+```
+
+Windows：
+
+```powershell
+where.exe nvm
+nvm version
+nvm root
+```
+
+macOS / Linux：
+
+```bash
+bash -lc 'command -v nvm || true; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && nvm --version || true'
+```
+
+## 用户确认模板
+
+### addon ABI 不兼容
+
+```markdown
+当前 addon.node 与当前 Node ABI 不兼容。addon-first 是补环境硬性基线，因此不应直接降级到 NativeProtect。
+
+兼容 Node.js 版本：v25.8.2。
+
+请选择：
+1. 自动检测 / 安装 nvm，并安装切换 Node.js v25.8.2 后重新加载 addon。
+2. 我手动安装 nvm；安装完成后回复“nvm 已安装成功”。
+3. 我已经安装 nvm，但当前未检测到；我提供 nvm 路径或可用 shell。
+4. 不安装兼容 Node，允许本 case 降级到 NativeProtect / JS fallback，并记录差异。
+
+在你确认前，我不会直接降级，也不会修改全局 Node 版本。
+```
+
+### isolated-vm ABI 不兼容
+
+```markdown
+当前随包魔改 xbs isolated-vm 与当前 Node ABI 不兼容。你已选择 isolated-vm 补环境框架，因此应先尝试兼容 Node，而不是退回 npm 原版 isolated-vm。
+
+兼容 Node.js 版本：v26.3.1。
+
+请选择：
+1. 自动检测 / 安装 nvm，并安装切换 Node.js v26.3.1 后重新运行 xbs isolated-vm 自检。
+2. 我手动安装 nvm；安装完成后回复“nvm 已安装成功”。
+3. 我已经安装 nvm，但当前未检测到；我提供 nvm 路径或可用 shell。
+4. 不安装兼容 Node，改为提供当前 Node ABI 匹配的魔改 isolated_vm.node 构建产物，或改选不使用框架 / vm / jsEnv。
+
+在你确认前，我不会改用 npm 原版 isolated-vm，也不会桥接旧 addon.node。
+```
+
+## nvm 安装与切换
+
+只有用户明确选择自动安装时，才输出安装计划并执行。用户选择手动安装时，只给教程并等待用户确认成功。
+
+Windows 推荐 nvm-windows：
+
+```powershell
+winget install CoreyButler.NVMforWindows
+# 或让用户从 nvm-windows 官方 Release 手动安装
+nvm version
+```
+
+macOS / Linux 常用 nvm-sh：
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+bash -lc 'source "$HOME/.nvm/nvm.sh" && nvm --version'
+```
+
+安装 / 检测 nvm 成功后按目标组件切换：
+
+```bash
+# addon.node
+nvm install 25.8.2
+nvm use 25.8.2
+node -v
+node -p "process.versions.modules"
+node scripts/load_native_addon.js --json
+
+# xbs isolated-vm
+nvm install 26.3.1
+nvm use 26.3.1
+node -v
+node -p "process.versions.modules"
+node --no-node-snapshot scripts/check_xbs_isolated_vm.js --strict --json
+```
+
+## 记录要求
+
+无论最终是否切换成功，都写入阶段报告、`case/notes/代码变更记忆.md` 和最终总结：
+
+- 触发组件：addon.node / xbs isolated-vm。
+- 原 Node 版本、原 ABI、平台、架构。
+- 用户选择：自动安装、手动安装、提供 nvm 路径、拒绝安装、提供匹配二进制或改选框架。
+- 新 Node 版本、新 ABI 和重新检测结果。
+- 如果降级，写明 fallback 范围、已知差异和用户确认记录。