补齐跨工程插件启动的界面测试响应

为五个项目打开与对话恢复测试提供插件项目绑定及空插件列表响应

保留原有业务状态断言和产品错误提示，修复完整界面门禁暴露的测试桩缺口

.gitattributes

@@ -23,3 +23,6 @@
 *.meta text
 *.anim text
 *.controller text
+
+# Rust ts-rs 生成的共享契约：保留在仓库中供 TS 消费，但不作为手写源文件统计。
+packages/shared/src/contracts/generated/** linguist-generated=true

.gitea/workflows/project-ci.yml

@@ -221,8 +221,7 @@ jobs:
       - name: Run AI game creator shell agent-run smoke
         run: npm run check:native-shells:agc-rust-smoke
 
-  # AGC 壳依赖的共享 / 平台 crate 测试用的是 server-rs workspace 与两个无锁独立 crate
+  # AGC 壳依赖的共享 / 平台和编辑器插件 crate 各自预热独立 manifest，再运行对应测试。
-  # 的 manifest，属另一套依赖图，因此单独一个 job 预热、单独跑。
   ai-game-creator-shell-rust-crates:
     name: AI game creator shell Rust crates
     runs-on: genarrative-ci
@@ -263,13 +262,15 @@ jobs:
           # `cargo test --manifest-path` 单独跑这两个 crate。不在这里预热的话，这两条测试
           # 会在测试阶段自己 `Updating crates.io index`，crates.io 一抖动整条 job 就红
           # （见 #327 / PR #316 run 1950）。
-          # 两个 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
+          # Cocos 插件也使用独立且未提交的锁文件，一并预热。
+          # 这些 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
           # 加锁标志会因为缺少锁文件直接失败。生成的 Cargo.lock 落在两个 crate 目录内，
           # 已被各自的 .gitignore 忽略，只留在容器里；随后的测试阶段因此能用锁定版本
           # 解析，不再触碰 registry index。
           for manifest_path in \
             server-rs/crates/agent-runtime-core/Cargo.toml \
-            server-rs/crates/agent-runtime-orchestration/Cargo.toml; do
+            server-rs/crates/agent-runtime-orchestration/Cargo.toml \
+            plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml; do
             for attempt in $(seq 1 5); do
               if cargo fetch \
                 --target x86_64-unknown-linux-gnu \
@@ -284,6 +285,23 @@ jobs:
             done
           done
 
+      - name: Prepare Unity plugin Rust dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          for attempt in $(seq 1 5); do
+            if cargo fetch --locked \
+              --target x86_64-unknown-linux-gnu \
+              --manifest-path plugins/agc-unity-editor/native/unity-editor-bridge/Cargo.toml; then
+              break
+            fi
+            if [[ "${attempt}" -eq 5 ]]; then
+              echo 'Unity plugin Cargo dependency fetch failed after 5 attempts.' >&2
+              exit 1
+            fi
+            sleep $((attempt * 2))
+          done
+
       - name: Run AI game creator shell shared crate gates
         run: npm run check:native-shells:agc-rust-crates
 

.gitignore

@@ -41,7 +41,17 @@ 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/
+/plugins/agc-unity-editor/dotnet/**/bin/
+/plugins/agc-unity-editor/dotnet/**/obj/
+/plugins/agc-unity-editor/dotnet/publish/
+/plugins/agc-unity-editor/dotnet/native-build/
 /apps/ai-game-creator-shell/logs/
 /apps/ai-game-creator-shell/.llm-drafts/
 /apps/ai-game-creator-shell/game-creator.config.local.json

.prettierrc.json

@@ -1,5 +1,14 @@
 {
   "singleQuote": true,
   "semi": true,
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "overrides": [
+    {
+      "files": "packages/shared/src/contracts/generated/**/*.ts",
+      "options": {
+        "printWidth": 1000,
+        "singleQuote": false
+      }
+    }
+  ]
 }

CONTEXT.md

@@ -50,24 +50,6 @@ _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成
 
 ## Language
 
-### 3D Model Generation
-
-**3D 模型生成操作**:
-由文本提示驱动、可异步查询并最终产生模型文件的 provider-neutral 操作；操作状态和产品资源结果分开建模。
-_Avoid_: 直接把第三方 provider task 当作产品资源、把模型 URL 当作永久资源地址
-
-**Provider task**:
-第三方 3D 生成平台返回的任务引用与任务快照，只存在于 provider adapter 的 Rust 边界内；它不是 Genarrative 的内部操作 ID。
-_Avoid_: 把 Tripo task ID 当作稳定产品 operationId、让 SDK 类型穿透 api-server
-
-**临时 provider URL**:
-第三方任务完成后返回的短时模型下载地址，必须通过显式下载流程转换为本地或持久化资源，不能直接当作长期资产地址。
-_Avoid_: 永久 OSS URL、资源 ID
-
-**模型 artifact**:
-由 text-to-model、image-to-model 或 multiview-to-model 任务产生、待应用层登记和持久化的模型文件结果；provider adapter 只提供可下载结果，不负责生成 resourceId 或 assetId。
-_Avoid_: 仅 UI 中展示的模型链接、没有来源任务的静态文件
-
 ### Puzzle Clear
 
 **拼消消**:
@@ -190,6 +172,20 @@ _Avoid_: 多步骤向导、完整规则编辑器、拖拽编辑器
 Bark Battle 平台作品闭环按契约与领域规则、后端存储/API、最小前端纵切、投影体验、收口验证的顺序推进。
 _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 
+## 项目开发对话（DirectProject）
+
+**项目对话历史**:
+AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
+_Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
+
+**运行态事件**:
+Thread Manager 向订阅者推送的当前回合原始事件流，只服务运行期间与短期断线恢复，不替代项目对话历史。
+_Avoid_: 进度通知、快照轮询、第二套历史
+
+**聊天投影**:
+把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
+_Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
+
 ## Relationships
 
 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -224,3 +220,5 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 - “入口闭环”曾可能只指内部 demo 或单个详情 CTA；已解析为 **正式作品入口闭环**，不新增独立专区或活动页。
 - “创作编辑”曾可能指多步骤向导或完整编辑器；已解析为 **轻配置编辑流程**，使用单页表单 + 预览卡片完成保存草稿、发布和发布后跳转作品详情。
 - “实施顺序”曾可能按 UI 或功能并行发散；已解析为契约/领域规则先行，再做后端存储/API，随后打通最小前端纵切，最后补投影体验与收口验证。
+- “回合进度事件”曾同时指 Direct turn update 与 Thread Manager 运行态事件；已解析为 AGC 项目开发对话只保留 **运行态事件**。
+- “哪些消息可显示”曾可能由后端历史分页判断；已解析为可见性判断属于 **聊天投影**，后端只按原始条目分页，前端负责跳过不可显示条目并推进分页锚点。

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

