另一架构切片不得借用宿主 npm

- runtimeSourceForTarget 对非宿主架构返回 npmCli: null，明令按该发行版自己的安装目录查找 npm
- 覆盖经 npm run 触发（npm_execpath 指向宿主 npm）时两份切片仍各带自己那份 npm 的用例

.encoding-check-ignore

@@ -4,3 +4,5 @@
 src/components/AdventurePanel.tsx
 src/data/customWorldCharacterLoadout.ts
 dist_check_monster_position/**
+# 固定上游UTF-8测试刻意包含U+FFFD；upstream-integrity.test.mjs逐字节验证来源hash。
+apps/ai-game-creator-shell/src-tauri/vendor/codex-utils-path-uri/src/api_path_string_tests.rs

.env.example

@@ -235,6 +235,10 @@ VITE_DEBUG_MODE=""
 # This is read by api-server and exposed through /api/runtime/frontend-config.
 GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 
+# 官网客户端下载检测渠道：dev、release 或自定义渠道；修改后重启 API 服务。
+# Windows/macOS 是系统维度，不填写 dev-win/dev-mac。
+GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL="dev"
+
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.

.gitea/workflows/project-ci.yml

@@ -31,28 +31,26 @@ env:
   RUSTC_WRAPPER: ''
   CARGO_BUILD_RUSTC_WRAPPER: ''
 
-# job 声明顺序就是 runner 领取顺序，因此把最长尾的客户端 Rust 门禁排在前面，
+# job 声明顺序就是 runner 领取顺序，因此把两条最长尾的客户端 Rust lane 排在前面，
 # 让它在最少的等待下占用并发槽位；其余 job 按时长递减排列。
 #
 # 客户端（微信壳 / Expo 移动壳 / Tauri 桌面壳 / AI 游戏创作壳）门禁原先全部串在
 # `Native shell tests` 一个 job 里，实测 18 分 37 秒。现在按门禁组拆成一个分组一个 job：
 # `Native shell tests`（契约 + H5 / 微信 / 移动 / 桌面壳门禁 + 发布构建 smoke）、
 # `AI game creator shell web tests`（typecheck + 壳内测试）、`AI game creator shell
-# Rust shard 1/4` 到 `4/4`（AGC 壳 bin 单测按名单分 4 片）、`AI game creator shell
-# Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的
+# Rust lane 1/2`、`lane 2/2`（每条 lane 顺序运行两片 AGC 壳 bin 单测）、`AI game creator
+# shell Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的
 # 共享 / 平台 crate 测试）。各自的命令与拆分前逐一对应，本地
 # `npm run check:native-shells` 仍是同一条串行序列。
 #
-# AGC 壳的 bin 单测（2466 条）按名单分 4 片、一片一个 job：片内保持 `--test-threads=1`
-# （当年线程并行会互相干扰的是进程内后台锁与异步终态），片与片之间靠 job 级并发摊开。
-# 不要改回「一个 job 里多进程并行这几片」：同一容器内它们会争抢共享 HOME、target 与固定
-# 临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」。
+# AGC 壳的 bin 单测（2466 条）仍按名单分 4 片、片内保持 `--test-threads=1`；两条 lane
+# 各自顺序运行两片，让一次 job 只做一次依赖预热，同时避免同一容器内多进程并行争抢
+# 共享 HOME、target 与固定临时路径。每个分片调用仍会自校验「片并集等于全集且互斥」。
 jobs:
-  # AGC 壳自身的 Rust bin 单测分片，4 片各自独立 job 并发执行、片内仍保持
-  # `--test-threads=1`。这里不装 npm 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，
-  # 也只需要 AGC 壳自己那份锁定依赖。
-  ai-game-creator-shell-rust-shard-1:
-    name: AI game creator shell Rust shard 1/4
+  # AGC 壳自身的 Rust bin 单测由两条 lane 承载，每条 lane 顺序运行两片；这里不装 npm
+  # 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，也只需要 AGC 壳自己那份锁定依赖。
+  ai-game-creator-shell-rust-lane-1:
+    name: AI game creator shell Rust lane 1/2
     runs-on: genarrative-ci
     steps:
       - name: Checkout full history from Gitea
@@ -87,41 +85,11 @@ jobs:
       - name: Run AI game creator shell Rust shard 1/4
         run: npm run check:native-shells:agc-rust-shard-1
 
-  ai-game-creator-shell-rust-shard-2:
-    name: AI game creator shell Rust shard 2/4
-    runs-on: genarrative-ci
-    steps:
-      - name: Checkout full history from Gitea
-        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
-          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
-        run: genarrative-gitea-checkout
-
-      - name: Validate preinstalled CI job image and sandbox
-        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
-
-      - name: Prepare AI game creator shell Rust dependencies
-        shell: bash
-        run: |
-          set -euo pipefail
-          for attempt in $(seq 1 5); do
-            if cargo fetch --locked \
-              --target x86_64-unknown-linux-gnu \
-              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
-              break
-            fi
-            if [[ "${attempt}" -eq 5 ]]; then
-              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
-              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
-
       - name: Run AI game creator shell Rust shard 2/4
         run: npm run check:native-shells:agc-rust-shard-2
 
-  ai-game-creator-shell-rust-shard-3:
-    name: AI game creator shell Rust shard 3/4
+  ai-game-creator-shell-rust-lane-2:
+    name: AI game creator shell Rust lane 2/2
     runs-on: genarrative-ci
     steps:
       - name: Checkout full history from Gitea
@@ -153,36 +121,6 @@ jobs:
       - name: Run AI game creator shell Rust shard 3/4
         run: npm run check:native-shells:agc-rust-shard-3
 
-  ai-game-creator-shell-rust-shard-4:
-    name: AI game creator shell Rust shard 4/4
-    runs-on: genarrative-ci
-    steps:
-      - name: Checkout full history from Gitea
-        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
-          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
-        run: genarrative-gitea-checkout
-
-      - name: Validate preinstalled CI job image and sandbox
-        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
-
-      - name: Prepare AI game creator shell Rust dependencies
-        shell: bash
-        run: |
-          set -euo pipefail
-          for attempt in $(seq 1 5); do
-            if cargo fetch --locked \
-              --target x86_64-unknown-linux-gnu \
-              --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
-              break
-            fi
-            if [[ "${attempt}" -eq 5 ]]; then
-              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
-              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
-
       - name: Run AI game creator shell Rust shard 4/4
         run: npm run check:native-shells:agc-rust-shard-4
 

.gitignore

@@ -47,12 +47,16 @@ temp*build*/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-package.json
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/manifest.json
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/NOTICE.md
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/darwin-arm64/
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/darwin-x64/
 /plugins/agc-cocos-editor/native/payload/
 /plugins/agc-unity-editor/dotnet/**/bin/
 /plugins/agc-unity-editor/dotnet/**/obj/
 /plugins/agc-unity-editor/dotnet/publish/
 /plugins/agc-unity-editor/dotnet/native-build/
 /apps/ai-game-creator-shell/logs/
+/apps/ai-game-creator-shell/src-tauri/resources/node-runtime/
+/apps/ai-game-creator-shell/src-tauri/resources/node-runtime-staging-*/
 /apps/ai-game-creator-shell/.llm-drafts/
 /apps/ai-game-creator-shell/game-creator.config.local.json
 /apps/mobile-shell/.expo/

AGENTS.md

