Merge remote-tracking branch 'origin/master' into fix/agc-acceptance-followup

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

@@ -5,9 +5,11 @@ import {
   executeAdminRechargeRefund,
   getAdminFeatureGateConfig,
   getAdminUserDetail,
+  listAdminGameDistributionReviews,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
   resolveAdminRechargeRefundManualReview,
+  reviewAdminGameDistributionVersion,
   updateAdminAccount,
   uploadAdminEditorShowcaseCampaignImage,
   upsertAdminFeatureGateConfig,
@@ -364,3 +366,87 @@ test('退款人工复核使用独立 resolve 管理员路由', async () => {
     }),
   );
 });
+
+test('游戏审核列表与审核动作使用约定的 URL、方法和幂等键', async () => {
+  const fetchMock = vi.fn().mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ entries: [], nextCursor: null }), {
+        status: 200,
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await listAdminGameDistributionReviews('admin-token');
+  await reviewAdminGameDistributionVersion(
+    'admin-token',
+    'gamever/1',
+    'game-review-key-1',
+    {
+      decision: 'approve',
+      expectedPublicationRevision: 3,
+      entryUrl: 'https://games.example.test/releases/game_1/index.html',
+    },
+  );
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe(
+    '/admin/api/game-distribution/reviews?limit=48',
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe(
+    '/admin/api/game-distribution/versions/gamever%2F1/review',
+  );
+  expect(fetchMock.mock.calls[1]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        'Idempotency-Key': 'game-review-key-1',
+      }),
+      body: JSON.stringify({
+        decision: 'approve',
+        expectedPublicationRevision: 3,
+        entryUrl: 'https://games.example.test/releases/game_1/index.html',
+      }),
+    }),
+  );
+});
+
+test('游戏审核拒绝请求携带理由，空幂等键在本地失败关闭', async () => {
+  const fetchMock = vi.fn().mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ version: {}, replayed: false }), {
+        status: 200,
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await reviewAdminGameDistributionVersion(
+    'admin-token',
+    'version-1',
+    'game-review-key-2',
+    {
+      decision: 'reject',
+      expectedPublicationRevision: 0,
+      reviewReason: '运行时报错',
+    },
+  );
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      body: JSON.stringify({
+        decision: 'reject',
+        expectedPublicationRevision: 0,
+        reviewReason: '运行时报错',
+      }),
+    }),
+  );
+
+  expect(() =>
+    reviewAdminGameDistributionVersion('admin-token', 'version-1', '   ', {
+      decision: 'reject',
+      expectedPublicationRevision: 0,
+      reviewReason: 'x',
+    }),
+  ).toThrow('审核幂等键必须是 1 到 128 个字符');
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+});

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

@@ -29,9 +29,14 @@ import type {
   AdminExternalApiKeyListQuery,
   AdminExternalApiKeyListResponse,
   AdminFeatureGateConfigResponse,
+  AdminGameDistributionReviewListResponse,
+  AdminGameDistributionReviewRequest,
+  AdminGameDistributionReviewResponse,
   AdminLoginResponse,
   AdminMeResponse,
   AdminOverviewResponse,
+  AdminProjectSnapshotListQuery,
+  AdminProjectSnapshotListResponse,
   AdminRechargeOrderListQuery,
   AdminRechargeOrderListResponse,
   AdminRechargeRefundActionResponse,
@@ -198,6 +203,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,
@@ -1088,3 +1179,42 @@ export function saveAgcModelCatalog(
     { token, method: 'PUT', body },
   );
 }
