修复发布目标与插件能力门禁并同步版本0.1.67

统一显式目标对应的版本读取、构建渠道、产物目录和更新清单无原生适配器时隐藏Cocos插件并阻止自动启动同步单架构更新规范并增加发布和插件回归测试更新版本与锁文件到0.1.67并记录Mac安装包验证结果
2026-09-18 12:15:00 +08:00
parent 6f012d419a
commit 16c905b51b
20 changed files with 548 additions and 90 deletions
@@ -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",
@@ -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,23 +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 ((explicitTarget || target) === 'universal-apple-darwin') {
-    throw new Error(
-      '内置 Codex 资源仅支持 macOS 单架构构建，请使用 aarch64-apple-darwin 或 x86_64-apple-darwin',
-    );
-  }
+  if (!noBundle || explicitTarget)
+    validateReleaseTarget(explicitTarget || target);
  const features = defaultEditorFeatures(
    explicitTarget || (noBundle ? platform : target),
  );
@@ -379,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' },
@@ -407,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;
@@ -421,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);
@@ -432,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
  );
@@ -455,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);
@@ -609,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}`);
  }
@@ -628,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');
@@ -680,14 +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);
-  // 目标校验必须先于远端版本读取与本地版本文件写入。
-  buildTauriBuildArguments(args);
-  if (!args.includes('--no-bundle')) await prepareReleaseVersion();
-  runTauriBuild(args);
-  if (!args.includes('--no-bundle')) await generateUpdateManifest();
+  await buildRelease(args);
 }
@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';

 import {
  agcReleasePathPatterns,
+  buildRelease,
  buildTauriBuildArguments,
  collectRecentReleaseCommits,
  collectReleaseCommits,
@@ -23,11 +24,14 @@ import {
  createUpdateManifest,
  formatRecentReleaseNotes,
  formatReleaseNotes,
+  generateUpdateManifest,
  nextPatchVersion,
  resolveManifestPlatformKeys,
  resolvePreviousReleaseCommit,
  resolveReleaseChannel,
+  resolveReleaseContext,
  resolveRemoteHighWaterVersion,
+  runTauriBuild,
  selectReleaseArtifact,
  updateManifestUrl,
 } from './build-release.mjs';
@@ -148,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), [
@@ -158,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: '修复与改进' }, () => {
@@ -361,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', () => {
@@ -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 指针，必须显式覆盖，否则流水线会误报成功但远端仍保留旧版本。
@@ -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",
@@ -1,6 +1,6 @@
 [package]
 name = "genarrative-ai-game-creator-shell"
-version = "0.1.47"
+version = "0.1.67"
 edition = "2021"
 publish = false

@@ -237,7 +237,7 @@ fn persist(guard: &BuiltinPluginState) -> Result<(), String> {
 /// Agent 工具面是否可用：编译期 feature 打开且用户没有禁用该内置插件。
 pub(crate) fn agent_tool_available(plugin: BuiltinPlugin) -> bool {
    plugin.exposes_agent_tools()
-        && cfg!(feature = "cocos-editor-execute")
+        && cfg!(all(windows, feature = "cocos-editor-execute"))
        && is_enabled(plugin.id())
 }

@@ -431,7 +431,7 @@ mod tests {
        let _guard = test_lock();
        let directory = tempdir().expect("temp config");
        initialize(directory.path()).expect("initialize");
-        let tool_visible_when_enabled = cfg!(feature = "cocos-editor-execute");
+        let tool_visible_when_enabled = cfg!(all(windows, feature = "cocos-editor-execute"));

        set_enabled(AGC_COCOS_EDITOR_PLUGIN_ID, true).expect("enable");
        assert_eq!(
@@ -4,10 +4,10 @@
 //! 目前由宿主在编译期链接（Cargo path 依赖），再按插件 manifest 的 `adapter`
 //! 字段注册到通用插件宿主。宿主只认适配器 id，不包含目标编辑器知识。

-#[cfg(feature = "cocos-editor")]
+#[cfg(all(windows, feature = "cocos-editor-execute"))]
 use std::path::PathBuf;

-#[cfg(feature = "cocos-editor")]
+#[cfg(all(windows, feature = "cocos-editor-execute"))]
 use tauri::Manager;

 use crate::plugin_host::PluginHost;
@@ -21,20 +21,20 @@ pub(crate) fn register_linked_editor_adapters(
    app: &tauri::AppHandle,
    host: &PluginHost,
 ) -> Result<(), String> {
-    #[cfg(feature = "cocos-editor")]
+    #[cfg(all(windows, feature = "cocos-editor-execute"))]
    {
        let adapter =
            cocos_editor_bridge::CocosEditorAdapter::new(cocos_bridge_payload_candidates(app));
        host.register_editor_adapter(Box::new(adapter))?;
    }
-    #[cfg(not(feature = "cocos-editor"))]
+    #[cfg(not(all(windows, feature = "cocos-editor-execute")))]
    {
        let _ = (app, host);
    }
    Ok(())
 }

-#[cfg(feature = "cocos-editor")]
+#[cfg(all(windows, feature = "cocos-editor-execute"))]
 fn cocos_bridge_payload_candidates(app: &tauri::AppHandle) -> Vec<PathBuf> {
    let mut candidates = Vec::new();
    if let Ok(resource_dir) = app.path().resource_dir() {
@@ -767,6 +767,22 @@ fn permission_for_method(method: &str) -> Option<&'static str> {
    }
 }

+fn has_cocos_editor_adapter(editors: &EditorRegistry) -> Result<bool, String> {
+    Ok(editors
+        .lock()
+        .map_err(|_| "编辑器注册表锁已损坏".to_string())?
+        .contains_key("cocos-editor"))
+}
+
+fn require_plugin_adapter(id: &str, editors: &EditorRegistry) -> Result<(), String> {
+    if id == crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID
+        && !has_cocos_editor_adapter(editors)?
+    {
+        return Err("当前客户端不支持 Cocos 编辑器桥接".to_string());
+    }
+    Ok(())
+}
+
 impl PluginHost {
    pub(crate) fn initialize(&self, config_dir: &Path) -> Result<(), String> {
        let root = plugin_root(config_dir)?;
@@ -948,11 +964,12 @@ impl PluginHost {
                    .flatten()
                    .is_some()
            });
+        let cocos_available = cocos_project && has_cocos_editor_adapter(&state.editors)?;
        state
            .plugins
            .values()
            .filter(|record| {
-                record.id != crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID || cocos_project
+                record.id != crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID || cocos_available
            })
            .map(|record| self.summary_locked(record))
            .collect()
@@ -1017,6 +1034,7 @@ impl PluginHost {
            .clone()
            .ok_or_else(|| "插件宿主尚未初始化".to_string())?;
        let active_project = state.active_project.clone();
+        require_plugin_adapter(id, &state.editors)?;
        if id == crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID
            && !active_project
                .lock()
@@ -1124,6 +1142,7 @@ impl PluginHost {
            .state
            .lock()
            .map_err(|_| "插件宿主锁已损坏".to_string())?;
+        require_plugin_adapter(id, &state.editors)?;
        let record = state
            .plugins
            .get(id)
@@ -1535,6 +1554,7 @@ impl PluginHost {
                Ok(json!({"path": input.path, "content": content}))
            }
            "host.rpc" => {
+                require_plugin_adapter(&manifest.id, editors)?;
                let input: EditorRpcInput = descriptor_from_params(params)?;
                if manifest.id == crate::builtin_plugins::AGC_COCOS_EDITOR_PLUGIN_ID
                    && !active_project
@@ -2122,6 +2142,8 @@ setTimeout(() => send({ jsonrpc: '2.0', id: 1, method: 'host.registerCommand', p
        let host = PluginHost::default();
        crate::builtin_plugins::initialize(directory.path()).expect("builtin plugin state");
        host.initialize(directory.path()).expect("initialize");
+        host.register_editor_adapter(Box::new(StubCocosAdapter))
+            .expect("register adapter");
        host.set_plugin_workspace(workspace)
            .expect("set plugins workspace");
        host.set_active_project(Some(directory.path().to_string_lossy().into_owned()))
@@ -2223,6 +2245,8 @@ setTimeout(() => send({ jsonrpc: '2.0', id: 1, method: 'host.registerCommand', p
        let workspace = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../../plugins");
        let host = PluginHost::default();
        host.initialize(directory.path()).expect("initialize");
+        host.register_editor_adapter(Box::new(StubCocosAdapter))
+            .expect("register adapter");
        host.set_plugin_workspace(workspace).expect("set workspace");

        let project = tempdir().expect("web project");
@@ -2235,4 +2259,53 @@ setTimeout(() => send({ jsonrpc: '2.0', id: 1, method: 'host.registerCommand', p
            .all(|plugin| plugin.id != "agc-cocos-editor"));
        assert!(host.start("agc-cocos-editor").is_err());
    }
+
+    #[test]
+    fn cocos_plugin_requires_registered_adapter_even_for_a_cocos_project() {
+        let _guard = crate::builtin_plugins::test_lock();
+        let directory = tempdir().expect("temp config");
+        fs::write(
+            directory.path().join("package.json"),
+            r#"{"creator":{"version":"3.8.8"}}"#,
+        )
+        .unwrap();
+        fs::create_dir(directory.path().join("assets")).unwrap();
+        crate::builtin_plugins::initialize(directory.path()).unwrap();
+        let host = PluginHost::default();
+        host.initialize(directory.path()).unwrap();
+        host.set_plugin_workspace(Path::new(env!("CARGO_MANIFEST_DIR")).join("../../../plugins"))
+            .unwrap();
+        host.set_active_project(Some(directory.path().to_string_lossy().into_owned()))
+            .unwrap();
+        assert!(host
+            .list()
+            .unwrap()
+            .iter()
+            .all(|plugin| plugin.id != "agc-cocos-editor"));
+        assert!(host
+            .list_extensions()
+            .unwrap()
+            .iter()
+            .all(|plugin| plugin.id != "agc-cocos-editor"));
+        assert!(host
+            .start("agc-cocos-editor")
+            .err()
+            .expect("unsupported adapter")
+            .contains("不支持 Cocos"));
+        assert!(host
+            .read_panel("agc-cocos-editor", "cocos-editor")
+            .err()
+            .expect("unsupported adapter")
+            .contains("不支持 Cocos"));
+        assert!(host.state.lock().unwrap().plugins["agc-cocos-editor"]
+            .running
+            .is_none());
+        host.register_editor_adapter(Box::new(StubCocosAdapter))
+            .unwrap();
+        assert!(host
+            .list()
+            .unwrap()
+            .iter()
+            .any(|plugin| plugin.id == "agc-cocos-editor"));
+    }
 }
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "陶泥儿",
-  "version": "0.1.47",
+  "version": "0.1.67",
  "identifier": "world.genarrative.ai-game-creator",
  "build": {
    "beforeDevCommand": "npm --prefix ../.. run agc:serve",
@@ -301,7 +301,10 @@ import {
  currentPlatformSessionGeneration,
  requestPlatformSessionRefresh,
 } from './services/platformSession';
-import { setAgcPluginProjectPath, startAgcPlugin } from './services/pluginHost';
+import {
+  setAgcPluginProjectPath,
+  startAvailableAgcPlugin,
+} from './services/pluginHost';
 import {
  canSubscribeTauriEvents,
  subscribeTauriEvent,
@@ -612,7 +615,7 @@ export function App({
    void setAgcPluginProjectPath(nextProjectPath)
      .then(async () => {
        if (workspaceProjectKind === 'cocos' && nextProjectPath) {
-          await startAgcPlugin('agc-cocos-editor');
+          await startAvailableAgcPlugin('agc-cocos-editor');
        }
      })
      .catch((error) => {
@@ -33,6 +33,16 @@ export async function startAgcPlugin(id: string) {
  }) as Promise<AgcPluginSummary>;
 }

+/** 只消费宿主的能力投影，不因项目类型自行推断原生适配器是否存在。 */
+export async function startAvailableAgcPlugin(id: string) {
+  const plugins = await listAgcPlugins();
+  const plugin = plugins.find((candidate) => candidate.id === id);
+  if (!plugin?.enabled || !plugin.hasRuntime || plugin.status === 'invalid') {
+    return;
+  }
+  return startAgcPlugin(id);
+}
+
 export async function stopAgcPlugin(id: string) {
  return invokeOrThrow()('stop_agc_plugin', {
    id,
@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { startAvailableAgcPlugin } from '../src/services/pluginHost';
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('插件自动启动使用后端能力投影', () => {
+  it.each(
+    [
+      [],
+      [
+        {
+          id: 'agc-cocos-editor',
+          enabled: false,
+          hasRuntime: true,
+          status: 'stopped',
+        },
+      ],
+      [
+        {
+          id: 'agc-cocos-editor',
+          enabled: true,
+          hasRuntime: false,
+          status: 'package',
+        },
+      ],
+      [
+        {
+          id: 'agc-cocos-editor',
+          enabled: true,
+          hasRuntime: true,
+          status: 'invalid',
+        },
+      ],
+    ].map((plugins) => ({ plugins })),
+  )('隐藏、禁用或不可执行的插件不启动（%j）', async ({ plugins }) => {
+    const invoke = vi.fn(async () => plugins);
+    vi.stubGlobal('window', { __TAURI__: { core: { invoke } } });
+    await startAvailableAgcPlugin('agc-cocos-editor');
+    expect(invoke).toHaveBeenCalledTimes(1);
+    expect(invoke).toHaveBeenCalledWith('list_agc_plugins');
+  });
+
+  it('支持的 Cocos 插件继续按原入口启动', async () => {
+    const invoke = vi.fn(async (command: string) =>
+      command === 'list_agc_plugins'
+        ? [
+            {
+              id: 'agc-cocos-editor',
+              enabled: true,
+              hasRuntime: true,
+              status: 'stopped',
+            },
+          ]
+        : {},
+    );
+    vi.stubGlobal('window', { __TAURI__: { core: { invoke } } });
+    await startAvailableAgcPlugin('agc-cocos-editor');
+    expect(invoke).toHaveBeenLastCalledWith('start_agc_plugin', {
+      id: 'agc-cocos-editor',
+    });
+  });
+});
@@ -1,12 +1,14 @@
 # Mac 客户端随包运行依赖补齐实施计划

- Version: 1
+- Version: 2
 - Status: awaiting-windows-acceptance
 - Date: 2026-09-18
 - Parent Spec: `【里程碑】Mac客户端随包运行依赖补齐-2026-09-18.md`

 ## 修改顺序

+本轮评审修复顺序：统一 release context（覆盖 build/upload 两入口）→ 版本/端点/产物/清单的定向回归 → 宿主列表/启动/面板与前端自动启动能力门禁 → 同步单架构权威文档 → Node/Vitest/Rust/typecheck/编码/文档/diff 检查。用户随后授权同步 master、重打 0.1.67 并推送当前 PR 分支；不读取私钥、不上传安装包、不合并 PR。
+
 1. 提取构建与运行共用的 Codex 平台布局；按 Cargo TARGET stage 锁定原生依赖并校验包元数据，保留可执行位。
 2. 增加 macOS 专属 Tauri 资源映射、声明、产物忽略规则；复用插件 staging，不复制 Windows 原生 payload。
 3. 修正 `.app/Contents/Resources` 定位与平台清单验证，保持外部安装回退。
@@ -18,7 +20,7 @@
 - `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml agent::codex_cli::tests:: -- --test-threads=1`
 - `npm run ai-game-creator-shell:typecheck`
 - 定向 Node 打包契约测试、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
- 本地 Tauri 构建关闭 updater artifact；不修改源码版本或读取发布私钥，不运行 release upload。
+- 本地 Tauri 构建关闭 updater artifact；版本按用户要求统一为 0.1.67，不读取发布私钥，不运行 release upload。

 ## 风险与停止条件

@@ -1,6 +1,6 @@
 # Mac 客户端随包运行依赖补齐

- Version: 1
+- Version: 2
 - Status: awaiting-windows-acceptance
 - Date: 2026-09-18
 - Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` / Runtime 边界 / 安装包侧车
