From 91f1554ac7b40e5d1e89b3fa7d1e3a2b348534e2 Mon Sep 17 00:00:00 2001
From: suzmii <suzmii@qq.com>
Date: Mon, 21 Sep 2026 11:58:22 +0800
Subject: [PATCH] =?UTF-8?q?macOS=20universal=20=E7=AE=A1=E7=BA=BF=E6=8E=A5?=
 =?UTF-8?q?=E5=85=A5=E5=8F=8C=E6=9E=B6=E6=9E=84=20Node=20=E8=BF=90?=
 =?UTF-8?q?=E8=A1=8C=E6=97=B6=E5=89=8D=E7=BD=AE=20-=20Jenkinsfile.ai-game-?=
 =?UTF-8?q?creator-shell-macos-build=20=E5=A2=9E=E5=8A=A0=20AGC=5FNODE=5FR?=
 =?UTF-8?q?UNTIME=5FDARWIN=5FX64=5FHOME=EF=BC=8C=E5=B9=B6=E5=9C=A8=20Toolc?=
 =?UTF-8?q?hain=20=E9=98=B6=E6=AE=B5=E7=BC=96=E8=AF=91=E5=89=8D=E6=A0=B8?=
 =?UTF-8?q?=E5=AF=B9=20x86=5F64=20=E5=8F=91=E8=A1=8C=E7=89=88=E5=AD=98?=
 =?UTF-8?q?=E5=9C=A8=E4=B8=94=E4=B8=8E=E6=9E=84=E5=BB=BA=20Node=20?=
 =?UTF-8?q?=E5=90=8C=E7=89=88=E6=9C=AC=20-=20Package=20=E9=98=B6=E6=AE=B5?=
 =?UTF-8?q?=E5=AF=BC=E5=87=BA=20AGC=5FNODE=5FRUNTIME=5FDARWIN=5FX64=5FPATH?=
 =?UTF-8?q?=20/=20=5FLICENSE=5FPATH=EF=BC=8C=E4=BE=9B=20universal=20stagin?=
 =?UTF-8?q?g=20=E5=8F=96=E5=8F=A6=E4=B8=80=E6=9E=B6=E6=9E=84=E6=9D=A5?=
 =?UTF-8?q?=E6=BA=90=20-=20=E5=BC=80=E5=8F=91=E8=BF=90=E7=BB=B4=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E8=AE=B0=E5=BD=95=E8=8A=82=E7=82=B9=E5=89=8D=E7=BD=AE?=
 =?UTF-8?q?=EF=BC=9A=E5=AE=98=E6=96=B9=20darwin-x64=20=E5=8F=91=E8=A1=8C?=
 =?UTF-8?q?=E7=89=88=E5=AE=89=E8=A3=85=E4=B8=8E=E6=A0=A1=E9=AA=8C=E5=91=BD?=
 =?UTF-8?q?=E4=BB=A4=E3=80=81=E5=90=8C=E7=89=88=E6=9C=AC=E8=A6=81=E6=B1=82?=
 =?UTF-8?q?=E3=80=81=E6=8C=89=E6=9E=B6=E6=9E=84=E5=B9=B6=E5=88=97=E7=9A=84?=
 =?UTF-8?q?=E8=B5=84=E6=BA=90=E5=B8=83=E5=B1=80=E3=80=81Rust=20=E4=BE=A7?=
 =?UTF-8?q?=E6=8C=89=E8=BF=90=E8=A1=8C=E6=9E=B6=E6=9E=84=E9=80=89=E6=8B=A9?=
 =?UTF-8?q?=E3=80=81=E7=BA=A6=20260=20MB=20=E8=A7=A3=E5=8C=85=E4=BD=93?=
 =?UTF-8?q?=E7=A7=AF=E4=BB=A3=E4=BB=B7=EF=BC=8C=E4=BB=A5=E5=8F=8A=E6=9C=AC?=
 =?UTF-8?q?=E6=9C=BA=E8=B7=A8=E6=9E=B6=E6=9E=84=E8=AF=8A=E6=96=AD=E6=9E=84?=
 =?UTF-8?q?=E5=BB=BA=E7=9A=84=E5=8F=96=E5=80=BC=E6=96=B9=E5=BC=8F=20-=20?=
 =?UTF-8?q?=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=E4=B8=8E=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=E6=A3=80=E6=9F=A5=E6=96=B9=E6=A1=88=E6=96=87=E6=A1=A3=E5=90=8C?=
 =?UTF-8?q?=E6=AD=A5=20universal=20=E6=90=BA=E5=B8=A6=E4=B8=A4=E5=A5=97?=
 =?UTF-8?q?=E6=9E=B6=E6=9E=84=E8=BF=90=E8=A1=8C=E6=97=B6=E7=9A=84=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...œ¯æ–¹æ¡ˆã€‘AGC客户端更新检查与下载-2026-08-31.md |  2 +-
 ...¹æ¡ˆã€‘AI游æˆ�创作智能体App实施计划-2026-06-24.md |  2 +-
 ...��维】本地开�验�与生产�维-2026-05-15.md | 17 +++++++++++
 ...kinsfile.ai-game-creator-shell-macos-build | 28 +++++++++++++++++++
 4 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/docs/technical/�技术方案】AGC客户端更新检查与下载-2026-08-31.md b/docs/technical/�技术方案】AGC客户端更新检查与下载-2026-08-31.md