@@ -32,6 +32,8 @@ import type {
   AdminLoginResponse,
   AdminMeResponse,
   AdminOverviewResponse,
+  AdminProjectSnapshotListQuery,
+  AdminProjectSnapshotListResponse,
   AdminRechargeOrderListQuery,
   AdminRechargeOrderListResponse,
   AdminRechargeRefundActionResponse,
@@ -198,6 +200,92 @@ export function listAdminAccounts(token: string) {
   return request<AdminAccountListResponse>('/admin/api/accounts', { token });
 }
 
+export function listAdminProjectSnapshots(
+  token: string,
+  query: AdminProjectSnapshotListQuery = {},
+  signal?: AbortSignal,
+) {
+  const params = new URLSearchParams();
+  if (query.cursor) params.set('cursor', query.cursor);
+  params.set('limit', String(query.limit ?? 20));
+  return request<AdminProjectSnapshotListResponse>(
+    `/admin/api/project-snapshots?${params.toString()}`,
+    { token, signal },
+  );
+}
+
+export async function downloadAdminProjectSnapshot(
+  token: string,
+  userId: string,
+  projectId: string,
+  signal?: AbortSignal,
+) {
+  const path = `/admin/api/project-snapshots/${encodeURIComponent(userId)}/${encodeURIComponent(projectId)}/download`;
+  const response = await fetch(buildRequestUrl(path), {
+    headers: {
+      Authorization: `Bearer ${token.trim()}`,
+      Accept: 'application/zip',
+      [API_RESPONSE_ENVELOPE_HEADER]: 'v1',
+    },
+    signal,
+  });
+  if (!response.ok) {
+    const responseText = await response.text();
+    throw buildAdminApiError(
+      response,
+      parseJsonResponse(responseText),
+      responseText,
+    );
+  }
+  const contentType = response.headers
+    .get('content-type')
+    ?.split(';')[0]
+    ?.trim()
+    .toLowerCase();
+  if (contentType !== 'application/zip') {
+    await response.body?.cancel();
+    throw new AdminApiError({
+      message: '下载失败：服务端未返回 ZIP 工程文件',
+      status: response.status,
+      code: 'INVALID_PROJECT_ARCHIVE_RESPONSE',
+    });
+  }
+  return {
+    blob: await response.blob(),
+    filename: projectArchiveFilename(
+      response.headers.get('content-disposition'),
+    ),
+  };
+}
+
+function projectArchiveFilename(contentDisposition: string | null): string {
+  const extended = contentDisposition?.match(
+    /(?:^|;)\s*filename\*=UTF-8'[^']*'([^;]+)/i,
+  );
+  const ordinary = contentDisposition?.match(
+    /(?:^|;)\s*filename=(?:"((?:[^"\\]|\\.)*)"|([^;]+))/i,
+  );
+  let filename =
+    ordinary?.[1]?.replace(/\\(.)/g, '$1') ?? ordinary?.[2]?.trim() ?? '';
+  if (extended?.[1]) {
+    try {
+      filename = decodeURIComponent(extended[1].trim());
+    } catch {
+      // 非法扩展编码继续使用普通文件名。
+    }
+  }
+  const safeName = Array.from(filename, (character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127 ? '_' : character;
+  })
+    .join('')
+    .replace(/[<>:"/\\|?*]/g, '_')
+    .trim()
+    .replace(/[. ]+$/, '');
+  if (!safeName || safeName.length > 240) return 'project.zip';
+  return /\.zip$/i.test(safeName) ? safeName : `${safeName}.zip`;
+}
+
 export function createAdminAccount(
   token: string,
   payload: AdminCreateAccountRequest,

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

@@ -96,6 +96,27 @@ export interface AdminMeResponse {
   admin: AdminSessionPayload;
 }
 
+export interface AdminProjectSnapshotEntry {
+  userId: string;
+  projectId: string;
+  projectName: string | null;
+  syncRevision: number;
+  syncedAtMs: number;
+  fileCount: number;
+  totalBytes: number;
+  status: 'ready' | 'partial' | 'unverified';
+}
+
+export interface AdminProjectSnapshotListQuery {
+  cursor?: string | null;
+  limit?: number;
+}
+
+export interface AdminProjectSnapshotListResponse {
+  items: AdminProjectSnapshotEntry[];
+  nextCursor: string | null;
+}
+
 export interface AdminErrorReportEntry {
   batchId: string;
   eventCount: number;

apps/admin-web/src/api/adminProjectSnapshotApi.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  downloadAdminProjectSnapshot,
+  listAdminProjectSnapshots,
+} from './adminApiClient';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test('项目列表携带分页与后台授权，解析标准响应', async () => {
+  const payload = { items: [], nextCursor: 'next' };
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue(
+      new Response(JSON.stringify({ ok: true, data: payload })),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+  const controller = new AbortController();
+  expect(
+    await listAdminProjectSnapshots(
+      'admin-token',
+      { cursor: 'user/a+项目', limit: 20 },
+      controller.signal,
+    ),
+  ).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/project-snapshots?cursor=user%2Fa%2B%E9%A1%B9%E7%9B%AE&limit=20',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+      signal: controller.signal,
+    }),
+  );
+});
+
+test('ZIP 下载以授权请求读取并优先保留中文附件名', async () => {
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response('PK\u0003\u0004', {
+      headers: {
+        'content-type': 'application/zip',
+        'content-disposition':
+          "attachment; filename=project.zip; filename*=UTF-8''%E4%B8%89%E6%B6%88-r2.zip",
+      },
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  const controller = new AbortController();
+  const archive = await downloadAdminProjectSnapshot(
+    'admin-token',
+    'user/a',
+    'project/b',
+    controller.signal,
+  );
+  expect(archive.filename).toBe('三消-r2.zip');
+  expect(archive.blob.type).toBe('application/zip');
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/project-snapshots/user%2Fa/project%2Fb/download',
+    expect.objectContaining({
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        Accept: 'application/zip',
+      }),
+      signal: controller.signal,
+    }),
+  );
+});
+
+test.each([
+  ['attachment; filename="工程.zip"; filename*=UTF-8\'\'%broken', '工程.zip'],
+  ['attachment; filename="../secret.zip"', '.._secret.zip'],
+  ["attachment; filename*=UTF-8''unsafe%00%1F%7F.zip", 'unsafe___.zip'],
+  [null, 'project.zip'],
+])('ZIP 附件名兼容安全回退 %s', async (header, expected) => {
+  const headers: Record<string, string> = { 'content-type': 'application/zip' };
+  // Response 的 Headers 只接受 Latin-1；真实 UTF-8 文件名使用 filename*。
+  if (header)
+    headers['content-disposition'] = header.replace('工程', 'project');
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue(new Response('PK', { headers })),
+  );
+  expect(
+    (await downloadAdminProjectSnapshot('token', 'user', 'project')).filename,
+  ).toBe(expected.replace('工程', 'project'));
+});
+
+test.each([401, 403, 409, 500])(
+  '下载 HTTP %s 保留后台错误，不返回 ZIP',
+  async (status) => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            ok: false,
+            error: { code: 'SNAPSHOT_FAILURE', message: '工程尚未同步完成' },
+          }),
+          {
+            status,
+            headers: { 'content-type': 'application/json' },
+          },
+        ),
+      ),
+    );
+    await expect(
+      downloadAdminProjectSnapshot('token', 'user', 'project'),
+    ).rejects.toMatchObject({
+      status,
+      code: 'SNAPSHOT_FAILURE',
+      message: '工程尚未同步完成',
+    });
+  },
+);
+
+test('200 JSON 或 HTML 不能被保存为成功 ZIP', async () => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue(
+      new Response('{"ok":false}', {
+        headers: { 'content-type': 'application/json' },
+      }),
+    ),
+  );
+  await expect(
+    downloadAdminProjectSnapshot('token', 'user', 'project'),
+  ).rejects.toMatchObject({ code: 'INVALID_PROJECT_ARCHIVE_RESPONSE' });
+});

apps/admin-web/src/app/AdminApp.tsx

@@ -31,6 +31,7 @@ import { AdminInviteCodePage } from '../pages/AdminInviteCodePage';
 import { AdminLoginPage } from '../pages/AdminLoginPage';
 import { AdminOverviewPage } from '../pages/AdminOverviewPage';
 import { AdminProfileWalletConfigPage } from '../pages/AdminProfileWalletConfigPage';