@@ -27,6 +27,14 @@

 ## 验收现状与剩余门禁

+### 评审反馈修订合同
+
+2026-09-18 编码前自审：本轮仅修复同里程碑的目标平台传递、Cocos 能力门禁和文档冲突，不新增原生桥接或发布管线。CLI 显式目标必须覆盖环境默认，并在版本、构建、产物和清单全链路保持一致；不支持平台或渠道错配应在副作用前失败。Cocos 必须由已注册适配器决定可见/启动，覆盖无适配器、有适配器及非 Cocos 项目；前端不盲目启动隐藏插件。更新权威文档改为单架构策略，拒绝 universal，且不宣称现有发布脚本支持跨构建合并两种架构。新增回归通过后仍等待 Windows 验收；本地 0.1.67 版本修改保留，不与旧 0.1.47 安装包证据混淆。
+
+评审修复验证：发布/feature/上传脚本测试 32 项通过，前端插件自动启动 5 项通过，Rust PluginHost 11 项与内置插件 10 项通过；Rust 使用 `TMPDIR=/private/tmp` 避免 macOS `/var` 系统链接触发既有路径安全断言。类型/配置、定向 ESLint、编码、文档索引和 diff 检查通过。测试覆盖显式目标覆盖环境、错误渠道提前拒绝、Tauri 实际注入配置、真实临时清单写入、Windows 默认 feature 保留、无 adapter 隐藏/启动拒绝、有 adapter RPC 回归。上述是自动化证据，不代表 Windows 真机、GUI 或带本次修复的新安装包已验收。
+
+重打验证：重新 fetch/merge `origin/master` 确认当前分支已包含最新 master；按用户要求将 package、Tauri、Cargo 与锁文件版本同步到 `0.1.67`。包含上述修复的 Release `.app` 构建通过，Info.plist 实测版本 `0.1.67`、最低系统 `15.0`；隔离安装包脚本再次通过，DMG 用 hdiutil 生成并校验通过。此版本仍等待用户 GUI 与 Windows 回归，不做正式签名、公证、更新签名或产物上传。
+
 - Mac 本地测试包已由用户确认“可以用了”；不外推为全部对话、工具和其它机器兼容性已覆盖。
 - 定向 Rust 验证 14 项通过，1 项真实认证用例按原配置跳过；发布脚本测试 21 项通过；隔离 HOME/PATH 的安装包资源检查、正式 Codex 查找、app-server 握手及缺组件拒绝通过。
 - 类型与配置、编码、文档索引、定向脚本 lint 和 diff 检查通过；139 MiB DMG 完整性通过。