index 8fa50c4f1..f07d93a6e 100644
--- a/docs/technical/�技术方案】AGC客户端更新检查与下载-2026-08-31.md
+++ b/docs/technical/�技术方案】AGC客户端更新检查与下载-2026-08-31.md
@@ -102,7 +102,7 @@
 
 - 对象布局：清�固定写� `agc/<channel>-win|mac/latest.json`；安装包与签�写��一分区的 `<version>/<file>` 与 `<file>.sig`。
 - macOS 正�交付使用 universal 主程�：两个平�键指��一个 `.app.tar.gz` 与签�，一份产物�时�务 Apple Silicon 与 Intel。�架构目标（`aarch64-apple-darwin` / `x86_64-apple-darwin`）�用于本机诊断，�登记正�分区清�——�架构构建��轮�覆盖�一个 `latest.json` 并宣称�架构��更新。
-- universal 主程��时�带分目录的 arm64/x64 原生 Codex 组件：�个组件��上游�架构布局与独立 SHA-256 清�，�行中的主程�切片�选择�架构目录，�得把两套原生包的元数�或辅助程�混装。
+- universal 主程��时�带分目录的 arm64/x64 原生 Codex 组件：�个组件��上游�架构布局与独立 SHA-256 清�，�行中的主程�切片�选择�架构目录，�得把两套原生包的元数�或辅助程�混装。�包 Node �行时�样按架构分目录（`game-runtime/node/darwin-arm64/`�`darwin-x64/`，�带 `agc-node-runtime.v1` 清�）：两套都�自节点上�版本的官方�行版，构建时缺一份或版本�一致�在写出资��失败，�行切片�采用与当�架构匹�的那一份，�架构构建���平目录��。
 - 构建期�求：打开 `bundle.createUpdaterArtifacts` 以生� `.sig`；构建环境�供签��钥与密�（�钥内容�得入库）；公钥写入客户端�置。公钥在首个带更新能力的版本�布���更�，更�等于放弃自动更新（�能手动�装）。
 - 版本递增按渠��系统分区独立进行：�布脚本读�该分区远端 `latest.json` 的 `version`，与本地版本�较高者递增 patch；��分区的远端版本互�影�。
 - 版本高水�：仅 dev 的 Windows 分区在�移窗�内�「分区清�版本�与「旧�议�移指针版本�较大值�递增，��已�布旧客户端版本倒退。�移窗�结�（旧指针 404）��读分区清�；release�自定义渠�与所有 Mac 分区���与旧指针比较。
diff --git a/docs/technical/�技术方案】AI游�创作智能体App实施计划-2026-06-24.md b/docs/technical/�技术方案】AI游�创作智能体App实施计划-2026-06-24.md
index 0657da9a2..bb044b152 100644
--- a/docs/technical/�技术方案】AI游�创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/�技术方案】AI游�创作智能体App实施计划-2026-06-24.md
@@ -71,7 +71,7 @@
 
 ### 环境与工作�
 