+import { AdminProjectSnapshotsPage } from '../pages/AdminProjectSnapshotsPage';
 import { AdminRechargeOrderPage } from '../pages/AdminRechargeOrderPage';
 import { AdminRechargeProductPage } from '../pages/AdminRechargeProductPage';
 import { AdminRedeemCodePage } from '../pages/AdminRedeemCodePage';
@@ -308,6 +309,12 @@ export function AdminApp() {
       {activeRouteId === 'accounts' ? (
         <AdminAccountsPage token={token} onUnauthorized={handleUnauthorized} />
       ) : null}
+      {activeRouteId === 'project-snapshots' ? (
+        <AdminProjectSnapshotsPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
     </AdminShell>
   );
 }

apps/admin-web/src/app/AdminShell.tsx

@@ -4,6 +4,7 @@ import {
   Bug,
   Coins,
   Database,
+  FolderArchive,
   GitBranch,
   Images,
   LayoutDashboard,
@@ -49,6 +50,7 @@ const routeIcons = {
   'editor-generation-pricing': Coins,
   'editor-showcase': Star,
   'editor-assets': Images,
+  'project-snapshots': FolderArchive,
   accounts: Users,
   'agc-models': ListChecks,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;

apps/admin-web/src/app/adminRoutes.test.ts

@@ -122,3 +122,28 @@ test('零权限 member 不回落到 Dashboard', () => {
   expect(routes).toEqual([]);
   expect(resolveAccessibleAdminRoute('#dashboard', routes)).toBeNull();
 });
+
+test('项目工程入口对 owner 与已授权 member 开放且可分配权限', () => {
+  const route = {
+    id: 'project-snapshots',
+    label: '项目工程',
+    hash: '#project-snapshots',
+  };
+  expect(adminRoutes.filter((item) => !item.ownerOnly)).toContainEqual(route);
+  expect(resolveAdminRoute('#project-snapshots')).toBe('project-snapshots');
+  expect(
+    getAccessibleAdminRoutes({ accountRole: 'owner', tabPermissions: [] }),
+  ).toContainEqual(route);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['project-snapshots'],
+    }),
+  ).toEqual([route]);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['tracking'],
+    }),
+  ).not.toContainEqual(route);
+});

apps/admin-web/src/app/adminRoutes.ts

@@ -16,6 +16,7 @@ export type AdminRouteId =
   | 'editor-generation-pricing'
   | 'editor-showcase'
   | 'editor-assets'
+  | 'project-snapshots'
   | 'agc-models'
   | 'accounts';
 
@@ -54,6 +55,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
   { id: 'agc-models', label: 'AGC 模型', hash: '#agc-models', ownerOnly: true },
   { id: 'editor-showcase', label: '精选审核', hash: '#editor-showcase' },
   { id: 'editor-assets', label: '素材查询', hash: '#editor-assets' },
+  { id: 'project-snapshots', label: '项目工程', hash: '#project-snapshots' },
   { id: 'accounts', label: '账号管理', hash: '#accounts', ownerOnly: true },
 ];
 

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