@@ -1,5 +1,9 @@
 # 踩坑与排障记录

+## 发布目标与原生能力必须贯穿完整入口
+
+显式 `--target` 不能只改变 Tauri 命令参数；AGC 发布入口必须把同一解析结果传给版本高水位、更新端点、产物目录/后缀和清单平台键，否则 macOS 构建可能错误使用 Windows 渠道。插件文件存在也不代表 native 能力可用：Cocos 在宿主注册表缺少适配器时应隐藏并拒绝启动，前端自动启动消费后端列表投影，不能仅凭项目类型推断能力。发布策略以客户端更新权威文档为准，单架构资源不能登记成双架构产物。
+
 ## macOS 安装包小不代表运行依赖齐全

 AGC 的 DMG 生成成功只证明应用可以被打包。平台专属 Codex staging、Tauri resource 映射、运行时资源目录定位和辅助组件 SHA-256 清单必须同时闭合；只配置 Windows 资源会让 Mac 开发机因全局 Codex 而掩盖缺包。macOS 使用锁定原生依赖中的 Codex、code-mode host、rg 和 zsh，不能复制 Windows EXE/DLL。用 `scripts/check-macos-bundle.mjs`（AGC 应用目录下）对复制到临时目录的 `.app` 做限制 PATH、隔离 HOME 的正式查找、app-server 握手和缺组件拒绝检查；GUI、账号、Provider 与 Cocos 原生桥接另行验收。插件 JS 入口仍依赖系统 Node，不得将“插件文件随包”表述为“无需任何外部工具链”。
