合并主线并保留资源kind枚举收口

合并 origin/master 的 AGC 画布参考与项目能力更新

解决 canvas 生成恢复与任务模型冲突并继续使用共享 GameCreationAppAssetKind

保留 run_id、generationKind 与外部协议字符串的独立边界

.gitignore

@@ -41,6 +41,12 @@ temp*build*/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/codex-resources/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/codex-package.json
 /apps/ai-game-creator-shell/src-tauri/resources/plugins/
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/bin/
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-path/
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-resources/
+/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
 /plugins/agc-cocos-editor/native/payload/
 /apps/ai-game-creator-shell/logs/
 /apps/ai-game-creator-shell/.llm-drafts/

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

@@ -1,7 +1,7 @@
 {
   "name": "@genarrative/ai-game-creator-shell",
   "private": true,
-  "version": "0.1.47",
+  "version": "0.1.67",
   "type": "module",
   "scripts": {
     "dev": "node scripts/start-tauri-dev.mjs",

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

@@ -14,16 +14,71 @@ const appRoot = fileURLToPath(new URL('..', import.meta.url));
 // 提交摘要里的 pathspec 与 `git log` 都以仓库根为基准，不能在应用目录里执行。
 const repoRoot = path.resolve(appRoot, '..', '..');
 const defaultReleaseTarget = 'x86_64-pc-windows-msvc';
-const releaseTarget =
-  process.env.AGC_BUILD_TARGET?.trim() || defaultReleaseTarget;
-const bundleRoot = path.join(
-  appRoot,
-  'src-tauri',
-  'target',
-  releaseTarget,
-  'release',
-  'bundle',
-);
+function defaultTarget() {
+  return process.env.AGC_BUILD_TARGET?.trim() || defaultReleaseTarget;
+}
+
+function explicitBuildTarget(args) {
+  let target;
+  const separator = args.indexOf('--');
+  const options = separator < 0 ? args : args.slice(0, separator);
+  for (let index = 0; index < options.length; index += 1) {
+    const argument = options[index];
+    let value;
+    if (argument === '--target' || argument === '-t') {
+      value = options[++index];
+    } else if (argument.startsWith('--target=')) {
+      value = argument.slice('--target='.length);
+    } else {
+      continue;
+    }
+    if (!value?.trim() || value.startsWith('-')) {
+      throw new Error('--target 缺少有效目标');
+    }
+    if (target !== undefined) throw new Error('不能重复指定 --target');
+    target = value.trim();
+  }
+  return target;
+}
+
+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',
+    ].includes(target)
+  ) {
+    throw new Error(`不支持的发布目标：${target}`);
+  }
+  return target;
+}
+
+/** 在入口冻结目标；所有发布步骤共享同一上下文，不再各自读取默认目标。 */
+export function resolveReleaseContext(args = [], env = process.env) {
+  const target = validateReleaseTarget(
+    explicitBuildTarget(args) ||
+      env.AGC_BUILD_TARGET?.trim() ||
+      defaultReleaseTarget,
+  );
+  return Object.freeze({
+    target,
+    channel: resolveReleaseChannel(env, target),
+    bundleRoot: path.join(
+      appRoot,
+      'src-tauri',
+      'target',
+      target,
+      'release',
+      'bundle',
+    ),
+  });
+}
 const packageJsonPath = path.join(appRoot, 'package.json');
 const rootPackageLockPath = path.resolve(appRoot, '../..', 'package-lock.json');
 const tauriConfigPath = path.join(appRoot, 'src-tauri', 'tauri.conf.json');
@@ -99,7 +154,7 @@ export function nextPatchVersion(localVersion, remoteVersion) {
   return `${major}.${minor}.${patch + 1}`;
 }
 