@@ -0,0 +1,288 @@
+// @vitest-environment jsdom
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  AdminApiError,
+  downloadAdminProjectSnapshot,
+  listAdminProjectSnapshots,
+} from '../api/adminApiClient';
+import type { AdminProjectSnapshotEntry } from '../api/adminApiTypes';
+import { AdminProjectSnapshotsPage } from './AdminProjectSnapshotsPage';
+
+vi.mock('../api/adminApiClient', async () => ({
+  ...(await vi.importActual<typeof import('../api/adminApiClient')>(
+    '../api/adminApiClient',
+  )),
+  downloadAdminProjectSnapshot: vi.fn(),
+  listAdminProjectSnapshots: vi.fn(),
+}));
+
+const entry: AdminProjectSnapshotEntry = {
+  userId: 'user-1',
+  projectId: 'project-1',
+  projectName: '三消工程',
+  syncRevision: 3,
+  syncedAtMs: 1_700_000_000_000,
+  fileCount: 12,
+  totalBytes: 2048,
+  status: 'ready',
+};
+
+beforeEach(() => {
+  vi.mocked(listAdminProjectSnapshots)
+    .mockReset()
+    .mockResolvedValue({ items: [entry], nextCursor: null });
+  vi.mocked(downloadAdminProjectSnapshot).mockReset();
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+test('按项目展示完整性并限制未完成工程下载', async () => {
+  vi.mocked(listAdminProjectSnapshots).mockResolvedValue({
+    items: [
+      entry,
+      {
+        ...entry,
+        projectId: 'partial-project',
+        projectName: '未完成工程',
+        status: 'partial',
+      },
+      {
+        ...entry,
+        projectId: 'legacy-project',
+        projectName: null,
+        status: 'unverified',
+      },
+    ],
+    nextCursor: null,
+  });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  const completeRow = (await screen.findByText('三消工程')).closest('tr')!;
+  expect(within(completeRow).getByText('2 KiB')).toBeTruthy();
+  expect(
+    within(completeRow)
+      .getByRole('button', { name: '下载完整工程' })
+      .hasAttribute('disabled'),
+  ).toBe(false);
+  expect(
+    screen.getByRole('button', { name: '同步未完成' }).hasAttribute('disabled'),
+  ).toBe(true);
+  expect(screen.getByText('完整性未知')).toBeTruthy();
+  expect(
+    screen
+      .getByRole('button', { name: '下载已存文件' })
+      .hasAttribute('disabled'),
+  ).toBe(false);
+});
+
+test('加载更多合并项目，刷新失败保留列表和错误，重试从首页开始', async () => {
+  vi.mocked(listAdminProjectSnapshots)
+    .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' })
+    .mockResolvedValueOnce({
+      items: [{ ...entry, projectId: 'project-2', projectName: '第二工程' }],
+      nextCursor: null,
+    })
+    .mockRejectedValueOnce(new Error('远端清单读取失败'))
+    .mockResolvedValueOnce({ items: [], nextCursor: null });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  fireEvent.click(await screen.findByRole('button', { name: '加载更多' }));
+  await screen.findByText('第二工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    2,
+    'token',
+    { cursor: 'page-2', limit: 20 },
+    expect.any(AbortSignal),
+  );
+  expect(screen.getByText('三消工程')).toBeTruthy();
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  await screen.findByRole('alert');
+  expect(screen.getByText('第二工程')).toBeTruthy();
+  expect(screen.queryByText('暂无已上传项目')).toBeNull();
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  await screen.findByText('暂无已上传项目');
+  expect(listAdminProjectSnapshots).toHaveBeenLastCalledWith(
+    'token',
+    { cursor: null, limit: 20 },
+    expect.any(AbortSignal),
+  );
+});
+
+test('下载使用返回的中文文件名，随后释放对象 URL', async () => {
+  const createObjectURL = vi.fn(() => 'blob:archive');
+  const revokeObjectURL = vi.fn();
+  vi.stubGlobal(
+    'URL',
+    class extends URL {
+      static createObjectURL = createObjectURL;
+      static revokeObjectURL = revokeObjectURL;
+    },
+  );
+  let savedFilename = '';
+  let savedHref = '';
+  vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (
+    this: HTMLAnchorElement,
+  ) {
+    savedFilename = this.download;
+    savedHref = this.href;
+  });
+  const blob = new Blob(['PK'], { type: 'application/zip' });
+  vi.mocked(downloadAdminProjectSnapshot).mockResolvedValue({
+    blob,
+    filename: '三消工程-r3.zip',
+  });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  const button = await screen.findByRole('button', { name: '下载完整工程' });
+  vi.useFakeTimers();
+  await act(async () => {
+    fireEvent.click(button);
+  });
+  expect(savedFilename).toBe('三消工程-r3.zip');
+  expect(savedHref).toBe('blob:archive');
+  expect(createObjectURL).toHaveBeenCalledWith(blob);
+  expect(downloadAdminProjectSnapshot).toHaveBeenCalledWith(
+    'token',
+    'user-1',
+    'project-1',
+    expect.any(AbortSignal),
+  );
+  act(() => vi.advanceTimersByTime(1000));
+  expect(revokeObjectURL).toHaveBeenCalledWith('blob:archive');
+});
+
+test('取消下载中止请求且不显示错误，卸载中止列表请求', async () => {
+  vi.mocked(downloadAdminProjectSnapshot).mockImplementation(
+    (_token, _user, _project, signal) =>
+      new Promise((_resolve, reject) => {
+        signal?.addEventListener('abort', () =>
+          reject(new DOMException('Aborted', 'AbortError')),
+        );
+      }),
+  );
+  const view = render(
+    <AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />,
+  );
+  fireEvent.click(await screen.findByRole('button', { name: '下载完整工程' }));
+  fireEvent.click(await screen.findByRole('button', { name: '取消下载' }));
+  expect(
+    vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[3]?.aborted,
+  ).toBe(true);
+  await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
+  vi.mocked(listAdminProjectSnapshots).mockReturnValue(new Promise(() => {}));
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  const signal = vi.mocked(listAdminProjectSnapshots).mock.calls.at(-1)?.[2];
+  view.unmount();
+  expect(signal?.aborted).toBe(true);
+});
+
+test('下载登录失效走现有会话处理，403 错误保留页面', async () => {
+  const onUnauthorized = vi.fn();
+  vi.mocked(downloadAdminProjectSnapshot)
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 403, message: '无项目工程权限' }),
+    )
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 401, message: '已过期' }),
+    );
+  render(
+    <AdminProjectSnapshotsPage token="token" onUnauthorized={onUnauthorized} />,
+  );
+  fireEvent.click(await screen.findByRole('button', { name: '下载完整工程' }));
+  expect(await screen.findByText('无项目工程权限')).toBeTruthy();
+  expect(onUnauthorized).not.toHaveBeenCalled();
+  fireEvent.click(screen.getByRole('button', { name: '下载完整工程' }));
+  await waitFor(() =>
+    expect(onUnauthorized).toHaveBeenCalledWith('登录状态已失效'),
+  );
+});
+
+test('首次列表失败显示错误而非空项目，401 失效回到会话处理', async () => {
+  const onUnauthorized = vi.fn();
+  vi.mocked(listAdminProjectSnapshots)
+    .mockRejectedValueOnce(new Error('清单存储不可用'))
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 401, message: '已过期' }),
+    );
+  render(
+    <AdminProjectSnapshotsPage token="token" onUnauthorized={onUnauthorized} />,
+  );
+  await screen.findByText('清单存储不可用');
+  expect(screen.queryByText('暂无已上传项目')).toBeNull();
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  await waitFor(() =>
+    expect(onUnauthorized).toHaveBeenCalledWith('登录状态已失效'),
+  );
+});
+
+test('更换登录令牌丢弃旧列表和晚返回请求', async () => {
+  let finishOldRequest!: (value: {
+    items: AdminProjectSnapshotEntry[];
+    nextCursor: null;
+  }) => void;
+  vi.mocked(listAdminProjectSnapshots)
+    .mockReturnValueOnce(
+      new Promise((resolve) => {
+        finishOldRequest = resolve;
+      }),
+    )
+    .mockResolvedValueOnce({
+      items: [{ ...entry, projectName: '新账号工程' }],
+      nextCursor: null,
+    });
+  const onUnauthorized = vi.fn();
+  const view = render(
+    <AdminProjectSnapshotsPage
+      token="old-token"
+      onUnauthorized={onUnauthorized}
+    />,
+  );
+  const oldSignal = vi.mocked(listAdminProjectSnapshots).mock.calls[0]?.[2];
+  view.rerender(
+    <AdminProjectSnapshotsPage
+      token="new-token"
+      onUnauthorized={onUnauthorized}
+    />,
+  );
+  await screen.findByText('新账号工程');
+  expect(oldSignal?.aborted).toBe(true);
+  await act(async () => {
+    finishOldRequest({ items: [entry], nextCursor: null });
+  });
+  expect(screen.queryByText('三消工程')).toBeNull();
+  expect(screen.getByText('新账号工程')).toBeTruthy();
+});
+
+test('卸载后完成的下载不会创建浏览器文件', async () => {
+  let finishDownload!: (value: { blob: Blob; filename: string }) => void;
+  vi.mocked(downloadAdminProjectSnapshot).mockReturnValue(
+    new Promise((resolve) => {
+      finishDownload = resolve;
+    }),
+  );
+  const click = vi
+    .spyOn(HTMLAnchorElement.prototype, 'click')
+    .mockImplementation(() => {});
+  const view = render(
+    <AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />,
+  );
+  fireEvent.click(await screen.findByRole('button', { name: '下载完整工程' }));
+  const signal = vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[3];
+  view.unmount();
+  expect(signal?.aborted).toBe(true);
+  await act(async () => {
+    finishDownload({ blob: new Blob(['PK']), filename: 'old.zip' });
+  });
+  expect(click).not.toHaveBeenCalled();
+});

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

