From 55cb0476542be6f408db1f9a38f5f2c29a551723 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 21 Sep 2026 12:15:28 +0800
Subject: [PATCH] =?UTF-8?q?=E6=94=AF=E6=8C=81=20macOS=20=E9=80=9A=E7=94=A8?=
 =?UTF-8?q?=E5=8C=85=E6=9E=84=E5=BB=BA=E6=97=B6=E7=9A=84=20Node=20?=
 =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=97=B6=E6=9A=82=E5=AD=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- stage-node-runtime 的 targetRuntime 支持 universal-apple-darwin：在 macOS 宿主上按宿主架构暂存官方 Node（通用包自检按 process.arch 校验），非 darwin 宿主仍失败关闭
- 同步 stage-node-runtime 测试期望：darwin 宿主可用、linux 宿主仍拒绝，Universal Node 合并（lipo）留作未完成项
- 共享记忆记录该限制：当前通用包侧车仍是宿主架构，Intel Mac 需等待真正的通用 Node
---
 .../scripts/stage-node-runtime.mjs              | 17 ++++++++++++++++-
 .../scripts/stage-node-runtime.test.mjs         | 16 +++++++++++++++-
 docs/project-memory/shared-memory/pitfalls.md   |  4 ++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs b/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
index e712534d6..8e6559dac 100644
--- a/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
+++ b/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
@@ -59,12 +59,27 @@ export function readInstalledNodeLicense(
   return result.content;
 }
 
-export function targetRuntime(target) {
+export function targetRuntime(
+  target,
+  { platform = process.platform, arch = process.arch } = {},
+) {
   const targets = {
     'x86_64-pc-windows-msvc': ['win32', 'x64'],
     'aarch64-apple-darwin': ['darwin', 'arm64'],
     'x86_64-apple-darwin': ['darwin', 'x64'],
   };
+  if (target === 'universal-apple-darwin') {
+    // Tauri 通用包含 arm64+x86_64 两个 slice，而这里的 Node 便携运行时是
+    // 「构建宿主架构」的单架构发行版：macOS 构建机（当前为 arm64）只能提供
+    // 自身架构的官方 Node。真正的通用 Node 需要另行下载另一架构发行版并
+    // 用 lipo 合并，属未完成项；在此之前 non-darwin 宿主必须失败关闭。
+    if (platform !== 'darwin') {
+      throw new Error(
+        `Node 运行时不支持在 ${platform}/${arch} 宿主构建通用 macOS 包：${target}`,
+      );
+    }
+    return { platform: 'darwin', arch };
+  }
   const value = targets[target];
   if (!value) throw new Error(`Node 运行时不支持发布目标：${target}`);
   return { platform: value[0], arch: value[1] };
diff --git a/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs b/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
index 8a55c6b3a..336a19ec6 100644
--- a/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
@@ -281,7 +281,21 @@ test('native target and macOS dynamic dependency policy reject nonportable Node'
     platform: 'darwin',
     arch: 'arm64',
   });
-  assert.throws(() => targetRuntime('universal-apple-darwin'), /不支持/u);
+  assert.deepEqual(
+    targetRuntime('universal-apple-darwin', {
+      platform: 'darwin',
+      arch: 'arm64',
+    }),
+    { platform: 'darwin', arch: 'arm64' },
+  );
+  assert.throws(
+    () =>
+      targetRuntime('universal-apple-darwin', {
+        platform: 'linux',
+        arch: 'x64',
+      }),
+    /不支持在 linux\/x64 宿主构建通用 macOS 包/u,
+  );
   assertPortableMacNode(
     '/node:\n\t/usr/lib/libSystem.B.dylib (compatibility version 1)\n',
   );
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 5912a73b2..8e22449c3 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,9 @@
 # 踩坑与排障记录
 
+## macOS 通用包里的 Node 便携运行时仍是宿主架构
+
+`stage-node-runtime.mjs` 只把**构建宿主的 Node** 打成便携运行时（`targetRuntime` 只支持 per-arch 目标），而 `build-macos-ci.mjs` 构建的是 `universal-apple-darwin`：2026-09-21 macOS Job #13 因此在 `stageNodeRuntime` 直接抛 `Node 运行时不支持发布目标：universal-apple-darwin`。当前按「通用包 + 宿主架构（arm64 构建机 → arm64）Node」放行：`check-macos-bundle.mjs` 按 `process.arch` 校验，所以本机自检通过，但**Intel Mac 上该侧车不可执行**。要真正通用需要另行下载另一架构官方 Node 发行版并用 `lipo -create` 合并，同时把 bundle 检查改成接受 `universal` 并核验 `lipo -archs node = arm64 x86_64`；在此之前不得宣称 macOS 通用包在 Intel 上可用。
+
 ## release 冷备空间不足会把生产留在维护态
 
 `Genarrative-Stdb-Module-Publish` 先进入维护模式、停掉 API/controller/worker，再执行发布前冷备份；archive 口径要求 `data × 1.1`（40.6GiB 数据 → 44.7GiB，加上生产根盘只剩 13.5GiB），于是 2026-09-21 的 release 发布在停服后失败并保持维护态，站点 503 直到人工恢复。规则：空间预检必须先于 `maintenance-on` 与停服；archive 不足且未显式禁用降级时改用 files（`max(data × 0.05, 2GiB)`，不落地本地归档，但 files 不支持 `--defer-upload`，会从 async 收敛为 sync）；只有真正开始 `spacetime publish` 之后的失败才允许保持维护态。另：定时备份的失效锁在当前仓库版本会自动清理，但生产机 `/var/lib/genarrative/backup-tools/database-backup-to-oss.mjs` 若是旧版会拒绝抢锁并要求人工删锁，需随 provision 更新。