补齐客户端埋点环境变量示例

补充本地、生产及容器的埋点 origin 配置示例和 dev/release 说明。
同步技术方案中的运行时配置入口与地址匹配要求。

.env.example

@@ -239,6 +239,12 @@ GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 # Windows/macOS 是系统维度，不填写 dev-win/dev-mac。
 GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL="dev"
 
+# 客户端埋点接收绑定的公开 origin，由 API Server 运行时读取；修改后重启服务。
+# 必须与客户端登录地址一致，不带 /api、路径或尾部斜杠；未配置/非法时上传接口返回 503。
+# 本地端口按实际启动结果填写（端口漂移后需同步），localhost 与 127.0.0.1 不可混用。
+# dev 使用 https://dev.genarrative.world；release 使用 https://www.genarrative.world。
+GENARRATIVE_AGC_ANALYTICS_ORIGIN="http://127.0.0.1:8082"
+
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.

.eslintrc.cjs

@@ -213,6 +213,8 @@ module.exports = {
     '!src/services/clipboard.test.ts',
     '!src/services/frontendRuntimeConfigService.ts',
     '!src/services/frontendRuntimeConfigService.test.ts',
+    '!src/services/gameDistributionClient.ts',
+    '!src/services/gameDistributionClient.test.ts',
     '!src/services/sseStream.ts',
     '!src/services/sseStream.test.ts',
     'src/AdventurePanel.tsx',

.gitea/workflows/project-ci.yml

@@ -82,12 +82,29 @@ jobs:
             sleep $((attempt * 2))
           done
 
+      - name: Prepare isolated Rust compilation cache
+        shell: bash
+        run: |
+          set -euo pipefail
+          node --test scripts/ci-rust-cache.test.mjs
+          bash scripts/ci-rust-cache.sh prepare
+
       - name: Run AI game creator shell Rust shard 1/4
         run: npm run check:native-shells:agc-rust-shard-1
 
       - name: Run AI game creator shell Rust shard 2/4
         run: npm run check:native-shells:agc-rust-shard-2
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   ai-game-creator-shell-rust-lane-2:
     name: AI game creator shell Rust lane 2/2
     runs-on: genarrative-ci
@@ -118,12 +135,25 @@ jobs:
             sleep $((attempt * 2))
           done
 
+      - name: Prepare isolated Rust compilation cache
+        run: bash scripts/ci-rust-cache.sh prepare
+
       - name: Run AI game creator shell Rust shard 3/4
         run: npm run check:native-shells:agc-rust-shard-3
 
       - name: Run AI game creator shell Rust shard 4/4
         run: npm run check:native-shells:agc-rust-shard-4
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   # agent-run smoke 会 spawn `cargo run`（走壳自己的 manifest），同样不装 npm 依赖，
   # 单独一个 job，免得把已经压到 4 分钟级的片 job 拖长。
   ai-game-creator-shell-rust-smoke:
@@ -156,9 +186,22 @@ jobs:
             sleep $((attempt * 2))
           done
 
+      - name: Prepare isolated Rust compilation cache
+        run: bash scripts/ci-rust-cache.sh prepare
+
       - name: Run AI game creator shell agent-run smoke
         run: npm run check:native-shells:agc-rust-smoke
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   # AGC 壳依赖的共享 / 平台和编辑器插件 crate 各自预热独立 manifest，再运行对应测试。
   ai-game-creator-shell-rust-crates:
     name: AI game creator shell Rust crates
@@ -257,9 +300,22 @@ jobs:
             sleep $((attempt * 2))
           done
 
+      - name: Prepare isolated Rust compilation cache
+        run: bash scripts/ci-rust-cache.sh prepare
+
       - name: Run AI game creator shell shared crate gates
         run: npm run check:native-shells:agc-rust-crates
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   backend-tests:
     name: Backend tests
     runs-on: genarrative-ci
@@ -330,6 +386,9 @@ jobs:
       - name: Check server-rs boundaries
         run: npm run check:server-rs-ddd
 
+      - name: Prepare isolated Rust compilation cache
+        run: bash scripts/ci-rust-cache.sh prepare
+
       - name: Run server-rs workspace tests
         run: cargo test --locked --workspace --exclude spacetime-module --no-fail-fast --manifest-path server-rs/Cargo.toml
 
@@ -342,6 +401,16 @@ jobs:
       - name: Check SpacetimeDB module
         run: cargo check --locked -p spacetime-module --manifest-path server-rs/Cargo.toml
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   # 客户端的壳级与契约门禁：静态契约断言、H5 / 微信 / 移动 / 桌面壳运行时门禁，
   # 以及依赖发布产物的构建 smoke。
   native-shell-tests:
@@ -384,15 +453,32 @@ jobs:
       - name: Run native shell contract gates
         run: npm run check:native-shells:contract
 
+      - name: Prepare isolated Rust compilation cache
+        run: bash scripts/ci-rust-cache.sh prepare
+
       - name: Run native shell gates
         run: npm run check:native-shells:shells
 
       - name: Run native shell release build smoke
+        # 发布构建有独立 profile/features 和资源 staging，不消费测试对象快照。
+        env:
+          RUSTC_WRAPPER: ''
+          CARGO_BUILD_RUSTC_WRAPPER: ''
         run: npm run check:native-shells:release
 
       - name: Ensure native lockfiles are unchanged
         run: git diff --exit-code -- apps/desktop-shell/src-tauri/Cargo.lock apps/ai-game-creator-shell/src-tauri/Cargo.lock
 
+      - name: Report isolated Rust compilation cache
+        if: always()
+        run: bash scripts/ci-rust-cache.sh report
+      - name: Publish master Rust cache artifact
+        continue-on-error: true
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        env:
+          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
+        run: python3 scripts/export-gitea-rust-cache.py
+
   frontend-tests:
     name: Frontend tests
     runs-on: genarrative-ci
@@ -410,7 +496,7 @@ jobs:
         run: bash scripts/ci-npm-ci-with-retry.sh
 
       - name: Run frontend and script tests
-        run: npm run test
+        run: npm run test:ci:frontend
 
       - name: Run BgFilter worker smoke harness tests
         run: npm run bgfilter-worker:smoke-test
@@ -474,6 +560,11 @@ jobs:
       - name: Install npm dependencies
         run: bash scripts/ci-npm-ci-with-retry.sh
 
+      - name: Validate CI cache maintenance behavior
+        run: |
+          python3 -m unittest discover -s scripts -p 'test_gitea_cache_*.py'
+          node --test scripts/export-ci-npm-download-cache.test.mjs
+
       - name: Run repository checks
         run: npm run check:repository-ci
 

CONTEXT.md

@@ -174,6 +174,14 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 
 ## 项目开发对话（DirectProject）
 
+**DirectProject 专属聊天模块**:
+AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、发送队列、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。
+_Avoid_: 把 DirectProject 作为项目总控聊天的一个布尔分支、把四种 Agent 会话抽象成同一事实源
+
+**项目工作台布局**:
+承载本地项目的资源工作区、项目级工具和独立聊天产品路径的外层界面；布局拥有跨面板的账户/钱包入口，聊天模块只负责项目对话，不嵌套账户展示。
+_Avoid_: 把钱包入口塞进聊天设置、让聊天组件拥有工作台级账户状态
+
 **项目对话历史**:
 AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
 _Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
@@ -186,6 +194,34 @@ _Avoid_: 进度通知、快照轮询、第二套历史
 把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
 _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 
+**引用候选**:
+输入区可以命中的对象集合（`@` 素材、`$` Skill），由宿主按种类注入；输入区不判断候选属于哪一类。
+_Avoid_: 输入区自己读项目清单或应用目录、把候选取值写死在组件里
+
+**引用 provider**:
+一种引用种类向输入区提供的全部能力：触发符、候选、身份解析与正文文本形态；每种引用各一份，宿主按需选择性注入。
+_Avoid_: 一个总装对象决定所有种类、输入区按种类分叉、provider 之间互相知道对方
+
+**静默 provider**:
+不提供候选、只负责已有引用身份与文本形态的 provider；附件与运行画面区域属于这一类，只能由外部插入或草稿回填进入正文。
+_Avoid_: 给附件或运行画面区域造候选、为它们保留输入区内的专门分支
+
+**引用文本语法**:
+引用在正文文本里的形态（`@显示名` / `$名称` / `@附件名`）及其反解析；出站与解析必须同一口径，token 前后各留一个空白。
+_Avoid_: 出站与解析各写一套、在空白边界之外再补兼容别名、让解析依赖具体种类的字段
+
+**引用输入区**:
+只负责编辑与渲染引用的共享输入组件；候选、身份解析与文本语法都来自注入的 provider，它不持有项目清单、不访问后端。
+_Avoid_: 输入区自己拉 Skill 目录、把选择器面板塞在输入区内部
+
+**引用选择器**:
+宿主渲染的独立面板，自己拿数据与筛选状态，确认后把选中的引用交给输入区的插入缝。
+_Avoid_: 输入区自带面板、每个宿主各画一个、绕开插入缝另开第二条通道
+
+**附件芯片**:
+聊天附件在正文里的唯一表示；附件导入成功即以芯片进入正文，正文之外不存在第二份附件状态。
+_Avoid_: 待发送附件列表与正文芯片并存、提交时再拼一遍附件
+
 ## Relationships
 
 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -201,6 +237,10 @@ _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 - **个人历史成绩** 由最近记录列表和个人最佳摘要组成，只允许本人查看；排行榜只公开入榜胜利成绩。
 - **正式作品入口闭环** 必须覆盖创作入口、作品详情 CTA、广场/作品卡片、我的作品/个人作品架、稳定作品 ID runtime 路由和 `work_play_start` 埋点。
 - **Phase 2 实施顺序** 固定为：契约与领域规则 → SpacetimeDB 表/reducer 与 api-server BFF → 最小前端纵切 → 投影与列表体验 → 收口验证。
+- **引用输入区** 由宿主注入的若干 **引用 provider** 组成；**引用候选** 与 **引用文本语法** 都来自 provider，输入区不判断引用种类。
+- **引用选择器** 不属于 **引用输入区**：它自己拿数据，确认后只通过输入区的插入缝交付引用。
+- 只有带触发符的 **引用 provider** 会产生候选；**静默 provider** 没有触发符，只能由外部插入或草稿回填进入正文。
+- **附件芯片** 是本轮附件的唯一事实源；附件导入失败时不产生芯片。
 
 ## Example dialogue
 

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

@@ -3,12 +3,19 @@ import { afterEach, expect, test, vi } from 'vitest';
 import {
   createAdminAccount,
   executeAdminRechargeRefund,
+  getAdminAgcTemplates,
   getAdminFeatureGateConfig,
   getAdminUserDetail,
+  importAdminAgcTemplates,
+  listAdminAgcTrackingEvents,
+  listAdminGameDistributionReviews,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
   resolveAdminRechargeRefundManualReview,
+  reviewAdminGameDistributionVersion,
+  suspendAdminGameDistributionGame,
   updateAdminAccount,
+  updateAdminAgcTemplate,
   uploadAdminEditorShowcaseCampaignImage,
   upsertAdminFeatureGateConfig,
   upsertProfileWalletConfig,
@@ -18,6 +25,117 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
+test('客户端埋点查询传递筛选和游标并复用后台认证', async () => {
+  const payload = { entries: [], nextCursor: null };
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ ok: true, data: payload }), {
+      status: 200,
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  expect(
+    await listAdminAgcTrackingEvents('token', {
+      userId: 'user+1',
+      projectId: 'project-1',
+      cursor: 'page/2',
+      limit: 50,
+    }),
+  ).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/agc/tracking-events?userId=user%2B1&projectId=project-1&cursor=page%2F2&limit=50',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer token' }),
+    }),
+  );
+});
+
+test('模板管理读取和更新复用认证封装，提交 revision 和封面但不提交 ZIP 或版本', async () => {
+  const library = { revision: 'revision-new', writable: true, templates: [] };
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: library }), {
+        status: 200,
+      }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  const controller = new AbortController();
+  expect(await getAdminAgcTemplates('admin-token', controller.signal)).toEqual(
+    library,
+  );
+  const update = {
+    expectedRevision: 'revision-old',
+    title: '空白模板',
+    summary: '简介',
+    tags: ['2D'],
+    enabled: true,
+    cover: { contentType: 'image/png', dataBase64: 'aW1hZ2U=' },
+  };
+  expect(
+    await updateAdminAgcTemplate('admin-token', 'template/1', update),
+  ).toEqual(library);
+  expect(fetchMock.mock.calls[0]).toEqual([
+    '/admin/api/agc-templates',
+    expect.objectContaining({
+      method: 'GET',
+      signal: controller.signal,
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+    }),
+  ]);
+  expect(fetchMock.mock.calls[1]).toEqual([
+    '/admin/api/agc-templates/template%2F1',
+    expect.objectContaining({
+      method: 'PUT',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        'Content-Type': 'application/json',
+      }),
+      body: JSON.stringify(update),
+    }),
+  ]);
+});
+
+test('模板批量导入走 multipart，不预设 JSON Content-Type', async () => {
+  const imported = {
+    revision: 'rev-2',
+    writable: true,
+    templates: [],
+    imported: [
+      {
+        id: 'alpha',
+        templateVersion: '0.1.0',
+        zipSizeBytes: 4,
+        zipSha256: 'a'.repeat(64),
+        reusedObjects: false,
+      },
+    ],
+  };
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: imported }), {
+        status: 200,
+      }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  const form = new FormData();
+  form.append(
+    'manifest',
+    JSON.stringify({ expectedRevision: 'rev-1', templates: [] }),
+  );
+  form.append(
+    'zip_0',
+    new File([new Uint8Array([1])], 'alpha.zip', { type: 'application/zip' }),
+  );
+
+  expect(await importAdminAgcTemplates('admin-token', form)).toEqual(imported);
+  const [url, init] = fetchMock.mock.calls[0]!;
+  expect(url).toBe('/admin/api/agc-templates/import');
+  expect(init.method).toBe('POST');
+  expect(init.body).toBe(form);
+  expect(init.headers).not.toHaveProperty('Content-Type');
+  expect(init.headers.Authorization).toBe('Bearer admin-token');
+});
+
 test('后台账号创建和更新同时携带 Tab 与独立操作权限', async () => {
   const fetchMock = vi.fn().mockImplementation(() =>
     Promise.resolve(
@@ -364,3 +482,134 @@ 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({ game: {}, replayed: false }), {
+        status: 200,
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await suspendAdminGameDistributionGame(
+    'admin-token',
+    'game/1',
+    'game-suspend-key-1',
+    { expectedPublicationRevision: 7, reason: '版权投诉' },
+  );
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe(
+    '/admin/api/game-distribution/games/game%2F1/suspend',
+  );
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        'Idempotency-Key': 'game-suspend-key-1',
+      }),
+      body: JSON.stringify({
+        expectedPublicationRevision: 7,
+        reason: '版权投诉',
+      }),
+    }),
+  );
+
+  expect(() =>
+    suspendAdminGameDistributionGame('admin-token', '  ', 'key', {
+      expectedPublicationRevision: 1,
+    }),
+  ).toThrow('缺少游戏 ID');
+  expect(() =>
+    suspendAdminGameDistributionGame('admin-token', 'game-1', '  ', {
+      expectedPublicationRevision: 1,
+    }),
+  ).toThrow('下架幂等键必须是 1 到 128 个字符');
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+});
+
+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