@@ -0,0 +1,270 @@
+import { Download, RefreshCcw, X } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  downloadAdminProjectSnapshot,
+  listAdminProjectSnapshots,
+} from '../api/adminApiClient';
+import type { AdminProjectSnapshotEntry } from '../api/adminApiTypes';
+import { handlePageError } from './pageUtils';
+
+interface AdminProjectSnapshotsPageProps {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}
+
+const snapshotStatuses = {
+  ready: {
+    label: '已同步',
+    className: 'admin-status-ok',
+    action: '下载完整工程',
+  },
+  partial: {
+    label: '同步未完成',
+    className: 'admin-status-pending',
+    action: '同步未完成',
+  },
+  unverified: {
+    label: '完整性未知',
+    className: 'admin-status-pending',
+    action: '下载已存文件',
+  },
+};
+
+export function AdminProjectSnapshotsPage({
+  token,
+  onUnauthorized,
+}: AdminProjectSnapshotsPageProps) {
+  const [items, setItems] = useState<AdminProjectSnapshotEntry[]>([]);
+  const [nextCursor, setNextCursor] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [hasLoaded, setHasLoaded] = useState(false);
+  const [errorMessage, setErrorMessage] = useState('');
+  const [downloadingKey, setDownloadingKey] = useState<string | null>(null);
+  const listController = useRef<AbortController | null>(null);
+  const downloadController = useRef<AbortController | null>(null);
+
+  const loadPage = useCallback(
+    async (cursor: string | null = null) => {
+      listController.current?.abort();
+      const controller = new AbortController();
+      listController.current = controller;
+      setIsLoading(true);
+      setErrorMessage('');
+      try {
+        const response = await listAdminProjectSnapshots(
+          token,
+          { cursor, limit: 20 },
+          controller.signal,
+        );
+        if (controller.signal.aborted) return;
+        setItems((current) => {
+          if (!cursor) return response.items;
+          const entries = new Map(
+            current.map((entry) => [snapshotKey(entry), entry]),
+          );
+          response.items.forEach((entry) =>
+            entries.set(snapshotKey(entry), entry),
+          );
+          return [...entries.values()];
+        });
+        setNextCursor(response.nextCursor);
+        setHasLoaded(true);
+      } catch (error: unknown) {
+        if (!controller.signal.aborted)
+          handlePageError(error, onUnauthorized, setErrorMessage);
+      } finally {
+        if (listController.current === controller) {
+          listController.current = null;
+          setIsLoading(false);
+        }
+      }
+    },
+    [token, onUnauthorized],
+  );
+
+  useEffect(() => {
+    setItems([]);
+    setNextCursor(null);
+    setHasLoaded(false);
+    setDownloadingKey(null);
+    void loadPage();
+    return () => {
+      listController.current?.abort();
+      listController.current = null;
+      downloadController.current?.abort();
+      downloadController.current = null;
+    };
+  }, [loadPage]);
+
+  async function downloadProject(entry: AdminProjectSnapshotEntry) {
+    if (downloadController.current || entry.status === 'partial') return;
+    const controller = new AbortController();
+    downloadController.current = controller;
+    setDownloadingKey(snapshotKey(entry));
+    setErrorMessage('');
+    try {
+      const archive = await downloadAdminProjectSnapshot(
+        token,
+        entry.userId,
+        entry.projectId,
+        controller.signal,
+      );
+      if (controller.signal.aborted) return;
+      const objectUrl = URL.createObjectURL(archive.blob);
+      const link = document.createElement('a');
+      link.href = objectUrl;
+      link.download = archive.filename;
+      document.body.append(link);
+      try {
+        link.click();
+      } finally {
+        link.remove();
+        // 给浏览器时间接管下载，随后释放临时 URL。
+        setTimeout(() => URL.revokeObjectURL(objectUrl), 1000);
+      }
+    } catch (error: unknown) {
+      if (!controller.signal.aborted)
+        handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      if (downloadController.current === controller) {
+        downloadController.current = null;
+        setDownloadingKey(null);
+      }
+    }
+  }
+
+  function cancelDownload() {
+    downloadController.current?.abort();
+    downloadController.current = null;
+    setDownloadingKey(null);
+  }
+
+  return (
+    <section className="admin-page admin-page-wide">
+      <div className="admin-page-heading">
+        <h2>项目工程</h2>
+        <button
+          className="admin-secondary-button"
+          disabled={isLoading}
+          type="button"
+          onClick={() => void loadPage()}
+        >
+          <RefreshCcw size={17} aria-hidden="true" />
+          <span>{isLoading ? '加载中' : '刷新'}</span>
+        </button>
+      </div>
+      {errorMessage ? (
+        <div className="admin-alert" role="alert">
+          {errorMessage}
+        </div>
+      ) : null}
+      <section
+        className="admin-panel admin-stack"
+        aria-label="项目工程列表"
+        aria-busy={isLoading}
+      >
+        <div className="admin-table-wrap">
+          <table className="admin-table admin-project-snapshot-table">
+            <thead>
+              <tr>
+                <th>项目</th>
+                <th>用户 ID</th>
+                <th>同步时间</th>
+                <th>文件数</th>
+                <th>体积</th>
+                <th>完整性</th>
+                <th>操作</th>
+              </tr>
+            </thead>
+            <tbody>
+              {items.map((entry) => {
+                const status = snapshotStatuses[entry.status];
+                const isDownloading = downloadingKey === snapshotKey(entry);
+                return (
+                  <tr key={snapshotKey(entry)}>
+                    <td data-label="项目">
+                      <strong>{entry.projectName || entry.projectId}</strong>
+                      <small>{entry.projectId}</small>
+                    </td>
+                    <td data-label="用户 ID">{entry.userId}</td>
+                    <td data-label="同步时间">
+                      <span>
+                        {new Date(entry.syncedAtMs).toLocaleString('zh-CN', {
+                          hour12: false,
+                        })}
+                        <small>版本 {entry.syncRevision}</small>
+                      </span>
+                    </td>
+                    <td data-label="文件数">
+                      {entry.fileCount.toLocaleString('zh-CN')}
+                    </td>
+                    <td data-label="体积">{formatBytes(entry.totalBytes)}</td>
+                    <td data-label="完整性">
+                      <span className={`admin-status ${status.className}`}>
+                        {status.label}
+                      </span>
+                    </td>
+                    <td data-label="操作">
+                      {isDownloading ? (
+                        <button
+                          className="admin-secondary-button"
+                          type="button"
+                          onClick={cancelDownload}
+                        >
+                          <X size={16} aria-hidden="true" />
+                          <span>取消下载</span>
+                        </button>
+                      ) : (
+                        <button
+                          className="admin-secondary-button"
+                          disabled={
+                            entry.status === 'partial' ||
+                            downloadingKey !== null
+                          }
+                          type="button"
+                          onClick={() => void downloadProject(entry)}
+                        >
+                          <Download size={16} aria-hidden="true" />
+                          <span>{status.action}</span>
+                        </button>
+                      )}
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+        {hasLoaded && items.length === 0 && !errorMessage ? (
+          <p className="admin-muted-text">暂无已上传项目</p>
+        ) : null}
+        {nextCursor ? (
+          <div className="admin-action-row">
+            <button
+              className="admin-secondary-button"
+              disabled={isLoading}
+              type="button"
+              onClick={() => void loadPage(nextCursor)}
+            >
+              {isLoading ? '加载中' : '加载更多'}
+            </button>
+          </div>
+        ) : null}
+      </section>
+    </section>
+  );
+}
+
+function snapshotKey(entry: AdminProjectSnapshotEntry) {
+  return `${entry.userId}/${entry.projectId}`;
+}
+
+function formatBytes(bytes: number) {
+  const units = ['B', 'KiB', 'MiB', 'GiB'];
+  const unit = Math.min(
+    Math.floor(Math.log2(Math.max(1, bytes)) / 10),
+    units.length - 1,
+  );
+  return `${(bytes / 1024 ** unit).toLocaleString('zh-CN', { maximumFractionDigits: 1 })} ${units[unit]}`;
+}

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

@@ -1452,6 +1452,112 @@ button:disabled {
   min-width: 1180px;
 }
 
+.admin-project-snapshot-table {
+  min-width: 0;
+  table-layout: fixed;
+}
+
+.admin-project-snapshot-table th,
+.admin-project-snapshot-table td {
+  overflow-wrap: anywhere;
+}
+
+.admin-project-snapshot-table th:first-child {
+  width: 20%;
+}
+
+.admin-project-snapshot-table th:nth-child(2) {
+  width: 14%;
+}
+
+.admin-project-snapshot-table th:nth-child(3) {
+  width: 18%;
+}
+
+.admin-project-snapshot-table th:nth-child(4) {
+  width: 7%;
+}
+
+.admin-project-snapshot-table th:nth-child(5) {
+  width: 9%;
+}
+
+.admin-project-snapshot-table th:nth-child(6) {
+  width: 12%;
+}
+
+.admin-project-snapshot-table th:last-child {
+  width: 20%;
+}
+
+@media (max-width: 1200px) {
+  .admin-project-snapshot-table,
+  .admin-project-snapshot-table tbody {
+    display: block;
+  }
+
+  .admin-project-snapshot-table thead {
+    display: none;
+  }
+
+  .admin-project-snapshot-table tr {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 10px 16px;
+    border-bottom: 1px solid #eaded2;
+    padding: 18px 0;
+  }
+
+  .admin-project-snapshot-table tr:first-child {
+    padding-top: 0;
+  }
+
+  .admin-project-snapshot-table tr:last-child {
+    border-bottom: 0;
+    padding-bottom: 0;
+  }
+
+  .admin-project-snapshot-table td {
+    display: flex;
+    min-width: 0;
+    align-items: baseline;
+    gap: 8px;
+    border: 0;
+    padding: 0;
+    font-size: 14px;
+  }
+
+  .admin-project-snapshot-table td::before {
+    flex-shrink: 0;
+    color: #8f7868;
+    font-size: 12px;
+    content: attr(data-label);
+  }
+
+  .admin-project-snapshot-table td:first-child,
+  .admin-project-snapshot-table td:nth-child(2),
+  .admin-project-snapshot-table td:nth-child(3),
+  .admin-project-snapshot-table td:nth-child(6),
+  .admin-project-snapshot-table td:last-child {
+    grid-column: 1 / -1;
+  }
+
+  .admin-project-snapshot-table td:first-child {
+    display: block;
+    font-size: 16px;
+  }
+
+  .admin-project-snapshot-table td:first-child::before,
+  .admin-project-snapshot-table td:last-child::before {
+    display: none;
+  }
+
+  .admin-project-snapshot-table td:last-child button {
+    width: 100%;
+    justify-content: center;
+  }
+}
+
 .admin-recharge-table {
   min-width: 1080px;
   table-layout: fixed;

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/agent-runtime-deterministic-playable-e2e.mjs

@@ -676,11 +676,11 @@ async function runSelfTest() {
       designFoundationAssetCall?.arguments?.input?.outputPath ===
         'assets/ui-prototype.png' &&
       designFoundationAssetCall.arguments.input.aspectRatio === '16:9' &&
-      designFoundationAssetCall.arguments.input.assetKind === 'ui-prototype' &&
+      designFoundationAssetCall.arguments.input.assetKind === 'ui-design' &&
       artAssetPlanAssetCall?.arguments?.input?.outputPath ===
         'assets/art-spritesheet.png' &&
       artAssetPlanAssetCall.arguments.input.aspectRatio === '1:1' &&
-      artAssetPlanAssetCall.arguments.input.assetKind === 'art-spritesheet',
+      artAssetPlanAssetCall.arguments.input.assetKind === 'icon-spritesheet',
     'self-test-visual-assets-invalid',
   );
 

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

@@ -70,7 +70,7 @@ const requiredFormalArtifactSpecs = [
   { path: 'game/balance.json', kind: 'json' },
   { path: 'assets/manifest.art.json', kind: 'json' },
   { path: 'assets/manifest.audio.json', kind: 'json' },
-  { path: 'game/index.html', kind: 'game-entry' },
+  { path: 'game/index.html', kind: 'file' },
   { path: 'exports/README.md', kind: 'file' },
 ];
 const editorImageArtifactSpecs = [

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 =
+function defaultTarget() {
-  process.env.AGC_BUILD_TARGET?.trim() || defaultReleaseTarget;
+  return process.env.AGC_BUILD_TARGET?.trim() || defaultReleaseTarget;
-const bundleRoot = path.join(
+}
+
+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',
-  releaseTarget,
+      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');
@@ -50,6 +105,7 @@ export const agcReleasePathPatterns = [
   'packages/',
   'server-rs/crates/',
   'plugins/agc-cocos-editor/',
+  'plugins/agc-unity-editor/',
   'apps/desktop-shell/src-tauri/icons/',
   'package.json',
   'package-lock.json',
@@ -99,7 +155,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 +164,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 +198,10 @@ export function updateManifestUrl(channel = resolveReleaseChannel()) {
 }
 
 /**
- * 更新插件按运行时平台键查找清单条目：universal macOS 包同时挂
+ * 单架构产物只登记实际目标，不能把同一原生资源映射为另一架构。
- * `darwin-aarch64` 与 `darwin-x86_64`，单架构目标只挂对应键。
  */
-export function resolveManifestPlatformKeys(target = releaseTarget) {
+export function resolveManifestPlatformKeys(target = defaultTarget()) {
-  if (target === 'universal-apple-darwin') {
+  validateReleaseTarget(target);
-    return ['darwin-aarch64', 'darwin-x86_64'];
-  }
   if (target === 'aarch64-apple-darwin') return ['darwin-aarch64'];
   if (target === 'x86_64-apple-darwin') return ['darwin-x86_64'];
   if (target.includes('windows')) {
@@ -256,8 +309,8 @@ function replaceVersionLine(source, version, pattern, label) {
   return source.replace(pattern, `$1${version}$3`);
 }
 
-export async function prepareReleaseVersion() {
+export async function prepareReleaseVersion(context = resolveReleaseContext()) {
-  const channel = resolveReleaseChannel();
+  const { channel } = context;
   const localVersion = parseVersion(readPackageJson().version, '本地版本');
   const remoteVersion = await resolveRemoteHighWaterVersion(channel);
   const requestedVersion = process.env.AGC_RELEASE_VERSION?.trim();
@@ -330,18 +383,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 = explicitBuildTarget(args);
-  const explicitTarget =
-    targetIndex >= 0
-      ? args[targetIndex + 1]
-      : args
-          .find((value) => value.startsWith('--target='))
-          ?.slice('--target='.length);
   const targetArgs = noBundle || explicitTarget ? [] : ['--target', target];
+  if (!noBundle || explicitTarget)
+    validateReleaseTarget(explicitTarget || target);
   const features = defaultEditorFeatures(
     explicitTarget || (noBundle ? platform : target),
   );
@@ -374,18 +423,33 @@ function writeChannelConfigFile(channel) {
   return configPath;
 }
 
-export function runTauriBuild(args = []) {
+export function runTauriBuild(
-  const tauriArguments = buildTauriBuildArguments(args);
+  args = [],
-  if (!tauriArguments.includes('--config') && !tauriArguments.includes('-c')) {
+  context = resolveReleaseContext(args),
-    const channel = resolveReleaseChannel();
+  { 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}`,
   );
-    tauriArguments.push('--config', 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 +466,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 +480,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,14 +492,50 @@ 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
   );
 }
 
+export function selectFirstInstallArtifact(
+  files,
+  { target, version, artifact },
+) {
+  validateReleaseTarget(target);
+  let selected;
+  if (target.includes('windows')) {
+    selected = artifact;
+    if (!selected?.endsWith('.exe')) {
+      throw new Error('Windows 首装包必须复用本次 NSIS .exe 更新包');
+    }
+  } else {
+    // Tauri DMG 文件名使用 aarch64 / x64，而 updater 的 Intel 平台键是 x86_64。
+    const architecture = target.startsWith('aarch64') ? 'aarch64' : 'x64';
+    const suffix = `_${version}_${architecture}.dmg`;
+    const candidates = files.filter((file) =>
+      path.basename(file).endsWith(suffix),
+    );
+    if (candidates.length !== 1) {
+      throw new Error(
+        `首装 DMG 必须唯一匹配本次版本 ${version} 和架构 ${architecture}，找到 ${candidates.length} 个`,
+      );
+    }
+    selected = candidates[0];
+  }
+  if (
+    !fs.existsSync(selected) ||
+    !fs.statSync(selected).isFile() ||
+    fs.statSync(selected).size === 0
+  ) {
+    throw new Error(`首装包不存在或为空：${selected}`);
+  }
+  return selected;
+}
+
 function readUpdaterSignature(artifactPath) {
   const signaturePath = `${artifactPath}.sig`;
   if (!fs.existsSync(signaturePath)) {
@@ -450,26 +551,37 @@ function readUpdaterSignature(artifactPath) {
 export function createUpdateManifest(
   artifactPath,
   {
-    channel = resolveReleaseChannel(),
+    target = defaultTarget(),
-    target = releaseTarget,
+    channel = resolveReleaseChannel(process.env, target),
     publishedAt = new Date().toISOString(),
     notes = readReleaseNotes(),
     commit = readHeadCommit(),
+    downloadArtifact,
   } = {},
 ) {
+  validateReleaseTarget(target);
+  resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel }, target);
   const signature = readUpdaterSignature(artifactPath);
   const version = readPackageJson().version;
+  const firstInstallArtifact = selectFirstInstallArtifact(
+    downloadArtifact ? [downloadArtifact] : [],
+    { target, version, artifact: artifactPath },
+  );
   const fileName = path.basename(artifactPath);
   const url = `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`;
+  const downloadUrl = `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(path.basename(firstInstallArtifact))}`;
   const platforms = {};
+  const downloads = {};
   for (const key of resolveManifestPlatformKeys(target)) {
     platforms[key] = { signature, url };
+    downloads[key] = { url: downloadUrl };
   }
   return {
     version,
     ...(notes ? { notes } : {}),
     pub_date: publishedAt,
     platforms,
+    downloads,
     // 非标准字段：更新插件会忽略，发布脚本用它定位下一次自动更新摘要的起点。
     ...(commit ? { commit } : {}),
   };
@@ -604,12 +716,20 @@ export function createLegacyUpdateManifest(
   };
 }
 
-export async function generateUpdateManifest() {
+export async function generateUpdateManifest(
-  const channel = resolveReleaseChannel();
+  context = resolveReleaseContext(),
-  const artifact = selectReleaseArtifact(listFiles(bundleRoot));
+) {
+  const { channel, target, bundleRoot } = context;
+  const files = listFiles(bundleRoot);
+  const artifact = selectReleaseArtifact(files, target);
   if (!artifact) {
     throw new Error(`未找到可发布的 AGC 安装包：${bundleRoot}`);
   }
+  const downloadArtifact = selectFirstInstallArtifact(files, {
+    target,
+    version: readPackageJson().version,
+    artifact,
+  });
   const manualNotes = readReleaseNotes();
   const previousCommit = await resolvePreviousReleaseCommit(channel);
   const commits = collectReleaseCommits(previousCommit);
@@ -623,7 +743,12 @@ 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,
+    downloadArtifact,
+  });
   const manifestPath = path.join(bundleRoot, 'latest.json');
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   const notesPath = path.join(bundleRoot, 'release-notes.txt');
@@ -648,6 +773,7 @@ export async function generateUpdateManifest() {
     `[ai-game-creator-shell] 渠道 ${channel}：已生成 ${manifestPath}`,
   );
   console.log(`[ai-game-creator-shell] 安装包：${artifact}`);
+  console.log(`[ai-game-creator-shell] 首装包：${downloadArtifact}`);
   console.log(
     manualNotes
       ? '[ai-game-creator-shell] 更新摘要：使用 AGC_UPDATE_RELEASE_NOTES 手动文案'
@@ -664,6 +790,7 @@ export async function generateUpdateManifest() {
   return {
     channel,
     artifact,
+    downloadArtifact,
     manifest,
     manifestPath,
     notes,
@@ -675,12 +802,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();
+  await buildRelease(args);
-  runTauriBuild(args);
-  if (!args.includes('--no-bundle')) await generateUpdateManifest();
 }

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,17 +24,46 @@ import {
   createUpdateManifest,
   formatRecentReleaseNotes,
   formatReleaseNotes,
+  generateUpdateManifest,
   nextPatchVersion,
   resolveManifestPlatformKeys,
   resolvePreviousReleaseCommit,
   resolveReleaseChannel,
+  resolveReleaseContext,
   resolveRemoteHighWaterVersion,
+  runTauriBuild,
+  selectFirstInstallArtifact,
   selectReleaseArtifact,
   updateManifestUrl,
 } from './build-release.mjs';
 
 const windowsTarget = 'x86_64-pc-windows-msvc';
 const universalTarget = 'universal-apple-darwin';
+const packageVersion = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
+function createDmgFixture(root, target, version = packageVersion) {
+  const architecture = target.startsWith('aarch64') ? 'aarch64' : 'x64';
+  const dmg = path.join(root, `陶泥儿_${version}_${architecture}.dmg`);
+  writeFileSync(dmg, 'first installation disk image');
+  return dmg;
+}
+
+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();
@@ -132,9 +163,12 @@ test('channel manifest URL and build-time endpoint follow the channel', () => {
   });
 });
 
-test('universal macOS builds publish one artifact under both platform keys', () => {
+test('macOS manifests only advertise the architecture actually built', () => {
-  assert.deepEqual(resolveManifestPlatformKeys(universalTarget), [
+  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 +176,317 @@ 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,
+                  downloadArtifact: createDmgFixture(
+                    path.dirname(artifact),
+                    context.target,
+                  ),
+                });
+                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]));
+});
+
+for (const target of ['aarch64-apple-darwin', 'x86_64-apple-darwin']) {
+  test(`real manifest writer publishes the ${target} updater and first installer separately`, 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 downloadArtifact = createDmgFixture(root, target);
+      const context = {
+        ...resolveReleaseContext([`--target=${target}`], {}),
+        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.downloadArtifact, downloadArtifact);
+      assert.equal(result.manifestPath, path.join(root, 'latest.json'));
+      assert.equal(result.legacyManifestPath, null);
+      const key = target.startsWith('aarch64')
+        ? 'darwin-aarch64'
+        : 'darwin-x86_64';
+      assert.deepEqual(Object.keys(result.manifest.platforms), [key]);
+      assert.deepEqual(Object.keys(result.manifest.downloads), [key]);
+      assert.match(
+        result.manifest.platforms[key].url,
+        /\/dev-mac\/.*\.app\.tar\.gz$/,
+      );
+      assert.equal(
+        decodeURIComponent(
+          new URL(result.manifest.downloads[key].url).pathname,
+        ),
+        `/agc/dev-mac/${packageVersion}/${path.basename(downloadArtifact)}`,
+      );
+      assert.deepEqual(
+        JSON.parse(readFileSync(result.manifestPath, 'utf8')),
+        result.manifest,
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+test('DMG selection ignores other versions and architectures but rejects missing, empty and ambiguous current packages', () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'agc-dmg-selection-'));
+  try {
+    const target = 'aarch64-apple-darwin';
+    const options = {
+      target,
+      version: '2.3.4',
+      artifact: path.join(root, '陶泥儿.app.tar.gz'),
+    };
+    const oldVersion = createDmgFixture(root, target, '2.3.3');
+    const wrongArchitecture = createDmgFixture(
+      root,
+      'x86_64-apple-darwin',
+      '2.3.4',
+    );
+    assert.throws(() => selectFirstInstallArtifact([], options), /找到 0 个/u);
+    assert.throws(
+      () =>
+        selectFirstInstallArtifact([oldVersion, wrongArchitecture], options),
+      /找到 0 个/u,
+    );
+    const current = createDmgFixture(root, target, '2.3.4');
+    assert.equal(
+      selectFirstInstallArtifact(
+        [oldVersion, wrongArchitecture, current],
+        options,
+      ),
+      current,
+    );
+    writeFileSync(current, '');
+    assert.throws(
+      () => selectFirstInstallArtifact([current], options),
+      /不存在或为空/u,
+    );
+    writeFileSync(current, 'valid dmg');
+    const second = path.join(root, '另一包_2.3.4_aarch64.dmg');
+    writeFileSync(second, 'ambiguous dmg');
+    assert.throws(
+      () => selectFirstInstallArtifact([current, second], options),
+      /找到 2 个/u,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('manifest writer refuses to create latest when the current Mac DMG is missing', async () => {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'agc-missing-dmg-'));
+  try {
+    const artifact = path.join(root, '陶泥儿.app.tar.gz');
+    writeFileSync(artifact, 'updater archive');
+    writeFileSync(`${artifact}.sig`, 'signature');
+    const context = {
+      ...resolveReleaseContext(['--target=aarch64-apple-darwin'], {}),
+      bundleRoot: root,
+    };
+    await assert.rejects(
+      () => generateUpdateManifest(context),
+      /首装 DMG 必须唯一匹配/u,
+    );
+    assert.throws(() => readFileSync(path.join(root, 'latest.json')), {
+      code: 'ENOENT',
+    });
+  } 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,unity-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: '修复与改进' }, () => {
@@ -154,6 +499,9 @@ test('channel manifest carries version, platform keys and signature', () => {
       assert.equal(manifest.notes, '修复与改进');
       assert.equal(manifest.pub_date, '2026-09-17T00:00:00.000Z');
       assert.deepEqual(Object.keys(manifest.platforms), ['windows-x86_64']);
+      assert.deepEqual(manifest.downloads, {
+        'windows-x86_64': { url: manifest.platforms['windows-x86_64'].url },
+      });
       assert.equal(
         manifest.platforms['windows-x86_64'].signature,
         'signature-content',
@@ -334,17 +682,18 @@ test('recent commit fallback marks that entries may repeat the previous release'
   }
 });
 
-test('release upload forces overwrite for artifact, signature and channel pointers', () => {
+test('release entry forwards the built artifacts and dry-run mode to the uploader', () => {
   const source = readFileSync(
     new URL('./release-upload.mjs', import.meta.url),
     'utf8',
   );
-  assert.equal(
+  assert.match(
-    (source.match(/runOssutil\(\[\s*'cp',\s*'--force'/gu) ?? []).length,
+    source,
-    4,
+    /const release = await buildRelease\(process\.argv\.slice\(2\)\)/u,
   );
-  assert.match(source, /agc\/\$\{channel\}\/latest\.json/u);
+  assert.match(source, /uploadReleaseArtifacts\(release, \{/u);
-  assert.match(source, /agc\/latest\.json/u);
+  assert.match(source, /const dryRun = readReleaseDryRun\(\);/u);
+  assert.ok(source.includes('\n  dryRun,\n'));
 });
 
 test('release notes list client commits with short sha and bound their size', () => {

apps/ai-game-creator-shell/scripts/cargo-features.mjs

@@ -19,6 +19,6 @@ export function withDefaultCargoFeatures(argv, features) {
 
 export function defaultEditorFeatures(target) {
   return target === 'win32' || target.includes('windows')
-    ? ['cocos-editor-execute']
+    ? ['cocos-editor-execute', 'unity-editor-execute']
     : [];
 }

apps/ai-game-creator-shell/scripts/cargo-features.test.mjs

@@ -9,7 +9,7 @@ test('Windows release includes the same editor feature as development', () => {
     buildTauriBuildArguments([], 'x86_64-pc-windows-msvc', 'win32'),
     [
       'build',
-      '--features=cocos-editor-execute',
+      '--features=cocos-editor-execute,unity-editor-execute',
       '--target',
       'x86_64-pc-windows-msvc',
     ],

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',
@@ -121,8 +127,7 @@ const allowedUncalledTauriCommands = [
   'open_game_creator_launcher_window',
   'open_game_creator_workspace_window',
   'read_direct_project_conversation',
-  // 项目定时快照上传只在 Rust 侧触发（周期定时器 / 工作区窗口关闭）与排障调用；
+  // 前端登记工程生命周期，上传由 Rust 调度；以下两个命令仅供本机排障。
-  // 按产品口径不做客户端可见界面，因此同 `open_game_creator_*_window` 一样按 native-only 登记。
   'read_local_project_snapshot_state',
   'sync_local_project_snapshot',
   'reset_design_agent_session',
@@ -137,7 +142,6 @@ const allowedUncalledTauriCommands = [
   'reload_agc_plugin',
   'call_agc_plugin',
   'read_agc_plugin_panel',
-  'set_agc_plugin_project_path',
   'set_agc_plugin_enabled',
 ];
 const sourceExtensions = new Set([
@@ -1358,6 +1362,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 +1757,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/deterministic-lane-defense-provider.mjs

@@ -290,7 +290,7 @@ function deterministicArtManifest(
           {
             id: 'garden-guardians-spritesheet',
             path: 'assets/art-spritesheet.png',
-            kind: 'art-spritesheet',
+            kind: 'icon-spritesheet',
             usage: ['defenders', 'enemies', 'battlefield-ui'],
             source: 'canvas',
             status: 'ready',
@@ -710,7 +710,7 @@ function canvasAssetCall(agentId) {
       outputPath: 'assets/ui-prototype.png',
       aspectRatio: '16:9',
       imageSize: '2K',
-      assetKind: 'ui-prototype',
+      assetKind: 'ui-design',
       assetLabel: '游戏横屏界面原型图',
       replaceExisting: false,
     });
@@ -721,7 +721,7 @@ function canvasAssetCall(agentId) {
     outputPath: 'assets/art-spritesheet.png',
     aspectRatio: '1:1',
     imageSize: '1K',
-    assetKind: 'art-spritesheet',
+    assetKind: 'icon-spritesheet',
     assetLabel: '游戏首版核心美术素材',
     replaceExisting: false,
     sliceMode: 'connected-components',
@@ -830,12 +830,12 @@ function missingGeneratedVisualAssetObservation(context, agentId) {
     },
     'design-foundation': {
       path: 'assets/ui-prototype.png',
-      kind: 'ui-prototype',
+      kind: 'ui-design',
       summary: '策划界面原型图尚未按正式视觉流程生成并登记，不能完成任务',
     },
     'art-asset-plan': {
       path: 'assets/art-spritesheet.png',
-      kind: 'art-spritesheet',
+      kind: 'icon-spritesheet',
       summary: '首版美术素材图尚未按正式视觉流程生成并登记，不能完成任务',
     },
   }[agentId];
@@ -2667,7 +2667,7 @@ function createDeterministicCanvasFixture(apiKey) {
           asset: {
             assetId: `asset-${sliceImageId}`,
             assetObjectId: sliceAssetObjectId,
-            assetKind: 'art-spritesheet-slice',
+            assetKind: 'icon',
             projectId,
             taskId,
           },
@@ -2707,7 +2707,7 @@ function createDeterministicCanvasFixture(apiKey) {
         spritesheetAsset: {
           assetId: `asset-${imageId}`,
           assetObjectId,
-          assetKind: 'art-spritesheet',
+          assetKind: 'icon-spritesheet',
           projectId,
           taskId,
         },
@@ -2749,7 +2749,7 @@ function createDeterministicCanvasFixture(apiKey) {
       const assetObjectId = `asset-object-${imageId}`;
       const resourceId = `resource-${imageId}`;
       const assetKind =
-        typeof body?.assetKind === 'string' ? body.assetKind : 'game-art';
+        typeof body?.assetKind === 'string' ? body.assetKind : 'image';
       images.set(imageId, {
         ...image,
         objectKey,