@@ -75,11 +75,11 @@
 | 渠道      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
 | --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
 | `dev-win` | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/dev-win/latest.json` |
-| `dev-mac` | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig`  | `<OSS base>/agc/dev-mac/latest.json` |
+| `dev-mac` | `aarch64-apple-darwin` 或 `x86_64-apple-darwin` | 对应 `darwin-aarch64` 或 `darwin-x86_64` | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/dev-mac/latest.json` |

 - 对象布局：清单固定写成 `agc/<channel>/latest.json`；安装包与签名写成 `agc/<channel>/<version>/<file>` 与 `<file>.sig`。
- macOS 使用 universal 包：`dev-mac` 按 universal 目标构建（Intel 与 Apple Silicon 共用一个包），清单把同一个 `.app.tar.gz` 与同一个签名分别写入 `darwin-aarch64` 与 `darwin-x86_64`，升级后仍是 universal 包。这是 Tauri 官方发布工具对 universal 产物的既有写法。
- 上一条的两个键不能合成单一 `darwin-universal` 键：更新插件按运行时实际架构解析清单键（Apple Silicon 命中 `darwin-aarch64`，Intel 命中 `darwin-x86_64`），不存在自动命中 `darwin-universal` 的情形。将来真要单独发该键，必须在客户端同时设置自定义 target，否则清单里这一项永远不会被读取。
+- macOS 当前采用单架构包：Apple Silicon 使用 `aarch64-apple-darwin`，Intel 使用 `x86_64-apple-darwin`；每次生成的清单只登记本次实际构建的架构，不把单架构原生 Codex 资源挂到另一架构。`universal-apple-darwin` 在版本读取/写入、构建和清单生成之前拒绝。
+- 渠道清单以实际运行架构为键。两种单架构构建不可轮流覆盖同一个 `latest.json` 并宣称双架构均可更新；当前不实现跨构建合并，Intel 发布需先完成其构建验证与多架构清单发布方案。
 - 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
 - 版本递增按渠道独立进行：发布脚本读取该渠道远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；两个渠道的版本号互不影响。
 - 版本高水位：发布脚本取「渠道清单版本」与「旧协议迁移指针版本」（迁移窗口内）中的较大值再递增。只看渠道清单会在渠道启用初期把版本链改小 —— 2026-09-17 首次渠道发布即把旧指针的 0.1.57 退回 0.1.48，随后以显式 0.1.60 纠偏；迁移窗口结束（旧指针 404）后自动只剩渠道清单，`dev-mac` 不参与旧指针比较。
@@ -90,6 +90,7 @@
 ## 构建与发布

 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
+- 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由构建参数显式指定，并按目标平台校验：Windows 目标只允许 `dev-win`，macOS 目标只允许 `dev-mac`；未显式指定时按目标平台取默认渠道。
 - 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
@@ -105,7 +106,7 @@
 | 条款                         | 验收方式                                                                | 证据                                                                                                                                 |
 | ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 渠道与端点映射、渠道校验     | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过（默认渠道、错配失败关闭、未知渠道失败关闭）                                                                                     |
-| universal 包挂两个平台键     | 同上 + 本地发布烟测（伪造 bundle）                                      | 通过（两键同 URL 同签名，不生成迁移清单）                                                                                            |
+| macOS 单架构清单与 universal 拒绝 | 定向发布脚本测试 | 单架构各用对应平台键；拒绝未闭合的 universal 发布 |
 | 缺签名时失败关闭             | 同上                                                                    | 通过                                                                                                                                 |
 | 开发态不检查更新             | `vitest run apps/ai-game-creator-shell/tests/appUpdate.test.ts`         | 通过（开关关闭时不请求清单）                                                                                                         |
 | 旧自研链路整条删除           | 代码检索无残留命令、事件与白名单条目                                    | 通过（`download_agc_update` / 下载事件 / 清单常量均无残留）                                                                          |
@@ -127,7 +128,7 @@

 已决策：

- macOS 采用 universal 包，同一产物同时挂 `darwin-aarch64` 与 `darwin-x86_64` 两个清单键（见「契约与迁移」）。
+- macOS 采用单架构包，只登记实际构建架构；Intel 真机构建与跨架构清单合并未验收，不公开宣称双架构分发就绪。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
 - macOS 发布方式：`dev-mac` 产物在本机 mac 上执行发布入口上传，Jenkins 暂不新增 macOS 节点；macOS 代码签名与公证凭据未确认前，相关闭环记为未验证项，不静默通过。
@@ -71,6 +71,8 @@ OpenAI 的标准模型是“Plugin 作为可安装包，组合 Skills、可选 M

 Windows 与 macOS 构建都将内置插件的清单、JS 入口与面板复制到应用资源目录；staging 每次重建，避免已删除插件或跨目标原生 payload 残留。macOS 不携带 Windows native payload。Cocos 进程桥接仍仅按既有 Windows 平台实现提供，插件文件可被发现不代表 macOS 已支持编辑器控制；JS 入口的系统 Node 前提不变。

+Cocos 插件对用户可见与可启动必须同时满足当前为 Cocos 项目、宿主已注册 `cocos-editor` 原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器仅在 Windows 且编译 `cocos-editor-execute` 时注册；Agent 工具使用相同平台与 feature 门禁。前端只按后端列表投影判断是否自动启动，不自行推断平台能力。
+
 ### 内置插件与可用开关

 `plugins/` 工作区里的插件是**内置插件**：随客户端分发，用户不能卸载或删除，只能通过可用开关控制是否生效。开关状态持久化在 AppData `extensions/builtin-plugins.json`（`schemaVersion = agc.builtin-plugins.v1`，`enabled` 是 id 到布尔的映射）；文件缺失按插件 manifest 的 `enabled` 处理，坏文件失败关闭。内置插件优先级高于同名导入插件，AppData 里的同名 Plugin 不会覆盖或间接卸载它。
@@ -356,6 +356,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 内置插件的清单、运行入口与面板同时在 Windows/macOS 随包分发，继续由既有 PluginHost 的应用资源目录扫描入口发现；不携带开发依赖、缓存、测试或私有配置。插件文件随包不等于原生适配器跨平台：Cocos 进程桥接仍受现有 Windows 实现和 feature 门禁约束，macOS 原生桥接另行设计与验收，不复制 Windows DLL 冒充支持。系统 Node、用户 Cocos Creator、账号登录、网络和生成工程的 npm 工具链仍是现有外部前提，不在此次 Codex 侧车补齐中隐式变更。
 - macOS 安装包验收必须包括：脱离仓库位置的 `.app` 资源与架构检查、受限 PATH/隔离 HOME 下内置 Codex 启动和 app-server 握手、必需文件缺失/篡改/平台错误的拒绝测试，以及 DMG 完整性检查。真实登录、Provider 对话、GUI 和 Cocos 操作必须独立列出证据，不能用压缩包生成或 `--version` 成功替代。未配置正式签名、公证的本地测试包不得作为公开发行包。
 - macOS 安装包的系统下限取主程序和全部原生组件中的最高要求；锁定 Codex 0.147.0 原生依赖所携带的 zsh 要求 macOS 15.0，因此 `bundle.macOS.minimumSystemVersion` 明确为 `15.0`。更新原生依赖时重新检查 Mach-O 的系统下限，不能只按 AGC 主程序宣称兼容版本。
+- 发布链路的目标解析和单架构清单以《AGC客户端更新检查与下载》为准：CLI 目标优先，版本、构建、端点、bundle 与更新清单共用单一发布上下文。插件能力以《AGC通用插件宿主与编辑器适配》为准：无已注册 Cocos 原生适配器时隐藏且拒绝启动，前端自动启动只消费后端可用性投影。
 - CLI 安全边界：CLI 固定使用 argv 启动，禁止 shell 拼接；工作目录使用本次请求专用的空临时目录，不把游戏项目绝对路径写入 prompt、stdout、stderr 或持久记录。调用固定使用 ephemeral、忽略用户配置和 exec rules、read-only sandbox、never approval，并关闭 Codex shell tool；只继承 CLI 运行和认证所需的最小环境，显式移除宿主 `CODEX_API_KEY`。用户级 Codex 登录态继续由本机 Codex 自己读取，API Key、auth 文件、Cookie、Token、`CODEX_HOME` 私有内容不得复制到项目配置、Runtime sidecar、Agent DB、conversation 或日志；stdout / stderr 无换行时也受硬上限约束，stderr 诊断只记录固定分类、字节数和 SHA-256。
 - 协议边界：Runtime 把既有 `LlmRunRequest` 的消息和当前函数目录编码为有界 prompt，并从同一函数 JSON Schema 生成 Codex structured-output schema。CLI 输出转换为现有 `LlmRunResponse / LlmToolCall` 后，继续经过 native tool / MCP 参数校验、动作上限、权限、pending、receipt、验证与格式修复链；最终回复仍走唯一提交路径，不新增平行响应协议。
 - 取消与恢复：Codex 子进程绑定当前 Provider request lifecycle，取消、暂停、Runner draining 或 GUI owner 丢失时终止并回收当前进程；started 后没有可信终态仍沿现有 Provider reconciliation 处理。`agentMode`、CLI 可执行身份和影响输出的 Codex 参数进入 `providerConfigFingerprint`，模式切换不得消费另一模式遗留的 retry/handoff。
@@ -95,7 +95,7 @@
    },
    "apps/ai-game-creator-shell": {
      "name": "@genarrative/ai-game-creator-shell",
-      "version": "0.1.47",
+      "version": "0.1.67",
      "dependencies": {
        "@cubone/react-file-manager": "^1.35.0",
        "@genarrative/image-canvas-core": "0.1.0",