+
+export function listAdminGameDistributionReviews(token: string, limit = 48) {
+  const normalizedLimit = Number.isFinite(limit)
+    ? Math.min(Math.max(Math.trunc(limit), 1), 48)
+    : 48;
+  return request<AdminGameDistributionReviewListResponse>(
+    `/admin/api/game-distribution/reviews?limit=${normalizedLimit}`,
+    { token },
+  );
+}
+
+/**
+ * 审核游戏发行版本。幂等键由调用方生成并在同一次提交内复用，避免重复点击产生
+ * 两条审核结论。
+ */
+export function reviewAdminGameDistributionVersion(
+  token: string,
+  versionId: string,
+  idempotencyKey: string,
+  payload: AdminGameDistributionReviewRequest,
+) {
+  const normalizedVersionId = versionId.trim();
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedVersionId) {
+    throw new Error('缺少发行版本 ID');
+  }
+  if (!normalizedKey || normalizedKey.length > 128) {
+    throw new Error('审核幂等键必须是 1 到 128 个字符');
+  }
+  return request<AdminGameDistributionReviewResponse>(
+    `/admin/api/game-distribution/versions/${encodeURIComponent(normalizedVersionId)}/review`,
+    {
+      method: 'POST',
+      token,
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: payload,
+    },
+  );
+}

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;
@@ -1010,3 +1031,33 @@ export interface AdminAgcModelCatalog {
   defaultModelId: string;
   models: AdminAgcModel[];
 }
+
+export interface AdminGameDistributionReviewEntry {
+  versionId: string;
+  gameId: string;
+  versionNumber: number;
+  packageSha256: string;
+  packageBytes: number;
+  status: string;
+  publicationRevision: number;
+  reviewReason: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AdminGameDistributionReviewListResponse {
+  entries: AdminGameDistributionReviewEntry[];
+  nextCursor: string | null;
+}
+
+export interface AdminGameDistributionReviewRequest {
+  decision: 'approve' | 'reject';
+  expectedPublicationRevision: number;
+  reviewReason?: string;
+  entryUrl?: string;
+}
+
+export interface AdminGameDistributionReviewResponse {
+  version: AdminGameDistributionReviewEntry;
+  replayed: boolean;
+}

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

@@ -26,11 +26,13 @@ import { AdminEditorAssetQueryPage } from '../pages/AdminEditorAssetQueryPage';
 import { AdminEditorGenerationPricingPage } from '../pages/AdminEditorGenerationPricingPage';
 import { AdminEditorShowcaseReviewPage } from '../pages/AdminEditorShowcaseReviewPage';
 import { AdminErrorReportsPage } from '../pages/AdminErrorReportsPage';
+import { AdminGameDistributionReviewPage } from '../pages/AdminGameDistributionReviewPage';
 import { AdminGrayReleaseConfigPage } from '../pages/AdminGrayReleaseConfigPage';
 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';
@@ -299,6 +301,12 @@ export function AdminApp() {
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {activeRouteId === 'game-distribution' ? (
+        <AdminGameDistributionReviewPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-assets' ? (
         <AdminEditorAssetQueryPage
           token={token}
@@ -308,6 +316,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,8 @@ import {
   Bug,
   Coins,
   Database,
+  FolderArchive,
+  Gamepad2,
   GitBranch,
   Images,
   LayoutDashboard,
@@ -48,7 +50,9 @@ const routeIcons = {
   'recharge-orders': ReceiptText,
   'editor-generation-pricing': Coins,
   'editor-showcase': Star,
+  'game-distribution': Gamepad2,
   '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,49 @@ 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);
+});
+
+test('后台游戏审核路由可通过导航和 hash 访问', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'game-distribution',
+    label: '游戏审核',
+    hash: '#game-distribution',
+  });
+  expect(resolveAdminRoute('#game-distribution')).toBe('game-distribution');
+  expect(routeHash('game-distribution')).toBe('#game-distribution');
+});
+
+test('member 可单独获得游戏审核 Tab 权限', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'member',
+    tabPermissions: ['game-distribution'],
+  });
+  expect(routes.map((route) => route.id)).toEqual(['game-distribution']);
+  expect(resolveAccessibleAdminRoute('#game-distribution', routes)).toBe(
+    'game-distribution',
+  );
+});

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

@@ -15,7 +15,9 @@ export type AdminRouteId =
   | 'recharge-orders'
   | 'editor-generation-pricing'
   | 'editor-showcase'