-export function resolveReleasePlatform(target = releaseTarget) {
+export function resolveReleasePlatform(target = defaultTarget()) {
   if (target.includes('windows')) return 'windows';
   if (target.includes('apple-darwin')) return 'darwin';
   if (target.includes('linux')) return 'linux';
@@ -108,7 +163,7 @@ export function resolveReleasePlatform(target = releaseTarget) {
 
 export function resolveReleaseChannel(
   env = process.env,
-  target = releaseTarget,
+  target = defaultTarget(),
 ) {
   const platform = resolveReleasePlatform(target);
   const requested = env.AGC_UPDATE_CHANNEL?.trim();
@@ -142,13 +197,10 @@ export function updateManifestUrl(channel = resolveReleaseChannel()) {
 }
 
 /**
- * 更新插件按运行时平台键查找清单条目：universal macOS 包同时挂
- * `darwin-aarch64` 与 `darwin-x86_64`，单架构目标只挂对应键。
+ * 单架构产物只登记实际目标，不能把同一原生资源映射为另一架构。
  */
-export function resolveManifestPlatformKeys(target = releaseTarget) {
-  if (target === 'universal-apple-darwin') {
-    return ['darwin-aarch64', 'darwin-x86_64'];
-  }
+export function resolveManifestPlatformKeys(target = defaultTarget()) {
+  validateReleaseTarget(target);
   if (target === 'aarch64-apple-darwin') return ['darwin-aarch64'];
   if (target === 'x86_64-apple-darwin') return ['darwin-x86_64'];
   if (target.includes('windows')) {
@@ -256,8 +308,8 @@ function replaceVersionLine(source, version, pattern, label) {
   return source.replace(pattern, `$1${version}$3`);
 }
 
-export async function prepareReleaseVersion() {
-  const channel = resolveReleaseChannel();
+export async function prepareReleaseVersion(context = resolveReleaseContext()) {
+  const { channel } = context;
   const localVersion = parseVersion(readPackageJson().version, '本地版本');
   const remoteVersion = await resolveRemoteHighWaterVersion(channel);
   const requestedVersion = process.env.AGC_RELEASE_VERSION?.trim();
@@ -330,18 +382,14 @@ export async function prepareReleaseVersion() {
 
 export function buildTauriBuildArguments(
   args = [],
-  target = releaseTarget,
+  target = defaultTarget(),
   platform = process.platform,
 ) {
   const noBundle = args.includes('--no-bundle');
-  const targetIndex = args.indexOf('--target');
-  const explicitTarget =
-    targetIndex >= 0
-      ? args[targetIndex + 1]
-      : args
-          .find((value) => value.startsWith('--target='))
-          ?.slice('--target='.length);
+  const explicitTarget = explicitBuildTarget(args);
   const targetArgs = noBundle || explicitTarget ? [] : ['--target', target];
+  if (!noBundle || explicitTarget)
+    validateReleaseTarget(explicitTarget || target);
   const features = defaultEditorFeatures(
     explicitTarget || (noBundle ? platform : target),
   );
@@ -374,18 +422,33 @@ function writeChannelConfigFile(channel) {
   return configPath;
 }
 
-export function runTauriBuild(args = []) {
-  const tauriArguments = buildTauriBuildArguments(args);
-  if (!tauriArguments.includes('--config') && !tauriArguments.includes('-c')) {
-    const channel = resolveReleaseChannel();
-    const configPath = writeChannelConfigFile(channel);
-    console.log(
-      `[ai-game-creator-shell] 渠道 ${channel} 端点配置：${configPath}`,
-    );
-    tauriArguments.push('--config', configPath);
+export function runTauriBuild(
+  args = [],
+  context = resolveReleaseContext(args),
+  { spawn = spawnSync } = {},
+) {
+  if (
+    explicitBuildTarget(args) &&
+    explicitBuildTarget(args) !== context.target
+  ) {
+    throw new Error('构建参数与发布上下文目标不一致');
   }
+  const tauriArguments = buildTauriBuildArguments(args, context.target);
+  const { channel } = context;
+  const configPath = writeChannelConfigFile(channel);
+  console.log(
+    `[ai-game-creator-shell] 渠道 ${channel} 端点配置：${configPath}`,
+  );
+  // 最后合并渠道配置，防止用户配置中的端点与实际发布目标分叉。
+  const separator = tauriArguments.indexOf('--');
+  tauriArguments.splice(
+    separator < 0 ? tauriArguments.length : separator,
+    0,
+    '--config',
+    configPath,
+  );
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const result = spawnSync(
+  const result = spawn(
     npmCommand,
     ['--prefix', '../..', 'exec', 'tauri', '--', ...tauriArguments],
     { cwd: appRoot, stdio: 'inherit', shell: process.platform === 'win32' },
@@ -402,11 +465,11 @@ function listFiles(root) {
   });
 }
 
-function artifactPriority(filePath) {
+function artifactPriority(filePath, target) {
   const name = path.basename(filePath).toLowerCase();
-  if (releaseTarget.includes('windows')) return name.endsWith('.exe') ? 0 : 99;
+  if (target.includes('windows')) return name.endsWith('.exe') ? 0 : 99;
   // 更新链路要的是 updater 产物（macOS 为 .app.tar.gz），dmg 只作人工分发。
-  if (releaseTarget.includes('apple-darwin')) {
+  if (target.includes('apple-darwin')) {
     return name.endsWith('.app.tar.gz') ? 0 : 99;
   }
   if (name.endsWith('.appimage.tar.gz')) return 0;
@@ -416,7 +479,8 @@ function artifactPriority(filePath) {
   return 99;
 }
 
-export function selectReleaseArtifact(files) {
+export function selectReleaseArtifact(files, target = defaultTarget()) {
+  validateReleaseTarget(target);
   const explicit = process.env.AGC_UPDATE_ARTIFACT?.trim();
   if (explicit) {
     const resolved = path.resolve(explicit);
@@ -427,9 +491,10 @@ export function selectReleaseArtifact(files) {
   }
   return (
     [...files]
-      .filter((filePath) => artifactPriority(filePath) < 99)
+      .filter((filePath) => artifactPriority(filePath, target) < 99)
       .sort((left, right) => {
-        const priority = artifactPriority(left) - artifactPriority(right);
+        const priority =
+          artifactPriority(left, target) - artifactPriority(right, target);
         return priority || left.localeCompare(right);
       })[0] ?? null
   );
@@ -450,13 +515,15 @@ function readUpdaterSignature(artifactPath) {
 export function createUpdateManifest(
   artifactPath,
   {
-    channel = resolveReleaseChannel(),
-    target = releaseTarget,
+    target = defaultTarget(),
+    channel = resolveReleaseChannel(process.env, target),
     publishedAt = new Date().toISOString(),
     notes = readReleaseNotes(),
     commit = readHeadCommit(),
   } = {},
 ) {
+  validateReleaseTarget(target);
+  resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel }, target);
   const signature = readUpdaterSignature(artifactPath);
   const version = readPackageJson().version;
   const fileName = path.basename(artifactPath);
@@ -604,9 +671,11 @@ export function createLegacyUpdateManifest(
   };
 }
 
-export async function generateUpdateManifest() {
-  const channel = resolveReleaseChannel();
-  const artifact = selectReleaseArtifact(listFiles(bundleRoot));
+export async function generateUpdateManifest(
+  context = resolveReleaseContext(),
+) {
+  const { channel, target, bundleRoot } = context;
+  const artifact = selectReleaseArtifact(listFiles(bundleRoot), target);
   if (!artifact) {
     throw new Error(`未找到可发布的 AGC 安装包：${bundleRoot}`);
   }
@@ -623,7 +692,7 @@ export async function generateUpdateManifest() {
       `[ai-game-creator-shell] 未生成自动更新摘要（上一发布 commit=${previousCommit ?? '未知'}，客户端相关提交=${commits ? commits.length : '不可判定'}，最近提交=${recentCommits ? recentCommits.length : '不可判定'}）`,
     );
   }
-  const manifest = createUpdateManifest(artifact, { channel, notes });
+  const manifest = createUpdateManifest(artifact, { channel, target, notes });
   const manifestPath = path.join(bundleRoot, 'latest.json');
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   const notesPath = path.join(bundleRoot, 'release-notes.txt');
@@ -675,12 +744,24 @@ export async function generateUpdateManifest() {
   };
 }
 
+export async function buildRelease(
+  args = [],
+  {
+    prepareVersion = prepareReleaseVersion,
+    build = runTauriBuild,
+    generateManifest = generateUpdateManifest,
+  } = {},
+) {
+  const context = resolveReleaseContext(args);
+  if (!args.includes('--no-bundle')) await prepareVersion(context);
+  build(args, context);
+  if (!args.includes('--no-bundle')) return generateManifest(context);
+}
+
 if (
   process.argv[1] &&
   path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 ) {
   const args = process.argv.slice(2);
-  if (!args.includes('--no-bundle')) await prepareReleaseVersion();
-  runTauriBuild(args);
-  if (!args.includes('--no-bundle')) await generateUpdateManifest();
+  await buildRelease(args);
 }

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

@@ -14,6 +14,8 @@ import { fileURLToPath } from 'node:url';
 
 import {
   agcReleasePathPatterns,
+  buildRelease,
+  buildTauriBuildArguments,
   collectRecentReleaseCommits,
   collectReleaseCommits,
   compareVersions,
@@ -22,11 +24,14 @@ import {
   createUpdateManifest,
   formatRecentReleaseNotes,
   formatReleaseNotes,
+  generateUpdateManifest,
   nextPatchVersion,
   resolveManifestPlatformKeys,
   resolvePreviousReleaseCommit,
   resolveReleaseChannel,
+  resolveReleaseContext,
   resolveRemoteHighWaterVersion,
+  runTauriBuild,
   selectReleaseArtifact,
   updateManifestUrl,
 } from './build-release.mjs';
@@ -34,6 +39,21 @@ import {
 const windowsTarget = 'x86_64-pc-windows-msvc';
 const universalTarget = 'universal-apple-darwin';
 
+test('native sidecar builds reject universal targets and accept each macOS architecture', () => {
+  assert.throws(() => buildTauriBuildArguments([], universalTarget), /单架构/);
+  assert.throws(
+    () => buildTauriBuildArguments(['--target=universal-apple-darwin']),
+    /单架构/,
+  );
+  for (const target of ['aarch64-apple-darwin', 'x86_64-apple-darwin']) {
+    assert.deepEqual(buildTauriBuildArguments([], target), [
+      'build',
+      '--target',
+      target,
+    ]);
+  }
+});
+
 function withEnv(overrides, run) {
   const previous = new Map();
   for (const [key, value] of Object.entries(overrides)) {
@@ -132,9 +152,12 @@ test('channel manifest URL and build-time endpoint follow the channel', () => {
   });
 });
 
-test('universal macOS builds publish one artifact under both platform keys', () => {
-  assert.deepEqual(resolveManifestPlatformKeys(universalTarget), [
+test('macOS manifests only advertise the architecture actually built', () => {
+  assert.throws(() => resolveManifestPlatformKeys(universalTarget), /单架构/);
+  assert.deepEqual(resolveManifestPlatformKeys('aarch64-apple-darwin'), [
     'darwin-aarch64',
+  ]);
+  assert.deepEqual(resolveManifestPlatformKeys('x86_64-apple-darwin'), [
     'darwin-x86_64',
   ]);
   assert.deepEqual(resolveManifestPlatformKeys(windowsTarget), [
@@ -142,6 +165,218 @@ test('universal macOS builds publish one artifact under both platform keys', ()
   ]);
 });
 
+test('release context resolves explicit targets before environment/default and fails closed', () => {
+  for (const args of [
+    ['--target', 'aarch64-apple-darwin'],
+    ['--target=aarch64-apple-darwin'],
+    ['-t', 'aarch64-apple-darwin'],
+  ]) {
+    for (const env of [{}, { AGC_BUILD_TARGET: windowsTarget }]) {
+      const context = resolveReleaseContext(args, env);
+      assert.equal(context.target, 'aarch64-apple-darwin');
+      assert.equal(context.channel, 'dev-mac');
+      assert.match(
+        context.bundleRoot.replaceAll('\\', '/'),
+        /target\/aarch64-apple-darwin\/release\/bundle$/,
+      );
+      assert.ok(Object.isFrozen(context));
+    }
+    assert.throws(
+      () => resolveReleaseContext(args, { AGC_UPDATE_CHANNEL: 'dev-win' }),
+      /只能用于 windows/,
+    );
+  }
+  assert.equal(resolveReleaseContext([], {}).target, windowsTarget);
+  assert.equal(
+    resolveReleaseContext([], { AGC_BUILD_TARGET: 'x86_64-apple-darwin' })
+      .channel,
+    'dev-mac',
+  );
+  for (const args of [
+    ['--target'],
+    ['--target='],
+    ['--target', '--no-bundle'],
+    ['--target', windowsTarget, '--target=aarch64-apple-darwin'],
+    ['--target', universalTarget],
+    ['--target', 'unknown'],
+  ])
+    assert.throws(() => resolveReleaseContext(args, {}));
+});
+
+test('explicit macOS target drives version lookup, Tauri endpoint, artifact and manifest together', async () => {
+  const calls = [];
+  const seenContexts = [];
+  await withStubbedFetch(
+    (url) => {
+      calls.push(url);
+      assert.match(url, /\/dev-mac\/latest\.json$/);
+      return jsonResponse({ version: '0.1.67' });
+    },
+    () =>
+      withEnv(
+        { AGC_BUILD_TARGET: undefined, AGC_UPDATE_CHANNEL: undefined },
+        () =>
+          buildRelease(['--target', 'aarch64-apple-darwin'], {
+            prepareVersion: async (context) => {
+              seenContexts.push(context);
+              assert.equal(
+                await resolveRemoteHighWaterVersion(context.channel),
+                '0.1.67',
+              );
+            },
+            build: (args, context) => {
+              seenContexts.push(context);
+              runTauriBuild(args, context, {
+                spawn: (_binary, command) => {
+                  const configIndex = command.lastIndexOf('--config');
+                  const config = JSON.parse(
+                    readFileSync(command[configIndex + 1], 'utf8'),
+                  );
+                  assert.match(
+                    config.plugins.updater.endpoints[0],
+                    /\/dev-mac\/latest\.json$/,
+                  );
+                  assert.ok(command.includes('aarch64-apple-darwin'));
+                  assert.ok(
+                    !command.includes('--features=cocos-editor-execute'),
+                  );
+                  return { status: 0 };
+                },
+              });
+            },
+            generateManifest: (context) => {
+              seenContexts.push(context);
+              withSignedArtifact('陶泥儿.app.tar.gz', (artifact) => {
+                assert.equal(
+                  selectReleaseArtifact(
+                    ['/tmp/win.exe', artifact, '/tmp/mac.dmg'],
+                    context.target,
+                  ),
+                  artifact,
+                );
+                const manifest = createUpdateManifest(artifact, context);
+                assert.deepEqual(Object.keys(manifest.platforms), [
+                  'darwin-aarch64',
+                ]);
+                assert.match(
+                  manifest.platforms['darwin-aarch64'].url,
+                  /\/dev-mac\//,
+                );
+              });
+            },
+          }),
+      ),
+  );
+  assert.equal(calls.length, 1, 'Mac 不应读取 Windows 迁移指针');
+  assert.equal(seenContexts.length, 3);
+  assert.ok(seenContexts.every((context) => context === seenContexts[0]));
+});
+
+test('real manifest writer uses the resolved bundle root and does not emit Windows artifacts', async () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'agc-mac-manifest-'));
+  try {
+    const artifact = path.join(root, '陶泥儿.app.tar.gz');
+    writeFileSync(artifact, 'mac package');
+    writeFileSync(`${artifact}.sig`, 'mac signature');
+    writeFileSync(path.join(root, 'windows.exe'), 'wrong platform');
+    const context = {
+      ...resolveReleaseContext(['--target=x86_64-apple-darwin'], {}),
+      bundleRoot: root,
+    };
+    const result = await withStubbedFetch(
+      (url) => {
+        assert.match(url, /\/dev-mac\/latest\.json$/);
+        return jsonResponse({}, 404);
+      },
+      () => generateUpdateManifest(context),
+    );
+    assert.equal(result.artifact, artifact);
+    assert.equal(result.manifestPath, path.join(root, 'latest.json'));
+    assert.equal(result.legacyManifestPath, null);
+    assert.deepEqual(Object.keys(result.manifest.platforms), ['darwin-x86_64']);
+    assert.match(result.manifest.platforms['darwin-x86_64'].url, /\/dev-mac\//);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('invalid target or mismatched channel fails before any release side effect', async () => {
+  let touched = false;
+  const sideEffects = {
+    prepareVersion: () => {
+      touched = true;
+    },
+    build: () => {
+      touched = true;
+    },
+    generateManifest: () => {
+      touched = true;
+    },
+  };
+  await assert.rejects(
+    () => buildRelease(['--target', universalTarget], sideEffects),
+    /单架构/,
+  );
+  await withEnv({ AGC_UPDATE_CHANNEL: 'dev-win' }, () =>
+    assert.rejects(
+      () => buildRelease(['--target=aarch64-apple-darwin'], sideEffects),
+      /只能用于 windows/,
+    ),
+  );
+  assert.equal(touched, false);
+});
+
+test('Windows remains the default and explicit Windows overrides macOS environment', () => {
+  const files = ['/tmp/mac.app.tar.gz', '/tmp/windows.exe', '/tmp/mac.dmg'];
+  for (const context of [
+    resolveReleaseContext([], {}),
+    resolveReleaseContext(['--target', windowsTarget], {
+      AGC_BUILD_TARGET: 'aarch64-apple-darwin',
+    }),
+  ]) {
+    assert.equal(context.channel, 'dev-win');
+    assert.equal(
+      selectReleaseArtifact(files, context.target),
+      '/tmp/windows.exe',
+    );
+    runTauriBuild(
+      ['--target', windowsTarget, '--config', 'user-config.json'],
+      context,
+      {
+        spawn: (_binary, command) => {
+          assert.ok(command.includes('--features=cocos-editor-execute'));
+          assert.ok(command.includes('user-config.json'));
+          const configIndex = command.lastIndexOf('--config');
+          const config = JSON.parse(
+            readFileSync(command[configIndex + 1], 'utf8'),
+          );
+          assert.match(
+            config.plugins.updater.endpoints[0],
+            /\/dev-win\/latest\.json$/,
+          );
+          return { status: 0 };
+        },
+      },
+    );
+  }
+});
+
+test('no-bundle smoke skips version writes and manifest generation', async () => {
+  const steps = [];
+  await buildRelease(['--no-bundle', '--target=aarch64-apple-darwin'], {
+    prepareVersion: () => {
+      steps.push('version');
+    },
+    build: (_args, context) => {
+      steps.push(context.channel);
+    },
+    generateManifest: () => {
+      steps.push('manifest');
+    },
+  });
+  assert.deepEqual(steps, ['dev-mac']);
+});
+
 test('channel manifest carries version, platform keys and signature', () => {
   withSignedArtifact('陶泥儿_0.1.48_x64-setup.exe', (artifact) => {
     withEnv({ AGC_UPDATE_RELEASE_NOTES: '修复与改进' }, () => {
@@ -345,6 +580,7 @@ test('release upload forces overwrite for artifact, signature and channel pointe
   );
   assert.match(source, /agc\/\$\{channel\}\/latest\.json/u);
   assert.match(source, /agc\/latest\.json/u);
+  assert.match(source, /await buildRelease\(process\.argv\.slice\(2\)\)/u);
 });
 
 test('release notes list client commits with short sha and bound their size', () => {

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

@@ -35,6 +35,12 @@ const windowsTauriConfig = JSON.parse(
     'utf8',
   ),
 );
+const macosTauriConfig = JSON.parse(
+  fs.readFileSync(
+    new URL('../src-tauri/tauri.macos.conf.json', import.meta.url),
+    'utf8',
+  ),
+);
 const cargoManifestSource = fs.readFileSync(
   new URL('../src-tauri/Cargo.toml', import.meta.url),
   'utf8',
@@ -1358,6 +1364,37 @@ if (windowsTauriConfig.bundle?.useLocalToolsDir !== true) {
     'AI game creator shell Windows Tauri config must cache bundling tools in the project target directory',
   );
 }
+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}`,
+    ]),
+    ['resources/plugins', 'plugins'],
+  ]),
+  'macOS must bundle the complete native Codex layout and plugin workspace',
+);
+assert.deepEqual(
+  macosTauriConfig.plugins?.updater?.endpoints,
+  [
+    'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/dev-mac/latest.json',
+  ],
+  'macOS local builds must not use the Windows update channel',
+);
+assert.equal(
+  macosTauriConfig.bundle?.macOS?.minimumSystemVersion,
+  '15.0',
+  'macOS deployment baseline must cover the bundled native zsh requirement',
+);
 
 if (tauriConfig.app?.withGlobalTauri !== true) {
   throw new Error(
@@ -1722,7 +1759,7 @@ for (const snippet of [
   'fn append_local_permission_log_at(',
   '"command.auto"',
   'GameCreationAppPermission::Auto',
-  'GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH',
+  'fn game_creator_bundled_codex_cli_path',
   'validate_game_creator_bundled_codex_cli',
   '内置 Codex CLI 完整性校验失败',
 ]) {

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

@@ -0,0 +1,222 @@
+import assert from 'node:assert/strict';
+import { spawn, 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';
+
+// 只操作临时复制品；不启动 GUI、不读取开发机凭据、不访问 Provider。
+assert.equal(process.platform, 'darwin', '此验证必须在 macOS 执行');
+const source = path.resolve(process.argv[2] || '');
+assert.ok(
+  source.endsWith('.app') && fs.statSync(source).isDirectory(),
+  '请传入 .app 绝对路径',
+);
+const root = fs.realpathSync(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'agc-macos-bundle-')),
+);
+const app = path.join(root, '陶泥儿 隔离测试.app');
+const home = path.join(root, 'home');
+const config = path.join(root, 'config');
+const tmp = path.join(root, 'tmp');
+const codexHome = path.join(root, 'codex-home');
+for (const directory of [home, config, tmp, codexHome]) {
+  fs.mkdirSync(directory, { mode: 0o700 });
+}
+const env = {
+  HOME: home,
+  PATH: '/usr/bin:/bin',
+  TMPDIR: tmp,
+  CODEX_HOME: codexHome,
+};
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    env,
+    encoding: 'utf8',
+    timeout: 30_000,
+    maxBuffer: 1024 * 1024,
+  });
+  assert.ifError(result.error);
+  return result;
+}
+
+async function hashFile(file) {
+  const hash = createHash('sha256');
+  for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function handshake(executable) {
+  const child = spawn(executable, ['app-server'], {
+    cwd: root,
+    env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  let buffered = '';
+  let stderrBytes = 0;
+  try {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('app-server 初始化超时')),
+        15_000,
+      );
+      const finish = (error) => {
+        clearTimeout(timer);
+        if (error) reject(error);
+        else resolve();
+      };
+      child.on('error', finish);
+      child.on('exit', (code) =>
+        finish(new Error(`app-server 提前退出 ${code}`)),
+      );
+      child.stderr.on('data', (chunk) => {
+        stderrBytes += chunk.length;
+        if (stderrBytes > 1024 * 1024)
+          finish(new Error('app-server stderr 超限'));
+      });
+      child.stdout.on('data', (chunk) => {
+        buffered += chunk.toString('utf8');
+        if (buffered.length > 1024 * 1024)
+          return finish(new Error('app-server stdout 超限'));
+        let end;
+        while ((end = buffered.indexOf('\n')) >= 0) {
+          const line = buffered.slice(0, end);
+          buffered = buffered.slice(end + 1);
+          try {
+            const message = JSON.parse(line);
+            if (message.id !== 1) continue;
+            assert.ok(message.result?.userAgent, '初始化必须返回真实服务身份');
+            assert.equal(message.error, undefined);
+            child.stdin.write(`${JSON.stringify({ method: 'initialized' })}\n`);
+            finish();
+          } catch (error) {
+            finish(error);
+          }
+        }
+      });
+      child.stdin.on('error', finish);
+      child.stdin.write(
+        `${JSON.stringify({
+          id: 1,
+          method: 'initialize',
+          params: {
+            clientInfo: {
+              name: 'agc_bundle_smoke',
+              title: 'AGC bundle smoke',
+              version: '1',
+            },
+            capabilities: { experimentalApi: true },
+          },
+        })}\n`,
+      );
+    });
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(() => child.kill('SIGKILL'), 3000);
+        child.once('exit', () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        child.kill('SIGTERM');
+      });
+    }
+  }
+}
+
+try {
+  fs.cpSync(source, app, { recursive: true });
+  const resources = path.join(app, 'Contents/Resources');
+  const bundle = path.join(resources, 'coding-agent/mac-native');
+  const executable = path.join(bundle, 'bin/codex');
+  const main = path.join(
+    app,
+    'Contents/MacOS/genarrative-ai-game-creator-shell',
+  );
+  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');
+  const components = [
+    'bin/codex',
+    'bin/codex-code-mode-host',
+    'codex-path/rg',
+    'codex-resources/zsh/bin/zsh',
+    'codex-package.json',
+  ];
+  assert.deepEqual(Object.keys(manifest.files).sort(), [...components].sort());
+  for (const component of components) {
+    const file = path.join(bundle, component);
+    assert.equal(await hashFile(file), manifest.files[component], component);
+    if (component !== 'codex-package.json') {
+      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.ok(fs.existsSync(path.join(bundle, 'NOTICE.md')));
+  const plugin = path.join(resources, 'plugins/agc-cocos-editor');
+  for (const file of [
+    'plugin.json',
+    'src/entry.mjs',
+    'panels/cocos-editor.html',
+  ]) {
+    assert.ok(fs.existsSync(path.join(plugin, file)), file);
+  }
+  const packageFiles = fs.readdirSync(resources, { recursive: true });
+  assert.ok(
+    !packageFiles.some((file) =>
+      /(^|\/)(\.env[^/]*|auth\.json|node_modules|target|\.git)(\/|$)|\.(exe|dll)$/.test(
+        file,
+      ),
+    ),
+  );
+  assert.equal(run(executable, ['--version']).stdout.trim(), manifest.version);
+  assert.equal(
+    run(path.join(bundle, 'codex-path/rg'), ['--version']).status,
+    0,
+  );
+  assert.equal(
+    run(path.join(bundle, 'codex-resources/zsh/bin/zsh'), ['--version']).status,
+    0,
+  );
+
+  // 使用正式 AGC 查找/校验入口，而非只证明 sidecar 可以独立执行。
+  const status = run(main, ['--config-dir', config, '--llm-status']);
+  const statusText = `${status.stdout}\n${status.stderr}`;
+  assert.ok(!statusText.includes('Codex CLI 未安装'), statusText);
+  assert.ok(
+    statusText.includes('authentication-required'),
+    '隔离账号应仅被登录门禁拒绝',
+  );
+  await handshake(executable);
+
+  // 临时复制品缺少辅助程序时，正式入口必须拒绝内置程序；PATH 无全局 Codex 可兜底。
+  fs.renameSync(
+    path.join(bundle, 'bin/codex-code-mode-host'),
+    path.join(root, 'saved-code-mode-host'),
+  );
+  const broken = run(main, ['--config-dir', config, '--llm-status']);
+  assert.notEqual(broken.status, 0);
+  assert.match(`${broken.stdout}\n${broken.stderr}`, /Codex CLI 未安装/);
+  console.log(
+    'PASS: 隔离安装包资源、架构、摘要、权限、正式 Codex 查找、app-server 握手及缺组件拒绝',
+  );
+  console.log(
+    '未验证：GUI、真实登录/Provider 对话、Cocos macOS 原生桥接；插件 Node 仍为外部前提',
+  );
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}

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

@@ -12,8 +12,7 @@ if (!/^[a-z0-9][a-z0-9.-]{1,62}$/u.test(bucket) || /[\r\n\0]/u.test(endpoint)) {
 process.env.AGC_UPDATE_OSS_BASE_URL ||= `https://${bucket}.${endpoint}/agc`;
 const dryRun = readReleaseDryRun();
 
-const { generateUpdateManifest, prepareReleaseVersion, runTauriBuild } =
-  await import('./build-release.mjs');
+const { buildRelease } = await import('./build-release.mjs');
 
 function runOssutil(args) {
   const binary = process.env.OSSUTIL_BIN?.trim() || 'ossutil';
@@ -51,10 +50,8 @@ function runOssutil(args) {
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-await prepareReleaseVersion();
-runTauriBuild([]);
 const { artifact, channel, legacyManifestPath, manifest, manifestPath } =
-  await generateUpdateManifest();
+  await buildRelease(process.argv.slice(2));
 const artifactKey = `agc/${channel}/${manifest.version}/${path.basename(artifact)}`;
 // Jenkins/ossutil 默认会在目标对象已存在时交互询问并按默认值跳过；
 // 发布清单是固定的 latest 指针，必须显式覆盖，否则流水线会误报成功但远端仍保留旧版本。

apps/ai-game-creator-shell/src-tauri/Cargo.lock

@@ -1745,7 +1745,7 @@ dependencies = [
 
 [[package]]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.47"
+version = "0.1.67"
 dependencies = [
  "agent-runtime-core",
  "axum",

apps/ai-game-creator-shell/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.47"
+version = "0.1.67"
 edition = "2021"
 publish = false
 

apps/ai-game-creator-shell/src-tauri/build.rs

@@ -1,31 +1,18 @@
+#[path = "build_support/codex_bundle.rs"]
+mod codex_bundle;
 #[path = "build_support/frontend_dist_guard.rs"]
 mod frontend_dist_guard;
 #[path = "build_support/runtime_prompt_bundle.rs"]
 mod runtime_prompt_bundle;
 
-#[cfg(windows)]
 use sha2::{Digest, Sha256};
 use std::collections::BTreeSet;
 use std::env;
 use std::fs;
 use std::path::PathBuf;
 
-#[cfg(windows)]
 use std::io::{BufReader, Read};
 
-const BUNDLED_CODEX_CLI_VERSION: &str = "codex-cli 0.147.0";
-
-#[cfg(windows)]
-const BUNDLED_CODEX_FILES: [&str; 6] = [
-    "bin/codex.exe",
-    "bin/codex-code-mode-host.exe",
-    "codex-path/rg.exe",
-    "codex-resources/codex-command-runner.exe",
-    "codex-resources/codex-windows-sandbox-setup.exe",
-    "codex-package.json",
-];
-
-#[cfg(windows)]
 fn sha256_file(path: &std::path::Path) -> Result<String, std::io::Error> {
     let file = fs::File::open(path)?;
     let mut reader = BufReader::new(file);
@@ -42,7 +29,15 @@ fn sha256_file(path: &std::path::Path) -> Result<String, std::io::Error> {
 }
 
 fn stage_bundled_codex_cli(manifest_dir: &std::path::Path) {
-    #[cfg(windows)]
+    let target = env::var("TARGET").expect("Cargo TARGET");
+    println!("cargo:rustc-env=AGC_BUILD_TARGET={target}");
+    let Some(layout) = codex_bundle::for_target(&target) else {
+        assert!(
+            !target.contains("windows") && !target.contains("apple-darwin"),
+            "不支持的 Codex 随包目标：{target}"
+        );
+        return;
+    };
     {
         let app_root = manifest_dir
             .parent()
@@ -51,24 +46,23 @@ fn stage_bundled_codex_cli(manifest_dir: &std::path::Path) {
             .parent()
             .and_then(|apps_dir| apps_dir.parent())
             .expect("AI 游戏创作应用必须位于仓库 apps 目录下");
-        let source_candidates = [
-            app_root.join(
-                "node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc",
-            ),
-            app_root.join(
-                "node_modules/@openai/codex/node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc",
-            ),
-            repo_root.join(
-                "node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc",
-            ),
-            repo_root.join(
-                "node_modules/@openai/codex/node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc",
-            ),
-        ];
+        let package = layout.npm_package;
+        let source_candidates = [app_root, repo_root]
+            .into_iter()
+            .flat_map(|root| {
+                [
+                    root.join(format!("node_modules/@openai/{package}/vendor/{target}")),
+                    root.join(format!(
+                        "node_modules/@openai/codex/node_modules/@openai/{package}/vendor/{target}"
+                    )),
+                ]
+            })
+            .collect::<Vec<_>>();
         let source = source_candidates
             .iter()
             .find(|path| {
-                BUNDLED_CODEX_FILES
+                layout
+                    .files
                     .iter()
                     .all(|relative| path.join(relative).is_file())
             })
@@ -83,14 +77,26 @@ fn stage_bundled_codex_cli(manifest_dir: &std::path::Path) {
                         .join("；")
                 )
             });
-        let target_dir = manifest_dir.join("resources/codex/win-x64");
+        let metadata: serde_json::Value = serde_json::from_slice(
+            &fs::read(source.join("codex-package.json")).expect("读取 Codex 原生包元数据失败"),
+        )
+        .expect("Codex 原生包元数据无效");
+        codex_bundle::validate_package_metadata(&metadata, &target, layout)
+            .unwrap_or_else(|error| panic!("{error}"));
+        let target_dir = manifest_dir.join("resources/codex").join(layout.directory);
         let notice = target_dir.join("NOTICE.md");
+        if target.contains("apple-darwin") {
+            let source_notice =
+                manifest_dir.join("resources/codex/【声明】Mac内置Codex组件-2026-09-18.md");
+            stage_plugin_file(&source_notice, &notice);
+            println!("cargo:rerun-if-changed={}", source_notice.display());
+        }
         if !notice.is_file() {
             panic!("内置 Codex CLI 第三方声明缺失：{}", notice.display());
         }
         fs::create_dir_all(&target_dir).expect("创建内置 Codex CLI 资源目录失败");
         let mut file_hashes = serde_json::Map::new();
-        for relative in BUNDLED_CODEX_FILES {
+        for relative in layout.files {
             let source_path = source.join(relative);
             let target_path = target_dir.join(relative);
             if let Some(parent) = target_path.parent() {
@@ -104,15 +110,23 @@ fn stage_bundled_codex_cli(manifest_dir: &std::path::Path) {
             if !target_matches_source {
                 fs::copy(&source_path, &target_path).expect("复制内置 Codex CLI 资源失败");
             }
+            // 内容相同但曾被错误 chmod 的 staging 文件也必须恢复执行权限。
+            fs::set_permissions(
+                &target_path,
+                fs::metadata(&source_path)
+                    .expect("读取组件权限失败")
+                    .permissions(),
+            )
+            .expect("保留内置 Codex CLI 组件权限失败");
             file_hashes.insert(
                 relative.to_string(),
                 serde_json::Value::String(source_sha256),
             );
         }
         let manifest = serde_json::json!({
-            "schemaVersion": "genarrative-codex-sidecar.v2",
-            "platform": "win32-x64",
-            "version": BUNDLED_CODEX_CLI_VERSION,
+            "schemaVersion": codex_bundle::SCHEMA,
+            "platform": layout.platform,
+            "version": codex_bundle::CLI_VERSION,
             "files": file_hashes,
         });
         let manifest_path = target_dir.join("manifest.json");
@@ -126,7 +140,7 @@ fn stage_bundled_codex_cli(manifest_dir: &std::path::Path) {
         {
             fs::write(&manifest_path, manifest_payload).expect("写入内置 Codex CLI 清单失败");
         }
-        for relative in BUNDLED_CODEX_FILES {
+        for relative in layout.files {
             println!("cargo:rerun-if-changed={}", source.join(relative).display());
         }
         println!("cargo:rerun-if-changed={}", notice.display());
@@ -256,8 +270,11 @@ fn stage_cocos_editor_payload(_manifest_dir: &std::path::Path) {}
 ///
 /// 只复制插件运行需要的清单、入口、面板和 native payload，不复制 native 源码、
 /// Cargo target 目录或 node_modules。
-#[cfg(windows)]
 fn stage_plugin_workspace(manifest_dir: &std::path::Path) {
+    let target = env::var("TARGET").expect("Cargo TARGET");
+    if !target.contains("windows") && !target.contains("apple-darwin") {
+        return;
+    }
     let repo_root = manifest_dir
         .parent()
         .and_then(|app_root| app_root.parent())
@@ -266,6 +283,10 @@ fn stage_plugin_workspace(manifest_dir: &std::path::Path) {
         .to_path_buf();
     let workspace = repo_root.join("plugins");
     let destination_root = manifest_dir.join("resources/plugins");
+    // staging 是专用生成目录；重建清除跨目标 payload 与已删除插件的残留。
+    if destination_root.exists() {
+        std::fs::remove_dir_all(&destination_root).expect("清理插件 staging 失败");
+    }
     std::fs::create_dir_all(&destination_root).expect("创建插件资源目录失败");
     let entries = match std::fs::read_dir(&workspace) {
         Ok(entries) => entries,
@@ -273,6 +294,13 @@ fn stage_plugin_workspace(manifest_dir: &std::path::Path) {
     };
     for entry in entries.flatten() {
         let plugin_root = entry.path();
+        assert!(
+            !entry
+                .file_type()
+                .expect("读取插件目录类型失败")
+                .is_symlink(),
+            "插件工作区不允许符号链接"
+        );
         if !plugin_root.is_dir() || !plugin_root.join("plugin.json").is_file() {
             continue;
         }
@@ -287,17 +315,18 @@ fn stage_plugin_workspace(manifest_dir: &std::path::Path) {
             std::path::PathBuf::from("panels"),
             std::path::PathBuf::from("native/payload"),
         ] {
+            if relative == std::path::Path::new("native/payload") && !target.contains("windows") {
+                continue;
+            }
             copy_plugin_tree(&plugin_root.join(&relative), &destination.join(&relative));
         }
         println!("cargo:rerun-if-changed={}", plugin_root.display());
     }
 }
 
-#[cfg(windows)]
 fn stage_plugin_file(source: &std::path::Path, destination: &std::path::Path) {
-    let Ok(bytes) = std::fs::read(source) else {
-        return;
-    };
+    let bytes = std::fs::read(source)
+        .unwrap_or_else(|error| panic!("读取随包资源失败 {}：{error}", source.display()));
     if std::fs::read(destination).is_ok_and(|existing| existing == bytes) {
         return;
     }
@@ -307,7 +336,6 @@ fn stage_plugin_file(source: &std::path::Path, destination: &std::path::Path) {
     std::fs::write(destination, bytes).expect("复制插件资源失败");
 }
 
-#[cfg(windows)]
 fn copy_plugin_tree(source: &std::path::Path, destination: &std::path::Path) {
     let entries = match std::fs::read_dir(source) {
         Ok(entries) => entries,
@@ -316,10 +344,17 @@ fn copy_plugin_tree(source: &std::path::Path, destination: &std::path::Path) {
     for entry in entries.flatten() {
         let target = destination.join(entry.file_name());
         let path = entry.path();
+        assert!(
+            !entry
+                .file_type()
+                .expect("读取插件文件类型失败")
+                .is_symlink(),
+            "插件资源不允许符号链接"
+        );
         if path.is_dir() {
             let name = entry.file_name();
             let name = name.to_string_lossy();
-            if matches!(name.as_ref(), "target" | "node_modules" | ".git") {
+            if name.starts_with('.') || matches!(name.as_ref(), "target" | "node_modules") {
                 continue;
             }
             std::fs::create_dir_all(&target).expect("创建插件资源目录失败");
@@ -331,12 +366,14 @@ fn copy_plugin_tree(source: &std::path::Path, destination: &std::path::Path) {
             if name.contains(".test.") {
                 continue;
             }
+            if name.starts_with('.') {
+                continue;
+            }
             stage_plugin_file(&path, &target);
         }
     }
 }
 
-#[cfg(windows)]
 fn copy_plugin_file(source: &std::path::Path, destination: &std::path::Path) {
     if !source.is_file() {
         return;
@@ -345,6 +382,3 @@ fn copy_plugin_file(source: &std::path::Path, destination: &std::path::Path) {
         .expect("创建插件资源目录失败");
     std::fs::copy(source, destination).expect("复制插件资源失败");
 }
-
-#[cfg(not(windows))]
-fn stage_plugin_workspace(_manifest_dir: &std::path::Path) {}

apps/ai-game-creator-shell/src-tauri/build_support/codex_bundle.rs

@@ -0,0 +1,133 @@
+//! 构建与运行共用的平台布局；只允许分发锁定原生包里的明确组件。
+
+pub const VERSION: &str = "0.147.0";
+pub const CLI_VERSION: &str = "codex-cli 0.147.0";
+pub const SCHEMA: &str = "genarrative-codex-sidecar.v2";
+
+#[derive(Clone, Copy, Debug)]
+pub struct Layout {
+    pub platform: &'static str,
+    pub npm_package: &'static str,
+    pub directory: &'static str,
+    pub executable: &'static str,
+    pub files: &'static [&'static str],
+}
+
+const WINDOWS_FILES: &[&str] = &[
+    "bin/codex.exe",
+    "bin/codex-code-mode-host.exe",
+    "codex-path/rg.exe",
+    "codex-resources/codex-command-runner.exe",
+    "codex-resources/codex-windows-sandbox-setup.exe",
+    "codex-package.json",
+];
+const MAC_FILES: &[&str] = &[
+    "bin/codex",
+    "bin/codex-code-mode-host",
+    "codex-path/rg",
+    "codex-resources/zsh/bin/zsh",
+    "codex-package.json",
+];
+
+pub fn for_target(target: &str) -> Option<Layout> {
+    match target {
+        "x86_64-pc-windows-msvc" => Some(Layout {
+            platform: "win32-x64",
+            npm_package: "codex-win32-x64",
+            directory: "win-x64",
+            executable: "bin/codex.exe",
+            files: WINDOWS_FILES,
+        }),
+        "aarch64-apple-darwin" | "x86_64-apple-darwin" => Some(Layout {
+            platform: if target.starts_with("aarch64") {
+                "darwin-arm64"
+            } else {
+                "darwin-x64"
+            },
+            npm_package: if target.starts_with("aarch64") {
+                "codex-darwin-arm64"
+            } else {
+                "codex-darwin-x64"
+            },
+            directory: "mac-native",
+            executable: "bin/codex",
+            files: MAC_FILES,
+        }),
+        _ => None,
+    }
+}
+
+pub fn validate_package_metadata(
+    metadata: &serde_json::Value,
+    target: &str,
+    layout: Layout,
+) -> Result<(), String> {
+    if metadata["layoutVersion"] == 1
+        && metadata["version"] == VERSION
+        && metadata["target"] == target
+        && metadata["entrypoint"] == layout.executable
+        && metadata["resourcesDir"] == "codex-resources"
+        && metadata["pathDir"] == "codex-path"
+    {
+        Ok(())
+    } else {
+        Err(format!("Codex 原生包版本、布局或架构不匹配目标 {target}"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn platform_layouts_are_explicit_and_preserve_upstream_components() {
+        let mac = for_target("aarch64-apple-darwin").unwrap();
+        assert_eq!(mac.platform, "darwin-arm64");
+        assert_eq!(mac.npm_package, "codex-darwin-arm64");
+        assert!(mac.files.contains(&"codex-resources/zsh/bin/zsh"));
+        assert!(mac.files.contains(&"bin/codex-code-mode-host"));
+        assert!(!mac.files.iter().any(|file| file.ends_with(".exe")));
+        let intel = for_target("x86_64-apple-darwin").unwrap();
+        assert_eq!(intel.platform, "darwin-x64");
+        assert_eq!(intel.npm_package, "codex-darwin-x64");
+        let windows = for_target("x86_64-pc-windows-msvc").unwrap();
+        assert_eq!(windows.directory, "win-x64");
+        assert_eq!(windows.files.len(), 6);
+        assert!(windows
+            .files
+            .contains(&"codex-resources/codex-windows-sandbox-setup.exe"));
+        assert!(for_target("universal-apple-darwin").is_none());
+        assert!(for_target("aarch64-pc-windows-msvc").is_none());
+        assert!(for_target("x86_64-unknown-linux-gnu").is_none());
+    }
+
+    #[test]
+    fn metadata_rejects_version_architecture_and_layout_drift() {
+        let target = "aarch64-apple-darwin";
+        let layout = for_target(target).unwrap();
+        let valid = serde_json::json!({
+            "layoutVersion": 1,
+            "version": VERSION,
+            "target": target,
+            "entrypoint": "bin/codex",
+            "resourcesDir": "codex-resources",
+            "pathDir": "codex-path",
+        });
+        assert!(validate_package_metadata(&valid, target, layout).is_ok());
+        for (key, value) in [
+            ("layoutVersion", serde_json::json!(2)),
+            ("version", serde_json::json!("0.0.0")),
+            ("target", serde_json::json!("x86_64-apple-darwin")),
+            ("entrypoint", serde_json::json!("bin/codex.exe")),
+            ("resourcesDir", serde_json::json!("../private")),
+            ("pathDir", serde_json::json!(null)),
+        ] {
+            let mut invalid = valid.clone();
+            invalid[key] = value;
+            assert!(
+                validate_package_metadata(&invalid, target, layout).is_err(),
+                "{key}"
+            );
+        }
+    }
+}

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/SKILL.md

@@ -14,6 +14,9 @@ Implement the user's actual game request in the current project as an npm-manage
 3. Build with the project's npm script before previewing. The playable entry is the package directory's `dist/index.html`; never report an unbuilt bare-module page as playable. Import assets or configure public assets so all runtime media is included in dist; preview and exports cannot read outside it.
 4. Build a complete playable loop: visible objective, responsive input, meaningful state changes, success or failure feedback, and a reliable restart path where the game needs one.
 5. Fit the active game scene to desktop and mobile viewports without accidental page scrollbars. Reserve deliberate safe space for HUD elements instead of covering interactive content.
+   - **画布居中只能由一处负责。** 使用 `Phaser.Scale.FIT` 与 `autoCenter: Phaser.Scale.CENTER_BOTH` 时，canvas 的直接父容器应使用尺寸明确的普通块布局，不再对同一 canvas 叠加 Grid/Flex 居中、`place-items: center`、自动外边距或居中 transform。Phaser 自动计算的 margin 与 CSS 居中叠加会使竖屏画面向右偏移。
+   - 若决定由 CSS 居中，则显式使用 `autoCenter: Phaser.Scale.NO_CENTER`，由 CSS 独立完成定位；外围页面可以继续使用 Grid/Flex，限制只针对同一 canvas 的重复定位。
+   - 出现偏移先检查游戏自身的 CSS 与 Phaser scale 配置，不添加 AGC 预览容器固定偏移补偿。修改布局后重新构建 dist，在桌面、移动及窗口 resize 后检查 canvas 相对游戏父容器居中（误差不超过 1 CSS px）、画面完整且无意外滚动条；不能仅凭 build 成功宣称布局通过。
 6. Invoke `taonier-art-assets` for every new game brief that needs visual assets. First reuse suitable registered Taonier art; when the brief's required visual elements are missing or unsuitable, call the reviewed `agc_tools` generation/edit workflow in the same task. After the tool returns, wire its relative paths into the game and verify the rendered result. A game with unused generated assets or placeholder emoji/CSS where requested art should appear is not complete. Load media defensively only for genuinely optional effects, and never relabel a local placeholder as platform art.
 7. Let Phaser own the render loop and input dispatch. Avoid duplicate scenes, stale event listeners, and state that survives restart unintentionally.
 8. After a meaningful game change, use the browser playtest Skill and fix issues shown by real evidence before reporting completion.

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-web-game-development/references/game-quality-checklist.md

@@ -7,5 +7,7 @@
 - Score, steps, health, timer, or other core state updates consistently.
 - Restart restores all state and does not duplicate timers, animation loops, or event listeners.
 - Desktop and mobile layouts keep the core scene visible without accidental document scrolling.
+- 画布的缩放与居中由 Phaser 或 CSS 中的一方独立负责。`FIT + CENTER_BOTH` 不与同一 canvas 父容器的 Grid/Flex 居中、自动外边距或居中 transform 叠加；使用 CSS 居中时关闭 Phaser 自动居中（`NO_CENTER`）。
+- 在构建后的实际页面检查桌面、移动和 resize：比较 canvas 与游戏父容器的中心，预期居中时水平/垂直误差不超过 1 CSS px，并检查画面没有溢出或意外滚动条。偏移先修游戏 CSS/scale 配置，不用修改 AGC 预览位置掩盖。
 - HUD and overlays reserve space and do not cover essential interactive content.
 - Requested Taonier art is visibly integrated into the core experience when available.

apps/ai-game-creator-shell/src-tauri/resources/agc-skills/manifest.json

@@ -80,7 +80,7 @@
         "agents/openai.yaml",
         "references/game-quality-checklist.md"
       ],
-      "sha256": "05b5cfbf7a40fd303717491f5cea84ff339a73359c9678b283fd54d2b5c45efd"
+      "sha256": "e122d8f3a6d986b594b95c971754d68197bf7896912fa8267d44a7aa129a57ba"
     },
     {
       "name": "agc-browser-playtest",

apps/ai-game-creator-shell/src-tauri/resources/codex/【声明】Mac内置Codex组件-2026-09-18.md

@@ -0,0 +1,14 @@
+# 内置 Codex CLI
+
+本安装包包含锁定版本 Codex CLI 0.147.0 的 macOS 原生组件。
+
+Codex CLI 按 Apache License 2.0 分发，源码与许可证见
+https://github.com/openai/codex。
+
+组件来自项目锁定的 `@openai/codex` 原生 npm 依赖，保留上游的
+`bin/codex`、`bin/codex-code-mode-host`、`codex-path/rg`、
+`codex-resources/zsh/bin/zsh` 和 `codex-package.json` 相对布局。
+原生依赖中的 ripgrep 与 zsh 按各自上游许可证分发：
+https://github.com/BurntSushi/ripgrep 和 https://www.zsh.org/。
+
+安装包不包含 API Key、登录状态、用户配置或项目数据。

apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs

@@ -797,6 +797,16 @@ fn direct_thread_visible_item(
     direct_thread_event_item(root, item)
 }
 
+/// AGC 预写的 canonical 用户条目 id：`direct-codex:{clientTurnId}:user`。
+///
+/// 与 `direct_project_history::is_direct_project_codex_user_item` 的判据同一份口径（前缀 +
+/// `:user` 后缀）。回合生命周期事件的 `userItemId` 只能来自这里或已落盘条目自身的 id；
+/// clientTurnId 缺失时不猜身份，返回 `None` 让前端按"未知归属"处理。
+fn direct_codex_user_item_id_for_client_turn_id(client_turn_id: &str) -> Option<String> {
+    let client_turn_id = client_turn_id.trim();
+    (!client_turn_id.is_empty()).then(|| format!("direct-codex:{client_turn_id}:user"))
+}
+
 fn direct_codex_command_is_game_verification(command: &str) -> bool {
     let command = command.to_ascii_lowercase();
     command.contains("game.static_smoke")
@@ -2927,7 +2937,7 @@ impl CodexAppServerConnection {
                     None => direct_project_local_message_item(
                         "user",
                         current_prompt,
-                        Some(&format!("direct-codex:{client_turn_id}:user")),
+                        direct_codex_user_item_id_for_client_turn_id(client_turn_id).as_deref(),
                     )
                     .map_err(platform_llm::LlmError::InvalidRequest)?,
                 };
@@ -3046,13 +3056,30 @@ impl CodexAppServerConnection {
         };
         turn_start_guard.armed = false;
         let direct_thread_id = direct_thread_id_for_project(history_root);
+        // 回合边界的阶段时间：Turn 上游只有**秒**级 `startedAt` / `completedAt`，秒级截断
+        // 撑不起前端 0.1 秒粒度的展示，也可能让完成时刻落进该轮用户消息的同一秒、落在真实
+        // 发送时间之前，被判成无效边界后整轮新回合被吞掉。因此这里只在宿主处理对应阶段时取
+        // 毫秒钟（与条目侧"没有原生阶段时间就用宿主钟"同一口径），不再读上游秒字段。
+        let direct_turn_started_at_ms = direct_tool_call_now_ms();
+        // 本轮开口用户条目的 canonical id：只从已落盘的那条条目上读身份（`id`，工具条目才用
+        // `call_id`），不在事件侧重造一份。拿不到就留空，让前端按"归属不可证明"处理。
+        let direct_turn_user_item_id = direct_persisted_user_item
+            .as_ref()
+            .and_then(direct_thread_item_identity);
         if self.inner.workspace_mode == CodexAppServerWorkspaceMode::DirectProject {
-            append_direct_thread_event(&direct_thread_id, DirectThreadEvent::turn_started());
+            append_direct_thread_event(
+                &direct_thread_id,
+                DirectThreadEvent::turn_started(direct_turn_started_at_ms)
+                    .with_user_item_id(direct_turn_user_item_id.as_deref()),
+            );
             if let Some(user_item) = direct_persisted_user_item.as_ref() {
                 if let Some(entry_item) = direct_thread_event_item(history_root, user_item) {
+                    // 这里的条目时间可能是启动应答后的观测时间；前端按同一用户条目身份
+                    // 保留更早的真实发送时间，不用此事件时间覆盖它。
+                    let user_item_at = entry_item.at();
                     append_direct_thread_event(
                         &direct_thread_id,
-                        DirectThreadEvent::item_completed(entry_item),
+                        DirectThreadEvent::item_completed(entry_item, user_item_at),
                     );
                 }
             }
@@ -3191,9 +3218,14 @@ impl CodexAppServerConnection {
                             .map_err(platform_llm::LlmError::InvalidRequest)?;
                             direct_project_history.complete_item(&item);
                             if let Some(entry_item) = entry_item {
+                                // `rawResponseItem/completed` 不带阶段时间，宿主处理到这条
+                                // 通知的钟就是该阶段唯一可证明的时间。
                                 append_direct_thread_event(
                                     &direct_thread_id,
-                                    DirectThreadEvent::item_completed(entry_item),
+                                    DirectThreadEvent::item_completed(
+                                        entry_item,
+                                        direct_tool_call_now_ms(),
+                                    ),
                                 );
                             }
                         }
@@ -3322,9 +3354,19 @@ impl CodexAppServerConnection {
                                 if let Some(entry_item) =
                                     direct_thread_visible_item(history_root, item)
                                 {
+                                    // `item/started` 的通知层带 `startedAtMs`：这是工具真正
+                                    // 开始的阶段时间，优先于条目展示时间与宿主钟。
                                     append_direct_thread_event(
                                         &direct_thread_id,
-                                        DirectThreadEvent::item_started(entry_item),
+                                        DirectThreadEvent::item_started(
+                                            entry_item,
+                                            direct_thread_item_event_at_ms(
+                                                &params,
+                                                item,
+                                                false,
+                                                direct_tool_call_now_ms(),
+                                            ),
+                                        ),
                                     );
                                 }
                             }
@@ -3367,9 +3409,19 @@ impl CodexAppServerConnection {
                             && matches!(status, "completed" | "interrupted" | "failed")
                         {
                             terminal_recorded = true;
+                            // 终态时间：`durationMs` 与宿主记下的毫秒起点都可靠时才派生，
+                            // 否则取宿主处理这条终态的钟；上游秒级 `completedAt` 一律不用。
                             append_direct_thread_event(
                                 &direct_thread_id,
-                                DirectThreadEvent::turn_completed(status.to_string()),
+                                DirectThreadEvent::turn_completed(
+                                    status.to_string(),
+                                    direct_thread_turn_completed_at_ms(
+                                        turn,
+                                        Some(direct_turn_started_at_ms),
+                                        direct_tool_call_now_ms(),
+                                    ),
+                                )
+                                .with_user_item_id(direct_turn_user_item_id.as_deref()),
                             );
                         }
                         match status {
@@ -3426,7 +3478,11 @@ impl CodexAppServerConnection {
                         "failed"
                     }
                     .to_string(),
-                ),
+                    // 这条兜底终态没有对应的 app-server 终态载荷，只能取宿主处理它的钟，
+                    // 不能拿最后一次正文或工具更新时间当回合终点。
+                    direct_tool_call_now_ms(),
+                )
+                .with_user_item_id(direct_turn_user_item_id.as_deref()),
             );
         }
         let text = match collect_result {
@@ -3624,6 +3680,15 @@ enum DirectCodexTurnCancelTarget {
 /// 这时显式释放这条守卫并把可读原因返回给界面。释放条件见
 /// [`release_stale_direct_taonier_active_invocation`] 的注释；"正在跑的是另一轮"仍然
 /// 保持原拒绝语义，什么都不释放。
+///
+/// 兜底终态带 `userItemId`：身份取 `release_stale_direct_taonier_active_invocation` 返回的
+/// clientTurnId（客户端回合身份的唯一来源），与正常路径的开口条目 id 同一份 canonical 口径。
+/// 拿不到 clientTurnId 就留空——这一轮不会再有原生终态，猜一个身份会让前端把边界盖到别人身上。
+fn direct_stale_cancel_turn_completed_event(client_turn_id: &str) -> DirectThreadEvent {
+    DirectThreadEvent::turn_completed("aborted".to_string(), direct_tool_call_now_ms())
+        .with_user_item_id(direct_codex_user_item_id_for_client_turn_id(client_turn_id).as_deref())
+}
+
 pub(crate) fn cancel_direct_codex_turn_at(
     root: &Path,
     client_turn_id: Option<&str>,
@@ -3680,7 +3745,7 @@ pub(crate) fn cancel_direct_codex_turn_at(
             // 兜底补一条，否则前端的"最新回合是否在跑"会永远停在运行中。
             append_direct_thread_event(
                 &direct_thread_id_for_project(root),
-                DirectThreadEvent::turn_completed("aborted".to_string()),
+                direct_stale_cancel_turn_completed_event(&released),
             );
             Ok(DirectTurnCancelView {
                 outcome: DIRECT_TURN_CANCEL_OUTCOME_RELEASED.to_string(),
@@ -5006,6 +5071,109 @@ mod tests {
         ));
     }
 
+    /// 阶段时间取自**通知层**字段，形状照抄 codex-cli 0.147 / 0.155 的 v2 协议 schema：
+    /// `item/started` 带 `startedAtMs`、`item/completed` 带 `completedAtMs`（毫秒），
+    /// `turn/completed` 带 `turn.startedAt` / `turn.completedAt`（秒）与 `turn.durationMs`（毫秒）。
+    /// 分类函数把 params 原样交给事件级 `at` 的投影函数，所以字段位置必须在这里钉住；
+    /// 回合边界的秒字段按"不用"锁在这里，避免以后有人再把秒级截断当 0.1 秒精度。
+    #[test]
+    fn direct_lifecycle_stage_times_come_from_notification_params() {
+        let started = serde_json::json!({
+            "threadId": "thread-1",
+            "turnId": "turn-1",
+            "startedAtMs": 1_700_000_000_123u64,
+            "item": {"id": "call-1", "type": "commandExecution", "command": "ls"},
+        });
+        let completed = serde_json::json!({
+            "threadId": "thread-1",
+            "turnId": "turn-1",
+            "completedAtMs": 1_700_000_001_500u64,
+            "item": {"id": "call-1", "type": "commandExecution", "command": "ls"},
+        });
+        for (method, params, expected_at_ms) in [
+            ("item/started", &started, 1_700_000_000_123u64),
+            ("item/completed", &completed, 1_700_000_001_500u64),
+        ] {
+            let Some(CodexTurnEvent::Item {
+                completed,
+                params: event_params,
+            }) = direct_codex_notification_event(method, params, None, None, "turn-1")
+            else {
+                panic!("{method} 必须分类成条目生命周期事件");
+            };
+            let item = event_params.get("item").expect("item payload");
+            assert_eq!(
+                direct_thread_item_event_at_ms(&event_params, item, completed, 9_999),
+                expected_at_ms,
+                "{method} 必须用通知层的阶段时间，而不是宿主钟"
+            );
+        }
+
+        let terminal = serde_json::json!({
+            "threadId": "thread-1",
+            "turn": {
+                "id": "turn-1",
+                "items": [],
+                "status": "completed",
+                "startedAt": 1_700_000_000i64,
+                "completedAt": 1_700_000_042i64,
+            },
+        });
+        let Some(CodexTurnEvent::Terminal(params)) =
+            direct_codex_notification_event("turn/completed", &terminal, None, None, "turn-1")
+        else {
+            panic!("turn/completed 必须分类成终态事件");
+        };
+        let turn = params.get("turn").unwrap_or(&params);
+        assert_eq!(
+            direct_thread_turn_completed_at_ms(turn, Some(1_700_000_000_500), 9_999),
+            9_999,
+            "上游只有秒级 completedAt：不采用，取宿主处理终态的毫秒钟"
+        );
+        let with_duration = serde_json::json!({
+            "id": "turn-1",
+            "items": [],
+            "status": "completed",
+            "startedAt": 1_700_000_000i64,
+            "completedAt": 1_700_000_042i64,
+            "durationMs": 42_500u64,
+        });
+        assert_eq!(
+            direct_thread_turn_completed_at_ms(&with_duration, Some(1_700_000_000_500), 9_999),
+            1_700_000_043_000,
+            "durationMs + 宿主高精度起点才派生结束"
+        );
+    }
+
+    /// 取消兜底终态也要带开口用户条目身份，且身份只有一个来源：release 返回的 clientTurnId
+    /// 走与正常路径同一份 canonical 口径；拿不到（空 / 空白）就留空，不猜。
+    #[test]
+    fn stale_cancel_terminal_event_keeps_opener_user_item_id_from_client_turn_id() {
+        let event = direct_stale_cancel_turn_completed_event("turn-0001");
+        assert_eq!(event.user_item_id(), Some("direct-codex:turn-0001:user"));
+        assert!(event.at().is_some(), "兜底终态仍要带宿主观测时间");
+        assert!(matches!(
+            event,
+            DirectThreadEvent::TurnCompleted { ref status, .. } if status == "aborted"
+        ));
+
+        for missing in ["", "   "] {
+            let event = direct_stale_cancel_turn_completed_event(missing);
+            assert_eq!(
+                event.user_item_id(),
+                None,
+                "拿不到 clientTurnId 时不得编造开口条目身份"
+            );
+        }
+
+        // canonical 口径与落盘侧同一份：`direct-codex:{clientTurnId}:user`。
+        assert_eq!(
+            direct_codex_user_item_id_for_client_turn_id("  turn-0001  ").as_deref(),
+            Some("direct-codex:turn-0001:user")
+        );
+        assert_eq!(direct_codex_user_item_id_for_client_turn_id(""), None);
+    }
+
     fn test_llm() -> GameCreatorLlmConfig {
         GameCreatorLlmConfig {
             custom_enabled: false,
@@ -6740,12 +6908,33 @@ done
 
         let consumed = crate::agent::consume_direct_thread(&bootstrap.subscription_id)
             .expect("consume events");
+        // 回合起止必须与开口用户条目同源：前端在「只有锚点 + 历史、运行态为空」的回合里靠这个
+        // 身份把边界认领给同一条用户条目，缺了它就只能隐藏未知用时。
+        let lifecycle_user_item_ids = consumed
+            .events
+            .iter()
+            .filter(|event| {
+                matches!(
+                    event,
+                    DirectThreadEvent::TurnStarted { .. } | DirectThreadEvent::TurnCompleted { .. }
+                )
+            })
+            .map(DirectThreadEvent::user_item_id)
+            .collect::<Vec<_>>();
+        assert_eq!(
+            lifecycle_user_item_ids,
+            vec![
+                Some("direct-codex:turn-0001:user"),
+                Some("direct-codex:turn-0001:user"),
+            ],
+            "turn.started / turn.completed 都要带本轮开口用户条目的 canonical itemId"
+        );
         let mut user_items = Vec::new();
         let mut assistant_items = Vec::new();
         for event in &consumed.events {
             let item = match event {
-                DirectThreadEvent::ItemStarted { item }
-                | DirectThreadEvent::ItemCompleted { item } => item,
+                DirectThreadEvent::ItemStarted { item, .. }
+                | DirectThreadEvent::ItemCompleted { item, .. } => item,
                 _ => continue,
             };
             match item {

apps/ai-game-creator-shell/src-tauri/src/agent/codex_cli.rs

@@ -5,18 +5,10 @@ use std::process::Stdio;
 use sha2::{Digest, Sha256};
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWriteExt};
 
+#[path = "../../build_support/codex_bundle.rs"]
+mod codex_bundle;
+
 const GAME_CREATOR_CODEX_CLI_EXECUTABLE: &str = "codex";
-const GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH: &str = "coding-agent/win-x64/bin/codex.exe";
-const GAME_CREATOR_BUNDLED_CODEX_CLI_MANIFEST_RELATIVE_PATH: &str =
-    "coding-agent/win-x64/manifest.json";
-const GAME_CREATOR_BUNDLED_CODEX_CLI_REQUIRED_FILES: [&str; 6] = [
-    "bin/codex.exe",
-    "bin/codex-code-mode-host.exe",
-    "codex-path/rg.exe",
-    "codex-resources/codex-command-runner.exe",
-    "codex-resources/codex-windows-sandbox-setup.exe",
-    "codex-package.json",
-];
 const GAME_CREATOR_CODEX_CLI_PROMPT_MAX_BYTES: usize = 4 * 1024 * 1024;
 const GAME_CREATOR_CODEX_CLI_STDOUT_MAX_BYTES: usize = 4 * 1024 * 1024;
 const GAME_CREATOR_CODEX_CLI_STDERR_MAX_BYTES: usize = 256 * 1024;
@@ -38,11 +30,11 @@ fn game_creator_codex_cli_executable_candidates_for(
     path: Option<&std::ffi::OsStr>,
 ) -> Vec<PathBuf> {
     let mut candidates = Vec::new();
+    if let Some(bundled) = game_creator_bundled_codex_cli_path(resource_dir) {
+        candidates.push(bundled);
+    }
     #[cfg(windows)]
     {
-        if let Some(resource_dir) = resource_dir {
-            candidates.push(resource_dir.join(GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH));
-        }
         fn append_native_npm_candidates(candidates: &mut Vec<PathBuf>, npm_root: &Path) {
             let vendor_root = npm_root
                 .join("node_modules")
@@ -109,52 +101,71 @@ fn game_creator_codex_cli_executable_candidates() -> Vec<PathBuf> {
 }
 
 fn game_creator_bundled_resource_dir() -> Option<PathBuf> {
+    let executable = std::env::current_exe().ok()?;
+    game_creator_bundled_resource_dir_for(&executable)
+}
+
+fn game_creator_bundled_resource_dir_for(executable: &Path) -> Option<PathBuf> {
     #[cfg(windows)]
     {
-        std::env::current_exe()
-            .ok()
-            .and_then(|path| path.parent().map(Path::to_path_buf))
+        executable.parent().map(Path::to_path_buf)
     }
-    #[cfg(not(windows))]
+    #[cfg(target_os = "macos")]
     {
+        let macos = executable.parent()?;
+        let contents = macos.parent()?;
+        // 只接受真正的 app bundle 结构，开发态不从任意相邻目录加载程序。
+        if macos.file_name()? != "MacOS"
+            || contents.file_name()? != "Contents"
+            || contents.parent()?.extension()? != "app"
+        {
+            return None;
+        }
+        Some(contents.join("Resources"))
+    }
+    #[cfg(not(any(windows, target_os = "macos")))]
+    {
+        let _ = executable;
         None
     }
 }
 
 fn game_creator_bundled_codex_cli_path(resource_dir: Option<&Path>) -> Option<PathBuf> {
-    resource_dir.map(|resource_dir| resource_dir.join(GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH))
+    let layout = codex_bundle::for_target(env!("AGC_BUILD_TARGET"))?;
+    Some(
+        resource_dir?
+            .join("coding-agent")
+            .join(layout.directory)
+            .join(layout.executable),
+    )
 }
 
 fn validate_game_creator_bundled_codex_cli(executable: &Path) -> Result<String, String> {
+    let layout = codex_bundle::for_target(env!("AGC_BUILD_TARGET"))
+        .ok_or_else(|| "当前平台不支持内置 Codex CLI".to_string())?;
     let bundle_root = executable
         .parent()
         .and_then(Path::parent)
         .ok_or_else(|| "内置 Codex CLI 路径无效".to_string())?;
-    let manifest_path = bundle_root.join(
-        Path::new(GAME_CREATOR_BUNDLED_CODEX_CLI_MANIFEST_RELATIVE_PATH)
-            .file_name()
-            .expect("bundled Codex manifest file name"),
-    );
+    let manifest_path = bundle_root.join("manifest.json");
     let manifest = std::fs::read_to_string(&manifest_path)
         .map_err(|_| "内置 Codex CLI 缺少完整性清单".to_string())
         .and_then(|value| {
             serde_json::from_str::<GameCreatorBundledCodexCliManifest>(&value)
                 .map_err(|_| "内置 Codex CLI 完整性清单无效".to_string())
         })?;
-    if manifest.schema_version != "genarrative-codex-sidecar.v2"
-        || manifest.platform != "win32-x64"
+    if manifest.schema_version != codex_bundle::SCHEMA
+        || manifest.platform != layout.platform
         || manifest.version.trim().is_empty()
-        || GAME_CREATOR_BUNDLED_CODEX_CLI_REQUIRED_FILES
-            .iter()
-            .any(|relative| {
-                manifest.files.get(*relative).map_or(true, |hash| {
-                    hash.len() != 64 || !hash.bytes().all(|byte| byte.is_ascii_hexdigit())
-                })
+        || layout.files.iter().any(|relative| {
+            manifest.files.get(*relative).map_or(true, |hash| {
+                hash.len() != 64 || !hash.bytes().all(|byte| byte.is_ascii_hexdigit())
             })
+        })
     {
         return Err("内置 Codex CLI 完整性清单不受支持".to_string());
     }
-    for relative in GAME_CREATOR_BUNDLED_CODEX_CLI_REQUIRED_FILES {
+    for relative in layout.files {
         let path = bundle_root.join(relative);
         let bytes = std::fs::read(&path).map_err(|_| {
             format!(
@@ -163,7 +174,7 @@ fn validate_game_creator_bundled_codex_cli(executable: &Path) -> Result<String,
             )
         })?;
         let actual = format!("{:x}", Sha256::digest(bytes));
-        if !actual.eq_ignore_ascii_case(manifest.files.get(relative).expect("validated hash")) {
+        if !actual.eq_ignore_ascii_case(manifest.files.get(*relative).expect("validated hash")) {
             return Err(format!("内置 Codex CLI 完整性校验失败：组件 {relative}"));
         }
     }
@@ -899,7 +910,7 @@ mod tests {
     fn codex_cli_candidates_prefer_bundled_sidecar_before_npm_and_path() {
         let temp = tempfile::tempdir().expect("temp dir");
         let resources = temp.path().join("resources");
-        let bundled = resources.join(GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH);
+        let bundled = game_creator_bundled_codex_cli_path(Some(&resources)).unwrap();
         std::fs::create_dir_all(bundled.parent().expect("bundled parent")).expect("bundled dir");
         let app_data = temp.path().join("app-data");
         let native = app_data
@@ -918,20 +929,19 @@ mod tests {
         assert_eq!(candidates[1], native);
     }
 
-    #[cfg(windows)]
+    #[cfg(any(windows, target_os = "macos"))]
     #[test]
     fn bundled_codex_cli_requires_matching_manifest_hash() {
         let temp = tempfile::tempdir().expect("temp dir");
-        let executable = temp
-            .path()
-            .join(GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH);
+        let executable = game_creator_bundled_codex_cli_path(Some(temp.path())).unwrap();
+        let layout = codex_bundle::for_target(env!("AGC_BUILD_TARGET")).unwrap();
         std::fs::create_dir_all(executable.parent().expect("sidecar parent")).expect("sidecar dir");
         let bundle_root = executable
             .parent()
             .and_then(Path::parent)
             .expect("bundle root");
         let mut hashes = std::collections::BTreeMap::new();
-        for relative in GAME_CREATOR_BUNDLED_CODEX_CLI_REQUIRED_FILES {
+        for relative in layout.files {
             let path = bundle_root.join(relative);
             std::fs::create_dir_all(path.parent().expect("component parent"))
                 .expect("component dir");
@@ -939,14 +949,14 @@ mod tests {
             std::fs::write(&path, bytes.as_bytes()).expect("component bytes");
             hashes.insert(relative, format!("{:x}", Sha256::digest(bytes.as_bytes())));
         }
-        let files = serde_json::to_string(&hashes).expect("component hashes");
-        std::fs::write(
-            bundle_root.join("manifest.json"),
-            format!(
-                r#"{{"schemaVersion":"genarrative-codex-sidecar.v2","platform":"win32-x64","version":"codex-cli test","files":{files}}}"#
-            ),
-        )
-        .expect("sidecar manifest");
+        let manifest = serde_json::json!({
+            "schemaVersion": codex_bundle::SCHEMA,
+            "platform": layout.platform,
+            "version": "codex-cli test",
+            "files": hashes,
+        });
+        let manifest_path = bundle_root.join("manifest.json");
+        std::fs::write(&manifest_path, manifest.to_string()).expect("sidecar manifest");
 
         assert_eq!(
             validate_game_creator_bundled_codex_cli(&executable).expect("trusted sidecar"),
@@ -956,15 +966,31 @@ mod tests {
         assert!(validate_game_creator_bundled_codex_cli(&executable)
             .expect_err("tampered sidecar must be rejected")
             .contains("完整性校验失败"));
+        std::fs::write(&executable, format!("trusted {}", layout.executable)).unwrap();
+        let mut wrong_platform = manifest.clone();
+        wrong_platform["platform"] = serde_json::json!("wrong-platform");
+        std::fs::write(&manifest_path, wrong_platform.to_string()).unwrap();
+        assert!(validate_game_creator_bundled_codex_cli(&executable)
+            .expect_err("wrong platform must be rejected")
+            .contains("完整性清单不受支持"));
+        std::fs::write(&manifest_path, manifest.to_string()).unwrap();
+        let helper = bundle_root.join(layout.files[1]);
+        std::fs::write(&helper, b"tampered helper").unwrap();
+        assert!(validate_game_creator_bundled_codex_cli(&executable)
+            .expect_err("tampered helper must be rejected")
+            .contains("完整性校验失败"));
+        std::fs::remove_file(&helper).unwrap();
+        assert!(validate_game_creator_bundled_codex_cli(&executable)
+            .expect_err("missing helper must be rejected")
+            .contains("缺少必需组件"));
     }
 
-    #[cfg(windows)]
+    #[cfg(any(windows, target_os = "macos"))]
     #[test]
     fn bundled_codex_cli_rejects_a_manifest_without_code_mode_host() {
         let temp = tempfile::tempdir().expect("temp dir");
-        let executable = temp
-            .path()
-            .join(GAME_CREATOR_BUNDLED_CODEX_CLI_RELATIVE_PATH);
+        let executable = game_creator_bundled_codex_cli_path(Some(temp.path())).unwrap();
+        let layout = codex_bundle::for_target(env!("AGC_BUILD_TARGET")).unwrap();
         std::fs::create_dir_all(executable.parent().expect("sidecar parent")).expect("sidecar dir");
         let bundle_root = executable
             .parent()
@@ -975,9 +1001,13 @@ mod tests {
         let hash = format!("{:x}", Sha256::digest(bytes));
         std::fs::write(
             bundle_root.join("manifest.json"),
-            format!(
-                r#"{{"schemaVersion":"genarrative-codex-sidecar.v2","platform":"win32-x64","version":"codex-cli test","files":{{"bin/codex.exe":"{hash}"}}}}"#
-            ),
+            serde_json::json!({
+                "schemaVersion": codex_bundle::SCHEMA,
+                "platform": layout.platform,
+                "version": "codex-cli test",
+                "files": { layout.executable: hash },
+            })
+            .to_string(),
         )
         .expect("sidecar manifest");
 
@@ -986,6 +1016,38 @@ mod tests {
             .contains("完整性清单不受支持"));
     }
 
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn macos_bundle_resources_and_candidates_do_not_require_a_development_path() {
+        let executable = Path::new("/Applications/陶泥儿 测试.app/Contents/MacOS/taonier");
+        let resources = game_creator_bundled_resource_dir_for(executable).unwrap();
+        assert_eq!(
+            resources,
+            Path::new("/Applications/陶泥儿 测试.app/Contents/Resources")
+        );
+        let bundled = game_creator_bundled_codex_cli_path(Some(&resources)).unwrap();
+        let candidates = game_creator_codex_cli_executable_candidates_for(
+            Some(&resources),
+            None,
+            None,
+            None,
+            None,
+        );
+        assert_eq!(candidates, vec![bundled, PathBuf::from("codex")]);
+        assert!(
+            game_creator_bundled_resource_dir_for(Path::new("/tmp/target/release/taonier"))
+                .is_none()
+        );
+        assert!(
+            game_creator_bundled_resource_dir_for(Path::new("/tmp/Contents/MacOS/taonier"))
+                .is_none()
+        );
+        assert_eq!(
+            game_creator_codex_cli_executable_candidates_for(None, None, None, None, None),
+            vec![PathBuf::from("codex")],
+        );
+    }
+
     #[cfg(windows)]
     #[test]
     fn codex_cli_resolver_finds_current_native_install() {

apps/ai-game-creator-shell/src-tauri/src/agent/direct_thread_manager.rs

@@ -427,12 +427,16 @@ mod tests {
         }
     }
 
+    /// 事件级阶段时间只在重放稳定性用例里逐个指定；其余用例用一个固定值即可，
+    /// 它们断言的是队列 / 游标语义，不是时间本身。
+    const FIXED_AT_MS: u64 = 1_000;
+
     fn item_started(item_id: &str) -> DirectThreadEvent {
-        DirectThreadEvent::item_started(message(item_id))
+        DirectThreadEvent::item_started(message(item_id), FIXED_AT_MS)
     }
 
     fn item_completed(item_id: &str) -> DirectThreadEvent {
-        DirectThreadEvent::item_completed(message(item_id))
+        DirectThreadEvent::item_completed(message(item_id), FIXED_AT_MS)
     }
 
     fn item_delta(item_id: &str) -> DirectThreadEvent {
@@ -450,7 +454,7 @@ mod tests {
     #[test]
     fn subscribers_have_independent_cursors_on_one_global_queue() {
         let mut manager = DirectThreadManager::with_limits(100, 100_000);
-        manager.append("thread-1", DirectThreadEvent::turn_started());
+        manager.append("thread-1", DirectThreadEvent::turn_started(FIXED_AT_MS));
         let first = manager.subscribe("thread-1");
         let second = manager.subscribe("thread-1");
         manager.append("thread-1", item_started("item-1"));
@@ -474,7 +478,7 @@ mod tests {
     #[test]
     fn bootstrap_contains_lifecycle_anchor_and_unfinished_events_only() {
         let mut manager = DirectThreadManager::with_limits(100, 100_000);
-        manager.append("thread-1", DirectThreadEvent::turn_started());
+        manager.append("thread-1", DirectThreadEvent::turn_started(FIXED_AT_MS));
         manager.append("thread-1", item_started("item-1"));
         manager.append("thread-1", item_delta("item-1"));
         manager.append("thread-1", item_completed("item-1"));
@@ -484,7 +488,7 @@ mod tests {
         assert!(matches!(
             bootstrap.events.as_slice(),
             [
-                DirectThreadEvent::TurnStarted {},
+                DirectThreadEvent::TurnStarted { .. },
                 DirectThreadEvent::ItemStarted { item, .. },
             ] if item.item_id() == "item-2"
         ));
@@ -589,15 +593,118 @@ mod tests {
         let mut manager = DirectThreadManager::with_limits(100, 100_000);
         manager.append(
             "thread-1",
-            DirectThreadEvent::turn_completed("completed".to_string()),
+            DirectThreadEvent::turn_completed("completed".to_string(), FIXED_AT_MS),
         );
         let bootstrap = manager.subscribe("thread-1");
         assert!(matches!(
             bootstrap.events.as_slice(),
-            [DirectThreadEvent::TurnCompleted { status }] if status == "completed"
+            [DirectThreadEvent::TurnCompleted { status, at, .. }]
+                if status == "completed" && *at == Some(FIXED_AT_MS)
         ));
     }
 
+    /// 阶段时间必须随事件一起进队列：bootstrap 与重复订阅都拿到**原值**，
+    /// 重放不得重新取钟（否则每次重连都会把已固定的起止时间改掉）。
+    #[test]
+    fn replayed_events_keep_their_original_stage_time() {
+        let mut manager = DirectThreadManager::with_limits(100, 100_000);
+        manager.append("thread-1", DirectThreadEvent::turn_started(1_000));
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_started(message("item-1"), 2_000),
+        );
+
+        let first = manager.subscribe("thread-1");
+        assert_eq!(
+            first
+                .events
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(1_000), Some(2_000)]
+        );
+
+        // 第二个订阅看到的是同一份事件，时间不因"又取了一次当前时间"而漂移。
+        let second = manager.subscribe("thread-1");
+        assert_eq!(second.events, first.events);
+
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_completed(message("item-1"), 3_000),
+        );
+        let completion = manager
+            .consume(&first.subscription_id)
+            .expect("consume completion")
+            .events;
+        assert_eq!(
+            completion
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(3_000)]
+        );
+        // 重复消费不产生新事件，也不改写已下发过的时间。
+        assert!(manager
+            .consume(&first.subscription_id)
+            .expect("empty consume")
+            .events
+            .is_empty());
+        assert_eq!(
+            completion
+                .iter()
+                .map(DirectThreadEvent::at)
+                .collect::<Vec<_>>(),
+            vec![Some(3_000)]
+        );
+    }
+
+    /// 生命周期锚点重放时必须带上开口用户条目身份：前端在「只有锚点 + 历史切片、运行态一直空」
+    /// 的回合里也要能把边界认领给同一条用户条目，而不是按时间戳猜。
+    #[test]
+    fn bootstrap_replays_opener_user_item_id() {
+        let mut manager = DirectThreadManager::with_limits(100, 100_000);
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::turn_started(1_000)
+                .with_user_item_id(Some("direct-codex:turn-1:user")),
+        );
+        let bootstrap = manager.subscribe("thread-1");
+        assert_eq!(
+            bootstrap
+                .events
+                .iter()
+                .map(DirectThreadEvent::user_item_id)
+                .collect::<Vec<_>>(),
+            vec![Some("direct-codex:turn-1:user")]
+        );
+        assert_eq!(bootstrap.events[0].at(), Some(1_000));
+
+        // 锚点是独立保存的副本：队列里那条事件被回收之后，新订阅仍拿到同一个身份。
+        manager
+            .consume(&bootstrap.subscription_id)
+            .expect("consume anchor");
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::item_completed(message("item-1"), 2_000),
+        );
+        manager.append(
+            "thread-1",
+            DirectThreadEvent::turn_completed("completed".to_string(), 3_000)
+                .with_user_item_id(Some("direct-codex:turn-1:user")),
+        );
+        let second = manager.subscribe("thread-1");
+        assert_eq!(
+            second
+                .events
+                .iter()
+                .map(DirectThreadEvent::user_item_id)
+                .collect::<Vec<_>>(),
+            vec![Some("direct-codex:turn-1:user")],
+            "起止同源：终态锚点也带同一个开口用户条目身份"
+        );
+        assert_eq!(second.events[0].at(), Some(3_000));
+    }
+
     #[test]
     fn queue_cleanup_only_removes_a_cleanable_prefix() {
         let mut manager = DirectThreadManager::with_limits(100, 100_000);

apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs

@@ -662,6 +662,19 @@ impl DirectToolBridgeState {
         );
         Ok((operation_id, idempotency_key))
     }
+
+    /// 不计费的派生请求（如抠图）不进 `resource_request_ids` 计数，只取回合身份做确定性 id 派生。
+    fn active_resource_turn_id(&self) -> Result<String, String> {
+        let authorization = self
+            .turn_authorization
+            .lock()
+            .map_err(|_| "AGC 工具桥回合授权状态不可用".to_string())?;
+        authorization
+            .active
+            .as_ref()
+            .map(|active| active.turn_id.clone())
+            .ok_or_else(|| "当前没有客户端签发的资源生成回合身份".to_string())
+    }
 }
 
 fn direct_resource_request_uuid(turn_id: &str, domain: &str, request_fingerprint: &str) -> String {
@@ -2021,7 +2034,12 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
             })
             .await?
         } else {
-            let (operation_id, idempotency_key) = state.resource_request_ids(&fingerprint)?;
+            // 抠图不计费且服务端秒级完成，不占每回合付费媒体请求的四项额度，不进计数 map；
+            // id 仍按回合身份与请求指纹确定性派生，同指纹重试与 pending 对账语义不变。
+            let turn_id = state.active_resource_turn_id()?;
+            let operation_id = direct_resource_request_uuid(&turn_id, "operation", &fingerprint);
+            let idempotency_key =
+                direct_resource_request_uuid(&turn_id, "idempotency", &fingerprint);
             let revision = read_game_creator_agent_runtime_project_revision(&state.root)?.revision;
             let request = DeriveLocalProjectResourceInput {
                 project_path: state.root.to_string_lossy().into_owned(),
@@ -2416,6 +2434,8 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value)
             slice_mode,
             grid_x,
             grid_y,
+            reference_asset_ids: Vec::new(),
+            target_category: None,
             screen_color,
         };
         let _generation_guard = state.image_generation_gate.lock().await;

apps/ai-game-creator-shell/src-tauri/src/agent/generation.rs

@@ -67,10 +67,11 @@ pub(crate) use canvas_generation::{
     generate_platform_art_asset_with_options_at,
     generate_platform_art_asset_with_required_slices_at, maybe_generate_platform_art_asset_step,
     needs_platform_art_asset_generation, normalize_platform_art_asset_generation_kind,
+    normalize_platform_art_reference_asset_ids, normalize_platform_art_target_category,
     platform_art_asset_art_spec, platform_art_asset_output_extension_matches,
-    prepare_platform_art_asset_output_path, project_canvas_asset_media_types,
-    role_has_canvas_assets, suggested_canvas_tool_call, PlatformArtAssetGenerationOptions,
-    PLATFORM_ART_ASSET_GENERATION_KINDS,
+    platform_art_runtime_references_match_request_contract, prepare_platform_art_asset_output_path,
+    project_canvas_asset_media_types, role_has_canvas_assets, suggested_canvas_tool_call,
+    PlatformArtAssetGenerationOptions, PLATFORM_ART_ASSET_GENERATION_KINDS,
 };
 #[allow(unused_imports)]
 pub(crate) use draft_validation::{

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs

@@ -581,6 +581,8 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio
         slice_mode: (!slice_mode.trim().is_empty()).then_some(slice_mode.clone()),
         grid_x,
         grid_y,
+        reference_asset_ids: Vec::new(),
+        target_category: None,
         screen_color: None,
     };
     if let Some(pending) = pending_action {
@@ -633,6 +635,9 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio
                 .or_else(|| (!slice_mode.trim().is_empty()).then_some(slice_mode)),
             grid_x,
             grid_y,
+            reference_asset_ids: requested_options.reference_asset_ids,
+            // Agent 运行时不会指定完成登记的目标栏目，保持调用方给的值（默认 `None`）。
+            target_category: requested_options.target_category,
             screen_color: requested_options.screen_color,
         }
     };

apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs

@@ -391,6 +391,12 @@ pub(crate) async fn start_local_project_asset_generation(
     image_size: Option<String>,
     asset_name: Option<String>,
     output_path: Option<String>,
+    // 前端 IPC 字段 `referenceAssetIds`：当前项目 manifest 里的图片素材 id，只做参考输入，
+    // 不进任务账本（重试由调用方继续用同一份引用提交，账本本身不新增字段）。
+    reference_asset_ids: Option<Vec<String>>,
+    // 前端 IPC 字段 `targetCategory`：完成登记时要落盘的正式栏目分类。同样不进任务账本：
+    // 它与引用一样属于「同一次提交的本地落点」，重试由调用方继续用同一个栏目提交。
+    target_category: Option<String>,
 ) -> Result<AssetGenerationTaskRecord, String> {
     let task_id = asset_generation_task_id(&task_id)?;
     let request = prepare_local_project_asset_generation(
@@ -401,6 +407,8 @@ pub(crate) async fn start_local_project_asset_generation(
         image_size.as_deref(),
         asset_name.as_deref(),
         output_path.as_deref(),
+        reference_asset_ids.as_deref().unwrap_or_default(),
+        target_category.as_deref(),
     )?;
     enforce_project_permission_policy(&request.root, "canvas.asset_generate")?;
     enforce_project_permission_policy(&request.root, "asset.register")?;