-- 客户端交付�套 Node/npm；�布包从本机已安装且与目标平�/架构一致的工具链制作�校验资�，�留许�并校验内容摘�。安装���赖系统 PATH 的 Node；开���使用已验�的宿主�行时。�得从项目或相对 PATH 加载伪造�行时。
+- 客户端交付�套 Node/npm；�布包从本机已安装且与目标平�/架构一致的工具链制作�校验资�，�留许�并校验内容摘�。安装���赖系统 PATH 的 Node；开���使用已验�的宿主�行时。�得从项目或相对 PATH 加载伪造�行时。universal 包�带**两套**架构�行时并按架构并列存放（`game-runtime/node/<platform>-<arch>/`，�自一份清�），�行切片�采用与当�架构一致的那一份；两套必须�自�一 Node 版本，缺一份或版本�一致时构建在写出任何资�之�失败，�能用「少带一份�或退回系统 Node 充数。
 - 新建 Web 游�在生图和大�实现�执行客户端环境预检，检查 Node/npm 的实际版本��览器�动和 CDP �用性。报告�包�安全状��版本�耗时和错误�。缺失或异常必须尽早返回阻塞，�能指示模型改宿主环境�全盘�索或自行下载一套�行时。编辑器工程�强制 Web 工具链。
 - 预检�安装�赖��修改项目 revision��请求平�生�；构建�执行项目自己的 npm 脚本。Codex 隔离 HOME 与平�凭�边界����，客户端把已验�的�行时加入执行 PATH，�能把宿主凭�目录交给模型。
 - 第一轮先明确本次必需玩法�素�和验收项。�批独立读�尽��并，必需图片一次规划；已有且�用的资产�用。已有目标全部通过�给出交付结果，�阻塞的新点�列为�续工作，�在收尾时主动开�新的生产链。