+  | 'game-distribution'
   | 'editor-assets'
+  | 'project-snapshots'
   | 'agc-models'
   | 'accounts';
 
@@ -53,7 +55,9 @@ export const adminRoutes: AdminRouteDefinition[] = [
   },
   { id: 'agc-models', label: 'AGC 模型', hash: '#agc-models', ownerOnly: true },
   { id: 'editor-showcase', label: '精选审核', hash: '#editor-showcase' },
+  { id: 'game-distribution', label: '游戏审核', hash: '#game-distribution' },
   { 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/AdminGrayReleaseConfigPage.test.tsx

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

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

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

apps/admin-web/src/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/scripts/agc-global-version.mjs

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

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

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

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

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

@@ -5,6 +5,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import {
+  assertRequestedVersionNotBelowChannel,
+  issueGlobalVersion as issueAgcGlobalVersion,
+} from './agc-global-version.mjs';
 import {
   defaultEditorFeatures,
   withDefaultCargoFeatures,
@@ -68,7 +72,7 @@ export function resolveReleaseContext(args = [], env = process.env) {
   );
   return Object.freeze({
     target,
-    channel: resolveReleaseChannel(env, target),
+    channel: resolveReleaseChannel(env),
     bundleRoot: path.join(
       appRoot,
       'src-tauri',
@@ -87,14 +91,14 @@ const cargoLockPath = path.join(appRoot, 'src-tauri', 'Cargo.lock');
 const defaultOssBaseUrl =
   'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc';
 
-/**
- * 发布渠道 → 目标平台。渠道名会进入 OSS 路径并烘焙进客户端端点，
- * 一旦发布就不能改名（改名等于已发布客户端再也找不到更新）。
- */
-const releaseChannels = {
-  'dev-win': 'windows',
-  'dev-mac': 'darwin',
-};
+const reservedChannelNames = new Set([
+  'win',
+  'mac',
+  'windows',
+  'macos',
+  'darwin',
+  'linux',
+]);
 
 /**
  * 影响 Windows 客户端产物的路径。调度管线的发布范围判定与这里的提交摘要必须
@@ -105,6 +109,8 @@ export const agcReleasePathPatterns = [
   'packages/',
   'server-rs/crates/',
   'plugins/agc-cocos-editor/',
+  'plugins/agc-unity-editor/',
+  'plugins/agc-godot-editor/',
   'apps/desktop-shell/src-tauri/icons/',
   'package.json',
   'package-lock.json',
@@ -161,39 +167,36 @@ export function resolveReleasePlatform(target = defaultTarget()) {
   throw new Error(`不支持的发布目标：${target}`);
 }
 
-export function resolveReleaseChannel(
-  env = process.env,
-  target = defaultTarget(),
-) {
-  const platform = resolveReleasePlatform(target);
-  const requested = env.AGC_UPDATE_CHANNEL?.trim();
-  if (requested) {
-    const channelPlatform = releaseChannels[requested];
-    if (!channelPlatform) {
-      throw new Error(
-        `未知发布渠道 ${requested}；当前支持：${Object.keys(releaseChannels).join('、')}`,
-      );
-    }
-    if (channelPlatform !== platform) {
-      throw new Error(
-        `渠道 ${requested} 只能用于 ${channelPlatform} 目标，当前构建目标为 ${target}`,
-      );
-    }
-    return requested;
-  }
-  const defaultChannel = Object.entries(releaseChannels).find(
-    ([, channelPlatform]) => channelPlatform === platform,
-  )?.[0];
-  if (!defaultChannel) {
+export function resolveReleaseChannel(env = process.env) {
+  const channel = env.AGC_UPDATE_CHANNEL?.trim() ?? 'dev';
+  if (
+    !/^[a-z][a-z0-9-]{0,31}$/u.test(channel) ||
+    channel.endsWith('-') ||
+    reservedChannelNames.has(channel) ||
+    /-(win|mac)$/u.test(channel)
+  ) {
     throw new Error(
-      `目标 ${target} 没有默认发布渠道，请显式设置 AGC_UPDATE_CHANNEL`,
+      '发布渠道无效：请使用 dev、release 或最多 32 位的小写字母、数字和连字符名称，系统名称不属于渠道',
     );
   }
-  return defaultChannel;
+  return channel;
 }
 
-export function updateManifestUrl(channel = resolveReleaseChannel()) {
-  return `${ossBaseUrl()}/${channel}/latest.json`;
+/** 系统分区延续已发布客户端端点，渠道本身不包含系统。 */
+export function resolveReleasePartition(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
+  channel = resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel });
+  validateReleaseTarget(target);
+  return `${channel}-${resolveReleasePlatform(target) === 'windows' ? 'win' : 'mac'}`;
+}
+
+export function updateManifestUrl(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
+  return `${ossBaseUrl()}/${resolveReleasePartition(channel, target)}/latest.json`;
 }
 
 /**
@@ -244,8 +247,8 @@ async function readManifestVersion(manifestUrl, label) {
 }
 
 /** 上一次发布的渠道清单：拿版本做高水位、拿 commit 生成自动更新摘要。 */
-async function readRemoteChannelManifest(channel = resolveReleaseChannel()) {
-  return fetchManifest(updateManifestUrl(channel), 'OSS 渠道清单');
+async function readRemoteChannelManifest(channel, target) {
+  return fetchManifest(updateManifestUrl(channel, target), 'OSS 渠道清单');
 }
 
 /**
@@ -257,14 +260,17 @@ async function readRemoteChannelManifest(channel = resolveReleaseChannel()) {
  */
 export async function resolvePreviousReleaseCommit(
   channel = resolveReleaseChannel(),
-  { override = process.env.AGC_UPDATE_PREVIOUS_COMMIT } = {},
+  {
+    override = process.env.AGC_UPDATE_PREVIOUS_COMMIT,
+    target = defaultTarget(),
+  } = {},
 ) {
   const explicit = override?.trim();
   if (explicit && /^[0-9a-f]{7,40}$/u.test(explicit)) {
     return explicit;
   }
   try {
-    const manifest = await readRemoteChannelManifest(channel);
+    const manifest = await readRemoteChannelManifest(channel, target);
     const commit =
       typeof manifest?.commit === 'string' ? manifest.commit.trim() : '';
     return /^[0-9a-f]{7,40}$/u.test(commit) ? commit : null;
@@ -286,12 +292,14 @@ export async function resolvePreviousReleaseCommit(
  */
 export async function resolveRemoteHighWaterVersion(
   channel = resolveReleaseChannel(),
+  target = defaultTarget(),
 ) {
   const channelVersion = await readManifestVersion(
-    updateManifestUrl(channel),
+    updateManifestUrl(channel, target),
     'OSS 渠道清单',
   );
-  if (channel !== 'dev-win') return channelVersion;
+  if (channel !== 'dev' || resolveReleasePlatform(target) !== 'windows')
+    return channelVersion;
   const legacyVersion = await readManifestVersion(
     legacyBridgeManifestUrl(),
     'OSS 迁移指针',
@@ -308,14 +316,35 @@ function replaceVersionLine(source, version, pattern, label) {
   return source.replace(pattern, `$1${version}$3`);
 }
 
+/**
+ * 版本来源固定为 OSS 总版本号（`agc/global-version.json`）：
+ * - CI 统一构建由发号 Job 先发号，再通过 AGC_RELEASE_VERSION 透传给各渠道；
+ * - 未传入时（本地手工兜底）由本函数现场发号并写回总号；
+ * - 渠道高水位只做断言：传入号低于本渠道清单版本即失败关闭。
+ */
 export async function prepareReleaseVersion(context = resolveReleaseContext()) {
-  const { channel } = context;
+  const { channel, target } = context;
   const localVersion = parseVersion(readPackageJson().version, '本地版本');
-  const remoteVersion = await resolveRemoteHighWaterVersion(channel);
+  const remoteVersion = await resolveRemoteHighWaterVersion(channel, target);
   const requestedVersion = process.env.AGC_RELEASE_VERSION?.trim();
   const nextVersion = requestedVersion
-    ? parseVersion(requestedVersion, '指定版本')
-    : nextPatchVersion(localVersion, remoteVersion);
+    ? assertRequestedVersionNotBelowChannel({
+        requested: requestedVersion,
+        channelVersion: remoteVersion,
+        channel,
+      })
+    : await issueAgcGlobalVersion({
+        channel,
+        commit:
+          process.env.COMMIT_HASH?.trim() ||
+          process.env.GIT_COMMIT?.trim() ||
+          null,
+        buildId:
+          process.env.BUILD_NUMBER?.trim() ||
+          process.env.AGC_BUILD_ID?.trim() ||
+          null,
+        repoVersion: localVersion,
+      });
 
   const packageSource = fs.readFileSync(packageJsonPath, 'utf8');
   fs.writeFileSync(
@@ -374,8 +403,8 @@ export async function prepareReleaseVersion(context = resolveReleaseContext()) {
 
   console.log(
     requestedVersion
-      ? `[ai-game-creator-shell] 渠道 ${channel} 使用指定版本 ${nextVersion}（本地 ${localVersion} / OSS ${remoteVersion ?? '不存在'}）`
-      : `[ai-game-creator-shell] 渠道 ${channel} 版本 ${localVersion} / OSS ${remoteVersion ?? '不存在'} -> ${nextVersion}`,
+      ? `[ai-game-creator-shell] 渠道 ${channel} 使用发号 Job 下发的总号 ${nextVersion}（本渠道清单 ${remoteVersion ?? '不存在'} / 仓库 ${localVersion}）`
+      : `[ai-game-creator-shell] 渠道 ${channel} 本地兜底发号 ${nextVersion}（本渠道清单 ${remoteVersion ?? '不存在'} / 仓库 ${localVersion}）`,
   );
   return nextVersion;
 }
@@ -400,24 +429,27 @@ export function buildTauriBuildArguments(
 }
 
 /** 渠道端点必须由构建期注入：官方更新插件的端点配置不支持运行期改渠道。 */
-export function createChannelConfig(channel = resolveReleaseChannel()) {
+export function createChannelConfig(
+  channel = resolveReleaseChannel(),
+  target = defaultTarget(),
+) {
   return {
     plugins: {
       updater: {
-        endpoints: [updateManifestUrl(channel)],
+        endpoints: [updateManifestUrl(channel, target)],
       },
     },
   };
 }
 
-function writeChannelConfigFile(channel) {
+function writeChannelConfigFile(channel, target) {
   const configPath = path.join(
     os.tmpdir(),
-    `agc-tauri-channel-${channel}.json`,
+    `agc-tauri-channel-${channel}-${target}.json`,
   );
   fs.writeFileSync(
     configPath,
-    `${JSON.stringify(createChannelConfig(channel), null, 2)}\n`,
+    `${JSON.stringify(createChannelConfig(channel, target), null, 2)}\n`,
   );
   return configPath;
 }
@@ -434,8 +466,8 @@ export function runTauriBuild(
     throw new Error('构建参数与发布上下文目标不一致');
   }
   const tauriArguments = buildTauriBuildArguments(args, context.target);
-  const { channel } = context;
-  const configPath = writeChannelConfigFile(channel);
+  const { channel, target } = context;
+  const configPath = writeChannelConfigFile(channel, target);
   console.log(
     `[ai-game-creator-shell] 渠道 ${channel} 端点配置：${configPath}`,
   );
@@ -500,6 +532,41 @@ export function selectReleaseArtifact(files, target = defaultTarget()) {
   );
 }
 
+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)) {
@@ -516,27 +583,36 @@ export function createUpdateManifest(
   artifactPath,
   {
     target = defaultTarget(),
-    channel = resolveReleaseChannel(process.env, target),
+    channel = resolveReleaseChannel(),
     publishedAt = new Date().toISOString(),
     notes = readReleaseNotes(),
     commit = readHeadCommit(),
+    downloadArtifact,
   } = {},
 ) {
   validateReleaseTarget(target);
-  resolveReleaseChannel({ AGC_UPDATE_CHANNEL: channel }, target);
+  const partition = resolveReleasePartition(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 url = `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`;
+  const downloadUrl = `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(path.basename(firstInstallArtifact))}`;
   const platforms = {};
+  const downloads = {};
   for (const key of resolveManifestPlatformKeys(target)) {
     platforms[key] = { signature, url };
+    downloads[key] = { url: downloadUrl };
   }
   return {
     version,
     ...(notes ? { notes } : {}),
     pub_date: publishedAt,
     platforms,
+    downloads,
     // 非标准字段：更新插件会忽略，发布脚本用它定位下一次自动更新摘要的起点。
     ...(commit ? { commit } : {}),
   };
@@ -657,14 +733,22 @@ export function formatRecentReleaseNotes(commits) {
 /** 旧协议（sha256）清单：只用于把已发布客户端带到新渠道协议，一个版本周期后整条删除。 */
 export function createLegacyUpdateManifest(
   artifactPath,
-  { channel = resolveReleaseChannel(), notes = readReleaseNotes() } = {},
+  {
+    channel = resolveReleaseChannel(),
+    target = defaultTarget(),
+    notes = readReleaseNotes(),
+  } = {},
 ) {
+  const partition = resolveReleasePartition(channel, target);
+  if (partition !== 'dev-win') {
+    throw new Error('旧协议迁移清单只属于 dev 渠道的 Windows 系统');
+  }
   const bytes = fs.readFileSync(artifactPath);
   const version = readPackageJson().version;
   const fileName = path.basename(artifactPath);
   return {
     version,
-    downloadUrl: `${ossBaseUrl()}/${channel}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`,
+    downloadUrl: `${ossBaseUrl()}/${partition}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`,
     sha256: createHash('sha256').update(bytes).digest('hex'),
     size: bytes.length,
     ...(notes ? { releaseNotes: notes } : {}),
@@ -675,12 +759,20 @@ export async function generateUpdateManifest(
   context = resolveReleaseContext(),
 ) {
   const { channel, target, bundleRoot } = context;
-  const artifact = selectReleaseArtifact(listFiles(bundleRoot), target);
+  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 previousCommit = await resolvePreviousReleaseCommit(channel, {
+    target,
+  });
   const commits = collectReleaseCommits(previousCommit);
   const recentCommits = previousCommit ? null : collectRecentReleaseCommits();
   const notes =
@@ -692,7 +784,12 @@ export async function generateUpdateManifest(
       `[ai-game-creator-shell] 未生成自动更新摘要（上一发布 commit=${previousCommit ?? '未知'}，客户端相关提交=${commits ? commits.length : '不可判定'}，最近提交=${recentCommits ? recentCommits.length : '不可判定'}）`,
     );
   }
-  const manifest = createUpdateManifest(artifact, { channel, target, 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');
@@ -701,8 +798,8 @@ export async function generateUpdateManifest(
     notes ? `${notes}\n` : '（本次没有可用的更新摘要）\n',
   );
   const legacyManifest =
-    channel === 'dev-win'
-      ? createLegacyUpdateManifest(artifact, { channel, notes })
+    channel === 'dev' && resolveReleasePlatform(target) === 'windows'
+      ? createLegacyUpdateManifest(artifact, { channel, target, notes })
       : null;
   const legacyManifestPath = legacyManifest
     ? path.join(bundleRoot, 'legacy-latest.json')
@@ -717,6 +814,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 手动文案'
@@ -732,7 +830,9 @@ export async function generateUpdateManifest(
   }
   return {
     channel,
+    target,
     artifact,
+    downloadArtifact,
     manifest,
     manifestPath,
     notes,

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', 'godot-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,godot-editor-execute',
       '--target',
       'x86_64-pc-windows-msvc',
     ],

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

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

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,

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

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

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

@@ -1,3 +1,8 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { resolveReleasePartition } from './build-release.mjs';
+
 /**
  * 发布上传的 OSS 命令行整理：把 ossutil 参数与凭据整理成可执行或可打印的形式，
  * 便于在 dry-run 下核对将要执行的上传，同时保证任何输出都不回显凭据明文。
@@ -25,3 +30,101 @@ export function formatOssutilCommand({ binary, args, endpoint, credentials }) {
   }
   return parts.map(quoteArgument).join(' ');
 }
+
+export function createReleaseUploadPlan(
+  {
+    artifact,
+    downloadArtifact,
+    channel,
+    target,
+    manifest,
+    manifestPath,
+    legacyManifestPath,
+  },
+  bucket,
+) {
+  if (
+    !artifact ||
+    !downloadArtifact ||
+    !manifestPath ||
+    !manifest?.version ||
+    !channel ||
+    !target
+  ) {
+    throw new Error('发布结果缺少渠道、构建目标、更新包、首装包或清单');
+  }
+  const partition = resolveReleasePartition(channel, target);
+  if (legacyManifestPath && partition !== 'dev-win') {
+    throw new Error('旧协议迁移清单只属于 dev 渠道的 Windows 系统');
+  }
+  const prefix = `oss://${bucket}/agc/${partition}`;
+  const artifacts = [
+    ...new Set(
+      [artifact, `${artifact}.sig`, downloadArtifact].map((file) =>
+        path.resolve(file),
+      ),
+    ),
+  ];
+  const plan = artifacts.map((source) => ({
+    source,
+    destination: `${prefix}/${manifest.version}/${path.basename(source)}`,
+  }));
+  plan.push({ source: manifestPath, destination: `${prefix}/latest.json` });
+  if (legacyManifestPath) {
+    plan.push({
+      source: legacyManifestPath,
+      destination: `oss://${bucket}/agc/latest.json`,
+    });
+  }
+  return plan;
+}
+
+export function uploadReleaseArtifacts(
+  release,
+  {
+    bucket,
+    endpoint,
+    binary = 'ossutil',
+    accessKeyId,
+    accessKeySecret,
+    dryRun = false,
+    spawn = spawnSync,
+    log = console.log,
+  },
+) {
+  if (Boolean(accessKeyId) !== Boolean(accessKeySecret)) {
+    throw new Error('OSS AccessKey ID 和 Secret 必须同时提供');
+  }
+  const plan = createReleaseUploadPlan(release, bucket);
+  for (const { source, destination } of plan) {
+    // 全部安装对象成功后才执行 latest 指针；失败立即终止，不发布悬空链接。
+    const args = ['cp', '--force', source, destination];
+    if (dryRun) {
+      log(
+        `[dry-run] ${formatOssutilCommand({ binary, args, endpoint, credentials: Boolean(accessKeyId) })}`,
+      );
+      continue;
+    }
+    const credentials = accessKeyId
+      ? ['--access-key-id', accessKeyId, '--access-key-secret', accessKeySecret]
+      : [];
+    const result = spawn(
+      binary,
+      [...args, '--endpoint', endpoint, ...credentials],
+      {
+        stdio: 'inherit',
+        shell: false,
+      },
+    );
+    if (result.error)
+      throw new Error(`无法执行 ${binary}，请先安装并配置 ossutil`);
+    if (result.status !== 0) {
+      throw new Error(
+        `OSS 上传失败（退出码 ${result.status ?? 1}）：${destination}`,
+      );
+    }
+    log(`[ai-game-creator-shell] 已上传 ${destination}`);
+  }
+  if (dryRun) log('[ai-game-creator-shell] dry-run：未写入任何 OSS 对象');
+  return plan;
+}