@@ -1,5 +1,8 @@
 import type {
   AdminAccountListResponse,
+  AdminAgcTemplateLibraryResponse,
+  AdminAgcTrackingEventListResponse,
+  AdminAgcTrackingEventQuery,
   AdminConfirmEditorShowcaseCampaignImageUploadRequest,
   AdminCreateAccountRequest,
   AdminCreateAccountResponse,
@@ -29,9 +32,14 @@ import type {
   AdminExternalApiKeyListQuery,
   AdminExternalApiKeyListResponse,
   AdminFeatureGateConfigResponse,
+  AdminGameDistributionReviewListResponse,
+  AdminGameDistributionReviewRequest,
+  AdminGameDistributionReviewResponse,
+  AdminImportAgcTemplatesResponse,
   AdminLoginResponse,
   AdminMeResponse,
   AdminOverviewResponse,
+  AdminProjectSnapshotChannelsResponse,
   AdminProjectSnapshotListQuery,
   AdminProjectSnapshotListResponse,
   AdminRechargeOrderListQuery,
@@ -47,6 +55,7 @@ import type {
   AdminTrackingEventListResponse,
   AdminUpdateAccountRequest,
   AdminUpdateAccountResponse,
+  AdminUpdateAgcTemplateRequest,
   AdminUploadedEditorShowcaseCampaignImage,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertFeatureGateConfigRequest,
@@ -85,6 +94,8 @@ interface AdminRequestOptions {
   method?: string;
   token?: string;
   body?: unknown;
+  /** multipart 表单：交给浏览器自己带 boundary，不能预设 Content-Type。 */
+  formData?: FormData;
   headers?: Record<string, string>;
   signal?: AbortSignal;
 }
@@ -172,6 +183,8 @@ export async function request<T>(
   if (typeof options.body !== 'undefined') {
     headers['Content-Type'] = 'application/json';
     init.body = JSON.stringify(options.body);
+  } else if (options.formData) {
+    init.body = options.formData;
   }
 
   const response = await fetch(buildRequestUrl(path), init);
@@ -207,6 +220,7 @@ export function listAdminProjectSnapshots(
 ) {
   const params = new URLSearchParams();
   if (query.cursor) params.set('cursor', query.cursor);
+  if (query.channel) params.set('channel', query.channel);
   params.set('limit', String(query.limit ?? 20));
   return request<AdminProjectSnapshotListResponse>(
     `/admin/api/project-snapshots?${params.toString()}`,
@@ -214,13 +228,27 @@ export function listAdminProjectSnapshots(
   );
 }
 
+export function getAdminProjectSnapshotChannels(
+  token: string,
+  signal?: AbortSignal,
+) {
+  return request<AdminProjectSnapshotChannelsResponse>(
+    '/admin/api/project-snapshots/channels',
+    { token, signal },
+  );
+}
+
 export async function downloadAdminProjectSnapshot(
   token: string,
+  channel: string,
   userId: string,
   projectId: string,
   signal?: AbortSignal,
 ) {
-  const path = `/admin/api/project-snapshots/${encodeURIComponent(userId)}/${encodeURIComponent(projectId)}/download`;
+  const params = new URLSearchParams();
+  if (channel) params.set('channel', channel);
+  const query = params.toString();
+  const path = `/admin/api/project-snapshots/${encodeURIComponent(userId)}/${encodeURIComponent(projectId)}/download${query ? `?${query}` : ''}`;
   const response = await fetch(buildRequestUrl(path), {
     headers: {
       Authorization: `Bearer ${token.trim()}`,
@@ -383,6 +411,31 @@ export function listAdminTrackingEventKeys(token: string) {
   );
 }
 
+export function listAdminAgcTrackingEvents(
+  token: string,
+  query: AdminAgcTrackingEventQuery = {},
+) {
+  return request<AdminAgcTrackingEventListResponse>(
+    `/admin/api/agc/tracking-events${buildQueryString((params) => {
+      for (const key of [
+        'userId',
+        'projectId',
+        'creativeTaskId',
+        'agentRunId',
+        'eventName',
+        'clientVersion',
+        'startTime',
+        'endTime',
+        'cursor',
+      ] as const) {
+        appendQueryParam(params, key, query[key]);
+      }
+      appendNumericQueryParam(params, 'limit', query.limit);
+    })}`,
+    { token },
+  );
+}
+
 export function listAdminErrorReports(
   token: string,
   query: {
@@ -1176,3 +1229,102 @@ 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 },
+  );
+}
+
+/**
+ * 审核游戏发行版本。幂等键由调用方生成并在同一次提交内复用，避免重复点击产生
+ * 两条审核结论。
+ */
+/**
+ * 安全下架整个游戏。管理员下架同样要求 CAS 修订号与幂等键，避免并发审核互相覆盖。
+ */
+export function suspendAdminGameDistributionGame(
+  token: string,
+  gameId: string,
+  idempotencyKey: string,
+  payload: import('./adminApiTypes').AdminGameDistributionSuspendRequest,
+) {
+  const normalizedGameId = gameId.trim();
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedGameId) {
+    throw new Error('缺少游戏 ID');
+  }
+  if (!normalizedKey || normalizedKey.length > 128) {
+    throw new Error('下架幂等键必须是 1 到 128 个字符');
+  }
+  return request<
+    import('./adminApiTypes').AdminGameDistributionSuspendResponse
+  >(
+    `/admin/api/game-distribution/games/${encodeURIComponent(normalizedGameId)}/suspend`,
+    {
+      method: 'POST',
+      token,
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: payload,
+    },
+  );
+}
+
+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,
+    },
+  );
+}
+
+export function getAdminAgcTemplates(token: string, signal?: AbortSignal) {
+  return request<AdminAgcTemplateLibraryResponse>('/admin/api/agc-templates', {
+    token,
+    signal,
+  });
+}
+
+export function updateAdminAgcTemplate(
+  token: string,
+  id: string,
+  body: AdminUpdateAgcTemplateRequest,
+) {
+  return request<AdminAgcTemplateLibraryResponse>(
+    `/admin/api/agc-templates/${encodeURIComponent(id)}`,
+    { token, method: 'PUT', body },
+  );
+}
+
+/** 批量导入模板包：manifest 与 zip_N / cover_N 一起走 multipart，一批一次锁一次提交。 */
+export function importAdminAgcTemplates(token: string, formData: FormData) {
+  return request<AdminImportAgcTemplatesResponse>(
+    '/admin/api/agc-templates/import',
+    {
+      token,
+      method: 'POST',
+      formData,
+    },
+  );
+}

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

@@ -105,11 +105,15 @@ export interface AdminProjectSnapshotEntry {
   fileCount: number;
   totalBytes: number;
   status: 'ready' | 'partial' | 'unverified';
+  channel: string;
+  authorDisplayName?: string | null;
+  authorPublicUserCode?: string | null;
 }
 
 export interface AdminProjectSnapshotListQuery {
   cursor?: string | null;
   limit?: number;
+  channel?: string | null;
 }
 
 export interface AdminProjectSnapshotListResponse {
@@ -117,6 +121,11 @@ export interface AdminProjectSnapshotListResponse {
   nextCursor: string | null;
 }
 
+export interface AdminProjectSnapshotChannelsResponse {
+  defaultChannel: string;
+  channels: string[];
+}
+
 export interface AdminErrorReportEntry {
   batchId: string;
   eventCount: number;
@@ -811,6 +820,44 @@ export interface AdminTrackingEventListResponse {
   entries: AdminTrackingEventEntryPayload[];
 }
 
+export interface AdminAgcTrackingEventQuery {
+  userId?: string;
+  projectId?: string;
+  creativeTaskId?: string;
+  agentRunId?: string;
+  eventName?: string;
+  clientVersion?: string;
+  startTime?: string;
+  endTime?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface AdminAgcTrackingEventEntry {
+  eventId: string;
+  schemaVersion: number;
+  eventName: string;
+  eventTime: string;
+  userId: string;
+  editorSessionId: string;
+  projectId: string | null;
+  creativeTaskId: string | null;
+  agentRunId: string | null;
+  agentTurnId: string | null;
+  status: string | null;
+  errorCode: string | null;
+  source: string;
+  clientVersion: string;
+  properties: Record<string, unknown>;
+  batchId: string;
+  receivedAt: string;
+}
+
+export interface AdminAgcTrackingEventListResponse {
+  entries: AdminAgcTrackingEventEntry[];
+  nextCursor: string | null;
+}
+
 export interface AdminTrackingEventKeyPayload {
   eventKey: string;
   eventTitle: string;
@@ -1033,3 +1080,112 @@ 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;
+}
+
+export interface AdminGameDistributionSuspendRequest {
+  expectedPublicationRevision: number;
+  reason?: string;
+}
+
+export interface AdminGameDistributionSuspendResponse {
+  game: {
+    id: string;
+    title: string;
+    status: string;
+    publicationRevision: number;
+  };
+  replayed: boolean;
+}
+
+export interface AdminAgcTemplatePayload {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  enabled: boolean;
+  coverUrl: string;
+  zipSizeBytes: number;
+}
+
+export interface AdminAgcTemplateLibraryResponse {
+  revision: string;
+  writable: boolean;
+  templates: AdminAgcTemplatePayload[];
+}
+
+export interface AdminUpdateAgcTemplateRequest {
+  expectedRevision: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  enabled: boolean;
+  cover?: {
+    contentType: string;
+    dataBase64: string;
+  };
+}
+
+export interface AdminImportAgcTemplateItemPayload {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  entry: string;
+  zipField: string;
+  coverField: string;
+}
+
+export interface AdminImportAgcTemplatesManifest {
+  expectedRevision: string;
+  templates: AdminImportAgcTemplateItemPayload[];
+}
+
+export interface AdminImportAgcTemplateResult {
+  id: string;
+  templateVersion: string;
+  zipSizeBytes: number;
+  zipSha256: string;
+  reusedObjects: boolean;
+}
+
+export interface AdminImportAgcTemplatesResponse
+  extends AdminAgcTemplateLibraryResponse {
+  imported: AdminImportAgcTemplateResult[];
+}

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

@@ -2,6 +2,7 @@ import { afterEach, expect, test, vi } from 'vitest';
 
 import {
   downloadAdminProjectSnapshot,
+  getAdminProjectSnapshotChannels,
   listAdminProjectSnapshots,
 } from './adminApiClient';
 
@@ -21,12 +22,12 @@ test('项目列表携带分页与后台授权，解析标准响应', async () =>
   expect(
     await listAdminProjectSnapshots(
       'admin-token',
-      { cursor: 'user/a+项目', limit: 20 },
+      { cursor: 'user/a+项目', limit: 20, channel: 'release' },
       controller.signal,
     ),
   ).toEqual(payload);
   expect(fetchMock).toHaveBeenCalledWith(
-    '/admin/api/project-snapshots?cursor=user%2Fa%2B%E9%A1%B9%E7%9B%AE&limit=20',
+    '/admin/api/project-snapshots?cursor=user%2Fa%2B%E9%A1%B9%E7%9B%AE&channel=release&limit=20',
     expect.objectContaining({
       headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
       signal: controller.signal,
@@ -34,6 +35,23 @@ test('项目列表携带分页与后台授权，解析标准响应', async () =>
   );
 });
 
+test('渠道列表按后台授权读取，解析本部署渠道', async () => {
+  const payload = { defaultChannel: 'release', channels: ['dev', 'release'] };
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue(
+      new Response(JSON.stringify({ ok: true, data: payload })),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+  expect(await getAdminProjectSnapshotChannels('admin-token')).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/project-snapshots/channels',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+    }),
+  );
+});
+
 test('ZIP 下载以授权请求读取并优先保留中文附件名', async () => {
   const fetchMock = vi.fn().mockResolvedValue(
     new Response('PK\u0003\u0004', {
@@ -48,6 +66,7 @@ test('ZIP 下载以授权请求读取并优先保留中文附件名', async () =
   const controller = new AbortController();
   const archive = await downloadAdminProjectSnapshot(
     'admin-token',
+    'release',
     'user/a',
     'project/b',
     controller.signal,
@@ -55,7 +74,7 @@ test('ZIP 下载以授权请求读取并优先保留中文附件名', async () =
   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',
+    '/admin/api/project-snapshots/user%2Fa/project%2Fb/download?channel=release',
     expect.objectContaining({
       headers: expect.objectContaining({
         Authorization: 'Bearer admin-token',
@@ -81,7 +100,8 @@ test.each([
     vi.fn().mockResolvedValue(new Response('PK', { headers })),
   );
   expect(
-    (await downloadAdminProjectSnapshot('token', 'user', 'project')).filename,
+    (await downloadAdminProjectSnapshot('token', 'release', 'user', 'project'))
+      .filename,
   ).toBe(expected.replace('工程', 'project'));
 });
 
@@ -104,7 +124,7 @@ test.each([401, 403, 409, 500])(
       ),
     );
     await expect(
-      downloadAdminProjectSnapshot('token', 'user', 'project'),
+      downloadAdminProjectSnapshot('token', 'release', 'user', 'project'),
     ).rejects.toMatchObject({
       status,
       code: 'SNAPSHOT_FAILURE',
@@ -123,6 +143,6 @@ test('200 JSON 或 HTML 不能被保存为成功 ZIP', async () => {
     ),
   );
   await expect(
-    downloadAdminProjectSnapshot('token', 'user', 'project'),
+    downloadAdminProjectSnapshot('token', 'release', 'user', 'project'),
   ).rejects.toMatchObject({ code: 'INVALID_PROJECT_ARCHIVE_RESPONSE' });
 });

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

@@ -19,6 +19,8 @@ import {
 } from '../auth/adminAuthStore';
 import { AdminAccountsPage } from '../pages/AdminAccountsPage';
 import { AdminAgcModelsPage } from '../pages/AdminAgcModelsPage';
+import { AdminAgcTemplatesPage } from '../pages/AdminAgcTemplatesPage';
+import { AdminAgcTrackingPage } from '../pages/AdminAgcTrackingPage';
 import { AdminDashboardPage } from '../pages/AdminDashboardPage';
 import { AdminDatabaseTablesPage } from '../pages/AdminDatabaseTablesPage';
 import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
@@ -26,6 +28,7 @@ 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';
@@ -231,6 +234,12 @@ export function AdminApp() {
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {activeRouteId === 'agc-tracking' ? (
+        <AdminAgcTrackingPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'error-reports' ? (
         <AdminErrorReportsPage
           token={token}
@@ -294,12 +303,24 @@ export function AdminApp() {
       {activeRouteId === 'agc-models' ? (
         <AdminAgcModelsPage token={token} onUnauthorized={handleUnauthorized} />
       ) : null}
+      {activeRouteId === 'agc-templates' ? (
+        <AdminAgcTemplatesPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-showcase' ? (
         <AdminEditorShowcaseReviewPage
           token={token}
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {activeRouteId === 'game-distribution' ? (
+        <AdminGameDistributionReviewPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-assets' ? (
         <AdminEditorAssetQueryPage
           token={token}

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

@@ -5,6 +5,7 @@ import {
   Coins,
   Database,
   FolderArchive,
+  Gamepad2,
   GitBranch,
   Images,
   LayoutDashboard,
@@ -39,6 +40,7 @@ const routeIcons = {
   tables: Database,
   debug: Bug,
   tracking: Table2,
+  'agc-tracking': Table2,
   'error-reports': Bug,
   'gray-release': GitBranch,
   redeem: TicketPercent,
@@ -49,10 +51,12 @@ 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,
+  'agc-templates': Images,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;
 
 export function AdminShell({

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

@@ -8,6 +8,22 @@ import {
   routeHash,
 } from './adminRoutes';
 
+test('客户端埋点路由遵守成员页签权限', () => {
+  expect(resolveAdminRoute('#agc-tracking')).toBe('agc-tracking');
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['agc-tracking'],
+    }).map((route) => route.id),
+  ).toEqual(['agc-tracking']);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['tracking'],
+    }).some((route) => route.id === 'agc-tracking'),
+  ).toBe(false);
+});
+
 test('后台默认进入 Dashboard', () => {
   expect(adminRoutes[0]).toEqual({
     id: 'dashboard',
@@ -147,3 +163,51 @@ test('项目工程入口对 owner 与已授权 member 开放且可分配权限',
     }),
   ).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',
+  );
+});
+
+test('模板管理只对 owner 或具有 agc-templates 权限的 member 可见', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'agc-templates',
+    label: '模板管理',
+    hash: '#agc-templates',
+  });
+  expect(resolveAdminRoute('#agc-templates')).toBe('agc-templates');
+  expect(routeHash('agc-templates')).toBe('#agc-templates');
+  expect(
+    getAccessibleAdminRoutes({ accountRole: 'owner', tabPermissions: [] }).some(
+      (route) => route.id === 'agc-templates',
+    ),
+  ).toBe(true);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['agc-templates'],
+    }).map((route) => route.id),
+  ).toEqual(['agc-templates']);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['editor-assets'],
+    }).some((route) => route.id === 'agc-templates'),
+  ).toBe(false);
+});

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

@@ -5,6 +5,7 @@ export type AdminRouteId =
   | 'tables'
   | 'debug'
   | 'tracking'
+  | 'agc-tracking'
   | 'error-reports'
   | 'gray-release'
   | 'redeem'
@@ -15,9 +16,11 @@ export type AdminRouteId =
   | 'recharge-orders'
   | 'editor-generation-pricing'
   | 'editor-showcase'
+  | 'game-distribution'
   | 'editor-assets'
   | 'project-snapshots'
   | 'agc-models'
+  | 'agc-templates'
   | 'accounts';
 
 export type AdminTabPermission = Exclude<
@@ -39,6 +42,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
   { id: 'tables', label: '表查询', hash: '#tables' },
   { id: 'debug', label: 'API 调试', hash: '#debug' },
   { id: 'tracking', label: '埋点数据', hash: '#tracking' },
+  { id: 'agc-tracking', label: '客户端埋点', hash: '#agc-tracking' },
   { id: 'error-reports', label: '错误报告', hash: '#error-reports' },
   { id: 'gray-release', label: '灰度发布', hash: '#gray-release' },
   { id: 'redeem', label: '兑换码', hash: '#redeem' },
@@ -53,7 +57,9 @@ export const adminRoutes: AdminRouteDefinition[] = [
     hash: '#editor-generation-pricing',
   },
   { id: 'agc-models', label: 'AGC 模型', hash: '#agc-models', ownerOnly: true },
+  { id: 'agc-templates', label: '模板管理', hash: '#agc-templates' },
   { 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/main.tsx

@@ -1,3 +1,4 @@
+import '@genarrative/shared/styles.css';
 import './styles/admin.css';
 
 import { StrictMode } from 'react';

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

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  AdminApiError,
+  listAdminAgcTrackingEvents,
+} from '../api/adminApiClient';
+import type { AdminAgcTrackingEventEntry } from '../api/adminApiTypes';
+import { AdminAgcTrackingPage } from './AdminAgcTrackingPage';
+
+vi.mock('../api/adminApiClient', async (original) => ({
+  ...(await original<typeof import('../api/adminApiClient')>()),
+  listAdminAgcTrackingEvents: vi.fn(),
+}));
+vi.mock('../components/AdminUserReferenceButton', () => ({
+  AdminUserReferenceButton: () => null,
+}));
+
+const entry: AdminAgcTrackingEventEntry = {
+  eventId: 'event-1',
+  schemaVersion: 1,
+  eventName: 'project_save',
+  eventTime: '2026-09-21T12:00:00.123Z',
+  userId: 'user-1',
+  editorSessionId: 'session-1',
+  projectId: 'project-1',
+  creativeTaskId: 'project-1',
+  agentRunId: null,
+  agentTurnId: null,
+  status: 'success',
+  errorCode: null,
+  source: 'gui',
+  clientVersion: '1.0',
+  properties: { reason: 'manual' },
+  batchId: 'batch-1',
+  receivedAt: '2026-09-21T12:15:00.000Z',
+};
+
+beforeEach(() => {
+  vi.mocked(listAdminAgcTrackingEvents).mockReset();
+});
+afterEach(cleanup);
+
+test('翻页沿用游标，筛选和刷新从第一页重新查询，详情保留 null 和事件属性', async () => {
+  vi.mocked(listAdminAgcTrackingEvents)
+    .mockResolvedValueOnce({ entries: [entry], nextCursor: 'cursor-page-2' })
+    .mockResolvedValueOnce({
+      entries: [{ ...entry, eventId: 'event-2' }],
+      nextCursor: null,
+    })
+    .mockResolvedValue({ entries: [entry], nextCursor: 'cursor-new' });
+  render(<AdminAgcTrackingPage token="admin-token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('保存项目', { selector: 'td' });
+  expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith('admin-token', {
+    cursor: undefined,
+    limit: 50,
+  });
+  fireEvent.click(screen.getByText('查看详情'));
+  const dialog = screen.getByRole('dialog');
+  expect(within(dialog).getAllByText('—').length).toBe(3);
+  expect(within(dialog).getByText(/"reason": "manual"/)).toBeTruthy();
+  expect(within(dialog).getByText(entry.eventTime)).toBeTruthy();
+  fireEvent.click(within(dialog).getByLabelText('关闭详情'));
+  fireEvent.click(screen.getByText('下一页'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith('admin-token', {
+      cursor: 'cursor-page-2',
+      limit: 50,
+    }),
+  );
+  await waitFor(() =>
+    expect(screen.getByText('查询').closest('button')?.disabled).toBe(false),
+  );
+  fireEvent.click(screen.getByText('上一页'));
+  await screen.findByText('第 1 页');
+  expect(listAdminAgcTrackingEvents).toHaveBeenCalledTimes(2);
+  fireEvent.change(screen.getByLabelText('项目 ID'), {
+    target: { value: 'project-2' },
+  });
+  fireEvent.click(screen.getByText('查询'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenLastCalledWith(
+      'admin-token',
+      expect.objectContaining({
+        projectId: 'project-2',
+        cursor: undefined,
+        limit: 50,
+      }),
+    ),
+  );
+  expect(screen.getByText('第 1 页')).toBeTruthy();
+  await waitFor(() =>
+    expect(screen.getByText('刷新').closest('button')?.disabled).toBe(false),
+  );
+  fireEvent.click(screen.getByText('刷新'));
+  await waitFor(() =>
+    expect(listAdminAgcTrackingEvents).toHaveBeenCalledTimes(4),
+  );
+});
+
+test('空结果、权限失败与登录失效沿用后台反馈', async () => {
+  const unauthorized = vi.fn();
+  vi.mocked(listAdminAgcTrackingEvents)
+    .mockResolvedValueOnce({ entries: [], nextCursor: null })
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 403, message: '无权访问客户端埋点' }),
+    )
+    .mockRejectedValueOnce(
+      new AdminApiError({ status: 401, message: '登录失效' }),
+    );
+  render(<AdminAgcTrackingPage token="token" onUnauthorized={unauthorized} />);
+  await screen.findByText('暂无客户端埋点数据');
+  fireEvent.click(screen.getByText('刷新'));
+  expect((await screen.findByRole('alert')).textContent).toContain(
+    '无权访问客户端埋点',
+  );
+  fireEvent.click(screen.getByText('刷新'));
+  await waitFor(() =>
+    expect(unauthorized).toHaveBeenCalledWith('登录状态已失效'),
+  );
+});

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

@@ -0,0 +1,379 @@
+import { Modal } from '@genarrative/shared/components';
+import { FormEvent, useEffect, useRef, useState } from 'react';
+
+import { listAdminAgcTrackingEvents } from '../api/adminApiClient';
+import type {
+  AdminAgcTrackingEventEntry,
+  AdminAgcTrackingEventListResponse,
+  AdminAgcTrackingEventQuery,
+} from '../api/adminApiTypes';
+import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
+import { handlePageError } from './pageUtils';
+
+const eventLabels: Record<string, string> = {
+  editor_session_start: '编辑器会话开始',
+  editor_session_end: '编辑器会话结束',
+  editor_focus_start: '编辑器获得焦点',
+  editor_focus_end: '编辑器失去焦点',
+  project_create_success: '项目创建成功',
+  project_open: '打开项目',
+  creative_task_submit: '首次提交创作目标',
+  agent_run_completed: 'Agent 运行完成',
+  agent_run_failed: 'Agent 运行失败',
+  project_revision_created: '项目产生修改',
+  preview_ready: '预览就绪',
+  project_save: '保存项目',
+};
+
+const fieldLabels: Record<keyof AdminAgcTrackingEventEntry, string> = {
+  eventId: '事件 ID',
+  schemaVersion: '事件版本',
+  eventName: '事件类型',
+  eventTime: '发生时间',
+  userId: '用户 ID',
+  editorSessionId: '编辑器会话 ID',
+  projectId: '项目 ID',
+  creativeTaskId: '创作目标 ID',
+  agentRunId: 'Agent run ID',
+  agentTurnId: 'Agent turn ID',
+  status: '结果',
+  errorCode: '错误码',
+  source: '来源',
+  clientVersion: '客户端版本',
+  properties: '事件属性',
+  batchId: '批次 ID',
+  receivedAt: '入库时间',
+};
+
+function formatTime(value: string) {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN');
+}
+
+export function AdminAgcTrackingPage({
+  token,
+  onUnauthorized,
+}: {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}) {
+  const [filters, setFilters] = useState({
+    userId: '',
+    projectId: '',
+    eventName: '',
+    startTime: '',
+    endTime: '',
+  });
+  const [query, setQuery] = useState<AdminAgcTrackingEventQuery>({});
+  const [cursors, setCursors] = useState<Array<string | undefined>>([
+    undefined,
+  ]);
+  const [page, setPage] = useState(0);
+  const [refresh, setRefresh] = useState(0);
+  const [entries, setEntries] = useState<AdminAgcTrackingEventEntry[]>([]);
+  const [nextCursor, setNextCursor] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  const [detail, setDetail] = useState<AdminAgcTrackingEventEntry | null>(null);
+  const cursor = cursors[page];
+  // 首页没有入站游标，返回首页时保留原快照，刷新才获取新数据。
+  const firstPage = useRef<{
+    token: string;
+    query: AdminAgcTrackingEventQuery;
+    response: AdminAgcTrackingEventListResponse;
+  } | null>(null);
+
+  useEffect(() => {
+    const saved = firstPage.current;
+    if (!cursor && saved?.token === token && saved.query === query) {
+      setEntries(saved.response.entries);
+      setNextCursor(saved.response.nextCursor);
+      setError('');
+      setLoading(false);
+      return;
+    }
+    let active = true;
+    setLoading(true);
+    setError('');
+    setEntries([]);
+    setNextCursor(null);
+    void listAdminAgcTrackingEvents(token, { ...query, cursor, limit: 50 })
+      .then((response) => {
+        if (!active) return;
+        if (!cursor) firstPage.current = { token, query, response };
+        setEntries(response.entries);
+        setNextCursor(response.nextCursor);
+      })
+      .catch((failure: unknown) => {
+        if (active) handlePageError(failure, onUnauthorized, setError);
+      })
+      .finally(() => {
+        if (active) setLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [token, query, cursor, refresh, onUnauthorized]);
+
+  function resetPages() {
+    firstPage.current = null;
+    setCursors([undefined]);
+    setPage(0);
+    setDetail(null);
+  }
+
+  function search(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (
+      filters.startTime &&
+      filters.endTime &&
+      new Date(filters.startTime) >= new Date(filters.endTime)
+    ) {
+      setError('结束时间必须晚于开始时间');
+      return;
+    }
+    resetPages();
+    setQuery({
+      userId: filters.userId.trim(),
+      projectId: filters.projectId.trim(),
+      eventName: filters.eventName,
+      startTime: filters.startTime
+        ? new Date(filters.startTime).toISOString()
+        : undefined,
+      endTime: filters.endTime
+        ? new Date(filters.endTime).toISOString()
+        : undefined,
+    });
+  }
+
+  function related(
+    key: 'creativeTaskId' | 'agentRunId' | 'clientVersion',
+    value: string,
+  ) {
+    resetPages();
+    setFilters({
+      userId: '',
+      projectId: '',
+      eventName: '',
+      startTime: '',
+      endTime: '',
+    });
+    setQuery({ [key]: value });
+  }
+
+  return (
+    <section className="admin-page admin-page-wide">
+      <div className="admin-page-heading">
+        <div>
+          <h2>客户端埋点</h2>
+          <p>按发生时间倒序展示</p>
+        </div>
+        <button
+          type="button"
+          className="admin-secondary-button"
+          disabled={loading}
+          onClick={() => {
+            resetPages();
+            setRefresh((value) => value + 1);
+          }}
+        >
+          刷新
+        </button>
+      </div>
+      <form className="admin-panel admin-form" onSubmit={search}>
+        <div className="admin-filter-grid">
+          {(['userId', 'projectId'] as const).map((key) => (
+            <label key={key} className="admin-field">
+              <span>{fieldLabels[key]}</span>
+              <input
+                value={filters[key]}
+                onChange={(event) =>
+                  setFilters({ ...filters, [key]: event.target.value })
+                }
+              />
+            </label>
+          ))}
+          <label className="admin-field">
+            <span>事件类型</span>
+            <select
+              value={filters.eventName}
+              onChange={(event) =>
+                setFilters({ ...filters, eventName: event.target.value })
+              }
+            >
+              <option value="">全部</option>
+              {Object.entries(eventLabels).map(([value, label]) => (
+                <option key={value} value={value}>
+                  {label}
+                </option>
+              ))}
+            </select>
+          </label>
+          {(['startTime', 'endTime'] as const).map((key) => (
+            <label key={key} className="admin-field">
+              <span>
+                {key === 'startTime'
+                  ? '发生时间起点（含）'
+                  : '发生时间终点（不含）'}
+              </span>
+              <input
+                type="datetime-local"
+                value={filters[key]}
+                onChange={(event) =>
+                  setFilters({ ...filters, [key]: event.target.value })
+                }
+              />
+            </label>
+          ))}
+        </div>
+        <div className="admin-action-row">
+          <button
+            type="submit"
+            className="admin-primary-button"
+            disabled={loading}
+          >
+            查询
+          </button>
+        </div>
+        {(['creativeTaskId', 'agentRunId', 'clientVersion'] as const)
+          .filter((key) => query[key])
+          .map((key) => (
+            <p key={key}>
+              {fieldLabels[key]}：{query[key]}（重新查询可清除）
+            </p>
+          ))}
+      </form>
+      {error ? (
+        <p role="alert" className="admin-error-message">
+          {error}
+        </p>
+      ) : null}
+      <div className="admin-panel">
+        <div className="admin-table-wrap">
+          <table className="admin-table">
+            <thead>
+              <tr>
+                {[
+                  '入库时间',
+                  '发生时间',
+                  '用户',
+                  '事件名称',
+                  '项目',
+                  '来源',
+                  '结果',
+                  '客户端版本',
+                  '详情',
+                ].map((label) => (
+                  <th key={label}>{label}</th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {entries.map((entry) => (
+                <tr key={entry.eventId}>
+                  <td>{formatTime(entry.receivedAt)}</td>
+                  <td>{formatTime(entry.eventTime)}</td>
+                  <td>
+                    {entry.userId}
+                    <AdminUserReferenceButton
+                      token={token}
+                      userId={entry.userId}
+                      onUnauthorized={onUnauthorized}
+                    />
+                  </td>
+                  <td>{eventLabels[entry.eventName] ?? entry.eventName}</td>
+                  <td>{entry.projectId ?? '—'}</td>
+                  <td>{entry.source}</td>
+                  <td>{entry.status ?? '—'}</td>
+                  <td>{entry.clientVersion}</td>
+                  <td>
+                    <button
+                      type="button"
+                      className="admin-ghost-button"
+                      onClick={() => setDetail(entry)}
+                    >
+                      查看详情
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        {loading ? (
+          <p role="status">加载中…</p>
+        ) : !error && entries.length === 0 ? (
+          <p>暂无客户端埋点数据</p>
+        ) : null}
+        <div className="admin-action-row">
+          <button
+            type="button"
+            className="admin-secondary-button"
+            disabled={loading || page === 0}
+            onClick={() => setPage((value) => value - 1)}
+          >
+            上一页
+          </button>
+          <span>第 {page + 1} 页</span>
+          <button
+            type="button"
+            className="admin-secondary-button"
+            disabled={loading || !nextCursor}
+            onClick={() => {
+              if (!nextCursor) return;
+              setCursors([...cursors.slice(0, page + 1), nextCursor]);
+              setPage(page + 1);
+            }}
+          >
+            下一页
+          </button>
+        </div>
+      </div>
+      {detail ? (
+        <Modal
+          open
+          title="客户端埋点详情"
+          closeLabel="关闭详情"
+          onClose={() => setDetail(null)}
+          className="genarrative-ui"
+        >
+          <dl>
+            {(
+              Object.keys(fieldLabels) as Array<
+                keyof AdminAgcTrackingEventEntry
+              >
+            )
+              .filter((key) => key !== 'properties')
+              .map((key) => (
+                <div key={key}>
+                  <dt>{fieldLabels[key]}</dt>
+                  <dd style={{ overflowWrap: 'anywhere' }}>
+                    {detail[key] == null ? '—' : String(detail[key])}
+                  </dd>
+                </div>
+              ))}
+          </dl>
+          <div className="admin-action-row">
+            {(['creativeTaskId', 'agentRunId', 'clientVersion'] as const).map(
+              (key) =>
+                detail[key] ? (
+                  <button
+                    type="button"
+                    key={key}
+                    className="admin-secondary-button"
+                    onClick={() => related(key, detail[key]!)}
+                  >
+                    查询同一{fieldLabels[key]}
+                  </button>
+                ) : null,
+            )}
+          </div>
+          <h3>事件属性</h3>
+          <pre style={{ whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }}>
+            {JSON.stringify(detail.properties, null, 2)}
+          </pre>
+        </Modal>
+      ) : null}
+    </section>
+  );
+}

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

@@ -2641,48 +2641,6 @@ const databaseTableLabelMap: Record<string, string> = {
   profile_recharge_order: '充值订单',
   profile_feedback_submission: '反馈提交',
   profile_save_archive: '存档记录',
-  story_session: '剧情会话',
-  story_event: '剧情事件',
-  npc_state: 'NPC 状态',
-  inventory_slot: '背包槽位',
-  battle_state: '战斗状态',
-  treasure_record: '宝藏记录',
-  quest_record: '任务记录',
-  quest_log: '任务日志',
-  player_progression: '玩家进度',
-  chapter_progression: '章节进度',
-  custom_world_profile: '自定义世界档案',
-  custom_world_session: '自定义世界会话',
-  custom_world_agent_session: '自定义世界 Agent 会话',
-  custom_world_agent_message: '自定义世界 Agent 消息',
-  custom_world_agent_operation: '自定义世界 Agent 操作',
-  custom_world_draft_card: '自定义世界草稿卡片',
-  custom_world_gallery_entry: '自定义世界画廊条目',
-  puzzle_agent_session: '拼图 Agent 会话',
-  puzzle_agent_message: '拼图 Agent 消息',
-  puzzle_work_profile: '拼图作品档案',
-  puzzle_event: '拼图事件',
-  puzzle_runtime_run: '拼图运行记录',
-  puzzle_leaderboard_entry: '拼图排行榜条目',
-  match3d_agent_session: '抓大鹅 Agent 会话',
-  match3d_agent_message: '抓大鹅 Agent 消息',
-  match3d_work_profile: '抓大鹅作品档案',
-  match3d_runtime_run: '抓大鹅运行记录',
-  square_hole_agent_session: '方洞挑战 Agent 会话',
-  square_hole_agent_message: '方洞挑战 Agent 消息',
-  square_hole_work_profile: '方洞挑战作品档案',
-  square_hole_runtime_run: '方洞挑战运行记录',
-  visual_novel_agent_session: '视觉小说 Agent 会话',
-  visual_novel_agent_message: '视觉小说 Agent 消息',
-  visual_novel_work_profile: '视觉小说作品档案',
-  visual_novel_runtime_run: '视觉小说运行记录',
-  visual_novel_runtime_history_entry: '视觉小说历史条目',
-  visual_novel_runtime_event: '视觉小说运行事件',
-  big_fish_creation_session: '大鱼吃小鱼创建会话',
-  big_fish_agent_message: '大鱼吃小鱼 Agent 消息',
-  big_fish_asset_slot: '大鱼吃小鱼资产槽位',
-  big_fish_event: '大鱼吃小鱼事件',
-  big_fish_runtime_run: '大鱼吃小鱼运行记录',
   asset_object: '资产对象',
   asset_entity_binding: '资产实体绑定',
   asset_event: '资产事件',
@@ -2724,48 +2682,6 @@ const databaseTableDescriptionMap: Record<string, string> = {
   profile_recharge_order: '充值订单表',
   profile_feedback_submission: '反馈提交记录表',
   profile_save_archive: '用户存档记录表',
-  story_session: '剧情会话表',
-  story_event: '剧情事件表',
-  npc_state: 'NPC 状态表',
-  inventory_slot: '背包槽位表',
-  battle_state: '战斗状态表',
-  treasure_record: '宝藏记录表',
-  quest_record: '任务记录表',
-  quest_log: '任务日志表',
-  player_progression: '玩家进度表',
-  chapter_progression: '章节进度表',
-  custom_world_profile: '自定义世界档案表',
-  custom_world_session: '自定义世界会话表',
-  custom_world_agent_session: '自定义世界 Agent 会话表',
-  custom_world_agent_message: '自定义世界 Agent 消息表',
-  custom_world_agent_operation: '自定义世界 Agent 操作表',
-  custom_world_draft_card: '自定义世界草稿卡片表',
-  custom_world_gallery_entry: '自定义世界画廊条目表',
-  puzzle_agent_session: '拼图 Agent 会话表',
-  puzzle_agent_message: '拼图 Agent 消息表',
-  puzzle_work_profile: '拼图作品档案表',
-  puzzle_event: '拼图事件表',
-  puzzle_runtime_run: '拼图运行记录表',
-  puzzle_leaderboard_entry: '拼图排行榜条目表',
-  match3d_agent_session: '抓大鹅 Agent 会话表',
-  match3d_agent_message: '抓大鹅 Agent 消息表',
-  match3d_work_profile: '抓大鹅作品档案表',
-  match3d_runtime_run: '抓大鹅运行记录表',
-  square_hole_agent_session: '方洞挑战 Agent 会话表',
-  square_hole_agent_message: '方洞挑战 Agent 消息表',
-  square_hole_work_profile: '方洞挑战作品档案表',
-  square_hole_runtime_run: '方洞挑战运行记录表',
-  visual_novel_agent_session: '视觉小说 Agent 会话表',
-  visual_novel_agent_message: '视觉小说 Agent 消息表',
-  visual_novel_work_profile: '视觉小说作品档案表',
-  visual_novel_runtime_run: '视觉小说运行记录表',
-  visual_novel_runtime_history_entry: '视觉小说历史条目表',
-  visual_novel_runtime_event: '视觉小说运行事件表',
-  big_fish_creation_session: '大鱼吃小鱼创建会话表',
-  big_fish_agent_message: '大鱼吃小鱼 Agent 消息表',
-  big_fish_asset_slot: '大鱼吃小鱼资产槽位表',
-  big_fish_event: '大鱼吃小鱼事件表',
-  big_fish_runtime_run: '大鱼吃小鱼运行记录表',
   asset_object: '资产对象表',
   asset_entity_binding: '资产实体绑定表',
   asset_event: '资产事件表',

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

@@ -0,0 +1,186 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  listAdminGameDistributionReviews,
+  reviewAdminGameDistributionVersion,
+  suspendAdminGameDistributionGame,
+} from '../api/adminApiClient';
+import type { AdminGameDistributionReviewEntry } from '../api/adminApiTypes';
+import {
+  AdminGameDistributionReviewPage,
+  resolveGameReleaseEntryUrlError,
+} from './AdminGameDistributionReviewPage';
+
+vi.mock('../api/adminApiClient', () => ({
+  isAdminApiError: vi.fn(
+    (error: unknown) =>
+      typeof error === 'object' &&
+      error !== null &&
+      'status' in error &&
+      typeof error.status === 'number',
+  ),
+  formatAdminApiError: vi.fn((error: unknown) =>
+    error instanceof Error ? error.message : '请求失败',
+  ),
+  listAdminGameDistributionReviews: vi.fn(),
+  reviewAdminGameDistributionVersion: vi.fn(),
+  suspendAdminGameDistributionGame: vi.fn(),
+}));
+
+const entry: AdminGameDistributionReviewEntry = {
+  versionId: 'version-1',
+  gameId: 'game_1',
+  versionNumber: 2,
+  packageSha256: 'a'.repeat(64),
+  packageBytes: 2048,
+  status: 'pending_review',
+  publicationRevision: 4,
+  reviewReason: null,
+  createdAt: '2026-09-20T08:00:00Z',
+  updatedAt: '2026-09-20T08:00:00Z',
+};
+
+beforeEach(() => {
+  vi.mocked(listAdminGameDistributionReviews).mockReset();
+  vi.mocked(reviewAdminGameDistributionVersion).mockReset();
+  vi.mocked(suspendAdminGameDistributionGame).mockReset();
+  vi.mocked(listAdminGameDistributionReviews).mockResolvedValue({
+    entries: [entry],
+    nextCursor: null,
+  });
+});
+
+test('发行入口必须是带完整来源的 HTTPS 地址', () => {
+  expect(resolveGameReleaseEntryUrlError('')).toBe('请填写发行入口');
+  expect(
+    resolveGameReleaseEntryUrlError('http://games.test/a/index.html'),
+  ).toBe('发行入口必须以 https:// 开头');
+  expect(
+    resolveGameReleaseEntryUrlError('https://games.test/a/index.html?token=1'),
+  ).toBe('发行入口不能包含 query 或 fragment');
+  expect(
+    resolveGameReleaseEntryUrlError('https://u:p@games.test/a/index.html'),
+  ).toBe('发行入口不能包含凭据');
+  expect(
+    resolveGameReleaseEntryUrlError('https://games.test/a/index.html'),
+  ).toBe('');
+});
+
+test('通过审核时提交当前 publicationRevision 与发行入口并刷新列表', async () => {
+  vi.mocked(reviewAdminGameDistributionVersion).mockResolvedValue({
+    version: { ...entry, status: 'published' },
+    replayed: false,
+  });
+
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText('game_1');
+
+  fireEvent.change(screen.getByLabelText('发行入口'), {
+    target: { value: 'https://games.test/releases/game_1/index.html' },
+  });
+  fireEvent.click(screen.getByRole('button', { name: '通过' }));
+
+  await waitFor(() =>
+    expect(reviewAdminGameDistributionVersion).toHaveBeenCalledTimes(1),
+  );
+  const [token, versionId, idempotencyKey, payload] =
+    vi.mocked(reviewAdminGameDistributionVersion).mock.calls[0] ?? [];
+  expect(token).toBe('admin-token');
+  expect(versionId).toBe('version-1');
+  expect(String(idempotencyKey)).toContain('version-1');
+  expect(payload).toEqual({
+    decision: 'approve',
+    expectedPublicationRevision: 4,
+    entryUrl: 'https://games.test/releases/game_1/index.html',
+  });
+  await waitFor(() =>
+    expect(vi.mocked(listAdminGameDistributionReviews)).toHaveBeenCalledTimes(
+      2,
+    ),
+  );
+});
+
+test('缺少拒绝理由时不调用审核接口', async () => {
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText('game_1');
+
+  fireEvent.click(screen.getByRole('button', { name: '拒绝' }));
+
+  expect(await screen.findByText('拒绝审核必须填写理由')).toBeTruthy();
+  expect(reviewAdminGameDistributionVersion).not.toHaveBeenCalled();
+});
+
+test('安全下架需要二次确认，并携带公开修订号与原因', async () => {
+  vi.mocked(suspendAdminGameDistributionGame).mockResolvedValue({
+    game: {
+      id: 'game_1',
+      title: '测试游戏',
+      status: 'suspended',
+      publicationRevision: 5,
+    },
+    replayed: false,
+  });
+
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText('game_1');
+
+  fireEvent.change(screen.getByLabelText('下架原因'), {
+    target: { value: '盗用素材' },
+  });
+  fireEvent.click(screen.getByRole('button', { name: '安全下架' }));
+
+  // 第一次点击只弹出确认面板，不直接调用后端。
+  expect(suspendAdminGameDistributionGame).not.toHaveBeenCalled();
+  expect(await screen.findByRole('dialog')).toBeTruthy();
+
+  fireEvent.click(screen.getByRole('button', { name: '确认' }));
+
+  await waitFor(() =>
+    expect(suspendAdminGameDistributionGame).toHaveBeenCalledTimes(1),
+  );
+  const [token, gameId, idempotencyKey, payload] =
+    vi.mocked(suspendAdminGameDistributionGame).mock.calls[0] ?? [];
+  expect(token).toBe('admin-token');
+  expect(gameId).toBe('game_1');
+  expect(String(idempotencyKey)).toContain('game_1');
+  expect(payload).toEqual({
+    expectedPublicationRevision: 4,
+    reason: '盗用素材',
+  });
+  expect(await screen.findByText(/已安全下架/u)).toBeTruthy();
+});
+
+test('取消确认时不下架', async () => {
+  render(
+    <AdminGameDistributionReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+  await screen.findByText('game_1');
+
+  fireEvent.click(screen.getByRole('button', { name: '安全下架' }));
+  await screen.findByRole('dialog');
+  fireEvent.click(screen.getByRole('button', { name: '取消' }));
+
+  await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+  expect(suspendAdminGameDistributionGame).not.toHaveBeenCalled();
+});

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

@@ -0,0 +1,365 @@
+import { RefreshCcw } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+
+import {
+  listAdminGameDistributionReviews,
+  reviewAdminGameDistributionVersion,
+  suspendAdminGameDistributionGame,
+} from '../api/adminApiClient';
+import type { AdminGameDistributionReviewEntry } from '../api/adminApiTypes';
+import { useAdminWriteConfirm } from '../components/useAdminWriteConfirm';
+import { handlePageError } from './pageUtils';
+
+interface AdminGameDistributionReviewPageProps {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}
+
+function formatBytes(value: number) {
+  if (value >= 1024 * 1024) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
+  }
+  if (value >= 1024) {
+    return `${(value / 1024).toFixed(1)} KiB`;
+  }
+  return `${value} B`;
+}
+
+function formatTime(value: string) {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return value;
+  return parsed.toLocaleString('zh-CN', { hour12: false });
+}
+
+function createSuspendIdempotencyKey(gameId: string) {
+  const random =
+    typeof crypto !== 'undefined' && 'randomUUID' in crypto
+      ? crypto.randomUUID()
+      : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return `game-suspend-${gameId}-${random}`.slice(0, 128);
+}
+
+function createReviewIdempotencyKey(versionId: string) {
+  const random =
+    typeof crypto !== 'undefined' && 'randomUUID' in crypto
+      ? crypto.randomUUID()
+      : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return `game-review-${versionId}-${random}`.slice(0, 128);
+}
+
+export function resolveGameReleaseEntryUrlError(value: string) {
+  const normalized = value.trim();
+  if (!normalized) return '请填写发行入口';
+  if (!normalized.startsWith('https://')) {
+    return '发行入口必须以 https:// 开头';
+  }
+  if (normalized.includes('?') || normalized.includes('#')) {
+    return '发行入口不能包含 query 或 fragment';
+  }
+  try {
+    const parsed = new URL(normalized);
+    if (parsed.username || parsed.password) {
+      return '发行入口不能包含凭据';
+    }
+  } catch {
+    return '发行入口不是合法 URL';
+  }
+  return '';
+}
+
+export function AdminGameDistributionReviewPage({
+  token,
+  onUnauthorized,
+}: AdminGameDistributionReviewPageProps) {
+  const [entries, setEntries] = useState<AdminGameDistributionReviewEntry[]>(
+    [],
+  );
+  const [isLoading, setIsLoading] = useState(false);
+  const [busyVersionId, setBusyVersionId] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+  const [statusMessage, setStatusMessage] = useState('');
+  const [entryUrlByVersion, setEntryUrlByVersion] = useState<
+    Record<string, string>
+  >({});
+  const [reasonByVersion, setReasonByVersion] = useState<
+    Record<string, string>
+  >({});
+  const [suspendReasonByGame, setSuspendReasonByGame] = useState<
+    Record<string, string>
+  >({});
+  const [busyGameId, setBusyGameId] = useState('');
+  const writeConfirm = useAdminWriteConfirm();
+
+  const loadReviews = useCallback(async () => {
+    setIsLoading(true);
+    setErrorMessage('');
+    try {
+      const response = await listAdminGameDistributionReviews(token);
+      setEntries(response.entries);
+    } catch (error) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [token, onUnauthorized]);
+
+  useEffect(() => {
+    void loadReviews();
+  }, [loadReviews]);
+
+  async function submitReview(
+    entry: AdminGameDistributionReviewEntry,
+    decision: 'approve' | 'reject',
+  ) {
+    const entryUrl = (entryUrlByVersion[entry.versionId] ?? '').trim();
+    const reason = (reasonByVersion[entry.versionId] ?? '').trim();
+    if (decision === 'approve') {
+      const invalid = resolveGameReleaseEntryUrlError(entryUrl);
+      if (invalid) {
+        setErrorMessage(invalid);
+        return;
+      }
+    } else if (!reason) {
+      setErrorMessage('拒绝审核必须填写理由');
+      return;
+    }
+    setBusyVersionId(entry.versionId);
+    setErrorMessage('');
+    setStatusMessage('');
+    try {
+      await reviewAdminGameDistributionVersion(
+        token,
+        entry.versionId,
+        createReviewIdempotencyKey(entry.versionId),
+        decision === 'approve'
+          ? {
+              decision,
+              expectedPublicationRevision: entry.publicationRevision,
+              entryUrl,
+            }
+          : {
+              decision,
+              expectedPublicationRevision: entry.publicationRevision,
+              reviewReason: reason,
+            },
+      );
+      setStatusMessage(
+        decision === 'approve'
+          ? `版本 v${entry.versionNumber} 已通过审核`
+          : `版本 v${entry.versionNumber} 已拒绝`,
+      );
+      await loadReviews();
+    } catch (error) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setBusyVersionId('');
+    }
+  }
+
+  /**
+   * 管理员安全下架：先二次确认，再带当前公开修订号调用后端；并发审核导致修订号变化时
+   * 由服务端返回冲突，前端只提示刷新，不静默重试。
+   */
+  async function suspendGame(entry: AdminGameDistributionReviewEntry) {
+    const reason = (suspendReasonByGame[entry.gameId] ?? '').trim();
+    const confirmed = await writeConfirm.confirmWrite({
+      action: '安全下架游戏',
+      target: `${entry.gameId}（版本 v${entry.versionNumber}）`,
+    });
+    if (!confirmed) return;
+    setBusyGameId(entry.gameId);
+    setErrorMessage('');
+    setStatusMessage('');
+    try {
+      await suspendAdminGameDistributionGame(
+        token,
+        entry.gameId,
+        createSuspendIdempotencyKey(entry.gameId),
+        {
+          expectedPublicationRevision: entry.publicationRevision,
+          ...(reason ? { reason } : {}),
+        },
+      );
+      setStatusMessage(`游戏 ${entry.gameId} 已安全下架，发行入口已关闭`);
+      setSuspendReasonByGame((current) => ({ ...current, [entry.gameId]: '' }));
+      await loadReviews();
+    } catch (error) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setBusyGameId('');
+    }
+  }
+
+  return (
+    <section className="admin-page admin-page-wide">
+      <div className="admin-page-heading">
+        <h1>游戏审核</h1>
+        <button
+          type="button"
+          className="admin-secondary-button"
+          onClick={() => void loadReviews()}
+          disabled={isLoading}
+        >
+          <RefreshCcw aria-hidden="true" />
+          刷新
+        </button>
+      </div>
+
+      {errorMessage ? (
+        <div className="admin-alert admin-alert-warning" role="alert">
+          {errorMessage}
+        </div>
+      ) : null}
+      {statusMessage ? (
+        <div className="admin-alert admin-alert-success" role="status">
+          {statusMessage}
+        </div>
+      ) : null}
+
+      <div className="admin-panel">
+        <div className="admin-panel-heading">
+          <h2>待审版本</h2>
+          <span className="admin-muted-text">共 {entries.length} 条</span>
+        </div>
+
+        {isLoading ? (
+          <p className="admin-muted-text">正在加载待审版本…</p>
+        ) : null}
+
+        {!isLoading && entries.length === 0 ? (
+          <p className="admin-muted-text">当前没有待审核的游戏版本。</p>
+        ) : null}
+
+        {!isLoading && entries.length > 0 ? (
+          <div className="admin-table-wrap">
+            <table className="admin-table admin-table-wide">
+              <thead>
+                <tr>
+                  <th>游戏</th>
+                  <th>版本</th>
+                  <th>发行包</th>
+                  <th>提交时间</th>
+                  <th>审核</th>
+                </tr>
+              </thead>
+              <tbody>
+                {entries.map((entry) => {
+                  const busy = busyVersionId === entry.versionId;
+                  return (
+                    <tr key={entry.versionId}>
+                      <td>
+                        <code>{entry.gameId}</code>
+                      </td>
+                      <td>
+                        v{entry.versionNumber}
+                        <div className="admin-muted-text">{entry.status}</div>
+                        {entry.reviewReason ? (
+                          <div className="admin-muted-text">
+                            {entry.reviewReason}
+                          </div>
+                        ) : null}
+                      </td>
+                      <td>
+                        {formatBytes(entry.packageBytes)}
+                        <div className="admin-muted-text">
+                          <code>{entry.packageSha256.slice(0, 12)}</code>
+                        </div>
+                      </td>
+                      <td>{formatTime(entry.createdAt)}</td>
+                      <td>
+                        <div className="admin-action-row">
+                          <div className="admin-field">
+                            <label
+                              htmlFor={`game-release-url-${entry.versionId}`}
+                            >
+                              发行入口
+                            </label>
+                            <input
+                              id={`game-release-url-${entry.versionId}`}
+                              value={entryUrlByVersion[entry.versionId] ?? ''}
+                              placeholder="https://"
+                              onChange={(event) =>
+                                setEntryUrlByVersion((current) => ({
+                                  ...current,
+                                  [entry.versionId]: event.target.value,
+                                }))
+                              }
+                              disabled={busy}
+                            />
+                          </div>
+                          <button
+                            type="button"
+                            className="admin-primary-button"
+                            disabled={busy}
+                            onClick={() => void submitReview(entry, 'approve')}
+                          >
+                            通过
+                          </button>
+                          <div className="admin-field">
+                            <label
+                              htmlFor={`game-reject-reason-${entry.versionId}`}
+                            >
+                              拒绝理由
+                            </label>
+                            <input
+                              id={`game-reject-reason-${entry.versionId}`}
+                              value={reasonByVersion[entry.versionId] ?? ''}
+                              onChange={(event) =>
+                                setReasonByVersion((current) => ({
+                                  ...current,
+                                  [entry.versionId]: event.target.value,
+                                }))
+                              }
+                              disabled={busy}
+                            />
+                          </div>
+                          <button
+                            type="button"
+                            className="admin-ghost-button"
+                            disabled={busy}
+                            onClick={() => void submitReview(entry, 'reject')}
+                          >
+                            拒绝
+                          </button>
+                          <div className="admin-field">
+                            <label
+                              htmlFor={`game-suspend-reason-${entry.versionId}`}
+                            >
+                              下架原因
+                            </label>
+                            <input
+                              id={`game-suspend-reason-${entry.versionId}`}
+                              value={suspendReasonByGame[entry.gameId] ?? ''}
+                              onChange={(event) =>
+                                setSuspendReasonByGame((current) => ({
+                                  ...current,
+                                  [entry.gameId]: event.target.value,
+                                }))
+                              }
+                              disabled={busy}
+                            />
+                          </div>
+                          <button
+                            type="button"
+                            className="admin-danger-button"
+                            disabled={busy || busyGameId === entry.gameId}
+                            onClick={() => void suspendGame(entry)}
+                          >
+                            {busyGameId === entry.gameId
+                              ? '正在下架…'
+                              : '安全下架'}
+                          </button>
+                        </div>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+        ) : null}
+      </div>
+      {writeConfirm.confirmDialog}
+    </section>
+  );
+}

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

@@ -175,6 +175,107 @@ test('灰度发布页可选择模板库并默认启用零比例灰度', 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 前缀'), [
+    'game-distribution',
+  ]);
+
+  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
+    'game-distribution:publish',
+  );
+  expect(
+    (screen.getByLabelText('Gate Key 目标') as HTMLSelectElement).value,
+  ).toBe('publish');
+  // 该开关的语义是「未配置/关闭 = 默认开放」，所以选中后不能默认打开收紧。
+  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
+    false,
+  );
+  expect((screen.getByLabelText('灰度比例') as HTMLInputElement).value).toBe(
+    '0',
+  );
+  expect(
+    (screen.getByLabelText('描述') as HTMLTextAreaElement).value,
+  ).toContain('游戏发布入口灰度');
+});
+
+test('灰度发布页保存游戏发布开关时写入白名单与比例', async () => {
+  const user = userEvent.setup();
+  vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({
+    gates: [
+      ...configResponse.gates,
+      {
+        gateKey: 'game-distribution:publish',
+        enabled: true,
+        rolloutPercent: 20,
+        allowUserIds: ['user-internal'],
+        allowUserTags: [],
+        denyUserIds: [],
+        description: '游戏发布入口灰度',
+        updatedAt: '2026-09-22T10:00:00Z',
+      },
+    ],
+  });
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  await screen.findByRole('button', { name: 'editor.new-toolbar' });
+  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), [
+    'game-distribution',
+  ]);
+  fireEvent.click(screen.getByLabelText('启用'));
+  fireEvent.change(screen.getByLabelText('灰度比例'), {
+    target: { value: '20' },
+  });
+  fireEvent.change(screen.getByLabelText('允许用户 ID'), {
+    target: { value: 'user-internal' },
+  });
+  fireEvent.change(screen.getByLabelText('描述'), {
+    target: { value: '游戏发布入口灰度' },
+  });
+  await user.click(screen.getByRole('button', { name: '保存配置' }));
+  await user.click(screen.getByRole('button', { name: '确认' }));
+
+  await waitFor(() =>
+    expect(upsertAdminFeatureGateConfig).toHaveBeenCalledWith('admin-token', {
+      gateKey: 'game-distribution:publish',
+      enabled: true,
+      rolloutPercent: 20,
+      allowUserIds: ['user-internal'],
+      allowUserTags: [],
+      denyUserIds: [],
+      description: '游戏发布入口灰度',
+    }),
+  );
+});
+
+test('未创建的预设开关在后台可见并可一键配置', async () => {
+  const user = userEvent.setup();
+  render(
+    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  const row = await screen.findByText('game-distribution:publish');
+  expect(row).not.toBeNull();
+  // 该开关默认未创建：列表里给出「配置」入口，点击后按默认关闭填充表单。
+  const configureButton = row.closest('tr')?.querySelector('button');
+  expect(configureButton).not.toBeNull();
+  await user.click(configureButton!);
+
+  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
+    'game-distribution:publish',
+  );
+  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
+    false,
+  );
+});
+
 test('灰度发布页保存时转换数组和百分比', async () => {
   const user = userEvent.setup();
   vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({

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

@@ -28,6 +28,7 @@ interface GateTargetOption {
 const GATE_PREFIX_LABELS: Record<string, string> = {
   'image-editor': '画布',
   agc: '客户端',
+  'game-distribution': '游戏分发',
 };
 
 const FIXED_GATE_TARGETS: GateTargetOption[] = [
@@ -45,6 +46,14 @@ const FIXED_GATE_TARGETS: GateTargetOption[] = [
     label: 'Agent 侧边栏',
     description: '画布 Agent 入口灰度',
   },
+  {
+    prefix: 'game-distribution',
+    suffix: 'publish',
+    key: 'game-distribution:publish',
+    label: '游戏发布',
+    description:
+      '游戏发布入口灰度：未配置或关闭时对已登录作者默认开放，开启后只放行白名单 / 灰度命中',
+  },
 ];
 
 export function AdminGrayReleaseConfigPage({
@@ -197,6 +206,11 @@ export function AdminGrayReleaseConfigPage({
     setErrorMessage('');
   }
 
+  // 预设里尚未创建行的开关也要可见：运营需要先看到 key 才能配置灰度。
+  const unconfiguredGateTargets = FIXED_GATE_TARGETS.filter(
+    (option) => !gates.some((gate) => gate.gateKey === option.key),
+  );
+
   function buildPayload(): AdminUpsertFeatureGateConfigRequest {
     return {
       gateKey: gateKey.trim(),
@@ -443,6 +457,53 @@ export function AdminGrayReleaseConfigPage({
             </div>
           )}
         </section>
+
+        <section className="admin-panel">
+          <div className="admin-panel-heading">
+            <h3>可配置开关</h3>
+            <span>{unconfiguredGateTargets.length}</span>
+          </div>
+          {unconfiguredGateTargets.length ? (
+            <div className="admin-table-wrap">
+              <table className="admin-table admin-table-compact">
+                <thead>
+                  <tr>
+                    <th>Gate</th>
+                    <th>说明</th>
+                    <th>操作</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {unconfiguredGateTargets.map((option) => (
+                    <tr key={option.key}>
+                      <td>
+                        {option.key}
+                        <small>
+                          {GATE_PREFIX_LABELS[option.prefix] ?? option.prefix} ·{' '}
+                          {option.label}
+                        </small>
+                      </td>
+                      <td>{option.description}</td>
+                      <td>
+                        <button
+                          className="admin-text-button"
+                          type="button"
+                          onClick={() => applyGateTarget(option)}
+                        >
+                          配置
+                        </button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          ) : (
+            <div className="admin-empty-state">
+              {isLoading ? '加载中' : '预设开关都已创建'}
+            </div>
+          )}
+        </section>
       </div>
 
       {confirmDialog}

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

@@ -13,6 +13,7 @@ import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 import {
   AdminApiError,
   downloadAdminProjectSnapshot,
+  getAdminProjectSnapshotChannels,
   listAdminProjectSnapshots,
 } from '../api/adminApiClient';
 import type { AdminProjectSnapshotEntry } from '../api/adminApiTypes';
@@ -23,6 +24,7 @@ vi.mock('../api/adminApiClient', async () => ({
     '../api/adminApiClient',
   )),
   downloadAdminProjectSnapshot: vi.fn(),
+  getAdminProjectSnapshotChannels: vi.fn(),
   listAdminProjectSnapshots: vi.fn(),
 }));
 
@@ -35,12 +37,18 @@ const entry: AdminProjectSnapshotEntry = {
   fileCount: 12,
   totalBytes: 2048,
   status: 'ready',
+  channel: 'dev',
+  authorDisplayName: '陶泥作者',
+  authorPublicUserCode: 'SY-00000007',
 };
 
 beforeEach(() => {
   vi.mocked(listAdminProjectSnapshots)
     .mockReset()
     .mockResolvedValue({ items: [entry], nextCursor: null });
+  vi.mocked(getAdminProjectSnapshotChannels)
+    .mockReset()
+    .mockResolvedValue({ defaultChannel: 'dev', channels: ['dev'] });
   vi.mocked(downloadAdminProjectSnapshot).mockReset();
 });
 afterEach(() => {
@@ -88,36 +96,166 @@ test('按项目展示完整性并限制未完成工程下载', async () => {
   ).toBe(false);
 });
 
-test('加载更多合并项目，刷新失败保留列表和错误，重试从首页开始', async () => {
+test('按游标翻页回到上一页时复用已取得的游标', async () => {
+  vi.mocked(listAdminProjectSnapshots)
+    .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' })
+    .mockResolvedValueOnce({
+      items: [{ ...entry, projectId: 'project-2', projectName: '第二工程' }],
+      nextCursor: 'page-3',
+    })
+    .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('三消工程');
+  const pagination = await screen.findByRole('navigation', {
+    name: '项目工程分页',
+  });
+  expect(pagination.textContent).toContain('第 1 页');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    1,
+    'token',
+    { cursor: null, limit: 20, channel: 'dev' },
+    expect.any(AbortSignal),
+  );
+  expect(
+    screen.getByRole('button', { name: '上一页' }).hasAttribute('disabled'),
+  ).toBe(true);
+
+  fireEvent.click(screen.getByRole('button', { name: '下一页' }));
+  await screen.findByText('第二工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    2,
+    'token',
+    { cursor: 'page-2', limit: 20, channel: 'dev' },
+    expect.any(AbortSignal),
+  );
+  expect(screen.queryByText('三消工程')).toBeNull();
+  expect(pagination.textContent).toContain('第 2 页');
+  expect(
+    screen.getByRole('button', { name: '下一页' }).hasAttribute('disabled'),
+  ).toBe(false);
+
+  fireEvent.click(screen.getByRole('button', { name: '上一页' }));
+  await screen.findByText('三消工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    3,
+    'token',
+    { cursor: null, limit: 20, channel: 'dev' },
+    expect.any(AbortSignal),
+  );
+  expect(pagination.textContent).toContain('第 1 页');
+});
+
+test('切换每页条数从第一页按新条数重新加载', async () => {
+  vi.mocked(listAdminProjectSnapshots)
+    .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' })
+    .mockResolvedValueOnce({
+      items: [{ ...entry, projectId: 'project-2', projectName: '第二工程' }],
+      nextCursor: 'page-3',
+    })
+    .mockResolvedValueOnce({ items: [entry], nextCursor: null });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('三消工程');
+  fireEvent.click(screen.getByRole('button', { name: '下一页' }));
+  await screen.findByText('第二工程');
+  const pagination = screen.getByRole('navigation', { name: '项目工程分页' });
+  expect(pagination.textContent).toContain('第 2 页');
+
+  fireEvent.change(screen.getByLabelText('每页条数'), {
+    target: { value: '50' },
+  });
+  await screen.findByText('三消工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    3,
+    'token',
+    { cursor: null, limit: 50, channel: 'dev' },
+    expect.any(AbortSignal),
+  );
+  // 重新加载时页脚会重建，必须重新取节点再断言。
+  expect(
+    screen.getByRole('navigation', { name: '项目工程分页' }).textContent,
+  ).toContain('第 1 页');
+});
+
+test('刷新重载当前页，翻页失败保留当前页并提示错误', async () => {
   vi.mocked(listAdminProjectSnapshots)
     .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' })
     .mockResolvedValueOnce({
       items: [{ ...entry, projectId: 'project-2', projectName: '第二工程' }],
       nextCursor: null,
     })
-    .mockRejectedValueOnce(new Error('远端清单读取失败'))
+    .mockRejectedValueOnce(new Error('翻页读取失败'));
-    .mockResolvedValueOnce({ items: [], nextCursor: null });
   render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
-  fireEvent.click(await screen.findByRole('button', { name: '加载更多' }));
+  await screen.findByText('三消工程');
+  fireEvent.click(screen.getByRole('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(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
-  expect(screen.queryByText('暂无已上传项目')).toBeNull();
+    3,
-  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
-  await screen.findByText('暂无已上传项目');
-  expect(listAdminProjectSnapshots).toHaveBeenLastCalledWith(
     'token',
-    { cursor: null, limit: 20 },
+    { cursor: 'page-2', limit: 20, channel: 'dev' },
     expect.any(AbortSignal),
   );
+  const pagination = screen.getByRole('navigation', { name: '项目工程分页' });
+  expect(pagination.textContent).toContain('第 2 页');
+  expect(screen.getByText('第二工程')).toBeTruthy();
+  expect(screen.queryByText('暂无已上传项目')).toBeNull();
+
+  vi.mocked(listAdminProjectSnapshots).mockResolvedValueOnce({
+    items: [],
+    nextCursor: null,
+  });
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  await screen.findByText('暂无已上传项目');
+  expect(screen.queryByRole('alert')).toBeNull();
+});
+
+test('用户列与素材查询同口径展示昵称、陶泥号和用户详情入口', async () => {
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  const row = (await screen.findByText('三消工程')).closest('tr')!;
+  expect(within(row).getByText('陶泥作者')).toBeTruthy();
+  expect(within(row).getByText('SY-00000007')).toBeTruthy();
+  expect(
+    within(row).getByRole('button', { name: '查看用户信息' }),
+  ).toBeTruthy();
+  expect(within(row).queryByText('user-1')).toBeNull();
+});
+
+test('默认查询本部署渠道，切换渠道后从第一页按该渠道重新查询', async () => {
+  vi.mocked(getAdminProjectSnapshotChannels).mockResolvedValue({
+    defaultChannel: 'release',
+    channels: ['dev', 'release'],
+  });
+  vi.mocked(listAdminProjectSnapshots)
+    .mockResolvedValueOnce({ items: [entry], nextCursor: 'page-2' })
+    .mockResolvedValueOnce({ items: [entry], nextCursor: null })
+    .mockResolvedValueOnce({
+      items: [{ ...entry, channel: 'dev', projectName: 'dev 工程' }],
+      nextCursor: null,
+    });
+  render(<AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('三消工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    1,
+    'token',
+    { cursor: null, limit: 20, channel: 'release' },
+    expect.any(AbortSignal),
+  );
+  const channelSelect = screen.getByLabelText('项目工程渠道');
+  expect((channelSelect as HTMLSelectElement).value).toBe('release');
+
+  fireEvent.click(screen.getByRole('button', { name: '下一页' }));
+  await screen.findByText('第 2 页，本页 1 个项目');
+  fireEvent.change(channelSelect, { target: { value: 'dev' } });
+  await screen.findByText('dev 工程');
+  expect(listAdminProjectSnapshots).toHaveBeenNthCalledWith(
+    3,
+    'token',
+    { cursor: null, limit: 20, channel: 'dev' },
+    expect.any(AbortSignal),
+  );
+  expect(screen.getByText('第 1 页，本页 1 个项目')).toBeTruthy();
 });
 
 test('下载使用返回的中文文件名，随后释放对象 URL', async () => {
@@ -154,6 +292,7 @@ test('下载使用返回的中文文件名，随后释放对象 URL', async () =
   expect(createObjectURL).toHaveBeenCalledWith(blob);
   expect(downloadAdminProjectSnapshot).toHaveBeenCalledWith(
     'token',
+    'dev',
     'user-1',
     'project-1',
     expect.any(AbortSignal),
@@ -164,7 +303,7 @@ test('下载使用返回的中文文件名，随后释放对象 URL', async () =
 
 test('取消下载中止请求且不显示错误，卸载中止列表请求', async () => {
   vi.mocked(downloadAdminProjectSnapshot).mockImplementation(
-    (_token, _user, _project, signal) =>
+    (_token, _channel, _user, _project, signal) =>
       new Promise((_resolve, reject) => {
         signal?.addEventListener('abort', () =>
           reject(new DOMException('Aborted', 'AbortError')),
@@ -177,7 +316,7 @@ test('取消下载中止请求且不显示错误，卸载中止列表请求', as
   fireEvent.click(await screen.findByRole('button', { name: '下载完整工程' }));
   fireEvent.click(await screen.findByRole('button', { name: '取消下载' }));
   expect(
-    vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[3]?.aborted,
+    vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[4]?.aborted,
   ).toBe(true);
   await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
   vi.mocked(listAdminProjectSnapshots).mockReturnValue(new Promise(() => {}));
@@ -248,6 +387,10 @@ test('更换登录令牌丢弃旧列表和晚返回请求', async () => {
       onUnauthorized={onUnauthorized}
     />,
   );
+  // 渠道确定之后才会发出列表请求，这里等到旧令牌的请求真的在途再换令牌。
+  await waitFor(() =>
+    expect(listAdminProjectSnapshots).toHaveBeenCalledTimes(1),
+  );
   const oldSignal = vi.mocked(listAdminProjectSnapshots).mock.calls[0]?.[2];
   view.rerender(
     <AdminProjectSnapshotsPage
@@ -278,7 +421,7 @@ test('卸载后完成的下载不会创建浏览器文件', async () => {
     <AdminProjectSnapshotsPage token="token" onUnauthorized={vi.fn()} />,
   );
   fireEvent.click(await screen.findByRole('button', { name: '下载完整工程' }));
-  const signal = vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[3];
+  const signal = vi.mocked(downloadAdminProjectSnapshot).mock.calls[0]?.[4];
   view.unmount();
   expect(signal?.aborted).toBe(true);
   await act(async () => {

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

@@ -1,11 +1,19 @@
-import { Download, RefreshCcw, X } from 'lucide-react';
+import {
+  ChevronLeft,
+  ChevronRight,
+  Download,
+  RefreshCcw,
+  X,
+} from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 import {
   downloadAdminProjectSnapshot,
+  getAdminProjectSnapshotChannels,
   listAdminProjectSnapshots,
 } from '../api/adminApiClient';
 import type { AdminProjectSnapshotEntry } from '../api/adminApiTypes';
+import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
 import { handlePageError } from './pageUtils';
 
 interface AdminProjectSnapshotsPageProps {
@@ -31,21 +39,32 @@ const snapshotStatuses = {
   },
 };
 
+const DEFAULT_PAGE_SIZE = 20;
+const PAGE_SIZE_OPTIONS = [20, 50, 100];
+
 export function AdminProjectSnapshotsPage({
   token,
   onUnauthorized,
 }: AdminProjectSnapshotsPageProps) {
   const [items, setItems] = useState<AdminProjectSnapshotEntry[]>([]);
   const [nextCursor, setNextCursor] = useState<string | null>(null);
+  const [pageIndex, setPageIndex] = useState(1);
+  const [pageSize, setPageSize] = useState(DEFAULT_PAGE_SIZE);
+  // null 表示渠道还没确定：先读完可选渠道再发列表请求，避免用错渠道白跑一次。
+  const [channel, setChannel] = useState<string | null>(null);
+  const [channelOptions, setChannelOptions] = useState<string[]>([]);
   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);
+  // 远端按游标分页且不给总数：第 N 页的起始游标只能由前 N-1 页依次返回，
+  // 因此按页记录已取得的游标，翻页只在这些游标之间移动。
+  const pageCursors = useRef<(string | null)[]>([null]);
 
   const loadPage = useCallback(
-    async (cursor: string | null = null) => {
+    async (cursor: string | null, limit: number, page: number) => {
       listController.current?.abort();
       const controller = new AbortController();
       listController.current = controller;
@@ -54,23 +73,16 @@ export function AdminProjectSnapshotsPage({
       try {
         const response = await listAdminProjectSnapshots(
           token,
-          { cursor, limit: 20 },
+          { cursor, limit, channel },
           controller.signal,
         );
         if (controller.signal.aborted) return;
-        setItems((current) => {
+        setItems(response.items);
-          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);
+        setPageIndex(page);
         setHasLoaded(true);
       } catch (error: unknown) {
+        // 翻页或刷新失败时保留当前页，不把已看到的列表换成空表。
         if (!controller.signal.aborted)
           handlePageError(error, onUnauthorized, setErrorMessage);
       } finally {
@@ -80,22 +92,70 @@ export function AdminProjectSnapshotsPage({
         }
       }
     },
-    [token, onUnauthorized],
+    [token, onUnauthorized, channel],
   );
 
   useEffect(() => {
+    // 换令牌或首次进入时取一次可选渠道；已选渠道保持不变，只在还没选时落到本部署渠道。
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        const response = await getAdminProjectSnapshotChannels(
+          token,
+          controller.signal,
+        );
+        if (controller.signal.aborted) return;
+        setChannelOptions(response.channels);
+        setChannel((current) => current ?? response.defaultChannel);
+      } catch (error: unknown) {
+        if (controller.signal.aborted) return;
+        // 渠道列表失败不阻塞查询：不带渠道按本部署渠道查询，并提示失败原因。
+        handlePageError(error, onUnauthorized, setErrorMessage);
+        setChannel((current) => current ?? '');
+      }
+    })();
+    return () => controller.abort();
+  }, [token, onUnauthorized]);
+
+  useEffect(() => {
+    if (channel === null) return undefined;
+    pageCursors.current = [null];
     setItems([]);
     setNextCursor(null);
+    setPageIndex(1);
     setHasLoaded(false);
     setDownloadingKey(null);
-    void loadPage();
+    void loadPage(null, pageSize, 1);
     return () => {
       listController.current?.abort();
       listController.current = null;
       downloadController.current?.abort();
       downloadController.current = null;
     };
-  }, [loadPage]);
+  }, [loadPage, pageSize, channel]);
+
+  function goToNextPage() {
+    if (!nextCursor) return;
+    pageCursors.current[pageIndex] = nextCursor;
+    void loadPage(nextCursor, pageSize, pageIndex + 1);
+  }
+
+  function goToPreviousPage() {
+    if (pageIndex <= 1) return;
+    void loadPage(
+      pageCursors.current[pageIndex - 2] ?? null,
+      pageSize,
+      pageIndex - 1,
+    );
+  }
+
+  function refreshCurrentPage() {
+    void loadPage(
+      pageCursors.current[pageIndex - 1] ?? null,
+      pageSize,
+      pageIndex,
+    );
+  }
 
   async function downloadProject(entry: AdminProjectSnapshotEntry) {
     if (downloadController.current || entry.status === 'partial') return;
@@ -106,6 +166,7 @@ export function AdminProjectSnapshotsPage({
     try {
       const archive = await downloadAdminProjectSnapshot(
         token,
+        channel ?? '',
         entry.userId,
         entry.projectId,
         controller.signal,
@@ -140,19 +201,42 @@ export function AdminProjectSnapshotsPage({
     setDownloadingKey(null);
   }
 
+  // 渠道列表读取失败时至少保留当前渠道，避免选择框空掉后看不出在查哪个渠道。
+  const visibleChannelOptions = channelOptions.length
+    ? channelOptions
+    : channel
+      ? [channel]
+      : [];
+
   return (
     <section className="admin-page admin-page-wide">
       <div className="admin-page-heading">
         <h2>项目工程</h2>
-        <button
+        <div className="admin-action-row">
-          className="admin-secondary-button"
+          <label className="admin-field admin-field-compact">
-          disabled={isLoading}
+            <span>渠道</span>
-          type="button"
+            <select
-          onClick={() => void loadPage()}
+              aria-label="项目工程渠道"
-        >
+              value={channel ?? ''}
-          <RefreshCcw size={17} aria-hidden="true" />
+              onChange={(event) => setChannel(event.target.value)}
-          <span>{isLoading ? '加载中' : '刷新'}</span>
+            >
-        </button>
+              {visibleChannelOptions.map((option) => (
+                <option key={option} value={option}>
+                  {option}
+                </option>
+              ))}
+            </select>
+          </label>
+          <button
+            className="admin-secondary-button"
+            disabled={isLoading}
+            type="button"
+            onClick={refreshCurrentPage}
+          >
+            <RefreshCcw size={17} aria-hidden="true" />
+            <span>{isLoading ? '加载中' : '刷新'}</span>
+          </button>
+        </div>
       </div>
       {errorMessage ? (
         <div className="admin-alert" role="alert">
@@ -169,7 +253,7 @@ export function AdminProjectSnapshotsPage({
             <thead>
               <tr>
                 <th>项目</th>
-                <th>用户 ID</th>
+                <th>用户</th>
                 <th>同步时间</th>
                 <th>文件数</th>
                 <th>体积</th>
@@ -187,7 +271,22 @@ export function AdminProjectSnapshotsPage({
                       <strong>{entry.projectName || entry.projectId}</strong>
                       <small>{entry.projectId}</small>
                     </td>
-                    <td data-label="用户 ID">{entry.userId}</td>
+                    <td data-label="用户">
+                      <div className="admin-inline-identity">
+                        <div>
+                          {projectOwnerDisplayName(entry)}
+                          <small>
+                            {entry.authorPublicUserCode?.trim() || '-'}
+                          </small>
+                        </div>
+                        <AdminUserReferenceButton
+                          token={token}
+                          userId={entry.userId}
+                          publicUserCode={entry.authorPublicUserCode}
+                          onUnauthorized={onUnauthorized}
+                        />
+                      </div>
+                    </td>
                     <td data-label="同步时间">
                       <span>
                         {new Date(entry.syncedAtMs).toLocaleString('zh-CN', {
@@ -239,23 +338,66 @@ export function AdminProjectSnapshotsPage({
         {hasLoaded && items.length === 0 && !errorMessage ? (
           <p className="admin-muted-text">暂无已上传项目</p>
         ) : null}
-        {nextCursor ? (
+        {hasLoaded ? (
-          <div className="admin-action-row">
+          <nav
-            <button
+            className="admin-action-row admin-project-snapshot-pagination"
-              className="admin-secondary-button"
+            aria-label="项目工程分页"
-              disabled={isLoading}
+          >
-              type="button"
+            <span className="admin-project-snapshot-pagination-info">
-              onClick={() => void loadPage(nextCursor)}
+              第 {pageIndex} 页
-            >
+              {items.length ? `，本页 ${items.length} 个项目` : ''}
-              {isLoading ? '加载中' : '加载更多'}
+            </span>
-            </button>
+            <div className="admin-action-row">
-          </div>
+              <label className="admin-field admin-field-compact">
+                <span>每页</span>
+                <select
+                  aria-label="每页条数"
+                  value={pageSize}
+                  onChange={(event) => setPageSize(Number(event.target.value))}
+                >
+                  {PAGE_SIZE_OPTIONS.map((option) => (
+                    <option key={option} value={option}>
+                      {option}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <button
+                aria-label="上一页"
+                className="admin-secondary-button"
+                disabled={isLoading || pageIndex <= 1}
+                title="上一页"
+                type="button"
+                onClick={goToPreviousPage}
+              >
+                <ChevronLeft size={17} aria-hidden="true" />
+                <span>上一页</span>
+              </button>
+              <button
+                aria-label="下一页"
+                className="admin-secondary-button"
+                disabled={isLoading || !nextCursor}
+                title="下一页"
+                type="button"
+                onClick={goToNextPage}
+              >
+                <span>下一页</span>
+                <ChevronRight size={17} aria-hidden="true" />
+              </button>
+            </div>
+          </nav>
         ) : null}
       </section>
     </section>
   );
 }
 
+function projectOwnerDisplayName(entry: AdminProjectSnapshotEntry) {
+  return (
+    entry.authorDisplayName?.trim() || entry.authorPublicUserCode?.trim() || '-'
+  );
+}
+
 function snapshotKey(entry: AdminProjectSnapshotEntry) {
   return `${entry.userId}/${entry.projectId}`;
 }

apps/admin-web/src/pages/adminAgcTemplateUploadModel.test.ts

@@ -0,0 +1,155 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+
+import {
+  attachCoverFiles,
+  buildTemplateImportFormData,
+  deriveTemplateUploadRow,
+  parseTemplateTags,
+  sanitizeTemplateId,
+  TEMPLATE_IMPORT_MAX_BATCH,
+  type TemplateUploadRow,
+  validateTemplateUploadRows,
+} from './adminAgcTemplateUploadModel';
+
+function zipFile(name: string) {
+  return new File([new Uint8Array([0x50, 0x4b, 0x03, 0x04])], name, {
+    type: 'application/zip',
+  });
+}
+
+function coverFile(name: string) {
+  return new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], name, {
+    type: 'image/png',
+  });
+}
+
+function row(zipName: string, patch: Partial<TemplateUploadRow> = {}) {
+  return { ...deriveTemplateUploadRow(zipFile(zipName)), ...patch };
+}
+
+describe('sanitizeTemplateId', () => {
+  it('lowercases, keeps whitelisted characters and drops traversal', () => {
+    expect(sanitizeTemplateId('Cocos Empty 2D.zip')).toBe('cocos-empty-2d');
+    expect(sanitizeTemplateId('../../evil.zip')).toBe('evil');
+    expect(sanitizeTemplateId('a..b.zip')).toBe('a.b');
+    expect(sanitizeTemplateId('__hidden__')).toBe('hidden__');
+    expect(sanitizeTemplateId(`${'x'.repeat(90)}.zip`)).toHaveLength(64);
+  });
+});
+
+describe('deriveTemplateUploadRow', () => {
+  it('starts from safe defaults so a batch only needs covers attached', () => {
+    const derived = row('my-template.zip');
+    expect(derived.id).toBe('my-template');
+    expect(derived.title).toBe('my-template');
+    expect(derived.runtime).toBe('html');
+    expect(derived.templateVersion).toBe('0.1.0');
+    expect(derived.entry).toBe('index.html');
+    expect(derived.coverFile).toBeNull();
+  });
+});
+
+describe('attachCoverFiles', () => {
+  it('matches covers by template id and ignores non-image files', () => {
+    const rows = [row('alpha.zip'), row('beta.zip')];
+    const covers = [
+      coverFile('alpha.png'),
+      coverFile('beta.webp'),
+      coverFile('notes.txt'),
+    ];
+
+    const next = attachCoverFiles(rows, covers);
+
+    expect(next[0]?.coverFile?.name).toBe('alpha.png');
+    expect(next[1]?.coverFile?.name).toBe('beta.webp');
+  });
+
+  it('keeps an already matched cover when the new selection has no partner', () => {
+    const rows = [row('alpha.zip', { coverFile: coverFile('alpha.png') })];
+    const next = attachCoverFiles(rows, [coverFile('other.png')]);
+    expect(next[0]?.coverFile?.name).toBe('alpha.png');
+  });
+});
+
+describe('validateTemplateUploadRows', () => {
+  it('accepts a complete batch', () => {
+    const rows = [
+      row('alpha.zip', { coverFile: coverFile('alpha.png') }),
+      row('beta.zip', { coverFile: coverFile('beta.png'), runtime: 'cocos' }),
+    ];
+    expect(validateTemplateUploadRows(rows)).toEqual({});
+  });
+
+  it('reports missing cover, duplicate id and invalid fields per row', () => {
+    const rows = [
+      row('alpha.zip'),
+      row('alpha.zip', { coverFile: coverFile('alpha.png'), key: 'second' }),
+      row('gamma.zip', {
+        coverFile: coverFile('gamma.png'),
+        runtime: 'docker',
+        templateVersion: 'Bad Version',
+        entry: '../escape.js',
+        title: '   ',
+      }),
+    ];
+    const errors = validateTemplateUploadRows(rows);
+    expect(errors['alpha.zip']).toContain('缺少封面');
+    expect(errors.second).toContain('ID 在本批次内重复');
+    expect(errors['gamma.zip']).toContain('名称必须是 1-80 个字符');
+  });
+
+  it('rejects a batch larger than the server limit', () => {
+    const rows = Array.from(
+      { length: TEMPLATE_IMPORT_MAX_BATCH + 1 },
+      (_, index) =>
+        row(`template-${index}.zip`, {
+          coverFile: coverFile(`template-${index}.png`),
+        }),
+    );
+    const errors = validateTemplateUploadRows(rows);
+    expect(Object.keys(errors)).toHaveLength(TEMPLATE_IMPORT_MAX_BATCH + 1);
+    expect(errors['template-0.zip']).toContain('单批最多上传');
+  });
+});
+
+describe('buildTemplateImportFormData', () => {
+  it('writes manifest field names and attaches zip / cover per row', () => {
+    const rows = [
+      row('alpha.zip', {
+        coverFile: coverFile('alpha.png'),
+        tags: '起步, 起步 2d',
+        title: ' Alpha ',
+      }),
+      row('beta.zip', { coverFile: coverFile('beta.png') }),
+    ];
+
+    const form = buildTemplateImportFormData('a'.repeat(64), rows);
+    const manifest = JSON.parse(String(form.get('manifest')));
+
+    expect(manifest.expectedRevision).toBe('a'.repeat(64));
+    expect(manifest.templates).toHaveLength(2);
+    expect(manifest.templates[0]).toMatchObject({
+      id: 'alpha',
+      title: 'Alpha',
+      tags: ['起步', '2d'],
+      zipField: 'zip_0',
+      coverField: 'cover_0',
+    });
+    expect(manifest.templates[1]).toMatchObject({
+      id: 'beta',
+      zipField: 'zip_1',
+      coverField: 'cover_1',
+    });
+    expect((form.get('zip_0') as File).name).toBe('alpha.zip');
+    expect((form.get('cover_1') as File).name).toBe('beta.png');
+  });
+
+  it('parses tags with dedupe and caps them at the server limit', () => {
+    expect(parseTemplateTags(' a, a，b  c ')).toEqual(['a', 'b', 'c']);
+    const many = Array.from({ length: 20 }, (_, index) => `t${index}`).join(
+      ',',
+    );
+    expect(parseTemplateTags(many)).toHaveLength(16);
+  });
+});