@@ -4,12 +4,13 @@
 
 - 本文件只保留 Agent 进入仓库后必须立即遵守的最高优先级规则；完整执行细则见 [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。
 - 团队级长期项目记忆位于 [`docs/project-memory/`](docs/project-memory/)，供 3 名开发人员和各自本地 Agent 通过 Git 同步。
-- [`.codex/`](.codex/) 只保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识不要写入 `.codex/`。
+- [`.codex/`](.codex/) 保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识写入 `docs/` 与 `docs/project-memory/`。
 - 若 `docs/project-memory/shared-memory/` 与当前代码或最新 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正过期共享记忆。
 
 ## 开始任务前
 
-- 先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项；工具探测、历史整理或验证便利不能自行改变任务目标。
+- 先写清一句话交付结果、验收判据和修改范围，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，其余记录为后续事项。
+- Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
 - 简单自包含任务可以直接执行；复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按顺序读取：
   1. 本文件。
   2. [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。
@@ -23,24 +24,20 @@
 
 - 禁止提交个人 `~/.codex` 配置、`.env`、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
 - 不要在 `.gitignore` 中新增 `.env.local`。
-- 不要擅自把现有中文文案、注释、剧情或文档改写成英文；看到中文乱码时先确认真实编码，不要沿用乱码或用英文替换。
-- 修改包含中文的文件时优先局部补丁，避免整文件重写；修改后优先运行仓库编码检查。
-- 后续新增 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；历史文档不要求批量重命名，除非本次任务明确涉及。
+- 现有中文文案、注释、剧情和文档保持中文；看到乱码时先确认真实编码并恢复正确中文。
+- 修改包含中文的文件时优先局部补丁；修改后优先运行仓库编码检查。
+- 新增 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。
 - 工程修改要同步更新对应 `docs/` 文档；产生长期有效的架构约定、接口变化、排障经验、开发流程或协作规则时，同步更新 `docs/project-memory/shared-memory/`。
-- 默认保持系统简洁：优先复用、修改、扩展现有系统、页面和公共组件，不新建平行系统或平行页面。
-- UI 开发优先复用现有公共组件；发现跨页面或跨端重复的视觉/交互模式时，先抽取到 `packages/shared` 共享组件库并让现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
-- 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，坚持“四不写”：
-  1. 不写历史兼容代码。
-  2. 不写用于维持退役行为的防御性兼容测试。
-  3. 不写仅说明其曾存在或已删除的墓碑注释。
-  4. 不写仅记录其已删除的墓碑文档；直接将权威文档更新为当前状态。
-- 公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移不适用“四不写”；必要兼容应最小化、白名单化并配套契约或迁移测试，迁移完成后同步删除兼容实现与对应测试。
-- UI 面板中不要默认写功能说明、规则描述或开发解释文案；移动端优先，同时保证网页端可正常显示和操作。
-- 点击按钮弹出独立面板的设计，不要实现成在当前面板下面追加内容。
+- 默认保持系统简洁：优先复用、修改、扩展现有系统、页面和公共组件。
+- UI 开发优先复用现有公共组件；发现跨页面或跨端重复的视觉/交互模式时，先抽取到 `packages/shared` 共享组件库并让现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
+- 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。
+- 公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移按实际需求保留最小、白名单化的兼容，并配套契约或迁移测试；迁移完成后同步删除兼容实现与对应测试。
+- UI 面板优先呈现任务内容与操作，说明按当前操作需要提供；移动端优先，同时保证网页端可正常显示和操作。
+- 点击按钮弹出的独立面板使用弹窗、抽屉、popover 或页面级 portal。
 
 ## 任务路由
 
-- Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 `tea` CLI，不使用 GitHub `gh` 或 GitLab `glab`，除非仓库已迁移。默认 triage 标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
+- Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 `tea` CLI。默认 triage 标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
 - 需要仓库级 Codex skills/plugins 时，再读取 [`.codex/README.md`](.codex/README.md)。
 - 涉及 AI 游戏创作独立 App、多智能体 Runtime、本地项目产物或本地 HTTP 预览时，先读取 [`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`](docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
 - 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 前，必须读取并按 [`genarrative-play-type-integration`](.codex/skills/genarrative-play-type-integration/SKILL.md) 执行。
@@ -50,10 +47,10 @@
 ## 后端红线
 
 - 后端最新技术约束以 [`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`](docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md) 为准。
-- 后端路线固定为 `server-rs + Axum + SpacetimeDB`；旧 `server-node`、Express、PostgreSQL、Go 服务端、`maincloud` / `Maincloud` / `MAINCLOUD` 只作为历史残留，不作为兼容目标。
+- 后端路线固定为 `server-rs + Axum + SpacetimeDB`。
 - DDD 分层边界按总纲执行：领域规则沉到 `module-*`，SpacetimeDB 表和事务编排留在 `spacetime-module`，后端访问 SpacetimeDB 统一经 `spacetime-client` facade，HTTP/SSE/BFF 留在 `api-server`，外部副作用留在 `platform-*`，前后端 DTO 留在 `shared-contracts`。
-- 前端只做表现、交互和临时 UI 状态，不承接正式业务真相，不绕过后端投影或后端 API 直接实现业务规则。
-- 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、`server-rs/crates/api-server/src/app.rs`、`shared-contracts` 和 `packages/shared` 为准；不得在前端、`api-server` 或临时兼容层中重新发明旧接口。
+- 前端负责表现、交互和临时 UI 状态；正式业务状态与规则以后端投影和后端 API 为准。
+- 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、`server-rs/crates/api-server/src/app.rs`、`shared-contracts` 和 `packages/shared` 为准。
 - 凡修改 `/api/external/v1` 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义，必须在同一次变更中同步更新权威契约 [`docs/openapi/genarrative-external-v1.openapi.json`](docs/openapi/genarrative-external-v1.openapi.json) 及对应契约测试；Rust 实现与 OpenAPI 未保持一致时任务不得视为完成。
 - SpacetimeDB 已有表新增字段时，字段必须放在 Rust 表结构体最后，并设置明确默认值；需要删除、改名、重排或改类型时，必须先询问用户并确认迁移计划。
 - 修改 SpacetimeDB schema 后必须同步 `migration.rs`、表目录和生成绑定，并运行 `npm run check:spacetime-schema`。

apps/admin-web/src/api/adminApiTypes.ts

@@ -144,6 +144,8 @@ export interface AdminErrorReportListResponse {
 }
 
 export interface AdminErrorReportDetail extends AdminErrorReportEntry {
+  firstFingerprint?: string;
+  firstSource?: string;
   note?: string;
   events: Array<Record<string, unknown>>;
   logNames: string[];

apps/admin-web/src/pages/AdminErrorReportsPage.test.tsx

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  formatAdminTimestamp,
+  parseAdminTimestamp,
+} from './AdminErrorReportsPage';
+
+describe('错误报告时间格式化', () => {
+  it('解析 SpacetimeDB seconds.microsZ 时间', () => {
+    expect(parseAdminTimestamp('1778207451.731746Z')).toBe(1778207451731);
+  });
+
+  it('解析微秒字符串并拒绝无效时间', () => {
+    expect(parseAdminTimestamp('1778207451731746')).toBe(1778207451731);
+    expect(formatAdminTimestamp('not-a-date')).toBe('-');
+    expect(formatAdminTimestamp('999999999999999999999999')).toBe('-');
+  });
+});

apps/admin-web/src/pages/AdminErrorReportsPage.tsx

@@ -17,6 +17,57 @@ type Props = { token: string; onUnauthorized: (message?: string) => void };
 
 const ADMIN_ERROR_REPORT_STATUSES = ['new', 'in-progress', 'resolved'] as const;
 const ERROR_REPORT_PAGE_SIZE = 50;
+const ERROR_REPORT_STATUS_LABELS: Record<string, string> = {
+  new: '待处理',
+  'in-progress': '处理中',
+  resolved: '已解决',
+};
+
+export function parseAdminTimestamp(value: string | null | undefined) {
+  const normalized = value?.trim() ?? '';
+  if (/^-?\d+\.\d{6}Z$/u.test(normalized)) {
+    const [secondsText, microsText] = normalized.slice(0, -1).split('.');
+    const seconds = Number(secondsText);
+    const micros = Number(microsText);
+    return Number.isFinite(seconds) && Number.isFinite(micros)
+      ? seconds * 1000 + Math.floor(micros / 1000)
+      : Number.NaN;
+  }
+  if (/^-?\d+$/u.test(normalized)) {
+    const numeric = Number(normalized);
+    if (!Number.isFinite(numeric)) return Number.NaN;
+    if (Math.abs(numeric) >= 1e14) return Math.floor(numeric / 1000);
+    if (Math.abs(numeric) >= 1e11) return numeric;
+    return numeric * 1000;
+  }
+  return Date.parse(normalized);
+}
+
+export function formatAdminTimestamp(value: string | null | undefined) {
+  const timestamp = parseAdminTimestamp(value);
+  if (!Number.isFinite(timestamp)) return '-';
+  const date = new Date(timestamp);
+  if (!Number.isFinite(date.getTime())) return '-';
+  try {
+    return new Intl.DateTimeFormat('zh-CN', {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    }).format(date);
+  } catch {
+    return '-';
+  }
+}
+
+function eventText(event: Record<string, unknown>, key: string) {
+  const value = event[key];
+  return typeof value === 'string' || typeof value === 'number'
+    ? String(value)
+    : '';
+}
 
 export function AdminErrorReportsPage({ token, onUnauthorized }: Props) {
   const [reports, setReports] = useState<AdminErrorReportEntry[]>([]);
@@ -29,6 +80,24 @@ export function AdminErrorReportsPage({ token, onUnauthorized }: Props) {
   const [pageInfo, setPageInfo] = useState({ total: 0, hasMore: false });
   const openReportRequestId = useRef(0);
   const loadRequestId = useRef(0);
+  const detailCloseButtonRef = useRef<HTMLButtonElement | null>(null);
+
+  useEffect(() => {
+    if (!selected) return;
+    const previousFocus = document.activeElement as HTMLElement | null;
+    const focusFrame = window.requestAnimationFrame(() => {
+      detailCloseButtonRef.current?.focus();
+    });
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setSelected(null);
+    };
+    window.addEventListener('keydown', handleEscape);
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      window.removeEventListener('keydown', handleEscape);
+      previousFocus?.focus?.();
+    };
+  }, [selected]);
 
   const load = useCallback(async () => {
     const requestId = ++loadRequestId.current;
@@ -184,9 +253,15 @@ export function AdminErrorReportsPage({ token, onUnauthorized }: Props) {
                 <td>{report.batchId}</td>
                 <td>{report.eventCount}</td>
                 <td>{report.source ?? '-'}</td>
-                <td>{report.status}</td>
+                <td>
+                  <span
+                    className={`admin-error-report-status is-${report.status}`}
+                  >
+                    {ERROR_REPORT_STATUS_LABELS[report.status] ?? report.status}
+                  </span>
+                </td>
                 <td>{report.userId}</td>
-                <td>{new Date(report.createdAt).toLocaleString()}</td>
+                <td>{formatAdminTimestamp(report.createdAt)}</td>
               </tr>
             ))}
           </tbody>
@@ -224,66 +299,173 @@ export function AdminErrorReportsPage({ token, onUnauthorized }: Props) {
           className="admin-detail-modal"
           role="dialog"
           aria-label="错误报告详情"
+          aria-modal="true"
+          onMouseDown={(event) => {
+            if (event.target === event.currentTarget) setSelected(null);
+          }}
         >
-          <div className="admin-detail-modal__panel">
-            <header>
-              <h2>{selected.batchId}</h2>
-              <button type="button" onClick={() => setSelected(null)}>
-                关闭
+          <div className="admin-detail-modal__panel admin-error-report-detail">
+            <header className="admin-error-report-detail__header">
+              <div className="admin-error-report-detail__heading">
+                <span className="admin-error-report-detail__eyebrow">
+                  错误报告详情
+                </span>
+                <h2>{selected.batchId}</h2>
+                <div className="admin-error-report-detail__badges">
+                  <span
+                    className={`admin-error-report-status is-${selected.status}`}
+                  >
+                    {ERROR_REPORT_STATUS_LABELS[selected.status] ??
+                      selected.status}
+                  </span>
+                  <span className="admin-error-report-detail__badge">
+                    {selected.firstSource ?? selected.source ?? '未知来源'}
+                  </span>
+                </div>
+              </div>
+              <button
+                type="button"
+                className="admin-error-report-detail__close"
+                ref={detailCloseButtonRef}
+                onClick={() => setSelected(null)}
+                aria-label="关闭错误报告详情"
+              >
+                ×
               </button>
             </header>
-            <p>
-              用户：{selected.userId} · 事件：{selected.eventCount} · 日志：
-              {selected.logCount}
-            </p>
-            <pre>{JSON.stringify(selected.events.slice(0, 20), null, 2)}</pre>
-            {selected.userDescription ? (
-              <p>用户描述：{selected.userDescription}</p>
-            ) : null}
-            <label className="admin-detail-modal__note">
-              处理备注
-              <textarea
-                value={selected.note ?? ''}
-                onChange={(event) =>
-                  setSelected((current) =>
-                    current
-                      ? { ...current, note: event.target.value }
-                      : current,
-                  )
-                }
-                maxLength={2000}
-                rows={4}
-                placeholder="记录处理结论或后续跟进事项"
-                disabled={busy}
-              />
-            </label>
-            <div className="admin-detail-modal__actions">
-              <select
-                value={selected.status}
-                onChange={(event) => void saveStatus(event.target.value)}
-                disabled={busy}
-              >
-                {ADMIN_ERROR_REPORT_STATUSES.map((value) => (
-                  <option key={value} value={value}>
-                    {value}
-                  </option>
-                ))}
-              </select>
-              <button
-                type="button"
-                onClick={() => void saveStatus(selected.status)}
-                disabled={busy}
-              >
-                保存备注
-              </button>
-              <button
-                type="button"
-                onClick={() => void download(selected.batchId)}
-                disabled={downloading}
-              >
-                {downloading ? '下载中…' : '下载诊断包'}
-              </button>
+            <div className="admin-error-report-detail__summary">
+              <div>
+                <span>用户</span>
+                <strong>{selected.userId}</strong>
+              </div>
+              <div>
+                <span>发生时间</span>
+                <strong>{formatAdminTimestamp(selected.createdAt)}</strong>
+              </div>
+              <div>
+                <span>错误事件</span>
+                <strong>{selected.eventCount}</strong>
+              </div>
+              <div>
+                <span>应用日志</span>
+                <strong>{selected.logCount}</strong>
+              </div>
             </div>
+            <div className="admin-error-report-detail__body">
+              <section className="admin-error-report-detail__section">
+                <div className="admin-error-report-detail__section-heading">
+                  <div>
+                    <h3>错误事件</h3>
+                    <span>展示最近 20 条，完整内容请下载诊断包。</span>
+                  </div>
+                  <span className="admin-error-report-detail__count">
+                    {selected.events.length} 条
+                  </span>
+                </div>
+                <div className="admin-error-report-event-list">
+                  {selected.events.length === 0 ? (
+                    <p className="admin-error-report-detail__empty">
+                      归档中没有可展示的错误事件。
+                    </p>
+                  ) : null}
+                  {selected.events.slice(0, 20).map((event, index) => {
+                    const message = eventText(event, 'message') || '未知错误';
+                    const stack = eventText(event, 'stack');
+                    const occurredAt = eventText(event, 'occurredAt');
+                    return (
+                      <article
+                        className="admin-error-report-event"
+                        key={`${index}-${message}`}
+                      >
+                        <div className="admin-error-report-event__topline">
+                          <span className="admin-error-report-event__index">
+                            #{index + 1}
+                          </span>
+                          <span>{eventText(event, 'source') || 'client'}</span>
+                          <span>{eventText(event, 'count') || '1'} 次</span>
+                          <time>{formatAdminTimestamp(occurredAt)}</time>
+                        </div>
+                        <p className="admin-error-report-event__message">
+                          {message}
+                        </p>
+                        {eventText(event, 'fingerprint') ? (
+                          <code>{eventText(event, 'fingerprint')}</code>
+                        ) : null}
+                        {stack ? (
+                          <details>
+                            <summary>查看调用栈</summary>
+                            <pre>{stack}</pre>
+                          </details>
+                        ) : null}
+                      </article>
+                    );
+                  })}
+                </div>
+              </section>
+              {selected.userDescription ? (
+                <section className="admin-error-report-detail__section">
+                  <div className="admin-error-report-detail__section-heading">
+                    <div>
+                      <h3>用户描述</h3>
+                    </div>
+                  </div>
+                  <p className="admin-error-report-detail__description">
+                    {selected.userDescription}
+                  </p>
+                </section>
+              ) : null}
+              <section className="admin-error-report-detail__section admin-error-report-detail__section--note">
+                <label className="admin-detail-modal__note">
+                  <span>处理备注</span>
+                  <textarea
+                    value={selected.note ?? ''}
+                    onChange={(event) =>
+                      setSelected((current) =>
+                        current
+                          ? { ...current, note: event.target.value }
+                          : current,
+                      )
+                    }
+                    maxLength={2000}
+                    rows={4}
+                    placeholder="记录处理结论或后续跟进事项"
+                    disabled={busy}
+                  />
+                </label>
+              </section>
+            </div>
+            <footer className="admin-error-report-detail__footer">
+              <label className="admin-error-report-detail__status-field">
+                状态
+                <select
+                  value={selected.status}
+                  onChange={(event) => void saveStatus(event.target.value)}
+                  disabled={busy}
+                >
+                  {ADMIN_ERROR_REPORT_STATUSES.map((value) => (
+                    <option key={value} value={value}>
+                      {ERROR_REPORT_STATUS_LABELS[value]}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <div className="admin-error-report-detail__footer-actions">
+                <button
+                  type="button"
+                  onClick={() => void saveStatus(selected.status)}
+                  disabled={busy}
+                >
+                  {busy ? '保存中…' : '保存备注'}
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void download(selected.batchId)}
+                  disabled={downloading}
+                >
+                  {downloading ? '下载中…' : '下载诊断包'}
+                </button>
+              </div>
+            </footer>
           </div>
         </div>
       ) : null}

apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx

@@ -154,6 +154,27 @@ test('灰度发布页可通过功能入口生成画布 Agent Gate Key', async ()
   );
 });
 
+test('灰度发布页可选择模板库并默认启用零比例灰度', async () => {
+  const user = userEvent.setup();
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+  await screen.findByRole('button', { name: 'editor.new-toolbar' });
+  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), ['agc']);
+  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
+    'agc:template-library',
+  );
+  expect(
+    (screen.getByLabelText('Gate Key 目标') as HTMLSelectElement).value,
+  ).toBe('template-library');
+  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
+    true,
+  );
+  expect((screen.getByLabelText('灰度比例') as HTMLInputElement).value).toBe(
+    '0',
+  );
+});
+
 test('灰度发布页保存时转换数组和百分比', async () => {
   const user = userEvent.setup();
   vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({

apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx

@@ -27,9 +27,17 @@ interface GateTargetOption {
 
 const GATE_PREFIX_LABELS: Record<string, string> = {
   'image-editor': '画布',
+  agc: '客户端',
 };
 
 const FIXED_GATE_TARGETS: GateTargetOption[] = [
+  {
+    prefix: 'agc',
+    suffix: 'template-library',
+    key: 'agc:template-library',
+    label: '模板库',
+    description: '客户端模板库灰度',
+  },
   {
     prefix: 'image-editor',
     suffix: 'agent-sidebar',
@@ -180,7 +188,7 @@ export function AdminGrayReleaseConfigPage({
     setSelectedGateKey('');
     setGatePrefix(option.prefix);
     setGateKey(option.key);
-    setEnabled(false);
+    setEnabled(option.key === 'agc:template-library');
     setRolloutPercent('0');
     setAllowUserIds('');
     setAllowUserTags('');

apps/admin-web/src/styles/admin.css

@@ -3213,6 +3213,377 @@ button:disabled {
   padding: 12px;
   border-radius: 8px;
 }
+
+.admin-error-report-detail {
+  width: min(980px, 100%);
+  padding: 0;
+  overflow: hidden;
+  border: 1px solid #eadfd6;
+  background: #fffdfb;
+  box-shadow: 0 24px 80px rgb(57 31 18 / 22%);
+}
+
+.admin-error-report-detail__header {
+  align-items: flex-start;
+  padding: 24px 28px 20px;
+  border-bottom: 1px solid #eee2d8;
+  background: linear-gradient(135deg, #fffaf5, #fffdfb 65%);
+}
+
+.admin-error-report-detail__heading {
+  min-width: 0;
+}
+
+.admin-error-report-detail__eyebrow {
+  display: block;
+  margin-bottom: 7px;
+  color: #a4775d;
+  font-size: 12px;
+  font-weight: 750;
+  letter-spacing: 0.08em;
+}
+
+.admin-error-report-detail__heading h2 {
+  margin: 0;
+  overflow-wrap: anywhere;
+  color: #3d2a20;
+  font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  font-size: 19px;
+  line-height: 1.35;
+}
+
+.admin-error-report-detail__badges,
+.admin-error-report-detail__footer-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.admin-error-report-detail__badges {
+  margin-top: 12px;
+}
+
+.admin-error-report-detail__badge,
+.admin-error-report-detail__count {
+  display: inline-flex;
+  align-items: center;
+  min-height: 26px;
+  padding: 0 9px;
+  border: 1px solid #eadfd6;
+  border-radius: 999px;
+  color: #785b49;
+  background: #fff;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.admin-error-report-detail__close {
+  display: inline-flex;
+  width: 34px;
+  height: 34px;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  border: 1px solid #e5d5c8;
+  border-radius: 9px;
+  color: #765848;
+  background: #fff;
+  font-size: 24px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.admin-error-report-detail__close:hover,
+.admin-error-report-detail__close:focus-visible {
+  border-color: #b6623f;
+  color: #9b4f31;
+  outline: none;
+}
+
+.admin-error-report-status {
+  display: inline-flex;
+  align-items: center;
+  min-height: 26px;
+  padding: 0 9px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 750;
+}
+
+.admin-error-report-status.is-new {
+  color: #a14e20;
+  background: #fff0e5;
+}
+
+.admin-error-report-status.is-in-progress {
+  color: #72551b;
+  background: #fff7d9;
+}
+
+.admin-error-report-status.is-resolved {
+  color: #28704d;
+  background: #e9f7ee;
+}
+
+.admin-error-report-detail__summary {
+  display: grid;
+  grid-template-columns: minmax(0, 1.7fr) repeat(3, minmax(100px, 1fr));
+  gap: 1px;
+  border-bottom: 1px solid #eee2d8;
+  background: #eee2d8;
+}
+
+.admin-error-report-detail__summary > div {
+  display: grid;
+  min-width: 0;
+  gap: 5px;
+  padding: 14px 18px;
+  background: #fffdfb;
+}
+
+.admin-error-report-detail__summary span,
+.admin-error-report-detail__section-heading span,
+.admin-error-report-detail__status-field {
+  color: #997d6a;
+  font-size: 12px;
+  font-weight: 650;
+}
+
+.admin-error-report-detail__summary strong {
+  overflow-wrap: anywhere;
+  color: #4d3326;
+  font-size: 13px;
+}
+
+.admin-error-report-detail__body {
+  display: grid;
+  gap: 16px;
+  max-height: min(62vh, 640px);
+  overflow: auto;
+  padding: 20px 28px;
+}
+
+.admin-error-report-detail__section {
+  display: grid;
+  gap: 12px;
+}
+
+.admin-error-report-detail__section-heading {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.admin-error-report-detail__section-heading h3 {
+  margin: 0 0 4px;
+  color: #4d3326;
+  font-size: 15px;
+}
+
+.admin-error-report-detail__section-heading span {
+  line-height: 1.5;
+}
+
+.admin-error-report-detail__count {
+  flex: 0 0 auto;
+}
+
+.admin-error-report-event-list {
+  display: grid;
+  gap: 10px;
+}
+
+.admin-error-report-detail__empty {
+  margin: 0;
+  padding: 16px;
+  border: 1px dashed #e4d2c5;
+  border-radius: 10px;
+  color: #997d6a;
+  background: #fffaf6;
+  text-align: center;
+}
+
+.admin-error-report-event {
+  display: grid;
+  gap: 9px;
+  padding: 14px 16px;
+  border: 1px solid #eee2d8;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.admin-error-report-event__topline {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  color: #927663;
+  font-size: 12px;
+}
+
+.admin-error-report-event__topline time {
+  margin-left: auto;
+  color: #aa9282;
+}
+
+.admin-error-report-event__index {
+  color: #b6623f;
+  font-weight: 750;
+}
+
+.admin-error-report-event__message {
+  margin: 0;
+  color: #4a3024;
+  font-size: 14px;
+  line-height: 1.55;
+  overflow-wrap: anywhere;
+}
+
+.admin-error-report-event code {
+  overflow-wrap: anywhere;
+  color: #957a69;
+  font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  font-size: 11px;
+}
+
+.admin-error-report-event details {
+  border-top: 1px solid #f0e7df;
+  padding-top: 9px;
+}
+
+.admin-error-report-event summary {
+  color: #a15d3e;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.admin-error-report-event pre {
+  max-height: 180px;
+  margin: 9px 0 0;
+  padding: 10px;
+  border: 1px solid #f0e7df;
+  background: #fffaf6;
+  color: #72594a;
+  font-size: 11px;
+  line-height: 1.5;
+}
+
+.admin-error-report-detail__description {
+  margin: 0;
+  padding: 13px 15px;
+  border-radius: 10px;
+  color: #634b3c;
+  background: #fff8f2;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.admin-error-report-detail__section--note {
+  padding-top: 4px;
+}
+
+.admin-error-report-detail__section--note .admin-detail-modal__note {
+  display: grid;
+  gap: 8px;
+  color: #624938;
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.admin-error-report-detail__section--note textarea {
+  width: 100%;
+  min-height: 100px;
+  box-sizing: border-box;
+  resize: vertical;
+  border: 1px solid #e4d2c5;
+  border-radius: 10px;
+  padding: 11px 12px;
+  color: #4d3326;
+  background: #fff;
+  font: inherit;
+  line-height: 1.5;
+}
+
+.admin-error-report-detail__section--note textarea:focus {
+  border-color: #b6623f;
+  box-shadow: 0 0 0 3px rgb(182 98 63 / 14%);
+  outline: none;
+}
+
+.admin-error-report-detail__footer {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 16px 28px 20px;
+  border-top: 1px solid #eee2d8;
+  background: #fffaf6;
+}
+
+.admin-error-report-detail__status-field {
+  display: grid;
+  gap: 6px;
+}
+
+.admin-error-report-detail__status-field select {
+  min-width: 132px;
+  min-height: 38px;
+  border: 1px solid #e4d2c5;
+  border-radius: 8px;
+  padding: 0 10px;
+  color: #4d3326;
+  background: #fff;
+  font: inherit;
+}
+
+.admin-error-report-detail__footer-actions button {
+  min-height: 38px;
+  border: 1px solid #d9c3b4;
+  border-radius: 8px;
+  padding: 0 13px;
+  color: #6d4b3a;
+  background: #fff;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.admin-error-report-detail__footer-actions button:last-child {
+  border-color: #a96442;
+  color: #fff;
+  background: #a96442;
+}
+
+.admin-error-report-detail__footer-actions button:hover,
+.admin-error-report-detail__footer-actions button:focus-visible {
+  border-color: #a96442;
+  outline: none;
+}
+
+@media (max-width: 720px) {
+  .admin-error-report-detail__header,
+  .admin-error-report-detail__body,
+  .admin-error-report-detail__footer {
+    padding-right: 18px;
+    padding-left: 18px;
+  }
+
+  .admin-error-report-detail__summary {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .admin-error-report-detail__footer {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .admin-error-report-detail__footer-actions button {
+    flex: 1;
+  }
+}
 .admin-agc-models {
   min-width: 0;
 }

apps/ai-game-creator-shell/package.json

@@ -66,15 +66,15 @@
     "zustand": "^5.0.14"
   },
   "devDependencies": {
-    "@openai/codex": "0.147.0",
+    "@openai/codex": "0.155.1",
     "@tailwindcss/vite": "^4.1.14",
     "@tauri-apps/cli": "^2.11.2",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@types/three": "^0.184.1",
     "@types/react-window": "^1.8.8",
+    "@types/three": "^0.184.1",
     "tailwindcss": "^4.1.14",
     "typescript": "~5.8.2",
     "vitest": "^0.34.6"

apps/ai-game-creator-shell/scripts/agc-global-version.mjs

@@ -0,0 +1,330 @@
+/**
+ * AGC 总版本号（发号源）。
+ *
+ * 唯一事实源是 OSS 对象 `agc/global-version.json`；渠道清单只写各自本次拿到的号。
+ * 仓库里的 5 个版本文件仍由构建改写，但只作构建输入参考，不作为事实源。
+ *
+ * 发号顺序固定为「先写总号 → 再构建 → 再发渠道清单」：任何一步失败都不回滚，
+ * 只烧号。这样渠道之间不会复用同一个号，代价是可能出现空洞。
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const AGC_GLOBAL_VERSION_OBJECT_KEY = 'agc/global-version.json';
+const defaultOssBaseUrl =
+  'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc';
+const versionPattern = /^\d+\.\d+\.\d+$/u;
+
+function trimTrailingSlashes(value) {
+  return value.replace(/\/+$/u, '');
+}
+
+export function ossBaseUrl(env = process.env) {
+  return trimTrailingSlashes(
+    env.AGC_UPDATE_OSS_BASE_URL?.trim() || defaultOssBaseUrl,
+  );
+}
+
+export function globalVersionUrl(env = process.env) {
+  return `${ossBaseUrl(env)}/global-version.json`;
+}
+
+export function parseVersion(value, label) {
+  if (typeof value !== 'string' || !versionPattern.test(value.trim())) {
+    throw new Error(`${label} 不是有效的三段版本号：${String(value)}`);
+  }
+  return value.trim();
+}
+
+export function compareVersions(left, right) {
+  const leftParts = parseVersion(left, '左版本').split('.').map(Number);
+  const rightParts = parseVersion(right, '右版本').split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] > rightParts[index] ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+/** 取较大版本；任一为空时返回另一个。 */
+export function maxVersion(...versions) {
+  return versions
+    .filter((value) => typeof value === 'string' && value.trim())
+    .map((value) => parseVersion(value, '候选版本'))
+    .reduce(
+      (best, current) =>
+        best == null || compareVersions(current, best) > 0 ? current : best,
+      null,
+    );
+}
+
+export function nextVersion(current) {
+  const [major, minor, patch] = parseVersion(current, '总版本')
+    .split('.')
+    .map(Number);
+  if (patch === Number.MAX_SAFE_INTEGER) {
+    throw new Error(`版本号 patch 已达到上限：${current}`);
+  }
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+export function readReleaseDryRun(env = process.env) {
+  const value = env.AGC_RELEASE_DRY_RUN?.trim().toLowerCase();
+  return value === '1' || value === 'true';
+}
+
+async function fetchJson(url, label, { fetchImpl = fetch } = {}) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { Accept: 'application/json' },
+    });
+  } catch (error) {
+    throw new Error(`读取 ${label} 失败：${error.message}`);
+  }
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`读取 ${label} 失败：HTTP ${response.status}`);
+  }
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`${label} 不是有效 JSON：${error.message}`);
+  }
+}
+
+/** 渠道清单版本；缺失或 404 时返回 null（首次启用渠道）。 */
+export async function readChannelVersion(channel, options = {}) {
+  const payload = await fetchJson(
+    `${ossBaseUrl(options.env)}/${channel}/latest.json`,
+    `${channel} 渠道清单`,
+    options,
+  );
+  if (payload == null) return null;
+  const version = typeof payload.version === 'string' ? payload.version : '';
+  if (!version) {
+    throw new Error(`${channel} 渠道清单缺少 version 字段`);
+  }
+  return parseVersion(version, `${channel} 渠道清单 version`);
+}
+
+/** 旧协议迁移指针 `agc/latest.json`；只在迁移窗口内存在，仅参与播种。 */
+export async function readLegacyPointerVersion(options = {}) {
+  const payload = await fetchJson(
+    `${ossBaseUrl(options.env)}/latest.json`,
+    'OSS 迁移指针',
+    options,
+  );
+  if (payload == null) return null;
+  const version = typeof payload.version === 'string' ? payload.version : '';
+  return version ? parseVersion(version, 'OSS 迁移指针 version') : null;
+}
+
+export async function readGlobalVersion(options = {}) {
+  const payload = await fetchJson(
+    globalVersionUrl(options.env),
+    'AGC 总版本号',
+    options,
+  );
+  if (payload == null) return null;
+  const version = typeof payload.version === 'string' ? payload.version : '';
+  if (!version) {
+    throw new Error('AGC 总版本号对象缺少 version 字段');
+  }
+  return {
+    ...payload,
+    version: parseVersion(version, 'AGC 总版本号 version'),
+  };
+}
+
+/**
+ * 一次性播种基线：仓库当前版本、渠道清单与旧迁移指针里的最大值。
+ * 基线本身不发给客户端，首个发放号是 baseline + 1。
+ */
+export async function resolveSeedBaseline({
+  channels = ['dev-win', 'dev-mac'],
+  repoVersion = null,
+  env = process.env,
+  fetchImpl = fetch,
+} = {}) {
+  const candidates = [];
+  if (repoVersion) candidates.push(parseVersion(repoVersion, '仓库当前版本'));
+  for (const channel of channels) {
+    const version = await readChannelVersion(channel, { env, fetchImpl });
+    if (version) candidates.push(version);
+  }
+  const legacy = await readLegacyPointerVersion({ env, fetchImpl });
+  if (legacy) candidates.push(legacy);
+  const baseline = maxVersion(...candidates);
+  if (!baseline) {
+    throw new Error('无法确定总版本号播种基线：仓库版本与渠道清单都不可用');
+  }
+  return baseline;
+}
+
+/**
+ * 组装 ossutil 参数。
+ *
+ * 该桶与凭据按 v1 签名使用（ossutil v2 默认 v4，缺 region 会直接失败），
+ * 因此默认显式传 `--sign-version v1`；需要 v4 时用 `AGC_OSS_SIGN_VERSION=v4`
+ * 并同时给 `AGC_OSS_REGION`。
+ */
+export function buildOssutilArgs({
+  args,
+  endpoint,
+  accessKeyId,
+  accessKeySecret,
+  env = process.env,
+}) {
+  const finalArgs = [...args, '--endpoint', endpoint];
+  const region = env.AGC_OSS_REGION?.trim();
+  if (region) finalArgs.push('--region', region);
+  finalArgs.push('--sign-version', env.AGC_OSS_SIGN_VERSION?.trim() || 'v1');
+  if (accessKeyId) {
+    finalArgs.push(
+      '--access-key-id',
+      accessKeyId,
+      '--access-key-secret',
+      accessKeySecret,
+    );
+  }
+  return finalArgs;
+}
+
+function runOssutil(args, { env = process.env } = {}) {
+  const binary = env.OSSUTIL_BIN?.trim() || 'ossutil';
+  const endpoint =
+    env.AGC_OSS_ENDPOINT?.trim() || 'oss-rg-china-mainland.aliyuncs.com';
+  const accessKeyId = env.AGC_OSS_ACCESS_KEY_ID?.trim();
+  const accessKeySecret = env.AGC_OSS_ACCESS_KEY_SECRET;
+  if (Boolean(accessKeyId) !== Boolean(accessKeySecret)) {
+    throw new Error('OSS AccessKey ID 和 Secret 必须同时提供');
+  }
+  const result = spawnSync(
+    binary,
+    buildOssutilArgs({
+      args,
+      endpoint,
+      accessKeyId,
+      accessKeySecret,
+      env,
+    }),
+    { stdio: 'inherit', shell: false, env },
+  );
+  if (result.error) {
+    throw new Error(`无法执行 ${binary}，请先安装并配置 ossutil`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`${binary} 执行失败，退出码 ${result.status}`);
+  }
+}
+
+/** 写入总版本号对象；dry-run 下只打印将要执行的上传。 */
+export function writeGlobalVersion(payload, options = {}) {
+  const { env = process.env, dryRun = readReleaseDryRun(env) } = options;
+  const bucket = env.AGC_OSS_BUCKET?.trim() || 'agc-dev';
+  const body = Buffer.from(`${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  const tempDirectory = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'agc-global-version-'),
+  );
+  const tempPath = path.join(tempDirectory, 'global-version.json');
+  try {
+    fs.writeFileSync(tempPath, body);
+    const ossUrl = `oss://${bucket}/${AGC_GLOBAL_VERSION_OBJECT_KEY}`;
+    if (dryRun) {
+      console.log(
+        `[dry-run] 不写总版本号：${ossUrl} <- ${JSON.stringify(payload)}`,
+      );
+      return { written: false, objectUrl: ossUrl, payload };
+    }
+    runOssutil(['cp', '--force', tempPath, ossUrl], { env });
+    return { written: true, objectUrl: ossUrl, payload };
+  } finally {
+    fs.rmSync(tempDirectory, { force: true, recursive: true });
+  }
+}
+
+/**
+ * 发一次号并写回总版本号对象。
+ *
+ * 写后回读校验：若远端值与自己写下的不一致，说明有并发发号，按失败关闭处理
+ * （号已烧，不重试、不回滚），由人工确认后再发。
+ */
+export async function issueGlobalVersion({
+  channel,
+  commit = null,
+  buildId = null,
+  repoVersion = null,
+  env = process.env,
+  fetchImpl = fetch,
+  now = () => new Date().toISOString(),
+  writeImpl = writeGlobalVersion,
+} = {}) {
+  if (!channel) throw new Error('发号必须显式指定 channel');
+  const dryRun = readReleaseDryRun(env);
+  const current = await readGlobalVersion({ env, fetchImpl });
+  let baseline = current?.version ?? null;
+  let seeded = false;
+  if (!baseline) {
+    baseline = await resolveSeedBaseline({ repoVersion, env, fetchImpl });
+    seeded = true;
+  }
+  const issued = nextVersion(baseline);
+  const payload = {
+    version: issued,
+    updatedAt: now(),
+    channel,
+    commit,
+    buildId,
+  };
+  console.log(
+    `[agc-global-version] ${
+      seeded ? `按播种基线 ${baseline} 首发` : `总号 ${baseline}`
+    } -> ${issued}（channel=${channel} dry-run=${dryRun}）`,
+  );
+  writeImpl(payload, { env, dryRun });
+  if (!dryRun) {
+    const stored = await readGlobalVersion({ env, fetchImpl });
+    if (!stored || stored.version !== issued) {
+      throw new Error(
+        `总版本号写后回读不一致：期望 ${issued}，远端 ${
+          stored?.version ?? '不存在'
+        }；可能存在并发发号，本次构建失败关闭`,
+      );
+    }
+  }
+  return issued;
+}
+
+/** 渠道高水位断言：请求号低于本渠道清单版本即失败关闭。 */
+export function assertRequestedVersionNotBelowChannel({
+  requested,
+  channelVersion,
+  channel,
+}) {
+  const requestedVersion = parseVersion(requested, '请求版本');
+  if (channelVersion == null) return requestedVersion;
+  const current = parseVersion(channelVersion, `${channel} 渠道版本`);
+  if (compareVersions(requestedVersion, current) < 0) {
+    throw new Error(
+      `请求版本 ${requestedVersion} 低于 ${channel} 渠道当前清单版本 ${current}；拒绝回退发布`,
+    );
+  }
+  return requestedVersion;
+}
+
+/** 只读预览：不写回、不烧号。 */
+export async function previewNextGlobalVersion(options = {}) {
+  const current = await readGlobalVersion(options);
+  const baseline =
+    current?.version ??
+    (await resolveSeedBaseline({
+      repoVersion: options.repoVersion,
+      env: options.env,
+      fetchImpl: options.fetchImpl,
+    }));
+  return nextVersion(baseline);
+}

apps/ai-game-creator-shell/scripts/agc-global-version.test.mjs

@@ -0,0 +1,206 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  assertRequestedVersionNotBelowChannel,
+  buildOssutilArgs,
+  issueGlobalVersion,
+  maxVersion,
+  nextVersion,
+  previewNextGlobalVersion,
+  resolveSeedBaseline,
+} from './agc-global-version.mjs';
+
+function jsonResponse(payload, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => payload,
+  };
+}
+
+/** 以 URL 为键的假 OSS：只读 fetch + 记录写入。 */
+function createFakeOss({ objects = {} } = {}) {
+  const state = { ...objects };
+  const writes = [];
+  return {
+    state,
+    writes,
+    fetchImpl: async (url) => {
+      const key = String(url).replace(/^https?:\/\/[^/]+\//u, '');
+      if (!(key in state)) return jsonResponse(null, 404);
+      return jsonResponse(state[key]);
+    },
+    writeImpl: (payload, options = {}) => {
+      writes.push({ payload, dryRun: Boolean(options.dryRun) });
+      if (!options.dryRun) state['agc/global-version.json'] = payload;
+      return { written: !options.dryRun, payload };
+    },
+  };
+}
+
+test('播种基线取仓库版本、各渠道清单与旧迁移指针的最大值', async () => {
+  const oss = createFakeOss({
+    objects: {
+      'agc/dev-win/latest.json': { version: '0.1.57' },
+      'agc/dev-mac/latest.json': { version: '0.1.12' },
+      'agc/latest.json': { version: '0.1.60' },
+    },
+  });
+  assert.equal(
+    await resolveSeedBaseline({
+      repoVersion: '0.1.48',
+      env: {},
+      fetchImpl: oss.fetchImpl,
+    }),
+    '0.1.60',
+  );
+  assert.equal(maxVersion('0.1.9', '0.1.10', null), '0.1.10');
+});
+
+test('无总号时按播种基线发首号，并把总号写回唯一事实源', async () => {
+  const oss = createFakeOss({
+    objects: {
+      'agc/dev-win/latest.json': { version: '0.1.57' },
+      'agc/dev-mac/latest.json': { version: '0.1.12' },
+    },
+  });
+  const issued = await issueGlobalVersion({
+    channel: 'dev-win',
+    commit: 'a'.repeat(40),
+    buildId: '319',
+    repoVersion: '0.1.48',
+    env: {},
+    fetchImpl: oss.fetchImpl,
+    writeImpl: oss.writeImpl,
+    now: () => '2026-09-20T00:00:00.000Z',
+  });
+  assert.equal(issued, '0.1.58');
+  assert.deepEqual(
+    oss.writes.map((entry) => entry.payload.version),
+    ['0.1.58'],
+  );
+  assert.equal(oss.state['agc/global-version.json'].version, '0.1.58');
+  assert.equal(oss.state['agc/global-version.json'].channel, 'dev-win');
+  assert.equal(oss.state['agc/global-version.json'].buildId, '319');
+});
+
+test('已有总号时只递增，不再回看渠道清单', async () => {
+  const oss = createFakeOss({
+    objects: {
+      'agc/global-version.json': { version: '0.2.7' },
+      // 渠道清单被手工改小也不能把总号拉回去。
+      'agc/dev-win/latest.json': { version: '0.1.10' },
+    },
+  });
+  const issued = await issueGlobalVersion({
+    channel: 'dev-mac',
+    env: {},
+    fetchImpl: oss.fetchImpl,
+    writeImpl: oss.writeImpl,
+  });
+  assert.equal(issued, '0.2.8');
+  assert.equal(oss.state['agc/global-version.json'].version, '0.2.8');
+});
+
+test('dry-run 只预览下一位，不写回、不烧号', async () => {
+  const oss = createFakeOss({
+    objects: { 'agc/global-version.json': { version: '0.3.4' } },
+  });
+  const preview = await previewNextGlobalVersion({
+    env: {},
+    fetchImpl: oss.fetchImpl,
+  });
+  assert.equal(preview, '0.3.5');
+  assert.equal(oss.writes.length, 0);
+
+  const issued = await issueGlobalVersion({
+    channel: 'dev-win',
+    env: { AGC_RELEASE_DRY_RUN: '1' },
+    fetchImpl: oss.fetchImpl,
+    writeImpl: oss.writeImpl,
+  });
+  assert.equal(issued, '0.3.5');
+  assert.deepEqual(
+    oss.writes.map((entry) => entry.dryRun),
+    [true],
+  );
+  assert.equal(oss.state['agc/global-version.json'].version, '0.3.4');
+});
+
+test('传入低于本渠道清单的号时失败关闭', () => {
+  assert.equal(
+    assertRequestedVersionNotBelowChannel({
+      requested: '0.1.60',
+      channelVersion: '0.1.60',
+      channel: 'dev-win',
+    }),
+    '0.1.60',
+  );
+  assert.throws(
+    () =>
+      assertRequestedVersionNotBelowChannel({
+        requested: '0.1.59',
+        channelVersion: '0.1.60',
+        channel: 'dev-win',
+      }),
+    /低于 dev-win 渠道当前清单版本/u,
+  );
+  assert.equal(
+    assertRequestedVersionNotBelowChannel({
+      requested: '0.1.1',
+      channelVersion: null,
+      channel: 'dev-mac',
+    }),
+    '0.1.1',
+  );
+});
+
+test('写后回读不一致（并发发号）时失败关闭', async () => {
+  const oss = createFakeOss({
+    objects: { 'agc/global-version.json': { version: '0.5.1' } },
+  });
+  await assert.rejects(
+    issueGlobalVersion({
+      channel: 'dev-win',
+      env: {},
+      // 模拟另一个发号进程在写入后覆盖了总号。
+      writeImpl: (payload, options) => {
+        const result = oss.writeImpl(payload, options);
+        // 另一个发号进程紧随其后覆盖总号。
+        oss.state['agc/global-version.json'] = { version: '0.5.9' };
+        return result;
+      },
+      fetchImpl: oss.fetchImpl,
+    }),
+    /写后回读不一致/u,
+  );
+});
+
+test('nextVersion 只在 patch 位递增', () => {
+  assert.equal(nextVersion('0.1.9'), '0.1.10');
+  assert.equal(nextVersion('1.0.0'), '1.0.1');
+  assert.throws(() => nextVersion('0.1'), /不是有效的三段版本号/u);
+});
+
+test('ossutil 参数默认使用 v1 签名，并可按需带 region 与 v4', () => {
+  const base = {
+    args: ['cp', '--force', '/tmp/a.json', 'oss://agc-dev/agc/global-version.json'],
+    endpoint: 'oss-rg-china-mainland.aliyuncs.com',
+    accessKeyId: 'id',
+    accessKeySecret: 'secret',
+    env: {},
+  };
+  const v1 = buildOssutilArgs(base);
+  assert.equal(v1[v1.indexOf('--sign-version') + 1], 'v1');
+  assert.ok(!v1.includes('--region'));
+  assert.equal(v1[v1.indexOf('--access-key-id') + 1], 'id');
+  assert.equal(v1[v1.indexOf('--access-key-secret') + 1], 'secret');
+
+  const v4 = buildOssutilArgs({
+    ...base,
+    env: { AGC_OSS_SIGN_VERSION: 'v4', AGC_OSS_REGION: 'cn-beijing' },
+  });
+  assert.equal(v4[v4.indexOf('--region') + 1], 'cn-beijing');
+  assert.equal(v4[v4.indexOf('--sign-version') + 1], 'v4');
+});

apps/ai-game-creator-shell/scripts/agent-swarm-test-chat.mjs

@@ -957,9 +957,6 @@ async function runInteractiveCargo(cliArguments, setActiveChild) {
   return result;
 }
 
-// 立项策划跑 standard 档，`agent.delegate` 这类动作按项目权限策略必须逐个确认，
-// 而确认和问询都只从 CLI 的 stdin 读。自主构建档没有这一步，所以只有 --plan 需要
-// 一个把「人坐在终端前敲 approve」自动化掉的应答器；判据本身仍然走后端确认命令。
 const swarmConfirmationPromptPattern = /输入 approve 或 reject：$/u;
 const swarmUserInputPromptPattern = /请选择 1-\d+，或直接输入其他答案：$/u;
 

apps/ai-game-creator-shell/scripts/build-macos-ci.mjs

@@ -0,0 +1,280 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  generateUpdateManifest,
+  prepareReleaseVersion,
+  resolveReleaseContext,
+  resolveReleasePartition,
+  runTauriBuild,
+} from './build-release.mjs';
+import { readReleaseDryRun, uploadReleaseArtifacts } from './release-oss.mjs';
+import {
+  readUpdaterPubkey,
+  verifyUpdaterSignature,
+} from './verify-updater-signature.mjs';
+
+/**
+ * AGC macOS 分区（`<channel>-mac`）发布入口：构建 universal 包 → 双架构 smoke → 生成 universal DMG
+ * → 生成分区清单 latest.json → 用产物内烘焙的公钥验签 → 按 dry-run 决定是否上传 OSS。
+ *
+ * 边界：
+ * - Apple 签名与公证暂缺：本入口剥离 `APPLE_*` 凭据让 Tauri 跳过 Apple 签名，但**不能传
+ *   `--no-sign`** —— 该标志同时会跳过 updater 的 minisign 签名，产物就没有 `.sig`；
+ *   未签名 + 未公证必须显式记录而非静默通过；
+ * - 更新包签名（TAURI_SIGNING_PRIVATE_KEY，minisign）是硬需求：缺了客户端一律拒绝安装，
+ *   因此构建前要求凭据存在，构建后用内置公钥复核 `.sig` 才允许继续上传；
+ * - 未通过验签绝不写 OSS：上传顺序为更新包、签名、首装包，全部成功后才覆盖渠道清单指针。
+ */
+const appRoot = fileURLToPath(new URL('..', import.meta.url));
+const repoRoot = path.resolve(appRoot, '../..');
+
+/**
+ * 产品名只从 Tauri 配置读取：它同时决定 `*.app` 目录名、updater 归档名与 DMG 卷名。
+ * 写死会在改名后让入口静默找错对象（清理、打包、归档三处一起失效）。
+ */
+function readProductName() {
+  const read = (file) =>
+    JSON.parse(fs.readFileSync(path.join(appRoot, 'src-tauri', file), 'utf8'));
+  const base = read('tauri.conf.json');
+  const macosPath = path.join(appRoot, 'src-tauri', 'tauri.macos.conf.json');
+  const productName = fs.existsSync(macosPath)
+    ? (read('tauri.macos.conf.json').productName ?? base.productName)
+    : base.productName;
+  assert.ok(
+    typeof productName === 'string' && productName.trim().length > 0,
+    'Tauri 配置缺少 productName',
+  );
+  return productName;
+}
+
+const productName = readProductName();
+const appBundleName = `${productName}.app`;
+const updaterArtifactName = `${productName}.app.tar.gz`;
+assert.equal(process.platform, 'darwin', '只能在 macOS Agent 执行');
+assert.equal(
+  process.env.JENKINS_URL?.length > 0,
+  true,
+  '此入口仅用于 Jenkins 独立工作区',
+);
+assert.equal(
+  fs.realpathSync(process.env.WORKSPACE || '.'),
+  fs.realpathSync(repoRoot),
+  '必须在 Jenkins workspace 根目录执行',
+);
+const space = fs.statfsSync(repoRoot);
+assert.ok(
+  space.bavail * space.bsize >= 8 * 1024 ** 3,
+  '构建前至少需要 8 GiB 可用空间；禁止自动清理开发缓存',
+);
+
+// 仅剥离 Apple 签名/公证变量：本节点没有证书，误用只会让构建失败；
+// 更新包签名与 OSS 凭据必须保留，它们是本入口发布能力的组成部分。
+for (const key of Object.keys(process.env)) {
+  if (/^APPLE_/u.test(key)) delete process.env[key];
+}
+assert.ok(
+  process.env.TAURI_SIGNING_PRIVATE_KEY?.length > 0 ||
+    process.env.TAURI_SIGNING_PRIVATE_KEY_PATH?.length > 0,
+  '缺少更新包签名私钥（TAURI_SIGNING_PRIVATE_KEY / _PATH）：无签名的更新包会被客户端拒绝，禁止继续',
+);
+
+const bucket = process.env.AGC_OSS_BUCKET?.trim() || 'agc-dev';
+const endpoint =
+  process.env.AGC_OSS_ENDPOINT?.trim() || 'oss-rg-china-mainland.aliyuncs.com';
+if (!/^[a-z0-9][a-z0-9.-]{1,62}$/u.test(bucket) || /[\r\n\0]/u.test(endpoint)) {
+  throw new Error('OSS bucket 或 endpoint 配置无效');
+}
+process.env.AGC_UPDATE_OSS_BASE_URL ||= `https://${bucket}.${endpoint}/agc`;
+const dryRun = readReleaseDryRun();
+
+process.env.CARGO_TARGET_DIR = path.join(appRoot, 'src-tauri/target');
+const context = resolveReleaseContext(['--target=universal-apple-darwin']);
+const partition = resolveReleasePartition(context.channel, context.target);
+const version = await prepareReleaseVersion(context);
+// 首装包名必须保持 `<产品名>_<版本>_universal.dmg`：清单侧按该后缀唯一匹配本次产物。
+const firstInstallName = `${productName}_${version}_universal.dmg`;
+
+// 幂等边界：workspace 会保留上一轮产物。先删掉本次将要写出的对象，否则
+//  1) hdiutil 会因同名 DMG 已存在直接失败（首次实跑即命中）；
+//  2) 上一轮遗留的 `.sig` 会让验签门禁把「本轮其实没签」判成通过。
+// 只删本次要写出的确切路径，不动其它版本产物与编译缓存。
+const macosBundle = path.join(context.bundleRoot, 'macos');
+for (const stale of [
+  path.join(macosBundle, updaterArtifactName),
+  path.join(macosBundle, `${updaterArtifactName}.sig`),
+  path.join(macosBundle, `${firstInstallName}`),
+  path.join(macosBundle, `${firstInstallName}.sha256`),
+  path.join(context.bundleRoot, 'latest.json'),
+  path.join(context.bundleRoot, 'release-notes.txt'),
+]) {
+  fs.rmSync(stale, { force: true });
+}
+
+const args = [
+  '--target=universal-apple-darwin',
+  '--bundles',
+  'app',
+  '--ci',
+  // 刻意不传 `--no-sign`：它会连带跳过 updater 签名，而客户端强制校验更新包签名。
+  // Apple 侧改为剥离 APPLE_* 凭据，未配置身份时 Tauri 不签名也不失败。
+  // 基础配置已开启；这里显式声明，避免被其它配置来源关掉后静默失去更新能力。
+  '--config',
+  '{"bundle":{"createUpdaterArtifacts":true}}',
+];
+const command = (binary, argv, options = {}) =>
+  execFileSync(binary, argv, { cwd: repoRoot, stdio: 'inherit', ...options });
+runTauriBuild(args, context);
+
+const app = path.join(context.bundleRoot, 'macos', appBundleName);
+for (const architecture of ['arm64', 'x86_64']) {
+  command(process.execPath, [
+    path.join(appRoot, 'scripts/check-macos-bundle.mjs'),
+    app,
+    architecture,
+    '--universal',
+  ]);
+}
+
+// DMG 放在 bundle 根目录下：渠道清单的首装包选择会扫描该目录，命名必须匹配 `_<version>_universal.dmg`。
+const dmgDirectory = path.join(context.bundleRoot, 'macos');
+fs.mkdirSync(dmgDirectory, { recursive: true });
+const dmg = path.join(dmgDirectory, firstInstallName);
+const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'agc-ci-dmg-'));
+try {
+  command('ditto', [app, path.join(stage, appBundleName)]);
+  fs.symlinkSync('/Applications', path.join(stage, 'Applications'));
+  command('hdiutil', [
+    'create',
+    // 前面已删除同名对象；这里再要求显式覆盖，避免残留文件让构建以「文件已存在」失败。
+    '-ov',
+    '-volname',
+    productName,
+    '-srcfolder',
+    stage,
+    '-format',
+    'UDZO',
+    dmg,
+  ]);
+  command('hdiutil', ['verify', dmg]);
+} finally {
+  fs.rmSync(stage, { recursive: true, force: true });
+}
+
+const release = await generateUpdateManifest(context);
+assert.equal(
+  path.resolve(release.downloadArtifact),
+  path.resolve(dmg),
+  '首装包必须锁定本次生成的 universal DMG',
+);
+
+// 上传前门禁：用产物里烘焙的公钥复核更新包签名。验不过就停在这里，绝不写 OSS。
+const signature = verifyUpdaterSignature({
+  artifactPath: release.artifact,
+  signaturePath: `${release.artifact}.sig`,
+  pubkey: readUpdaterPubkey(),
+});
+console.log(
+  `[agc-macos] 更新包签名校验通过：alg=${signature.algorithm}，keyId=${signature.keyId}`,
+);
+
+const artifacts = path.join(repoRoot, 'artifacts');
+// 只清理本 Job 的归档输出，不能把上次 DMG 当成本次成功产物。
+fs.rmSync(artifacts, { recursive: true, force: true });
+fs.mkdirSync(artifacts, { recursive: true });
+const sha256 = (file) => {
+  const hash = createHash('sha256');
+  hash.update(fs.readFileSync(file));
+  return hash.digest('hex');
+};
+const dmgHash = sha256(dmg);
+fs.writeFileSync(`${dmg}.sha256`, `${dmgHash}  ${path.basename(dmg)}\n`);
+
+const uploadPlan = uploadReleaseArtifacts(release, {
+  bucket,
+  endpoint,
+  binary: process.env.OSSUTIL_BIN?.trim() || 'ossutil',
+  accessKeyId: process.env.AGC_OSS_ACCESS_KEY_ID?.trim(),
+  accessKeySecret: process.env.AGC_OSS_ACCESS_KEY_SECRET,
+  dryRun,
+});
+
+const archived = [
+  dmg,
+  `${dmg}.sha256`,
+  release.manifestPath,
+  release.notesPath,
+  `${release.artifact}.sig`,
+];
+for (const file of archived) {
+  fs.copyFileSync(file, path.join(artifacts, path.basename(file)));
+}
+
+const commit = execFileSync('git', ['rev-parse', 'HEAD'], {
+  cwd: repoRoot,
+  encoding: 'utf8',
+}).trim();
+// Apple 签名状态必须实测：剥离 APPLE_* 后 Tauri 通常跳过签名，但节点若装了 Developer ID
+// 证书仍可能签上，硬编码 appleSigned=false 会把「其实签了」写成假事实。
+const signatureProbe = spawnSync('codesign', ['-dv', '--verbose=2', app], {
+  encoding: 'utf8',
+});
+const signatureText = `${signatureProbe.stdout ?? ''}${signatureProbe.stderr ?? ''}`;
+const appleSigned = /Authority=Developer ID Application/u.test(signatureText);
+const appleSignatureKind = appleSigned
+  ? 'developer-id'
+  : /Signature=adhoc/u.test(signatureText)
+    ? 'adhoc'
+    : 'unsigned';
+fs.writeFileSync(
+  path.join(artifacts, 'build-manifest.json'),
+  `${JSON.stringify(
+    {
+      version,
+      commit,
+      target: context.target,
+      channel: context.channel,
+      // Apple 签名与公证暂缺：显式记录为未验证项，不静默通过。
+      appleSigned,
+      appleSignatureKind,
+      notarized: false,
+      dryRun,
+      uploaded: !dryRun,
+      updaterSignature: {
+        algorithm: signature.algorithm,
+        keyId: signature.keyId,
+        verified: true,
+      },
+      oss: {
+        bucket,
+        endpoint,
+        partition,
+        latest: `oss://${bucket}/agc/${partition}/latest.json`,
+        objects: uploadPlan.map(({ destination }) => destination),
+      },
+      artifacts: {
+        updater: path.basename(release.artifact),
+        updaterSha256: sha256(release.artifact),
+        updaterBytes: fs.statSync(release.artifact).size,
+        updaterSignature: path.basename(`${release.artifact}.sig`),
+        firstInstall: path.basename(dmg),
+        firstInstallSha256: dmgHash,
+        manifest: 'latest.json',
+      },
+      smokes: ['arm64', 'x86_64'],
+      intelSmoke: process.arch === 'arm64' ? 'Rosetta' : 'native',
+    },
+    null,
+    2,
+  )}\n`,
+);
+console.log(
+  dryRun
+    ? `[agc-macos] dry-run 完成：${partition} 分区产物与清单已生成，未写入 OSS`
+    : `[agc-macos] ${partition} 分区更新包、签名、首装包与清单已上传 OSS`,
+);

apps/ai-game-creator-shell/scripts/build-release.mjs

@@ -5,10 +5,15 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import {
+  assertRequestedVersionNotBelowChannel,
+  issueGlobalVersion as issueAgcGlobalVersion,
+} from './agc-global-version.mjs';
 import {
   defaultEditorFeatures,
   withDefaultCargoFeatures,
 } from './cargo-features.mjs';
+import { stageNodeRuntimeForTarget } from './stage-node-runtime.mjs';
 
 const appRoot = fileURLToPath(new URL('..', import.meta.url));
 // 提交摘要里的 pathspec 与 `git log` 都以仓库根为基准，不能在应用目录里执行。
@@ -42,16 +47,12 @@ function explicitBuildTarget(args) {
 }
 
 function validateReleaseTarget(target) {
-  if (target === 'universal-apple-darwin') {
-    throw new Error(
-      '内置 Codex 资源仅支持 macOS 单架构构建，请使用 aarch64-apple-darwin 或 x86_64-apple-darwin',
-    );
-  }
   if (
     ![
       'x86_64-pc-windows-msvc',
       'aarch64-apple-darwin',
       'x86_64-apple-darwin',
+      'universal-apple-darwin',
     ].includes(target)
   ) {
     throw new Error(`不支持的发布目标：${target}`);
@@ -68,7 +69,7 @@ export function resolveReleaseContext(args = [], env = process.env) {
   );
   return Object.freeze({
     target,
-    channel: resolveReleaseChannel(env, target),
+    channel: resolveReleaseChannel(env),
     bundleRoot: path.join(
       appRoot,
       'src-tauri',
@@ -87,14 +88,14 @@ const cargoLockPath = path.join(appRoot, 'src-tauri', 'Cargo.lock');
 const defaultOssBaseUrl =
   'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc';
 
-/**
- * 发布渠道 → 目标平台。渠道名会进入 OSS 路径并烘焙进客户端端点，
- * 一旦发布就不能改名（改名等于已发布客户端再也找不到更新）。
- */
-const releaseChannels = {
-  'dev-win': 'windows',
-  'dev-mac': 'darwin',
-};
+const reservedChannelNames = new Set([
+  'win',
+  'mac',
+  'windows',
+  'macos',
+  'darwin',
+  'linux',
+]);
 
 /**
  * 影响 Windows 客户端产物的路径。调度管线的发布范围判定与这里的提交摘要必须
@@ -163,46 +164,45 @@ export function resolveReleasePlatform(target = defaultTarget()) {
   throw new Error(`不支持的发布目标：${target}`);
 }
 
-export function resolveReleaseChannel(
-  env = process.env,
-  target = defaultTarget(),
-) {
-  const platform = resolveReleasePlatform(target);
-  const requested = env.AGC_UPDATE_CHANNEL?.trim();
-  if (requested) {
-    const channelPlatform = releaseChannels[requested];
-    if (!channelPlatform) {
-      throw new Error(
-        `未知发布渠道 ${requested}；当前支持：${Object.keys(releaseChannels).join('、')}`,
-      );
-    }
-    if (channelPlatform !== platform) {
-      throw new Error(
-        `渠道 ${requested} 只能用于 ${channelPlatform} 目标，当前构建目标为 ${target}`,
-      );
-    }
-    return requested;
-  }
-  const defaultChannel = Object.entries(releaseChannels).find(
-    ([, channelPlatform]) => channelPlatform === platform,
-  )?.[0];
-  if (!defaultChannel) {
+export function resolveReleaseChannel(env = process.env) {
+  const channel = env.AGC_UPDATE_CHANNEL?.trim() ?? 'dev';
+  if (
+    !/^[a-z][a-z0-9-]{0,31}$/u.test(channel) ||
+    channel.endsWith('-') ||
+    reservedChannelNames.has(channel) ||
+    /-(win|mac)$/u.test(channel)
+  ) {
     throw new Error(
-      `目标 ${target} 没有默认发布渠道，请显式设置 AGC_UPDATE_CHANNEL`,
+      '发布渠道无效：请使用 dev、release 或最多 32 位的小写字母、数字和连字符名称，系统名称不属于渠道',
     );
   }
-  return defaultChannel;
+  return channel;
 }
 
-export function updateManifestUrl(channel = resolveReleaseChannel()) {
-  return `${ossBaseUrl()}/${channel}/latest.json`;
+/** 系统分区延续已发布客户端端点，渠道本身不包含系统。 */
+export function resolveReleasePartition(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
+  channel = resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel });
+  validateReleaseTarget(target);
+  return `${channel}-${resolveReleasePlatform(target) === 'windows' ? 'win' : 'mac'}`;
+}
+
+export function updateManifestUrl(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
+  return `${ossBaseUrl()}/${resolveReleasePartition(channel, target)}/latest.json`;
 }
 
 /**
- * 单架构产物只登记实际目标，不能把同一原生资源映射为另一架构。
+ * universal 主程序与双目录原生资源共用一个更新包；单架构只登记实际目标。
  */
 export function resolveManifestPlatformKeys(target = defaultTarget()) {
   validateReleaseTarget(target);
+  if (target === 'universal-apple-darwin')
+    return ['darwin-aarch64', 'darwin-x86_64'];
   if (target === 'aarch64-apple-darwin') return ['darwin-aarch64'];
   if (target === 'x86_64-apple-darwin') return ['darwin-x86_64'];
   if (target.includes('windows')) {
@@ -246,8 +246,8 @@ async function readManifestVersion(manifestUrl, label) {
 }
 
 /** 上一次发布的渠道清单：拿版本做高水位、拿 commit 生成自动更新摘要。 */
-async function readRemoteChannelManifest(channel = resolveReleaseChannel()) {
-  return fetchManifest(updateManifestUrl(channel), 'OSS 渠道清单');
+async function readRemoteChannelManifest(channel, target) {
+  return fetchManifest(updateManifestUrl(channel, target), 'OSS 渠道清单');
 }
 
 /**
@@ -259,14 +259,17 @@ async function readRemoteChannelManifest(channel = resolveReleaseChannel()) {
  */
 export async function resolvePreviousReleaseCommit(
   channel = resolveReleaseChannel(),
-  { override = process.env.AGC_UPDATE_PREVIOUS_COMMIT } = {},
+  {
+    override = process.env.AGC_UPDATE_PREVIOUS_COMMIT,
+    target = defaultTarget(),
+  } = {},
 ) {
   const explicit = override?.trim();
   if (explicit && /^[0-9a-f]{7,40}$/u.test(explicit)) {
     return explicit;
   }
   try {
-    const manifest = await readRemoteChannelManifest(channel);
+    const manifest = await readRemoteChannelManifest(channel, target);
     const commit =
       typeof manifest?.commit === 'string' ? manifest.commit.trim() : '';
     return /^[0-9a-f]{7,40}$/u.test(commit) ? commit : null;
@@ -288,12 +291,14 @@ export async function resolvePreviousReleaseCommit(
  */
 export async function resolveRemoteHighWaterVersion(
   channel = resolveReleaseChannel(),
+  target = defaultTarget(),
 ) {
   const channelVersion = await readManifestVersion(
-    updateManifestUrl(channel),
+    updateManifestUrl(channel, target),
     'OSS 渠道清单',
   );
-  if (channel !== 'dev-win') return channelVersion;
+  if (channel !== 'dev' || resolveReleasePlatform(target) !== 'windows')
+    return channelVersion;
   const legacyVersion = await readManifestVersion(
     legacyBridgeManifestUrl(),
     'OSS 迁移指针',
@@ -310,14 +315,35 @@ function replaceVersionLine(source, version, pattern, label) {
   return source.replace(pattern, `$1${version}$3`);
 }
 
+/**
+ * 版本来源固定为 OSS 总版本号（`agc/global-version.json`）：
+ * - CI 统一构建由发号 Job 先发号，再通过 AGC_RELEASE_VERSION 透传给各渠道；
+ * - 未传入时（本地手工兜底）由本函数现场发号并写回总号；
+ * - 渠道高水位只做断言：传入号低于本渠道清单版本即失败关闭。
+ */
 export async function prepareReleaseVersion(context = resolveReleaseContext()) {
-  const { channel } = context;
+  const { channel, target } = context;
   const localVersion = parseVersion(readPackageJson().version, '本地版本');
-  const remoteVersion = await resolveRemoteHighWaterVersion(channel);
+  const remoteVersion = await resolveRemoteHighWaterVersion(channel, target);
   const requestedVersion = process.env.AGC_RELEASE_VERSION?.trim();
   const nextVersion = requestedVersion
-    ? parseVersion(requestedVersion, '指定版本')
-    : nextPatchVersion(localVersion, remoteVersion);
+    ? assertRequestedVersionNotBelowChannel({
+        requested: requestedVersion,
+        channelVersion: remoteVersion,
+        channel,
+      })
+    : await issueAgcGlobalVersion({
+        channel,
+        commit:
+          process.env.COMMIT_HASH?.trim() ||
+          process.env.GIT_COMMIT?.trim() ||
+          null,
+        buildId:
+          process.env.BUILD_NUMBER?.trim() ||
+          process.env.AGC_BUILD_ID?.trim() ||
+          null,
+        repoVersion: localVersion,
+      });
 
   const packageSource = fs.readFileSync(packageJsonPath, 'utf8');
   fs.writeFileSync(
@@ -376,8 +402,8 @@ export async function prepareReleaseVersion(context = resolveReleaseContext()) {
 
   console.log(
     requestedVersion
-      ? `[ai-game-creator-shell] 渠道 ${channel} 使用指定版本 ${nextVersion}（本地 ${localVersion} / OSS ${remoteVersion ?? '不存在'}）`
-      : `[ai-game-creator-shell] 渠道 ${channel} 版本 ${localVersion} / OSS ${remoteVersion ?? '不存在'} -> ${nextVersion}`,
+      ? `[ai-game-creator-shell] 渠道 ${channel} 使用发号 Job 下发的总号 ${nextVersion}（本渠道清单 ${remoteVersion ?? '不存在'} / 仓库 ${localVersion}）`
+      : `[ai-game-creator-shell] 渠道 ${channel} 本地兜底发号 ${nextVersion}（本渠道清单 ${remoteVersion ?? '不存在'} / 仓库 ${localVersion}）`,
   );
   return nextVersion;
 }
@@ -402,32 +428,39 @@ export function buildTauriBuildArguments(
 }
 
 /** 渠道端点必须由构建期注入：官方更新插件的端点配置不支持运行期改渠道。 */
-export function createChannelConfig(channel = resolveReleaseChannel()) {
+export function createChannelConfig(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
   return {
     plugins: {
       updater: {
-        endpoints: [updateManifestUrl(channel)],
+        endpoints: [updateManifestUrl(channel, target)],
       },
     },
   };
 }
 
-function writeChannelConfigFile(channel) {
+function writeChannelConfigFile(channel, target, includeNodeRuntime = false) {
   const configPath = path.join(
     os.tmpdir(),
-    `agc-tauri-channel-${channel}.json`,
-  );
-  fs.writeFileSync(
-    configPath,
-    `${JSON.stringify(createChannelConfig(channel), null, 2)}\n`,
+    `agc-tauri-channel-${channel}-${target}.json`,
   );
+  const config = createChannelConfig(channel, target);
+  // 普通 cargo test/dev 不要求发行资源；只有完成 staging 的发行构建加入映射。
+  if (includeNodeRuntime)
+    config.bundle = {
+      resources: { 'resources/node-runtime': 'game-runtime/node' },
+    };
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
   return configPath;
 }
 
 export function runTauriBuild(
   args = [],
   context = resolveReleaseContext(args),
-  { spawn = spawnSync } = {},
+  // 默认按发布目标 stage：universal 需要两份架构运行时，单架构目标行为不变。
+  { spawn = spawnSync, stageRuntime = stageNodeRuntimeForTarget } = {},
 ) {
   if (
     explicitBuildTarget(args) &&
@@ -436,8 +469,13 @@ export function runTauriBuild(
     throw new Error('构建参数与发布上下文目标不一致');
   }
   const tauriArguments = buildTauriBuildArguments(args, context.target);
-  const { channel } = context;
-  const configPath = writeChannelConfigFile(channel);
+  const { channel, target } = context;
+  if (!args.includes('--no-bundle')) stageRuntime(target);
+  const configPath = writeChannelConfigFile(
+    channel,
+    target,
+    !args.includes('--no-bundle'),
+  );
   console.log(
     `[ai-game-creator-shell] 渠道 ${channel} 端点配置：${configPath}`,
   );
@@ -453,7 +491,17 @@ export function runTauriBuild(
   const result = spawn(
     npmCommand,
     ['--prefix', '../..', 'exec', 'tauri', '--', ...tauriArguments],
-    { cwd: appRoot, stdio: 'inherit', shell: process.platform === 'win32' },
+    {
+      cwd: appRoot,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      env: {
+        ...process.env,
+        // Vite embeds the platform API origin in the packaged renderer. The
+        // release channel and updater channel therefore cannot drift apart.
+        VITE_AGC_PLATFORM_CHANNEL: channel,
+      },
+    },
   );
   if (result.error) throw result.error;
   if (result.status !== 0) process.exit(result.status ?? 1);
@@ -513,6 +561,18 @@ export function selectFirstInstallArtifact(
     if (!selected?.endsWith('.exe')) {
       throw new Error('Windows 首装包必须复用本次 NSIS .exe 更新包');
     }
+  } else if (target === 'universal-apple-darwin') {
+    // universal 主程序只产出一个 DMG，aarch64 与 x86_64 首装共用它（命名见 build-macos-ci.mjs）。
+    const suffix = `_${version}_universal.dmg`;
+    const candidates = files.filter((file) =>
+      path.basename(file).endsWith(suffix),
+    );
+    if (candidates.length !== 1) {
+      throw new Error(
+        `首装 DMG 必须唯一匹配本次版本 ${version} 的 universal 产物，找到 ${candidates.length} 个`,
+      );
+    }
+    selected = candidates[0];
   } else {
     // Tauri DMG 文件名使用 aarch64 / x64，而 updater 的 Intel 平台键是 x86_64。
     const architecture = target.startsWith('aarch64') ? 'aarch64' : 'x64';
@@ -553,7 +613,7 @@ export function createUpdateManifest(
   artifactPath,
   {
     target = defaultTarget(),
-    channel = resolveReleaseChannel(process.env, target),
+    channel = resolveReleaseChannel(),
     publishedAt = new Date().toISOString(),
     notes = readReleaseNotes(),
     commit = readHeadCommit(),
@@ -561,7 +621,7 @@ export function createUpdateManifest(
   } = {},
 ) {
   validateReleaseTarget(target);
-  resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel }, target);
+  const partition = resolveReleasePartition(channel, target);
   const signature = readUpdaterSignature(artifactPath);
   const version = readPackageJson().version;
   const firstInstallArtifact = selectFirstInstallArtifact(
@@ -569,8 +629,8 @@ export function createUpdateManifest(
     { target, version, artifact: artifactPath },
   );
   const fileName = path.basename(artifactPath);
-  const url = `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`;
-  const downloadUrl = `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(path.basename(firstInstallArtifact))}`;
+  const url = `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`;
+  const downloadUrl = `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(path.basename(firstInstallArtifact))}`;
   const platforms = {};
   const downloads = {};
   for (const key of resolveManifestPlatformKeys(target)) {
@@ -703,14 +763,22 @@ export function formatRecentReleaseNotes(commits) {
 /** 旧协议（sha256）清单：只用于把已发布客户端带到新渠道协议，一个版本周期后整条删除。 */
 export function createLegacyUpdateManifest(
   artifactPath,
-  { channel = resolveReleaseChannel(), notes = readReleaseNotes() } = {},
+  {
+    channel = resolveReleaseChannel(),
+    target = defaultTarget(),
+    notes = readReleaseNotes(),
+  } = {},
 ) {
+  const partition = resolveReleasePartition(channel, target);
+  if (partition !== 'dev-win') {
+    throw new Error('旧协议迁移清单只属于 dev 渠道的 Windows 系统');
+  }
   const bytes = fs.readFileSync(artifactPath);
   const version = readPackageJson().version;
   const fileName = path.basename(artifactPath);
   return {
     version,
-    downloadUrl: `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`,
+    downloadUrl: `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`,
     sha256: createHash('sha256').update(bytes).digest('hex'),
     size: bytes.length,
     ...(notes ? { releaseNotes: notes } : {}),
@@ -732,7 +800,9 @@ export async function generateUpdateManifest(
     artifact,
   });
   const manualNotes = readReleaseNotes();
-  const previousCommit = await resolvePreviousReleaseCommit(channel);
+  const previousCommit = await resolvePreviousReleaseCommit(channel, {
+    target,
+  });
   const commits = collectReleaseCommits(previousCommit);
   const recentCommits = previousCommit ? null : collectRecentReleaseCommits();
   const notes =
@@ -758,8 +828,8 @@ export async function generateUpdateManifest(
     notes ? `${notes}\n` : '（本次没有可用的更新摘要）\n',
   );
   const legacyManifest =
-    channel === 'dev-win'
-      ? createLegacyUpdateManifest(artifact, { channel, notes })
+    channel === 'dev' && resolveReleasePlatform(target) === 'windows'
+      ? createLegacyUpdateManifest(artifact, { channel, target, notes })
       : null;
   const legacyManifestPath = legacyManifest
     ? path.join(bundleRoot, 'legacy-latest.json')
@@ -790,6 +860,7 @@ export async function generateUpdateManifest(
   }
   return {
     channel,
+    target,
     artifact,
     downloadArtifact,
     manifest,

apps/ai-game-creator-shell/scripts/check-config.mjs

@@ -4,9 +4,25 @@ import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import ts from 'typescript';
 
+// 固定解析源码保留上游测试中的替换字符；必须同时核对原始字节与许可。
+execFileSync(
+  process.execPath,
+  [
+    '--test',
+    fileURLToPath(
+      new URL(
+        '../src-tauri/vendor/codex-patch-parser/upstream-integrity.test.mjs',
+        import.meta.url,
+      ),
+    ),
+  ],
+  { stdio: 'inherit' },
+);
+
 import {
   appIdentifier,
   defaultRealSwarmTestTask,
@@ -1313,6 +1329,18 @@ if (tauriConfig.identifier !== 'world.genarrative.ai-game-creator') {
 
 const expectedBundledDesignAgentResources = {
   'design-agent': 'design-agent',
+  ...Object.fromEntries(
+    [
+      'codex-patch-parser',
+      'codex-utils-path-uri',
+      'codex-utils-absolute-path',
+    ].flatMap((name) =>
+      ['LICENSE', 'NOTICE'].map((file) => [
+        `vendor/${name}/${file}`,
+        `licenses/${name}/${file}`,
+      ]),
+    ),
+  ),
 };
 const expectedBundledWindowsResources = {
   'resources/codex/win-x64/bin/codex.exe': 'coding-agent/win-x64/bin/codex.exe',
@@ -1336,7 +1364,7 @@ assert.deepEqual(
   'AI game creator shell base Tauri config must bundle the design-agent resource pack',
 );
 for (const key of Object.keys(tauriConfig.bundle?.resources ?? {})) {
-  if (String(key).includes('codex')) {
+  if (String(key).startsWith('resources/codex/')) {
     throw new Error(
       'AI game creator shell base Tauri config must not require Windows-only Codex resources',
     );
@@ -1365,18 +1393,20 @@ if (windowsTauriConfig.bundle?.useLocalToolsDir !== true) {
 assert.deepEqual(
   macosTauriConfig.bundle?.resources,
   Object.fromEntries([
-    ...[
-      'bin/codex',
-      'bin/codex-code-mode-host',
-      'codex-path/rg',
-      'codex-resources/zsh/bin/zsh',
-      'codex-package.json',
-      'NOTICE.md',
-      'manifest.json',
-    ].map((file) => [
-      `resources/codex/mac-native/${file}`,
-      `coding-agent/mac-native/${file}`,
-    ]),
+    ...['darwin-arm64', 'darwin-x64'].flatMap((arch) =>
+      [
+        'bin/codex',
+        'bin/codex-code-mode-host',
+        'codex-path/rg',
+        'codex-resources/zsh/bin/zsh',
+        'codex-package.json',
+        'NOTICE.md',
+        'manifest.json',
+      ].map((file) => [
+        `resources/codex/mac-native/${arch}/${file}`,
+        `coding-agent/mac-native/${arch}/${file}`,
+      ]),
+    ),
     ['resources/plugins', 'plugins'],
   ]),
   'macOS must bundle the complete native Codex layout and plugin workspace',

apps/ai-game-creator-shell/scripts/check-macos-bundle.mjs

@@ -8,6 +8,13 @@ import path from 'node:path';
 // 只操作临时复制品；不启动 GUI、不读取开发机凭据、不访问 Provider。
 assert.equal(process.platform, 'darwin', '此验证必须在 macOS 执行');
 const source = path.resolve(process.argv[2] || '');
+const architecture =
+  process.argv[3] || (process.arch === 'arm64' ? 'arm64' : 'x86_64');
+assert.ok(
+  ['arm64', 'x86_64'].includes(architecture),
+  '架构只接受 arm64 / x86_64',
+);
+const requireUniversal = process.argv.includes('--universal');
 assert.ok(
   source.endsWith('.app') && fs.statSync(source).isDirectory(),
   '请传入 .app 绝对路径',
@@ -15,7 +22,28 @@ assert.ok(
 const root = fs.realpathSync(
   fs.mkdtempSync(path.join(os.tmpdir(), 'agc-macos-bundle-')),
 );
-const app = path.join(root, '陶泥儿 隔离测试.app');
+// 产品名从传入的 .app 推导，不在校验脚本里写死；改名后校验对象仍指向同一个包。
+const appBundleName = path.basename(source);
+const app = path.join(root, `隔离-${appBundleName}`);
+// 侧车清单版本必须等于锁定的 @openai/codex 版本，避免两处固定版本漂移。
+const appPackage = JSON.parse(
+  fs.readFileSync(
+    path.join(
+      path.dirname(new URL(import.meta.url).pathname),
+      '../package.json',
+    ),
+    'utf8',
+  ),
+);
+const pinnedCodexVersion =
+  appPackage.dependencies?.['@openai/codex'] ??
+  appPackage.devDependencies?.['@openai/codex'] ??
+  appPackage.optionalDependencies?.['@openai/codex'];
+assert.match(
+  pinnedCodexVersion,
+  /^\d+\.\d+\.\d+$/u,
+  'package.json 必须锁定精确的 @openai/codex 版本',
+);
 const home = path.join(root, 'home');
 const config = path.join(root, 'config');
 const tmp = path.join(root, 'tmp');
@@ -31,15 +59,83 @@ const env = {
 };
 
 function run(command, args) {
-  const result = spawnSync(command, args, {
+  // 只强制被测应用切片；本机 Xcode 检查工具可能仅提供宿主架构。
+  const useSlice = command.startsWith(`${app}${path.sep}`);
+  const result = spawnSync(
+    useSlice ? '/usr/bin/arch' : command,
+    useSlice ? [`-${architecture}`, command, ...args] : args,
+    {
+      cwd: root,
+      env,
+      encoding: 'utf8',
+      timeout: 120_000,
+      maxBuffer: 1024 * 1024,
+    },
+  );
+  assert.ifError(result.error);
+  return result;
+}
+
+/**
+ * 单独执行随包 Node 分片：分片架构与宿主一致时直接跑，不一致时用 `arch` 强制
+ * （arm64 机器上的 x86_64 分片依赖 Rosetta，与 `.app` 双架构 smoke 的前提相同）。
+ */
+function runNodeSlice(directory, args) {
+  const native = process.arch === 'arm64' ? 'arm64' : 'x86_64';
+  const binary = path.join(directory, 'node');
+  const [command, argv] =
+    architecture === native
+      ? [binary, args]
+      : ['/usr/bin/arch', [`-${architecture}`, binary, ...args]];
+  const result = spawnSync(command, argv, {
     cwd: root,
     env,
     encoding: 'utf8',
-    timeout: 30_000,
+    timeout: 120_000,
     maxBuffer: 1024 * 1024,
   });
   assert.ifError(result.error);
-  return result;
+  assert.equal(
+    result.status,
+    0,
+    `${directory} 随包 Node 执行失败：${result.stderr || result.stdout}`,
+  );
+  return result.stdout.trim();
+}
+
+/**
+ * APFS 上优先用 `ditto --clone`：整包按区块克隆，秒级完成且几乎不占额外空间。
+ * 跨卷或非 APFS 时回退到真实复制；两种路径都必须产出可独立改动的副本，
+ * 因为「缺组件拒绝」用例会在副本里改名文件。
+ */
+function copyBundle(from, to) {
+  const cloned = spawnSync('/usr/bin/ditto', ['--clone', from, to], {
+    encoding: 'utf8',
+  });
+  if (
+    cloned.status === 0 &&
+    fs.existsSync(path.join(to, 'Contents/Info.plist'))
+  ) {
+    return 'clone';
+  }
+  fs.cpSync(from, to, { recursive: true });
+  return 'copy';
+}
+
+/** 可执行名以包内 Info.plist 为准：它是稳定契约，但没必要在校验脚本里重复硬编码。 */
+function readBundleExecutable(appPath) {
+  const plist = path.join(appPath, 'Contents/Info.plist');
+  const result = spawnSync(
+    '/usr/libexec/PlistBuddy',
+    ['-c', 'Print :CFBundleExecutable', plist],
+    { encoding: 'utf8' },
+  );
+  const name = (result.stdout ?? '').trim();
+  assert.ok(
+    name.length > 0,
+    `无法从 Info.plist 读取 CFBundleExecutable：${plist}`,
+  );
+  return name;
 }
 
 async function hashFile(file) {
@@ -60,7 +156,7 @@ async function handshake(executable) {
     await new Promise((resolve, reject) => {
       const timer = setTimeout(
         () => reject(new Error('app-server 初始化超时')),
-        15_000,
+        120_000,
       );
       const finish = (error) => {
         clearTimeout(timer);
@@ -127,23 +223,39 @@ async function handshake(executable) {
 }
 
 try {
-  fs.cpSync(source, app, { recursive: true });
+  const copiedWith = copyBundle(source, app);
   const resources = path.join(app, 'Contents/Resources');
-  const bundle = path.join(resources, 'coding-agent/mac-native');
+  const platform = architecture === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  const bundle = path.join(resources, 'coding-agent/mac-native', platform);
   const executable = path.join(bundle, 'bin/codex');
-  const main = path.join(
-    app,
-    'Contents/MacOS/genarrative-ai-game-creator-shell',
-  );
+  const main = path.join(app, 'Contents/MacOS', readBundleExecutable(app));
+  const mainArchitectures = run('/usr/bin/lipo', ['-archs', main]);
+  assert.equal(mainArchitectures.status, 0);
+  assert.ok(mainArchitectures.stdout.split(/\s+/).includes(architecture));
+  if (requireUniversal) {
+    assert.deepEqual(mainArchitectures.stdout.trim().split(/\s+/).sort(), [
+      'arm64',
+      'x86_64',
+    ]);
+    for (const platform of ['darwin-arm64', 'darwin-x64']) {
+      assert.ok(
+        fs.existsSync(
+          path.join(
+            resources,
+            'coding-agent/mac-native',
+            platform,
+            'manifest.json',
+          ),
+        ),
+      );
+    }
+  }
   const manifest = JSON.parse(
     fs.readFileSync(path.join(bundle, 'manifest.json'), 'utf8'),
   );
   assert.equal(manifest.schemaVersion, 'genarrative-codex-sidecar.v2');
-  assert.equal(
-    manifest.platform,
-    process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64',
-  );
-  assert.equal(manifest.version, 'codex-cli 0.147.0');
+  assert.equal(manifest.platform, platform);
+  assert.equal(manifest.version, `codex-cli ${pinnedCodexVersion}`);
   const components = [
     'bin/codex',
     'bin/codex-code-mode-host',
@@ -159,14 +271,88 @@ try {
       fs.accessSync(file, fs.constants.X_OK);
       const arch = run('/usr/bin/lipo', ['-archs', file]);
       assert.equal(arch.status, 0, component);
-      assert.equal(
-        arch.stdout.trim(),
-        process.arch === 'arm64' ? 'arm64' : 'x86_64',
-        component,
-      );
+      assert.equal(arch.stdout.trim(), architecture, component);
     }
   }
   assert.ok(fs.existsSync(path.join(bundle, 'NOTICE.md')));
+  // 随包 Node：单架构构建是扁平目录，universal 构建把两套架构运行时并列放进
+  // `game-runtime/node/<platform>-<arch>/`（与 Codex 侧车同形态，由 Rust 侧按运行架构选择）。
+  // 两套清单在本函数里都做完整性与架构校验；只执行与本次 smoke 架构一致的那一份，
+  // 另一份由另一次架构的 smoke 覆盖（build-macos-ci.mjs 会对 arm64 / x86_64 各跑一次）。
+  const nodeRoot = path.join(resources, 'game-runtime/node');
+  const nodeSlices = requireUniversal
+    ? ['darwin-arm64', 'darwin-x64'].map((platform) => ({
+        platform,
+        directory: path.join(nodeRoot, platform),
+      }))
+    : [{ platform: null, directory: nodeRoot }];
+  for (const slice of nodeSlices) {
+    const { directory } = slice;
+    const nodeManifest = JSON.parse(
+      fs.readFileSync(path.join(directory, 'manifest.json'), 'utf8'),
+    );
+    assert.equal(nodeManifest.schemaVersion, 'agc-node-runtime.v1');
+    assert.equal(nodeManifest.platform, 'darwin');
+    if (slice.platform) {
+      // 目录名与清单架构必须一致：错位会让用户拿到跑不起来的运行时。
+      assert.equal(`darwin-${nodeManifest.arch}`, slice.platform);
+      assert.ok(
+        /^(arm64|x64)$/u.test(nodeManifest.arch),
+        `未知运行架构：${nodeManifest.arch}`,
+      );
+    } else {
+      assert.equal(nodeManifest.arch, process.arch);
+    }
+    const runtimeFiles = fs
+      .readdirSync(directory, { recursive: true })
+      .filter(
+        (file) =>
+          fs.statSync(path.join(directory, file)).isFile() &&
+          file !== 'manifest.json',
+      );
+    assert.deepEqual(
+      runtimeFiles.sort(),
+      Object.keys(nodeManifest.files).sort(),
+      slice.platform ?? 'flat',
+    );
+    for (const [file, digest] of Object.entries(nodeManifest.files)) {
+      assert.equal(await hashFile(path.join(directory, file)), digest, file);
+    }
+    assert.ok(nodeManifest.files['NODE-LICENSE']);
+    assert.ok(nodeManifest.files['node_modules/npm/LICENSE']);
+    fs.accessSync(path.join(directory, 'node'), fs.constants.X_OK);
+    // 二进制本身必须是本分片的单一架构：官方发行版不做 universal，lipo 能直接证明。
+    const sliceArchitecture = spawnSync(
+      '/usr/bin/lipo',
+      ['-archs', path.join(directory, 'node')],
+      { encoding: 'utf8' },
+    );
+    assert.equal(sliceArchitecture.status, 0, 'lipo -archs node');
+    assert.equal(
+      sliceArchitecture.stdout.trim(),
+      nodeManifest.arch === 'x64' ? 'x86_64' : 'arm64',
+      '随包 Node 的二进制架构必须等于清单架构',
+    );
+    // 只有与本次 smoke 架构一致的分片才执行；另一架构留给对应的那次 smoke。
+    if (
+      !requireUniversal ||
+      nodeManifest.arch === (architecture === 'arm64' ? 'arm64' : 'x64')
+    ) {
+      assert.equal(
+        runNodeSlice(directory, ['--version']),
+        nodeManifest.nodeVersion,
+        `${slice.platform ?? 'flat'} node --version`,
+      );
+      assert.equal(
+        runNodeSlice(directory, [
+          path.join(directory, 'node_modules/npm/bin/npm-cli.js'),
+          '--version',
+        ]),
+        nodeManifest.npmVersion,
+        `${slice.platform ?? 'flat'} npm --version`,
+      );
+    }
+  }
   const plugin = path.join(resources, 'plugins/agc-cocos-editor');
   for (const file of [
     'plugin.json',
@@ -177,10 +363,18 @@ try {
   }
   const packageFiles = fs.readdirSync(resources, { recursive: true });
   assert.ok(
-    !packageFiles.some((file) =>
-      /(^|\/)(\.env[^/]*|auth\.json|node_modules|target|\.git)(\/|$)|\.(exe|dll)$/.test(
-        file,
-      ),
+    !packageFiles.some(
+      (file) =>
+        /(^|\/)(\.env[^/]*|auth\.json|target|\.git)(\/|$)|\.(exe|dll)$/.test(
+          file,
+        ) ||
+        // 只有随包 Node 自带的 npm 允许出现 node_modules；两种布局都要放行：
+        // 单架构的 `game-runtime/node/node_modules/npm` 与 universal 的
+        // `game-runtime/node/<platform>-<arch>/node_modules/npm`。
+        (/(^|\/)node_modules(\/|$)/.test(file) &&
+          !/^game-runtime\/node\/((darwin-(arm64|x64))\/)?node_modules\/npm(\/|$)/u.test(
+            file,
+          )),
     ),
   );
   assert.equal(run(executable, ['--version']).stdout.trim(), manifest.version);
@@ -212,7 +406,7 @@ try {
   assert.notEqual(broken.status, 0);
   assert.match(`${broken.stdout}\n${broken.stderr}`, /Codex CLI 未安装/);
   console.log(
-    'PASS: 隔离安装包资源、架构、摘要、权限、正式 Codex 查找、app-server 握手及缺组件拒绝',
+    `PASS (${architecture}, 副本=${copiedWith}): 隔离安装包资源、架构、摘要、权限、正式 Codex 查找、app-server 握手及缺组件拒绝`,
   );
   console.log(
     '未验证：GUI、真实登录/Provider 对话、Cocos macOS 原生桥接；插件 Node 仍为外部前提',

apps/ai-game-creator-shell/scripts/issue-global-version.mjs

@@ -0,0 +1,121 @@
+/**
+ * AGC 总版本号发号入口（CI 发号 Job 与本地手工兜底共用）。
+ *
+ * 用法：
+ *   node scripts/issue-global-version.mjs --channel dev-win [--commit <sha>] [--build-id <id>] [--out <file>]
+ *   node scripts/issue-global-version.mjs --seed-only
+ *   node scripts/issue-global-version.mjs --dry-run --channel dev-win   # 只预览，不写回、不烧号
+ *
+ * 输出固定为一行 `AGC_GLOBAL_VERSION=<version>`，便于 Jenkins 直接读取。
+ */
+import fs from 'node:fs';
+
+import {
+  issueGlobalVersion,
+  previewNextGlobalVersion,
+  readGlobalVersion,
+  readReleaseDryRun,
+  resolveSeedBaseline,
+  writeGlobalVersion,
+} from './agc-global-version.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    channel: '',
+    commit: '',
+    buildId: '',
+    repoVersion: '',
+    out: '',
+    seedOnly: false,
+    dryRun: readReleaseDryRun(),
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const readValue = (label) => {
+      const value = argv[index + 1];
+      if (value == null || value.startsWith('--')) {
+        throw new Error(`${label} 缺少取值`);
+      }
+      index += 1;
+      return value;
+    };
+    switch (arg) {
+      case '--channel':
+        options.channel = readValue('--channel');
+        break;
+      case '--commit':
+        options.commit = readValue('--commit');
+        break;
+      case '--build-id':
+        options.buildId = readValue('--build-id');
+        break;
+      case '--repo-version':
+        options.repoVersion = readValue('--repo-version');
+        break;
+      case '--out':
+        options.out = readValue('--out');
+        break;
+      case '--seed-only':
+        options.seedOnly = true;
+        break;
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+      default:
+        throw new Error(`未知参数：${arg}`);
+    }
+  }
+  return options;
+}
+
+function emit(version, options) {
+  console.log(`AGC_GLOBAL_VERSION=${version}`);
+  if (options.out) {
+    fs.writeFileSync(options.out, `${version}\n`, 'utf8');
+  }
+}
+
+const options = parseArgs(process.argv.slice(2));
+process.env.AGC_RELEASE_DRY_RUN = options.dryRun ? '1' : '0';
+
+if (options.seedOnly) {
+  const current = await readGlobalVersion();
+  if (current) {
+    console.log(
+      `[agc-global-version] 总号已存在（${current.version}），播种跳过；需要重新播种请先人工确认`,
+    );
+    emit(current.version, options);
+  } else {
+    const baseline = await resolveSeedBaseline({
+      repoVersion: options.repoVersion || null,
+    });
+    const payload = {
+      version: baseline,
+      updatedAt: new Date().toISOString(),
+      channel: options.channel || 'seed',
+      commit: options.commit || null,
+      buildId: options.buildId || null,
+    };
+    writeGlobalVersion(payload, { dryRun: options.dryRun });
+    console.log(
+      `[agc-global-version] 播种基线 ${baseline}（尚未发号，首发为下一位）`,
+    );
+    emit(baseline, options);
+  }
+} else if (options.dryRun) {
+  const preview = await previewNextGlobalVersion({
+    repoVersion: options.repoVersion || null,
+  });
+  console.log(
+    `[agc-global-version] 预览下一个总号 ${preview}（dry-run 不写回、不烧号）`,
+  );
+  emit(preview, options);
+} else {
+  const issued = await issueGlobalVersion({
+    channel: options.channel || 'manual',
+    commit: options.commit || null,
+    buildId: options.buildId || null,
+    repoVersion: options.repoVersion || null,
+  });
+  emit(issued, options);
+}

apps/ai-game-creator-shell/scripts/prepare-macos-codex.mjs

@@ -0,0 +1,134 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const appRoot = fileURLToPath(new URL('..', import.meta.url));
+const repoRoot = path.resolve(appRoot, '../..');
+const platforms = {
+  arm64: 'aarch64-apple-darwin',
+  x64: 'x86_64-apple-darwin',
+};
+
+export function lockedMacPackage(lock, arch, version) {
+  assert.ok(Object.hasOwn(platforms, arch), '未知 macOS 架构');
+  const alias = `@openai/codex-darwin-${arch}`;
+  const entry = lock.packages?.[`node_modules/${alias}`];
+  assert.equal(
+    entry?.version,
+    `${version}-darwin-${arch}`,
+    '原生依赖必须与应用锁定版本一致',
+  );
+  assert.deepEqual(entry.os, ['darwin']);
+  assert.deepEqual(entry.cpu, [arch]);
+  const url = new URL(entry.resolved);
+  assert.equal(url.protocol, 'https:');
+  assert.equal(
+    url.hostname,
+    'registry.npmjs.org',
+    '只下载锁定的官方 npm 原生包',
+  );
+  assert.equal(url.username + url.password + url.search + url.hash, '');
+  assert.match(entry.integrity, /^sha512-[A-Za-z0-9+/]+={0,2}$/);
+  return { alias, target: platforms[arch], ...entry };
+}
+
+export function verifyPackageIntegrity(bytes, expected) {
+  const actual = `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+  assert.equal(actual, expected, 'Codex 下载包 lockfile integrity 不匹配');
+}
+
+export function validateArchiveListing(listing) {
+  const files = listing.trim().split(/\r?\n/u);
+  assert.ok(files.length > 0);
+  for (const file of files) {
+    assert.ok(file.startsWith('package/'), '原生包必须只有 package 根目录');
+    assert.ok(
+      !file.split('/').includes('..') && !file.includes('\\'),
+      '压缩包路径不安全',
+    );
+  }
+}
+
+export async function prepareMacosCodex() {
+  assert.equal(process.platform, 'darwin', '该入口仅用于 macOS 构建机');
+  const lock = JSON.parse(
+    fs.readFileSync(path.join(repoRoot, 'package-lock.json'), 'utf8'),
+  );
+  const app = JSON.parse(
+    fs.readFileSync(path.join(appRoot, 'package.json'), 'utf8'),
+  );
+  const version = app.devDependencies['@openai/codex'];
+  assert.match(version, /^\d+\.\d+\.\d+$/u, 'Codex 必须锁定精确版本');
+  const cache = path.join(appRoot, 'src-tauri/target/.macos-native-cache');
+  fs.mkdirSync(cache, { recursive: true });
+  for (const arch of Object.keys(platforms)) {
+    const entry = lockedMacPackage(lock, arch, version);
+    const archive = path.join(cache, `codex-${entry.version}.tgz`);
+    if (!fs.existsSync(archive)) {
+      const response = await fetch(entry.resolved, {
+        signal: AbortSignal.timeout(300_000),
+      });
+      assert.ok(response.ok, `原生包下载失败 HTTP ${response.status}`);
+      const bytes = Buffer.from(await response.arrayBuffer());
+      verifyPackageIntegrity(bytes, entry.integrity);
+      const partial = `${archive}.${process.pid}.tmp`;
+      fs.writeFileSync(partial, bytes);
+      fs.renameSync(partial, archive);
+    }
+    verifyPackageIntegrity(fs.readFileSync(archive), entry.integrity);
+    validateArchiveListing(
+      execFileSync('tar', ['-tzf', archive], { encoding: 'utf8' }),
+    );
+    // 拒绝链接、设备及其它特殊条目，不能让 tar 在包目录之外写入。
+    const entries = execFileSync('tar', ['-tvzf', archive], {
+      encoding: 'utf8',
+    });
+    assert.ok(
+      entries
+        .trim()
+        .split(/\r?\n/u)
+        .every((line) => /^[-d]/u.test(line)),
+      '原生包禁止链接或特殊文件',
+    );
+    const parent = path.join(repoRoot, 'node_modules/@openai');
+    fs.mkdirSync(parent, { recursive: true });
+    const stage = fs.mkdtempSync(path.join(parent, '.mac-native-'));
+    try {
+      execFileSync(
+        'tar',
+        ['-xzf', archive, '-C', stage, '--strip-components=1'],
+        { stdio: 'pipe' },
+      );
+      const metadata = JSON.parse(
+        fs.readFileSync(
+          path.join(stage, 'vendor', entry.target, 'codex-package.json'),
+          'utf8',
+        ),
+      );
+      assert.equal(metadata.version, version);
+      assert.equal(metadata.target, entry.target);
+      assert.equal(metadata.entrypoint, 'bin/codex');
+      const destination = path.join(repoRoot, 'node_modules', entry.alias);
+      assert.ok(
+        !fs.existsSync(destination) ||
+          !fs.lstatSync(destination).isSymbolicLink(),
+        '拒绝覆盖链接依赖',
+      );
+      fs.rmSync(destination, { recursive: true, force: true });
+      fs.renameSync(stage, destination);
+    } finally {
+      fs.rmSync(stage, { recursive: true, force: true });
+    }
+    console.log(`[macOS Codex] ${entry.version}: lockfile integrity 已验证`);
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  await prepareMacosCodex();
+}

apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs

@@ -0,0 +1,197 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { test } from 'node:test';
+
+import {
+  lockedMacPackage,
+  validateArchiveListing,
+  verifyPackageIntegrity,
+} from './prepare-macos-codex.mjs';
+
+const lock = JSON.parse(
+  fs.readFileSync(new URL('../../../package-lock.json', import.meta.url)),
+);
+const version = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url)),
+).devDependencies['@openai/codex'];
+
+test('both macOS dependencies resolve from the lockfile without floating versions', () => {
+  assert.equal(
+    lockedMacPackage(lock, 'arm64', version).target,
+    'aarch64-apple-darwin',
+  );
+  assert.equal(
+    lockedMacPackage(lock, 'x64', version).target,
+    'x86_64-apple-darwin',
+  );
+  assert.throws(() => lockedMacPackage(lock, 'other', version));
+  assert.throws(() => lockedMacPackage(lock, 'x64', '0.0.0'));
+});
+
+test('native package integrity rejects tampering', () => {
+  const bytes = Buffer.from('pinned package');
+  const integrity = `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+  verifyPackageIntegrity(bytes, integrity);
+  assert.throws(() =>
+    verifyPackageIntegrity(Buffer.from('modified'), integrity),
+  );
+});
+
+test('archive traversal and non-package entries fail closed', () => {
+  validateArchiveListing(
+    'package/package.json\npackage/vendor/target/bin/codex\n',
+  );
+  for (const listing of [
+    '',
+    '/tmp/payload',
+    'package/../private',
+    'other/file',
+    'package/..\\file',
+  ]) {
+    assert.throws(() => validateArchiveListing(listing));
+  }
+});
+
+test('CI pipeline is manual, publishes the macOS partition and never reuses a developer workspace', () => {
+  const pipeline = fs.readFileSync(
+    new URL(
+      '../../../jenkins/Jenkinsfile.ai-game-creator-shell-macos-build',
+      import.meta.url,
+    ),
+    'utf8',
+  );
+  for (const required of [
+    'genarrative-agc-macos',
+    'disableConcurrentBuilds()',
+    '$AGC_AGENT_ROOT',
+    'StrictHostKeyChecking=yes',
+    'git merge-base --is-ancestor',
+    'allowEmptyArchive: false',
+    "string(name: 'AGC_UPDATE_CHANNEL', defaultValue: 'dev'",
+    'AGC_UPDATE_CHANNEL=${params.AGC_UPDATE_CHANNEL}',
+    "string(credentialsId: 'AgcUpdaterSigningKey'",
+    "string(credentialsId: 'AgcUpdaterSigningKeyPassword'",
+    "string(credentialsId: 'AliyunAccessKeyId'",
+    "string(credentialsId: 'AliyunaccessKeySecret'",
+    'AGC_RELEASE_VERSION',
+    'OSSUTIL_BIN',
+    // 并行度必须可调：节点是共用机器，写死容易把整机压满或反过来浪费一半核心。
+    "string(name: 'CARGO_BUILD_JOBS', defaultValue: '8'",
+    'CARGO_BUILD_JOBS=${params.CARGO_BUILD_JOBS}',
+    // Agent 工作区按约定匹配，不写死节点名：节点改名（-local → -01）后守卫仍成立。
+    '"$HOME"/Library/Jenkins/agents/*/workspace/*',
+    // 上一次发布的 commit 落在 master 上，取到它更新摘要才不会退化成「最近提交」。
+    'refs/heads/master:refs/remotes/origin/master',
+  ]) {
+    assert.ok(pipeline.includes(required), required);
+  }
+  assert.ok(
+    !pipeline.includes('genarrative-agc-macos-local'),
+    'Jenkinsfile 不得写死具体节点名',
+  );
+  // 这条管线是正式发布入口（与 Windows 对称）：默认真发布，演练需显式勾选。
+  assert.match(
+    pipeline,
+    /booleanParam\(name: 'AGC_RELEASE_DRY_RUN', defaultValue: false/u,
+    'Channel 发布默认必须是真发布，演练只能显式勾选',
+  );
+  // 节点是办公机：离线期间排队的旧构建必须自行让位，且跳过要覆盖后续全部阶段。
+  assert.match(
+    pipeline,
+    /booleanParam\(name: 'SKIP_IF_SUPERSEDED', defaultValue: false/u,
+  );
+  // 仓库文件不得出现节点用户名/个人 Home 路径：换机或改名后必须仍然可用。
+  assert.ok(
+    !pipeline.includes('/Users/'),
+    'Jenkinsfile 不得写死个人 Home 路径，工具链位置应按 $HOME 展开',
+  );
+  assert.ok(
+    pipeline.includes('export PATH="$HOME/'),
+    'PATH 必须在 shell 步骤里按 $HOME 展开',
+  );
+  // 超时必须高于实测最慢（78 分钟冷构建 + 共用机器），否则会被中断在链接阶段。
+  assert.ok(
+    pipeline.includes('timeout(time: 150'),
+    '构建超时上限必须留出冷构建余量',
+  );
+  for (const diagnostic of ['macOS 发布失败', '被中断']) {
+    assert.ok(pipeline.includes(diagnostic), diagnostic);
+  }
+  assert.ok(
+    pipeline.includes('.jenkins-superseded-by'),
+    '必须记录被推进的标记供后续阶段判定',
+  );
+  assert.equal(
+    (pipeline.match(/env\.AGC_BUILD_SUPERSEDED != 'true'/gu) ?? []).length,
+    3,
+    'Toolchain / Package / Archive 三个阶段都必须按跳过标记收口',
+  );
+  for (const forbidden of [
+    'triggers {',
+    'cron(',
+    'pollSCM(',
+    'git clean -fdx',
+    // release:upload 会重新触发一次完整构建，既翻倍耗时也绕过本 Job 的验签门禁。
+    'release:upload',
+  ]) {
+    assert.ok(!pipeline.includes(forbidden), forbidden);
+  }
+});
+
+test('macOS release entry verifies the updater signature before uploading', () => {
+  const entry = fs.readFileSync(
+    new URL('./build-macos-ci.mjs', import.meta.url),
+    'utf8',
+  );
+  const verifyIndex = entry.indexOf('verifyUpdaterSignature({');
+  const uploadIndex = entry.indexOf('uploadReleaseArtifacts(release');
+  assert.ok(verifyIndex > 0, '必须调用更新包验签');
+  assert.ok(uploadIndex > 0, '必须调用 OSS 上传');
+  assert.ok(verifyIndex < uploadIndex, '必须先验签再上传，验不过不得写 OSS');
+  // 无签名私钥时禁止构建：未签名的更新包会被客户端一律拒绝。
+  assert.ok(entry.includes('TAURI_SIGNING_PRIVATE_KEY'));
+  // `--no-sign` 会连带跳过 updater 的 minisign 签名，产物将没有 .sig，入口不得传它。
+  assert.ok(
+    !entry.includes("'--no-sign'"),
+    '--no-sign 会同时跳过 updater 签名，产物缺少 .sig',
+  );
+  // workspace 会跨构建保留产物：必须先删本次要写的对象，否则会因同名 DMG 失败，
+  // 或让上一轮遗留的 .sig 让验签门禁误通过。
+  for (const required of [
+    // 清理对象用派生的产品名算出来，而不是写死某个名字。
+    '${updaterArtifactName}.sig',
+    '${firstInstallName}.sha256',
+    'fs.rmSync(stale, { force: true })',
+    "'-ov'",
+  ]) {
+    assert.ok(entry.includes(required), required);
+  }
+});
+
+test('macOS release entry and smoke script derive product names from config and the bundle', () => {
+  const entry = fs.readFileSync(
+    new URL('./build-macos-ci.mjs', import.meta.url),
+    'utf8',
+  );
+  // 产品名决定 *.app、updater 归档与 DMG 卷名：写死会在改名后静默找错对象。
+  assert.ok(entry.includes('readProductName'), '入口必须从 Tauri 配置读产品名');
+  assert.ok(!entry.includes('陶泥儿'), 'macOS 发布入口不得写死产品名');
+  assert.ok(
+    entry.includes('_${version}_universal.dmg'),
+    '首装包名必须保留清单侧唯一匹配所需的后缀',
+  );
+
+  const smoke = fs.readFileSync(
+    new URL('./check-macos-bundle.mjs', import.meta.url),
+    'utf8',
+  );
+  assert.ok(!smoke.includes('陶泥儿'), '校验脚本不得写死产品名');
+  for (const required of [
+    'path.basename(source)',
+    'Print :CFBundleExecutable',
+    "'--clone'",
+  ]) {
+    assert.ok(smoke.includes(required), required);
+  }
+});

apps/ai-game-creator-shell/scripts/read-installed-node-license.ps1

@@ -0,0 +1,95 @@
+# 只读取 Windows Installer 已登记的同版本 Node.js 缓存；不执行安装、不访问网络。
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$expectedVersion = $env:AGC_STAGING_NODE_VERSION
+if ($expectedVersion -notmatch '^\d+\.\d+\.\d+$') { throw 'Invalid Node version' }
+
+# WinVerifyTrust 强制仅使用本地证书缓存，禁止吊销/证书 URL 网络检索。
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class AgcOfflineSignature {
+    [StructLayout(LayoutKind.Sequential)]
+    struct FileInfo { public uint Size; public IntPtr Path; public IntPtr File; public IntPtr Subject; }
+    [StructLayout(LayoutKind.Sequential)]
+    struct TrustData {
+        public uint Size; public IntPtr Policy; public IntPtr Sip; public uint Ui;
+        public uint Revocation; public uint Choice; public IntPtr File;
+        public uint StateAction; public IntPtr State; public IntPtr Url;
+        public uint Flags; public uint Context;
+    }
+    [DllImport("wintrust.dll", ExactSpelling=true, PreserveSig=true)]
+    static extern int WinVerifyTrust(IntPtr window, ref Guid action, ref TrustData data);
+    public static bool Verify(string path) {
+        IntPtr name = Marshal.StringToCoTaskMemUni(path);
+        IntPtr file = Marshal.AllocHGlobal(Marshal.SizeOf(typeof(FileInfo)));
+        try {
+            var info = new FileInfo { Size=(uint)Marshal.SizeOf(typeof(FileInfo)), Path=name };
+            Marshal.StructureToPtr(info, file, false);
+            var data = new TrustData { Size=(uint)Marshal.SizeOf(typeof(TrustData)), Ui=2, Choice=1, File=file, Flags=0x1000|0x10 };
+            var action = new Guid("00AAC56B-CD44-11d0-8CC2-00C04FC295EE");
+            return WinVerifyTrust(new IntPtr(-1), ref action, ref data) == 0;
+        } finally { Marshal.FreeHGlobal(file); Marshal.FreeCoTaskMem(name); }
+    }
+}
+'@
+
+function Read-Property($database, [string]$name) {
+    $view = $database.OpenView("SELECT ``Value`` FROM ``Property`` WHERE ``Property`` = '$name'")
+    try {
+        [void]$view.Execute()
+        $record = $view.Fetch()
+        if ($null -ne $record) { return $record.StringData(1) }
+        return ''
+    } finally { [void]$view.Close() }
+}
+
+$installer = New-Object -ComObject WindowsInstaller.Installer
+$cacheRoot = [System.IO.Path]::GetFullPath((Join-Path ([Environment]::GetFolderPath('Windows')) 'Installer'))
+$registrations = @(
+    'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*',
+    'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*',
+    'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*'
+)
+$products = Get-ItemProperty $registrations -ErrorAction SilentlyContinue |
+    Where-Object { $_.DisplayName -eq 'Node.js' -and $_.DisplayVersion -eq $expectedVersion -and $_.PSChildName -match '^\{[0-9A-Fa-f-]{36}\}$' } |
+    Select-Object -ExpandProperty PSChildName -Unique
+foreach ($product in $products) {
+    try {
+        if ($installer.ProductInfo($product, 'ProductName') -ne 'Node.js') { continue }
+        if ($installer.ProductInfo($product, 'VersionString') -ne $expectedVersion) { continue }
+        $package = [System.IO.Path]::GetFullPath($installer.ProductInfo($product, 'LocalPackage'))
+        if (-not [string]::Equals([System.IO.Path]::GetDirectoryName($package), $cacheRoot, [StringComparison]::OrdinalIgnoreCase)) { continue }
+        if ([System.IO.Path]::GetExtension($package) -ne '.msi') { continue }
+        $entry = Get-Item -LiteralPath $package -Force
+        $cache = Get-Item -LiteralPath $cacheRoot -Force
+        if (($entry.Attributes -band [IO.FileAttributes]::ReparsePoint) -or ($cache.Attributes -band [IO.FileAttributes]::ReparsePoint)) { continue }
+        if (-not [AgcOfflineSignature]::Verify($package)) { continue }
+        $certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new([System.Security.Cryptography.X509Certificates.X509Certificate]::CreateFromSignedFile($package))
+        if ($certificate.Subject -notmatch '(^|,\s*)O=OpenJS Foundation(,|$)') { continue }
+        $database = $installer.OpenDatabase($package, 0)
+        if ((Read-Property $database 'ProductName') -ne 'Node.js') { continue }
+        if ((Read-Property $database 'ProductVersion') -ne $expectedVersion) { continue }
+        if ((Read-Property $database 'ProductCode') -ne $product) { continue }
+        $manufacturer = Read-Property $database 'Manufacturer'
+        if ($manufacturer -notin @('Node.js Foundation', 'OpenJS Foundation')) { continue }
+        $view = $database.OpenView('SELECT `Text` FROM `Control` WHERE `Dialog_` = ''LicenseAgreementDlg'' AND `Control` = ''LicenseText''')
+        try {
+            [void]$view.Execute()
+            $record = $view.Fetch()
+            if ($null -eq $record) { continue }
+            $content = $record.StringData(1)
+        } finally { [void]$view.Close() }
+        if (-not $content.StartsWith('{\rtf') -or $content.Length -gt 1048576) { continue }
+        if (-not $content.Contains('Node.js') -or -not $content.Contains('Permission is hereby granted')) { continue }
+        [pscustomobject]@{
+            productName = 'Node.js'; version = $expectedVersion; manufacturer = $manufacturer
+            signatureVerified = $true; signer = 'OpenJS Foundation'; format = 'rtf'; content = $content
+        } | ConvertTo-Json -Compress
+        exit 0
+    } catch {
+        # 单个损坏/无权限缓存不能绕过验证；继续查找其它已登记候选。
+        continue
+    }
+}
+throw 'No matching trusted installed Node.js license'