diff --git a/docs/�开��维】本地开�验�与生产�维-2026-05-15.md b/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
index 0596085fc..f72e3be9c 100644
--- a/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
+++ b/docs/�开��维】本地开�验�与生产�维-2026-05-15.md
@@ -736,6 +736,23 @@ Job �为 `Genarrative-Agc-MacOS-Build`，SCM 直接读�仓库内上述 Jenki
 
 �布凭�全部走 Jenkins 全局凭�，并在 `withCredentials` 内注入当�进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；�钥与凭��写入 workspace�日志或归档产物。上传顺�为更新包�签��首装包，三者全部�功��覆盖 `agc/<channel>-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 与 Windows 渠�对称：默认关闭�真�布，勾选��退化为演练（�打�将上传的对象��写任何 OSS 对象）。本 Job 是正��布入�，调度器在���与 Windows 一起触�它，并�外传 `SKIP_IF_SUPERSEDED=true`——Mac 节点是日常办公机，离线期间排队的旧构建在节点回��若已被��分支推进，直接跳过而��布过期版本。Mac 节点需� `ossutil`（实测 1.7.19 原生 arm64 �用，装在 `~/.local/bin`，已在 Job 的 PATH 内），�用 `OSSUTIL_BIN` 指定命令�或�对路径。首次�布建议显�指定 `AGC_RELEASE_VERSION`，��按渠�高水�递增时出现版本链回退。
 
+�包 Node �行时也是节点�置，且 universal 需�**两套架构�一份**：客户端�布包内嵌 Node + npm 作为�校验资�（`agc-node-runtime.v1` 清� + �文件 SHA-256），构建时�从**本机已安装�且与目标平�/架构一致**的工具链��，缺文件�版本�符或目标�匹�立�失败，�止回退系统 Node�也��许从项目或相对 PATH 里借用�行时。宿主架构那一份直接�构建 Node（Mac 节点为 arm64，� PATH 上的 `node`）；�一架构必须由节点显��供：预装官方 darwin-x64 �行版到 `~/Library/Jenkins/node/darwin-x64`（�置�用 `AGC_NODE_RUNTIME_DARWIN_X64_HOME` 覆盖），�留 `LICENSE` 与 `lib/node_modules/npm`，Job 会把它们导出为 `AGC_NODE_RUNTIME_DARWIN_X64_PATH` / `AGC_NODE_RUNTIME_DARWIN_X64_LICENSE_PATH`。两套必须**�版本**（首次接入时�为 `v22.23.2`）：缺一份�架构�符或版本�一致，staging 都会在写出任何�行时目录之�失败关闭，�会生��套资�的更新包；版本核对�时是 Job 的编译�预检。预装与核对命令（官方 dist，校验 `SHASUMS256.txt`，�确认架构与版本）：
+
+```sh
+version=22.23.2
+curl -fsSLO "https://nodejs.org/dist/v${version}/node-v${version}-darwin-x64.tar.gz"
+curl -fsSLO "https://nodejs.org/dist/v${version}/SHASUMS256.txt"
+grep " node-v${version}-darwin-x64.tar.gz\$" SHASUMS256.txt | shasum -a 256 -c -
+mkdir -p "$HOME/Library/Jenkins/node/darwin-x64"
+tar -xzf "node-v${version}-darwin-x64.tar.gz" -C "$HOME/Library/Jenkins/node/darwin-x64" --strip-components=1
+/usr/bin/lipo -archs "$HOME/Library/Jenkins/node/darwin-x64/bin/node"          # 期望 x86_64
+/usr/bin/arch -x86_64 "$HOME/Library/Jenkins/node/darwin-x64/bin/node" --version  # 期望与构建 Node 相�
+```
+
+universal 包的�包 Node 按架构并列存放：`Contents/Resources/game-runtime/node/darwin-arm64/` 与 `darwin-x64/`，�自带独立 `manifest.json`；Rust 侧按当��行架构选择对应目录（两个候选都�过清�的平�/架构校验，存在但��则失败关闭，��退回系统 Node），架构校验脚本对两份都�完整性核对与 `lipo -archs` 架构核对，�执行与本次 smoke 架构一致的那一份，�一份由�一次架构的 smoke 覆盖。�架构目标�写�平目录 `game-runtime/node/`，行为��。体积代价：官方 Node + npm 解包�约 130 MB/份（实测 arm64 `node` 112.9 MB + npm 16.3 MB，x64 `node` 115.4 MB + npm 15.6 MB），universal 两份�计约 260 MB，DMG 压缩�增�预计在 50 MB �级——这是�架构必须付的代价，�通过「Mac 跳过�包 Node���。
+
+�一�规则适用于本机跨架构诊断构建：宿主架构以外的目标（例如 Apple Silicon 上打 `x86_64-apple-darwin`）必须用 `AGC_NODE_RUNTIME_<PLATFORM>_<ARCH>_PATH` 指定��，缺失时报「缺少 <platform>/<arch> 的 Node �行时�并给出该���，��退化��义模糊的「平�/架构�一致�。
+
 产物边界：macOS 代�签�与公�暂缺，构建通过剥离 `APPLE_*` 凭�让 Tauri 跳过 Apple 签�，**�得使用 `--no-sign`**——该标志会连带跳过 updater 的 minisign 签�，产物缺少 `.sig` 会直接�在验签门�（首次实跑�命中该�）。构建清�按 `codesign -dv` 实测记录 `appleSigned` / `appleSignatureKind`（如 `adhoc`），并固定记录 `notarized=false`。用户首次安装需�在 Gatekeeper 中手动放行；更新包校验本身��赖 minisign 签�，因此未签��阻断自动更新的校验环节，但「安装 → ��接管新版本�的实机闭环�未验�，�得以构建�功替代。
 
 Job �述与节点�述是 Jenkins 侧元数�，**��仓库�步**：Jenkinsfile �回写�数定义，�述必须手工维护，�则会�留在建 Job 时的�径（2026-09-20 就出现过�述还写�「�构建归档��签��上传�，而实际已�是�签��分区清��验签与 OSS 上传的�布管线）。当��径：Job �述说明「构建 universal → �架构 smoke → DMG → `<channel>-mac` 分区清� → 更新包验签 → 按 dry-run 决定上传，未� Apple 签�与公��；节点�述说明「`genarrative-agc-macos`�EXCLUSIVE � executor�仅手动触��独立 workspace�sccache 在 HOME�。维护手法：该 Job 上 `POST job/<name>/config.xml` 会返回 500，节点侧�接�正常；因此改 Job �述用脚本接�原地更新（�留构建历�），��为了改�述删 Job �建。
diff --git a/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build b/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
index 91bcfdc97..511c0bd42 100644
--- a/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
+++ b/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
@@ -34,6 +34,10 @@ pipeline {
     CARGO_INCREMENTAL = '0'
     // �把节点用户�写进仓库：PATH 在下�的 shell 步骤里按 $HOME 展开。
     AGC_EXTRA_PATH = '/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin'
+    // universal 需�两份**�版本**的架构�行时：宿主（arm64）�自 PATH 里的构建 Node，
+    // x86_64 由节点预装的官方�行版�供。�写相对 HOME 的目录，�对路径在 shell 步骤里拼。
+    // 节点没有它时构建��失败，���默跳过或让更新包缺一份�行时。
+    AGC_NODE_RUNTIME_DARWIN_X64_HOME = 'Library/Jenkins/node/darwin-x64'
   }
   stages {
     stage('Checkout') {
@@ -116,6 +120,24 @@ pipeline {
           arch -x86_64 /usr/bin/uname -m
           if command -v sccache >/dev/null 2>&1; then sccache --version; else echo '[agc-macos] 未找到 sccache；本次回退到 rustc 直接构建。'; fi
           rustup target add aarch64-apple-darwin x86_64-apple-darwin
+          # �包 Node 的两套架构�行时：宿主那一份就是 PATH 里的构建 Node，
+          # x86_64 那一份必须是节点上预装的官方�行版（� LICENSE 与 lib/node_modules/npm）。
+          # 两份版本必须一致，�则 staging 会在写出任何资��失败关闭；这里��到编译�暴露。
+          x64_root="${AGC_NODE_RUNTIME_DARWIN_X64_HOME:-Library/Jenkins/node/darwin-x64}"
+          case "$x64_root" in /*) ;; *) x64_root="${HOME:?HOME �能为空}/$x64_root" ;; esac
+          if [ ! -x "${x64_root}/bin/node" ]; then
+            echo "[agc-macos] 缺少 x86_64 Node �行时：${x64_root}/bin/node"
+            echo '[agc-macos] 安装官方 darwin-x64 �行版到该目录（�留 LICENSE 与 lib/node_modules/npm）��试；也�以覆盖 AGC_NODE_RUNTIME_DARWIN_X64_HOME'
+            exit 1
+          fi
+          host_node_version="$(node --version)"
+          x64_node_version="$(/usr/bin/arch -x86_64 "${x64_root}/bin/node" --version)"
+          if [ "$host_node_version" != "$x64_node_version" ]; then
+            echo "[agc-macos] 两套 Node �行时版本�一致：arm64=${host_node_version} x86_64=${x64_node_version}"
+            echo '[agc-macos] universal 更新包�接��版本的两套�行时，请把节点上的 x86_64 �行版�到与构建 Node 相�版本'
+            exit 1
+          fi
+          echo "[agc-macos] �包 Node �行时：arm64=${host_node_version} x86_64=${x64_node_version}（�� ${x64_root}）"
           npm ci --no-audit --no-fund
           node apps/ai-game-creator-shell/scripts/prepare-macos-codex.mjs
         '''
@@ -143,6 +165,12 @@ pipeline {
             sh '''
             set -eu
             export PATH="$HOME/.local/bin:$HOME/.cargo/bin:${AGC_EXTRA_PATH}"
+            # universal staging 需��一架构的 Node ��；路径与 Toolchain 阶段�一�径，
+            # 缺失/版本�一致由 staging 在任何�盘��次失败关闭。
+            x64_root="${AGC_NODE_RUNTIME_DARWIN_X64_HOME:-Library/Jenkins/node/darwin-x64}"
+            case "$x64_root" in /*) ;; *) x64_root="${HOME:?HOME �能为空}/$x64_root" ;; esac
+            export AGC_NODE_RUNTIME_DARWIN_X64_PATH="${x64_root}/bin/node"
+            export AGC_NODE_RUNTIME_DARWIN_X64_LICENSE_PATH="${x64_root}/LICENSE"
             echo "[agc-macos] 渠�=${AGC_UPDATE_CHANNEL} 分区=${AGC_UPDATE_CHANNEL}-mac 目标=universal-apple-darwin dry-run=${AGC_RELEASE_DRY_RUN}"
               ossutil_bin="${OSSUTIL_BIN:-ossutil}"
               if command -v "${ossutil_bin}" >/dev/null 2>&1; then