diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index 8a4b2d0c6..6368883c8 100644
--- a/.eslintrc.cjs
+++ b/.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',
diff --git a/.gitea/workflows/project-ci.yml b/.gitea/workflows/project-ci.yml
index 78f48200b..8338196cf 100644
--- a/.gitea/workflows/project-ci.yml
+++ b/.gitea/workflows/project-ci.yml
@@ -98,6 +98,12 @@ jobs:
       - 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
@@ -129,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:
@@ -167,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
@@ -268,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
@@ -341,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
 
@@ -353,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:
@@ -395,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
@@ -485,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
 
diff --git a/CONTEXT.md b/CONTEXT.md
index 724d95de3..59acab2ff 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -194,6 +194,34 @@ _Avoid_: 进度通知、快照轮询、第二套历史
 把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
 _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 
+**引用候选**:
+输入区可以命中的对象集合（`@` 素材、`$` Skill），由宿主按种类注入；输入区不判断候选属于哪一类。
+_Avoid_: 输入区自己读项目清单或应用目录、把候选取值写死在组件里
+
+**引用 provider**:
+一种引用种类向输入区提供的全部能力：触发符、候选、身份解析与正文文本形态；每种引用各一份，宿主按需选择性注入。
+_Avoid_: 一个总装对象决定所有种类、输入区按种类分叉、provider 之间互相知道对方
+
+**静默 provider**:
+不提供候选、只负责已有引用身份与文本形态的 provider；附件与运行画面区域属于这一类，只能由外部插入或草稿回填进入正文。
+_Avoid_: 给附件或运行画面区域造候选、为它们保留输入区内的专门分支
+
+**引用文本语法**:
+引用在正文文本里的形态（`@显示名` / `$名称` / `@附件名`）及其反解析；出站与解析必须同一口径，token 前后各留一个空白。
+_Avoid_: 出站与解析各写一套、在空白边界之外再补兼容别名、让解析依赖具体种类的字段
+
+**引用输入区**:
+只负责编辑与渲染引用的共享输入组件；候选、身份解析与文本语法都来自注入的 provider，它不持有项目清单、不访问后端。
+_Avoid_: 输入区自己拉 Skill 目录、把选择器面板塞在输入区内部
+
+**引用选择器**:
+宿主渲染的独立面板，自己拿数据与筛选状态，确认后把选中的引用交给输入区的插入缝。
+_Avoid_: 输入区自带面板、每个宿主各画一个、绕开插入缝另开第二条通道
+
+**附件芯片**:
+聊天附件在正文里的唯一表示；附件导入成功即以芯片进入正文，正文之外不存在第二份附件状态。
+_Avoid_: 待发送附件列表与正文芯片并存、提交时再拼一遍附件
+
 ## Relationships
 
 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -209,6 +237,10 @@ _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 - **个人历史成绩** 由最近记录列表和个人最佳摘要组成，只允许本人查看；排行榜只公开入榜胜利成绩。
 - **正式作品入口闭环** 必须覆盖创作入口、作品详情 CTA、广场/作品卡片、我的作品/个人作品架、稳定作品 ID runtime 路由和 `work_play_start` 埋点。
 - **Phase 2 实施顺序** 固定为：契约与领域规则 → SpacetimeDB 表/reducer 与 api-server BFF → 最小前端纵切 → 投影与列表体验 → 收口验证。
+- **引用输入区** 由宿主注入的若干 **引用 provider** 组成；**引用候选** 与 **引用文本语法** 都来自 provider，输入区不判断引用种类。
+- **引用选择器** 不属于 **引用输入区**：它自己拿数据，确认后只通过输入区的插入缝交付引用。
+- 只有带触发符的 **引用 provider** 会产生候选；**静默 provider** 没有触发符，只能由外部插入或草稿回填进入正文。
+- **附件芯片** 是本轮附件的唯一事实源；附件导入失败时不产生芯片。
 
 ## Example dialogue
 
diff --git a/apps/admin-web/src/api/adminApiClient.test.ts b/apps/admin-web/src/api/adminApiClient.test.ts
index cf1cbc31e..05cfdc10e 100644
--- a/apps/admin-web/src/api/adminApiClient.test.ts
+++ b/apps/admin-web/src/api/adminApiClient.test.ts
@@ -8,9 +8,12 @@ import {
   getAdminUserDetail,
   importAdminAgcTemplates,
   listAdminAgcTrackingEvents,
+  listAdminGameDistributionReviews,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
   resolveAdminRechargeRefundManualReview,
+  reviewAdminGameDistributionVersion,
+  suspendAdminGameDistributionGame,
   updateAdminAccount,
   updateAdminAgcTemplate,
   uploadAdminEditorShowcaseCampaignImage,
@@ -479,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);
+});
diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts
index aedc6352c..da313c68b 100644
--- a/apps/admin-web/src/api/adminApiClient.ts
+++ b/apps/admin-web/src/api/adminApiClient.ts
@@ -32,6 +32,9 @@ import type {
   AdminExternalApiKeyListQuery,
   AdminExternalApiKeyListResponse,
   AdminFeatureGateConfigResponse,
+  AdminGameDistributionReviewListResponse,
+  AdminGameDistributionReviewRequest,
+  AdminGameDistributionReviewResponse,
   AdminImportAgcTemplatesResponse,
   AdminLoginResponse,
   AdminMeResponse,
@@ -1227,6 +1230,75 @@ export function saveAgcModelCatalog(
   );
 }
 
+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,
diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts
index b7a0c6229..71159500c 100644
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -1081,6 +1081,51 @@ export interface AdminAgcModelCatalog {
   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;
diff --git a/apps/admin-web/src/app/AdminApp.tsx b/apps/admin-web/src/app/AdminApp.tsx
index ecc003727..73b48d326 100644
--- a/apps/admin-web/src/app/AdminApp.tsx
+++ b/apps/admin-web/src/app/AdminApp.tsx
@@ -28,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';
@@ -314,6 +315,12 @@ export function AdminApp() {
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {activeRouteId === 'game-distribution' ? (
+        <AdminGameDistributionReviewPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-assets' ? (
         <AdminEditorAssetQueryPage
           token={token}
diff --git a/apps/admin-web/src/app/AdminShell.tsx b/apps/admin-web/src/app/AdminShell.tsx
index b288d7216..83be06884 100644
--- a/apps/admin-web/src/app/AdminShell.tsx
+++ b/apps/admin-web/src/app/AdminShell.tsx
@@ -5,6 +5,7 @@ import {
   Coins,
   Database,
   FolderArchive,
+  Gamepad2,
   GitBranch,
   Images,
   LayoutDashboard,
@@ -50,6 +51,7 @@ const routeIcons = {
   'recharge-orders': ReceiptText,
   'editor-generation-pricing': Coins,
   'editor-showcase': Star,
+  'game-distribution': Gamepad2,
   'editor-assets': Images,
   'project-snapshots': FolderArchive,
   accounts: Users,
diff --git a/apps/admin-web/src/app/adminRoutes.test.ts b/apps/admin-web/src/app/adminRoutes.test.ts
index 13275b30b..30b7c46e3 100644
--- a/apps/admin-web/src/app/adminRoutes.test.ts
+++ b/apps/admin-web/src/app/adminRoutes.test.ts
@@ -164,6 +164,27 @@ 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',
diff --git a/apps/admin-web/src/app/adminRoutes.ts b/apps/admin-web/src/app/adminRoutes.ts
index db1478310..46aa13750 100644
--- a/apps/admin-web/src/app/adminRoutes.ts
+++ b/apps/admin-web/src/app/adminRoutes.ts
@@ -16,6 +16,7 @@ export type AdminRouteId =
   | 'recharge-orders'
   | 'editor-generation-pricing'
   | 'editor-showcase'
+  | 'game-distribution'
   | 'editor-assets'
   | 'project-snapshots'
   | 'agc-models'
@@ -58,6 +59,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
   { 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 },
diff --git a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx
new file mode 100644
index 000000000..ae00212d9
--- /dev/null
+++ b/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();
+});
diff --git a/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx b/apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx
new file mode 100644
index 000000000..b1e993ed7
--- /dev/null
+++ b/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>
+  );
+}
diff --git a/apps/ai-game-creator-shell/scripts/build-release.mjs b/apps/ai-game-creator-shell/scripts/build-release.mjs
index bd1d5907b..742e4f8d1 100644
--- a/apps/ai-game-creator-shell/scripts/build-release.mjs
+++ b/apps/ai-game-creator-shell/scripts/build-release.mjs
@@ -648,6 +648,32 @@ function readHeadCommit() {
   }
 }
 
+/**
+ * Git 的 %s 会把「标题后紧接说明行、没有空行」的整个首段拼成一行；
+ * 更新摘要只允许展示原始提交消息的第一行，避免把说明暴露给用户。
+ */
+function commitMessageTitle(message) {
+  return String(message ?? '')
+    .split(/\r?\n/u, 1)[0]
+    .trim();
+}
+
+/** 解析 `git log -z --format=%h%x09%B`，只保留每个 commit 的消息首行。 */
+function parseReleaseCommitLog(output) {
+  return output
+    .split('\0')
+    .map((record) => record.trimEnd())
+    .filter(Boolean)
+    .map((record) => {
+      const separator = record.indexOf('\t');
+      if (separator < 0) return null;
+      const sha = record.slice(0, separator);
+      const subject = commitMessageTitle(record.slice(separator + 1));
+      return sha && subject ? { sha, subject } : null;
+    })
+    .filter(Boolean);
+}
+
 /**
  * 上一次发布到本次之间的客户端相关提交。
  *
@@ -675,8 +701,9 @@ export function collectReleaseCommits(
       'git',
       [
         'log',
+        '-z',
         '--no-merges',
-        '--format=%h%x09%s',
+        '--format=%h%x09%B',
         `${previousCommit}..${headCommit}`,
         '--',
         ...paths,
@@ -686,28 +713,22 @@ export function collectReleaseCommits(
   } catch {
     return null;
   }
-  return output
-    .split(/\r?\n/u)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => {
-      const [sha = '', ...subject] = line.split('\t');
-      return { sha, subject: subject.join('\t') };
-    });
+  return parseReleaseCommitLog(output);
 }
 
-/** 自动更新摘要：逐条列客户端相关改动，超过上限时折叠并整体截断。 */
+/** 自动更新摘要：逐条列客户端相关改动标题，超过上限时折叠并整体截断。 */
 export function formatReleaseNotes(
   commits,
   { limit = 12, subjectLength = 80, maxLength = 900 } = {},
 ) {
   if (!commits || commits.length === 0) return '';
-  const lines = commits.slice(0, limit).map(({ sha, subject }) => {
+  const lines = commits.slice(0, limit).map(({ subject }) => {
+    const title = commitMessageTitle(subject);
     const trimmed =
-      subject.length > subjectLength
-        ? `${subject.slice(0, subjectLength - 1)}…`
-        : subject;
-    return `- ${trimmed}（${sha}）`;
+      title.length > subjectLength
+        ? `${title.slice(0, subjectLength - 1)}…`
+        : title;
+    return `- ${trimmed}`;
   });
   if (commits.length > limit) {
     lines.push(`- 其余 ${commits.length - limit} 项客户端改动省略`);
@@ -726,20 +747,21 @@ export function collectRecentReleaseCommits({
   try {
     output = execFileSync(
       'git',
-      ['log', '--no-merges', `-n${limit}`, '--format=%h%x09%s', '--', ...paths],
+      [
+        'log',
+        '-z',
+        '--no-merges',
+        `-n${limit}`,
+        '--format=%h%x09%B',
+        '--',
+        ...paths,
+      ],
       { cwd, encoding: 'utf8' },
     );
   } catch {
     return null;
   }
-  const commits = output
-    .split(/\r?\n/u)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => {
-      const [sha = '', ...subject] = line.split('\t');
-      return { sha, subject: subject.join('\t') };
-    });
+  const commits = parseReleaseCommitLog(output);
   return commits.length > 0 ? commits : null;
 }
 
diff --git a/apps/ai-game-creator-shell/scripts/build-release.test.mjs b/apps/ai-game-creator-shell/scripts/build-release.test.mjs
index 848b74692..427166456 100644
--- a/apps/ai-game-creator-shell/scripts/build-release.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/build-release.test.mjs
@@ -645,17 +645,19 @@ test('Windows remains the default and explicit Windows overrides macOS environme
 
 test('no-bundle smoke skips version writes and manifest generation', async () => {
   const steps = [];
-  await buildRelease(['--no-bundle', '--target=aarch64-apple-darwin'], {
-    prepareVersion: () => {
-      steps.push('version');
-    },
-    build: (_args, context) => {
-      steps.push(context.channel);
-    },
-    generateManifest: () => {
-      steps.push('manifest');
-    },
-  });
+  await withEnv({ AGC_UPDATE_CHANNEL: undefined }, () =>
+    buildRelease(['--no-bundle', '--target=aarch64-apple-darwin'], {
+      prepareVersion: () => {
+        steps.push('version');
+      },
+      build: (_args, context) => {
+        steps.push(context.channel);
+      },
+      generateManifest: () => {
+        steps.push('manifest');
+      },
+    }),
+  );
   assert.deepEqual(steps, ['dev']);
 });
 
@@ -1075,20 +1077,17 @@ test('release entry forwards the built artifacts and dry-run mode to the uploade
   assert.ok(source.includes('\n  dryRun,\n'));
 });
 
-test('release notes list client commits with short sha and bound their size', () => {
+test('release notes list client commit subjects only and bound their size', () => {
   const notes = formatReleaseNotes([
     { sha: 'a5fd25f1', subject: '客户端更新切换到官方更新插件' },
     { sha: '55af6014', subject: '修'.repeat(120) },
   ]);
   const lines = notes.split('\n');
   assert.equal(lines.length, 2);
-  assert.match(lines[0], /^- 客户端更新切换到官方更新插件（a5fd25f1）$/u);
-  const truncatedSubject = lines[1]
-    .replace(/^- /u, '')
-    .replace(/（55af6014）$/u, '');
+  assert.equal(lines[0], '- 客户端更新切换到官方更新插件');
+  const truncatedSubject = lines[1].replace(/^- /u, '');
   assert.equal(truncatedSubject.length, 80, `主题应截断到 80 字：${lines[1]}`);
   assert.match(truncatedSubject, /…$/u);
-  assert.match(lines[1], /（55af6014）$/u);
 
   const many = formatReleaseNotes(
     Array.from({ length: 20 }, (_, index) => ({
@@ -1097,6 +1096,15 @@ test('release notes list client commits with short sha and bound their size', ()
     })),
   );
   assert.match(many, /- 其余 8 项客户端改动省略$/u);
+  assert.equal(
+    formatReleaseNotes([
+      {
+        sha: 'ignored',
+        subject: '提交标题\n不应展示的说明一\n不应展示的说明二',
+      },
+    ]),
+    '- 提交标题',
+  );
   assert.equal(formatReleaseNotes([]), '');
   assert.equal(formatReleaseNotes(null), '');
 });
@@ -1120,8 +1128,17 @@ test('release commits cover only client paths and skip merge commits', () => {
       path.join(directory, 'apps/ai-game-creator-shell/main.rs'),
       'fn main() {}\n',
     );
+    const commitMessagePath = path.join(
+      directory,
+      '.git',
+      'commit-message.txt',
+    );
+    writeFileSync(
+      commitMessagePath,
+      '客户端：新增更新插件接入\n补充更新插件接入的详细说明\n',
+    );
     git('add', '.');
-    git('commit', '--quiet', '-m', '客户端：新增更新插件接入');
+    git('commit', '--quiet', '-F', commitMessagePath);
 
     writeFileSync(path.join(directory, 'docs/readme.md'), '# 文档\n');
     git('add', '.');
@@ -1147,6 +1164,7 @@ test('release commits cover only client paths and skip merge commits', () => {
     const commits = collectReleaseCommits(base, 'HEAD', { cwd: directory });
     assert.ok(commits, '应能在临时仓库里收集提交');
     const subjects = commits.map((entry) => entry.subject);
+    // 标题后没有空行时，git %s 会把说明行拼进标题；摘要必须取原始首行。
     // 合并提交本身被 --no-merges 排除，但它带入的客户端改动仍然计入。
     assert.deepEqual(subjects, [
       '客户端：侧分支改动',
diff --git a/apps/ai-game-creator-shell/scripts/check-config.mjs b/apps/ai-game-creator-shell/scripts/check-config.mjs
index bd2f20c68..40577bdcf 100644
--- a/apps/ai-game-creator-shell/scripts/check-config.mjs
+++ b/apps/ai-game-creator-shell/scripts/check-config.mjs
@@ -200,15 +200,16 @@ const allowedUncalledTauriCommands = [
   'read_agc_plugin_panel',
   'set_agc_plugin_enabled',
   // 下面这些命令的调用方只有随 Project Supervisor 前端链路一起删除的旧命令聊天入口；
-  // 现在 App 前端、工作台与策划聊天都没有接线（检查点 / 恢复 / 索引 / 导出包 /
+  // 现在 App 前端、工作台与策划聊天都没有接线（检查点 / 恢复 / 索引 /
   // 画板同步 / 素材登记 / 权限策略 / 本地草案 / 平台美术），Rust 侧只剩注册与实现，
   // `*_at` helper 仍由 Rust 用例覆盖。接回新入口还是删除属于 native 能力取舍，先按
   // native-only 登记，避免孤儿检查一直报错。
   // 预览不在本清单：`activate_local_game_preview` 已按 ADR 回接到 App 的「运行」入口。
+  // 导出试玩包同样不在本清单：发布链路（`requestGamePublish`）已把它接回
+  // DirectProject 聊天头的「发布」入口。
   'build_local_project_index',
   'control_agent_run',
   'create_local_project_checkpoint',
-  'export_local_project_package',
   'generate_local_game_draft',
   'generate_platform_art_asset',
   'import_canvas_asset',
@@ -1946,6 +1947,7 @@ for (const snippet of [
   '官方账号服务（固定）',
   'runtime_config.save',
   "'/run：运行自检，启动本地 HTTP 预览并载入客户端运行视图'",
+  '已载入客户端运行视图',
   'async function executeRunLocal',
   'function needsInitializedChatProject',
   "'/remember [short|long|blackboard] 内容：追加短期、长期或黑板记忆'",
diff --git a/apps/ai-game-creator-shell/scripts/nsis-toolset.mjs b/apps/ai-game-creator-shell/scripts/nsis-toolset.mjs
index d79c9f8a7..f52c82836 100644
--- a/apps/ai-game-creator-shell/scripts/nsis-toolset.mjs
+++ b/apps/ai-game-creator-shell/scripts/nsis-toolset.mjs
@@ -88,15 +88,21 @@ export function resolveNsisCacheDir(
   env = process.env,
   platform = process.platform,
 ) {
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
   const explicit = env.AGC_TAURI_NSIS_CACHE_DIR?.trim();
-  if (explicit) return path.resolve(explicit);
+  if (explicit) return pathImpl.resolve(explicit);
   // Jenkins Windows 节点以 SYSTEM 运行，ProgramData 稳定可写且不受工作区清理影响；
   // 缓存里只有待解压的原始归档，不会从该目录执行任何程序。
   if (platform === 'win32') {
     const programData = env.ProgramData?.trim() || 'C:\\ProgramData';
-    return path.join(programData, 'genarrative', 'tauri-nsis-cache');
+    return pathImpl.join(programData, 'genarrative', 'tauri-nsis-cache');
   }
-  return path.join(os.homedir(), '.cache', 'genarrative', 'tauri-nsis-cache');
+  return pathImpl.join(
+    os.homedir(),
+    '.cache',
+    'genarrative',
+    'tauri-nsis-cache',
+  );
 }
 
 /** 与 tauri-bundler 相同的镜像开关语义，便于构建机绕过不可达的 GitHub。 */
diff --git a/apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs b/apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs
index 26faca27e..d5ce2fbf0 100644
--- a/apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs
@@ -7,6 +7,7 @@ import { test } from 'node:test';
 import JSZip from 'jszip';
 
 import {
+  defaultAppRoot,
   ensureNsisToolset,
   extractNsisArchive,
   NSIS_ARCHIVE_ASSET_NAME,
@@ -23,10 +24,7 @@ import {
   verifyNsisToolset,
 } from './nsis-toolset.mjs';
 
-const appRoot = path.resolve(
-  path.dirname(new URL(import.meta.url).pathname),
-  '..',
-);
+const appRoot = defaultAppRoot();
 const silentLogger = { log() {}, warn() {} };
 
 function createSandbox() {
@@ -98,6 +96,14 @@ test('NSIS 工具链目录与 Tauri useLocalToolsDir 配置保持一致', () =>
 });
 
 test('缓存目录默认落在工作区之外并支持环境变量覆盖', () => {
+  assert.equal(
+    resolveNsisCacheDir({ AGC_TAURI_NSIS_CACHE_DIR: 'D:\\agc-cache' }, 'win32'),
+    'D:\\agc-cache',
+  );
+  assert.equal(
+    resolveNsisCacheDir({ ProgramData: 'D:\\ProgramData' }, 'win32'),
+    path.win32.join('D:\\ProgramData', 'genarrative', 'tauri-nsis-cache'),
+  );
   assert.equal(
     resolveNsisCacheDir(
       { AGC_TAURI_NSIS_CACHE_DIR: '/tmp/agc-cache' },
@@ -105,13 +111,9 @@ test('缓存目录默认落在工作区之外并支持环境变量覆盖', () =>
     ),
     '/tmp/agc-cache',
   );
-  assert.equal(
-    resolveNsisCacheDir({ ProgramData: 'D:\\ProgramData' }, 'win32'),
-    path.join('D:\\ProgramData', 'genarrative', 'tauri-nsis-cache'),
-  );
   assert.ok(
     resolveNsisCacheDir({}, 'linux').endsWith(
-      path.join('.cache', 'genarrative', 'tauri-nsis-cache'),
+      path.posix.join('.cache', 'genarrative', 'tauri-nsis-cache'),
     ),
   );
 });
diff --git a/apps/ai-game-creator-shell/src-tauri/capabilities/main.json b/apps/ai-game-creator-shell/src-tauri/capabilities/main.json
index b62ed9e70..753d89477 100644
--- a/apps/ai-game-creator-shell/src-tauri/capabilities/main.json
+++ b/apps/ai-game-creator-shell/src-tauri/capabilities/main.json
@@ -16,7 +16,8 @@
         { "url": "https://www.genarrative.world/api/*" },
         { "url": "https://*/api/*" },
         { "url": "http://localhost:*/*" },
-        { "url": "http://127.0.0.1:*/*" }
+        { "url": "http://127.0.0.1:*/*" },
+        { "url": "https://*.aliyuncs.com/*" }
       ]
     },
     "opener:default",
diff --git a/apps/ai-game-creator-shell/src-tauri/src/browser.rs b/apps/ai-game-creator-shell/src-tauri/src/browser.rs
index 919fb7467..16b4ed4bd 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/browser.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/browser.rs
@@ -6,6 +6,7 @@ mod model;
 mod network_policy;
 mod playtest;
 mod process;
+mod sweep;
 
 pub use discovery::discover_chrome_or_edge;
 #[allow(unused_imports)]
@@ -22,6 +23,7 @@ pub(crate) use process::validate_local_preview_in_browser_with_cancellation;
 pub use process::{
     validate_local_preview_in_browser, validate_local_preview_in_browser_with_interaction,
 };
+pub(crate) use sweep::sweep_stale_browser_processes;
 
 pub(crate) use model::required_viewport_playtests_passed;
 pub(crate) use playtest::browser_playtest_scenario_fingerprint;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/browser/process.rs b/apps/ai-game-creator-shell/src-tauri/src/browser/process.rs
index 3330832ff..098f43841 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/browser/process.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/browser/process.rs
@@ -1,9 +1,14 @@
 use std::fs;
 use std::path::PathBuf;
 use std::time::Duration;
+#[cfg(windows)]
+use std::time::Instant;
 
+use chromiumoxide::async_process::{Child as BrowserChild, ChildStderr as BrowserChildStderr};
 use chromiumoxide::browser::{Browser, BrowserConfig};
-use futures::StreamExt;
+use chromiumoxide::handler::viewport::Viewport;
+use chromiumoxide::handler::HandlerConfig;
+use futures::{AsyncBufReadExt, FutureExt, StreamExt};
 use tempfile::{Builder as TempDirBuilder, TempDir};
 
 use super::cdp::run_browser_validation;
@@ -15,8 +20,12 @@ use super::model::{
     BrowserIdentity, BrowserValidationInput, BrowserValidationResult, BROWSER_TIMEOUT,
 };
 use super::network_policy::{preview_proxy_bypass_list, validate_input};
+#[cfg(windows)]
+use crate::process_session::WindowsProcessJob;
 
-fn browser_process_temp_root() -> PathBuf {
+pub(super) const BROWSER_TEMP_PREFIX: &str = "ga-browser-";
+
+pub(super) fn browser_process_temp_root() -> PathBuf {
     #[cfg(unix)]
     {
         PathBuf::from("/tmp")
@@ -29,7 +38,7 @@ fn browser_process_temp_root() -> PathBuf {
 
 pub(super) fn create_browser_process_temp_dir() -> Result<TempDir, String> {
     TempDirBuilder::new()
-        .prefix("ga-browser-")
+        .prefix(BROWSER_TEMP_PREFIX)
         .tempdir_in(browser_process_temp_root())
         .map_err(|error| format!("创建浏览器临时目录失败：{error}"))
 }
@@ -63,21 +72,306 @@ fn browser_config(
         .map_err(|error| format!("构建浏览器配置失败：{error}"))
 }
 
-/// 仅验证浏览器启动和真实 CDP，不加载项目、不生成试玩凭证。
-/// 每次独立 profile；既不串行化其它工具，也不继承 Codex 的临时 HOME。
-pub(crate) async fn check_browser_health() -> Result<BrowserIdentity, String> {
-    let discovered = discover_chrome_or_edge().map_err(|_| "browser-not-found")?;
-    let temporary = create_browser_process_temp_dir().map_err(|_| "browser-temp-unavailable")?;
-    let config = browser_config(&discovered.executable_path, &temporary, "<-loopback>")
-        .map_err(|_| "browser-config-invalid")?;
-    // 外层超时给 Chromiumoxide 内部启动超时后的 kill/wait 留出清理窗口。
-    let (mut browser, mut handler) = tokio::time::timeout(
-        BROWSER_TIMEOUT + Duration::from_secs(5),
-        Browser::launch(config),
+const BROWSER_CLOSE_TIMEOUT: Duration = Duration::from_secs(5);
+const MAX_LAUNCH_STDERR_BYTES: usize = 64 * 1024;
+const MAX_WS_URL_LEN: usize = 512;
+
+/// 必须与 browser_config 的 builder 调用保持一致：request_timeout /
+/// enable_request_intercept / disable_cache 在这里逐项镜像；viewport 镜像
+/// BrowserConfigBuilder 的默认值 Some(Viewport::default())（800x600，旧
+/// Browser::launch 会把它带入 HandlerConfig）；其余字段
+/// （ignore_https_errors / ignore_invalid_messages）沿用
+/// HandlerConfig::default()，与 builder 默认值相同。
+fn handler_config() -> HandlerConfig {
+    let mut config = HandlerConfig::default();
+    config.request_timeout = BROWSER_TIMEOUT;
+    config.request_intercept = true;
+    config.cache_enabled = false;
+    config.viewport = Some(Viewport::default());
+    config
+}
+
+/// 从浏览器 stderr 行提取 DevTools ws 地址；只接受 loopback 端点，
+/// 避免伪造输出把 CDP 连接引导到任意地址。
+fn parse_devtools_ws_url(line: &str) -> Option<String> {
+    let (_, ws) = line.rsplit_once("listening on ")?;
+    let ws = ws.trim();
+    if ws.is_empty() || ws.len() > MAX_WS_URL_LEN || !ws.contains("devtools/browser") {
+        return None;
+    }
+    let authority = ws.strip_prefix("ws://")?.split('/').next()?;
+    let (host, port) = authority.rsplit_once(':')?;
+    if !matches!(host, "127.0.0.1" | "localhost" | "[::1]")
+        || port.is_empty()
+        || !port.bytes().all(|byte| byte.is_ascii_digit())
+    {
+        return None;
+    }
+    Some(ws.to_string())
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum OwnedBrowserLaunchError {
+    SpawnFailed,
+    WsTimeout,
+    WsFailed,
+    ConnectTimeout,
+    ConnectFailed,
+}
+
+impl OwnedBrowserLaunchError {
+    fn is_timeout(self) -> bool {
+        matches!(self, Self::WsTimeout | Self::ConnectTimeout)
+    }
+
+    fn code(self) -> &'static str {
+        match self {
+            Self::SpawnFailed => "browser-spawn-failed",
+            Self::WsTimeout => "browser-ws-timeout",
+            Self::WsFailed => "browser-ws-failed",
+            Self::ConnectTimeout => "browser-cdp-connect-timeout",
+            Self::ConnectFailed => "browser-cdp-connect-failed",
+        }
+    }
+}
+
+type BrowserStderrReader = futures::io::BufReader<BrowserChildStderr>;
+
+/// 复刻 chromiumoxide 私有 ws_url_from_output 的语义（读 stderr 直到
+/// DevTools listening 行、提前退出即失败、整体有界），但 root 进程始终
+/// 留在调用方手里，并把 stderr reader 交还给调用方持续排空。
+async fn devtools_ws_url_from_stderr(
+    child: &mut BrowserChild,
+    timeout: Duration,
+) -> Result<(String, BrowserStderrReader), OwnedBrowserLaunchError> {
+    let stderr = child
+        .stderr
+        .take()
+        .ok_or(OwnedBrowserLaunchError::SpawnFailed)?;
+    let mut reader = futures::io::BufReader::new(stderr);
+    let mut captured: Vec<u8> = Vec::new();
+    let mut exited = Box::pin(child.wait()).fuse();
+    let read = async {
+        loop {
+            let mut line = Vec::new();
+            futures::select! {
+                _status = exited => return Err(OwnedBrowserLaunchError::WsFailed),
+                result = reader.read_until(b'\n', &mut line).fuse() => {
+                    let count = result.map_err(|_| OwnedBrowserLaunchError::WsFailed)?;
+                    if count == 0 {
+                        return Err(OwnedBrowserLaunchError::WsFailed);
+                    }
+                    captured.extend_from_slice(&line);
+                    if captured.len() > MAX_LAUNCH_STDERR_BYTES {
+                        return Err(OwnedBrowserLaunchError::WsFailed);
+                    }
+                    let Ok(text) = std::str::from_utf8(&line) else {
+                        return Err(OwnedBrowserLaunchError::WsFailed);
+                    };
+                    if let Some(url) = parse_devtools_ws_url(text) {
+                        return Ok(url);
+                    }
+                }
+            }
+        }
+    };
+    match tokio::time::timeout(timeout, read).await {
+        Ok(Ok(url)) => Ok((url, reader)),
+        Ok(Err(error)) => Err(error),
+        Err(_) => Err(OwnedBrowserLaunchError::WsTimeout),
+    }
+}
+
+fn spawn_stderr_drain(mut reader: BrowserStderrReader) -> tokio::task::JoinHandle<()> {
+    // 持续排空 stderr：浏览器日志写满管道会整体 stall。内容有界、不留存。
+    tokio::spawn(async move {
+        let mut buffer = Vec::with_capacity(4096);
+        loop {
+            buffer.clear();
+            match reader.read_until(b'\n', &mut buffer).await {
+                Ok(0) | Err(_) => break,
+                Ok(_) => {}
+            }
+        }
+    })
+}
+
+/// 自持浏览器进程：root 从 spawn 起归本结构所有；Windows 下整树挂进
+/// KILL_ON_JOB_CLOSE 的 Job——失败路径、遗忘 shutdown、甚至宿主进程
+/// 被杀，整棵树都会被回收，不再留下无父进程的无头浏览器。
+struct BrowserProcessGuard {
+    child: BrowserChild,
+    #[cfg(windows)]
+    job: Option<WindowsProcessJob>,
+}
+
+impl BrowserProcessGuard {
+    /// 整树收割：Windows 由 Job 终止全树，再 kill+wait root 兜底；
+    /// Unix 只终止 root，子进程依赖 root 死亡后的级联退出。
+    /// 返回是否已确认 root 进程退出。
+    async fn reap(&mut self) -> bool {
+        #[cfg(windows)]
+        if let Some(job) = &self.job {
+            let _ = job.terminate();
+        }
+        let _ = tokio::time::timeout(BROWSER_CLOSE_TIMEOUT, self.child.kill()).await;
+        matches!(
+            tokio::time::timeout(BROWSER_CLOSE_TIMEOUT, self.child.wait()).await,
+            Ok(Ok(_))
+        )
+    }
+
+    async fn confirm_reaped(&mut self) -> Result<(), String> {
+        #[cfg(windows)]
+        {
+            if let Some(job) = &self.job {
+                let deadline = Instant::now() + BROWSER_CLOSE_TIMEOUT;
+                loop {
+                    if job
+                        .is_empty()
+                        .map_err(|_| "browser-tree-reap-unconfirmed".to_string())?
+                    {
+                        return Ok(());
+                    }
+                    if Instant::now() >= deadline {
+                        return Err("browser-tree-reap-unconfirmed".into());
+                    }
+                    tokio::time::sleep(Duration::from_millis(20)).await;
+                }
+            }
+            Ok(())
+        }
+        #[cfg(not(windows))]
+        {
+            // 兜底确认 root 确已退出：否则调用方会在浏览器仍存活时删除
+            // 配置目录，且 browser-cleanup-unconfirmed 永远不会暴露。
+            match self.child.inner.try_wait() {
+                Ok(Some(_)) => Ok(()),
+                _ => Err("browser-tree-reap-unconfirmed".into()),
+            }
+        }
+    }
+}
+
+impl Drop for BrowserProcessGuard {
+    fn drop(&mut self) {
+        // Windows：Job 句柄关闭触发 KILL_ON_JOB_CLOSE 收掉整树；
+        // Unix：tokio kill_on_drop 终止 root，子进程随 IPC 断开级联退出。
+    }
+}
+
+struct OwnedBrowser {
+    browser: Browser,
+    process: BrowserProcessGuard,
+    handler_task: tokio::task::JoinHandle<()>,
+    drain_task: tokio::task::JoinHandle<()>,
+    // Option 以便在收割未确认时取出并保留目录（OwnedBrowser 有 Drop，
+    // 不能直接移动字段）。
+    temp: Option<TempDir>,
+}
+
+impl OwnedBrowser {
+    fn browser(&self) -> &Browser {
+        &self.browser
+    }
+
+    /// 优雅收束：CDP close → wait；失败则整树终止并确认收割。
+    async fn shutdown(mut self) -> Result<(), String> {
+        let close = tokio::time::timeout(BROWSER_CLOSE_TIMEOUT, self.browser.close()).await;
+        let waited = tokio::time::timeout(BROWSER_CLOSE_TIMEOUT, self.process.child.wait()).await;
+        self.handler_task.abort();
+        self.drain_task.abort();
+        if matches!(close, Ok(Ok(_))) && matches!(waited, Ok(Ok(_))) {
+            return Ok(());
+        }
+        if !self.process.reap().await {
+            // 进程退出未确认：保留目录与 owner.json，留待下次启动或
+            // 预检时由跨会话清扫收割，而不是删掉证据让清扫失明。
+            if let Some(temp) = self.temp.take() {
+                std::mem::forget(temp);
+            }
+            return Err("browser-cleanup-unconfirmed".into());
+        }
+        let confirmed = self.process.confirm_reaped().await;
+        if confirmed.is_err() {
+            if let Some(temp) = self.temp.take() {
+                std::mem::forget(temp);
+            }
+        }
+        confirmed
+    }
+}
+
+impl Drop for OwnedBrowser {
+    fn drop(&mut self) {
+        self.handler_task.abort();
+        self.drain_task.abort();
+        // 进程侧由 BrowserProcessGuard 的 Drop 兜底。
+    }
+}
+
+/// 自拉浏览器并完成 CDP 连接。spawn 与 Job 绑定之间存在极小的逸出
+/// 窗口：绑定前产生的子进程未入 Job——Unix 上随 root 死亡级联退出；
+/// Windows 没有这种级联，但窗口只有毫秒级（Chrome 此时尚未拉起子
+/// 进程），真发生泄漏时临时目录因被占用而保留，留待系统或用户清理。
+/// 绑定之后的一切子进程由 Job 全覆盖。
+async fn launch_owned_browser(
+    config: BrowserConfig,
+    executable: &std::path::Path,
+    temp: TempDir,
+) -> Result<OwnedBrowser, OwnedBrowserLaunchError> {
+    let child = config
+        .launch()
+        .map_err(|_| OwnedBrowserLaunchError::SpawnFailed)?;
+    // 无法证明整树可收割时拒绝放行浏览器；child 随 drop 由 kill_on_drop 收尾。
+    #[cfg(windows)]
+    let job = match WindowsProcessJob::assign_tokio(&child.inner) {
+        Ok(job) => Some(job),
+        Err(_) => return Err(OwnedBrowserLaunchError::SpawnFailed),
+    };
+    let mut process = BrowserProcessGuard {
+        child,
+        #[cfg(windows)]
+        job,
+    };
+    // 跨会话清扫的身份锚点：写入失败时该目录之后按旧残留只删不杀。
+    if let Some(pid) = process.child.inner.id() {
+        super::sweep::write_browser_process_owner(temp.path(), pid, executable);
+    }
+    let (url, reader) = match devtools_ws_url_from_stderr(&mut process.child, BROWSER_TIMEOUT).await
+    {
+        Ok(pair) => pair,
+        Err(error) => {
+            // 收割未确认时保留目录与 owner.json，交给跨会话清扫。
+            if !process.reap().await {
+                std::mem::forget(temp);
+            }
+            return Err(error);
+        }
+    };
+    let drain_task = spawn_stderr_drain(reader);
+    let connected = tokio::time::timeout(
+        BROWSER_TIMEOUT,
+        Browser::connect_with_config(url, handler_config()),
     )
-    .await
-    .map_err(|_| "browser-start-timeout")?
-    .map_err(|_| "browser-start-failed")?;
+    .await;
+    let (browser, mut handler) = match connected {
+        Ok(Ok(pair)) => pair,
+        Ok(Err(_)) => {
+            drain_task.abort();
+            if !process.reap().await {
+                std::mem::forget(temp);
+            }
+            return Err(OwnedBrowserLaunchError::ConnectFailed);
+        }
+        Err(_) => {
+            drain_task.abort();
+            if !process.reap().await {
+                std::mem::forget(temp);
+            }
+            return Err(OwnedBrowserLaunchError::ConnectTimeout);
+        }
+    };
     let handler_task = tokio::spawn(async move {
         while let Some(message) = handler.next().await {
             if message.is_err() {
@@ -85,14 +379,33 @@ pub(crate) async fn check_browser_health() -> Result<BrowserIdentity, String> {
             }
         }
     });
-    let version = tokio::time::timeout(Duration::from_secs(5), browser.version()).await;
-    let close = tokio::time::timeout(Duration::from_secs(5), browser.close()).await;
-    let waited = tokio::time::timeout(Duration::from_secs(5), browser.wait()).await;
-    handler_task.abort();
-    let _ = handler_task.await;
-    if !matches!(close, Ok(Ok(_))) || !matches!(waited, Ok(Ok(_))) {
-        let _ = tokio::time::timeout(Duration::from_secs(5), browser.kill()).await;
-        let _ = tokio::time::timeout(Duration::from_secs(5), browser.wait()).await;
+    Ok(OwnedBrowser {
+        browser,
+        process,
+        handler_task,
+        drain_task,
+        temp: Some(temp),
+    })
+}
+
+/// 仅验证浏览器启动和真实 CDP，不加载项目、不生成试玩凭证。
+/// 每次独立 profile；既不串行化其它工具，也不继承 Codex 的临时 HOME。
+pub(crate) async fn check_browser_health() -> Result<BrowserIdentity, String> {
+    let discovered = discover_chrome_or_edge().map_err(|_| "browser-not-found")?;
+    let temporary = create_browser_process_temp_dir().map_err(|_| "browser-temp-unavailable")?;
+    let config = browser_config(&discovered.executable_path, &temporary, "<-loopback>")
+        .map_err(|_| "browser-config-invalid")?;
+    let owned = launch_owned_browser(config, &discovered.executable_path, temporary)
+        .await
+        .map_err(|error| {
+            if error.is_timeout() {
+                "browser-start-timeout"
+            } else {
+                "browser-start-failed"
+            }
+        })?;
+    let version = tokio::time::timeout(Duration::from_secs(5), owned.browser().version()).await;
+    if owned.shutdown().await.is_err() {
         return Err("browser-cleanup-failed".into());
     }
     let version = version
@@ -155,23 +468,18 @@ pub(crate) async fn validate_local_preview_in_browser_with_cancellation(
         &proxy_bypass_list,
     )?;
 
-    let (mut browser, mut handler) = tokio::time::timeout(
-        BROWSER_TIMEOUT + Duration::from_secs(5),
-        Browser::launch(config),
-    )
-    .await
-    .map_err(|_| "启动浏览器超时".to_string())?
-    .map_err(|error| format!("启动浏览器失败：{error}"))?;
-    let handler_task = tokio::spawn(async move {
-        while let Some(message) = handler.next().await {
-            if message.is_err() {
-                break;
+    let owned = launch_owned_browser(config, &browser_executable.executable_path, browser_temp)
+        .await
+        .map_err(|error| {
+            if error.is_timeout() {
+                "启动浏览器超时".to_string()
+            } else {
+                format!("启动浏览器失败：{}", error.code())
             }
-        }
-    });
+        })?;
 
     let work = run_browser_validation(
-        &browser,
+        owned.browser(),
         &browser_executable,
         &preview_url,
         &input,
@@ -191,22 +499,11 @@ pub(crate) async fn validate_local_preview_in_browser_with_cancellation(
         _=cancelled => Err("宿主已停止本轮浏览器验证".to_string()),
     };
 
-    let close_result = tokio::time::timeout(Duration::from_secs(5), browser.close()).await;
-    let wait_result = tokio::time::timeout(Duration::from_secs(5), browser.wait()).await;
-    handler_task.abort();
-    let _ = handler_task.await;
-    if !matches!(close_result, Ok(Ok(_))) || !matches!(wait_result, Ok(Ok(_))) {
-        let _ = tokio::time::timeout(Duration::from_secs(5), browser.kill()).await;
-        if !matches!(
-            tokio::time::timeout(Duration::from_secs(5), browser.wait()).await,
-            Ok(Ok(_))
-        ) {
-            return Err(
-                "browser-cleanup-unconfirmed: 浏览器收束后无法证明退出，请核对本轮验证进程".into(),
-            );
-        }
+    if owned.shutdown().await.is_err() {
+        return Err(
+            "browser-cleanup-unconfirmed: 浏览器收束后无法证明退出，请核对本轮验证进程".into(),
+        );
     }
-    drop(browser_temp);
     let mut result = validation?;
     result.completed_at_unix_ms = unix_time_ms();
     let persisted_result = browser_validation_result_for_report(&result)?;
@@ -231,6 +528,61 @@ mod health_tests {
         assert!(safe_version_label("HeadlessChrome/140.0.1.2"));
     }
 
+    #[test]
+    fn devtools_ws_url_only_accepts_loopback_browser_endpoints() {
+        assert_eq!(
+            parse_devtools_ws_url(
+                "DevTools listening on ws://127.0.0.1:53317/devtools/browser/abc-123\r\n"
+            )
+            .as_deref(),
+            Some("ws://127.0.0.1:53317/devtools/browser/abc-123")
+        );
+        assert!(parse_devtools_ws_url(
+            "DevTools listening on ws://localhost:9222/devtools/browser/x"
+        )
+        .is_some());
+        assert!(
+            parse_devtools_ws_url("DevTools listening on ws://[::1]:9222/devtools/browser/x")
+                .is_some()
+        );
+        // 非 loopback、非 ws 协议、非 browser 端点、非法端口一律拒绝。
+        assert!(parse_devtools_ws_url(
+            "DevTools listening on ws://evil.example.com:9222/devtools/browser/x"
+        )
+        .is_none());
+        assert!(parse_devtools_ws_url(
+            "DevTools listening on http://127.0.0.1:9222/devtools/browser/x"
+        )
+        .is_none());
+        assert!(
+            parse_devtools_ws_url("DevTools listening on ws://127.0.0.1:9222/devtools/page/x")
+                .is_none()
+        );
+        assert!(parse_devtools_ws_url(
+            "DevTools listening on ws://127.0.0.1:notaport/devtools/browser/x"
+        )
+        .is_none());
+        assert!(parse_devtools_ws_url("random browser log line").is_none());
+        let overlong = format!(
+            "DevTools listening on ws://127.0.0.1:9222/devtools/browser/{}",
+            "a".repeat(MAX_WS_URL_LEN)
+        );
+        assert!(parse_devtools_ws_url(&overlong).is_none());
+    }
+
+    #[test]
+    fn handler_config_mirrors_browser_config_builder() {
+        let config = handler_config();
+        assert_eq!(config.request_timeout, BROWSER_TIMEOUT);
+        assert!(config.request_intercept);
+        assert!(!config.cache_enabled);
+        // 其余字段必须与 BrowserConfigBuilder 默认值保持一致
+        // （builder 默认 viewport 为 Some(Viewport::default())，即 800x600）。
+        assert!(config.ignore_https_errors);
+        assert!(config.ignore_invalid_messages);
+        assert_eq!(config.viewport, Some(Viewport::default()));
+    }
+
     #[tokio::test]
     #[ignore = "requires an installed Chrome/Chromium/Edge; local CDP only"]
     async fn real_browser_health_checks_can_run_concurrently() {
diff --git a/apps/ai-game-creator-shell/src-tauri/src/browser/sweep.rs b/apps/ai-game-creator-shell/src-tauri/src/browser/sweep.rs
new file mode 100644
index 000000000..21c681161
--- /dev/null
+++ b/apps/ai-game-creator-shell/src-tauri/src/browser/sweep.rs
@@ -0,0 +1,613 @@
+//! 跨会话清扫陈旧的无头浏览器进程与临时目录。
+//!
+//! 运行期 launch 会把 owner.json 写进 ga-browser-* 目录；启动与每次预检前
+//! 按「进程身份 + 可信浏览器路径」双重校验收割遗留进程树并删除目录。
+//! 没有 owner.json 的旧版本残留只删目录，绝不按猜测杀进程。
+
+use std::fs;
+use std::path::Path;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+use super::discovery::system_browser_candidates;
+use super::process::{browser_process_temp_root, BROWSER_TEMP_PREFIX};
+
+const OWNER_FILE: &str = "owner.json";
+const OWNER_SCHEMA: &str = "agc-browser-process.v1";
+/// 过新的目录可能属于正在进行中的预检（含 owner.json 写失败的极端情况），跳过。
+const SWEEP_MIN_AGE: Duration = Duration::from_secs(5 * 60);
+const TREE_KILL_MAX_PASSES: u32 = 20;
+const TREE_KILL_PASS_INTERVAL: Duration = Duration::from_millis(50);
+
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub(super) struct BrowserProcessOwner {
+    schema_version: String,
+    browser_pid: u32,
+    browser_start_identity: String,
+    executable: String,
+    owner_pid: u32,
+    owner_start_identity: String,
+    created_unix_ms: u64,
+}
+
+/// 运行期 launch 的身份锚点；任何一步拿不到身份证明都不写，
+/// 该目录之后按旧残留只删不杀。
+pub(super) fn write_browser_process_owner(temp_root: &Path, browser_pid: u32, executable: &Path) {
+    let identity = crate::runner::external_agent_runner_process_start_identity(browser_pid);
+    let owner_identity =
+        crate::runner::external_agent_runner_process_start_identity(std::process::id());
+    let (Ok(Some(identity)), Ok(Some(owner_identity))) = (identity, owner_identity) else {
+        return;
+    };
+    let owner = BrowserProcessOwner {
+        schema_version: OWNER_SCHEMA.into(),
+        browser_pid,
+        browser_start_identity: identity,
+        executable: executable.to_string_lossy().into_owned(),
+        owner_pid: std::process::id(),
+        owner_start_identity: owner_identity,
+        created_unix_ms: super::evidence::unix_time_ms(),
+    };
+    let Ok(bytes) = serde_json::to_vec_pretty(&owner) else {
+        return;
+    };
+    let _ = fs::write(temp_root.join(OWNER_FILE), bytes);
+}
+
+fn read_browser_process_owner(dir: &Path) -> Option<BrowserProcessOwner> {
+    let bytes = fs::read(dir.join(OWNER_FILE)).ok()?;
+    if bytes.len() > 16 * 1024 {
+        return None;
+    }
+    let owner: BrowserProcessOwner = serde_json::from_slice(&bytes).ok()?;
+    if owner.schema_version != OWNER_SCHEMA
+        || owner.browser_pid == 0
+        || owner.owner_pid == 0
+        || owner.browser_start_identity.is_empty()
+        || owner.browser_start_identity.len() > 128
+        || owner.owner_start_identity.is_empty()
+        || owner.owner_start_identity.len() > 128
+        || owner.executable.is_empty()
+        || owner.executable.len() > 1024
+    {
+        return None;
+    }
+    Some(owner)
+}
+
+/// PID 存活且启动身份一致（创建时间相同），排除 PID 复用。
+fn process_identity_matches(pid: u32, identity: &str) -> bool {
+    crate::runner::external_agent_runner_process_start_identity(pid)
+        .ok()
+        .flatten()
+        .is_some_and(|live| live == identity)
+}
+
+/// 可执行文件路径等价性：双方规范化后比较，Windows 下忽略大小写。
+fn same_executable_path(actual: &Path, expected: &Path) -> bool {
+    let canonical = |path: &Path| path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+    let actual = canonical(actual);
+    let expected = canonical(expected);
+    #[cfg(windows)]
+    {
+        return actual
+            .to_string_lossy()
+            .eq_ignore_ascii_case(&expected.to_string_lossy());
+    }
+    #[cfg(not(windows))]
+    {
+        actual == expected
+    }
+}
+
+/// exe 必须仍是系统标准路径下的可信浏览器，防止伪造 owner.json 借刀杀进程。
+fn trusted_browser_executable(path: &Path) -> bool {
+    let canonical = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+    if !canonical.is_file() {
+        return false;
+    }
+    system_browser_candidates()
+        .into_iter()
+        .any(|(candidate, _)| same_executable_path(&candidate, path))
+}
+
+/// 杀前复核：PID 对应的活进程镜像必须就是 owner.json 声明的那个可执行
+/// 文件。仅核对字符串不够——/tmp 全局可写时，同机其他用户可以伪造
+/// owner.json 把 browser_pid 指到本用户的任意进程借清扫杀之。
+/// Linux 进一步要求命令行声明本目录的 profile，把 PID 绑到这份配置
+/// 目录，挡住同用户伪造 owner.json 指向正在使用的浏览器。
+#[cfg(windows)]
+fn live_process_executable_matches(pid: u32, expected: &Path, _profile_dir: &Path) -> bool {
+    // 已知残余风险：Windows 读他进程命令行成本高（PEB/WMI），此处只核对
+    // 镜像；同用户伪造 owner.json 指向正在使用的浏览器时可误杀它。
+    use windows_sys::Win32::Foundation::CloseHandle;
+    use windows_sys::Win32::System::Threading::{
+        OpenProcess, QueryFullProcessImageNameW, PROCESS_QUERY_LIMITED_INFORMATION,
+    };
+    // SAFETY: 句柄非空时由 CloseHandle 释放；打开失败按不匹配处理（fail-closed）。
+    let handle = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid) };
+    if handle.is_null() {
+        return false;
+    }
+    let mut buffer = [0u16; 1024];
+    let mut length = buffer.len() as u32;
+    // SAFETY: buffer 可写，length 先传入容量、返回实际长度。
+    let okay = unsafe { QueryFullProcessImageNameW(handle, 0, buffer.as_mut_ptr(), &mut length) };
+    // SAFETY: handle 是本函数持有的合法句柄。
+    unsafe { CloseHandle(handle) };
+    if okay == 0 || length == 0 {
+        return false;
+    }
+    let actual = std::path::PathBuf::from(String::from_utf16_lossy(&buffer[..length as usize]));
+    same_executable_path(&actual, expected)
+}
+
+#[cfg(target_os = "linux")]
+fn live_process_executable_matches(pid: u32, expected: &Path, profile_dir: &Path) -> bool {
+    let Ok(actual) = fs::read_link(format!("/proc/{pid}/exe")) else {
+        return false;
+    };
+    if !same_executable_path(&actual, expected) {
+        return false;
+    }
+    // 命令行必须携带 --user-data-dir=<本目录>/profile：镜像一致只证明是
+    // 浏览器，不能证明是“这轮预检的”浏览器。
+    let Ok(cmdline) = fs::read(format!("/proc/{pid}/cmdline")) else {
+        return false;
+    };
+    let marker = format!("--user-data-dir={}", profile_dir.to_string_lossy());
+    cmdline
+        .split(|byte| *byte == 0)
+        .any(|arg| arg == marker.as_bytes())
+}
+
+// macOS 等无 /proc 的平台没有廉价的镜像与命令行核对手段，由目录属主检查
+// 兜底；已知残余风险：同用户伪造 owner.json 时可终止任意存活 PID。
+#[cfg(all(unix, not(target_os = "linux")))]
+fn live_process_executable_matches(_pid: u32, expected: &Path, _profile_dir: &Path) -> bool {
+    expected.is_file()
+}
+
+/// /tmp 是全局可写目录：属主目录必须由本用户创建，否则视为伪造并拒绝处置。
+#[cfg(unix)]
+fn directory_owned_by_current_user(dir: &Path) -> bool {
+    use std::os::unix::fs::MetadataExt;
+    dir.metadata()
+        // SAFETY: geteuid 无前置条件，总是安全的。
+        .map(|metadata| metadata.uid() == unsafe { libc::geteuid() })
+        .unwrap_or(false)
+}
+
+fn kill_browser_process_tree(root_pid: u32, expected_identity: &str) -> Result<(), String> {
+    #[cfg(windows)]
+    {
+        // 追踪所有经确认属于这棵树的 PID；只有它们全部从快照中消失才判
+        // 成功——root 先死而子进程残留时不再误报收割完成。
+        let mut tracked: Vec<(u32, String)> = Vec::new();
+        for _ in 0..TREE_KILL_MAX_PASSES {
+            let snapshot = windows_process_snapshot()?;
+            let root_present = snapshot.iter().any(|(pid, _)| *pid == root_pid);
+            if root_present && process_identity_matches(root_pid, expected_identity) {
+                // root 仍是目标浏览器：发现并追踪当前整棵子树。
+                for pid in windows_process_tree_pids_from(&snapshot, root_pid)? {
+                    track_process(&mut tracked, pid);
+                }
+            } else if !root_present {
+                // root 已退出且 PID 未被复用：发现临终前才拉起、仍挂在旧父
+                // PID 上的孤儿子进程。PID 已被复用时不做发现，避免误认
+                // 复用者的子进程。
+                for (pid, ppid) in &snapshot {
+                    if *ppid == root_pid {
+                        track_process(&mut tracked, *pid);
+                    }
+                }
+            }
+            // 只统计仍存活且启动身份未变的成员（复核排除 PID 复用）；
+            // 全部消失才算收割完成。
+            tracked.retain(|(pid, identity)| {
+                snapshot.iter().any(|(live, _)| live == pid)
+                    && process_identity_matches(*pid, identity)
+            });
+            if tracked.is_empty() {
+                return Ok(());
+            }
+            for (pid, _) in &tracked {
+                // 终止结果以“下一轮快照中是否消失”验证；对正在退出的进程
+                // OpenProcess 的瞬时失败会在下一轮自然消解。
+                windows_terminate_process(*pid);
+            }
+            std::thread::sleep(TREE_KILL_PASS_INTERVAL);
+        }
+        return Err("browser-sweep-tree-not-reaped".into());
+    }
+    #[cfg(not(windows))]
+    {
+        // 只杀 root：子进程随 IPC 断开级联退出（与运行期收割语义一致）。
+        if !process_identity_matches(root_pid, expected_identity) {
+            return Ok(());
+        }
+        // SAFETY: 目标 PID 与启动身份均已复核。
+        if unsafe { libc::kill(root_pid as i32, libc::SIGKILL) } != 0 {
+            return Err("browser-sweep-kill-failed".into());
+        }
+        // SIGKILL 后必须确认进程真正消失再报成功。
+        for _ in 0..TREE_KILL_MAX_PASSES {
+            // SAFETY: signal 0 仅做存活探测，无副作用。
+            if unsafe { libc::kill(root_pid as i32, 0) } != 0 {
+                return Ok(());
+            }
+            std::thread::sleep(TREE_KILL_PASS_INTERVAL);
+        }
+        Err("browser-sweep-tree-not-reaped".into())
+    }
+}
+
+#[cfg(windows)]
+/// 记录待收割成员及其启动身份：之后每轮终止前复核身份，排除 PID 复用
+/// 后误杀无关进程。拿不到身份的进程不追踪、不触碰（fail-closed）。
+#[cfg(windows)]
+fn track_process(tracked: &mut Vec<(u32, String)>, pid: u32) {
+    if tracked.iter().any(|(known, _)| *known == pid) {
+        return;
+    }
+    if let Ok(Some(identity)) = crate::runner::external_agent_runner_process_start_identity(pid) {
+        tracked.push((pid, identity));
+    }
+}
+
+#[cfg(windows)]
+fn windows_process_snapshot() -> Result<Vec<(u32, u32)>, String> {
+    use windows_sys::Win32::Foundation::{
+        CloseHandle, GetLastError, ERROR_NO_MORE_FILES, INVALID_HANDLE_VALUE,
+    };
+    use windows_sys::Win32::System::Diagnostics::ToolHelp::{
+        CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W,
+        TH32CS_SNAPPROCESS,
+    };
+    // SAFETY: 快照句柄非 INVALID_HANDLE_VALUE 时由 CloseHandle 释放。
+    let snapshot = unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0) };
+    if snapshot == INVALID_HANDLE_VALUE {
+        return Err("browser-sweep-snapshot-failed".into());
+    }
+    let mut entry = PROCESSENTRY32W::default();
+    entry.dwSize = std::mem::size_of::<PROCESSENTRY32W>() as u32;
+    let mut processes = Vec::new();
+    // SAFETY: entry 指向可写的 PROCESSENTRY32W，dwSize 已初始化。返回 0
+    // 只在 ERROR_NO_MORE_FILES 时是正常结束，其余错误按截断处理
+    // （fail-closed：残缺快照会导致误报收割完成）。
+    let mut available = unsafe { Process32FirstW(snapshot, &mut entry) };
+    loop {
+        if available == 0 {
+            // SAFETY: 紧跟失败的枚举调用读取错误码。
+            let error = unsafe { GetLastError() };
+            // SAFETY: snapshot 是本函数持有的合法句柄。
+            unsafe { CloseHandle(snapshot) };
+            if error == ERROR_NO_MORE_FILES {
+                return Ok(processes);
+            }
+            return Err("browser-sweep-snapshot-truncated".into());
+        }
+        processes.push((entry.th32ProcessID, entry.th32ParentProcessID));
+        // SAFETY: 同上。
+        available = unsafe { Process32NextW(snapshot, &mut entry) };
+    }
+}
+
+#[cfg(windows)]
+fn windows_process_tree_pids_from(
+    processes: &[(u32, u32)],
+    root_pid: u32,
+) -> Result<Vec<u32>, String> {
+    if !processes.iter().any(|(pid, _)| *pid == root_pid) {
+        return Ok(Vec::new());
+    }
+    let mut tree = vec![root_pid];
+    let mut index = 0;
+    while index < tree.len() {
+        let parent = tree[index];
+        for (pid, ppid) in processes {
+            if *ppid == parent && !tree.contains(pid) {
+                tree.push(*pid);
+            }
+        }
+        index += 1;
+        if tree.len() > 512 {
+            return Err("browser-sweep-tree-too-large".into());
+        }
+    }
+    Ok(tree)
+}
+
+#[cfg(windows)]
+fn windows_terminate_process(pid: u32) {
+    use windows_sys::Win32::Foundation::CloseHandle;
+    use windows_sys::Win32::System::Threading::{OpenProcess, TerminateProcess};
+    const PROCESS_TERMINATE: u32 = 0x0001;
+    // SAFETY: 句柄非空时由 CloseHandle 释放；空句柄直接返回。
+    let handle = unsafe { OpenProcess(PROCESS_TERMINATE, 0, pid) };
+    if handle.is_null() {
+        return;
+    }
+    // SAFETY: handle 是刚打开的合法进程句柄，退出码仅作占位。
+    unsafe { TerminateProcess(handle, 1) };
+    // SAFETY: 同上。
+    unsafe { CloseHandle(handle) };
+}
+
+/// 清扫陈旧的无头浏览器进程与临时目录，返回逐条处置记录供启动日志留痕。
+pub(crate) fn sweep_stale_browser_processes() -> Vec<String> {
+    sweep_stale_browser_processes_at(&browser_process_temp_root(), SWEEP_MIN_AGE)
+}
+
+fn sweep_stale_browser_processes_at(root: &Path, min_age: Duration) -> Vec<String> {
+    let mut notes = Vec::new();
+    let Ok(entries) = fs::read_dir(root) else {
+        return notes;
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().into_owned();
+        if !name.starts_with(BROWSER_TEMP_PREFIX) {
+            continue;
+        }
+        let dir = entry.path();
+        let Ok(metadata) = entry.metadata() else {
+            continue;
+        };
+        if !metadata.is_dir() {
+            continue;
+        }
+        let too_young = metadata
+            .created()
+            .or_else(|_| metadata.modified())
+            .ok()
+            .and_then(|time| time.elapsed().ok())
+            .is_some_and(|age| age < min_age);
+        if too_young {
+            continue;
+        }
+        match read_browser_process_owner(&dir) {
+            Some(owner) => sweep_owned_directory(&dir, &name, &owner, &mut notes),
+            None => match fs::remove_dir_all(&dir) {
+                Ok(()) => notes.push(format!("removed-legacy-dir:{name}")),
+                Err(_) => notes.push(format!("kept-legacy-dir-in-use:{name}")),
+            },
+        }
+    }
+    notes
+}
+
+fn sweep_owned_directory(
+    dir: &Path,
+    name: &str,
+    owner: &BrowserProcessOwner,
+    notes: &mut Vec<String>,
+) {
+    // /tmp 全局可写：属主目录必须是本用户创建，否则视为伪造，拒绝处置。
+    #[cfg(unix)]
+    if !directory_owned_by_current_user(dir) {
+        notes.push(format!("kept-foreign-dir:{name}"));
+        return;
+    }
+    // 另一个活着的 App 实例仍持有这轮浏览器：整目录跳过。
+    if process_identity_matches(owner.owner_pid, &owner.owner_start_identity) {
+        return;
+    }
+    if !process_identity_matches(owner.browser_pid, &owner.browser_start_identity) {
+        // 进程已退出或 PID 已被复用：不动任何进程，仅删目录。
+        if fs::remove_dir_all(dir).is_ok() {
+            notes.push(format!("removed-exited-dir:{name}"));
+        }
+        return;
+    }
+    if !trusted_browser_executable(Path::new(&owner.executable)) {
+        notes.push(format!("kept-untrusted-executable:{name}"));
+        return;
+    }
+    // 活进程镜像必须与声明的浏览器一致：防止伪造 owner.json 借清扫
+    // 终止本用户的无关进程。profile 子目录名与 process.rs 的
+    // browser_config 保持一致；Linux 上借此把 PID 绑到本目录。
+    if !live_process_executable_matches(
+        owner.browser_pid,
+        Path::new(&owner.executable),
+        &dir.join("profile"),
+    ) {
+        notes.push(format!("kept-image-mismatch:{name}"));
+        return;
+    }
+    match kill_browser_process_tree(owner.browser_pid, &owner.browser_start_identity) {
+        Ok(()) => {
+            let _ = fs::remove_dir_all(dir);
+            notes.push(format!(
+                "killed-stale-tree:{name}:pid={}",
+                owner.browser_pid
+            ));
+        }
+        Err(_) => notes.push(format!("kill-unconfirmed:{name}:pid={}", owner.browser_pid)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn exited_child_pid() -> u32 {
+        #[cfg(windows)]
+        let mut command = std::process::Command::new("cmd.exe");
+        #[cfg(windows)]
+        command.args(["/c", "exit", "0"]);
+        #[cfg(not(windows))]
+        let mut command = std::process::Command::new("/bin/true");
+        let mut child = command.spawn().expect("spawn exit fixture");
+        let pid = child.id();
+        child.wait().expect("reap exit fixture");
+        pid
+    }
+
+    fn write_owner(dir: &Path, owner: &BrowserProcessOwner) {
+        fs::write(
+            dir.join(OWNER_FILE),
+            serde_json::to_vec_pretty(owner).unwrap(),
+        )
+        .unwrap();
+    }
+
+    fn owner_fixture(browser_pid: u32, owner_pid: u32) -> BrowserProcessOwner {
+        BrowserProcessOwner {
+            schema_version: OWNER_SCHEMA.into(),
+            browser_pid,
+            browser_start_identity: "fixture-identity".into(),
+            executable: "C:\\fixture\\chrome.exe".into(),
+            owner_pid,
+            owner_start_identity: "fixture-owner-identity".into(),
+            created_unix_ms: super::super::evidence::unix_time_ms(),
+        }
+    }
+
+    #[test]
+    fn legacy_directory_without_owner_file_is_removed_only_when_old_enough() {
+        let root = tempfile::tempdir().unwrap();
+        let stale = root.path().join(format!("{BROWSER_TEMP_PREFIX}stale"));
+        fs::create_dir(&stale).unwrap();
+        // 默认年龄门禁：新建的目录视为可能属于进行中的预检，跳过。
+        assert!(sweep_stale_browser_processes_at(root.path(), SWEEP_MIN_AGE).is_empty());
+        assert!(stale.is_dir());
+        // 零门禁等价于“足够旧”：无 owner.json 的旧残留只删目录。
+        let notes = sweep_stale_browser_processes_at(root.path(), Duration::ZERO);
+        assert!(notes
+            .iter()
+            .any(|note| note.starts_with("removed-legacy-dir:")));
+        assert!(!stale.exists());
+    }
+
+    #[test]
+    fn directory_owned_by_a_live_app_instance_is_skipped() {
+        let root = tempfile::tempdir().unwrap();
+        let dir = root.path().join(format!("{BROWSER_TEMP_PREFIX}owned"));
+        fs::create_dir(&dir).unwrap();
+        let owner_identity =
+            crate::runner::external_agent_runner_process_start_identity(std::process::id())
+                .expect("self identity")
+                .expect("self identity present");
+        let mut owner = owner_fixture(exited_child_pid(), std::process::id());
+        owner.owner_start_identity = owner_identity;
+        write_owner(&dir, &owner);
+        assert!(sweep_stale_browser_processes_at(root.path(), Duration::ZERO).is_empty());
+        assert!(dir.is_dir());
+    }
+
+    #[test]
+    fn exited_or_reused_browser_pid_deletes_directory_without_touching_processes() {
+        let root = tempfile::tempdir().unwrap();
+        let dir = root.path().join(format!("{BROWSER_TEMP_PREFIX}exited"));
+        fs::create_dir(&dir).unwrap();
+        let owner = owner_fixture(exited_child_pid(), exited_child_pid());
+        write_owner(&dir, &owner);
+        let notes = sweep_stale_browser_processes_at(root.path(), Duration::ZERO);
+        assert!(notes
+            .iter()
+            .any(|note| note.starts_with("removed-exited-dir:")));
+        assert!(!dir.exists());
+    }
+
+    #[test]
+    fn owner_file_with_bad_schema_or_unknown_fields_is_treated_as_legacy() {
+        let root = tempfile::tempdir().unwrap();
+        let dir = root.path().join(format!("{BROWSER_TEMP_PREFIX}bad-owner"));
+        fs::create_dir(&dir).unwrap();
+        fs::write(
+            dir.join(OWNER_FILE),
+            br#"{"schemaVersion":"other","extra":true}"#,
+        )
+        .unwrap();
+        assert!(read_browser_process_owner(&dir).is_none());
+        let notes = sweep_stale_browser_processes_at(root.path(), Duration::ZERO);
+        assert!(notes
+            .iter()
+            .any(|note| note.starts_with("removed-legacy-dir:")));
+        assert!(!dir.exists());
+    }
+
+    #[test]
+    fn trusted_browser_executable_matches_system_candidates_only() {
+        assert!(!trusted_browser_executable(Path::new(
+            "C:\\fixture\\chrome.exe"
+        )));
+        let Some((installed, _)) = system_browser_candidates()
+            .into_iter()
+            .find(|(candidate, _)| candidate.is_file())
+        else {
+            // 没有安装浏览器的机器上无可信目标可断言。
+            return;
+        };
+        assert!(trusted_browser_executable(&installed));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn kill_browser_process_tree_reaps_fixture_tree() {
+        use std::process::{Command, Stdio};
+
+        // timeout.exe 在 stdio 被重定向时会立即退出，ping 才能在 null stdio 下存活。
+        let mut child = Command::new("cmd.exe")
+            .args([
+                "/c",
+                "ping",
+                "127.0.0.1",
+                "-n",
+                "60",
+                "&",
+                "ping",
+                "127.0.0.1",
+                "-n",
+                "60",
+            ])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn fixture");
+        let pid = child.id();
+        std::thread::sleep(Duration::from_millis(500));
+        let identity = crate::runner::external_agent_runner_process_start_identity(pid)
+            .expect("fixture identity")
+            .expect("fixture identity present");
+        let before =
+            windows_process_tree_pids_from(&windows_process_snapshot().expect("snapshot"), pid)
+                .expect("tree snapshot");
+        assert!(before.len() >= 2, "fixture 必须包含子进程: {before:?}");
+        kill_browser_process_tree(pid, &identity).expect("kill tree");
+        // 不仅 root 消失，快照里记录到的每个树成员（含 ping 子进程）都必须
+        // 真正被收割，不能只凭 root 不在就判成功。
+        let alive = windows_process_snapshot().expect("snapshot after kill");
+        for member in &before {
+            assert!(
+                !alive.iter().any(|(live, _)| live == member),
+                "fixture 进程 {member} 必须被收割: {before:?}"
+            );
+        }
+        let _ = child.kill();
+        let _ = child.wait();
+    }
+
+    #[cfg(any(windows, target_os = "linux"))]
+    #[test]
+    fn live_process_executable_matches_current_process_image() {
+        let exe = std::env::current_exe().unwrap();
+        let profile = Path::new("C:\\fixture\\ga-browser-x\\profile");
+        // Windows 只核对镜像；Linux 还要求命令行绑定 profile，本测试进程
+        // 不具备该标记，正例只在 Windows 断言。
+        #[cfg(windows)]
+        assert!(live_process_executable_matches(
+            std::process::id(),
+            &exe,
+            profile
+        ));
+        assert!(!live_process_executable_matches(
+            std::process::id(),
+            Path::new("C:\\fixture\\chrome.exe"),
+            profile
+        ));
+    }
+}
diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
index 3a1b403c1..2c24760aa 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
@@ -6164,6 +6164,16 @@ pub(crate) fn export_local_project_package(
     export_local_project_package_at(root)
 }
 
+#[tauri::command]
+pub(crate) fn read_local_project_export_package(
+    project_path: String,
+    package_relative_path: String,
+) -> Result<LocalProjectExportPackagePayload, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_permission_policy(root, "project.export_package")?;
+    read_local_project_export_package_at(root, package_relative_path.trim())
+}
+
 #[tauri::command]
 pub(crate) fn list_local_project_export_packages(
     project_path: String,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs b/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
index 532503c75..4378f32d7 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
@@ -304,6 +304,8 @@ async fn host_npm(
 
 pub(crate) async fn host_web_creation_preflight() -> Value {
     let started = Instant::now();
+    // 预检前顺手清扫陈旧的无头浏览器，避免残留进程放大本轮超时。
+    let _ = tokio::task::spawn_blocking(crate::browser::sweep_stale_browser_processes).await;
     let run = async {
         let fixture = tempfile::tempdir().map_err(|_| "web-preflight-temp-unavailable")?;
         let root = fixture.path();
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index 5fd240119..2f3642a99 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -2506,6 +2506,17 @@ fn main() {
             if let Some(directory) = game_creator_runtime_config_dir() {
                 setup_log.set(directory.join("diagnostics/startup.log"));
             }
+            // 跨会话清扫陈旧的无头浏览器（上次异常退出/被杀留下的 ga-browser-*）。
+            // 后台执行，不阻塞启动；杀树前按进程身份与可信浏览器路径双重校验。
+            tauri::async_runtime::spawn(async move {
+                let notes =
+                    tokio::task::spawn_blocking(crate::browser::sweep_stale_browser_processes)
+                        .await
+                        .unwrap_or_default();
+                if !notes.is_empty() {
+                    app_log!("startup.browser-sweep: {}", notes.join("; "));
+                }
+            });
             setup_log.append("startup.appdata.configure.complete");
             let config_dir = game_creator_runtime_config_dir().ok_or_else(|| {
                 let error = std::io::Error::new(
@@ -2761,6 +2772,7 @@ fn main() {
             build_local_project_index,
             create_local_project_checkpoint,
             export_local_project_package,
+            read_local_project_export_package,
             list_local_project_export_packages,
             diff_local_project_checkpoint,
             restore_local_project_checkpoint,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/process_session/tests.rs b/apps/ai-game-creator-shell/src-tauri/src/process_session/tests.rs
index d963ea811..c96ef974c 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/process_session/tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/process_session/tests.rs
@@ -1810,3 +1810,112 @@ setInterval(() => {}, 1000);
         thread::sleep(Duration::from_millis(25));
     }
 }
+
+#[cfg(windows)]
+#[test]
+fn windows_process_job_terminate_reaps_process_tree() {
+    use std::process::{Command, Stdio};
+
+    // 系统进程快照（pid, ppid），用于证明 ping 子进程真实存在并被收割。
+    fn windows_process_snapshot_for_test() -> Vec<(u32, u32)> {
+        use windows_sys::Win32::Foundation::{CloseHandle, INVALID_HANDLE_VALUE};
+        use windows_sys::Win32::System::Diagnostics::ToolHelp::{
+            CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W,
+            TH32CS_SNAPPROCESS,
+        };
+        // SAFETY: 快照句柄非 INVALID_HANDLE_VALUE 时由 CloseHandle 释放。
+        let snapshot = unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0) };
+        if snapshot == INVALID_HANDLE_VALUE {
+            return Vec::new();
+        }
+        let mut entry = PROCESSENTRY32W::default();
+        entry.dwSize = std::mem::size_of::<PROCESSENTRY32W>() as u32;
+        let mut processes = Vec::new();
+        // SAFETY: entry 指向可写的 PROCESSENTRY32W，dwSize 已初始化。
+        let mut available = unsafe { Process32FirstW(snapshot, &mut entry) };
+        while available != 0 {
+            processes.push((entry.th32ProcessID, entry.th32ParentProcessID));
+            // SAFETY: 同上。
+            available = unsafe { Process32NextW(snapshot, &mut entry) };
+        }
+        // SAFETY: snapshot 是本函数持有的合法句柄。
+        unsafe { CloseHandle(snapshot) };
+        processes
+    }
+
+    // cmd 启动第一个 ping 子进程后整树存活；terminate 必须连子进程一起收割。
+    // timeout.exe 在 stdio 被重定向时会立即退出，ping 才能在 null stdio 下存活。
+    let mut child = Command::new("cmd.exe")
+        .args([
+            "/c",
+            "ping",
+            "127.0.0.1",
+            "-n",
+            "60",
+            "&",
+            "ping",
+            "127.0.0.1",
+            "-n",
+            "60",
+        ])
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn cmd fixture");
+    let job = WindowsProcessJob::assign_std(&child).expect("assign job");
+    thread::sleep(Duration::from_millis(500));
+    // 前置检查不能只凭 Job 非空：快照里必须真的看到 cmd 拉起了 ping 子进程。
+    let tree_before: Vec<u32> = {
+        let snapshot = windows_process_snapshot_for_test();
+        let mut tree = vec![child.id()];
+        let mut index = 0;
+        while index < tree.len() {
+            let parent = tree[index];
+            for (pid, ppid) in &snapshot {
+                if *ppid == parent && !tree.contains(pid) {
+                    tree.push(*pid);
+                }
+            }
+            index += 1;
+        }
+        tree
+    };
+    assert!(
+        tree_before.len() >= 2,
+        "fixture 必须包含 ping 子进程，否则收割断言是空转: {tree_before:?}"
+    );
+    assert!(
+        !job.is_empty().expect("query job"),
+        "fixture 进程树必须先存活，否则收割断言是空转"
+    );
+    job.terminate().expect("terminate job");
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while !job.is_empty().expect("query job") {
+        assert!(
+            std::time::Instant::now() < deadline,
+            "Windows Job 进程树未被收割"
+        );
+        thread::sleep(Duration::from_millis(50));
+    }
+    // Job 为空之外，快照里的整棵树（含 ping 子进程）也必须真实消失。
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    loop {
+        let snapshot = windows_process_snapshot_for_test();
+        let survivors: Vec<u32> = tree_before
+            .iter()
+            .copied()
+            .filter(|pid| snapshot.iter().any(|(live, _)| live == pid))
+            .collect();
+        if survivors.is_empty() {
+            break;
+        }
+        assert!(
+            std::time::Instant::now() < deadline,
+            "Job terminate 后 fixture 子进程仍存活: {survivors:?}"
+        );
+        thread::sleep(Duration::from_millis(50));
+    }
+    let _ = child.kill();
+    let _ = child.wait();
+}
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/export.rs b/apps/ai-game-creator-shell/src-tauri/src/project/export.rs
index 6b4f7f43c..cb8fc948c 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/export.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/export.rs
@@ -1,5 +1,27 @@
 use super::*;
 
+use sha2::{Digest, Sha256};
+use std::collections::BTreeSet;
+use std::io::{Cursor, Read};
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LocalProjectExportPackageFileDigest {
+    pub(crate) path: String,
+    pub(crate) size_bytes: u64,
+    pub(crate) sha256: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LocalProjectExportPackagePayload {
+    pub(crate) package_relative_path: String,
+    pub(crate) package_bytes: Vec<u8>,
+    pub(crate) package_sha256: String,
+    pub(crate) package_size_bytes: u64,
+    pub(crate) files: Vec<LocalProjectExportPackageFileDigest>,
+}
+
 pub(crate) fn export_local_project_package_at(
     root: &Path,
 ) -> Result<LocalProjectExportPackageResult, String> {
@@ -110,6 +132,114 @@ pub(crate) fn export_local_project_package_at(
     })
 }
 
+/// Read a previously exported package for the explicit AGC publish flow.
+///
+/// The caller receives the package bytes and a deterministic file manifest, but
+/// never receives a filesystem path that it could accidentally send to the API.
+pub(crate) fn read_local_project_export_package_at(
+    root: &Path,
+    package_relative_path: &str,
+) -> Result<LocalProjectExportPackagePayload, String> {
+    validate_project_root(root)?;
+    let normalized = normalize_export_package_entry_path(package_relative_path)?;
+    if !normalized.starts_with("exports/playtest-package-")
+        || !normalized.ends_with(".zip")
+        || normalized.contains('/') && normalized.split('/').count() != 2
+    {
+        return Err("发行包路径必须是 exports/playtest-package-*.zip".to_string());
+    }
+    let package_path = resolve_local_project_path(root, &normalized)?;
+    prepare_game_creator_private_path_for_read(&package_path, false, "发行包")?;
+    let metadata = checked_export_package_metadata(&package_path, &normalized)?;
+    if !metadata.is_file() {
+        return Err("发行包必须是普通文件".to_string());
+    }
+    if metadata.len() == 0 || metadata.len() > MAX_PROJECT_EXPORT_PACKAGE_BYTES {
+        return Err("发行包大小超出本地发布上限".to_string());
+    }
+    let package_bytes =
+        fs::read(&package_path).map_err(|error| format!("读取发行包失败：{error}"))?;
+    if package_bytes.len() as u64 != metadata.len() {
+        return Err("发行包在读取期间发生变化，请重新导出".to_string());
+    }
+
+    let mut archive = zip::ZipArchive::new(Cursor::new(&package_bytes))
+        .map_err(|error| format!("读取发行包 ZIP 失败：{error}"))?;
+    let mut entries = Vec::with_capacity(archive.len());
+    let mut seen = BTreeSet::new();
+    for index in 0..archive.len() {
+        let mut entry = archive
+            .by_index(index)
+            .map_err(|error| format!("读取发行包条目失败：{error}"))?;
+        if entry.is_dir() {
+            continue;
+        }
+        let source_path = normalize_export_package_entry_path(entry.name())?;
+        // 本地试玩包以 game/index.html 为入口，而平台发行合同要求根
+        // index.html。把 game/ 前缀剥离到内存 ZIP，避免上传本地路径或修改
+        // 工作区里的原始导出文件；根目录的 README/assets 等公共条目原样保留。
+        let path = source_path
+            .strip_prefix("game/")
+            .unwrap_or(source_path.as_str())
+            .to_string();
+        let path = normalize_export_package_entry_path(&path)?;
+        if !seen.insert(path.clone()) {
+            return Err(format!("发行包包含重复条目：{path}"));
+        }
+        let expected_size = entry.size();
+        let mut content = Vec::with_capacity(expected_size.min(16 * 1024 * 1024) as usize);
+        entry
+            .read_to_end(&mut content)
+            .map_err(|error| format!("读取发行包文件失败：{path}: {error}"))?;
+        if content.len() as u64 != expected_size {
+            return Err(format!("发行包条目长度不一致：{path}"));
+        }
+        entries.push((path, content));
+    }
+    entries.sort_by(|left, right| left.0.cmp(&right.0));
+    if entries.is_empty() {
+        return Err("发行包没有可上传文件".to_string());
+    }
+
+    let mut normalized_writer = zip::ZipWriter::new(Cursor::new(Vec::new()));
+    let options = zip::write::SimpleFileOptions::default()
+        .compression_method(zip::CompressionMethod::Deflated);
+    for (path, content) in &entries {
+        normalized_writer
+            .start_file(path, options)
+            .map_err(|error| format!("写入发行包条目失败：{path}: {error}"))?;
+        normalized_writer
+            .write_all(content)
+            .map_err(|error| format!("写入发行包文件失败：{path}: {error}"))?;
+    }
+    let normalized_cursor = normalized_writer
+        .finish()
+        .map_err(|error| format!("完成发行包失败：{error}"))?;
+    let package_bytes = normalized_cursor.into_inner();
+    if package_bytes.is_empty() || package_bytes.len() as u64 > MAX_PROJECT_EXPORT_PACKAGE_BYTES {
+        return Err("归一化发行包大小超出本地发布上限".to_string());
+    }
+    let package_sha256 = format!("{:x}", Sha256::digest(&package_bytes));
+    let files = entries
+        .into_iter()
+        .map(|(path, content)| LocalProjectExportPackageFileDigest {
+            size_bytes: content.len() as u64,
+            sha256: format!("{:x}", Sha256::digest(&content)),
+            path,
+        })
+        .collect::<Vec<_>>();
+    if !files.iter().any(|file| file.path == "index.html") {
+        return Err("归一化发行包缺少根 index.html".to_string());
+    }
+    Ok(LocalProjectExportPackagePayload {
+        package_relative_path: normalized,
+        package_size_bytes: package_bytes.len() as u64,
+        package_bytes,
+        package_sha256,
+        files,
+    })
+}
+
 pub(crate) fn next_project_export_package_relative_path(root: &Path) -> Result<String, String> {
     let seed = unix_millis();
     for suffix in 0..1000 {
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs b/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs
index d81ed7686..dd1c045bb 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs
@@ -348,79 +348,113 @@ pub(crate) fn should_skip_project_index_path(relative_path: &str) -> bool {
         || should_skip_project_snapshot_path(relative_path)
 }
 
+/// 项目索引、checkpoint、Agent 上下文与 git 检查共用的排除口径：`.agent` 是这些结果的
+/// 本机控制面，不参与其中。
 pub(crate) fn should_skip_project_snapshot_path(relative_path: &str) -> bool {
+    project_snapshot_path_is_excluded(relative_path, false)
+}
+
+/**
+ * 项目快照同步（上传）的排除口径。
+ *
+ * 与 `should_skip_project_snapshot_path` 是同一份组件与后缀规则，唯一区别是 `.agent`：
+ * 它承载项目身份与 Agent 状态（`manifest.json`、`agent.db`、会话、运行日志、checkpoint、
+ * workbench、`project.lock`），必须整目录随快照同步，因此不再把 `.agent` 组件本身当作
+ * 排除项，并放行其中的 Agent 状态数据库（`.db` / `.db-wal` / `.db-shm`）。
+ *
+ * 其余排除项在 `.agent` 内同样生效：版本库、依赖与构建目录、凭据目录、敏感后缀、
+ * `.env*` 与凭据类文件名一律不参与同步；符号链接与重解析点在扫描阶段单独跳过。
+ */
+pub(crate) fn should_skip_project_snapshot_sync_path(relative_path: &str) -> bool {
+    project_snapshot_path_is_excluded(relative_path, true)
+}
+
+/// 任意层级出现即排除的目录组件。`.agent` 只有项目快照同步会放行。
+const PROJECT_SNAPSHOT_EXCLUDED_COMPONENTS: &[&str] = &[
+    ".agent",
+    ".git",
+    ".hg",
+    ".svn",
+    ".ssh",
+    ".aws",
+    ".azure",
+    ".gnupg",
+    ".kube",
+    ".docker",
+    ".gcloud",
+    ".terraform",
+    ".password-store",
+    ".secrets",
+    "secrets",
+    "credentials",
+    "node_modules",
+    "target",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    ".cache",
+];
+
+/// 凭据、密钥与数据库转储类文件名后缀。
+const PROJECT_SNAPSHOT_EXCLUDED_SUFFIXES: &[&str] = &[
+    ".pem",
+    ".key",
+    ".p12",
+    ".pfx",
+    ".ppk",
+    ".jks",
+    ".keystore",
+    ".kdbx",
+    ".db",
+    ".db-wal",
+    ".db-shm",
+    ".sqlite",
+    ".sqlite-wal",
+    ".sqlite-shm",
+    ".sqlite3",
+    ".sqlite3-wal",
+    ".sqlite3-shm",
+    ".sql",
+    ".sql.gz",
+    ".sql.bz2",
+    ".sql.xz",
+    ".dump",
+    ".dump.gz",
+    ".dmp",
+    ".bak",
+    ".mdb",
+    ".accdb",
+    ".rdb",
+    ".bson",
+    ".pgdump",
+    ".tfstate",
+    ".tfstate.backup",
+];
+
+/// `.agent` 内的 Agent 状态数据库（`agent.db` 及其 WAL / SHM 旁文件）属于项目状态，
+/// 随快照同步；其它数据库与转储后缀仍然排除。
+const PROJECT_AGENT_STATE_DATABASE_SUFFIXES: &[&str] = &[".db", ".db-wal", ".db-shm"];
+
+fn project_snapshot_path_is_excluded(relative_path: &str, include_agent_state: bool) -> bool {
     let components = relative_path
         .split('/')
         .filter(|component| !component.is_empty())
         .map(str::to_ascii_lowercase)
         .collect::<Vec<_>>();
     if components.iter().any(|component| {
-        matches!(
-            component.as_str(),
-            ".agent"
-                | ".git"
-                | ".hg"
-                | ".svn"
-                | ".ssh"
-                | ".aws"
-                | ".azure"
-                | ".gnupg"
-                | ".kube"
-                | ".docker"
-                | ".gcloud"
-                | ".terraform"
-                | ".password-store"
-                | ".secrets"
-                | "secrets"
-                | "credentials"
-                | "node_modules"
-                | "target"
-                | "dist"
-                | "build"
-                | ".next"
-                | "coverage"
-                | ".cache"
-        )
+        PROJECT_SNAPSHOT_EXCLUDED_COMPONENTS.contains(&component.as_str())
+            && !(include_agent_state && component == ".agent")
     }) {
         return true;
     }
     let Some(file_name) = components.last() else {
         return true;
     };
-    let sensitive_suffixes = [
-        ".pem",
-        ".key",
-        ".p12",
-        ".pfx",
-        ".ppk",
-        ".jks",
-        ".keystore",
-        ".kdbx",
-        ".db",
-        ".db-wal",
-        ".db-shm",
-        ".sqlite",
-        ".sqlite-wal",
-        ".sqlite-shm",
-        ".sqlite3",
-        ".sqlite3-wal",
-        ".sqlite3-shm",
-        ".sql",
-        ".sql.gz",
-        ".sql.bz2",
-        ".sql.xz",
-        ".dump",
-        ".dump.gz",
-        ".dmp",
-        ".bak",
-        ".mdb",
-        ".accdb",
-        ".rdb",
-        ".bson",
-        ".pgdump",
-        ".tfstate",
-        ".tfstate.backup",
-    ];
+    let agent_state_database = include_agent_state
+        && components
+            .first()
+            .is_some_and(|first| first.as_str() == ".agent");
     let structured_secret_suffixes = [".json", ".txt", ".toml", ".yaml", ".yml"];
     file_name == ".env"
         || file_name.starts_with(".env.")
@@ -471,9 +505,10 @@ pub(crate) fn should_skip_project_snapshot_path(relative_path: &str) -> bool {
         || file_name.starts_with("id_ecdsa")
         || file_name.starts_with("id_ed25519")
         || file_name.starts_with("id_xmss")
-        || sensitive_suffixes
-            .iter()
-            .any(|suffix| file_name.ends_with(suffix))
+        || PROJECT_SNAPSHOT_EXCLUDED_SUFFIXES.iter().any(|suffix| {
+            file_name.ends_with(suffix)
+                && !(agent_state_database && PROJECT_AGENT_STATE_DATABASE_SUFFIXES.contains(suffix))
+        })
         || ((file_name.contains("cookie") || file_name.contains("credential"))
             && structured_secret_suffixes
                 .iter()
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/scan.rs b/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/scan.rs
index 964e10a38..a17a89b38 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/scan.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/scan.rs
@@ -23,9 +23,10 @@ pub(crate) struct ProjectSnapshotScanResult {
     pub(crate) skipped: Vec<ProjectSnapshotSkippedPath>,
 }
 
-/// 扫描项目目录，复用 checkpoint / 项目索引同一份排除口径：
-/// `.agent`、版本控制目录、依赖与构建产物目录、凭据目录、符号链接与重解析点
-/// 都不参与同步，超出单文件上限的文件进入跳过清单而不是静默丢弃。
+/// 扫描项目目录，排除口径见 `should_skip_project_snapshot_sync_path`：
+/// `.agent` 是项目身份与 Agent 状态的权威位置，整目录参与同步；版本控制目录、
+/// 依赖与构建产物目录、凭据目录、符号链接与重解析点都不参与同步，超出单文件
+/// 上限的文件进入跳过清单而不是静默丢弃。
 pub(crate) fn scan_project_snapshot_files(
     root: &Path,
     max_file_bytes: u64,
@@ -52,7 +53,7 @@ pub(crate) fn scan_project_snapshot_files(
             let Ok(relative_path) = relative_project_path(root, &path) else {
                 continue;
             };
-            if should_skip_project_snapshot_path(&relative_path) {
+            if should_skip_project_snapshot_sync_path(&relative_path) {
                 continue;
             }
             let metadata = match fs::symlink_metadata(&path) {
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/tests.rs b/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/tests.rs
index a39b2b8b1..73a7209c2 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project_snapshot/tests.rs
@@ -95,8 +95,6 @@ fn project_snapshot_scan_skips_excluded_paths_and_oversized_files() {
     let root = fixture_root();
     write_fixture_file(root.path(), "game/index.html", b"<html></html>");
     write_fixture_file(root.path(), "assets/manifest.json", b"{}");
-    write_fixture_file(root.path(), ".agent/runtime/state.json", b"{}");
-    write_fixture_file(root.path(), ".agent/manifest.json", b"{}");
     write_fixture_file(root.path(), "node_modules/pkg/index.js", b"export {};");
     write_fixture_file(root.path(), "game/dist/bundle.js", b"bundle");
     write_fixture_file(root.path(), "secrets/key.pem", b"private-key");
@@ -111,7 +109,7 @@ fn project_snapshot_scan_skips_excluded_paths_and_oversized_files() {
     assert_eq!(
         scanned,
         vec!["assets/manifest.json".to_string()],
-        ".agent、node_modules、dist 与凭据目录里的文件不能进入候选集合"
+        "node_modules、dist 与凭据目录里的文件不能进入候选集合"
     );
     let skipped = scan
         .skipped
@@ -125,6 +123,111 @@ fn project_snapshot_scan_skips_excluded_paths_and_oversized_files() {
     );
 }
 
+#[test]
+fn project_snapshot_scan_uploads_whole_agent_directory() {
+    let root = fixture_root();
+    write_fixture_file(root.path(), "game/index.html", b"<html></html>");
+    write_fixture_file(root.path(), ".agent/manifest.json", b"{}");
+    write_fixture_file(root.path(), ".agent/agent.db", b"sqlite");
+    write_fixture_file(root.path(), ".agent/agent.db-wal", b"wal");
+    write_fixture_file(root.path(), ".agent/project.lock", b"{}");
+    write_fixture_file(root.path(), ".agent/.manifest.json.lock", b"");
+    write_fixture_file(root.path(), ".agent/conversations/project.jsonl", b"{}\n");
+    write_fixture_file(root.path(), ".agent/runtime/events/art.jsonl", b"{}\n");
+    write_fixture_file(
+        root.path(),
+        ".agent/runtime/command-env/home/.config.json",
+        b"{}",
+    );
+    write_fixture_file(root.path(), ".agent/logs/command.log", b"log");
+    write_fixture_file(
+        root.path(),
+        ".agent/checkpoints/0001/manifest.json",
+        b"{\"files\":[]}",
+    );
+    write_fixture_file(
+        root.path(),
+        ".agent/workbench/resource-layouts/art.json",
+        b"{}",
+    );
+
+    let scan = scan_fixture(root.path());
+    let scanned = scan
+        .files
+        .iter()
+        .map(|file| file.relative_path.clone())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        scanned,
+        vec![
+            ".agent/.manifest.json.lock".to_string(),
+            ".agent/agent.db".to_string(),
+            ".agent/agent.db-wal".to_string(),
+            ".agent/checkpoints/0001/manifest.json".to_string(),
+            ".agent/conversations/project.jsonl".to_string(),
+            ".agent/logs/command.log".to_string(),
+            ".agent/manifest.json".to_string(),
+            ".agent/project.lock".to_string(),
+            ".agent/runtime/command-env/home/.config.json".to_string(),
+            ".agent/runtime/events/art.jsonl".to_string(),
+            ".agent/workbench/resource-layouts/art.json".to_string(),
+            "game/index.html".to_string(),
+        ],
+        "`.agent` 是项目身份与 Agent 状态的权威位置，必须整目录参与同步"
+    );
+    assert!(
+        scan.skipped.is_empty(),
+        "`.agent` 内的普通文件既不跳过也不延后"
+    );
+}
+
+#[test]
+fn project_snapshot_sync_policy_keeps_agent_state_and_still_blocks_credentials() {
+    for relative_path in [
+        ".agent/manifest.json",
+        ".agent/agent.db",
+        ".agent/agent.db-wal",
+        ".agent/agent.db-shm",
+        ".agent/project.lock",
+        ".agent/runtime/events/art.jsonl",
+        ".agent/runtime/locks/append/01.lock",
+        ".agent/checkpoints/0001/manifest.json",
+        ".agent/conversations/project.jsonl",
+        ".agent/workbench/resource-layouts/art.json",
+        ".AGENT/manifest.json",
+    ] {
+        assert!(
+            !should_skip_project_snapshot_sync_path(relative_path),
+            "`.agent` 状态必须参与同步：{relative_path}"
+        );
+    }
+
+    for relative_path in [
+        ".agent/credentials/platform.json",
+        ".agent/.ssh/id_rsa",
+        ".agent/certs/server.pem",
+        ".agent/node_modules/pkg/index.js",
+        ".agent/runtime/command-env/home/.env",
+        ".agent/runtime/command-env/home/.npmrc",
+        ".agent/backup/game.sql",
+        ".git/config",
+        "node_modules/pkg/index.js",
+        "game/dist/bundle.js",
+        "secrets/key.pem",
+        "",
+    ] {
+        assert!(
+            should_skip_project_snapshot_sync_path(relative_path),
+            "凭据、版本库与构建产物仍然排除：{relative_path}"
+        );
+    }
+
+    // 项目索引、checkpoint 与 Agent 上下文继续排除整个 `.agent`，本变更只放开快照同步。
+    assert!(should_skip_project_snapshot_path(".agent/manifest.json"));
+    assert!(should_skip_project_index_path(".agent/manifest.json"));
+    assert!(should_skip_project_index_path(".agent/agent.db"));
+}
+
 #[test]
 fn project_snapshot_diff_reuses_metadata_and_reports_a_single_modification() {
     let root = fixture_root();
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
index 6e9abb9e8..a67c171f5 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
@@ -3935,6 +3935,54 @@ fn local_project_export_package_uses_runtime_whitelist_and_records() {
     fs::remove_dir_all(root).ok();
 }
 
+#[test]
+fn local_project_export_package_publish_payload_contains_bytes_and_file_digests() {
+    let root = unique_project_path();
+    init_existing_html_project_at(&root, "project-publish", "在线试玩项目").expect("project init");
+    write_local_project_file_at(&root, "game/index.html", &fake_llm_game_draft().game_html)
+        .expect("write playable html");
+    write_local_project_file_at(&root, "exports/README.md", "publish notes").expect("write readme");
+
+    let exported = export_local_project_package_at(&root).expect("export package");
+    let payload = read_local_project_export_package_at(&root, &exported.package_relative_path)
+        .expect("read publish payload");
+
+    assert_eq!(
+        payload.package_relative_path,
+        exported.package_relative_path
+    );
+    assert_eq!(
+        payload.package_size_bytes,
+        payload.package_bytes.len() as u64
+    );
+    assert_eq!(payload.files.len(), 2);
+    assert!(payload.files.iter().any(|file| file.path == "index.html"));
+    assert!(payload
+        .files
+        .iter()
+        .any(|file| file.path == "exports/README.md"));
+    let mut archive = zip::ZipArchive::new(std::io::Cursor::new(&payload.package_bytes))
+        .expect("read normalized package");
+    let names = (0..archive.len())
+        .map(|index| {
+            archive
+                .by_index(index)
+                .expect("normalized entry")
+                .name()
+                .to_string()
+        })
+        .collect::<Vec<_>>();
+    assert!(names.iter().any(|name| name == "index.html"));
+    assert!(!names.iter().any(|name| name.starts_with("game/")));
+    assert_eq!(payload.package_sha256.len(), 64);
+    assert!(payload
+        .package_sha256
+        .chars()
+        .all(|value| value.is_ascii_hexdigit()));
+
+    fs::remove_dir_all(root).ok();
+}
+
 #[test]
 fn local_project_export_package_list_only_returns_recent_playtest_zips() {
     let root = unique_project_path();
diff --git a/apps/ai-game-creator-shell/src/App.tsx b/apps/ai-game-creator-shell/src/App.tsx
index 044322d2c..00f0cda8f 100644
--- a/apps/ai-game-creator-shell/src/App.tsx
+++ b/apps/ai-game-creator-shell/src/App.tsx
@@ -40,12 +40,14 @@ import type {
   LocalGameProjectRevisionStatus,
   LocalPreviewResult,
   LocalPreviewStatus,
+  LocalProjectExportPackageResult,
   LocalProjectFileResult,
   LocalProjectKind,
   PendingUiConfirmation,
   ProjectPermissionPolicyView,
   TauriInvoke,
 } from './app/types';
+import { GameDistributionPublishPanel } from './components/game-distribution/GameDistributionPublishPanel';
 import {
   agentConversationId,
   agentRuntimeStateFromResult,
@@ -91,6 +93,7 @@ import {
   type ResourceReferenceInsertEventDetail,
 } from './features/project-workspace/resourceReferences';
 import { RuntimeConfigDialog } from './features/runtime-config/RuntimeConfigDialog';
+import { readGamePublishAvailability } from './services/gameDistributionPublish';
 import {
   setAgcPluginProjectPath,
   startAvailableAgcEditorPlugins,
@@ -167,7 +170,6 @@ type AppProps = {
   initialProjectManifest?: GameCreationAppManifest;
   initialProjectKind?: LocalProjectKind;
   planningStartMode?: boolean;
-  activeVersionId?: ProjectChatComponentProps['activeVersionId'];
   initialPlanningPrompt?: string;
   initialPlanningPromptClaimScope?: string;
   initialCreationType?: HomeCreationType | null;
@@ -181,6 +183,7 @@ type AppProps = {
     metadata?: ProjectManifestSnapshotMetadata,
   ) => void;
   onPreviewChange?: (preview: GameCreationAppPreviewState | null) => void;
+  onRunNotice?: ProjectChatComponentProps['onRunNotice'];
   onAgentRuntimeSummariesChange?: (
     summaries: ProjectAgentRuntimeSummary[],
   ) => void;
@@ -203,7 +206,6 @@ export function App({
   initialProjectManifest,
   initialProjectKind = 'web',
   planningStartMode = false,
-  activeVersionId = null,
   initialPlanningPrompt = '',
   initialPlanningPromptClaimScope = '',
   initialCreationType = null,
@@ -213,6 +215,7 @@ export function App({
   onPlayRequestHandled,
   onManifestChange,
   onPreviewChange,
+  onRunNotice,
   onAgentRuntimeSummariesChange,
   onAgentResultsChange,
 }: AppProps = {}) {
@@ -361,6 +364,12 @@ export function App({
 
   const chatComposerRef = useRef<ResourceReferenceInputHandle | null>(null);
   const [chatAgentBusy, setChatAgentBusy] = useState(false);
+  // 发布到游戏广场：试玩包导出结果与面板开关由工作台壳持有，聊天容器只负责触发。
+  const [publishPackageResult, setPublishPackageResult] =
+    useState<LocalProjectExportPackageResult | null>(null);
+  const [publishPanelOpen, setPublishPanelOpen] = useState(false);
+  // 发布灰度：只有命中的账号才把「发布到游戏广场」入口交给聊天头；读取失败按不开放处理。
+  const [gamePublishAllowed, setGamePublishAllowed] = useState(false);
   const [projectChatError, setProjectChatError] = useState('');
   const [designAgentTransientReply, setDesignAgentTransientReplyVisible] =
     useState('');
@@ -513,6 +522,7 @@ export function App({
       texts.push(entry.text);
       reasoningByMessageId.set(entry.messageId, texts);
     }
+    // 持久策划消息没有发送时间，不能把读取时刻显示成历史发送时间。
     const messages: ChatMessage[] = view.messages
       .filter((message) => message.text.trim())
       .map((message) => ({
@@ -521,7 +531,6 @@ export function App({
         runtimeOwned: true,
         messageId: message.id,
         reasoningText: reasoningByMessageId.get(message.id)?.join('\n\n'),
-        updatedAt: Date.now(),
       }));
     const initialPrompt = initialPlanningPromptLatchRef.current.prompt;
     if (
@@ -534,7 +543,6 @@ export function App({
         role: 'user',
         text: initialPrompt,
         runtimeOwned: true,
-        updatedAt: Date.now(),
       });
     }
     return messages;
@@ -804,9 +812,7 @@ export function App({
   const agentRuntimeResumeProjectPathRef = useRef<string | null>(null);
   const initialProjectOpenedRef = useRef(false);
   const pendingUiConfirmationActionRef = useRef<(() => void) | null>(null);
-  const executeRunLocalRef = useRef<(announceToChat: boolean) => void>(
-    () => undefined,
-  );
+  const executeRunLocalRef = useRef<() => void>(() => undefined);
   const [runtimeConfigOpen, setRuntimeConfigOpen] = useState(false);
 
   function requestRuntimeConfigOpen() {
@@ -872,7 +878,15 @@ export function App({
     if (messageList) {
       messageList.scrollTop = messageList.scrollHeight;
     }
-  }, [messages, projectChatError]);
+  }, [
+    messages,
+    projectChatError,
+    designAgentTransientReply,
+    designAgentReasoning,
+    designAgentView,
+    pendingUiConfirmation,
+    chatFileImportNotice,
+  ]);
 
   useEffect(() => {
     latestMessagesRef.current = messages;
@@ -1172,6 +1186,71 @@ export function App({
     }
   }
 
+  useEffect(() => {
+    let cancelled = false;
+    void readGamePublishAvailability()
+      .then((allowed) => {
+        if (!cancelled) setGamePublishAllowed(allowed);
+      })
+      .catch(() => {
+        if (!cancelled) setGamePublishAllowed(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [localProject?.projectPath]);
+
+  /**
+   * 导出试玩包并打开发布面板。
+   *
+   * 权限口径沿用本地命令：`project.export_package` 需要确认时先入队，确认后再导出；
+   * 导出结果只留在壳里，发布面板关闭即丢弃，不写入项目。
+   */
+  async function requestGamePublish() {
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setWorkspaceStatus('需要在 Tauri App 内发布');
+      return;
+    }
+    const nextProjectPath =
+      resolveChatProjectPath(localProject) ?? projectPath.trim();
+    if (!nextProjectPath) {
+      setWorkspaceStatus('先打开一个项目再发布');
+      return;
+    }
+    const runExport = async () => {
+      try {
+        const result = await invoke<LocalProjectExportPackageResult>(
+          'export_local_project_package',
+          { projectPath: nextProjectPath },
+        );
+        setWorkspaceStatus(`已导出本地试玩包：${result.packageRelativePath}`);
+        setPublishPackageResult(result);
+        setPublishPanelOpen(true);
+        appendLocalPermissionLog(
+          nextProjectPath,
+          'command.auto',
+          'project.export_package',
+        );
+      } catch (error) {
+        setWorkspaceStatus(
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    };
+    const queued = await queueProjectPolicyConfirmationIfNeeded(
+      invoke,
+      'project.export_package',
+      nextProjectPath,
+      '导出试玩包并打开「发布到游戏广场」面板。',
+      '导出试玩包需要确认，确认后继续。',
+      () => void runExport(),
+    );
+    if (!queued) {
+      await runExport();
+    }
+  }
+
   async function confirmUiCommand() {
     const pending = pendingUiConfirmation;
     if (!pending) {
@@ -1307,7 +1386,7 @@ export function App({
     }
     handledPlayRequestRef.current = requestKey;
     onPlayRequestHandled?.(playRequest.requestId);
-    void executeRunLocalRef.current(true);
+    void executeRunLocalRef.current();
   }, [localProject?.projectPath, onPlayRequestHandled, playRequest]);
 
   /**
@@ -1639,20 +1718,6 @@ export function App({
     }
   }
 
-  /**
-   * 工作台壳要把一句结果说给用户在项目对话里听。
-   *
-   * DirectProject 的会话由聊天容器持有，壳只把这句话交给聊天的本地消息流；
-   * 立项策划路径仍写壳自己的 `messages`。
-   */
-  function announceProjectChatMessage(text: string) {
-    if (directProjectMode) {
-      directProjectChatRef.current?.announce(text);
-      return;
-    }
-    setMessages((current) => [...current, { role: 'assistant', text }]);
-  }
-
   async function executeChatAgentReply({
     prompt,
     clientTurnId: directConversationTurnId,
@@ -1758,19 +1823,18 @@ export function App({
     }
   }
 
-  async function executeRunLocal(announceToChat: boolean) {
+  async function executeRunLocal() {
     const invoke = resolveTauriInvoke();
     if (!invoke) {
-      if (announceToChat) {
-        announceProjectChatMessage('需要在 Tauri App 内运行。');
-      }
+      onRunNotice?.({ tone: 'error', message: '需要在 Tauri App 内运行。' });
       return;
     }
     const nextProjectPath = resolveChatProjectPath(localProject);
     if (!nextProjectPath) {
-      if (announceToChat) {
-        announceProjectChatMessage('请先用 /project 设置本地项目。');
-      }
+      onRunNotice?.({
+        tone: 'error',
+        message: '请先用 /project 设置本地项目。',
+      });
       return;
     }
 
@@ -1781,11 +1845,9 @@ export function App({
       );
       if (activePreview) {
         updateClientPreview(activePreview);
-        if (announceToChat) {
-          announceProjectChatMessage(
-            `已切换到客户端运行视图：${activePreview.url}`,
-          );
-        }
+        // 运行成功的反馈走工作台壳的 toast（对话区只保留对话内容），因此不再往聊天里
+        // 写一条「已切换到客户端运行视图：URL」。
+        onRunNotice?.({ message: '已载入客户端运行视图' });
         return;
       }
       const previewResult = await invoke<LocalPreviewResult>(
@@ -1797,16 +1859,19 @@ export function App({
       if (!directProjectMode) {
         void refreshAgentRunTrace(nextProjectPath);
       }
-      if (announceToChat) {
-        announceProjectChatMessage(
-          `运行通过，已载入客户端运行视图：${previewResult.url}`,
-        );
-      }
+      /*
+       * 成功与失败都走工作台壳的 toast，对话区不再承载这条过程反馈，所以这两处不受
+       * `announceToChat` 约束（它是旧的「聊天播报」开关）。当前唯一调用点由播放请求驱动、
+       * 恒为 true（见 `executeRunLocalRef.current(true)`）。
+       */
+      onRunNotice?.({ message: '运行通过，已载入客户端运行视图' });
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (announceToChat) {
-        announceProjectChatMessage(message);
-      }
+      onRunNotice?.({
+        tone: 'error',
+        message: `运行游戏失败：${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      });
     }
   }
 
@@ -2132,11 +2197,6 @@ export function App({
   const chatProjectAssets = manifest.assets.filter(
     (asset) => asset.localPath && !asset.localPath.startsWith('.agent/'),
   );
-  // `@` 面板「当前版本素材」的版本来源：版本列表来自 manifest，
-  // 当前版本由工作台壳（`WorkspaceLauncherShell`）持有的那一份状态给出，
-  // 传 `null` 表示回退到 manifest 中最新的版本。
-  const chatProjectVersions = manifest.versions ?? [];
-  const chatActiveVersionId = activeVersionId;
 
   const visibleMessages = latestVisibleItems(
     messages,
@@ -2239,13 +2299,25 @@ export function App({
     // 普通项目固定走 DirectProject 自己的聊天容器：订阅、历史、发送、队列和附件都由
     // 容器持有，工作台壳只提供项目身份、入口首轮需求和两条权限门。
     return (
-      <DirectProjectChatView
-        ensureConversationReadAllowed={ensureDirectHistoryReadAllowed}
-        ensureConversationWriteAllowed={ensureDirectTurnWriteAllowed}
-        initialTurn={initialDirectTurn}
-        projectPath={localProject?.projectPath ?? projectPath ?? null}
-        ref={directProjectChatRef}
-      />
+      <>
+        <DirectProjectChatView
+          ensureConversationReadAllowed={ensureDirectHistoryReadAllowed}
+          ensureConversationWriteAllowed={ensureDirectTurnWriteAllowed}
+          initialTurn={initialDirectTurn}
+          onRequestGamePublish={
+            gamePublishAllowed ? requestGamePublish : undefined
+          }
+          projectPath={localProject?.projectPath ?? projectPath ?? null}
+          ref={directProjectChatRef}
+        />
+        <GameDistributionPublishPanel
+          open={publishPanelOpen}
+          projectPath={localProject?.projectPath ?? projectPath ?? ''}
+          manifest={manifest}
+          packageResult={publishPackageResult}
+          onClose={() => setPublishPanelOpen(false)}
+        />
+      </>
     );
   }
 
@@ -2253,7 +2325,6 @@ export function App({
     <>
       <PlanningChatView
         initialPlanningPrompt={initialPlanningPrompt}
-        activeVersionId={chatActiveVersionId}
         composerRef={chatComposerRef}
         chatProjectAssets={chatProjectAssets}
         hiddenConversationCount={hiddenConversationCount}
@@ -2383,7 +2454,6 @@ export function App({
         attachmentNotice={chatFileImportNotice}
         importingFiles={chatFilesImporting}
         onUploadFiles={(files) => void handleDesignComposerUploadFiles(files)}
-        versions={chatProjectVersions}
       />
       {runtimeConfigOpen ? (
         <RuntimeConfigDialog
@@ -2391,6 +2461,13 @@ export function App({
           onClose={() => setRuntimeConfigOpen(false)}
         />
       ) : null}
+      <GameDistributionPublishPanel
+        open={publishPanelOpen}
+        projectPath={localProject?.projectPath ?? projectPath ?? ''}
+        manifest={manifest}
+        packageResult={publishPackageResult}
+        onClose={() => setPublishPanelOpen(false)}
+      />
     </>
   );
 }
diff --git a/apps/ai-game-creator-shell/src/app/types.ts b/apps/ai-game-creator-shell/src/app/types.ts
index 210cbd489..227966041 100644
--- a/apps/ai-game-creator-shell/src/app/types.ts
+++ b/apps/ai-game-creator-shell/src/app/types.ts
@@ -801,6 +801,20 @@ export interface LocalProjectExportPackageResult {
   totalBytes: number;
 }
 
+export interface LocalProjectExportPackageFileDigest {
+  path: string;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface LocalProjectExportPackagePayload {
+  packageRelativePath: string;
+  packageBytes: number[];
+  packageSha256: string;
+  packageSizeBytes: number;
+  files: LocalProjectExportPackageFileDigest[];
+}
+
 export interface LocalProjectExportPackageSummary {
   packagePath: string;
   packageRelativePath: string;
diff --git a/apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx b/apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx
new file mode 100644
index 000000000..5f11e3f37
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx
@@ -0,0 +1,511 @@
+import { useEffect, useRef, useState } from 'react';
+
+import type { GameCreationAppManifest } from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import { resolveTauriInvoke } from '../../app/tauri';
+import type { LocalProjectExportPackageResult } from '../../app/types';
+import { uploadPlatformMediaAsset } from '../../services/assetDirectUpload';
+import {
+  createGameDistributionPublishKey,
+  type GameDistributionPublishMetadata,
+  type GameDistributionPublishResult,
+  MAX_AGC_GAME_SCREENSHOTS,
+  publishLocalProjectGame,
+} from '../../services/gameDistributionPublish';
+import { ThemedModal } from '../modal/ThemedModal';
+
+/** 封面与截图都是公开展示素材，限制单张体积，避免手机原图直传拖垮发布流程。 */
+const PANEL_IMAGE_MAX_BYTES = 6 * 1024 * 1024;
+const PANEL_IMAGE_ACCEPT = 'image/png,image/jpeg,image/webp,image/gif';
+
+type PanelImageKind = 'cover' | 'screenshot';
+
+type PanelImageAsset = {
+  /** 文件签名；同一文件重复选择时复用已上传素材，不重复直传。 */
+  signature: string;
+  name: string;
+  assetObjectId: string;
+  previewUrl: string;
+};
+
+function resolvePanelImageLabel(kind: PanelImageKind) {
+  return kind === 'cover' ? '游戏封面' : '游戏截图';
+}
+
+/** 本地预检；服务端仍会独立校验素材归属与图片类型。 */
+function resolvePanelImageFileError(file: File, kind: PanelImageKind) {
+  const label = resolvePanelImageLabel(kind);
+  if (file.size <= 0) return `${label}文件为空，请重新选择`;
+  if (file.size > PANEL_IMAGE_MAX_BYTES) {
+    return `${label}过大，请压缩后再上传（最多 6MB）`;
+  }
+  const contentType = file.type.trim();
+  if (contentType && !contentType.startsWith('image/')) {
+    return `${label}必须是图片文件`;
+  }
+  return '';
+}
+
+function buildPanelImageSignature(file: File, kind: PanelImageKind) {
+  return `${kind}:${file.name}:${file.size}:${file.lastModified}`;
+}
+
+/** 预览只在 WebView 支持 object URL 时生成；否则退回文字占位，不影响上传。 */
+function buildPanelImagePreviewUrl(file: File) {
+  if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') {
+    return '';
+  }
+  try {
+    return URL.createObjectURL(file);
+  } catch {
+    return '';
+  }
+}
+
+const CATEGORIES = [
+  '休闲',
+  '益智',
+  '动作',
+  '冒险',
+  '模拟',
+  '策略',
+  '其他',
+] as const;
+
+export function GameDistributionPublishPanel({
+  open,
+  projectPath,
+  manifest,
+  packageResult,
+  onClose,
+  onPublished,
+}: {
+  open: boolean;
+  projectPath: string;
+  manifest: GameCreationAppManifest;
+  packageResult: LocalProjectExportPackageResult | null;
+  onClose: () => void;
+  onPublished?: (result: GameDistributionPublishResult) => void;
+}) {
+  const [title, setTitle] = useState('');
+  const [summary, setSummary] = useState('');
+  const [category, setCategory] =
+    useState<GameDistributionPublishMetadata['category']>('其他');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+  const [result, setResult] = useState<GameDistributionPublishResult | null>(
+    null,
+  );
+  const [cover, setCover] = useState<PanelImageAsset | null>(null);
+  const [screenshots, setScreenshots] = useState<PanelImageAsset[]>([]);
+  const [uploadingLabel, setUploadingLabel] = useState('');
+  const publishIdempotencyKeyRef = useRef('');
+  const coverInputRef = useRef<HTMLInputElement>(null);
+  const screenshotInputRef = useRef<HTMLInputElement>(null);
+  // 文件签名 → 素材 ID：同一次打开面板重复提交不会重复上传同一张图。
+  const uploadedAssetCacheRef = useRef(new Map<string, string>());
+  const objectUrlsRef = useRef(new Set<string>());
+
+  useEffect(() => {
+    if (!open) return;
+    setTitle(manifest.name.trim());
+    setSummary(
+      (manifest.goal ?? '由陶泥儿创作的可在线游玩游戏').trim().slice(0, 120),
+    );
+    setCategory('其他');
+    setBusy(false);
+    setError('');
+    setResult(null);
+  }, [manifest.goal, manifest.name, open, packageResult?.packageRelativePath]);
+
+  useEffect(() => {
+    if (open) {
+      publishIdempotencyKeyRef.current = createGameDistributionPublishKey();
+    }
+  }, [open, packageResult?.packageRelativePath]);
+
+  useEffect(() => {
+    const objectUrls = objectUrlsRef.current;
+    return () => {
+      objectUrls.forEach((url) => {
+        try {
+          URL.revokeObjectURL(url);
+        } catch {
+          // 预览地址释放失败不影响关闭面板。
+        }
+      });
+      objectUrls.clear();
+    };
+  }, []);
+
+  async function resolveAssetObjectId(file: File, kind: PanelImageKind) {
+    const signature = buildPanelImageSignature(file, kind);
+    const cached = uploadedAssetCacheRef.current.get(signature);
+    if (cached) return cached;
+    const uploaded = await uploadPlatformMediaAsset({
+      file,
+      assetKind:
+        kind === 'cover'
+          ? 'game_distribution_cover'
+          : 'game_distribution_screenshot',
+      pathSegments: ['game-distribution', kind, `${Date.now()}`],
+      entityId: `game-distribution-${kind}`,
+      metadata: { game_distribution_media: kind },
+    });
+    uploadedAssetCacheRef.current.set(signature, uploaded.assetObjectId);
+    return uploaded.assetObjectId;
+  }
+
+  function buildPanelImageAsset(
+    file: File,
+    kind: PanelImageKind,
+    assetObjectId: string,
+  ) {
+    const previewUrl = buildPanelImagePreviewUrl(file);
+    if (previewUrl) objectUrlsRef.current.add(previewUrl);
+    return {
+      signature: buildPanelImageSignature(file, kind),
+      name: file.name.trim() || resolvePanelImageLabel(kind),
+      assetObjectId,
+      previewUrl,
+    };
+  }
+
+  async function handleCoverSelected(file: File | null) {
+    if (!file) return;
+    setError('');
+    const fileError = resolvePanelImageFileError(file, 'cover');
+    if (fileError) {
+      setError(fileError);
+      return;
+    }
+    setUploadingLabel('正在上传封面…');
+    try {
+      const assetObjectId = await resolveAssetObjectId(file, 'cover');
+      setCover(buildPanelImageAsset(file, 'cover', assetObjectId));
+    } catch (uploadError) {
+      setError(
+        uploadError instanceof Error
+          ? uploadError.message
+          : '封面上传失败，请重试',
+      );
+    } finally {
+      setUploadingLabel('');
+      if (coverInputRef.current) coverInputRef.current.value = '';
+    }
+  }
+
+  async function handleScreenshotsSelected(files: File[]) {
+    if (files.length === 0) return;
+    const remaining = MAX_AGC_GAME_SCREENSHOTS - screenshots.length;
+    if (files.length > remaining) {
+      setError(
+        remaining > 0
+          ? `游戏截图最多 6 张，还可以再选 ${remaining} 张`
+          : '游戏截图最多 6 张',
+      );
+      if (screenshotInputRef.current) screenshotInputRef.current.value = '';
+      return;
+    }
+    setError('');
+    setUploadingLabel('正在上传截图…');
+    try {
+      for (const file of files) {
+        const fileError = resolvePanelImageFileError(file, 'screenshot');
+        if (fileError) {
+          setError(fileError);
+          return;
+        }
+        const assetObjectId = await resolveAssetObjectId(file, 'screenshot');
+        // 逐张入库：中途失败时已传好的截图保留，作者不用重新选择。
+        setScreenshots((current) =>
+          current.length >= MAX_AGC_GAME_SCREENSHOTS
+            ? current
+            : [
+                ...current,
+                buildPanelImageAsset(file, 'screenshot', assetObjectId),
+              ],
+        );
+      }
+    } catch (uploadError) {
+      setError(
+        uploadError instanceof Error
+          ? uploadError.message
+          : '截图上传失败，请重试',
+      );
+    } finally {
+      setUploadingLabel('');
+      if (screenshotInputRef.current) screenshotInputRef.current.value = '';
+    }
+  }
+
+  async function handleSubmit() {
+    if (!packageResult || !projectPath.trim()) {
+      setError('请先导出有效的试玩包');
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setError('需要在 Tauri App 内发布');
+      return;
+    }
+    if (!cover) {
+      setError('请先选择游戏封面（JPG/PNG/WebP）');
+      return;
+    }
+    if (uploadingLabel) {
+      setError('素材还在上传中，请稍候再发布');
+      return;
+    }
+    setBusy(true);
+    setError('');
+    try {
+      const next = await publishLocalProjectGame({
+        invoke,
+        projectPath,
+        packageRelativePath: packageResult.packageRelativePath,
+        manifest,
+        metadata: {
+          title,
+          summary,
+          category,
+          coverAssetId: cover.assetObjectId,
+          screenshots: screenshots.map((item) => item.assetObjectId),
+        },
+        idempotencyKey: publishIdempotencyKeyRef.current,
+      });
+      setResult(next);
+      onPublished?.(next);
+    } catch (nextError) {
+      setError(
+        nextError instanceof Error ? nextError.message : String(nextError),
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <ThemedModal
+      open={open}
+      ariaLabel="发布到游戏广场"
+      onClose={busy ? () => undefined : onClose}
+      panelClassName="game-distribution-publish-panel"
+      closeOnBackdrop={!busy}
+      closeOnEscape={!busy}
+    >
+      <header className="game-distribution-publish-panel__header">
+        <div>
+          <span className="game-distribution-publish-panel__eyebrow">
+            发布到游戏广场
+          </span>
+          <h2>让玩家现在就能试玩</h2>
+        </div>
+        <button
+          type="button"
+          onClick={onClose}
+          disabled={busy}
+          aria-label="关闭发布面板"
+        >
+          ×
+        </button>
+      </header>
+      {result ? (
+        <div className="game-distribution-publish-panel__success" role="status">
+          <strong>已提交审核</strong>
+          <p>版本已进入审核队列，审核通过后才会在游戏广场公开展示。</p>
+          <p className="game-distribution-publish-panel__mono">
+            版本 {result.versionNumber} ·{' '}
+            {result.packageSizeBytes.toLocaleString()} B ·{' '}
+            {result.packageSha256.slice(0, 16)}…
+          </p>
+          <div className="game-distribution-publish-panel__actions">
+            <button type="button" onClick={onClose}>
+              完成
+            </button>
+          </div>
+        </div>
+      ) : (
+        <>
+          <p className="game-distribution-publish-panel__intro">
+            仅上传已导出的 ZIP 字节和摘要信息；不会上传本地路径或项目源码快照。
+          </p>
+          <div
+            className="game-distribution-publish-panel__package"
+            aria-label="发行包摘要"
+          >
+            <span>{packageResult?.packageRelativePath ?? '未找到试玩包'}</span>
+            <span>
+              {packageResult
+                ? `${packageResult.fileCount} 个文件 · ${packageResult.totalBytes.toLocaleString()} B`
+                : '请先导出'}
+            </span>
+          </div>
+          <div className="game-distribution-publish-panel__fields">
+            <label>
+              游戏名称
+              <input
+                value={title}
+                maxLength={40}
+                onChange={(event) => setTitle(event.target.value)}
+              />
+            </label>
+            <label>
+              一句话简介
+              <textarea
+                value={summary}
+                maxLength={120}
+                rows={2}
+                onChange={(event) => setSummary(event.target.value)}
+              />
+            </label>
+            <label>
+              分类
+              <select
+                value={category}
+                onChange={(event) =>
+                  setCategory(
+                    event.target
+                      .value as GameDistributionPublishMetadata['category'],
+                  )
+                }
+              >
+                {CATEGORIES.map((item) => (
+                  <option key={item} value={item}>
+                    {item}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+          <div
+            className="game-distribution-publish-panel__media"
+            aria-label="封面与截图"
+          >
+            <div className="game-distribution-publish-panel__cover">
+              <div className="game-distribution-publish-panel__cover-preview">
+                {cover?.previewUrl ? (
+                  <img src={cover.previewUrl} alt="游戏封面预览" />
+                ) : (
+                  <span>{cover ? '封面已上传' : '还没有封面'}</span>
+                )}
+              </div>
+              <label>
+                游戏封面（必需）
+                {/*
+                  原生 file 控件在清空 value 后会显示“未选择任何文件”，与下方提示互相矛盾；
+                  上传后必须清空 value 才能重选同一张图，所以这里改用自定义触发按钮。
+                */}
+                <span className="game-distribution-publish-panel__picker">
+                  <input
+                    ref={coverInputRef}
+                    type="file"
+                    accept={PANEL_IMAGE_ACCEPT}
+                    disabled={busy}
+                    onChange={(event) => {
+                      void handleCoverSelected(event.target.files?.[0] ?? null);
+                    }}
+                  />
+                  <span className="game-distribution-publish-panel__pick">
+                    {cover ? '更换封面图片' : '选择封面图片'}
+                  </span>
+                </span>
+                <span className="game-distribution-publish-panel__hint">
+                  {cover
+                    ? `已选择「${cover.name}」；重新选择即可替换封面。`
+                    : '封面会作为游戏广场卡片与详情页首图，建议 16:9 的 JPG/PNG/WebP，最大 6MB。'}
+                </span>
+              </label>
+              {cover ? (
+                <button
+                  type="button"
+                  onClick={() => setCover(null)}
+                  disabled={busy}
+                >
+                  移除封面
+                </button>
+              ) : null}
+            </div>
+            <label>
+              {`游戏截图（可选，最多 ${MAX_AGC_GAME_SCREENSHOTS} 张）`}
+              <span className="game-distribution-publish-panel__picker">
+                <input
+                  ref={screenshotInputRef}
+                  type="file"
+                  accept={PANEL_IMAGE_ACCEPT}
+                  multiple
+                  disabled={
+                    busy || screenshots.length >= MAX_AGC_GAME_SCREENSHOTS
+                  }
+                  onChange={(event) => {
+                    void handleScreenshotsSelected(
+                      Array.from(event.target.files ?? []),
+                    );
+                  }}
+                />
+                <span className="game-distribution-publish-panel__pick">
+                  {screenshots.length >= MAX_AGC_GAME_SCREENSHOTS
+                    ? '截图已满 6 张'
+                    : '添加截图'}
+                </span>
+              </span>
+              <span className="game-distribution-publish-panel__hint">
+                截图会按选择顺序展示在游戏详情页；不需要可以留空。
+              </span>
+            </label>
+            {screenshots.length > 0 ? (
+              <ul className="game-distribution-publish-panel__shots">
+                {screenshots.map((item, index) => (
+                  <li key={item.signature}>
+                    {item.previewUrl ? (
+                      <img
+                        src={item.previewUrl}
+                        alt={`截图 ${index + 1} 预览`}
+                      />
+                    ) : (
+                      <span>{`截图 ${index + 1}`}</span>
+                    )}
+                    <button
+                      type="button"
+                      disabled={busy}
+                      onClick={() =>
+                        setScreenshots((current) =>
+                          current.filter((_, itemIndex) => itemIndex !== index),
+                        )
+                      }
+                    >
+                      {`移除截图 ${index + 1}`}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+            {uploadingLabel ? (
+              <span className="game-distribution-publish-panel__hint">
+                {uploadingLabel}
+              </span>
+            ) : null}
+          </div>
+          {error ? (
+            <p className="game-distribution-publish-panel__error" role="alert">
+              {error}
+            </p>
+          ) : null}
+          <div className="game-distribution-publish-panel__actions">
+            <button type="button" onClick={onClose} disabled={busy}>
+              稍后再说
+            </button>
+            <button
+              type="button"
+              onClick={() => void handleSubmit()}
+              disabled={
+                busy || !title.trim() || !summary.trim() || !packageResult
+              }
+            >
+              {busy ? '上传中…' : uploadingLabel ? '素材上传中…' : '发布游戏'}
+            </button>
+          </div>
+        </>
+      )}
+    </ThemedModal>
+  );
+}
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/RunNoticeToast.tsx b/apps/ai-game-creator-shell/src/features/app-shell/RunNoticeToast.tsx
new file mode 100644
index 000000000..85e4cc298
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/app-shell/RunNoticeToast.tsx
@@ -0,0 +1,70 @@
+import { PlatformRuntimeStatusToast } from '@genarrative/shared/components';
+import { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+import type { ProjectRunNotice } from './model';
+
+/**
+ * 成功提示一闪而过就够；失败提示要留得够久，用户得看清是什么没跑起来。
+ *
+ * 「运行 / 预览失败」这类错误已经不再写对话区（那里只保留对话内容），所以这枚 toast 是它
+ * 唯一的出口——2.6 秒对错误太短。
+ */
+const RUN_NOTICE_MILLIS: Record<'success' | 'error', number> = {
+  success: 2600,
+  error: 6000,
+};
+
+export type RunNotice = ProjectRunNotice & {
+  /** 每次提示自增，保证重复触发同一个文案时也会重新弹一次。 */
+  id: number;
+};
+
+/**
+ * 运行 / 预览类动作的浮层提示。
+ *
+ * 这类过程反馈以前以 assistant 消息写进对话区，会一直堆在对话底部挡住运行画面；
+ * 现在统一走 toast，对话区只保留对话内容——运行页的预览地址改用顶栏的「在浏览器打开」。
+ */
+export function RunNoticeToast({
+  notice,
+  onDismiss,
+}: {
+  notice: RunNotice | null;
+  onDismiss: () => void;
+}) {
+  useEffect(() => {
+    if (!notice) {
+      return;
+    }
+    const timer = window.setTimeout(
+      onDismiss,
+      RUN_NOTICE_MILLIS[notice.tone ?? 'success'],
+    );
+    return () => {
+      window.clearTimeout(timer);
+    };
+  }, [notice, onDismiss]);
+
+  if (!notice) {
+    return null;
+  }
+  return createPortal(
+    <div
+      key={notice.id}
+      className="pointer-events-none fixed bottom-8 left-1/2 z-[1100] -translate-x-1/2"
+      data-project-run-notice-toast="true"
+    >
+      <PlatformRuntimeStatusToast
+        tone={notice.tone ?? 'success'}
+        surface="solid"
+        size="sm"
+        shape="pill"
+        className="shadow-lg"
+      >
+        {notice.message}
+      </PlatformRuntimeStatusToast>
+    </div>,
+    document.body,
+  );
+}
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx b/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
index aab0ab06b..440107a2d 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
+++ b/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
@@ -42,8 +42,9 @@ import { projectPathsMatchForInvalidation } from '../project-summary/projectPath
 import { RuntimeConfigDialog } from '../runtime-config/RuntimeConfigDialog';
 import { useTemplateLibrary } from '../template-library/useTemplateLibrary';
 import { AccountWalletBar, AccountWalletDialogs } from './AccountWallet';
-import type { WorkspaceLauncherShellProps } from './model';
+import type { ProjectRunNotice, WorkspaceLauncherShellProps } from './model';
 import { NonEmptyProjectDialog, ProjectsPage } from './ProjectCreation';
+import { type RunNotice, RunNoticeToast } from './RunNoticeToast';
 import { useAccountWallet } from './useAccountWallet';
 import {
   DESIGN_ARTIFACTS_BUILD_PROMPT,
@@ -79,6 +80,13 @@ export function WorkspaceLauncherShell({
     title: string;
     message: string;
   } | null>(null);
+  /**
+   * 运行 / 预览类动作的浮层提示。
+   *
+   * 这类过程反馈不进对话区（见 `ProjectChatComponentProps.onRunNotice`），
+   * `id` 每次自增，保证同一句文案连续触发时也会重新弹一次。
+   */
+  const [runNotice, setRunNotice] = useState<RunNotice | null>(null);
   // 「做成游戏」切换记录按项目上下文（路径 + createdAt）定位。运行模式必须随
   // currentProjectContext 同步派生，不能靠 effect 后置修正：首帧挂错 lane 会先
   // 以游戏运行时挂载并消耗首轮 claim，重挂后的策划实例再也发不出首轮。
@@ -615,6 +623,10 @@ export function WorkspaceLauncherShell({
     setLauncherView(view);
   }
 
+  const handleRunNotice = useCallback((notice: ProjectRunNotice) => {
+    setRunNotice((current) => ({ id: (current?.id ?? 0) + 1, ...notice }));
+  }, []);
+
   function showLauncherNotice(title: string) {
     setLauncherNotice({
       title,
@@ -841,6 +853,7 @@ export function WorkspaceLauncherShell({
                   currentProjectContext.projectPath,
                 )
               }
+              onNotice={handleRunNotice}
               onManifestChange={syncActiveProjectManifest}
               onHomeOpen={() => navigateLauncher('home')}
               onProjectsOpen={() => navigateLauncher('projects')}
@@ -872,12 +885,12 @@ export function WorkspaceLauncherShell({
                   initialPlanningPromptClaimScope={
                     switchedToGameRuntime ? 'approved-design-build' : ''
                   }
-                  activeVersionId={activeVersionId}
                   planningStartMode={planningStartMode}
                   playRequest={playRequest}
                   onPlayRequestHandled={handlePlayRequestHandled}
                   onManifestChange={syncActiveProjectManifest}
                   onPreviewChange={setActiveProjectPreview}
+                  onRunNotice={handleRunNotice}
                   onAgentRuntimeSummariesChange={
                     setActiveProjectAgentRuntimeSummaries
                   }
@@ -921,6 +934,7 @@ export function WorkspaceLauncherShell({
       ) : isWindowChrome ? null : (
         <AccountWalletBar controller={accountWallet} />
       )}
+      <RunNoticeToast notice={runNotice} onDismiss={() => setRunNotice(null)} />
       {launcherNotice ? (
         <div
           className="launcher-dialog-backdrop"
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/model.ts b/apps/ai-game-creator-shell/src/features/app-shell/model.ts
index ff0a5acda..ba86f1dcb 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/model.ts
+++ b/apps/ai-game-creator-shell/src/features/app-shell/model.ts
@@ -34,6 +34,17 @@ export type WorkspaceLauncherProps = {
   initialView?: LauncherView;
 };
 
+/**
+ * 运行 / 预览类动作的一次性浮层提示。
+ *
+ * `tone` 只区分观感（成功绿 / 失败红），文案由发出方给出：运行成功、切到运行视图、
+ * 在浏览器打开失败都走这一条通道。
+ */
+export type ProjectRunNotice = {
+  message: string;
+  tone?: 'success' | 'error';
+};
+
 export type ProjectChatComponentProps = {
   initialProjectPath?: string;
   initialProjectManifest?: GameCreationAppManifest;
@@ -48,11 +59,6 @@ export type ProjectChatComponentProps = {
     importing: boolean,
   ) => void;
   planningStartMode?: boolean;
-  /**
-   * C7 当前游戏版本：由工作台壳持有，策划聊天里的 `@` 面板按它切「当前版本素材」。
-   * `null` 表示回退到 manifest 中最新的版本。
-   */
-  activeVersionId?: string | null;
   playRequest?: {
     projectPath: string;
     requestId: number;
@@ -64,6 +70,13 @@ export type ProjectChatComponentProps = {
     metadata?: ProjectManifestSnapshotMetadata,
   ) => void;
   onPreviewChange?: (preview: GameCreationAppPreviewState | null) => void;
+  /**
+   * 运行 / 预览类动作的一次性浮层提示。
+   *
+   * 「跑起来了」「已切到运行视图」「在浏览器打开失败」属于过程反馈，不进对话区——
+   * 对话区只保留对话内容。工作台壳收到后弹 toast，`tone` 决定成功还是失败观感。
+   */
+  onRunNotice?: (notice: ProjectRunNotice) => void;
   onAgentRuntimeSummariesChange?: (
     summaries: ProjectAgentRuntimeSummary[],
   ) => void;
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceChip.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceChip.tsx
index f86fbc6b4..d1cbf408b 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceChip.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceChip.tsx
@@ -2,13 +2,13 @@ import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext
 import { $getNodeByKey, type NodeKey } from 'lexical';
 import { Paperclip, X } from 'lucide-react';
 
-import type { DirectCodexUserAttachmentReferencePart } from '../../view/project-development/chat/generated/DirectCodexUserAttachmentReferencePart';
+import type { AttachmentReference } from './resourceReferences';
 
 export function AttachmentReferenceChip({
   attachment,
   nodeKey,
 }: {
-  attachment: DirectCodexUserAttachmentReferencePart;
+  attachment: AttachmentReference;
   nodeKey: NodeKey;
 }) {
   const [editor] = useLexicalComposerContext();
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceNode.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceNode.tsx
deleted file mode 100644
index 5e4225c38..000000000
--- a/apps/ai-game-creator-shell/src/features/project-workspace/AttachmentReferenceNode.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import {
-  $applyNodeReplacement,
-  DecoratorNode,
-  type EditorConfig,
-  type LexicalNode,
-  type NodeKey,
-  type SerializedLexicalNode,
-  type Spread,
-} from 'lexical';
-import type { ReactNode } from 'react';
-
-import type { DirectCodexUserAttachmentReferencePart } from '../../view/project-development/chat/generated/DirectCodexUserAttachmentReferencePart';
-import { AttachmentReferenceChip } from './AttachmentReferenceChip';
-
-export type SerializedAttachmentReferenceNode = Spread<
-  {
-    attachment: DirectCodexUserAttachmentReferencePart;
-    type: 'attachment-reference';
-    version: 1;
-  },
-  SerializedLexicalNode
->;
-
-/** 附件在纯文本里的唯一占位字符：一个附件 chip 就当一个字符。 */
-const OBJECT_REPLACEMENT = '\uFFFC';
-
-/**
- * Inline canonical attachment part rendered inside the Lexical composer.
- * The node stores the complete part so read-back preserves the project path and status.
- */
-export class AttachmentReferenceNode extends DecoratorNode<ReactNode> {
-  __attachment: DirectCodexUserAttachmentReferencePart;
-
-  static getType() {
-    return 'attachment-reference';
-  }
-
-  static clone(node: AttachmentReferenceNode) {
-    return new AttachmentReferenceNode(node.__attachment, node.__key);
-  }
-
-  static importJSON(serializedNode: SerializedAttachmentReferenceNode) {
-    return $createAttachmentReferenceNode(serializedNode.attachment);
-  }
-
-  constructor(
-    attachment: DirectCodexUserAttachmentReferencePart,
-    key?: NodeKey,
-  ) {
-    super(key);
-    this.__attachment = attachment;
-  }
-
-  exportJSON(): SerializedAttachmentReferenceNode {
-    return {
-      ...super.exportJSON(),
-      attachment: this.__attachment,
-      type: 'attachment-reference',
-      version: 1,
-    };
-  }
-
-  createDOM(_config: EditorConfig) {
-    return document.createElement('span');
-  }
-
-  updateDOM() {
-    return false;
-  }
-
-  getTextContent() {
-    return OBJECT_REPLACEMENT;
-  }
-
-  getTextContentSize() {
-    return OBJECT_REPLACEMENT.length;
-  }
-
-  isInline() {
-    return true;
-  }
-
-  isKeyboardSelectable() {
-    return true;
-  }
-
-  decorate() {
-    return (
-      <AttachmentReferenceChip
-        attachment={this.__attachment}
-        nodeKey={this.__key}
-      />
-    );
-  }
-}
-
-export function $createAttachmentReferenceNode(
-  attachment: DirectCodexUserAttachmentReferencePart,
-) {
-  return $applyNodeReplacement(new AttachmentReferenceNode(attachment));
-}
-
-export function $isAttachmentReferenceNode(
-  node: LexicalNode | null | undefined,
-): node is AttachmentReferenceNode {
-  return node instanceof AttachmentReferenceNode;
-}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceChip.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceChip.tsx
index 80a5d81c3..c67090dc2 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceChip.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceChip.tsx
@@ -11,9 +11,20 @@ function chipTitle(reference: ChatReference) {
   if (reference.type === 'skill') {
     return `${reference.name} · Skill`;
   }
+  if (reference.type === 'attachment') {
+    return `${reference.name} · 附件`;
+  }
   return `${reference.label} · 运行区域`;
 }
 
+/** chip 显示的引用名：附件有自己的芯片（`AttachmentReferenceChip`），这里只是把联合收窄。 */
+function chipLabel(reference: ChatReference) {
+  if (reference.type === 'skill' || reference.type === 'attachment') {
+    return reference.name;
+  }
+  return reference.label;
+}
+
 export function ResourceReferenceChip({
   reference,
   nodeKey,
@@ -39,11 +50,11 @@ export function ResourceReferenceChip({
     >
       <span aria-hidden="true">{reference.type === 'skill' ? '$' : '@'}</span>
       <span className="resource-reference-chip-label">
-        {reference.type === 'skill' ? reference.name : reference.label}
+        {chipLabel(reference)}
       </span>
       <button
         type="button"
-        aria-label={`移除引用 ${reference.type === 'skill' ? reference.name : reference.label}`}
+        aria-label={`移除引用 ${chipLabel(reference)}`}
         onMouseDown={(event) => event.preventDefault()}
         onClick={() => {
           editor.update(() => {
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx
index 1d9adf5e6..ad0cb2396 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx
@@ -19,23 +19,13 @@ import {
   COMMAND_PRIORITY_HIGH,
   type EditorState,
   KEY_ENTER_COMMAND,
-  KEY_ESCAPE_COMMAND,
   type LexicalNode,
   type TextNode,
 } from 'lexical';
-import {
-  AtSign,
-  Check,
-  FileText,
-  Image as ImageIcon,
-  Loader2,
-  Music2,
-  RotateCcw,
-  Sparkles,
-  Video,
-} from 'lucide-react';
+import { Loader2, RotateCcw, Sparkles } from 'lucide-react';
 import {
   forwardRef,
+  type ReactNode,
   type Ref,
   type RefObject,
   useCallback,
@@ -47,27 +37,8 @@ import {
 } from 'react';
 import { createPortal } from 'react-dom';
 
-import { PlatformResourceFilterBar } from '../../../../../packages/shared/src/components/PlatformResourceFilterBar';
-import { PlatformSegmentedTabs } from '../../../../../packages/shared/src/components/PlatformSegmentedTabs';
-import {
-  type GameCreationAppAssetManifestEntry,
-  gameCreationAppAssetTags,
-  type GameIterationVersion,
-  isGameCreationAppUiDesignDocAsset,
-} from '../../../../../packages/shared/src/contracts/gameCreationApp';
-import { resolveTauriInvoke } from '../../app/tauri';
 import RichTextInput from '../../components/RichTextInput';
-import {
-  cancelLocalProjectResourcePreviewScope,
-  createProjectResourcePreviewRequestId,
-  createProjectResourcePreviewScopeId,
-} from '../../services/projectResourcePreviewTransport';
 import type { DirectCodexUserContentPart } from '../../view/project-development/chat/generated/DirectCodexUserContentPart';
-import {
-  $createAttachmentReferenceNode,
-  $isAttachmentReferenceNode,
-  AttachmentReferenceNode,
-} from './AttachmentReferenceNode';
 import {
   chatPromptDraftKey,
   readChatPromptPolishReminderDisabled,
@@ -75,6 +46,7 @@ import {
   writeChatPromptPolishReminderDisabled,
 } from './chatPromptPolish';
 import { ChatPromptPolishReminder } from './ChatPromptPolishReminder';
+import type { ReferenceProvider } from './reference-source/types';
 import {
   $createResourceReferenceNode,
   $isResourceReferenceNode,
@@ -84,24 +56,12 @@ import {
   buildContentFromTextTokens,
   type ChatComposerDraft,
   type ChatReference,
+  chatReferenceDisplayHint,
+  chatReferenceKey,
+  chatReferenceMentionToken,
   chatReferenceToContentPart,
-  contentPartMentionToken,
-  currentIterationVersionAssets,
   dedupeChatReferences,
-  directCodexContentToPromptText,
-  refreshResourceReference,
-  RESOURCE_REFERENCE_FILTERS,
-  RESOURCE_REFERENCE_SCOPES,
-  type ResourceReference,
-  resourceReferenceCategoryLabel,
-  type ResourceReferenceFilter,
-  resourceReferenceFromAsset,
-  resourceReferenceMatchesCategoryFilter,
-  resourceReferenceMatchesQuery,
-  resourceReferenceMatchesTagSelection,
-  type ResourceReferenceScope,
-  resourceReferenceTagLibrary,
-  type SkillReference,
+  joinMentionText,
 } from './resourceReferences';
 import { usePromptPolish } from './usePromptPolish';
 
@@ -109,23 +69,23 @@ type ResourceReferenceInputProps = {
   onChange?: (draft: ChatComposerDraft) => void;
   onEditorStateChange?: (editorState: EditorState) => void;
   initialContent?: DirectCodexUserContentPart[];
-  assets: GameCreationAppAssetManifestEntry[];
-  skills?: SkillReference[];
-  projectPath: string;
   /**
-   * `@` 面板「当前版本素材」页签使用的版本 id。
-   * 没传 / `null` 时回退到 manifest `versions[]` 中最新的那个版本；
-   * 版本不存在或没有绑定资源时该页签显示空态。
+   * 宿主注入的引用来源，**按数组顺序取第一个非空回答**。
+   *
+   * 输入区不认识任何引用种类：候选菜单按各 provider 的触发符动态派生，part 的身份解析、
+   * 改名刷新与正文文本形态也都问它们。没注入就没有这类引用——只注入资源 provider 就只有 `@`。
    */
-  activeVersionId?: string | null;
-  /** manifest 的正式版本列表，用于解析「当前版本素材」。 */
-  versions?: GameIterationVersion[];
+  providers: readonly ReferenceProvider[];
+  /**
+   * 项目路径只给输入区自己的润色链路用（润色服务按项目上下文改写提示词）。
+   * 引用候选与素材选择器都不再从这里拿数据。
+   */
+  projectPath: string;
   disabled?: boolean;
   placeholder?: string;
   ariaLabel: string;
   multiline?: boolean;
   rows?: number;
-  showTriggerButton?: boolean;
   /**
    * 内置「AI 润色 / 恢复原文」动作是否渲染，默认 `true`。
    *
@@ -134,40 +94,21 @@ type ResourceReferenceInputProps = {
    * 避免同一个面板里出现两个润色入口。
    */
   showPolishAction?: boolean;
+  /**
+   * 宿主的外部浮层（素材选择器）打开时为 `true`：Enter 让位给下层默认行为，不提交表单。
+   * 与候选菜单打开时的处置同一口径。
+   */
+  submitSuppressed?: boolean;
+  /** 输入区操作排（编辑器右侧那一列）里宿主注入的内容，例如素材选择器的 `@` 触发钮。 */
+  inputActions?: ReactNode;
   inputRef?: RefObject<HTMLDivElement | null>;
+  /** 输入区容器元素：宿主定位自己的浮层时用它当锚点。 */
+  containerRef?: RefObject<HTMLDivElement | null>;
 };
 
-type ResourcePickerScopeState = {
-  query: string;
-  filter: ResourceReferenceFilter;
-  selectedResourceIds: string[];
-  /** 已选标签（多选），与搜索词、功能分类三者叠加生效。 */
-  selectedTags: string[];
-};
-
-function createResourcePickerScopeState(): ResourcePickerScopeState {
-  return {
-    query: '',
-    filter: 'all',
-    selectedResourceIds: [],
-    selectedTags: [],
-  };
-}
-
-function createResourcePickerScopeStates(): Record<
-  ResourceReferenceScope,
-  ResourcePickerScopeState
-> {
-  return {
-    'current-version': createResourcePickerScopeState(),
-    'all-canvas': createResourcePickerScopeState(),
-  };
-}
-
 export type ResourceReferenceInputHandle = {
   insertReferences: (references: ChatReference[]) => void;
   insertText: (text: string) => void;
-  openPicker: () => void;
   focus: () => void;
   clear: () => void;
   replaceText: (text: string) => void;
@@ -175,21 +116,18 @@ export type ResourceReferenceInputHandle = {
   getDraft: () => ChatComposerDraft;
 };
 
-class ResourceMentionOption extends MenuOption {
-  reference: ResourceReference;
+class ReferenceMentionOption extends MenuOption {
+  reference: ChatReference;
+  label: string;
+  hint: string;
 
-  constructor(reference: ResourceReference) {
-    super(reference.resourceId);
+  constructor(reference: ChatReference) {
+    // key 必须是引用的唯一身份：显示 token（`@显示名`）不唯一，同名素材会撞 key 并让
+    // React 复用错 DOM、键盘高亮落到别的候选上。显示 token 只留给 `label`。
+    super(chatReferenceKey(reference));
     this.reference = reference;
-  }
-}
-
-class SkillMentionOption extends MenuOption {
-  skill: SkillReference;
-
-  constructor(skill: SkillReference) {
-    super(skill.name);
-    this.skill = skill;
+    this.label = chatReferenceMentionToken(reference);
+    this.hint = chatReferenceDisplayHint(reference);
   }
 }
 
@@ -199,7 +137,6 @@ class SkillMentionOption extends MenuOption {
  * 有效输入只在整条 content 上判定（`hasMeaningfulDirectCodexContent` 与 Rust
  * `validate_direct_codex_user_item` 同口径），前端不替用户改写他输入了什么。
  */
-
 function collectDraftParts(
   node: LexicalNode,
   references: ChatReference[],
@@ -217,10 +154,6 @@ function collectDraftParts(
     content.push({ type: 'input_text', text: '\n' });
     return;
   }
-  if ($isAttachmentReferenceNode(node)) {
-    content.push({ type: 'agc_attachment_reference', ...node.__attachment });
-    return;
-  }
   if ($isResourceReferenceNode(node)) {
     references.push(node.__reference);
     content.push(chatReferenceToContentPart(node.__reference));
@@ -269,10 +202,49 @@ export function readResourceReferenceDraft(
   return editorState.read(readDraftFromNodes);
 }
 
+/** 第一个认得这个 part 的 provider 给出的引用；都不认得时返回 `null`。 */
+function referenceFromPart(
+  providers: readonly ReferenceProvider[],
+  part: DirectCodexUserContentPart,
+): ChatReference | null {
+  for (const provider of providers) {
+    const reference = provider.toReference(part);
+    if (reference) return reference;
+  }
+  return null;
+}
+
+/** 第一个认得这个 part 的 provider 给出的正文 token；都不认得（例如文本 part）时返回 `null`。 */
+function mentionTokenFromPart(
+  providers: readonly ReferenceProvider[],
+  part: DirectCodexUserContentPart,
+): string | null {
+  for (const provider of providers) {
+    const token = provider.mentionToken(part);
+    if (token) return token;
+  }
+  return null;
+}
+
+/**
+ * 草稿的展示文本：把每个引用 part 按注入的 provider 展开成它的 token，其余文本逐字保留。
+ *
+ * 与出站（发给润色服务 / 队列 chip / agent）的口径是同一份 `joinMentionText`：
+ * 所以润色回包还能按同一批 token 原位换回真 part，不需要第二套文本口径。
+ */
+function promptTextFromContent(
+  providers: readonly ReferenceProvider[],
+  content: readonly DirectCodexUserContentPart[],
+): string {
+  return joinMentionText(content, (part) =>
+    mentionTokenFromPart(providers, part),
+  );
+}
+
 /**
  * 润色回写：回包文本里还剩哪个 token，就在那个位置换回真的 part——引用与附件同一套扫描
- * 口径（`contentPartMentionToken`），所以润色改过的那段文字里如果还留着 `@显示名` / `$名称` /
- * `@附件名`，chip 原位复活；整体被改写的那些 part 补在末尾，不丢。
+ * 口径（provider 的 `mentionToken`），所以润色改过的那段文字里如果还留着 `@显示名` /
+ * `$名称` / `@附件名`，chip 原位复活；整体被改写的那些 part 补在末尾，不丢。
  *
  * TODO: 润色服务整体改写文本、把 `@名称` token 也删掉时，前端无法反推原位置，只能补在末尾。
  * 需要“润色精确恢复引用/附件原位置”时，由产品补一个带位置信息的润色协议，不在前端猜字符串。
@@ -280,56 +252,20 @@ export function readResourceReferenceDraft(
 function applyPolishedTextToRoot(
   value: string,
   current: DraftProjection,
-  assetsById: ReadonlyMap<string, GameCreationAppAssetManifestEntry>,
+  providers: readonly ReferenceProvider[],
 ) {
-  const resourceLabels = new Map(
-    current.references.flatMap((reference) =>
-      reference.type === 'resource'
-        ? [[reference.resourceId, reference.label] as const]
-        : [],
-    ),
-  );
   // 候选按 canonical content 原顺序取：引用、Skill、runtime 区域与附件共用一套 token 扫描，
   // 与出站给润色服务的文本口径一致，因此回包保留下来的 token 能原位换回真 part。
   const candidates = current.content.flatMap((part) => {
-    const token = contentPartMentionToken(part, resourceLabels);
+    const token = mentionTokenFromPart(providers, part);
     return token ? [{ token, part }] : [];
   });
-  applyContentToRoot(buildContentFromTextTokens(value, candidates), assetsById);
-}
-
-function referenceFromContentPart(
-  part: DirectCodexUserContentPart,
-  assetsById: ReadonlyMap<string, GameCreationAppAssetManifestEntry>,
-): ChatReference | null {
-  if (part.type === 'agc_resource_reference') {
-    const asset = assetsById.get(part.resourceId);
-    return asset ? resourceReferenceFromAsset(asset, 'asset-picker') : null;
-  }
-  if (part.type === 'agc_skill_reference') {
-    return { type: 'skill', name: part.name };
-  }
-  if (part.type === 'agc_runtime_region_reference') {
-    return {
-      type: 'runtime-region',
-      label: part.label,
-      runId: part.runId ?? undefined,
-      versionId: part.versionId ?? undefined,
-      elementTag: part.elementTag ?? undefined,
-      elementRole: part.elementRole ?? undefined,
-      text: part.text ?? undefined,
-      width: part.width ?? undefined,
-      height: part.height ?? undefined,
-      resourceIds: part.resourceIds,
-      source: 'runtime-picker',
-    };
-  }
-  return null;
+  applyContentToRoot(buildContentFromTextTokens(value, candidates), providers);
 }
 
 function applyContentToRoot(
   content: readonly DirectCodexUserContentPart[],
-  assetsById: ReadonlyMap<string, GameCreationAppAssetManifestEntry>,
+  providers: readonly ReferenceProvider[],
 ) {
   const root = $getRoot();
   root.clear();
@@ -347,86 +283,18 @@ function applyContentToRoot(
       });
       return;
     }
-    if (part.type === 'agc_attachment_reference') {
-      paragraph.append($createAttachmentReferenceNode(part));
-      return;
-    }
-    const reference = referenceFromContentPart(part, assetsById);
+    const reference = referenceFromPart(providers, part);
     if (reference) {
       paragraph.append($createResourceReferenceNode(reference));
     }
   });
 }
 
-function isMentionableAsset(asset: GameCreationAppAssetManifestEntry) {
-  return Boolean(asset.localPath) && !asset.localPath.startsWith('.agent/');
-}
-
 /**
- * 引用显示名只由 manifest 资产内容决定，而调用方每次渲染都会重建 assets 数组，
- * 这里用内容签名做依赖，避免与改名无关的渲染反复刷新已有引用。
+ * 引用身份刷新（资源改名等）：每个节点问第一个认得它的 provider 要新引用，
+ * 拿到不同实例就换成新节点。providers 原样返回表示无需改写。
  */
-function assetsSignature(assets: readonly GameCreationAppAssetManifestEntry[]) {
-  return assets
-    .map((asset) =>
-      [
-        asset.id,
-        asset.kind,
-        asset.mediaType,
-        asset.localPath,
-        asset.category ?? '',
-        gameCreationAppAssetTags(asset).join(','),
-      ].join('\u0000'),
-    )
-    .join('\u0001');
-}
-
-function mentionableAssetReferences(
-  assets: GameCreationAppAssetManifestEntry[],
-  source: ResourceReference['source'],
-) {
-  return assets
-    .filter(isMentionableAsset)
-    .map((asset) => resourceReferenceFromAsset(asset, source));
-}
-
-/**
- * 版本列表的内容签名：「当前版本素材」只由版本 id、顺序与绑定资源决定，
- * 按签名取依赖才能跳过与版本无关的渲染。
- */
-function iterationsSignature(
-  versions: readonly GameIterationVersion[] | undefined,
-) {
-  return (versions ?? [])
-    .map(
-      (version) =>
-        `${version.versionId}\u0002${version.resourceBindings
-          .map((binding) => binding.resourceId)
-          .join(',')}`,
-    )
-    .join('\u0001');
-}
-
-/** `@` 面板空态文案：先分「这个范围本来就没有素材」和「筛完没有命中」两件事。 */
-function pickerEmptyMessage(
-  scopeReferenceCount: number,
-  scope: ResourceReferenceScope,
-) {
-  if (scopeReferenceCount > 0) {
-    return '没有匹配的素材';
-  }
-  return scope === 'current-version'
-    ? '当前版本还没有绑定素材'
-    : '当前项目还没有已登记素材';
-}
-
-/**
- * 资源改名后把编辑区里已有的引用 chip 刷成 manifest 的最新显示名。
- * 只改写仍能找到对应资产的引用；已删除资源保持原引用，不合成资源卡。
- */
-function $staleResourceReferenceNodes(
-  assetsById: ReadonlyMap<string, GameCreationAppAssetManifestEntry>,
-) {
+function $refreshReferenceNodes(providers: readonly ReferenceProvider[]) {
   const staleNodes: {
     node: ResourceReferenceNode;
     reference: ChatReference;
@@ -437,13 +305,14 @@ function $staleResourceReferenceNodes(
       if (!$isElementNode(block)) return;
       block.getChildren().forEach((child) => {
         if (!$isResourceReferenceNode(child)) return;
-        if (child.__reference.type !== 'resource') return;
-        const nextReference = refreshResourceReference(
-          child.__reference,
-          assetsById,
-        );
-        if (nextReference === child.__reference) return;
-        staleNodes.push({ node: child, reference: nextReference });
+        for (const provider of providers) {
+          const nextReference = provider.refresh(child.__reference);
+          if (!nextReference) continue;
+          if (nextReference !== child.__reference) {
+            staleNodes.push({ node: child, reference: nextReference });
+          }
+          return;
+        }
       });
     });
   return staleNodes;
@@ -453,15 +322,13 @@ function ResourceReferenceEditor({
   onChange,
   onEditorStateChange,
   initialContent,
-  assets,
-  skills = [],
+  providers,
   projectPath,
-  activeVersionId = null,
-  versions,
   disabled,
   multiline,
-  showTriggerButton = true,
   showPolishAction = true,
+  submitSuppressed = false,
+  inputActions,
   composerRef,
   rootRef,
 }: ResourceReferenceInputProps & {
@@ -470,176 +337,25 @@ function ResourceReferenceEditor({
 }) {
   const [editor] = useLexicalComposerContext();
   const skipInitialDraftChangeRef = useRef(false);
-  const [query, setQuery] = useState<string | null>(null);
-  const [skillQuery, setSkillQuery] = useState<string | null>(null);
-  const [builtinSkills, setBuiltinSkills] = useState<SkillReference[]>([]);
-  const [clientSkills, setClientSkills] = useState<SkillReference[]>([]);
-  const skillCatalogRequestedRef = useRef(false);
-  const [pickerOpen, setPickerOpen] = useState(false);
+  // providers 每次渲染都可能是新数组（宿主按 assets 派生）。回调和命令处理只经 ref 读最新值，
+  // 避免因为 identity 变化反复重注册 HIGH 优先级命令。
+  const providersRef = useRef(providers);
+  providersRef.current = providers;
+  const submitSuppressedRef = useRef(submitSuppressed);
+  submitSuppressedRef.current = submitSuppressed;
   // Enter 提交要避开候选浮层。用 ref 让命令处理器读到最新状态，不必因为
-  // query / pickerOpen 变化反复重注册 HIGH 优先级命令。
+  // 打开哪个菜单、宿主的浮层开关变化反复重注册 HIGH 优先级命令。
   const mentionMenuOpenRef = useRef(false);
-  const pickerVisibleRef = useRef(false);
-  useEffect(() => {
-    mentionMenuOpenRef.current = query !== null || skillQuery !== null;
-  }, [query, skillQuery]);
-  useEffect(() => {
-    pickerVisibleRef.current = pickerOpen;
-  }, [pickerOpen]);
-  const [pickerScopeStates, setPickerScopeStates] = useState<
-    Record<ResourceReferenceScope, ResourcePickerScopeState>
-  >(createResourcePickerScopeStates);
-  const [pickerScopeOverride, setPickerScopeOverride] =
-    useState<ResourceReferenceScope | null>(null);
-  const [pickerPosition, setPickerPosition] = useState<{
-    left: number;
-    top: number;
-    width: number;
-    maxHeight: number;
-  } | null>(null);
-  // Skill 清单来自宿主：只在用户真正打开 `$` 候选时查一次。输入区挂载即发起
-  // Tauri 调用会让「工作区路径非法时不产生任何后端访问」的边界失效。
-  // 查询失败时放开 requested 标记：一次瞬时失败不能让这个输入区此后永远拿不到技能候选。
-  useEffect(() => {
-    if (skillQuery === null || skillCatalogRequestedRef.current) return;
-    const invoke = resolveTauriInvoke();
-    if (!invoke) return;
-    skillCatalogRequestedRef.current = true;
-    void invoke<Array<{ name: string; description: string }>>(
-      'list_agc_skill_catalog',
-    )
-      .then((items) => {
-        setBuiltinSkills(
-          items.map((item) => ({
-            type: 'skill' as const,
-            name: item.name,
-            description: item.description,
-          })),
-        );
-      })
-      .catch(() => {
-        skillCatalogRequestedRef.current = false;
-        setBuiltinSkills([]);
-      });
-    void invoke<
-      Array<{
-        name: string;
-        extensionType: string;
-        enabled: boolean;
-        status: string;
-      }>
-    >('list_client_extensions')
-      .then((items) => {
-        setClientSkills(
-          items
-            .filter(
-              (item) =>
-                item.extensionType === 'skill' &&
-                item.enabled &&
-                item.status === 'enabled',
-            )
-            .map((item) => ({ type: 'skill' as const, name: item.name })),
-        );
-      })
-      .catch(() => {
-        skillCatalogRequestedRef.current = false;
-        setClientSkills([]);
-      });
-  }, [skillQuery]);
+  const openMenuTriggersRef = useRef<Set<string>>(new Set());
 
-  const assetsContentSignature = assetsSignature(assets);
-  const versionsContentSignature = iterationsSignature(versions);
-  const assetsById = useMemo(
-    () => new Map(assets.map((asset) => [asset.id, asset])),
-    // 依赖内容签名：assets 数组身份每次渲染都会变，内容不变时没必要重建索引。
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [assetsContentSignature],
-  );
-  const assetReferences = useMemo(
-    () => mentionableAssetReferences(assets, 'asset-picker'),
-    // 依赖内容签名：调用方每次渲染都会重建 assets 数组，内容不变时没必要重算。
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [assetsContentSignature],
-  );
-  const currentVersionAssetReferences = useMemo(
-    () =>
-      mentionableAssetReferences(
-        currentIterationVersionAssets(assets, versions, activeVersionId),
-        'version-asset',
-      ),
-    // 同上：versions 数组身份同样每次渲染都换，按内容签名取依赖才真的能跳过。
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [activeVersionId, assetsContentSignature, versionsContentSignature],
-  );
-  // 两个页签的默认落点：当前版本确实绑定了已登记素材时优先展示「当前版本素材」，
-  // 否则落到「全部画布素材」，避免没有版本的项目一打开就是空列表。
-  const defaultPickerScope: ResourceReferenceScope =
-    currentVersionAssetReferences.length > 0 ? 'current-version' : 'all-canvas';
-  const pickerScope = pickerScopeOverride ?? defaultPickerScope;
-  const pickerScopeState = pickerScopeStates[pickerScope];
-  const pickerQuery = pickerScopeState.query;
-  const pickerFilter = pickerScopeState.filter;
-  const selectedResourceIds = pickerScopeState.selectedResourceIds;
-  const selectedTags = pickerScopeState.selectedTags;
-
-  const scopeReferences =
-    pickerScope === 'current-version'
-      ? currentVersionAssetReferences
-      : assetReferences;
-
-  // 标签库按当前页签的候选派生：两个页签各自一份，标签与计数都不跨页签串。
-  const scopeTagItems = useMemo(
-    () => resourceReferenceTagLibrary(scopeReferences),
-    [scopeReferences],
-  );
-
-  const updatePickerScopeState = useCallback(
-    (patch: Partial<ResourcePickerScopeState>) => {
-      setPickerScopeStates((current) => ({
-        ...current,
-        [pickerScope]: { ...current[pickerScope], ...patch },
-      }));
-    },
-    [pickerScope],
-  );
-
-  const mentionOptions = useMemo(() => {
-    if (query === null) return [];
-    return assetReferences
-      .filter((reference) => resourceReferenceMatchesQuery(reference, query))
-      .slice(0, 8)
-      .map((reference) => new ResourceMentionOption(reference));
-  }, [assetReferences, query]);
-
-  const skillOptions = useMemo(() => {
-    if (skillQuery === null) return [];
-    const normalized = skillQuery.trim().toLowerCase();
-    const allSkills = [...builtinSkills, ...clientSkills, ...skills];
-    const seen = new Set<string>();
-    return allSkills
-      .filter((skill) => {
-        if (seen.has(skill.name)) return false;
-        seen.add(skill.name);
-        return (
-          !normalized ||
-          skill.name.toLowerCase().includes(normalized) ||
-          skill.description?.toLowerCase().includes(normalized)
-        );
-      })
-      .slice(0, 8)
-      .map((skill) => new SkillMentionOption(skill));
-  }, [builtinSkills, clientSkills, skillQuery, skills]);
-
-  const triggerFn = useBasicTypeaheadTriggerMatch('@', {
-    minLength: 0,
-    maxLength: 64,
-    allowWhitespace: false,
-  });
-  const skillTriggerFn = useBasicTypeaheadTriggerMatch('$', {
-    minLength: 0,
-    maxLength: 64,
-    allowWhitespace: false,
-  });
+  const handleMenuOpenChange = useCallback((trigger: string, open: boolean) => {
+    if (open) {
+      openMenuTriggersRef.current.add(trigger);
+    } else {
+      openMenuTriggersRef.current.delete(trigger);
+    }
+    mentionMenuOpenRef.current = openMenuTriggersRef.current.size > 0;
+  }, []);
 
   const insertReferences = useCallback(
     (nextReferences: ChatReference[]) => {
@@ -669,12 +385,6 @@ function ResourceReferenceEditor({
     [editor],
   );
 
-  const openPicker = useCallback(() => {
-    setPickerScopeStates(createResourcePickerScopeStates());
-    setPickerScopeOverride(null);
-    setPickerOpen(true);
-  }, []);
-
   const insertText = useCallback(
     (text: string) => {
       const insert = text.replace(/\s+$/u, '');
@@ -699,29 +409,35 @@ function ResourceReferenceEditor({
     [editor],
   );
 
+  const applyContent = useCallback(
+    (content: readonly DirectCodexUserContentPart[]) => {
+      applyContentToRoot(content, providersRef.current);
+    },
+    [],
+  );
+
   useImperativeHandle(
     composerRef,
     () => ({
       insertReferences,
       insertText,
-      openPicker,
       focus: () => editor.focus(),
       clear: () => {
         editor.update(() => {
-          applyContentToRoot([], assetsById);
+          applyContent([]);
           $getRoot().selectEnd();
         });
       },
       replaceText: (text: string) => {
         editor.update(() => {
           const current = readDraftProjectionFromNodes();
-          applyPolishedTextToRoot(text, current, assetsById);
+          applyPolishedTextToRoot(text, current, providersRef.current);
           $getRoot().selectEnd();
         });
       },
       getDraft: () => readResourceReferenceDraft(editor.getEditorState()),
     }),
-    [assetsById, editor, insertReferences, insertText, openPicker],
+    [applyContent, editor, insertReferences, insertText],
   );
 
   useEffect(() => {
@@ -733,52 +449,51 @@ function ResourceReferenceEditor({
     if (initialDraftAppliedRef.current || !initialContent) {
       return;
     }
-    // Manifest assets can arrive after the initial editor mount. Do not mark the
-    // draft as applied while resource references still have no lookup table;
-    // otherwise the later assetsById update cannot restore those references.
-    const hasUnresolvedResourceReference = initialContent.some(
+    // provider 的数据可能晚于编辑器挂载到达（例如 manifest 还在加载）。
+    // 草稿里已经有它认不出、但它迟早能认出来的 part 时先不落：落下就等于把那条引用静默丢掉。
+    const hasUnresolvedPart = initialContent.some(
       (part) =>
-        part.type === 'agc_resource_reference' &&
-        !assetsById.has(part.resourceId),
+        part.type !== 'input_text' &&
+        referenceFromPart(providers, part) === null,
     );
-    if (hasUnresolvedResourceReference && assetsById.size === 0) {
+    const pendingProvider = providers.some(
+      (provider) => provider.isReady && !provider.isReady(),
+    );
+    if (hasUnresolvedPart && pendingProvider) {
       return;
     }
-    // TODO: let the Lexical resource node resolve its asset label from the
-    // manifest itself, so unresolved references can remain as nodes while the
-    // manifest loads instead of waiting in this effect.
     initialDraftAppliedRef.current = true;
     editor.update(() => {
-      applyContentToRoot(initialContent, assetsById);
+      applyContent(initialContent);
       skipInitialDraftChangeRef.current = initialContent.length > 0;
       $getRoot().selectEnd();
     });
-  }, [assetsById, editor, initialContent]);
+  }, [applyContent, editor, initialContent, providers]);
 
-  // 资源改名后刷新已有引用 chip 的显示名：改写节点会触发 OnChangePlugin，
+  // 引用身份变化（资源改名）后刷新已有 chip 的显示名：改写节点会触发 OnChangePlugin，
   // 把带新显示名的草稿同步回父级，chip 与候选列表都不会残留旧名。
   // Lexical 的更新可能排到微任务里提交，这里额外挂一次更新监听兜底。
-  const refreshResourceReferenceLabels = useCallback(() => {
-    if (assetsById.size === 0) return;
+  const refreshReferenceLabels = useCallback(() => {
     const hasStaleReferences = editor
       .getEditorState()
-      .read(() => $staleResourceReferenceNodes(assetsById).length > 0);
+      .read(() => $refreshReferenceNodes(providersRef.current).length > 0);
     if (!hasStaleReferences) return;
     editor.update(() => {
-      $staleResourceReferenceNodes(assetsById).forEach(
+      $refreshReferenceNodes(providersRef.current).forEach(
         ({ node, reference }) => {
           node.replace($createResourceReferenceNode(reference));
         },
       );
     });
-  }, [assetsById, editor]);
+  }, [editor]);
 
   useEffect(() => {
-    refreshResourceReferenceLabels();
+    refreshReferenceLabels();
     return editor.registerUpdateListener(() => {
-      refreshResourceReferenceLabels();
+      refreshReferenceLabels();
     });
-  }, [editor, refreshResourceReferenceLabels]);
+    // providers 一并当依赖：宿主刚把新清单换进来时立刻刷一次，不必等下一次编辑。
+  }, [editor, providers, refreshReferenceLabels]);
 
   // Enter 提交只属于单行输入区（聊天 / 项目总控）。多行输入区（资源卡快速编辑提示词）
   // 的 Enter 必须留给换行，否则用户没法在提示词里分行。
@@ -791,11 +506,11 @@ function ResourceReferenceEditor({
           !event ||
           event.shiftKey ||
           event.isComposing ||
-          // 候选菜单 / 选择器开着时 Enter 属于它们：返回 false 把按键让给
-          // LexicalTypeaheadMenuPlugin（它在 NORMAL 优先级选候选），
+          // 候选菜单 / 宿主的素材选择器开着时 Enter 属于它们：返回 false 把按键让给
+          // 下层默认行为（LexicalTypeaheadMenuPlugin 在 NORMAL 优先级用 Enter 选候选），
           // 而不是在 HIGH 优先级抢先提交表单。
           mentionMenuOpenRef.current ||
-          pickerVisibleRef.current
+          submitSuppressedRef.current
         ) {
           return false;
         }
@@ -807,63 +522,6 @@ function ResourceReferenceEditor({
     );
   }, [editor, multiline]);
 
-  useEffect(
-    () =>
-      editor.registerCommand(
-        KEY_ESCAPE_COMMAND,
-        () => {
-          if (!pickerOpen) return false;
-          setPickerOpen(false);
-          return true;
-        },
-        COMMAND_PRIORITY_HIGH,
-      ),
-    [editor, pickerOpen],
-  );
-
-  const insertReferenceNode = useCallback(
-    (
-      reference: ChatReference,
-      textNodeContainingQuery: TextNode | null,
-      closeMenu: () => void,
-    ) => {
-      textNodeContainingQuery?.remove();
-      const selection = $getSelection();
-      const node = $createResourceReferenceNode(reference);
-      if ($isRangeSelection(selection)) {
-        selection.insertNodes([node, $createTextNode(' ')]);
-      } else {
-        const paragraph = $createParagraphNode();
-        paragraph.append(node, $createTextNode(' '));
-        $getRoot().append(paragraph);
-      }
-      closeMenu();
-    },
-    [],
-  );
-
-  const handleSelectMention = useCallback(
-    (
-      option: ResourceMentionOption,
-      textNodeContainingQuery: TextNode | null,
-      closeMenu: () => void,
-    ) => {
-      insertReferenceNode(option.reference, textNodeContainingQuery, closeMenu);
-    },
-    [insertReferenceNode],
-  );
-
-  const handleSelectSkill = useCallback(
-    (
-      option: SkillMentionOption,
-      textNodeContainingQuery: TextNode | null,
-      closeMenu: () => void,
-    ) => {
-      insertReferenceNode(option.skill, textNodeContainingQuery, closeMenu);
-    },
-    [insertReferenceNode],
-  );
-
   // —— C8 AI 润色与发送前提醒 ——
   // 润色状态机抽到 `usePromptPolish`（资源侧两处入口共用同一份）；这里只剩下
   // 聊天特有的「发送前提醒」：提醒偏好、本轮已确认草稿指纹与表单拦截。
@@ -878,13 +536,10 @@ function ResourceReferenceEditor({
     content: initialContent ?? [],
   });
   const [draftText, setDraftText] = useState(() =>
-    directCodexContentToPromptText(initialContent ?? [], assets),
+    promptTextFromContent(providers, initialContent ?? []),
   );
   const reminderDisabledRef = useRef(reminderDisabled);
   reminderDisabledRef.current = reminderDisabled;
-  // 提交拦截只注册一次，但草稿里的 @ 显示名依赖最新 assets；用 ref 让监听器拿到当前值。
-  const assetsRef = useRef(assets);
-  assetsRef.current = assets;
 
   /**
    * 我们自己回填进草稿的那一份文本，用于区分「润色回填」与「用户手改」：
@@ -897,16 +552,17 @@ function ResourceReferenceEditor({
       appliedPromptRef.current = text;
       editor.update(() => {
         const current = readDraftProjectionFromNodes();
-        applyPolishedTextToRoot(text, current, assetsById);
+        applyPolishedTextToRoot(text, current, providersRef.current);
         $getRoot().selectEnd();
       });
     },
-    [assetsById, editor],
+    [editor],
   );
 
   const readPromptText = useCallback(
-    () => directCodexContentToPromptText(liveDraftRef.current.content, assets),
-    [assets],
+    () =>
+      promptTextFromContent(providersRef.current, liveDraftRef.current.content),
+    [],
   );
   const resolvePolishContext = useCallback(
     () => projectPath || null,
@@ -993,9 +649,9 @@ function ResourceReferenceEditor({
       if (
         !shouldRemindChatPromptPolish({
           content: liveDraftRef.current.content,
-          prompt: directCodexContentToPromptText(
+          prompt: promptTextFromContent(
+            providersRef.current,
             liveDraftRef.current.content,
-            assetsRef.current,
           ),
           acknowledgedDraftKey: acknowledgedDraftKeyRef.current,
           reminderDisabled: reminderDisabledRef.current,
@@ -1011,9 +667,149 @@ function ResourceReferenceEditor({
     return () => form.removeEventListener('submit', handleFormSubmit, true);
   }, [rootRef]);
 
-  const renderMentionMenu: MenuRenderFn<
-    ResourceMentionOption | SkillMentionOption
-  > = useCallback(
+  return (
+    <>
+      <div className="resource-reference-input-actions">
+        {inputActions}
+        {showPolishAction ? (
+          <>
+            <button
+              type="button"
+              className="resource-reference-input-polish"
+              aria-label="AI 润色"
+              title="AI 润色"
+              aria-busy={polishing}
+              disabled={disabled || polishing || draftText.trim() === ''}
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={() => void polishPrompt()}
+            >
+              {polishing ? (
+                <Loader2
+                  size={15}
+                  className="animate-spin"
+                  aria-hidden="true"
+                />
+              ) : (
+                <Sparkles size={15} aria-hidden="true" />
+              )}
+            </button>
+            {polishedOriginalText !== null ? (
+              <button
+                type="button"
+                className="resource-reference-input-restore"
+                aria-label="恢复原文"
+                title="恢复原文"
+                disabled={disabled || polishing}
+                onMouseDown={(event) => event.preventDefault()}
+                onClick={restoreOriginalPrompt}
+              >
+                <RotateCcw size={15} aria-hidden="true" />
+              </button>
+            ) : null}
+          </>
+        ) : null}
+      </div>
+      {/* 提醒面板打开时错误提示只在面板里出现，输入区不重复显示。 */}
+      {/* 「与原文相同 / 已截断」这类提示也要可见：只报失败会让「润色没变化」看起来像按钮坏了。 */}
+      {showPolishAction &&
+      !reminderOpen &&
+      (polishing || polishError || polishNotice) ? (
+        <span
+          className="resource-reference-input-status"
+          role="status"
+          aria-live="polite"
+        >
+          {polishing ? '润色中…' : (polishError ?? polishNotice)}
+        </span>
+      ) : null}
+      {providers.map((provider) =>
+        provider.trigger ? (
+          <ProviderMentionMenu
+            key={provider.trigger}
+            provider={provider}
+            rootRef={rootRef}
+            onOpenChange={handleMenuOpenChange}
+          />
+        ) : null,
+      )}
+      {reminderOpen ? (
+        <ChatPromptPolishReminder
+          busy={reminderPolishing}
+          error={polishError}
+          reminderDisabled={reminderDisabled}
+          onPolishAndSubmit={() => void polishAndSubmitFromReminder()}
+          onUseOriginalAndSubmit={useOriginalAndSubmit}
+          onClose={closeReminder}
+          onReminderDisabledChange={setPromptPolishReminderDisabled}
+        />
+      ) : null}
+      <OnChangePlugin
+        onChange={(editorState) => {
+          const nextDraft = readResourceReferenceDraft(editorState);
+          liveDraftRef.current = nextDraft;
+          setDraftText(
+            promptTextFromContent(providersRef.current, nextDraft.content),
+          );
+          if (nextDraft.content.length === 0) {
+            resetPromptPolish();
+            acknowledgedDraftKeyRef.current = null;
+          }
+          if (skipInitialDraftChangeRef.current) {
+            skipInitialDraftChangeRef.current = false;
+            return;
+          }
+          onEditorStateChange?.(editorState);
+          onChange?.(nextDraft);
+        }}
+      />
+    </>
+  );
+}
+
+/**
+ * 一种引用来源的候选菜单：触发符、候选与插入全按 provider 走。
+ *
+ * 输入区不再写死 `@` / `$` 两条链，而是「有几个带触发符的 provider 就有几个菜单」。
+ */
+function ProviderMentionMenu({
+  provider,
+  rootRef,
+  onOpenChange,
+}: {
+  provider: ReferenceProvider;
+  rootRef: RefObject<HTMLDivElement | null>;
+  onOpenChange: (trigger: string, open: boolean) => void;
+}) {
+  const trigger = provider.trigger ?? '';
+  const [query, setQuery] = useState<string | null>(null);
+  const triggerFn = useBasicTypeaheadTriggerMatch(trigger, {
+    minLength: 0,
+    maxLength: 64,
+    allowWhitespace: false,
+  });
+
+  const handleQueryChange = useCallback(
+    (nextQuery: string | null) => {
+      setQuery(nextQuery);
+      onOpenChange(trigger, nextQuery !== null);
+    },
+    [onOpenChange, trigger],
+  );
+
+  // 懒加载的唯一入口：菜单开合/查询变化经 effect 回调给 provider，`match` 始终保持纯函数，
+  // 渲染阶段（下面的 useMemo）不会替 provider 发起请求、写 ref 或读清单。
+  useEffect(() => {
+    provider.onMenuQueryChange?.(query);
+  }, [provider, query]);
+
+  const options = useMemo(() => {
+    if (query === null || !provider.match) return [];
+    return provider
+      .match(query)
+      .map((reference) => new ReferenceMentionOption(reference));
+  }, [provider, query]);
+
+  const renderMenu: MenuRenderFn<ReferenceMentionOption> = useCallback(
     (_anchorElementRef, itemProps) => {
       const inputRect = rootRef.current?.getBoundingClientRect();
       if (!inputRect || itemProps.options.length === 0) {
@@ -1071,16 +867,8 @@ function ResourceReferenceEditor({
               onMouseDown={(event) => event.preventDefault()}
               onClick={() => itemProps.selectOptionAndCleanUp(option)}
             >
-              <span>
-                {'reference' in option
-                  ? `@${option.reference.label}`
-                  : `$${option.skill.name}`}
-              </span>
-              <small>
-                {'reference' in option
-                  ? option.reference.kind
-                  : (option.skill.description ?? 'Skill')}
-              </small>
+              <span>{option.label}</span>
+              <small>{option.hint}</small>
             </button>
           ))}
         </div>,
@@ -1090,425 +878,57 @@ function ResourceReferenceEditor({
     [rootRef],
   );
 
-  const pickerReferences = useMemo(() => {
-    return scopeReferences.filter((reference) => {
-      if (!resourceReferenceMatchesQuery(reference, pickerQuery)) return false;
-      if (!resourceReferenceMatchesCategoryFilter(reference, pickerFilter)) {
-        return false;
+  const handleSelectOption = useCallback(
+    (
+      option: ReferenceMentionOption,
+      textNodeContainingQuery: TextNode | null,
+      closeMenu: () => void,
+    ) => {
+      textNodeContainingQuery?.remove();
+      const selection = $getSelection();
+      const node = $createResourceReferenceNode(option.reference);
+      if ($isRangeSelection(selection)) {
+        selection.insertNodes([node, $createTextNode(' ')]);
+      } else {
+        const paragraph = $createParagraphNode();
+        paragraph.append(node, $createTextNode(' '));
+        $getRoot().append(paragraph);
       }
-      return resourceReferenceMatchesTagSelection(reference, selectedTags);
-    });
-  }, [pickerFilter, pickerQuery, scopeReferences, selectedTags]);
-
-  const visiblePickerReferences = pickerReferences.slice(0, 120);
-
-  const updatePickerPosition = useCallback(() => {
-    const rect = rootRef.current?.getBoundingClientRect();
-    if (!rect) return;
-    const viewportPadding = 12;
-    const gap = 8;
-    const width = Math.min(
-      Math.max(rect.width, 360),
-      Math.max(280, window.innerWidth - viewportPadding * 2),
-    );
-    const left = Math.min(
-      Math.max(viewportPadding, rect.left),
-      Math.max(viewportPadding, window.innerWidth - width - viewportPadding),
-    );
-    /**
-     * 上边界钳制：面板高度**必须**由输入框上下实际可用的空间决定。
-     *
-     * 之前只把底边钉在输入框上方（`bottom: 视口高 - rect.top + 8`）却让高度自由取到 480px，
-     * 输入框靠上时（居中弹层里的提示词输入、窄屏）整块面板的顶边会被顶出视口——顶部那一排
-     * 搜索与筛选既看不见也点不到。这里与 `@` 候选菜单同一套口径：先算上下各有多少空间，
-     * 空间不足就翻到下方，并把高度收在该侧可用空间内，再对 `top` 兜一次底。
-     */
-    const availableAbove = Math.max(0, rect.top - viewportPadding - gap);
-    const availableBelow = Math.max(
-      0,
-      window.innerHeight - rect.bottom - viewportPadding - gap,
-    );
-    const openAbove = availableAbove >= 200 || availableAbove >= availableBelow;
-    const maxHeight = Math.max(
-      160,
-      Math.min(480, openAbove ? availableAbove : availableBelow),
-    );
-    const top = openAbove
-      ? Math.max(viewportPadding, rect.top - gap - maxHeight)
-      : Math.min(
-          Math.max(
-            viewportPadding,
-            window.innerHeight - viewportPadding - maxHeight,
-          ),
-          rect.bottom + gap,
-        );
-    setPickerPosition({
-      left,
-      top,
-      width,
-      maxHeight,
-    });
-  }, [rootRef]);
-
-  useEffect(() => {
-    if (!pickerOpen) {
-      setPickerPosition(null);
-      return;
-    }
-    updatePickerPosition();
-    window.addEventListener('resize', updatePickerPosition);
-    window.addEventListener('scroll', updatePickerPosition, true);
-    return () => {
-      window.removeEventListener('resize', updatePickerPosition);
-      window.removeEventListener('scroll', updatePickerPosition, true);
-    };
-  }, [pickerOpen, updatePickerPosition]);
+      closeMenu();
+    },
+    [],
+  );
 
   return (
-    <>
-      <div className="resource-reference-input-actions">
-        {showTriggerButton ? (
-          <button
-            type="button"
-            className="resource-reference-input-at"
-            aria-label="插入素材引用"
-            title="插入素材引用"
-            disabled={disabled}
-            onMouseDown={(event) => event.preventDefault()}
-            onClick={openPicker}
-          >
-            <AtSign size={15} aria-hidden="true" />
-          </button>
-        ) : null}
-        {showPolishAction ? (
-          <>
-            <button
-              type="button"
-              className="resource-reference-input-polish"
-              aria-label="AI 润色"
-              title="AI 润色"
-              aria-busy={polishing}
-              disabled={disabled || polishing || draftText.trim() === ''}
-              onMouseDown={(event) => event.preventDefault()}
-              onClick={() => void polishPrompt()}
-            >
-              {polishing ? (
-                <Loader2
-                  size={15}
-                  className="animate-spin"
-                  aria-hidden="true"
-                />
-              ) : (
-                <Sparkles size={15} aria-hidden="true" />
-              )}
-            </button>
-            {polishedOriginalText !== null ? (
-              <button
-                type="button"
-                className="resource-reference-input-restore"
-                aria-label="恢复原文"
-                title="恢复原文"
-                disabled={disabled || polishing}
-                onMouseDown={(event) => event.preventDefault()}
-                onClick={restoreOriginalPrompt}
-              >
-                <RotateCcw size={15} aria-hidden="true" />
-              </button>
-            ) : null}
-          </>
-        ) : null}
-      </div>
-      {/* 提醒面板打开时错误提示只在面板里出现，输入区不重复显示。 */}
-      {/* 「与原文相同 / 已截断」这类提示也要可见：只报失败会让「润色没变化」看起来像按钮坏了。 */}
-      {showPolishAction &&
-      !reminderOpen &&
-      (polishing || polishError || polishNotice) ? (
-        <span
-          className="resource-reference-input-status"
-          role="status"
-          aria-live="polite"
-        >
-          {polishing ? '润色中…' : (polishError ?? polishNotice)}
-        </span>
-      ) : null}
-      <LexicalTypeaheadMenuPlugin<ResourceMentionOption>
-        options={mentionOptions}
-        triggerFn={triggerFn}
-        onQueryChange={setQuery}
-        onSelectOption={(option, textNode, closeMenu) =>
-          handleSelectMention(option, textNode, closeMenu)
-        }
-        menuRenderFn={
-          renderMentionMenu as unknown as MenuRenderFn<ResourceMentionOption>
-        }
-        anchorClassName="resource-reference-menu-anchor"
-        preselectFirstItem
-      />
-      <LexicalTypeaheadMenuPlugin<SkillMentionOption>
-        options={skillOptions}
-        triggerFn={skillTriggerFn}
-        onQueryChange={setSkillQuery}
-        onSelectOption={(option, textNode, closeMenu) =>
-          handleSelectSkill(option, textNode, closeMenu)
-        }
-        menuRenderFn={
-          renderMentionMenu as unknown as MenuRenderFn<SkillMentionOption>
-        }
-        anchorClassName="resource-reference-menu-anchor"
-        preselectFirstItem
-      />
-      {pickerOpen && pickerPosition
-        ? createPortal(
-            <div
-              className="resource-reference-picker"
-              role="dialog"
-              aria-modal="false"
-              aria-label="选择素材"
-              style={{
-                // 与 `@` 候选菜单同一坐标系（fixed + top + 高度钳制）：底边锚点在
-                // 输入框上方会被顶出视口，只有钉住顶边并收紧高度才能保证整块面板可见。
-                position: 'fixed',
-                top: `${pickerPosition.top}px`,
-                left: `${pickerPosition.left}px`,
-                right: 'auto',
-                bottom: 'auto',
-                width: `${pickerPosition.width}px`,
-                maxHeight: `${pickerPosition.maxHeight}px`,
-              }}
-            >
-              <header>
-                <strong>选择素材</strong>
-                <button
-                  type="button"
-                  aria-label="关闭素材选择"
-                  onClick={() => setPickerOpen(false)}
-                >
-                  ×
-                </button>
-              </header>
-              <PlatformSegmentedTabs
-                items={RESOURCE_REFERENCE_SCOPES}
-                activeId={pickerScope}
-                onChange={(nextScope) => {
-                  setPickerScopeOverride(nextScope);
-                }}
-                gap="sm"
-                frame="bare"
-                surface="transparent"
-                size="sm"
-                semantics="tabs"
-                ariaLabel="素材范围"
-                className="platform-theme platform-theme--light resource-reference-picker-scopes"
-              />
-              {/* 搜索 + 功能分类 + 标签用共享筛选条：与资源画布、参考图弹窗同一套筛选 UI，
-                  标签口径也来自共享标签库；两个页签各自持有一份独立状态。 */}
-              <PlatformResourceFilterBar
-                ariaLabel="素材筛选"
-                search={{
-                  value: pickerQuery,
-                  label:
-                    pickerScope === 'current-version'
-                      ? '搜索当前版本素材'
-                      : '搜索全部画布素材',
-                  placeholder: '搜索名称或资源 ID',
-                  onChange: (value) => updatePickerScopeState({ query: value }),
-                }}
-                categoryItems={RESOURCE_REFERENCE_FILTERS}
-                activeCategoryId={pickerFilter}
-                onCategoryChange={(nextFilter) =>
-                  updatePickerScopeState({ filter: nextFilter })
-                }
-                tagItems={scopeTagItems}
-                activeTags={selectedTags}
-                onToggleTag={(tag) =>
-                  updatePickerScopeState({
-                    selectedTags: selectedTags.includes(tag)
-                      ? selectedTags.filter((item) => item !== tag)
-                      : [...selectedTags, tag],
-                  })
-                }
-                className="platform-theme platform-theme--light resource-reference-picker-filters"
-              />
-              <div className="resource-reference-picker-list" role="listbox">
-                {visiblePickerReferences.length === 0 ? (
-                  <p className="resource-reference-picker-empty">
-                    {pickerEmptyMessage(scopeReferences.length, pickerScope)}
-                  </p>
-                ) : (
-                  visiblePickerReferences.map((reference) => {
-                    const selected = selectedResourceIds.includes(
-                      reference.resourceId,
-                    );
-                    return (
-                      <button
-                        type="button"
-                        role="option"
-                        aria-selected={selected}
-                        key={`${reference.resourceId}:${reference.kind}`}
-                        className={selected ? 'is-selected' : undefined}
-                        onClick={() =>
-                          updatePickerScopeState({
-                            selectedResourceIds: selected
-                              ? selectedResourceIds.filter(
-                                  (resourceId) =>
-                                    resourceId !== reference.resourceId,
-                                )
-                              : [...selectedResourceIds, reference.resourceId],
-                          })
-                        }
-                      >
-                        <ResourcePickerThumbnail
-                          asset={assetsById.get(reference.resourceId)}
-                          projectPath={projectPath}
-                        />
-                        <span>
-                          <strong>{reference.label}</strong>
-                          <small>
-                            {resourceReferenceCategoryLabel(reference.category)}{' '}
-                            · {reference.kind} · {reference.mediaType}
-                          </small>
-                        </span>
-                        {selected ? (
-                          <Check size={14} aria-hidden="true" />
-                        ) : null}
-                      </button>
-                    );
-                  })
-                )}
-              </div>
-              <footer>
-                <span>
-                  已选择 {selectedResourceIds.length} 个
-                  {pickerReferences.length > visiblePickerReferences.length
-                    ? `，当前显示前 ${visiblePickerReferences.length} 个`
-                    : ''}
-                </span>
-                <button
-                  type="button"
-                  disabled={selectedResourceIds.length === 0}
-                  onClick={() => {
-                    insertReferences(
-                      scopeReferences.filter((reference) =>
-                        selectedResourceIds.includes(reference.resourceId),
-                      ),
-                    );
-                    setPickerOpen(false);
-                  }}
-                >
-                  插入引用
-                </button>
-              </footer>
-            </div>,
-            document.body,
-          )
-        : null}
-      {reminderOpen ? (
-        <ChatPromptPolishReminder
-          busy={reminderPolishing}
-          error={polishError}
-          reminderDisabled={reminderDisabled}
-          onPolishAndSubmit={() => void polishAndSubmitFromReminder()}
-          onUseOriginalAndSubmit={useOriginalAndSubmit}
-          onClose={closeReminder}
-          onReminderDisabledChange={setPromptPolishReminderDisabled}
-        />
-      ) : null}
-      <OnChangePlugin
-        onChange={(editorState) => {
-          const nextDraft = readResourceReferenceDraft(editorState);
-          liveDraftRef.current = nextDraft;
-          setDraftText(
-            directCodexContentToPromptText(nextDraft.content, assets),
-          );
-          if (nextDraft.content.length === 0) {
-            resetPromptPolish();
-            acknowledgedDraftKeyRef.current = null;
-          }
-          if (skipInitialDraftChangeRef.current) {
-            skipInitialDraftChangeRef.current = false;
-            return;
-          }
-          onEditorStateChange?.(editorState);
-          onChange?.(nextDraft);
-        }}
-      />
-    </>
+    <LexicalTypeaheadMenuPlugin<ReferenceMentionOption>
+      options={options}
+      triggerFn={triggerFn}
+      onQueryChange={handleQueryChange}
+      onSelectOption={handleSelectOption}
+      menuRenderFn={renderMenu}
+      anchorClassName="resource-reference-menu-anchor"
+      preselectFirstItem
+    />
   );
 }
 
-function ResourcePickerThumbnail({
-  asset,
-  projectPath,
-}: {
-  asset?: GameCreationAppAssetManifestEntry;
-  projectPath: string;
-}) {
-  const previewScopeIdRef = useRef(createProjectResourcePreviewScopeId());
-  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
-  const [failed, setFailed] = useState(false);
-  const mediaType = asset?.mediaType.toLowerCase() ?? '';
-
-  useEffect(() => {
-    setPreviewUrl(null);
-    setFailed(false);
-    if (!asset || !projectPath || !mediaType.startsWith('image/')) {
-      return;
-    }
-    const invoke = resolveTauriInvoke();
-    if (!invoke) return;
-    let cancelled = false;
-    void invoke<{ dataUrl: string }>('read_local_project_image_preview', {
-      projectPath,
-      relativePath: asset.localPath,
-      scopeId: previewScopeIdRef.current,
-      requestId: createProjectResourcePreviewRequestId(),
-    })
-      .then((result) => {
-        if (!cancelled) setPreviewUrl(result.dataUrl);
-      })
-      .catch(() => {
-        if (!cancelled) setFailed(true);
-      });
-    return () => {
-      cancelled = true;
-      // 只靠 cancelled 标记只是忽略迟到的结果，请求本身还在跑；换素材 / 卸载时
-      // 主动作废上一个 scope，避免快速切换素材叠出一串在飞预览请求。
-      cancelLocalProjectResourcePreviewScope(previewScopeIdRef.current);
-      previewScopeIdRef.current = createProjectResourcePreviewScopeId();
-    };
-  }, [asset, mediaType, projectPath]);
-
-  if (previewUrl) {
-    return <img src={previewUrl} alt="" />;
-  }
-  if (failed) {
-    return <FileText size={18} aria-hidden="true" />;
-  }
-  if (mediaType.startsWith('video/')) {
-    return <Video size={18} aria-hidden="true" />;
-  }
-  if (mediaType.startsWith('audio/')) {
-    return <Music2 size={18} aria-hidden="true" />;
-  }
-  if (mediaType.startsWith('image/')) {
-    return <Loader2 size={18} className="animate-spin" aria-hidden="true" />;
-  }
-  if (asset && isGameCreationAppUiDesignDocAsset(asset)) {
-    return <FileText size={18} aria-hidden="true" />;
-  }
-  return <ImageIcon size={18} aria-hidden="true" />;
-}
-
 export const ResourceReferenceInput = forwardRef<
   ResourceReferenceInputHandle,
   ResourceReferenceInputProps
->(function ResourceReferenceInput(props, ref) {
+>(function ResourceReferenceInput({ containerRef, ...props }, ref) {
   const rootRef = useRef<HTMLDivElement | null>(null);
+  const assignContainer = useCallback(
+    (element: HTMLDivElement | null) => {
+      rootRef.current = element;
+      if (containerRef) containerRef.current = element;
+    },
+    [containerRef],
+  );
   return (
     <RichTextInput
       namespace="agc-resource-reference-input"
-      nodes={[ResourceReferenceNode, AttachmentReferenceNode]}
-      containerRef={rootRef}
+      nodes={[ResourceReferenceNode]}
+      containerRef={assignContainer}
       containerClassName={`resource-reference-input${props.multiline ? '' : ' is-single-line'}`}
       disabled={props.disabled}
       contentEditable={
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceNode.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceNode.tsx
index a536ec791..01ced3b28 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceNode.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceNode.tsx
@@ -9,6 +9,7 @@ import {
 } from 'lexical';
 import type { ReactNode } from 'react';
 
+import { AttachmentReferenceChip } from './AttachmentReferenceChip';
 import { ResourceReferenceChip } from './ResourceReferenceChip';
 import type { ChatReference } from './resourceReferences';
 
@@ -89,7 +90,15 @@ export class ResourceReferenceNode extends DecoratorNode<ReactNode> {
   }
 
   decorate() {
-    return (
+    // 引用节点只有一个类型（`ChatReference` 联合），chip 的外观按引用成员选：
+    // 附件芯片的 DOM 契约（`data-attachment-reference` / `data-attachment-status` / title）
+    // 由它自己那段组件保证，节点层不复制一份。
+    return this.__reference.type === 'attachment' ? (
+      <AttachmentReferenceChip
+        attachment={this.__reference}
+        nodeKey={this.__key}
+      />
+    ) : (
       <ResourceReferenceChip
         reference={this.__reference}
         nodeKey={this.__key}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferencePicker.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferencePicker.tsx
new file mode 100644
index 000000000..733c04736
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferencePicker.tsx
@@ -0,0 +1,573 @@
+import {
+  AtSign,
+  Check,
+  FileText,
+  Image as ImageIcon,
+  Loader2,
+  Music2,
+  Video,
+} from 'lucide-react';
+import {
+  forwardRef,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import { PlatformResourceFilterBar } from '../../../../../packages/shared/src/components/PlatformResourceFilterBar';
+import { PlatformSegmentedTabs } from '../../../../../packages/shared/src/components/PlatformSegmentedTabs';
+import {
+  type GameCreationAppAssetManifestEntry,
+  type GameIterationVersion,
+  isGameCreationAppUiDesignDocAsset,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import { resolveTauriInvoke } from '../../app/tauri';
+import {
+  cancelLocalProjectResourcePreviewScope,
+  createProjectResourcePreviewRequestId,
+  createProjectResourcePreviewScopeId,
+} from '../../services/projectResourcePreviewTransport';
+import {
+  assetsSignature,
+  currentIterationVersionAssets,
+  mentionableAssetReferences,
+  RESOURCE_REFERENCE_FILTERS,
+  RESOURCE_REFERENCE_SCOPES,
+  type ResourceReference,
+  resourceReferenceCategoryLabel,
+  type ResourceReferenceFilter,
+  resourceReferenceMatchesCategoryFilter,
+  resourceReferenceMatchesQuery,
+  resourceReferenceMatchesTagSelection,
+  type ResourceReferenceScope,
+  resourceReferenceTagLibrary,
+} from './resourceReferences';
+
+type ResourcePickerScopeState = {
+  query: string;
+  filter: ResourceReferenceFilter;
+  selectedResourceIds: string[];
+  /** 已选标签（多选），与搜索词、功能分类三者叠加生效。 */
+  selectedTags: string[];
+};
+
+function createResourcePickerScopeState(): ResourcePickerScopeState {
+  return {
+    query: '',
+    filter: 'all',
+    selectedResourceIds: [],
+    selectedTags: [],
+  };
+}
+
+function createResourcePickerScopeStates(): Record<
+  ResourceReferenceScope,
+  ResourcePickerScopeState
+> {
+  return {
+    'current-version': createResourcePickerScopeState(),
+    'all-canvas': createResourcePickerScopeState(),
+  };
+}
+
+/**
+ * 版本列表的内容签名：「当前版本素材」只由版本 id、顺序与绑定资源决定，
+ * 按签名取依赖才能跳过与版本无关的渲染。
+ */
+function iterationsSignature(
+  versions: readonly GameIterationVersion[] | undefined,
+) {
+  return (versions ?? [])
+    .map(
+      (version) =>
+        `${version.versionId}\u0002${version.resourceBindings
+          .map((binding) => binding.resourceId)
+          .join(',')}`,
+    )
+    .join('\u0001');
+}
+
+/** 空态文案：先分「这个范围本来就没有素材」和「筛完没有命中」两件事。 */
+function pickerEmptyMessage(
+  scopeReferenceCount: number,
+  scope: ResourceReferenceScope,
+) {
+  if (scopeReferenceCount > 0) {
+    return '没有匹配的素材';
+  }
+  return scope === 'current-version'
+    ? '当前版本还没有绑定素材'
+    : '当前项目还没有已登记素材';
+}
+
+export type ResourceReferencePickerHandle = {
+  open: () => void;
+  close: () => void;
+};
+
+type ResourceReferencePickerProps = {
+  /**
+   * 面板的定位锚点：输入区容器。浮层钉在它上方（空间不足翻到下方），
+   * 与 `@` 候选菜单同一坐标系。
+   */
+  anchorRef: RefObject<HTMLElement | null>;
+  assets: readonly GameCreationAppAssetManifestEntry[];
+  versions?: GameIterationVersion[];
+  /**
+   * 「当前版本素材」页签使用的版本 id。没传 / `null` 时回退到 manifest `versions[]`
+   * 中最新的那个版本；版本不存在或没有绑定资源时该页签显示空态。
+   */
+  activeVersionId?: string | null;
+  projectPath: string;
+  /** 确认插入：宿主把它交给输入区句柄的 `insertReferences`。 */
+  onInsert: (references: ResourceReference[]) => void;
+  /** 打开态给宿主：宿主据此压制输入区的 Enter 提交。 */
+  onOpenChange?: (open: boolean) => void;
+};
+
+/**
+ * 素材选择器面板：自己拿数据（`assets` / `versions` / `activeVersionId` / `projectPath`
+ * 与缩略图预览 invoke），自己管打开态与筛选状态，确认后只把选中的引用交给宿主。
+ *
+ * 它与输入区之间只有一个接缝：`onInsert` → 输入区句柄的 `insertReferences`。
+ * 触发钮不在这个组件里：宿主把触发钮放在自己的位置（输入区操作排或控制排），
+ * 经 `ResourceReferencePickerHandle.open()` 打开。面板 portal 到 `document.body`，
+ * 宿主的「点外部关闭」判定请用 `isResourceReferenceOverlayTarget`。
+ */
+export const ResourceReferencePicker = forwardRef<
+  ResourceReferencePickerHandle,
+  ResourceReferencePickerProps
+>(function ResourceReferencePicker(
+  {
+    anchorRef,
+    assets,
+    versions,
+    activeVersionId = null,
+    projectPath,
+    onInsert,
+    onOpenChange,
+  },
+  ref,
+) {
+  const [open, setOpen] = useState(false);
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const onInsertRef = useRef(onInsert);
+  onInsertRef.current = onInsert;
+
+  const setPickerOpen = useCallback((next: boolean) => {
+    setOpen(next);
+    onOpenChangeRef.current?.(next);
+  }, []);
+
+  const [pickerScopeStates, setPickerScopeStates] = useState<
+    Record<ResourceReferenceScope, ResourcePickerScopeState>
+  >(createResourcePickerScopeStates);
+  const [pickerScopeOverride, setPickerScopeOverride] =
+    useState<ResourceReferenceScope | null>(null);
+  const [pickerPosition, setPickerPosition] = useState<{
+    left: number;
+    top: number;
+    width: number;
+    maxHeight: number;
+  } | null>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => {
+        setPickerScopeStates(createResourcePickerScopeStates());
+        setPickerScopeOverride(null);
+        setPickerOpen(true);
+      },
+      close: () => setPickerOpen(false),
+    }),
+    [setPickerOpen],
+  );
+
+  const assetsContentSignature = assetsSignature(assets);
+  const versionsContentSignature = iterationsSignature(versions);
+  const assetsById = useMemo(
+    () => new Map(assets.map((asset) => [asset.id, asset])),
+    // 依赖内容签名：assets 数组身份每次渲染都会变，内容不变时没必要重建索引。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [assetsContentSignature],
+  );
+  const assetReferences = useMemo(
+    () => mentionableAssetReferences(assets, 'asset-picker'),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [assetsContentSignature],
+  );
+  const currentVersionAssetReferences = useMemo(
+    () =>
+      mentionableAssetReferences(
+        currentIterationVersionAssets(assets, versions, activeVersionId),
+        'version-asset',
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [activeVersionId, assetsContentSignature, versionsContentSignature],
+  );
+  // 两个页签的默认落点：当前版本确实绑定了已登记素材时优先展示「当前版本素材」，
+  // 否则落到「全部画布素材」，避免没有版本的项目一打开就是空列表。
+  const defaultPickerScope: ResourceReferenceScope =
+    currentVersionAssetReferences.length > 0 ? 'current-version' : 'all-canvas';
+  const pickerScope = pickerScopeOverride ?? defaultPickerScope;
+  const pickerScopeState = pickerScopeStates[pickerScope];
+  const pickerQuery = pickerScopeState.query;
+  const pickerFilter = pickerScopeState.filter;
+  const selectedResourceIds = pickerScopeState.selectedResourceIds;
+  const selectedTags = pickerScopeState.selectedTags;
+
+  const scopeReferences =
+    pickerScope === 'current-version'
+      ? currentVersionAssetReferences
+      : assetReferences;
+
+  // 标签库按当前页签的候选派生：两个页签各自一份，标签与计数都不跨页签串。
+  const scopeTagItems = useMemo(
+    () => resourceReferenceTagLibrary(scopeReferences),
+    [scopeReferences],
+  );
+
+  const updatePickerScopeState = useCallback(
+    (patch: Partial<ResourcePickerScopeState>) => {
+      setPickerScopeStates((current) => ({
+        ...current,
+        [pickerScope]: { ...current[pickerScope], ...patch },
+      }));
+    },
+    [pickerScope],
+  );
+
+  const pickerReferences = useMemo(() => {
+    return scopeReferences.filter((reference) => {
+      if (!resourceReferenceMatchesQuery(reference, pickerQuery)) return false;
+      if (!resourceReferenceMatchesCategoryFilter(reference, pickerFilter)) {
+        return false;
+      }
+      return resourceReferenceMatchesTagSelection(reference, selectedTags);
+    });
+  }, [pickerFilter, pickerQuery, scopeReferences, selectedTags]);
+
+  const visiblePickerReferences = pickerReferences.slice(0, 120);
+
+  const updatePickerPosition = useCallback(() => {
+    const rect = anchorRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    const viewportPadding = 12;
+    const gap = 8;
+    const width = Math.min(
+      Math.max(rect.width, 360),
+      Math.max(280, window.innerWidth - viewportPadding * 2),
+    );
+    const left = Math.min(
+      Math.max(viewportPadding, rect.left),
+      Math.max(viewportPadding, window.innerWidth - width - viewportPadding),
+    );
+    /**
+     * 上边界钳制：面板高度**必须**由输入框上下实际可用的空间决定。
+     *
+     * 之前只把底边钉在输入框上方（`bottom: 视口高 - rect.top + 8`）却让高度自由取到 480px，
+     * 输入框靠上时（居中弹层里的提示词输入、窄屏）整块面板的顶边会被顶出视口——顶部那一排
+     * 搜索与筛选既看不见也点不到。这里与 `@` 候选菜单同一套口径：先算上下各有多少空间，
+     * 空间不足就翻到下方，并把高度收在该侧可用空间内，再对 `top` 兜一次底。
+     */
+    const availableAbove = Math.max(0, rect.top - viewportPadding - gap);
+    const availableBelow = Math.max(
+      0,
+      window.innerHeight - rect.bottom - viewportPadding - gap,
+    );
+    const openAbove = availableAbove >= 200 || availableAbove >= availableBelow;
+    const maxHeight = Math.max(
+      160,
+      Math.min(480, openAbove ? availableAbove : availableBelow),
+    );
+    const top = openAbove
+      ? Math.max(viewportPadding, rect.top - gap - maxHeight)
+      : Math.min(
+          Math.max(
+            viewportPadding,
+            window.innerHeight - viewportPadding - maxHeight,
+          ),
+          rect.bottom + gap,
+        );
+    setPickerPosition({
+      left,
+      top,
+      width,
+      maxHeight,
+    });
+  }, [anchorRef]);
+
+  useEffect(() => {
+    if (!open) {
+      setPickerPosition(null);
+      return;
+    }
+    updatePickerPosition();
+    window.addEventListener('resize', updatePickerPosition);
+    window.addEventListener('scroll', updatePickerPosition, true);
+    return () => {
+      window.removeEventListener('resize', updatePickerPosition);
+      window.removeEventListener('scroll', updatePickerPosition, true);
+    };
+  }, [open, updatePickerPosition]);
+
+  // Escape 关闭：与旧口径一致——焦点在输入区（面板外）时 Escape 收起面板，
+  // 焦点在面板内部的搜索框时不收（那里 Escape 不该把整块面板一起关掉）。
+  // 只监听、不拦截事件：其他层的 Escape 语义（例如画布弹层的关闭）照旧收到。
+  useEffect(() => {
+    if (!open) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.defaultPrevented) return;
+      if (
+        event.target instanceof Node &&
+        panelRef.current?.contains(event.target)
+      ) {
+        return;
+      }
+      setPickerOpen(false);
+    };
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [open, setPickerOpen]);
+
+  if (!open || !pickerPosition) {
+    return null;
+  }
+
+  return createPortal(
+    <div
+      ref={panelRef}
+      className="resource-reference-picker"
+      role="dialog"
+      aria-modal="false"
+      aria-label="选择素材"
+      style={{
+        // 与 `@` 候选菜单同一坐标系（fixed + top + 高度钳制）：底边锚点在
+        // 输入框上方会被顶出视口，只有钉住顶边并收紧高度才能保证整块面板可见。
+        position: 'fixed',
+        top: `${pickerPosition.top}px`,
+        left: `${pickerPosition.left}px`,
+        right: 'auto',
+        bottom: 'auto',
+        width: `${pickerPosition.width}px`,
+        maxHeight: `${pickerPosition.maxHeight}px`,
+      }}
+    >
+      <header>
+        <strong>选择素材</strong>
+        <button
+          type="button"
+          aria-label="关闭素材选择"
+          onClick={() => setPickerOpen(false)}
+        >
+          ×
+        </button>
+      </header>
+      <PlatformSegmentedTabs
+        items={RESOURCE_REFERENCE_SCOPES}
+        activeId={pickerScope}
+        onChange={(nextScope) => {
+          setPickerScopeOverride(nextScope);
+        }}
+        gap="sm"
+        frame="bare"
+        surface="transparent"
+        size="sm"
+        semantics="tabs"
+        ariaLabel="素材范围"
+        className="platform-theme platform-theme--light resource-reference-picker-scopes"
+      />
+      {/* 搜索 + 功能分类 + 标签用共享筛选条：与资源画布、参考图弹窗同一套筛选 UI，
+          标签口径也来自共享标签库；两个页签各自持有一份独立状态。 */}
+      <PlatformResourceFilterBar
+        ariaLabel="素材筛选"
+        search={{
+          value: pickerQuery,
+          label:
+            pickerScope === 'current-version'
+              ? '搜索当前版本素材'
+              : '搜索全部画布素材',
+          placeholder: '搜索名称或资源 ID',
+          onChange: (value) => updatePickerScopeState({ query: value }),
+        }}
+        categoryItems={RESOURCE_REFERENCE_FILTERS}
+        activeCategoryId={pickerFilter}
+        onCategoryChange={(nextFilter) =>
+          updatePickerScopeState({ filter: nextFilter })
+        }
+        tagItems={scopeTagItems}
+        activeTags={selectedTags}
+        onToggleTag={(tag) =>
+          updatePickerScopeState({
+            selectedTags: selectedTags.includes(tag)
+              ? selectedTags.filter((item) => item !== tag)
+              : [...selectedTags, tag],
+          })
+        }
+        className="platform-theme platform-theme--light resource-reference-picker-filters"
+      />
+      <div className="resource-reference-picker-list" role="listbox">
+        {visiblePickerReferences.length === 0 ? (
+          <p className="resource-reference-picker-empty">
+            {pickerEmptyMessage(scopeReferences.length, pickerScope)}
+          </p>
+        ) : (
+          visiblePickerReferences.map((reference) => {
+            const selected = selectedResourceIds.includes(reference.resourceId);
+            return (
+              <button
+                type="button"
+                role="option"
+                aria-selected={selected}
+                key={`${reference.resourceId}:${reference.kind}`}
+                className={selected ? 'is-selected' : undefined}
+                onClick={() =>
+                  updatePickerScopeState({
+                    selectedResourceIds: selected
+                      ? selectedResourceIds.filter(
+                          (resourceId) => resourceId !== reference.resourceId,
+                        )
+                      : [...selectedResourceIds, reference.resourceId],
+                  })
+                }
+              >
+                <ResourcePickerThumbnail
+                  asset={assetsById.get(reference.resourceId)}
+                  projectPath={projectPath}
+                />
+                <span>
+                  <strong>{reference.label}</strong>
+                  <small>
+                    {resourceReferenceCategoryLabel(reference.category)} ·{' '}
+                    {reference.kind} · {reference.mediaType}
+                  </small>
+                </span>
+                {selected ? <Check size={14} aria-hidden="true" /> : null}
+              </button>
+            );
+          })
+        )}
+      </div>
+      <footer>
+        <span>
+          已选择 {selectedResourceIds.length} 个
+          {pickerReferences.length > visiblePickerReferences.length
+            ? `，当前显示前 ${visiblePickerReferences.length} 个`
+            : ''}
+        </span>
+        <button
+          type="button"
+          disabled={selectedResourceIds.length === 0}
+          onClick={() => {
+            onInsertRef.current(
+              scopeReferences.filter((reference) =>
+                selectedResourceIds.includes(reference.resourceId),
+              ),
+            );
+            setPickerOpen(false);
+          }}
+        >
+          插入引用
+        </button>
+      </footer>
+    </div>,
+    document.body,
+  );
+});
+
+/**
+ * 输入区操作排里的 `@` 触发钮：与 `resource-reference-input-actions` 里其他方钮同一外观。
+ * 宿主把它放进输入区的 `inputActions` 槽，点击经 picker 句柄开面板。
+ */
+export function ResourceReferencePickerAction({
+  disabled,
+  onOpen,
+}: {
+  disabled?: boolean;
+  onOpen: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className="resource-reference-input-at"
+      aria-label="插入素材引用"
+      title="插入素材引用"
+      disabled={disabled}
+      onMouseDown={(event) => event.preventDefault()}
+      onClick={onOpen}
+    >
+      <AtSign size={15} aria-hidden="true" />
+    </button>
+  );
+}
+
+function ResourcePickerThumbnail({
+  asset,
+  projectPath,
+}: {
+  asset?: GameCreationAppAssetManifestEntry;
+  projectPath: string;
+}) {
+  const previewScopeIdRef = useRef(createProjectResourcePreviewScopeId());
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  const mediaType = asset?.mediaType.toLowerCase() ?? '';
+
+  useEffect(() => {
+    setPreviewUrl(null);
+    setFailed(false);
+    if (!asset || !projectPath || !mediaType.startsWith('image/')) {
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) return;
+    let cancelled = false;
+    void invoke<{ dataUrl: string }>('read_local_project_image_preview', {
+      projectPath,
+      relativePath: asset.localPath,
+      scopeId: previewScopeIdRef.current,
+      requestId: createProjectResourcePreviewRequestId(),
+    })
+      .then((result) => {
+        if (!cancelled) setPreviewUrl(result.dataUrl);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+    return () => {
+      cancelled = true;
+      // 只靠 cancelled 标记只是忽略迟到的结果，请求本身还在跑；换素材 / 卸载时
+      // 主动作废上一个 scope，避免快速切换素材叠出一串在飞预览请求。
+      cancelLocalProjectResourcePreviewScope(previewScopeIdRef.current);
+      previewScopeIdRef.current = createProjectResourcePreviewScopeId();
+    };
+  }, [asset, mediaType, projectPath]);
+
+  if (previewUrl) {
+    return <img src={previewUrl} alt="" />;
+  }
+  if (failed) {
+    return <FileText size={18} aria-hidden="true" />;
+  }
+  if (mediaType.startsWith('video/')) {
+    return <Video size={18} aria-hidden="true" />;
+  }
+  if (mediaType.startsWith('audio/')) {
+    return <Music2 size={18} aria-hidden="true" />;
+  }
+  if (mediaType.startsWith('image/')) {
+    return <Loader2 size={18} className="animate-spin" aria-hidden="true" />;
+  }
+  if (asset && isGameCreationAppUiDesignDocAsset(asset)) {
+    return <FileText size={18} aria-hidden="true" />;
+  }
+  return <ImageIcon size={18} aria-hidden="true" />;
+}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts
new file mode 100644
index 000000000..762ef2657
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts
@@ -0,0 +1,43 @@
+import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
+import type { ChatReference } from '../resourceReferences';
+import type { ReferenceProvider } from './types';
+
+/** canonical 附件 part → `ChatReference` 的附件成员（字段逐字对齐）。 */
+export function attachmentReferenceFromPart(
+  part: DirectCodexUserContentPart & { type: 'agc_attachment_reference' },
+): ChatReference {
+  return {
+    type: 'attachment',
+    name: part.name,
+    mediaType: part.mediaType,
+    size: part.size,
+    localPath: part.localPath,
+    status: part.status,
+  };
+}
+
+/**
+ * 附件的 provider：**静默**（没有触发符、没有候选）。
+ *
+ * 附件只由宿主的导入动作或跨会话草稿回填进入正文，所以它只需要回答「这个 part 是不是附件」
+ * 「它在正文里长什么样」。附件本身不进候选菜单，也不需要改名刷新。
+ */
+export function createAttachmentReferenceProvider(): ReferenceProvider {
+  return {
+    trigger: null,
+    toReference: (part: DirectCodexUserContentPart): ChatReference | null =>
+      part.type === 'agc_attachment_reference'
+        ? attachmentReferenceFromPart(part)
+        : null,
+    refresh: (reference: ChatReference): ChatReference | null =>
+      reference.type === 'attachment' ? reference : null,
+    mentionToken: (part) =>
+      part.type === 'agc_attachment_reference' ? `@${part.name}` : null,
+  };
+}
+
+/**
+ * 附件 provider 无状态，宿主可以共用同一个实例。
+ * 它没有触发符，所以「注入它」不会给输入区加出任何候选入口。
+ */
+export const attachmentReferenceProvider = createAttachmentReferenceProvider();
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts
new file mode 100644
index 000000000..cf7c9b5be
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts
@@ -0,0 +1,78 @@
+import type { GameCreationAppAssetManifestEntry } from '../../../../../../packages/shared/src/contracts/gameCreationApp';
+import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
+import {
+  assetsSignature,
+  type ChatReference,
+  mentionableAssetReferences,
+  refreshResourceReference,
+  resourceDisplayName,
+  type ResourceReference,
+  resourceReferenceFromAsset,
+  resourceReferenceMatchesQuery,
+} from '../resourceReferences';
+import type { ReferenceProvider } from './types';
+
+/** 候选菜单最多展示多少条：两条触发链（`@` / `$`）共用同一个上限。 */
+const MENTION_OPTION_LIMIT = 8;
+
+type ResourceProviderData = {
+  byId: ReadonlyMap<string, GameCreationAppAssetManifestEntry>;
+  references: ResourceReference[];
+};
+
+let cachedSignature = '\u0000';
+let cachedData: ResourceProviderData | null = null;
+
+function resourceProviderData(
+  assets: readonly GameCreationAppAssetManifestEntry[],
+): ResourceProviderData {
+  const signature = assetsSignature(assets);
+  if (cachedData && signature === cachedSignature) {
+    return cachedData;
+  }
+  cachedSignature = signature;
+  cachedData = {
+    byId: new Map(assets.map((asset) => [asset.id, asset])),
+    references: mentionableAssetReferences(assets, 'asset-picker'),
+  };
+  return cachedData;
+}
+
+/**
+ * 资源引用的 provider：候选、身份解析、显示名刷新与 `@显示名` 文本形态都按宿主传进来的
+ * 这份 manifest 展开。输入区自己不再读清单。
+ */
+export function createResourceReferenceProvider({
+  assets,
+}: {
+  assets: readonly GameCreationAppAssetManifestEntry[];
+}): ReferenceProvider {
+  return {
+    trigger: '@',
+    match: (query) =>
+      resourceProviderData(assets)
+        .references.filter((reference) =>
+          resourceReferenceMatchesQuery(reference, query),
+        )
+        .slice(0, MENTION_OPTION_LIMIT),
+    toReference: (part: DirectCodexUserContentPart): ChatReference | null => {
+      if (part.type !== 'agc_resource_reference') return null;
+      const asset = resourceProviderData(assets).byId.get(part.resourceId);
+      // 资产已不在 manifest（已删除）：这里不合成引用，由调用方按同一份清单显式报缺口，
+      // 而不是静默把一条「带参考」变成「无参考」。
+      return asset ? resourceReferenceFromAsset(asset, 'asset-picker') : null;
+    },
+    refresh: (reference) =>
+      reference.type === 'resource'
+        ? refreshResourceReference(reference, resourceProviderData(assets).byId)
+        : null,
+    mentionToken: (part) => {
+      if (part.type !== 'agc_resource_reference') return null;
+      const asset = resourceProviderData(assets).byId.get(part.resourceId);
+      if (!asset) return `@${part.resourceId}`;
+      return `@${resourceDisplayName(asset)}`;
+    },
+    // manifest 还空着时先别把草稿落进编辑器：这时候落下去，引用会被当成「已删除」丢掉。
+    isReady: () => assets.length > 0,
+  };
+}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/runtimeRegionReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/runtimeRegionReferenceProvider.ts
new file mode 100644
index 000000000..1a662443a
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/runtimeRegionReferenceProvider.ts
@@ -0,0 +1,45 @@
+import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
+import type {
+  ChatReference,
+  RuntimeRegionReference,
+} from '../resourceReferences';
+import type { ReferenceProvider } from './types';
+
+/**
+ * 运行画面区域引用的 provider：**静默**（没有触发符、没有候选）。
+ *
+ * 这类引用来自本地游戏预览里的选点动作，走 `RESOURCE_REFERENCE_INSERT_EVENT` 直接进正文，
+ * 从来没有过候选菜单；它在这里负责的是跨会话草稿回填与 `@标签` 文本形态。
+ */
+export function createRuntimeRegionReferenceProvider(): ReferenceProvider {
+  return {
+    trigger: null,
+    toReference: (part: DirectCodexUserContentPart): ChatReference | null => {
+      if (part.type !== 'agc_runtime_region_reference') return null;
+      return {
+        type: 'runtime-region',
+        label: part.label,
+        runId: part.runId ?? undefined,
+        versionId: part.versionId ?? undefined,
+        elementTag: part.elementTag ?? undefined,
+        elementRole: part.elementRole ?? undefined,
+        text: part.text ?? undefined,
+        width: part.width ?? undefined,
+        height: part.height ?? undefined,
+        resourceIds: part.resourceIds,
+        source: 'runtime-picker',
+      } satisfies RuntimeRegionReference;
+    },
+    refresh: (reference: ChatReference): ChatReference | null =>
+      reference.type === 'runtime-region' ? reference : null,
+    mentionToken: (part) =>
+      part.type === 'agc_runtime_region_reference' ? `@${part.label}` : null,
+  };
+}
+
+/**
+ * 运行画面区域 provider 无状态，宿主可以共用同一个实例。
+ * 它没有触发符，所以「注入它」不会给输入区加出任何候选入口。
+ */
+export const runtimeRegionReferenceProvider =
+  createRuntimeRegionReferenceProvider();
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
new file mode 100644
index 000000000..e3c34da47
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
@@ -0,0 +1,127 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import { resolveTauriInvoke } from '../../../app/tauri';
+import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
+import type { ChatReference } from '../resourceReferences';
+import type { ReferenceProvider } from './types';
+
+/** 候选菜单最多展示多少条：与资源候选同一上限。 */
+const MENTION_OPTION_LIMIT = 8;
+
+type SkillCatalogItem = { name: string; description?: string };
+
+/**
+ * 读应用级 Skill 目录：内置 Skill 与已启用的客户端 Skill 合起来是同一份候选。
+ *
+ * 这是一次**应用级**读取（不是项目清单），所以只在用户第一次敲出 `$` 时发生：
+ * 挂载即查询会让「工作区路径非法时不产生任何后端访问」的边界失效。
+ * 查询失败时放开已请求标记：一次瞬时失败不能让这个输入区此后永远拿不到技能候选。
+ */
+function loadSkillCatalog(): Promise<SkillCatalogItem[]> {
+  const invoke = resolveTauriInvoke();
+  if (!invoke) return Promise.resolve([]);
+  return Promise.all([
+    invoke<Array<{ name: string; description: string }>>(
+      'list_agc_skill_catalog',
+    ).then((items) =>
+      items.map((item) => ({
+        name: item.name,
+        description: item.description,
+      })),
+    ),
+    invoke<
+      Array<{
+        name: string;
+        extensionType: string;
+        enabled: boolean;
+        status: string;
+      }>
+    >('list_client_extensions').then((items) =>
+      items
+        .filter(
+          (item) =>
+            item.extensionType === 'skill' &&
+            item.enabled &&
+            item.status === 'enabled',
+        )
+        .map((item) => ({ name: item.name })),
+    ),
+  ]).then(([builtin, client]) => [...builtin, ...client]);
+}
+
+function matchesSkillQuery(skill: SkillCatalogItem, query: string) {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return true;
+  return (
+    skill.name.toLowerCase().includes(normalized) ||
+    (skill.description?.toLowerCase().includes(normalized) ?? false)
+  );
+}
+
+/**
+ * Skill 引用的 provider（宿主 hook）。
+ *
+ * 与资源 provider 不同，Skill 候选是**异步**的应用级读取，所以它必须是一份 React 状态：
+ * 用户敲出 `$` 打开候选菜单时（`onMenuQueryChange` 收到非 `null`，由输入区在 effect 里回调）
+ * 发起读取，结果到了之后宿主重渲染，输入区随之拿到新的候选。
+ * `match` 保持纯函数，候选只从已就绪的状态里过滤——渲染阶段不产生任何副作用。
+ * 读取本身不进输入区，只有宿主才知道这条路该不该存在——
+ * 目前只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill。
+ */
+export function useSkillReferenceProvider(): ReferenceProvider {
+  const [skills, setSkills] = useState<SkillCatalogItem[]>([]);
+  const requestedRef = useRef(false);
+
+  const ensureCatalog = useCallback(() => {
+    if (requestedRef.current) return;
+    requestedRef.current = true;
+    void loadSkillCatalog()
+      .then((items) => setSkills(items))
+      .catch((error) => {
+        // 失败不静默：一次瞬时失败会在下一次菜单查询变化（继续敲字或重开菜单）时重试，
+        // 但持续失败至少要在控制台留痕，否则用户看到的是「敲 `$` 什么都没有」，排障时没有任何线索。
+        console.warn(
+          '[skill-reference] Skill 目录读取失败，下次触发重试',
+          error,
+        );
+        requestedRef.current = false;
+        setSkills([]);
+      });
+  }, []);
+
+  return useMemo(
+    () => ({
+      trigger: '$',
+      // 懒加载走菜单回调：只有用户真的敲出 `$`（query 非 null）时才值得读这份应用级目录。
+      onMenuQueryChange: (query) => {
+        if (query !== null) ensureCatalog();
+      },
+      match: (query) => {
+        const seen = new Set<string>();
+        return skills
+          .filter((skill) => {
+            if (seen.has(skill.name)) return false;
+            seen.add(skill.name);
+            return matchesSkillQuery(skill, query);
+          })
+          .slice(0, MENTION_OPTION_LIMIT)
+          .map(
+            (skill): ChatReference => ({
+              type: 'skill',
+              name: skill.name,
+              description: skill.description,
+            }),
+          );
+      },
+      toReference: (part: DirectCodexUserContentPart): ChatReference | null =>
+        part.type === 'agc_skill_reference'
+          ? { type: 'skill', name: part.name }
+          : null,
+      refresh: (reference: ChatReference): ChatReference | null =>
+        reference.type === 'skill' ? reference : null,
+      mentionToken: (part) =>
+        part.type === 'agc_skill_reference' ? `$${part.name}` : null,
+    }),
+    [ensureCatalog, skills],
+  );
+}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts
new file mode 100644
index 000000000..ca138d75f
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts
@@ -0,0 +1,49 @@
+import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
+import type { ChatReference } from '../resourceReferences';
+
+/**
+ * 宿主注入给引用输入区的一种引用来源。
+ *
+ * 一个 provider 只认一种引用：候选、身份解析、改名刷新与「它在正文里的文本形态」都归它。
+ * 输入区按 `providers` 数组顺序取**第一个非空回答**，不判断引用种类，也不认识任何具体字段；
+ * 「没注入就没有这类引用」是默认，可见性不需要额外的开关。
+ *
+ * 每种引用一个独立工厂，宿主按需选择性注入——只注入资源 provider 就只有 `@`，
+ * 再注入 Skill provider 才出现 `$`。**不做总装 builder**。
+ */
+export type ReferenceProvider = {
+  /**
+   * 触发候选菜单的字符（`@` / `$`）；`null` 表示静默 provider：
+   * 它仍参与 part 身份解析、改名刷新与文本形态，但不会在输入区里开出候选菜单
+   * （附件、运行画面区域就是这样进来的）。
+   */
+  trigger: string | null;
+  /**
+   * 候选项：过滤、排序与截断都在 provider 内部完成。静默 provider 不实现。
+   *
+   * **必须是纯函数**：输入区在渲染阶段（`useMemo`）调用它，读清单、写 ref、发请求都会
+   * 在渲染期生效。需要为「菜单打开」拉一次数据时，用下面的 `onMenuQueryChange`。
+   */
+  match?: (query: string) => ChatReference[];
+  /**
+   * 候选菜单的查询变化（菜单关闭时收到 `null`）；输入区在 `useEffect` 里调它，**只在
+   * 带触发符的 provider 上调用**。
+   *
+   * 这是懒加载的唯一入口：例如 Skill 目录是应用级异步读取，第一次收到非 `null` 时再发起，
+   * 挂载即查询会让「工作区路径非法时不产生任何后端访问」的边界失效。
+   */
+  onMenuQueryChange?: (query: string | null) => void;
+  /** canonical part → 引用；不属于本 provider 或暂时无法解析时返回 `null`。 */
+  toReference: (part: DirectCodexUserContentPart) => ChatReference | null;
+  /** 引用身份刷新（资源改名等）；不属于本 provider 时返回 `null`，原样返回表示无需改写。 */
+  refresh: (reference: ChatReference) => ChatReference | null;
+  /** part 在正文文本里的 token（`@显示名` / `$名称`）；不属于本 provider 时返回 `null`。 */
+  mentionToken: (part: DirectCodexUserContentPart) => string | null;
+  /**
+   * 数据是否已经到齐（例如 manifest 还没加载完时为 `false`）；省略表示始终就绪。
+   *
+   * 输入区用它决定「要不要现在就把初始草稿落进编辑器」：草稿里有本 provider 认不出、
+   * 但它迟早能认出来的 part 时先不落，否则那条引用会被静默丢掉。
+   */
+  isReady?: () => boolean;
+};
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts b/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
index 00cbea707..85f814c3f 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
@@ -53,10 +53,21 @@ export type SkillReference = {
   description?: string;
 };
 
+/**
+ * 聊天附件在正文里的引用形态。
+ *
+ * 与 canonical part `agc_attachment_reference` 逐字同字段（名称、类型、大小、项目相对路径、状态），
+ * 因为「导入成功即入正文」之后，附件芯片就是本轮附件的唯一事实源，没有第二份状态可以回退。
+ */
+export type AttachmentReference = {
+  type: 'attachment';
+} & DirectCodexUserAttachmentReferencePart;
+
 export type ChatReference =
   | ResourceReference
   | RuntimeRegionReference
-  | SkillReference;
+  | SkillReference
+  | AttachmentReference;
 
 export type ChatComposerDraft = {
   /** Lexical 节点按顺序投影出的 canonical user content，唯一事实源。 */
@@ -67,7 +78,6 @@ export type ChatComposerDraft = {
 export type DirectCodexLegacyContentDto = {
   text: string;
   references: ChatReference[];
-  attachments: DirectCodexUserAttachmentReferencePart[];
 };
 
 export const RESOURCE_REFERENCE_INSERT_EVENT = 'agc-resource-reference-insert';
@@ -128,36 +138,82 @@ export function isResourceReferenceOverlayTarget(target: EventTarget | null) {
 }
 
 /**
- * canonical content → 可读文本；资源引用按当前 manifest 展开为显示名。
+ * 资源显示名解析：由调用方注入，函数自己不去读 manifest。
  *
- * **逐字投影，不裁剪空白**：前端不替用户改写输入，只有整条 content 的全空白判定
- * （`hasMeaningfulDirectCodexContent`）算「空」。需要首尾裁剪的调用方在自己的边界做。
+ * 返回 `undefined` 时按引用自带的 `resourceId` 兜底显示，保持「引用不因清单缺失而消失」的口径。
+ */
+export type ResourceLabelResolver = (resourceId: string) => string | undefined;
+
+/** 按 manifest 取资源显示名；引用已不在清单时返回 `undefined`。 */
+export function resourceLabelResolver(
+  assets: readonly GameCreationAppAssetManifestEntry[],
+): ResourceLabelResolver {
+  return (resourceId) => {
+    const asset = assets.find((item) => item.id === resourceId);
+    return asset ? resourceDisplayName(asset) : undefined;
+  };
+}
+
+/**
+ * canonical content → 可读文本；每个引用 part 经 `tokenOf` 展开，文本 part 逐字保留。
+ *
+ * **每个 token 前后各留一个空白**（相邻已是空白或相邻就是另一个 token 时不重复补）：这样
+ * 出站文本与「前后是空白 / 行首行尾」的反解析口径自洽，`@显示名` 紧贴中文的写法不会出现。
+ * 逐字保留文本 part 自己的空白，只有整条 content 的全空白判定
+ * （`hasMeaningfulDirectCodexContent`）算「空」；需要首尾裁剪的调用方在自己的边界做。
+ */
+export function joinMentionText(
+  content: readonly DirectCodexUserContentPart[],
+  tokenOf: (part: DirectCodexUserContentPart) => string | null,
+): string {
+  let text = '';
+  // 上一个 token 的后置空白尚未落地：下一个 part 决定它是被吃掉（本来就以空白开头）
+  // 还是真的补出来，避免出现双空白。
+  let pendingBlank = false;
+  for (const part of content) {
+    const token = tokenOf(part);
+    if (token === null) {
+      if (part.type !== 'input_text' || part.text === '') continue;
+      if (pendingBlank) {
+        pendingBlank = false;
+        if (!/^\s/u.test(part.text)) text += ' ';
+      }
+      text += part.text;
+      continue;
+    }
+    if (pendingBlank) {
+      text += ' ';
+      pendingBlank = false;
+    } else if (!/\s$/u.test(text)) {
+      text += ' ';
+    }
+    text += token;
+    pendingBlank = true;
+  }
+  return pendingBlank ? `${text} ` : text;
+}
+
+/**
+ * canonical content → 可读文本；资源引用按调用方注入的解析器展开为显示名。
+ *
+ * 显示名解析不进这个函数：调用方（聊天控制器、队列 chip、legacy 投影）各自持有清单，
+ * 由它们把 `resourceLabelResolver(assets)` 传进来。
+ *
+ * TODO we will rewrite this with ref as component later.
+ * （引用最终要作为组件参与渲染，那时这层「content → 文本」的展开就由组件自己承担，
+ * 这里的 token 拼接只是当前口径的落点。）
  */
 export function directCodexContentToPromptText(
   content: readonly DirectCodexUserContentPart[],
-  assets: readonly GameCreationAppAssetManifestEntry[],
+  resolveResourceLabel: ResourceLabelResolver,
 ) {
-  const labels = new Map(
-    assets.map((asset) => [asset.id, resourceDisplayName(asset)]),
-  );
-  return content
-    .map((part) => {
-      if (part.type === 'input_text') return part.text;
-      if (part.type === 'agc_resource_reference') {
-        return `@${labels.get(part.resourceId) ?? part.resourceId}`;
-      }
-      if (part.type === 'agc_skill_reference') {
-        return `$${part.name}`;
-      }
-      if (part.type === 'agc_runtime_region_reference') {
-        return `@${part.label}`;
-      }
-      if (part.type === 'agc_attachment_reference') {
-        return `@${part.name}`;
-      }
-      return '';
-    })
-    .join('');
+  return joinMentionText(content, (part) => {
+    if (part.type === 'input_text') return null;
+    if (part.type === 'agc_attachment_reference') return `@${part.name}`;
+    if (part.type === 'agc_skill_reference') return `$${part.name}`;
+    if (part.type === 'agc_runtime_region_reference') return `@${part.label}`;
+    return `@${resolveResourceLabel(part.resourceId) ?? part.resourceId}`;
+  });
 }
 
 /** 只在整条 content 上判定有效性；单个纯空白文本 part 合法。 */
@@ -205,6 +261,16 @@ export function chatReferenceToContentPart(
   if (reference.type === 'skill') {
     return { type: 'agc_skill_reference', name: reference.name };
   }
+  if (reference.type === 'attachment') {
+    return {
+      type: 'agc_attachment_reference',
+      name: reference.name,
+      mediaType: reference.mediaType,
+      size: reference.size,
+      localPath: reference.localPath,
+      status: reference.status,
+    };
+  }
   return {
     type: 'agc_runtime_region_reference',
     label: reference.label,
@@ -220,26 +286,25 @@ export function chatReferenceToContentPart(
 }
 
 /**
- * part 在「文本 → content」反解析里的可扫描 token：与 `directCodexContentToPromptText`
- * 出站口径逐字一致——附件是 `@附件名`，资源与 runtime 引用是 `@显示名`，Skill 是 `$名称`。
- * `input_text` 没有 token，返回 `null`。
+ * 单条引用在文本里的可扫描 token：与出站口径逐字一致——附件 `@附件名`、Skill `$名称`、
+ * 资源与运行画面区域 `@显示名`。资源引用自带显示名，所以这里不必再查 manifest。
  */
-export function contentPartMentionToken(
-  part: DirectCodexUserContentPart,
-  resourceLabels: ReadonlyMap<string, string>,
-): string | null {
-  if (part.type === 'input_text') return null;
-  if (part.type === 'agc_attachment_reference') return `@${part.name}`;
-  if (part.type === 'agc_skill_reference') return `$${part.name}`;
-  if (part.type === 'agc_runtime_region_reference') return `@${part.label}`;
-  return `@${resourceLabels.get(part.resourceId) ?? part.resourceId}`;
+export function chatReferenceMentionToken(reference: ChatReference): string {
+  if (reference.type === 'skill') return `$${reference.name}`;
+  if (reference.type === 'attachment') return `@${reference.name}`;
+  return `@${reference.label}`;
 }
 
-/** 单条引用在文本里的可扫描 token（引用自带显示名，不必再查 manifest）。 */
-export function chatReferenceMentionToken(reference: ChatReference): string {
-  return reference.type === 'skill'
-    ? `$${reference.name}`
-    : `@${reference.label}`;
+/**
+ * 候选菜单的副标题：引用自带的补充说明。
+ *
+ * 只在这里按引用种类分支——输入区与选择器都按这一份口径渲染，不各自再判一次类型。
+ */
+export function chatReferenceDisplayHint(reference: ChatReference): string {
+  if (reference.type === 'resource') return reference.kind;
+  if (reference.type === 'skill') return reference.description ?? 'Skill';
+  if (reference.type === 'attachment') return reference.mediaType || '附件';
+  return reference.elementTag ?? '运行区域';
 }
 
 /** 一条待恢复 part 与它在文本里的 token。 */
@@ -358,24 +423,18 @@ export function buildContentFromTextTokens(
  *
  * 面板重开草稿、润色回包等 legacy 输入都走这一条翻译；文本里保留着 `@显示名` / `$名称` /
  * `@附件名` 就能原位恢复 chip，整体被改写的 part 补在末尾（见 `buildContentFromTextTokens`）。
+ * 附件就是 `references` 里的 `attachment` 成员：本轮附件只有「正文芯片」一份事实源，
+ * 这里不再有第二个 `attachments` 数组可以叠加。
  */
 export function legacyContentDtoToContent(dto: {
   text: string;
   references: readonly ChatReference[];
-  attachments?: readonly DirectCodexUserAttachmentReferencePart[];
 }): DirectCodexUserContentPart[] {
   return buildContentFromTextTokens(dto.text, [
     ...dto.references.map((reference) => ({
       token: chatReferenceMentionToken(reference),
       part: chatReferenceToContentPart(reference),
     })),
-    ...(dto.attachments ?? []).map((attachment) => ({
-      token: `@${attachment.name}`,
-      part: {
-        type: 'agc_attachment_reference' as const,
-        ...attachment,
-      },
-    })),
   ]);
 }
 
@@ -419,7 +478,13 @@ function unresolvedResourceReference(resourceId: string): ResourceReference {
   };
 }
 
-/** canonical content → legacy text + reference + attachment DTO。只允许单向翻译。 */
+/**
+ * canonical content → legacy text + reference DTO。只允许单向翻译。
+ *
+ * 附件也在 `references` 里（`attachment` 成员），所以这一层不需要第二个附件数组；
+ * 资源引用要带回 manifest 的完整身份（kind / mediaType / 分类 / 标签），所以这一层
+ * 仍然收 `assets`，只是把显示名展开交给 `resourceLabelResolver` 这一份注入的口径。
+ */
 export function directCodexContentToLegacyContentDto(
   content: readonly DirectCodexUserContentPart[],
   assets: readonly GameCreationAppAssetManifestEntry[],
@@ -453,14 +518,25 @@ export function directCodexContentToLegacyContentDto(
     }
     if (part.type === 'agc_skill_reference') {
       references.push({ type: 'skill', name: part.name });
+      return;
+    }
+    if (part.type === 'agc_attachment_reference') {
+      references.push({
+        type: 'attachment',
+        name: part.name,
+        mediaType: part.mediaType,
+        size: part.size,
+        localPath: part.localPath,
+        status: part.status,
+      });
     }
   });
   return {
-    text: directCodexContentToPromptText(content, assets),
-    references,
-    attachments: content.flatMap((part) =>
-      part.type === 'agc_attachment_reference' ? [part] : [],
+    text: directCodexContentToPromptText(
+      content,
+      resourceLabelResolver(assets),
     ),
+    references,
   };
 }
 
@@ -485,6 +561,45 @@ export function resourceReferenceFromAsset(
   };
 }
 
+/**
+ * `@` 候选只收「有本地文件、且不是 `.agent/` 内部产物」的已登记素材。
+ * 判据只影响候选与引用身份解析，不影响 manifest 本身。
+ */
+export function isMentionableAsset(asset: GameCreationAppAssetManifestEntry) {
+  return Boolean(asset.localPath) && !asset.localPath.startsWith('.agent/');
+}
+
+/** 可提及素材 → 候选引用（`@` 面板与 `@` 候选共用同一份投影）。 */
+export function mentionableAssetReferences(
+  assets: readonly GameCreationAppAssetManifestEntry[],
+  source: ResourceReferenceSource,
+) {
+  return assets
+    .filter(isMentionableAsset)
+    .map((asset) => resourceReferenceFromAsset(asset, source));
+}
+
+/**
+ * 引用显示名只由 manifest 资产内容决定，而调用方每次渲染都会重建 assets 数组，
+ * 这里用内容签名做缓存键，避免与改名无关的渲染反复重算。
+ */
+export function assetsSignature(
+  assets: readonly GameCreationAppAssetManifestEntry[],
+) {
+  return assets
+    .map((asset) =>
+      [
+        asset.id,
+        asset.kind,
+        asset.mediaType,
+        asset.localPath,
+        asset.category ?? '',
+        gameCreationAppAssetTags(asset).join(','),
+      ].join('\u0000'),
+    )
+    .join('\u0001');
+}
+
 export function sameResourceReference(
   left: ResourceReference,
   right: ResourceReference,
@@ -673,13 +788,23 @@ function runtimeRegionReferenceDiscriminators(
   }:${reference.width ?? ''}:${reference.height ?? ''}:${resourceIds}`;
 }
 
-function chatReferenceKey(reference: ChatReference) {
+/**
+ * 引用的身份键：只认稳定身份，**不含显示名**。
+ *
+ * 同一个显示名可以来自两条不同引用（`characters/hero.png` 与 `enemies/hero.png` 都展开成
+ * `@hero`），所以去重与候选菜单的 React key 都必须用它，而不是显示 token。
+ */
+export function chatReferenceKey(reference: ChatReference) {
   if (reference.type === 'resource') {
     return `resource:${reference.resourceId}:${reference.source}`;
   }
   if (reference.type === 'skill') {
     return `skill:${reference.name}`;
   }
+  if (reference.type === 'attachment') {
+    // 附件身份落在导入产物上：同名文件可以来自不同目录，项目相对路径才是它的唯一身份。
+    return `attachment:${reference.localPath}:${reference.name}`;
+  }
   return `runtime-region:${runtimeRegionReferenceDiscriminators(reference)}`;
 }
 
@@ -696,6 +821,9 @@ export function chatReferenceListKey(references: ChatReference[]) {
       if (reference.type === 'skill') {
         return `skill:${reference.name}`;
       }
+      if (reference.type === 'attachment') {
+        return `attachment:${reference.localPath}:${reference.name}`;
+      }
       return `runtime-region:${runtimeRegionReferenceDiscriminators(reference)}`;
     })
     .join('\u0001');
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/GameRunVersionPicker.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/GameRunVersionPicker.tsx
index 65a739217..bc5d79f0f 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/GameRunVersionPicker.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/GameRunVersionPicker.tsx
@@ -75,7 +75,14 @@ export function GameRunVersionPicker({
         aria-label={`当前版本：${formatIterationVersionLabel(currentVersion)}`}
         onClick={() => setOpen((current) => !current)}
       >
-        {formatIterationVersionLabel(currentVersion)}
+        {/*
+          版本名可能很长（`初始版本 · 2026/9/19 02:10:03`）。按钮是 flex 容器，直接放文本节点
+          时 `text-overflow: ellipsis` 不生效（匿名 flex item 不参与父级省略），所以套一层
+          span 由它省略（见样式里的 `.game-run-version-trigger-label`）。
+        */}
+        <span className="game-run-version-trigger-label">
+          {formatIterationVersionLabel(currentVersion)}
+        </span>
       </button>
       {open
         ? createPortal(
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
index 9e7abb194..70f91e38a 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
@@ -5,6 +5,7 @@ import {
   type CSSProperties,
   type FormEvent,
   useEffect,
+  useMemo,
   useRef,
   useState,
 } from 'react';
@@ -21,11 +22,20 @@ import { EDITOR_ICON_DESCRIPTION_MAX_CHARS } from '../../../../../src/services/i
 import { ThemedModal } from '../../components/modal/ThemedModal';
 import type { DirectCodexUserContentPart } from '../../view/project-development/chat/generated/DirectCodexUserContentPart';
 import { resourceEditPromptMaxLength } from '../../view/project-development/resourceEditModel';
+import { attachmentReferenceProvider } from '../project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../project-workspace/reference-source/runtimeRegionReferenceProvider';
 import {
   ResourceReferenceInput,
   type ResourceReferenceInputHandle,
 } from '../project-workspace/ResourceReferenceInput';
 import {
+  ResourceReferencePicker,
+  ResourceReferencePickerAction,
+  type ResourceReferencePickerHandle,
+} from '../project-workspace/ResourceReferencePicker';
+import {
+  assetsSignature,
   type ChatComposerDraft,
   directCodexContentKey,
   directCodexContentToLegacyContentDto,
@@ -253,6 +263,24 @@ export function ResourceCanvasAssetGenerationPanelView({
   const referenceAssets = resourceCanvasAssetGenerationReferenceAssets(
     assets ?? [],
   );
+  const referenceAssetsSignature = assetsSignature(referenceAssets);
+  /*
+    引用来源：画布生成面板只注入资源与两个静默 provider——它把 `@` 引用当参考图用，
+    而 `$` Skill 候选只有 DirectProject 回合那条路径会被解析成真 Skill，这里不注入。
+   */
+  const referenceProviders = useMemo(
+    () => [
+      createResourceReferenceProvider({ assets: referenceAssets }),
+      attachmentReferenceProvider,
+      runtimeRegionReferenceProvider,
+    ],
+    // `referenceAssets` 每次渲染都是新数组（`.filter()` 派生），依赖它等于从不命中缓存：
+    // provider 身份一变，输入区就会重新注册 Lexical 更新监听。按内容签名取依赖才真的能跳过重建。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [referenceAssetsSignature],
+  );
+  const promptInputRootRef = useRef<HTMLDivElement | null>(null);
+  const referencePickerRef = useRef<ResourceReferencePickerHandle | null>(null);
   /*
     content 是唯一事实源：提示词与引用在这里单向派生，面板不各存一份镜像。
 
@@ -473,14 +501,30 @@ export function ResourceCanvasAssetGenerationPanelView({
                 ariaLabel="生成提示词"
                 initialContent={content}
                 onChange={applyDraft}
-                assets={referenceAssets}
+                providers={referenceProviders}
                 projectPath={projectPath ?? ''}
-                versions={versions}
-                activeVersionId={activeVersionId}
                 multiline
                 rows={3}
                 placeholder={`${action.promptPlaceholder}（可用 @ 选择参考图）`}
                 showPolishAction={false}
+                containerRef={promptInputRootRef}
+                inputActions={
+                  <ResourceReferencePickerAction
+                    onOpen={() => referencePickerRef.current?.open()}
+                  />
+                }
+              />
+              {/* 素材选择器由宿主渲染、自己拿数据；确认后只把选中的引用交回输入区句柄。 */}
+              <ResourceReferencePicker
+                ref={referencePickerRef}
+                anchorRef={promptInputRootRef}
+                assets={referenceAssets}
+                versions={versions}
+                activeVersionId={activeVersionId}
+                projectPath={projectPath ?? ''}
+                onInsert={(references) =>
+                  promptInputRef.current?.insertReferences(references)
+                }
               />
             </div>
           ) : (
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
index f526ea984..3399d5376 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
@@ -56,7 +56,7 @@ export type ResourceCanvasAssetGenerationTasksPanelViewProps = {
    *
    * 两页之间切换时锚点高度走样式里的 transition，不瞬移。
    */
-  placement?: 'canvas-overview' | 'canvas' | 'run' | 'editor';
+  placement?: 'canvas-overview' | 'canvas' | 'editor';
 };
 
 /**
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
index fc6cbf3d3..cb53b2c14 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
@@ -23,8 +23,9 @@
  * 偏移量迟早会压在工具条上（验收现场那条「生成任务和菜单栏重叠」就是这么来的）。
  * 放进同一个网格单元格以后，「画布顶边 + 一小段内缩」由网格自己保证，工具条多高都不用管。
  *
- * 分档：资源栏目画布与 UI 编辑器在第二 / 第三行，运行表现层占 `2 / -1` 且它右上角
- * （`top: 20px; right: 20px`）被版本入口占着，所以那一档把内缩上边距加大到版本入口之下。
+ * 分档：资源栏目画布与 UI 编辑器各一档（第二 / 第三行）。**运行表现层没有这一档**——
+ * 运行页不挂这个锚点（见 `project-development/index.tsx`），画面右上角留给版本入口与
+ * 预览地址小字。
  */
 .game-resource-generation-tasks-anchor {
   grid-row: 3;
@@ -67,11 +68,6 @@
   margin-top: calc(2.625rem + 0.5rem);
 }
 
-.game-resource-generation-tasks-anchor[data-generation-tasks-placement='run'] {
-  grid-row: 2 / -1;
-  margin: 3.5rem 1.1rem 0.85rem 0.85rem;
-}
-
 .game-resource-generation-tasks-anchor[data-generation-tasks-placement='editor'] {
   grid-row: 2;
 }
diff --git a/apps/ai-game-creator-shell/src/services/assetDirectUpload.ts b/apps/ai-game-creator-shell/src/services/assetDirectUpload.ts
new file mode 100644
index 000000000..d0b00b106
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/services/assetDirectUpload.ts
@@ -0,0 +1,167 @@
+import { fetch as tauriHttpFetch } from '@tauri-apps/plugin-http';
+
+import { requestClientApi } from './clientApi';
+
+/** 直传凭证里的对象存储目标；字段口径与平台 `/api/assets/direct-upload-tickets` 一致。 */
+type DirectUploadTicketResponse = {
+  upload: {
+    bucket: string;
+    host: string;
+    objectKey: string;
+    legacyPublicPath: string;
+    formFields: Record<string, string | null | undefined>;
+  };
+};
+
+type ConfirmAssetObjectResponse = {
+  assetObject: {
+    assetObjectId: string;
+    objectKey: string;
+    assetKind: string;
+  };
+};
+
+export type UploadedPlatformAsset = {
+  assetObjectId: string;
+  objectKey: string;
+};
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * 平台直传凭证支持的 OSS 主机白名单前缀。
+ *
+ * Tauri 的 http 插件只允许访问 `capabilities/main.json` 里声明的地址，这里再做一次校验，
+ * 保证即使能力配置放宽到 `*.aliyuncs.com`，客户端也只把文件发到平台素材存储，而不是任意主机。
+ */
+const PLATFORM_UPLOAD_HOST_SUFFIXES = ['.aliyuncs.com'];
+
+function isLocalUploadHost(parsed: URL) {
+  return (
+    parsed.protocol === 'http:' &&
+    (parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost')
+  );
+}
+
+/** 校验直传地址；不是平台素材存储时直接失败关闭，避免把本地文件发给第三方主机。 */
+export function resolvePlatformAssetUploadUrl(host: string) {
+  const trimmedHost = host.trim();
+  if (!trimmedHost) {
+    throw new Error('素材上传地址为空，请稍后重试');
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmedHost);
+  } catch {
+    throw new Error('素材上传地址无效，请稍后重试');
+  }
+  const isOssHost =
+    parsed.protocol === 'https:' &&
+    PLATFORM_UPLOAD_HOST_SUFFIXES.some((suffix) =>
+      parsed.hostname.endsWith(suffix),
+    );
+  if (!isOssHost && !isLocalUploadHost(parsed)) {
+    throw new Error('素材上传地址不属于平台素材存储，已终止上传');
+  }
+  return parsed.toString();
+}
+
+function buildDirectUploadFormData(
+  upload: DirectUploadTicketResponse['upload'],
+  file: File,
+) {
+  const formData = new FormData();
+  Object.entries(upload.formFields ?? {}).forEach(([key, value]) => {
+    if (value !== null && value !== undefined) {
+      formData.append(key, value);
+    }
+  });
+  // OSS 要求 file 字段位于表单末尾，否则签名校验会失败。
+  formData.append('file', file, file.name);
+  return formData;
+}
+
+/**
+ * 把本地文件上传成平台素材对象并返回素材标识。
+ *
+ * 三步与网页端一致：申请直传凭证 → 直传对象存储 → confirm 登记素材。AGC 无法在浏览器里
+ * 直接跨域直传 OSS，所以直传这一步固定走 Tauri HTTP 插件（Rust 侧发起请求）。
+ */
+export async function uploadPlatformMediaAsset(args: {
+  file: File;
+  assetKind: string;
+  pathSegments: string[];
+  entityId: string;
+  metadata?: Record<string, string>;
+  /** 单测注入的直传实现；正式运行时固定使用 Tauri HTTP。 */
+  fetchImpl?: FetchLike;
+}): Promise<UploadedPlatformAsset> {
+  const fileName = args.file.name.trim() || 'cover.png';
+  const contentType = args.file.type.trim() || 'application/octet-stream';
+  const ticket = await requestClientApi<DirectUploadTicketResponse>(
+    '/api/assets/direct-upload-tickets',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        legacyPrefix: 'generated-character-drafts',
+        pathSegments: args.pathSegments,
+        fileName,
+        contentType,
+        access: 'private',
+        maxSizeBytes: args.file.size,
+        metadata: {
+          asset_kind: args.assetKind,
+          ...args.metadata,
+        },
+      }),
+    },
+    '创建素材上传凭证失败',
+  );
+
+  const uploadHost = resolvePlatformAssetUploadUrl(ticket.upload.host);
+  const uploadFetch = args.fetchImpl ?? tauriHttpFetch;
+  let uploadResponse: Response;
+  try {
+    uploadResponse = await uploadFetch(uploadHost, {
+      method: 'POST',
+      body: buildDirectUploadFormData(ticket.upload, args.file),
+    });
+  } catch (error) {
+    // Tauri http 插件在目标不在能力作用域、网络不可达或请求被取消时直接抛错；
+    // 统一转成可操作文案，避免把英文插件错误原样暴露给作者。
+    const detail = error instanceof Error ? error.message.trim() : '';
+    throw new Error(
+      `上传素材失败：无法访问素材存储，请检查网络后重试${
+        detail ? `（${detail.slice(0, 120)}）` : ''
+      }`,
+    );
+  }
+  if (!uploadResponse.ok) {
+    throw new Error(
+      `上传素材到对象存储失败（HTTP ${uploadResponse.status}），请重试`,
+    );
+  }
+
+  const confirmed = await requestClientApi<ConfirmAssetObjectResponse>(
+    '/api/assets/objects/confirm',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bucket: ticket.upload.bucket,
+        objectKey: ticket.upload.objectKey,
+        contentType,
+        contentLength: args.file.size,
+        assetKind: args.assetKind,
+        accessPolicy: 'private',
+        entityId: args.entityId,
+      }),
+    },
+    '确认素材资产失败',
+  );
+  return {
+    assetObjectId: confirmed.assetObject.assetObjectId,
+    objectKey: confirmed.assetObject.objectKey,
+  };
+}
diff --git a/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts b/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts
new file mode 100644
index 000000000..51cd91e82
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts
@@ -0,0 +1,269 @@
+import type { GameCreationAppManifest } from '../../../../packages/shared/src/contracts/gameCreationApp';
+import type {
+  GameDistributionCategory,
+  GameDistributionCreateGameRequest,
+  GameDistributionCreateVersionRequest,
+  GameDistributionInputMode,
+  GameDistributionOrientation,
+} from '../../../../packages/shared/src/contracts/gameDistribution';
+import type {
+  LocalProjectExportPackagePayload,
+  TauriInvoke,
+} from '../app/types';
+import { requestClientApi } from './clientApi';
+
+export type GameDistributionPublishMetadata = {
+  title: string;
+  summary: string;
+  description: string;
+  category: GameDistributionCategory;
+  tags: string[];
+  /** 平台素材库里的封面素材 ID；服务端要求发布必须带封面。 */
+  coverAssetId: string;
+  /** 平台素材库里的截图素材 ID，最多 6 张。 */
+  screenshots?: string[];
+  deviceSupport: {
+    desktop: boolean;
+    mobile: boolean;
+    touch: boolean;
+  };
+  inputModes: GameDistributionInputMode[];
+  orientation: GameDistributionOrientation;
+};
+
+/** 游戏截图上限与服务端 `MAX_GAME_SCREENSHOTS` 保持一致。 */
+export const MAX_AGC_GAME_SCREENSHOTS = 6;
+
+type FrontendRuntimeConfigResponse = {
+  imageEditorAgentSidebarEnabled?: boolean;
+  agcTemplateLibraryEnabled?: boolean;
+  gameDistributionPublishEnabled?: boolean;
+};
+
+/**
+ * 读取当前账号的游戏发布灰度。
+ *
+ * 与网页端共用 `/api/runtime/frontend-config`：后端未配置 `game-distribution:publish`
+ * 时对已登录作者默认开放，运营收紧后只有白名单/灰度命中的作者返回 `true`。读取失败按
+ * “不开放入口”处理——写入口本身还会再拦一次，AGC 面板不作为唯一把关点。
+ */
+export async function readGamePublishAvailability(): Promise<boolean> {
+  const config = await requestClientApi<FrontendRuntimeConfigResponse>(
+    '/api/runtime/frontend-config',
+    { method: 'GET' },
+    '读取发布灰度配置失败',
+  );
+  return config?.gameDistributionPublishEnabled === true;
+}
+
+export type GameDistributionPublishResult = {
+  gameId: string;
+  versionId: string;
+  versionNumber: number;
+  status: string;
+  packageSha256: string;
+  packageSizeBytes: number;
+  fileCount: number;
+};
+
+type CreatedGame = { id: string; publicationRevision?: number };
+type CreatedVersion = {
+  gameId: string;
+  versionId: string;
+  versionNumber: number;
+  status: string;
+};
+
+export function createGameDistributionPublishKey() {
+  const randomUuid =
+    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return `agc-publish-${randomUuid}`;
+}
+
+function normalizeMetadata(
+  manifest: GameCreationAppManifest,
+  metadata?: Partial<GameDistributionPublishMetadata>,
+): GameDistributionPublishMetadata {
+  const title = (metadata?.title ?? manifest.name).trim();
+  const summary = (
+    metadata?.summary ??
+    manifest.goal ??
+    '由陶泥儿创作的可在线游玩游戏'
+  ).trim();
+  if (!title || title.length > 40) {
+    throw new Error('游戏标题必须为 1 到 40 个字符');
+  }
+  if (!summary || summary.length > 120) {
+    throw new Error('游戏简介必须为 1 到 120 个字符');
+  }
+  const coverAssetId = (metadata?.coverAssetId ?? '').trim();
+  if (!coverAssetId) {
+    // 服务端会拒绝没有封面的发布；在创建游戏前失败关闭，避免留下无资料的半成品。
+    throw new Error('请先选择游戏封面（JPG/PNG/WebP），再发布到游戏广场');
+  }
+  const screenshots = (metadata?.screenshots ?? [])
+    .map((screenshot) => screenshot.trim())
+    .filter(Boolean);
+  if (screenshots.length > MAX_AGC_GAME_SCREENSHOTS) {
+    throw new Error('游戏截图最多 6 张');
+  }
+  return {
+    title,
+    summary,
+    description: (metadata?.description ?? summary).trim().slice(0, 2_000),
+    category: metadata?.category ?? '其他',
+    tags: metadata?.tags ?? [],
+    coverAssetId,
+    screenshots,
+    deviceSupport: metadata?.deviceSupport ?? {
+      desktop: true,
+      mobile: true,
+      touch: true,
+    },
+    inputModes: metadata?.inputModes ?? ['keyboard', 'mouse', 'touch'],
+    orientation: metadata?.orientation ?? 'responsive',
+  };
+}
+
+function toCreateGameRequest(
+  metadata: GameDistributionPublishMetadata,
+  localProjectId: string,
+): GameDistributionCreateGameRequest {
+  return {
+    localProjectId,
+    title: metadata.title,
+    summary: metadata.summary,
+    description: metadata.description,
+    category: metadata.category,
+    tags: metadata.tags,
+    coverAssetId: metadata.coverAssetId,
+    screenshots: metadata.screenshots ?? [],
+    deviceSupport: metadata.deviceSupport,
+    inputModes: metadata.inputModes,
+    orientation: metadata.orientation,
+  };
+}
+
+export async function publishLocalProjectGame(args: {
+  invoke: TauriInvoke;
+  projectPath: string;
+  packageRelativePath: string;
+  manifest: GameCreationAppManifest;
+  metadata?: Partial<GameDistributionPublishMetadata>;
+  idempotencyKey?: string;
+}): Promise<GameDistributionPublishResult> {
+  const projectPath = args.projectPath.trim();
+  const packageRelativePath = args.packageRelativePath.trim();
+  if (!projectPath || !packageRelativePath) {
+    throw new Error('发布需要绑定本地项目和试玩包');
+  }
+  const payload = await args.invoke<LocalProjectExportPackagePayload>(
+    'read_local_project_export_package',
+    { projectPath, packageRelativePath },
+  );
+  if (
+    !payload.packageBytes.length ||
+    payload.packageSizeBytes !== payload.packageBytes.length ||
+    payload.files.length === 0
+  ) {
+    throw new Error('本地发行包摘要无效，请重新导出试玩包');
+  }
+  if (payload.packageRelativePath !== packageRelativePath) {
+    throw new Error('本地发行包路径已变化，请重新导出试玩包');
+  }
+
+  const metadata = normalizeMetadata(args.manifest, args.metadata);
+  const localProjectId = args.manifest.projectId.trim();
+  if (!localProjectId) {
+    throw new Error('发布需要本地项目标识，请重新打开项目后再试');
+  }
+  const gameMetadata = toCreateGameRequest(metadata, localProjectId);
+  const rootKey =
+    args.idempotencyKey?.trim() || createGameDistributionPublishKey();
+  const game = await requestClientApi<CreatedGame>(
+    '/api/game-distribution/games',
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `${rootKey}:game`,
+      },
+      body: JSON.stringify(gameMetadata),
+    },
+    '创建平台游戏失败',
+  );
+  if (!game?.id?.trim()) {
+    throw new Error('创建平台游戏未返回游戏 ID');
+  }
+
+  const versionRequest: GameDistributionCreateVersionRequest = {
+    localProjectId,
+    packageSha256: payload.packageSha256,
+    packageBytes: payload.packageSizeBytes,
+    packageFileCount: payload.files.length,
+    packageEntryPath: 'index.html',
+    gameMetadata,
+  };
+  const version = await requestClientApi<CreatedVersion>(
+    `/api/game-distribution/games/${encodeURIComponent(game.id)}/versions`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `${rootKey}:version`,
+      },
+      body: JSON.stringify(versionRequest),
+    },
+    '创建游戏发行版本失败',
+  );
+  if (!version?.versionId?.trim()) {
+    throw new Error('创建发行版本未返回版本 ID');
+  }
+
+  const packageBody = new Blob([new Uint8Array(payload.packageBytes)], {
+    type: 'application/zip',
+  });
+  const uploaded = await requestClientApi<{
+    versionId: string;
+    status: string;
+  }>(
+    `/api/game-distribution/versions/${encodeURIComponent(version.versionId)}/package`,
+    {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/zip',
+        'Idempotency-Key': `${rootKey}:upload`,
+      },
+      body: packageBody,
+    },
+    '上传游戏发行包失败',
+  );
+  const submitted = await requestClientApi<{
+    game?: { publicationRevision?: number };
+    version?: { status?: string };
+  }>(
+    `/api/game-distribution/versions/${encodeURIComponent(version.versionId)}/submit`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Idempotency-Key': `${rootKey}:submit`,
+      },
+      body: JSON.stringify({
+        expectedPublicationRevision: game.publicationRevision ?? 0,
+      }),
+    },
+    '提交审核失败',
+  );
+  return {
+    gameId: game.id,
+    versionId: version.versionId,
+    versionNumber: version.versionNumber,
+    status: submitted?.version?.status ?? uploaded?.status ?? 'pending_review',
+    packageSha256: payload.packageSha256,
+    packageSizeBytes: payload.packageSizeBytes,
+    fileCount: payload.files.length,
+  };
+}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 4a3f31494..41a36fceb 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3465,6 +3465,371 @@ textarea {
   color: #fff;
 }
 
+.game-distribution-publish-panel {
+  width: min(520px, 100%);
+  max-height: min(760px, calc(100vh - 48px));
+  overflow-y: auto;
+  padding: 24px;
+  border: 1px solid rgb(104 77 57 / 16%);
+  border-radius: 20px;
+  box-shadow: 0 24px 80px rgb(74 48 33 / 20%);
+}
+
+.game-distribution-publish-panel__header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 18px;
+}
+
+.game-distribution-publish-panel__header h2 {
+  margin: 5px 0 0;
+  color: var(--platform-text-strong);
+  font-size: 24px;
+  letter-spacing: -0.03em;
+}
+
+.game-distribution-publish-panel__header > button {
+  width: 32px;
+  height: 32px;
+  border: 1px solid rgb(104 77 57 / 16%);
+  border-radius: 50%;
+  background: transparent;
+  color: var(--platform-text-muted);
+  font-size: 22px;
+  line-height: 1;
+}
+
+.game-distribution-publish-panel__eyebrow {
+  color: #a8663d;
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.game-distribution-publish-panel__intro {
+  margin: 18px 0;
+  color: var(--platform-text-muted);
+  font-size: 13px;
+  line-height: 1.6;
+}
+
+.game-distribution-publish-panel__package {
+  display: grid;
+  gap: 5px;
+  margin-bottom: 18px;
+  padding: 12px 14px;
+  border: 1px solid rgb(168 102 61 / 16%);
+  border-radius: 12px;
+  background: rgb(168 102 61 / 6%);
+  color: var(--platform-text-muted);
+  font-size: 12px;
+}
+
+.game-distribution-publish-panel__package span:first-child {
+  overflow: hidden;
+  color: var(--platform-text-strong);
+  font-weight: 700;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.game-distribution-publish-panel__fields {
+  display: grid;
+  gap: 14px;
+}
+
+.game-distribution-publish-panel__fields label {
+  display: grid;
+  gap: 6px;
+  color: var(--platform-text-strong);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.game-distribution-publish-panel__fields input,
+.game-distribution-publish-panel__fields textarea,
+.game-distribution-publish-panel__fields select {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  padding: 10px 12px;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 10px;
+  background: rgb(255 255 255 / 76%);
+  color: var(--platform-text-strong);
+  font: inherit;
+  line-height: 1.45;
+}
+
+.game-distribution-publish-panel__fields textarea {
+  resize: vertical;
+}
+
+.game-distribution-publish-panel__fields input:focus-visible,
+.game-distribution-publish-panel__fields textarea:focus-visible,
+.game-distribution-publish-panel__fields select:focus-visible {
+  border-color: #a8663d;
+  outline: 2px solid rgb(168 102 61 / 20%);
+  outline-offset: 1px;
+}
+
+.game-distribution-publish-panel__media {
+  display: grid;
+  gap: 14px;
+  margin-top: 18px;
+  padding-top: 16px;
+  border-top: 1px dashed rgb(104 77 57 / 18%);
+}
+
+.game-distribution-publish-panel__media > label,
+.game-distribution-publish-panel__cover label {
+  display: grid;
+  gap: 6px;
+  color: var(--platform-text-strong);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.game-distribution-publish-panel__media input[type='file'] {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  padding: 10px 12px;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 10px;
+  background: rgb(255 255 255 / 76%);
+  color: var(--platform-text-strong);
+  font: inherit;
+}
+
+.game-distribution-publish-panel__picker {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+/* 透明 input 覆盖在触发按钮上：真实点击永远命中原生控件，自定义文案只负责显示。 */
+.game-distribution-publish-panel__picker input[type='file'] {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.game-distribution-publish-panel__pick {
+  display: inline-flex;
+  pointer-events: none;
+  align-items: center;
+  padding: 6px 14px;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 999px;
+  background: rgb(255 255 255 / 76%);
+  color: var(--platform-text-strong);
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+  transition: 160ms ease;
+}
+
+.game-distribution-publish-panel__picker:hover
+  .game-distribution-publish-panel__pick {
+  border-color: #a8663d;
+}
+
+.game-distribution-publish-panel__picker
+  input[type='file']:focus-visible
+  + .game-distribution-publish-panel__pick {
+  outline: 2px solid rgb(168 102 61 / 24%);
+  outline-offset: 2px;
+}
+
+.game-distribution-publish-panel__picker
+  input[type='file']:disabled
+  + .game-distribution-publish-panel__pick {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.game-distribution-publish-panel__cover {
+  display: grid;
+  grid-template-columns: minmax(0, 168px) minmax(0, 1fr);
+  gap: 14px;
+  align-items: start;
+}
+
+.game-distribution-publish-panel__cover-preview {
+  display: grid;
+  aspect-ratio: 16 / 9;
+  place-items: center;
+  overflow: hidden;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 12px;
+  background: rgb(168 102 61 / 8%);
+  color: var(--platform-text-muted);
+  font-size: 12px;
+}
+
+.game-distribution-publish-panel__cover-preview img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.game-distribution-publish-panel__hint {
+  color: var(--platform-text-muted);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1.5;
+}
+
+.game-distribution-publish-panel__cover > button,
+.game-distribution-publish-panel__shots button {
+  justify-self: start;
+  width: fit-content;
+  padding: 5px 12px;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--platform-text-muted);
+  font: inherit;
+  font-size: 11px;
+  cursor: pointer;
+}
+
+/* 移除封面按钮固定落在文字列，避免占掉预览列的第二行。 */
+.game-distribution-publish-panel__cover > button {
+  grid-column: 2;
+}
+
+.game-distribution-publish-panel__shots {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.game-distribution-publish-panel__shots li {
+  display: grid;
+  gap: 6px;
+  width: 124px;
+}
+
+.game-distribution-publish-panel__shots img,
+.game-distribution-publish-panel__shots li > span {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border: 1px solid rgb(104 77 57 / 18%);
+  border-radius: 10px;
+}
+
+.game-distribution-publish-panel__shots img {
+  object-fit: cover;
+}
+
+.game-distribution-publish-panel__shots li > span {
+  display: grid;
+  place-items: center;
+  border-style: dashed;
+  color: var(--platform-text-muted);
+  font-size: 11px;
+}
+
+@media (max-width: 560px) {
+  .game-distribution-publish-panel__cover {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .game-distribution-publish-panel__cover > button {
+    grid-column: 1;
+  }
+}
+
+.game-distribution-publish-panel__error {
+  margin: 14px 0 0;
+  color: #b42318;
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+.game-distribution-publish-panel__success {
+  margin-top: 18px;
+  padding: 16px;
+  border-radius: 14px;
+  background: rgb(51 125 87 / 9%);
+  color: var(--platform-text-strong);
+}
+
+.game-distribution-publish-panel__success p {
+  margin: 8px 0 0;
+  color: var(--platform-text-muted);
+  font-size: 13px;
+  line-height: 1.55;
+}
+
+.game-distribution-publish-panel__mono {
+  font-variant-numeric: tabular-nums;
+}
+
+.game-distribution-publish-panel__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  margin-top: 22px;
+}
+
+.game-distribution-publish-panel__actions button {
+  min-height: 38px;
+  padding: 0 16px;
+  border: 1px solid rgb(104 77 57 / 20%);
+  border-radius: 10px;
+  background: transparent;
+  color: var(--platform-text-strong);
+  cursor: pointer;
+  font: inherit;
+  font-weight: 700;
+}
+
+.game-distribution-publish-panel__actions button:last-child {
+  border-color: #a8663d;
+  background: #a8663d;
+  color: #fff;
+}
+
+.game-distribution-publish-panel__actions button:disabled,
+.game-distribution-publish-panel__header > button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+@media (max-width: 560px) {
+  .game-distribution-publish-panel {
+    padding: 18px;
+    border-radius: 16px;
+  }
+
+  .game-distribution-publish-panel__header h2 {
+    font-size: 21px;
+  }
+
+  .game-distribution-publish-panel__actions {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+  }
+
+  .game-distribution-publish-panel__actions button {
+    width: 100%;
+  }
+}
+
 .app-shell {
   min-height: 100vh;
   background: #f5f7fb;
@@ -8103,8 +8468,8 @@ iframe.preview-frame {
   display: grid;
   grid-template-rows: minmax(300px, 1fr) auto;
   grid-row: 2 / -1;
-  /* 与右上角任务锚点同格（见 resourceCanvasAssetGenerationTasksSidebar.css）：显式钉第 1 列，
-     避免画布被自动列放置挤到隐式列里。 */
+  /* 显式钉第 1 列（见 resourceCanvasAssetGenerationTasksSidebar.css），避免画面被自动列放置
+     挤到隐式列里。 */
   grid-column: 1;
   gap: 12px;
   height: 100%;
@@ -8113,39 +8478,35 @@ iframe.preview-frame {
   background: transparent;
 }
 
-/* C7 版本入口：运行模块右上角，没有版本时不渲染。 */
+/*
+ * C7 版本入口：住在工作台顶栏动作区（`.game-workbench-view-actions`），外观由那一组的基础
+ * 规则给（描边 + secondary 填充 + 12px/700），这里只补「版本名可能很长」这一件事。
+ *
+ * 它曾经是运行画面里的绝对定位浮层（top 20px / right 20px）：压在游戏画面上，还与顶栏其他
+ * 按钮分成两套皮。**不要再给它加 border / background / color / hover**——那就是第二套皮。
+ */
 .game-run-version-picker {
-  position: absolute;
-  top: 20px;
-  right: 20px;
-  z-index: 5;
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
 }
 
 .game-run-version-trigger {
-  display: inline-flex;
   max-width: min(18rem, 60vw);
-  min-height: 30px;
-  align-items: center;
-  padding: 0 12px;
-  border: 1px solid #e5cfc4;
-  border-radius: 999px;
-  background: rgb(255 250 246 / 92%);
-  color: #8a4a30;
-  cursor: pointer;
-  font-size: 12px;
-  font-weight: 700;
+  min-width: 0;
+}
+
+/*
+ * 版本名单独一层才省得掉：按钮是 flex 容器，文本直接挂在按钮上时 `text-overflow`
+ * 落在匿名 flex item 上、不生效（见 `GameRunVersionPicker` 里的注释）。
+ */
+.game-run-version-trigger-label {
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.game-run-version-trigger:hover,
-.game-run-version-trigger:focus-visible {
-  border-color: #cc8060;
-  outline: 0;
-  box-shadow: 0 3px 10px rgb(158 87 57 / 14%);
-}
-
 .game-run-version-menu {
   display: grid;
   gap: 2px;
@@ -10121,8 +10482,8 @@ button.design-workspace-tree__entry:hover,
   justify-self: start;
 }
 
-/* 策划聊天区包含阶段控制卡、消息、Runtime 状态和输入框。GameAgent 资源工作台的
-   消息列表默认占满整个聊天区，策划模式需要单独恢复五行布局，避免输入框被推到视口外。 */
+/* 阶段、状态条和可选待办按内容排布，只有消息列表吸收剩余高度。
+   不按子节点序号分配 grid 行，避免状态条或待办占用消息的伸缩空间。 */
 /* 策划工作台保留标题行，避免共用跨行规则将标题挤到底部。 */
 .game-workbench-layout--design .game-workbench-chat {
   grid-template-rows: auto minmax(0, 1fr);
@@ -10142,13 +10503,24 @@ button.design-workspace-tree__entry:hover,
 }
 
 .game-workbench-layout--design .project-chat-conversation {
-  display: grid;
-  grid-template-rows: auto minmax(0, 1fr) auto auto auto;
+  display: flex;
+  flex-direction: column;
   height: 100%;
   min-height: 0;
   overflow: visible;
 }
 
+.game-workbench-layout--design .project-chat-conversation > * {
+  flex: 0 0 auto;
+  min-width: 0;
+}
+
+.game-workbench-layout--design
+  .project-chat-conversation
+  > .project-chat-message-list {
+  flex: 1 1 0;
+}
+
 .game-workbench-layout--design .project-chat-message-list {
   height: auto;
   min-height: 0;
@@ -10156,6 +10528,16 @@ button.design-workspace-tree__entry:hover,
   padding-bottom: 12px;
 }
 
+.game-workbench-layout--design .design-agent-controls,
+.game-workbench-layout--design .design-agent-pending-actions,
+.game-workbench-layout--design .pending-command {
+  flex-shrink: 1;
+  min-height: 0;
+  max-height: 30%;
+  overflow: auto;
+  overflow-wrap: anywhere;
+}
+
 .game-workbench-layout--design .project-chat-composer {
   min-height: 0;
   grid-template-columns: minmax(0, 1fr);
@@ -10176,13 +10558,24 @@ button.design-workspace-tree__entry:hover,
 }
 
 @media (max-width: 760px) {
-  .game-workbench-layout--design {
-    height: auto;
+  .game-project-workbench--design {
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  /* 两块面板在固定外壳内滚动；覆盖外壳的 height: 100%，避免第二行被裁切。 */
+  .game-project-workbench--design .game-workbench-layout--design {
+    height: auto;
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .game-workbench-layout--design .game-workbench-stage {
+    height: 560px;
   }
 
-  .game-workbench-layout--design .game-workbench-stage,
   .game-workbench-layout--design .game-workbench-chat {
     min-height: 560px;
+    height: clamp(560px, calc(100dvh - 154px), 900px);
   }
 
   .game-workbench-layout--design .project-chat-surface,
@@ -10935,11 +11328,7 @@ button.design-workspace-tree__entry:hover,
   gap: 6px;
 }
 
-/* 待发附件 / 队列 chip：压在输入区上方，横向排布、超出换行。 */
-.game-workbench-chat
-  .project-chat-surface.is-direct-codex
-  .project-chat-composer.is-direct-codex
-  .project-chat-composer-attachments,
+/* 队列 chip：压在输入区上方，横向排布、超出换行。 */
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-composer.is-direct-codex
@@ -10953,11 +11342,6 @@ button.design-workspace-tree__entry:hover,
   list-style: none;
 }
 
-.game-workbench-chat
-  .project-chat-surface.is-direct-codex
-  .project-chat-composer.is-direct-codex
-  .project-chat-composer-attachments
-  li,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-composer.is-direct-codex
@@ -10974,12 +11358,6 @@ button.design-workspace-tree__entry:hover,
   font-size: 12px;
 }
 
-.game-workbench-chat
-  .project-chat-surface.is-direct-codex
-  .project-chat-composer.is-direct-codex
-  .project-chat-composer-attachments
-  li
-  span,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-composer.is-direct-codex
@@ -10990,11 +11368,6 @@ button.design-workspace-tree__entry:hover,
   white-space: nowrap;
 }
 
-.game-workbench-chat
-  .project-chat-surface.is-direct-codex
-  .project-chat-composer.is-direct-codex
-  .project-chat-composer-attachments
-  button,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-composer.is-direct-codex
@@ -11019,6 +11392,12 @@ button.design-workspace-tree__entry:hover,
   font-variant-numeric: tabular-nums;
 }
 
+.game-workbench-layout--design .project-chat-composer-notice {
+  max-height: 96px;
+  overflow: auto;
+  overflow-wrap: anywhere;
+}
+
 .game-workbench-layout--design .project-chat-composer-notice,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
@@ -11223,9 +11602,9 @@ button.design-workspace-tree__entry:hover,
   margin-top: 0;
 }
 
-/* direct-codex 里 `ResourceReferenceInput` 收到的是 `showTriggerButton={!directCodex}`，
-   即输入框内的 `.resource-reference-input-at` 根本不会渲染（`@` 触发钮是下面控制排里的
-   `.project-chat-reference-trigger`）。这里原本有一条针对它的
+/* direct-codex 的 `@` 触发钮是下面控制排里的 `.project-chat-reference-trigger`，
+   不是输入区操作排里的 `.resource-reference-input-at`（宿主不注入
+   `ResourceReferencePickerAction`，改用控制排那个按钮）。这里原本有一条针对它的
    `position: static !important` / 30px 主色方块规则，永远匹配不到，已删除；
    要改 direct-codex 的 `@` 触发钮外观请改 `.project-chat-reference-trigger`。 */
 
@@ -11253,6 +11632,7 @@ button.design-workspace-tree__entry:hover,
 
 /* 顶部极简条：44px 高、无独立背景块，只有一条极细分隔线。
    左右内缩与消息内容 / 输入盒统一为 16px（面板自身 padding 已归 0）。 */
+.game-workbench-layout--design .project-chat-topbar,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-topbar {
@@ -11267,6 +11647,7 @@ button.design-workspace-tree__entry:hover,
   background: transparent;
 }
 
+.game-workbench-layout--design .project-chat-topbar-status,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-topbar-status {
@@ -11279,6 +11660,53 @@ button.design-workspace-tree__entry:hover,
   line-height: 1.5;
 }
 
+.game-workbench-chat
+  .project-chat-surface.is-direct-codex
+  .project-chat-topbar-actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 0 0 auto;
+}
+
+/* 发布入口：图标 + 文字胶囊，与设置按钮同高同风格。 */
+.game-workbench-chat
+  .project-chat-surface.is-direct-codex
+  .project-chat-publish-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  height: 28px;
+  padding: 0 11px;
+  border: 1px solid var(--platform-button-primary-border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--platform-text-soft);
+  font: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.game-workbench-chat
+  .project-chat-surface.is-direct-codex
+  .project-chat-publish-trigger:hover:not(:disabled),
+.game-workbench-chat
+  .project-chat-surface.is-direct-codex
+  .project-chat-publish-trigger:focus-visible {
+  background: var(--platform-button-ghost-fill);
+  color: var(--platform-text-strong);
+  outline: none;
+}
+
+.game-workbench-chat
+  .project-chat-surface.is-direct-codex
+  .project-chat-publish-trigger:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.game-workbench-layout--design .project-chat-topbar-status > span:last-child,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-topbar-status
@@ -11287,6 +11715,7 @@ button.design-workspace-tree__entry:hover,
   overflow-wrap: anywhere;
 }
 
+.game-workbench-layout--design .project-chat-topbar-dot,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-topbar-dot {
@@ -11298,6 +11727,7 @@ button.design-workspace-tree__entry:hover,
   background: var(--platform-neutral-bg);
 }
 
+.game-workbench-layout--design .project-chat-topbar-dot.is-busy,
 .game-workbench-chat
   .project-chat-surface.is-direct-codex
   .project-chat-topbar-dot.is-busy {
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx
index 839b37053..a067a1a01 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx
@@ -1,6 +1,12 @@
 import type { UIEventHandler } from 'react';
 import type { Ref } from 'react';
-import { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import {
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 import { AGENT_CHAT_SCROLL_BOTTOM_THRESHOLD } from '../../../app/constants';
 import { claimInitialTurnForPage } from '../../../app/initialTurnClaims';
@@ -18,6 +24,7 @@ import {
   useDirectProjectChatController,
 } from './controller/useDirectProjectChatController';
 import { useDirectProjectManifest } from './controller/useDirectProjectManifest';
+import { useDirectProjectTurnStatus } from './controller/useDirectProjectTurnStatus';
 import {
   createDirectProjectTurnId,
   directCodexConversationMessageId,
@@ -71,6 +78,8 @@ export type DirectProjectChatViewProps = {
   ensureConversationReadAllowed: DirectProjectConversationReadGate;
   /** 项目对话写权限门：只在发起回合时检查；同样必填，缺省会让未传入的调用方静默跳过授权。 */
   ensureConversationWriteAllowed: DirectProjectConversationWriteGate;
+  /** 发布入口：由工作台壳持有导出与发布面板，聊天只提供触发按钮。 */
+  onRequestGamePublish?: () => void;
   /** 工作台壳把运行/预览这类动作结果交给聊天的出口。 */
   ref?: Ref<DirectProjectChatHandle>;
 };
@@ -85,6 +94,7 @@ function directInitialTurnText(content: readonly DirectCodexUserContentPart[]) {
 }
 
 export function DirectProjectChatView({
+  onRequestGamePublish,
   projectPath,
   initialTurn = null,
   ensureConversationReadAllowed,
@@ -112,8 +122,8 @@ export function DirectProjectChatView({
   });
   const {
     appendLocalMessage,
-    attachments,
     attachmentNotice,
+    attachmentsImporting,
     cancelQueuedTurn,
     cancelTurn,
     composerNotice,
@@ -122,8 +132,8 @@ export function DirectProjectChatView({
     historyHasMore,
     loadEarlierHistory,
     localMessages,
+    pendingUserItemId,
     queuedTurns,
-    removeAttachment,
     startInitialTurn,
     statusNotice,
     submit,
@@ -131,7 +141,27 @@ export function DirectProjectChatView({
     turnCancelling,
     uploadFiles,
   } = chat;
-  const busy = turnBusy || directTurnRunning;
+  // 这份投影要参与下游 memo 的判据，必须自己先缓存：不缓存的话每次渲染都是一份新数组，
+  // `useDirectProjectTurnStatus` 里以 `turns` 为判据的 `useMemo` 永远命中不了，那层 memo
+  // 就成了死代码，读代码的人还会误以为 `turnStatus` 是引用稳定的。
+  const directTurns = useMemo(
+    () =>
+      buildDirectChatTurns({
+        entries: directEntries,
+        localMessages,
+        turnRunning: directTurnRunning,
+        pendingUserItemId,
+      }),
+    [directEntries, localMessages, directTurnRunning, pendingUserItemId],
+  );
+  // 「这一轮在跑吗」只从这一个派生入口读：原生真相 / 本地命令在飞 / 最新一轮三态。
+  const turnStatus = useDirectProjectTurnStatus({
+    turnRunning: directTurnRunning,
+    turnBusy,
+    turns: directTurns,
+  });
+  const activeTurnStartedAt =
+    directTurns.find((turn) => turn.state === 'running')?.startedAt ?? 0;
   const statusText =
     runtimeNotice ||
     statusNotice ||
@@ -144,7 +174,7 @@ export function DirectProjectChatView({
       return;
     if (projectPath !== initialTurn.projectPath) return;
     // projectId 来自项目清单：清单还没到位时不能先认领，否则首轮需求会被空项目吃掉。
-    if (!projectId || busy) return;
+    if (!projectId || turnStatus.displayBusy) return;
     if (
       !claimInitialTurnForPage(initialTurn.projectPath, initialTurn.claimScope)
     ) {
@@ -165,9 +195,9 @@ export function DirectProjectChatView({
         : {}),
       userItem,
     });
-    // 首轮需求只由入口 payload、项目身份、清单就绪和回合态驱动。
+    // 首轮需求只由入口 payload、项目身份、清单就绪和回合忙态驱动。
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [busy, initialTurn, projectId, projectPath]);
+  }, [turnStatus.displayBusy, initialTurn, projectId, projectPath]);
 
   useEffect(() => {
     if (!shouldFollowLatestRef.current) return;
@@ -175,14 +205,6 @@ export function DirectProjectChatView({
     if (list) list.scrollTop = list.scrollHeight;
   }, [directEntries, localMessages]);
 
-  const directTurns = buildDirectChatTurns({
-    entries: directEntries,
-    localMessages,
-    turnRunning: directTurnRunning,
-  });
-  const activeTurnStartedAt =
-    directTurns.find((turn) => turn.active)?.startedAt ?? 0;
-
   useImperativeHandle(ref, () => ({
     announce: (text: string) => {
       appendLocalMessage({ role: 'assistant', text, updatedAt: Date.now() });
@@ -206,15 +228,16 @@ export function DirectProjectChatView({
     >
       <div className="project-chat-conversation">
         <DirectProjectChatHeader
-          busy={busy}
+          busy={turnStatus.displayBusy}
           statusText={statusText}
           onOpenSettings={() => setSettingsOpen(true)}
+          onRequestGamePublish={onRequestGamePublish}
         />
         <DirectProjectConversation
           turns={directTurns}
           messagesRef={messagesRef}
           historyHasMore={historyHasMore}
-          running={directTurnRunning}
+          nativeRunning={turnStatus.nativeRunning}
           activeTurnStartedAt={activeTurnStartedAt}
           onLoadEarlierHistory={() => void loadEarlierHistory()}
           onScroll={handleScroll}
@@ -223,11 +246,11 @@ export function DirectProjectChatView({
           assets={assets}
           {...(versions ? { versions } : {})}
           projectPath={projectPath}
-          attachments={attachments}
           attachmentNotice={attachmentNotice}
+          attachmentsImporting={attachmentsImporting}
           queuedTurns={queuedTurns}
           composerNotice={composerNotice}
-          busy={busy}
+          busy={turnStatus.displayBusy}
           turnCancelling={turnCancelling}
           onCancelQueuedTurn={cancelQueuedTurn}
           onCancelTurn={() => void cancelTurn()}
@@ -236,9 +259,8 @@ export function DirectProjectChatView({
             // 打开 `@` 选择器时按需重读聊天自己那份清单，别把旧标签当现状。
             if (projectPath) void refresh(projectPath);
           }}
-          onRemoveAttachment={removeAttachment}
           onSubmit={submit}
-          onUploadFiles={(files) => void uploadFiles(files)}
+          onUploadFiles={uploadFiles}
         />
       </div>
       {settingsOpen ? (
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectChatHeader/DirectProjectChatHeader.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectChatHeader/DirectProjectChatHeader.tsx
index 5ba497dee..a1f7a9681 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectChatHeader/DirectProjectChatHeader.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectChatHeader/DirectProjectChatHeader.tsx
@@ -1,4 +1,4 @@
-import { Settings } from 'lucide-react';
+import { Rocket, Settings } from 'lucide-react';
 
 /**
  * DirectProject 聊天头：运行状态与设置入口。
@@ -10,10 +10,13 @@ export function DirectProjectChatHeader({
   busy,
   statusText,
   onOpenSettings,
+  onRequestGamePublish,
 }: {
   busy: boolean;
   statusText: string;
   onOpenSettings: () => void;
+  /** 没有项目或不在 Tauri 宿主时不传；传了才渲染发布入口。 */
+  onRequestGamePublish?: () => void;
 }) {
   return (
     <header className="project-chat-topbar">
@@ -24,15 +27,30 @@ export function DirectProjectChatHeader({
         />
         {busy ? '陶泥儿正在处理' : statusText}
       </span>
-      <button
-        type="button"
-        className="project-chat-settings-trigger"
-        aria-label="设置"
-        title="设置"
-        onClick={onOpenSettings}
-      >
-        <Settings size={16} aria-hidden="true" />
-      </button>
+      <div className="project-chat-topbar-actions">
+        {onRequestGamePublish ? (
+          <button
+            type="button"
+            className="project-chat-publish-trigger"
+            aria-label="发布到游戏广场"
+            title="发布到游戏广场"
+            disabled={busy}
+            onClick={onRequestGamePublish}
+          >
+            <Rocket size={16} aria-hidden="true" />
+            <span>发布</span>
+          </button>
+        ) : null}
+        <button
+          type="button"
+          className="project-chat-settings-trigger"
+          aria-label="设置"
+          title="设置"
+          onClick={onOpenSettings}
+        >
+          <Settings size={16} aria-hidden="true" />
+        </button>
+      </div>
     </header>
   );
 }
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/ComposerControls.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/ComposerControls.tsx
index abb6f7edc..dc4904ed0 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/ComposerControls.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/ComposerControls.tsx
@@ -2,7 +2,7 @@
  * 输入盒控件（Codex 观感）：左 `+`（上传本地文件 / 引用项目素材）、右侧推理强度 +
  * 模型 + 麦克风 + 发送/终止，以及输入盒上方的待发附件与消息队列 chip。
  *
- * 这些组件只承载表现与交互；回合附件由 `App.tsx` 上传并落进 `DirectCodexTurnAttachment`，
+ * 这些组件只承载表现与交互；回合附件由宿主导入后插成正文芯片（正文是唯一事实源），
  * 队列由 `chatComposerQueue.ts` 的纯函数维护。
  */
 import {
@@ -30,7 +30,6 @@ import {
   DEFAULT_COMPOSER_REASONING_EFFORT,
   normalizeComposerReasoningEffort,
 } from '../../../../../features/project-workspace/composerReasoningEffort';
-import type { DirectCodexTurnAttachment } from '../../conversation/directCodexTurnAttachments';
 import type { QueuedChatTurn } from './chatComposerQueue';
 import { queuedChatTurnLabel } from './chatComposerQueue';
 import {
@@ -152,41 +151,6 @@ export function ComposerAttachmentMenu({
   );
 }
 
-/** 待发附件 chip：随下次提交一起进入回合，可单条移除。 */
-export function ComposerPendingAttachments({
-  attachments,
-  onRemove,
-}: {
-  attachments: readonly DirectCodexTurnAttachment[];
-  onRemove: (index: number) => void;
-}) {
-  if (attachments.length === 0) {
-    return null;
-  }
-  return (
-    <ul className="project-chat-composer-attachments" aria-label="待发送附件">
-      {attachments.map((attachment, index) => (
-        <li
-          key={`${attachment.name}-${index}`}
-          data-attachment-status={attachment.status ?? 'ready'}
-        >
-          <span title={attachment.localPath ?? attachment.name}>
-            {attachment.name}
-          </span>
-          <button
-            type="button"
-            aria-label={`移除附件 ${attachment.name}`}
-            title={`移除附件 ${attachment.name}`}
-            onClick={() => onRemove(index)}
-          >
-            <X size={12} aria-hidden="true" />
-          </button>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
 /** 队列 chip：回合运行中入队的消息，按 FIFO 顺序展示，可单条取消。 */
 export function ComposerTurnQueue({
   turns,
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/DirectProjectComposer.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/DirectProjectComposer.tsx
index 62c89b163..c92cd74d1 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/DirectProjectComposer.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/DirectProjectComposer.tsx
@@ -1,5 +1,5 @@
 import { ArrowUp, AtSign } from 'lucide-react';
-import { useRef, useState } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
 
 import type {
   GameCreationAppAssetManifestEntry,
@@ -9,23 +9,39 @@ import {
   ConversationModelSelect,
   type ConversationModelSelectHandle,
 } from '../../../../../features/project-workspace/ConversationModelSelect';
+import { attachmentReferenceProvider } from '../../../../../features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../../../../../features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../../../../../features/project-workspace/reference-source/runtimeRegionReferenceProvider';
+import { useSkillReferenceProvider } from '../../../../../features/project-workspace/reference-source/skillReferenceProvider';
 import {
   ResourceReferenceInput,
   type ResourceReferenceInputHandle,
 } from '../../../../../features/project-workspace/ResourceReferenceInput';
+import {
+  ResourceReferencePicker,
+  type ResourceReferencePickerHandle,
+} from '../../../../../features/project-workspace/ResourceReferencePicker';
+import { assetsSignature } from '../../../../../features/project-workspace/resourceReferences';
 import type { DirectCodexTurnAttachment } from '../../conversation/directCodexTurnAttachments';
-import { directCodexAttachmentContentParts } from '../../conversation/directCodexTurnAttachments';
 import type { DirectCodexUserContentPart } from '../../generated/DirectCodexUserContentPart';
 import type { QueuedChatTurn } from './chatComposerQueue';
 import {
   ComposerAttachmentMenu,
-  ComposerPendingAttachments,
   ComposerReasoningEffortSelect,
   ComposerStopButton,
   ComposerTurnQueue,
   ComposerVoiceButton,
 } from './ComposerControls';
 
+/** 草稿里已有的附件芯片数：附件上限按它算，不再另存一份待发列表。 */
+function draftAttachmentCount(draft: {
+  content: DirectCodexUserContentPart[];
+}) {
+  return draft.content.filter(
+    (part) => part.type === 'agc_attachment_reference',
+  ).length;
+}
+
 /**
  * DirectProject 输入区：队列、附件、`@` 引用输入框、模型/推理选择和发送/终止。
  *
@@ -36,8 +52,8 @@ export function DirectProjectComposer({
   assets,
   versions,
   projectPath,
-  attachments,
   attachmentNotice,
+  attachmentsImporting,
   queuedTurns,
   composerNotice,
   busy,
@@ -45,15 +61,15 @@ export function DirectProjectComposer({
   onCancelQueuedTurn,
   onCancelTurn,
   onReferencePickerOpen,
-  onRemoveAttachment,
   onSubmit,
   onUploadFiles,
 }: {
   assets: GameCreationAppAssetManifestEntry[];
   versions?: GameIterationVersion[];
   projectPath: string | null;
-  attachments: DirectCodexTurnAttachment[];
   attachmentNotice: string;
+  /** 附件导入进行中：导入结果还没落成芯片，这一轮先不许发出去。 */
+  attachmentsImporting: boolean;
   queuedTurns: QueuedChatTurn[];
   composerNotice: string;
   busy: boolean;
@@ -68,16 +84,74 @@ export function DirectProjectComposer({
    * 用户真正要看这份清单的时刻是打开选择器的这一刻，所以在这里补一次重读。
    */
   onReferencePickerOpen?: () => void;
-  onRemoveAttachment: (index: number) => void;
   onSubmit: (content: DirectCodexUserContentPart[]) => boolean;
-  onUploadFiles: (files: readonly File[]) => void;
+  /**
+   * 导入文件：`draftAttachmentCount` 是草稿里已有的附件芯片数（上限按它算）。
+   * 返回导入成功的附件——由这里插成正文芯片；失败的一条都不插入。
+   */
+  onUploadFiles: (
+    files: readonly File[],
+    draftAttachmentCount: number,
+  ) => Promise<DirectCodexTurnAttachment[]>;
 }) {
   const composerRef = useRef<ResourceReferenceInputHandle | null>(null);
+  const composerRootRef = useRef<HTMLDivElement | null>(null);
+  const pickerRef = useRef<ResourceReferencePickerHandle | null>(null);
   const modelSelectRef = useRef<ConversationModelSelectHandle>(null);
   const modelValidateInFlightRef = useRef(false);
   const [voiceNotice, setVoiceNotice] = useState('');
   const [modelReady, setModelReady] = useState(false);
   const [modelValidating, setModelValidating] = useState(false);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  /*
+    引用来源：DirectProject 是唯一会把 `agc_skill_reference` 解析成真 Skill 的宿主
+    （Rust `direct_codex_user_item_to_codex_turn_input`），所以只有这里注入 Skill provider。
+  */
+  const skillProvider = useSkillReferenceProvider();
+  const assetsContentSignature = assetsSignature(assets);
+  const referenceProviders = useMemo(
+    () => [
+      createResourceReferenceProvider({ assets }),
+      skillProvider,
+      attachmentReferenceProvider,
+      runtimeRegionReferenceProvider,
+    ],
+    // `assets` 由 manifest 订阅每次渲染重新 `.filter()` 派生，依赖它等于从不命中缓存：
+    // provider 身份一变，输入区就重新注册 Lexical 更新监听（流式回复时每帧都换）。
+    // 按内容签名取依赖才真的能跳过重建。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [assetsContentSignature, skillProvider],
+  );
+  const openPicker = useCallback(() => {
+    onReferencePickerOpen?.();
+    pickerRef.current?.open();
+  }, [onReferencePickerOpen]);
+  /**
+   * 导入成功即插芯片：附件只有「正文芯片」这一份事实源，没有第二份待发列表可以回退。
+   * 失败 / 异常一律不插。导入期间允许多次点击：各自的结果插各自的芯片。
+   */
+  const uploadFiles = useCallback(
+    async (files: readonly File[]) => {
+      const current = composerRef.current?.getDraft();
+      const imported = await onUploadFiles(
+        files,
+        current ? draftAttachmentCount(current) : 0,
+      );
+      if (imported.length === 0) return;
+      composerRef.current?.insertReferences(
+        imported.map((attachment) => ({
+          type: 'attachment' as const,
+          name: attachment.name,
+          mediaType: attachment.mediaType,
+          size: attachment.size ?? 0,
+          localPath: attachment.localPath ?? '',
+          status:
+            attachment.status ?? (attachment.localPath ? 'imported' : 'failed'),
+        })),
+      );
+    },
+    [onUploadFiles],
+  );
   // 这个按钮只在非 busy 分支出现（busy 时由 ComposerStopButton 接管），所以不再带忙态逻辑。
   const submitButton = (
     <button
@@ -85,7 +159,7 @@ export function DirectProjectComposer({
       className="project-chat-submit-button"
       aria-label="发送"
       title="发送"
-      disabled={!modelReady || modelValidating}
+      disabled={!modelReady || modelValidating || attachmentsImporting}
     >
       <ArrowUp size={16} aria-hidden="true" />
     </button>
@@ -96,7 +170,7 @@ export function DirectProjectComposer({
       className="project-chat-composer is-direct-codex"
       onSubmit={(event) => {
         event.preventDefault();
-        if (modelValidateInFlightRef.current) return;
+        if (modelValidateInFlightRef.current || attachmentsImporting) return;
         modelValidateInFlightRef.current = true;
         setModelValidating(true);
         void (async () => {
@@ -105,10 +179,7 @@ export function DirectProjectComposer({
               ? await modelSelectRef.current.ensureUsable()
               : modelReady;
             if (ready) {
-              const content = [
-                ...(composerRef.current?.getDraft().content ?? []),
-                ...directCodexAttachmentContentParts(attachments),
-              ];
+              const content = composerRef.current?.getDraft().content ?? [];
               if (onSubmit(content)) {
                 composerRef.current?.clear();
               }
@@ -125,20 +196,16 @@ export function DirectProjectComposer({
         assets={assets}
         onCancel={onCancelQueuedTurn}
       />
-      <ComposerPendingAttachments
-        attachments={attachments}
-        onRemove={onRemoveAttachment}
-      />
       <ResourceReferenceInput
         ref={composerRef}
         ariaLabel="陶泥儿对话内容"
-        versions={versions}
-        assets={assets}
+        providers={referenceProviders}
         projectPath={projectPath ?? ''}
         disabled={modelValidating}
         rows={3}
         placeholder="描述你的想法，或 @ 引用素材"
-        showTriggerButton={false}
+        submitSuppressed={pickerOpen}
+        containerRef={composerRootRef}
       />
       <div className="project-chat-composer-controls">
         <div className="project-chat-composer-controls-left">
@@ -148,20 +215,14 @@ export function DirectProjectComposer({
             aria-label="插入素材引用"
             title="插入素材引用"
             disabled={busy}
-            onClick={() => {
-              onReferencePickerOpen?.();
-              composerRef.current?.openPicker();
-            }}
+            onClick={openPicker}
           >
             <AtSign size={15} aria-hidden="true" />
           </button>
           <ComposerAttachmentMenu
             disabled={busy || modelValidating}
-            onPickFiles={(files) => void onUploadFiles(files)}
-            onOpenReferencePicker={() => {
-              onReferencePickerOpen?.();
-              composerRef.current?.openPicker();
-            }}
+            onPickFiles={(files) => void uploadFiles(files)}
+            onOpenReferencePicker={openPicker}
           />
         </div>
         <div className="project-chat-composer-controls-right">
@@ -192,6 +253,21 @@ export function DirectProjectComposer({
           {composerNotice || attachmentNotice || voiceNotice}
         </p>
       ) : null}
+      {/*
+        素材选择器由宿主渲染、自己拿数据：确认后只把选中的引用交给输入区句柄，
+        输入区与它之间只有 `insertReferences` 这一个接缝。
+      */}
+      <ResourceReferencePicker
+        ref={pickerRef}
+        anchorRef={composerRootRef}
+        assets={assets}
+        {...(versions ? { versions } : {})}
+        projectPath={projectPath ?? ''}
+        onInsert={(references) =>
+          composerRef.current?.insertReferences(references)
+        }
+        onOpenChange={setPickerOpen}
+      />
     </form>
   );
 }
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/chatComposerQueue.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/chatComposerQueue.ts
index c89e971d2..97136f07c 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/chatComposerQueue.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectComposer/chatComposerQueue.ts
@@ -5,7 +5,10 @@
  * 依次发出。队列项能在输入盒上方单独取消。这里只放与 React 无关的纯逻辑，便于单测。
  */
 import type { GameCreationAppAssetManifestEntry } from '../../../../../../../../packages/shared/src/contracts/gameCreationApp';
-import { directCodexContentToPromptText } from '../../../../../features/project-workspace/resourceReferences';
+import {
+  directCodexContentToPromptText,
+  resourceLabelResolver,
+} from '../../../../../features/project-workspace/resourceReferences';
 import type { DirectCodexUserItem } from '../../generated/DirectCodexUserItem';
 
 /** 队列上限：满了以后拒绝入队并给出可读提示，而不是静默丢消息。 */
@@ -85,7 +88,10 @@ export function queuedChatTurnLabel(
   turn: QueuedChatTurn,
   assets: readonly GameCreationAppAssetManifestEntry[],
 ): string {
-  const text = directCodexContentToPromptText(turn.userItem.content, assets)
+  const text = directCodexContentToPromptText(
+    turn.userItem.content,
+    resourceLabelResolver(assets),
+  )
     .trim()
     .replace(/\s+/gu, ' ');
   if (!text) return '未命名消息';
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx
index b982c84ae..fec7a00e4 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx
@@ -19,7 +19,7 @@ export function DirectProjectConversation({
   turns,
   messagesRef,
   historyHasMore,
-  running,
+  nativeRunning,
   activeTurnStartedAt,
   onLoadEarlierHistory,
   onScroll,
@@ -27,7 +27,11 @@ export function DirectProjectConversation({
   turns: DirectChatTurn[];
   messagesRef: RefObject<HTMLDivElement | null>;
   historyHasMore: boolean;
-  running: boolean;
+  /**
+   * 原生回合是否在跑（reducer 的 `turnRunning`）：只决定这张"正在处理"卡片。
+   * 本地命令在飞但原生还没认领的窗口见 `DirectProjectTurnStatus`。
+   */
+  nativeRunning: boolean;
   activeTurnStartedAt: number;
   onLoadEarlierHistory: () => void;
   onScroll: UIEventHandler<HTMLDivElement>;
@@ -53,7 +57,7 @@ export function DirectProjectConversation({
           <DirectProjectTurn key={turn.key} turn={turn} />
         ))}
       </div>
-      {running ? (
+      {nativeRunning ? (
         <AgentMessageContent
           as="section"
           tone="process"
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn.tsx
index 5b043e8dd..b3d0df6c6 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn.tsx
@@ -20,14 +20,22 @@ import {
 /**
  * 一个完整回合的分区表现：用户发言、执行过程（工具/思考）与最终答复。
  *
- * 运行中的回合把执行过程平铺出来，已结束的回合折叠进「执行过程」；这一层只做投影到
- * 表现的渲染，不拥有任何回合状态。
+ * 未结束的回合（`running` / `awaiting-start`）把执行过程平铺出来并隐藏终态文案，
+ * `finished` 才折叠进「执行过程」；这一层只做投影到表现的渲染，不拥有任何回合状态。
+ *
+ * 三态的判据分两类，不要对调（三态定义与真值表见
+ * `../../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`）：
+ * - **否定式**（不要说它结束、不要折叠、不要显示终态文案）读 `state !== 'finished'`：
+ *   `awaiting-start` 时轮次确实还没结束，只是宿主还没确认。
+ * - **肯定式**（哪一段正文在流式、"正在处理"这类断言）读 `state === 'running'`：
+ *   `awaiting-start` 只说明本地已发出，不能据此断言宿主已经在跑。
  */
 export function DirectProjectTurn({ turn }: { turn: DirectChatTurn }) {
-  const streamingKey = turn.active
-    ? ([...turn.process].reverse().find((block) => block.kind === 'assistant')
-        ?.key ?? null)
-    : null;
+  const streamingKey =
+    turn.state === 'running'
+      ? ([...turn.process].reverse().find((block) => block.kind === 'assistant')
+          ?.key ?? null)
+      : null;
   return (
     <Fragment>
       {turn.users.map((block) =>
@@ -48,7 +56,7 @@ function renderTurnProcess(turn: DirectChatTurn, streamingKey: string | null) {
   const blocks = turn.process.map((block) =>
     renderBlock(turn, block, 'process', streamingKey),
   );
-  if (turn.active) return blocks;
+  if (turn.state !== 'finished') return blocks;
   return (
     <details className="message-turn-process" data-testid="turn-process">
       <summary>执行过程</summary>
@@ -58,7 +66,14 @@ function renderTurnProcess(turn: DirectChatTurn, streamingKey: string | null) {
 }
 
 function DirectProjectTurnUsage({ turn }: { turn: DirectChatTurn }) {
-  if (turn.active || !turn.startedAt) return null;
+  // 否定式判据：未结束的回合不显示终态文案。`awaiting-start` 走这一条，所以"本地已发出、
+  // 原生还没认领"的窗口里不会再出现「本轮结束于 … 耗时 0.0秒」。
+  // 仍未修的另一半（A）：`finished` 但没有可证明终态时间的回合，会被下面的 `Math.max` 兜底
+  // 量化成 0.0 秒，共两类——① 重进项目后读回来的历史回合（`turnEndedAt` 只活在本次会话里，
+  // 不会随 `project.jsonl` 持久化）；② 本地已发出却一个原生事件都没产生的回合（发送失败）。
+  // 修法是只在 `turn.endedAt > 0` 时渲染终态文案、耗时改由 `turnTotalDurationMs()` 出（边界缺失
+  // 就隐藏），属于产品口径变化（宁可隐藏也不编），确认后单独改；改完把这半段注释删掉。
+  if (turn.state !== 'finished' || !turn.startedAt) return null;
   const endedAt = Math.max(turn.endedAt, turn.startedAt);
   return (
     <p
@@ -84,7 +99,7 @@ function renderBlock(
       <ToolCallGroup
         key={block.key}
         calls={block.calls}
-        active={turn.active}
+        active={turn.state === 'running'}
         className="message-tool-call"
       />
     );
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts
index db43fe8e7..57356ad13 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts
@@ -12,6 +12,7 @@ import {
   directCodexContentToPromptText,
   directCodexUserItemFromContent,
   hasMeaningfulDirectCodexContent,
+  resourceLabelResolver,
 } from '../../../../features/project-workspace/resourceReferences';
 import { beginDirectRunAnalytics } from '../../../../services/clientAnalytics';
 import { captureAgentRuntimeError } from '../../../../services/errorReporting';
@@ -95,6 +96,56 @@ export type DirectProjectChatControllerProps = {
  *
  * 订阅、首屏锚点与历史分页、发送与 FIFO 队列、附件、终止、草稿和本地消息都归这里；
  * 工作台壳只注入项目上下文与两条权限门，不再持有 Direct 专属 state/ref/effect。
+ *
+ * ## 数据流（改判据前先读这一段）
+ *
+ * ```
+ * Rust 宿主（事实的产生地）
+ * ├─ project.jsonl                   持久化原始条目（AGC 写；app-server 回显的用户消息被过滤）
+ * └─ Thread Manager 事件队列（内存）   per-thread 事件序列 + 每 subscriber 游标 + lifecycle_anchor
+ *         │ append_direct_thread_event() → notify（只带 subscriptionId，纯唤醒）
+ *         ▼
+ * 传输层（三条通道，前端各拉各的）
+ *   A 运行态：notify → invoke consume_direct_project_thread → events[]（实时）
+ *   B 历史：  invoke read_direct_project_history_slice → items[]（分页，文件尾反向扫描）
+ *   C 本地：  前端自己造（乐观用户气泡、忙态、失败 / 终止说明）
+ *         ▼
+ * 前端
+ * useDirectThreadChatSubscription  reducer：A + B 进同一份 state（turnRunning / history / live）
+ *         ▼
+ * useDirectProjectChatController   本地状态：localMessages / turnBusy / pendingUserItemId / 队列
+ *         ▼
+ * DirectProjectChatView            turns = buildDirectChatTurns(...)；status = useDirectProjectTurnStatus(...)
+ *         ▼
+ * DirectProjectTurn                用户气泡 / 过程块 / 最终回复 / 本轮耗时
+ * ```
+ *
+ * 三份原始输入各自是什么、带什么、活多久：
+ * - 项目对话历史（`.agent/conversations/project.jsonl`）：持久，只有条目、**没有回合边界**，
+ *   经历史切片读取（首屏按 `lastCompletedItemId` 锚定）。
+ * - 运行态事件（subscribe / consume / notify）：进程内；`turn.started` / `turn.completed` 是原生回合
+ *   活跃与否的**唯一**判据；可回收事件被回收后靠 `lifecycle_anchor` 保住最新一条生命周期事件。
+ * - 本地发送：只存在于本次会话，`projectPath` 变化即清空；乐观气泡与原生条目同身份
+ *   （`direct-codex:{clientTurnId}:user`），所以两边按**身份**合并，不按时间戳猜。
+ *
+ * 一次发送的时序（第 2 → 3 步之间就是「本地已发出、宿主还没确认」的空窗）：
+ * 1. 按下发送：`localMessages += 乐观气泡`、`turnBusy=true`、`pendingUserItemId=本轮身份`（同帧）。
+ * 2. `invoke('chat_with_game_creator_direct_codex')`：Rust 先落盘用户条目，再发 `turn/start`，
+ *    **应答返回后**才 append `turn.started` 并 notify。
+ * 3. notify → consume → `turn.started`：reducer 的 `turnRunning=true`、`turnStartedAt`、`turnUserItemId`。
+ * 4. `item.completed`（本轮用户条目回显）：同身份条目已在历史里就合并进去，否则进 `live`；本地气泡此时被去重。
+ * 5. `item.delta` / `item.started` / `item.completed`：正文追加、工具卡片 upsert（先到定形、后到只补空）。
+ * 6. `turn.completed`：`live` 并入 `history` 后清空，`turnEndedAt` 冻结，边界按身份盖到本轮开口条目上。
+ * 7. 命令收尾（`finally`）：刷新清单 → `endTurnCommand()` 清掉忙态与在途身份 → 出队下一轮。
+ *    **顺序是契约**：出队会同步开始下一轮并设上它自己的忙态，所以清忙态必须早于出队；
+ *    权限被拒那种「本轮从未发出但要继续出队」的情况，也只标记 `queueAdvance`、由这里统一收口。
+ *
+ * 状态变量归属：reducer 的三个回合字段与 `history` / `live` 只由 `directThreadChat.ts` 写；
+ * 本文件的 `turnBusy` / `pendingUserItemId`（同生共死，唯一入口 `beginTurnCommand` /
+ * `endTurnCommand`）、`localMessages`、发送队列与分页 ref 只服务发送与展示；界面上的
+ * 「这一轮在跑吗」只有一个派生入口 `useDirectProjectTurnStatus()`，三态判据与真值表在
+ * `../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`，渲染时否定式读
+ * `state !== 'finished'`、肯定式读 `state === 'running'`（见 `DirectProjectTurn.tsx`）。
  */
 export function useDirectProjectChatController({
   assets,
@@ -106,10 +157,18 @@ export function useDirectProjectChatController({
   projectPath,
   refreshManifest,
 }: DirectProjectChatControllerProps) {
-  const [attachments, setAttachments] = useState<DirectCodexTurnAttachment[]>(
-    [],
-  );
   const [attachmentNotice, setAttachmentNotice] = useState('');
+  /**
+   * 附件导入进行中：导入结果还没落成正文芯片，这一轮先不许发出去，
+   * 否则用户以为带上的附件根本没进这一轮。并发导入共用一个计数。
+   */
+  const [attachmentsImporting, setAttachmentsImporting] = useState(false);
+  const attachmentsImportingCountRef = useRef(0);
+  /**
+   * 已经在飞、还没落成正文芯片的附件条数：并发导入各算各的预算时，这些名额必须先占住，
+   * 否则两次并发导入会拿着同一份草稿附件数各自放行，插进正文的芯片就超过上限。
+   */
+  const attachmentsPendingCountRef = useRef(0);
   const [queuedTurns, setQueuedTurns] = useState<QueuedChatTurn[]>([]);
   const queuedTurnsRef = useRef<QueuedChatTurn[]>([]);
   queuedTurnsRef.current = queuedTurns;
@@ -117,6 +176,9 @@ export function useDirectProjectChatController({
   const [statusNotice, setStatusNotice] = useState('');
   const [turnCancelling, setTurnCancelling] = useState(false);
   const [turnBusy, setTurnBusy] = useState(false);
+  // 本地已发出、原生还没认领的那一轮用户条目身份：只服务投影的 `awaiting-start` 展示态，
+  // 生命周期与 `turnBusy` 完全一致（命令在飞期间有值，收尾即清）。
+  const [pendingUserItemId, setPendingUserItemId] = useState<string>('');
   const [localMessages, setLocalMessages] = useState<ChatMessage[]>([]);
   // 订阅（subscribe/consume/notify）与聊天 reducer 状态在自己的 hook 里：
   // controller 只读投影后的条目与回合忙态，不再直接持有线程状态。
@@ -140,13 +202,13 @@ export function useDirectProjectChatController({
   const previousTurnRunningRef = useRef(currentTurnRunning);
 
   useEffect(() => {
-    setAttachments([]);
     setAttachmentNotice('');
     setComposerNotice('');
     setStatusNotice('');
     setQueuedTurns([]);
     queuedTurnsRef.current = [];
     setLocalMessages([]);
+    setPendingUserItemId('');
     setHistoryHasMore(false);
     historyOldestItemIdRef.current = null;
   }, [projectPath]);
@@ -198,9 +260,21 @@ export function useDirectProjectChatController({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [enabled, projectPath]);
 
-  function markTurnBusy(busy: boolean) {
-    turnBusyRef.current = busy;
-    setTurnBusy(busy);
+  /**
+   * 「本地这一轮的命令在飞」的唯一起止点：按下发送时带上本轮用户条目身份，收尾时一起清掉。
+   *
+   * 忙态与待认领身份必须同生共死，否则投影会拿一个过期的身份去判 `awaiting-start`。
+   */
+  function beginTurnCommand(userItemId: string) {
+    turnBusyRef.current = true;
+    setTurnBusy(true);
+    setPendingUserItemId(userItemId);
+  }
+
+  function endTurnCommand() {
+    turnBusyRef.current = false;
+    setTurnBusy(false);
+    setPendingUserItemId('');
   }
 
   function appendLocalMessage(message: ChatMessage) {
@@ -250,22 +324,43 @@ export function useDirectProjectChatController({
     if (next.length === 0) setComposerNotice('');
   }
 
-  async function uploadFiles(files: readonly File[]) {
+  /**
+   * 导入文件：上限按 `draftAttachmentCount`（草稿里已有的附件芯片数）算，
+   * 只把**导入成功**的附件交回宿主，由宿主插成正文芯片；失败的一条都不返回。
+   *
+   * 控制器不再持有待发附件列表：本轮附件只有「正文芯片」一份事实源，
+   * 所以这里不做任何「提交时再拼一次」的事。
+   *
+   * 上限必须是硬上限：草稿里的附件芯片数 + 这次与其它并发导入已经放行、还没落地的条数
+   * 一起算预算，放行的那部分在 `finally` 里还回去。
+   */
+  async function uploadFiles(
+    files: readonly File[],
+    draftAttachmentCount: number,
+  ): Promise<DirectCodexTurnAttachment[]> {
     const invoke = resolveTauriInvoke();
     if (!invoke || !projectPath) {
       setAttachmentNotice('需要先打开本地项目，才能上传文件');
-      return;
+      return [];
     }
     const accepted = files.slice(
       0,
-      Math.max(MAX_CHAT_COMPOSER_ATTACHMENTS - attachments.length, 0),
+      Math.max(
+        MAX_CHAT_COMPOSER_ATTACHMENTS -
+          draftAttachmentCount -
+          attachmentsPendingCountRef.current,
+        0,
+      ),
     );
     if (accepted.length === 0) {
       setAttachmentNotice(
         `最多同时携带 ${MAX_CHAT_COMPOSER_ATTACHMENTS} 个附件，请先移除已有附件`,
       );
-      return;
+      return [];
     }
+    attachmentsPendingCountRef.current += accepted.length;
+    attachmentsImportingCountRef.current += 1;
+    setAttachmentsImporting(true);
     setAttachmentNotice('正在上传文件');
     try {
       const imported = await uploadLocalFilesAsAttachments(
@@ -274,39 +369,41 @@ export function useDirectProjectChatController({
         accepted,
       );
       const nextAttachments = toDirectCodexTurnAttachments(imported);
-      if (projectPathRef.current !== projectPath) return;
-      setAttachments((current) =>
-        [...current, ...nextAttachments].slice(
-          0,
-          MAX_CHAT_COMPOSER_ATTACHMENTS,
-        ),
-      );
+      if (projectPathRef.current !== projectPath) return [];
       const failed = nextAttachments.filter(
         (attachment) => attachment.status === 'failed',
       );
-      setAttachmentNotice(
-        failed.length > 0
-          ? `${failed.length} 个文件未能上传：${failed[0]?.name ?? ''}`
-          : `已上传 ${nextAttachments.length} 个文件，将在下次发送时作为本轮附件`,
-      );
+      if (failed.length > 0) {
+        setAttachmentNotice(
+          `${failed.length} 个文件未能上传：${failed[0]?.name ?? ''}`,
+        );
+      } else {
+        setAttachmentNotice(
+          `已上传 ${nextAttachments.length} 个文件，将在下次发送时作为本轮附件`,
+        );
+      }
       void refreshManifest(projectPath);
+      return nextAttachments.filter(
+        (attachment) => attachment.status !== 'failed',
+      );
     } catch (error) {
       if (projectPathRef.current === projectPath) {
         setAttachmentNotice(
           error instanceof Error ? error.message : String(error),
         );
       }
+      return [];
+    } finally {
+      attachmentsPendingCountRef.current -= accepted.length;
+      attachmentsImportingCountRef.current -= 1;
+      if (attachmentsImportingCountRef.current <= 0) {
+        attachmentsImportingCountRef.current = 0;
+        setAttachmentsImporting(false);
+      }
     }
   }
 
-  function removeAttachment(index: number) {
-    setAttachments((current) =>
-      current.filter((_, currentIndex) => currentIndex !== index),
-    );
-  }
-
   function clearDraftInput() {
-    setAttachments([]);
     setAttachmentNotice('');
   }
 
@@ -334,7 +431,10 @@ export function useDirectProjectChatController({
       }
       return false;
     }
-    const prompt = directCodexContentToPromptText(content, assets).trim();
+    const prompt = directCodexContentToPromptText(
+      content,
+      resourceLabelResolver(assets),
+    ).trim();
     if (prompt === '/history') {
       clearPendingInput();
       void reloadHistory();
@@ -386,15 +486,23 @@ export function useDirectProjectChatController({
         role: 'user',
         text:
           input.messageText ??
-          directCodexContentToPromptText(input.userItem.content, assets),
+          directCodexContentToPromptText(
+            input.userItem.content,
+            resourceLabelResolver(assets),
+          ),
         runtimeOwned: true,
         messageId: directCodexConversationMessageId(input.clientTurnId, 'user'),
         updatedAt: Date.now(),
       });
     }
-    markTurnBusy(true);
+    beginTurnCommand(
+      directCodexConversationMessageId(input.clientTurnId, 'user'),
+    );
     void (async () => {
       let invoked = false;
+      // 权限被拒也要继续出队（见下），但出队必须发生在 finally 的 endTurnCommand() 之后：
+      // 在这里出队的话，下一轮刚设上的忙态会被紧接着的 finally 清掉。
+      let queueAdvance = false;
       try {
         onRuntimeError('');
         if (!input.directPolicyChecked) {
@@ -408,10 +516,9 @@ export function useDirectProjectChatController({
           });
           if (!allowed) {
             // 写权限门返回 false 且没有调用 onConfirmed（被策略拒绝、或读策略失败），
-            // 说明这一轮不会重跑；它已经被 dispatchNextQueuedTurn 出队，必须自己把
-            // 忙态放下并继续出队，否则后面的排队消息会永久卡住。
-            markTurnBusy(false);
-            dispatchNextQueuedTurn();
+            // 说明这一轮不会重跑；它已经被出队，必须继续出队，否则后面的排队消息会
+            // 永久卡住。放忙态与出队都交给 finally 收口，这里只做标记。
+            queueAdvance = true;
             return;
           }
         }
@@ -433,8 +540,15 @@ export function useDirectProjectChatController({
         if (invoked) {
           await refreshDirectManifest(nextProjectPath);
         }
-        markTurnBusy(false);
-        if (invoked && projectPathRef.current === nextProjectPath) {
+        // 忙态与在途身份每轮只在这里放一次，且必须早于出队：出队会同步开始下一轮并设上
+        // 它自己的忙态，清在它后面就等于把下一轮的忙态抹掉（composer 会以为可以并发发送，
+        // 下一轮的三态也会因为身份被清空而掉回 finished）。
+        endTurnCommand();
+        // 出队条件保持原样：真发出过的一轮要求项目没被换掉；权限被拒的一轮从未发出，
+        // 不受项目切换影响，照旧出队。
+        const invokedInSameProject =
+          invoked && projectPathRef.current === nextProjectPath;
+        if (queueAdvance || invokedInSameProject) {
           dispatchNextQueuedTurn();
         }
       }
@@ -491,6 +605,13 @@ export function useDirectProjectChatController({
         });
         return;
       }
+      // 真失败：这条命令返回就说明这一轮在宿主那边已经收场，但终态事件可能永远不来
+      // （app-server 崩了、任务被中止、panic 都只留下一条开着的 `turn.started`）。
+      // 按本轮身份放掉原生忙态，否则界面会一直显示「正在处理」、输入盒一直排队。
+      // 主动终止与「正在跑的是另一轮」不走这里：前者宿主必然补终态，后者不是这一轮。
+      directThread.stopCommandTurn(
+        directCodexConversationMessageId(input.clientTurnId, 'user'),
+      );
       void captureAgentRuntimeError(error, DIRECT_CODEX_AGENT_ID);
       const message = error instanceof Error ? error.message : String(error);
       let persistedDetail = '';
@@ -554,7 +675,7 @@ export function useDirectProjectChatController({
       const message = result?.message?.trim();
       if (result?.outcome === 'released') {
         directThread.markTurnStopped();
-        markTurnBusy(false);
+        endTurnCommand();
         onRuntimeError('');
         setComposerNotice(message ?? '已结束这一轮占用，可以直接重新发送消息');
       } else if (message) {
@@ -717,8 +838,8 @@ export function useDirectProjectChatController({
 
   return {
     appendLocalMessage,
-    attachments,
     attachmentNotice,
+    attachmentsImporting,
     cancelQueuedTurn,
     cancelTurn,
     composerNotice,
@@ -727,9 +848,9 @@ export function useDirectProjectChatController({
     historyHasMore,
     loadEarlierHistory,
     localMessages,
+    pendingUserItemId,
     queuedTurns,
     reloadHistory,
-    removeAttachment,
     startInitialTurn: startTurn,
     statusNotice,
     submit,
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts
new file mode 100644
index 000000000..05c9f456e
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts
@@ -0,0 +1,68 @@
+import { useMemo } from 'react';
+
+import type {
+  DirectChatTurn,
+  DirectChatTurnState,
+} from '../conversation/directTurnPresentation';
+
+/**
+ * DirectProject「这一轮在跑吗」的唯一派生入口。
+ *
+ * 同一件事此前在四层里各叫一个名字（reducer 的 `turnRunning`、controller 的 `turnBusy`、
+ * 视图里手拼的 `busy`、投影里的 `active`），读代码时无法判断谁该信谁。这里把它们的语义
+ * 一次讲清楚，组件只读这一个对象：
+ *
+ * - `nativeRunning`：**原生真相**。只由订阅 reducer 的 `turnRunning` 给出（`turn.started`
+ *   已到、`turn.completed` 未到）。它决定"陶泥儿正在处理"这类原生过程提示。
+ * - `commandInFlight`：**本地真相**。本次会话的发送命令是否在飞（写权限门 → invoke →
+ *   收尾）；它从按下发送那一刻就为真，与原生是否已经开始无关。
+ * - `displayBusy`：header / composer 该读的忙态，就是两者的并集：只要有一条成立就不能再
+ *   接受新的发送。
+ * - `latestTurnState`：最新一轮在界面上的三态（投影结果）；没有回合时为 null。
+ *
+ * 约定：新增"忙/在跑"类判据一律先落进这里，不要在组件里再拼布尔。
+ * `latestTurnState` 三态各自的含义、判据输入与真值表写在
+ * `../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。
+ * 数据流、变量归属与一次发送的时序见 `useDirectProjectChatController.ts` 的模块注释。
+ */
+export type DirectProjectTurnStatus = {
+  nativeRunning: boolean;
+  commandInFlight: boolean;
+  displayBusy: boolean;
+  latestTurnState: DirectChatTurnState | null;
+};
+
+export function deriveDirectProjectTurnStatus({
+  turnRunning,
+  turnBusy,
+  turns,
+}: {
+  turnRunning: boolean;
+  turnBusy: boolean;
+  turns: readonly DirectChatTurn[];
+}): DirectProjectTurnStatus {
+  const nativeRunning = Boolean(turnRunning);
+  const commandInFlight = Boolean(turnBusy);
+  const latest = turns.length > 0 ? turns[turns.length - 1] : null;
+  return {
+    nativeRunning,
+    commandInFlight,
+    displayBusy: nativeRunning || commandInFlight,
+    latestTurnState: latest ? latest.state : null,
+  };
+}
+
+export function useDirectProjectTurnStatus({
+  turnRunning,
+  turnBusy,
+  turns,
+}: {
+  turnRunning: boolean;
+  turnBusy: boolean;
+  turns: readonly DirectChatTurn[];
+}): DirectProjectTurnStatus {
+  return useMemo(
+    () => deriveDirectProjectTurnStatus({ turnRunning, turnBusy, turns }),
+    [turnRunning, turnBusy, turns],
+  );
+}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts
index 90757bdce..463954657 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts
@@ -19,6 +19,7 @@ import {
   mergeDirectHistoryItems,
   resolveDirectThreadBootstrap,
   selectDirectChatEntries,
+  stopDirectThreadTurn,
 } from '../conversation/directThreadChat';
 import type { DirectThreadConsumeResult } from '../generated/DirectThreadConsumeResult';
 import type { DirectThreadItem } from '../generated/DirectThreadItem';
@@ -40,6 +41,11 @@ export type DirectThreadChatSubscription = {
   mergeHistoryItems: (items: readonly DirectThreadItem[]) => void;
   /** 终止成功（`released`）时手动放掉回合占用：订阅可能要等下一个事件才知道。 */
   markTurnStopped: () => void;
+  /**
+   * 本地命令失败收场时按身份放掉这一轮：宿主的终态事件可能永远不会来（进程崩了 /
+   * 任务被中止），不能一直挂在 `turn.started` 上显示「正在处理」。
+   */
+  stopCommandTurn: (userItemId: string) => void;
 };
 
 /**
@@ -185,6 +191,13 @@ export function useDirectThreadChatSubscription({
     [],
   );
 
+  const stopCommandTurn = useMemo(
+    () => (userItemId: string) => {
+      setState((current) => stopDirectThreadTurn(current, userItemId));
+    },
+    [],
+  );
+
   const entries = useMemo(() => selectDirectChatEntries(state), [state]);
 
   return {
@@ -194,5 +207,6 @@ export function useDirectThreadChatSubscription({
     anchorGateRef,
     mergeHistoryItems,
     markTurnStopped,
+    stopCommandTurn,
   };
 }
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts
index 4ed45d4c6..7075634a6 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts
@@ -45,7 +45,14 @@ export type DirectChatEntry = {
 };
 
 export type DirectThreadChatState = {
-  /** 最新回合是否还在跑；只由生命周期事件的先后决定。 */
+  /**
+   * 最新**原生**回合是否还在跑；只由生命周期事件（`turn.started` / `turn.completed`）
+   * 的先后决定。
+   *
+   * 它不等于界面上的「这一轮在跑吗」：本地已发出、宿主还没回 `turn.started` 的那一段
+   * 窗口里它为假，但那一轮在界面上是"待认领"而不是"已结束"。界面侧的三态与判据见
+   * `directTurnPresentation.ts` 的 `DirectChatTurnState`。
+   */
   turnRunning: boolean;
   /** 原生 `turn.started.at`：本轮用户实际发送时间缺失时的起点兜底；0 = 缺失。 */
   turnStartedAt: number;
@@ -58,6 +65,16 @@ export type DirectThreadChatState = {
    * 也不用时间戳近似。空串 = 原生没给身份（旧事件），此时不猜历史归属。
    */
   turnUserItemId: string;
+  /**
+   * 「本地命令已经返回、宿主却一直没给终态」的那一轮身份（见 `stopDirectThreadTurn`）。
+   *
+   * `turn.started` 与 `turn.completed` 是原生回合唯一的开闭配对，但**进程崩了、任务被
+   * 中止、panic** 这类收场不会补终态事件，只留一条永远开着的 `turn.started`：界面上就
+   * 一直显示「正在处理」，输入盒也一直忙。本地那一条命令（`chat_with_game_creator_direct_codex`）
+   * 返回时说到底就是"这一轮在宿主那边已经收场"，这条身份就是它的记录：同身份的
+   * `turn.started` 迟到 / 重放回来不再复活这一轮，避免收口之后又被拉回运行态。
+   */
+  commandClosedTurnUserItemId: string;
   /** 历史切片条目，保持文件顺序。 */
   history: DirectChatEntry[];
   /** 当前回合的运行态条目，保持到达顺序；回合结束即并入历史并清空。 */
@@ -70,11 +87,40 @@ export function emptyDirectThreadChatState(): DirectThreadChatState {
     turnStartedAt: 0,
     turnEndedAt: 0,
     turnUserItemId: '',
+    commandClosedTurnUserItemId: '',
     history: [],
     live: [],
   };
 }
 
+/**
+ * 本地命令失败收场：这一轮命令已经返回，宿主却还在事件流里挂着 `turn.started`。
+ *
+ * 只放掉"是否在跑"，**不写终态时间**——命令返回不等于我们知道这一轮真正的结束时刻，
+ * 编一个只会让耗时变成假数。收口后同身份的 `turn.started` 迟到 / 重放回来不再复活，
+ * 免得刚修好的"还在处理"又被拉起来。宿主随后真发来 `turn.completed` 时照旧正常收口。
+ *
+ * 身份不同的轮次不动：宿主同时只允许一条回合，但"正在跑的是另一轮"（`another-turn-running`）
+ * 这种拒绝也要能原样报给用户，不能顺手把别人那轮抹掉。空身份（宿主没能落上身份）时按
+ * 本轮处理，否则这条兜底永远盖不住协议早期失败。
+ */
+export function stopDirectThreadTurn(
+  state: DirectThreadChatState,
+  userItemId: string,
+): DirectThreadChatState {
+  if (state.turnUserItemId !== '' && state.turnUserItemId !== userItemId) {
+    return state;
+  }
+  if (!state.turnRunning && state.commandClosedTurnUserItemId === userItemId) {
+    return state;
+  }
+  return {
+    ...state,
+    turnRunning: false,
+    commandClosedTurnUserItemId: userItemId,
+  };
+}
+
 /** 时间戳合法性：缺失 / 0 / 非有限都算没有这个边界，不用它计任何耗时。 */
 function validBoundaryAt(value: number | null | undefined): number {
   return typeof value === 'number' && Number.isFinite(value) && value > 0
@@ -295,6 +341,14 @@ export function reduceDirectThreadEvent(
       // 本轮的 canonical user identity 跟着事件走：新回合就换成新的；旧原生不带身份时
       // 清空而不是继承上一轮，避免上一轮迟到的终态按身份匹配到这一轮。
       const turnUserItemId = readDirectThreadEventUserItemId(event);
+      // 本地命令已经收过场的那一轮：迟到的 `turn.started` 不得把它拉回运行态（见
+      // `commandClosedTurnUserItemId`）。身份按 clientTurnId 唯一，只挡它自己那一轮。
+      if (
+        turnUserItemId !== '' &&
+        turnUserItemId === state.commandClosedTurnUserItemId
+      ) {
+        return state;
+      }
       return {
         ...state,
         turnRunning: true,
@@ -316,7 +370,17 @@ export function reduceDirectThreadEvent(
         return state;
       }
       // 已经收口、而且没有新的运行态条目：重复 / 迟到的终态事件不改动时间，也不复活运行态。
-      if (!state.turnRunning && state.live.length === 0) {
+      // 例外是"本地命令兜底收口"的那一轮（`commandClosedTurnUserItemId` 命中且还没有终态
+      // 时间）：那次收口本来就没写时间，宿主这份迟到的终态要拿来补上真正的结束时刻。
+      const lateTerminalForCommandClosedTurn =
+        eventUserItemId !== '' &&
+        eventUserItemId === state.commandClosedTurnUserItemId &&
+        state.turnEndedAt <= 0;
+      if (
+        !state.turnRunning &&
+        state.live.length === 0 &&
+        !lateTerminalForCommandClosedTurn
+      ) {
         return state;
       }
       return finishDirectThreadTurn(state, eventAt);
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts
index 1673032c9..33711fa2d 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts
@@ -36,6 +36,57 @@ export type DirectChatBlock =
   | { kind: 'reasoning'; key: string; text: string }
   | { kind: 'tools'; key: string; calls: DirectChatToolCard[] };
 
+/**
+ * 界面上一轮的三态。它是**展示态**，不是第二套回合生命周期。
+ *
+ * 三态各自能断言什么（渲染时按这个分两类，不要对调）：
+ * - `running`：**宿主已确认这一轮开始了**（订阅流里出现过 `turn.started`、还没出现
+ *   `turn.completed`）。它是唯一能做肯定式断言的态。
+ * - `awaiting-start`：**本地已把这轮交出去、宿主还没确认**（乐观气泡已出现，`turn.started`
+ *   未到）。只支持否定式断言："它还没结束"，不能说"它正在跑"。
+ * - `finished`：其余全部 —— 拿到终态的、身份不匹配的、不是最新一轮的，以及**拿不到边界的
+ *   历史回合**（这类最容易被误判成"还在跑"，必须落在这一态）。
+ *
+ * 判据用四个输入（下方 `buildDirectChatTurns` 里那几句 if 就是全部实现）：
+ * - `turn.nativeRunning` ← 入参 `turnRunning` ← reducer 的 `state.turnRunning`
+ *   （只由 `turn.started` / `turn.completed` 决定；`if (current)` 只赋给最后一条回合，
+ *   所以「非最新一轮 + nativeRunning」不可达）。
+ * - `pendingUserItemId` ← controller 在 `beginTurnCommand` / `endTurnCommand` 之间维护，
+ *   生命周期与 `turnBusy` 一致；空串 = 没有在途的本地回合。
+ * - `turn.key` ← 开这一轮的条目身份：原生用户条目用 `entry.itemId`，本地乐观气泡用
+ *   `message.messageId` —— 两者是**同一个** `direct-codex:{clientTurnId}:user`。
+ * - `stampedEnd` ← 本轮条目上盖的终态时间，只有 `turn.completed` / 终止收口才写。
+ *
+ * 真值表：
+ *
+ * | nativeRunning | 最新一轮 && pendingUserItemId 身份命中 | stampedEnd > 0 | → state |
+ * | true          | —                                     | —              | running |
+ * | false         | false                                 | 任意            | finished |
+ * | false         | true                                  | true           | finished |
+ * | false         | true                                  | false          | awaiting-start |
+ *
+ * 判据一律用**身份与显式事件**，不用时间戳大小：原生阶段时间是秒级精度、同一秒里可能连开
+ * 两轮，回显条目的 `at` 还是宿主 ack 的观测时间（晚于用户真实发送）。这也是为什么
+ * `awaiting-start` 在"原生条目已回显、`turn.started` 未到"的次窗口里同样成立。
+ *
+ * 两个容易读错的地方：
+ * - `pendingUserItemId` 有值 **≠** `awaiting-start`：`invoke` 直到整轮结束才返回，所以
+ *   `turn.started` 之后它仍在，但那时 `nativeRunning` 已经把它接成 `running`。
+ * - `endedAt === 0` **≠** 还在跑：历史回合没有边界元数据（`turnEndedAt` 只是会话内展示
+ *   缓存），它们必须落 `finished`。
+ *
+ * 三态在渲染上的映射（否定式 / 肯定式）见 `DirectProjectTurn.tsx` 顶部注释；数据流、变量归属与
+ * 一次发送的时序见 `../controller/useDirectProjectChatController.ts` 的模块注释。
+ *
+ * 已知边界（改 `finished` 判据时要连着一起看）：`finished` 只断言"不再有理由认为它在跑"，
+ * **不断言"拿得到终态时间"**。有两类回合没有可证明的边界时间，只被
+ * `Math.max(turn.endedAt, turn.startedAt)` 兜底量化成 0.0 秒——① 重进项目后读回来的历史回合
+ * （`turnEndedAt` 只是会话内展示缓存，不随 `project.jsonl` 持久化）；② 本地已发出却一个原生事件
+ * 都没产生的回合（发送失败、`turn.started` 没来）。要不要把这两类的终态文案藏掉是产品口径问题
+ * （宁可隐藏也不编），需要单独确认后单独改，不要顺手塞进三态判据。
+ */
+export type DirectChatTurnState = 'running' | 'awaiting-start' | 'finished';
+
 export type DirectChatTurn = {
   key: string;
   /** 用户气泡：顺序即发出顺序。 */
@@ -44,7 +95,8 @@ export type DirectChatTurn = {
   process: DirectChatBlock[];
   /** 最终回复，以及失败 / 终止这类只存在于运行期的说明。 */
   finals: DirectChatBlock[];
-  active: boolean;
+  /** 这一轮在界面上的状态（三态，取代原来的 `active` 布尔）。 */
+  state: DirectChatTurnState;
   /**
    * 本轮起点：该轮**实际用户消息的发送时间**优先（与气泡显示的时间同源），
    * 缺失时用原生 `turn.started.at`，都拿不到是 0（此时隐藏不能证明的总耗时）。
@@ -60,7 +112,8 @@ type DirectChatTurnEntries = {
   /** 本地乐观用户气泡：还没有任何落盘条目时的用户消息。 */
   localUsers: DirectChatBlock[];
   notices: ChatMessage[];
-  active: boolean;
+  /** 原生回合是否在跑；只有一个来源——reducer 的 `turnRunning`。 */
+  nativeRunning: boolean;
 };
 
 function blockFromEntry(
@@ -178,7 +231,7 @@ function newTurn(key: string): DirectChatTurnEntries {
     entries: [],
     localUsers: [],
     notices: [],
-    active: false,
+    nativeRunning: false,
   };
 }
 
@@ -193,6 +246,7 @@ export function buildDirectChatTurns({
   localMessages = [],
   turnRunning = false,
   turnStartedAt = 0,
+  pendingUserItemId = '',
 }: {
   entries: readonly DirectChatEntry[];
   localMessages?: readonly ChatMessage[];
@@ -202,6 +256,14 @@ export function buildDirectChatTurns({
    * 不会覆盖用户实际发送时间，也不参与已完成回合。
    */
   turnStartedAt?: number;
+  /**
+   * 本地已发出、原生还没认领的那一轮用户条目身份（`direct-codex:{clientTurnId}:user`）。
+   *
+   * 只服务 `awaiting-start` 这一个展示态：身份命中、且本轮还没有明确终态时，最新一轮按
+   * 「待认领」而不是「已结束」呈现。原生 `turn.started` 一到，`turnRunning` 就把这一轮接
+   * 过去，这个入参不再参与判定；空串 = 没有在途的本地回合。
+   */
+  pendingUserItemId?: string;
 }): DirectChatTurn[] {
   const turns: DirectChatTurnEntries[] = [];
   let current: DirectChatTurnEntries | null = null;
@@ -247,10 +309,11 @@ export function buildDirectChatTurns({
     }
     current.notices.push(message);
   });
-  if (current) current.active = turnRunning;
+  if (current) current.nativeRunning = turnRunning;
 
-  return turns.map((turn) => {
-    const lastAssistant = turn.active
+  const newestTurnIndex = turns.length - 1;
+  return turns.map((turn, turnIndex) => {
+    const lastAssistant = turn.nativeRunning
       ? -1
       : turn.entries.reduce(
           (found, entry, index) =>
@@ -301,21 +364,38 @@ export function buildDirectChatTurns({
       (found, entry) => found || normalizeDirectTimestamp(entry.turnEndedAt),
       0,
     );
-    const startedAt =
-      userSentAt > 0
-        ? userSentAt
-        : turn.active
-          ? normalizeDirectTimestamp(turnStartedAt)
-          : stampedStart;
+    // 起点优先级（逐级覆盖，不嵌套三元）：条目上盖的起点 → 运行中改读原生
+    // `turn.started.at`（拿不到就是 0，不退回去用条目兜底）→ 该轮用户气泡自己的发送
+    // 时间最高优先。
+    let startedAt = stampedStart;
+    if (turn.nativeRunning) {
+      startedAt = normalizeDirectTimestamp(turnStartedAt);
+    }
+    if (userSentAt > 0) {
+      startedAt = userSentAt;
+    }
     // 终态只读**本轮条目**上盖的边界：跨轮 fallback 会把最新回合的终点填进所有
     // 拿不到时间的旧历史回合，等于给未知耗时编一个值。
-    const endedAt = turn.active ? 0 : stampedEnd;
+    const endedAt = turn.nativeRunning ? 0 : stampedEnd;
+    // 三态只在这里产生：原生在跑 = running；最新一轮是本地在途身份且没有终态 =
+    // awaiting-start；其余都是 finished。判据是身份（`itemId`）而不是时间戳大小。
+    let state: DirectChatTurnState = 'finished';
+    if (turn.nativeRunning) {
+      state = 'running';
+    } else if (
+      turnIndex === newestTurnIndex &&
+      pendingUserItemId !== '' &&
+      turn.key === pendingUserItemId &&
+      stampedEnd <= 0
+    ) {
+      state = 'awaiting-start';
+    }
     return {
       key: turn.key,
       users,
       process: mergeToolBlocks(process),
       finals,
-      active: turn.active,
+      state,
       startedAt,
       endedAt,
     } satisfies DirectChatTurn;
diff --git a/apps/ai-game-creator-shell/src/view/project-development/index.tsx b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
index edf2bc0d5..5aea932d5 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/index.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
@@ -16,10 +16,12 @@ import {
 } from '@genarrative/image-canvas-react';
 import { CanvasCardCornerActions } from '@genarrative/shared/components';
 import { save as saveNativeFileDialog } from '@tauri-apps/plugin-dialog';
+import { openUrl } from '@tauri-apps/plugin-opener';
 import {
   AtSign,
   Box,
   Crosshair,
+  ExternalLink,
   Eye,
   FileCode2,
   FileText,
@@ -104,16 +106,25 @@ import {
   isFloatingOverlayWheelEvent,
   useImageCanvasFloatingOptionDismiss,
 } from '../../../../../src/components/image-editor/useImageCanvasFloatingOptionDismiss';
+import type { ProjectRunNotice } from '../../features/app-shell/model';
 import { DesignWorkspacePanel } from '../../features/project-workspace/DesignWorkspacePanel';
 import {
   LocalGamePreviewFrame,
   type LocalGamePreviewInspectSelection,
   resolveEmbeddedPreviewUrl,
 } from '../../features/project-workspace/LocalGamePreviewFrame';
+import { attachmentReferenceProvider } from '../../features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../../features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../../features/project-workspace/reference-source/runtimeRegionReferenceProvider';
 import {
   ResourceReferenceInput,
   type ResourceReferenceInputHandle,
 } from '../../features/project-workspace/ResourceReferenceInput';
+import {
+  ResourceReferencePicker,
+  ResourceReferencePickerAction,
+  type ResourceReferencePickerHandle,
+} from '../../features/project-workspace/ResourceReferencePicker';
 import {
   type ChatComposerDraft,
   type ChatReference,
@@ -127,6 +138,7 @@ import {
   legacyContentDtoToContent,
   resolveActiveIterationVersion,
   resourceDisplayName,
+  resourceLabelResolver,
   resourceReferenceCategoryLabel,
 } from '../../features/project-workspace/resourceReferences';
 import { GameRunVersionPicker } from '../../features/resource-canvas/GameRunVersionPicker';
@@ -790,6 +802,13 @@ export type ProjectDevelopmentViewProps = {
   onPlay?: () => void;
   onMakeGame?: () => void;
   onRevealProjectDirectory?: () => void | Promise<void>;
+  /**
+   * 过程提示（成功 / 失败）的唯一出口。
+   *
+   * 「运行起来了」「在浏览器打开失败」这类反馈不进对话区，交给工作台壳弹 toast；
+   * 本视图不自己造第二套提示位。
+   */
+  onNotice?: (notice: ProjectRunNotice) => void;
   onManifestChange?: (
     projectPath: string,
     manifest: GameCreationAppManifest,
@@ -1795,6 +1814,7 @@ export default function ProjectDevelopmentView({
   onPlay,
   onMakeGame,
   onRevealProjectDirectory,
+  onNotice,
 }: ProjectDevelopmentViewProps) {
   const [mode, setMode] = useState<WorkbenchMode>('resources');
   const [runtimeInspectMode, setRuntimeInspectMode] = useState(false);
@@ -1886,6 +1906,21 @@ export default function ProjectDevelopmentView({
   const quickEditPromptInputRef = useRef<ResourceReferenceInputHandle | null>(
     null,
   );
+  const quickEditPromptRootRef = useRef<HTMLDivElement | null>(null);
+  const quickEditReferencePickerRef =
+    useRef<ResourceReferencePickerHandle | null>(null);
+  /*
+    快速编辑提示词的引用来源：只注入资源与两个静默 provider。
+    快速编辑把 `@` 引用当参考图用，`$` Skill 候选在这一条路径上只会退化成正文文本。
+  */
+  const quickEditReferenceProviders = useMemo(
+    () => [
+      createResourceReferenceProvider({ assets: manifest.assets }),
+      attachmentReferenceProvider,
+      runtimeRegionReferenceProvider,
+    ],
+    [manifest.assets],
+  );
   /**
    * 从本地未提交草稿回填到快速编辑输入区的 `@` 资源引用。
    *
@@ -2709,6 +2744,33 @@ export default function ProjectDevelopmentView({
 
   const preview = previewOverride ?? manifest.preview ?? null;
   const embeddedPreviewUrl = resolveEmbeddedPreviewUrl(preview);
+  /**
+   * 「在浏览器打开」：把当前预览地址交给系统默认浏览器。
+   *
+   * 这是**用户主动**动作。预览的启动与切换仍然只走内置运行画面、不自动开外部浏览器
+   * （那条边界由 `scripts/check-native-shells.mjs` 的守卫钉着）；失败时把原因交给
+   * `onNotice` 弹 toast，不在工具条里另造一条提示位、也不写进对话区。
+   */
+  const openPreviewInBrowser = useCallback(async () => {
+    if (!embeddedPreviewUrl) {
+      return;
+    }
+    try {
+      await openUrl(embeddedPreviewUrl);
+    } catch (error) {
+      // 没有提示通道时（测试挂载、未来宿主）至少留下排查痕迹，不静默吞掉。
+      if (!onNotice) {
+        console.error('[agc] 在浏览器打开失败', error);
+        return;
+      }
+      onNotice({
+        tone: 'error',
+        message: `在浏览器打开失败：${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      });
+    }
+  }, [embeddedPreviewUrl, onNotice]);
   const runAvailable =
     embeddedPreviewUrl !== null ||
     manifest.tasks.some(
@@ -7793,7 +7855,7 @@ export default function ProjectDevelopmentView({
         currentDraft &&
         directCodexContentToPromptText(
           currentDraft.content,
-          manifest.assets,
+          resourceLabelResolver(manifest.assets),
         ) !== text
       ) {
         quickEditPromptInputRef.current?.replaceText(text);
@@ -9645,6 +9707,22 @@ export default function ProjectDevelopmentView({
                   {runtimeInspectMode ? '退出点选' : '点选素材'}
                 </button>
               ) : null}
+              {/*
+                当前预览地址的出口。以前这里是一条「已载入客户端运行视图：http://…」小字，
+                长地址既占位又不可点：地址本身对用户没用，能一步跳浏览器才有用。
+                只在有活预览时出现，外观与其他动作按钮同款（见 `.game-workbench-view-actions button`）。
+              */}
+              {mode === 'run' && embeddedPreviewUrl ? (
+                <button
+                  type="button"
+                  className="game-workbench-browser-open-button"
+                  onClick={() => void openPreviewInBrowser()}
+                  title={`在浏览器打开 ${embeddedPreviewUrl}`}
+                >
+                  <ExternalLink size={15} aria-hidden="true" />
+                  在浏览器打开
+                </button>
+              ) : null}
               {mode === 'resources' && !uiEditorRoute ? (
                 <>
                   <button
@@ -9736,6 +9814,21 @@ export default function ProjectDevelopmentView({
                   </div>
                 </>
               ) : null}
+              {/*
+                C7 版本入口：与「打开项目目录 / 在浏览器打开」同处顶栏动作区，外观也走同一套
+                （基础规则在 `.game-workbench-view-actions button`）。它不再浮在运行画面上：
+                以前是绝对定位压在画面右上角，挡画面且与预览地址不对齐。
+
+                **UI 编辑器壳里不渲染**：那一页是聚焦编辑某个资源的界面，顶栏只留通用动作；
+                版本入口服务于资源画布与运行页（`@` 面板按当前版本取素材），编辑器不需要它。
+              */}
+              {uiEditorRoute ? null : (
+                <GameRunVersionPicker
+                  versions={projectVersions}
+                  activeVersionId={activeVersionId}
+                  onSelectVersion={selectActiveVersion}
+                />
+              )}
             </div>
             {/*
               布局状态提示**不进动作行**：它是一段随保存过程变长的文案（空 →「保存中」→
@@ -10170,10 +10263,8 @@ export default function ProjectDevelopmentView({
                                           ),
                                         ]}
                                         onChange={applyResourceQuickEditDraft}
-                                        assets={manifest.assets}
+                                        providers={quickEditReferenceProviders}
                                         projectPath={projectPath}
-                                        versions={projectVersions}
-                                        activeVersionId={activeVersionId}
                                         multiline
                                         rows={3}
                                         placeholder="你希望素材如何修改？"
@@ -10181,6 +10272,28 @@ export default function ProjectDevelopmentView({
                                         // （带资源编辑场景上下文与长度上限），
                                         // 不在这里再渲染第二个润色入口。
                                         showPolishAction={false}
+                                        containerRef={quickEditPromptRootRef}
+                                        inputActions={
+                                          <ResourceReferencePickerAction
+                                            onOpen={() =>
+                                              quickEditReferencePickerRef.current?.open()
+                                            }
+                                          />
+                                        }
+                                      />
+                                      {/* 素材选择器由宿主渲染、自己拿数据；确认后只把选中的引用交回输入区句柄。 */}
+                                      <ResourceReferencePicker
+                                        ref={quickEditReferencePickerRef}
+                                        anchorRef={quickEditPromptRootRef}
+                                        assets={manifest.assets}
+                                        versions={projectVersions}
+                                        activeVersionId={activeVersionId}
+                                        projectPath={projectPath}
+                                        onInsert={(references) =>
+                                          quickEditPromptInputRef.current?.insertReferences(
+                                            references,
+                                          )
+                                        }
                                       />
                                     </div>
                                   }
@@ -10889,11 +11002,6 @@ export default function ProjectDevelopmentView({
             </>
           ) : (
             <section className="game-run-surface" aria-label="运行表现层">
-              <GameRunVersionPicker
-                versions={projectVersions}
-                activeVersionId={activeVersionId}
-                onSelectVersion={selectActiveVersion}
-              />
               <div className="game-run-preview">
                 {embeddedPreviewUrl ? (
                   <LocalGamePreviewFrame
@@ -10931,41 +11039,42 @@ export default function ProjectDevelopmentView({
             </section>
           )}
           {/*
-            「生成任务」侧栏：常驻在**工作面右上角**（资源画布 / 运行表现层 / UI 编辑器各自一档坐标），
-            可折叠、非模态。它**不**参与 `isResourceCanvasFloatingPanelOpen` 的模态遮挡判据——
-            生成在后台跑，侧栏展开时画布必须照样能看能用；折叠只影响这个视图，任务本身活在账本
-            与本地队列里。位置与开合形态照抄美术画布（开关常驻右上角 + 面板贴着它展开），
-            颜色与外形仍走 AGC 的平台 token。
+            「生成任务」侧栏：常驻在**资源画布 / UI 编辑器**的右上角（各一档坐标），可折叠、非模态。
+            它**不**参与 `isResourceCanvasFloatingPanelOpen` 的模态遮挡判据——生成在后台跑，
+            侧栏展开时画布必须照样能看能用；折叠只影响这个视图，任务本身活在账本与本地队列里。
+
+            **运行表现层不挂它**：运行页要留给游戏画面，右上角是版本入口与「在浏览器打开」，
+            再叠一枚任务开关（或展开的面板）就会压在画面上。任务不会因此丢，切回资源页即可见。
           */}
-          <ResourceCanvasAssetGenerationTasksPanelView
-            tasks={resourceAssetGenerationTasks.filter(
-              (task) => task.projectId === manifest.projectId,
-            )}
-            resourceEditTasks={resourceCanvasResourceEdits.filter(
-              (task) =>
-                !task.restored ||
-                !resourceCanvasResourceEditTaskIsTerminal(task),
-            )}
-            open={resourceAssetGenerationTasksPanelOpen}
-            onToggleOpen={() =>
-              setResourceAssetGenerationTasksPanelOpen((current) => !current)
-            }
-            onFocusTask={focusResourceAssetGenerationTask}
-            /*
-              资源总览页与资源栏目画布页的顶部 chrome 不同：画布页钉着整宽的栏目标题栏
-              （含「返回资源总览」），总览页没有。两页因此各有一档坐标（见样式里的
-              `[data-generation-tasks-placement]`），切换时走锚点高度过渡。
-            */
-            placement={
-              uiEditorRoute
-                ? 'editor'
-                : mode === 'run'
-                  ? 'run'
+          {mode === 'run' ? null : (
+            <ResourceCanvasAssetGenerationTasksPanelView
+              tasks={resourceAssetGenerationTasks.filter(
+                (task) => task.projectId === manifest.projectId,
+              )}
+              resourceEditTasks={resourceCanvasResourceEdits.filter(
+                (task) =>
+                  !task.restored ||
+                  !resourceCanvasResourceEditTaskIsTerminal(task),
+              )}
+              open={resourceAssetGenerationTasksPanelOpen}
+              onToggleOpen={() =>
+                setResourceAssetGenerationTasksPanelOpen((current) => !current)
+              }
+              onFocusTask={focusResourceAssetGenerationTask}
+              /*
+                资源总览页与资源栏目画布页的顶部 chrome 不同：画布页钉着整宽的栏目标题栏
+                （含「返回资源总览」），总览页没有。两页因此各有一档坐标（见样式里的
+                `[data-generation-tasks-placement]`），切换时走锚点高度过渡。
+              */
+              placement={
+                uiEditorRoute
+                  ? 'editor'
                   : resourceBookView === 'child'
                     ? 'canvas'
                     : 'canvas-overview'
-            }
-          />
+              }
+            />
+          )}
         </section>
 
         {!uiEditorRoute ? (
diff --git a/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx b/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
index 81f8fe86d..d0b7d74d4 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
@@ -1,6 +1,6 @@
 import { ArrowUp, FileUp, Loader2 } from 'lucide-react';
 import type { FormEventHandler, RefObject, UIEventHandler } from 'react';
-import { useRef } from 'react';
+import { useMemo, useRef } from 'react';
 
 import { AgentMessageContent } from '../../../../../../packages/shared/src/components/AgentMessageContent';
 import type {
@@ -16,10 +16,14 @@ import {
   projectRuntimeVisibleError,
 } from '../../../features/agent-runtime';
 import { ConversationModelSelect } from '../../../features/project-workspace/ConversationModelSelect';
+import { attachmentReferenceProvider } from '../../../features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../../../features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../../../features/project-workspace/reference-source/runtimeRegionReferenceProvider';
 import {
   ResourceReferenceInput,
   type ResourceReferenceInputHandle,
 } from '../../../features/project-workspace/ResourceReferenceInput';
+import { assetsSignature } from '../../../features/project-workspace/resourceReferences';
 import { AgentReasoning } from '../chat/components/AgentReasoning/AgentReasoning';
 import { ComposerReasoningEffortSelect } from '../chat/components/DirectProjectComposer/ComposerControls';
 import { formatClockTime } from '../chat/components/ToolCallGroup/toolCallGroupPresentation';
@@ -55,7 +59,6 @@ function workspaceStatusForDisplay(workspaceStatus: string) {
 }
 
 type PlanningChatViewProps = {
-  activeVersionId?: string | null;
   chatProjectAssets: import('../../../../../../packages/shared/src/contracts/gameCreationApp').GameCreationAppAssetManifestEntry[];
   composerRef?: RefObject<ResourceReferenceInputHandle | null>;
   controlBusy: boolean;
@@ -84,7 +87,6 @@ type PlanningChatViewProps = {
   visibleMessages: ChatMessage[];
   conversationMessages?: ChatMessage[];
   workspaceStatus: string;
-  versions?: import('../../../../../../packages/shared/src/contracts/gameCreationApp').GameIterationVersion[];
   designView?: DesignView | null;
   onDesignApprove?: (requestId: string, approved: boolean) => void;
   onDesignClarify?: (
@@ -96,7 +98,6 @@ type PlanningChatViewProps = {
 };
 
 export function PlanningChatView({
-  activeVersionId = null,
   chatProjectAssets,
   composerRef,
   controlBusy,
@@ -123,13 +124,30 @@ export function PlanningChatView({
   visibleMessages,
   conversationMessages = visibleMessages,
   workspaceStatus,
-  versions,
   designView = null,
   onDesignApprove,
   onDesignClarify,
   onDesignRetry,
 }: PlanningChatViewProps) {
   const designFileInputRef = useRef<HTMLInputElement>(null);
+  /*
+    策划输入盒的引用来源：**只注入资源与两个静默 provider**。
+
+    `$` Skill 候选只有 DirectProject 回合那条路径会把 `agc_skill_reference` 解析成真 Skill，
+    这里注入 Skill provider 只会得到一个退化成本文的误导入口，所以不注入。
+  */
+  const chatProjectAssetsSignature = assetsSignature(chatProjectAssets);
+  const referenceProviders = useMemo(
+    () => [
+      createResourceReferenceProvider({ assets: chatProjectAssets }),
+      attachmentReferenceProvider,
+      runtimeRegionReferenceProvider,
+    ],
+    // `chatProjectAssets` 由工作台壳每次渲染重新 `.filter()` 派生，依赖它等于从不命中缓存：
+    // provider 身份一变，输入区就重新注册 Lexical 更新监听。按内容签名取依赖才真的能跳过重建。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [chatProjectAssetsSignature],
+  );
   let submitLabel = '发送';
   if (needsUserInput) {
     submitLabel = '等待回答';
@@ -199,9 +217,11 @@ export function PlanningChatView({
               className={`project-chat-topbar-dot${controlBusy ? ' is-busy' : ''}`}
               aria-hidden="true"
             />
-            {controlBusy
-              ? '策划 Agent 正在处理'
-              : workspaceStatusForDisplay(workspaceStatus)}
+            <span>
+              {controlBusy
+                ? '策划 Agent 正在处理'
+                : workspaceStatusForDisplay(workspaceStatus)}
+            </span>
           </span>
         </header>
         <div
@@ -304,13 +324,10 @@ export function PlanningChatView({
           <ResourceReferenceInput
             ref={composerRef}
             ariaLabel="项目需求"
-            activeVersionId={activeVersionId}
-            versions={versions}
-            assets={chatProjectAssets}
+            providers={referenceProviders}
             projectPath={projectPath}
             disabled={composerDisabled}
             rows={3}
-            showTriggerButton={false}
             showPolishAction={false}
             placeholder=""
           />
diff --git a/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts
index b38005fc0..205bd0fca 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts
@@ -22,6 +22,7 @@ import {
   act,
   createGameCreationAppManifest,
   createProjectChatRuntimeHarness,
+  emptyProjectPolicy,
   expect,
   fireEvent,
   it,
@@ -256,9 +257,10 @@ export function registerChatComposerControlTests() {
       },
     ];
 
-    // chip 文案与聊天输入区同口径：用户看到的是 `@显示名`，不是 `@内部 id`。
+    // chip 文案与聊天输入区同口径：用户看到的是 `@显示名`，不是 `@内部 id`；
+    // 引用 token 前后各留一个空白（出站文本与反解析口径自洽）。
     expect(queuedChatTurnLabel(turn, manifestAssets)).toBe(
-      '用这张图改一下@hero',
+      '用这张图改一下 @hero',
     );
   });
 
@@ -520,6 +522,134 @@ export function registerChatComposerControlTests() {
     });
   });
 
+  it('does not report a finished turn while the host has not acknowledged the send yet', async () => {
+    const pending: Array<{ resolve: (value: string) => void }> = [];
+    const { invoke, surface } = await openDirectCodexSurface({
+      chat_with_game_creator_direct_codex: () =>
+        new Promise<string>((resolve) => {
+          pending.push({ resolve });
+        }),
+    });
+    const composer = within(surface).getByLabelText('陶泥儿对话内容');
+    await submitDirectTurn(surface, composer, '窗口期的消息');
+
+    // 写权限门是异步的，先等命令真的发出去，否则下面的窗口期断言会在 invoke 还没发生时就
+    // 通过、收尾的 `pending[0]?.resolve` 也变成空操作，用例根本没盖住它要盖的窗口。
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith(
+        'chat_with_game_creator_direct_codex',
+        expectDirectTurnWithText('窗口期的消息'),
+      );
+    });
+
+    // 本地乐观气泡立刻可见；此刻原生既没回 turn.started，也没回显用户条目，
+    // 这一轮属于「本地已发出、宿主未确认」，不得渲染成已结束。
+    await waitFor(() => {
+      expect(within(surface).getByText('窗口期的消息')).not.toBeNull();
+    });
+    expect(within(surface).queryByText(/本轮结束于/)).toBeNull();
+    expect(within(surface).queryByTestId('turn-usage')).toBeNull();
+
+    await act(async () => {
+      pending[0]?.resolve('回复');
+    });
+  });
+
+  it('stops claiming the turn is running when a failed send left turn.started open', async () => {
+    let harness: ReturnType<typeof createProjectChatRuntimeHarness> | null =
+      null;
+    const { surface } = await openDirectCodexSurface(
+      {
+        chat_with_game_creator_direct_codex: (
+          args: Record<string, unknown> | undefined,
+        ) => {
+          // 宿主先认领了这一轮（turn.started），随后崩掉：没有终态事件，命令以失败返回。
+          harness?.emitDirectThreadEvents({
+            type: 'turn.started',
+            at: 5_000,
+            userItemId: `direct-codex:${String(args?.clientTurnId ?? '')}:user`,
+          });
+          throw new Error('模拟宿主崩溃：turn.started 之后没有终态事件');
+        },
+      },
+      (directHarness) => {
+        harness = directHarness;
+      },
+    );
+    const composer = within(surface).getByLabelText('陶泥儿对话内容');
+    await submitDirectTurn(surface, composer, '崩掉的那条');
+
+    await waitFor(() => {
+      expect(
+        within(surface).getAllByText('陶泥儿智能创作 执行失败，请稍后重试')
+          .length,
+      ).toBeGreaterThan(0);
+    });
+    // 命令已经收场：卡片和输入区都不能再声称"还在处理"。
+    expect(within(surface).queryAllByText('陶泥儿正在处理')).toHaveLength(0);
+    expect(within(surface).queryByRole('button', { name: '终止' })).toBeNull();
+    expect(
+      within(surface).getByRole('button', { name: '发送' }),
+    ).not.toBeNull();
+  });
+
+  it('keeps the next queued turn busy when the write gate refuses the running one', async () => {
+    const pending: Array<{ resolve: (value: string) => void }> = [];
+    const deferredPolicies: Array<(value: unknown) => void> = [];
+    let policyAllowsWrite = false;
+    const { invoke, surface } = await openDirectCodexSurface({
+      read_project_permission_policy: () => {
+        if (policyAllowsWrite) return Promise.resolve(emptyProjectPolicy());
+        return new Promise((resolve) => {
+          deferredPolicies.push(resolve);
+        });
+      },
+      chat_with_game_creator_direct_codex: () =>
+        new Promise<string>((resolve) => {
+          pending.push({ resolve });
+        }),
+    });
+    const composer = within(surface).getByLabelText('陶泥儿对话内容');
+    await submitDirectTurn(surface, composer, '被拒的那条');
+
+    // 权限门还没回，先把第二条排进队列：后面那条要等被拒的这一轮出队才会发出去。
+    await setComposerText(composer, '后面那条');
+    submitComposerForm(composer);
+    const queue = await within(surface).findByLabelText('待发送消息队列');
+    expect(within(queue).getByText('后面那条')).not.toBeNull();
+
+    // 写权限门拒绝这一轮（策略要求确认，且此刻没有 onConfirmed）：这一轮不会重跑，
+    // 队列必须继续走，而它出队后那一轮仍要算「命令在飞」。
+    policyAllowsWrite = true;
+    await act(async () => {
+      for (const resolve of deferredPolicies.splice(0)) {
+        resolve({
+          path: '.agent/policy.json',
+          policy: {
+            deniedCommands: [],
+            confirmCommands: ['conversation.write'],
+          },
+        });
+      }
+    });
+
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith(
+        'chat_with_game_creator_direct_codex',
+        expectDirectTurnWithText('后面那条'),
+      );
+    });
+    // 被出队的那一轮还在飞：上一轮的收尾不得把它刚设上的忙态清掉。
+    expect(within(surface).queryByRole('button', { name: '发送' })).toBeNull();
+    expect(
+      within(surface).getByRole('button', { name: '终止' }),
+    ).not.toBeNull();
+
+    await act(async () => {
+      pending[0]?.resolve('回复');
+    });
+  });
+
   it('restores a running DirectProject turn, queues the next message, and dispatches it on turn.completed', async () => {
     const pending: Array<{ resolve: (value: string) => void }> = [];
     const { invoke, surface, harness } = await openDirectCodexSurface(
diff --git a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
index 393e85953..79f1e49b7 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
@@ -405,6 +405,148 @@ export function registerDesignAgentSurfaceTests() {
     );
   });
 
+  it('follows streamed Design Agent content until the user scrolls up', async () => {
+    const harness = createProjectChatRuntimeHarness({
+      designAgentView: designConversationView(),
+      designAgentContinueView: designConversationView(),
+    });
+    renderDesignAgent(harness);
+
+    const input = await screen.findByLabelText('项目需求');
+    await setComposerText(input, '请继续完善方案');
+    fireEvent.submit(input.closest('form') as HTMLFormElement);
+    await waitFor(() =>
+      expect(harness.invoke).toHaveBeenCalledWith(
+        'continue_design_agent_session',
+        expect.objectContaining({
+          input: { type: 'message', text: '请继续完善方案' },
+        }),
+      ),
+    );
+    const continueCall = [...harness.invoke.mock.calls]
+      .reverse()
+      .find(([command]) => command === 'continue_design_agent_session');
+    const clientTurnId = String(
+      (continueCall?.[1] as { clientTurnId?: string }).clientTurnId,
+    );
+    const messageList = screen.getByLabelText('立项策划消息');
+    Object.defineProperty(messageList, 'scrollHeight', {
+      configurable: true,
+      value: 1000,
+    });
+    Object.defineProperty(messageList, 'clientHeight', {
+      configurable: true,
+      value: 200,
+    });
+
+    messageList.scrollTop = 800;
+    fireEvent.scroll(messageList);
+    act(() =>
+      harness.emitDesignAgentEvent({
+        projectPath: harness.projectPath,
+        clientTurnId,
+        kind: 'reasoning',
+        reasoningText: '先核对玩法循环',
+      }),
+    );
+    await screen.findAllByText('先核对玩法循环');
+    await waitFor(() => expect(messageList.scrollTop).toBe(1000));
+
+    messageList.scrollTop = 800;
+    fireEvent.scroll(messageList);
+    act(() =>
+      harness.emitDesignAgentEvent({
+        projectPath: harness.projectPath,
+        clientTurnId,
+        kind: 'text',
+        text: '正在补充关卡节奏',
+      }),
+    );
+    await screen.findByLabelText('策划 Agent 实时回复');
+    await waitFor(() => expect(messageList.scrollTop).toBe(1000));
+
+    messageList.scrollTop = 120;
+    fireEvent.scroll(messageList);
+    act(() => {
+      harness.emitDesignAgentEvent({
+        projectPath: harness.projectPath,
+        clientTurnId,
+        kind: 'reasoning',
+        reasoningText: '继续检查多人规则',
+      });
+      harness.emitDesignAgentEvent({
+        projectPath: harness.projectPath,
+        clientTurnId,
+        kind: 'text',
+        text: '正在补充关卡节奏与多人规则',
+      });
+    });
+    await screen.findAllByText('继续检查多人规则');
+    await waitFor(() =>
+      expect(
+        screen.getByLabelText('策划 Agent 实时回复').textContent,
+      ).toContain('多人规则'),
+    );
+    expect(messageList.scrollTop).toBe(120);
+  });
+
+  it('shows only known optimistic send times and does not invent persisted times', async () => {
+    const hydratedView = {
+      ...designConversationView(),
+      messages: [{ id: 'user-history', role: 'user', text: '历史策划需求' }],
+    };
+    const continuedView = {
+      ...designConversationView(),
+      messages: [
+        ...hydratedView.messages,
+        { id: 'user-current', role: 'user', text: '当前补充需求' },
+      ],
+    };
+    const harness = createProjectChatRuntimeHarness({
+      designAgentView: hydratedView,
+      designAgentContinueView: continuedView,
+    });
+    const originalInvoke = harness.invoke.getMockImplementation()!;
+    let finishContinue!: () => void;
+    const continueGate = new Promise<void>((resolve) => {
+      finishContinue = resolve;
+    });
+    harness.invoke.mockImplementation(async (command, args) => {
+      if (command === 'continue_design_agent_session') {
+        await continueGate;
+      }
+      return originalInvoke(command, args);
+    });
+    renderDesignAgent(harness);
+
+    const historicalText = await screen.findByText('历史策划需求');
+    expect(
+      historicalText.closest('.message')?.querySelector('time'),
+    ).toBeNull();
+
+    const input = screen.getByLabelText('项目需求');
+    await setComposerText(input, '当前补充需求');
+    fireEvent.submit(input.closest('form') as HTMLFormElement);
+    const optimisticText = await screen.findByText('当前补充需求');
+    const optimisticTime = optimisticText
+      .closest('.message')
+      ?.querySelector('time');
+    expect(optimisticTime).not.toBeNull();
+    expect(optimisticTime?.getAttribute('dateTime')).toBeTruthy();
+
+    await act(async () => finishContinue());
+    await waitFor(() => {
+      const currentText = screen.getByText('当前补充需求');
+      expect(currentText.closest('.message')?.querySelector('time')).toBeNull();
+    });
+    expect(
+      screen
+        .getByText('历史策划需求')
+        .closest('.message')
+        ?.querySelector('time'),
+    ).toBeNull();
+  });
+
   it('hydrates an existing design session and decides approval through design commands', async () => {
     const harness = createProjectChatRuntimeHarness({
       designAgentView: designApprovalView(),
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 119b1463f..1d30225a8 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -8821,7 +8821,8 @@ export function registerProjectAgentStatusTests() {
     );
     expect(within(reopened).getByText('待提交设计图')).not.toBeNull();
 
-    // 入口在「运行」页签下同样常驻：侧栏本体在运行态可见，入口若只在资源页签就没法再打开。
+    // 运行页签下**不挂**「生成任务」：那一页要留给游戏画面（顶栏是版本入口与「在浏览器打开」）。
+    // 任务不会因此丢——切回资源页签，入口与面板都回来。
     fireEvent.click(
       within(reopened).getByRole('button', { name: '关闭生成任务' }),
     );
@@ -8831,8 +8832,16 @@ export function registerProjectAgentStatusTests() {
     expect(
       screen.getByRole('tab', { name: '运行' }).getAttribute('aria-selected'),
     ).toBe('true');
+    expect(
+      screen.queryByRole('button', { name: /^生成任务(?: · \d+)?$/ }),
+    ).toBeNull();
+    expect(
+      document.querySelector('.game-resource-generation-tasks-anchor'),
+    ).toBeNull();
+
+    fireEvent.click(screen.getByRole('tab', { name: '资源管理' }));
     fireEvent.click(
-      screen.getByRole('button', { name: /^生成任务(?: · \d+)?$/ }),
+      await screen.findByRole('button', { name: /^生成任务(?: · \d+)?$/ }),
     );
     expect(
       await screen.findByRole('region', { name: '生成任务' }),
diff --git a/apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts b/apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts
new file mode 100644
index 000000000..5d9d59f3e
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts
@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+/**
+ * AGC 素材直传（封面 / 截图）的三步链路边界。
+ *
+ * 这里只替换平台 API 调用与对象存储直传实现，验证「凭证 → 直传 → confirm」的字段口径、
+ * 地址白名单与错误文案，不触达真实 Tauri HTTP 插件或 OSS。
+ */
+import { beforeEach, expect, test, vi } from 'vitest';
+
+const requestClientApiMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../src/services/clientApi', () => ({
+  requestClientApi: (...args: unknown[]) => requestClientApiMock(...args),
+}));
+
+import {
+  resolvePlatformAssetUploadUrl,
+  uploadPlatformMediaAsset,
+} from '../src/services/assetDirectUpload';
+
+const TICKET = {
+  upload: {
+    bucket: 'genarrative-assets',
+    host: 'https://genarrative-assets.oss-cn-shanghai.aliyuncs.com/',
+    objectKey:
+      'generated-character-drafts/game-distribution/cover/42/cover.png',
+    legacyPublicPath: '/generated-character-drafts/game-distribution/cover/42',
+    formFields: {
+      key: 'generated-character-drafts/game-distribution/cover/42/cover.png',
+      policy: 'policy-value',
+      OSSAccessKeyId: 'ak-value',
+      signature: 'signature-value',
+      success_action_status: '204',
+      'x-oss-meta-asset_kind': 'game_distribution_cover',
+    },
+  },
+};
+
+const CONFIRMED = {
+  assetObject: {
+    assetObjectId: 'asset_cover_1',
+    objectKey: TICKET.upload.objectKey,
+    assetKind: 'game_distribution_cover',
+  },
+};
+
+function buildCoverFile() {
+  return new File(['cover-bytes'], 'cover.png', { type: 'image/png' });
+}
+
+beforeEach(() => {
+  requestClientApiMock.mockReset();
+  requestClientApiMock
+    .mockResolvedValueOnce(TICKET)
+    .mockResolvedValueOnce(CONFIRMED);
+});
+
+test('封面按凭证、直传、confirm 三步上传并返回素材标识', async () => {
+  const uploadFetch = vi.fn(async () => new Response(null, { status: 204 }));
+  const file = buildCoverFile();
+
+  const uploaded = await uploadPlatformMediaAsset({
+    file,
+    assetKind: 'game_distribution_cover',
+    pathSegments: ['game-distribution', 'cover', '42'],
+    entityId: 'game-distribution-cover',
+    metadata: { game_distribution_media: 'cover' },
+    fetchImpl: uploadFetch,
+  });
+
+  expect(uploaded).toEqual({
+    assetObjectId: 'asset_cover_1',
+    objectKey: TICKET.upload.objectKey,
+  });
+
+  const ticketCall = requestClientApiMock.mock.calls[0];
+  expect(ticketCall?.[0]).toBe('/api/assets/direct-upload-tickets');
+  const ticketBody = JSON.parse(String((ticketCall?.[1] as RequestInit).body));
+  expect(ticketBody).toEqual(
+    expect.objectContaining({
+      legacyPrefix: 'generated-character-drafts',
+      pathSegments: ['game-distribution', 'cover', '42'],
+      fileName: 'cover.png',
+      contentType: 'image/png',
+      access: 'private',
+      maxSizeBytes: file.size,
+      metadata: {
+        asset_kind: 'game_distribution_cover',
+        game_distribution_media: 'cover',
+      },
+    }),
+  );
+
+  const uploadCall = uploadFetch.mock.calls[0] as unknown as [
+    string,
+    RequestInit,
+  ];
+  expect(uploadCall[0]).toBe(TICKET.upload.host);
+  expect(uploadCall[1].method).toBe('POST');
+  const formData = uploadCall[1].body as FormData;
+  expect(formData.get('policy')).toBe('policy-value');
+  expect(formData.get('signature')).toBe('signature-value');
+  expect(formData.get('success_action_status')).toBe('204');
+  const uploadedFile = formData.get('file');
+  expect(uploadedFile).toBeInstanceOf(File);
+  expect((uploadedFile as File).name).toBe('cover.png');
+
+  const confirmCall = requestClientApiMock.mock.calls[1];
+  expect(confirmCall?.[0]).toBe('/api/assets/objects/confirm');
+  expect(JSON.parse(String((confirmCall?.[1] as RequestInit).body))).toEqual({
+    bucket: 'genarrative-assets',
+    objectKey: TICKET.upload.objectKey,
+    contentType: 'image/png',
+    contentLength: file.size,
+    assetKind: 'game_distribution_cover',
+    accessPolicy: 'private',
+    entityId: 'game-distribution-cover',
+  });
+});
+
+test('直传地址不属于平台素材存储时失败关闭，且不发送文件', async () => {
+  requestClientApiMock.mockReset();
+  requestClientApiMock
+    .mockResolvedValueOnce({
+      upload: { ...TICKET.upload, host: 'https://evil.example.com/upload' },
+    })
+    .mockResolvedValueOnce(CONFIRMED);
+  const uploadFetch = vi.fn();
+
+  await expect(
+    uploadPlatformMediaAsset({
+      file: buildCoverFile(),
+      assetKind: 'game_distribution_cover',
+      pathSegments: ['game-distribution', 'cover', '42'],
+      entityId: 'game-distribution-cover',
+      fetchImpl: uploadFetch as never,
+    }),
+  ).rejects.toThrow('素材上传地址不属于平台素材存储，已终止上传');
+
+  expect(uploadFetch).not.toHaveBeenCalled();
+  expect(requestClientApiMock).toHaveBeenCalledTimes(1);
+});
+
+test('对象存储拒绝上传时给出可重试文案', async () => {
+  const uploadFetch = vi.fn(
+    async () => new Response('denied', { status: 403 }),
+  );
+
+  await expect(
+    uploadPlatformMediaAsset({
+      file: buildCoverFile(),
+      assetKind: 'game_distribution_screenshot',
+      pathSegments: ['game-distribution', 'screenshot', '42'],
+      entityId: 'game-distribution-screenshot',
+      fetchImpl: uploadFetch,
+    }),
+  ).rejects.toThrow('上传素材到对象存储失败（HTTP 403），请重试');
+
+  // 直传失败时不得再登记素材，避免留下没有实体的素材记录。
+  expect(requestClientApiMock).toHaveBeenCalledTimes(1);
+});
+
+test('直传网络/作用域错误转成可操作文案', async () => {
+  const uploadFetch = vi.fn(async () => {
+    throw new Error('url not allowed on the configured scope');
+  });
+
+  await expect(
+    uploadPlatformMediaAsset({
+      file: buildCoverFile(),
+      assetKind: 'game_distribution_cover',
+      pathSegments: ['game-distribution', 'cover', '42'],
+      entityId: 'game-distribution-cover',
+      fetchImpl: uploadFetch,
+    }),
+  ).rejects.toThrow(
+    '上传素材失败：无法访问素材存储，请检查网络后重试（url not allowed on the configured scope）',
+  );
+
+  // 直传抛错时不得继续登记素材。
+  expect(requestClientApiMock).toHaveBeenCalledTimes(1);
+});
+
+test('本地回环与阿里云 OSS 之外的主机一律拒绝', () => {
+  expect(resolvePlatformAssetUploadUrl('http://127.0.0.1:9000/bucket')).toBe(
+    'http://127.0.0.1:9000/bucket',
+  );
+  expect(
+    resolvePlatformAssetUploadUrl(
+      'https://genarrative-assets.oss-cn-beijing.aliyuncs.com/',
+    ),
+  ).toBe('https://genarrative-assets.oss-cn-beijing.aliyuncs.com/');
+  expect(() =>
+    resolvePlatformAssetUploadUrl('http://oss.example.com/'),
+  ).toThrow('素材上传地址不属于平台素材存储，已终止上传');
+  expect(() => resolvePlatformAssetUploadUrl('   ')).toThrow(
+    '素材上传地址为空，请稍后重试',
+  );
+});
diff --git a/apps/ai-game-creator-shell/tests/chatComposerAttachmentCap.test.tsx b/apps/ai-game-creator-shell/tests/chatComposerAttachmentCap.test.tsx
new file mode 100644
index 000000000..9698af429
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/chatComposerAttachmentCap.test.tsx
@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  MAX_CHAT_COMPOSER_ATTACHMENTS,
+  useDirectProjectChatController,
+} from '../src/view/project-development/chat/controller/useDirectProjectChatController';
+import type { DirectCodexTurnAttachment } from '../src/view/project-development/chat/conversation/directCodexTurnAttachments';
+
+// jsdom 的 Blob/File 没实现 `arrayBuffer`，而附件导入链路要按字节读文件。
+if (typeof Blob.prototype.arrayBuffer !== 'function') {
+  Blob.prototype.arrayBuffer = () =>
+    Promise.resolve(new Uint8Array([120]).buffer);
+}
+
+function files(count: number, prefix: string) {
+  return Array.from(
+    { length: count },
+    (_, index) =>
+      new File(['x'], `${prefix}-${index}.png`, { type: 'image/png' }),
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  window.__TAURI__ = undefined;
+});
+
+describe('聊天输入盒的附件上限', () => {
+  it('并发导入也守得住上限：在飞的条数先占名额', async () => {
+    let uploadSeq = 0;
+    const invoke = vi.fn(async (command: string, args?: unknown) => {
+      if (command !== 'upload_local_asset') {
+        throw new Error(`unexpected invoke ${command}`);
+      }
+      const fileName = (args as { fileName?: string }).fileName ?? 'file';
+      return { localPath: `assets/upload-${(uploadSeq += 1)}-${fileName}` };
+    });
+    window.__TAURI__ = { core: { invoke: invoke as never } };
+
+    const { result } = renderHook(() =>
+      useDirectProjectChatController({
+        assets: [],
+        enabled: false,
+        ensureConversationReadAllowed: async () => true,
+        ensureConversationWriteAllowed: async () => true,
+        onRuntimeError: () => undefined,
+        projectId: 'project-1',
+        projectPath: 'C:/project',
+        refreshManifest: () => undefined,
+      }),
+    );
+
+    // 两次并发导入各带 5 个文件：第一次占住 5 个名额，第二次只剩 3 个名额。
+    const imported: DirectCodexTurnAttachment[][] = [[], []];
+    await act(async () => {
+      const first = result.current.uploadFiles(files(5, 'first'), 0);
+      const second = result.current.uploadFiles(files(5, 'second'), 0);
+      [imported[0], imported[1]] = await Promise.all([first, second]);
+    });
+
+    await waitFor(() => {
+      expect(result.current.attachmentsImporting).toBe(false);
+    });
+    expect(imported[0]).toHaveLength(5);
+    expect(imported[1]).toHaveLength(3);
+    expect(imported[0].length + imported[1].length).toBe(
+      MAX_CHAT_COMPOSER_ATTACHMENTS,
+    );
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts b/apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts
index c185710a3..20a1ff525 100644
--- a/apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts
+++ b/apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts
@@ -416,3 +416,138 @@ describe('陶泥儿对话区：Codex 三段式（顶栏 / 唯一滚动区 / 文
     expect(pixelValue(listInPanelDirectCodex, 'min-height')).toBe(0);
   });
 });
+
+describe('策划对话：消息伸缩与长内容边界', () => {
+  function planningDeclarations(className: string, width: number) {
+    const root = document.createElement('div');
+    root.innerHTML = `<div class="window-chrome"><div class="window-chrome__content">
+      <div class="launcher-shell platform-theme"><aside></aside><main class="launcher-main">
+      <section class="launcher-page launcher-project-development game-project-workbench game-project-workbench--design">
+      <div class="game-workbench-layout game-workbench-layout--design">
+      <section class="game-workbench-stage"><div class="design-workspace-panel">
+        <div class="design-workspace-panel__body"><div class="design-workspace-tree"></div></div>
+      </div></section>
+      <aside class="game-workbench-chat"><header>策划</header>
+        <section class="project-chat-surface"><div class="project-chat-conversation">
+          <section class="design-agent-controls"></section>
+          <header class="project-chat-topbar"><span class="project-chat-topbar-status">
+            <span class="project-chat-topbar-dot"></span><span>已打开：项目</span>
+          </span></header>
+          <div class="message-list project-chat-message-list"></div>
+          <section class="design-agent-pending-actions"></section>
+          <form class="project-chat-composer"><p class="project-chat-composer-notice"></p></form>
+        </div></section>
+      </aside></div></section></main></div></div></div>`;
+    const element = root.querySelector(className)!;
+    // 从 DOM 匹配完整选择器，防止遗漏基础规则或误把 Direct 专用样式算到策划入口。
+    const selectors = rules.flatMap((rule) =>
+      rule.selectors.filter((selector) => {
+        try {
+          return element.matches(selector);
+        } catch {
+          // jsdom 不支持的浏览器伪类与本面板无关。
+          return false;
+        }
+      }),
+    );
+    return resolveDeclarations(rules, selectors, width);
+  }
+
+  it.each([1440, 390])(
+    '%ipx：消息吸收剩余高度，状态和输入区不参与拉伸',
+    (width) => {
+      const conversation = planningDeclarations(
+        '.project-chat-conversation',
+        width,
+      );
+      const list = planningDeclarations('.project-chat-message-list', width);
+      const composer = planningDeclarations('.project-chat-composer', width);
+      const topbar = planningDeclarations('.project-chat-topbar', width);
+      expect(declaration(conversation, 'display')).toBe('flex');
+      expect(declaration(conversation, 'flex-direction')).toBe('column');
+      expect(declaration(conversation, 'height')).toBe('100%');
+      expect(declaration(conversation, 'overflow')).toBe('visible');
+      expect(declaration(list, 'flex')).toBe('1 1 0');
+      expect(declaration(list, 'min-height')).toBe('0');
+      expect(declaration(list, 'overflow-y')).toBe('auto');
+      expect(declaration(composer, 'flex')).toBe('0 0 auto');
+      expect(declaration(topbar, 'flex')).toBe('0 0 auto');
+      expect(declaration(topbar, 'min-height')).toBe('44px');
+      expect(
+        declaration(
+          planningDeclarations('.project-chat-topbar-status', width),
+          'font-size',
+        ),
+      ).toBe('12px');
+      expect(
+        declaration(
+          planningDeclarations(
+            '.project-chat-topbar-status > span:last-child',
+            width,
+          ),
+          'overflow-wrap',
+        ),
+      ).toBe('anywhere');
+      for (const selector of [
+        '.design-agent-controls',
+        '.design-agent-pending-actions',
+      ]) {
+        const panel = planningDeclarations(selector, width);
+        expect(declaration(panel, 'max-height')).toBe('30%');
+        expect(declaration(panel, 'min-height')).toBe('0');
+        expect(declaration(panel, 'overflow')).toBe('auto');
+      }
+    },
+  );
+
+  it.each([390, 760])(
+    '%ipx：固定外壳内工作台可滚动到对话，两块面板保持明确高度',
+    (width) => {
+      const workbench = planningDeclarations('.game-project-workbench', width);
+      const layout = planningDeclarations('.game-workbench-layout', width);
+      const stage = planningDeclarations('.game-workbench-stage', width);
+      const chat = planningDeclarations('.game-workbench-chat', width);
+      expect(declaration(workbench, 'min-height')).toBe('0');
+      expect(declaration(workbench, 'overflow-y')).toBe('auto');
+      expect(declaration(workbench, 'overflow-x')).toBe('hidden');
+      expect(declaration(layout, 'height')).toBe('auto');
+      expect(declaration(layout, 'grid-template-columns')).toBe(
+        'minmax(0, 1fr)',
+      );
+      expect(declaration(stage, 'height')).toBe('560px');
+      expect(declaration(chat, 'height')).toBe(
+        'clamp(560px, calc(100dvh - 154px), 900px)',
+      );
+      expect(
+        declaration(
+          planningDeclarations('.design-workspace-panel', width),
+          'height',
+        ),
+      ).toBe('100%');
+      expect(
+        declaration(
+          planningDeclarations('.design-workspace-tree', width),
+          'overflow',
+        ),
+      ).toBe('auto');
+    },
+  );
+
+  it.each([761, 1280])('%ipx：双栏继续填满外壳剩余高度', (width) => {
+    const workbench = planningDeclarations('.game-project-workbench', width);
+    const layout = planningDeclarations('.game-workbench-layout', width);
+    expect(declaration(workbench, 'overflow')).toBe('hidden');
+    expect(workbench.has('overflow-y')).toBe(false);
+    expect(declaration(layout, 'height')).toBe('100%');
+    expect(declaration(layout, 'grid-template-columns')).toBe(
+      'minmax(0, 1fr) minmax(380px, 0.42fr)',
+    );
+  });
+
+  it('批量导入失败提示可滚动且可换行，不撑高输入区或撑宽面板', () => {
+    const notice = planningDeclarations('.project-chat-composer-notice', 390);
+    expect(declaration(notice, 'max-height')).toBe('96px');
+    expect(declaration(notice, 'overflow')).toBe('auto');
+    expect(declaration(notice, 'overflow-wrap')).toBe('anywhere');
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/chatPromptPolish.test.tsx b/apps/ai-game-creator-shell/tests/chatPromptPolish.test.tsx
index c179df4fc..0098d3bc7 100644
--- a/apps/ai-game-creator-shell/tests/chatPromptPolish.test.tsx
+++ b/apps/ai-game-creator-shell/tests/chatPromptPolish.test.tsx
@@ -21,6 +21,9 @@ import {
   shouldRemindChatPromptPolish,
   writeChatPromptPolishReminderDisabled,
 } from '../src/features/project-workspace/chatPromptPolish';
+import { attachmentReferenceProvider } from '../src/features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../src/features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../src/features/project-workspace/reference-source/runtimeRegionReferenceProvider';
 import type { ResourceReferenceInputHandle } from '../src/features/project-workspace/ResourceReferenceInput';
 import { ResourceReferenceInput } from '../src/features/project-workspace/ResourceReferenceInput';
 import {
@@ -123,7 +126,11 @@ function ControlledChatComposer({
         ref={composerRef}
         initialContent={initialContent}
         onChange={() => {}}
-        assets={[]}
+        providers={[
+          createResourceReferenceProvider({ assets: [] }),
+          attachmentReferenceProvider,
+          runtimeRegionReferenceProvider,
+        ]}
         projectPath="C:/project"
         ariaLabel="创作想法"
       />
diff --git a/apps/ai-game-creator-shell/tests/directProjectChatHeader.test.tsx b/apps/ai-game-creator-shell/tests/directProjectChatHeader.test.tsx
new file mode 100644
index 000000000..812e27427
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/directProjectChatHeader.test.tsx
@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+/**
+ * DirectProject 聊天头的发布入口。
+ *
+ * 发布面板与试玩包导出由工作台壳持有，聊天头只负责在壳传入回调时渲染入口；
+ * 没有回调（例如策划聊天面）时不能出现点不动的按钮。
+ */
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { DirectProjectChatHeader } from '../src/view/project-development/chat/components/DirectProjectChatHeader/DirectProjectChatHeader';
+
+afterEach(() => {
+  cleanup();
+});
+
+function renderHeader(
+  overrides: Partial<Parameters<typeof DirectProjectChatHeader>[0]> = {},
+) {
+  const onOpenSettings = vi.fn();
+  const onRequestGamePublish = vi.fn();
+  render(
+    <DirectProjectChatHeader
+      busy={false}
+      statusText="就绪"
+      onOpenSettings={onOpenSettings}
+      onRequestGamePublish={onRequestGamePublish}
+      {...overrides}
+    />,
+  );
+  return { onOpenSettings, onRequestGamePublish };
+}
+
+describe('DirectProjectChatHeader', () => {
+  it('传入发布回调时渲染发布入口并可触发', () => {
+    const { onRequestGamePublish } = renderHeader();
+
+    const publish = screen.getByRole('button', { name: '发布到游戏广场' });
+    expect(publish).toHaveProperty('disabled', false);
+    fireEvent.click(publish);
+    expect(onRequestGamePublish).toHaveBeenCalledTimes(1);
+  });
+
+  it('没有发布回调时不渲染发布入口', () => {
+    renderHeader({ onRequestGamePublish: undefined });
+
+    expect(screen.queryByRole('button', { name: '发布到游戏广场' })).toBeNull();
+    expect(screen.getByRole('button', { name: '设置' })).not.toBeNull();
+  });
+
+  it('回合进行中禁用发布入口，避免与运行时抢占', () => {
+    const { onRequestGamePublish } = renderHeader({ busy: true });
+
+    const publish = screen.getByRole('button', { name: '发布到游戏广场' });
+    expect(publish).toHaveProperty('disabled', true);
+    fireEvent.click(publish);
+    expect(onRequestGamePublish).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx b/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx
new file mode 100644
index 000000000..1561a54e7
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx
@@ -0,0 +1,61 @@
+/** @vitest-environment jsdom */
+import { render } from '@testing-library/react';
+import React from 'react';
+import { expect, it } from 'vitest';
+
+import { DirectProjectTurn } from '../src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn';
+import type {
+  DirectChatTurn,
+  DirectChatTurnState,
+} from '../src/view/project-development/chat/conversation/directTurnPresentation';
+
+const SENT_AT = 1_800_000_000_000;
+const ENDED_AT = SENT_AT + 12_400;
+
+const turn = (
+  state: DirectChatTurnState,
+  overrides: Partial<DirectChatTurn> = {},
+): DirectChatTurn => ({
+  key: 'direct-codex:turn-1:user',
+  users: [{ kind: 'user', key: 'u', text: '帮我做一个跳跃动作', at: SENT_AT }],
+  process: [
+    { kind: 'reasoning', key: 'r', text: '先看目录' },
+    { kind: 'assistant', key: 'a', text: '正在写' },
+  ],
+  finals: [{ kind: 'assistant', key: 'a-final', text: '改好了', at: ENDED_AT }],
+  state,
+  startedAt: SENT_AT,
+  endedAt: state === 'finished' ? ENDED_AT : 0,
+  ...overrides,
+});
+
+it('awaiting-start：本地已发出、原生还没认领时不显示终态文案，也不折叠过程', () => {
+  const view = render(
+    React.createElement(DirectProjectTurn, {
+      turn: turn('awaiting-start'),
+    }),
+  );
+  expect(view.queryByTestId('turn-usage')).toBeNull();
+  expect(view.queryByText(/本轮结束于/)).toBeNull();
+  // 否定式判据：未结束的回合把过程平铺出来，不折进「执行过程」。
+  expect(view.queryByTestId('turn-process')).toBeNull();
+  expect(view.getByLabelText('思考过程')).not.toBeNull();
+});
+
+it('running：原生回合在跑时同样不显示终态文案', () => {
+  const view = render(
+    React.createElement(DirectProjectTurn, { turn: turn('running') }),
+  );
+  expect(view.queryByTestId('turn-usage')).toBeNull();
+  expect(view.queryByTestId('turn-process')).toBeNull();
+});
+
+it('finished 且有明确终态：显示结束时间与耗时，过程折叠', () => {
+  const view = render(
+    React.createElement(DirectProjectTurn, { turn: turn('finished') }),
+  );
+  const usage = view.getByTestId('turn-usage');
+  expect(usage.textContent).toContain('本轮结束于');
+  expect(usage.textContent).toContain('耗时 12.4秒');
+  expect(view.queryByTestId('turn-process')).not.toBeNull();
+});
diff --git a/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts b/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts
new file mode 100644
index 000000000..7cab1828d
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+
+import { deriveDirectProjectTurnStatus } from '../src/view/project-development/chat/controller/useDirectProjectTurnStatus';
+import type { DirectChatTurn } from '../src/view/project-development/chat/conversation/directTurnPresentation';
+
+const turn = (key: string, state: DirectChatTurn['state']): DirectChatTurn => ({
+  key,
+  users: [],
+  process: [],
+  finals: [],
+  state,
+  startedAt: 1_800_000_000_000,
+  endedAt: 0,
+});
+
+describe('DirectProject 回合状态派生', () => {
+  it('displayBusy 是原生真相与本地命令在飞的并集', () => {
+    expect(
+      deriveDirectProjectTurnStatus({
+        turnRunning: true,
+        turnBusy: false,
+        turns: [],
+      }).displayBusy,
+    ).toBe(true);
+    expect(
+      deriveDirectProjectTurnStatus({
+        turnRunning: false,
+        turnBusy: true,
+        turns: [],
+      }).displayBusy,
+    ).toBe(true);
+    expect(
+      deriveDirectProjectTurnStatus({
+        turnRunning: false,
+        turnBusy: false,
+        turns: [],
+      }).displayBusy,
+    ).toBe(false);
+  });
+
+  it('两个来源各自独立暴露，不被并集吃掉', () => {
+    const status = deriveDirectProjectTurnStatus({
+      turnRunning: true,
+      turnBusy: true,
+      turns: [],
+    });
+    expect(status.nativeRunning).toBe(true);
+    expect(status.commandInFlight).toBe(true);
+  });
+
+  it('latestTurnState 取最新一轮的三态；没有回合时为 null', () => {
+    expect(
+      deriveDirectProjectTurnStatus({
+        turnRunning: false,
+        turnBusy: false,
+        turns: [turn('u1', 'finished'), turn('u2', 'awaiting-start')],
+      }).latestTurnState,
+    ).toBe('awaiting-start');
+    expect(
+      deriveDirectProjectTurnStatus({
+        turnRunning: false,
+        turnBusy: false,
+        turns: [],
+      }).latestTurnState,
+    ).toBeNull();
+  });
+
+  it('本地命令在飞不等于原生在跑', () => {
+    const status = deriveDirectProjectTurnStatus({
+      turnRunning: false,
+      turnBusy: true,
+      turns: [turn('u1', 'awaiting-start')],
+    });
+    expect(status.nativeRunning).toBe(false);
+    expect(status.latestTurnState).toBe('awaiting-start');
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/directThreadChat.test.ts b/apps/ai-game-creator-shell/tests/directThreadChat.test.ts
index 55a1b05d6..98c6d397e 100644
--- a/apps/ai-game-creator-shell/tests/directThreadChat.test.ts
+++ b/apps/ai-game-creator-shell/tests/directThreadChat.test.ts
@@ -11,6 +11,7 @@ import {
   reduceDirectThreadEvents,
   resolveDirectThreadBootstrap,
   selectDirectChatEntries,
+  stopDirectThreadTurn,
 } from '../src/view/project-development/chat/conversation/directThreadChat';
 import type { DirectThreadItem } from '../src/view/project-development/chat/conversation/directThreadItemProjection';
 import type { DirectThreadEvent } from '../src/view/project-development/chat/generated/DirectThreadEvent';
@@ -176,6 +177,54 @@ describe('DirectProject 聊天 reducer', () => {
     expect(selectDirectChatEntries(done)).toHaveLength(2);
   });
 
+  it('本地命令兜底收口后，迟到的同名 turn.started 不复活这一轮', () => {
+    const identity = 'direct-codex:client-turn-1:user';
+    const running = reduceDirectThreadEvents(emptyDirectThreadChatState(), [
+      event(withUserItemId({ type: 'turn.started', at: 1_000 }, identity)),
+      event({ type: 'item.completed', item: messageItem() }),
+    ]);
+    expect(running.turnRunning).toBe(true);
+
+    const stopped = stopDirectThreadTurn(running, identity);
+    expect(stopped.turnRunning).toBe(false);
+    // 兜底收口不写终态时间：命令返回不等于知道这一轮真正的结束时刻。
+    expect(stopped.turnEndedAt).toBe(0);
+
+    // 同一轮迟到的 turn.started 不再把它拉回运行态，运行态条目也没丢。
+    const revived = reduceDirectThreadEvents(stopped, [
+      event(withUserItemId({ type: 'turn.started', at: 2_000 }, identity)),
+    ]);
+    expect(revived.turnRunning).toBe(false);
+    expect(selectDirectChatEntries(revived)).toHaveLength(1);
+
+    // 宿主随后补上的真终态照旧收口，并把真正的结束时间补上。
+    const late = reduceDirectThreadEvents(revived, [
+      event(
+        withUserItemId(
+          { type: 'turn.completed', status: 'failed', at: 3_000 },
+          identity,
+        ),
+      ),
+    ]);
+    expect(late.turnRunning).toBe(false);
+    expect(late.turnEndedAt).toBe(3_000);
+  });
+
+  it('本地命令兜底收口不碰身份不同的那轮', () => {
+    const other = reduceDirectThreadEvents(emptyDirectThreadChatState(), [
+      event(
+        withUserItemId(
+          { type: 'turn.started', at: 1_000 },
+          'direct-codex:client-turn-9:user',
+        ),
+      ),
+    ]);
+    expect(
+      stopDirectThreadTurn(other, 'direct-codex:client-turn-1:user')
+        .turnRunning,
+    ).toBe(true);
+  });
+
   it('历史切片搬运层不合并，合并发生在前端投影', () => {
     const state = mergeDirectHistoryItems(emptyDirectThreadChatState(), [
       toolStarted(),
diff --git a/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts b/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts
index 853c930cd..1b95a2c0a 100644
--- a/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts
+++ b/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts
@@ -184,7 +184,7 @@ describe('DirectProject 聊天分区', () => {
       ],
       turnRunning: true,
     });
-    expect(turns[0]?.active).toBe(true);
+    expect(turns[0]?.state).toBe('running');
     expect(turns[0]?.finals).toEqual([]);
     expect(turns[0]?.process.map((block) => block.kind)).toEqual([
       'assistant',
@@ -293,7 +293,63 @@ describe('DirectProject 聊天分区', () => {
     });
     expect(turns.map((turn) => turn.key)).toEqual(['u1', 'local:1']);
     expect(turns[1]?.users).toHaveLength(1);
-    expect(turns[1]?.active).toBe(true);
+    expect(turns[1]?.state).toBe('running');
+  });
+
+  it('三态：本地已发出、原生还没认领的那一轮是 awaiting-start，不是已结束', () => {
+    const turns = buildDirectChatTurns({
+      entries: [],
+      localMessages: [localUser('本轮提问', 'direct-codex:turn-1:user')],
+      pendingUserItemId: 'direct-codex:turn-1:user',
+    });
+    expect(turns.map((turn) => turn.state)).toEqual(['awaiting-start']);
+    expect(turns[0]?.endedAt).toBe(0);
+    expect(turns[0]?.startedAt).toBe(1_800_000_002_000);
+  });
+
+  it('三态：原生用户条目先到、turn.started 还没到时仍是 awaiting-start', () => {
+    const turns = buildDirectChatTurns({
+      // 同身份的原生条目已经到了（本地气泡被去重），但原生回合还没开始。
+      entries: [userEntry('direct-codex:turn-1:user')],
+      localMessages: [localUser('本轮提问', 'direct-codex:turn-1:user')],
+      pendingUserItemId: 'direct-codex:turn-1:user',
+    });
+    expect(turns.map((turn) => turn.state)).toEqual(['awaiting-start']);
+  });
+
+  it('三态：拿到明确终态后，在途身份不再把这一轮判成待认领', () => {
+    const turns = buildDirectChatTurns({
+      entries: [
+        {
+          ...userEntry('direct-codex:turn-1:user'),
+          turnEndedAt: 1_800_000_010_000,
+        },
+      ],
+      pendingUserItemId: 'direct-codex:turn-1:user',
+    });
+    expect(turns[0]?.state).toBe('finished');
+    expect(turns[0]?.endedAt).toBe(1_800_000_010_000);
+  });
+
+  it('三态：只有最新一轮能是 awaiting-start，身份不匹配也不影响判定', () => {
+    const notNewest = buildDirectChatTurns({
+      entries: [userEntry('direct-codex:turn-1:user')],
+      localMessages: [localUser('第二条', 'direct-codex:turn-2:user')],
+      pendingUserItemId: 'direct-codex:turn-1:user',
+    });
+    expect(notNewest.map((turn) => turn.state)).toEqual([
+      'finished',
+      'finished',
+    ]);
+    const mismatch = buildDirectChatTurns({
+      entries: [userEntry('u1')],
+      localMessages: [localUser('第二条', 'direct-codex:turn-2:user')],
+      pendingUserItemId: 'direct-codex:turn-9:user',
+    });
+    expect(mismatch.map((turn) => turn.state)).toEqual([
+      'finished',
+      'finished',
+    ]);
   });
 
   it('历史无用户条目时也保留一个回合承载正文', () => {
diff --git a/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts b/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts
new file mode 100644
index 000000000..8c0f34c9f
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts
@@ -0,0 +1,193 @@
+// @vitest-environment jsdom
+import { beforeEach, expect, test, vi } from 'vitest';
+
+const fetchClientHttp = vi.fn();
+
+vi.mock('../src/services/clientHttp', () => ({
+  AGC_DEVELOPMENT_API_BASE_URL: 'https://dev.genarrative.world',
+  fetchClientHttp: (...args: unknown[]) => fetchClientHttp(...args),
+  getClientServerBaseUrl: () => 'https://dev.genarrative.world',
+  readClientHttpResponseText: (response: Response) => response.text(),
+}));
+
+vi.mock('../src/services/errorReporting', () => ({
+  captureClientError: vi.fn(),
+}));
+
+import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  publishLocalProjectGame,
+  readGamePublishAvailability,
+} from '../src/services/gameDistributionPublish';
+
+const MANIFEST = {
+  projectId: 'local-proj-1',
+  name: '星轨防线',
+  goal: '守住轨道城',
+} as unknown as GameCreationAppManifest;
+
+function jsonResponse(payload: unknown) {
+  return new Response(
+    JSON.stringify({
+      ok: true,
+      data: payload,
+      error: null,
+      meta: { apiVersion: 'v1' },
+    }),
+    {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    },
+  );
+}
+
+beforeEach(() => {
+  fetchClientHttp.mockReset();
+  window.localStorage.clear();
+});
+
+test('发布时携带本地项目标识，让重复发布复用同一个平台游戏', async () => {
+  fetchClientHttp
+    .mockResolvedValueOnce(
+      jsonResponse({ id: 'game_1', publicationRevision: 0 }),
+    )
+    .mockResolvedValueOnce(
+      jsonResponse({
+        gameId: 'game_1',
+        versionId: 'gamever_1',
+        versionNumber: 1,
+        status: 'awaiting_upload',
+      }),
+    )
+    .mockResolvedValueOnce(
+      jsonResponse({ versionId: 'gamever_1', status: 'uploaded' }),
+    )
+    .mockResolvedValueOnce(
+      jsonResponse({ version: { status: 'pending_review' } }),
+    );
+
+  const result = await publishLocalProjectGame({
+    invoke: (async (command: string) => {
+      expect(command).toBe('read_local_project_export_package');
+      return {
+        packageRelativePath: 'exports/playtest-package-1.zip',
+        packageBytes: [1, 2, 3],
+        packageSha256: 'a'.repeat(64),
+        packageSizeBytes: 3,
+        files: [{ path: 'index.html', sizeBytes: 3, sha256: 'a'.repeat(64) }],
+      };
+    }) as never,
+    projectPath: '/tmp/project',
+    packageRelativePath: 'exports/playtest-package-1.zip',
+    manifest: MANIFEST,
+    metadata: {
+      coverAssetId: 'asset_cover',
+      screenshots: ['asset_shot_1', 'asset_shot_2'],
+    },
+  });
+
+  const createGameCall = fetchClientHttp.mock.calls[0];
+  expect(createGameCall?.[0]).toBe('/api/game-distribution/games');
+  const createGameBody = JSON.parse(
+    String((createGameCall?.[1] as RequestInit).body),
+  );
+  expect(createGameBody.localProjectId).toBe('local-proj-1');
+  expect(createGameBody.coverAssetId).toBe('asset_cover');
+  expect(createGameBody.screenshots).toEqual(['asset_shot_1', 'asset_shot_2']);
+
+  const createVersionCall = fetchClientHttp.mock.calls[1];
+  expect(createVersionCall?.[0]).toBe(
+    '/api/game-distribution/games/game_1/versions',
+  );
+  expect(
+    JSON.parse(String((createVersionCall?.[1] as RequestInit).body))
+      .localProjectId,
+  ).toBe('local-proj-1');
+
+  expect(result.gameId).toBe('game_1');
+  expect(result.versionId).toBe('gamever_1');
+});
+
+test('缺少本地项目标识时在发起请求前失败关闭', async () => {
+  await expect(
+    publishLocalProjectGame({
+      invoke: (async () => ({
+        packageRelativePath: 'exports/playtest-package-1.zip',
+        packageBytes: [1],
+        packageSha256: 'a'.repeat(64),
+        packageSizeBytes: 1,
+        files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
+      })) as never,
+      projectPath: '/tmp/project',
+      packageRelativePath: 'exports/playtest-package-1.zip',
+      manifest: { ...MANIFEST, projectId: '   ' } as GameCreationAppManifest,
+      metadata: { coverAssetId: 'asset_cover' },
+    }),
+  ).rejects.toThrow('发布需要本地项目标识');
+  expect(fetchClientHttp).not.toHaveBeenCalled();
+});
+
+test('缺少封面时在创建游戏前失败关闭', async () => {
+  await expect(
+    publishLocalProjectGame({
+      invoke: (async () => ({
+        packageRelativePath: 'exports/playtest-package-1.zip',
+        packageBytes: [1],
+        packageSha256: 'a'.repeat(64),
+        packageSizeBytes: 1,
+        files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
+      })) as never,
+      projectPath: '/tmp/project',
+      packageRelativePath: 'exports/playtest-package-1.zip',
+      manifest: MANIFEST,
+      metadata: { coverAssetId: '   ' },
+    }),
+  ).rejects.toThrow('请先选择游戏封面');
+  expect(fetchClientHttp).not.toHaveBeenCalled();
+});
+
+test('截图超过 6 张时在创建游戏前失败关闭', async () => {
+  await expect(
+    publishLocalProjectGame({
+      invoke: (async () => ({
+        packageRelativePath: 'exports/playtest-package-1.zip',
+        packageBytes: [1],
+        packageSha256: 'a'.repeat(64),
+        packageSizeBytes: 1,
+        files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
+      })) as never,
+      projectPath: '/tmp/project',
+      packageRelativePath: 'exports/playtest-package-1.zip',
+      manifest: MANIFEST,
+      metadata: {
+        coverAssetId: 'asset_cover',
+        screenshots: Array.from({ length: 7 }, (_, index) => `asset_${index}`),
+      },
+    }),
+  ).rejects.toThrow('游戏截图最多 6 张');
+  expect(fetchClientHttp).not.toHaveBeenCalled();
+});
+
+test('发布灰度按后端运行时配置判定，命中才开放入口', async () => {
+  fetchClientHttp.mockResolvedValueOnce(
+    jsonResponse({ gameDistributionPublishEnabled: true }),
+  );
+  await expect(readGamePublishAvailability()).resolves.toBe(true);
+  expect(fetchClientHttp.mock.calls[0]?.[0]).toBe(
+    '/api/runtime/frontend-config',
+  );
+
+  fetchClientHttp.mockResolvedValueOnce(
+    jsonResponse({ gameDistributionPublishEnabled: false }),
+  );
+  await expect(readGamePublishAvailability()).resolves.toBe(false);
+
+  // 老后端/字段缺失时按未命中处理，入口不暴露。
+  fetchClientHttp.mockResolvedValueOnce(jsonResponse({}));
+  await expect(readGamePublishAvailability()).resolves.toBe(false);
+});
+
+test('发布灰度读取失败时抛出，由调用方按不开放处理', async () => {
+  fetchClientHttp.mockRejectedValueOnce(new Error('network down'));
+  await expect(readGamePublishAvailability()).rejects.toThrow();
+});
diff --git a/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts b/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
new file mode 100644
index 000000000..552b6c26c
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
@@ -0,0 +1,246 @@
+// @vitest-environment jsdom
+/**
+ * AGC「一键发布」的真实链路验证（默认跳过，按需开启）。
+ *
+ * 运行方式：
+ *   GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL=http://127.0.0.1:10001 \
+ *     npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
+ *
+ * 开启后测试会注册一个临时作者，并通过真实的 `clientApi` / `clientHttp`（而不是
+ * mock 请求层）调用 AGC 的发布函数，覆盖：本地导出包读取、创建游戏、同
+ * `localProjectId` 复用游戏身份、真实 ZIP 上传、送审与版本回读。
+ */
+import { createHash } from 'node:crypto';
+
+import JSZip from 'jszip';
+import { expect, test, vi } from 'vitest';
+
+import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import type { LocalProjectExportPackagePayload } from '../src/app/types';
+import { uploadPlatformMediaAsset } from '../src/services/assetDirectUpload';
+import { setStoredAuthAccessToken } from '../src/services/clientAuth';
+import { publishLocalProjectGame } from '../src/services/gameDistributionPublish';
+
+/** 1x1 透明 PNG：真实上传一张合法图片作为封面，避免依赖本地素材文件。 */
+const LIVE_COVER_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
+
+function buildLiveCoverFile() {
+  const bytes = Buffer.from(LIVE_COVER_PNG_BASE64, 'base64');
+  return new File([new Uint8Array(bytes)], 'agc-live-cover.png', {
+    type: 'image/png',
+  });
+}
+
+const liveBaseUrl = (process.env.GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL ?? '')
+  .trim()
+  .replace(/\/+$/u, '');
+const liveTest = liveBaseUrl ? test : test.skip;
+
+const realFetch = globalThis.fetch.bind(globalThis);
+const ENVELOPE_HEADERS = { 'x-genarrative-response-envelope': 'v1' };
+
+function apiUrl(path: string) {
+  return new URL(path, `${liveBaseUrl}/`).toString();
+}
+
+/** 把 AGC 的相对请求改写到本地栈；其余语义（头部、超时包装）保持真实实现。 */
+function installFetchBridge() {
+  vi.stubGlobal(
+    'fetch',
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url =
+        typeof input === 'string'
+          ? apiUrl(input)
+          : input instanceof URL
+            ? input.toString()
+            : input;
+      const body = init?.body;
+      if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        // jsdom 的 Blob/ArrayBuffer 属于另一个 realm，且旧版 jsdom 没有
+        // Blob.arrayBuffer；统一读成字节后复制为 Node 侧 Buffer 再转发。
+        const bytes = await readBlobBytes(body);
+        return realFetch(url as string, {
+          ...init,
+          body: Buffer.from(bytes),
+        });
+      }
+      return realFetch(url as string, init);
+    },
+  );
+}
+
+async function readBlobBytes(blob: Blob): Promise<Uint8Array> {
+  const maybeArrayBuffer = (
+    blob as Blob & { arrayBuffer?: () => Promise<ArrayBuffer> }
+  ).arrayBuffer;
+  if (typeof maybeArrayBuffer === 'function') {
+    return new Uint8Array(await maybeArrayBuffer.call(blob));
+  }
+  return await new Promise<Uint8Array>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const result = reader.result;
+      resolve(
+        result instanceof ArrayBuffer
+          ? new Uint8Array(result)
+          : new Uint8Array(0),
+      );
+    };
+    reader.onerror = () =>
+      reject(reader.error ?? new Error('读取发行包字节失败'));
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+async function unwrap<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  const parsed: unknown = JSON.parse(text);
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    (parsed as { ok?: boolean }).ok !== true
+  ) {
+    throw new Error(`后端返回失败：${text.slice(0, 400)}`);
+  }
+  return (parsed as { data: T }).data;
+}
+
+async function registerAuthor(): Promise<string> {
+  const phone = `136${String(Date.now()).slice(-8)}`;
+  const response = await realFetch(apiUrl('/api/auth/entry'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...ENVELOPE_HEADERS },
+    body: JSON.stringify({
+      purePhoneNumber: phone,
+      password: 'GenTest123!',
+    }),
+  });
+  const data = await unwrap<{ token: string }>(response);
+  return data.token;
+}
+
+async function buildExportPayload(): Promise<LocalProjectExportPackagePayload> {
+  const zip = new JSZip();
+  const indexHtml =
+    '<!doctype html><html><head><meta charset="utf-8"><title>AGC Live</title>' +
+    '<script src="assets/app.js"></script></head><body><h1>AGC-LIVE</h1></body></html>';
+  const appJs =
+    'window.__agcLive=1;document.documentElement.dataset.booted="agc";';
+  zip.file('index.html', indexHtml);
+  zip.file('assets/app.js', appJs);
+  const bytes = await zip.generateAsync({ type: 'uint8array' });
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  return {
+    packageRelativePath: 'dist/game.zip',
+    packageBytes: Array.from(bytes),
+    packageSha256: sha256,
+    packageSizeBytes: bytes.length,
+    files: [
+      {
+        path: 'index.html',
+        sizeBytes: Buffer.byteLength(indexHtml),
+        sha256: createHash('sha256').update(indexHtml).digest('hex'),
+      },
+      {
+        path: 'assets/app.js',
+        sizeBytes: Buffer.byteLength(appJs),
+        sha256: createHash('sha256').update(appJs).digest('hex'),
+      },
+    ],
+  };
+}
+
+liveTest(
+  'AGC 发布函数在真实后端完成创建、上传、送审并在重复发布时复用游戏身份',
+  async () => {
+    installFetchBridge();
+    const token = await registerAuthor();
+    setStoredAccessToken(token);
+
+    const payload = await buildExportPayload();
+    const stamp = String(Date.now());
+    const manifest = {
+      projectId: `agc-live-${stamp}`,
+      name: `AGC 真实发布${stamp.slice(-4)}`,
+      goal: '验证 AGC 一键发布链路',
+    } as unknown as GameCreationAppManifest;
+    const invoke = vi.fn(async () => payload);
+    // 服务端要求发布必须带封面：真实走一遍凭证 → 直传 → confirm。
+    const uploadedCover = await uploadPlatformMediaAsset({
+      file: buildLiveCoverFile(),
+      assetKind: 'game_distribution_cover',
+      pathSegments: ['game-distribution', 'cover', stamp],
+      entityId: 'game-distribution-cover',
+      // jsdom 里没有 Tauri HTTP 插件，复用测试注入的 fetch bridge 直连 dev OSS。
+      fetchImpl: (input, init) => realFetch(apiUrl(input), init),
+    });
+    expect(uploadedCover.assetObjectId).toMatch(/\S/u);
+    const metadata = {
+      summary: '由 AGC 发布函数真实提交',
+      description:
+        '集成验证：AGC 发布函数 → 本地 api-server → SpacetimeDB / 私有 OSS',
+      category: '益智' as const,
+      tags: ['集成验证'],
+      deviceSupport: { desktop: true, mobile: false, touch: false },
+      inputModes: ['keyboard', 'mouse'] as const,
+      orientation: 'landscape' as const,
+      coverAssetId: uploadedCover.assetObjectId,
+      screenshots: [] as string[],
+    };
+
+    const first = await publishLocalProjectGame({
+      invoke,
+      projectPath: '/data/dsk/Genarrative/tmp-agc-live-project',
+      packageRelativePath: 'dist/game.zip',
+      manifest,
+      metadata: { ...metadata, inputModes: [...metadata.inputModes] },
+    });
+    expect(first.status).toBe('pending_review');
+    expect(first.versionNumber).toBe(1);
+    expect(first.packageSha256).toBe(payload.packageSha256);
+
+    const readResult = await unwrap<{
+      version: { versionId: string; status: string; recoveryAction: string };
+      game: { id: string };
+    }>(
+      await realFetch(
+        apiUrl(`/api/game-distribution/versions/${first.versionId}`),
+        { headers: { Authorization: `Bearer ${token}`, ...ENVELOPE_HEADERS } },
+      ),
+    );
+    expect(readResult.version.status).toBe('pending_review');
+    expect(readResult.version.recoveryAction).toBe('wait');
+    expect(readResult.game.id).toBe(first.gameId);
+
+    // 第二次发布不带旧幂等键：同 localProjectId 必须复用同一 gameId 并新增版本。
+    const second = await publishLocalProjectGame({
+      invoke,
+      projectPath: '/data/dsk/Genarrative/tmp-agc-live-project',
+      packageRelativePath: 'dist/game.zip',
+      manifest,
+      metadata: { ...metadata, inputModes: [...metadata.inputModes] },
+    });
+    expect(second.gameId).toBe(first.gameId);
+    expect(second.versionNumber).toBe(first.versionNumber + 1);
+
+    const myGames = await unwrap<{
+      games: Array<{
+        id: string;
+        latestVersion: { versionId: string; status: string } | null;
+      }>;
+    }>(
+      await realFetch(apiUrl('/api/game-distribution/my-games'), {
+        headers: { Authorization: `Bearer ${token}`, ...ENVELOPE_HEADERS },
+      }),
+    );
+    const published = myGames.games.find((game) => game.id === first.gameId);
+    expect(published?.latestVersion?.versionId).toBe(second.versionId);
+    expect(published?.latestVersion?.status).toBe('pending_review');
+  },
+  120_000,
+);
+
+function setStoredAccessToken(token: string) {
+  setStoredAuthAccessToken(token);
+}
diff --git a/apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx b/apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx
new file mode 100644
index 000000000..3fc008027
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx
@@ -0,0 +1,323 @@
+// @vitest-environment jsdom
+/**
+ * AGC「发布到游戏广场」面板的行为边界。
+ *
+ * 这里只覆盖面板自身（预填资料、必填门禁、防重复点击、成功/失败态与无 Tauri 宿主），
+ * 真实的 HTTP 链路由 `gameDistributionPublishLive.test.ts` 覆盖。
+ */
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import type { LocalProjectExportPackageResult } from '../src/app/types';
+import { GameDistributionPublishPanel } from '../src/components/game-distribution/GameDistributionPublishPanel';
+import { uploadPlatformMediaAsset } from '../src/services/assetDirectUpload';
+import { publishLocalProjectGame } from '../src/services/gameDistributionPublish';
+
+vi.mock('../src/services/gameDistributionPublish', async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import('../src/services/gameDistributionPublish')
+    >();
+  return { ...actual, publishLocalProjectGame: vi.fn() };
+});
+
+// 面板只负责选图与调用上传；这里替换掉真实直传，避免测试触达 Tauri/OSS。
+vi.mock('../src/services/assetDirectUpload', () => ({
+  uploadPlatformMediaAsset: vi.fn(),
+}));
+
+type TauriInvoke = (
+  command: string,
+  args?: Record<string, unknown>,
+) => Promise<unknown>;
+
+function installTauriInvoke(invoke: TauriInvoke) {
+  const mock = vi.fn(invoke);
+  (
+    window as unknown as {
+      __TAURI__?: { core?: { invoke?: typeof mock } };
+    }
+  ).__TAURI__ = { core: { invoke: mock } };
+  return mock;
+}
+
+const MANIFEST = {
+  projectId: 'local-proj-1',
+  name: '星轨防线',
+  goal: '守住轨道城',
+} as unknown as GameCreationAppManifest;
+
+const PACKAGE_RESULT = {
+  packageRelativePath: 'exports/playtest-package-unit.zip',
+  packageBytes: [1, 2, 3],
+  packageSha256: 'a'.repeat(64),
+  packageSizeBytes: 3,
+  fileCount: 2,
+  totalBytes: 3,
+} as unknown as LocalProjectExportPackageResult;
+
+function buildImageFile(name: string) {
+  return new File(['cover-bytes'], name, { type: 'image/png' });
+}
+
+/** 选择封面并等待上传完成；面板只有在素材拿到 ID 之后才允许发布。 */
+async function selectCover(
+  file: File = buildImageFile('cover.png'),
+  assetObjectId = 'asset_cover',
+) {
+  vi.mocked(uploadPlatformMediaAsset).mockResolvedValueOnce({
+    assetObjectId,
+    objectKey: `game-distribution/cover/${file.name}`,
+  });
+  fireEvent.change(screen.getByLabelText(/游戏封面/u), {
+    target: { files: [file] },
+  });
+  await screen.findByText(new RegExp(`已选择「${file.name}」`, 'u'));
+}
+
+function renderPanel(
+  overrides: Partial<Parameters<typeof GameDistributionPublishPanel>[0]> = {},
+) {
+  const onClose = vi.fn();
+  const onPublished = vi.fn();
+  render(
+    <GameDistributionPublishPanel
+      open
+      projectPath="/tmp/authorized-game"
+      manifest={MANIFEST}
+      packageResult={PACKAGE_RESULT}
+      onClose={onClose}
+      onPublished={onPublished}
+      {...overrides}
+    />,
+  );
+  return { onClose, onPublished };
+}
+
+afterEach(() => {
+  cleanup();
+  vi.mocked(publishLocalProjectGame).mockReset();
+  vi.mocked(uploadPlatformMediaAsset).mockReset();
+  delete (window as unknown as { __TAURI__?: unknown }).__TAURI__;
+  window.localStorage.clear();
+});
+
+describe('GameDistributionPublishPanel', () => {
+  test('打开时预填游戏资料并展示发行包摘要', () => {
+    installTauriInvoke(async () => undefined);
+    renderPanel();
+
+    expect(screen.getByLabelText('游戏名称')).toHaveProperty(
+      'value',
+      '星轨防线',
+    );
+    expect(screen.getByLabelText('一句话简介')).toHaveProperty(
+      'value',
+      '守住轨道城',
+    );
+    expect(screen.getByLabelText('发行包摘要').textContent).toContain(
+      'exports/playtest-package-unit.zip',
+    );
+    expect(screen.getByLabelText('发行包摘要').textContent).toContain(
+      '2 个文件',
+    );
+  });
+
+  test('提交时带上项目路径、发行包与资料，成功后展示审核状态', async () => {
+    const invoke = installTauriInvoke(async () => undefined);
+    vi.mocked(publishLocalProjectGame).mockResolvedValue({
+      gameId: 'game_1',
+      versionId: 'gamever_1',
+      versionNumber: 1,
+      status: 'pending_review',
+      packageSha256: 'a'.repeat(64),
+      packageSizeBytes: 3,
+      fileCount: 2,
+    });
+    const { onPublished } = renderPanel();
+
+    fireEvent.change(screen.getByLabelText('游戏名称'), {
+      target: { value: '星轨防线二' },
+    });
+    fireEvent.change(screen.getByLabelText('分类'), {
+      target: { value: '动作' },
+    });
+    await selectCover();
+    vi.mocked(uploadPlatformMediaAsset).mockResolvedValueOnce({
+      assetObjectId: 'asset_shot_1',
+      objectKey: 'game-distribution/screenshot/shot-1.png',
+    });
+    fireEvent.change(screen.getByLabelText(/游戏截图/u), {
+      target: { files: [buildImageFile('shot-1.png')] },
+    });
+    await screen.findByText('移除截图 1');
+    fireEvent.click(screen.getByRole('button', { name: '发布游戏' }));
+
+    await waitFor(() =>
+      expect(publishLocalProjectGame).toHaveBeenCalledTimes(1),
+    );
+    const args = vi.mocked(publishLocalProjectGame).mock.calls[0]?.[0];
+    expect(args?.invoke).toBeDefined();
+    expect(args?.projectPath).toBe('/tmp/authorized-game');
+    expect(args?.packageRelativePath).toBe('exports/playtest-package-unit.zip');
+    expect(args?.manifest).toBe(MANIFEST);
+    expect(args?.metadata).toEqual({
+      title: '星轨防线二',
+      summary: '守住轨道城',
+      category: '动作',
+      coverAssetId: 'asset_cover',
+      screenshots: ['asset_shot_1'],
+    });
+    expect(String(args?.idempotencyKey)).toMatch(/^agc-publish-/u);
+    expect(invoke).toBeDefined();
+
+    expect(await screen.findByText('已提交审核')).not.toBeNull();
+    expect(screen.getByText(/版本 1/u)).not.toBeNull();
+    expect(onPublished).toHaveBeenCalledTimes(1);
+  });
+
+  test('连续点击只提交一次，上传中禁用动作按钮', async () => {
+    installTauriInvoke(async () => undefined);
+    let resolvePublish: (value: unknown) => void = () => undefined;
+    vi.mocked(publishLocalProjectGame).mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolvePublish = resolve as (value: unknown) => void;
+        }) as never,
+    );
+    renderPanel();
+    await selectCover();
+
+    const submit = screen.getByRole('button', { name: '发布游戏' });
+    fireEvent.click(submit);
+    fireEvent.click(submit);
+
+    expect(await screen.findByText('上传中…')).not.toBeNull();
+    expect(publishLocalProjectGame).toHaveBeenCalledTimes(1);
+
+    resolvePublish({
+      gameId: 'game_1',
+      versionId: 'gamever_1',
+      versionNumber: 1,
+      status: 'pending_review',
+      packageSha256: 'a'.repeat(64),
+      packageSizeBytes: 3,
+      fileCount: 2,
+    });
+    expect(await screen.findByText('已提交审核')).not.toBeNull();
+  });
+
+  test('服务端失败时保留面板并展示可读错误', async () => {
+    installTauriInvoke(async () => undefined);
+    vi.mocked(publishLocalProjectGame).mockRejectedValue(
+      new Error('上传游戏发行包失败：游戏分发服务暂不可用（503）'),
+    );
+    renderPanel();
+    await selectCover();
+
+    fireEvent.click(screen.getByRole('button', { name: '发布游戏' }));
+
+    expect(
+      await screen.findByText(
+        '上传游戏发行包失败：游戏分发服务暂不可用（503）',
+      ),
+    ).not.toBeNull();
+    expect(screen.queryByText('已提交审核')).toBeNull();
+  });
+
+  test('没有选择封面时不发起发布并给出可操作提示', async () => {
+    installTauriInvoke(async () => undefined);
+    renderPanel();
+
+    fireEvent.click(screen.getByRole('button', { name: '发布游戏' }));
+
+    expect(
+      await screen.findByText('请先选择游戏封面（JPG/PNG/WebP）'),
+    ).not.toBeNull();
+    expect(publishLocalProjectGame).not.toHaveBeenCalled();
+  });
+
+  test('封面与截图都先上传成平台素材，重复提交复用同一素材 ID', async () => {
+    installTauriInvoke(async () => undefined);
+    vi.mocked(publishLocalProjectGame).mockRejectedValue(new Error('先失败'));
+    const coverFile = buildImageFile('cover.png');
+    renderPanel();
+    await selectCover(coverFile, 'asset_cover_cached');
+
+    expect(vi.mocked(uploadPlatformMediaAsset).mock.calls[0]?.[0]).toEqual(
+      expect.objectContaining({
+        assetKind: 'game_distribution_cover',
+        entityId: 'game-distribution-cover',
+      }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '发布游戏' }));
+    await waitFor(() =>
+      expect(publishLocalProjectGame).toHaveBeenCalledTimes(1),
+    );
+
+    // 再次选择同一个文件对象不应重新上传（面板按文件签名复用素材 ID）。
+    fireEvent.change(screen.getByLabelText(/游戏封面/u), {
+      target: { files: [coverFile] },
+    });
+    await screen.findByText(/已选择「cover.png」/u);
+    expect(uploadPlatformMediaAsset).toHaveBeenCalledTimes(1);
+  });
+
+  test('截图超过 6 张时本地拦截且不上传', async () => {
+    installTauriInvoke(async () => undefined);
+    renderPanel();
+
+    fireEvent.change(screen.getByLabelText(/游戏截图/u), {
+      target: {
+        files: Array.from({ length: 7 }, (_, index) =>
+          buildImageFile(`shot-${index}.png`),
+        ),
+      },
+    });
+
+    expect(await screen.findByText(/游戏截图最多 6 张/u)).not.toBeNull();
+    expect(uploadPlatformMediaAsset).not.toHaveBeenCalled();
+  });
+
+  test('素材上传失败时保留面板并展示原因', async () => {
+    installTauriInvoke(async () => undefined);
+    vi.mocked(uploadPlatformMediaAsset).mockRejectedValueOnce(
+      new Error('创建素材上传凭证失败'),
+    );
+    renderPanel();
+
+    fireEvent.change(screen.getByLabelText(/游戏封面/u), {
+      target: { files: [buildImageFile('cover.png')] },
+    });
+
+    expect(await screen.findByText('创建素材上传凭证失败')).not.toBeNull();
+    expect(screen.getByText('还没有封面')).not.toBeNull();
+    expect(publishLocalProjectGame).not.toHaveBeenCalled();
+  });
+
+  test('不在 Tauri 宿主或缺少试玩包时失败关闭且不调用发布接口', async () => {
+    renderPanel();
+    fireEvent.click(screen.getByRole('button', { name: '发布游戏' }));
+    expect(await screen.findByText('需要在 Tauri App 内发布')).not.toBeNull();
+    expect(publishLocalProjectGame).not.toHaveBeenCalled();
+
+    cleanup();
+    installTauriInvoke(async () => undefined);
+    renderPanel({ packageResult: null });
+    expect(screen.getByRole('button', { name: '发布游戏' })).toHaveProperty(
+      'disabled',
+      true,
+    );
+    expect(screen.getByLabelText('发行包摘要').textContent).toContain(
+      '未找到试玩包',
+    );
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/gameRunToolbarActionsStyle.test.ts b/apps/ai-game-creator-shell/tests/gameRunToolbarActionsStyle.test.ts
new file mode 100644
index 000000000..85cdf0265
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameRunToolbarActionsStyle.test.ts
@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, test } from 'vitest';
+
+import { repoPath } from './repoPath';
+import {
+  declaration,
+  parseStyleSheet,
+  resolveDeclarations,
+} from './styleCascade';
+
+/**
+ * 运行页顶栏动作区的声明级断言。
+ *
+ * jsdom 不加载全局样式表，所以这里按仓库既有做法（`styleCascade`）解析真实生效的声明：
+ * 「版本入口与「在浏览器打开」跟其他动作按钮同一套皮」只由样式决定，用例必须钉在声明上，
+ * 否则下一次改动给版本入口单开一套 border / background / hover 时没有任何东西会红。
+ */
+const GLOBAL_CSS_PATH = repoPath('apps/ai-game-creator-shell/src/styles.css');
+const rules = parseStyleSheet(readFileSync(GLOBAL_CSS_PATH, 'utf8'));
+// 同一个求值器限制：全局表里也有 `prefers-reduced-motion` 档，求值时先排除掉。
+const widthRules = rules.filter(
+  (rule) => !(rule.media ?? '').includes('prefers-reduced-motion'),
+);
+
+function resolved(selectors: readonly string[]): Map<string, string> {
+  return resolveDeclarations(widthRules, selectors, 1280);
+}
+
+function hasRule(selector: string): boolean {
+  return widthRules.some((rule) => rule.selectors.includes(selector));
+}
+
+describe('运行页顶栏动作区样式', () => {
+  test('运行画面回到两行，页面里不再有预览地址状态行', () => {
+    const surface = resolved(['.game-run-surface']);
+    expect(declaration(surface, 'grid-template-rows')).toBe(
+      'minmax(300px, 1fr) auto',
+    );
+    // 状态行与那行小字整体退役：地址不再以文字常驻在页面上。
+    expect(hasRule('.game-run-status-bar')).toBe(false);
+    expect(hasRule('.game-run-status-hint')).toBe(false);
+  });
+
+  test('版本入口住进顶栏动作区，皮由那一组的基础规则给', () => {
+    // 动作区的按钮共用一套基础外观（这一组是「在浏览器打开」与版本入口的共同来源）。
+    const actionsButton = resolved(['.game-workbench-view-actions button']);
+    expect(declaration(actionsButton, 'min-height')).toBe('30px');
+    expect(declaration(actionsButton, 'border-radius')).toBe('999px');
+    expect(declaration(actionsButton, 'font-size')).toBe('12px');
+    expect(declaration(actionsButton, 'font-weight')).toBe('700');
+
+    // 版本入口只补「版本名可能很长」这一件事，不再自带边框 / 底色 / 文字色 / hover。
+    const trigger = resolved(['.game-run-version-trigger']);
+    expect(trigger.has('border')).toBe(false);
+    expect(trigger.has('background')).toBe(false);
+    expect(trigger.has('color')).toBe(false);
+    expect(declaration(trigger, 'min-width')).toBe('0');
+    // 省略号要真的生效：按钮是 flex 容器，文本必须挂在自带 overflow 的 span 上。
+    const label = resolved(['.game-run-version-trigger-label']);
+    expect(declaration(label, 'overflow')).toBe('hidden');
+    expect(declaration(label, 'text-overflow')).toBe('ellipsis');
+    expect(declaration(label, 'white-space')).toBe('nowrap');
+    expect(hasRule('.game-run-version-trigger:hover')).toBe(false);
+    expect(hasRule('.game-run-version-trigger:focus-visible')).toBe(false);
+
+    // 版本入口不再绝对定位压在游戏画面上。
+    const picker = resolved(['.game-run-version-picker']);
+    expect(picker.has('position')).toBe(false);
+    expect(picker.has('top')).toBe(false);
+    expect(picker.has('right')).toBe(false);
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/previewActivation.test.tsx b/apps/ai-game-creator-shell/tests/previewActivation.test.tsx
index c349dea8b..68a7af95a 100644
--- a/apps/ai-game-creator-shell/tests/previewActivation.test.tsx
+++ b/apps/ai-game-creator-shell/tests/previewActivation.test.tsx
@@ -12,6 +12,10 @@
  * 只核对内存 registry 并回传 loopback 地址，活着就复用（不重启预览服务），没活着
  * （stopped / 不属于这个项目 / 权限位要求确认）才回落到 `start_local_game_preview`。
  *
+ * 成功反馈走工作台壳的 toast（`onRunNotice`），**不再**写进对话区：那条「已载入客户端
+ * 运行视图：URL」以前常驻对话底部挡住运行画面。用例因此直接断言这条通道，并反过来钉住
+ * 对话容器里没有这类提示。
+ *
  * 这条行为过去只剩 `scripts/check-native-shells.mjs` 的源码守卫与 Rust 实现，前端没有
  * 用例；一旦有人再把它当死链路删掉，守卫会先报「missing await invoke」而不知道现场。
  */
@@ -41,7 +45,10 @@ function createFixtureManifest(): GameCreationAppManifest {
  * `activate_local_game_preview` 的替身由用例给定：它决定「这条预览还活着吗」，
  * 其余命令沿用聊天 harness，运行入口之外的链路保持真实形状。
  */
-function installTauri(activateLocalGamePreview: () => unknown) {
+function installTauri(
+  activateLocalGamePreview: () => unknown,
+  options: { startFails?: string } = {},
+) {
   const manifest = createFixtureManifest();
   const chatHarness = createProjectChatRuntimeHarness({
     projectPath: PROJECT_PATH,
@@ -60,6 +67,9 @@ function installTauri(activateLocalGamePreview: () => unknown) {
         return activateLocalGamePreview();
       }
       if (command === 'start_local_game_preview') {
+        if (options.startFails) {
+          throw new Error(options.startFails);
+        }
         return { url: PREVIEW_URL, port: 43210, root: PROJECT_PATH };
       }
       return chatHarness.invoke(command, args);
@@ -74,20 +84,28 @@ function installTauri(activateLocalGamePreview: () => unknown) {
 
 /** 「运行」入口由工作台壳的播放请求驱动，这里直接用同一形状的请求触发。 */
 function renderRunningProjectChat() {
-  return render(
+  const onRunNotice = vi.fn();
+  render(
     <App
       initialProjectPath={PROJECT_PATH}
       initialProjectManifest={createFixtureManifest()}
       onPlayRequestHandled={vi.fn()}
+      onRunNotice={onRunNotice}
       playRequest={{ projectPath: PROJECT_PATH, requestId: 1 }}
     />,
   );
+  return { onRunNotice };
 }
 
-/** 运行结果由聊天自己的本地消息流展示，这里按对话容器文本断言。 */
-async function expectChatAnnouncement(text: string) {
+/** 运行反馈走 toast；对话容器里不该再出现这类过程提示。 */
+async function expectRunNoticeWithoutChatTip(
+  onRunNotice: ReturnType<typeof vi.fn>,
+  message: string,
+) {
+  await waitFor(() => expect(onRunNotice).toHaveBeenCalledWith({ message }));
   const surface = await screen.findByLabelText('陶泥儿项目对话');
-  await waitFor(() => expect(surface.textContent ?? '').toContain(text));
+  expect(surface.textContent ?? '').not.toContain('运行通过');
+  expect(surface.textContent ?? '').not.toContain('已切换到客户端运行视图');
 }
 
 beforeEach(() => {
@@ -103,14 +121,14 @@ describe('运行入口切到已经在跑的客户端预览', () => {
       root: PROJECT_PATH,
     }));
 
-    renderRunningProjectChat();
+    const { onRunNotice } = renderRunningProjectChat();
 
     await waitFor(() =>
       expect(invoke).toHaveBeenCalledWith('activate_local_game_preview', {
         projectPath: PROJECT_PATH,
       }),
     );
-    await expectChatAnnouncement(`已切换到客户端运行视图：${PREVIEW_URL}`);
+    await expectRunNoticeWithoutChatTip(onRunNotice, '已载入客户端运行视图');
     expect(invokeCounts.get('start_local_game_preview') ?? 0).toBe(0);
   });
 
@@ -122,15 +140,16 @@ describe('运行入口切到已经在跑的客户端预览', () => {
       root: null,
     }));
 
-    renderRunningProjectChat();
+    const { onRunNotice } = renderRunningProjectChat();
 
     await waitFor(() =>
       expect(invokeCounts.get('start_local_game_preview') ?? 0).toBeGreaterThan(
         0,
       ),
     );
-    await expectChatAnnouncement(
-      `运行通过，已载入客户端运行视图：${PREVIEW_URL}`,
+    await expectRunNoticeWithoutChatTip(
+      onRunNotice,
+      '运行通过，已载入客户端运行视图',
     );
   });
 
@@ -139,15 +158,34 @@ describe('运行入口切到已经在跑的客户端预览', () => {
       throw new Error('需要先确认预览权限');
     });
 
-    renderRunningProjectChat();
+    const { onRunNotice } = renderRunningProjectChat();
 
     await waitFor(() =>
       expect(invokeCounts.get('start_local_game_preview') ?? 0).toBeGreaterThan(
         0,
       ),
     );
-    await expectChatAnnouncement(
-      `运行通过，已载入客户端运行视图：${PREVIEW_URL}`,
+    await expectRunNoticeWithoutChatTip(
+      onRunNotice,
+      '运行通过，已载入客户端运行视图',
     );
   });
+
+  it('启动预览失败时走失败色提示，不再写进对话区', async () => {
+    installTauri(
+      () => ({ status: 'stopped', url: null, port: null, root: null }),
+      { startFails: '预览端口被占用' },
+    );
+
+    const { onRunNotice } = renderRunningProjectChat();
+
+    await waitFor(() =>
+      expect(onRunNotice).toHaveBeenCalledWith({
+        tone: 'error',
+        message: '运行游戏失败：预览端口被占用',
+      }),
+    );
+    const surface = await screen.findByLabelText('陶泥儿项目对话');
+    expect(surface.textContent ?? '').not.toContain('预览端口被占用');
+  });
 });
diff --git a/apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx b/apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx
index a5adb973d..946a60c71 100644
--- a/apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx
+++ b/apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx
@@ -1135,13 +1135,14 @@ describe('project resource live canvas integration', () => {
     fireEvent.click(within(panel).getByRole('button', { name: '修改' }));
     await waitFor(() => expect(deriveCalls).toHaveLength(1));
 
-    // 出站负载：派生请求里的提示词就是聊天 `@` 拼出来的那一串（`@显示名`），
-    // 期望值直接由共享引用模型算，钉住"快速编辑没有第二种引用格式"。
+    // 出站负载：派生请求里的提示词就是聊天 `@` 拼出来的那一串（`@显示名`，
+    // token 前后各留一个空白），期望值直接由共享引用模型算，
+    // 钉住"快速编辑没有第二种引用格式"。
     const mentionedAsset = canvasFixture.manifest?.assets.find(
       (entry) => entry.id === 'source-rules',
     );
     if (!mentionedAsset) throw new Error('missing source-rules fixture');
-    const expectedText = `把夜色改成星空@${
+    const expectedText = `把夜色改成星空 @${
       resourceReferenceFromAsset(mentionedAsset, 'asset-picker').label
     }`;
     expect(deriveCalls[0]?.prompt).toBe(expectedText);
diff --git a/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
new file mode 100644
index 000000000..d7e6bf23c
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
@@ -0,0 +1,474 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  GameCreationAppAssetKind,
+  GameCreationAppAssetManifestEntry,
+} from '../../../packages/shared/src/contracts/gameCreationApp';
+import { attachmentReferenceProvider } from '../src/features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../src/features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../src/features/project-workspace/reference-source/runtimeRegionReferenceProvider';
+import { useSkillReferenceProvider } from '../src/features/project-workspace/reference-source/skillReferenceProvider';
+import {
+  type AttachmentReference,
+  type ChatReference,
+  chatReferenceKey,
+  chatReferenceMentionToken,
+  type ResourceReference,
+  type RuntimeRegionReference,
+} from '../src/features/project-workspace/resourceReferences';
+import type { DirectCodexUserContentPart } from '../src/view/project-development/chat/generated/DirectCodexUserContentPart';
+
+function asset(
+  id: string,
+  kind: GameCreationAppAssetKind,
+  mediaType: string,
+  localPath: string,
+): GameCreationAppAssetManifestEntry {
+  return {
+    id,
+    kind,
+    mediaType,
+    localPath,
+    source: { kind: 'uploaded' },
+  };
+}
+
+const heroAsset = asset(
+  'asset-hero',
+  'character',
+  'image/png',
+  'assets/hero-idle.png',
+);
+
+const runtimeRegionPart: DirectCodexUserContentPart = {
+  type: 'agc_runtime_region_reference',
+  label: '主画面',
+  runId: 'run-1',
+  versionId: 'version-1',
+  elementTag: 'canvas',
+  elementRole: 'playfield',
+  text: '可试玩区域',
+  width: 320,
+  height: 180,
+  resourceIds: ['asset-hero'],
+};
+
+const attachmentPart: DirectCodexUserContentPart = {
+  type: 'agc_attachment_reference',
+  name: 'brief.md',
+  mediaType: 'text/markdown',
+  size: 128,
+  localPath: 'notes/brief.md',
+  status: 'imported',
+};
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  window.__TAURI__ = undefined;
+});
+
+describe('资源引用 provider', () => {
+  const provider = createResourceReferenceProvider({ assets: [heroAsset] });
+
+  it('触发符是 `@`，且清单为空时先不自称就绪', () => {
+    expect(provider.trigger).toBe('@');
+    expect(createResourceReferenceProvider({ assets: [] }).isReady?.()).toBe(
+      false,
+    );
+    // 清单到位后才允许把草稿落进编辑器，否则引用会被当成已删除丢掉。
+    expect(provider.isReady?.()).toBe(true);
+  });
+
+  it('候选只含可提及素材，`match` 按显示名 / id / kind 过滤并截断到 8 条', () => {
+    const assets = [
+      heroAsset,
+      asset('asset-icon', 'icon', 'image/png', 'assets/btn.png'),
+      // 没有 localPath 与 `.agent/` 下的产物都不是可提及素材。
+      asset('asset-orphan', 'image', 'image/png', ''),
+      asset('asset-agent', 'document', 'text/markdown', '.agent/notes.md'),
+    ];
+    const scoped = createResourceReferenceProvider({ assets });
+    expect(scoped.match?.('')).toHaveLength(2);
+
+    const many = Array.from({ length: 10 }, (_, index) =>
+      asset(`asset-${index}`, 'image', 'image/png', `assets/pic-${index}.png`),
+    );
+    const limited = createResourceReferenceProvider({ assets: many });
+    expect(limited.match?.('')).toHaveLength(8);
+
+    expect(provider.match?.('hero')?.map((item) => item.type)).toEqual([
+      'resource',
+    ]);
+    expect(provider.match?.('HERO-IDLE')).toHaveLength(1);
+    expect(provider.match?.('character')).toHaveLength(1);
+    expect(provider.match?.('  hero  ')).toHaveLength(1);
+    expect(provider.match?.('missing')).toEqual([]);
+  });
+
+  it('同名不同目录的素材是两条候选：显示名相同，但身份键不同', () => {
+    const sameName = createResourceReferenceProvider({
+      assets: [
+        asset('asset-hero-a', 'character', 'image/png', 'characters/hero.png'),
+        asset('asset-hero-b', 'character', 'image/png', 'enemies/hero.png'),
+      ],
+    });
+
+    const candidates = sameName.match?.('') ?? [];
+    // 显示 token 会撞（都是 `@hero`），所以候选菜单的 key 不能拿 token 当身份。
+    expect(candidates.map((item) => chatReferenceMentionToken(item))).toEqual([
+      '@hero',
+      '@hero',
+    ]);
+    expect(new Set(candidates.map((item) => chatReferenceKey(item))).size).toBe(
+      2,
+    );
+  });
+
+  it('`toReference` 只认资源 part：资产已删除时不合成引用', () => {
+    expect(provider.toReference({ type: 'input_text', text: '看素材' })).toBe(
+      null,
+    );
+    expect(provider.toReference(attachmentPart)).toBe(null);
+    expect(
+      provider.toReference({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-hero',
+      }),
+    ).toMatchObject({ type: 'resource', label: 'hero-idle' });
+    expect(
+      provider.toReference({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-gone',
+      }),
+    ).toBe(null);
+  });
+
+  it('`refresh` 按 manifest 换显示名：改名换新引用、未变恒等、已删除原样返回', () => {
+    const reference = provider.match?.('hero')?.[0] as ResourceReference;
+    expect(provider.refresh(reference)).toBe(reference);
+
+    const renamed = createResourceReferenceProvider({
+      assets: [
+        asset('asset-hero', 'character', 'image/png', 'assets/hero-v2.png'),
+      ],
+    });
+    const refreshed = renamed.refresh(reference);
+    expect(refreshed?.type === 'resource' ? refreshed.label : null).toBe(
+      'hero-v2',
+    );
+
+    const deleted = createResourceReferenceProvider({
+      assets: [asset('asset-other', 'icon', 'image/png', 'assets/btn.png')],
+    });
+    expect(deleted.refresh(reference)).toBe(reference);
+
+    const skill: ChatReference = { type: 'skill', name: 'agc-test-skill' };
+    expect(provider.refresh(skill)).toBe(null);
+  });
+
+  it('`mentionToken` 展开为 `@显示名`，清单缺失时退回引用 id', () => {
+    expect(
+      provider.mentionToken({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-hero',
+      }),
+    ).toBe('@hero-idle');
+    expect(
+      provider.mentionToken({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-gone',
+      }),
+    ).toBe('@asset-gone');
+    expect(provider.mentionToken({ type: 'input_text', text: '看' })).toBe(
+      null,
+    );
+  });
+});
+
+describe('附件 provider', () => {
+  it('静默：没有触发符也没有候选，注入它不会加出任何入口', () => {
+    expect(attachmentReferenceProvider.trigger).toBe(null);
+    expect(attachmentReferenceProvider.match).toBeUndefined();
+  });
+
+  it('`toReference` 逐字搬运附件字段，并只认附件 part', () => {
+    expect(attachmentReferenceProvider.toReference(attachmentPart)).toEqual({
+      type: 'attachment',
+      name: 'brief.md',
+      mediaType: 'text/markdown',
+      size: 128,
+      localPath: 'notes/brief.md',
+      status: 'imported',
+    });
+    expect(
+      attachmentReferenceProvider.toReference({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-hero',
+      }),
+    ).toBe(null);
+    expect(
+      attachmentReferenceProvider.toReference({ type: 'input_text', text: '' }),
+    ).toBe(null);
+  });
+
+  it('`refresh` 对附件恒等，`mentionToken` 是 `@附件名`', () => {
+    const reference = attachmentReferenceProvider.toReference(
+      attachmentPart,
+    ) as AttachmentReference;
+    expect(attachmentReferenceProvider.refresh(reference)).toBe(reference);
+    expect(
+      attachmentReferenceProvider.refresh({ type: 'skill', name: 'x' }),
+    ).toBe(null);
+    expect(attachmentReferenceProvider.mentionToken(attachmentPart)).toBe(
+      '@brief.md',
+    );
+    expect(
+      attachmentReferenceProvider.mentionToken({
+        type: 'input_text',
+        text: '',
+      }),
+    ).toBe(null);
+  });
+});
+
+describe('运行画面区域 provider', () => {
+  it('静默且只认运行画面区域 part，可选字段缺失时收成 undefined', () => {
+    expect(runtimeRegionReferenceProvider.trigger).toBe(null);
+    expect(runtimeRegionReferenceProvider.match).toBeUndefined();
+    expect(
+      runtimeRegionReferenceProvider.toReference(runtimeRegionPart),
+    ).toEqual({
+      type: 'runtime-region',
+      label: '主画面',
+      runId: 'run-1',
+      versionId: 'version-1',
+      elementTag: 'canvas',
+      elementRole: 'playfield',
+      text: '可试玩区域',
+      width: 320,
+      height: 180,
+      resourceIds: ['asset-hero'],
+      source: 'runtime-picker',
+    });
+    expect(
+      runtimeRegionReferenceProvider.toReference({
+        type: 'agc_runtime_region_reference',
+        label: '主画面',
+        runId: null,
+        versionId: null,
+        elementTag: null,
+        elementRole: null,
+        text: null,
+        width: null,
+        height: null,
+        resourceIds: [],
+      }),
+    ).toEqual({
+      type: 'runtime-region',
+      label: '主画面',
+      runId: undefined,
+      versionId: undefined,
+      elementTag: undefined,
+      elementRole: undefined,
+      text: undefined,
+      width: undefined,
+      height: undefined,
+      resourceIds: [],
+      source: 'runtime-picker',
+    });
+    expect(attachmentReferenceProvider.toReference(runtimeRegionPart)).toBe(
+      null,
+    );
+  });
+
+  it('`refresh` 对运行区域恒等，`mentionToken` 是 `@标签`', () => {
+    const reference = runtimeRegionReferenceProvider.toReference(
+      runtimeRegionPart,
+    ) as RuntimeRegionReference;
+    expect(runtimeRegionReferenceProvider.refresh(reference)).toBe(reference);
+    expect(
+      runtimeRegionReferenceProvider.refresh({ type: 'skill', name: 'x' }),
+    ).toBe(null);
+    expect(runtimeRegionReferenceProvider.mentionToken(runtimeRegionPart)).toBe(
+      '@主画面',
+    );
+    expect(
+      runtimeRegionReferenceProvider.mentionToken({
+        type: 'input_text',
+        text: '@主画面',
+      }),
+    ).toBe(null);
+  });
+});
+
+describe('Skill provider', () => {
+  it('触发符是 `$`：挂载与 `match` 都不发查询，菜单第一次打开时才读应用级目录', async () => {
+    const invoke = vi.fn(async (command: string) => {
+      if (command === 'list_agc_skill_catalog') {
+        return [{ name: 'agc-test-skill', description: '测试 Skill' }];
+      }
+      if (command === 'list_client_extensions') return [];
+      throw new Error(`unexpected invoke ${command}`);
+    });
+    window.__TAURI__ = { core: { invoke: invoke as never } };
+
+    const { result } = renderHook(() => useSkillReferenceProvider());
+    expect(result.current.trigger).toBe('$');
+    expect(invoke).not.toHaveBeenCalled();
+
+    // `match` 是纯函数：输入区在渲染阶段调它，这里不能替 provider 发起任何读取。
+    act(() => {
+      expect(result.current.match?.('')).toEqual([]);
+    });
+    expect(invoke).not.toHaveBeenCalled();
+
+    // 懒加载只由菜单回调触发（菜单打开 → 输入区在 effect 里给非 null 的 query）。
+    act(() => {
+      result.current.onMenuQueryChange?.('');
+    });
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith('list_agc_skill_catalog');
+    });
+    await waitFor(() => {
+      expect(result.current.match?.('')).toHaveLength(1);
+    });
+    // 目录只读一次：后续每次敲 `$` 都复用同一份候选。
+    expect(invoke).toHaveBeenCalledTimes(2);
+    // 菜单关闭（query 为 `null`）不触发读取。
+    act(() => {
+      result.current.onMenuQueryChange?.(null);
+    });
+    expect(invoke).toHaveBeenCalledTimes(2);
+    expect(result.current.match?.('测试')?.[0]).toMatchObject({
+      type: 'skill',
+      name: 'agc-test-skill',
+    });
+  });
+
+  it('内置目录与已启用客户端 Skill 合并后按名字去重，并截断到 8 条', async () => {
+    const invoke = vi.fn(async (command: string) => {
+      if (command === 'list_agc_skill_catalog') {
+        return Array.from({ length: 9 }, (_, index) => ({
+          name: `builtin-${index}`,
+          description: '内置',
+        }));
+      }
+      if (command === 'list_client_extensions') {
+        return [
+          {
+            name: 'builtin-0',
+            extensionType: 'skill',
+            enabled: true,
+            status: 'enabled',
+          },
+          {
+            name: 'client-skill',
+            extensionType: 'skill',
+            enabled: true,
+            status: 'enabled',
+          },
+          // 未启用 / 非 Skill 的扩展不进候选。
+          {
+            name: 'client-off',
+            extensionType: 'skill',
+            enabled: false,
+            status: 'enabled',
+          },
+          {
+            name: 'client-plugin',
+            extensionType: 'plugin',
+            enabled: true,
+            status: 'enabled',
+          },
+        ];
+      }
+      throw new Error(`unexpected invoke ${command}`);
+    });
+    window.__TAURI__ = { core: { invoke: invoke as never } };
+
+    const { result } = renderHook(() => useSkillReferenceProvider());
+    act(() => {
+      result.current.onMenuQueryChange?.('');
+    });
+    await waitFor(() => {
+      expect(result.current.match?.('')).toHaveLength(8);
+    });
+    // 同名客户端项被内置项挡掉，上限只作用于当前查询的命中集合。
+    expect(result.current.match?.('builtin-0')).toHaveLength(1);
+    expect(result.current.match?.('builtin-')).toHaveLength(8);
+    expect(result.current.match?.('client-skill')).toMatchObject([
+      { type: 'skill', name: 'client-skill' },
+    ]);
+    // 未启用与非 Skill 扩展都不是候选。
+    expect(result.current.match?.('client-off')).toEqual([]);
+    expect(result.current.match?.('client-plugin')).toEqual([]);
+  });
+
+  it('一次瞬时失败不锁死候选：下一次 `match` 还会重读目录，并在控制台留痕', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const invoke = vi
+      .fn(async (command: string) => {
+        if (command === 'list_agc_skill_catalog') {
+          return [{ name: 'agc-test-skill' }];
+        }
+        if (command === 'list_client_extensions') return [];
+        throw new Error(`unexpected invoke ${command}`);
+      })
+      .mockRejectedValueOnce(new Error('transient'));
+    window.__TAURI__ = { core: { invoke: invoke as never } };
+
+    const { result } = renderHook(() => useSkillReferenceProvider());
+    act(() => {
+      result.current.onMenuQueryChange?.('');
+    });
+    // 一次触发读两份目录：内置 Skill 与客户端扩展。
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledTimes(2);
+    });
+    act(() => {
+      result.current.onMenuQueryChange?.('a');
+    });
+    await waitFor(() => {
+      expect(result.current.match?.('')).toHaveLength(1);
+    });
+    expect(invoke).toHaveBeenCalledTimes(4);
+    // 读取失败不能静默：控制台要留下可排障的一条。
+    expect(warn).toHaveBeenCalledWith(
+      '[skill-reference] Skill 目录读取失败，下次触发重试',
+      expect.any(Error),
+    );
+  });
+
+  it('`toReference` / `refresh` / `mentionToken` 只认 Skill', async () => {
+    const invoke = vi.fn(async () => []);
+    window.__TAURI__ = { core: { invoke: invoke as never } };
+    const { result } = renderHook(() => useSkillReferenceProvider());
+
+    expect(
+      result.current.toReference({ type: 'agc_skill_reference', name: 'demo' }),
+    ).toEqual({ type: 'skill', name: 'demo' });
+    expect(
+      result.current.toReference({
+        type: 'agc_resource_reference',
+        resourceId: 'asset-hero',
+      }),
+    ).toBe(null);
+    const reference: ChatReference = { type: 'skill', name: 'demo' };
+    expect(result.current.refresh(reference)).toBe(reference);
+    expect(result.current.refresh({ type: 'resource' } as ChatReference)).toBe(
+      null,
+    );
+    expect(
+      result.current.mentionToken({
+        type: 'agc_skill_reference',
+        name: 'demo',
+      }),
+    ).toBe('$demo');
+    expect(
+      result.current.mentionToken({ type: 'input_text', text: '$demo' }),
+    ).toBe(null);
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
index bce33f8e5..22dfdb814 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
@@ -14,6 +14,7 @@ import {
   type ChatReference,
   directCodexContentToPromptText,
   legacyContentDtoToContent,
+  resourceLabelResolver,
   resourceReferenceFromAsset,
 } from '../src/features/project-workspace/resourceReferences';
 import {
@@ -115,7 +116,10 @@ function submittedText(
   input: ResourceCanvasAssetGenerationSubmitInput | undefined,
   assets: readonly GameCreationAppAssetManifestEntry[],
 ): string {
-  return directCodexContentToPromptText(input?.content ?? [], assets);
+  return directCodexContentToPromptText(
+    input?.content ?? [],
+    resourceLabelResolver(assets),
+  );
 }
 
 describe('参考图模型', () => {
@@ -284,7 +288,8 @@ describe('生成面板的参考接线', () => {
     const submitted = onSubmit.mock.calls[0]?.[0];
     expect(submitted?.kind).toBe('image');
     // 提交载荷是那一份 canonical content：正文逐字，引用仍是稳定 resourceId。
-    expect(submittedText(submitted, [imageAsset])).toBe('画一只猫 @素材-a');
+    // token 前后各留一个空白：引用在末尾时读回的正文也带着那个分隔空白。
+    expect(submittedText(submitted, [imageAsset])).toBe('画一只猫 @素材-a ');
     expect(submitted?.content).toContainEqual({
       type: 'agc_resource_reference',
       resourceId: 'asset-a',
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
index c30d6d682..aabf0d912 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
@@ -356,23 +356,12 @@ describe('「生成任务」侧栏', () => {
     expect(onToggleOpen).toHaveBeenCalledTimes(1);
   });
 
-  test('锚点按工作面分档：资源画布 / 运行表现层 / UI 编辑器各挂一档', () => {
-    const { container, rerender } = renderSidebar([], { placement: 'run' });
+  test('锚点按工作面分档：资源画布 / UI 编辑器各挂一档', () => {
+    const { container, rerender } = renderSidebar([], { placement: 'editor' });
     const placementOf = () =>
       container
         .querySelector('.game-resource-generation-tasks-anchor')
         ?.getAttribute('data-generation-tasks-placement');
-    expect(placementOf()).toBe('run');
-
-    rerender(
-      <ResourceCanvasAssetGenerationTasksPanelView
-        tasks={[]}
-        open
-        onToggleOpen={vi.fn()}
-        onFocusTask={vi.fn()}
-        placement="editor"
-      />,
-    );
     expect(placementOf()).toBe('editor');
 
     // 缺省 = 资源栏目画布，老调用方不传这个 prop 也落在画布右上角。
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
index d3aea4611..f4ebcccdd 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
@@ -231,7 +231,7 @@ describe('「生成任务」侧栏样式', () => {
     expect(sidebar.has('left')).toBe(false);
   });
 
-  test('锚点贴在工作面右上角，运行表现层让开版本入口，开关沿用次级胶囊样式', () => {
+  test('锚点贴在工作面右上角，运行表现层不挂这一档，开关沿用次级胶囊样式', () => {
     const anchor = resolved(['.game-resource-generation-tasks-anchor']);
     // 锚点是 stage 网格里与工作面同一个单元格的条目：贴右贴顶由网格给，不再用写死 top 的绝对定位
     //（写死的 top 会被工具条换行顶穿，验收现场那条「生成任务和菜单栏重叠」就是这么来的）。
@@ -244,14 +244,15 @@ describe('「生成任务」侧栏样式', () => {
     // 画布顶边内缩一小段，不压在工具条那一行上。
     expect(declaration(anchor, 'margin')).toBe('0.85rem');
 
-    // 运行表现层右上角被版本入口（`game-run-version-picker`：top 20px / right 20px）占着，
-    // 这一档必须把开关压到那枚版本入口下面（内缩上边距 3.5rem）。
-    const runAnchor = resolved([
-      '.game-resource-generation-tasks-anchor',
-      ".game-resource-generation-tasks-anchor[data-generation-tasks-placement='run']",
-    ]);
-    expect(declaration(runAnchor, 'grid-row')).toBe('2 / -1');
-    expect(declaration(runAnchor, 'margin')).toContain('3.5rem');
+    // 运行表现层不再挂这个锚点（运行页要留给游戏画面，见 `project-development/index.tsx`）：
+    // 「让开右上角版本入口」那一档坐标随之退役，留一条死规则在这里只会误导下一次改动。
+    expect(
+      widthRules.some((rule) =>
+        rule.selectors.includes(
+          ".game-resource-generation-tasks-anchor[data-generation-tasks-placement='run']",
+        ),
+      ),
+    ).toBe(false);
 
     // UI 编辑器那一档与资源画布同档（第二行），不引入第三套坐标。
     const editorAnchor = resolved([
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanel.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanel.test.tsx
index 22af6e739..f2d1b33e3 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanel.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanel.test.tsx
@@ -10,7 +10,10 @@ import userEvent from '@testing-library/user-event';
 import { afterEach, describe, expect, test, vi } from 'vitest';
 
 import type { GameCreationAppAssetManifestEntry } from '../../../packages/shared/src/contracts/gameCreationApp';
-import { directCodexContentToPromptText } from '../src/features/project-workspace/resourceReferences';
+import {
+  directCodexContentToPromptText,
+  resourceLabelResolver,
+} from '../src/features/project-workspace/resourceReferences';
 import { ResourceCanvasAssetGenerationPanelView } from '../src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView';
 import type { ResourceCanvasAssetToolAction } from '../src/features/resource-canvas/resourceCanvasBottomToolbarModel';
 import type { DirectCodexUserContentPart } from '../src/view/project-development/chat/generated/DirectCodexUserContentPart';
@@ -106,9 +109,12 @@ describe('生成浮层里的引用选择（真实组件，不做 props mock）',
       content: DirectCodexUserContentPart[];
     };
     // 提交载荷只有一份 canonical content：正文逐字，引用仍是稳定 resourceId。
-    expect(directCodexContentToPromptText(submitted.content, assets)).toContain(
-      '画一只猫',
-    );
+    expect(
+      directCodexContentToPromptText(
+        submitted.content,
+        resourceLabelResolver(assets),
+      ),
+    ).toContain('画一只猫');
     expect(
       submitted.content.some(
         (part) =>
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
index bee83446f..b6c627d0b 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
@@ -170,6 +170,55 @@ describe('「生成任务」侧栏的开合与入口位置', () => {
     ).toBe(true);
   });
 
+  it('运行页不挂「生成任务」入口与面板，切回资源页又回来', async () => {
+    installInvoke();
+    const manifest = createGameCreationAppManifest(
+      'workbench-run-hides-tasks-entry',
+      '运行页隐藏生成任务',
+    );
+    // 有已完成的可运行原型：运行页签可用，但没有活预览，所以首屏仍停在资源管理。
+    manifest.tasks = manifest.tasks.map((task) =>
+      task.id === 'code-prototype' ? { ...task, status: 'completed' } : task,
+    );
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-run-hides-tasks-entry',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    // 资源页照旧有入口与锚点。
+    expect(
+      await screen.findByRole('button', { name: '生成任务' }),
+    ).not.toBeNull();
+    expect(
+      document.querySelector('.game-resource-generation-tasks-anchor'),
+    ).not.toBeNull();
+
+    // 运行页：入口、面板、锚点一起消失，画面右上角只留版本入口与预览地址小字。
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    await waitFor(() =>
+      expect(screen.getByLabelText('运行表现层')).not.toBeNull(),
+    );
+    expect(
+      document.querySelector('.game-resource-generation-tasks-anchor'),
+    ).toBeNull();
+    expect(screen.queryByRole('button', { name: /^生成任务/ })).toBeNull();
+
+    // 切回资源页入口回来：任务只是在这页不显示，没有被丢掉。
+    fireEvent.click(screen.getByRole('tab', { name: '资源管理' }));
+    expect(
+      await screen.findByRole('button', { name: '生成任务' }),
+    ).not.toBeNull();
+  });
+
   it('「依赖 / 类型」与前一按钮之间的间距跟行内其他按钮一致', () => {
     const styles = readFileSync(
       repoPath('apps/ai-game-creator-shell/src/styles.css'),
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasQuickEditDraft.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasQuickEditDraft.test.tsx
index b9383a561..c98db582b 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasQuickEditDraft.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasQuickEditDraft.test.tsx
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
 import {
+  composerValue,
   createGameCreationAppManifest,
   findResourceSelectButton,
   fireEvent,
@@ -368,6 +369,17 @@ function panelPromptText(panel: HTMLElement) {
   return within(panel).getByLabelText('快速编辑提示词').textContent ?? '';
 }
 
+/**
+ * 「重开面板后提示词应当回填」不能同步读。
+ *
+ * 面板（dialog）先出现，Lexical 的编辑器值随后才落；同步读 `textContent` 在并发跑全量时
+ * 会偶发读到空串——CI run 2702 与本地一次全量各命中过一次（同一条用例、`expected '' to
+ * include '把角色头发改成红色'`）。这里等值真的落位，不再赌时序。
+ */
+async function expectPanelPromptContains(panel: HTMLElement, expected: string) {
+  await waitFor(() => expect(panelPromptText(panel)).toContain(expected));
+}
+
 /** 关掉画布浮层：Esc 与点外部同一条既有链路（`clearResourceCanvasFocus`）。 */
 async function dismissPanel() {
   fireEvent.keyDown(document, { key: 'Escape' });
@@ -408,7 +420,7 @@ describe('快速编辑草稿的保留与恢复', () => {
     await dismissPanel();
 
     const reopened = await openQuickEditPanel('source-art.png');
-    expect(panelPromptText(reopened)).toContain('把夜色改成星空');
+    await expectPanelPromptContains(reopened, '把夜色改成星空');
     expect(
       document.querySelector('[data-resource-reference-id="source-rules"]'),
     ).not.toBeNull();
@@ -438,13 +450,15 @@ describe('快速编辑草稿的保留与恢复', () => {
     );
 
     await dismissPanel();
-    expect(
-      panelPromptText(await openQuickEditPanel('source-art.png')),
-    ).toContain('第一张的草稿');
+    await expectPanelPromptContains(
+      await openQuickEditPanel('source-art.png'),
+      '第一张的草稿',
+    );
     await dismissPanel();
-    expect(
-      panelPromptText(await openQuickEditPanel('source-art-2.png')),
-    ).toContain('第二张的草稿');
+    await expectPanelPromptContains(
+      await openQuickEditPanel('source-art-2.png'),
+      '第二张的草稿',
+    );
   });
 
   it('恢复入口按草稿计数，「继续编辑」重开面板并回填，丢弃后入口消失', async () => {
@@ -486,7 +500,7 @@ describe('快速编辑草稿的保留与恢复', () => {
     const resumed = await screen.findByRole('dialog', {
       name: '快速编辑图片',
     });
-    expect(panelPromptText(resumed)).toContain('把角色头发改成红色');
+    await expectPanelPromptContains(resumed, '把角色头发改成红色');
     await dismissPanel();
 
     fireEvent.click(
@@ -539,7 +553,7 @@ describe('快速编辑草稿的保留与恢复', () => {
     ).not.toBeNull();
 
     const resumed = await openQuickEditPanel('source-art.png');
-    expect(panelPromptText(resumed)).toContain('把夜色改成星空');
+    await expectPanelPromptContains(resumed, '把夜色改成星空');
   });
 
   it('正规化换掉卡片投影后，草稿跟着资源走、重开在正式素材上继续', async () => {
@@ -605,7 +619,7 @@ describe('快速编辑草稿的保留与恢复', () => {
     // 旧卡片已经不在画布上：草稿按**路径**归属，新投影的正式素材卡照样命中，否则这一笔
     // 就再也点不到。
     const reopened = await openQuickEditPanel('task-art.png');
-    expect(panelPromptText(reopened)).toContain('把夜色改成星空');
+    await expectPanelPromptContains(reopened, '把夜色改成星空');
   });
 
   /**
@@ -664,7 +678,7 @@ describe('快速编辑草稿的保留与恢复', () => {
     );
 
     const reopened = await openQuickEditPanel('task-art.png');
-    expect(panelPromptText(reopened)).toContain('把夜色改成星空');
+    await expectPanelPromptContains(reopened, '把夜色改成星空');
   });
 
   it('原生恢复队列与本地草稿共用同一枚入口，两边都能继续', async () => {
@@ -732,7 +746,11 @@ describe('快速编辑草稿的保留与恢复', () => {
     );
 
     const reopened = await openQuickEditPanel('source-art.png');
-    expect(panelPromptText(reopened)).not.toContain('把夜色改成星空');
+    // 用 `composerValue` 读（它内部先让 Lexical 落值）：同步读会在值未落时拿到空串，
+    // 让这条否定断言空过——那正是上面那条回填断言的同一类竞态。
+    expect(
+      await composerValue(within(reopened).getByLabelText('快速编辑提示词')),
+    ).not.toContain('把夜色改成星空');
   });
 });
 
@@ -815,7 +833,7 @@ describe('提交中的快速编辑进「生成任务」侧栏', () => {
 
     // 回到第一张：草稿照旧回填，但这一笔已经在跑——再点提交必须被拦下。
     const reopened = await openQuickEditPanel('source-art.png');
-    expect(panelPromptText(reopened)).toContain('把嘴改小一点');
+    await expectPanelPromptContains(reopened, '把嘴改小一点');
     fireEvent.click(within(reopened).getByRole('button', { name: '修改' }));
     expect(
       await within(reopened).findByText(
diff --git a/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx b/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
index eb06cfcd7..37a5bc8a7 100644
--- a/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
@@ -10,7 +10,15 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { $getRoot, $getSelection, $isRangeSelection } from 'lexical';
-import { createRef, StrictMode, useState } from 'react';
+import {
+  createRef,
+  forwardRef,
+  StrictMode,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { afterEach, describe, expect, test, vi } from 'vitest';
 
 import type {
@@ -21,10 +29,19 @@ import {
   LOCAL_GAME_PREVIEW_INSPECT_MESSAGE,
   parseLocalGamePreviewInspectMessage,
 } from '../src/features/project-workspace/LocalGamePreviewFrame';
+import { attachmentReferenceProvider } from '../src/features/project-workspace/reference-source/attachmentReferenceProvider';
+import { createResourceReferenceProvider } from '../src/features/project-workspace/reference-source/resourceReferenceProvider';
+import { runtimeRegionReferenceProvider } from '../src/features/project-workspace/reference-source/runtimeRegionReferenceProvider';
+import { useSkillReferenceProvider } from '../src/features/project-workspace/reference-source/skillReferenceProvider';
 import {
   ResourceReferenceInput,
   type ResourceReferenceInputHandle,
 } from '../src/features/project-workspace/ResourceReferenceInput';
+import {
+  ResourceReferencePicker,
+  ResourceReferencePickerAction,
+  type ResourceReferencePickerHandle,
+} from '../src/features/project-workspace/ResourceReferencePicker';
 import {
   type ChatComposerDraft,
   type ChatReference,
@@ -40,6 +57,7 @@ import {
   RESOURCE_REFERENCE_INSERT_EVENT,
   RESOURCE_REFERENCE_INSERT_MANY_EVENT,
   RESOURCE_REFERENCE_SCOPES,
+  resourceLabelResolver,
   resourceReferenceCategory,
   resourceReferenceFromAsset,
   resourceReferenceMatchesCategoryFilter,
@@ -88,11 +106,105 @@ async function settleComposer() {
   });
 }
 
-/** 草稿展示文本：canonical content 是唯一真相；这里刻意不传 manifest，引用展开成 `@id`。 */
+/** 草稿展示文本：canonical content 是唯一真相；这里刻意不给清单，引用展开成 `@id`。 */
 function draftText(draft: ChatComposerDraft | undefined) {
-  return directCodexContentToPromptText(draft?.content ?? [], []);
+  return directCodexContentToPromptText(
+    draft?.content ?? [],
+    resourceLabelResolver([]),
+  );
 }
 
+/**
+ * 测试夹具：按真实宿主的接法把「输入区（注入 provider）+ 宿主渲染的素材选择器」拼起来。
+ *
+ * 夹具保持旧 props 形状（`assets` / `versions` / `activeVersionId` / `projectPath`），
+ * 内部翻译成注入的 provider——用例因此只关心行为，不关心接线。
+ * `withSkillProvider` 打开 `$` 候选（只有 DirectProject 宿主才注入它）。
+ */
+const ComposerHost = forwardRef<
+  ResourceReferenceInputHandle,
+  {
+    ariaLabel: string;
+    assets?: GameCreationAppAssetManifestEntry[];
+    versions?: GameIterationVersion[];
+    activeVersionId?: string | null;
+    projectPath?: string;
+    initialContent?: ChatComposerDraft['content'];
+    onChange?: (draft: ChatComposerDraft) => void;
+    multiline?: boolean;
+    rows?: number;
+    showPolishAction?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    withSkillProvider?: boolean;
+  }
+>(function ComposerHost(
+  {
+    assets = [],
+    versions,
+    activeVersionId = null,
+    projectPath = 'C:/project',
+    withSkillProvider = false,
+    ...inputProps
+  },
+  ref,
+) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const pickerRef = useRef<ResourceReferencePickerHandle | null>(null);
+  const localInputRef = useRef<ResourceReferenceInputHandle | null>(null);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const skillProvider = useSkillReferenceProvider();
+  const assignInputRef = useCallback(
+    (handle: ResourceReferenceInputHandle | null) => {
+      localInputRef.current = handle;
+      if (typeof ref === 'function') {
+        ref(handle);
+      } else if (ref) {
+        ref.current = handle;
+      }
+    },
+    [ref],
+  );
+  const providers = useMemo(
+    () => [
+      createResourceReferenceProvider({ assets }),
+      ...(withSkillProvider ? [skillProvider] : []),
+      attachmentReferenceProvider,
+      runtimeRegionReferenceProvider,
+    ],
+    [assets, skillProvider, withSkillProvider],
+  );
+  return (
+    <>
+      <ResourceReferenceInput
+        {...inputProps}
+        ref={assignInputRef}
+        providers={providers}
+        projectPath={projectPath}
+        containerRef={containerRef}
+        submitSuppressed={pickerOpen}
+        inputActions={
+          <ResourceReferencePickerAction
+            onOpen={() => pickerRef.current?.open()}
+          />
+        }
+      />
+      <ResourceReferencePicker
+        ref={pickerRef}
+        anchorRef={containerRef}
+        assets={assets}
+        versions={versions}
+        activeVersionId={activeVersionId}
+        projectPath={projectPath}
+        onInsert={(references) =>
+          localInputRef.current?.insertReferences(references)
+        }
+        onOpenChange={setPickerOpen}
+      />
+    </>
+  );
+});
+
 /** 草稿里的资源引用 id，按 content 顺序。 */
 function draftResourceIds(draft: ChatComposerDraft | undefined) {
   return (draft?.content ?? []).flatMap((part) =>
@@ -198,11 +310,12 @@ describe('ResourceReferenceInput', () => {
 
     try {
       render(
-        <ResourceReferenceInput
+        <ComposerHost
           onChange={vi.fn()}
           assets={assets}
           projectPath="C:/project"
           ariaLabel="聊天"
+          withSkillProvider
         />,
       );
 
@@ -269,7 +382,7 @@ describe('ResourceReferenceInput', () => {
           >
             模拟润色
           </button>
-          <ResourceReferenceInput
+          <ComposerHost
             ref={composerRef}
             initialContent={[
               { type: 'input_text', text: '原始需求' },
@@ -316,7 +429,7 @@ describe('ResourceReferenceInput', () => {
           >
             模拟润色
           </button>
-          <ResourceReferenceInput
+          <ComposerHost
             ref={composerRef}
             initialContent={[chatReferenceToContentPart(reference)]}
             onChange={onChange}
@@ -343,7 +456,8 @@ describe('ResourceReferenceInput', () => {
       { type: 'input_text', text: '\n' },
       { type: 'input_text', text: '把这一版改成夜景' },
     ]);
-    expect(draftText(draft)).toBe('@hero\n把这一版改成夜景');
+    // token 前后各留一个空白：草稿以引用开头时，读回的 prompt 前面也有那个分隔空白。
+    expect(draftText(draft)).toBe(' @hero\n把这一版改成夜景');
   });
 
   test('润色改写掉 `@附件名` token 时，附件 part 补在末尾而不是丢掉', async () => {
@@ -366,7 +480,7 @@ describe('ResourceReferenceInput', () => {
         >
           模拟润色
         </button>
-        <ResourceReferenceInput
+        <ComposerHost
           ref={composerRef}
           initialContent={[chatReferenceToContentPart(reference), attachment]}
           onChange={onChange}
@@ -411,7 +525,7 @@ describe('ResourceReferenceInput', () => {
         >
           模拟润色
         </button>
-        <ResourceReferenceInput
+        <ComposerHost
           ref={composerRef}
           initialContent={[
             chatReferenceToContentPart(reference),
@@ -453,7 +567,7 @@ describe('ResourceReferenceInput', () => {
             onSubmit();
           }}
         >
-          <ResourceReferenceInput
+          <ComposerHost
             initialContent={draft.content}
             onChange={setDraft}
             assets={assets}
@@ -485,7 +599,7 @@ describe('ResourceReferenceInput', () => {
     const user = userEvent.setup();
     const onChange = vi.fn<(draft: ChatComposerDraft) => void>();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={onChange}
         assets={assets}
         projectPath="C:/project"
@@ -519,7 +633,7 @@ describe('ResourceReferenceInput', () => {
       enemyPart,
       { type: 'input_text', text: ' ' },
     ]);
-    expect(draftText(draft)).toBe('@hero @enemy ');
+    expect(draftText(draft)).toBe(' @hero @enemy ');
     expect(draftResourceIds(draft)).toEqual(['hero', 'enemy']);
     expect(
       document.querySelector('[data-resource-reference-id="hero"]'),
@@ -538,7 +652,7 @@ describe('ResourceReferenceInput', () => {
     ).__TAURI__ = { core: { invoke } };
     render(
       <StrictMode>
-        <ResourceReferenceInput
+        <ComposerHost
           onChange={vi.fn()}
           assets={assets}
           projectPath="C:/project"
@@ -658,7 +772,7 @@ describe('ResourceReferenceInput', () => {
     const onChange = vi.fn<(draft: ChatComposerDraft) => void>();
     const composerRef = createRef<ResourceReferenceInputHandle>();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         ref={composerRef}
         initialContent={[]}
         onChange={onChange}
@@ -758,7 +872,7 @@ describe('ResourceReferenceInput', () => {
     const user = userEvent.setup();
     const onChange = vi.fn<(draft: ChatComposerDraft) => void>();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={onChange}
         assets={assets}
         projectPath="C:/project"
@@ -780,7 +894,7 @@ describe('ResourceReferenceInput', () => {
   test('counts one inserted reference as a single character in the editor text model', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={assets}
         projectPath="C:/project"
@@ -807,7 +921,7 @@ describe('ResourceReferenceInput', () => {
     const user = userEvent.setup();
     const onChange = vi.fn<(draft: ChatComposerDraft) => void>();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={onChange}
         assets={assets}
         projectPath="C:/project"
@@ -830,7 +944,7 @@ describe('ResourceReferenceInput', () => {
 
     // 草稿 text 是 content 的逐字投影，前端不裁剪：引用节点后的分隔空格照样留在文本里；
     // 结构化引用完整保留，后端按整条消息判断是否有有效内容。
-    expect(draftText(onChange.mock.calls.at(-1)?.[0])).toBe('@hero ');
+    expect(draftText(onChange.mock.calls.at(-1)?.[0])).toBe(' @hero ');
     expect(draftResourceIds(onChange.mock.calls.at(-1)?.[0])).toEqual(['hero']);
 
     // 引用节点是原子的：一次操作删掉整个 chip，不存在"删一半"的中间态。
@@ -887,7 +1001,7 @@ describe('ResourceReferenceInput', () => {
   test('keeps an independent search and filter state per picker scope', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={assets}
         versions={[
@@ -937,7 +1051,7 @@ describe('ResourceReferenceInput', () => {
   test('shows an empty state when the active version has no bound resources', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={assets}
         activeVersionId="v1"
@@ -960,7 +1074,7 @@ describe('ResourceReferenceInput', () => {
   test('shows the current-version empty state when the project has no versions', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={assets}
         versions={[]}
@@ -984,7 +1098,7 @@ describe('ResourceReferenceInput', () => {
       assets[2]!,
     ];
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         initialContent={[
           { type: 'input_text', text: '用这个角色' },
           chatReferenceToContentPart(
@@ -1017,7 +1131,7 @@ describe('ResourceReferenceInput', () => {
     const onChange = vi.fn<(draft: ChatComposerDraft) => void>();
     const composerRef = createRef<ResourceReferenceInputHandle>();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         initialContent={[{ type: 'input_text', text: '上一个会话的草稿' }]}
         ref={composerRef}
         onChange={onChange}
@@ -1074,7 +1188,7 @@ describe('ResourceReferenceInput', () => {
   test('标签筛选把不符合的候选筛掉，多标签叠加，再与搜索关键字、功能分类叠加', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={taggedAssets}
         projectPath="C:/project"
@@ -1125,7 +1239,7 @@ describe('ResourceReferenceInput', () => {
   test('两个页签各自持有一份独立的标签库与已选标签', async () => {
     const user = userEvent.setup();
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         onChange={vi.fn()}
         assets={taggedAssets}
         versions={[iterationVersion('v1', ['hero', 'theme'])]}
@@ -1176,13 +1290,13 @@ describe('ResourceReferenceInput', () => {
     const quickEditOnChange = vi.fn<(draft: ChatComposerDraft) => void>();
     render(
       <>
-        <ResourceReferenceInput
+        <ComposerHost
           onChange={chatOnChange}
           assets={taggedAssets}
           projectPath="C:/project"
           ariaLabel="聊天"
         />
-        <ResourceReferenceInput
+        <ComposerHost
           onChange={quickEditOnChange}
           assets={taggedAssets}
           projectPath="C:/project"
@@ -1213,7 +1327,7 @@ describe('ResourceReferenceInput', () => {
 
   test('快速编辑提示词输入区不渲染内置润色入口：润色归宿主的 ResourcePromptPolishSlot', async () => {
     render(
-      <ResourceReferenceInput
+      <ComposerHost
         initialContent={[{ type: 'input_text', text: '把夜色改成星空' }]}
         onChange={vi.fn()}
         assets={taggedAssets}
diff --git a/apps/ai-game-creator-shell/tests/resourceReferences.test.ts b/apps/ai-game-creator-shell/tests/resourceReferences.test.ts
index 90f987e9b..ed38f7d4a 100644
--- a/apps/ai-game-creator-shell/tests/resourceReferences.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceReferences.test.ts
@@ -5,6 +5,7 @@ import {
   chatComposerDraftToDirectCodexUserItem,
   directCodexContentToPromptText,
   hasMeaningfulDirectCodexContent,
+  resourceLabelResolver,
 } from '../src/features/project-workspace/resourceReferences';
 
 describe('DirectProject user Response item', () => {
@@ -102,7 +103,7 @@ describe('DirectProject user Response item', () => {
           { type: 'agc_resource_reference', resourceId: 'asset-hero' },
           { type: 'input_text', text: ' 做主视觉' },
         ],
-        [],
+        resourceLabelResolver([]),
       ),
     ).toBe('用 @asset-hero 做主视觉');
   });
diff --git a/apps/ai-game-creator-shell/tests/runNoticeShellWiring.test.tsx b/apps/ai-game-creator-shell/tests/runNoticeShellWiring.test.tsx
new file mode 100644
index 000000000..04209b358
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/runNoticeShellWiring.test.tsx
@@ -0,0 +1,158 @@
+/** @vitest-environment jsdom */
+
+/**
+ * 运行提示的外壳级接线：`ProjectChat` 发一条提示，工作台壳真的把它渲染成浮层。
+ *
+ * 单测（`runNoticeToast`）只证明组件本身，`previewActivation` 只证明 App 会调这条通道；
+ * 从「通道被调用」到「用户看到 toast」之间还差一层壳的接线（prop 名、handler、portal 挂点、
+ * tone 传递）。这里用替身聊天把这一层单独钉住：以后有人把 `<RunNoticeToast/>` 挪进条件
+ * 分支、或在传 prop 时写错名字，这条会红。
+ */
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createGameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import type { ProjectChatComponentProps } from '../src/features/app-shell/model';
+import { WorkspaceLauncherShell } from '../src/features/app-shell/WorkspaceLauncher';
+import {
+  createProjectChatRuntimeHarness,
+  pickProjectFromLauncher,
+  testAuthUser,
+} from './appSurface/harness';
+
+const PROJECT_PATH = '/tmp/run-notice-shell-project';
+
+function StubRunNoticeChat({ onRunNotice }: ProjectChatComponentProps) {
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() =>
+          onRunNotice?.({ message: '运行通过，已载入客户端运行视图' })
+        }
+      >
+        触发成功提示
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          onRunNotice?.({
+            tone: 'error',
+            message: '运行游戏失败：预览端口被占用',
+          })
+        }
+      >
+        触发失败提示
+      </button>
+    </div>
+  );
+}
+
+/**
+ * 打开工作台所需的最小命令集照抄 `home.suite` 的活动清单用例：项目目录探测 + 清单 +
+ * 资源图 / 布局读回，其余命令沿用聊天 harness。
+ */
+function renderWorkbench() {
+  const manifest = createGameCreationAppManifest(
+    'run-notice-shell-project',
+    '运行提示接线项目',
+  );
+  const runtimeHarness = createProjectChatRuntimeHarness({
+    projectPath: PROJECT_PATH,
+  });
+  const invoke = vi.fn(
+    async (command: string, args?: Record<string, unknown>) => {
+      if (command === 'get_design_agent_runtime_mode') return null;
+      if (command === 'inspect_local_project_directory') {
+        return {
+          projectPath: PROJECT_PATH,
+          exists: true,
+          isDirectory: true,
+          isGameCreatorProject: true,
+          projectName: manifest.name,
+          recentRunStatus: null,
+          recentRunStopReason: null,
+        };
+      }
+      if (command === 'get_local_game_manifest') {
+        return manifest;
+      }
+      if (command === 'read_local_project_resource_graph') {
+        return {
+          resourceIds: [],
+          referenceEdges: [],
+          taskFlows: [],
+          connectionIndex: [],
+          producerAssignments: [],
+          dependencyDepths: [],
+          unresolvedReferenceResourceIds: [],
+          cyclicResourceIds: [],
+          cyclicTaskIds: [],
+          producerMappingTruncated: false,
+        };
+      }
+      if (command === 'read_local_project_resource_canvas_layout') {
+        return {
+          schemaVersion: 'game-creator-resource-layout.v1',
+          projectId: manifest.projectId,
+          mode: args?.mode,
+          revision: 0,
+          positions: [],
+          updatedAt: 0,
+        };
+      }
+      return runtimeHarness.invoke(command, args);
+    },
+  );
+  window.__TAURI__ = {
+    core: { invoke: invoke as never },
+    event: { listen: runtimeHarness.listen as never },
+  };
+  render(
+    <WorkspaceLauncherShell
+      currentUser={testAuthUser}
+      initialView="projects"
+      onLogout={vi.fn()}
+      ProjectChat={StubRunNoticeChat}
+    />,
+  );
+  pickProjectFromLauncher(PROJECT_PATH);
+}
+
+function toastElement() {
+  return document.querySelector('[data-project-run-notice-toast="true"]');
+}
+
+describe('运行提示的外壳接线', () => {
+  it('成功提示渲染成浮层，且不落在对话容器里', async () => {
+    renderWorkbench();
+    await screen.findByLabelText('项目开发工作台');
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '触发成功提示' }),
+    );
+
+    await waitFor(() => expect(toastElement()).not.toBeNull());
+    expect(toastElement()?.textContent ?? '').toContain(
+      '运行通过，已载入客户端运行视图',
+    );
+    // 「对话区里没有这条提示」由 `previewActivation` 用真实聊天容器断言；这里用的替身
+    // 聊天没有消息列表，重复断言只会自证。
+  });
+
+  it('失败提示按 alert 渲染', async () => {
+    renderWorkbench();
+    await screen.findByLabelText('项目开发工作台');
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '触发失败提示' }),
+    );
+
+    await waitFor(() =>
+      expect(toastElement()?.querySelector('[role="alert"]')).not.toBeNull(),
+    );
+    expect(toastElement()?.textContent ?? '').toContain(
+      '运行游戏失败：预览端口被占用',
+    );
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/runNoticeToast.test.tsx b/apps/ai-game-creator-shell/tests/runNoticeToast.test.tsx
new file mode 100644
index 000000000..3739e17bf
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/runNoticeToast.test.tsx
@@ -0,0 +1,120 @@
+/** @vitest-environment jsdom */
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { RunNoticeToast } from '../src/features/app-shell/RunNoticeToast';
+
+const RUN_MESSAGE = '运行通过，已载入客户端运行视图';
+
+function toastElement() {
+  return document.querySelector('[data-project-run-notice-toast="true"]');
+}
+
+describe('运行 / 预览浮层提示', () => {
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+  });
+
+  it('没有提示时不渲染任何浮层', () => {
+    render(<RunNoticeToast notice={null} onDismiss={vi.fn()} />);
+
+    expect(toastElement()).toBeNull();
+    expect(screen.queryByText(RUN_MESSAGE)).toBeNull();
+  });
+
+  it('在浮层里显示提示，并在到点后自动收起', () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+
+    render(
+      <RunNoticeToast
+        notice={{ id: 1, message: RUN_MESSAGE }}
+        onDismiss={onDismiss}
+      />,
+    );
+
+    expect(toastElement()).not.toBeNull();
+    expect(screen.getByText(RUN_MESSAGE)).not.toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(2_600);
+    });
+
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('同一句文案连续触发时重新计时', () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+    const { rerender } = render(
+      <RunNoticeToast
+        notice={{ id: 1, message: RUN_MESSAGE }}
+        onDismiss={onDismiss}
+      />,
+    );
+
+    rerender(
+      <RunNoticeToast
+        notice={{ id: 2, message: RUN_MESSAGE }}
+        onDismiss={onDismiss}
+      />,
+    );
+    act(() => {
+      vi.advanceTimersByTime(2_000);
+    });
+    expect(onDismiss).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(600);
+    });
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('失败提示用错误色调，不需要调用方再拼一套文案', () => {
+    render(
+      <RunNoticeToast
+        notice={{
+          id: 1,
+          tone: 'error',
+          message: '在浏览器打开失败：permission denied',
+        }}
+        onDismiss={vi.fn()}
+      />,
+    );
+
+    const toast = toastElement()?.querySelector(
+      '.platform-runtime-status-toast',
+    );
+    // `PlatformRuntimeStatusToast` 的失败态就是 alert + assertive，成功态是 status + polite。
+    expect(toast?.getAttribute('role')).toBe('alert');
+    expect(
+      screen.getByText('在浏览器打开失败：permission denied'),
+    ).not.toBeNull();
+  });
+
+  it('失败提示比成功提示留得久：2.6 秒不该把错误收走', () => {
+    vi.useFakeTimers();
+    const onDismiss = vi.fn();
+    render(
+      <RunNoticeToast
+        notice={{
+          id: 1,
+          tone: 'error',
+          message: '运行游戏失败：预览端口被占用',
+        }}
+        onDismiss={onDismiss}
+      />,
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(2_600);
+    });
+    expect(onDismiss).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(3_400);
+    });
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/runPreviewBrowserOpen.test.tsx b/apps/ai-game-creator-shell/tests/runPreviewBrowserOpen.test.tsx
new file mode 100644
index 000000000..029445850
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/runPreviewBrowserOpen.test.tsx
@@ -0,0 +1,119 @@
+/** @vitest-environment jsdom */
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createGameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import ProjectDevelopmentView from '../src/view/project-development';
+
+const openUrl = vi.fn(async () => undefined);
+vi.mock('@tauri-apps/plugin-opener', () => ({
+  openUrl: (url: string) => openUrl(url),
+}));
+
+const PREVIEW_URL = 'http://127.0.0.1:4173/';
+
+function installInvoke() {
+  window.__TAURI__ = {
+    core: {
+      invoke: vi.fn(async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return {
+            resourceIds: [],
+            referenceEdges: [],
+            taskFlows: [],
+            categories: [],
+            diagnostics: [],
+          };
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId: args?.expectedProjectId,
+            mode: args?.mode,
+            revision: 0,
+            positions: [],
+            updatedAt: 0,
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      }),
+    },
+  } as unknown as typeof window.__TAURI__;
+}
+
+function renderRunView(options: { withPreview?: boolean } = {}) {
+  installInvoke();
+  const manifest = createGameCreationAppManifest(
+    'run-preview-browser-open',
+    '运行页浏览器入口',
+  );
+  const onNotice = vi.fn();
+  render(
+    <ProjectDevelopmentView
+      projectName={manifest.name}
+      projectPath="/tmp/run-preview-browser-open"
+      manifest={manifest}
+      attachments={[]}
+      recentRunStatus={null}
+      recentRunStopReason={null}
+      preview={
+        options.withPreview === false
+          ? null
+          : { status: 'running', url: PREVIEW_URL, port: 4173 }
+      }
+      supervisor={<div>项目总控</div>}
+      onHomeOpen={vi.fn()}
+      onProjectsOpen={vi.fn()}
+      onNotice={onNotice}
+    />,
+  );
+  return { onNotice };
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+});
+
+describe('运行页「在浏览器打开」', () => {
+  it('点顶栏那枚按钮就把当前预览地址交给系统浏览器', async () => {
+    renderRunView();
+
+    const entry = await screen.findByRole('button', {
+      name: '在浏览器打开',
+    });
+    // 入口住在工作台顶栏的动作区里，与版本入口同一排；预览地址本身不再以文字出现。
+    expect(entry.closest('.game-workbench-view-actions')).not.toBeNull();
+    expect(document.body.textContent ?? '').not.toContain(PREVIEW_URL);
+    expect(document.querySelector('.game-run-status-hint')).toBeNull();
+    fireEvent.click(entry);
+
+    await waitFor(() => expect(openUrl).toHaveBeenCalledWith(PREVIEW_URL));
+    // 成功不弹提示：浏览器真的起来了，用户自己看得见。
+    expect(openUrl).toHaveBeenCalledTimes(1);
+  });
+
+  it('没有活预览时不渲染这枚入口', async () => {
+    renderRunView({ withPreview: false });
+
+    await screen.findByRole('tab', { name: '运行' });
+    expect(screen.queryByRole('button', { name: '在浏览器打开' })).toBeNull();
+  });
+
+  it('打开失败时把原因交给统一提示通道，而不是静默吞掉', async () => {
+    openUrl.mockRejectedValueOnce(new Error('permission denied'));
+    const { onNotice } = renderRunView();
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '在浏览器打开' }),
+    );
+
+    await waitFor(() =>
+      expect(onNotice).toHaveBeenCalledWith({
+        tone: 'error',
+        message: '在浏览器打开失败：permission denied',
+      }),
+    );
+  });
+});
diff --git a/deploy/container/README.md b/deploy/container/README.md
index 62d3c5904..6ecf28b5a 100644
--- a/deploy/container/README.md
+++ b/deploy/container/README.md
@@ -79,7 +79,21 @@ bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-git
 bash scripts/gitea-ci-job-image.sh load-runner
 ```
 
-默认构建 tag 为 `genarrative/gitea-project-ci:20260920.2`。脚本通过 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本、根 workspace 的唯一 npm lock 与全部 workspace manifest，以及 server-rs、桌面壳和 AI 游戏创作壳的 Cargo manifests/lock，外加 AI 游戏创作壳本地路径依赖的三个编辑器 bridge crate 源树；不会把业务源码、素材或本地私密文件发送给 Docker daemon。新镜像显式安装并精确校验 `npm 10.9.7`，不依赖 Node 发行包隐含的 npm 版本；除固定工具链外，还按一份 npm workspace lock 与三份 Cargo lock 预热下载缓存。npm 只执行一次忽略 lifecycle scripts 的 workspace `npm ci`（最多 5 次整命令级有界重试，处理 registry ECONNRESET），三个 `cargo fetch --locked` 最多执行 5 次整命令级有界重试，再分别以断网 `cargo fetch --locked` 验证缓存闭合，镜像不包含 `node_modules` 或 Cargo `target`。`build` 完成后会自动运行环境校验，`load-runner` 还会比对宿主和 runner 内层的完整 Image ID，并在内层执行 bwrap 与 Chrome headless canary。workspace lock 或 manifest 变化落地后必须按下述顺序重建并装载镜像；过渡期旧固定镜像缺少 `GENARRATIVE_GITEA_CI_NPM_VERSION` 时，校验只输出 `npm_version=partial` 和 Actions warning，继续由当前 job 的根 `npm ci` 验证唯一 lock，不能据此宣称 npm 版本或新依赖缓存已经闭合。执行这些命令不要求必须使用 root，但执行账号必须有权访问宿主 Docker API 并管理 runner 容器；没有该权限时交给 runner 运维人员执行。
+默认构建 tag 为 `genarrative/gitea-project-ci:20260920.2`。脚本通过 NUL 分隔白名单 tar 流只发送 Dockerfile、构建配置与缓存导出脚本、checkout 脚本、根 workspace 的唯一 npm lock 与全部 workspace manifest，以及 server-rs、桌面壳和 AI 游戏创作壳的 Cargo manifests/lock。AGC 的 `vendor/*/Cargo.toml` 和三个编辑器 bridge crate 的 manifest 同样参与，避免漏掉本地 path 依赖；不发送业务源码、素材或本地私密文件。新镜像显式安装并精确校验 `npm 10.9.7`，不依赖 Node 发行包隐含的 npm 版本；除固定工具链外，还按一份 npm workspace lock 与三份 Cargo lock 预热下载缓存。npm 只执行一次忽略 lifecycle scripts 的 workspace `npm ci`（最多 5 次整命令级有界重试，处理 registry ECONNRESET），三个 `cargo fetch --locked` 最多执行 5 次整命令级有界重试，再分别以断网 `cargo fetch --locked` 验证缓存闭合，镜像不包含 `node_modules` 或 Cargo `target`。`build` 完成后会自动运行环境校验，`load-runner` 还会比对宿主和 runner 内层的完整 Image ID，并在内层执行 bwrap 与 Chrome headless canary。workspace lock 或 manifest 变化落地后必须按下述顺序重建并装载镜像；过渡期旧固定镜像缺少 `GENARRATIVE_GITEA_CI_NPM_VERSION` 时，校验只输出 `npm_version=partial` 和 Actions warning，继续由当前 job 的根 `npm ci` 验证唯一 lock，不能据此宣称 npm 版本或新依赖缓存已经闭合。执行这些命令不要求必须使用 root，但执行账号必须有权访问宿主 Docker API 并管理 runner 容器；没有该权限时交给 runner 运维人员执行。
+
+基础镜像构建需要 Docker Buildx 插件，固定使用独立的 `genarrative-ci-images` docker-container builder（BuildKit `v0.23.2`），不改变默认 builder、Docker daemon 配置或其它构建。脚本按 `gitea-ci-buildkitd.toml` 首次创建 builder；配置的 24 GB 为 GC 空间目标、4 GB 为保留量、宿主保留 10 GB 空闲，均不是活动构建的硬磁盘配额。BuildKit 自动回收可释放的旧记录，正在使用的记录受保护；不运行全局 prune。已有 builder 的配置变更须另择空闲窗口应用，脚本不会为修改 GC 配置而重启它。
+
+Cargo registry 的压缩包与索引、npm `_cacache` 使用稳定命名、`sharing=locked` 的持久 cache mount，不随 commit 或 lock 哈希更名。它们仅供受信任宿主的镜像构建使用，不挂给 PR job；未缓存的新版本仍按当前锁文件下载并校验。cache mount 本身不进入输出镜像，因此构建显式物化下载快照：Cargo 只导出本次实际解包的 crate 归档及索引；npm 按当前 lock 的 integrity 筛选已下载条目并校验内容，不把历史包版本、凭据或可写 target 一并复制。最终 CI 镜像仍提供独立的下载缓存目录，普通 job 在自身容器内使用。
+
+首次启用前可从现有可信 CI 镜像导入下载缓存，避免从空缓存重新下载；后续正常构建不必重复导入。维护服务以 root 运行时，下述命令也以 root 执行，确保使用同一套 Buildx 配置。Ubuntu 发行版 Docker 的插件包名为 `docker-buildx`（Docker 官方发行源则为 `docker-buildx-plugin`）；只安装匹配当前 Docker 来源的插件包，无需重启 runner。
+
+```bash
+sudo apt-get install docker-buildx
+# 替换为运维已验证的完整 Image ID；只提取 registry/cache、registry/index 和 npm/_cacache。
+sudo bash scripts/gitea-ci-job-image.sh seed-downloads 'sha256:<可信镜像的64位摘要>'
+```
+
+seed 临时目录与容器在结束时删除，既有镜像只读提取、不运行其入口；新基础镜像继续从固定工具链与 runner base 构建，不继承旧对象快照层。未执行 seed 或下载缓存被 GC 回收只影响速度，不影响正确性。升级维护器需同步安装新版 `maintain-gitea-rust-cache.py` 才会获得 journal 阶段日志；基础镜像构建脚本与 Dockerfile 来自所选 master run 的提交，不把 PR 分支代码直接用于线上维护。
 
 runner 配置保留原 `ubuntu-latest` 映射，`genarrative-ci` 继续映射到经 `build / verify / load-runner` 验证并写入配置的完整 Image ID。内层 Docker 数据必须持久化，`force_pull` 保持 `false`；该精确 Image ID 在内层不存在时 job 应直接失败，不回退到浮动 tag 或现场拉取。各个 job 使用镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，带 5 次有界重试，不再运行时下载 GitHub checkout action；随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验工具链、一份 npm workspace 缓存锁、三份 Cargo 缓存锁、bwrap 和 Chrome headless。锁不匹配时校验会输出 `partial` 和醒目的 Actions warning，提示在可信分支落地后刷新镜像。各 job 仍各自运行一次干净的根 `npm ci`，以唯一 workspace lock 校验全部 App/package/tool 依赖并隔离 PR 依赖；统一通过 `scripts/ci-npm-ci-with-retry.sh` 最多执行 3 次整命令级有界重试，并使用镜像内 npm cache 和 `prefer-offline`。锁文件新增依赖时允许经受控网络补齐，本阶段不启用共享 Actions cache。
 
@@ -89,17 +103,25 @@ runner 配置保留原 `ubuntu-latest` 映射，`genarrative-ci` 继续映射到
 2. 执行 `load-runner`，确认该 ID 已进入 runner 内层 Docker。
 3. 确认没有活跃 job，将当前 runner config 备份到仓库外的受控位置；备份不得进入 Git，也不得在文档或日志中回显注册信息。
 4. 增加或替换 `genarrative-ci` 的精确 `docker://<Image ID>` 映射，然后执行 `docker restart --timeout 660 gitea-runner`。
-5. 重跑真实 PR 的四个 CI job；全部通过且隔离边界复核完成后，才能清理旧镜像。
+5. 用真实 CI 的九个 job 验证新镜像；全部通过且隔离边界复核完成后，才能清理旧镜像。
 
 `docker restart --timeout 660` 只提供容器停止宽限，不是 Runner drain API；rootless DinD 的 supervisor 可能与 runner 同时停止内层 dockerd。重启前必须同时确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空，不能依赖该 timeout 等待活跃 job。
 
 回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复备份的 runner config 并用同一超时重启 runner。不要在真实 CI 验证前删除旧映射或旧镜像。
 
-### 可选的 AGC Rust 编译对象快照
+### Rust 测试组编译对象快照
 
-`scripts/build-gitea-rust-cache.sh` 在已验证的 job 镜像上生成候选镜像，供 AGC Rust lane 1 试验；lane 2 保持直接 rustc。固定 sccache `0.18.0` 的 Linux x64 musl 归档并校验 SHA-256，维护者从 origin/master 的确定提交预热编译对象，PR job 没有生成/发布公共快照的权限。
+自动维护由宿主 systemd timer 调用 `scripts/maintain-gitea-rust-cache.py`，只管理 Gitea CI 测试镜像，不修改 Jenkins、生产发布、本地开发或客户端发行构建。六个 Rust job 仅在 master push 中导出本次 CI 新增的 sccache 对象；已命中的继承对象只上传新近使用时间，通过 Gitea 原生 V4 artifact 接口上传；PR 不发布。维护器选择已结束且六组产物完整的最新 master run，校验提交、任务尝试、工具链与来源镜像，与六组实际使用的同一镜像快照合并去重，并按新近使用时间限制快照总容量为 4 GiB，然后从无对象缓存基础镜像组装新镜像，**不重复执行 Cargo 预热编译，也不要求源 run 事先全绿**。缺组、取消或校验失败时保留现役版，不混合不同 run 的对象来假装完整快照。
 
-基础镜像必须不含 `/opt/genarrative-ci/rust-cache`；脚本在拉取源码、下载工具和预热前执行只读、断网检查，发现已有对象快照就拒绝构建。不能在旧缓存镜像上删除目录再叠加新快照，删除操作不会释放旧镜像层。切换且真实 CI 验证通过后，人工定向清理更旧的缓存镜像与导出归档，保留当前版、一个回滚版及运行中 CI 使用的版本；2 GiB 对象缓存上限不覆盖这些宿主文件，不使用全局 prune。
+维护 journal 分阶段记录来源 run、基础镜像重建或复用、artifact 下载、对象合并、镜像组装校验、导出、载入及空闲等待；长操作记录开始和结束耗时，失败输出对应私有 `artifacts/<source-sha>/build.log` 路径。构建的详细下载与 Docker 输出仍只写该日志，不回显 Token、命令环境或认证配置。
+
+切换先通过专属入口阻断新的 FetchTask，确认已转发的领取请求全部收到完整上游响应，并检查入口持久化跟踪的已领取任务全部结束、内层 Docker 没有活动容器。任务终态必须依据 Runner 的执行结束及最终上报协议，不能由容器暂时为空、API 已取消或请求超时推断。有任务即恢复领取并延后，不停止任务；状态未知拒绝切换。维护器只需普通账号的 `write:repository` Token（包括查询、下载及定向删除 artifact），不访问全局 Runner 管理 API。切换后等待使用该 Image ID 的完整真实 master push CI 通过，才允许下一次升级及旧镜像清理；不会自动重跑失败用例或为了验收额外触发整轮 CI。首次接管的历史镜像默认不归自动清理管理。
+
+维护状态、凭据、归档和配置备份保存在仓库外。当前版、回滚版、待验证候选、它们的基础镜像及容器引用的镜像均受保护。清理只针对维护器登记的专属 tag、完整 Image ID 和专用目录中的归档；禁止全局 prune。API、构建、验证或空闲检查失败时保留现役镜像与回滚资料，不以失败重跑制造全绿结果。
+
+`scripts/build-gitea-rust-cache.sh` 仅用于首次缺少可消费快照时的人工 bootstrap，在已验证的 job 镜像上生成候选镜像，覆盖 AGC Rust 两条 lane、crates、agent-run smoke、Backend 和 Native shell 的桌面壳测试。Native shell 的 release build smoke 显式清空两个 wrapper，不消费测试快照。固定 sccache `0.18.0` 的 Linux x64 musl 归档并校验 SHA-256，维护者从 origin/master 的确定提交预热编译对象，PR job 没有生成/发布公共快照的权限。
+
+基础镜像必须不含 `/opt/genarrative-ci/rust-cache`；脚本在拉取源码、下载工具和预热前执行只读、断网检查，发现已有对象快照就拒绝构建。不能在旧缓存镜像上删除目录再叠加新快照，删除操作不会释放旧镜像层。切换且真实 CI 验证通过后，维护器定向清理自己登记的更旧缓存镜像与导出归档，保留当前版、一个回滚版、所需基础镜像及容器引用的版本；接管前的试验镜像/归档仍由维护者确认后人工清理。对象缓存上限不覆盖这些宿主文件，不使用全局 prune，也不清理其它构建的 Docker build cache。
 
 ```bash
 bash scripts/build-gitea-rust-cache.sh genarrative/gitea-project-ci:20260920.2 genarrative/gitea-project-ci:rust-cache-candidate
@@ -108,13 +130,62 @@ bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/ci-rust-cache.t
 bash scripts/gitea-ci-job-image.sh load-runner genarrative/gitea-project-ci:rust-cache-candidate
 ```
 
-预热容器上限为 4 核、12 GiB，移除 capabilities，不挂宿主目录/socket，也不注入 Git/OSS/Jenkins 凭据。源码通过 `git archive` 复制，当前工作区、ignored 文件和 `.git` 不进入容器。最终从原镜像重新组装，仅复制 `/opt/genarrative-ci/rust-cache` 的 sccache、对象和来源元数据，不提交含源码/target 的预热容器；镜像本身的下载缓存与工具链校验保持原样。
+自动维护不调用预热脚本；以下人工 bootstrap 脚本接受第三个参数 `<完整 master SHA>`。脚本确认该 SHA 是抓取到的 master 祖先，源码和 `ci-rust-cache.sh` 均来自该提交；两参数人工调用仍默认使用最新 master。基础镜像的 `revision` 由同一份 build context 清单计算；输入变化时维护器先生成新的无对象缓存基础镜像。Rust 输入指纹保守包含代码、配置、资源、脚本和内嵌 skill，仅排除一般 `docs/` 及几个根说明文档，`docs/openapi/` 始终参与。
 
-快照由固定 Image ID 分发，每个 job 仅修改容器自己的写时复制层，缓存上限 2 GiB，结束后不回传。`ci-rust-cache.sh prepare` 清空继承的 `SCCACHE_*` 远程配置，使用独立配置和 Unix socket；旧镜像、工具链不匹配或限时 wrapper 探测失败时使用直接 rustc，正式编译启用 sccache 的 server IO 错误回退。真实编译/测试失败保留非零退出码。`report` 输出命中统计并停止本 job daemon，分片日志输出独立编译耗时。
+缓存产物通过六个 `Publish master Rust cache artifact` 步骤发布，daemon 成功停止才导出。源 run 必须结束，且六组为 success/failure 并有完整上传证据；整轮或任一 Rust 组取消、旧 attempt、缺组、混用来源镜像均不采用。上传失败仅告警，不改变测试结论。每组仅导出相对其启动快照的新 key，命中只上报触达时间；宿主按真实 job 日志确认同一来源 Image ID，再复用其对象，不信任产物中的可执行文件。合并校验 tar/zip 路径、对象大小与 SHA256，同 key 内容冲突拒绝发布。sccache 可执行文件取自可信来源镜像，不从 artifact 执行代码。
 
-生成候选不会改变 runner 配置。线上有活跃 CI 时禁止停止 job、重启 runner 或切换标签；只在确认空闲后按上节流程切换固定 Image ID。先用相同源码、独立干净 target 比较无缓存、冷缓存、热缓存，真实 CI 验收通过后再考虑推广。回滚缓存试验可以移除 lane 1 的 prepare/report，或恢复原镜像 ID，均不需要改变 incremental 或测试分片。
+候选已校验、导出并装载内层 Docker 后，可定向删除该 run 已收集的六份上传产物；旧镜像清理仍须等真实 CI 验证。专属缓存 artifact 保留 7 天，宿主也清理超过 7 天且源 run 已结束的遗留项，不删普通构建产物、run 或日志。Gitea 1.26.4 不清理未 finalized 的上传块：上传器使用专属双层编码块标识，宿主从 `artifact_storage_dir/tmp-upload/run-<id>-v4/` 定向清理本上传器的普通文件，要求所属仓库 master run 已结束超过 7 天且文件本身也超过 7 天。未知、年轻、符号链接或不属于本上传器的文件受到保护，不改数据库、不删除目录。已完成产物通过 API 删除；未完成上传留下的数据库元数据仍归 Gitea 管理。宿主的未完成下载/合并临时文件仅在登记的私有目录内清理。
 
-预热路径固定为实际 Gitea checkout 的 `/workspace/GenarrativeAI/Genarrative`，Cargo 从 AGC `src-tauri` 目录启动；`workspace.txt` 不匹配时直接编译。Rust cache key 对 cwd 敏感，不能假定 `SCCACHE_BASEDIRS` 足以跨路径复用。固定 sccache `0.18.0` 返回基础设施错误码 `2` 时 wrapper 只回退这一次 rustc 调用，其它状态原样返回，不重跑测试。
+### 自动维护首次部署与恢复
+
+首次部署在本变更合入 master 后进行。维护脚本安装到 `/opt/genarrative-ci-cache/scripts/`；运行状态、源码专用 clone、日志和归档放在 `/var/lib/genarrative-ci-cache/`，token 放在 `/etc/genarrative-ci-cache/api-token`（root 所有、0600），均不进入 Git。复制 `gitea-ci-cache.config.example.json` 为该目录的 `config.json` 并核实仓库、Runner 容器与网关地址。Token 使用具有目标仓库 Actions 读写权限的普通账号，授予 `write:repository` 即可，不需要 `admin`；写操作仅定向删除本维护器的缓存 artifact，不重跑或取消任务。宿主运行账号还须能通过 `clone_url` 拉取专属 clone，API Token 不自动传给 Git。`artifact_storage_dir` 必须指向当前 Gitea 本地 ActionsArtifacts 存储的真实宿主路径（不是容器路径）；按当前 `/data` bind mount 和 `APP_DATA_PATH`，模板为 `/opt/gitea-stack/data/gitea/gitea/actions_artifacts`。部署时由 root 核实路径与 Gitea `[actions.artifacts]`/storage 配置一致，不能指向其它目录；此残块清理实现只支持本地存储，外部对象存储需要另行适配。
+
+领取入口由 `gitea-runner-fetch-gate.compose.yml` 启动，使用已验证且含 Python 3 的无对象缓存 CI Image ID（`GITEA_FETCH_GATE_IMAGE`）。它只连接现有 `gitea-actions` 内部网络，不发布宿主端口、不挂 Docker socket；仅转发 `/api/actions/` RPC，控制 socket 位于独立私有目录 `/var/lib/genarrative-ci-cache-gate/`。该目录必须由 root 持有且权限为 0700。普通 job 无法访问控制 socket。部署前先运行下述测试，不直接启用 timer。
+
+```bash
+python3 -m unittest discover -s scripts -p 'test_gitea_cache_*.py'
+install -d -m 700 /etc/genarrative-ci-cache /var/lib/genarrative-ci-cache /var/lib/genarrative-ci-cache-gate
+install -d /opt/genarrative-ci-cache/scripts
+install -m 755 scripts/maintain-gitea-rust-cache.py scripts/gitea-runner-fetch-gate.py /opt/genarrative-ci-cache/scripts/
+install -m 644 scripts/gitea_cache_snapshot.py scripts/gitea_cache_upload_cleanup.py /opt/genarrative-ci-cache/scripts/
+install -m 600 deploy/container/gitea-ci-cache.config.example.json /etc/genarrative-ci-cache/config.json
+# 由维护者写入 write:repository API token，并核实 config.json；不要在终端回显 token。
+# 设置 GITEA_FETCH_GATE_IMAGE 为已验证基础镜像的完整 Image ID 后：
+docker compose -f deploy/container/gitea-runner-fetch-gate.compose.yml up -d
+```
+
+**首次接入或从不跟踪任务的旧网关升级，需要空闲维护窗口**：确认无活跃 CI 且暂停新 CI 触发，再备份现有 runner 配置和注册文件，在 runner 部署的 `GITEA_INSTANCE_URL` 及 `/data/.runner` 的 `address` 中改用 `http://gitea-runner-fetch-gate:8080`，保留其余注册字段；runner 进程的 `NO_PROXY` / `no_proxy` 必须加入 `gitea-runner-fetch-gate`。同时在 `/data/config.yaml` 的 `runner.envs` 中设置 `GENARRATIVE_GITEA_REPOSITORY_URL: "http://genarrative-station/git/GenarrativeAI/Genarrative.git"`，与维护器的 `repository_url` 一致。当前 job 通过 `--add-host=genarrative-station:172.30.0.3` 访问现有 actions gateway，job 的代理例外保留 `genarrative-station`；runner 自身能访问的 `http://gitea:3000` 不代表内层 job 也能访问。此专用变量也覆盖旧 PR 的 checkout；不要用同名 GITHUB_SERVER_URL 环境变量代替，Runner 会再次覆盖它。按原流程重启并验证 runner 注册。
+
+维护器的 `clone_url` 属于宿主网络：当前 Gitea 将容器 3000 映射到宿主 3003，因此使用 `http://127.0.0.1:3003/GenarrativeAI/Genarrative.git`，避免本机完整 clone 绕公网导致 900 秒超时；不要把这个 loopback 地址传给 job。其它部署必须按实际端口核实。`api_url` 仍使用 HTTPS 公开 API 地址。
+
+内层 Docker 的默认地址池必须避开外层 `gitea-actions` 的 `172.30.0.0/24` 和 egress 的 `172.31.0.0/24`。当前 `/opt/gitea-stack/config/runner-dockerd-run` 在 dockerd 参数中设置 `--default-address-pool base=10.240.0.0/16,size=24`，每个 job 获得独立 `/24`。变更在 runner 重启后生效，只影响新网络；先逐个检查并定向删除无容器引用的 `GITEA-ACTIONS-TASK-*` 遗留网络，不能全局 prune。取消或强制停止 runner 可能留下空网络，默认 Docker `/16` 地址池累积到 `172.30.0.0/16` 会截走网关流量。
+
+恢复领取前，必须在内层 Docker 新建与 job 相同的 bridge，使用现役 CI Image ID、相同 host 映射和代理环境，实际执行 `genarrative-gitea-checkout` 并访问 `http://genarrative-station/git/api/v1/version`；同时确认新网络使用上述 `/24` 地址池。仅宿主 `git ls-remote`、runner 注册成功或 FetchTask 路由通过，均不能替代 job 网络验收。
+
+不能仅改磁盘文件却不让进程加载；维护器还会检查独立 checkout URL，并确认入口实际见到了当前容器本次启动后的 FetchTask 来源 IP。此一次接入不由维护器冒险猜测空闲，也不对运行中 CI 动手。实例 API 根地址仍使用配置中的 HTTPS Gitea 地址，不能指向只支持 runner RPC 的入口。上传脚本从独立 `GENARRATIVE_GITEA_REPOSITORY_URL` 推导真实 Gitea 地址，使用本任务临时凭据调用原生 V4 API；不依赖被网关覆盖的 `GITHUB_SERVER_URL` / `ACTIONS_RUNTIME_URL`。Gitea 1.26.4 的仓库 REST 下载接口只支持 V4，不能换回 V3 上传。宿主下载只跟随同一 HTTPS Gitea origin 的签名重定向，不转发长期 Token；如配置外部对象存储直出，需另行适配下载来源。
+
+```bash
+# --apply 缺省时只检查 API、runner、master 和入口路径，不修改配置或镜像。
+python3 /opt/genarrative-ci-cache/scripts/maintain-gitea-rust-cache.py --config /etc/genarrative-ci-cache/config.json
+install -m 644 deploy/systemd/genarrative-ci-cache.service deploy/systemd/genarrative-ci-cache.timer /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now genarrative-ci-cache.timer
+journalctl -u genarrative-ci-cache.service -n 50
+```
+
+timer 在上次执行结束后约 5 分钟再次检查，文件锁防止人工与定时执行重叠。构建日志位于状态目录 `artifacts/<SHA>/build.log`。同一 run 组装失败后不每 5 分钟重复消耗资源；新的完整 master run 到来后自动尝试，也可修复环境后显式运行 `--apply --retry`。切换事务及暂停归属先落状态文件；`ExecStopPost --resume` 恢复本维护器暂停的领取，下次执行再收敛中断的切换。其它人暂停的入口不由维护器擅自恢复；不修改 Gitea 的 Runner disabled 设置。
+
+候选切换后的验收读取真实 **master push** 的完整九个 job，要求全部 success、每个 job 均使用目标 Image ID，六个 Rust job 有启用缓存、正命中数和零缓存错误。测试失败、旧 PR 缺 prepare、混用镜像或缺日志均不清理旧版，也不伪造“缓存已验收”。仍保留源代码失败需要修复的原始结果。
+
+入口遇到“已发送 FetchTask，但上游响应未完整结束”会持久化 `uncertain` 并拒绝继续领取/自动切换；不会因为客户端的 5 秒超时就认定服务端事务已回滚。其它 RPC 和任务上报仍继续转发。维护者需先核实 Gitea 在途领取事务与该 runner 的任务全部收敛，在维护窗口停止入口，核实并修复它的 `tasks.json` 任务账本及 `uncertain` / `inflight` 标记后再启动并恢复领取。网关按 Gitea 1.26.4 / Runner 2.0.0 的 Connect Protobuf 协议，在最终日志确认及 Runner 执行结束后的最终任务上报确认后才清账；取消响应不等于进程停止，任务 ID 不按超时自动删除。禁止自动删这些标记绕过屏障。停用自动维护先 `systemctl disable --now genarrative-ci-cache.timer`；不要为了停 timer 停止运行中的 CI 容器。已接入的领取入口继续运行，不影响普通 CI。
+
+人工 bootstrap 预热容器上限为 4 核、12 GiB，移除 capabilities，不挂宿主目录/socket，也不注入 Git/OSS/Jenkins 凭据。源码通过 `git archive` 复制，当前工作区、ignored 文件和 `.git` 不进入容器。最终从原镜像重新组装，仅复制 `/opt/genarrative-ci/rust-cache` 的 sccache、对象和来源元数据，不提交含源码/target 的预热容器；镜像本身的下载缓存与工具链校验保持原样。
+
+快照由固定 Image ID 分发，每个 job 仅修改容器自己的写时复制层，缓存上限 4 GiB，只有 master push 在结束前回传新增对象；PR 不扫描基线、不打包、不回传。`ci-rust-cache.sh prepare` 清空继承的 `SCCACHE_*` 远程配置，使用独立配置和 Unix socket；旧镜像、工具链不匹配或限时 wrapper 探测失败时使用直接 rustc，正式编译启用 sccache 的 server IO 错误回退。真实编译/测试失败保留非零退出码。`report` 输出命中统计并停止本 job daemon，分片日志输出独立编译耗时。sccache 0.18.0 的只读模式在 miss 后仍打包再拒绝写入，不能用它宣称零 miss 开销；普通 CI 继续只向容器层写入。
+
+生成候选不会改变 runner 配置。线上有活跃 CI 时禁止停止 job、重启 runner 或切换标签；只在确认空闲后按上节流程切换固定 Image ID。全组启用须重建完整快照；旧 AGC 单目标快照不能作为其它组预热成功的证据。按组用相同源码、独立干净 target 比较编译命中与耗时；分片测试内容和前置检查不同，不能直接用两条 lane 总耗时推断缓存收益。回滚时可移除各 job 的 prepare/report，或恢复无对象缓存的原基础镜像 ID，均不需要改变 incremental 或测试分片。
+
+预热路径固定为实际 Gitea checkout 的 `/workspace/GenarrativeAI/Genarrative`：后端、独立 crate、插件、桌面壳和提示词契约从仓库根目录启动 Cargo；AGC 分片从 `src-tauri` 启动；agent-run smoke 从 AGC App 根目录启动。切换 AGC cwd 前仅清理预热容器内的 AGC target，避免 Cargo 的 fresh 判断跳过新 cwd 的对象。后端 workspace 与 spacetime-module 保持分开编译，测试仅 `--no-run`，smoke 仅 `cargo build`。`workspace.txt` 不匹配时直接编译。Rust cache key 对 cwd 敏感，不能假定 `SCCACHE_BASEDIRS` 足以跨路径复用。固定 sccache `0.18.0` 返回基础设施错误码 `2` 时 wrapper 只回退这一次 rustc 调用，其它状态原样返回，不重跑测试。
 
 ## 启动与验证
 
diff --git a/deploy/container/gitea-ci-buildkitd.toml b/deploy/container/gitea-ci-buildkitd.toml
new file mode 100644
index 000000000..5da73da8d
--- /dev/null
+++ b/deploy/container/gitea-ci-buildkitd.toml
@@ -0,0 +1,18 @@
+# 专用于 Gitea CI 基础镜像；不调整宿主 Docker 或其它 builder 的 GC。
+[worker.oci]
+  gc = true
+  reservedSpace = "4GB"
+  maxUsedSpace = "24GB"
+  minFreeSpace = "10GB"
+
+  # 覆盖默认的 48 小时 / 488 MiB 临时缓存回收规则，周末后仍可命中下载包。
+  [[worker.oci.gcpolicy]]
+    filters = ["type==exec.cachemount"]
+    keepDuration = "168h"
+    maxUsedSpace = "8GB"
+
+  [[worker.oci.gcpolicy]]
+    all = true
+    reservedSpace = "4GB"
+    maxUsedSpace = "24GB"
+    minFreeSpace = "10GB"
diff --git a/deploy/container/gitea-ci-cache.config.example.json b/deploy/container/gitea-ci-cache.config.example.json
new file mode 100644
index 000000000..9b21303ed
--- /dev/null
+++ b/deploy/container/gitea-ci-cache.config.example.json
@@ -0,0 +1,12 @@
+{
+  "api_url": "https://git.genarrative.world/git/api/v1",
+  "repository": "GenarrativeAI/Genarrative",
+  "repository_url": "http://genarrative-station/git/GenarrativeAI/Genarrative.git",
+  "clone_url": "http://127.0.0.1:3003/GenarrativeAI/Genarrative.git",
+  "runner_container": "gitea-runner",
+  "token_file": "/etc/genarrative-ci-cache/api-token",
+  "state_dir": "/var/lib/genarrative-ci-cache",
+  "artifact_storage_dir": "/opt/gitea-stack/data/gitea/gitea/actions_artifacts",
+  "gate_socket": "/var/lib/genarrative-ci-cache-gate/gate.sock",
+  "gate_url": "http://gitea-runner-fetch-gate:8080"
+}
diff --git a/deploy/container/gitea-ci-job.Dockerfile b/deploy/container/gitea-ci-job.Dockerfile
index ec94382f6..cc5433557 100644
--- a/deploy/container/gitea-ci-job.Dockerfile
+++ b/deploy/container/gitea-ci-job.Dockerfile
@@ -8,6 +8,16 @@ RUN rustup component add rustfmt \
     && cargo --version \
     && rustfmt --version
 
+# 显式的一次性迁移入口：只导入下载缓存，不继承旧 CI 镜像层。
+FROM rust-toolchain AS download-cache-seed
+RUN --mount=type=bind,from=download-seed,target=/seed \
+    --mount=type=cache,id=genarrative-ci-cargo-cache-v1,target=/downloads/cargo-cache,sharing=locked \
+    --mount=type=cache,id=genarrative-ci-cargo-index-v1,target=/downloads/cargo-index,sharing=locked \
+    --mount=type=cache,id=genarrative-ci-npm-v1,target=/downloads/npm,sharing=locked \
+    cp -a /seed/cargo-cache/. /downloads/cargo-cache/ \
+    && cp -a /seed/cargo-index/. /downloads/cargo-index/ \
+    && cp -a /seed/npm/. /downloads/npm/
+
 FROM rust-toolchain AS rust-dependency-cache
 
 ENV CARGO_HTTP_MULTIPLEXING=false \
@@ -20,7 +30,9 @@ COPY plugins/agc-cocos-editor/native/cocos-editor-bridge /tmp/genarrative-cargo-
 COPY plugins/agc-unity-editor/native/unity-editor-bridge /tmp/genarrative-cargo-cache/plugins/agc-unity-editor/native/unity-editor-bridge
 COPY plugins/agc-godot-editor/native/godot-editor-bridge /tmp/genarrative-cargo-cache/plugins/agc-godot-editor/native/godot-editor-bridge
 
-RUN find /tmp/genarrative-cargo-cache -name Cargo.toml -exec dirname {} \; \
+RUN --mount=type=cache,id=genarrative-ci-cargo-cache-v1,target=/usr/local/cargo/registry/cache,sharing=locked \
+    --mount=type=cache,id=genarrative-ci-cargo-index-v1,target=/usr/local/cargo/registry/index,sharing=locked \
+    find /tmp/genarrative-cargo-cache -name Cargo.toml -exec dirname {} \; \
         | while IFS= read -r crate_dir; do \
             mkdir -p "${crate_dir}/src"; \
             : > "${crate_dir}/src/lib.rs"; \
@@ -53,6 +65,16 @@ RUN find /tmp/genarrative-cargo-cache -name Cargo.toml -exec dirname {} \; \
     && CARGO_NET_OFFLINE=true cargo fetch --locked \
         --target x86_64-unknown-linux-gnu \
         --manifest-path /tmp/genarrative-cargo-cache/apps/ai-game-creator-shell/src-tauri/Cargo.toml \
+    && mkdir -p /opt/ci-downloads/registry/cache \
+    && cp -a /usr/local/cargo/registry/index /opt/ci-downloads/registry/ \
+    && for source in /usr/local/cargo/registry/src/*/*; do \
+        [ -d "${source}" ] || continue; \
+        registry="$(basename "$(dirname "${source}")")"; \
+        package="$(basename "${source}")"; \
+        mkdir -p "/opt/ci-downloads/registry/cache/${registry}"; \
+        cp "/usr/local/cargo/registry/cache/${registry}/${package}.crate" \
+           "/opt/ci-downloads/registry/cache/${registry}/" || exit 1; \
+    done \
     && rm -rf /tmp/genarrative-cargo-cache
 
 FROM ${RUNNER_IMAGE}
@@ -127,6 +149,7 @@ RUN node_archive="node-v${NODE_VERSION}-linux-x64.tar.xz" \
     && ln -sfn /usr/local/lib/genarrative-node/bin/corepack /usr/local/bin/corepack
 
 COPY --from=rust-dependency-cache /usr/local/cargo /usr/local/cargo
+COPY --from=rust-dependency-cache /opt/ci-downloads/registry /usr/local/cargo/registry
 COPY --from=rust-dependency-cache /usr/local/rustup /usr/local/rustup
 
 ARG NPM_LOCK_SHA256
@@ -148,10 +171,12 @@ COPY server-rs/Cargo.lock /usr/local/share/genarrative-ci/locks/server-rs.Cargo.
 COPY apps/desktop-shell/src-tauri/Cargo.lock /usr/local/share/genarrative-ci/locks/desktop-shell.Cargo.lock
 COPY apps/ai-game-creator-shell/src-tauri/Cargo.lock /usr/local/share/genarrative-ci/locks/ai-game-creator-shell.Cargo.lock
 COPY deploy/container/gitea-ci-checkout.sh /usr/local/bin/genarrative-gitea-checkout
+COPY scripts/export-ci-npm-download-cache.mjs /usr/local/share/genarrative-ci/export-npm-cache.mjs
 
 # npm registry 偶发 ECONNRESET，镜像预热也需要整命令级有界重试；
 # 失败重试复用同一 npm cache，不会重复下载已完成的包。
-RUN test -n "${NPM_LOCK_SHA256}" \
+RUN --mount=type=cache,id=genarrative-ci-npm-v1,target=/var/cache/genarrative-ci-npm,sharing=locked \
+    test -n "${NPM_LOCK_SHA256}" \
     && test -n "${SERVER_RUST_LOCK_SHA256}" \
     && test -n "${DESKTOP_RUST_LOCK_SHA256}" \
     && test -n "${AGC_RUST_LOCK_SHA256}" \
@@ -175,6 +200,7 @@ RUN test -n "${NPM_LOCK_SHA256}" \
     && npm_ci_with_retry() { \
         for attempt in 1 2 3 4 5; do \
             if npm ci \
+                --cache /var/cache/genarrative-ci-npm \
                 --ignore-scripts \
                 --no-audit \
                 --no-fund \
@@ -194,6 +220,12 @@ RUN test -n "${NPM_LOCK_SHA256}" \
         /usr/local/share/genarrative-ci/npm/apps/*/node_modules \
         /usr/local/share/genarrative-ci/npm/packages/*/node_modules \
         /usr/local/share/genarrative-ci/npm/tools/*/node_modules \
+    && rm -rf /root/.npm/_cacache \
+    && mkdir -p /root/.npm/_cacache \
+    && node /usr/local/share/genarrative-ci/export-npm-cache.mjs \
+        /usr/local/lib/genarrative-node/lib/node_modules/npm \
+        /usr/local/share/genarrative-ci/npm/package-lock.json \
+        /var/cache/genarrative-ci-npm/_cacache /root/.npm/_cacache \
     && npm cache verify
 
 # 依赖预热会在 workspace 内解析出 Node 发行包自带的 npm（例如 10.9.8），
diff --git a/deploy/container/gitea-ci-job.Dockerfile.dockerignore b/deploy/container/gitea-ci-job.Dockerfile.dockerignore
index 43bc93a4c..edcf31154 100644
--- a/deploy/container/gitea-ci-job.Dockerfile.dockerignore
+++ b/deploy/container/gitea-ci-job.Dockerfile.dockerignore
@@ -3,6 +3,9 @@
 !deploy/container/
 !deploy/container/gitea-ci-job.Dockerfile
 !deploy/container/gitea-ci-checkout.sh
+!deploy/container/gitea-ci-buildkitd.toml
+!scripts/
+!scripts/export-ci-npm-download-cache.mjs
 !package.json
 !package-lock.json
 !server-rs/
@@ -19,6 +22,9 @@
 !apps/ai-game-creator-shell/src-tauri/
 !apps/ai-game-creator-shell/src-tauri/Cargo.toml
 !apps/ai-game-creator-shell/src-tauri/Cargo.lock
+!apps/ai-game-creator-shell/src-tauri/vendor/
+!apps/ai-game-creator-shell/src-tauri/vendor/*/
+!apps/ai-game-creator-shell/src-tauri/vendor/*/Cargo.toml
 !apps/desktop-shell/
 !apps/desktop-shell/package.json
 !apps/desktop-shell/src-tauri/
@@ -48,4 +54,4 @@
 !plugins/agc-godot-editor/
 !plugins/agc-godot-editor/native/
 !plugins/agc-godot-editor/native/godot-editor-bridge/
-!plugins/agc-*-editor/native/*-editor-bridge/**
+!plugins/agc-*-editor/native/*-editor-bridge/Cargo.toml
diff --git a/deploy/container/gitea-runner-fetch-gate.compose.yml b/deploy/container/gitea-runner-fetch-gate.compose.yml
new file mode 100644
index 000000000..f97c433d0
--- /dev/null
+++ b/deploy/container/gitea-runner-fetch-gate.compose.yml
@@ -0,0 +1,23 @@
+# 只加入 runner 与 Gitea 共用的内部网络，不发布端口，不挂 Docker socket。
+services:
+  gitea-runner-fetch-gate:
+    image: ${GITEA_FETCH_GATE_IMAGE:?Set a verified no-object-cache CI image ID with Python 3}
+    container_name: gitea-runner-fetch-gate
+    restart: unless-stopped
+    entrypoint: ['python3', '/app/gitea-runner-fetch-gate.py']
+    environment:
+      GITEA_RUNNER_UPSTREAM: http://gitea:3000
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    cpus: 0.5
+    mem_limit: 256m
+    pids_limit: 128
+    volumes:
+      - /opt/genarrative-ci-cache/scripts/gitea-runner-fetch-gate.py:/app/gitea-runner-fetch-gate.py:ro
+      - /var/lib/genarrative-ci-cache-gate:/control
+    networks: [gitea-actions]
+
+networks:
+  gitea-actions:
+    external: true
diff --git a/deploy/nginx/README.md b/deploy/nginx/README.md
index e6fe4ca99..c3c4bff34 100644
--- a/deploy/nginx/README.md
+++ b/deploy/nginx/README.md
@@ -99,3 +99,11 @@ curl -sSI -H 'Accept-Encoding: br' \
 - gzip 可用时返回 `Content-Encoding: gzip`。
 - br 可用时返回 `Content-Encoding: br`。
 - 响应头应包含 `Vary: Accept-Encoding`。
+
+## 游戏发行来源（每游戏独立 origin）
+
+- `deploy/nginx/genarrative-release-origin.conf` 为已公开游戏提供每游戏独立来源：`https://<gameId>.games.example.com/`。部署前替换域名、通配证书路径与 upstream 端口，并为 `*.games.example.com` 配置通配 DNS 与通配 TLS。
+- 该来源只把子域根路径映射到 `…/releases/<gameId>/index.html`、其余路径映射到 `…/releases/<gameId>/<原路径>`；平台 API、后台、SPA 与上传接口都不在这个来源上暴露，命中即 404。
+- 发行来源不使用 Cookie：带 `Cookie` 的请求在边缘直接 403，转发前也会 `proxy_set_header Cookie ""`。响应头（`X-Content-Type-Options`、CORP、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate`）由 `api-server` 发行网关设置，边缘不覆盖。
+- 审核通过时填写的 `entryUrl` 就是该子域根地址 `https://<gameId>.games.example.com/`；换版本或下架只改变后端公开投影，边缘不需要改配置。
+- 门禁：`npm run check:release-origin-config` 会逐条校验模板约束、交叉检查发行网关仍在设置上述响应头，并在本机存在 `nginx` 与 `openssl` 时用自签通配证书渲染一份临时配置执行 `nginx -t`。
diff --git a/deploy/nginx/genarrative-release-origin.conf b/deploy/nginx/genarrative-release-origin.conf
new file mode 100644
index 000000000..5e120726d
--- /dev/null
+++ b/deploy/nginx/genarrative-release-origin.conf
@@ -0,0 +1,80 @@
+# 游戏发行来源（每游戏独立 origin）
+#
+# 部署前替换：
+#   1) `games.example.com` 为真实发行域，并为 `*.games.example.com` 配置通配 DNS
+#      与通配 TLS 证书；
+#   2) `ssl_certificate` / `ssl_certificate_key` 指向该通配证书；
+#   3) upstream 端口与 api-server 实际监听一致。
+#
+# 设计约定：
+#   - 每个已公开游戏使用自己的子域：`https://<gameId>.games.example.com/`；
+#   - 该来源只把请求映射到发行网关
+#     `/api/game-distribution/releases/<gameId>/…`，平台 API、后台、SPA 与上传
+#     接口都不在这个来源上暴露；
+#   - 发行来源从不使用 Cookie：带 Cookie 的请求直接 403，转发前也会清空 Cookie；
+#   - `X-Content-Type-Options` / CORP / 无凭据 CORS / HTML CSP / 内容类型白名单由
+#     api-server 发行网关设置，这里不覆盖，避免两层策略漂移；
+#   - 公开版本切换与下架由后端 `publication_revision` CAS 决定，边缘只做按主机映射。
+
+upstream genarrative_release_api {
+    server 127.0.0.1:8082;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    server_name ~^(?<game_id>[a-z0-9_]+)\.games\.example\.com$;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    server_name ~^(?<game_id>[a-z0-9_]+)\.games\.example\.com$;
+
+    ssl_certificate /etc/letsencrypt/live/games.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/games.example.com/privkey.pem;
+
+    access_log /var/log/nginx/genarrative-release.access.log;
+    error_log /var/log/nginx/genarrative-release.error.log warn;
+
+    # 发行文件是公开静态资源，从不携带平台 Cookie。带上 Cookie 的请求说明它落在
+    # 平台会话来源上，直接拒绝，避免发行内容被主站同源脚本读取。
+    if ($http_cookie) {
+        return 403;
+    }
+
+    # 子域根路径直接服务该游戏的 index.html，游戏内其余资源按相对路径原样交给
+    # 发行网关；这样审核通过时填写的 entryUrl 就是 https://<gameId>.games.example.com/。
+    location = / {
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Request-Id $request_id;
+        proxy_set_header Cookie "";
+        proxy_pass http://genarrative_release_api/api/game-distribution/releases/$game_id/index.html;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 60s;
+    }
+
+    location / {
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Request-Id $request_id;
+        proxy_set_header Cookie "";
+        proxy_pass http://genarrative_release_api/api/game-distribution/releases/$game_id$request_uri;
+        proxy_read_timeout 60s;
+        proxy_send_timeout 60s;
+    }
+}
diff --git a/deploy/systemd/genarrative-ci-cache.service b/deploy/systemd/genarrative-ci-cache.service
new file mode 100644
index 000000000..b7e0934b7
--- /dev/null
+++ b/deploy/systemd/genarrative-ci-cache.service
@@ -0,0 +1,22 @@
+[Unit]
+Description=Refresh and retain trusted Gitea CI Rust cache images
+After=network-online.target docker.service
+Wants=network-online.target
+Requires=docker.service
+ConditionPathExists=/etc/genarrative-ci-cache/config.json
+
+[Service]
+Type=oneshot
+User=root
+WorkingDirectory=/opt/genarrative-ci-cache
+UMask=0077
+ExecStart=/usr/bin/python3 /opt/genarrative-ci-cache/scripts/maintain-gitea-rust-cache.py --config /etc/genarrative-ci-cache/config.json --apply
+ExecStopPost=/usr/bin/python3 /opt/genarrative-ci-cache/scripts/maintain-gitea-rust-cache.py --config /etc/genarrative-ci-cache/config.json --resume
+TimeoutStartSec=3h
+TimeoutStopSec=60s
+Nice=10
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7
+
+[Install]
+WantedBy=multi-user.target
diff --git a/deploy/systemd/genarrative-ci-cache.timer b/deploy/systemd/genarrative-ci-cache.timer
new file mode 100644
index 000000000..417aa54e4
--- /dev/null
+++ b/deploy/systemd/genarrative-ci-cache.timer
@@ -0,0 +1,11 @@
+[Unit]
+Description=Check for new Gitea CI compilation inputs
+
+[Timer]
+OnBootSec=5min
+OnUnitInactiveSec=5min
+RandomizedDelaySec=30s
+Unit=genarrative-ci-cache.service
+
+[Install]
+WantedBy=timers.target
diff --git a/docs/README.md b/docs/README.md
index bc2f3a06f..b1eea2e71 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -42,6 +42,7 @@
 - [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。
 - [DirectProject 独立聊天容器与工作台钱包布局](./adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md)：DirectProject 与 Supervisor 等路径分容器，钱包入口由项目工作台布局独立承载。
+- [引用候选由宿主注入](./adr/【ADR】引用候选由宿主注入-2026-09-22.md)：引用输入区只接受宿主注入的引用 provider，素材选择面板独立成组件，附件芯片成为本轮附件唯一事实源。
 - [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
 - [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
diff --git a/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md b/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md
index 0642ca205..48a2e5933 100644
--- a/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md
+++ b/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md
@@ -51,5 +51,7 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 - 旧项目磁盘上遗留的 `turn-stream.jsonl` / `tool-calls.jsonl` 保留不动，不迁移、不清理、不再由 DirectProject 聊天框读取。
 - 工具卡片的脱敏与截断必须在读取期执行一次，不能因为"原始条目已在磁盘"就把未脱敏内容直接渲染到界面。
 - 回合结束语义务必由 `turn.completed` 判定；缺少该事件的残留回合不得被渲染成运行中。
+- 「活动回合的唯一判据」约束的是**原生回合**：界面上的「本地已发出、原生还没认领」是投影的展示态（`DirectChatTurn.state = 'awaiting-start'`），由本地在途用户条目身份派生，不构成第二套原生生命周期，也不参与 `turnRunning` 的判定。
+- 三层数据流、变量归属与一次发送的时序写在代码里：`apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表在 `apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。改判据时同步这两处与对应测试。
 - 验收证据是端到端行为，不是单元测试：回合进行中杀掉应用进程后重开项目，应看到部分文本与工具卡片按原顺序出现且不显示忙碌；正常结束后重进应与实时渲染一致；文件系统不得再新增 `turn-stream.jsonl` / `tool-calls.jsonl`。
 - id 空间已用源码核对：codex-rs `app-server-protocol/src/protocol/thread_history.rs` 中所有工具 item 都是 `id: payload.call_id.clone()`，而 `project.jsonl` 落盘的是原始 response item。真实 app-server 会话核对仍列为运行时验收项。
diff --git a/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md b/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md
new file mode 100644
index 000000000..bd50d9767
--- /dev/null
+++ b/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md
@@ -0,0 +1,21 @@
+# 引用候选由宿主注入
+
+状态：已接受
+
+引用输入区（`ResourceReferenceInput`）不再自己去拿候选。素材清单、Skill 目录、缩略图预览这些项目级或应用级事实全部改由宿主注入：输入区只接受一组「引用 provider」（每种引用一份，暴露触发符、候选、身份解析与正文文本形态；需要为菜单开合拉一次数据的 provider 另有 `onMenuQueryChange`，由输入区在 effect 里回调），宿主按需选择性注入——只注入资源 provider 就只存在 `@`，再注入 Skill provider 才出现 `$`。素材选择面板同时拆成独立组件（`ResourceReferencePicker`），自己拿数据、由宿主渲染，确认后经输入区句柄的 `insertReferences` 交回。
+
+这么改的理由是双向的。留在组件里的读取属于后端副作用，越过了「共享表现组件不拥有后端副作用与正式业务状态」的边界；而「组件自己查 Skill 目录」又让所有宿主无差别获得 `$` 候选，可只有 DirectProject 那条路径会把 `agc_skill_reference` 解析成真 Skill，其余宿主只把它退化成字面文本，形成误导入口。注入之后「没注入就没有这类引用」成为默认，可见性不再需要额外的开关。
+
+## 备选与取舍
+
+- 只把 Skill 目录外移、素材继续留在组件内部：改动更小，但输入区仍要知道资源种类的字段（显示名、版本 scope、可提及过滤），「只认接口」不成立。
+- 一个总装 builder 统一产出全部候选：调用方接线更短，但所有种类被焊死在同一层，无法只注入资源、也无法单独测试某一种引用。
+- 附件继续留在正文之外（待发送列表）：改动更小，但本轮附件会有两份事实源（正文芯片与列表条目），提交时还要再拼一遍；收敛成一份之后，移除语义、上限口径与排队路径都自然归位。
+
+## 影响
+
+- 输入区删除 `versions` / `activeVersionId` / `showTriggerButton` / `onReferencePickerOpen` / `skills`，`assets` 被注入的 provider 取代；`projectPath` 只保留给输入区自己的润色链路。
+- 输入区与宿主之间只留三个通用接缝：`providers`（引用来源）、`inputActions`（操作排里的宿主控件，例如 `@` 触发钮）、`submitSuppressed`（宿主浮层打开时 Enter 让位）。引用种类一个都不进输入区。
+- `provider.match` 必须是纯函数（输入区在渲染阶段调它取候选）；懒加载走 provider 的可选 `onMenuQueryChange(query)`，由输入区在 `useEffect` 里回调，菜单关闭时收到 `null`。Skill 目录因此第一次敲出 `$` 时才读，渲染期不再有 invokes 或 ref 写入。
+- 附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件导入成功后以芯片进入正文，失败不插入；控制器不再持有附件数组，`MAX_CHAT_COMPOSER_ATTACHMENTS` 改为按草稿中的附件芯片数计算，导入进行中禁止发送。
+- 用户可见行为保持不变，唯一例外是已裁决的缺陷修复：非 DirectProject 宿主不再出现 `$` Skill 候选。
diff --git a/docs/project-memory/plans/【实施计划】AGC项目定时快照上传-2026-09-17.md b/docs/project-memory/plans/【实施计划】AGC项目定时快照上传-2026-09-17.md
index 3fe5a8630..b9cce0d88 100644
--- a/docs/project-memory/plans/【实施计划】AGC项目定时快照上传-2026-09-17.md
+++ b/docs/project-memory/plans/【实施计划】AGC项目定时快照上传-2026-09-17.md
@@ -38,6 +38,6 @@ Parent Milestone: `【里程碑】AGC项目定时快照上传-2026-09-17.md`
 ## 风险与回滚
 
 - 上传体积与带宽：首轮全量可能很大，先设单文件与单次同步总量上限并把超限项记入跳过清单；不静默截断。
-- 数据出境边界：只上传项目目录内普通文件，排除 `.agent/runtime`、`.agent/logs`、`.git`、构建产物与临时文件；凭据类文件不在白名单内。
+- 数据出境边界（2026-09-22 修订）：只上传项目目录内普通文件。`.agent` 承载项目身份与 Agent 状态，整目录上传（含 conversations、logs、runtime、checkpoint、`agent.db`）；`.git`、构建产物、临时文件与凭据类文件仍不在白名单内。该修订只作用于快照同步，项目索引与 checkpoint 继续排除整个 `.agent`。
 - 服务端未配置 bucket 时客户端必须失败关闭，不能把本地索引推进成"已同步"，否则后续同步会漏传。
 - 回滚：客户端可停用触发接线（保留模块与测试）即可回到无上传行为；服务端路由与配置项可单独移除，不影响既有 OSS 前缀与错误报告链路。
diff --git a/docs/project-memory/plans/【实施计划】引用输入区重构与宿主注入-2026-09-22.md b/docs/project-memory/plans/【实施计划】引用输入区重构与宿主注入-2026-09-22.md
new file mode 100644
index 000000000..e2f957c43
--- /dev/null
+++ b/docs/project-memory/plans/【实施计划】引用输入区重构与宿主注入-2026-09-22.md
@@ -0,0 +1,63 @@
+# 引用输入区重构与宿主注入实施计划
+
+对应：[引用候选由宿主注入](../../adr/【ADR】引用候选由宿主注入-2026-09-22.md)；决策记录见 `docs/project-memory/shared-memory/decision-log.md` 的 2026-09-22 条目。本计划不含粘贴解析。
+
+## 一句话交付与验收判据
+
+把 `ResourceReferenceInput` 拆成「纯输入区 + 宿主注入的引用 provider + 独立的选择器面板」，并让附件芯片成为本轮附件的唯一事实源。
+
+验收判据：
+
+1. 输入区不 import 任何具体引用种类，也不判断 `part.type` / `reference.type`：候选、身份解析、正文文本形态都经注入的 provider。
+2. 宿主按需选择性注入：只注入资源 → 只有 `@`；资源 + Skill → `@` 与 `$`；未注入的宿主连触发符都不存在，不需要额外的可见性开关。
+3. 素材选择器面板独立成组件、自己拿数据、由宿主渲染；输入区不再有 `versions` / `activeVersionId` / `showTriggerButton` / `onReferencePickerOpen` / `skills`。
+4. 附件导入成功后以芯片进入正文，失败或异常不插入；控制器不再持有附件数组，「待发送附件列表」删除；上限 8 按草稿中的附件芯片数计算；导入进行中禁止发送。
+5. 行为零变化：改名后芯片显示名自动刷新、打开面板前重读清单、`@`/`$` 候选与键盘交互、上限与失败提示文案逐条一致；唯一例外是已裁决的 Skill 可见性缺陷修复（非 DirectProject 宿主不再出现 `$`）。
+
+## 流程判定
+
+本次是无行为变化重构加两条已裁决缺陷修复（Skill 可见性、附件单一事实源），按轻量流程只建本实施计划，不新建主规范与里程碑规范；若评审要求补 SDD 里程碑，再单独补。
+
+## 提交切分
+
+1. **接口与 provider 工厂**：新增 `features/project-workspace/reference-source/types.ts`（`ReferenceProvider`）与四个工厂（资源 / Skill / 附件 / 运行画面区域），配规则矩阵单测：触发符有无、`match` 过滤、`toReference`、`refresh`（改名 / 删除 / 恒等）、`mentionToken`。
+2. **输入区接入注入**：输入区改为按 `providers` 派生候选菜单（不再写死两个触发符）、按数组顺序取第一个非空回答做草稿回填与改名刷新，删除 `skills` prop；测试夹具（22 处 `assets={assets}`）同批迁移为注入 provider。
+3. **面板外移**：素材选择器面板与缩略图预览搬进独立组件，宿主渲染并接线（`onConfirm → insertReferences`），输入区删除相关 props 与其死 CSS 规则（`styles.css` 里 `resource-reference-*` 共 78 条，逐条核对哪些随面板离开而失效）。
+4. **附件并入联合**：附件成为 `ChatReference` 成员，节点层收敛为单一节点类型，附件 chip 的 DOM 契约逐字保留（`data-attachment-reference`、`data-attachment-status`、`title`、移除按钮 `aria-label`）。
+5. **附件单一事实源**：`uploadFiles` 改为返回导入结果，composer 在导入成功后插入芯片、失败不插入；删除控制器附件状态、`ComposerPendingAttachments` 与提交时的附件 parts 拼接；上限改为按草稿芯片数计算，导入进行中禁止发送。
+6. **显示口径与文档**：`directCodexContentToPromptText` 的 token 前后补空白（不重复）并加 `// TODO we will rewrite this with ref as component later.`，显示名反查改由调用方注入；同步更新 `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`（`ResourceReferenceInput` 共用口径、`@`/`$` 可见性、附件入口与上限口径都会变）。
+
+`resource-reference-*` 的 CSS 类名重命名（78 条规则 / 15 个文件 / 22 处测试断言）留作最后一个独立机械提交，必须与 `RESOURCE_REFERENCE_OVERLAY_SELECTOR` 常量同批修改。
+
+## 验证
+
+每个提交后跑定向用例：`npx vitest run apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx`，加上该提交触达的宿主用例（聊天 composer / 策划输入盒 / 画布生成面板 / 资源卡快速编辑）。全部完成后跑 `npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`，再按验收判据第 5 条逐条对照行为。真实客户端手感（候选菜单位置、面板内滚轮、附件插入位置）留待真机验收，未执行前按未验证项记录。
+
+## 风险与回滚
+
+- 漏注入某个宿主会让该宿主静默失去候选；fail-closed 语义正确，但必须在用例里逐宿主覆盖。
+- `LexicalTypeaheadMenuPlugin` 由两个写死实例改为按 provider 派生后，Enter 让位与 Escape 关闭口径要重新覆盖（`mentionMenuOpenRef` 需聚合成「任一菜单开着」）。
+- 附件插入位置在异步导入期间可能漂移：导入失败一律不插入；文档或选区已改动时退到草稿末尾。
+- 删除 `ComposerPendingAttachments` 会连带影响样式与既有断言，属于预期内的行为收敛，需在提交说明里写清。
+- 回滚按提交粒度 revert；无数据迁移，canonical content 形状不变。
+
+## 执行状态（2026-09-22）
+
+已落地的提交内容：
+
+1. 接口与 provider 工厂：`features/project-workspace/reference-source/types.ts` + 四个工厂（资源 / Skill / 附件 / 运行画面区域），规则矩阵单测落在 `apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts`（触发符有无、`match` 过滤 / 去重 / 截断、`toReference`、`refresh`（改名 / 删除 / 恒等）、`mentionToken`、`isReady`、Skill 目录「首次 `match` 才读、失败可重试」）。
+2. 输入区接入注入：`providers` / `inputActions` / `submitSuppressed` 三个通用接缝；`skills`、`assets`、`versions`、`activeVersionId`、`showTriggerButton`、`openPicker` 全部删除；`ProviderMentionMenu` 按带触发符的 provider 派生（Enter 让位按 `mentionMenuOpenRef` 聚合）。
+3. 面板外移：`ResourceReferencePicker` + `ResourceReferencePickerAction` 由宿主渲染并接线（`onInsert → insertReferences`、`onOpenChange → submitSuppressed`），三个宿主的 `@` 触发钮位置逐处保持原样。
+4. 附件并入联合：附件成为 `ChatReference` 成员，编辑器只剩 `ResourceReferenceNode` 一种节点，附件 chip 的 DOM 契约逐字保留。
+5. 附件单一事实源：`uploadFiles(files, draftAttachmentCount)` 只返回导入成功的附件、失败不插入；控制器附件状态、`ComposerPendingAttachments`、提交时的附件 parts 拼接都删除；上限按草稿芯片数计算；导入进行中禁止发送。
+6. 显示口径与文档：`directCodexContentToPromptText(content, resolver)` 的 token 前后各补一个空白（不重复）并加 `// TODO we will rewrite this with ref as component later.`；显示名反查改由 `resourceLabelResolver(assets)` 注入；同步更新功能说明、ADR 与决策记录。
+
+顺带清理：`ProjectChatComponentProps.activeVersionId` 在策划输入盒不再有 `@` 触发钮之后已无消费方，随本次删除（工作台壳自己的那份仍归 `ProjectDevelopmentView`）。
+
+验证结果：`npx tsc -p tsconfig.json --noEmit`、`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 全通过；定向用例（`referenceSourceProviders`、`resourceReferenceInput`、`chatPromptPolish`、`resourceReferences`、画布生成面板、快速编辑、资源卡实时集成、`appSurface` 215 项、工作台壳清单合并 / 窗口同步、资源标签统计刷新、版本切换 / 替换）全绿。整仓 `npx vitest run` 仍有与本改动无关的既有环境失败（jsdom 缺 `localStorage`：`clientApi` / `clientAuthStorage` / `clientHttp` / `projectCreationDirectory` / `recentProjectsHook` 与 `src/components/image-editor/*` 若干），失败集合与本改动触及的模块不相交。
+
+未完成项：
+
+- `resource-reference-*` CSS 类名重命名（78 条规则 / 15 个文件 / 22 处断言）仍是独立机械提交，须与 `RESOURCE_REFERENCE_OVERLAY_SELECTOR` 同批修改；本次未动，输入区与面板的既有类名逐字保留。
+- 真实客户端手感（候选菜单位置、面板内滚轮、附件插入位置、`@` 触发钮落点）未做真机验收，按未验证项记录。
+- 粘贴解析仍不在本次范围（未来接入点是 provider 的 `mentionToken` 与既有 `buildContentFromTextTokens`）。
diff --git a/docs/project-memory/plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md b/docs/project-memory/plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md
new file mode 100644
index 000000000..c5b4f61eb
--- /dev/null
+++ b/docs/project-memory/plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md
@@ -0,0 +1,123 @@
+# 【实施计划】游戏分发阶段A领域合同
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md` 阶段 A |
+| Status | in_progress |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：`module-game-distribution` 新领域 crate、workspace 声明、Rust shared-contracts DTO、领域单测及文档证据。
+- 明确不修改：发行域名与 CDN、旧 public work/runtime、AGC native 上传命令、网页发布表单。
+
+## 行为范围
+
+- 定义游戏身份、版本状态、包摘要、owner 权限、幂等 key 冲突和 publication revision CAS。
+- 领域服务先以纯内存仓储验证状态合同，再接入已冻结的 SpacetimeDB 游戏/版本/幂等收据表；不把内存仓储作为生产事实源。
+- 阶段 A 只提供身份、版本、真实包确认和状态回读基础，不提供“发布成功”或公开可玩状态，不绕过人工审核。
+
+## 验证命令
+
+1. `cargo test -p module-game-distribution --manifest-path server-rs/Cargo.toml`
+2. `cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check`
+3. `npm run check:encoding`
+4. `git diff --check`
+
+## 风险与回滚点
+
+- API 接入前端前必须完成 SpacetimeDB facade 和 schema 门禁；任何失败都保留旧版本数据，不覆盖已有业务表。
+- 内存仓储只用于行为合同测试，不得被前端当作正式数据源。
+
+## 已完成证据（当前切片）
+
+- `module-game-distribution` 已落地游戏/版本状态机、owner 校验、幂等摘要冲突、上传确认、验证失败重试、审核 CAS、撤回和管理员暂停的纯领域服务与内存测试仓储。
+- 同一 crate 已加入不执行上传代码的 ZIP 包校验：根 `index.html`、路径穿越/大小写冲突、符号链接、加密文件、敏感文件、嵌套压缩包、单文件/总展开量/压缩比上限和逐文件 SHA-256 清单；并新增按白名单内容类型取单个发行资源的读取层。
+- Rust/TypeScript 跨端 DTO、SpacetimeDB 三张持久表、migration 白名单、生成 bindings、typed facade 和游戏分发 HTTP 路由已接入，覆盖创建、上传、送审、审核、下架、公开目录与详情。
+- `api-server` 新增发行网关 `GET /api/game-distribution/releases/{gameId}/{assetPath}`：只服务当前已公开版本，未知扩展名 404，附带 nosniff / CORP / HTML CSP，拒绝带 Cookie 请求，并按对象键做有界包缓存。
+- 重复发布复用游戏身份：游戏表末尾新增可空 `local_project_id`，`create_game_distribution_game` 在 owner + local_project_id 命中时复用既有 `gameId` 并只新增版本；`localProjectId` 经 shared-contracts（Rust/TS）透传，AGC 发布链路写入并在缺失时于发请求前失败关闭，api-server 对短标识做路径分隔符与控制字符校验。
+- 后台新增 `#game-distribution` 游戏审核页：待审列表、通过（要求 HTTPS 发行入口）、拒绝（要求理由）、幂等键与列表刷新；对应 `editor-showcase` Tab 权限映射、API client 与页面测试已加入。
+- 路由级测试证明发行网关、公开目录与登录发布路由确实挂载：带 Cookie 的发行请求 403、未知扩展名 404 且不触达对象存储、无 Bearer 的发布请求 401、目录在无数据库时返回 502 而不是 404。
+- 自动化证据：`cargo test -p module-game-distribution`（11 passed）、`cargo test -p api-server` 游戏分发模块（9 passed）与全量 `cargo test -p api-server`（1069 passed / 6 ignored）、`cargo test -p shared-contracts`、admin-web Vitest（149 passed，含新增游戏审核页与 client 用例）、前端游戏定向 Vitest（15 passed）、AGC `typecheck` 与 `local_project_export` Rust 测试（7 passed）、Vite build。
+- 版本回读、撤回与管理员安全下架闭环：新增 SpacetimeDB `get_game_distribution_version_and_return` / `cancel_game_distribution_version_and_return`（幂等收据 + 公开修订号 CAS）、`spacetime-client` façade、`GET /api/game-distribution/versions/{versionId}`（作者，未知与非 owner 一律 404）、`GET /admin/api/game-distribution/versions/{versionId}`（管理员）与 `POST /api/game-distribution/versions/{versionId}/cancel`（作者，`Idempotency-Key` + `expectedPublicationRevision`）；版本私有投影新增服务端派生的 `recoveryAction`（upload/submit/wait/none/reupload/fix_package/fix_metadata）。后台游戏审核页补齐「安全下架」入口（原因输入 + 二次确认弹窗 + 幂等键）。
+- 幂等响应语义修正：写操作 procedure 现在把「命中既有幂等收据」如实回传为 `replayed: true`（此前所有写操作都固定返回 false），覆盖创建游戏/版本、确认包、上传失败、送审、审核、撤回、下架与暂停。
+- 网页端恢复与撤回：`/games/publish` 在创建版本后写入带 owner 的发布草稿，窗口关闭或上传中断后同一账号可见「继续上传／继续送审」并复用原 `versionId`，换账号只忽略不读取；`/games/mine` 对可撤回状态提供二次确认的「撤回审核」，成功后刷新状态。
+- AGC 发布真实链路回归测试：新增 `apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`（默认跳过，设置 `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL` 指向运行中的 api-server 才执行）。它不 mock 请求层，而是走真实的 `clientApi`/`clientHttp` 调用 `publishLocalProjectGame`，覆盖本地导出包读取、创建游戏、同 `localProjectId` 复用游戏身份、真实 ZIP 上传、送审、版本回读与 `my-games` 聚合，把「AGC 一键发布」从请求组装单测提升到真实后端链路证据。
+- AGC 客户端回归修复：导出试玩包后自动打开的发布面板是焦点陷阱模态，会让既有 `appSurface` 导出快捷操作用例静默失效；用例改为先断言面板出现、关闭后再继续，`appSurface.test.ts` 552 项（535 passed / 17 skipped）恢复全绿，并顺手补上该面板此前缺失的行为断言。同一轮修掉 `gameDistributionPublish.test.ts` 的模块 mock 缺少 `getClientServerBaseUrl` 导出的既有失败。
+- 发行来源（每游戏独立 origin）部署工件：新增 `deploy/nginx/genarrative-release-origin.conf` 与 `scripts/check-release-origin-config.mjs`（`npm run check:release-origin-config`）。模板按命名捕获 `game_id` 把 `https://<gameId>.games.<域>/` 映射到该游戏的 `index.html`、其余路径映射到发行网关前缀，边缘拒绝并清空 Cookie，不代理平台 API/后台/SPA；门禁逐条校验模板约束、交叉检查发行网关仍在设置 `nosniff`/CORP/CORS/CSP 与 Cookie 403，并在本机渲染临时配置跑 `nginx -t`。
+- AGC 发布面板组件测试：新增 `apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx`，覆盖打开时预填资料、发行包摘要、提交入参（项目路径/发行包/资料/幂等键）、连续点击只提交一次、服务端失败保留面板与无 Tauri 宿主/缺包时失败关闭。
+- 视觉与交互巡检修复：真实栈 + headless Chromium 逐页巡检 `/games`、`/games/detail`、`/games/play`、`/games/mine`、`/games/publish`（桌面 1440×900 与移动 390×844）。修掉两处：① 详情页「游玩方式」只读公开投影里恒为空的 `version.controls`，作者声明的 `inputModes` 被忽略，现在优先展示「键盘 · 鼠标 · 触屏」再退回自由文本；② 桌面端 hero 过高导致首屏看不到任何游戏卡片，改为仅桌面压缩 hero 高度，首排卡片进入 900px 视口。
+- 容量与限额边界（阶段 D 证据）：新增真实栈脚本覆盖 5 类包——① 99.0 MiB（两个 50/49 MiB 文件 + `index.html`，均在单文件/展开量/压缩比限制内）上传 200、耗时 11.8s、api-server RSS 81.6→378.0 MB（峰值 +296 MB）后回落 83.2 MB，随后送审 202 进入 `pending_review`；② 声明的 `packageBytes` 为 101 MiB 时在创建版本即被拒 413 `PAYLOAD_TOO_LARGE`（"发行包大小超出限制"，不落版本）；③ 声明合法但请求体 101 MiB 时被请求体限制拒绝 413（0.03s、内存零增长、版本保持 `awaiting_upload`/`upload`，可原版本重传）；④ 60 MiB 全零文件压到 61 KB（压缩比约 1000）拒绝 422 `PACKAGE_VALIDATION_FAILED`（0.01s，`upload_failed`/`reupload`）；⑤ 单文件 65 MiB 与 10,001 个文件同样 422（0.05s / 0.02s）。失败包都不出现在公开目录。
+- 发行包 PUT 受控重试：`platform-oss` 新增 `put_internal_object_with_retry`（复用既有 `oss_error_is_retryable` 分类：传输/超时/connect、408、429、5xx 与 400+RequestTimeout 可重试，确定性 4xx 不重试；body 只转一次 `Bytes` 供各 attempt 复用），发行包上传接入 3 次尝试 + 250/500ms 退避。触发原因：本机实测 99 MiB 单次 PUT 三次里出现过一次 `UPSTREAM_ERROR`（`请求 OSS 失败：error sending request`），客户端需要白传整包。
+- 网页端「为既有游戏发布新版本」：发布页新增 `updateGameId` 更新模式（按作者中心的最近版本回读冻结资料与公开修订号预填，提交时跳过创建游戏、直接在既有 `gameId` 下创建不可变新版本），作者中心新增「发布新版本」入口，壳层支持 `/games/publish?game=<gameId>`。浏览器真实链路：从 `/games/mine` 点「发布新版本」→ `/games/publish?game=…` 预填并显示「为《…》发布新版本 v2」→ 选包提交 → 该 `gameId` 下出现 `versions [(2, pending_review), (1, published)]`，公开入口仍指向并返回 v1 内容。此前网页端只能新建游戏，更新无法沿用 `gameId`，与里程碑「更新沿用相同 gameId」不符。
+- 全生命周期回归（真实栈，11 步）：待审公开不可见（目录不返回 + 详情 404）→ 管理员通过 v1 后目录/详情/网关可玩 V1 → v2 待审期间网关仍是 V1 → v2 被拒后仍是 V1 → 重复批准 `rejected` 版本返回 409（`rejected` 是终态，必须新建版本，与主规范一致）→ 新建 v3 通过后公开入口切换为 V3 → 作者回读被拒版本为 `rejected`/`fix_metadata` → 作者下架后目录/详情/网关全部关闭。同一轮修掉 5 条既有的壳层导航用例失败（游戏分发新增「游戏」页签与移动底栏后，测试仍断言旧导航集合）。
+- 边界、越权与隔离运行时证据（真实栈）：① 跨作者越权——作者 B 对作者 A 的版本上传 403、送审 403、撤回 404、回读 404，且 A 的版本状态未被改变；② 过期 CAS——管理员用错误 `publicationRevision` 批准返回 409，正确修订号才通过；③ 包边界——符号链接条目、`.env` 凭据文件、嵌套 ZIP 分别返回 422 `PACKAGE_VALIDATION_FAILED`，版本落到 `upload_failed`/`reupload`；④ 私有对象直取——按对象键直接 GET 私有 OSS 地址返回 **403**，发行文件只能经网关读取。
+- 浏览器沙箱隔离实测：发布一个自检探测包（内联脚本主动探测并 `postMessage` 回传结果），在 `/games/play` 里点「开始游戏」后收到 `{ origin: "http://127.0.0.1:10001", cookie: "throw:SecurityError", storage: "throw:SecurityError", parentDom: "throw:SecurityError", externalFetch: "throw:TypeError" }`——主站 Cookie、localStorage、父页面 DOM 全部不可访问，外站 fetch 被 CSP `connect-src 'self'` 阻断。键盘可达抽查：桌面端 Tab 顺序覆盖导航 → 搜索 → 下载客户端 → 账户，游戏分发自己的控件（发布游戏/我的游戏/分类页签/游戏卡片）聚焦时都有可见的浏览器默认焦点环。同一探测包还验证了音频链路：沙箱内 `fetch('assets/beep.wav')` 返回 `status:200 type:audio/wav`，WebAudio `decodeAudioData` 成功解出 `0.40s / 48000Hz`（`AudioContext.state = suspended`，与浏览器“首次播放需帧内用户手势”的策略一致，玩家进入游戏后的第一次交互即提供该手势）。游戏内真实触屏输入也已验证（见下一条）。
+- 上传中断与进程重启恢复（真实栈，两次独立实验）：60 MiB 包 PUT 进行到 ~2.5s 时 `SIGKILL` api-server，客户端拿到 `RemoteDisconnected`（等价于响应丢失）；重启后该版本仍是 `awaiting_upload`/`upload`，没有半确认状态。① 用不同字节重传返回 422 `PACKAGE_VALIDATION_FAILED`（`InvalidArchive`）并转 `upload_failed`/`reupload`；② 用固定时间戳构造的确定性 60 MiB 包重传**相同字节**返回 200（7.64s），版本转 `uploaded`/`submit`，随后送审 202 进入 `pending_review`。两次实验中游戏都未出现在公开目录。
+- 发布开关（回滚/事故能力）：新增 `game-distribution:publish` 灰度 gate（复用现役灰度配置机制与后台入口）。默认开放；`enabled=true` 时按白名单/用户标签/灰度百分比放行，`rolloutPercent=0` 且无白名单即全部关闭。关闭时作者写入与管理员批准返回 `503 GAME_DISTRIBUTION_PUBLISH_DISABLED`，而目录、详情、版本回读、发行网关、`/my-games`、审核队列读取、拒绝审核与安全下架继续可用；开关读取失败按关闭处理。路由级测试覆盖「默认放行 / 全关拦截 / 读取不受影响 / 白名单放行」，真实栈验证同口径：关闭后作者写入 503、目录/详情/网关/my-games 全 200、管理员批准 503 而拒绝 200、白名单用户可发布、重新开放后恢复。
+- 游戏内真实触屏输入（本机 Chromium + CDP `Input.dispatchTouchEvent`，390×844 视口）：在 `/games/play` 点「开始游戏」后，向 iframe 可视区域坐标派发 `touchStart`/`touchEnd`；`sandbox="allow-scripts"` 且 `ready` 的沙箱内探测包回传 `{touchstart: 1, touchend: 1, pointerdown: 1, pointerTypes: ["touch"], click: 1, target: "pad", touches: 1}`，证明真实触摸事件经平台进入游戏容器并命中目标元素。注意：触摸模拟必须在 iframe 文档创建之前启用，否则文档不会注册 touch 事件支持（首次实测只收到 pointerdown，重载后 touchstart/touchend 才出现）。
+- 可观测性（阶段 D「上传失败、校验耗时、审核积压、撤销传播」）：`api-server` 的游戏分发模块补齐结构化事件，均带 `request_id`（可 join 访问日志）与 `operation`，不记录 Token、signed URL、完整文件内容或本地路径。事件与字段：`package_confirmed`（game_id/version_id/package_bytes/file_count/sha256_prefix/oss_put_skipped/elapsed_ms）、`package_rejected`（code/reason/uploaded_bytes/elapsed_ms）、`version_submitted`、`version_cancelled`、`review_backlog_listed`（pending_versions/limit）、`review_decided`（decision/admin_user_id/publication_revision）、`game_unpublished`（visibility/publication_revision/active_version_id）、`game_suspended`（admin/reason/publication_revision）、`publish_switch_blocked`/`publish_switch_unavailable`、发行网关 `release_rejected`（debug 级：reason=cookie_present/unsupported_extension/not_public/no_active_version/version_not_published）。真实栈复跑一次完整链路后，8 类事件各出现 1-2 次，字段与耗时均可用（样例：`package_rejected … reason=InvalidArchive uploaded_bytes=9 elapsed_ms=6`、`game_unpublished … visibility=unpublished publication_revision=2 active_version_id=""`）。
+- 工程门禁：`npm run check:spacetime-schema`（147 tables）、`npm run check:server-rs-ddd`、`cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+## 运行时证据（2026-09-20，真实本地栈）
+
+`npm run dev` 在无冲突端口段启动（spacetime `127.0.0.1:10004`、api-server `127.0.0.1:10001`、真实 OSS bucket `xushi-dev`），用 HTTP 全链路脚本验证：
+
+- 管理员登录 + 用户口令注册/登录均走真实路由。
+- 创建游戏后，用相同 `localProjectId` 再次创建返回**同一个 `gameId`**（去重在真实数据库上生效）。
+- 真实 ZIP（根 `index.html` + `assets/app.js`）上传私有 OSS，服务端重算 SHA-256 / 字节数 / 文件数并确认 `uploaded`。
+- 送审返回 `202` 与 `pending_review`；此时公开目录、公开详情都不返回该游戏。
+- 管理员用 HTTPS `entryUrl` 审核通过后，目录与详情出现该游戏并带当前版本 `entryUrl`。
+- 发行网关返回 `text/html` 与 `text/javascript`；带 `Cookie` 的发行请求 403，未知扩展名 404。
+- 作者下架后公开详情回到 404。
+- 更新链路：v2 送审期间与 v2 被拒后，公开入口始终停留在 v1 且 v1 内容仍可读取；v3 通过审核后才替换公开版本。
+- 真实浏览器（headless Chromium）加载发行网关的 `index.html`：文档渲染、同源 `assets/app.js` 在现役 CSP 下执行成功（`booted=1`、`window.__gd=1`），控制台只剩 favicon 404。
+- 浏览器打开 `http://127.0.0.1:10000/games` 能看到已发布游戏卡片，`/games/detail?id=<id>` 渲染标题与「立即玩」。
+- 平台页面内嵌游玩：浏览器打开 `/games/play?id=<id>`，点「开始游戏」后 iframe 以 `sandbox="allow-scripts"` 挂载发行网关地址，`game-player-frame--ready` 置位，控制台无 CSP/CORP 拦截，api-server 访问日志显示该版本 `assets/app.js` 返回 200。
+- 非生产环境允许 http 回环 `entryUrl`（与前端 `normalizeGameEntryUrl` 同口径），生产仍只接受 HTTPS；这样本地无需 TLS 即可验证内嵌游玩。
+- 作者中心 `/games/mine`：SpacetimeDB 新增 `list_owner_game_distribution_games_and_return`（owner 只从认证主体派生，每游戏最多回 10 个最近版本），`api-server` 暴露 `GET /api/game-distribution/my-games`；浏览器里用真实作者 token 打开该页，能看到「已公开」状态与「下架」按钮，点击后状态变为「未公开」、按钮消失，公开目录同步不再返回该游戏。
+- 网页端发布入口 `/games/publish`：浏览器里用真实文件选择框上传 ZIP（根 `index.html` + `assets/app.js`），api-server 访问日志记录 `POST /api/game-distribution/games` 200 → `POST /api/game-distribution/games/{gameId}/versions` 200 → `PUT /api/game-distribution/versions/{versionId}/package` 200 → `POST /api/game-distribution/versions/{versionId}/submit` 202；随后同一账号在 `/games/mine` 看到该游戏为「未公开 / 版本 v1 · 审核中」，公开目录不返回它。
+
+- 版本回读/撤回真实链路（`npm run dev`，api-server `127.0.0.1:10001`、SpacetimeDB `127.0.0.1:10004`）：作者送审后 `GET /versions/{id}` 返回 `pending_review` + `recoveryAction=wait`；其他账号与未知版本都是 404；过期修订号撤回 409；正常撤回 200 且状态变 `cancelled`、`recoveryAction=none`；同 key 同请求重放返回 `replayed=true`，同 key 不同摘要 409；撤回后公开目录不返回该游戏。
+- 主链路回归（同一真实栈）：正式发布 `replayed=false`、重复送审 `replayed=true`；待审期间目录不可见；管理员读版本 200、审核通过后状态 `published` 且目录与详情返回 `currentVersion.entryUrl`；发行网关 `index.html` 200、带 Cookie 403、未知扩展名 404。
+- AGC 发布真实链路（同一真实栈）：`GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL=http://127.0.0.1:10001 npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts` 通过——AGC 发布函数依次完成创建游戏、创建版本、上传 ZIP、送审，返回 `pending_review`；版本回读为 `pending_review`/`wait`；不带旧幂等键的第二次发布复用同一 `gameId` 并生成 v2；`/my/games` 的 `latestVersion` 指向 v2。
+- 非法包真实链路（同一真实栈）：缺根 `index.html` 且含 `../` 条目的 ZIP 上传返回 422（包校验错误），版本进入 `upload_failed` 且 `recoveryAction=reupload`，此时送审被拒（409）、公开目录不返回该游戏，作者仍可撤回该版本重新出包。
+- 发行来源真实边缘验证（同一真实栈 + 本机 nginx 1.28.3，模板渲染到 `~/data/tmp` 后监听高位端口）：`Host: <gameId>.games.example.com` 时根路径 200 `text/html`（游戏 `index.html`）、`/assets/app.js` 200 `text/javascript`；带 `Cookie` 403；`/api/auth/me` 404（平台命名空间未暴露）；未知 gameId 404；http 301 到 https；响应头经边缘透传后仍是 `nosniff` + CORP `cross-origin` + 无凭据 CORS + HTML CSP + `Cache-Control: public, max-age=60, must-revalidate`。
+- 移动视口真实游玩：headless Chromium 以 `390x844` 打开已发布游戏 `/games/play?id=<id>`，页面显示「横屏设计，旋转设备」提示与移动端底部导航，点击「开始游戏」后 iframe 以 `sandbox="allow-scripts"` + `allow="fullscreen"` 挂载发行网关地址并 `ready`，`index.html` 与 `assets/app.js` 均返回 200，控制台无 CSP/CORP 报错；截图存于本轮验证记录（不入库）。
+本轮同时修掉三个真实缺陷：Vite dev 代理缺少 `/api/game-distribution` 前缀（本地全部 404）；详情页在「已发布但没有 controls」时误显示「暂未发布可玩版本」；发行网关的 `Cross-Origin-Resource-Policy: same-origin` 会让 opaque origin 沙箱内的游戏加载不了自己的脚本（改为 `cross-origin` + 无凭据 CORS，详见 `pitfalls.md`）。
+
+- 资料冻结与展示闭环（封面 + 截图）：游戏表末尾新增可空 `cover_object_key` / `screenshots_json`，版本表末尾新增可空 `metadata_json`；创建版本时 api-server 校验「必需封面、≤6 张截图、素材属于当前作者且 `content_type` 为 `image/`」，并从素材记录派生对象键生成冻结快照，审核通过时整体生效到游戏行。
+- 公开素材读授权：只有 `published` 且存在有效 `active_version_id` 的游戏，其封面/截图素材才在 `/api/assets/read-url` 获得匿名读授权；其余素材仍按 owner 校验。
+- 作者续发复用：版本回读（作者本人）与审核回读（管理员）的版本投影新增 `frozenMetadata`，带回 `coverAssetId` / `screenshots[].assetId`；`/games/publish` 更新模式据此预填封面与截图，不要求作者为沿用封面重新上传；快照缺素材 ID 的旧版本明确要求重新选择封面。公开投影仍只暴露对象键。
+- 网页发布资料入口：`/games/publish` 新增「封面与截图」区（封面必需、截图 ≤6、可逐张移除、上传中禁用提交），复用平台图片直传 + confirm 通道；本地校验与服务端口径对齐（缺封面/超 6 张在发请求前拦截）。
+- 网页展示：游戏广场卡片与详情页 hero 用 `useResolvedAssetReadUrl` 换签展示真实封面，详情页在存在截图时给出可点击缩略图条（封面 + 截图，选中态 + 键盘可达），换签失败或无素材时静默回退原有渐变占位，不出现空框。
+- 本切片验证：`cargo check -p api-server -p spacetime-module -p spacetime-client`；`cargo test -p api-server game_distribution`（17 passed，含新增 `version_detail_payload_exposes_frozen_metadata_to_owner`）；`npm run typecheck`；`npx vitest run src/components/game-distribution src/services/gameDistributionClient.test.ts`（46 passed）；改动文件 `eslint --max-warnings 0` 与 `npm run check:encoding`。
+
+- AGC 发布面板资料入口：新增 `apps/ai-game-creator-shell/src/services/assetDirectUpload.ts`（凭证 → 直传 → confirm，直传固定走 Tauri HTTP 插件并校验目标主机必须是平台素材存储），面板支持封面必选 + 截图 ≤6、本地预览、逐张移除、上传中禁用发布；缺封面时在创建游戏前失败关闭，服务端「封面」类错误原样展示；同一文件重复提交复用素材 ID 不重复直传。为支持直传，`src-tauri/capabilities/main.json` 的 http 作用域新增 `https://*.aliyuncs.com/*`（配合客户端主机白名单，避免把本地文件发给任意主机）。
+- AGC 测试证据：`npx vitest run apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx apps/ai-game-creator-shell/tests/clientApi.test.ts`（27 passed）；`npm --prefix apps/ai-game-creator-shell run typecheck`；改动文件 `eslint --max-warnings 0`。
+
+- 真实本地栈媒体验证（2026-09-20，`npm run dev:api-server` + `dev:web`，api-server `127.0.0.1:12401`、SpacetimeDB `127.0.0.1:12402`、真实 dev OSS 桶）：`E2E_ADMIN_USER=… E2E_ADMIN_PASSWORD=… npm run check:game-distribution-media-e2e`（`scripts/check-game-distribution-media-e2e.mjs`）27 项全部通过——真实直传封面与 2 张截图素材、缺封面 400、截图 7 张 400、不存在素材 400（创建游戏与创建版本两处）、他人素材 403、创建游戏/版本/上传/送审（202 + `pending_review`）、作者回读拿到 `frozenMetadata` 且素材 ID 与顺序一致、待审期间公开目录不含该游戏且封面匿名读返回 404、管理员审核通过后公开投影带封面与截图对象键且不含素材 ID、匿名 `read-url` 对封面与截图都返回签名地址、发行网关 `index.html` 与 `assets/app.js` 均 200 且带 nosniff。
+- 真实浏览器展示验证（同一栈，headless Chromium `390x844` 与 `1280x900`）：`/games` 卡片渲染真实封面签名地址（无占位回退），`/games/detail?id=…` hero 显示封面、缩略图条渲染「封面 + 2 张截图」，点击第 3 张后 `aria-pressed` 与 hero 图片同步切换；移动端布局正常。截图存于 `~/data/tmp/gd3/`（不入库）。
+- 网页发布页真实上传验证（同一栈 + headless Chromium）：在 `/games/publish` 里用作者会话填写资料、选择真实 PNG 封面与 ZIP 并提交，页面返回「已提交审核」；随后 `my-games` 显示该游戏 `pending_review`，版本回读的 `frozenMetadata.coverAssetId` / `coverObjectKey` 正是本次浏览器上传的素材，证明网页端封面直传（凭证 → OSS → confirm）与冻结链路真实可用。
+- 发布资料入口交互打磨：原生 file 控件在上传后清空 value 时会显示「未选择任何文件」，与「已选择」提示互相矛盾；网页发布页与 AGC 面板都改成透明 input 覆盖自定义胶囊按钮（点击命中原生控件，文案显示「选择/更换封面图片」「添加截图」），并在验证中用 `elementFromPoint` 确认点击命中的是 `input[type=file]`。
+- AGC 直传能力作用域静态验证：用 `tauri-plugin-http` 同一套 `urlpattern` 解析逻辑验证 `capabilities/main.json` 新增的 `https://*.aliyuncs.com/*` 命中 dev 桶（`xushi-dev.oss-cn-beijing.aliyuncs.com/…`）与生产桶（`genarrative-assets.oss-cn-shanghai.aliyuncs.com/…`）、拒绝 `evil.example.com`；直传失败（含作用域拒绝/网络不可达）统一转成中文可操作文案，并有单测覆盖。桌面端真实执行仍需在装有 AGC 的机器上跑一次。
+- 创建游戏同步校验素材归属：此前 `POST /api/game-distribution/games` 只校验「封面必填 / 截图 ≤6 / ID 非空」，素材是否存在与是否属于当前作者要等到创建版本才失败，游戏行会先落一个无效素材 ID；现在创建游戏与创建版本都走 `resolve_owned_game_media`，不存在返回 400、他人素材返回 403。
+
+- 合并 master（`81e0c41f1`，含 `429f991bd` 定向回滚、Godot 原生绑定迁移与策划 Agent 模型控件）：回滚提交把混入 master 的游戏分发代码整体删掉，其中 25 个文件在本次合并里属于“双方都改动同一区域之外”的自动删除，直接合并会静默丢功能。处理方式是按“分支补回功能、master 保留迁移”逐类归位：模块注册（`spacetime-module/src/active.rs`）、api-server 路由与权限映射、后台审核页、AGC 发布命令与 payload 类型、`SelectionStage` 的 games 阶段、`ProjectSupervisorView` 的 `overlay` 挂载点、主站路由/标题、Cargo 依赖与锁、vite/vitest 代理与 tailwind source 全部取回分支版本；master 的 Godot C++ 迁移（删除旧 vendored GDExtension、新的 composer 控件样式）保留。合并后用“按文件对比 game-distribution 引用数不得下降”的脚本复核 85 个相关文件，无残留丢失。
+- 顺带修掉 master 自带的一处红灯：`src/config/viteProxyConfig.test.ts` 断言 `/api/creation-entry` 会被代理，但 master 的 `vite.config.ts` 并无该代理项，且 api-server 已把 `/api/creation-entry/config` 列入 retired 路由测试（dev 中间件按退役路径返回 404）。测试改为断言“退役路径不进入代理”，与 `isRetiredApiPath` 事实一致。
+
+- 第二次合并 master（`81e0c41f1` → `500835407`，304 个提交：DirectProject 聊天容器重构、Project Supervisor 退役、策划附件导入、CI 隔离编译缓存等）：冲突 9 个文件，其中真正需要集成决策的是 AGC 侧——master 把 `ProjectSupervisorView` / `SupervisorChatOnlyView` 整体退役（含我们此前挂 overlay 的挂载点），并且前端不再调用 `export_local_project_package`（`check-config.mjs` 把它登记为 native-only）。处理方式：接受 master 的退役与删除；把发布入口重新接到新架构上——`DirectProjectChatHeader` 新增「发布到游戏广场」按钮（没有回调时不渲染、忙态禁用），`DirectProjectChatView` 透传 `onRequestGamePublish`，`App.tsx` 用工作台壳持有试玩包导出与 `GameDistributionPublishPanel`（沿用 `project.export_package` 权限确认队列），并把该命令从 `check-config.mjs` 的 native-only 清单移回 App invoke。
+- 同轮修掉 master 自带的红灯断言：`src/config/viteProxyConfig.test.ts` 曾断言 `/api/creation-entry` 会被代理，但配置无该代理项且 api-server 已把 `/api/creation-entry/config` 列为退役路由，测试改为断言退役路径不进入代理。
+- 覆盖率与门禁（合并后）：全量 `npm test` 392 文件 / 4371 用例通过（appSurface 重构后 215 用例）、两端与 admin-web typecheck、`cargo check`（api-server / spacetime-module / spacetime-client）、`cargo test`（api-server 游戏分发 17、module-game-distribution 11）、`check:encoding`、`check:doc-index`、`check:rustfmt`、SpacetimeDB schema guard（对比 `origin/master`）。
+
+- 第三次合并 master（`500835407` → `fdc14404b`：DirectProject 回合三态、投影 memo、宿主崩溃后的回合收口、策划对话布局修复、AGC release 每日调度）：git 自动合并无冲突，但产生了**静默拼接缺陷**——新加的聊天头 CSS 被并进了 master 策划态分组选择器中间，导致 `.project-chat-topbar-status` 在策划态丢失 `font-size`（`chatDialogFrameLayout` 用例抓到）。修复方式是按 master 原文重建分组规则、把发布入口规则独立成块，并把重复的状态规则删掉。
+- 合并后复核：全量 `npm test` 393 文件 / 4374 用例通过，root / AGC / admin-web 三端 typecheck 通过，发布入口（聊天头「发布到游戏广场」→ 试玩包导出 → 发布面板）在新回合三态下保持接线。
+
+- 发布入口灰度下发：`GET /api/runtime/frontend-config` 新增 `gameDistributionPublishEnabled`，复用既有 `is_game_distribution_publish_enabled_for_user`（未配置 `game-distribution:publish` 或 `enabled=false` 时对已登录作者默认开放，显式收紧后只放行白名单/灰度命中，匿名恒为 false），避免前端入口与写入口出现两套判据。网页端 `PlatformEntryActiveFlowShell` 据此隐藏「发布游戏 / 发布新版本」入口，`/games/publish` 直接访问时渲染「发布功能正在灰度中」并提供重新检查；AGC 端 `readGamePublishAvailability` 同样读该字段，只有命中才把发布回调交给 DirectProject 聊天头。
+- 灰度验证：`cargo test -p api-server frontend_runtime_config`（6 passed，含新增的 `frontend_runtime_config_game_distribution_publish_is_scoped_to_authenticated_gate`：无 gate 行 → 登录作者 true/匿名 false；`enabled=true` 无白名单 → false；白名单命中 → true；`deny_user_ids` → false；`enabled=false` → true；`rolloutPercent=100` → true）、网页发布页 15 用例（含灰度未命中隐藏表单与「重新检查」放行）、平台壳 18 用例（含广场入口按灰度隐藏/显示）、AGC 发布服务 6 用例（含字段缺失与读取失败按不开放处理）。
+
+## 尚未完成
+
+- 真实独立发行域名、通配 TLS 与 CDN 仍属部署侧：边缘模板与门禁已就绪，本地已用真实 nginx 验证按主机映射、Cookie 403 与命名空间隔离，但仍需在真实域名/证书下跑一次“审核通过 → 游玩 → 换版 → 下架”并确认 CDN TTL 不超过 60 秒窗口。
+- 版本回读、撤回与管理员安全下架已实现；主规范 HTTP 表中不再有待落地路由。容量与限额边界、发行包 PUT 重试已有真实栈证据；仍未做的是 CDN purge 失败行为、回滚演练与清理策略（不删除仍被公开版本引用的对象）的上线验收。
+- 生产调用依赖已初始化的 editor generation runtime service identity；未初始化时 procedure 拒绝写入，不会退回 API 进程内存状态。
diff --git a/docs/project-memory/plans/【里程碑】AGC项目定时快照上传-2026-09-17.md b/docs/project-memory/plans/【里程碑】AGC项目定时快照上传-2026-09-17.md
index 25f0c802e..bc4889cda 100644
--- a/docs/project-memory/plans/【里程碑】AGC项目定时快照上传-2026-09-17.md
+++ b/docs/project-memory/plans/【里程碑】AGC项目定时快照上传-2026-09-17.md
@@ -17,7 +17,7 @@ AGC 在项目打开期间按周期把用户项目增量上传到 OSS `agc-dev`
 - 目标 bucket 配置：`GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_*`，默认 `agc-dev`。
 - 契约：`shared-contracts::agc_project_snapshots` 新增请求/响应 DTO 与项目 ID、相对路径、摘要校验函数。
 - 客户端增量索引：`<AppData>/project-snapshots/<projectId>/index.json`，按用户身份判等，换号后按冷启动全量重算。
-- 排除口径：复用 `should_skip_project_snapshot_path`（整个 `.agent`、`.git`、构建与依赖目录、凭据目录、敏感后缀、符号链接与重解析点）。
+- 排除口径：快照同步使用 `should_skip_project_snapshot_sync_path`（2026-09-22 起）。`.agent` 承载项目身份与 Agent 状态，整目录同步；`.git`、构建与依赖目录、凭据目录、敏感后缀、符号链接与重解析点仍然排除。项目索引、checkpoint、Agent 上下文与 git 检查继续沿用 `should_skip_project_snapshot_path` 的整个 `.agent` 排除口径。
 
 ## 不做
 
@@ -32,7 +32,7 @@ AGC 在项目打开期间按周期把用户项目增量上传到 OSS `agc-dev`
 1. 首次同步上传项目内全部符合条件的普通文件；再次同步在无改动时上传 0 个文件。
 2. 只修改一个文件时，差异集合恰好包含一个修改项；删除一个文件时上传集合为空且清单中不再包含该文件。
 3. `(字节数, 修改时间)` 未变的文件复用已存摘要，不重复读取内容计算摘要。
-4. 排除规则命中项（`.agent/runtime`、`.agent/logs`、`.git`、`node_modules`、构建产物、临时文件、符号链接）与超限文件进入跳过清单，不进入上传集合。
+4. 项目内 `.agent` 的全部普通文件（`manifest.json`、`agent.db` 与其 WAL/SHM、`.manifest.json.lock`、`project.lock`、conversations、logs、runtime、checkpoint、workbench）进入上传集合；`.git`、`node_modules`、构建产物、凭据目录与敏感后缀仍不进入；超限文件进入跳过或延后清单，不静默丢弃。
 5. 任一次同步失败（非鉴权类）不推进本地索引，下一次触发重算并重试；鉴权/权限类失败不自动重试。
 6. 同一项目的并发触发串行执行，不产生两路重复上传。
 7. 工作区窗口关闭与应用退出都会触发一次同步，且关闭路径不因同步失败而阻塞退出超过超时上限。
diff --git a/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
new file mode 100644
index 000000000..4024b8e92
--- /dev/null
+++ b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
@@ -0,0 +1,135 @@
+# 【里程碑】游戏分发、发布与在线游玩
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 0.2 |
+| Status | accepted（用户“继续”确认按既定假设进入阶段 A；A 未验收） |
+| Date | 2026-09-18 |
+| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` |
+
+## 交付与评审边界
+
+本文件拆分主规范“AGC 游戏分发与在线游玩合同”的完整业务：真实上传、持久化发行、审核、隔离托管、AGC 发布、网页上传与游玩、上线运维。当前只授权阶段 A 实现，阶段 B/C/D 仍为 `proposed`，没有已上线/已验收结论。
+
+先完成主规范与本文件评审，再为一个获准阶段创建单独实施计划；未经该阶段验收，不进入依赖它的阶段。里程碑只规定行为与证据，不预先写代码步骤。
+
+| 阶段 | 行为切片 | 依赖 | 状态 |
+| --- | --- | --- | --- |
+| A | 真实包、游戏身份与可恢复发行 | 主规范评审及持久化合同冻结 | accepted（实现中） |
+| B | 人工审核、公开投影与隔离托管 | A 验收；发行站点/私有存储/审核策略确认 | proposed |
+| C | AGC 与网页发布、现代游戏目录和跨端游玩 | B 验收；导航与交互稿评审 | proposed |
+| D | 端到端验收、容量与撤销、上线准备 | C 验收；实际部署资源可用 | proposed |
+
+## 实现进度（2026-09-20，未验收）
+
+以下是已落地的实现与本地运行时证据，**不等于阶段验收**：B/C 的隔离托管、域名与生产验收仍缺少真实发行域名、TLS/CDN 与生产账号。
+
+- 阶段 A：真实 ZIP 上传、游戏身份、owner/幂等/CAS、状态机、DTO 与 schema 门禁已完成；真实 SpacetimeDB + 私有 OSS 的创建/上传/确认/重启恢复已有证据。
+- 阶段 B：人工审核（后台列表、通过需 HTTPS 入口、拒绝需理由）、公开投影、发行网关（按公开版本服务、扩展名白名单、`nosniff`/CORP/CSP、带 Cookie 403）与作者下架已实现；每游戏独立来源已有可执行工件 `deploy/nginx/genarrative-release-origin.conf` 与门禁 `npm run check:release-origin-config`，并已在本机用真实 nginx + 真实网关验证按主机映射、Cookie 403 与平台命名空间 404；生产域名、通配证书与 CDN TTL 仍需上线环境确认。
+- 阶段 C：AGC 客户端「发布到平台」面板与发布链路（dist 归一化根 `index.html`、摘要/字节数声明、幂等键、`localProjectId` 复用）已实现并有请求组装与 Rust 导出测试；网页 `/games/publish` 走同一服务端管道，本地已用真实文件选择验证；AGC GUI 自身的端到端发布仍待客户端环境验收。目录（关键词/分类/设备筛选、滚动与筛选恢复）、详情、游玩页（主动作后加载、超时重试、旋转提示、全屏、移动端门槛）与作者中心（状态、驳回理由、撤回、下架）已实现；本地已在桌面与 `390x844` 移动视口真实游玩。
+- 阶段 D：容量/额度、重启恢复、CDN 撤销与回滚演练尚未开始，依赖生产资源。
+
+细节与命令级证据见[实施计划【游戏分发阶段A领域合同】](【实施计划】游戏分发阶段A领域合同-2026-09-19.md)的「已完成证据」「运行时证据」「尚未完成」。
+
+## 共通范围与不做项
+
+- 正式状态来自后端，素材仍复用平台上传与归属能力；前端和 AGC 不另建公开游戏状态、owner 事实或审核结果。
+- 真实发行包具有不可变版本和 SHA-256，AGC dist 归一化为发行根 `index.html`；网页 ZIP 与 AGC 共用一条服务管道。
+- 不恢复退役玩法 API、公开作品表或专属 runtime；不把私有项目源码镜像公开。
+- 首版不包含原生/Wasm 游戏、任意外网依赖、服务端进程、多人联机、云存档、评论/评分/关注、排行榜、推荐算法和收益结算。
+- 本文件只协调本业务；不顺带改造图片编辑器、Agent Runtime 执行模型或无关项目数据。
+
+## 阶段 A：真实包、身份与可恢复发行
+
+### 前置条件
+
+- 主规范的包类型、限额、身份/幂等/CAS、状态机和内部 API 已评审。
+- 游戏、版本、审核与操作账本的完整字段、索引、唯一约束、受信服务身份及清理策略已经冻结；若涉及已有表破坏性变更，另有已确认迁移计划。
+
+### 行为与验收
+
+- [ ] 登录用户创建服务端分配的游戏，owner 不能由请求伪造；其他账号不能读取私有版本、上传、提交或撤销。
+- [ ] 服务端接收真实 ZIP 字节，重算摘要/字节数并建立展开清单；只有 metadata 的请求不能获得已上传或已发布状态。
+- [ ] 缺入口、越界/重复/大小写冲突路径、符号链接、压缩炸弹、敏感内容和额度超限均失败关闭，原私有对象和公开状态保持一致。
+- [ ] 一份版本只接受一份已确认内容；同 key 同请求重放无重复游戏/版本，不同请求冲突；同版本并发上传不混写。
+- [ ] 校验可异步恢复，响应丢失、服务进程退出和客户端重试均回到原版本；确定失败和未知结果在响应中可区分。
+- [ ] 正常及失败状态、私有查询和错误 envelope 在 Rust 与 TypeScript DTO 中一致；新增 schema、迁移、表目录与绑定一致。
+
+### 证据要求
+
+- 自动化：领域状态机、owner、幂等/CAS、包读取与错误路径、DTO 和 schema 定向测试。
+- 运行时：真实 SpacetimeDB 与私有对象存储完成上传/回读/重启恢复；`/healthz` 正常。
+- 边界：服务端记录的 ZIP 摘要与测试上传字节一致；未审核目录不能匿名读取；无凭据或本地路径泄漏。
+
+## 阶段 B：审核、公开投影与隔离托管
+
+### 前置条件
+
+- A 已验收；人工审核角色、资料检查标准与拒绝/封禁行为已确认。
+- 已确定不同可注册站点的发行域名、每游戏独立 origin、私有存储和网关能力；同源临时路径不能作为验收替代。
+
+### 行为与验收
+
+- [ ] 自动校验通过只进入待审，管理员可查看真实待审游戏并批准/拒绝；审核记录可追溯且普通作者不能提交审核动作。
+- [ ] 新游戏审核通过并核验发行文件可读后才公开；更新待审或失败不改变旧版资料、URL 与可玩性。
+- [ ] 审核激活与下架使用 `publicationRevision` CAS；过期审核、重复批准、并发更新和下架不会恢复本应关闭的游戏。
+- [ ] 游客目录、详情和启动接口只返回已公开投影；未公开和已下架状态均不可见，不返回私有快照地址。
+- [ ] 每游戏在独立 HTTPS origin 上，iframe sandbox、网关 CSP/CORS/MIME/禁止 Worker 等策略与主规范一致。
+- [ ] 实际 npm/Vite 模块和同包资源在 opaque sandbox 下可载入；外站 fetch/WebSocket、平台 Cookie/storage/DOM、顶层跳转、弹窗和敏感权限被阻断。
+- [ ] 作者下架及管理员安全下架会关闭新启动和发行读取；不能绕过网关直取公开 OSS 对象；撤销传播符合最大缓存窗口。
+
+### 证据要求
+
+- 自动化：审核权限、版本切换事务、公开投影与入口 allowlist、响应头和缓存策略测试。
+- 运行时：真实独立域名内运行至少一个代表性游戏；真实审核、更新失败、并发下架和旧 URL 回读证据。
+- 边界：外部请求阻断、匿名私有对象拒绝、跨游戏 origin 隔离及 60 秒以内缓存撤销（以获批值为准）。
+
+## 阶段 C：双端发布与现代游戏体验
+
+### 前置条件
+
+- B 已验收；网页根入口、桌面/移动导航、暖色主题交互稿及首版设备范围已评审。
+- AGC 现有 npm 构建/导出能提供完整 dist，不需要把源码同步管道改作发行管道。
+
+### 行为与验收
+
+- [ ] AGC 从已构建 dist 生成根入口为 `index.html` 的真实包，一次提交动作完成检查、资料确认、上传和送审；状态及失败原因与服务端回读一致。
+- [ ] 网页可选 ZIP、提交封面和必需资料，进入相同上传/校验/审核流程；任一客户端可以查看同账号游戏状态，更新沿用相同 `gameId`。
+- [ ] 上传中断、双击、登录失效、窗口关闭后恢复原操作；换账号不能恢复前账号私有状态；待审不能显示为已发布。
+- [ ] 目录支持真实数据、关键词/分类/设备筛选、空/错/加载态；详情提供明确主动作，搜索与返回恢复上下文。
+- [ ] 游客从目录/分享链接进入详情再启动真实已发布游戏；开始操作后才加载 iframe，加载失败可重试，退出不会自动重启游戏。
+- [ ] 桌面与移动导航、详情、上传/发布面板、旋转提示、全屏、安全区和焦点可达符合主规范；不适配移动端的游戏有明确门槛。
+- [ ] 视觉沿用现有 warm token，通用交互复用共享组件；没有固定假统计、本地演示兜底或同源 iframe 放宽。
+
+### 证据要求
+
+- 自动化：AGC 打包与操作恢复定向 Rust 测试、两端客户端/组件/路由/状态测试及类型检查。
+- 运行时：AGC 一次真实发布、网页一次真实 ZIP 上传，分别审核后从桌面和手机游玩；浏览器覆盖游戏模块、素材、音频、触屏及横竖屏。
+- 边界：未构建/失效 dist、资料缺失、换账号、迟到响应、审核拒绝、非移动游戏及真实空态。
+
+## 阶段 D：端到端、运维与上线准备
+
+### 前置条件
+
+- C 已验收；生产域名/TLS、CDN、私有存储、审核账号及保留/清理周期可用且已确认。
+
+### 行为与验收
+
+- [ ] 真实环境中完整跑通“首次上传 → 校验 → 审核 → 公开 → 游客游玩 → 更新待审旧版在线 → 新版切换 → 下架撤销”。
+- [ ] 100 MiB 包与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。
+- [ ] 校验执行器重启可恢复，审核积压与失败可观测，清理不删除仍被公开版本引用的文件。
+- [ ] CDN purge 失败时仍在获批缓存 TTL 内拒绝新资源；明确已下载脚本无法远程抹除的边界。
+- [ ] 发布/回滚步骤保留当前公开版本，能关闭新提交和新版本激活；部署路由、缓存、响应头、日志脱敏和告警完成检查。
+- [ ] 主规范逐条证据矩阵齐全，未验证项明确列出；有任何核心路径未验证时不标记上线完成。
+
+### 证据要求
+
+- 自动化：范围匹配前后端、schema/契约、编码与文档索引门禁，部署配置检查。
+- 运行时：真实发行域名、真实存储、真实账号和两类客户端的完整链路证据，桌面及移动视口记录。
+- 边界：压力/额度、重启恢复、缓存撤销、误删防护和回滚演练。
+
+## 当前待审项与下一门禁
+
+主规范仍待确认人工审核策略、导航、首版能力/额度、对象保留、发行域名及运营责任；当前没有主规范与里程碑通过评审的记录，也没有任何阶段验收证据。先评审这些决策，再冻结 A 的持久化与 DTO 明细并创建仅覆盖 A 的实施计划。不得把该文档状态改为 accepted 以代替评审。
+
+所有阶段完成并验收后，稳定事实回写主规范，删除本临时里程碑与各阶段实施计划；过程记录不进入产品代码、用户文案或长期共享记忆。
diff --git a/docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md b/docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md
index 04bfa55a1..15adcc42f 100644
--- a/docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md
+++ b/docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md
@@ -25,6 +25,7 @@
 - [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
 - [ ] 后台列表按部署渠道查询，显示项目名/ID、用户（昵称 + 陶泥号）、同步时间、文件数、体积和完整性，支持刷新与游标分页（每页 20/50/100 + 上一页/下一页）。
 - [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
+- [ ] `.agent` 承载项目身份与 Agent 状态，整目录随快照上传，并在后台 ZIP 中按原相对路径还原；归档因此可用于还原项目身份与 AGC 对话历史。凭据、版本库与构建产物仍不进快照。
 - [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
 - [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。
 - [ ] 无后台权限不能读取项目或 ZIP；不泄漏凭据；ZIP 构建有体积、并发和临时文件清理边界。
@@ -39,6 +40,10 @@
 | 层次 | 结果 |
 | --- | --- |
 | 客户端 Rust `project_snapshot` | 22 通过、1 忽略（写入式真实上传 smoke 未运行）；含排队退出等待回归 |
+| `.agent` 全量上传口径（2026-09-22 修订） | `project_snapshot` 定向 24 通过、1 忽略；新增扫描纳入 `.agent` 与策略单测，覆盖 `.agent` 内凭据、版本库、`.env*` 继续排除，以及项目索引 / checkpoint 口径不变 |
+| `.agent` 真实样本复核 | 对 15 个本地 AppData 项目的 487 个 `.agent` 普通文件按新规则复算，0 个仍落在排除集；该复算是脚本复刻规则，不是 Rust 运行时证据 |
+| `.agent` 客户端链路运行时 smoke（2026-09-22） | 用真实项目副本（`.agent` 164 个文件 / 5.61 MiB，项目 `gameagent-agentsmoke1`）走真实差异引擎 → 本地 api-server → 真实 OSS：首轮 `synced`、`uploaded=179` / `18,991,590` 字节、跳过与失败均为 0；紧接着第二轮 `no-op` / 上传 0 个文件。`uploaded=179` 恰好等于原口径的 15 个项目文件加 164 个 `.agent` 文件 |
+| `.agent` 存储与后台归档（2026-09-22） | 只读 GET 真实 OSS 清单对象（`agc/project-snapshots/v1/<user>/gameagent-agentsmoke1/manifest.json`，26,356 字节）：`files=179`、其中 `.agent/**` 164 条、`pendingFiles=0`、合计 18,991,590 字节；按清单里的 `大小-摘要` 构造对象键 HEAD 命中 `.agent/manifest.json`(18,319)、`.agent/agent.db`(9,353)、`.agent/conversations/project.jsonl`(1,422,226) 与 `game/package.json`(227)。后台 `download` 返回的 ZIP 解压出 179 条目、164 条在 `.agent/` 下，抽样 6 个文件（含 `agent.db`、会话、运行态文件）与本地 SHA-256 完全一致；正在运行的 dev api-server 列表显示同一项目 `files=179 status=ready` |
 | 客户端前端生命周期与启动器 | 3 文件、10 测试通过；完整 AGC typecheck、skill-pack、check-config 通过 |
 | 后台页面、API client、路由与样式 | 44 测试通过；admin-web typecheck/build 通过 |
 | 后端快照与权限 | 14 定向测试通过；未认证路由矩阵与页签映射 2 测试通过 |
@@ -53,3 +58,5 @@
 `npm run dev:api-server -- --api-port 4198 --bgfilter-worker-port 4199 --api-timeout-seconds 600` 编译成功，但当前工作区配置的本地数据库 `xushi-p4wfr` 在 `127.0.0.1:3101` 返回 404，启动认证投影无法完成，故 `/healthz` 及完整 HTTP smoke 未通过。仅本任务启动的 API/worker 已停止；没有清库、迁移数据库、改 `.env` 或替换其它项目的验证目标。
 
 尚未替换安装版、构建新客户端发布包或部署；提交推送按用户本轮授权执行。当前条款已有上述自动化与只读存储证据，最终验收仍等待当前工作区数据库就绪后的 HTTP 联调，以及新客户端的隔离实机自动上传验证；完成后再关闭里程碑并清理两份计划。
+
+`.agent` 全量口径已在上表取得真实上传、真实 OSS 清单与后台 ZIP 三层运行时证据。两点边界仍需记住：① 本次 smoke 用的是真实项目的可丢弃副本，其 `projectId` 改成 `gameagent-agentsmoke1`、走 dev 专用账号上传，历史真实项目在下一个同步周期前仍是旧口径清单（不含 `.agent`）；② 本地 `api-server.exe` 构建于 2026-09-21 14:06，早于渠道分区提交 `4951b71d7`（2026-09-21 16:57），因此本次对象键仍是 `agc/project-snapshots/v1/` 布局、`GET /admin/api/project-snapshots/channels` 在本地返回 404；升级到 v2 键布局需要重建并重启本地 api-server。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 572fd07b0..85b08d74d 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,10 @@
 # 决策记录
 
+## 2026-09-22 埋点分支同步发布入口与工作台更新
+
+- 合并 master `079466b29`，同时保留项目离开埋点与工作台运行通知、后台埋点查询与游戏发布审核入口；不扩大采集范围。
+- 本次冲突位于工作台相邻回调、后台 API 测试导入及本文件新增记录，均保留双方现役内容；Direct 聊天的认证重试埋点与 master 回合状态调整继续共存。
+
 ## 2026-09-22 埋点分支合并 DirectProject 聊天重构
 
 - 保留 master 的独立 DirectProject 聊天控制器及 canonical `userItem` 合同；旧 Supervisor、独立 prompt/attachments IPC 参数和已退役删除命令不恢复。
@@ -21,6 +26,47 @@
 - 本地采集阶段已验收明文 JSONL 持久化；当前仍不做加密。一个项目对应一个目标，事件按业务节点采集，5 分钟封存，7 天或 20 MiB 清理；上传失败也受保留上限约束。
 - 当前上传实现已完成隔离环境验收，证据见同一主规范第 13 节：每 15 分钟上传匹配当前账号与平台的封存批次，新增一张客户端事件私有表、批次原子入库与幂等确认、成功清理及独立后台明细栏目；失败静默留待下周期重试。真实客户端文件、HTTP、数据库与后台查询已关联同一事件验证，浏览器列表/筛选/详情通过；未部署生产。保持原 12 类事件和原采集边界。上线须配置 `GENARRATIVE_AGC_ANALYTICS_ORIGIN`，按数据库、API/后台、客户端顺序发布。
 - 已按技术负责人授权开始实施：合同与本地队列、会话窗口与项目接入、策划阶段成果、首次提交及两类 Agent run 已实现并经独立审查；定向测试、生产编译和前序 GUI 启停证据统一见主规范第 12 节。不得宣称完整产品采集已上线。
+## 2026-09-22 引用输入区改为宿主注入引用 provider，选择器面板与输入区分离
+
+- 背景：`ResourceReferenceInput`（`apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx`）同时承担「拿数据」与「编辑数据」：素材以未过滤 manifest 传入后由组件自己派生候选、显示名与「当前版本素材」scope，Skill 候选由组件自己 invoke `list_agc_skill_catalog` 与 `list_client_extensions`（只在用户敲出 `$` 时触发），素材选择面板与缩略图预览 invoke 也住在组件内部。后果是 5 个宿主（DirectProject 聊天、策划输入盒、画布生成面板、资源卡快速编辑、测试夹具）无差别获得 `$` Skill 候选，而只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（Rust `direct_codex_user_item_to_codex_turn_input`，`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/wire.rs`），其余宿主只把它退化成字面文本，形成误导入口。
+- 决策（注入）：输入区只接受宿主注入的 `providers: readonly ReferenceProvider[]`。每种引用一个独立工厂——`createResourceReferenceProvider({ assets })`、`useSkillReferenceProvider()`（Skill 候选是异步的应用级读取，所以它同时是宿主 hook：第一次候选菜单打开时才发起读取——`match` 保持纯函数，懒加载走 `onMenuQueryChange`，由输入区在 effect 里回调；结果到了宿主重渲染，读取不进输入区），附件与运行画面区域为静默 provider（无触发符、无候选）；**没有总装 builder**，宿主按需选择性注入。provider 暴露 `trigger` / `match(query)` / `toReference(part)` / `refresh(reference)` / `mentionToken(part)` 与可选的 `onMenuQueryChange(query)`（菜单懒加载的唯一入口，`match` 保持纯函数）与 `isReady()`（数据未到齐时输入区先不把初始草稿落成文本，否则草稿里的引用会被静默丢掉），输入区只按数组顺序取第一个非空回答，不判断引用种类。
+- 决策（分离）：素材选择面板拆成独立组件 `ResourceReferencePicker`（含一个可复用的 `@` 触发钮 `ResourceReferencePickerAction`），自己拿数据（`assets` / `versions` / `activeVersionId` / `projectPath` 与缩略图预览 invoke），由宿主渲染并把确认结果交给输入区句柄的 `insertReferences`——这是两者之间唯一的接缝。输入区删除 `versions` / `activeVersionId` / `showTriggerButton` / `openPicker` / `skills`，改为收宿主的 `inputActions`（操作排槽位，放触发钮）与 `submitSuppressed`（宿主浮层打开时 Enter 不提交，与候选菜单同一口径）；`projectPath` 只保留给输入区自己的润色链路。
+- 决策（附件）：附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件在**导入成功后**以芯片插入正文，`status === 'failed'` 或异常一律不插入；控制器不再持有 `attachments` 数组，`ComposerPendingAttachments` 与提交时的附件 parts 拼接一并删除，单次上限 `MAX_CHAT_COMPOSER_ATTACHMENTS = 8` 改为按草稿中的附件芯片数计算（否则上限失效），导入进行中禁止发送。
+- 决策（显示口径）：`directCodexContentToPromptText` 的引用 token 前后各补一个空白（相邻已是空白或相邻即另一个 token 时不重复），并加 `// TODO we will rewrite this with ref as component later.`；该函数的 `resourceId → 显示名` 反查改由调用方注入，函数自己不再读 manifest。
+- 原因：读项目/应用清单是后端副作用，按 AGENTS.md 的边界应留在宿主与后端侧，留在共享表现组件里既越界，又制造了「Skill 在所有输入区可见、只有一条路径可用」的误导。按种类分 provider 让选择性注入成为默认，避免再造一个把全部种类焊死、无法只注入资源或资源 + Skill 的总装层。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/**`、`apps/ai-game-creator-shell/src/view/project-development/**`（chat composer / controller、planning、index）、`apps/ai-game-creator-shell/tests/**`、`apps/ai-game-creator-shell/src/styles.css`，以及 `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`。
+- 顺带清理：`ProjectChatComponentProps.activeVersionId`（`apps/ai-game-creator-shell/src/features/app-shell/model.ts`）已无消费方——它只在策划输入盒的 `@` 面板里生效，而策划输入盒的 `@` 触发钮早在本次重构前就不渲染（`showTriggerButton={false}`），工作台壳自己的那份 `activeVersionId` 仍由 `ProjectDevelopmentView`（游戏运行版本）消费，因此只删「壳 → 聊天」这一段穿不过去的参数。
+- 未纳入本次：粘贴解析（未来接入点是 provider 的 `mentionToken` 与既有 `buildContentFromTextTokens`）、`resource-reference-*` CSS 类名重命名（独立机械提交）、扩展变更事件的即时失效。
+- 验证方式：定向 `npx vitest run apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx` 与受影响宿主用例、`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`；行为零变化按「改名后芯片显示名自动刷新、打开面板前重读清单、`@`/`$` 候选与键盘交互、附件上限与失败提示文案」逐条对照核验，唯一例外是已裁决的 Skill 可见性缺陷修复。
+
+## 2026-09-22 release 每日调度纳入正式 Full Build 并收集结果
+
+- 背景：原 `Genarrative-Scheduled-Release-Trigger` 只处理 AGC Windows/macOS，且对下游使用 `wait: false` 后立即推进 revision；正式服务端 release 仍只能人工触发，客户端构建失败也不会回传调度器。
+- 决策：release 调度同时计算 `AGC` 与 `FullBuild` 两条 scope。服务端相关路径变化时以 `DEPLOY_TARGET=release`、`CONFIRM_RELEASE_DEPLOY_AGENT=true` 触发 `Genarrative-Full-Build-And-Deploy`；客户端相关路径变化时保持统一发号并触发 Windows/macOS release。Full Build、Windows、macOS 三路均等待结果并汇总，只有成功的 lane 才推进对应 `.jenkins-last-release-full-revision` / `.jenkins-last-release-agc-revision`，失败 lane 在下一轮单独补发，避免重复部署已成功的服务端版本。`DATABASE_BACKUP_MODE` 默认 `async`，并显式提供 `STDB_API_ROLLOUT_MODE` / approvers 以保留正式维护门禁。
+- 原因：正式 release 需要与 dev 小时调度隔离，同时不能继续依赖人工触发服务端；lane-level 成功状态可区分“已成功但另一 lane 失败”的部分发布，避免下一次调度重复发布 Full Build。
+- 影响范围：`jenkins/Jenkinsfile.scheduled-release-trigger`、`jenkins/scheduled-release-trigger-job-config.xml`、`scripts/check-production-ops-guardrails.mjs`、开发运维文档与共享开发工作流。
+- 验证方式：生产运维门禁检查 Full Build release 参数、双 scope、`wait: true` 结果聚合、三路分支和成功后才写 lane revision；并用 Jenkins 具体构建验证 Full Build/AGC 的 build number 与结果能回传到调度 Job。
+
+## 2026-09-22 AGC release 增加每日调度，dev 调度保持双平台
+
+> 已被上一条决策取代：release 调度现已纳入正式服务端 Full Build。
+
+- 背景：原有 `Genarrative-Scheduled-Revision-Trigger` 每小时跟随 revision 发布 dev 客户端，但没有对应的 release 渠道自动入口；Mac 节点此前已纳入小时 dev 调度，需要避免新增 release 调度时再退回 Windows-only。
+- 决策：新增 `Genarrative-Scheduled-Release-Trigger`，每天 04:00 检查 `SOURCE_BRANCH`，使用独立的 `.jenkins-last-release-revision` 与客户端相关路径白名单；上一轮 release 调度后有客户端变更时，先经 `Genarrative-Agc-Global-Version-Issue` 发统一总号，再以同一固定 `COMMIT_HASH` 触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 的 `AGC_UPDATE_CHANNEL=release` 分区，Mac 继续带 `SKIP_IF_SUPERSEDED=true`。小时 dev 调度保持同时触发 Windows 与 macOS dev。
+- 原因：release 与 dev 是不同渠道和发布节奏，不能靠同一个小时 Job 隐式切换；独立 Job 能分别去重、记录状态和审计发号。release 调度不触发 Full Build，避免把桌面客户端发布与线上全栈部署绑定。
+- 影响范围：`jenkins/Jenkinsfile.scheduled-release-trigger`、`jenkins/scheduled-release-trigger-job-config.xml`、`jenkins/Jenkinsfile.agc-global-version-issue`、`scripts/check-production-ops-guardrails.mjs`、开发运维文档、共享开发工作流与 AGC 总版本号技术方案。
+- 验证方式：`npm run check:production-ops` 校验 release Job 的 cron、发号、双平台 release 参数、Mac 让位和 Copy Artifact 授权；`npm run check:encoding` 与 `git diff --check` 校验文件与补丁。
+
+## 2026-09-22 项目快照 `.agent` 全量上传：远端工程包要能还原项目身份与 Agent 历史
+
+- 背景：快照上传此前复用 `should_skip_project_snapshot_path`，把整个 `.agent`（`manifest.json`、`agent.db`、conversations、logs、runtime、checkpoint、workbench、`project.lock`）排除在上传集合之外。后台“项目工程”的「下载完整工程」是按清单逐文件打包的，于是导出的 ZIP 里没有项目身份与对话历史，用户在 AGC 里恢复不出同一个项目。
+- 决策：快照同步改用独立口径 `should_skip_project_snapshot_sync_path`（`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`）。它与原口径共用同一份组件与后缀规则（提取为 `PROJECT_SNAPSHOT_EXCLUDED_COMPONENTS` / `PROJECT_SNAPSHOT_EXCLUDED_SUFFIXES`），只额外放行两点：`.agent` 组件本身，以及 `.agent` 内的 Agent 状态数据库后缀 `.db`/`.db-wal`/`.db-shm`（`agent.db` 是项目状态而不是凭据转储）。扫描入口 `src-tauri/src/project_snapshot/scan.rs` 切到新口径。
+- 边界：`.agent` 内部的版本库 / 依赖 / 构建目录、凭据目录（`.ssh`、`credentials`、`secrets` 等）、`.env*` 与 `.pem`/`.key`/`.sql` 等敏感后缀继续排除；符号链接与重解析点照旧在扫描阶段跳过；单文件 64 MiB、单次 512 MiB、单项目 2 GiB 上限不变。项目索引、checkpoint、Agent 上下文与 git 检查继续使用 `should_skip_project_snapshot_path`（仍排除整个 `.agent`）——本变更只放开快照同步。
+- 代价与取舍：`.agent` 里的会话记录、运行日志与诊断快照会随项目离机并写入该用户自己的私有前缀，这是“可还原”的代价，属于本轮产品决定。服务端不需要改动：快照路径校验只检查路径形状，后台归档按清单逐文件打包，都不含 `.agent` 特判。模板包导入门禁（`IMPORT_FORBIDDEN_SEGMENTS`）与 CLI 模板发布门禁继续拒绝 `.agent`，不会因为这份 ZIP 而放宽。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`、`src-tauri/src/project_snapshot/{scan.rs,tests.rs}`；主规范 `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-17 AGC 项目定时快照上传”与“后台工程列表与下载”两节；`docs/project-memory/plans/` 的两份里程碑与实施计划。
+- 验证方式：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot`（24 passed、0 failed、1 ignored），新增用例覆盖 `.agent` 整目录进入候选集、`.agent` 内凭据与 `.env*` 仍被排除、项目索引与 checkpoint 口径不变；另用同一份规则复算 15 个本机 AppData 项目的 487 个 `.agent` 普通文件，0 个仍落在排除集。
+- 运行时证据（2026-09-22）：真实项目副本（`.agent` 164 文件 / 5.61 MiB，`projectId=gameagent-agentsmoke1`）经真实差异引擎 → 本地 api-server → 真实 OSS `agc-dev`：`uploaded=179`（= 原口径 15 个项目文件 + 164 个 `.agent` 文件）/18,991,590 字节、`synced` 后第二轮 `no-op`；只读 GET 远端 `agc/project-snapshots/v1/<user>/gameagent-agentsmoke1/manifest.json` 得 `files=179`（`.agent/**` 164 条）、HEAD 命中 `agent.db` 等对象；后台 download 的 ZIP 含 179 条目（164 条 `.agent/`），抽样文件 SHA-256 与本地一致。注意该 bucket 仍是 `v1/` 键布局：本地 `api-server.exe`（2026-09-21 14:06）早于渠道分区提交 `4951b71d7`（16:57），重建重启后才会写 `v2/{channel}/`。
+
 ## 2026-09-21 合并 origin/master：Supervisor 永久退役，策划 V1V2 退役落到当前两条产品路径
 
 - 背景：`refactor/split-direct-project`（DirectProject 独立聊天容器）与 `origin/master`（#355 退役策划 Agent V1/V2）在 2026-09-18 之后各走一条线：本分支删掉 Supervisor 前端链路、把立项策划收敛到 `view/project-development/planning/`，master 删掉整套策划 V1/V2（前端会话 / 审批卡 / 适配器 / 类型与 Rust `planning_*_v2` 命令、`planning_gdd_model.rs`、`planning_policy_v2.rs`、`planning_session_v2.rs`）只保留 Design Agent。两边都在删 Supervisor，冲突集中在 `App.tsx`、聊天视图（`PlanningChatView`、`DirectProjectTurn`、`ToolCallGroup`）、Direct composer / 引用输入区、`styles.css`、Rust direct user item 与 appSurface 用例。
@@ -298,6 +344,42 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
 - 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
 - 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
 
+## 2026-09-20 游戏分发用灰度开关承载「关闭投稿、保在线」的回滚口径
+
+- 背景：主规范要求回滚部署时“关闭新提交和新版本激活，保留当前可玩版本与状态读取”。此前只能靠改配置或停服实现。
+- 决策：复用现役灰度配置（`game-distribution:publish`，后台「灰度发布配置」可改），没有 gate 行或 `enabled=false` 时默认开放；`enabled=true` 时只有白名单/标签/灰度命中的作者能发布，`rolloutPercent=0` 且无白名单等于紧急关闭投稿。拦截范围是作者写入（创建游戏/版本、上传、送审、撤回、下架）与管理员批准；读取、发行网关、审核队列读取、拒绝审核与安全下架始终可用，避免把“关投稿”变成“停服务”或“无法处理事故”。
+- 失败姿态：开关读取失败按关闭处理（写入口 503），读取路径不受影响。
+- 关联：`server-rs/crates/module-runtime/src/application.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[开发运维文档](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
+
+## 2026-09-20 游戏发行包 PUT 采用受控重试与容量边界口径
+
+- 背景：阶段 D 容量验证时实测 99.0 MiB 发行包单次 PUT 成功耗时 11.8s、api-server 峰值内存 378 MB（基线 82 MB），但三次尝试里出现过一次 `请求 OSS 失败：error sending request`。当时版本停在 `awaiting_upload`（可原版本重传），代价是作者白传一次整包。
+- 决策：`platform-oss` 新增 `put_internal_object_with_retry`，复用既有 `oss_error_is_retryable` 分类（传输/超时/connect、408、429、5xx、400+RequestTimeout 可重试；确定性 4xx 不重试），body 只转一次引用计数的 `Bytes`，各 attempt 复用同一份字节；发行包上传配置为 3 次尝试、250/500ms 退避，参数不合法（次数为 0 或缺退避）时按配置错误失败关闭。
+- 容量口径（真实栈实测，作为阶段 D 证据基线）：99.0 MiB 包 11.8s / 峰值 +296 MB；声明 101 MiB 在创建版本即 413；请求体 101 MiB 被请求体限制 413 且版本保持可重传；压缩比 1000 与单文件 65 MiB、10,001 文件都是 422 `PACKAGE_VALIDATION_FAILED` 并落到 `upload_failed`/`reupload`；失败包不进公开目录。
+- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[实施计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)。
+
+## 2026-09-20 游戏详情的“游玩方式”以版本声明的 inputModes 为准
+
+- 背景：公开投影里 `currentVersion.controls` 一直是空数组（首版没有自由文本操作说明的录入），详情页却只读它，于是所有已发布游戏都显示「未标注操作方式」，而作者其实在发布时声明过 `inputModes`。
+- 决策：展示层优先用公开投影里已有的结构化 `inputModes`（键盘 / 鼠标 / 触屏，去重后按声明顺序拼接），再退回 `controls` 自由文本，两者都为空才显示「未标注操作方式」。不改 HTTP 契约、不新增后端字段。
+- 关联：`src/components/game-distribution/GameDetailPage.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 游戏分发的版本回读、撤回与安全下架以服务端 recoveryAction 为准
+
+- 决策：游戏发行版本的「下一步做什么」不从客户端状态推断。`GET /api/game-distribution/versions/{versionId}`（作者）与 `/admin/api/game-distribution/versions/{versionId}`（管理员）返回版本私有投影 + 服务端派生的 `recoveryAction`（`upload` / `submit` / `wait` / `none` / `reupload` / `fix_package` / `fix_metadata`），网页发布页与作者中心只按它渲染主行动作。
+- 撤回语义：`POST /api/game-distribution/versions/{versionId}/cancel` 只能撤回未参与当前公开投影的版本，要求 `Idempotency-Key` 与 `expectedPublicationRevision` CAS；已公开版本必须走作者下架或管理员 `suspend`，不能借撤回关闭线上入口。
+- 可见性：未知版本与非 owner 的版本一律 404，不用 403 区分「别人的版本」和「不存在的版本」。
+- 幂等响应：命中既有幂等收据的写操作统一回传 `replayed: true`（此前所有写操作固定 false），客户端据此区分「本次生效」与「复用既有结果」。
+- 网页恢复：`/games/publish` 只把 `{ownerUserId, gameId, versionId, versionNumber, title}` 写入 localStorage 作为恢复标识；换账号只忽略草稿、不回读也不清除，禁止展示上一账号的私有状态。
+- 关联文档：[游戏分发实现计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-18 AGC backend 采用共享 Runtime、本地宿主与云端控制面分层
+
+- 决策：AGC backend 统一按“`agent-runtime-core`/`agent-runtime-orchestration` 共享内核 + Tauri 本地执行宿主 + `server-rs` 云端控制面 + `module-*`/`platform-*` 领域与外部适配器”整理；先建立 application facade、能力合同和跨边界状态映射，不新建第二套 Agent Runtime、会话库或业务真相。
+- 数据边界：本地项目文件、manifest、JSONL、checkpoint、锁和 Runner 状态由 AGC 本地宿主持有；认证、模型目录、编辑器资源、异步生成、计费、快照元数据和诊断由云端持有；大对象按现有 OSS 合同保存。
+- 约束：Runtime core 不依赖 Tauri/Axum/SpacetimeDB/Provider；领域规则留在 `module-*`；HTTP/SSE/BFF 留在 `api-server`；SpacetimeDB 访问统一经 `spacetime-client`；外部服务统一经 `platform-*`；前端只消费后端或本地宿主投影。
+- 权威文档：[AGC 后端框架整理与演进路线](../../technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)。
+
 ## 2026-09-17 AGC 抠图提交使用远端画布项目身份
 
 - 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
@@ -9333,3 +9415,41 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（空白口径）：`directCodexContentToPromptText` 逐字投影、不再 `trim`（前端只在整条 content 上判空）；出站提示词的收边规范化收敛成一个共享函数 `resourceCanvasAssetGenerationPromptText`，面板校验与任务落账共用，图集走 Unicode White_Space、其余走 JS 口径。
 - 影响面：`apps/ai-game-creator-shell/src/features/{project-workspace/resourceReferences.ts,project-workspace/ResourceReferenceInput.tsx,resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx,resource-canvas/resourceCanvasAssetGenerationTaskModel.ts,resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx` 与对应 6 个定向测试文件。
 - 验证：定向 `resourceCanvasAssetGenerationReferences` / `resourceCanvasAssetGenerationBackgroundClose` / `resourceCanvasBottomToolbar` / `resourceCanvasGenerationFloatingPanel(Chrome)` / `resourceReferenceInput` / `resourceReferences` / `resourceCanvasAssetGenerationTasksPanel` 全绿；全量 `npm run test -- apps/ai-game-creator-shell/tests` 只剩 `clientHttp` / `clientApi` / `clientAuthStorage` / `projectCreationDirectory` / `recentProjectsHook` 五个 jsdom `localStorage` 环境用例红（与本次改动无调用关系）；TS typecheck、`check:encoding`、`git diff --check` 通过。未复核真实客户端观感。
+
+## 2026-09-22 运行页收口：过程提示退出对话区，顶栏统一承载运行入口
+
+- 背景：点播放（以及历史上 `/preview`、`/open-preview`、生成后自动启动预览）都会往对话区写一条 assistant 提示（`运行通过，已载入客户端运行视图：http://127.0.0.1:63155/` 这类）。它常驻对话底部遮挡运行画面，也让对话区混进非对话内容；运行页本身还有三处遮挡与两套皮：预览地址是一行常驻小字（不可点）、版本入口是绝对定位压在画面右上角的浮层、右上角还叠着「生成任务」开关。
+- 决策（对话区只留对话内容）：运行 / 预览的反馈不再进对话区，**成功与失败都**走工作台壳的 toast——`ProjectChatComponentProps.onRunNotice` → `RunNoticeToast`（同一句连续触发重新计时；成功 2.6 秒收起，失败 6 秒收起，`tone` 决定观感）。失败三处：启动预览报错（`运行游戏失败：…`）、缺 Tauri / 缺项目这两条前置条件、以及「在浏览器打开失败」。原先承载这些文案的 `announceProjectChatMessage` 已无调用方，连同删除。
+- 与上一条的关系（2026-09-21「预览激活回接运行入口」）：那条接线决策（先问 Rust 要活体预览、命中就只切视图不重启）原样保留；被本次改掉的只是它当时为这条链路选的**播报渠道**——`经 DirectProjectChatHandle.announce 说一句「已切换到客户端运行视图：<url>」` 按验收反馈（提示常驻对话底部遮挡运行画面）改成 toast，「复用活体预览不重启」的判据与 `tests/previewActivation.test.tsx` 的三条路径不变。
+- 决策（运行页顶栏是唯一入口）：运行区域上方的状态行与预览地址小字整体退役（运行画面回到两行栅格）；预览地址改成顶栏动作区里的一枚「在浏览器打开」按钮（opener 插件的 `openUrl`，只在有活预览时渲染；`scripts/check-native-shells.mjs` 另加「视图里 `openUrl(` 只有一个调用点」的判据）；版本入口搬进同一个顶栏动作区，外观复用 `.game-workbench-view-actions button` 的基础规则，不再自带边框 / 底色 / hover，也不再是绝对定位浮层。版本入口在**资源画布与运行页**显示，UI 编辑器壳里不渲染（那一页是聚焦编辑某个资源的界面）。版本名改用一层 span 承载省略号——按钮是 flex 容器，文本直接挂在按钮上时 `text-overflow` 不生效。
+- 决策（运行页不挂生成任务）：`ResourceCanvasAssetGenerationTasksPanelView` 只在资源画布 / UI 编辑器出现，运行页的入口、面板与锚点都不渲染；`[data-generation-tasks-placement='run']` 那一档坐标与组件 `placement` 联合类型里的 `run` 一并删除。任务不丢，切回资源页即可见。
+- 边界：预览的**启动与切换**仍然只走内置运行画面、不自动开系统浏览器——`scripts/check-native-shells.mjs` 那条负向守卫保持原样，本轮只补「浏览器入口只有顶栏这一枚按钮」的正向断言。
+- 影响面：`apps/ai-game-creator-shell/src/{App.tsx,styles.css,view/project-development/index.tsx,features/app-shell/*,features/resource-canvas/*}`；用例新增 `tests/runPreviewBrowserOpen.test.tsx`、`tests/runNoticeToast.test.tsx`、`tests/runNoticeShellWiring.test.tsx`（外壳级：替身聊天发提示 → 壳真的渲染浮层）、`tests/gameRunToolbarActionsStyle.test.ts`，改写 `tests/previewActivation.test.tsx`（原断言「聊天里出现已载入运行视图」的地方改为断言 toast 通道 + 对话容器里没有这类提示，并补一条「启动失败走失败色提示且不写对话区」）与 `tests/appSurface/project-development.suite.ts` 的生成任务入口用例。
+- 验证：`appSurface` 全量、AGC 壳目录全量、`npm run typecheck`、`check:native-shells:contract`、`check:encoding`、`git diff --check` 全绿；真机观感未复验。
+
+## 2026-09-22 DirectProject 聊天状态显式化：回合三态 + 「在跑吗」唯一派生入口 + 数据流地图
+
+- 背景：DirectProject 聊天框只有三份真相源（`project.jsonl` 历史切片、Thread Manager 运行态事件、本地乐观消息），但「这一轮在跑吗」在四层里各叫一个名字——reducer 的 `turnRunning`、controller 的 `turnBusy`、视图里手拼的 `busy`、投影里的 `active`。定位发送后空窗缺陷时，读代码无法判断某个窗口期的界面表现是否有依据，也说不清谁该信谁。
+- 决策（三态取代布尔）：`DirectChatTurn.active` 改为 `DirectChatTurn.state: 'running' | 'awaiting-start' | 'finished'`。`running` 只由 reducer 的 `turnRunning` 决定；`awaiting-start` 由「最新一轮的用户条目身份 = 本地在途的 `pendingUserItemId`（`direct-codex:{clientTurnId}:user`）、且本轮还没有明确终态」决定；其余是 `finished`。判据是身份不是时间戳，`pendingUserItemId` 由 controller 在 `beginTurnCommand()` / `endTurnCommand()` 里与 `turnBusy` 同生共死。
+- 决策（单一派生入口）：新增 `useDirectProjectTurnStatus()`，返回 `{ nativeRunning, commandInFlight, displayBusy, latestTurnState }`。header / composer 只读 `displayBusy`（两者并集，语义与原来的 `turnBusy || directTurnRunning` 完全一致），「陶泥儿正在处理」卡片只读 `nativeRunning`。约定：新增「忙 / 在跑」类判据先落进这里，不在组件里另拼布尔。
+- 决策（地图落代码）：三层数据流、三份原始输入、一次发送的时序（含空窗步骤）与状态变量归属写进 `apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表写进 `.../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。不另开技术方案文档——这套说明是给改这块代码的人看的，放代码里才不会与实现脱节。ADR 补一条「活动回合唯一判据约束的是**原生回合**」的澄清与代码指针。
+- 口径更正（2026-09-22，同日第二条）：本条记录的「`awaiting-start` 暂时与 `finished` 同渲染」已由随后的三态接入渲染改动修掉，见下面那条。
+- 边界（本次不修）：`awaiting-start` 暂时与 `finished` 同渲染，所以空窗期内仍会显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」；`Math.max(turn.endedAt, turn.startedAt)` 的兜底与 `DirectProjectTurnUsage` 的渲染条件都没动。同源的第二条缺陷也记录在案：`turnEndedAt` 只是会话内展示缓存，页面重进后所有已结束回合都会走同一条兜底显示 0.0 秒（临时渲染用例实测确认，用例未入库）。修法与证据要求见下面那条（三态接入渲染）以及 `DirectProjectTurn.tsx` 里标注未修范围的注释。
+- 验证：`npx vitest run` 定向 `directTurnPresentation`（17 条，新增 4 条三态用例）、`directProjectTurnStatus`（4 条）、`directHistoryPaging`（9 条）全绿；`appSurface.test.ts` 202 passed / 13 skipped；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。真实客户端观感与窗口期表现未在客户端复核。
+
+## 2026-09-22 空窗期不再谎报「本轮结束」：DirectProject 三态接入渲染
+
+- 背景：上一条只把回合三态显式化，渲染层仍按 `state === 'running'` 判断，于是「本地已发出、宿主还没回 `turn.started`」的窗口里 `awaiting-start` 被当成 `finished` 渲染，显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」（用户现场反馈的现象）。
+- 决策（判据分两类，不许对调）：**否定式**判断（不要说它结束、不要折叠过程、不要显示终态文案）读 `state !== 'finished'`；**肯定式**判断（哪段正文在流式、「陶泥儿正在处理」卡片与滚动已耗时）读 `state === 'running'`。理由是 `awaiting-start` 能支持"还没结束"，但不能支持"宿主已经在跑"——后者只有 `turn.started` 能证明。
+- 决策（卡片口径取保守）：`DirectProjectConversation` 的「正在处理」卡片与 `activeTurnStartedAt` 仍只认 `turnStatus.nativeRunning`，窗口期不出现这张卡片。文案是「陶泥儿正在处理」，在 `turn.started` 之前无法断言宿主已经开始，这与空窗缺陷是同一个病根（把"本地已发出"当成"宿主已在跑"）；窗口期用户看到的是"消息已发出 + 输入框忙"，语义诚实。若将来改成窗口期也显示卡片，`running` 在渲染层就没有消费者了，那时应把投影压成 `unfinished: boolean`，不要留一个没人读的状态成员。
+- 边界（A 仍未修）：`DirectProjectTurnUsage` 的 `Math.max(turn.endedAt, turn.startedAt)` 兜底没动，所以两类 `finished` 回合仍显示「耗时 0.0秒」——① 页面重进后读回来的历史回合（`turnEndedAt` 只是会话内展示缓存）；② 发送后没有产生任何原生事件 / 发送失败的本地回合。为什么会有这两类、修法与要产品确认的口径都写在代码里（`DirectProjectTurn.tsx` 的 `DirectProjectTurnUsage` 注释与 `directTurnPresentation.ts` 的 `DirectChatTurnState` 注释），改完删掉那段注释。
+- 验证：`tests/directProjectTurn.test.tsx`（新增 3 条渲染契约：`awaiting-start` 与 `running` 不显示终态文案且不折叠、`finished` 有终态时显示结束时间与耗时）；`tests/appSurface/chat-composer.suite.ts` 新增 `does not report a finished turn while the host has not acknowledged the send yet`（invoke 挂起、无任何原生事件时断言不出现「本轮结束于」）；变异验证：把 `state !== 'finished'` 退回 `state === 'running'` 后渲染契约用例变红，恢复即绿。定向 vitest、`appSurface.test.ts`（203 passed / 13 skipped）、`tsc`、ESLint、Prettier、`check:encoding`、`check:doc-index`、`git diff --check` 通过。真实客户端观感未复核。
+
+## 2026-09-22 宿主崩掉不再留下永远开着的回合：本地命令失败时按身份兜底收口
+
+- 背景：`turn.started` / `turn.completed` 是原生回合唯一的开闭配对，界面上的「正在处理」卡片与输入盒忙态都读 reducer 的 `turnRunning`。但 app-server 崩了、回合任务被中止或 panic 时没人补终态事件，事件流里就留一条永远开着的 `turn.started`：界面一直显示「陶泥儿正在处理」、输入盒一直排队（用户现场反馈）。
+- 决策（本地命令返回即这一轮在宿主那边收场）：`chat_with_game_creator_direct_codex` 以真失败返回时，controller 按本轮身份调用 `stopDirectThreadTurn`，只放掉「是否在跑」，**不写终态时间**——命令返回不等于知道这一轮真正的结束时刻，编一个只会让耗时变成假数。用户主动终止与「正在跑的是另一轮」两条不适用：前者宿主必然补终态，后者不是这一轮（不能顺手抹掉别人的回合）。
+- 决策（身份作用域 + 不复活）：`stopDirectThreadTurn` 只在 reducer 里的运行身份相同或为空时生效；收口记进 `commandClosedTurnUserItemId`，同身份迟到的 `turn.started` 不再把这一轮拉回运行态（迟到的 `turn.completed` 例外放行，仍要拿它补上真正的结束时间）。身份按 clientTurnId 唯一，所以这条记忆只挡它自己那一轮。
+- 影响面：`apps/ai-game-creator-shell/src/view/project-development/chat/{conversation/directThreadChat.ts,controller/useDirectThreadChatSubscription.ts,controller/useDirectProjectChatController.ts}` 与 `apps/ai-game-creator-shell/tests/{directThreadChat.test.ts,appSurface/chat-composer.suite.ts}`。
+- 验证：reducer 新增 2 条用例（兜底收口后同名 `turn.started` 不复活且真终态仍能补上结束时间；身份不同的回合不动），appSurface 新增 `stops claiming the turn is running when a failed send left turn.started open`；变异验证：拿掉 controller 里的兜底收口调用后该用例变红（界面仍显示「陶泥儿正在处理」），恢复即绿。
+- 边界（未做）：根因仍在宿主侧——要在进程内保证开闭配对，应由 Rust 在回合函数退出（含 panic / 任务中止）时补一条终态事件（drop 守卫）；本次只做到前端不再跟着说谎。另：兜底收口的回合没有终态时间，仍会落进「`finished` 但拿不到终态时间」那个已知缺口（终态文案要不要藏，见 `DirectProjectTurn.tsx` 与 `DirectChatTurnState` 注释里的 A 项）。
diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md
index 78ec2adfa..000ce042f 100644
--- a/docs/project-memory/shared-memory/development-workflow.md
+++ b/docs/project-memory/shared-memory/development-workflow.md
@@ -92,10 +92,18 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 
 ## Jenkins 定时版本调度
 
-定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 传给 `Genarrative-Full-Build-And-Deploy`，并先经 `Genarrative-Agc-Global-Version-Issue` 发号、再把同一个总版本号透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，保证两个客户端的平台分区发布同一个版本。这三个下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。macOS 节点是日常办公机，调度触发它时置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+定时与版本比较收口到两条调度器：`Genarrative-Scheduled-Revision-Trigger` 每小时处理 dev 渠道，变化时触发 Full Build、AGC Windows/macOS dev，并让两个客户端平台共用同一个总版本号；`Genarrative-Scheduled-Release-Trigger` 每天 04:00 按服务端与客户端两条独立 scope 处理 release，服务端变化时用 `DEPLOY_TARGET=release` 触发正式 Full Build，客户端变化时经 `Genarrative-Agc-Global-Version-Issue` 发同一个总号并触发 AGC Windows/macOS release。两条调度都等待并汇总下游，按成功 lane 推进 revision；失败 lane 下一轮单独补发。各下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住回退。macOS 节点是日常办公机，两条调度触发它时都置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## Gitea CI 依赖闭合
 
-AGC Rust lane 1 试点镜像内可信 sccache 对象快照，lane 2 保持直接 rustc 作为对照。维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中生成快照，最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计。线上存在活跃 CI 时不得重启 runner 或切换标签；候选镜像和真实无缓存/冷/热对照验收见开发运维文档。
+Gitea 基础镜像通过专用 `genarrative-ci-images` Buildx builder 持久复用 Cargo/npm 下载缓存；稳定 cache mount 与 commit、lock 哈希无关，以 `sharing=locked` 隔离并发写入，仅供可信宿主构建、不开放给 PR。最终镜像显式物化当前依赖下载快照，仍不包含 node_modules/target 或上一版 sccache 层。首次可用 `seed-downloads` 从可信完整 Image ID 提取包缓存，操作账号须与维护服务一致；部署要求及 builder GC 空间目标见 `deploy/container/README.md`。构建上下文必须覆盖 AGC vendor 与编辑器 bridge 的全部本地 path manifest，普通源码变化不应使依赖层失效。维护 journal 提供阶段耗时和失败 build.log 定位。
+
+Gitea Rust 缓存自动维护由宿主 `genarrative-ci-cache.timer` 收集同一 master push run 六个 Rust job 的原生 V4 缓存产物，不重复执行 Cargo 预热。只传本轮新 key，命中对象只传使用时间；宿主与真实来源镜像对象合并、去重、按新近使用时间裁剪到 4 GiB，从无对象缓存基础镜像重新组装。源 run 不要求全绿，但取消、缺组、旧 attempt、未完成上传或混用来源镜像不得采用。网关暂停新 FetchTask、在途领取结束、持久化任务账本清空且内层活动容器为空才切换，不打断运行中的 CI。首次接入/升级网关需空闲窗口；Token 只需普通仓库 `write:repository`，不查管理员 API。候选装载后清理已收集 artifact，遗留项保留 7 天；真实 master CI 验证后才清理旧镜像，保留当前、一个回滚版、基础镜像及容器引用。部署入口见 `deploy/container/README.md`，合并代码不等于服务启用。
+
+修改 Gitea workflow 的 job 显示名称、ID 或缓存导出组时，必须同步维护器的 `JOBS` / `RUST_JOB_IDS`；`test_gitea_cache_maintenance.py` 直接对照实际 workflow 检查全集和导出映射，避免自动刷新或镜像验收因名单漂移长期等待。维护器 `Api.request` 的 `method` 是必填关键字参数，GET 也必须显式指定，不根据 body 推断请求方法。
+
+Gitea 缓存部署必须区分网络：runner 的 RPC 走 `gitea-runner-fetch-gate:8080`；内层 job 的 checkout/上传走映射到 `172.30.0.3` 的 `http://genarrative-station/git`；宿主专用 clone 走 `http://127.0.0.1:3003`。不要把 runner 可达的 `gitea:3000` 配给 job。内层 Docker 使用 `10.240.0.0/16`、每 job `/24` 的默认地址池，避开外层 `172.30/172.31` 网段；恢复领取前必须在真实 job 网络里验证 checkout 与 Gitea API，不能只验证 FetchTask。具体配置与遗留空网络处理见 `deploy/container/README.md`。
+
+AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。仅首次人工 bootstrap 时，维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。
 
 `.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。两条 Rust lane、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译后按 `--list` 名单分 4 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index fe0dd8996..7e2d98345 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,20 @@
 # 踩坑与排障记录
 
+## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查
+
+- **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。
+- **原因**：`capabilities/main.json` 已为封面与截图直传加入 `https://*.aliyuncs.com/*`，`scripts/check-native-shells.mjs` 的精确白名单仍只有五项，且误以为更新下载迁至原生 updater 后就不再需要 OSS 权限。`assetDirectUpload.ts` 仍通过 Tauri HTTP 插件执行素材直传。
+- **处理**：契约期望同步包含现有 OSS HTTPS 项，保留完整白名单精确比较；不得删除业务所需权限或改成任意 URL 放行。更新下载与素材直传是不同调用链，变更能力配置时同步检查调用方和契约。
+- **验证**：运行 `npm run check:native-shells:contract` 与 `apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts`；缓存完整性以实际 artifact 和导出日志为准，不能仅看上传 step 是否成功。
+
+## release 安装包文件名中的编码空格不能按控制字符拒绝
+
+- **现象**：release 环境点击“下载客户端”只显示无法获取最新版本，`GET /api/client-downloads` 返回 `502 UPSTREAM_ERROR`；dev 环境正常。
+- **原因**：release 渠道产品名为“陶泥儿 Release”，NSIS 首装包名因此包含空格，OSS `latest.json` 中的 URL 使用 `%20`。`validate_download_url` 的百分号解码校验把 `0x20` 当成控制字符拒绝，Windows 清单被判非法；release macOS 清单当时又未发布，聚合后两端都无下载项并返回 502。
+- **处理（现行口径）**：清单 URL 校验允许百分号编码的空格，继续拒绝其它控制字符、`/`、`\`、DEL、非法编码和跨目录文件名；不得通过改写真实产物名绕过校验。
+- **验证**：`platform-oss` 用 `陶泥儿%20Release_0.1.110_x64-setup.exe` 做清单解析回归；线上修复后接口应返回 release Windows 下载项，macOS 未发布时进入 `unavailablePlatforms`。
+- **关联**：`server-rs/crates/platform-oss/src/client_downloads.rs`、`apps/ai-game-creator-shell/scripts/build-release.mjs`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
+
 ## 客户端图标素材描述不能先包装再截断
 
 - 现象：资源画布填写了具体图标需求，平台实际收到的 `iconDescriptions` 却只包含泛化的小游戏美术指令，生成结果不遵循输入。
@@ -42,6 +57,14 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只
 
 `Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET=release` 只控制 Stdb / API / Web 全量发布，不会自动成为 AGC 的 `AGC_UPDATE_CHANNEL`。2026-09-21 的手工发布 #10 就因此让 Windows #107 与 macOS #16 使用默认 `dev`，把 `0.1.95` 上传到 `agc/dev-win`、`agc/dev-mac`，而 `agc/release-win/latest.json`、`agc/release-mac/latest.json` 保持 404。现行口径：手工入口按 `release -> release`、`development -> dev` 同时给 Windows 与 macOS AGC Build 传 `AGC_UPDATE_CHANNEL`；补发已烧号的同一版本时用相同 `AGC_RELEASE_VERSION` 直接重跑两条 AGC Job，不重新发号。OSS 发布对象是 `agc/<channel>-win|mac/`，不存在 `agc/release/` 这一层。
 
+## Jenkins 渠道参数会进入 Node 测试进程，默认值测试必须隔离环境
+
+- **现象**：release 渠道的 macOS Job 在 Tauri 构建前的 `build-release.test.mjs` 失败，唯一差异是 `no-bundle smoke skips version writes and manifest generation` 期望 `dev`、实际得到 `release`；构建尚未进入 Rust/Tauri 编译。
+- **原因**：Jenkins Job 参数 `AGC_UPDATE_CHANNEL=release` 会成为子进程环境变量，而该测试直接依赖未设置的默认渠道，却只显式传了 `--target` 和 `--no-bundle`。
+- **处理（现行口径）**：断言默认渠道、默认目标等环境派生值的测试，必须用现有 `withEnv` 显式清除相关变量；构建入口继续按 `AGC_UPDATE_CHANNEL` 选择渠道，不为迁就测试改生产逻辑。
+- **验证**：用 `AGC_UPDATE_CHANNEL=release node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs apps/ai-game-creator-shell/scripts/cargo-features.test.mjs` 复现并验证修复，未设置变量时也必须通过。
+- **关联**：`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`。
+
 ## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃
 
 - 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
@@ -5455,7 +5478,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - 原因：tauri-bundler 的 `download_and_verify` 现场从 GitHub 取 NSIS 工具链，只有一次机会、没有重试；响应体被截断即报 `io: unexpected end of file`，看起来像打包错误其实是网络问题。Checkout 阶段的 `git clean -fdx` 每次都会清掉 `target/.tauri`，所以每个构建都要重新下载，在受限网络下必然反复失败。
 - 处理：新增 `apps/ai-game-creator-shell/scripts/nsis-toolset.mjs` 与 `ensure-nsis-toolset.mjs`，在 `buildRelease`（Windows 目标且需要打包时）与 Jenkins `Tauri NSIS toolchain` 阶段按固定 SHA1 预置 `target/.tauri/NSIS`：原始归档带 4 次重试，缓存在工作区外的 `%ProgramData%\genarrative\tauri-nsis-cache`（可用 `AGC_TAURI_NSIS_CACHE_DIR` 覆盖），镜像开关沿用 bundler 的 `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR_TEMPLATE` / `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR`。该阶段同时执行 `makensis.exe -VERSION`，把 2026-09-02 记录的缓存目录不可执行问题也提前到编译之前暴露。Checkout 阶段改为 `git clean -fdx -e apps/ai-game-creator-shell/src-tauri/target/.tauri`：Tauri 的工具缓存位于工作区内，裸 `git clean -fdx` 会连它一起删，排除后同一节点的稳态构建不再需要联网，只有冷缓存（新节点、工作区重建）才下载。
 - 验证：`node --test apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs`（已就绪零下载复用、缓存离线还原、失败重试、哈希不符与归档越界失败关闭）与 `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs`；真实节点上该阶段必须早于 Rust 编译失败关闭。
-- 注意：不要改回 `bundle.useLocalToolsDir: false` 去用 `%LOCALAPPDATA%`，也不要依赖 PATH 里预装的 `makensis`；升级 `@tauri-apps/cli` 时同步核对归档 URL、SHA1 与必需文件清单。
+- 注意：不要改回 `bundle.useLocalToolsDir: false` 去用 `%LOCALAPPDATA%`，也不要依赖 PATH 里预装的 `makensis`；升级 `@tauri-apps/cli` 时同步核对归档 URL、SHA1 与必需文件清单。回归测试自身也必须跨平台：仓库根目录用 `fileURLToPath(new URL(...))` / `defaultAppRoot()` 解析，不能用 `URL.pathname` 得到 `/C:/...` 后再 `path.resolve`；模拟 Windows 与 POSIX 缓存路径时要分别使用 `path.win32` 与 `path.posix`，不要用当前节点的原生分隔符断言另一平台。
 
 ## AGC 登录态续期必须同步本地运行时
 
@@ -5909,6 +5932,56 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。
 
+## 2026-09-22 自动合并"无冲突"也可能静默拼坏 CSS 分组选择器
+
+- **现象**：合并 master 时 git 报告 0 冲突，但 `apps/ai-game-creator-shell/src/styles.css` 里新加的头条规则被并进了 master 策划态分组选择器的中间——`.game-workbench-layout--design .project-chat-topbar-status,` 后面直接跟了别的选择器，策划态的 `font-size` / `color` 等声明整块丢失；类型检查与多数用例都不受影响，只有 `chatDialogFrameLayout` 这类 CSS 级联用例报"缺少生效声明"。
+- **原因**：双方在同一分组选择器附近各自插入规则时，hunk 可以"兼容"地拼在一起，git 不会报冲突，但选择器列表被拆散。
+- **处理**：改完 CSS 后按 master 原文重建分组规则、把新增规则独立成块；顺手删掉重复规则时要用带上下文的精确片段，避免删到分组选择器的第二个选择器。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts`（12 用例）与全量 `npm test` 通过。
+
+## 2026-09-22 合并 master 时“双方保留”不是通用解法
+
+- **现象**：把分支与 master 的同一批冲突统一按“ours + theirs 依次保留”处理后，`apps/admin-web/src/api/adminApiTypes.ts`、`api/adminApiClient.ts`、`app/adminRoutes.test.ts` 都出现语法/结构错误（接口少闭合、函数体被截断、用例少 `});`）。prettier 能通过、vitest 里被转译的纯类型文件也不报错，只有 `tsc`（admin-web typecheck）与随后单文件跑测试才暴露。
+- **原因**：冲突块可能切断一个语法结构（接口、函数、`test(...)` 调用），而双方各自的块只是在“同一位置添加内容”，拼起来会丢闭合；类型文件在 vitest 里被 esbuild 直接剥离类型，不会校验。
+- **处理**：冲突若落在语法结构内部，按“以某一侧为完整骨架、把另一侧的新增内容插到正确位置”重建，而不是简单拼接；重建后必须跑 `tsc`（含 `npm run admin-web:typecheck`）并对改动文件单独跑一次 vitest，别只看全量测试是否绿。
+- **验证**：合并后 admin-web 23 个测试文件 212 用例全绿、两端 typecheck 通过。
+
+## 2026-09-20 复用注册端口段时可能连到别的 worktree 的 SpacetimeDB
+
+- **现象**：在 `/data/dsk/Genarrative` 跑 `npm run dev:api-server` 后，日志显示端口段 `10000-10099 (dsk)`、spacetime `http://127.0.0.1:10002`，但 api-server 反复报 `ws://127.0.0.1:10002/v1/database/xushi-p4wfr/subscribe` 返回 `HTTP error: 404 Not Found`，且始终不响应 `/healthz`。
+- **原因**：该端口段是**按用户**登记的，同一用户的其他 worktree 实例已占用 `10002`；启动器只探测到端口被占用就按"已复用"继续，api-server 于是连到了另一份 data-dir 的 standalone，那里没有当前 database，发布步骤也没有落到这个实例上。api-server 在启动恢复阶段会一直重试，**accept 了连接但不返回任何响应**，所以 `curl` 表现为超时而不是连接拒绝。
+- **处理（现行口径）**：核对 `ss -ltnp | grep :10002` 的进程与 `--data-dir` 是否属于当前仓库；不属于就换用空闲端口段（`GENARRATIVE_DEV_PORT_RANGE` / `--port-range`）或先停掉确认无用的实例，不要把 404 当作 schema 缺失去改代码。排查"健康检查通过但接口 404"时不要只跑 `/healthz`。
+- **关联**：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`/var/tmp/genarrative-dev-port-ranges/registry.json`、[`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`](../../../.codex/skills/genarrative-dev-stack-port-routing/SKILL.md)。
+
+## 2026-09-20 新增 API 命名空间在本地返回 404：Vite 代理是前缀白名单
+
+- **现象**：api-server 上 `GET /api/game-distribution/games` 直连返回 200，但浏览器里 `http://127.0.0.1:<web>/games` 报 `404`，页面显示「读取游戏目录失败」。同一 URL 换成 `curl` 直连后端却正常。
+- **原因**：`vite.config.ts` 的 `server.proxy` 是**逐个前缀白名单**（`/api/auth`、`/api/profile`、`/api/runtime`、`/api/editor`、`/api/assets`、`/api/llm`、`/api/ws`），没有兜底 `/api/`。未登记的新命名空间不会转发到 Rust 后端，而是回退到 SPA 静态资源，前端再按 JSON 解析就失败。生产 nginx 走的是通用 `location ^~ /api/`，所以症状只出现在本地 dev。
+- **处理（现行口径）**：新增任何 `/api/<namespace>` 时，同一次变更里补 `vite.config.ts` 代理项和 `src/config/viteProxyConfig.test.ts` 断言；`src/config/**` 已加入 `vitest.config.ts` 的 include，漏测会直接红。注意该测试文件里可能残留已退役前缀（例如已退役的 `/api/creation-entry`）的断言，退役命名空间按「四不写」直接删断言，不要为它补代理。
+- **关联**：`vite.config.ts`、`src/config/viteProxyConfig.test.ts`、`vitest.config.ts`、`server-rs/crates/api-server/src/app.rs`、`deploy/nginx/genarrative.conf`。
+
+## 2026-09-20 发行网关用 CORP same-origin 会让沙箱内游戏加载不了自己的脚本
+
+- **现象**：平台游玩页的 iframe 明明 `onLoad` 了（加载遮罩消失、`game-player-frame--ready`），但控制台出现 `net::ERR_BLOCKED_BY_RESPONSE.NotSameOrigin … /releases/<gameId>/assets/app.js`，游戏内的脚本从未执行；直接在新标签页打开同一个 `index.html` 却一切正常，很容易误判成「已经能玩」。
+- **原因**：按安全合同 iframe 必须只用 `sandbox="allow-scripts"`（禁止 `allow-same-origin`），文档因此是不透明来源（opaque origin）。此时它对同包资源的请求不再与网关同源，而响应上的 `Cross-Origin-Resource-Policy: same-origin` 会把请求判为跨来源并拦下；ES modules 还会额外走 CORS，需要 `Access-Control-Allow-Origin`。
+- **处理（现行口径）**：发行网关的公开静态响应使用 `Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`，继续保留 `X-Content-Type-Options: nosniff`、内容类型白名单、HTML 最小权限 CSP 和「带 Cookie 一律 403」。这些都是公开静态文件，放宽 CORP/CORS 不暴露凭据；容器隔离靠沙箱、CSP 与独立来源，不靠 CORP。
+- **验证方式**：不要只用 `onLoad` 判断可玩。要在真实浏览器里点「开始游戏」，确认控制台没有 `ERR_BLOCKED_BY_RESPONSE`/CSP 报错，并核对 api-server 访问日志里该版本资源的 `http.response.status_code=200`。
+- **关联**：`server-rs/crates/api-server/src/modules/game_distribution.rs`（`release_asset_response`）、`src/components/game-distribution/GamePlayPage.tsx`、[`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 在 jsdom 里把 AGC 发布接到真实后端：Blob 没有 arrayBuffer，且跨 realm BodyInit 会被 undici 拒绝
+
+- **现象**：给 AGC 的 `publishLocalProjectGame` 写“默认跳过”的真实后端集成测试时，创建游戏、创建版本都成功，只有上传 ZIP 报“无法连接登录服务”（`networkError: true`），服务端访问日志里也没有这次上传。
+- **原因**：测试跑在 jsdom 环境，`fetch` 是 Node(undici)，但请求体是 jsdom 的 `Blob`：① 该 jsdom 版本的 `Blob` 没有 `arrayBuffer()`（`typeof blob.arrayBuffer === 'undefined'`），直接调用会抛异常；② 即便拿到字节，jsdom realm 的 `ArrayBuffer`/`Uint8Array` 也不是 undici 认得的 `BodyInit`。
+- **处理（现行口径）**：桥接层用 `FileReader.readAsArrayBuffer` 读 jsdom Blob（有 `arrayBuffer` 时才走它），再用 `Buffer.from(new Uint8Array(...))` 复制成 Node 侧 Buffer 交给 undici。参考 `apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`。
+- **关联**：`apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`、`apps/ai-game-creator-shell/src/services/clientHttp.ts`。
+
+## 2026-09-20 AGC 导出后自动弹发布面板：焦点陷阱会吞掉模态之外的点击，既有导出快捷操作用例变红
+
+- **现象**：给 AGC 加「导出试玩包后自动打开发布到游戏广场面板」后，`appSurface.test.ts` 的「预览快捷操作：导出确认、取消与包列表」变红——期望点消息上的「显示目录」把 `/open-project` 填进输入框，实际输入框仍是空。把发布面板的自动打开去掉，或用例先关掉面板，就恢复绿色。
+- **原因**：同目录的 `ThemedModal` 用 `createPortal` + `focus-trap-react` 渲染模态。焦点陷阱存在时，模态之外的 `click` 不会触达 React 的处理器（实测：临时把 `FocusTrap` 换成普通 `div`、其余不动，同一个被模态遮住的按钮点击立刻恢复生效），所以自动化里“点模态背后的按钮”不会报错，只是静默无效。
+- **处理（现行口径）**：① 产品行为保留“导出成功后自动打开面板”（一键发布入口），但受影响的用例必须先用 `findByRole('dialog', { name: '发布到游戏广场' })` 断言面板出现、点「关闭发布面板」再继续后续会话操作；② 给这类“新增自动弹窗”改流程时，先跑一遍相关 `appSurface` 用例，避免只跑新增用例；③ 排查同类“点了没反应”时，先看当前是否有焦点陷阱模态打开，而不是先怀疑事件绑定或状态。
+- **关联**：`apps/ai-game-creator-shell/src/App.tsx`（`setPublishPanelOpen(true)`）、`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-preview/preview-shortcuts/assert-project-tools-and-preview.ts`。
+
 ## 2026-09-21 受控 Lexical 输入区的回写用被动 effect：滞后渲染的 props 会把用户草稿清空
 
 - **现象**：DirectProject 输入盒里粘贴（或连续输入）长文本，提交时 `chat_with_game_creator_direct_codex` 根本没发出去，界面停在空输入盒；`chat-composer` 用例里表现为「队列/终止/语音追加」五条一起红，但手工操作只在快速输入后偶发。
@@ -5943,6 +6016,18 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 
 `append_application_log_line` 在落盘前对整行做 `sanitize_diagnostic_message`：行内只要出现 `token=`、`bearer `、`authorization`、`credential`、`api key` / `apikey` / `api_key` 这类标记，**整行**就被换成 `<sensitive diagnostic details redacted>`，只留下时间戳与 `RUST module:` 前缀；同时每行还会被截到 2048 字符。于是把“身份字段 + 诊断正文”拼成一行 `app_log!` 时，正文里一个凭据词就可能让整条记录连 `eventId`、`code` 一起消失（2026-09-21 加统一错误事件的日志投影时按两行落：身份行只放程序生成与调用方常量字段，summary / hint / detail 等自由文本一律只放详情行，且自由文本先自行压平换行——裸词标记脱敏消不掉，自由文本放错行会把 eventId、code 一起带走）。
 
+## 2026-09-22 本地 node_modules 里的内置 Codex 原生包过旧会让 AGC build script panic
+
+- **现象**：`npm run agc` 编到壳 crate 的 build script 时中止，stderr 是 `panicked at build.rs:103: Codex 原生包版本、布局或架构不匹配目标 x86_64-pc-windows-msvc`，stdout 只有 `cargo:rustc-env=AGC_BUILD_TARGET=...`。
+- **原因**：`build_support/codex_bundle.rs` 把随包 Codex CLI 钉在一个固定版本，而本地 `node_modules/@openai/codex-win32-x64/vendor/<target>/codex-package.json` 还停在上一次安装的旧版本。`package-lock.json` 早就升到新版本，缺的只是本地安装；这条判据只看版本元数据，文件齐全、架构正确也照样拦。
+- **处理（现行口径）**：在仓库根目录执行 `npm ci`（不要改成子目录或单包安装），随后 `node_modules/@openai/codex/package.json` 与 vendor 的 `codex-package.json` 版本应当一致。Windows 上 `npm ci` 会先 unlink 整个 `node_modules`：RustRover 的 Tailwind language server / `oxide-helper` 进程会占住 `@tailwindcss/oxide-*.node`，报 `EPERM: operation not permitted, unlink ...` 时先结束这些 helper 再重试，否则会停在半装状态。
+- **验证**：`npm ci` 后 `cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 通过，不再触发该 panic。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`、`apps/ai-game-creator-shell/src-tauri/build_support/codex_bundle.rs`、`package-lock.json`。
+
+## 策划聊天不能按可选子节点序号分配消息高度
+
+策划与开发 Agent 共用聊天类名，但布局合同不同。策划新增状态条后，按第二个子节点分配 `1fr` 会把空白给状态条、让消息框随回复增长；只给 `.is-direct-codex` 的状态样式也不会覆盖策划。策划使用纵向 Flex，仅消息列表伸缩，阶段/待处理区域限高滚动；改共用样式时同时核对两种入口。jsdom 交互通过不代表布局正确，须匹配完整 CSS 层叠并用真实浏览器核对空/短/长消息与长待办。窄屏上下堆叠必须在固定外壳内提供工作台滚动容器，两块面板明确限高；低优先级的 `height: auto` 不能覆盖外壳后代规则的 `height: 100%`。布局夹具必须包含窗口外壳与启动器层级，并实际滚动验证输入框可见可操作，不能只检查输入框在聊天面板内部。实时正文/思考不更新持久消息数组，滚动跟随必须覆盖这些独立状态并保留用户上滚门禁；历史消息缺失的时间不得用读取时刻填补。详见 AGC 实施计划的“策划 Agent 对话显示与滚动合同”。
+
 ## 2026-09-22 Rust 对象快照必须对齐 CI 编译目录和 Cargo 环境
 
 - 现象：sccache 快照已包含数百 MiB 对象，但全新 target 的“热缓存”仍然全部 miss，甚至比直接 rustc 更慢。
@@ -5950,4 +6035,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - 处理：预热使用已核实的 Gitea 路径 `/workspace/GenarrativeAI/Genarrative`，并与分片运行器一样从 AGC `src-tauri` 启动 Cargo；保存 `workspace.txt`，路径不符时回退直接编译。wrapper 放在容器内固定路径，daemon 状态与 Unix socket 仍使用随机私有目录；预热环境与 workflow 的 Cargo 环境由定向契约测试核对。不要为命中率随意增加 `RUSTFLAGS`、改写源码路径或恢复共享可写 target。
 - 验证：相同源码、资源上限和独立干净 target 下分别记录无缓存、冷缓存、热缓存的编译耗时和 hit/miss；只有真实热命中有净收益才切换候选镜像。PR 的写入始终留在 job 容器层，公共快照仍由可信维护流程生成。
 - 统计：job 私有 daemon 设置 `SCCACHE_IDLE_TIMEOUT=0`，由 `report` 显式停止；最终测试 bin 的不可缓存编译或测试可能超过一分钟，短 idle timeout 会让 daemon 提前退出，结尾查询启动新 daemon 后误报零次请求。容器销毁仍会回收该 job 的全部进程。
-- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。2 GiB 上限不涵盖宿主旧镜像及导出归档，切换验证后按运维文档人工保留当前版和一个回滚版，同时保护运行中 CI 使用的镜像。
+- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。对象缓存容量上限不涵盖宿主旧镜像及导出归档。自动维护只回收自己预先登记的 Image ID/tag 和专属归档，保留当前、一个回滚版、基础镜像及所有容器引用；内层按 ID 导入的镜像可能没有 tag，不能只按 tag 判断已清理。接管前历史试验版本仍需人工确认。
+- CI 产物清理：Gitea 1.26.4 的仓库 REST 仅列出 finalized/expired V4 artifact，内置到期清理不回收上传中断的 tmp-upload 分块。缓存上传块须带专属标识，宿主只清理目标仓库已结束且超过 7 天的 master run 中同样过期的自有普通文件，未知文件/符号链接保护，不改数据库或全局 prune。Artifact.workflow_run 仅含 ID/SHA，判断过期产物所属事件和状态须再读 run API，不能当作完整 run 使用。
+- 自动切换：Gitea 1.26.4 的 disabled 检查与 FetchTask 事务不原子，Runner 客户端超时不能证明服务端回滚，容器暂时为空也不能证明没有已领取任务。网关必须解析实际 Connect Protobuf/gzip，转发 FetchTask 结果前持久化任务 ID，仅在最终日志及执行清理后的最终 UpdateTask 确认后清账；取消响应不能提前释放。暂停新领取、在途为零、账本为零且内层活动容器为空才可切换，无需全局 Runner admin API。未知协议/响应或崩溃遗留标记停止切换；旧网关缺 active_tasks 不能默认零。首次接入与账本升级须空闲窗口。.runner 的 mtime 不证明地址已加载，应核验真实 FetchTask 来源及本次容器启动时间。
+- 扩展：预热所有 Rust 测试组时保留各自 cwd、profile、features 和锁策略；同一临时 target 的 Cargo fresh 不代表不同 cwd 都已生成缓存键，AGC 提示词契约、分片和 smoke 切换入口前清理预热 target。不要把 workspace 与 spacetime-module 合并成一次编译；Native shell release step 清空双 wrapper，避免将测试缓存扩展成发布缓存。当前 sccache 0.18.0 的 READ_ONLY 在 miss 后仍打包产物并产生 cache write error，不适合用来承诺“未命中无开销”。
diff --git a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
index 68388ccc4..7e5f202f8 100644
--- a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
+++ b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
@@ -1,6 +1,6 @@
 # AGC 客户端更新检查与下载
 
-更新时间：`2026-09-21`
+更新时间：`2026-09-22`
 
 本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。
 
@@ -27,6 +27,7 @@
 - 数据不跨渠道共享：本地项目、工程快照、模板、登录态、诊断日志与 Runner/项目锁按渠道身份分目录。切渠道等于换一个客户端，不迁移、不合并本地数据；渠道内的 origin 隔离规则不变。
 - 主窗口与工作区/启动器窗口标题取构建期产品名，让同机并存的渠道客户端在任务栏与 Alt-Tab 中可区分；默认渠道标题仍是「陶泥儿」。
 - 首装包与更新包的对象名包含产品名（如 `陶泥儿 Release_0.1.96_x64-setup.exe`、`陶泥儿 Release_0.1.96_aarch64.dmg`）。清单 `downloads` 地址由发布脚本按本次真实产物派生，禁止写死产品名；首装包选择按 `<版本>_<架构>.dmg` 唯一匹配，不依赖产品名字面量。
+- 产品名中的空格在清单 URL 中必须使用标准百分号编码（如 `%20`）；网站服务端允许这种合法文件名编码，但仍拒绝控制字符、路径分隔符、DEL 和非法百分号编码，不得通过改写真实产物名绕过校验。
 - Windows 提权 ACL 修复助手按目录名识别安装身份：`<基线>` 与 `<基线>.<渠道>` 都在 AGC 自有的 managed 范围内；相似前缀（例如 `world.genarrative.ai-game-creator-backup`）不在范围内，落回 user-selected 范围或直接拒绝。
 
 ## 非目标
@@ -136,8 +137,8 @@
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
 - 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
-- 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
-- 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
+- 定时调度分别判断服务端与客户端 scope：dev 小时调度在提交含 AGC 相关路径时发布对应渠道，纯文档或流水线自身的提交仍只跑 Full Build；release 每日调度在服务端相关路径变化时发布正式 Full Build，在 AGC 相关路径变化时发布 release 客户端，并在同一调度内等待、汇总各 lane 结果，失败 lane 下一轮补发。判定失败或勾选强制触发时按"需要发布"处理。
+- 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题`，标题只取 commit message 第一行并忽略后续说明行；最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
 - 上传：安装包与 `.sig` 上传到 `agc/<channel>-win|mac/<version>/`，清单以 `--force` 覆盖上传到对应分区的 `latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
 - 首装发布：发布脚本生成 `downloads`，Windows 复用已选 NSIS `.exe`，Mac 选择本次版本和目标架构匹配的非空 `.dmg`；缺失、歧义或版本/架构不匹配时失败，不发布带悬空地址的清单。上传顺序为更新包、签名及首装包全部成功后再更新渠道清单，Windows 相同对象只上传一次。`dry-run` 不写 OSS。各渠道独立写自己的清单，由 BFF 汇总，Windows 与 Mac 发布不会覆盖彼此的下载项；Mac 跨架构合并仍遵循现有单架构发布约束。
diff --git a/docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md b/docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md
index fad9d5cef..0d39ddb27 100644
--- a/docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md
+++ b/docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md
@@ -1,6 +1,6 @@
 # AGC 总版本号与发号
 
-更新时间：`2026-09-20`
+更新时间：`2026-09-22`
 
 ## 背景
 
@@ -18,7 +18,7 @@ AGC 客户端此前按「渠道各自比高水位自增」发号：`dev-win` 与
 
 - `next = 总号 + 1`；总号不存在时先一次性播种，见下节。
 - 顺序固定为「先写总号 → 再构建 → 再发渠道清单」；任何一步失败都不回滚，只烧号。
-- 统一构建：发一次号，通过 `AGC_RELEASE_VERSION` 同时传给 `dev-win`、`dev-mac`（以及后续渠道），各渠道共用同一个号。
+- 统一构建：发一次号，通过 `AGC_RELEASE_VERSION` 同时传给同一渠道组的两个平台；dev 调度写 `dev-win` / `dev-mac`，每日 release 调度写 `release-win` / `release-mac`，组内共用同一个号。
 - 单渠道热修：发一次号，只传给该渠道；其他渠道清单保持原值。
 - 显式传入 `AGC_RELEASE_VERSION` 的构建不再自行发号，只做高水位断言。
 
@@ -39,8 +39,8 @@ AGC 客户端此前按「渠道各自比高水位自增」发号：`dev-win` 与
 - 发号模块：`apps/ai-game-creator-shell/scripts/agc-global-version.mjs`（读总号 / 播种 / 发号 / 写后回读 / 渠道高水位断言 / dry-run 预览）。
 - 发号入口：`apps/ai-game-creator-shell/scripts/issue-global-version.mjs`（CI 与本地共用，输出固定为 `AGC_GLOBAL_VERSION=<version>`）。
 - 构建侧：`build-release.mjs` 的 `prepareReleaseVersion()` 优先采用传入总号，未传入时现场发号；`resolveRemoteHighWaterVersion()` 降级为断言来源，只用于「请求号低于本渠道清单版本即失败关闭」。
-- CI：`jenkins/Jenkinsfile.agc-global-version-issue` + `jenkins/agc-global-version-issue-job-config.xml`；调度管线 `jenkins/Jenkinsfile.scheduled-revision-trigger` 与手动管线先调发号 Job，再把号透传给 AGC Build。
-- 发号 Job 的 Copy Artifact 采用生产权限模式，`options` 里的 `copyArtifactPermission(...)` 必须显式列出**全部**消费者：定时调度 `Genarrative-Scheduled-Revision-Trigger` 与手动发布 `Genarrative-Manual-Build-And-Deploy`。用户触发的构建按「认证用户」判权（SYSTEM 定时构建短路放行），漏列时手动发布会报 `Unable to find project for artifact copy: Genarrative-Agc-Global-Version-Issue`，且失败点在发号之后。改完该 `options` 后必须先单独跑一次发号 Job，让 Declarative Pipeline 把 Job property 写回 Jenkins。
+- CI：`jenkins/Jenkinsfile.agc-global-version-issue` + `jenkins/agc-global-version-issue-job-config.xml`；dev 调度管线 `jenkins/Jenkinsfile.scheduled-revision-trigger`、每日 release 调度管线 `jenkins/Jenkinsfile.scheduled-release-trigger` 与手动管线先调发号 Job，再把号透传给 AGC Build；release 调度的服务端 Full Build 不使用 AGC 总号，只使用固定 `COMMIT_HASH` 与 Full Build 自身版本。
+- 发号 Job 的 Copy Artifact 采用生产权限模式，`options` 里的 `copyArtifactPermission(...)` 必须显式列出**全部**消费者：小时 dev 调度 `Genarrative-Scheduled-Revision-Trigger`、每日 release 调度 `Genarrative-Scheduled-Release-Trigger` 与手动发布 `Genarrative-Manual-Build-And-Deploy`。用户触发的构建按「认证用户」判权（SYSTEM 定时构建短路放行），漏列时手动发布会报 `Unable to find project for artifact copy: Genarrative-Agc-Global-Version-Issue`，且失败点在发号之后。改完该 `options` 后必须先单独跑一次发号 Job，让 Declarative Pipeline 把 Job property 写回 Jenkins。
 
 ## 不改的东西
 
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 8613a787b..a311db87c 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -241,6 +241,25 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
 
 Rust 分片日志在失败时输出有界 stdout 尾部中的失败段，保留 panic 位置、断言详情和 Rust 汇总；selected 只表示该分片选中的用例数量。成功分片保留简短摘要。定向验证使用相关 Rust 用例与 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`。
 
+## 策划 Agent 对话显示与滚动合同
+
+策划工作台的对话区保留阶段状态、工作区状态、消息、可选确认/澄清和输入区。面板高度由工作台和视口决定；空消息、短回复和流式长回复不能改变消息区域的上下边界。阶段、状态条、输入区按内容排列，消息区独占剩余空间并内部滚动；待处理卡片出现时只让出其实际所需且有上限的空间，不依赖可选节点的序号分配伸缩高度。
+
+- 工作区状态条复用现有聊天状态条的字号、间距和状态点。长项目名允许换行，不能撑宽面板；长错误、澄清和批量文件导入结果在受限区域内完整可读，不能挤走输入框。输入编辑器保留原有高度上限，模型/推理菜单继续允许弹出面板。
+- 已在消息底部时，实时正文与思考增高后继续跟随；用户主动上滚阅读历史后不自动抢回底部，发送新消息后恢复跟随。阶段/待处理卡片改变消息可用高度时，仍遵守同一跟随意图。滚动仅为临时 UI 状态，不写入正式会话。
+- 历史消息只有收到真实发送时间才能显示时间。现有策划持久消息不含逐消息时间，读取或刷新时保持未知，不以当前时刻补造。当前会话刚提交的乐观消息可以显示已知发送时间；正式快照覆盖后不补造或猜配旧消息时间。
+- ≤760px 时资源区与对话区单列排列，策划工作台在固定外壳内纵向滚动，用户向下滚动可到达输入区。布局使用内容高度，并以同等或更高选择器优先级覆盖外壳的 `height: 100%`；资源区明确为 560px，对话区高度为 `clamp(560px, calc(100dvh - 154px), 900px)`。文件树与消息列表各自内部滚动，长内容不增加两块面板高度。>760px 继续共用外壳剩余高度，不启用工作台整体滚动。正式主窗最小宽度不变，窄屏验收覆盖浏览器响应式布局。
+- 审批、澄清、导入期间禁用、错误重试、项目归属和发送权限沿用现有行为。此次调整不改变 Runtime、API、持久协议或数据库，无数据迁移；不重做开发 Agent 的对话布局。
+
+验收使用策划组件与现有界面测试覆盖流式/历史跟随、未知时间、审批澄清和导入禁用；使用真实浏览器与当前样式核对桌面/窄屏的空、短、长消息，长项目名、长错误与长澄清，以及输入框和菜单位置。布局验收必须包含 `window-chrome → window-chrome__content → launcher-shell → launcher-main → game-project-workbench` 的完整外壳层级，覆盖 390px、760px、761px 和桌面尺寸；窄屏实际滚动工作台后，输入框须进入可视范围且可操作，长文件树、长消息和待确认内容不能使面板失去高度边界。不能只断言输入框位于聊天面板内部。开发 Agent 的既有布局回归同批执行。真实 Provider 请求不作为纯展示修复的前置条件，验证记录须区分模拟事件与真实 Provider。
+
+| 验收面 | 对应证据 |
+| --- | --- |
+| 策划与开发 Agent 布局隔离、伸缩与窄屏滚动可达 | `chatDialogFrameLayout.test.ts` 包含外壳的选择器层叠回归；Chrome 实际组件、完整外壳与完整样式的 390px/760px/761px/桌面几何、滚动和输入操作检查 |
+| 实时正文/思考跟随、上滚停留、发送恢复 | `appSurface/design-agent.suite.ts` 的实时事件与发送恢复用例；还原旧滚动依赖时新增用例失败 |
+| 历史未知时间与乐观发送时间 | 同套界面测试覆盖读取、乐观发送和正式快照覆盖；恢复 `Date.now()` 补造时新增用例失败 |
+| 审批/澄清、文件导入禁用及共用控件 | `appSurface.test.ts` 现有交互回归与 Chrome 模型菜单位置检查；不改变原生调用和业务状态 |
+
 ## 策划 Agent 批量局部修改
 
 `patch_file` 的所有 edits 均匹配同一份原文件，参数顺序不影响结果。完成唯一匹配与不重叠校验后，按原文起点升序拼接未修改片段与替换文本，最后一次性写入；任一校验失败时不写文件。回归用例覆盖乱序 edits、中文内容与替换长度增减，并核对完整落盘内容。此行为仅属于策划 Agent 文件工具。
@@ -1805,7 +1824,8 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 失败关闭：单个文件失败不推进该文件的索引项，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（401/403）与格式类拒绝（400/413）是确定性失败，停止本轮剩余请求并等待用户处理后重试；服务端配额或频率拒绝（429）与传输类失败按可重试处理。
 - 配额与限流：单文件 64 MiB、单次同步上传预算 512 MiB（超出部分延后到下一次）、单项目常驻上限 2 GiB（客户端在扫描后先判，超限直接给出明确失败；服务端按清单累计体积复核并返回 413）；服务端按用户做进程内小时配额（文件 3000 次、清单 120 次）并对同一项目强制 5 秒最小清单间隔，超限返回 429 且带 `Retry-After`。进程内配额只用于抑制异常客户端与失控重试，跨节点配额由"单项目上限 + 清单引用回收"保证。
 - 生命周期：同步有界超时（单文件与整次同步分别设上限），项目关闭与应用退出路径不因同步失败而阻塞或延迟退出超过超时上限。
-- 上传内容边界：复用项目索引与 checkpoint 同一份 `should_skip_project_snapshot_path` 口径——整个 `.agent`（含 runtime、logs、checkpoint、manifest、project.lock）、版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录与 `.pem`/`.key` 等敏感后缀都不参与同步；符号链接与重解析点同样跳过。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
+- 上传内容边界：`.agent` 是项目身份与 Agent 状态的权威位置，**整目录参与同步**（`manifest.json`、`agent.db` 及其 WAL/SHM、conversations、logs、checkpoint、workbench、`project.lock`、`.manifest.json.lock`）。因此快照同步使用独立口径 `should_skip_project_snapshot_sync_path`：它与 `should_skip_project_snapshot_path` 共用同一份组件与后缀规则，只额外放行 `.agent` 组件本身，以及 `.agent` 内的 Agent 状态数据库后缀（`.db`/`.db-wal`/`.db-shm`）。其余排除项在 `.agent` 内同样生效——版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录、`.pem`/`.key`/`.sql` 等敏感后缀与 `.env*` 都不参与同步；符号链接与重解析点在扫描阶段跳过（不能被当作普通文件传输）。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
+- 该口径只对快照同步生效：项目索引、checkpoint、Agent 上下文与 git 检查继续排除整个 `.agent`。收录 `.agent` 意味着会话记录、运行日志与诊断快照随项目离机并写入该用户自己的私有前缀，这是本轮产品决定（远端工程包要能还原项目身份与 AGC 历史），不是遗漏。
 
 ### 契约与兼容
 
@@ -1829,7 +1849,7 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 只读取该用户/项目的固定清单与其引用对象，返回 `application/zip` 附件。ZIP 中路径直接使用原始相对路径，不包含 userId、摘要目录或 OSS 前缀；名称使用经过安全处理的项目名和 revision。下载固定本次读到的清单，远端并发回收导致对象缺失则整体失败，不能静默遗漏。
 - `partial` 快照下载返回 409；`unverified` 历史快照可导出已同步文件，列表明确显示“完整性未知”，动作称“下载已存文件”。`ready` 才显示“下载完整工程”。ZIP 构建核验每一文件的长度与 fnv1a64 摘要，拒绝穿越、绝对路径、重复/大小写冲突路径、非法项目身份；缺失或损坏整体失败，不返回成功的残缺 ZIP。
 - ZIP 使用服务端临时文件并限制并发，不将 2 GiB 工程整体驻留内存；成功、失败、客户端取消均清理临时文件。单文件、总量、文件数沿用上传上限，超限明确拒绝。零字节工程文件可以上传和导出。OSS 凭据与签名不下发浏览器，列表失败保留错误而非伪造空列表。
-- 工程归档范围与上传策略一致：源码、素材及引擎配置按原路径保存，依赖/构建缓存、凭据、`.agent` 会话与运行日志排除；此 ZIP 不声明能恢复 AGC 对话历史。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
+- 工程归档范围与上传策略一致：源码、素材、引擎配置与 `.agent`（含会话、运行日志、checkpoint、`agent.db`）都按原相对路径保存，依赖/构建缓存与凭据排除；因此该 ZIP 可以还原项目身份与 AGC 对话历史（归档只保证字节还原，不承诺跨机器可用性）。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
 - 验收覆盖真实单窗口生命周期登记、首次/增量/零字节上传、后台列表分页和权限、ZIP 解压目录及摘要、部分/历史清单、缺失对象、路径拒绝、下载取消清理，并分别报告定向测试和真实环境证据。
 
 ### 未决问题
diff --git a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
index 317fb6bb0..940c49ff5 100644
--- a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
+++ b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
@@ -1,15 +1,29 @@
 # AGC 聊天素材引用
 
-更新时间：2026-09-21
+更新时间：2026-09-22
 
 AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，并提供 Codex 风格的 Skill 提及。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；输入 `$` 会按当前 DirectProject 可用 Skill 名称过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。
 
+## 引用来源由宿主注入（2026-09-22）
+
+`ResourceReferenceInput` 只接受宿主注入的一组「引用 provider」（`ReferenceProvider`，每种引用一个独立工厂）：
+
+- `createResourceReferenceProvider({ assets })` → `@` 素材候选；
+- `useSkillReferenceProvider()` → `$` Skill 候选（读取应用级 Skill 目录，只在用户第一次敲出 `$` 时发生——输入区在 effect 里回调 provider 的 `onMenuQueryChange`，`match` 本身是纯函数；失败会放开重试）；
+- 附件与运行画面区域是**静默 provider**（无触发符、无候选），只参与正文 part 的身份解析、改名刷新与文本形态。
+
+输入区按 `providers` 数组顺序取第一个非空回答，不判断任何引用种类，也没有总装 builder。**没注入就没有这类引用**：只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（Rust `direct_codex_user_item_to_codex_turn_input`），所以只有它注入 Skill provider；策划输入盒、画布生成面板、资源卡快速编辑与画布生成浮层只注入资源 + 两个静默 provider，不再出现退化成正文文本的 `$` 误导入口（已裁决的缺陷修复）。
+
+素材选择面板拆成独立组件 `ResourceReferencePicker`：自己拿数据（`assets` / `versions` / `activeVersionId` / `projectPath` 与缩略图预览 invoke），自己管打开态与两个页签的筛选状态，由宿主渲染并把触发钮放在自己的位置（输入区操作排的 `inputActions` 槽，或宿主自己的控制排）。确认后只经 `insertReferences` 把选中的引用交回输入区——这是两者之间唯一的接缝。输入区不再收 `assets` / `versions` / `activeVersionId` / `skills` / `showTriggerButton`；`projectPath` 只留给输入区自己的润色链路。
+
+引用在正文文本里的形态（出站给 agent、润色、队列 chip 的那一份）由各 provider 的 `mentionToken` 决定，每个 token **前后各留一个空白**（相邻已是空白或相邻就是另一个 token 时不重复补），与「token 前后必须是行首/行尾或空白」的反解析口径自洽。`directCodexContentToPromptText` 的 `resourceId → 显示名` 反查改由调用方注入（`resourceLabelResolver(assets)`），函数自己不再读 manifest。
+
 素材选择面板支持缩略图、名称或资源 ID 搜索、类型筛选和多选；面板顶部有两个页签：
 
 - 「当前版本素材」：列出版本 `resourceBindings` 里绑定的、且仍登记在 manifest 的素材；
 - 「全部画布素材」：列出全部已登记素材。
 
-两个页签各自持有独立的搜索与类型筛选状态，互不影响，也不与资源画布筛选联动。当前版本取 `ResourceReferenceInput` 的 `activeVersionId`；未传或传 `null` 时回退到 manifest `versions[]` 中最新的那个版本。版本不存在或该版本没有绑定素材时页签显示空态，不合成资源卡；绑定指向已删除资源（悬空绑定）时按资源 `id` 过滤掉。
+两个页签各自持有独立的搜索与类型筛选状态，互不影响，也不与资源画布筛选联动。当前版本取宿主传给 `ResourceReferencePicker` 的 `activeVersionId`；未传或传 `null` 时回退到 manifest `versions[]` 中最新的那个版本。版本不存在或该版本没有绑定素材时页签显示空态，不合成资源卡；绑定指向已删除资源（悬空绑定）时按资源 `id` 过滤掉。
 
 确认后素材以 `@素材名` 芯片插入编辑器，Skill 以 `$skill-name` 芯片插入编辑器；用户可以在芯片前后继续编辑自然语言，也可以单独删除芯片。素材芯片内部保存稳定 `resourceId`，展示名称只用于界面，不参与引用解析。Skill 芯片保存稳定 Skill 名称，发送时由 Rust 根据当前 DirectProject 已启用 Skill 清单解析为 Codex 原生 `type: "skill"` 输入项。资源改名后，编辑区已有芯片与候选列表都会按 `resourceId` 刷新成 manifest 的最新显示名，并同步回父级草稿。
 
@@ -25,14 +39,24 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，
 - 只认**已登记到 manifest** 的素材，引用身份、来源标记 `resource-card` 与「引用」按钮逐字一致，所以同一素材两处进来是同一枚引用（去重键也一样）；一条都引用不了时（素材都未登记）用提示条说明原因。
 - 一次松手只派发一次批量事件（`RESOURCE_REFERENCE_INSERT_MANY_EVENT`），草稿只重建一次、插入顺序即拖动集合顺序。
 
+## 附件进入正文（2026-09-22）
+
 本地上传入口不区分图片和其它文件：用户从同一个文件选择器提交任意附件，前端不做 MIME 类型分流，所有上传文件统一编码为 `agc_attachment_reference`。图片不会因为扩展名或 MIME 类型获得另一种 canonical part；只有未来真正支持 Codex 多模态 `input_image` 投影时，才另行设计图片协议。
 
+本轮附件只有**正文芯片**这一份事实源：导入成功后附件立即以芯片插入正文，`status === 'failed'` 或导入异常一律不插入；控制器不再持有待发附件数组，`ComposerPendingAttachments` 与提交时的附件 parts 拼接都已删除。因此：
+
+- 附件可以出现在正文的任意位置（在光标处插入），移除就是删除那枚芯片；
+- 单次上限仍是 `MAX_CHAT_COMPOSER_ATTACHMENTS = 8`，但按草稿里已有的附件芯片数计算；
+- 导入进行中禁止发送（导入结果还没落成芯片时发出去，用户会以为带上了附件）；导入期间允许再次点击 `+`，并发导入各自插入自己的芯片；
+- 「正在上传文件 / N 个文件未能上传：xxx / 已上传 N 个文件，将在下次发送时作为本轮附件」三条文案保持不变。
+
 当前已完成：
 
-- 三个聊天入口共用 `ResourceReferenceInput`；
+- 四个入口（DirectProject 聊天、策划输入盒、画布生成面板、资源卡快速编辑）共用 `ResourceReferenceInput`，引用来源由宿主选择性注入；
 - 输入 `@` 触发候选，支持键盘选择和 Esc 关闭；
-- 输入 `$` 触发 Skill 候选，支持键盘选择和 Esc 关闭；Skill 候选只显示当前 DirectProject 已启用且已由 app-server 发现的 Skill；
-- `@` 按钮打开素材选择面板；
+- 输入 `$` 触发 Skill 候选，支持键盘选择和 Esc 关闭（只有注入 Skill provider 的 DirectProject 输入界面有 `$`）；Skill 候选只显示当前 DirectProject 已启用且已由 app-server 发现的 Skill；
+- `@` 按钮打开素材选择面板（面板由宿主渲染，自己拿数据）；
+- 附件导入成功即插成正文芯片，失败不插入，随本轮 canonical content 一起发送；
 - 支持搜索、类型筛选和多选；
 - 素材芯片可插入、编辑和删除；
 - 资源画布支持把资源卡拖到对话栏批量引用（2026-09-21，见上一节）；
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index b21488801..b995f5b55 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -658,6 +658,33 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 2026-09-05 修订：`/api/llm/responses` 与 `/api/llm/chat/completions` 仍在 Router provisioning 前用钱包总余额阻止零余额账号创建或续期；解析凭据后、上游调用前再执行累计额度同步，以扣除退款占用后的剩余可消费余额为准。余额为 `0` 时返回 `409 MUD_POINTS_INSUFFICIENT`；余额或额度同步失败时失败关闭。上游已成功时，后置同步失败只记录错误并留待下次调用前补结算，不把成功模型响应改写为失败。
 - Windows 私有文件准备：AGC 自有 AppData、凭据目录和 `.agent` 运行态继续使用 managed 范围；用户通过原生选择器明确选中的项目根或文件，若 owner/DACL 仅因权限不足无法读取，则由一次性 UAC helper 在严格复核普通文件/目录、非 reparse/symlink、路径类型和目标 TokenUser 后接管并收紧为当前用户私有 DACL。项目放在当前 profile 之外（例如其他磁盘）不再因为路径位置被拒绝；未经过原生选择器或 AGC 项目根入口的内部路径仍不获得任意提权资格。
 
+### `game_distribution_game`
+
+- Rust 结构体：`GameDistributionGame`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：游戏分发稳定身份与公开版本指针。保存 owner、标题/简介/分类资料、设备与输入声明、`publication_revision`、当前 `active_version_id`、可见性和游玩计数；标签与输入模式按版本化 JSON 保存，展示资料由 `api-server` 通过 `spacetime-client` 归一后返回。
+- 公开素材：游戏行末尾追加可空 `cover_object_key` 与 `screenshots_json`（截图 `{assetId, objectKey}` 数组）；创建游戏时 `api-server` 就复核封面/截图素材存在且属于当前作者（不存在 400、他人素材 403），创建版本时按同一口径再次复核并派生对象键。 发布写入受灰度配置键 `game-distribution:publish` 约束：未配置或 `enabled=false` 默认开放，显式收紧后写入口（创建游戏/版本、确认包、送审、审核通过激活）返回 503 `GAME_DISTRIBUTION_PUBLISH_DISABLED`，读取与安全下架保持可用；同一判据在 `GET /api/runtime/frontend-config` 以 `gameDistributionPublishEnabled` 下发给前端入口，匿名恒为 `false`。只有可见性为 `published` 且存在有效 `active_version_id` 的游戏，其封面/截图素材才在 `/api/assets/read-url` 上获得匿名读授权。
+- 复用规则：末尾可空列 `local_project_id` 保存发布方本地项目标识（AGC 的 `manifest.projectId`）。同一 `owner_user_id` 再次以相同 `local_project_id` 创建游戏时复用既有 `game_id` 并只新增版本，避免“更新”被实现成新建游戏；该字段只是复用提示，不构成所有权或路径凭证，也不能用于跨账号匹配。
+- 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published` 且存在有效 `active_version_id` 的投影。
+
+### `game_distribution_version`
+
+- Rust 结构体：`GameDistributionVersion`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：不可变发行版本与真实包确认事实。创建后冻结 `package_sha256`、字节数、文件数、根入口和版本号；后续只推进上传、校验、审核、公开、撤回状态，并记录私有对象键、文件清单、入口 URL、审核者和阶段时间。
+- 索引：`by_game_distribution_version_game_id`、`by_game_distribution_version_owner_user_id`。真实 ZIP 由 `api-server` 校验并写入私有 OSS 后，才通过 facade 确认 `uploaded`；表不保存 ZIP 正文。
+- 冻结资料：版本表末尾追加可空 `metadata_json`，保存创建版本时由 api-server 校验（标题/简介/分类/标签/设备/方向/必需封面/≤6 张截图）并从素材记录派生对象键后的资料快照；`approve_game_distribution_version_and_return` 通过审核时把该快照整体生效到游戏行，因此公开投影展示的始终是“已随版本审核通过”的资料，旧版本（无快照）保持原值。
+- 作者回读投影：版本回读（作者本人）与审核回读（管理员）在版本 payload 上追加 `frozenMetadata`（冻结快照原样 JSON，历史版本为 `null`）。只有公开投影会剥掉素材 ID，作者与管理员拿到 `coverAssetId` / `screenshots[].assetId`，因此作者续发时可以直接复用同一批封面与截图素材，不需要为了沿用封面重新上传一次；素材 ID 缺失（旧版本）时前端必须要求作者重新选择封面，不能用对象键反推素材身份。
+- 撤回与回读：`cancel_game_distribution_version_and_return` 只允许把未参与当前公开投影的版本推进到 `cancelled`，并要求 `expected_publication_revision` 与游戏公开修订号一致；`get_game_distribution_version_and_return` 供管理员按版本 ID 直读。客户端看到的 `recoveryAction` 由 `api-server` 按 `status` 派生，不落表。
+
+### `game_distribution_idempotency_receipt`
+
+- Rust 结构体：`GameDistributionIdempotencyReceipt`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：创建、上传、提交、审核、撤回和下架操作的幂等收据。`owner_user_id + action + idempotency_key` 组合唯一，保存请求摘要、结果 ID、有限结果 JSON、创建/过期时间和完成时间；同 key 不同摘要必须返回冲突，收据不保存凭据或包正文。
+- 索引：owner、game、version 和 `by_game_distribution_receipt_scope` 组合索引；默认保留窗口由服务端清理策略控制。
+- 重放语义：写操作命中既有收据时，procedure 回传 `replayed = true` 并复用收据里的结果 ID，不重复创建游戏、版本或审核结论；同 key 不同请求摘要必须返回冲突。
+
 ### `llm_router_account`
 
 - 当前 AGC Router 需求由 `llm_router_account` 表单独承载：API Key 核心字段、加密凭据、Router 账号元数据、生命周期与 provisioning 状态均在该表；不依赖 `external_api_key`。api-server 每次上游调用都读取权威 `llm_router_account` active/revoked 状态并即时解密当前密文，不做 TTL 凭据缓存，避免任意实例轮换或撤销后继续使用旧 Key。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 98b728ab8..3aa30b5be 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -141,9 +141,9 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去
 
 普通图片错误素材类型清理使用 `npm run spacetime:editor-image-asset-kind:clean -- --database <database> --server-url <url>`，只能由已授权 migration operator 执行。先进入维护模式并发布包含 `clean_editor_image_asset_kind_and_return` 的 SpacetimeDB module，并保持旧版本 API / controller / worker 停止；随后运行默认全量 dry-run，核对 `asset → project-resource → showcase → canvas` 各 scope 的扫描数、命中行数、字段数和 blocker 均符合预期，再追加 `--apply`。脚本对每批重新 dry-run、绑定包含画布迁移摘要、结构化 layer 与 generation-dialog 权威 JSON 的 SHA-256，最后自动从头复核零命中；任一画布数据异常都会只输出哈希化 ID、scope 与原因并停止，不能跳过。清理只处理精确业务旧值，不修改 `asset_object.asset_kind`、MIME 或媒体类型；project-resource scope 在清行前验证同工程 migration 并将其状态纳入批次 hash，layout version 0 的 legacy 画布可以没有 migration，但 structured 画布缺 migration 必须立即形成 blocker，资源行不得先被清空；清行后能保持原 status 不变量时立即刷新摘要，否则只允许留给后续精确 canvas 字段清理收口。canvas scope 在任何布局写入前再次按 active / backfilled / rolled_back 状态验证原 migration 凭证和双份 legacy / structured 不变量，将 `editor_canvas_generation_dialog.dialog_json` 与 layer rows 一并扫描并在同一事务 patch；只允许本批资源清零及精确字段删除造成的差异，写入后从全部结构化权威行重建 layout、再次复核新状态才受控重签摘要，同时保持业务 revision、migration status 与全部时间戳不变。新版本 API、SpacetimeDB storage 创建入口、legacy 画布元数据提取和项目资源落表边界都会将 trim 后精确等于 `image` 的 `assetKind` 归一为 `NULL`，防止旧页面、滞留请求或 legacy 保存重新制造废弃值。完成零残留复核，并分别确认 cleaned backfilled 可激活、active 可继续保存、rolled_back 可重复复检后恢复应用版本，最后退出维护。Stdb build artifact 和完整 release 包必须同时包含 `scripts/spacetime-clean-editor-image-asset-kind.mjs` 与 `scripts/spacetime-migration-common.mjs`。
 
-`Genarrative-Scheduled-Revision-Trigger` 是唯一的定时入口，每小时检查一次（`H * * * *`，分钟由 Jenkins 按 Job 名散列，不等同于整点）。它只用 `git ls-remote` 解析 `SOURCE_BRANCH`（默认 `master`）的远端 HEAD，不 checkout 工作区；解析出的完整 commit 与上一次触发过的 revision 相同则标记 `NOT_BUILT` 并结束，不触发任何下游。
+`Genarrative-Scheduled-Revision-Trigger` 是 dev 渠道的小时调度入口，每小时检查一次（`H * * * *`，分钟由 Jenkins 按 Job 名散列，不等同于整点）。`Genarrative-Scheduled-Release-Trigger` 是 release 渠道服务端与客户端的每日调度入口，固定在每天 04:00（`0 4 * * *`）检查同一个源码分支。两条调度器都只用 `git ls-remote` 解析 `SOURCE_BRANCH`（默认 `master`）的远端 HEAD，不 checkout 工作区；解析出的完整 commit 与对应 lane 上一次成功的 revision 相同则标记 `NOT_BUILT` 并结束，不触发任何下游。
 
-revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy`、`Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，各条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。这些下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Windows 客户端发布额外按路径过滤：调度管线比较「上一轮已触发的 revision」与本次 revision 之间的变更路径，只有出现 `apps/ai-game-creator-shell/`、`packages/`、`server-rs/crates/`、`plugins/agc-cocos-editor/`、`apps/desktop-shell/src-tauri/icons/`、`package.json` 或 `package-lock.json` 时才触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`（两个平台分区发布同一个发号 Job 下发的总版本号），纯文档或流水线自身的提交只触发 Full Build、不推高客户端版本号；判定取消或失败一律按「需要发布」处理，勾选 `FORCE_TRIGGER` 可强制两条都触发。两条下游各自判定：AGC Windows Build 采用「客户端相关路径白名单」，Full Build 采用「与线上站点 / 后端无关的路径黑名单」（`docs/`、`.codex/`、`jenkins/`、`apps/ai-game-creator-shell/`、`apps/mobile-shell/`、`apps/desktop-shell/`、`apps/preview-deployer-web/`、`tools/`、根级 `*.md`），改动只要落在黑名单之外就会照常部署，避免漏发线上站点或后端；两条同时被判为跳过时调度管线只推进 revision 状态、不触发任何发布。AGC 客户端版本号不再由渠道各自递增：唯一发号源是 OSS 对象 `agc/global-version.json`，发号收口到 `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()` + 写后回读校验；集群未装 `lockable-resources` 插件）。调度管线与手动发布管线都先调用该 Job 发号，再用归档产物 `agc-global-version.txt` 读取总号并作为 `AGC_RELEASE_VERSION` 透传给客户端构建；统一构建只发一次号供各渠道共用，单渠道热修只把号传给该渠道。显式传入的号低于本渠道当前清单版本时构建失败关闭；`AGC_RELEASE_DRY_RUN` 只预览下一位，不写回、不烧号。一次性播种用 `SEED_ONLY`：基线取「仓库版本 / 各渠道清单 / 旧迁移指针」的最大值，播种本身不烧号。仓库里的 5 个版本文件仍由构建改写，只作构建输入参考，不是事实源。客户端渠道清单的更新摘要同样自动生成：发布脚本读取上一份渠道清单的 `commit` 字段，把该提交到本次提交之间触及客户端相关路径的提交标题逐条写进 `notes`（旧协议清单写入 `releaseNotes`，并落盘归档文件 `release-notes.txt`）；`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准，缺少上一份 `commit` 时不写摘要。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 结束后都会触发 `Genarrative-Notify-Email`；只有正式 OSS 发布成功时，通知正文才附加本次生成的 `latest.json` 首装包 URL，演练、失败或跳过构建时留空，避免把未写入或不完整的对象地址发给收件人。
+dev 调度器发现 revision 变化时，把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy`、`Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，各条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。这些下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Windows 客户端发布额外按路径过滤：调度管线比较「上一轮已触发的 revision」与本次 revision 之间的变更路径，只有出现 `apps/ai-game-creator-shell/`、`packages/`、`server-rs/crates/`、`plugins/agc-cocos-editor/`、`apps/desktop-shell/src-tauri/icons/`、`package.json` 或 `package-lock.json` 时才触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`（两个平台分区发布同一个发号 Job 下发的总版本号），纯文档或流水线自身的提交只触发 Full Build、不推高客户端版本号；判定取消或失败一律按「需要发布」处理，勾选 `FORCE_TRIGGER` 可强制两条都触发。每日 release 调度器按服务端/客户端两个独立 scope 决定下游，固定使用 `DEPLOY_TARGET=release` 和 `CONFIRM_RELEASE_DEPLOY_AGENT=true`：服务端相关路径变化时触发 Full Build，`DATABASE_BACKUP_MODE` 默认 `async`，Stdb/API rollout 模式与审批人由调度参数显式透传；客户端相关路径变化时先经发号 Job 获取统一总号，再以同一个固定 commit 触发 AGC Windows 与 macOS 的 `release` 分区构建，macOS 仍带 `SKIP_IF_SUPERSEDED=true`。三类下游均 `wait: true` 并汇总结果，只有成功 lane 才推进 `.jenkins-last-release-full-revision` 或 `.jenkins-last-release-agc-revision`，失败 lane 下一轮单独补发，不重复已成功的服务端发布。dev 调度器的下游各自判定：AGC Windows Build 采用「客户端相关路径白名单」，Full Build 采用「与线上站点 / 后端无关的路径黑名单」（`docs/`、`.codex/`、`jenkins/`、`apps/ai-game-creator-shell/`、`apps/mobile-shell/`、`apps/desktop-shell/`、`apps/preview-deployer-web/`、`tools/`、根级 `*.md`），改动只要落在黑名单之外就会照常部署，避免漏发线上站点或后端；两条同时被判为跳过时调度管线只推进 revision 状态、不触发任何发布。AGC 客户端版本号不再由渠道各自递增：唯一发号源是 OSS 对象 `agc/global-version.json`，发号收口到 `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()` + 写后回读校验；集群未装 `lockable-resources` 插件）。dev / release 两条调度管线与手动发布管线都先调用该 Job 发号，再用归档产物 `agc-global-version.txt` 读取总号并作为 `AGC_RELEASE_VERSION` 透传给客户端构建；统一构建只发一次号供各渠道共用，单渠道热修只把号传给该渠道。显式传入的号低于本渠道当前清单版本时构建失败关闭；`AGC_RELEASE_DRY_RUN` 只预览下一位，不写回、不烧号。一次性播种用 `SEED_ONLY`：基线取「仓库版本 / 各渠道清单 / 旧迁移指针」的最大值，播种本身不烧号。仓库里的 5 个版本文件仍由构建改写，只作构建输入参考，不是事实源。客户端渠道清单的更新摘要同样自动生成：发布脚本读取上一份渠道清单的 `commit` 字段，把该提交到本次提交之间触及客户端相关路径的提交消息第一行（标题）逐条写进 `notes`，忽略标题后的说明行（旧协议清单写入 `releaseNotes`，并落盘归档文件 `release-notes.txt`）；`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准，缺少上一份 `commit` 时不写摘要。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；release 调度显式覆盖为 `release` 目标并透传备份、rollout、Pingora 和维护退出参数。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 结束后都会触发 `Genarrative-Notify-Email`；只有正式 OSS 发布成功时，通知正文才附加本次生成的 `latest.json` 首装包 URL，演练、失败或跳过构建时留空，避免把未写入或不完整的对象地址发给收件人。
 
 手工发布入口 `Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET` 与 AGC 更新渠道是两个独立维度。手工入口必须把 `release` 映射为 `AGC_UPDATE_CHANNEL=release`、把 `development` 映射为 `dev`，并把该参数同时透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`；只传 `AGC_RELEASE_VERSION` 时下游会落回各自默认 `dev`。统一号 `0.1.95` 的 release 包应分别位于 `agc/release-win/0.1.95/` 与 `agc/release-mac/0.1.95/`，渠道清单为对应目录下的 `latest.json`，不存在 `agc/release/` 这一层。补发本轮已烧号的版本时，直接以相同 `AGC_RELEASE_VERSION` 重跑两条 AGC Job，不重新发号。
 
@@ -332,19 +332,21 @@ workflow 首次成功运行后，**不**把 Project CI 的 job 配成 Gitea `mas
 
 master 日常交付必须禁止直接 push，只允许经 PR 在最近一次 Project CI 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。
 
-#### AGC Rust lane 1 的隔离编译缓存试验
+#### Rust 测试组的隔离编译缓存
 
-每次生成快照必须使用不含对象缓存的原始 CI 基础镜像；构建脚本在拉取源码和预热前拒绝已存在 `/opt/genarrative-ci/rust-cache` 的基础镜像，避免重复叠加不可释放的旧对象层。切换并完成真实 CI 验证后，按 `deploy/container/README.md` 的保留规则人工定向清理旧缓存镜像及归档，保护运行中 CI 使用的版本。
+每次生成快照必须使用不含对象缓存的原始 CI 基础镜像，避免叠加不可释放的旧层。宿主自动维护器 `scripts/maintain-gitea-rust-cache.py` 收集完整 master push CI 的六组 V4 增量产物，复用其真实来源镜像对象并合并去重，总容量 4 GiB，不重复执行 Cargo 预热编译。测试失败可收集，取消、缺组、未完成上传、旧 attempt 或混用来源镜像不可发布。候选校验、导出和装载后删除已收集 artifact，遗留项保留 7 天；切换后通过真实 master CI 才定向清理受管旧镜像/归档，保护当前、一个回滚版、基础镜像及容器引用。
 
-只在 `AI game creator shell Rust lane 1/2` 启用 sccache，lane 2 保持直接 rustc。继续设置 `CARGO_INCREMENTAL=0`，不共享 target、不恢复 Actions 可写缓存。可信快照通过已有固定 Image ID 分发：镜像只增加固定版本的 sccache、编译对象和来源元数据，不包含源码、target 或凭据；容器写时复制层承接本 job 的新增对象，job 删除后丢弃，PR 没有 Docker API 或快照发布权限。该权限边界由 runner 基础设施保证，不能仅用 workflow 的分支条件替代。
+AGC Rust 两条 lane、crates、agent-run smoke、Backend 和 Native shell 的桌面壳测试均启用 sccache。Native shell 的 release build smoke 显式清空两个 wrapper，保持发布构建原有 profile/features 与资源 staging；前端和 repository checks 不启用对象缓存。继续设置 `CARGO_INCREMENTAL=0`，不共享 target、不恢复 Actions 可写缓存。可信快照通过已有固定 Image ID 分发：镜像只增加固定版本的 sccache、编译对象和来源元数据，不包含源码、target 或凭据；容器写时复制层承接本 job 的新增对象，job 删除后丢弃，PR 没有 Docker API 或快照发布权限。该权限边界由 runner 基础设施保证，不能仅用 workflow 的分支条件替代。
 
-维护者在受信任 checkout 中运行 `bash scripts/build-gitea-rust-cache.sh <已验证基础镜像> <候选镜像tag>`。脚本从 origin 获取 master 的确定提交，在无宿主目录挂载、无凭据且有 CPU/内存上限的临时容器中编译 AGC bin 测试，仅导出 sccache 对象；最终镜像从原基础镜像重新组装，不提交预热容器。公共快照不接受 PR 上传，也不复用 Jenkins 发布缓存。工具链或系统依赖变化时重新生成快照，缓存命中仍由 sccache 的编译输入校验决定，不能省略 Cargo 构建。
+人工 bootstrap 在没有可消费快照时使用 `bash scripts/build-gitea-rust-cache.sh <已验证基础镜像> <候选镜像tag> [完整master-SHA]`；自动维护不调用它。bootstrap 固定 master 归档，在无宿主挂载、无凭据、有资源限额的容器中只编译预热，不执行测试/应用，Cargo features 和工作目录保持实际 CI 口径。日常更新由 master CI 导出新 key，命中继承对象只传使用时间；PR 不导出、不扫描。宿主验证来源、大小和哈希，不从上传产物执行程序，只从可信来源镜像复制固定 sccache。工具链或基础镜像输入变化时重建无对象缓存基础镜像，缓存工具链必须匹配。公共快照不接受 PR，不复用 Jenkins 发布缓存。
 
-lane 1 在编译前执行 `scripts/ci-rust-cache.sh prepare`：检查快照与 rustc 身份，隔离 sccache 配置和 daemon，限时探测真实 wrapper。旧镜像没有快照或探测失败时保留空 wrapper，输出 fallback 原因；缓存故障不得把真实编译/测试失败改成成功，也不允许重跑整个测试组掩盖失败。结束时 `report` 输出命中统计；分片日志单独记录 Cargo 编译耗时。对象缓存上限为 2 GiB，最终测试 bin 的链接仍须执行。
+各 Rust job 在编译前执行 `scripts/ci-rust-cache.sh prepare`：检查快照与 rustc 身份，隔离 sccache 配置和 daemon，限时探测真实 wrapper。旧镜像没有快照或探测失败时保留空 wrapper，输出 fallback 原因；缓存故障不得把真实编译/测试失败改成成功，也不允许重跑整个测试组掩盖失败。结束时 `report` 输出命中统计；分片日志单独记录 Cargo 编译耗时。对象缓存上限为 4 GiB，快照构建完成后输出实际体积；最终测试 bin 的链接仍须执行。全组开启时必须生成覆盖全部目标的新快照，不能把旧 AGC 单目标快照当作后端/桌面壳的预热验收。
 
 候选镜像沿用 `gitea-ci-job-image.sh verify/export/load-runner` 验证和装载。现役 CI 正在运行时只允许准备候选镜像，不停止 job、不重启 runner、不切换标签；待确认无运行中的 job 后再按上述镜像更新顺序切换。验收分别记录独立 target 的无缓存、冷缓存和热缓存构建耗时及命中率，并检查失效/故障回退、两容器写入互不影响。未完成真实 CI 验证前不能宣称提速或推广到其它 job。
 
-Rust 对象 key 包含编译工作目录。预热必须使用已核实的 Gitea checkout 路径 `/workspace/GenarrativeAI/Genarrative`，并像分片运行器一样从 `apps/ai-game-creator-shell/src-tauri` 启动 Cargo；快照保存 `workspace.txt`，job 根路径不符时直接编译，避免零命中的缓存开销。不要仅设置 `SCCACHE_BASEDIRS` 就假定 Rust 可以跨 cwd 命中，也不为缓存改写 `RUSTFLAGS` 或源码路径语义。固定 sccache `0.18.0` 的基础设施错误码 `2` 会由 wrapper 回退执行本次 rustc；其它退出码原样返回，升级 sccache/Rust 时须复核此约定。
+自动维护首次部署及故障恢复统一见 `deploy/container/README.md`。timer 约每 5 分钟检查，文件锁串行执行，使用专属 clone/状态/归档目录；只管理 Gitea CI 测试镜像，Native shell release smoke 继续清空双 wrapper。凭据只需普通账号 `write:repository`，读取 run/job/日志/产物并定向删除缓存 artifact，不需要管理员权限。切换依赖 FetchTask 暂停与在途屏障、任务持久账本和内层 Docker 空闲；Gitea 显示 cancelled、disabled 或客户端超时都不能证明执行已经结束。网关依据最终日志与执行收尾后的最终任务上报确认释放任务。首次接入/旧网关升级须等待 CI 自然结束的空闲窗口，不在运行中的 CI 上试切；脚本合并不等于服务已部署。
+
+Rust 对象 key 包含编译工作目录。预热必须使用已核实的 Gitea checkout 路径 `/workspace/GenarrativeAI/Genarrative`：后端、独立 crate、插件、桌面壳及提示词契约从仓库根目录启动 Cargo，AGC 分片从 `apps/ai-game-creator-shell/src-tauri` 启动，agent-run smoke 从 `apps/ai-game-creator-shell` 启动。切换 AGC 编译入口前清理该临时容器的 AGC target，防止 Cargo 的 fresh 判断跳过新 cwd 所需对象；CI 各 job 的 target 本来就独立。快照保存 `workspace.txt`，job 根路径不符时直接编译。不要仅设置 `SCCACHE_BASEDIRS` 就假定 Rust 可以跨 cwd 命中，也不为缓存改写 `RUSTFLAGS` 或源码路径语义。固定 sccache `0.18.0` 的基础设施错误码 `2` 会由 wrapper 回退执行本次 rustc；其它退出码原样返回，升级 sccache/Rust 时须复核此约定。
 
 sccache `0.18.0` 还会 hash 大部分 `CARGO_*` 环境变量。因此 wrapper 固定在每个容器自己的 `/opt/genarrative-ci/rust-cache/rustc-wrapper`，prepare 重写 launcher 后才启用；daemon 状态与 socket 仍各自随机隔离。预热同步 workflow 的 `CARGO_INCREMENTAL`、`CARGO_HTTP_MULTIPLEXING`、`CARGO_NET_RETRY` 和 `CARGO_TERM_COLOR`，由现有 CI 契约测试验证一致；新增 Cargo 环境配置时须同步评估 cache key，不能只看快照文件是否存在。
 
@@ -638,6 +640,52 @@ Nginx 负责站点和反向代理
 Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 ```
 
+### 游戏发行来源（发行域名、每游戏 origin 与缓存窗口）
+
+已公开游戏运行在**独立来源**上，与主站来源隔离；这是发行网关（`api-server`）之外唯一需要的边缘配置。
+
+- 配置工件：`deploy/nginx/genarrative-release-origin.conf`。上线前替换域名、通配证书路径与 upstream 端口，并把文件安装到 Nginx 站点目录。
+- 前置资源：`*.games.<域名>` 通配 DNS 指向同一入口，以及覆盖该通配名的 TLS 证书（certbot DNS-01 或等价流程）。
+- 路由约定：`https://<gameId>.games.<域名>/` 是该游戏的入口（子域根路径映射到该游戏的 `index.html`），其余路径按原样映射到 `/api/game-distribution/releases/<gameId>/…`；平台 API、后台、SPA 与上传接口在这个来源上一律 404，命中即证明边缘多代理了命名空间。
+- 会话隔离：发行来源从不使用 Cookie。带 `Cookie` 的请求在边缘直接 403，转发前也会 `proxy_set_header Cookie ""`；发行网关自身同样对带 Cookie 的请求返回 403。
+- 响应头与缓存：`X-Content-Type-Options`、CORP（`cross-origin`）、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate` 都由发行网关设置，边缘不覆盖。换版与下架只改变后端公开投影，因此**最迟 60 秒**内新请求不再拿到旧版本；已经下载到浏览器的脚本无法远程抹除，撤销能力以“停止继续分发”为准。
+- 审核动作：管理员审核通过时填写的 `entryUrl` 必须是该游戏的子域根地址 `https://<gameId>.games.<域名>/`（HTTPS、无凭据、无 query/fragment）；非生产环境仍按现有口径允许 http 回环地址用于本地联调。
+- 门禁与本地联调：
+
+```bash
+# 模板约束 + 发行网关响应头策略交叉检查；本机有 nginx/openssl 时还会渲染一份临时配置跑 nginx -t
+npm run check:release-origin-config
+```
+
+本地想在真实边缘语义下复验时，可以把模板渲染到 `~/data/tmp`（替换 upstream 为本地 api-server 端口、证书换成自签通配证书、监听端口换成高位端口），用 `nginx -c <渲染文件>` 起一个临时实例，再用 `curl -H 'Host: <gameId>.games.example.com'` 验证：根路径 200 `text/html`、`/assets/*` 200、带 Cookie 403、平台 API 路径 404、未知 gameId 404、http 301 到 https。
+
+#### 游戏分发可观测事件
+
+`api-server` 的游戏分发日志都带 `request_id`（与访问日志同一值）和 `operation`，可直接按游戏/版本关联；不记录 Token、signed URL、文件内容或本地路径。
+
+```bash
+# 上传与审核链路
+journalctl -u genarrative-api -o cat | grep -E 'operation="(package_confirmed|package_rejected|version_submitted|version_cancelled|review_decided|review_backlog_listed|game_unpublished|game_suspended)"'
+# 发布开关是否在拦流量
+journalctl -u genarrative-api -o cat | grep -E 'operation="publish_switch_(blocked|unavailable)"'
+# 发行网关 4xx 原因（需要 debug 级日志）
+journalctl -u genarrative-api -o cat | grep 'operation="release_rejected"'
+```
+
+关键字段：`package_confirmed.elapsed_ms` 与 `package_bytes`（校验耗时/容量）、`package_rejected.code|reason`（失败原因）、`review_backlog_listed.pending_versions`（审核积压）、`game_unpublished|game_suspended.publication_revision`（撤销传播时可与详情回读对账）。
+
+#### 发布开关（关闭投稿、保在线）
+
+发布事故或回滚窗口里用 `game-distribution:publish` 灰度开关控制写入，不需要改代码或重启：
+
+- 开关位置：后台「灰度发布配置」（`GET/PUT /admin/api/feature-gates`），`gateKey = game-distribution:publish`。
+- 语义：没有该 gate 行或 `enabled=false` 表示**默认开放**；`enabled=true` 时只有 `allowUserIds` / `allowUserTags` / `rolloutPercent` 命中的作者能发布，`rolloutPercent=0` 且无白名单即**全部关闭**（等价紧急关闭投稿）。
+- 关闭范围：创建游戏、创建版本、上传包、送审、撤回、作者下架，以及管理员**批准**（新版本激活）都返回 `503 GAME_DISTRIBUTION_PUBLISH_DISABLED`。
+- 始终可用：目录、详情、版本回读、发行网关（已公开游戏继续游玩）、`/my-games`、审核队列读取、**拒绝审核**与管理员**安全下架**。
+- 失败姿态：开关状态读取失败时按关闭处理，避免绕过运营刚下的收紧动作；本地排障时确认 SpacetimeDB 正常后再判断业务是否被误伤。
+
+上线前仍需确认的外部状态：通配 DNS 与证书已生效、upstream 端口与 `genarrative-api.service` 一致、若前面还有 CDN 需把 TTL 收敛到不超过上述 60 秒窗口，并跑一次真实域名下的“审核通过 → 游玩 → 换版 → 下架”链路。
+
 ### 生产健康巡检
 
 `Genarrative-Server-Provision` 会安装并启用 `genarrative-health-patrol.timer`，默认每 5 分钟运行一次 `genarrative-health-patrol.service`。巡检脚本随 API release 归档到 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs`，只读检查：
@@ -730,7 +778,7 @@ cat /var/lib/genarrative/health-patrol/status.json
 
 如需接外部告警，可在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_WEBHOOK_URL`；脚本只会在 `WARNING` 或 `CRITICAL` 时向该 webhook 发送 JSON。未配置 webhook 时，告警来源是 systemd 失败状态、journal 和状态文件。
 
-Jenkins Copy Artifact 必须保持 `Production` 权限模式；产物生产者要在 Jenkinsfile 中用 `copyArtifactPermission` 精确授权消费者，不能依赖 Migration 模式或全局 `Job/Read`。固定映射为 `Genarrative-Stdb-Module-Build` → `Genarrative-Stdb-Module-Publish`、`Genarrative-Api-Build` → `Genarrative-Api-Deploy`、`Genarrative-Web-Build` → `Genarrative-Web-Deploy`、`Genarrative-Database-Export` → `Genarrative-Database-Import`、`Genarrative-Agc-Global-Version-Issue` → `Genarrative-Scheduled-Revision-Trigger`（发号 Job 必须授权调度器读 `agc-global-version.txt`；缺这条会让整轮调度在发号之后失败——号已烧、渠道构建没被触发，2026-09-20 #103 即为此）。如果 `copyArtifacts` 报 `Unable to find project for artifact copy`，但来源 Job、指定构建号和归档都实际存在，先检查来源 Job 的 `CopyArtifactPermissionProperty`；修复 Jenkinsfile 后必须先运行一次产物生产者，让 Declarative Pipeline 把 Job property 写回 Jenkins，再重跑 Deploy / Publish / Import。`npm run check:production-ops` 会防止四条白名单再次丢失。
+Jenkins Copy Artifact 必须保持 `Production` 权限模式；产物生产者要在 Jenkinsfile 中用 `copyArtifactPermission` 精确授权消费者，不能依赖 Migration 模式或全局 `Job/Read`。固定映射为 `Genarrative-Stdb-Module-Build` → `Genarrative-Stdb-Module-Publish`、`Genarrative-Api-Build` → `Genarrative-Api-Deploy`、`Genarrative-Web-Build` → `Genarrative-Web-Deploy`、`Genarrative-Database-Export` → `Genarrative-Database-Import`、`Genarrative-Agc-Global-Version-Issue` → `Genarrative-Scheduled-Revision-Trigger` / `Genarrative-Scheduled-Release-Trigger`（发号 Job 必须授权两条调度器读取 `agc-global-version.txt`；缺这条会让整轮调度在发号之后失败——号已烧、渠道构建没被触发，2026-09-20 #103 即为此）。如果 `copyArtifacts` 报 `Unable to find project for artifact copy`，但来源 Job、指定构建号和归档都实际存在，先检查来源 Job 的 `CopyArtifactPermissionProperty`；修复 Jenkinsfile 后必须先运行一次产物生产者，让 Declarative Pipeline 把 Job property 写回 Jenkins，再重跑 Deploy / Publish / Import。`npm run check:production-ops` 会防止这些 Copy Artifact 授权再次丢失。
 
 `Genarrative-Web-Build` 的主站构建失败若出现 Rollup 报错 `"xxx" is not exported by "src/services/publicWorkCode.ts"`，优先按前端公开作品号工具缺失处理，而不是排查 Jenkins 节点环境。修复时要让 `publicWorkCode.ts` 的 `build<Play>PublicWorkCode` 与 `isSame<Play>PublicWorkCode` 成对导出，并补 `src/services/publicWorkCode.test.ts` 覆盖对应玩法前缀；随后用 `npm run build:production-release -- --component web --name <临时名>` 复现 Jenkins web 构建路径。
 
@@ -760,7 +808,7 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.
 
 ### AGC macOS 手动构建节点
 
-Mac 单架构（arm64）构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发、自身不设 cron（定时只来自调度 Job）；它已接入每小时版本调度：`Genarrative-Scheduled-Revision-Trigger` 先调发号 Job 拿同一个总号，再把 `SOURCE_BRANCH`、固定 `COMMIT_HASH`、`AGC_UPDATE_CHANNEL=dev`、`AGC_RELEASE_VERSION=<总号>` 与 `SKIP_IF_SUPERSEDED=true` 透传给本 Job，**因此正常发布不需要（也不应该）手工点构建**；手工触发只是排障手段。它不改 Windows 发布职责。它使它只在专用 Agent 目录下构建：默认按约定匹配 `$HOME/Library/Jenkins/agents/<node>/workspace/`（不写死节点名，节点改名后仍成立），也可用 `AGC_AGENT_ROOT` 显式覆盖；禁止指向开发 checkout 或共享其可写 target/node_modules。
+Mac 单架构（arm64）构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发、自身不设 cron（定时只来自调度 Job）；它同时接入每小时 dev 与每日 04:00 release 两条版本调度：`Genarrative-Scheduled-Revision-Trigger` / `Genarrative-Scheduled-Release-Trigger` 先调发号 Job 拿同一个总号，再把 `SOURCE_BRANCH`、固定 `COMMIT_HASH`、对应 `AGC_UPDATE_CHANNEL=dev|release`、`AGC_RELEASE_VERSION=<总号>` 与 `SKIP_IF_SUPERSEDED=true` 透传给本 Job，**因此正常发布不需要（也不应该）手工点构建**；手工触发只是排障手段。它不改 Windows 发布职责。它使它只在专用 Agent 目录下构建：默认按约定匹配 `$HOME/Library/Jenkins/agents/<node>/workspace/`（不写死节点名，节点改名后仍成立），也可用 `AGC_AGENT_ROOT` 显式覆盖；禁止指向开发 checkout 或共享其可写 target/node_modules。
 
 Job 名为 `Genarrative-Agc-MacOS-Build`，SCM 直接读取仓库内上述 Jenkinsfile，参数为 `SOURCE_BRANCH`、`COMMIT_HASH`、`AGC_UPDATE_CHANNEL`、`AGC_RELEASE_VERSION`、`AGC_RELEASE_DRY_RUN`、`AGC_UPDATE_RELEASE_NOTES`、`OSSUTIL_BIN`、`CARGO_BUILD_JOBS`、`NOTIFICATION_EMAILS`。渠道参数是基础名（不含系统，默认 `dev`），脚本不接受 `dev-mac` 这类系统后缀，写入分区固定推导为 `<channel>-mac`：这与 Windows Job 的 `<channel>-win` 对称，也延续已发布客户端的端点。
 
diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
index 267aaab0f..3272fd5ca 100644
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -50,3 +50,129 @@
 
 - 供应商密钥、Token、Cookie 和本地私密路径不得进入前端或文档示例。
 - 生成或导入资产必须经过后端鉴权、对象确认和换签读取；上传失败或换签失败时显示可操作错误，不回退为公开裸路径。
+
+## AGC 游戏分发与在线游玩合同
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 0.2 |
+| Status | proposed（待评审，未上线） |
+| Date | 2026-09-18 |
+| 适用边界 | 本节是新增业务提案；评审与实现验收前，不改变上文现役入口和移动端合同 |
+
+### 交付目标与范围
+
+交付“AGC 一键提交游戏 / 网页上传游戏 ZIP → 后端收取真实发行包 → 校验与人工审核 → 主站发现、详情、游客在线游玩 → 更新与下架”的完整闭环。验收必须使用真实上传、真实存储、真实审核状态和隔离发行域名；静态演示卡片、metadata-only 请求或前端本地发布状态不能作为完成证据。
+
+首版支持可以离线运行的静态 Web 游戏：HTML、JavaScript、CSS、JSON 与图片、字体、音视频。AGC 首先支持现有 npm/Vite Web 工程；网页入口允许上传符合相同包合同的 ZIP，不以游戏引擎名称限制普通静态产物。Godot/Cocos 工程源码、原生可执行文件、Wasm、服务端进程、外部 API、多人联机、云存档和跨版本存档迁移不在首版内。暂不做评分、评论、关注、榜单、推荐算法、交易和创作者收入。
+
+### 入口与产品体验
+
+- 提议网页根路径 `/` 进入 `/games`；桌面一级导航为“游戏 / 创作 / 项目 / 我的”，移动端为“游戏 / 我的”。图片创作及项目编辑仍遵守原有桌面端边界，移动端不再以仅支持作品展示的欢迎遮罩阻断游戏浏览和游玩。该变更仅在本节通过评审并完成验收后生效。
+- 游戏目录 `/games`、详情 `/games/detail?id=<gameId>`、游玩 `/games/play?id=<gameId>`；作者管理 `/games/mine` 只列当前账号的游戏和发行状态。平台壳及既有账号页提供入口，不建立第二套账号或作品系统。
+- 目录使用重点推荐位和紧凑卡片网格，首版推荐位只消费后台明确设置且已公开的游戏；其余列表按发布时间排列。支持关键词、分类与设备筛选，筛选写入 URL，返回列表恢复筛选和滚动位置；没有内容时展示真实空态。
+- 详情的主动作是“立即玩”，展示封面、标题、作者、短简介、设备标识、截图和简短操作方式；不虚构评分、玩家数、排名和收藏状态。游客浏览详情及启动游戏均无需登录；上传、更新、撤回和作者管理需要当前平台登录态。
+- 游玩页先展示封面与开始按钮，用户点击后加载游戏，避免列表自动加载多个 iframe 或自动播音；提供加载、超时、重试、返回详情和全屏。iframe 的 `load` 事件只表示文档已加载，不宣称已经通过运行验证；首版不把 iframe 消息当平台业务状态。
+- 移动端优先采用全宽内容、底部主要动作、至少 44px 点击区域，覆盖安全区、横竖屏和键盘焦点。游戏声明仅支持桌面时，手机详情保留可浏览内容并禁用开始，明确显示“请在电脑上游玩”；横屏游戏提供旋转提示，但不能把系统方向锁定成功作为启动前提。
+- 视觉延续当前暖色主题 token、米白/浅暖背景、橙色主动作与现有字体；通过封面占比、留白、圆角和清晰状态层级现代化呈现，不另建配色系统。通用卡片动作、弹窗、上传、状态反馈、空态与媒体预览优先复用共享组件。发布打开独立弹窗/抽屉，不在当前页面末尾追加表单；技术信息仅在失败诊断或确需用户决策时展示。
+
+### 参考产品验证
+
+本次交互取已能核验的公开模式：TapTap 的详情主动作和阶段化审核发布（[详情示例](https://www.taptap.cn/app/29648)、[开发者创建游戏](https://developer.taptap.cn/docs/store/release/publish/create-game/)）；Astrocade 的精选/趋势分区、卡片播放量和作者入口（[首页](https://www.astrocade.com/)、[作者页](https://www.astrocade.com/creators)）；4399 的“无需下载，点开即玩”、适配设备与包体提示（[在线玩](https://h.4399.com/)、[上传中心](https://www.4399.com/gameupload.htm)）；7k7k 的分类、玩法说明、加载提示和玩家上传声明（[首页](https://www.7k7k.com/)、[上传页](https://www.7k7k.com/html/upload.htm)）。星匣仅确认其公开定位为 AI 一键生成与即点即玩，页面正文为动态应用，未把无法核验的栏目当作合同依据；限定调研内未找到可确认官方域名的“造梦工坊”，不据此推断产品行为。
+
+### 真实发行包与资料合同
+
+1. AGC 发布取当前 npm 工程已成功构建的 `dist/` 内容，重新检查入口和实际字节；ZIP 内部必须把 `dist/index.html` 归一化为根 `index.html`，其余路径相对发行根保持不变。不得上传整个项目、源码快照或仅发送本地路径。网页 ZIP 同样要求根 `index.html`，不猜测并自动剥离多层目录。
+2. 所有运行依赖都必须在发行包内。资源 URL 使用与发行版本目录兼容的相对地址；前导 `/assets`、本地文件 URL、外部脚本/样式/媒体/字体地址均不属于可接受发行合同。客户端给出可操作错误，服务器仍独立校验；静态校验不能代替运行时 CSP 阻断。
+3. 建议首版限额：压缩包 100 MiB、展开总量 250 MiB、单文件 64 MiB、最多 10,000 个文件、展开/压缩比不超过 100。服务端拒绝加密 ZIP、重复或大小写冲突路径、绝对路径、`..`、符号链接/重解析点、设备文件和嵌套压缩包；拒绝 `.agent`、版本控制目录、`node_modules`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。
+4. 提交声明 ZIP 的 SHA-256 与字节数，服务端对收到的真实 ZIP 重新计算，再对展开文件建立相对路径、字节数和 SHA-256 清单。摘要不一致、缺文件或入口损坏时停止；只有 metadata 而没有已确认完整对象的提交必须失败。
+5. 游戏资料随发行版本冻结：标题 2–40 字、短简介不超过 120 字、详细介绍不超过 2,000 字、一个分类、最多 5 个标签（每个不超过 20 字）、必需封面、最多 6 张截图、操作方式不超过 240 字。分类首版为休闲、益智、动作、冒险、模拟、策略、其他；封面/截图复用平台图片上传与归属校验，不接受任意外链作为审核图片。发布入口按灰度下发：后端灰度配置键固定为 `game-distribution:publish`（后台「灰度发布配置」可改，支持 `enabled` / `rolloutPercent` / `allowUserIds` / `allowUserTags`）。未配置该键、或 `enabled=false` 时对已登录作者默认开放；显式 `enabled=true` 后只有白名单或灰度命中的作者拿到开放状态，匿名恒为不开放。发布入口的开放状态随 `/api/runtime/frontend-config` 的 `gameDistributionPublishEnabled` 下发，网页广场/我的游戏入口与 AGC 聊天头「发布到游戏广场」按钮据此显示或隐藏；写入口仍独立校验，收紧期间提交返回 503 与可读文案，读接口、目录、详情、发行网关与安全下架不受影响。作者续发时按版本冻结快照回填封面与截图并复用同一批素材；公开投影只暴露对象键，素材 ID 只在作者与管理员回读时返回，快照里缺素材 ID 的旧版本必须要求作者重新选择封面。
+6. `supportedDevices` 至少包含 `desktop` 或 `mobile`；`inputModes` 来自 `keyboard`、`mouse`、`touch`；声明移动端必须包含 `touch`。`orientation` 为 `landscape`、`portrait` 或 `responsive`。这些是待人工复核的作者声明，目录只显示已经随版本审核通过的值。
+7. 原始 ZIP、未审核展开目录、审核资料均为私有对象；公开版本不暴露源码镜像键、本地路径、访问凭据或私有账号元数据。运行文件只能由发行网关按游戏、版本和文件白名单读取，不能绕过网关访问公开 OSS bucket。
+8. 现役发行网关由 `api-server` 提供：`GET /api/game-distribution/releases/{gameId}/{assetPath}` 只服务当前已公开版本包内的文件，私有 ZIP 与未公开版本不因知道 ID 而可读。响应按扩展名白名单设定内容类型，未知扩展名返回 404；全部响应带 `X-Content-Type-Options: nosniff`、`Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`（发行文档运行在 `allow-scripts` 的 opaque origin 沙箱里，`same-origin` 会让游戏自己的脚本被浏览器拦下），HTML 追加最小权限 CSP。带平台 `Cookie` 的请求一律 `403`，避免发行文件被主站同源读取；发行网关必须部署在独立来源。发行包按对象键在进程内做有界缓存，单个超预算包不进入缓存。
+9. 审核通过时必须提交绝对 HTTPS `entryUrl`，且不接受凭据、query 和 fragment；服务端不根据请求 Host 或本地路径拼默认发行地址，避免把内网地址或主站来源写进公开投影。 非生产环境额外允许 http 回环地址（`127.0.0.1` / `localhost` / `[::1]`），口径与前端 `normalizeGameEntryUrl` 一致，便于本地在没有 TLS 的情况下验证内嵌游玩；生产环境只接受 HTTPS。
+
+### 身份、状态、审核与更新
+
+- `gameId` 是服务端分配的稳定游戏身份；`ownerUserId` 只从当前认证主体派生。AGC 的本地 `projectId` 只能作为作者名下的关联提示，不能证明云端游戏所有权。网页上传和 AGC 发布使用相同游戏、版本与上传记录，不建立两套发行系统。
+- 同一作者用相同 `localProjectId` 再次发布时复用既有 `gameId` 并只新增版本；游戏身份、版本号和服务端校验都不依赖客户端传来的路径或 ID 可信度。缺少 `localProjectId` 的旧客户端仍可发布，但会被视为新建游戏。
+- 每次发行分配唯一 `versionId` 与游戏内递增 `versionNumber`。版本的游戏归属、包摘要、已确认字节和送审资料冻结后不可变；改包或改送审资料必须创建新版本。版本状态可以流转，内容不能原地覆盖。
+- 游戏单独保存 `publicationRevision`、`activeVersionId` 和可见性 `unpublished | published | suspended`；正式可见性由服务端持久化事实决定。未通过审核时 `activeVersionId` 为空；`suspended` 是管理员安全下架，作者不能自行解除。
+- 版本状态为 `awaiting_upload → uploaded → validating → pending_review → published`。上传确定失败进入 `upload_failed`，验证失败进入 `validation_failed`，人工拒绝进入 `rejected`；尚未公开版本可以撤回为 `cancelled`，已公开版本可撤销为 `revoked`。已成功上传的相同字节可重新校验；内容改变或审核拒绝后的修改必须新建版本。
+- 首版建议人工审核。审核员检查游戏资料、真实桌面运行、声明移动适配、内容与外部请求被阻断的行为；自动包校验通过只进入 `pending_review`，不自动公开。审核记录保存审核者、目标版本、结论、理由和时间。后台只授权现有管理员身份，不让普通作者调用审核动作。
+- 更新送审时旧 `activeVersionId` 继续服务目录、详情与游玩。审核通过并完成对象可读验证后，一次事务切换当前公开版本和公开资料；新版本上传、校验、审核或对象安装失败均不改变旧版本。
+- 发布页先自动填入可用标题和封面，首次需要确认必需资料，此后复用上次资料；用户一次“提交发布”动作串联校验、上传和送审，并显示真实阶段。等待审核不能显示“已发布”；成功后提供查看详情和复制公开链接。
+
+### 幂等、并发与恢复
+
+- 所有创建、提交、审核、撤销和下架动作携带 `Idempotency-Key`。服务端以认证主体、动作和 key 保存请求摘要与结果；同 key 同请求返回原结果，同 key 不同请求返回 `409 IDEMPOTENCY_CONFLICT`。至少保留 30 天；客户端超出恢复窗口先回读记录，不能把未知结果自动当作失败重发。
+- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。首版整包重传，不宣称支持分片断点续传。
+- 重复提交同一次 AGC 操作不得创建第二个游戏或版本；原生端持久保存操作 ID、目标游戏/版本和 key，网页保存恢复标识并以服务端回读为准。相同 ZIP 用于不同资料修订时允许新版本，不能仅按包摘要吞掉新的发布意图。
+- 公开版本切换、作者下架和管理员审核必须带 `expectedPublicationRevision`，在持久化事务中比较并推进。并发变化返回 `409 PUBLICATION_CONFLICT`；旧送审版本不能在用户已发布更新或下架之后静默覆盖状态。审核员重新查看现状后才能提交新的明确动作。
+- 网络中断或响应丢失后先查询原操作/版本；服务端恢复 `validating` 的在途任务并按版本身份幂等续作，不另建版本。登录失效保留私有草稿和恢复标识，重新登录同账号后继续；换账号不能读取或接管原账号操作。
+
+### HTTP 与持久化边界（拟定）
+
+现役内部命名空间使用 `/api/game-distribution`；除标注为完整后台路径的行外，下表路径都带该前缀。标注「已实现」的路由已在 `api-server` 挂载并有定向测试；本表当前没有待落地路由。公开目录只消费后端投影；所有变更经过现有鉴权、限流和埋点中间件。账号内部 API 不扩展 `/api/external/v1`，后续若对外开放再同步 External OpenAPI。
+
+| 方法与路径 | 身份 | 行为 |
+| --- | --- | --- |
+| `GET /games` | 游客 | **已实现**：关键词与分类筛选，最多 48 项；仅公开可玩版本 |
+| `GET /games/{gameId}` | 游客 | **已实现**：当前公开资料与 `currentVersion.entryUrl`；不可见时 404 |
+| `GET /game-distribution/releases/{gameId}/{assetPath}` | 游客 | **已实现**：发行网关只服务当前已公开版本包内文件，按扩展名白名单设内容类型，未知扩展名 404，带 Cookie 的请求 403；游玩页的入口来自详情投影的 `currentVersion.entryUrl` |
+| `GET /my/games` | 登录作者 | **已实现**：当前账号游戏、最近版本状态与驳回理由；owner 只从认证主体派生 |
+| `POST /games` | 登录作者 | **已实现**：幂等创建游戏身份，尚不公开；带 `localProjectId` 时同一作者复用既有 `gameId` |
+| `POST /games/{gameId}/versions` | owner | **已实现**：创建不可变待上传版本，冻结包摘要/字节数/文件数与资料 |
+| `PUT /versions/{versionId}/package` | owner | **已实现**：接收真实 ZIP、重算摘要与文件清单并写入私有对象；不执行游戏代码 |
+| `GET /versions/{versionId}` | owner/管理员 | **已实现**：回读状态、错误代码、审核结论与服务端 `recoveryAction`；管理员走 `/admin/api/game-distribution/versions/{versionId}`；未知版本与别人的版本都按不可见返回 404 |
+| `POST /versions/{versionId}/submit` | owner | **已实现**：只有已确认完整包可提交，返回 202 并进入 `pending_review` |
+| `POST /versions/{versionId}/cancel` | owner | **已实现**：带 `expectedPublicationRevision` CAS 与 `Idempotency-Key`，只能撤回未参与公开投影的版本；同 key 同请求重放返回 `replayed: true`，摘要不同返回 409 |
+| `POST /games/{gameId}/unpublish` | owner | **已实现**：CAS 关闭公开游戏及其版本入口，不删除审核记录 |
+| `GET /admin/api/game-distribution/reviews` | 管理员 | **已实现**：分页获取待审版本；此行是完整后台路径 |
+| `POST /admin/api/game-distribution/versions/{versionId}/review` | 管理员 | **已实现**：批准需 HTTPS 发行入口并执行公开版本 CAS；拒绝需理由；此行是完整后台路径 |
+| `POST /admin/api/game-distribution/games/{gameId}/suspend` | 管理员 | **已实现**：安全下架整个游戏并撤销发行访问，要求 `expectedPublicationRevision` CAS 与幂等键；后台游戏审核页提供带原因输入与二次确认的入口；此行是完整后台路径 |
+
+除显式 `/admin/api/...` 外，表内路径均相对 `/api/game-distribution`。错误采用现有平台 envelope，覆盖 400 格式错误、401 未登录、403 owner/审核权限错误、404 不可见、409 幂等/状态/并发冲突、413 大小上限、422 包或资料校验失败、429 限流和明确的可重试 5xx；服务端响应不包含存储凭据和本地绝对路径。
+
+领域规则进入 `module-*`，游戏/版本/审核/操作账本和事务进入 `spacetime-module`，访问统一通过 `spacetime-client`，HTTP 与上传编排进入 `api-server`，对象存储副作用复用 `platform-*`，跨端 DTO 同步 Rust `shared-contracts` 与 `packages/shared`。新业务不复用退役玩法表或私有源码快照作为公开事实；实际表字段、索引、受信服务身份及迁移清单在持久化里程碑评审时冻结。已有表若确需加字段，只能末尾追加并给明确默认值；删除/改名/重排/改类型必须另行确认迁移计划。
+
+### 发行域名、沙箱与网络能力
+
+- 发行域名必须与平台使用不同的可注册站点（不同 eTLD+1），不能仅使用 `*.genarrative.world` 的兄弟子域；域名需在部署前确定。每个游戏有独立 HTTPS origin，例如 `https://g-<gameId>.<发行站点>`，不同游戏不能共用 origin；版本固定在 `/releases/<versionId>/index.html`。
+- 主站仅接受服务端配置允许的 HTTPS 发行 host 与发行版本路径，拒绝任意 URL、重定向目标、用户输入 URL、`javascript:` 和 `srcdoc`。发行站点不设置平台 Cookie、不接收平台 Bearer、不挂载主站 API；请求和日志也不得携带平台认证数据。
+- iframe 首版仅使用 `sandbox="allow-scripts"`，全屏通过明确的 iframe 能力授权与用户手势开放。禁止 `allow-same-origin`、顶层导航、弹窗、表单提交、下载、模态对话框、相机、麦克风、剪贴板和地理位置；不提供持久 localStorage/IndexedDB 存档保证，不启用 Service Worker。
+- 网关对所有发行 HTML 强制 CSP：默认拒绝；脚本只允许本游戏 origin 和必要内联脚本，不开放 `unsafe-eval`；样式允许本游戏 origin 与内联样式；图片/字体/音频只允许本游戏静态源及必要 `data:`/`blob:`；`connect-src` 仅为当前游戏静态 origin，`worker-src`、`frame-src`、`object-src`、`form-action` 为 `none`，`base-uri 'none'`，`frame-ancestors` 仅主站明确 origin。不能由包内 meta 放宽响应头策略。
+- 首版允许加载同游戏发行包内 JSON/二进制素材，禁止外部 API、远程分析、广告、第三方 SDK 网络依赖及任意外站 fetch/WebSocket。静态网关不代理任意外部地址。为兼容 opaque sandbox 下的 ES modules，发行静态资源提供不带 credentials 的 CORS；此能力只对获准发行文件生效，不能扩到主站或私有存储。
+- 发行响应固定正确 MIME 与 `X-Content-Type-Options: nosniff`，不把未知扩展名返回为 HTML；ZIP 校验和人工审核不能代替这些运行时隔离措施。真实浏览器验收必须确认 npm/Vite 模块、Phaser 素材加载、音频和触屏在该策略下正常，而外站请求与越权访问被阻断。
+
+### 下架、缓存与运维
+
+- 作者下架或管理员封禁成功后，公开列表、详情和启动 API 立即停止返回游戏；发行网关同步按游戏和版本授权拒绝新请求，原始对象不可绕过网关访问。管理员封禁禁止作者自行重发绕过；解除需管理员明确动作并重新审核。
+- 建议 HTML、公开状态与启动 API 使用 `no-store`；发行静态资源的浏览器与 CDN 有效期均不超过 60 秒，禁止 `stale-while-revalidate`、`stale-if-error` 和发行 Service Worker。下架主动 purge 相关 CDN 键，60 秒作为最大缓存撤销窗口，不把 purge 成功当唯一保障。旧版本被更新替代后，新启动只用当前版；旧游戏已经载入的脚本/资源不承诺远程抹除，用户退出或刷新后按当前授权重新判断。
+- 发布所需部署依赖包括独立站点域名及通配 TLS、每游戏 host 路由、私有存储、网关 CSP/CORS/MIME、CDN TTL/purge、管理员审核运营入口和可恢复校验执行器；缺少任一项不能宣布公开上线。
+- 观察上传失败、校验耗时、审核积压、发行 4xx/5xx、撤销传播时间与容量，日志按游戏/版本/操作 ID 关联，不记录 Token、完整用户文件内容或 signed URL。原始失败/撤回包建议保留 7 天后清理，公开版本和审核记录的保留周期在上线前确定；清理必须先检查引用，不能删除仍在服务的版本。
+- 回滚部署时关闭新提交和新版本激活，保留当前可玩版本与状态读取；数据库迁移不以删表回滚。安全事件通过服务端关闭游戏发行权限，不依赖前端隐藏按钮。现役实现：`game-distribution:publish` 灰度开关（后台「灰度发布配置」）控制作者写入与新版本激活——没有 gate 行或 `enabled=false` 时默认开放；`enabled=true` 时只有白名单/灰度命中的用户能发布（`rolloutPercent=0` 且无白名单即全部关闭）。关闭期间目录、详情、版本回读、发行网关、审核队列读取、拒绝审核与安全下架都不受影响；开关读取失败按关闭处理。
+
+### 验收标准与证据
+
+| 条款 | 必须获得的证据 |
+| --- | --- |
+| 真实包闭环 | 网页 ZIP 与 AGC dist 分别提交同一管道，服务端实际包 SHA-256/文件清单和发行回读一致；仅 metadata 请求被拒绝 |
+| 包与数据边界 | 缺入口、摘要不符、穿越、符号链接、压缩炸弹、超限、凭据路径及未授权对象均被拒绝且未公开 |
+| 权限与游客 | 匿名浏览/游玩成功，匿名写入 401，其他作者写入/读取私有版本被拒，伪造 owner 无效 |
+| 幂等与恢复 | 双击、响应丢失、上传中断、同 key 不同内容、重启恢复、换账号迟到响应分别验证，不生成重复发行版本 |
+| 审核与并发 | 待审不公开；拒绝有理由；旧版在更新失败/待审期间在线；审核与下架并发 CAS 拒绝过期写入 |
+| 真正可玩 | 桌面及手机真实浏览器覆盖模块加载、素材、音频、触屏、横竖屏、开始/重试/退出和可用全屏；不以 iframe load 代替 |
+| 隔离与撤销 | 真实不同站点和每游戏 origin 下，主站 Cookie/storage/DOM 不可访问，外部网络阻断，旧 URL 在缓存窗口后不能取得新资源 |
+| 页面与视觉 | 当前 warm token 下的目录、详情、发布、加载/空/失败/待审态，桌面和移动视口无操作遮挡，键盘可达 |
+| 工程门禁 | 定向前后端测试、两端类型检查、真实 SpacetimeDB/API smoke、schema/绑定检查、编码、文档索引及 diff 检查 |
+
+所有运行时证据须注明实际环境和结论；缺少发行域名、登录、存储、审核或真实游戏时写明未验证，不使用演示 fixture 填充为业务成功。
+
+### 待评审决策
+
+1. 是否采纳人工审核及资料随发行版本审核、更新期间旧版保持公开的首版策略；审核负责人、处理时限与申诉/解除封禁口径需确定。
+2. 是否采用 `/games` 为网页根入口，以及“游戏 / 创作 / 项目 / 我的”和移动“游戏 / 我的”的导航提案。
+3. 是否接受首版离线静态包、无 Wasm/外网/持久存档的范围，以及建议包额度、7 天失败包保留和 60 秒缓存撤销窗口；公开/撤销版本及审核记录保留周期待定。
+4. 不同可注册站点发行域名、DNS/TLS/CDN、存储区域及运营责任尚待选定。不同站点和每游戏 origin 是上线门禁，不能退化成主站同源目录。
+5. 本节已提供页面行为、发行状态、真实上传、幂等/CAS 和 API 草案，足以评审完整业务；尚不足以直接实现持久化和部署，必须在对应里程碑评审前冻结表/索引/服务身份、额度/清理、最终响应 DTO 与发行基础设施配置。未经评审不建立 `ready` 实施计划，不把 proposed 标记为 accepted。
diff --git a/jenkins/Jenkinsfile.agc-global-version-issue b/jenkins/Jenkinsfile.agc-global-version-issue
index 824394f7c..83277e23c 100644
--- a/jenkins/Jenkinsfile.agc-global-version-issue
+++ b/jenkins/Jenkinsfile.agc-global-version-issue
@@ -16,14 +16,15 @@ pipeline {
     skipDefaultCheckout(true)
     buildDiscarder(logRotator(numToKeepStr: '100', artifactNumToKeepStr: '20'))
     // Copy Artifact 保持 Production 权限模式：生产者必须显式授权消费者。
-    // 调度管线与手动发布管线都要 copy 本 Job 的 agc-global-version.txt 才能把总号
+    // 所有调度与手动发布管线都要 copy 本 Job 的 agc-global-version.txt 才能把总号
     // 透传给渠道构建；缺授权时 copyArtifacts 会报「Unable to find project for
     // artifact copy」（用户触发的构建按「认证用户」判权，SYSTEM 定时构建会短路放行，
     // 所以定时调度能过、手动发布必挂；2026-09-20 #103 与 2026-09-21 手动发布
-    // #6/#7 均命中）。这里必须同时列出两条消费者：Genarrative-Scheduled-Revision-Trigger
-    // 与 Genarrative-Manual-Build-And-Deploy。改完本文件后必须先单独跑一次本 Job，
-    // 让 Declarative Pipeline 把 Job property 写回 Jenkins，再重跑调度或手动发布。
-    copyArtifactPermission('Genarrative-Scheduled-Revision-Trigger,Genarrative-Manual-Build-And-Deploy')
+    // #6/#7 均命中）。这里必须列出全部消费者：Genarrative-Scheduled-Revision-Trigger、
+    // Genarrative-Scheduled-Release-Trigger 与 Genarrative-Manual-Build-And-Deploy。
+    // 改完本文件后必须先单独跑一次本 Job，让 Declarative Pipeline 把 Job property
+    // 写回 Jenkins，再重跑调度或手动发布。
+    copyArtifactPermission('Genarrative-Scheduled-Revision-Trigger,Genarrative-Scheduled-Release-Trigger,Genarrative-Manual-Build-And-Deploy')
   }
 
   environment {
@@ -34,7 +35,7 @@ pipeline {
   }
 
   parameters {
-    choice(name: 'AGC_CHANNEL', choices: ['unified', 'dev-win', 'dev-mac'], description: '发号用途：unified 为统一构建（一个号同时给 dev-win 与 dev-mac），其余为单渠道热修')
+    choice(name: 'AGC_CHANNEL', choices: ['unified', 'dev-win', 'dev-mac', 'release-unified', 'release-win', 'release-mac'], description: '发号用途标签：unified / release-unified 为一个号同时给两个平台，其余为单渠道热修')
     string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '取发号脚本的源码分支；默认 master')
     string(name: 'COMMIT_HASH', defaultValue: '', description: '可选：固定提交；留空则解析 SOURCE_BRANCH 当前 revision')
     booleanParam(name: 'SEED_ONLY', defaultValue: false, description: '仅做一次性播种：写入渠道与仓库版本的最大值作为基线，不递增、不烧号')
diff --git a/jenkins/Jenkinsfile.scheduled-release-trigger b/jenkins/Jenkinsfile.scheduled-release-trigger
new file mode 100644
index 000000000..28c87b17f
--- /dev/null
+++ b/jenkins/Jenkinsfile.scheduled-release-trigger
@@ -0,0 +1,289 @@
+// release 每日调度管线：每天 04:00 检查源码分支，
+// 按独立 scope 触发 release Full Build 与 AGC Windows/macOS，
+// 等待并汇总结果；只有对应 lane 成功后才推进该 lane 的成功 revision。
+pipeline {
+  agent {
+    label 'linux && genarrative-build'
+  }
+
+  options {
+    disableConcurrentBuilds()
+    skipDefaultCheckout(true)
+    buildDiscarder(logRotator(numToKeepStr: '100', artifactNumToKeepStr: '10'))
+  }
+
+  triggers {
+    cron('0 4 * * *')
+  }
+
+  environment {
+    GIT_REMOTE_URL = 'ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_CREDENTIAL_ID = 'genarrative-local-gitea-ssh'
+    FULL_BUILD_JOB_NAME = 'Genarrative-Full-Build-And-Deploy'
+    AGC_WINDOWS_BUILD_JOB_NAME = 'Genarrative-Agc-Windows-Build'
+    AGC_MACOS_BUILD_JOB_NAME = 'Genarrative-Agc-MacOS-Build'
+    AGC_GLOBAL_VERSION_JOB_NAME = 'Genarrative-Agc-Global-Version-Issue'
+    AGC_GLOBAL_VERSION_ARTIFACT = 'agc-global-version.txt'
+    REVISION_STATE_FILE = '.jenkins-last-release-revision'
+    FULL_REVISION_STATE_FILE = '.jenkins-last-release-full-revision'
+    AGC_REVISION_STATE_FILE = '.jenkins-last-release-agc-revision'
+    AGC_SCOPE_CACHE_DIR = '.agc-release-scope-cache'
+  }
+
+  parameters {
+    string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '被检查的源码分支；默认 master')
+    booleanParam(name: 'FORCE_TRIGGER', defaultValue: false, description: '勾选后忽略版本与路径比较，强制发布 release 服务端与 AGC 双平台')
+    choice(name: 'DATABASE_BACKUP_MODE', choices: ['async', 'sync', 'skip'], description: 'release 发布前 SpacetimeDB 备份策略；常规使用 async，高风险迁移使用 sync，skip 仅限明确无需备份')
+    choice(name: 'STDB_API_ROLLOUT_MODE', choices: ['normal', 'pause-after-stdb'], description: 'normal 为自动完成 Stdb → API；pause-after-stdb 在发布 Stdb 后等待审批人放行 API')
+    string(name: 'STDB_API_ROLLOUT_APPROVERS', defaultValue: '', description: 'pause-after-stdb 必填：允许放行 API 的 Jenkins 用户/组，多个值用逗号分隔')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: true, description: 'release API 是否构建、归档并部署 Pingora 影子网关')
+    booleanParam(name: 'EXIT_MAINTENANCE_MODE_AFTER_COMPLETION', defaultValue: true, description: '完整发布成功后是否退出维护模式；首次验收可暂时关闭')
+  }
+
+  stages {
+    stage('Resolve Revision') {
+      steps {
+        withCredentials([sshUserPrivateKey(credentialsId: env.GIT_REMOTE_CREDENTIAL_ID, keyFileVariable: 'GENARRATIVE_GIT_SSH_KEY')]) {
+          sh '''#!/usr/bin/env bash
+            set -euo pipefail
+            export GIT_SSH_COMMAND="ssh -i ${GENARRATIVE_GIT_SSH_KEY:?缺少 Git SSH 凭据} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"
+            revision="$(git ls-remote "${GIT_REMOTE_URL:?缺少 GIT_REMOTE_URL}" "refs/heads/${SOURCE_BRANCH}" | awk 'NR == 1 { print $1 }')"
+            if [[ ! "${revision}" =~ ^[0-9a-f]{40}$ ]]; then
+              echo "无法解析远端分支版本: branch=${SOURCE_BRANCH} revision=${revision:-<empty>}" >&2
+              exit 1
+            fi
+            printf '%s' "${revision}" > .jenkins-remote-revision
+            echo "release 远端版本: branch=${SOURCE_BRANCH} revision=${revision}"
+          '''
+        }
+        script {
+          env.REMOTE_REVISION = readFile('.jenkins-remote-revision').trim()
+          def legacyRevision = fileExists(env.REVISION_STATE_FILE) ? readFile(env.REVISION_STATE_FILE).trim() : ''
+          env.LAST_FULL_REVISION = fileExists(env.FULL_REVISION_STATE_FILE) ? readFile(env.FULL_REVISION_STATE_FILE).trim() : legacyRevision
+          env.LAST_AGC_REVISION = fileExists(env.AGC_REVISION_STATE_FILE) ? readFile(env.AGC_REVISION_STATE_FILE).trim() : legacyRevision
+          env.FULL_REVISION_CHANGED = (params.FORCE_TRIGGER || env.LAST_FULL_REVISION != env.REMOTE_REVISION) ? 'true' : 'false'
+          env.AGC_REVISION_CHANGED = (params.FORCE_TRIGGER || env.LAST_AGC_REVISION != env.REMOTE_REVISION) ? 'true' : 'false'
+          env.REVISION_CHANGED = (env.FULL_REVISION_CHANGED == 'true' || env.AGC_REVISION_CHANGED == 'true') ? 'true' : 'false'
+          if (params.STDB_API_ROLLOUT_MODE == 'pause-after-stdb' && !params.STDB_API_ROLLOUT_APPROVERS?.trim()) {
+            error('pause-after-stdb 必须填写 STDB_API_ROLLOUT_APPROVERS。')
+          }
+          if (env.REVISION_CHANGED != 'true') {
+            currentBuild.result = 'NOT_BUILT'
+            currentBuild.description = "release 版本未变化，跳过：${env.SOURCE_BRANCH} 仍是 ${env.REMOTE_REVISION.take(12)}"
+            echo currentBuild.description
+          }
+        }
+      }
+    }
+
+    stage('Resolve Release Scope') {
+      when {
+        expression { return env.REVISION_CHANGED == 'true' }
+      }
+      steps {
+        withCredentials([sshUserPrivateKey(credentialsId: env.GIT_REMOTE_CREDENTIAL_ID, keyFileVariable: 'GENARRATIVE_GIT_SSH_KEY')]) {
+          script {
+            // 判定失败一律按「需要发布」处理，避免路径过滤阻塞正式发布。
+            def output = 'agc=changed\nfull=changed'
+            try {
+              output = sh(script: '''#!/usr/bin/env bash
+                set -uo pipefail
+                export GIT_SSH_COMMAND="ssh -i ${GENARRATIVE_GIT_SSH_KEY:?缺少 Git SSH 凭据} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"
+                previous_agc="$(cat "${AGC_REVISION_STATE_FILE}" 2>/dev/null || cat "${REVISION_STATE_FILE}" 2>/dev/null || true)"
+                previous_full="$(cat "${FULL_REVISION_STATE_FILE}" 2>/dev/null || cat "${REVISION_STATE_FILE}" 2>/dev/null || true)"
+                mkdir -p "${AGC_SCOPE_CACHE_DIR}"
+                if [[ ! -d "${AGC_SCOPE_CACHE_DIR}/.git" ]]; then
+                  git -C "${AGC_SCOPE_CACHE_DIR}" init --quiet
+                  git -C "${AGC_SCOPE_CACHE_DIR}" remote add origin "${GIT_REMOTE_URL}" 2>/dev/null || true
+                fi
+                refspec="+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+                if ! git -C "${AGC_SCOPE_CACHE_DIR}" fetch --quiet --depth=200 --no-tags --filter=blob:none origin "${refspec}"; then
+                  git -C "${AGC_SCOPE_CACHE_DIR}" fetch --quiet --depth=200 --no-tags origin "${refspec}" || { printf 'agc=changed\nfull=changed\n'; exit 0; }
+                fi
+                changed_paths_for() {
+                  local previous="$1"
+                  if [[ -z "${previous}" ]] || ! git -C "${AGC_SCOPE_CACHE_DIR}" cat-file -e "${previous}^{commit}" 2>/dev/null; then
+                    printf '__changed__\n'
+                    return
+                  fi
+                  git -C "${AGC_SCOPE_CACHE_DIR}" diff --name-only "${previous}" "${REMOTE_REVISION}" 2>/dev/null || printf '__changed__\n'
+                }
+                agc_paths="$(changed_paths_for "${previous_agc}")"
+                agc_scope=unchanged
+                if [[ "${agc_paths}" == '__changed__' ]]; then
+                  agc_scope=changed
+                else
+                  while IFS= read -r changed_path; do
+                    [[ -z "${changed_path}" ]] && continue
+                    case "${changed_path}" in
+                      apps/ai-game-creator-shell/*|packages/*|server-rs/crates/*|plugins/agc-cocos-editor/*|plugins/agc-unity-editor/*|plugins/agc-godot-editor/*|apps/desktop-shell/src-tauri/icons/*|package.json|package-lock.json)
+                        agc_scope=changed
+                        ;;
+                    esac
+                  done <<< "${agc_paths}"
+                fi
+                full_paths="$(changed_paths_for "${previous_full}")"
+                full_scope=unchanged
+                if [[ "${full_paths}" == '__changed__' ]]; then
+                  full_scope=changed
+                else
+                  while IFS= read -r changed_path; do
+                    [[ -z "${changed_path}" ]] && continue
+                    case "${changed_path}" in
+                      docs/*|.codex/*|jenkins/*|apps/ai-game-creator-shell/*|apps/mobile-shell/*|apps/desktop-shell/*|apps/preview-deployer-web/*|tools/*|*.md)
+                        ;;
+                      *)
+                        full_scope=changed
+                        ;;
+                    esac
+                  done <<< "${full_paths}"
+                fi
+                printf 'agc=%s\nfull=%s\n' "${agc_scope}" "${full_scope}"
+              ''', returnStdout: true).trim()
+            } catch (error) {
+              echo "release 发布范围判定失败，按需要发布处理：${error}"
+              output = 'agc=changed\nfull=changed'
+            }
+            def values = output.split('\n').collect { it.trim() }.findAll { it }
+            def readScope = { String key ->
+              def entry = values.find { it.startsWith(key + '=') }
+              def value = entry == null ? '' : entry.split('=')[1]
+              return (value == 'unchanged') ? 'unchanged' : 'changed'
+            }
+            env.AGC_RELEASE_SCOPE = readScope('agc')
+            env.FULL_BUILD_SCOPE = readScope('full')
+            echo "release 发布范围：AGC=${env.AGC_RELEASE_SCOPE} FullBuild=${env.FULL_BUILD_SCOPE}（AGC=${env.LAST_AGC_REVISION ?: '无'}，Full=${env.LAST_FULL_REVISION ?: '无'}）"
+          }
+        }
+      }
+    }
+
+    stage('Trigger Release Downstreams') {
+      when {
+        expression { return env.REVISION_CHANGED == 'true' }
+      }
+      steps {
+        script {
+          def pinnedRevision = env.REMOTE_REVISION
+          def fullTriggered = params.FORCE_TRIGGER || env.FULL_BUILD_SCOPE != 'unchanged'
+          def agcTriggered = params.FORCE_TRIGGER || env.AGC_RELEASE_SCOPE != 'unchanged'
+          def fullParameters = [
+            string(name: 'SOURCE_BRANCH', value: env.SOURCE_BRANCH),
+            string(name: 'COMMIT_HASH', value: pinnedRevision),
+            string(name: 'DEPLOY_TARGET', value: 'release'),
+            booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', value: true),
+            string(name: 'DATABASE_BACKUP_MODE', value: params.DATABASE_BACKUP_MODE),
+            string(name: 'STDB_API_ROLLOUT_MODE', value: params.STDB_API_ROLLOUT_MODE),
+            string(name: 'STDB_API_ROLLOUT_APPROVERS', value: params.STDB_API_ROLLOUT_APPROVERS?.trim() ?: ''),
+            booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', value: params.INCLUDE_PINGORA_GATEWAY),
+            booleanParam(name: 'EXIT_MAINTENANCE_MODE_AFTER_COMPLETION', value: params.EXIT_MAINTENANCE_MODE_AFTER_COMPLETION),
+          ]
+          if (!fullTriggered) {
+            echo "上一轮 release 调度后没有服务端相关变更，跳过 ${env.FULL_BUILD_JOB_NAME}"
+          }
+          if (!agcTriggered) {
+            echo "上一轮 release 调度后没有 AGC 客户端相关变更，跳过 ${env.AGC_WINDOWS_BUILD_JOB_NAME} 与 ${env.AGC_MACOS_BUILD_JOB_NAME}"
+          }
+          def outcome = [:]
+          def runDownstream = { String jobName, List jobParameters, int timeoutMinutes ->
+            try {
+              timeout(time: timeoutMinutes, unit: 'MINUTES') {
+                def run = build job: jobName,
+                  wait: true,
+                  propagate: false,
+                  parameters: jobParameters
+                outcome[jobName] = "#${run.number}:${run.result}"
+                if (run.result != 'SUCCESS') {
+                  error("${jobName} 结果=${run.result}")
+                }
+              }
+            } catch (err) {
+              if (!outcome[jobName]) {
+                outcome[jobName] = "异常:${err.message}"
+              }
+              echo "${jobName} 等待失败: ${err.message}"
+              throw err
+            }
+          }
+          def branches = [:]
+          def fullTimeout = params.STDB_API_ROLLOUT_MODE == 'pause-after-stdb' ? 300 : 150
+          if (fullTriggered) {
+            branches[env.FULL_BUILD_JOB_NAME] = {
+              runDownstream(env.FULL_BUILD_JOB_NAME, fullParameters, fullTimeout)
+            }
+          }
+          if (agcTriggered) {
+            // Windows 与 macOS 共用一个总号；发号 Job 是唯一发号源。
+            def versionRun = build job: env.AGC_GLOBAL_VERSION_JOB_NAME,
+              wait: true,
+              propagate: true,
+              parameters: [
+                string(name: 'SOURCE_BRANCH', value: env.SOURCE_BRANCH),
+                string(name: 'COMMIT_HASH', value: pinnedRevision),
+                string(name: 'AGC_CHANNEL', value: 'release-unified'),
+              ]
+            copyArtifacts(
+              projectName: env.AGC_GLOBAL_VERSION_JOB_NAME,
+              selector: specific(versionRun.number.toString()),
+              filter: env.AGC_GLOBAL_VERSION_ARTIFACT,
+              target: '.',
+              flatten: true,
+            )
+            env.AGC_GLOBAL_VERSION = readFile(env.AGC_GLOBAL_VERSION_ARTIFACT).trim()
+            echo "本轮 AGC release 客户端总版本号: ${env.AGC_GLOBAL_VERSION}"
+            def agcParameters = [
+              string(name: 'SOURCE_BRANCH', value: env.SOURCE_BRANCH),
+              string(name: 'COMMIT_HASH', value: pinnedRevision),
+              string(name: 'AGC_UPDATE_CHANNEL', value: 'release'),
+              string(name: 'AGC_RELEASE_VERSION', value: env.AGC_GLOBAL_VERSION),
+            ]
+            // macOS 节点是办公机：离线期间排队的旧构建在节点回来后必须自行让位。
+            def agcMacosParameters = agcParameters + [
+              booleanParam(name: 'SKIP_IF_SUPERSEDED', value: true),
+            ]
+            branches[env.AGC_WINDOWS_BUILD_JOB_NAME] = {
+              runDownstream(env.AGC_WINDOWS_BUILD_JOB_NAME, agcParameters, 120)
+            }
+            branches[env.AGC_MACOS_BUILD_JOB_NAME] = {
+              runDownstream(env.AGC_MACOS_BUILD_JOB_NAME, agcMacosParameters, 120)
+            }
+          }
+          if (!branches.isEmpty()) {
+            try {
+              parallel branches
+            } catch (err) {
+              echo "release 并行下游存在失败分支: ${err.message}"
+            }
+          }
+          def fullResult = outcome[env.FULL_BUILD_JOB_NAME]
+          def windowsResult = outcome[env.AGC_WINDOWS_BUILD_JOB_NAME]
+          def macosResult = outcome[env.AGC_MACOS_BUILD_JOB_NAME]
+          def fullSucceeded = !fullTriggered || (fullResult != null && fullResult.endsWith(':SUCCESS'))
+          def agcSucceeded = !agcTriggered || (windowsResult != null && windowsResult.endsWith(':SUCCESS') && macosResult != null && macosResult.endsWith(':SUCCESS'))
+          if (fullSucceeded) {
+            writeFile file: env.FULL_REVISION_STATE_FILE, text: pinnedRevision
+          }
+          if (agcSucceeded) {
+            writeFile file: env.AGC_REVISION_STATE_FILE, text: pinnedRevision
+          }
+          if (fullSucceeded && agcSucceeded) {
+            writeFile file: env.REVISION_STATE_FILE, text: pinnedRevision
+          }
+          def summary = outcome.collect { jobName, result -> "${jobName}=${result}" }.join(' ')
+          def target = "${env.SOURCE_BRANCH}@${pinnedRevision.take(12)}"
+          currentBuild.description = "release 调度 ${target}；FullBuild=${fullTriggered ? 'triggered' : 'unchanged'}；AGC=${agcTriggered ? 'triggered' : 'unchanged'}${summary ? '；' + summary : ''}"
+          echo currentBuild.description
+          if (!fullSucceeded || !agcSucceeded) {
+            error("release 下游未全部成功: ${summary}")
+          }
+        }
+      }
+    }
+  }
+
+  post {
+    always {
+      echo "release 调度结束: branch=${env.SOURCE_BRANCH} revision=${env.REMOTE_REVISION ?: ''} changed=${env.REVISION_CHANGED ?: ''} agcScope=${env.AGC_RELEASE_SCOPE ?: ''} fullScope=${env.FULL_BUILD_SCOPE ?: ''}"
+    }
+  }
+}
diff --git a/jenkins/agc-global-version-issue-job-config.xml b/jenkins/agc-global-version-issue-job-config.xml
index 858f39d5e..b55dbcac7 100644
--- a/jenkins/agc-global-version-issue-job-config.xml
+++ b/jenkins/agc-global-version-issue-job-config.xml
@@ -1,19 +1,22 @@
 <?xml version='1.1' encoding='UTF-8'?>
 <flow-definition plugin="workflow-job">
   <actions/>
-  <description>AGC 总版本号唯一发号入口：先写 OSS agc/global-version.json，再由各渠道构建接收号发布。统一构建发一次号给所有渠道；dry-run 只预览不烧号。</description>
+  <description>AGC 总版本号唯一发号入口：先写 OSS agc/global-version.json，再由各渠道构建接收号发布。dev / release 的统一构建各自发一次号给两个平台；dry-run 只预览不烧号。</description>
   <keepDependencies>false</keepDependencies>
   <properties>
     <hudson.model.ParametersDefinitionProperty>
       <parameterDefinitions>
         <hudson.model.ChoiceParameterDefinition>
           <name>AGC_CHANNEL</name>
-          <description>发号用途：unified 为统一构建（一个号同时给 dev-win 与 dev-mac），其余为单渠道热修</description>
+          <description>发号用途标签：unified / release-unified 为一个号同时给两个平台，其余为单渠道热修</description>
           <choices class="java.util.Arrays$ArrayList">
             <a class="string-array">
               <string>unified</string>
               <string>dev-win</string>
               <string>dev-mac</string>
+              <string>release-unified</string>
+              <string>release-win</string>
+              <string>release-mac</string>
             </a>
           </choices>
         </hudson.model.ChoiceParameterDefinition>
diff --git a/jenkins/scheduled-release-trigger-job-config.xml b/jenkins/scheduled-release-trigger-job-config.xml
new file mode 100644
index 000000000..8a8afe6be
--- /dev/null
+++ b/jenkins/scheduled-release-trigger-job-config.xml
@@ -0,0 +1,92 @@
+<?xml version='1.1' encoding='UTF-8'?>
+<flow-definition plugin="workflow-job">
+  <actions/>
+  <description>每天 04:00 检查源码分支版本（cron 定义在 Jenkinsfile 内）：revision 变化且出现服务端相关路径时触发 release Full Build，出现客户端相关路径时经 Genarrative-Agc-Global-Version-Issue 发号并触发 AGC Windows、macOS；调度器等待并汇总三类下游结果，按成功 lane 推进 revision，失败 lane 下一轮补发。下游 Job 一律不自带触发器。</description>
+  <keepDependencies>false</keepDependencies>
+  <properties>
+    <hudson.model.ParametersDefinitionProperty>
+      <parameterDefinitions>
+        <hudson.model.StringParameterDefinition>
+          <name>SOURCE_BRANCH</name>
+          <description>被检查的源码分支；默认 master</description>
+          <defaultValue>master</defaultValue>
+          <trim>true</trim>
+        </hudson.model.StringParameterDefinition>
+        <hudson.model.BooleanParameterDefinition>
+          <name>FORCE_TRIGGER</name>
+          <description>勾选后忽略版本与路径比较，强制发布 release 服务端与 AGC 双平台</description>
+          <defaultValue>false</defaultValue>
+        </hudson.model.BooleanParameterDefinition>
+        <hudson.model.ChoiceParameterDefinition>
+          <name>DATABASE_BACKUP_MODE</name>
+          <description>release 发布前 SpacetimeDB 备份策略；常规使用 async，高风险迁移使用 sync，skip 仅限明确无需备份</description>
+          <choices class="java.util.Arrays$ArrayList">
+            <a class="string-array">
+              <string>async</string>
+              <string>sync</string>
+              <string>skip</string>
+            </a>
+          </choices>
+        </hudson.model.ChoiceParameterDefinition>
+        <hudson.model.ChoiceParameterDefinition>
+          <name>STDB_API_ROLLOUT_MODE</name>
+          <description>normal 为自动完成 Stdb → API；pause-after-stdb 在发布 Stdb 后等待审批人放行 API</description>
+          <choices class="java.util.Arrays$ArrayList">
+            <a class="string-array">
+              <string>normal</string>
+              <string>pause-after-stdb</string>
+            </a>
+          </choices>
+        </hudson.model.ChoiceParameterDefinition>
+        <hudson.model.StringParameterDefinition>
+          <name>STDB_API_ROLLOUT_APPROVERS</name>
+          <description>pause-after-stdb 必填：允许放行 API 的 Jenkins 用户/组，多个值用逗号分隔</description>
+          <defaultValue></defaultValue>
+          <trim>true</trim>
+        </hudson.model.StringParameterDefinition>
+        <hudson.model.BooleanParameterDefinition>
+          <name>INCLUDE_PINGORA_GATEWAY</name>
+          <description>release API 是否构建、归档并部署 Pingora 影子网关</description>
+          <defaultValue>true</defaultValue>
+        </hudson.model.BooleanParameterDefinition>
+        <hudson.model.BooleanParameterDefinition>
+          <name>EXIT_MAINTENANCE_MODE_AFTER_COMPLETION</name>
+          <description>完整发布成功后是否退出维护模式；首次验收可暂时关闭</description>
+          <defaultValue>true</defaultValue>
+        </hudson.model.BooleanParameterDefinition>
+      </parameterDefinitions>
+    </hudson.model.ParametersDefinitionProperty>
+  </properties>
+  <definition class="org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition" plugin="workflow-cps">
+    <scm class="hudson.plugins.git.GitSCM" plugin="git">
+      <configVersion>2</configVersion>
+      <userRemoteConfigs>
+        <hudson.plugins.git.UserRemoteConfig>
+          <url>ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git</url>
+          <credentialsId>genarrative-local-gitea-ssh</credentialsId>
+          <refspec>+refs/heads/master:refs/remotes/origin/master</refspec>
+        </hudson.plugins.git.UserRemoteConfig>
+      </userRemoteConfigs>
+      <branches>
+        <hudson.plugins.git.BranchSpec>
+          <name>*/master</name>
+        </hudson.plugins.git.BranchSpec>
+      </branches>
+      <doGenerateSubmoduleConfigurations>false</doGenerateSubmoduleConfigurations>
+      <submoduleCfg class="empty-list"/>
+      <extensions>
+        <hudson.plugins.git.extensions.impl.CloneOption>
+          <shallow>true</shallow>
+          <noTags>true</noTags>
+          <reference></reference>
+          <depth>1</depth>
+          <honorRefspec>true</honorRefspec>
+        </hudson.plugins.git.extensions.impl.CloneOption>
+      </extensions>
+    </scm>
+    <scriptPath>jenkins/Jenkinsfile.scheduled-release-trigger</scriptPath>
+    <lightweight>false</lightweight>
+  </definition>
+  <triggers/>
+  <disabled>false</disabled>
+</flow-definition>
diff --git a/package.json b/package.json
index 929a974d3..c57f75654 100644
--- a/package.json
+++ b/package.json
@@ -71,6 +71,7 @@
     "check:repository-ci": "bash scripts/check-repository-ci.sh",
     "check:rustfmt": "cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check && cargo fmt --all --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check && cargo fmt --all --manifest-path plugins/agc-unity-editor/native/unity-editor-bridge/Cargo.toml -- --check && cargo fmt --all --manifest-path plugins/agc-godot-editor/native/godot-editor-bridge/Cargo.toml -- --check",
     "check:spacetime-schema": "node scripts/check-spacetime-schema-guard.mjs",
+    "check:game-distribution-media-e2e": "node scripts/check-game-distribution-media-e2e.mjs",
     "check:production-ops": "node scripts/check-production-ops-guardrails.mjs",
     "check:preview-deployer": "node scripts/check-preview-deployer.mjs",
     "check:maintenance-page": "node scripts/check-maintenance-page.mjs",
@@ -82,6 +83,7 @@
     "check:pingora-gateway-smoke": "node scripts/check-pingora-gateway-smoke.mjs",
     "check:nginx-pingora-canary": "node scripts/check-nginx-pingora-canary.mjs",
     "check:nginx-spa-routes": "node scripts/check-nginx-spa-routes.mjs",
+    "check:release-origin-config": "node scripts/check-release-origin-config.mjs",
     "check:pingora-route-parity": "node scripts/check-pingora-route-parity.mjs",
     "check:pingora-canary-live": "node scripts/check-pingora-canary-live.mjs",
     "check:pingora-canary-live-guard": "node scripts/check-pingora-canary-live-guard.mjs",
diff --git a/packages/shared/src/contracts/gameDistribution.ts b/packages/shared/src/contracts/gameDistribution.ts
new file mode 100644
index 000000000..27225d45f
--- /dev/null
+++ b/packages/shared/src/contracts/gameDistribution.ts
@@ -0,0 +1,185 @@
+export const GAME_DISTRIBUTION_CATEGORIES = [
+  '休闲',
+  '益智',
+  '动作',
+  '冒险',
+  '模拟',
+  '策略',
+  '其他',
+] as const;
+
+export type GameDistributionCategory =
+  (typeof GAME_DISTRIBUTION_CATEGORIES)[number];
+
+export type GameDistributionDeviceSupport = {
+  desktop: boolean;
+  mobile: boolean;
+  touch: boolean;
+};
+
+export type GameDistributionInputMode = 'keyboard' | 'mouse' | 'touch';
+export type GameDistributionOrientation =
+  | 'landscape'
+  | 'portrait'
+  | 'responsive';
+
+export type GameDistributionAuthor = {
+  id: string;
+  name: string;
+  avatarUrl?: string | null;
+};
+
+export type GameDistributionVersionStatus =
+  | 'awaiting_upload'
+  | 'uploaded'
+  | 'validating'
+  | 'pending_review'
+  | 'published'
+  | 'upload_failed'
+  | 'validation_failed'
+  | 'rejected'
+  | 'cancelled'
+  | 'revoked';
+
+export type GameDistributionGameVisibility =
+  | 'unpublished'
+  | 'published'
+  | 'suspended';
+
+export type GameDistributionVersionSummary = {
+  id: string;
+  version: string;
+  entryUrl: string;
+  sha256: string;
+  publishedAt: string;
+  controls: string[];
+};
+
+export type GameDistributionGame = {
+  id: string;
+  title: string;
+  summary: string;
+  description: string;
+  category: GameDistributionCategory;
+  tags: string[];
+  coverColor: string;
+  icon: string;
+  /**
+   * 公开封面的 OSS objectKey；未上传封面时为空，展示层需回退到 coverColor/icon 占位。
+   * 通过 `/api/assets/read-url` 换签名 URL 读取，不接受直连外链。
+   */
+  coverObjectKey?: string | null;
+  /** 公开截图的 OSS objectKey 列表，最多 6 张，随版本冻结。 */
+  screenshots?: string[];
+  author: GameDistributionAuthor;
+  deviceSupport: GameDistributionDeviceSupport;
+  inputModes?: GameDistributionInputMode[];
+  orientation?: GameDistributionOrientation;
+  status: Extract<GameDistributionGameVisibility, 'published' | 'unpublished'>;
+  /** 公开切换 CAS 版本号；作者下架与管理员审核都必须回传当前值。 */
+  publicationRevision: number;
+  currentVersion: GameDistributionVersionSummary | null;
+  playCount: number;
+  createdAt: string;
+};
+
+export type GameDistributionListResponse = {
+  games: GameDistributionGame[];
+  nextCursor?: string | null;
+};
+
+export type GameDistributionCreateGameRequest = {
+  /** 发布方本地项目标识；同一作者重复发布会复用既有 gameId。 */
+  localProjectId?: string | null;
+  title: string;
+  summary: string;
+  description?: string;
+  category: GameDistributionCategory;
+  tags?: string[];
+  coverAssetId?: string;
+  /** 截图素材 ID（最多 6 张，复用平台图片上传与归属校验）。 */
+  screenshots?: string[];
+  deviceSupport: GameDistributionDeviceSupport;
+  inputModes: GameDistributionInputMode[];
+  orientation: GameDistributionOrientation;
+};
+
+export type GameDistributionCreateVersionRequest = {
+  localProjectId?: string | null;
+  packageSha256: string;
+  packageBytes: number;
+  packageFileCount: number;
+  packageEntryPath: 'index.html';
+  gameMetadata: GameDistributionCreateGameRequest;
+};
+
+export type GameDistributionPrivateVersion = {
+  versionId: string;
+  gameId: string;
+  versionNumber: number;
+  packageSha256: string;
+  packageBytes: number;
+  status: GameDistributionVersionStatus;
+  /** 游戏公开修订号；撤回与审核动作都必须回传当前值做 CAS。 */
+  publicationRevision: number;
+  reviewReason?: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * 版本状态的下一步动作，由服务端派生；客户端只按它渲染主行动作，不自行推断状态。
+ */
+export type GameDistributionRecoveryAction =
+  | 'upload'
+  | 'submit'
+  | 'wait'
+  | 'none'
+  | 'reupload'
+  | 'fix_package'
+  | 'fix_metadata';
+
+/** 冻结资料里的截图：同时保留素材 ID（作者续发可复用）与对象键（展示换签用）。 */
+export type GameDistributionFrozenScreenshot = {
+  assetId: string;
+  objectKey: string;
+};
+
+/**
+ * 随版本冻结的游戏资料快照。
+ *
+ * 只有作者本人（版本回读）与管理员（审核回读）会拿到素材 ID；公开投影只给对象键。
+ * 历史版本可能没有快照，读取方必须按空值处理。
+ */
+export type GameDistributionVersionFrozenMetadata = {
+  title?: string;
+  summary?: string;
+  description?: string;
+  category?: GameDistributionCategory;
+  tags?: string[];
+  coverAssetId?: string | null;
+  coverObjectKey?: string | null;
+  screenshots?: GameDistributionFrozenScreenshot[];
+  deviceSupport?: GameDistributionDeviceSupport;
+  inputModes?: GameDistributionInputMode[];
+  orientation?: GameDistributionOrientation;
+};
+
+export type GameDistributionVersionDetail = {
+  game: GameDistributionGame;
+  version: GameDistributionPrivateVersion & {
+    recoveryAction: GameDistributionRecoveryAction;
+    frozenMetadata?: GameDistributionVersionFrozenMetadata | null;
+  };
+};
+
+export type GameDistributionCancelVersionRequest = {
+  expectedPublicationRevision: number;
+  reason?: string;
+};
+
+export type GameDistributionCancelVersionResponse = {
+  game: GameDistributionGame;
+  version: GameDistributionPrivateVersion;
+  replayed: boolean;
+};
diff --git a/packages/shared/src/contracts/index.ts b/packages/shared/src/contracts/index.ts
index c2c2e38c3..30d615d47 100644
--- a/packages/shared/src/contracts/index.ts
+++ b/packages/shared/src/contracts/index.ts
@@ -1,5 +1,6 @@
 export * from './editorAgent';
 export type * from './editorAudio';
 export * from './gameCreationApp';
+export * from './gameDistribution';
 export * from './hostBridge';
 export type * from './hyper3d';
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 598fe155f..87fb5dc00 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -5,6 +5,7 @@ export * from './contracts/common';
 export type * from './contracts/editorAudio';
 export * from './contracts/editorScene';
 export * from './contracts/externalGeneration';
+export * from './contracts/gameDistribution';
 export type * from './contracts/hyper3d';
 export * from './contracts/runtime';
 export * from './http';
diff --git a/scripts/build-gitea-rust-cache.sh b/scripts/build-gitea-rust-cache.sh
index 6ad7d893b..1bd6a22aa 100644
--- a/scripts/build-gitea-rust-cache.sh
+++ b/scripts/build-gitea-rust-cache.sh
@@ -5,6 +5,15 @@ set -euo pipefail
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
 base_ref="${1:?usage: build-gitea-rust-cache.sh <verified-base-image> <candidate-tag>}"
 candidate_tag="${2:?candidate image tag is required}"
+requested_source_commit="${3:-}"
+if [[ "$#" -gt 3 ]]; then
+  echo 'usage: build-gitea-rust-cache.sh <verified-base-image> <candidate-tag> [master-commit-sha]' >&2
+  exit 2
+fi
+if [[ -n "${requested_source_commit}" && ! "${requested_source_commit}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+  echo 'master-commit-sha must be a complete 40-character SHA.' >&2
+  exit 2
+fi
 # 与实际 Gitea checkout 路径一致；Rust 对象 key 包含编译 cwd，不能随意换临时根。
 workspace=/workspace/GenarrativeAI/Genarrative
 [[ "${CI:-}" != true ]] || { echo 'Run on the trusted image builder, outside CI jobs.' >&2; exit 1; }
@@ -22,7 +31,17 @@ bash "${repo_root}/scripts/gitea-ci-job-image.sh" verify "${base_id}"
 
 # 只归档远端 master 的确定提交；不复制当前工作区或本地凭据。
 git -C "${repo_root}" fetch --no-tags origin refs/heads/master
-source_commit="$(git -C "${repo_root}" rev-parse FETCH_HEAD^{commit})"
+master_commit="$(git -C "${repo_root}" rev-parse FETCH_HEAD^{commit})"
+if [[ -n "${requested_source_commit}" ]]; then
+  git -C "${repo_root}" cat-file -e "${requested_source_commit}^{commit}"
+  if ! git -C "${repo_root}" merge-base --is-ancestor "${requested_source_commit}" "${master_commit}"; then
+    echo "master-commit-sha is not contained in fetched master: ${requested_source_commit}" >&2
+    exit 1
+  fi
+  source_commit="$(git -C "${repo_root}" rev-parse "${requested_source_commit}^{commit}")"
+else
+  source_commit="${master_commit}"
+fi
 work_dir="$(mktemp -d "${TMPDIR:-/tmp}/gitea-rust-cache.XXXXXX")"
 container_id=''
 cleanup() {
@@ -50,7 +69,7 @@ container_id="$(docker run --detach --cpus=4 --memory=12g --pids-limit=1024 \
 docker exec "${container_id}" mkdir -p "${workspace}" /opt/genarrative-ci/rust-cache/objects
 git -C "${repo_root}" archive "${source_commit}" | docker cp - "${container_id}:${workspace}"
 docker cp "${work_dir}/snapshot/." "${container_id}:/opt/genarrative-ci/rust-cache/"
-docker cp "${repo_root}/scripts/ci-rust-cache.sh" "${container_id}:/tmp/ci-rust-cache.sh"
+docker exec "${container_id}" cp "${workspace}/scripts/ci-rust-cache.sh" /tmp/ci-rust-cache.sh
 docker exec --interactive --workdir "${workspace}" "${container_id}" bash -s <<'WARM'
 set -euo pipefail
 rustc -vV > /opt/genarrative-ci/rust-cache/rustc.txt
@@ -63,9 +82,49 @@ source "${GITHUB_ENV}"
 set +a
 test -n "${RUSTC_WRAPPER}"
 trap 'bash /tmp/ci-rust-cache.sh report' EXIT
-cd apps/ai-game-creator-shell/src-tauri
-cargo test --locked --manifest-path Cargo.toml \
-  --bin genarrative-ai-game-creator-shell --no-run
+# 与 CI 的工作目录、features 和目标逐项对齐，只编译，不运行测试/应用。
+echo '[rust-cache] warming backend tests and checks'
+cargo test --locked --workspace --exclude spacetime-module --no-fail-fast \
+  --manifest-path server-rs/Cargo.toml --no-run
+cargo test --locked -p spacetime-module --no-fail-fast \
+  --manifest-path server-rs/Cargo.toml --no-run
+cargo check --locked -p api-server --all-targets --manifest-path server-rs/Cargo.toml
+cargo check --locked -p spacetime-module --manifest-path server-rs/Cargo.toml
+
+echo '[rust-cache] warming AGC standalone, shared and plugin crates'
+for manifest in \
+  server-rs/crates/agent-runtime-core/Cargo.toml \
+  server-rs/crates/agent-runtime-orchestration/Cargo.toml \
+  plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml; do
+  # 与 CI 一样，这些 crate 没有已提交的独立 Cargo.lock。
+  cargo test --manifest-path "${manifest}" --no-run
+done
+cargo test --locked -p platform-llm --manifest-path server-rs/Cargo.toml --no-run
+cargo test --locked -p shared-contracts --manifest-path server-rs/Cargo.toml --no-run
+for editor in unity godot; do
+  cargo test --locked --manifest-path "plugins/agc-${editor}-editor/native/${editor}-editor-bridge/Cargo.toml" --no-run
+done
+
+echo '[rust-cache] warming desktop tests and AGC prompt contracts'
+cargo test --manifest-path apps/desktop-shell/src-tauri/Cargo.toml --no-run
+cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml \
+  --test runtime_prompt_bundle_build --test prompt_source_boundaries --no-run
+
+# Cargo 的 fresh 判断不保证不同 cwd 都经过 sccache；先清掉临时容器中的 target。
+cargo clean --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
+echo '[rust-cache] warming AGC Rust lanes'
+(
+  cd apps/ai-game-creator-shell/src-tauri
+  cargo test --locked --manifest-path Cargo.toml \
+    --bin genarrative-ai-game-creator-shell --no-run
+)
+cargo clean --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
+echo '[rust-cache] warming AGC agent-run smoke executable'
+(
+  cd apps/ai-game-creator-shell
+  cargo build --manifest-path src-tauri/Cargo.toml
+)
+du -sh /opt/genarrative-ci/rust-cache/objects
 WARM
 docker cp "${container_id}:/opt/genarrative-ci/rust-cache/." "${work_dir}/snapshot/"
 docker rm -f "${container_id}" >/dev/null
diff --git a/scripts/check-game-distribution-media-e2e.mjs b/scripts/check-game-distribution-media-e2e.mjs
new file mode 100644
index 000000000..90599514b
--- /dev/null
+++ b/scripts/check-game-distribution-media-e2e.mjs
@@ -0,0 +1,508 @@
+// 游戏分发「封面 + 截图」真实链路检查（需要本地 dev 栈 + 真实 OSS 配置）。
+//
+// 用法：
+//   E2E_ADMIN_USER=<管理员用户名> E2E_ADMIN_PASSWORD=<管理员密码> \
+//     npm run check:game-distribution-media-e2e
+//   E2E_API_BASE 可覆盖 api-server 地址（默认 http://127.0.0.1:12401）。
+//
+// 覆盖：真实素材直传 OSS → 创建游戏（素材归属校验）→ 创建版本（资料冻结）→ 送审 →
+// 作者回读 frozenMetadata → 待审期间匿名不可见/不可读 → 管理员审核通过 → 公开投影
+// 暴露对象键且不泄露素材 ID → 匿名换签读封面与截图 → 发行网关可直接游玩。
+import JSZip from 'jszip';
+
+const API = process.env.E2E_API_BASE ?? 'http://127.0.0.1:12401';
+const ENVELOPE = { 'x-genarrative-response-envelope': 'v1' };
+const ADMIN_USER = (process.env.E2E_ADMIN_USER ?? '').trim();
+const ADMIN_PASSWORD = process.env.E2E_ADMIN_PASSWORD ?? '';
+if (!ADMIN_USER || !ADMIN_PASSWORD) {
+  console.error(
+    '缺少 E2E_ADMIN_USER / E2E_ADMIN_PASSWORD：请用已配置管理员账号的环境变量运行，' +
+      '本地栈可先以 GENARRATIVE_ADMIN_USERNAME / GENARRATIVE_ADMIN_PASSWORD 启动 api-server。',
+  );
+  process.exit(2);
+}
+const COVER_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64',
+);
+
+let failures = 0;
+function check(name, ok, detail = '') {
+  if (!ok) failures += 1;
+  console.log(
+    `${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` :: ${detail}` : ''}`,
+  );
+}
+
+async function api(path, options = {}) {
+  const { method = 'GET', token, body, headers = {}, binary } = options;
+  const finalHeaders = { ...ENVELOPE, ...headers };
+  if (token) finalHeaders.Authorization = `Bearer ${token}`;
+  let finalBody;
+  if (binary) {
+    finalBody = binary;
+  } else if (body !== undefined) {
+    finalHeaders['Content-Type'] = 'application/json';
+    finalBody = JSON.stringify(body);
+  }
+  const response = await fetch(`${API}${path}`, {
+    method,
+    headers: finalHeaders,
+    body: finalBody,
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = null;
+  }
+  return {
+    status: response.status,
+    json,
+    text,
+    data: json?.data,
+    error: json?.error,
+  };
+}
+
+function stamp() {
+  return `${Date.now()}${Math.floor(Math.random() * 1000)}`;
+}
+
+async function uploadImage(token, kind, id) {
+  const bytes = COVER_PNG;
+  const fileName = `${kind}-${id}.png`;
+  const ticket = await api('/api/assets/direct-upload-tickets', {
+    method: 'POST',
+    token,
+    body: {
+      legacyPrefix: 'generated-character-drafts',
+      pathSegments: ['game-distribution', kind, id],
+      fileName,
+      contentType: 'image/png',
+      access: 'private',
+      maxSizeBytes: bytes.length,
+      metadata: { asset_kind: `game_distribution_${kind}` },
+    },
+  });
+  if (ticket.status !== 200) {
+    throw new Error(
+      `创建直传凭证失败 ${ticket.status} ${ticket.text.slice(0, 300)}`,
+    );
+  }
+  const upload = ticket.data.upload;
+  const form = new FormData();
+  for (const [key, value] of Object.entries(upload.formFields ?? {})) {
+    if (value !== null && value !== undefined) form.append(key, String(value));
+  }
+  form.append('file', new Blob([bytes], { type: 'image/png' }), fileName);
+  const put = await fetch(upload.host, { method: 'POST', body: form });
+  if (!put.ok) {
+    throw new Error(`直传对象存储失败 ${put.status}`);
+  }
+  const confirm = await api('/api/assets/objects/confirm', {
+    method: 'POST',
+    token,
+    body: {
+      bucket: upload.bucket,
+      objectKey: upload.objectKey,
+      contentType: 'image/png',
+      contentLength: bytes.length,
+      assetKind: `game_distribution_${kind}`,
+      accessPolicy: 'private',
+      entityId: `game-distribution-${kind}`,
+    },
+  });
+  if (confirm.status !== 200) {
+    throw new Error(
+      `confirm 失败 ${confirm.status} ${confirm.text.slice(0, 300)}`,
+    );
+  }
+  return {
+    assetObjectId: confirm.data.assetObject.assetObjectId,
+    objectKey: confirm.data.assetObject.objectKey,
+  };
+}
+
+function gameMetadata(overrides = {}) {
+  return {
+    title: `分发媒体验证 ${stamp().slice(-6)}`,
+    summary: '真实链路验证封面与截图冻结',
+    description: 'E2E：真实素材直传 + 冻结 + 审核生效',
+    category: '益智',
+    tags: ['E2E'],
+    deviceSupport: { desktop: true, mobile: true, touch: true },
+    inputModes: ['keyboard', 'mouse', 'touch'],
+    orientation: 'responsive',
+    ...overrides,
+  };
+}
+
+async function buildZip() {
+  const zip = new JSZip();
+  zip.file(
+    'index.html',
+    '<!doctype html><html><head><meta charset="utf-8"><title>E2E 媒体验证</title><script src="assets/app.js"></script></head><body><h1>E2E-MEDIA-OK</h1></body></html>',
+  );
+  zip.file('assets/app.js', 'document.documentElement.dataset.e2e="media";');
+  const bytes = await zip.generateAsync({ type: 'uint8array' });
+  return Buffer.from(bytes);
+}
+
+async function main() {
+  // 1. 作者注册
+  const phone = `137${String(Date.now()).slice(-8)}`;
+  const entry = await api('/api/auth/entry', {
+    method: 'POST',
+    body: { purePhoneNumber: phone, password: 'GenE2e123!' },
+  });
+  check(
+    '作者注册拿到 token',
+    entry.status === 200 && Boolean(entry.data?.token),
+    `status=${entry.status}`,
+  );
+  const author = entry.data.token;
+  const otherEntry = await api('/api/auth/entry', {
+    method: 'POST',
+    body: {
+      purePhoneNumber: `138${String(Date.now() + 7).slice(-8)}`,
+      password: 'GenE2e123!',
+    },
+  });
+  const another = otherEntry.data.token;
+
+  // 2. 真实素材直传
+  const id = stamp();
+  const cover = await uploadImage(author, 'cover', id);
+  const shot1 = await uploadImage(author, 'screenshot', `${id}-1`);
+  const shot2 = await uploadImage(author, 'screenshot', `${id}-2`);
+  check(
+    '封面素材直传并 confirm',
+    Boolean(cover.assetObjectId) &&
+      cover.objectKey.includes('game-distribution/cover'),
+    cover.objectKey,
+  );
+  check(
+    '截图素材直传并 confirm',
+    Boolean(shot1.assetObjectId) && Boolean(shot2.assetObjectId),
+  );
+
+  // 3. 服务端校验：缺封面 / 超 6 张 / 素材不存在
+  const noCover = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-nocover-${id}` },
+    body: gameMetadata({ title: '缺封面验证' }),
+  });
+  check(
+    '缺少封面被拒（400）',
+    noCover.status === 400,
+    `status=${noCover.status} msg=${noCover.error?.message ?? ''}`,
+  );
+
+  const tooMany = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-many-${id}` },
+    body: gameMetadata({
+      coverAssetId: cover.assetObjectId,
+      screenshots: Array.from({ length: 7 }, () => shot1.assetObjectId),
+    }),
+  });
+  check(
+    '截图超过 6 张被拒（400）',
+    tooMany.status === 400,
+    `status=${tooMany.status} msg=${tooMany.error?.message ?? ''}`,
+  );
+
+  const ghost = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-ghost-${id}` },
+    body: gameMetadata({ coverAssetId: 'asset_not_exists', screenshots: [] }),
+  });
+  check(
+    '不存在的封面素材被拒',
+    ghost.status === 400,
+    `status=${ghost.status} msg=${ghost.error?.message ?? ''}`,
+  );
+
+  // 4. 创建游戏 + 版本（冻结资料）
+  const metadata = gameMetadata({
+    title: `分发媒体验证 ${id.slice(-6)}`,
+    coverAssetId: cover.assetObjectId,
+    screenshots: [shot1.assetObjectId, shot2.assetObjectId],
+  });
+  const created = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-game-${id}` },
+    body: metadata,
+  });
+  check(
+    '创建游戏成功',
+    created.status === 200 && Boolean(created.data?.id),
+    `status=${created.status} ${created.text.slice(0, 200)}`,
+  );
+  const gameId = created.data.id;
+
+  // 版本级校验用例需要真实的游戏行：用合法素材建一个只用于负面校验的游戏。
+  const ghostGame = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-ghostgame-${id}` },
+    body: gameMetadata({
+      title: `版本级素材校验 ${id.slice(-6)}`,
+      coverAssetId: cover.assetObjectId,
+      screenshots: [],
+    }),
+  });
+  const gameIdForGhost = ghostGame.data?.id ?? gameId;
+
+  const ghostVersion = await api(
+    `/api/game-distribution/games/${gameIdForGhost}/versions`,
+    {
+      method: 'POST',
+      token: author,
+      headers: { 'Idempotency-Key': `e2e-ghost-version-${id}` },
+      body: {
+        packageSha256: 'a'.repeat(64),
+        packageBytes: 1024,
+        packageFileCount: 1,
+        packageEntryPath: 'index.html',
+        gameMetadata: gameMetadata({
+          coverAssetId: 'asset_not_exists',
+          screenshots: [],
+        }),
+      },
+    },
+  );
+  check(
+    '版本冻结时同样拒绝不存在的素材',
+    ghostVersion.status >= 400,
+    `status=${ghostVersion.status}`,
+  );
+
+  const zipBytes = await buildZip();
+  const crypto = await import('node:crypto');
+  const sha256 = crypto.createHash('sha256').update(zipBytes).digest('hex');
+  const version = await api(`/api/game-distribution/games/${gameId}/versions`, {
+    method: 'POST',
+    token: author,
+    headers: { 'Idempotency-Key': `e2e-version-${id}` },
+    body: {
+      packageSha256: sha256,
+      packageBytes: zipBytes.length,
+      packageFileCount: 2,
+      packageEntryPath: 'index.html',
+      gameMetadata: metadata,
+    },
+  });
+  check(
+    '创建版本成功',
+    version.status === 200 && Boolean(version.data?.versionId),
+    `status=${version.status} ${version.text.slice(0, 200)}`,
+  );
+  const versionId = version.data.versionId;
+
+  const uploadPackage = await api(
+    `/api/game-distribution/versions/${versionId}/package`,
+    {
+      method: 'PUT',
+      token: author,
+      headers: {
+        'Idempotency-Key': `e2e-upload-${id}`,
+        'Content-Type': 'application/zip',
+      },
+      binary: zipBytes,
+    },
+  );
+  check(
+    '上传发行包成功',
+    uploadPackage.status === 200 && uploadPackage.data?.status === 'uploaded',
+    `status=${uploadPackage.status}`,
+  );
+
+  const submitted = await api(
+    `/api/game-distribution/versions/${versionId}/submit`,
+    {
+      method: 'POST',
+      token: author,
+      headers: { 'Idempotency-Key': `e2e-submit-${id}` },
+      body: {
+        expectedPublicationRevision: created.data.publicationRevision ?? 0,
+      },
+    },
+  );
+  check(
+    '送审成功（202 + pending_review）',
+    submitted.status === 202 &&
+      submitted.data?.version?.status === 'pending_review',
+    `status=${submitted.status} ${submitted.text.slice(0, 200)}`,
+  );
+
+  // 版本冻结前仍要复核素材归属：换成别人的封面素材必须被拒。
+  const foreign = await api('/api/game-distribution/games', {
+    method: 'POST',
+    token: another,
+    headers: { 'Idempotency-Key': `e2e-foreign-game-${id}` },
+    body: gameMetadata({
+      title: `他人素材验证 ${id.slice(-6)}`,
+      coverAssetId: cover.assetObjectId,
+      screenshots: [],
+    }),
+  });
+  check(
+    '借用他人封面素材创建游戏被拒',
+    foreign.status === 403 || foreign.status === 400,
+    `status=${foreign.status} msg=${foreign.error?.message ?? ''}`,
+  );
+
+  // 5. 作者回读版本：冻结资料带回素材 ID
+  const readback = await api(`/api/game-distribution/versions/${versionId}`, {
+    token: author,
+  });
+  const frozen = readback.data?.version?.frozenMetadata;
+  check(
+    '作者回读拿到 frozenMetadata',
+    Boolean(frozen),
+    `status=${readback.status}`,
+  );
+  check(
+    '冻结资料保留封面素材 ID',
+    frozen?.coverAssetId === cover.assetObjectId,
+    String(frozen?.coverAssetId),
+  );
+  check(
+    '冻结资料保留截图素材 ID 顺序',
+    Array.isArray(frozen?.screenshots) &&
+      frozen.screenshots[0]?.assetId === shot1.assetObjectId &&
+      frozen.screenshots[1]?.assetId === shot2.assetObjectId,
+  );
+  check(
+    '冻结资料对象键由服务端派生',
+    frozen?.coverObjectKey === cover.objectKey,
+    String(frozen?.coverObjectKey),
+  );
+
+  // 6. 待审期间：公开目录不可见，匿名读封面被拒
+  const catalogBefore = await api('/api/game-distribution/games');
+  check(
+    '待审期间公开目录不含该游戏',
+    !(catalogBefore.data?.games ?? []).some((game) => game.id === gameId),
+  );
+  const readBefore = await api(
+    `/api/assets/read-url?objectKey=${encodeURIComponent(cover.objectKey)}`,
+  );
+  check(
+    '未公开游戏的封面没有匿名读授权',
+    readBefore.status >= 400,
+    `status=${readBefore.status}`,
+  );
+
+  // 7. 管理员审核通过（本地非生产允许回环 http 入口）
+  const adminLogin = await api('/admin/api/login', {
+    method: 'POST',
+    body: { username: ADMIN_USER, password: ADMIN_PASSWORD },
+  });
+  check(
+    '管理员登录成功',
+    adminLogin.status === 200 &&
+      Boolean(adminLogin.data?.token ?? adminLogin.data?.accessToken),
+    `status=${adminLogin.status}`,
+  );
+  const admin = adminLogin.data?.token ?? adminLogin.data?.accessToken;
+
+  const approved = await api(
+    `/admin/api/game-distribution/versions/${versionId}/review`,
+    {
+      method: 'POST',
+      token: admin,
+      headers: { 'Idempotency-Key': `e2e-approve-${id}` },
+      body: {
+        decision: 'approve',
+        expectedPublicationRevision: readback.data.version.publicationRevision,
+        entryUrl: `${API}`,
+      },
+    },
+  );
+  check(
+    '管理员审核通过',
+    approved.status === 200,
+    `status=${approved.status} ${approved.text.slice(0, 250)}`,
+  );
+
+  // 8. 公开目录：封面/截图对象键生效
+  const catalogAfter = await api('/api/game-distribution/games');
+  const publishedGame = (catalogAfter.data?.games ?? []).find(
+    (game) => game.id === gameId,
+  );
+  check('公开目录返回该游戏', Boolean(publishedGame));
+  check(
+    '公开投影带封面对象键',
+    publishedGame?.coverObjectKey === cover.objectKey,
+    String(publishedGame?.coverObjectKey),
+  );
+  check(
+    '公开投影带截图对象键',
+    Array.isArray(publishedGame?.screenshots) &&
+      publishedGame.screenshots[0] === shot1.objectKey,
+    JSON.stringify(publishedGame?.screenshots ?? []),
+  );
+  check(
+    '公开投影不泄露素材 ID',
+    !JSON.stringify(publishedGame ?? {}).includes(cover.assetObjectId),
+  );
+
+  // 9. 匿名读授权：封面与截图都能换签名地址
+  const coverRead = await api(
+    `/api/assets/read-url?objectKey=${encodeURIComponent(cover.objectKey)}`,
+  );
+  check(
+    '匿名可读已公开游戏封面',
+    coverRead.status === 200 &&
+      Boolean(coverRead.data?.read?.signedUrl ?? coverRead.data?.signedUrl),
+    `status=${coverRead.status}`,
+  );
+  const shotRead = await api(
+    `/api/assets/read-url?objectKey=${encodeURIComponent(shot1.objectKey)}`,
+  );
+  check(
+    '匿名可读已公开游戏截图',
+    shotRead.status === 200 &&
+      Boolean(shotRead.data?.read?.signedUrl ?? shotRead.data?.signedUrl),
+    `status=${shotRead.status}`,
+  );
+
+  // 10. 发行网关可直接玩
+  const release = await fetch(
+    `${API}/api/game-distribution/releases/${gameId}/index.html`,
+  );
+  const releaseBody = await release.text();
+  check(
+    '发行网关返回游戏入口',
+    release.status === 200 && releaseBody.includes('E2E-MEDIA-OK'),
+    `status=${release.status}`,
+  );
+  check(
+    '发行入口带 nosniff',
+    release.headers.get('x-content-type-options') === 'nosniff',
+  );
+  const releaseAsset = await fetch(
+    `${API}/api/game-distribution/releases/${gameId}/assets/app.js`,
+  );
+  check(
+    '发行网关返回包内资源',
+    releaseAsset.status === 200,
+    `status=${releaseAsset.status}`,
+  );
+
+  console.log(`\n结果：${failures === 0 ? '全部通过' : `${failures} 项失败`}`);
+  process.exitCode = failures === 0 ? 0 : 1;
+}
+
+main().catch((error) => {
+  console.error('E2E 脚本异常：', error);
+  process.exitCode = 1;
+});
diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs
index 220d5f0ee..5c0f8af18 100644
--- a/scripts/check-native-shells.mjs
+++ b/scripts/check-native-shells.mjs
@@ -2602,12 +2602,13 @@ function assertAiGameCreatorShellUserDevBoundary() {
         { url: 'https://*/api/*' },
         { url: 'http://localhost:*/*' },
         { url: 'http://127.0.0.1:*/*' },
+        { url: 'https://*.aliyuncs.com/*' },
       ])
   ) {
     throw new Error(
-      // 更新清单与安装包下载已改由 tauri-plugin-updater 在原生侧完成，
-      // 不再需要为 webview 的 http 插件放行 OSS 域名。
-      'AI game creator native HTTP scope must match the release, dev, custom HTTPS, and loopback API boundary',
+      // 更新清单与安装包下载由 tauri-plugin-updater 在原生侧完成；
+      // 封面与截图仍通过 webview 的 http 插件向凭证指定的 OSS 地址直传。
+      'AI game creator native HTTP scope must match the release, dev, custom HTTPS, loopback API, and OSS media upload boundary',
     );
   }
 
@@ -2647,7 +2648,7 @@ function assertAiGameCreatorShellUserDevBoundary() {
   }
   for (const snippet of [
     "await invoke<LocalPreviewStatus>(\n        'activate_local_game_preview'",
-    '已切换到客户端运行视图',
+    '已载入客户端运行视图',
   ]) {
     if (!sourceIncludesSnippet(aiGameCreatorShellAppSource, snippet)) {
       throw new Error(
@@ -2665,6 +2666,14 @@ function assertAiGameCreatorShellUserDevBoundary() {
       );
     }
   }
+  /*
+   * 预览**不自动**开系统浏览器：启动与切换运行视图只走内置画面，两条老路必须一直挡着
+   * （App.tsx 里的 `openPreviewInExternalBrowser` / 前端直调 `open_local_game_preview` /
+   * Rust 侧 `.open_url(`）。
+   *
+   * 用户主动点「在浏览器打开」是另一回事：它走 opener 插件的 `openUrl`，入口只有顶栏那一枚
+   * 按钮（见下面那条正向断言）。别把这条负向守卫推广成「任何地方都不许出现 openUrl」。
+   */
   if (
     aiGameCreatorShellAppSource.includes('openPreviewInExternalBrowser') ||
     aiGameCreatorShellAppSource.includes('open_local_game_preview') ||
@@ -2674,6 +2683,31 @@ function assertAiGameCreatorShellUserDevBoundary() {
       'AI game creator preview must not invoke the external browser',
     );
   }
+  for (const snippet of [
+    "'@tauri-apps/plugin-opener'",
+    '在浏览器打开',
+    'await openUrl(embeddedPreviewUrl)',
+  ]) {
+    if (
+      !sourceIncludesSnippet(aiGameCreatorProjectDevelopmentSource, snippet)
+    ) {
+      throw new Error(
+        `AI game creator in-browser preview entry drifted: missing ${snippet}`,
+      );
+    }
+  }
+  /*
+   * 上面那条负向守卫只盯着 App.tsx 里的两条老路，而真正的浏览器出口在运行页视图里。
+   * 这里再补一条「调用点只有一个」的判据：视图里冒出第二个 `openUrl(`（自动跳浏览器、
+   * 或者拿它去开任意地址）时必须先显式改这条守卫，而不是顺手加一行。
+   */
+  const openUrlCallCount =
+    aiGameCreatorProjectDevelopmentSource.split('openUrl(').length - 1;
+  if (openUrlCallCount !== 1) {
+    throw new Error(
+      `AI game creator must keep exactly one user-clicked browser-open call in the run view (found ${openUrlCallCount})`,
+    );
+  }
   if (
     aiGameCreatorShellTauriSource.includes('fn open_developer_window(') ||
     aiGameCreatorShellTauriSource.includes(
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index 83270f8f7..a25f85cc3 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -54,6 +54,17 @@ const checks = [
     reason:
       'Copy Artifact Production 模式下，AGC 发号 Job 还必须授权手动发布管线读取总号，否则用户触发的手动发布会停在 copyArtifacts（SYSTEM 定时构建不受影响）。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.agc-global-version-issue',
+    includes: 'Genarrative-Scheduled-Release-Trigger',
+    reason:
+      'Copy Artifact Production 模式下，AGC 发号 Job 必须授权每日 release 调度器读取总号。',
+  },
+  {
+    file: 'jenkins/agc-global-version-issue-job-config.xml',
+    includes: '<string>release-unified</string>',
+    reason: 'AGC 发号 Job 配置必须保留 release 调度的统一发号用途标签。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-stdb-module-build',
     includes: 'npm run check:rustfmt',
@@ -7733,6 +7744,14 @@ const scheduledRevisionTriggerJobConfig = readFileSync(
   'jenkins/scheduled-revision-trigger-job-config.xml',
   'utf8',
 );
+const scheduledReleaseTriggerContent = readFileSync(
+  'jenkins/Jenkinsfile.scheduled-release-trigger',
+  'utf8',
+);
+const scheduledReleaseTriggerJobConfig = readFileSync(
+  'jenkins/scheduled-release-trigger-job-config.xml',
+  'utf8',
+);
 
 // 定时与版本比较统一收敛到调度管线，两个下游流水线不得再自带触发器。
 for (const [file, content] of [
@@ -7742,7 +7761,7 @@ for (const [file, content] of [
   if (/\btriggers\s*\{/u.test(content) || content.includes('cron(')) {
     failed = true;
     console.error(
-      `[check:production-ops] ${file} 不得自带定时触发器；版本检查与触发必须由 Genarrative-Scheduled-Revision-Trigger 统一负责。`,
+      `[check:production-ops] ${file} 不得自带定时触发器；版本检查与触发必须由两条定时调度管线统一负责。`,
     );
   }
 }
@@ -7883,6 +7902,123 @@ if (
     '[check:production-ops] scheduled-revision-trigger Job 必须指向调度 Jenkinsfile、使用本机 Git 入口与既有 SSH 凭据，并把定时器留在 Jenkinsfile。',
   );
 }
+
+for (const [snippet, reason] of [
+  ["cron('0 4 * * *')", 'release 调度器必须在每天 04:00 检查远端版本'],
+  ['disableConcurrentBuilds()', '必须禁止 release 调度器并发触发'],
+  ['skipDefaultCheckout(true)', 'release 调度器不得依赖本地 SCM 工作区'],
+  ['git ls-remote', 'release 调度器必须直接从远端解析分支版本'],
+  [
+    "FULL_BUILD_JOB_NAME = 'Genarrative-Full-Build-And-Deploy'",
+    '必须声明 release Full Build 目标 Job',
+  ],
+  [
+    "AGC_WINDOWS_BUILD_JOB_NAME = 'Genarrative-Agc-Windows-Build'",
+    '必须声明 AGC Windows release 构建目标 Job',
+  ],
+  [
+    "AGC_MACOS_BUILD_JOB_NAME = 'Genarrative-Agc-MacOS-Build'",
+    '必须声明 AGC macOS release 构建目标 Job',
+  ],
+  [
+    "FULL_REVISION_STATE_FILE = '.jenkins-last-release-full-revision'",
+    '必须独立记录 Full Build 成功 revision',
+  ],
+  [
+    "AGC_REVISION_STATE_FILE = '.jenkins-last-release-agc-revision'",
+    '必须独立记录 AGC 双平台成功 revision',
+  ],
+  ['full=changed', 'release 调度器必须计算服务端 Full Build scope'],
+  [
+    "env.FULL_BUILD_SCOPE = readScope('full')",
+    'release 调度器必须解析 Full Build scope',
+  ],
+  [
+    "string(name: 'AGC_CHANNEL', value: 'release-unified')",
+    'release 调度器必须先通过发号 Job 获取统一总版本号',
+  ],
+  [
+    "string(name: 'AGC_UPDATE_CHANNEL', value: 'release')",
+    'release 调度器必须把 Windows 与 macOS 都发到 release 分区',
+  ],
+  [
+    "string(name: 'DEPLOY_TARGET', value: 'release')",
+    'release Full Build 必须固定部署到 release',
+  ],
+  [
+    "booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', value: true)",
+    'release Full Build 必须确认使用独立 release 部署 agent',
+  ],
+  [
+    "string(name: 'DATABASE_BACKUP_MODE', value: params.DATABASE_BACKUP_MODE)",
+    'release Full Build 必须显式透传数据库备份策略',
+  ],
+  [
+    "string(name: 'STDB_API_ROLLOUT_MODE', value: params.STDB_API_ROLLOUT_MODE)",
+    'release Full Build 必须显式透传 Stdb/API rollout 策略',
+  ],
+  [
+    'def runDownstream = { String jobName, List jobParameters, int timeoutMinutes ->',
+    'release 调度器必须统一等待并收集三个下游结果',
+  ],
+  [
+    'build job: jobName,\n                  wait: true,\n                  propagate: false,',
+    'release 下游必须等待完成并保留每个 Job 的结果',
+  ],
+  [
+    'branches[env.FULL_BUILD_JOB_NAME] = {',
+    'release 调度器必须触发 Full Build',
+  ],
+  [
+    'branches[env.AGC_WINDOWS_BUILD_JOB_NAME] = {',
+    'release 调度器必须触发 AGC Windows release 构建',
+  ],
+  [
+    'branches[env.AGC_MACOS_BUILD_JOB_NAME] = {',
+    'release 调度器必须触发 AGC macOS release 构建',
+  ],
+  [
+    "booleanParam(name: 'SKIP_IF_SUPERSEDED', value: true)",
+    'release 调度器必须让 macOS 节点恢复后跳过过期排队构建',
+  ],
+  [
+    'if (fullSucceeded) {',
+    '只有 Full Build 成功后才能推进 Full Build revision',
+  ],
+  ['if (agcSucceeded) {', '只有 AGC 双平台成功后才能推进 AGC revision'],
+  [
+    'error("release 下游未全部成功: ${summary}")',
+    '任一 release 下游失败时调度器必须失败',
+  ],
+]) {
+  if (!scheduledReleaseTriggerContent.includes(snippet)) {
+    failed = true;
+    console.error(`[check:production-ops] release 调度管线${reason}。`);
+  }
+}
+if (scheduledReleaseTriggerContent.includes('wait: false')) {
+  failed = true;
+  console.error(
+    '[check:production-ops] release 调度管线不得 fire-and-forget，必须等待并汇总 Full Build 与 AGC 结果。',
+  );
+}
+if (
+  !scheduledReleaseTriggerJobConfig.includes(
+    '<scriptPath>jenkins/Jenkinsfile.scheduled-release-trigger</scriptPath>',
+  ) ||
+  !scheduledReleaseTriggerJobConfig.includes(
+    'ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git',
+  ) ||
+  !scheduledReleaseTriggerJobConfig.includes(
+    '<credentialsId>genarrative-local-gitea-ssh</credentialsId>',
+  ) ||
+  !scheduledReleaseTriggerJobConfig.includes('<triggers/>')
+) {
+  failed = true;
+  console.error(
+    '[check:production-ops] scheduled-release-trigger Job 必须指向 release 调度 Jenkinsfile、使用本机 Git 入口与既有 SSH 凭据，并把定时器留在 Jenkinsfile。',
+  );
+}
 if (
   !fullPipelineContent.includes(
     "string(name: 'COMMIT_HASH', value: env.SOURCE_COMMIT)",
diff --git a/scripts/check-release-origin-config.mjs b/scripts/check-release-origin-config.mjs
new file mode 100644
index 000000000..7a3164ae6
--- /dev/null
+++ b/scripts/check-release-origin-config.mjs
@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * 游戏发行来源配置门禁。
+ *
+ * 逐条校验 `deploy/nginx/genarrative-release-origin.conf`：
+ *   1) 每游戏独立 origin 的按主机映射（命名捕获 `game_id` + 发行网关前缀）；
+ *   2) 只暴露发行网关，不代理平台 API / 后台 / SPA；
+ *   3) 发行来源不使用 Cookie（边缘 403 + 转发前清空）；
+ *   4) 响应头策略仍由 api-server 发行网关负责（源码级交叉检查）。
+ * 只要本机存在 nginx 与 openssl，还会用自签通配证书渲染一份临时配置执行
+ * `nginx -t`，把语法与指令上下文一起验证掉。
+ */
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(scriptDir, '..');
+const templatePath = join(
+  repoRoot,
+  'deploy/nginx/genarrative-release-origin.conf',
+);
+const gatewayPath = join(
+  repoRoot,
+  'server-rs/crates/api-server/src/modules/game_distribution.rs',
+);
+
+const failures = [];
+const notes = [];
+
+function fail(message) {
+  failures.push(message);
+}
+
+function normalize(source) {
+  return source.replace(/\s+/gu, ' ');
+}
+
+function requireSnippet(source, snippet, message) {
+  if (!normalize(source).includes(normalize(snippet))) {
+    fail(message);
+  }
+}
+
+function main() {
+  if (!existsSync(templatePath)) {
+    fail(`缺少发行来源模板：${templatePath}`);
+    return;
+  }
+  const template = readFileSync(templatePath, 'utf8');
+
+  requireSnippet(
+    template,
+    'server_name ~^(?<game_id>[a-z0-9_]+)\\.games\\.example\\.com$;',
+    '发行来源必须用命名捕获 game_id 的子域匹配（每游戏独立 origin）',
+  );
+  requireSnippet(
+    template,
+    'ssl_certificate /etc/letsencrypt/live/games.example.com/fullchain.pem;',
+    '发行来源必须使用通配 TLS 证书',
+  );
+  requireSnippet(
+    template,
+    'if ($http_cookie) { return 403; }',
+    '发行来源必须拒绝携带平台 Cookie 的请求',
+  );
+  requireSnippet(
+    template,
+    'proxy_set_header Cookie "";',
+    '发行来源转发前必须清空 Cookie',
+  );
+  requireSnippet(
+    template,
+    'proxy_pass http://genarrative_release_api/api/game-distribution/releases/$game_id$request_uri;',
+    '发行来源必须按 game_id 映射到发行网关前缀',
+  );
+  requireSnippet(
+    template,
+    'location /.well-known/acme-challenge/',
+    '发行来源必须保留 ACME challenge 路径',
+  );
+
+  requireSnippet(
+    template,
+    'location = / {',
+    '发行来源必须显式把子域根路径映射为该游戏的 index.html',
+  );
+  requireSnippet(
+    template,
+    'proxy_pass http://genarrative_release_api/api/game-distribution/releases/$game_id/index.html;',
+    '子域根路径必须映射到该游戏的 index.html',
+  );
+  const proxyPassCount = (template.match(/proxy_pass\s/gu) ?? []).length;
+  if (proxyPassCount !== 2) {
+    fail(
+      `发行来源只应存在两条 proxy_pass（子域根路径与发行网关前缀），实际 ${proxyPassCount} 条`,
+    );
+  }
+  const cookieStripCount = (
+    template.match(/proxy_set_header Cookie "";/gu) ?? []
+  ).length;
+  if (cookieStripCount !== 2) {
+    fail(`每条发行来源代理都必须清空 Cookie，实际 ${cookieStripCount} 处`);
+  }
+  const gatewayPrefixCount = (
+    template.match(/api\/game-distribution\/releases\/\$game_id/gu) ?? []
+  ).length;
+  if (gatewayPrefixCount !== 2) {
+    fail(`发行来源代理必须都映射到发行网关前缀，实际 ${gatewayPrefixCount} 处`);
+  }
+  for (const forbidden of [
+    '/api/auth',
+    '/api/profile',
+    '/admin/api',
+    '/api/game-distribution/games',
+    '/api/game-distribution/versions',
+  ]) {
+    if (template.includes(forbidden)) {
+      fail(`发行来源不得代理平台命名空间：${forbidden}`);
+    }
+  }
+
+  if (!existsSync(gatewayPath)) {
+    fail(`缺少发行网关源码：${gatewayPath}`);
+  } else {
+    const gateway = readFileSync(gatewayPath, 'utf8');
+    for (const [snippet, message] of [
+      [
+        'header::X_CONTENT_TYPE_OPTIONS',
+        '发行网关必须继续设置 X-Content-Type-Options',
+      ],
+      [
+        'HeaderName::from_static("cross-origin-resource-policy")',
+        '发行网关必须继续设置 CORP',
+      ],
+      [
+        'HeaderValue::from_static("cross-origin")',
+        'CORP 必须是 cross-origin（opaque sandbox 才能加载自有脚本）',
+      ],
+      [
+        'header::ACCESS_CONTROL_ALLOW_ORIGIN',
+        '发行网关必须继续设置无凭据 CORS',
+      ],
+      ['header::CONTENT_SECURITY_POLICY', '发行网关必须继续为 HTML 设置 CSP'],
+      ['StatusCode::FORBIDDEN', '发行网关必须继续拒绝携带 Cookie 的请求'],
+    ]) {
+      if (!gateway.includes(snippet)) {
+        fail(message);
+      }
+    }
+  }
+
+  validateWithNginx(template);
+
+  if (failures.length > 0) {
+    console.error('[check:release-origin-config] FAILED');
+    for (const message of failures) {
+      console.error(`- ${message}`);
+    }
+    process.exit(1);
+  }
+  for (const note of notes) {
+    console.log(`[check:release-origin-config] ${note}`);
+  }
+  console.log(
+    '[check:release-origin-config] OK（发行来源模板、网关响应头策略与 nginx 语法一致）',
+  );
+}
+
+function binaryExists(binary) {
+  try {
+    execFileSync('sh', ['-c', `command -v ${binary}`], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateWithNginx(template) {
+  if (!binaryExists('nginx')) {
+    notes.push('未找到 nginx，跳过渲染后的 nginx -t');
+    return;
+  }
+  const workDir = mkdtempSync(join(tmpdir(), 'genarrative-release-origin-'));
+  try {
+    const certPath = join(workDir, 'wildcard.crt');
+    const keyPath = join(workDir, 'wildcard.key');
+    if (binaryExists('openssl')) {
+      execFileSync(
+        'openssl',
+        [
+          'req',
+          '-x509',
+          '-newkey',
+          'rsa:2048',
+          '-nodes',
+          '-days',
+          '1',
+          '-subj',
+          '/CN=games.example.com',
+          '-addext',
+          'subjectAltName=DNS:*.games.example.com,DNS:games.example.com',
+          '-keyout',
+          keyPath,
+          '-out',
+          certPath,
+        ],
+        { stdio: 'ignore' },
+      );
+    } else {
+      notes.push('未找到 openssl，跳过渲染后的 nginx -t');
+      return;
+    }
+    const rendered = template
+      .replace(
+        '/etc/letsencrypt/live/games.example.com/fullchain.pem',
+        certPath,
+      )
+      .replace('/etc/letsencrypt/live/games.example.com/privkey.pem', keyPath)
+      .replace(
+        /\/var\/log\/nginx\/(genarrative-release\.[a-z]+\.log)/gu,
+        join(workDir, '$1'),
+      )
+      // 非 root 环境无法绑定 80/443；语法检查用高位端口，不改生产模板本身。
+      .replace('listen 80;', 'listen 18080;')
+      .replace('listen 443 ssl http2;', 'listen 18443 ssl http2;');
+    const renderedPath = join(workDir, 'release-origin.conf');
+    writeFileSync(renderedPath, rendered);
+    const wrapperPath = join(workDir, 'nginx.conf');
+    writeFileSync(
+      wrapperPath,
+      [
+        `pid ${join(workDir, 'nginx.pid')};`,
+        `error_log ${join(workDir, 'error.log')} warn;`,
+        'events { worker_connections 64; }',
+        'http {',
+        '    access_log off;',
+        '    client_body_temp_path ' + join(workDir, 'client-body') + ';',
+        '    proxy_temp_path ' + join(workDir, 'proxy') + ';',
+        '    fastcgi_temp_path ' + join(workDir, 'fastcgi') + ';',
+        '    uwsgi_temp_path ' + join(workDir, 'uwsgi') + ';',
+        '    scgi_temp_path ' + join(workDir, 'scgi') + ';',
+        `    include ${renderedPath};`,
+        '}',
+        '',
+      ].join('\n'),
+    );
+    try {
+      execFileSync('nginx', ['-t', '-c', wrapperPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      notes.push('渲染后的发行来源配置通过 nginx -t');
+    } catch (error) {
+      const stderr = error.stderr ? String(error.stderr) : '';
+      fail(
+        `渲染后的发行来源配置未通过 nginx -t：${stderr.trim() || error.message}`,
+      );
+    }
+  } finally {
+    rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+main();
diff --git a/scripts/ci-rust-cache.sh b/scripts/ci-rust-cache.sh
index 83d3108fa..c19459da9 100644
--- a/scripts/ci-rust-cache.sh
+++ b/scripts/ci-rust-cache.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# 仅消费镜像内的可信快照；所有写入留在当前容器的可写层。
+# 消费镜像内可信快照；写入留在任务容器，master push 可在任务结束后导出。
 set -euo pipefail
 
 cache_root="${GENARRATIVE_CI_RUST_CACHE_ROOT:-/opt/genarrative-ci/rust-cache}"
@@ -12,7 +12,7 @@ configure_local_cache() {
   for variable in ${!SCCACHE_@}; do unset "${variable}"; done
   export SCCACHE_CONF="${state}/config"
   export SCCACHE_DIR="${cache_root}/objects"
-  export SCCACHE_CACHE_SIZE=2G
+  export SCCACHE_CACHE_SIZE=4G
   export SCCACHE_SERVER_UDS="${state}/server.sock"
   # 单个不可缓存的链接/测试阶段可能超过一分钟；保持统计直到 report 显式停止。
   export SCCACHE_IDLE_TIMEOUT=0
@@ -22,7 +22,7 @@ configure_local_cache() {
 case "${1:-}" in
   prepare)
     : "${GITHUB_ENV:?GITHUB_ENV is required}"
-    printf 'RUSTC_WRAPPER=\nCARGO_BUILD_RUSTC_WRAPPER=\nGENARRATIVE_CI_RUST_CACHE_STATE=\n' >> "${GITHUB_ENV}"
+    printf 'RUSTC_WRAPPER=\nCARGO_BUILD_RUSTC_WRAPPER=\nGENARRATIVE_CI_RUST_CACHE_STATE=\nGENARRATIVE_CI_RUST_CACHE_EXPORT_READY=\n' >> "${GITHUB_ENV}"
     fallback() { printf '[rust-cache] mode=direct reason=%s\n' "$1"; exit 0; }
     [[ -x "${cache_binary}" && -d "${cache_root}/objects" && -f "${cache_root}/rustc.txt" && -f "${cache_root}/source-commit.txt" && -f "${cache_root}/workspace.txt" ]] \
       || fallback snapshot-unavailable
@@ -44,6 +44,10 @@ case "${1:-}" in
       fallback wrapper-probe-failed
     fi
     script_path="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/$(basename "${BASH_SOURCE[0]}")"
+    if [[ "${GITHUB_EVENT_NAME:-}" == push && "${GITHUB_REF:-}" == refs/heads/master ]]; then
+      # 只记 key/大小/时间，不读取对象正文；PR 没有扫描与打包开销。
+      python3 "$(dirname "${script_path}")/export-gitea-rust-cache.py" baseline "${state}/baseline.json"
+    fi
     # wrapper 路径也参与 Rust cache key；固定容器内路径，隔离由 job 容器保证。
     wrapper_path="${cache_root}/rustc-wrapper"
     printf '#!/usr/bin/env bash\nexec bash %q "$@"\n' "${script_path}" > "${wrapper_path}"
@@ -59,7 +63,13 @@ case "${1:-}" in
     if [[ -n "${state}" && -d "${state}" ]]; then
       configure_local_cache
       timeout --kill-after=2 5 "${cache_binary}" --show-stats || true
-      timeout --kill-after=2 5 "${cache_binary}" --stop-server >/dev/null 2>&1 || true
+      # 只有成功停服后才允许读取对象；失败不能把仍在写入的目录发布成完整快照。
+      if timeout --kill-after=2 15 "${cache_binary}" --stop-server >/dev/null 2>&1; then
+        if [[ "${GITHUB_EVENT_NAME:-}" == push && "${GITHUB_REF:-}" == refs/heads/master && ! -f "${state}/disabled" && -f "${state}/baseline.json" ]]; then
+          mv -- "${state}/baseline.json" "${cache_root}/export-baseline.json"
+          printf 'GENARRATIVE_CI_RUST_CACHE_EXPORT_READY=1\n' >> "${GITHUB_ENV}"
+        fi
+      fi
       rm -rf -- "${state}"
     else
       printf '[rust-cache] mode=direct\n'
diff --git a/scripts/ci-rust-cache.test.mjs b/scripts/ci-rust-cache.test.mjs
index 2b4f4f0ad..84ab6d9f9 100644
--- a/scripts/ci-rust-cache.test.mjs
+++ b/scripts/ci-rust-cache.test.mjs
@@ -35,7 +35,8 @@ function fixture(t) {
     `#!/bin/bash
 set -eu
 case "$1" in
-  --stop-server|--show-stats) exit 0 ;;
+  --stop-server) exit "\${STOP_FAILURE:-0}" ;;
+  --show-stats) exit 0 ;;
 esac
 if [[ "$*" == *-vV ]]; then
   [[ "\${PROBE_FAILURE:-}" != 1 ]] || exit 1
@@ -215,3 +216,25 @@ linuxTest('lost local cache state still invokes the real compiler', (t) => {
   const f = fixture(t);
   assert.equal(f.run(['/bin/bash', '-c', 'exit 43']).status, 43);
 });
+
+linuxTest('only a cleanly stopped master cache can export objects', (t) => {
+  const master = {
+    GITHUB_EVENT_NAME: 'push',
+    GITHUB_REF: 'refs/heads/master',
+  };
+  for (const stopFailure of ['0', '1']) {
+    const f = fixture(t);
+    const prepared = f.run(['prepare'], master);
+    assert.equal(prepared.status, 0, prepared.stderr);
+    const result = f.run(['report'], {
+      ...f.preparedEnv(),
+      ...master,
+      STOP_FAILURE: stopFailure,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(
+      f.preparedEnv().GENARRATIVE_CI_RUST_CACHE_EXPORT_READY,
+      stopFailure === '0' ? '1' : '',
+    );
+  }
+});
diff --git a/scripts/export-ci-npm-download-cache.mjs b/scripts/export-ci-npm-download-cache.mjs
new file mode 100644
index 000000000..de2f97bf1
--- /dev/null
+++ b/scripts/export-ci-npm-download-cache.mjs
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// 持久下载缓存可以保留旧版本；交付给 CI 镜像的快照只带当前 lock 已下载的包。
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+const [npmRoot, lockPath, source, destination] = process.argv.slice(2);
+if (!npmRoot || !lockPath || !source || !destination) {
+  throw new Error(
+    'usage: export-ci-npm-download-cache.mjs <npm-root> <lock> <source> <destination>',
+  );
+}
+const require = createRequire(path.resolve(npmRoot, 'package.json'));
+const cacache = require('cacache');
+const lock = JSON.parse(await fs.readFile(lockPath, 'utf8'));
+const integrities = new Set(
+  Object.values(lock.packages).flatMap((entry) =>
+    typeof entry.integrity === 'string' ? [entry.integrity] : [],
+  ),
+);
+let count = 0;
+for await (const entry of cacache.ls.stream(source)) {
+  if (!integrities.has(entry.integrity)) continue;
+  await pipeline(
+    cacache.get.stream(source, entry.key, { integrity: entry.integrity }),
+    cacache.put.stream(destination, entry.key, {
+      integrity: entry.integrity,
+      metadata: entry.metadata,
+    }),
+  );
+  count += 1;
+}
+console.log(
+  `[ci-image] exported ${count} npm cache entries for the current lock`,
+);
diff --git a/scripts/export-ci-npm-download-cache.test.mjs b/scripts/export-ci-npm-download-cache.test.mjs
new file mode 100644
index 000000000..9cfc4acfe
--- /dev/null
+++ b/scripts/export-ci-npm-download-cache.test.mjs
@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const npmRoot = [
+  path.resolve(path.dirname(process.execPath), 'node_modules/npm'),
+  path.resolve(path.dirname(process.execPath), '../lib/node_modules/npm'),
+  ...(process.env.npm_execpath
+    ? [path.resolve(path.dirname(process.env.npm_execpath), '..')]
+    : []),
+].find((root) => existsSync(path.join(root, 'node_modules/cacache')));
+assert.ok(npmRoot, 'tests require the cacache bundled with npm');
+const cacache = createRequire(path.join(npmRoot, 'package.json'))('cacache');
+const script = fileURLToPath(
+  new URL('./export-ci-npm-download-cache.mjs', import.meta.url),
+);
+
+async function fixture(t) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ci-npm-snapshot-'));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  const source = path.join(root, 'source');
+  const destination = path.join(root, 'destination');
+  const lock = path.join(root, 'package-lock.json');
+  const key =
+    'make-fetch-happen:request-cache:https://registry.npmjs.org/example/-/example-1.0.0.tgz';
+  const metadata = {
+    url: key.slice('make-fetch-happen:request-cache:'.length),
+  };
+  const integrity = String(
+    await cacache.put(source, key, 'current-package', { metadata }),
+  );
+  await cacache.put(source, 'old-package', 'unused-old-version');
+  await fs.writeFile(
+    lock,
+    JSON.stringify({ packages: { 'node_modules/example': { integrity } } }),
+  );
+  const run = () =>
+    spawnSync(process.execPath, [script, npmRoot, lock, source, destination], {
+      encoding: 'utf8',
+    });
+  return { source, destination, key, metadata, integrity, run };
+}
+
+test('exports only current lock content, preserving npm request metadata for offline use', async (t) => {
+  const f = await fixture(t);
+  const result = f.run();
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(Object.keys(await cacache.ls(f.destination)), [f.key]);
+  const output = await cacache.get(f.destination, f.key);
+  assert.equal(output.data.toString(), 'current-package');
+  assert.deepEqual(output.metadata, f.metadata);
+  // 输出是独立快照；移走持久缓存仍可使用，不依赖挂载、链接或旧 builder。
+  await fs.rm(f.source, { recursive: true });
+  assert.equal(
+    (await cacache.get(f.destination, f.key)).data.toString(),
+    'current-package',
+  );
+});
+
+test('rejects a corrupted cached package instead of publishing it', async (t) => {
+  const f = await fixture(t);
+  const digest = Buffer.from(f.integrity.split('-')[1], 'base64').toString(
+    'hex',
+  );
+  const contentPath = path.join(
+    f.source,
+    'content-v2',
+    'sha512',
+    digest.slice(0, 2),
+    digest.slice(2, 4),
+    digest.slice(4),
+  );
+  await fs.writeFile(contentPath, 'corrupted-package');
+  const result = f.run();
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /EINTEGRITY|EBADSIZE/);
+});
diff --git a/scripts/export-gitea-rust-cache.py b/scripts/export-gitea-rust-cache.py
new file mode 100644
index 000000000..3ad38e606
--- /dev/null
+++ b/scripts/export-gitea-rust-cache.py
@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""只把 master push 的任务内 sccache 对象导出为 Gitea Actions 产物。"""
+
+import base64
+from datetime import datetime, timedelta, timezone
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+import tarfile
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+
+
+MAX_OBJECT_BYTES = 4 * 1024**3
+CHUNK_BYTES = 8 * 1024**2
+JOBS = {
+    "ai-game-creator-shell-rust-lane-1",
+    "ai-game-creator-shell-rust-lane-2",
+    "ai-game-creator-shell-rust-smoke",
+    "ai-game-creator-shell-rust-crates",
+    "backend-tests",
+    "native-shell-tests",
+}
+
+
+def object_path(name):
+    parts = name.split("/")
+    return (
+        len(parts) == 3
+        and re.fullmatch(r"[a-f0-9]{64}", parts[2]) is not None
+        and parts[0] == parts[2][0]
+        and parts[1] == parts[2][1]
+    )
+
+
+class HashingReader:
+    def __init__(self, stream):
+        self.stream = stream
+        self.digest = hashlib.sha256()
+
+    def read(self, size=-1):
+        data = self.stream.read(size)
+        self.digest.update(data)
+        return data
+
+
+def scan_objects(root):
+    objects = root / "objects"
+    if objects.is_symlink() or not objects.is_dir():
+        raise ValueError("cache object directory is unavailable")
+    candidates = []
+    for directory, directories, files in os.walk(objects, followlinks=False):
+        directories[:] = [
+            name for name in directories if not (Path(directory) / name).is_symlink()
+        ]
+        for filename in files:
+            path = Path(directory) / filename
+            relative = path.relative_to(objects).as_posix()
+            info = path.lstat()
+            if object_path(relative) and stat.S_ISREG(info.st_mode):
+                candidates.append((path, relative, info))
+    return candidates
+
+
+def save_baseline(root, destination):
+    # sccache 命中会更新 mtime，不能把时间变化当成内容变化，否则又变成全量上传。
+    baseline = {
+        relative: {"size": info.st_size, "mtime_ns": info.st_mtime_ns}
+        for _, relative, info in scan_objects(root)
+    }
+    destination.write_text(json.dumps(baseline), encoding="utf-8")
+
+
+def pack_snapshot(root, destination, metadata, baseline, limit=MAX_OBJECT_BYTES):
+    """仅归档新 key；命中的已有对象只传递新近使用时间，不传输对象内容。"""
+    candidates = scan_objects(root)
+    candidates.sort(key=lambda item: (-item[2].st_mtime_ns, item[1]))
+    entries = []
+    touched = []
+    total = 0
+    with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_STORED) as bundle, \
+            bundle.open("snapshot.tar", "w", force_zip64=True) as tar_stream, \
+            tarfile.open(fileobj=tar_stream, mode="w|", format=tarfile.USTAR_FORMAT) as archive:
+        for path, relative, info in candidates:
+            previous = baseline.get(relative)
+            if previous is not None and previous["size"] == info.st_size:
+                if previous["mtime_ns"] != info.st_mtime_ns:
+                    touched.append({"path": "objects/" + relative, "mtime_ns": info.st_mtime_ns})
+                continue
+            if info.st_size <= 0 or total + info.st_size > limit:
+                continue
+            # report 已成功停止 daemon；打开后再核实对象，避免导出变化中的文件。
+            descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+            with os.fdopen(descriptor, "rb") as stream:
+                actual = os.fstat(stream.fileno())
+                if not stat.S_ISREG(actual.st_mode) or (
+                    actual.st_size, actual.st_mtime_ns, actual.st_ino
+                ) != (info.st_size, info.st_mtime_ns, info.st_ino):
+                    raise ValueError("cache object changed during export")
+                member = tarfile.TarInfo("objects/" + relative)
+                member.size = info.st_size
+                member.mode = 0o644
+                member.mtime = int(info.st_mtime)
+                reader = HashingReader(stream)
+                archive.addfile(member, reader)
+                entries.append({
+                    "path": member.name,
+                    "size": info.st_size,
+                    "sha256": reader.digest.hexdigest(),
+                    "mtime_ns": info.st_mtime_ns,
+                })
+                total += info.st_size
+        manifest = dict(metadata, schema=1, mode="delta", objects=entries, touched=touched)
+        data = json.dumps(manifest, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        member = tarfile.TarInfo("manifest.json")
+        member.size = len(data)
+        member.mode = 0o644
+        archive.addfile(member, io.BytesIO(data))
+    return len(entries), total
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        # runtime token 只允许发往明确配置的 Gitea 地址。
+        return None
+
+
+def request(method, url, token, data=None, headers=None, attempts=3):
+    opener = urllib.request.build_opener(NoRedirect())
+    for attempt in range(attempts):
+        req = urllib.request.Request(url, data=data, method=method, headers={
+            **({"Authorization": "Bearer " + token} if token else {}),
+            "Content-Type": "application/json",
+            **(headers or {}),
+        })
+        try:
+            with opener.open(req, timeout=120) as response:
+                body = response.read(1024 * 1024)
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as error:
+            if error.code not in (408, 429, 500, 502, 503, 504) or attempt == attempts - 1:
+                raise RuntimeError(f"artifact {method} failed: HTTP {error.code}") from None
+        except (urllib.error.URLError, TimeoutError, ConnectionError):
+            if attempt == attempts - 1:
+                raise RuntimeError(f"artifact {method} connection failed") from None
+        time.sleep(2 ** attempt)
+
+
+def artifact_base_url(env):
+    # .runner.address 可指向仅支持 RPC 的领取网关，不能用 GITHUB_SERVER_URL。
+    repository = env["GITHUB_REPOSITORY"]
+    clone_url = env["GENARRATIVE_GITEA_REPOSITORY_URL"]
+    suffix = "/" + repository + ".git"
+    parsed = urllib.parse.urlsplit(clone_url)
+    if (
+        parsed.scheme not in ("http", "https")
+        or not parsed.netloc
+        or parsed.username or parsed.password or parsed.query or parsed.fragment
+        or not parsed.path.endswith(suffix)
+    ):
+        raise ValueError("a credential-free HTTP Gitea repository URL is required")
+    return urllib.parse.urlunsplit((
+        parsed.scheme, parsed.netloc, parsed.path[:-len(suffix)], "", ""
+    ))
+
+
+def upload_snapshot(path, name, run_id, base_url, token):
+    """Gitea 1.26.4 原生 v4：只有完成全部块并校验 SHA256 后才发布。"""
+    producer_match = re.fullmatch(r"rust-cache-v1-([a-z0-9-]+)-attempt-(0|[1-9][0-9]*)", name)
+    if not producer_match or producer_match[1] not in JOBS:
+        raise ValueError("unexpected cache artifact name")
+    producer = f"{producer_match[1]}:{producer_match[2]}"
+    endpoint = f"{base_url}/twirp/github.actions.results.api.v1.ArtifactService"
+    # Gitea 从任务凭据确定 job，只要求请求中的 run ID 与任务所属 run 一致。
+    identity = {"workflowRunBackendId": str(run_id), "name": name}
+    created = request("POST", endpoint + "/CreateArtifact", token, json.dumps({
+        **identity, "version": 4,
+        # Gitea 将剩余小时向下取整成天；多给一天，服务端才实际保留至少七天。
+        "expiresAt": (datetime.now(timezone.utc) + timedelta(days=8)).isoformat(),
+    }).encode())
+    received = urllib.parse.urlsplit(created.get("signedUploadUrl", ""))
+    expected_path = urllib.parse.urlsplit(endpoint).path + "/UploadArtifact"
+    if not created.get("ok") or received.path != expected_path or not received.query:
+        raise ValueError("unexpected artifact upload path")
+    # 服务可能返回外部 AppURL；保留签名，但只连接配置的内部 Gitea 地址。
+    upload_url = endpoint + "/UploadArtifact?" + received.query
+    size = path.stat().st_size
+    digest = hashlib.sha256()
+    blocks = []
+    with path.open("rb") as source:
+        while chunk := source.read(CHUNK_BYTES):
+            # 双层编码中的内层保留所属任务；宿主只回收带此前缀的过期未完成块。
+            block = base64.b64encode(
+                f"genarrative-rust-cache-v1:{producer}:{len(blocks):08d}".encode()
+            ).decode()
+            blocks.append(block)
+            digest.update(chunk)
+            request("PUT", upload_url + "&" + urllib.parse.urlencode({
+                "comp": "block", "blockid": block,
+            }), None, chunk, {
+                "Content-Type": "application/octet-stream",
+            })
+    blocklist = "<BlockList>" + "".join(f"<Latest>{block}</Latest>" for block in blocks) + "</BlockList>"
+    request("PUT", upload_url + "&comp=blocklist", None, blocklist.encode(), {
+        "Content-Type": "application/xml",
+    })
+    # Finalize 会消耗服务端块列表；响应不确定时不盲目重试、也不宣告成功。
+    finalized = request("POST", endpoint + "/FinalizeArtifact", token, json.dumps({
+        **identity, "size": str(size), "hash": "sha256:" + digest.hexdigest(),
+    }).encode(), attempts=1)
+    if not finalized.get("ok"):
+        raise ValueError("artifact was not finalized")
+
+
+def export(env):
+    # 双重限定：手工调用、PR 和其它分支不会扫描、打包或上传对象。
+    if env.get("GITHUB_EVENT_NAME") != "push" or env.get("GITHUB_REF") != "refs/heads/master":
+        return
+    if env.get("GENARRATIVE_CI_RUST_CACHE_EXPORT_READY") != "1":
+        print("[rust-cache] export skipped: cache daemon did not stop cleanly")
+        return
+    job = env.get("GITHUB_JOB")
+    if job not in JOBS:
+        raise ValueError("unexpected Rust cache job")
+    sha = env["GITHUB_SHA"]
+    if not re.fullmatch(r"[a-f0-9]{40}", sha):
+        raise ValueError("a complete source SHA is required")
+    run_id, attempt = int(env["GITHUB_RUN_ID"]), int(env["GITHUB_RUN_ATTEMPT"])
+    if run_id <= 0 or attempt < 0:
+        raise ValueError("invalid run identity")
+    token = env.get("ACTIONS_RUNTIME_TOKEN") or env["GENARRATIVE_GITEA_TOKEN"]
+    base_url = artifact_base_url(env)
+    root = Path(env.get("GENARRATIVE_CI_RUST_CACHE_ROOT", "/opt/genarrative-ci/rust-cache"))
+    baseline_path = root / "export-baseline.json"
+    baseline = json.loads(baseline_path.read_text(encoding="utf-8"))
+    rustc = subprocess.check_output(["rustc", "-vV"], text=True)
+    workspace = str(Path.cwd().resolve())
+    if rustc != (root / "rustc.txt").read_text() or workspace != (root / "workspace.txt").read_text().strip():
+        raise ValueError("cache provenance changed after prepare")
+    metadata = {
+        "repository": env["GITHUB_REPOSITORY"],
+        "run_id": run_id, "run_attempt": attempt, "job": job, "source_sha": sha,
+        "rustc": rustc, "workspace": workspace,
+        "inherited_source_sha": (root / "source-commit.txt").read_text().strip(),
+        "sccache_version": subprocess.check_output([str(root / "sccache"), "--version"], text=True).strip(),
+    }
+    if (root / "base-image.txt").is_file():
+        metadata["base_image"] = (root / "base-image.txt").read_text().strip()
+    name = f"rust-cache-v1-{job}-attempt-{attempt}"
+    try:
+        with tempfile.TemporaryDirectory(prefix="ci-rust-cache-export-") as directory:
+            path = Path(directory) / "snapshot.zip"
+            count, size = pack_snapshot(root, path, metadata, baseline)
+            upload_snapshot(path, name, run_id, base_url, token)
+    finally:
+        baseline_path.unlink(missing_ok=True)
+    print(f"[rust-cache] artifact={name} objects={count} bytes={size} complete=true")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3 and sys.argv[1] == "baseline":
+        save_baseline(Path(os.environ.get("GENARRATIVE_CI_RUST_CACHE_ROOT", "/opt/genarrative-ci/rust-cache")), Path(sys.argv[2]))
+    else:
+        export(os.environ)
diff --git a/scripts/gitea-ci-job-image.sh b/scripts/gitea-ci-job-image.sh
index e9e06c8db..c0df68721 100644
--- a/scripts/gitea-ci-job-image.sh
+++ b/scripts/gitea-ci-job-image.sh
@@ -6,12 +6,31 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
 dockerfile_context_path="deploy/container/gitea-ci-job.Dockerfile"
 image_tag="${GENARRATIVE_GITEA_CI_IMAGE_TAG:-genarrative/gitea-project-ci:20260920.2}"
 runner_container="${GENARRATIVE_GITEA_RUNNER_CONTAINER:-gitea-runner}"
+builder_name="genarrative-ci-images"
+
+prepare_builder() {
+  if ! docker buildx version >/dev/null 2>&1; then
+    echo 'Gitea CI image builds require the Docker Buildx plugin; see deploy/container/README.md.' >&2
+    return 1
+  fi
+  if ! docker buildx inspect "${builder_name}" >/dev/null 2>&1; then
+    docker buildx create --name "${builder_name}" --driver docker-container \
+      --driver-opt image=moby/buildkit:v0.23.2@sha256:ddd1ca44b21eda906e81ab14a3d467fa6c39cd73b9a39df1196210edcb8db59e \
+      --buildkitd-config "${repo_root}/deploy/container/gitea-ci-buildkitd.toml"
+  fi
+  if [[ "$(docker buildx inspect "${builder_name}" --format '{{.Driver}}')" != docker-container ]]; then
+    echo "${builder_name} must use the isolated docker-container driver" >&2
+    return 1
+  fi
+}
 
 write_build_context_file_list() {
   printf '%s\0' \
     deploy/container/gitea-ci-job.Dockerfile \
     deploy/container/gitea-ci-job.Dockerfile.dockerignore \
+    deploy/container/gitea-ci-buildkitd.toml \
     deploy/container/gitea-ci-checkout.sh \
+    scripts/export-ci-npm-download-cache.mjs \
     package.json \
     package-lock.json \
     apps/admin-web/package.json \
@@ -29,8 +48,9 @@ write_build_context_file_list() {
     server-rs/Cargo.lock \
     apps/desktop-shell/src-tauri/Cargo.toml \
     apps/desktop-shell/src-tauri/Cargo.lock
-  find server-rs/crates plugins/agc-*-editor/native/*-editor-bridge \
-    \( -name Cargo.toml -o -path 'plugins/agc-*-editor/native/*-editor-bridge/*' \) \
+  find server-rs/crates apps/ai-game-creator-shell/src-tauri/vendor \
+    plugins/agc-*-editor/native/*-editor-bridge \
+    -name Cargo.toml \
     -type f -print0 \
     | sort -z
 }
@@ -39,6 +59,8 @@ usage() {
   cat <<'EOF'
 用法：
   bash scripts/gitea-ci-job-image.sh build
+  bash scripts/gitea-ci-job-image.sh seed-downloads <可信 CI 镜像完整 Image ID>
+  bash scripts/gitea-ci-job-image.sh revision
   bash scripts/gitea-ci-job-image.sh verify [镜像引用]
   bash scripts/gitea-ci-job-image.sh load-runner [镜像引用]
   bash scripts/gitea-ci-job-image.sh export <归档路径> [镜像引用]
@@ -65,40 +87,38 @@ verify_image() {
 
 command_name="${1:-}"
 case "${command_name}" in
-  build)
-    image_revision="$(
+  seed-downloads)
+    # 运维显式指定的可信镜像只贡献下载包，不作为新基础镜像的父层。
+    seed_image="${2:-}"
+    [[ "${seed_image}" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo 'seed requires a full trusted Image ID' >&2; exit 2; }
+    prepare_builder
+    seed_dir="$(mktemp -d)"
+    seed_container=""
+    cleanup_seed() {
+      if [[ -n "${seed_container}" ]]; then docker rm --volumes "${seed_container}" >/dev/null; fi
+      rm -rf -- "${seed_dir}"
+    }
+    trap cleanup_seed EXIT
+    seed_container="$(docker create "${seed_image}")"
+    mkdir -p "${seed_dir}/cargo-cache" "${seed_dir}/cargo-index" "${seed_dir}/npm"
+    docker cp "${seed_container}:/usr/local/cargo/registry/cache/." "${seed_dir}/cargo-cache/"
+    docker cp "${seed_container}:/usr/local/cargo/registry/index/." "${seed_dir}/cargo-index/"
+    docker cp "${seed_container}:/root/.npm/_cacache/." "${seed_dir}/npm/"
+    docker buildx build --builder "${builder_name}" --progress plain \
+      --target download-cache-seed --no-cache-filter download-cache-seed \
+      --build-context "download-seed=${seed_dir}" \
+      --file "${repo_root}/${dockerfile_context_path}" "${seed_dir}"
+    ;;
+  revision)
+    # 与 build 的 IMAGE_REVISION 使用同一份输入顺序，用于维护器判断基础镜像是否过期。
+    (
       cd "${repo_root}"
-      {
-        sha256sum \
-          deploy/container/gitea-ci-job.Dockerfile \
-          deploy/container/gitea-ci-job.Dockerfile.dockerignore \
-          deploy/container/gitea-ci-checkout.sh \
-          package.json \
-          package-lock.json \
-          apps/admin-web/package.json \
-          apps/ai-game-creator-shell/package.json \
-          apps/desktop-shell/package.json \
-          apps/mobile-shell/package.json \
-          apps/preview-deployer-web/package.json \
-          packages/image-canvas-core/package.json \
-          packages/image-canvas-react/package.json \
-          packages/shared/package.json \
-          tools/spine-json-export-validator/package.json \
-          apps/ai-game-creator-shell/src-tauri/Cargo.toml \
-          apps/ai-game-creator-shell/src-tauri/Cargo.lock \
-          server-rs/Cargo.toml \
-          server-rs/Cargo.lock \
-          apps/desktop-shell/src-tauri/Cargo.toml \
-          apps/desktop-shell/src-tauri/Cargo.lock
-        find server-rs/crates plugins/agc-*-editor/native/*-editor-bridge \
-          \( -name Cargo.toml -o -path 'plugins/agc-*-editor/native/*-editor-bridge/*' \) \
-          -type f -print0 \
-          | sort -z \
-          | xargs -0 -r sha256sum
-      } \
-        | sha256sum \
-        | awk '{ print $1 }'
-    )"
+      write_build_context_file_list | xargs -0 -r sha256sum | sha256sum | awk '{ print $1 }'
+    )
+    ;;
+  build)
+    prepare_builder
+    image_revision="$(bash "${BASH_SOURCE[0]}" revision)"
     npm_lock_sha256="$(sha256sum "${repo_root}/package-lock.json")"
     npm_lock_sha256="${npm_lock_sha256%% *}"
     server_rust_lock_sha256="$(sha256sum "${repo_root}/server-rs/Cargo.lock")"
@@ -111,7 +131,7 @@ case "${command_name}" in
       cd "${repo_root}"
       write_build_context_file_list \
         | tar --null --create --file - --files-from=- \
-        | docker build \
+        | docker buildx build --builder "${builder_name}" --load --progress plain \
           --pull=false \
           --build-arg "IMAGE_REVISION=${image_revision}" \
           --build-arg "NPM_LOCK_SHA256=${npm_lock_sha256}" \
diff --git a/scripts/gitea-runner-fetch-gate.py b/scripts/gitea-runner-fetch-gate.py
new file mode 100644
index 000000000..7f8346e65
--- /dev/null
+++ b/scripts/gitea-runner-fetch-gate.py
@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+"""Gitea Runner 领取屏障；控制 socket 仅供宿主缓存维护任务使用。"""
+
+import http.client
+import http.server
+import gzip
+import io
+import json
+import os
+from pathlib import Path
+import socketserver
+import threading
+import time
+import urllib.parse
+import zlib
+
+MAX_BODY = 32 * 1024 * 1024
+HOP_HEADERS = {
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailer", "transfer-encoding", "upgrade", "host", "content-length",
+}
+RPC_PREFIX = "/api/actions/runner.v1.RunnerService/"
+
+
+def protobuf_fields(data):
+    """只解码已核对的 actions-proto-go v0.4.1 字段，不引入 protobuf 运行时。"""
+    fields = {}
+    offset = 0
+
+    def varint():
+        nonlocal offset
+        value = 0
+        for shift in range(0, 70, 7):
+            if offset >= len(data):
+                raise ValueError("truncated protobuf")
+            byte = data[offset]
+            offset += 1
+            value |= (byte & 127) << shift
+            if byte < 128:
+                return value
+        raise ValueError("invalid protobuf varint")
+
+    while offset < len(data):
+        tag = varint()
+        number, wire = tag >> 3, tag & 7
+        if not number:
+            raise ValueError("invalid protobuf tag")
+        if wire == 0:
+            value = varint()
+        elif wire in (1, 2, 5):
+            length = varint() if wire == 2 else (8 if wire == 1 else 4)
+            if offset + length > len(data):
+                raise ValueError("truncated protobuf field")
+            value = data[offset:offset + length]
+            offset += length
+        else:
+            raise ValueError("unsupported protobuf wire type")
+        fields.setdefault(number, []).append(value)
+    return fields
+
+
+def single(fields, number, default=None):
+    values = fields.get(number, [])
+    if len(values) > 1:
+        raise ValueError("ambiguous tracking field")
+    return values[0] if values else default
+
+
+def rpc_fields(body, headers):
+    encoding = headers.get("Content-Encoding", "identity").lower()
+    if encoding == "gzip":
+        with gzip.GzipFile(fileobj=io.BytesIO(body)) as stream:
+            body = stream.read(MAX_BODY + 1)
+    elif encoding != "identity":
+        raise ValueError("unsupported RPC encoding")
+    if len(body) > MAX_BODY:
+        raise ValueError("decoded RPC too large")
+    if headers.get("Content-Type", "").split(";", 1)[0] != "application/proto":
+        raise ValueError("task tracking requires Connect protobuf")
+    return protobuf_fields(body)
+
+
+def task_state(fields):
+    nested = single(fields, 1)
+    if not isinstance(nested, bytes):
+        raise ValueError("missing task state")
+    state = protobuf_fields(nested)
+    task_id = positive_id(single(state, 1))
+    result = single(state, 2, 0)
+    if type(result) is not int or result not in range(5):
+        raise ValueError("unknown task result")
+    return task_id, result
+
+
+def positive_id(value):
+    if type(value) is not int or not 0 < value < 2 ** 63:
+        raise ValueError("invalid task ID")
+    return str(value)
+
+
+class Gate:
+    def __init__(self, directory):
+        self.directory = Path(directory)
+        self.directory.mkdir(parents=True, exist_ok=True)
+        self.lock = threading.Lock()
+        self.inflight = 0
+        self.last_fetch_peer = None
+        self.last_fetch_at = None
+        self.tasks = {}
+        self.uncertain = (self.directory / "uncertain").exists()
+        try:
+            if (self.directory / "tasks.json").exists():
+                tasks = json.loads((self.directory / "tasks.json").read_text())
+                if (not isinstance(tasks, dict) or any(
+                        positive_id(int(key)) != key or type(value) is not bool
+                        for key, value in tasks.items())):
+                    raise ValueError("invalid task ledger")
+                self.tasks = tasks
+        except (ValueError, TypeError, OSError):
+            self.uncertain = True
+            self.mark("uncertain")
+        if (self.directory / "inflight").exists():
+            self.uncertain = True
+            self.mark("uncertain")
+        self.paused = (self.directory / "paused").exists() or self.uncertain
+
+    def mark(self, name):
+        with (self.directory / name).open("w", encoding="ascii") as stream:
+            stream.write("1\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        self.sync_directory()
+
+    def sync_directory(self):
+        descriptor = os.open(self.directory, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+
+    def snapshot(self):
+        return {"paused": self.paused, "inflight": self.inflight,
+                "active_tasks": len(self.tasks), "task_ids": sorted(self.tasks),
+                "uncertain": self.uncertain, "last_fetch_peer": self.last_fetch_peer,
+                "last_fetch_at": self.last_fetch_at}
+
+    def save_tasks(self):
+        temporary = self.directory / "tasks.json.tmp"
+        with temporary.open("w", encoding="ascii") as stream:
+            json.dump(self.tasks, stream, sort_keys=True)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, self.directory / "tasks.json")
+        self.sync_directory()
+
+    def fail_closed(self):
+        with self.lock:
+            self.uncertain = self.paused = True
+            self.mark("uncertain")
+
+    def assigned(self, fields):
+        task = single(fields, 1)
+        if task is None:
+            return
+        if not isinstance(task, bytes):
+            raise ValueError("invalid fetched task")
+        task_id = positive_id(single(protobuf_fields(task), 1))
+        with self.lock:
+            self.tasks[task_id] = False
+            # 必须先持久化，再把领取结果交给 runner；仅保存 ID，不保存 secrets。
+            self.save_tasks()
+
+    def reported(self, method, request, response):
+        if method == "UpdateLog":
+            task_id = positive_id(single(request, 1))
+            index = single(request, 2, 0)
+            ack = single(response, 1, 0)
+            no_more = single(request, 4, 0)
+            if (type(index) is not int or type(ack) is not int
+                    or index < 0 or ack < 0 or no_more not in (0, 1)):
+                raise ValueError("invalid log acknowledgement")
+            finalized = no_more == 1 and ack == index + len(request.get(3, []))
+        else:
+            task_id, result = task_state(request)
+            response_id, response_result = task_state(response)
+            if response_id != task_id:
+                raise ValueError("mismatched task acknowledgement")
+            # 取消响应可能出现在任务执行途中，必须等 runner 自己报告终态。
+            finalized = result != 0 and response_result != 0
+            output_keys = {single(protobuf_fields(entry), 1, b"")
+                           for entry in request.get(2, [])}
+            finalized = finalized and output_keys.issubset(set(response.get(2, [])))
+        with self.lock:
+            if task_id not in self.tasks:
+                # 客户端可能未读到已成功发出的终态响应而重试；v2.0.0 仅在
+                # executor 清理后的 Close 中发送终态，不为幂等重报增加墓碑账本。
+                if method == "UpdateTask" and finalized:
+                    return
+                raise ValueError("report for untracked task; idle bootstrap required")
+            if method == "UpdateLog" and finalized:
+                self.tasks[task_id] = True
+                self.save_tasks()
+            elif method == "UpdateTask" and finalized and self.tasks[task_id]:
+                # act_runner Reporter.Close 在 executor 清理之后先封存日志再报终态。
+                del self.tasks[task_id]
+                self.save_tasks()
+
+    def record_fetch(self, peer):
+        with self.lock:
+            self.last_fetch_peer = peer
+            self.last_fetch_at = time.time()
+
+    def control(self, action):
+        with self.lock:
+            if action == "pause":
+                self.mark("paused")
+                self.paused = True
+            elif action == "resume":
+                if self.uncertain:
+                    return {**self.snapshot(), "error": "upstream completion uncertain; operator recovery required"}
+                (self.directory / "paused").unlink(missing_ok=True)
+                self.sync_directory()
+                self.paused = False
+            elif action != "status":
+                return {**self.snapshot(), "error": "unknown action"}
+            return self.snapshot()
+
+    def enter(self):
+        with self.lock:
+            if self.paused or self.uncertain:
+                return False
+            # 必须先落盘再转发；崩溃后不能把遗留的领取请求误认为已完成。
+            self.mark("inflight")
+            self.inflight += 1
+            return True
+
+    def leave(self, completed):
+        with self.lock:
+            self.inflight -= 1
+            if not completed:
+                self.uncertain = self.paused = True
+                self.mark("uncertain")
+            if self.inflight == 0 and not self.uncertain:
+                (self.directory / "inflight").unlink(missing_ok=True)
+                self.sync_directory()
+
+
+def read_body(stream, headers):
+    """解码 HTTP 请求；拒绝含糊 framing，不依赖下游连接关闭。"""
+    encodings = headers.get_all("Transfer-Encoding", [])
+    lengths = headers.get_all("Content-Length", [])
+    if encodings and lengths:
+        raise ValueError("ambiguous request framing")
+    if len(lengths) > 1 or len(encodings) > 1:
+        raise ValueError("duplicate request framing")
+
+    def exact(length):
+        data = stream.read(length)
+        if len(data) != length:
+            raise ValueError("incomplete request body")
+        return data
+
+    if not encodings:
+        length = int(lengths[0]) if lengths else 0
+        if not 0 <= length <= MAX_BODY:
+            raise ValueError("request too large")
+        return exact(length)
+    if encodings[0].strip().lower() != "chunked":
+        raise ValueError("unsupported transfer encoding")
+    body = bytearray()
+    while True:
+        line = stream.readline(8193)
+        if len(line) > 8192 or not line.endswith(b"\r\n"):
+            raise ValueError("invalid chunk header")
+        length = int(line.split(b";", 1)[0].strip(), 16)
+        if length < 0 or len(body) + length > MAX_BODY:
+            raise ValueError("request too large")
+        if length == 0:
+            trailer_size = 0
+            while True:
+                line = stream.readline(8193)
+                trailer_size += len(line)
+                if trailer_size > 8192 or not line.endswith(b"\r\n"):
+                    raise ValueError("invalid request trailers")
+                if line == b"\r\n":
+                    return bytes(body)
+        body.extend(exact(length))
+        if exact(2) != b"\r\n":
+            raise ValueError("invalid chunk terminator")
+
+
+class Proxy(http.server.BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *_args):
+        pass  # 不输出 RPC 认证头、请求内容或带认证信息的 URL。
+
+    def reply(self, status, body, headers=()):
+        delivered = False
+        try:
+            self.send_response(status)
+            excluded = HOP_HEADERS | {
+                item.strip().lower() for key, value in headers if key.lower() == "connection"
+                for item in value.split(",")
+            }
+            for key, value in headers:
+                if key.lower() not in excluded:
+                    self.send_header(key, value)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Connection", "close")
+            self.end_headers()
+            self.wfile.write(body)
+            self.wfile.flush()
+            delivered = True
+        except (OSError, ValueError):
+            pass
+        self.close_connection = True
+        return delivered
+
+    def do_POST(self):
+        path = urllib.parse.urlsplit(self.path)
+        if (path.scheme or path.netloc or not path.path.startswith("/api/actions/")
+                or "%" in path.path or any(p in (".", "..") for p in path.path.split("/"))):
+            self.reply(404, b"runner RPC only\n")
+            return
+        try:
+            body = read_body(self.rfile, self.headers)
+        except (ValueError, OSError):
+            self.reply(400, b"invalid request body\n")
+            return
+        method = path.path.removeprefix(RPC_PREFIX) if path.path.startswith(RPC_PREFIX) else ""
+        is_fetch = method == "FetchTask"
+        if is_fetch:
+            # 包括暂停时被拒绝的请求；只记录网络来源与时间以证明 daemon 路由。
+            self.server.gate.record_fetch(self.client_address[0])
+            if not self.server.gate.enter():
+                self.reply(503, b"runner maintenance\n")
+                return
+        completed = False
+        connection = None
+        try:
+            upstream = self.server.upstream
+            cls = http.client.HTTPSConnection if upstream.scheme == "https" else http.client.HTTPConnection
+            connection = cls(upstream.hostname, upstream.port, timeout=None)
+            try:
+                connection.connect()
+            except OSError:
+                # TCP/TLS 连接阶段尚未发送 RPC，不存在服务端分配事务。
+                completed = True
+                raise
+            excluded = HOP_HEADERS | {
+                name.strip().lower() for name in self.headers.get("Connection", "").split(",")
+            }
+            headers = {key: value for key, value in self.headers.items() if key.lower() not in excluded}
+            headers["Content-Length"] = str(len(body))
+            connection.request("POST", self.path, body=body, headers=headers)
+            response = connection.getresponse()
+            result = bytearray()
+            oversized = False
+            # 客户端即使断开，也继续读取上游完整响应，再释放领取屏障。
+            while block := response.read(65536):
+                if len(result) + len(block) <= MAX_BODY and not oversized:
+                    result.extend(block)
+                else:
+                    oversized = True
+                    result.clear()
+            if response.length not in (None, 0):
+                raise http.client.IncompleteRead(bytes(result), response.length)
+            completed = True
+            if is_fetch:
+                try:
+                    if oversized or response.status != 200:
+                        raise ValueError("unknown FetchTask result")
+                    self.server.gate.assigned(rpc_fields(bytes(result), response.headers))
+                except (ValueError, TypeError, OSError, EOFError, zlib.error):
+                    self.server.gate.fail_closed()
+                self.server.gate.leave(True)
+                is_fetch = False
+            if oversized:
+                self.reply(502, b"upstream response too large\n")
+            else:
+                # 日志封存先记账再返回，避免 runner 立即发终态时抢先读到旧账本。
+                if method == "UpdateLog" and response.status == 200:
+                    self.observe_report(method, body, bytes(result), response.headers)
+                delivered = self.reply(response.status, bytes(result), response.getheaders())
+                if method == "UpdateTask" and response.status == 200 and delivered:
+                    self.observe_report(method, body, bytes(result), response.headers)
+        except (OSError, http.client.HTTPException, ValueError):
+            self.reply(502, b"runner upstream unavailable\n")
+        finally:
+            if connection is not None:
+                connection.close()
+            if is_fetch:
+                self.server.gate.leave(completed)
+
+    def observe_report(self, method, request, response, headers):
+        try:
+            self.server.gate.reported(method, rpc_fields(request, self.headers),
+                                      rpc_fields(response, headers))
+        except (ValueError, TypeError, OSError, EOFError, zlib.error):
+            self.server.gate.fail_closed()
+
+
+class Control(socketserver.StreamRequestHandler):
+    def handle(self):
+        try:
+            line = self.rfile.readline(4097)
+            if len(line) > 4096 or not line.endswith(b"\n"):
+                raise ValueError("invalid control request")
+            request = json.loads(line)
+            result = self.server.gate.control(request["action"])
+        except (ValueError, KeyError, TypeError, OSError):
+            result = {"error": "invalid control request"}
+        self.wfile.write(json.dumps(result).encode("utf-8") + b"\n")
+
+
+class ControlServer(socketserver.ThreadingUnixStreamServer):
+    daemon_threads = True
+
+
+def create_proxy(address, upstream, gate):
+    parsed = urllib.parse.urlsplit(upstream)
+    if (parsed.scheme not in ("http", "https") or not parsed.hostname
+            or parsed.username or parsed.password or parsed.path not in ("", "/")
+            or parsed.query or parsed.fragment):
+        raise ValueError("upstream must be an HTTP(S) origin")
+    server = http.server.ThreadingHTTPServer(address, Proxy)
+    server.upstream = parsed
+    server.gate = gate
+    return server
+
+
+def main():
+    gate = Gate(os.environ.get("GITEA_GATE_CONTROL_DIR", "/control"))
+    socket_path = gate.directory / "gate.sock"
+    socket_path.unlink(missing_ok=True)
+    control = ControlServer(str(socket_path), Control)
+    control.gate = gate
+    os.chmod(socket_path, 0o600)
+    proxy = create_proxy(("0.0.0.0", 8080), os.environ.get(
+        "GITEA_RUNNER_UPSTREAM", "http://gitea:3000"), gate)
+    threading.Thread(target=control.serve_forever, daemon=True).start()
+    proxy.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/gitea_cache_snapshot.py b/scripts/gitea_cache_snapshot.py
new file mode 100644
index 000000000..46e117e15
--- /dev/null
+++ b/scripts/gitea_cache_snapshot.py
@@ -0,0 +1,649 @@
+#!/usr/bin/env python3
+"""Validate and merge Gitea CI sccache artifacts into one object snapshot."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import stat
+import tarfile
+import tempfile
+from typing import BinaryIO, Mapping, Sequence
+import zipfile
+
+
+GIB = 1024 ** 3
+DEFAULT_MAX_COMBINED_BYTES = 4 * GIB
+MAX_INPUT_OBJECT_BYTES = 4 * GIB
+MAX_MANIFEST_BYTES = 16 * 1024 ** 2
+MAX_OBJECTS = 100_000
+MAX_BASE_OBJECTS = 1_000_000
+MAX_TAR_OVERHEAD_BYTES = 128 * 1024 ** 2
+OBJECT_PATH = re.compile(r"objects/([0-9a-f])/([0-9a-f])/([0-9a-f]{64})\Z")
+SHA256 = re.compile(r"[0-9a-f]{64}\Z")
+TEMP_PREFIX = ".gitea-cache-snapshot-"
+
+
+class SnapshotError(ValueError):
+    """The downloaded snapshot does not satisfy the trusted artifact contract."""
+
+
+@dataclass(frozen=True)
+class ArtifactIdentity:
+    repository: str
+    run_id: int
+    run_attempt: int
+    job: str
+    source_sha: str
+
+
+@dataclass(frozen=True)
+class ArtifactInput:
+    archive: Path
+    expected: ArtifactIdentity
+
+
+@dataclass(frozen=True)
+class MergeResult:
+    object_count: int
+    total_bytes: int
+    source_sha: str
+    rustc: str
+    workspace: str
+    base_image: str | None
+    sccache_version: str
+
+
+@dataclass(frozen=True)
+class _Object:
+    path: str
+    size: int
+    sha256: str | None
+    mtime_ns: int
+    source_index: int | None
+
+
+@dataclass(frozen=True)
+class _Touch:
+    path: str
+    mtime_ns: int
+
+
+@dataclass(frozen=True)
+class _Archive:
+    input: ArtifactInput
+    manifest: Mapping[str, object]
+    objects: tuple[_Object, ...]
+    touched: tuple[_Touch, ...]
+    signature: tuple[int, int, int]
+
+
+def _is_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _require_string(value: object, field: str) -> str:
+    if not isinstance(value, str) or not value or "\0" in value:
+        raise SnapshotError(f"manifest {field} must be a non-empty string")
+    return value
+
+
+def _strict_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise SnapshotError(f"manifest contains duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def _archive_signature(path: Path) -> tuple[int, int, int]:
+    try:
+        status = path.stat()
+    except OSError as error:
+        raise SnapshotError(f"cannot stat artifact archive: {path}") from error
+    if path.is_symlink() or not path.is_file():
+        raise SnapshotError(f"artifact archive must be a regular file: {path}")
+    return status.st_size, status.st_mtime_ns, status.st_ino
+
+
+def _safe_zip_path(name: str) -> tuple[str, ...]:
+    if not name or "\0" in name or "\\" in name or name.startswith("/"):
+        raise SnapshotError(f"unsafe ZIP member path: {name!r}")
+    parts = PurePosixPath(name.rstrip("/")).parts
+    if not parts or any(part in {"", ".", ".."} for part in parts):
+        raise SnapshotError(f"unsafe ZIP member path: {name!r}")
+    return parts
+
+
+def _snapshot_member(archive: Path) -> tuple[zipfile.ZipFile, zipfile.ZipInfo]:
+    try:
+        bundle = zipfile.ZipFile(archive)
+    except (OSError, zipfile.BadZipFile) as error:
+        raise SnapshotError(f"invalid artifact ZIP: {archive}") from error
+
+    try:
+        infos = bundle.infolist()
+        if len({info.filename for info in infos}) != len(infos):
+            raise SnapshotError("ZIP contains duplicate members")
+        files: list[zipfile.ZipInfo] = []
+        directories: list[tuple[str, ...]] = []
+        for info in infos:
+            parts = _safe_zip_path(info.filename)
+            mode = info.external_attr >> 16
+            if info.flag_bits & 1:
+                raise SnapshotError("encrypted ZIP members are not accepted")
+            if stat.S_ISLNK(mode):
+                raise SnapshotError("ZIP links are not accepted")
+            if info.is_dir():
+                directories.append(parts)
+            else:
+                files.append(info)
+        if len(files) != 1:
+            raise SnapshotError("ZIP must contain exactly one snapshot.tar file")
+        member = files[0]
+        parts = _safe_zip_path(member.filename)
+        if not (parts == ("snapshot.tar",) or
+                (len(parts) == 2 and parts[1] == "snapshot.tar")):
+            raise SnapshotError("ZIP member must be snapshot.tar or <artifact>/snapshot.tar")
+        expected_directories = set() if len(parts) == 1 else {(parts[0],)}
+        if set(directories) - expected_directories:
+            raise SnapshotError("ZIP contains unexpected directory members")
+        maximum_tar_size = (
+            MAX_INPUT_OBJECT_BYTES + MAX_MANIFEST_BYTES + MAX_TAR_OVERHEAD_BYTES
+        )
+        if member.file_size > maximum_tar_size:
+            raise SnapshotError("snapshot.tar exceeds the per-job input bound")
+        if member.compress_type != zipfile.ZIP_STORED:
+            raise SnapshotError("snapshot.tar ZIP member must use ZIP_STORED")
+        return bundle, member
+    except Exception:
+        bundle.close()
+        raise
+
+
+def _tar_stream(archive: Path):
+    bundle, member = _snapshot_member(archive)
+    try:
+        raw = bundle.open(member, "r")
+    except Exception:
+        bundle.close()
+        raise
+    try:
+        tar = tarfile.open(fileobj=raw, mode="r|")
+    except (OSError, tarfile.TarError) as error:
+        raw.close()
+        bundle.close()
+        raise SnapshotError(f"invalid snapshot.tar in {archive}") from error
+    return bundle, raw, tar
+
+
+def _hash_stream(stream: BinaryIO, expected_size: int) -> tuple[int, str]:
+    digest = hashlib.sha256()
+    total = 0
+    while True:
+        chunk = stream.read(1024 * 1024)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > expected_size:
+            raise SnapshotError("tar member contains more bytes than declared")
+        digest.update(chunk)
+    if total != expected_size:
+        raise SnapshotError("tar member is truncated")
+    return total, digest.hexdigest()
+
+
+def _validate_object_path(path: str) -> None:
+    match = OBJECT_PATH.fullmatch(path)
+    if not match or match[1] != match[3][0] or match[2] != match[3][1]:
+        raise SnapshotError(f"invalid sccache object path: {path!r}")
+
+
+def _parse_manifest(
+    contents: bytes,
+    expected: ArtifactIdentity,
+    expected_inherited_source_sha: str,
+) -> dict[str, object]:
+    try:
+        manifest = json.loads(contents, object_pairs_hook=_strict_object)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise SnapshotError("manifest.json is not valid UTF-8 JSON") from error
+    if not isinstance(manifest, dict):
+        raise SnapshotError("manifest.json must contain an object")
+    required = {
+        "schema", "repository", "run_id", "run_attempt", "job", "source_sha",
+        "rustc", "workspace", "sccache_version", "mode", "inherited_source_sha",
+        "objects", "touched",
+    }
+    allowed = required | {"base_image"}
+    if set(manifest) != required and set(manifest) != allowed:
+        raise SnapshotError("manifest.json has missing or unexpected fields")
+    if not _is_int(manifest["schema"]) or manifest["schema"] != 1:
+        raise SnapshotError("manifest schema must be 1")
+    for field in ("repository", "job", "source_sha", "rustc", "workspace",
+                  "sccache_version", "mode", "inherited_source_sha"):
+        _require_string(manifest[field], field)
+    if manifest["mode"] != "delta":
+        raise SnapshotError("manifest mode must be delta")
+    if manifest["inherited_source_sha"] != expected_inherited_source_sha:
+        raise SnapshotError("manifest inherited_source_sha does not match expected source image")
+    for field in ("run_id", "run_attempt"):
+        if not _is_int(manifest[field]) or manifest[field] < 1:
+            raise SnapshotError(f"manifest {field} must be a positive integer")
+    if "base_image" in manifest:
+        _require_string(manifest["base_image"], "base_image")
+
+    for field in ("repository", "run_id", "run_attempt", "job", "source_sha"):
+        if manifest[field] != getattr(expected, field):
+            raise SnapshotError(f"manifest {field} does not match expected identity")
+    if not isinstance(manifest["objects"], list):
+        raise SnapshotError("manifest objects must be a list")
+    if not isinstance(manifest["touched"], list):
+        raise SnapshotError("manifest touched must be a list")
+    return manifest
+
+
+def _manifest_objects(manifest: Mapping[str, object], source_index: int) -> tuple[_Object, ...]:
+    rows = manifest["objects"]
+    assert isinstance(rows, list)
+    if len(rows) > MAX_OBJECTS:
+        raise SnapshotError("manifest contains too many objects")
+    objects: list[_Object] = []
+    seen: set[str] = set()
+    for row in rows:
+        if not isinstance(row, dict) or set(row) != {"path", "size", "sha256", "mtime_ns"}:
+            raise SnapshotError("manifest object has missing or unexpected fields")
+        path = row["path"]
+        checksum = row["sha256"]
+        if not isinstance(path, str):
+            raise SnapshotError("manifest object path must be a string")
+        _validate_object_path(path)
+        if path in seen:
+            raise SnapshotError(f"manifest contains duplicate object: {path}")
+        seen.add(path)
+        if not _is_int(row["size"]) or row["size"] < 0:
+            raise SnapshotError(f"manifest object size is invalid: {path}")
+        if not isinstance(checksum, str) or not SHA256.fullmatch(checksum):
+            raise SnapshotError(f"manifest object sha256 is invalid: {path}")
+        if not _is_int(row["mtime_ns"]) or row["mtime_ns"] < 0:
+            raise SnapshotError(f"manifest object mtime_ns is invalid: {path}")
+        objects.append(_Object(
+            path=path,
+            size=row["size"],
+            sha256=checksum,
+            mtime_ns=row["mtime_ns"],
+            source_index=source_index,
+        ))
+    return tuple(objects)
+
+
+def _manifest_touches(manifest: Mapping[str, object]) -> tuple[_Touch, ...]:
+    rows = manifest["touched"]
+    assert isinstance(rows, list)
+    if len(rows) > MAX_OBJECTS:
+        raise SnapshotError("manifest contains too many touched objects")
+    touched: list[_Touch] = []
+    seen: set[str] = set()
+    for row in rows:
+        if not isinstance(row, dict) or set(row) != {"path", "mtime_ns"}:
+            raise SnapshotError("manifest touched object has missing or unexpected fields")
+        path = row["path"]
+        if not isinstance(path, str):
+            raise SnapshotError("manifest touched path must be a string")
+        _validate_object_path(path)
+        if path in seen:
+            raise SnapshotError(f"manifest contains duplicate touched object: {path}")
+        seen.add(path)
+        if not _is_int(row["mtime_ns"]) or row["mtime_ns"] < 0:
+            raise SnapshotError(f"manifest touched mtime_ns is invalid: {path}")
+        touched.append(_Touch(path=path, mtime_ns=row["mtime_ns"]))
+    return tuple(touched)
+
+
+def _validate_archive(
+    item: ArtifactInput,
+    source_index: int,
+    expected_inherited_source_sha: str,
+) -> _Archive:
+    path = Path(item.archive)
+    signature = _archive_signature(path)
+    bundle, raw, tar = _tar_stream(path)
+    actual: dict[str, tuple[int, str]] = {}
+    manifest_contents: bytes | None = None
+    total_bytes = 0
+    member_count = 0
+    try:
+        try:
+            for member in tar:
+                member_count += 1
+                if member_count > MAX_OBJECTS + 1:
+                    raise SnapshotError("snapshot.tar contains too many members")
+                if manifest_contents is not None:
+                    raise SnapshotError("manifest.json must be the last tar member")
+                if not member.isreg():
+                    raise SnapshotError(f"tar member must be a regular file: {member.name!r}")
+                if member.name == "manifest.json":
+                    if member.size < 0 or member.size > MAX_MANIFEST_BYTES:
+                        raise SnapshotError("manifest.json exceeds its size bound")
+                    stream = tar.extractfile(member)
+                    if stream is None:
+                        raise SnapshotError("cannot read manifest.json")
+                    manifest_contents = stream.read(MAX_MANIFEST_BYTES + 1)
+                    if len(manifest_contents) != member.size:
+                        raise SnapshotError("manifest.json is truncated")
+                    continue
+                _validate_object_path(member.name)
+                if member.size < 0:
+                    raise SnapshotError(f"tar member has a negative size: {member.name}")
+                if member.name in actual:
+                    raise SnapshotError(f"snapshot.tar contains duplicate member: {member.name}")
+                total_bytes += member.size
+                if total_bytes > MAX_INPUT_OBJECT_BYTES:
+                    raise SnapshotError("snapshot exceeds the per-job object byte bound")
+                stream = tar.extractfile(member)
+                if stream is None:
+                    raise SnapshotError(f"cannot read tar member: {member.name}")
+                actual[member.name] = _hash_stream(stream, member.size)
+        except (OSError, tarfile.TarError, zipfile.BadZipFile) as error:
+            raise SnapshotError(f"cannot stream snapshot archive: {path}") from error
+    finally:
+        tar.close()
+        raw.close()
+        bundle.close()
+
+    if manifest_contents is None:
+        raise SnapshotError("snapshot.tar is missing final manifest.json")
+    manifest = _parse_manifest(
+        manifest_contents, item.expected, expected_inherited_source_sha,
+    )
+    objects = _manifest_objects(manifest, source_index)
+    touched = _manifest_touches(manifest)
+    if {obj.path for obj in objects} & {touch.path for touch in touched}:
+        raise SnapshotError("an object cannot be both uploaded and touched")
+    described = {obj.path: (obj.size, obj.sha256) for obj in objects}
+    if actual != described:
+        raise SnapshotError("manifest object list, sizes, or checksums do not match snapshot.tar")
+    return _Archive(
+        input=item, manifest=manifest, objects=objects, touched=touched,
+        signature=signature,
+    )
+
+
+def _consistent_metadata(archives: Sequence[_Archive]) -> tuple[str, str, str, str, str | None]:
+    first = archives[0].manifest
+    fields = (
+        "source_sha", "rustc", "workspace", "sccache_version", "base_image",
+        "inherited_source_sha",
+    )
+    expected = tuple(first.get(field) for field in fields)
+    for archive in archives[1:]:
+        if tuple(archive.manifest.get(field) for field in fields) != expected:
+            raise SnapshotError("artifact compiler, workspace, source, or base-image metadata differs")
+    source_sha, rustc, workspace, sccache_version, base_image, _ = expected
+    assert isinstance(source_sha, str)
+    assert isinstance(rustc, str)
+    assert isinstance(workspace, str)
+    assert isinstance(sccache_version, str)
+    assert base_image is None or isinstance(base_image, str)
+    return source_sha, rustc, workspace, sccache_version, base_image
+
+
+def _validated_base_objects(base_objects: os.PathLike[str] | str) -> tuple[Path, dict[str, _Object]]:
+    requested = Path(base_objects)
+    if not requested.is_absolute():
+        raise SnapshotError("base_objects must be absolute")
+    try:
+        root = requested.resolve(strict=True)
+    except OSError as error:
+        raise SnapshotError("base_objects must exist") from error
+    if requested != root or requested.is_symlink() or not root.is_dir():
+        raise SnapshotError("base_objects must be a real canonical directory")
+
+    objects: dict[str, _Object] = {}
+    for first in root.iterdir():
+        if first.is_symlink() or not first.is_dir() or not re.fullmatch(r"[0-9a-f]", first.name):
+            raise SnapshotError(f"noncanonical entry in base objects: {first}")
+        for second in first.iterdir():
+            if second.is_symlink() or not second.is_dir() or not re.fullmatch(r"[0-9a-f]", second.name):
+                raise SnapshotError(f"noncanonical entry in base objects: {second}")
+            for entry in second.iterdir():
+                relative = f"objects/{first.name}/{second.name}/{entry.name}"
+                _validate_object_path(relative)
+                if entry.is_symlink() or not entry.is_file():
+                    raise SnapshotError(f"base object must be a regular file: {entry}")
+                status = entry.stat()
+                objects[relative] = _Object(
+                    path=relative,
+                    size=status.st_size,
+                    sha256=None,
+                    mtime_ns=status.st_mtime_ns,
+                    source_index=None,
+                )
+                if len(objects) > MAX_BASE_OBJECTS:
+                    raise SnapshotError("base_objects contains too many files")
+    return root, objects
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                return digest.hexdigest()
+            digest.update(chunk)
+
+
+def _select_objects(
+    archives: Sequence[_Archive],
+    base_root: Path,
+    base: Mapping[str, _Object],
+    maximum: int,
+) -> tuple[_Object, ...]:
+    merged = dict(base)
+    delta_paths = {obj.path for archive in archives for obj in archive.objects}
+    touched_paths = {touch.path for archive in archives for touch in archive.touched}
+    overlap = delta_paths & touched_paths
+    if overlap:
+        raise SnapshotError(f"object appears as both delta and touched: {min(overlap)}")
+    for archive in archives:
+        for touch in archive.touched:
+            current = merged.get(touch.path)
+            if current is None or current.source_index is not None:
+                raise SnapshotError(f"touched object is absent from inherited base: {touch.path}")
+            if touch.mtime_ns > current.mtime_ns:
+                merged[touch.path] = _Object(
+                    path=current.path,
+                    size=current.size,
+                    sha256=current.sha256,
+                    mtime_ns=touch.mtime_ns,
+                    source_index=None,
+                )
+
+    base_hashes: dict[str, str] = {}
+    for archive in archives:
+        for candidate in archive.objects:
+            current = merged.get(candidate.path)
+            if current is None:
+                merged[candidate.path] = candidate
+            elif current.source_index is None:
+                if current.size != candidate.size:
+                    raise SnapshotError(f"conflicting content for duplicate object: {candidate.path}")
+                checksum = base_hashes.get(candidate.path)
+                if checksum is None:
+                    checksum = _file_sha256(
+                        base_root.joinpath(*PurePosixPath(candidate.path).parts[1:])
+                    )
+                    base_hashes[candidate.path] = checksum
+                if checksum != candidate.sha256:
+                    raise SnapshotError(f"conflicting content for duplicate object: {candidate.path}")
+                merged[candidate.path] = _Object(
+                    path=current.path,
+                    size=current.size,
+                    sha256=checksum,
+                    mtime_ns=max(current.mtime_ns, candidate.mtime_ns),
+                    source_index=None,
+                )
+            elif (current.size, current.sha256) != (candidate.size, candidate.sha256):
+                raise SnapshotError(f"conflicting content for duplicate object: {candidate.path}")
+            elif candidate.mtime_ns > current.mtime_ns:
+                merged[candidate.path] = _Object(
+                    path=current.path,
+                    size=current.size,
+                    sha256=current.sha256,
+                    mtime_ns=candidate.mtime_ns,
+                    source_index=current.source_index,
+                )
+
+    selected: list[_Object] = []
+    total = 0
+    for candidate in sorted(merged.values(), key=lambda obj: (-obj.mtime_ns, obj.path)):
+        if candidate.size <= maximum - total:
+            selected.append(candidate)
+            total += candidate.size
+    return tuple(selected)
+
+
+def _copy_selected(archive: _Archive, selected: Mapping[str, _Object], root: Path) -> None:
+    if _archive_signature(Path(archive.input.archive)) != archive.signature:
+        raise SnapshotError(f"artifact archive changed while merging: {archive.input.archive}")
+    bundle, raw, tar = _tar_stream(Path(archive.input.archive))
+    remaining = set(selected)
+    try:
+        try:
+            for member in tar:
+                target_object = selected.get(member.name)
+                if target_object is None:
+                    continue
+                if not member.isreg() or member.size != target_object.size:
+                    raise SnapshotError(f"selected object changed while merging: {member.name}")
+                source = tar.extractfile(member)
+                if source is None:
+                    raise SnapshotError(f"cannot read selected object: {member.name}")
+                destination = root.joinpath(*PurePosixPath(member.name).parts)
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                digest = hashlib.sha256()
+                written = 0
+                with destination.open("xb") as output:
+                    while True:
+                        chunk = source.read(1024 * 1024)
+                        if not chunk:
+                            break
+                        written += len(chunk)
+                        if written > target_object.size:
+                            raise SnapshotError(f"selected object grew while merging: {member.name}")
+                        digest.update(chunk)
+                        output.write(chunk)
+                if written != target_object.size or digest.hexdigest() != target_object.sha256:
+                    raise SnapshotError(f"selected object checksum changed while merging: {member.name}")
+                os.utime(destination, ns=(target_object.mtime_ns, target_object.mtime_ns))
+                remaining.remove(member.name)
+        except (OSError, tarfile.TarError, zipfile.BadZipFile) as error:
+            raise SnapshotError(f"cannot copy selected objects from {archive.input.archive}") from error
+    finally:
+        tar.close()
+        raw.close()
+        bundle.close()
+    if remaining:
+        raise SnapshotError(f"selected objects disappeared from {archive.input.archive}")
+
+
+def _copy_base(base_root: Path, selected: Mapping[str, _Object], root: Path) -> None:
+    for relative, obj in selected.items():
+        source = base_root.joinpath(*PurePosixPath(relative).parts[1:])
+        if source.is_symlink() or not source.is_file() or source.stat().st_size != obj.size:
+            raise SnapshotError(f"inherited base object changed while merging: {relative}")
+        destination = root.joinpath(*PurePosixPath(relative).parts)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with source.open("rb") as input_stream, destination.open("xb") as output_stream:
+            shutil.copyfileobj(input_stream, output_stream, length=1024 * 1024)
+        if destination.stat().st_size != obj.size:
+            raise SnapshotError(f"inherited base object was truncated while merging: {relative}")
+        os.utime(destination, ns=(obj.mtime_ns, obj.mtime_ns))
+
+
+def _write_metadata(path: Path, value: str) -> None:
+    path.write_text(value if value.endswith("\n") else value + "\n", encoding="utf-8")
+
+
+def _validated_output(output_dir: os.PathLike[str] | str) -> tuple[Path, Path]:
+    output = Path(output_dir)
+    if not output.is_absolute():
+        raise SnapshotError("output_dir must be absolute")
+    if output.exists() or output.is_symlink():
+        raise SnapshotError("output_dir must not already exist")
+    try:
+        parent = output.parent.resolve(strict=True)
+    except OSError as error:
+        raise SnapshotError("output_dir parent must already exist") from error
+    if output.parent.is_symlink() or not parent.is_dir():
+        raise SnapshotError("output_dir parent must be a real directory")
+    if output.parent != parent:
+        raise SnapshotError("output_dir parent must use its canonical absolute path")
+    return output, parent
+
+
+def merge_snapshots(
+    inputs: Sequence[ArtifactInput],
+    output_dir: os.PathLike[str] | str,
+    *,
+    base_objects: os.PathLike[str] | str,
+    expected_inherited_source_sha: str,
+    max_combined_bytes: int = DEFAULT_MAX_COMBINED_BYTES,
+) -> MergeResult:
+    """Validate artifacts and atomically create a bounded sccache object snapshot."""
+    if not inputs:
+        raise SnapshotError("at least one artifact is required")
+    if not _is_int(max_combined_bytes) or max_combined_bytes < 0:
+        raise SnapshotError("max_combined_bytes must be a non-negative integer")
+    _require_string(expected_inherited_source_sha, "expected_inherited_source_sha")
+    output, parent = _validated_output(output_dir)
+
+    base_root, base = _validated_base_objects(base_objects)
+    archives = tuple(
+        _validate_archive(item, index, expected_inherited_source_sha)
+        for index, item in enumerate(inputs)
+    )
+    source_sha, rustc, workspace, sccache_version, base_image = _consistent_metadata(archives)
+    selected = _select_objects(archives, base_root, base, max_combined_bytes)
+    by_source: dict[int, dict[str, _Object]] = {}
+    from_base: dict[str, _Object] = {}
+    for obj in selected:
+        if obj.source_index is None:
+            from_base[obj.path] = obj
+        else:
+            by_source.setdefault(obj.source_index, {})[obj.path] = obj
+
+    temporary = Path(tempfile.mkdtemp(prefix=TEMP_PREFIX, dir=parent))
+    try:
+        snapshot = temporary / "snapshot"
+        (snapshot / "objects").mkdir(parents=True)
+        _copy_base(base_root, from_base, snapshot)
+        for source_index, objects in by_source.items():
+            _copy_selected(archives[source_index], objects, snapshot)
+        _write_metadata(snapshot / "rustc.txt", rustc)
+        _write_metadata(snapshot / "workspace.txt", workspace)
+        _write_metadata(snapshot / "source-commit.txt", source_sha)
+        if base_image is not None:
+            _write_metadata(snapshot / "base-image.txt", base_image)
+        snapshot.replace(output)
+    finally:
+        if temporary.parent != parent or not temporary.name.startswith(TEMP_PREFIX):
+            raise RuntimeError("refusing to clean an unexpected temporary directory")
+        shutil.rmtree(temporary, ignore_errors=False)
+
+    return MergeResult(
+        object_count=len(selected),
+        total_bytes=sum(obj.size for obj in selected),
+        source_sha=source_sha,
+        rustc=rustc,
+        workspace=workspace,
+        base_image=base_image,
+        sccache_version=sccache_version,
+    )
diff --git a/scripts/gitea_cache_upload_cleanup.py b/scripts/gitea_cache_upload_cleanup.py
new file mode 100644
index 000000000..6801d193a
--- /dev/null
+++ b/scripts/gitea_cache_upload_cleanup.py
@@ -0,0 +1,115 @@
+"""定向回收 Gitea 1.26.4 不会自动过期的本仓库缓存上传块。"""
+
+import base64
+import binascii
+import math
+from pathlib import Path
+import re
+import stat
+
+
+JOBS = {
+    "ai-game-creator-shell-rust-lane-1",
+    "ai-game-creator-shell-rust-lane-2",
+    "ai-game-creator-shell-rust-smoke",
+    "ai-game-creator-shell-rust-crates",
+    "backend-tests",
+    "native-shell-tests",
+}
+CHUNK = re.compile(r"block-([1-9][0-9]*)-([1-9][0-9]*)-(0|[1-9][0-9]*)-([A-Za-z0-9_-]+={0,2})")
+BLOCKLIST = re.compile(r"([1-9][0-9]*)-([1-9][0-9]*)-blocklist")
+MARKER = re.compile(r"genarrative-rust-cache-v1:([a-z0-9-]+):(0|[1-9][0-9]*):([0-9]{8})")
+
+
+def decode_owner(encoded):
+    """Gitea 文件名编码为 URL-base64(生产者上传的标准 base64 blockid)。"""
+    try:
+        block_id = base64.b64decode(encoded, altchars=b"-_", validate=True)
+        if base64.urlsafe_b64encode(block_id).decode() != encoded:
+            return None
+        marker = base64.b64decode(block_id, validate=True)
+        if base64.b64encode(marker) != block_id:
+            return None
+        match = MARKER.fullmatch(marker.decode("ascii"))
+        if match and match[1] in JOBS:
+            return match[1], int(match[2])
+    except (binascii.Error, UnicodeError, ValueError):
+        pass
+    return None
+
+
+def _unchanged_old_regular(path, previous, cutoff):
+    try:
+        current = path.lstat()
+    except FileNotFoundError:
+        return False
+    return (
+        stat.S_ISREG(current.st_mode)
+        and current.st_mtime < cutoff
+        and (current.st_ino, current.st_size, current.st_mtime_ns)
+        == (previous.st_ino, previous.st_size, previous.st_mtime_ns)
+    )
+
+
+def cleanup_upload_chunks(storage_root: Path, eligible_runs: set[int], cutoff_timestamp: float) -> int:
+    """调用方先用仓库 API 确认这些 master run 已结束超过保留期限。"""
+    storage_root = Path(storage_root)
+    if not storage_root.is_absolute() or storage_root.resolve(strict=True) != storage_root:
+        raise ValueError("artifact storage root must be an existing absolute real directory")
+    if not stat.S_ISDIR(storage_root.lstat().st_mode):
+        raise ValueError("artifact storage root must be a directory")
+    if not math.isfinite(cutoff_timestamp) or cutoff_timestamp <= 0:
+        raise ValueError("invalid artifact cleanup cutoff")
+    if any(type(run_id) is not int or run_id <= 0 for run_id in eligible_runs):
+        raise ValueError("invalid eligible run ID")
+    temporary = storage_root / "tmp-upload"
+    if not temporary.exists() and not temporary.is_symlink():
+        return 0
+    if temporary.is_symlink() or not temporary.is_dir():
+        raise ValueError("artifact temporary path must be a real directory")
+
+    deleted = 0
+    for run_id in sorted(eligible_runs):
+        directory = temporary / f"run-{run_id}-v4"
+        if directory.is_symlink() or not directory.is_dir():
+            continue
+        groups = {}
+        unknown = False
+        for path in directory.iterdir():
+            chunk = CHUNK.fullmatch(path.name)
+            blocklist = BLOCKLIST.fullmatch(path.name)
+            match = chunk or blocklist
+            if match and int(match[1]) == run_id:
+                artifact_id = int(match[2])
+                owner = decode_owner(chunk[4]) if chunk else None
+                owned = owner is not None if chunk else True
+            else:
+                # 若仍能识别 artifact ID，仅保护该组；无法识别时保护整个 run。
+                prefix = re.match(rf"(?:block-)?{run_id}-([1-9][0-9]*)-", path.name)
+                if not prefix:
+                    unknown = True
+                    break
+                artifact_id, owner, owned = int(prefix[1]), None, False
+            group = groups.setdefault(artifact_id, {"files": [], "owners": set(), "safe": True})
+            try:
+                info = path.lstat()
+            except FileNotFoundError:
+                group["safe"] = False
+                continue
+            group["safe"] &= owned and stat.S_ISREG(info.st_mode) and info.st_mtime < cutoff_timestamp
+            if owner:
+                group["owners"].add(owner)
+            group["files"].append((path, info))
+        if unknown:
+            continue
+        for group in groups.values():
+            if not group["safe"] or len(group["owners"]) != 1:
+                continue
+            files = group["files"]
+            if not all(_unchanged_old_regular(path, info, cutoff_timestamp) for path, info in files):
+                continue
+            # 保留目录，不使用递归删除；没有所属块证明的孤立 blocklist 也不会删除。
+            for path, _ in files:
+                path.unlink()
+                deleted += 1
+    return deleted
diff --git a/scripts/maintain-gitea-rust-cache.py b/scripts/maintain-gitea-rust-cache.py
new file mode 100644
index 000000000..1219fc3a1
--- /dev/null
+++ b/scripts/maintain-gitea-rust-cache.py
@@ -0,0 +1,909 @@
+#!/usr/bin/env python3
+"""宿主专用的 Rust 缓存维护器；仅使用 Python 标准库，不在 CI job 中运行。"""
+
+import argparse
+import contextlib
+import datetime
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import socket
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from gitea_cache_snapshot import ArtifactIdentity, ArtifactInput, merge_snapshots
+from gitea_cache_upload_cleanup import cleanup_upload_chunks
+
+
+IMAGE = re.compile(r"sha256:[0-9a-f]{64}\Z")
+SHA = re.compile(r"[0-9a-f]{40}\Z")
+LABEL = re.compile(r'(?m)^(\s*-\s*[\"\x27]?)genarrative-ci:docker://(sha256:[0-9a-f]{64})([\"\x27]?\s*)$')
+JOBS = {
+    "AI game creator shell Rust lane 1/2",
+    "AI game creator shell Rust lane 2/2",
+    "AI game creator shell Rust smoke",
+    "AI game creator shell Rust crates",
+    "Backend tests", "Native shell tests", "Frontend tests",
+    "Repository checks", "AI game creator shell web tests",
+}
+RUST_JOB_IDS = {
+    "AI game creator shell Rust lane 1/2": "ai-game-creator-shell-rust-lane-1",
+    "AI game creator shell Rust lane 2/2": "ai-game-creator-shell-rust-lane-2",
+    "AI game creator shell Rust smoke": "ai-game-creator-shell-rust-smoke",
+    "AI game creator shell Rust crates": "ai-game-creator-shell-rust-crates",
+    "Backend tests": "backend-tests",
+    "Native shell tests": "native-shell-tests",
+}
+RUST_JOBS = set(RUST_JOB_IDS)
+ARTIFACT_PREFIX = "rust-cache-v1-"
+MAX_DOWNLOAD = 4 * 1024 ** 3 + 129 * 1024 ** 2
+EXPORT_STEP = "Publish master Rust cache artifact"
+
+
+def now():
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def timestamp(value):
+    return datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def log(message):
+    print(f"[cache-maintenance] {message}", flush=True)
+
+
+@contextlib.contextmanager
+def operation(name, *, build_log=None):
+    """Record long maintenance stages without exposing command arguments or API data."""
+    started = time.monotonic()
+    location = f"; build log={build_log}" if build_log is not None else ""
+    log(f"{name}: started{location}")
+    try:
+        yield
+    except Exception:
+        elapsed = time.monotonic() - started
+        log(f"{name}: failed after {elapsed:.1f}s{location}")
+        raise
+    else:
+        elapsed = time.monotonic() - started
+        log(f"{name}: completed in {elapsed:.1f}s")
+
+
+def command(*args, cwd=None, data=None, env=None, output=None, timeout=120, combined=False):
+    result = subprocess.run(
+        args, cwd=cwd, input=data, text=True, env=env, timeout=timeout,
+        stdout=output or subprocess.PIPE,
+        stderr=output or (subprocess.STDOUT if combined else subprocess.PIPE),
+    )
+    if result.returncode:
+        # 参数、stderr 或 HTTP body 可能含凭据，只把详细构建输出写到私有日志。
+        raise RuntimeError(f"{Path(args[0]).name} failed (exit {result.returncode})")
+    return result.stdout or ""
+
+
+def atomic_json(path, value):
+    temporary = path.with_suffix(".tmp")
+    with temporary.open("w", encoding="utf-8") as out:
+        json.dump(value, out, ensure_ascii=False, indent=2)
+        out.write("\n")
+        out.flush()
+        os.fsync(out.fileno())
+    temporary.replace(path)
+    if os.name == "posix":
+        directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+
+
+def cache_inputs(tree):
+    """只排除已知不参与构建的说明文档；docs/openapi 与内嵌 skill 必须参与。"""
+    rows = []
+    for row in (tree.split("\0") if "\0" in tree else tree.splitlines()):
+        if not row:
+            continue
+        path = row.split("\t", 1)[1]
+        if path.startswith("docs/") and not path.startswith("docs/openapi/"):
+            continue
+        if path in {"AGENTS.md", "README.md", "deploy/container/README.md"}:
+            continue
+        rows.append(row)
+    return hashlib.sha256("\n".join(rows).encode()).hexdigest()
+
+
+def configured_image(config):
+    labels = list(LABEL.finditer(config))
+    if len(labels) != 1:
+        raise RuntimeError("expected exactly one genarrative-ci Image ID label")
+    return labels[0].group(2)
+
+
+def replace_image(config, old, new):
+    if not IMAGE.fullmatch(new) or configured_image(config) != old:
+        raise RuntimeError("runner image changed outside maintenance; refusing overwrite")
+    return LABEL.sub(lambda match: match[1] + "genarrative-ci:docker://" + new + match[3], config)
+
+
+def fully_passed(run, jobs):
+    return (
+        run.get("status") == "completed" and run.get("conclusion") == "success"
+        and len(jobs) == len(JOBS) and {job["name"] for job in jobs} == JOBS
+        and all(job.get("conclusion") == "success" for job in jobs)
+    )
+
+
+def verifies_image(job, contents, image, require_cache=True):
+    if not re.search(r"(?m)^\S+ image: " + re.escape(image) + r"\s*$", contents):
+        return False
+    if not require_cache or job["name"] not in RUST_JOBS:
+        return True
+    # 旧分支使用了镜像却未 prepare，不算完成缓存上线验收。
+    hits = re.search(r"Cache hits\s+(\d+)\s*$", contents, re.M)
+    errors = [re.search(rf"{name}\s+(\d+)\s*$", contents, re.M)
+              for name in ("Cache errors", "Cache read errors", "Cache write errors")]
+    return ("[rust-cache] mode=sccache" in contents and hits is not None
+            and int(hits[1]) > 0 and all(item and int(item[1]) == 0 for item in errors))
+
+
+class Api:
+    def __init__(self, url, token_file):
+        self.url = url.rstrip("/")
+        if not self.url.startswith("https://"):
+            raise ValueError("api_url must use HTTPS")
+        self.token_file = Path(token_file)
+
+    def request(self, path, *, method, body=None, raw=False):
+        token = self.token_file.read_text().strip()
+        if not token or "\n" in token:
+            raise ValueError("invalid token file")
+        request = urllib.request.Request(
+            self.url + "/" + path.lstrip("/"),
+            data=None if body is None else json.dumps(body).encode(),
+            method=method,
+            headers={"Authorization": "token " + token, "Content-Type": "application/json"},
+        )
+        try:
+            # 不允许带 Authorization 的请求跟随跨站重定向。
+            opener = urllib.request.build_opener(NoRedirect())
+            with opener.open(request, timeout=30) as response:
+                content = response.read().decode()
+        except urllib.error.HTTPError as error:
+            error.close()
+            if method == "DELETE" and error.code == 404:
+                return None
+            raise RuntimeError(f"Gitea API HTTP {error.code}") from None
+        return content if raw else (json.loads(content) if content else None)
+
+    def download(self, path, destination):
+        """REST V4 archive redirects to a signed URL; never forward the API token."""
+        token = self.token_file.read_text().strip()
+        url = self.url + "/" + path.lstrip("/")
+        opener = urllib.request.build_opener(NoRedirect())
+        request = urllib.request.Request(url, headers={"Authorization": "token " + token})
+        try:
+            response = opener.open(request, timeout=60)
+        except urllib.error.HTTPError as error:
+            error.close()
+            if error.code not in (301, 302, 303, 307, 308):
+                raise RuntimeError(f"artifact download HTTP {error.code}") from None
+            target = urllib.parse.urljoin(url, error.headers.get("Location", ""))
+            parsed, origin = urllib.parse.urlsplit(target), urllib.parse.urlsplit(self.url)
+            if (parsed.scheme != "https" or parsed.netloc != origin.netloc
+                    or parsed.username or parsed.password or target == url):
+                raise RuntimeError("artifact redirect must stay on configured HTTPS Gitea origin") from None
+            response = opener.open(target, timeout=60)
+        try:
+            with response, destination.open("wb") as out:
+                total = 0
+                while chunk := response.read(1024 * 1024):
+                    total += len(chunk)
+                    if total > MAX_DOWNLOAD:
+                        raise RuntimeError("artifact exceeds per-job size limit")
+                    out.write(chunk)
+        except Exception:
+            destination.unlink(missing_ok=True)
+            raise
+
+    def pages(self, path, key):
+        separator = "&" if "?" in path else "?"
+        page = 1
+        while True:
+            response = self.request(f"{path}{separator}limit=50&page={page}", method="GET")
+            items = response[key]
+            yield from items
+            if len(items) < 50:
+                return
+            page += 1
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class Maintenance:
+    def __init__(self, config):
+        self.config = config
+        if not Path(config["state_dir"]).is_absolute():
+            raise ValueError("state_dir must be a dedicated absolute directory")
+        self.root = Path(config["state_dir"]).resolve()
+        if self.root == Path("/"):
+            raise ValueError("state_dir must be a dedicated absolute directory")
+        self.repo = self.root / "source"
+        self.runner = config.get("runner_container", "gitea-runner")
+        self.api = Api(config["api_url"], config["token_file"])
+        self.repo_api = "repos/" + config["repository"]
+        self.state_path = self.root / "state.json"
+        self.state = json.loads(self.state_path.read_text()) if self.state_path.exists() else {
+            "versions": [], "current": None, "rollback": None, "candidate": None,
+        }
+
+    def save(self):
+        atomic_json(self.state_path, self.state)
+
+    def docker(self, *args, inner=False, **kwargs):
+        prefix = ("docker", "exec", self.runner, "docker") if inner else ("docker",)
+        return command(*prefix, *args, **kwargs)
+
+    def image_info(self, image, inner=False):
+        return json.loads(self.docker("image", "inspect", image, inner=inner))[0]
+
+    def read_config(self):
+        return self.docker("exec", self.runner, "cat", "/data/config.yaml")
+
+    def write_config(self, content):
+        self.docker("exec", "--user", "0", "-i", self.runner, "sh", "-c",
+                    "cat > /data/config.yaml", data=content)
+
+    def version(self, image):
+        return next(row for row in self.state["versions"] if row["image"] == image)
+
+    def adopt_current(self):
+        actual = configured_image(self.read_config())
+        if self.state["current"]:
+            if actual != self.state["current"]:
+                raise RuntimeError("runner configuration differs from recorded current image")
+            return
+        info = self.image_info(actual)
+        labels = info["Config"].get("Labels") or {}
+        source = labels.get("world.genarrative.ci.rust-cache-source")
+        base = labels.get("world.genarrative.ci.rust-cache-base", actual)
+        if source is not None and not SHA.fullmatch(source):
+            raise RuntimeError("invalid image source SHA")
+        self.state["versions"].append({
+            "image": actual, "source": source, "base": base, "owned": False,
+            "activated": "1970-01-01T00:00:00+00:00", "verified_run": None,
+        })
+        self.state["current"] = actual
+        self.save()
+
+    def fetch_source(self):
+        if self.repo.resolve() != self.repo:
+            raise RuntimeError("dedicated clone must not be a symlink")
+        marker = self.repo / ".git" / "genarrative-cache-maintenance"
+        if not (self.repo / ".git").exists():
+            if self.repo.exists():
+                raise RuntimeError("source directory already exists without .git")
+            command("git", "clone", "--no-checkout", self.config["clone_url"], str(self.repo), timeout=900)
+            marker.write_text("owned source checkout\n")
+        if not marker.is_file():
+            raise RuntimeError("refusing to clean a checkout not created by this maintainer")
+        if command("git", "remote", "get-url", "origin", cwd=self.repo).strip() != self.config["clone_url"]:
+            raise RuntimeError("dedicated clone origin differs from configured repository")
+        command("git", "fetch", "--no-tags", "origin", "refs/heads/master", cwd=self.repo, timeout=900)
+        sha = command("git", "rev-parse", "FETCH_HEAD^{commit}", cwd=self.repo).strip()
+        if not SHA.fullmatch(sha):
+            raise RuntimeError("invalid master SHA")
+        # 这是维护器专属 clone，不修改开发者工作区；编译期间不再 checkout 新提交。
+        command("git", "checkout", "--detach", "--force", sha, cwd=self.repo)
+        command("git", "clean", "-ffdx", cwd=self.repo)
+        tree = command("git", "ls-tree", "-rz", sha, cwd=self.repo)
+        return sha, cache_inputs(tree)
+
+    def build_command(self, log_file, script, *args, env=None, description=None):
+        with operation(description or f"run {script}", build_log=log_file):
+            with log_file.open("a") as out:
+                command("bash", str(self.repo / "scripts" / script), *args, cwd=self.repo,
+                        env=env, output=out, timeout=7200)
+
+    def master_run(self, run):
+        return (run.get("path") == "project-ci.yml@refs/heads/master"
+                and run.get("event") == "push" and run.get("head_branch") == "master"
+                and SHA.fullmatch(run.get("head_sha", "")) is not None)
+
+    def source_run(self):
+        """Only complete exports from the latest eligible master run; never mix runs."""
+        current = self.version(self.state["current"])
+        current_inputs = (cache_inputs(command("git", "ls-tree", "-rz", current["source"], cwd=self.repo))
+                          if current.get("source") else None)
+        for run in self.api.pages(self.repo_api + "/actions/runs?branch=master&event=push", "workflow_runs"):
+            if (not self.master_run(run) or run.get("status") != "completed"
+                    or run.get("conclusion") not in {"success", "failure"}
+                    or run["id"] <= current.get("run_id", 0)):
+                continue
+            sha = run["head_sha"]
+            if sha == current.get("source"):
+                continue
+            ancestry = subprocess.run(["git", "merge-base", "--is-ancestor", sha, "FETCH_HEAD"],
+                                      cwd=self.repo, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            if ancestry.returncode:
+                continue
+            if current.get("source"):
+                ancestry = subprocess.run(["git", "merge-base", "--is-ancestor", current["source"], sha],
+                                          cwd=self.repo, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                if ancestry.returncode:
+                    continue
+            inputs = cache_inputs(command("git", "ls-tree", "-rz", sha, cwd=self.repo))
+            if inputs == current_inputs:
+                continue
+            jobs = list(self.api.pages(self.repo_api + f'/actions/runs/{run["id"]}/jobs', "jobs"))
+            rust_jobs = [job for job in jobs if job["name"] in RUST_JOB_IDS]
+            if len(rust_jobs) != len(RUST_JOB_IDS) or {job["name"] for job in rust_jobs} != RUST_JOBS:
+                continue
+            if any(job.get("status") != "completed" or job.get("conclusion") not in {"success", "failure"}
+                   or job.get("head_sha") != sha
+                   or not any(step.get("name") == EXPORT_STEP and step.get("conclusion") == "success"
+                              for step in job.get("steps", [])) for job in rust_jobs):
+                continue
+            artifacts = list(self.api.pages(self.repo_api + f'/actions/runs/{run["id"]}/artifacts', "artifacts"))
+            selected = []
+            images = set()
+            for job in rust_jobs:
+                name = f'{ARTIFACT_PREFIX}{RUST_JOB_IDS[job["name"]]}-attempt-{job["run_attempt"]}'
+                matches = [item for item in artifacts if item["name"] == name and not item.get("expired")
+                           and item.get("workflow_run", {}).get("id") == run["id"]]
+                if len(matches) != 1:
+                    break
+                content = self.api.request(self.repo_api + f'/actions/jobs/{job["id"]}/logs', method="GET", raw=True)
+                if not re.search(re.escape(f"[rust-cache] artifact={name}")
+                                 + r" objects=\d+ bytes=\d+ complete=true", content):
+                    break
+                used = set(re.findall(r"(?m)^\S+ image: (sha256:[0-9a-f]{64})\s*$", content))
+                if len(used) != 1:
+                    break
+                images.update(used)
+                selected.append({"id": matches[0]["id"], "name": name,
+                                 "job": RUST_JOB_IDS[job["name"]], "attempt": job["run_attempt"]})
+            if len(selected) != len(RUST_JOB_IDS) or len(images) != 1:
+                continue
+            source_image = images.pop()
+            if source_image not in {row["image"] for row in self.state["versions"]}:
+                continue
+            return {"run_id": run["id"], "source": sha, "inputs": inputs, "source_image": source_image,
+                    "exports": selected}
+        return None
+
+    def build(self, source):
+        """Assemble existing CI objects; no cargo warm-up or test execution."""
+        sha = source["source"]
+        command("git", "checkout", "--detach", "--force", sha, cwd=self.repo)
+        command("git", "clean", "-ffdx", cwd=self.repo)
+        artifact = self.root / "artifacts" / sha
+        artifact.mkdir(parents=True, exist_ok=True)
+        build_log = artifact / "build.log"
+        tag = "genarrative/gitea-project-ci:rust-cache-auto-" + sha
+        base_tag = "genarrative/gitea-project-ci:base-auto-" + sha
+        attempt = {**source, "tag": tag, "base_tag": base_tag, "artifact": str(artifact)}
+        self.state.setdefault("attempts", []).append(attempt)
+        self.save()
+        env = {**os.environ, "GENARRATIVE_GITEA_RUNNER_CONTAINER": self.runner}
+        env.pop("CI", None)
+        labels = self.image_info(source["source_image"])["Config"].get("Labels") or {}
+        inherited_source = labels.get("world.genarrative.ci.rust-cache-source")
+        base = labels.get("world.genarrative.ci.rust-cache-base")
+        if not IMAGE.fullmatch(base or "") or not SHA.fullmatch(inherited_source or ""):
+            raise RuntimeError("source image must contain a trusted cache snapshot")
+        revision = command("bash", "scripts/gitea-ci-job-image.sh", "revision", cwd=self.repo).strip()
+        base_labels = self.image_info(base)["Config"].get("Labels") or {}
+        if base_labels.get("com.genarrative.ci.definition-sha256") != revision:
+            env["GENARRATIVE_GITEA_CI_IMAGE_TAG"] = base_tag
+            self.build_command(build_log, "gitea-ci-job-image.sh", "build", env=env,
+                               description="rebuild cache base image")
+            base = self.image_info(base_tag)["Id"]
+            self.state.setdefault("bases", {})[base] = base_tag
+            self.save()
+        else:
+            log("reuse compatible cache base image")
+        # 与旧缓存镜像分离；绝不把 Docker 可写层、源码或 target commit 成镜像。
+        with operation("validate cache base image", build_log=build_log):
+            self.docker("run", "--rm", "--network", "none", "--read-only", "--cap-drop=ALL",
+                        "--entrypoint", "bash", base, "-c", "test ! -e /opt/genarrative-ci/rust-cache")
+        with tempfile.TemporaryDirectory(prefix="assemble-", dir=artifact) as temporary:
+            work = Path(temporary)
+            inherited = work / "inherited"
+            inherited.mkdir()
+            container = self.docker("create", source["source_image"]).strip()
+            try:
+                self.docker("cp", container + ":/opt/genarrative-ci/rust-cache/.", str(inherited), timeout=600)
+            finally:
+                self.docker("rm", "--volumes", container)
+            inputs = []
+            for export in source["exports"]:
+                archive = work / (str(export["id"]) + ".zip")
+                with operation(f"download cache artifact job={export['job']} attempt={export['attempt']}",
+                               build_log=build_log):
+                    self.api.download(self.repo_api + f'/actions/artifacts/{export["id"]}/zip', archive)
+                inputs.append(ArtifactInput(archive, ArtifactIdentity(
+                    self.config["repository"], source["run_id"], export["attempt"], export["job"], sha)))
+            snapshot = work / "snapshot"
+            with operation(f"merge {len(inputs)} cache artifacts", build_log=build_log):
+                merged = merge_snapshots(inputs, snapshot, base_objects=inherited / "objects",
+                                         expected_inherited_source_sha=inherited_source)
+            if merged.sccache_version != "sccache 0.18.0":
+                raise RuntimeError("unsupported sccache version")
+            if merged.base_image is not None and merged.base_image != labels["world.genarrative.ci.rust-cache-base"]:
+                raise RuntimeError("artifact base differs from its actual source image")
+            with operation("validate merged snapshot against target image", build_log=build_log):
+                rustc = self.docker("run", "--rm", "--network", "none", "--read-only", base, "rustc", "-vV")
+                if rustc.strip() != merged.rustc.strip():
+                    raise RuntimeError("artifact toolchain differs from target base image")
+                if merged.workspace != "/workspace/" + self.config["repository"]:
+                    raise RuntimeError("artifact workspace differs from CI checkout")
+            shutil.copyfile(inherited / "sccache", snapshot / "sccache")
+            (snapshot / "sccache").chmod(0o755)
+            (snapshot / "base-image.txt").write_text(base + "\n")
+            (work / "Dockerfile").write_text(
+                f"FROM {base}\nCOPY snapshot/ /opt/genarrative-ci/rust-cache/\n"
+                f'LABEL world.genarrative.ci.rust-cache-source="{sha}"\n'
+                f'LABEL world.genarrative.ci.rust-cache-base="{base}"\n')
+            (work / ".dockerignore").write_text("**\n!Dockerfile\n!snapshot/\n!snapshot/**\n")
+            with operation("assemble cache candidate image", build_log=build_log):
+                with build_log.open("a") as out:
+                    self.docker("build", "--pull=false", "--tag", tag, str(work), output=out, timeout=1800)
+            self.build_command(build_log, "gitea-ci-job-image.sh", "verify", tag, env=env,
+                               description="verify cache candidate image")
+        image = self.image_info(tag)["Id"]
+        self.state["versions"].append({**attempt, "image": image, "base": base,
+                                        "owned": True, "verified_run": None})
+        self.state["candidate"] = image
+        self.state["attempts"] = [row for row in self.state["attempts"] if row["source"] != sha]
+        self.save()
+        log(f"candidate assembled run={source['run_id']} source={sha} image={image}")
+
+    def stage_candidate(self):
+        candidate = self.version(self.state["candidate"])
+        command("git", "checkout", "--detach", "--force", candidate["source"], cwd=self.repo)
+        command("git", "clean", "-ffdx", cwd=self.repo)
+        artifact = Path(candidate["artifact"])
+        archive = artifact / "image.tar.zst"
+        sidecar = archive.with_suffix(".zst.sha256")
+        if (candidate.get("staged") and archive.is_file() and sidecar.is_file()
+                and candidate["image"] in self.docker("image", "ls", "--all", "--no-trunc", "--quiet", inner=True).split()):
+            log("reuse exported and loaded candidate image")
+            return
+        env = {**os.environ, "GENARRATIVE_GITEA_RUNNER_CONTAINER": self.runner}
+        build_log = artifact / "build.log"
+        if not sidecar.exists():
+            # 只删除登记目录中的未完成导出文件，不覆盖已验证归档。
+            archive.unlink(missing_ok=True)
+            self.build_command(build_log, "gitea-ci-job-image.sh", "export", str(archive), candidate["image"], env=env,
+                               description="export cache candidate image")
+        with operation("validate exported cache candidate image", build_log=build_log):
+            command("sha256sum", "--check", sidecar.name, cwd=artifact, timeout=600)
+        self.build_command(build_log, "gitea-ci-job-image.sh", "load-runner", candidate["image"], env=env,
+                           description="load cache candidate image into runner")
+        with operation("verify loaded cache candidate image", build_log=build_log):
+            if self.image_info(candidate["image"], inner=True)["Id"] != candidate["image"]:
+                raise RuntimeError("inner runner image mismatch")
+        candidate["staged"] = True
+        self.save()
+
+    def idle(self):
+        gate = self.gate("status")
+        if type(gate.get("active_tasks")) is not int or gate["active_tasks"] < 0:
+            raise RuntimeError("gate must support durable task tracking before automatic switching")
+        # 已领取但尚未建容器、正在收尾上报的任务都由入口跟踪，不查管理员 API。
+        return (gate.get("uncertain") is False and gate.get("active_tasks") == 0
+                and not self.docker("ps", "-q", "--filter", "status=running",
+                                    "--filter", "status=created", "--filter", "status=restarting",
+                                    "--filter", "status=paused", inner=True).strip())
+
+    def wait_for_idle(self, purpose):
+        with operation(f"wait for idle runner before {purpose}"):
+            ready = self.idle()
+        if not ready:
+            log(f"runner is busy; defer {purpose}")
+        return ready
+
+    def verify_current(self):
+        current = self.version(self.state["current"])
+        if current.get("verified_run"):
+            return True
+        for run in self.api.pages(self.repo_api + "/actions/runs?status=success&branch=master&event=push", "workflow_runs"):
+            if run.get("path") != "project-ci.yml@refs/heads/master" or run.get("event") != "push":
+                continue
+            sha = run.get("head_sha", "")
+            if not SHA.fullmatch(sha):
+                continue
+            ancestry = subprocess.run(["git", "merge-base", "--is-ancestor", sha, "FETCH_HEAD"],
+                                      cwd=self.repo, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            if ancestry.returncode != 0:
+                continue
+            if timestamp(run["started_at"]) < timestamp(current["activated"]):
+                continue
+            jobs = list(self.api.pages(self.repo_api + f'/actions/runs/{run["id"]}/jobs', "jobs"))
+            if not fully_passed(run, jobs):
+                continue
+            if all(verifies_image(job, self.api.request(
+                self.repo_api + f'/actions/jobs/{job["id"]}/logs', method="GET", raw=True), current["image"],
+                require_cache=current.get("source") is not None,
+            ) for job in jobs):
+                current["verified_run"] = run["id"]
+                current["verified_sha"] = sha
+                self.save()
+                log(f'current image verified by run={run["id"]}')
+                return True
+        log("waiting for a complete successful CI run using current image and cache")
+        return False
+
+    def protected_images(self):
+        protected = {self.state[key] for key in ("current", "rollback", "candidate") if self.state.get(key)}
+        for image in list(protected):
+            protected.add(self.version(image)["base"])
+        # 保护包括已停止容器在内的全部引用；不强制删除被 Docker 引用的镜像。
+        for inner in (False, True):
+            ids = self.docker("ps", "-aq", inner=inner).split()
+            for container in ids:
+                protected.add(self.docker("inspect", "--format", "{{.Image}}", container, inner=inner).strip())
+        protected.add(configured_image(self.read_config()))
+        return protected
+
+    def remove_owned_image(self, image, tag, protected):
+        if image in protected or not IMAGE.fullmatch(image):
+            return False
+        for inner in (True, False):
+            available = self.docker("image", "ls", "--all", "--no-trunc", "--quiet", inner=inner).split()
+            if image not in available:
+                continue
+            info = self.image_info(image, inner=inner)
+            if not set(info.get("RepoTags") or []).issubset({tag}):
+                log(f"retain image with additional tags: {image}")
+                return False
+            # 不使用 --force；并发创建的容器也由 Docker 的引用检查保护。
+            self.docker("image", "rm", image, inner=inner)
+            if image in self.docker("image", "ls", "--all", "--no-trunc", "--quiet", inner=inner).split():
+                raise RuntimeError("managed image is still present after removal")
+        return True
+
+    def cleanup(self):
+        if not self.version(self.state["current"]).get("verified_run"):
+            return
+        protected = self.protected_images()
+        for record in list(self.state["versions"]):
+            if not record.get("owned") or record["image"] in protected:
+                continue
+            expected = self.root / "artifacts" / record["source"]
+            if (not SHA.fullmatch(record["source"]) or Path(record["artifact"]).resolve() != expected
+                    or expected.is_symlink() or expected.parent.is_symlink()
+                    or record["tag"] != "genarrative/gitea-project-ci:rust-cache-auto-" + record["source"]):
+                raise RuntimeError("archive path outside managed source directory")
+            if not self.remove_owned_image(record["image"], record["tag"], protected):
+                continue
+            # 不递归删除目录，只删除本维护器创建的已知文件。
+            for name in ("image.tar.zst", "image.tar.zst.sha256", "build.log"):
+                (expected / name).unlink(missing_ok=True)
+            if expected.exists() and not any(expected.iterdir()):
+                expected.rmdir()
+            self.state["versions"].remove(record)
+            self.save()
+            log(f'removed old managed snapshot {record["image"]}')
+        for image, tag in list(self.state.get("bases", {}).items()):
+            used_bases = {row["base"] for row in self.state["versions"]}
+            if image not in used_bases and self.remove_owned_image(image, tag, protected):
+                del self.state["bases"][image]
+                self.save()
+
+    def cleanup_exports(self):
+        """Only our named artifacts; keep logs/runs and every unrelated artifact."""
+        protected_runs = {row["run_id"] for row in self.state.get("attempts", []) if row.get("run_id")}
+        for row in self.state["versions"]:
+            if row.get("run_id") and not row.get("staged"):
+                protected_runs.add(row["run_id"])
+            if not row.get("staged"):
+                continue
+            for item in row.get("exports", []):
+                if item.get("deleted"):
+                    continue
+                self.api.request(self.repo_api + f'/actions/artifacts/{item["id"]}', method="DELETE")
+                item["deleted"] = True
+                self.save()
+        cutoff = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=7)
+        # 先收集再删除，避免按页删除让下一页位置前移、漏掉旧产物。
+        artifacts = list(self.api.pages(self.repo_api + "/actions/artifacts", "artifacts"))
+        pattern = re.compile(re.escape(ARTIFACT_PREFIX) + "(" + "|".join(RUST_JOB_IDS.values())
+                             + r")-attempt-\d+\Z")
+        runs = {}
+        for item in artifacts:
+            run_id = (item.get("workflow_run") or {}).get("id")
+            if (not pattern.fullmatch(item["name"]) or not run_id or run_id in protected_runs
+                    or timestamp(item["created_at"]) >= cutoff):
+                continue
+            # Artifact.workflow_run 在 Gitea 1.26.4 中只有 id/repository_id/head_sha。
+            if run_id not in runs:
+                runs[run_id] = self.api.request(self.repo_api + f"/actions/runs/{run_id}", method="GET")
+            run = runs[run_id]
+            if not self.master_run(run) or run.get("status") != "completed":
+                continue
+            self.api.request(self.repo_api + f'/actions/artifacts/{item["id"]}', method="DELETE")
+
+    def cleanup_pending_uploads(self):
+        # Gitea 1.26.4 的过期/DELETE API 不会清理未 finalized 的 V4 分块。
+        # 只处理本上传器命名的块，且 run 和文件本身均已过保留期限。
+        cutoff = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=7)
+        eligible = set()
+        protected = {row["run_id"] for row in self.state.get("attempts", []) if row.get("run_id")}
+        for run in self.api.pages(self.repo_api + "/actions/runs?branch=master&event=push", "workflow_runs"):
+            if (self.master_run(run) and run.get("status") == "completed"
+                    and run["id"] not in protected and run.get("completed_at")
+                    and timestamp(run["completed_at"]) < cutoff):
+                eligible.add(run["id"])
+        removed = cleanup_upload_chunks(Path(self.config["artifact_storage_dir"]), eligible, cutoff.timestamp())
+        if removed:
+            log(f"removed {removed} expired owned upload fragments")
+
+    def tick(self, retry=False):
+        if not self.recover_switch():
+            return
+        self.adopt_current()
+        self.fetch_source()
+        self.recover_builds()
+        self.cleanup_exports()
+        self.cleanup_pending_uploads()
+        if not self.verify_current():
+            return
+        self.cleanup()
+        if self.state.get("candidate"):
+            self.stage_candidate()
+            self.activate()
+            return
+        source = self.source_run()
+        if source is None:
+            log("waiting for a complete set of master CI cache exports")
+            return
+        log(f"selected cache source run={source['run_id']} source={source['source']}")
+        if not retry and self.state.get("failed_run") == source["run_id"]:
+            log(f'previous assembly failed at run={source["run_id"]}; waiting for new run or --retry')
+            return
+        # 下载、合并和镜像装载也消耗宿主 IO；繁忙时留给 CI，下轮再收集。
+        if not self.wait_for_idle("cache assembly"):
+            return
+        try:
+            self.build(source)
+        except Exception:
+            self.state["failed_run"] = source["run_id"]
+            self.save()
+            raise
+        self.state.pop("failed_run", None)
+        self.save()
+        self.stage_candidate()
+        self.cleanup_exports()
+        self.activate()
+
+    def recover_builds(self):
+        # 宕机可能发生在 docker build 完成之后、登记 Image ID 之前。
+        # 只接管预先登记的确定性 tag；恢复的候选仍须经过 stage 的 verify/load。
+        for attempt in list(self.state.get("attempts", [])):
+            artifact = self.root / "artifacts" / attempt["source"]
+            if (not SHA.fullmatch(attempt["source"]) or Path(attempt["artifact"]).resolve() != artifact
+                    or artifact.is_symlink() or artifact.parent.is_symlink()):
+                raise RuntimeError("interrupted assembly directory is outside managed artifacts")
+            # 持有维护锁，只有此前中断的组装可能遗留这些私有工作目录。
+            for directory in artifact.glob("assemble-*"):
+                if directory.is_symlink() or not directory.is_dir():
+                    raise RuntimeError("unexpected interrupted assembly entry")
+                shutil.rmtree(directory)
+            for kind in ("base_tag", "tag"):
+                ids = set(self.docker("image", "ls", "--no-trunc", "--quiet", attempt[kind]).split())
+                if not ids:
+                    continue
+                if len(ids) != 1:
+                    raise RuntimeError("ambiguous managed build tag")
+                image = ids.pop()
+                if kind == "base_tag":
+                    self.state.setdefault("bases", {})[image] = attempt[kind]
+                elif not any(row["image"] == image for row in self.state["versions"]):
+                    labels = self.image_info(image)["Config"].get("Labels") or {}
+                    if labels.get("world.genarrative.ci.rust-cache-source") != attempt["source"]:
+                        raise RuntimeError("interrupted build tag has unexpected source")
+                    self.state["versions"].append({
+                        **attempt, "image": image, "owned": True, "verified_run": None,
+                        "base": labels["world.genarrative.ci.rust-cache-base"],
+                    })
+                    if self.state.get("candidate") not in (None, image):
+                        raise RuntimeError("interrupted build conflicts with an existing candidate")
+                    self.state["candidate"] = image
+            self.state["attempts"].remove(attempt)
+            self.save()
+
+    def recover_switch(self):
+        if self.state.get("switch"):
+            # 不能仅凭配置文件已经替换，就认定内存中的 runner 已加载新映射。
+            log("recovering interrupted image switch")
+            return self.activate()
+        if self.state.get("pause_owned"):
+            self.resume()
+        return True
+
+    def resume(self):
+        if self.state.get("pause_owned"):
+            if self.gate("resume").get("paused") is not False:
+                raise RuntimeError("runner resume could not be confirmed")
+            self.state.pop("pause_owned", None)
+            self.save()
+
+    def gate(self, action):
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.settimeout(10)
+            client.connect(self.config["gate_socket"])
+            client.sendall((json.dumps({"action": action}) + "\n").encode())
+            with client.makefile("rb") as stream:
+                response = json.loads(stream.readline(4096))
+        if "error" in response:
+            raise RuntimeError("runner gate refused command")
+        return response
+
+    def check_gate_route(self):
+        checkout = re.search(r"(?m)^\s+GENARRATIVE_GITEA_REPOSITORY_URL:\s*(.+?)\s*$", self.read_config())
+        if not checkout or checkout[1].strip("\"'") != self.config["repository_url"]:
+            raise RuntimeError("runner.envs must pin GENARRATIVE_GITEA_REPOSITORY_URL independently of the RPC gate")
+        # .runner 含认证材料，只在进程内取 address，不回显原文。
+        registration = json.loads(self.docker("exec", self.runner, "cat", "/data/.runner"))
+        if registration.get("address", "").rstrip("/") != self.config["gate_url"].rstrip("/"):
+            raise RuntimeError("runner is not configured to use the FetchTask gate")
+        info = json.loads(self.docker("inspect", self.runner))[0]
+        started = timestamp(info["State"]["StartedAt"]).timestamp()
+        addresses = {network["IPAddress"] for network in info["NetworkSettings"]["Networks"].values()}
+        gate = self.gate("status")
+        # .runner 会因 label 更新而回写；mtime 不能证明内存中的地址。
+        # 要求入口实际见到本次容器启动后、来自它的 FetchTask。
+        if gate.get("last_fetch_peer") not in addresses or (gate.get("last_fetch_at") or 0) < started:
+            raise RuntimeError("gate has not observed FetchTask from this runner startup")
+        if type(gate.get("active_tasks")) is not int or gate["active_tasks"] < 0:
+            raise RuntimeError("gate must support durable task tracking before automatic switching")
+
+    def activate(self):
+        self.check_gate_route()
+        candidate = self.version(self.state["candidate"])
+        config = self.read_config()
+        gate = self.gate("status")
+        if gate.get("paused") is not False and not self.state.get("pause_owned"):
+            log("runner gate paused by operator; defer switch")
+            return False
+        if not self.state.get("switch") and not self.wait_for_idle("runner switch"):
+            log("CI active; candidate stays staged")
+            return False
+        # 先持久化恢复意图；控制请求超时也可能已生效，ExecStopPost/下次 tick 会恢复。
+        self.state["pause_owned"] = True
+        self.save()
+        try:
+            if self.gate("pause").get("paused") is not True:
+                raise RuntimeError("runner pause could not be confirmed")
+            # 不用 FetchTask 客户端超时猜测服务端事务是否已经结束。
+            # 入口必须完整读完已转发的响应；不确定时拒绝自动重启。
+            with operation("wait for FetchTask completion before runner switch"):
+                for _ in range(30):
+                    gate = self.gate("status")
+                    if gate.get("uncertain"):
+                        raise RuntimeError("in-flight FetchTask completion is uncertain; manual gate inspection required")
+                    if gate.get("paused") is not True:
+                        raise RuntimeError("runner gate unexpectedly resumed")
+                    if gate.get("inflight") == 0:
+                        break
+                    time.sleep(1)
+                else:
+                    log("FetchTask still in flight; defer switch")
+                    return False
+            if not self.wait_for_idle("runner restart"):
+                log("in-flight task appeared; defer switch without stopping runner")
+                return False
+            latest_config = self.read_config()
+            if latest_config != config:
+                raise RuntimeError("runner config changed while pausing")
+            pending = self.state.get("switch")
+            if pending is None:
+                old = self.state["current"]
+                updated = replace_image(config, old, candidate["image"])
+                backup = self.root / "backups" / (candidate["source"] + ".yaml")
+                backup.parent.mkdir(parents=True, exist_ok=True)
+                backup.write_text(config)
+                pending = {"old": old, "new": candidate["image"], "backup": str(backup)}
+                self.state["switch"] = pending
+                self.save()
+            else:
+                actual = configured_image(config)
+                if actual not in {pending["old"], pending["new"]}:
+                    raise RuntimeError("interrupted switch conflicts with operator configuration")
+                updated = replace_image(config, actual, pending["new"])
+            self.write_config(updated)
+            if self.read_config() != updated or not self.idle():
+                # 配置尚未重启加载，恢复旧文件即可；不干扰意外出现的 job。
+                self.write_config(Path(pending["backup"]).read_text())
+                self.state.pop("switch", None)
+                self.save()
+                log("idle check changed before restart; restored configuration")
+                return False
+            with operation("restart runner with cache candidate image"):
+                self.docker("restart", "--timeout", "660", self.runner, timeout=720)
+            started = self.docker("inspect", "--format", "{{.State.StartedAt}}", self.runner).strip()
+            ready = False
+            with operation("wait for runner image registration"):
+                for _ in range(30):
+                    try:
+                        info = self.docker("inspect", "--format", "{{.State.Status}}", self.runner).strip()
+                        recent = self.docker("logs", "--since", started, self.runner, combined=True)
+                        ready = (info == "running" and "declare successfully" in recent
+                                 and self.image_info(candidate["image"], inner=True)["Id"] == candidate["image"])
+                    except RuntimeError:
+                        ready = False
+                    if ready:
+                        break
+                    time.sleep(2)
+                if not ready:
+                    raise RuntimeError("runner registration not confirmed; pending switch retained for recovery")
+            candidate["activated"] = now()
+            self.state["rollback"] = pending["old"]
+            self.state["current"] = pending["new"]
+            self.state["candidate"] = None
+            self.state.pop("switch", None)
+            self.save()
+            log(f'activated {candidate["image"]}; awaiting real master CI validation')
+            return True
+        finally:
+            # 持久化 switch 保证崩溃后不会错误宣称新镜像已验证。
+            self.resume()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--apply", action="store_true", help="执行维护；默认只检查连接和配置")
+    parser.add_argument("--retry", action="store_true", help="重试同一 master run 上失败的缓存组装")
+    parser.add_argument("--resume", action="store_true", help="仅恢复本维护器暂停的领取；用于 ExecStopPost")
+    args = parser.parse_args()
+    if os.environ.get("CI") == "true":
+        parser.error("run on the trusted host, outside CI jobs")
+    os.umask(0o077)
+    config = json.loads(Path(args.config).read_text())
+    maintenance = Maintenance(config)
+    if not args.apply and not args.resume:
+        maintenance.api.request(maintenance.repo_api + "/actions/artifacts?limit=1", method="GET")
+        image = configured_image(maintenance.read_config())
+        head = command("git", "ls-remote", config["clone_url"], "refs/heads/master").split()[0]
+        maintenance.check_gate_route()
+        cleanup_upload_chunks(Path(config["artifact_storage_dir"]), set(), time.time())
+        gate = maintenance.gate("status")
+        if gate.get("uncertain"):
+            raise RuntimeError("runner gate needs manual inspection")
+        log(f'check master={head} image={image} active_tasks={gate.get("active_tasks")}')
+        return
+    import fcntl  # Linux 宿主；纯逻辑测试仍可在 Windows 上导入。
+    maintenance.root.mkdir(parents=True, exist_ok=True)
+    with (maintenance.root / "maintenance.lock").open("a") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            log("another maintenance process holds the lock")
+            return
+        # 加锁后重新读取状态，避免另一个进程完成后覆盖旧快照。
+        maintenance = Maintenance(config)
+        if args.resume:
+            maintenance.resume()
+        else:
+            maintenance.tick(retry=args.retry)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        log(f"maintenance failed: {type(error).__name__}: {error}")
+        sys.exit(1)
diff --git a/scripts/project-ci-workflow.test.ts b/scripts/project-ci-workflow.test.ts
index 2dedd7980..6f793634a 100644
--- a/scripts/project-ci-workflow.test.ts
+++ b/scripts/project-ci-workflow.test.ts
@@ -142,23 +142,77 @@ function backendStepIndex(stepName: string) {
 }
 
 describe('project CI workflow', () => {
-  it('trials isolated compilation caching only in AGC Rust lane 1', () => {
-    const lane = jobSection('ai-game-creator-shell-rust-lane-1');
-    expect(lane).toContain('node --test scripts/ci-rust-cache.test.mjs');
-    expect(lane.indexOf('bash scripts/ci-rust-cache.sh prepare')).toBeLessThan(
-      lane.indexOf('npm run check:native-shells:agc-rust-shard-1'),
-    );
-    expect(
-      stepSection(
-        'ai-game-creator-shell-rust-lane-1',
-        'Report isolated Rust compilation cache',
-      ),
-    ).toContain('if: always()');
-    for (const job of jobNames.filter(
-      (name) => name !== 'ai-game-creator-shell-rust-lane-1',
-    )) {
-      expect(jobSection(job)).not.toContain('ci-rust-cache.sh');
+  it('publishes cache deltas only after Rust reporting on non-cancelled master pushes', () => {
+    const producers = [
+      'ai-game-creator-shell-rust-lane-1',
+      'ai-game-creator-shell-rust-lane-2',
+      'ai-game-creator-shell-rust-smoke',
+      'ai-game-creator-shell-rust-crates',
+      'backend-tests',
+      'native-shell-tests',
+    ];
+    for (const job of jobNames) {
+      if (!producers.includes(job)) {
+        expect(jobSection(job)).not.toContain('export-gitea-rust-cache.py');
+        continue;
+      }
+      const publish = stepSection(job, 'Publish master Rust cache artifact');
+      expect(publish).toContain(
+        "if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/master' }}",
+      );
+      expect(publish).toContain('GENARRATIVE_GITEA_TOKEN: ${{ github.token }}');
+      expect(publish).toContain('continue-on-error: true');
+      expect(publish).toContain(
+        'run: python3 scripts/export-gitea-rust-cache.py',
+      );
+      const section = jobSection(job);
+      expect(
+        section.indexOf('Publish master Rust cache artifact'),
+      ).toBeGreaterThan(
+        section.indexOf('run: bash scripts/ci-rust-cache.sh report'),
+      );
     }
+  });
+
+  it('uses isolated compilation caching for every Rust test job', () => {
+    const firstRustSteps = {
+      'ai-game-creator-shell-rust-lane-1':
+        'Run AI game creator shell Rust shard 1/4',
+      'ai-game-creator-shell-rust-lane-2':
+        'Run AI game creator shell Rust shard 3/4',
+      'ai-game-creator-shell-rust-smoke':
+        'Run AI game creator shell agent-run smoke',
+      'ai-game-creator-shell-rust-crates':
+        'Run AI game creator shell shared crate gates',
+      'backend-tests': 'Run server-rs workspace tests',
+      'native-shell-tests': 'Run native shell gates',
+    };
+    for (const job of jobNames) {
+      const section = jobSection(job);
+      if (!(job in firstRustSteps)) {
+        expect(section).not.toContain('ci-rust-cache.sh');
+        continue;
+      }
+      const firstRustStep = firstRustSteps[job as keyof typeof firstRustSteps];
+      const prepare = section.indexOf('bash scripts/ci-rust-cache.sh prepare');
+      expect(prepare).toBeGreaterThan(
+        section.indexOf('Checkout full history from Gitea'),
+      );
+      expect(prepare).toBeLessThan(section.indexOf(`- name: ${firstRustStep}`));
+      expect(
+        stepSection(job, 'Report isolated Rust compilation cache'),
+      ).toContain('if: always()');
+    }
+    // 缓存自身的行为测试只执行一次，避免随 job 数量重复运行。
+    expect(
+      workflow.match(/node --test scripts\/ci-rust-cache.test.mjs/g),
+    ).toHaveLength(1);
+    const releaseStep = stepSection(
+      'native-shell-tests',
+      'Run native shell release build smoke',
+    );
+    expect(releaseStep).toContain("RUSTC_WRAPPER: ''");
+    expect(releaseStep).toContain("CARGO_BUILD_RUSTC_WRAPPER: ''");
     expect(workflow).toContain("CARGO_INCREMENTAL: '0'");
     expect(workflow).toContain("RUSTC_WRAPPER: ''");
     for (const [, name, value] of workflow
@@ -170,6 +224,30 @@ describe('project CI workflow', () => {
     }
   });
 
+  it('warms backend targets without merging the SpacetimeDB feature boundary', () => {
+    const warmCommands = rustCacheBuildScript
+      .replace(/\\\r?\n/g, '')
+      .replace(/\s+/g, ' ');
+    for (const [, command] of jobSection('backend-tests').matchAll(
+      /run: (cargo [^\n]+)/g,
+    )) {
+      expect(warmCommands).toContain(command.trim());
+    }
+    expect(warmCommands).toContain(
+      'cargo test --locked --workspace --exclude spacetime-module --no-fail-fast --manifest-path server-rs/Cargo.toml --no-run',
+    );
+    expect(warmCommands).toContain(
+      'cargo test --locked -p spacetime-module --no-fail-fast --manifest-path server-rs/Cargo.toml --no-run',
+    );
+    expect(warmCommands).toContain('cd apps/ai-game-creator-shell/src-tauri');
+    expect(warmCommands).toContain(
+      'cd apps/ai-game-creator-shell cargo build --manifest-path src-tauri/Cargo.toml',
+    );
+    expect(warmCommands).toContain(
+      'cargo test --manifest-path apps/desktop-shell/src-tauri/Cargo.toml --no-run',
+    );
+  });
+
   it('runs for master pushes, pull requests, and manual dispatch only', () => {
     expect(workflow).toMatch(
       /on:\n {2}push:\n {4}branches:\n {6}- master\n {2}pull_request:\n {2}workflow_dispatch:/u,
@@ -285,7 +363,8 @@ describe('project CI workflow', () => {
     const rustLock = 'apps/ai-game-creator-shell/src-tauri/Cargo.lock';
 
     for (const workspaceManifest of workspaceManifests) {
-      expect(imageBuildScript.split(workspaceManifest)).toHaveLength(3);
+      // 构建上下文与 revision 共用一份清单，不重复枚举 manifest。
+      expect(imageBuildScript.split(workspaceManifest)).toHaveLength(2);
       expect(imageDockerignore).toContain(`!${workspaceManifest}`);
       expect(imageDockerfile).toContain(
         `COPY ${workspaceManifest} /usr/local/share/genarrative-ci/npm/${workspaceManifest}`,
@@ -293,16 +372,15 @@ describe('project CI workflow', () => {
     }
 
     for (const [path, expectedCount] of [
-      [rustManifest, 2],
-      [rustLock, 3],
+      [rustManifest, 1],
+      [rustLock, 2],
     ] as const) {
       expect(imageBuildScript.split(path)).toHaveLength(expectedCount + 1);
       expect(imageDockerignore).toContain(`!${path}`);
     }
 
-    // AGC 通过本地 path 依赖引用三个编辑器 bridge crate。镜像预热会对
-    // AGC manifest 执行 cargo fetch --locked，构建上下文与 dockerignore
-    // 必须同时放行这些 crate，否则镜像在 cargo fetch 阶段必然失败。
+    // AGC 通过本地 path 依赖引用三个编辑器 bridge crate。Cargo fetch 只需要
+    // manifest；完整源码不得进入镜像构建上下文，实际清单闭包由 Python tar 测试核验。
     for (const bridgeDir of [
       'plugins/agc-cocos-editor/native/cocos-editor-bridge',
       'plugins/agc-unity-editor/native/unity-editor-bridge',
@@ -315,6 +393,18 @@ describe('project CI workflow', () => {
         `COPY ${bridgeDir} /tmp/genarrative-cargo-cache/${bridgeDir}`,
       );
     }
+    expect(imageBuildScript).toContain(
+      'apps/ai-game-creator-shell/src-tauri/vendor',
+    );
+    expect(imageDockerignore).toContain(
+      '!apps/ai-game-creator-shell/src-tauri/vendor/*/Cargo.toml',
+    );
+    expect(imageDockerignore).toContain(
+      '!plugins/agc-*-editor/native/*-editor-bridge/Cargo.toml',
+    );
+    expect(imageDockerfile).toContain(
+      'COPY apps/ai-game-creator-shell/src-tauri /tmp/genarrative-cargo-cache/apps/ai-game-creator-shell/src-tauri',
+    );
 
     expect(imageBuildScript).toContain(
       '--build-arg "AGC_RUST_LOCK_SHA256=${agc_rust_lock_sha256}"',
@@ -352,6 +442,25 @@ describe('project CI workflow', () => {
     expect(imageCheckScript).toContain(
       '::warning title=CI dependency cache is partial::',
     );
+
+    // 下载缓存由 BuildKit 的固定 ID 独占写入，最终镜像只复制受控快照，不继承旧镜像层。
+    for (const mount of [
+      'id=genarrative-ci-cargo-cache-v1,target=/usr/local/cargo/registry/cache,sharing=locked',
+      'id=genarrative-ci-cargo-index-v1,target=/usr/local/cargo/registry/index,sharing=locked',
+      'id=genarrative-ci-npm-v1,target=/var/cache/genarrative-ci-npm,sharing=locked',
+    ]) {
+      expect(imageDockerfile).toContain(mount);
+    }
+    expect(imageDockerfile).toContain(
+      'FROM rust-toolchain AS download-cache-seed',
+    );
+    expect(imageBuildScript).toContain('--target download-cache-seed');
+    expect(imageDockerfile).toContain(
+      'COPY --from=rust-dependency-cache /opt/ci-downloads/registry /usr/local/cargo/registry',
+    );
+    expect(imageDockerfile).toContain(
+      '/var/cache/genarrative-ci-npm/_cacache /root/.npm/_cacache',
+    );
   });
 
   it('copies every workspace manifest before the API image web-builder clean install', () => {
diff --git a/scripts/test_gitea_cache_builder.py b/scripts/test_gitea_cache_builder.py
new file mode 100644
index 000000000..1069023d4
--- /dev/null
+++ b/scripts/test_gitea_cache_builder.py
@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Targeted regression tests for the trusted Gitea Rust-cache image builder."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import shlex
+import stat
+import subprocess
+import tempfile
+import textwrap
+import unittest
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parent.parent
+BUILDER_NAME = "build-gitea-rust-cache.sh"
+FIXED_SHA = "a" * 40
+MASTER_SHA = "b" * 40
+
+
+class GiteaRustCacheBuilderTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory(ignore_cleanup_errors=True)
+        self.root = Path(self.temporary_directory.name)
+        self.repo = self.root / "repo"
+        scripts = self.repo / "scripts"
+        scripts.mkdir(parents=True)
+        shutil.copy2(REPOSITORY_ROOT / "scripts" / BUILDER_NAME, scripts / BUILDER_NAME)
+        (scripts / "gitea-ci-job-image.sh").write_text("#!/usr/bin/env bash\nexit 0\n")
+        (scripts / "ci-rust-cache.sh").write_text("#!/usr/bin/env bash\nexit 0\n")
+        self.trace = self.root / "trace.log"
+        self.bin = self.root / "bin"
+        self.bin.mkdir()
+        self.write_fake_tools()
+        self.execution_bin = self.wsl_path(self.bin)
+        self.wsl_fake_root: str | None = None
+        if os.name == "nt":
+            self.wsl_fake_root = f"/tmp/gitea-cache-builder-{self.root.name}"
+            subprocess.run(
+                [
+                    "bash",
+                    "-c",
+                    "rm -rf {root}; mkdir -p {root}/bin; cp {source}/* {root}/bin/; chmod +x {root}/bin/*".format(
+                        root=shlex.quote(self.wsl_fake_root),
+                        source=shlex.quote(self.wsl_path(self.bin)),
+                    ),
+                ],
+                check=True,
+            )
+            self.execution_bin = f"{self.wsl_fake_root}/bin"
+
+    def tearDown(self) -> None:
+        if self.wsl_fake_root is not None:
+            subprocess.run(
+                ["bash", "-c", f"rm -rf {shlex.quote(self.wsl_fake_root)}"],
+                check=False,
+            )
+        self.temporary_directory.cleanup()
+
+    def write_tool(self, name: str, source: str) -> None:
+        target = self.bin / name
+        target.write_bytes(textwrap.dedent(source).encode("utf-8"))
+        target.chmod(target.stat().st_mode | stat.S_IXUSR)
+
+    def write_fake_tools(self) -> None:
+        self.write_tool(
+            "git",
+            """#!/usr/bin/env bash
+            set -eu
+            printf 'git:%s\\n' "$*" >> "$TRACE"
+            if [[ "$1" == '-C' ]]; then shift 2; fi
+            case "$1" in
+              fetch|cat-file) exit 0 ;;
+              merge-base)
+                [[ "${FAKE_NON_ANCESTOR:-}" != 1 ]]
+                exit
+                ;;
+              rev-parse)
+                if [[ "$2" == 'FETCH_HEAD^{commit}' ]]; then
+                  printf '%s\\n' "$FAKE_MASTER_SHA"
+                else
+                  printf '%s\\n' "$FAKE_FIXED_SHA"
+                fi
+                ;;
+              archive) printf 'archived %s\\n' "$2" ;;
+              *) echo "unexpected git command: $*" >&2; exit 9 ;;
+            esac
+            """,
+        )
+        self.write_tool(
+            "docker",
+            """#!/usr/bin/env bash
+            set -eu
+            # Drain the archive pipeline before logging to avoid concurrent
+            # appends to the shared trace on Windows/WSL filesystems.
+            if [[ "$1" == cp && "$2" == '-' ]]; then
+              cat >/dev/null
+            fi
+            printf 'docker:%s\\n' "$*" >> "$TRACE"
+            if [[ "$1" == image && "$2" == inspect ]]; then
+              printf 'sha256:%064d\\n' 0
+            elif [[ "$1" == run && " $* " == *' --detach '* ]]; then
+              printf 'fake-container\\n'
+            elif [[ "$1" == exec && " $* " == *' bash -s '* ]]; then
+              cat >/dev/null
+            fi
+            """,
+        )
+        self.write_tool(
+            "curl",
+            """#!/usr/bin/env bash
+            set -eu
+            while [[ "$#" -gt 0 ]]; do
+              if [[ "$1" == --output ]]; then touch "$2"; exit 0; fi
+              shift
+            done
+            exit 9
+            """,
+        )
+        self.write_tool("sha256sum", "#!/usr/bin/env bash\ncat >/dev/null\n")
+        self.write_tool(
+            "tar",
+            """#!/usr/bin/env bash
+            set -eu
+            while [[ "$#" -gt 0 ]]; do
+              if [[ "$1" == --directory ]]; then
+                mkdir -p "$2/sccache-v0.18.0-x86_64-unknown-linux-musl"
+                printf '#!/usr/bin/env bash\\nexit 0\\n' > "$2/sccache-v0.18.0-x86_64-unknown-linux-musl/sccache"
+                chmod +x "$2/sccache-v0.18.0-x86_64-unknown-linux-musl/sccache"
+                exit 0
+              fi
+              shift
+            done
+            exit 9
+            """,
+        )
+
+    @staticmethod
+    def wsl_path(path: Path) -> str:
+        value = path.resolve().as_posix()
+        if len(value) >= 3 and value[1] == ":":
+            return f"/mnt/{value[0].lower()}{value[2:]}"
+        return value
+
+    def run_builder(self, *arguments: str, non_ancestor: bool = False) -> subprocess.CompletedProcess[str]:
+        script_path = self.wsl_path(self.repo / "scripts" / BUILDER_NAME)
+        assignments = {
+            "TRACE": self.wsl_path(self.trace),
+            "FAKE_FIXED_SHA": FIXED_SHA,
+            "FAKE_MASTER_SHA": MASTER_SHA,
+            "FAKE_NON_ANCESTOR": "1" if non_ancestor else "",
+        }
+        exports = "; ".join(
+            f"export {name}={shlex.quote(value)}" for name, value in assignments.items()
+        )
+        command = (
+            f"unset CI; {exports}; export PATH={shlex.quote(self.execution_bin)}:\"$PATH\"; cd /; "
+            f"exec bash {shlex.quote(script_path)} "
+            + " ".join(shlex.quote(argument) for argument in arguments)
+        )
+        return subprocess.run(
+            ["bash", "-c", command],
+            env=os.environ,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def trace_text(self) -> str:
+        return self.trace.read_bytes().decode("utf-8", errors="replace")
+
+    def test_archives_requested_master_ancestor_and_uses_its_helper(self) -> None:
+        result = self.run_builder("trusted-base", "candidate", FIXED_SHA)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn(f"snapshot_source={FIXED_SHA}", result.stdout)
+        trace = self.trace_text()
+        self.assertIn(f"archive {FIXED_SHA}", trace)
+        self.assertIn(
+            "docker:exec fake-container cp "
+            "/workspace/GenarrativeAI/Genarrative/scripts/ci-rust-cache.sh "
+            "/tmp/ci-rust-cache.sh",
+            trace,
+        )
+
+    def test_rejects_commit_outside_fetched_master(self) -> None:
+        result = self.run_builder("trusted-base", "candidate", FIXED_SHA, non_ancestor=True)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("not contained in fetched master", result.stderr)
+        self.assertNotIn(" archive ", self.trace_text())
+
+    def test_rejects_non_full_sha_before_calling_external_tools(self) -> None:
+        result = self.run_builder("trusted-base", "candidate", "abc123")
+        self.assertEqual(result.returncode, 2)
+        self.assertIn("complete 40-character SHA", result.stderr)
+        self.assertFalse(self.trace.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_export.py b/scripts/test_gitea_cache_export.py
new file mode 100644
index 000000000..0ab36732c
--- /dev/null
+++ b/scripts/test_gitea_cache_export.py
@@ -0,0 +1,205 @@
+"""master 产物的增量归档与 Gitea v4 上传协议回归。"""
+
+import hashlib
+import base64
+from contextlib import redirect_stdout
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import importlib.util
+import io
+import json
+import os
+from pathlib import Path
+import tarfile
+import tempfile
+import threading
+import unittest
+from unittest.mock import patch
+import urllib.parse
+import zipfile
+
+from gitea_cache_upload_cleanup import decode_owner
+
+
+spec = importlib.util.spec_from_file_location("cache_export", Path(__file__).with_name("export-gitea-rust-cache.py"))
+exporter = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(exporter)
+
+
+class ExportTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        (self.root / "objects").mkdir()
+
+    def object(self, key, value, mtime):
+        path = self.root / "objects" / key[0] / key[1] / key
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(value)
+        os.utime(path, ns=(mtime * 10**9, mtime * 10**9))
+        return path
+
+    def unpack(self, baseline, limit=1024):
+        destination = self.root / "snapshot.zip"
+        result = exporter.pack_snapshot(self.root, destination, {"job": "fixture"}, baseline, limit)
+        with zipfile.ZipFile(destination) as bundle:
+            self.assertEqual(bundle.namelist(), ["snapshot.tar"])
+            with tarfile.open(fileobj=io.BytesIO(bundle.read("snapshot.tar"))) as archive:
+                files = {member.name: archive.extractfile(member).read() for member in archive}
+        return result, json.loads(files.pop("manifest.json")), files
+
+    def test_delta_omits_hit_bytes_preserves_recency_and_exports_new_keys(self):
+        inherited = self.object("a" * 64, b"old", 10)
+        baseline_path = self.root / "baseline.json"
+        exporter.save_baseline(self.root, baseline_path)
+        baseline = json.loads(baseline_path.read_text())
+        # sccache 对命中对象更新 mtime，不能因此重复上传已有对象。
+        os.utime(inherited, ns=(20 * 10**9, 20 * 10**9))
+        self.object("b" * 64, b"new", 30)
+        result, manifest, files = self.unpack(baseline)
+        key = "objects/b/b/" + "b" * 64
+        self.assertEqual(result, (1, 3))
+        self.assertEqual(files, {key: b"new"})
+        self.assertEqual(manifest["mode"], "delta")
+        self.assertEqual(manifest["touched"], [{"path": "objects/a/a/" + "a" * 64, "mtime_ns": 20 * 10**9}])
+        self.assertEqual(manifest["objects"][0]["sha256"], hashlib.sha256(b"new").hexdigest())
+
+    def test_empty_delta_is_valid_and_changed_size_is_exported(self):
+        path = self.object("a" * 64, b"old", 10)
+        baseline = {"a/a/" + "a" * 64: {"size": 3, "mtime_ns": 10 * 10**9}}
+        self.assertEqual(self.unpack(baseline)[0], (0, 0))
+        path.write_bytes(b"replacement")
+        self.assertEqual(self.unpack(baseline)[0], (1, 11))
+
+    def test_capacity_prefers_newest_objects_and_excludes_unrelated_files(self):
+        self.object("a" * 64, b"old", 10)
+        self.object("b" * 64, b"new", 20)
+        (self.root / "objects" / "credentials").write_bytes(b"secret")
+        (self.root / "sccache").write_bytes(b"binary")
+        result, _, files = self.unpack({}, limit=3)
+        self.assertEqual(result, (1, 3))
+        self.assertEqual(list(files.values()), [b"new"])
+
+    @unittest.skipUnless(os.name == "posix", "symlink fixture requires POSIX")
+    def test_symlink_objects_and_subdirectories_are_not_exported(self):
+        outside = self.root / "secret"
+        outside.write_bytes(b"secret")
+        linked = self.object("a" * 64, b"old", 10)
+        linked.unlink()
+        linked.symlink_to(outside)
+        (self.root / "objects" / "b").symlink_to(self.root, target_is_directory=True)
+        self.assertEqual(self.unpack({})[0], (0, 0))
+
+    def test_non_master_and_unclean_shutdown_do_not_scan_or_upload(self):
+        with patch.object(exporter, "scan_objects", side_effect=AssertionError("must not scan")), \
+                patch.object(exporter, "upload_snapshot", side_effect=AssertionError("must not upload")):
+            exporter.export({"GITHUB_EVENT_NAME": "pull_request", "GITHUB_REF": "refs/heads/master"})
+            exporter.export({"GITHUB_EVENT_NAME": "push", "GITHUB_REF": "refs/heads/feature"})
+            exporter.export({"GITHUB_EVENT_NAME": "push", "GITHUB_REF": "refs/heads/master"})
+
+    def test_internal_repository_route_bypasses_rpc_only_gateway(self):
+        env = {
+            "GITHUB_REPOSITORY": "owner/repo",
+            "GITHUB_SERVER_URL": "http://fetch-gate:8080",
+            "GENARRATIVE_GITEA_REPOSITORY_URL": "http://gitea:3000/sub/owner/repo.git",
+        }
+        self.assertEqual(exporter.artifact_base_url(env), "http://gitea:3000/sub")
+        env["GENARRATIVE_GITEA_REPOSITORY_URL"] = "http://token@gitea:3000/owner/repo.git"
+        with self.assertRaises(ValueError):
+            exporter.artifact_base_url(env)
+
+    def test_native_v4_chunks_finalize_with_verified_size_and_hash(self):
+        calls = []
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def do_POST(self):
+                body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+                calls.append((self.command, self.path, dict(self.headers), body))
+                payload = {"ok": True}
+                if self.path.endswith("CreateArtifact"):
+                    payload["signedUploadUrl"] = "https://external.invalid/twirp/github.actions.results.api.v1.ArtifactService/UploadArtifact?sig=private&taskID=4&artifactID=8"
+                else:
+                    payload["artifactId"] = "8"
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(json.dumps(payload).encode())
+
+            def do_PUT(self):
+                body = self.rfile.read(int(self.headers["Content-Length"]))
+                calls.append((self.command, self.path, dict(self.headers), body))
+                self.send_response(201)
+                self.end_headers()
+                self.wfile.write(b'"created"')
+
+        server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        try:
+            path = self.root / "test.zip"
+            path.write_bytes(b"123456789")
+            with patch.object(exporter, "CHUNK_BYTES", 4):
+                exporter.upload_snapshot(path, "rust-cache-v1-backend-tests-attempt-1", 123, f"http://127.0.0.1:{server.server_port}", "ephemeral")
+        finally:
+            server.shutdown()
+            server.server_close()
+            thread.join()
+        self.assertEqual(len(calls), 6)
+        self.assertEqual(calls[0][3]["workflowRunBackendId"], "123")
+        remaining = datetime.fromisoformat(calls[0][3]["expiresAt"]) - datetime.now(timezone.utc)
+        self.assertGreater(remaining.total_seconds(), 7 * 24 * 3600)
+        self.assertLessEqual(remaining.total_seconds(), 8 * 24 * 3600)
+        blocks = calls[1:4]
+        self.assertEqual(b"".join(call[3] for call in blocks), b"123456789")
+        self.assertEqual(len({urllib.parse.parse_qs(urllib.parse.urlsplit(call[1]).query)["blockid"][0] for call in blocks}), 3)
+        for call in blocks:
+            block_id = urllib.parse.parse_qs(urllib.parse.urlsplit(call[1]).query)["blockid"][0]
+            gitea_filename_suffix = base64.urlsafe_b64encode(block_id.encode()).decode()
+            self.assertEqual(decode_owner(gitea_filename_suffix), ("backend-tests", 1))
+        self.assertTrue(all("Authorization" not in call[2] for call in calls[1:5]))
+        self.assertEqual(calls[-1][2]["Authorization"], "Bearer ephemeral")
+        self.assertEqual(calls[-1][3]["size"], "9")
+        self.assertEqual(calls[-1][3]["hash"], "sha256:" + hashlib.sha256(b"123456789").hexdigest())
+
+    def test_upload_failure_never_finalizes_an_incomplete_artifact(self):
+        path = self.root / "test.zip"
+        path.write_bytes(b"data")
+        with patch.object(exporter, "request", side_effect=[
+            {"ok": True, "signedUploadUrl": "http://gitea/twirp/github.actions.results.api.v1.ArtifactService/UploadArtifact?sig=x"},
+            RuntimeError("upload failed"),
+        ]) as request:
+            with self.assertRaisesRegex(RuntimeError, "upload failed"):
+                exporter.upload_snapshot(path, "rust-cache-v1-backend-tests-attempt-1", 123, "http://gitea", "ephemeral")
+            self.assertEqual(request.call_count, 2)
+
+    def test_failed_optional_export_never_emits_host_completion_marker(self):
+        (self.root / "export-baseline.json").write_text("{}")
+        (self.root / "rustc.txt").write_text("rustc fixture\n")
+        (self.root / "workspace.txt").write_text(str(Path.cwd().resolve()))
+        (self.root / "source-commit.txt").write_text("a" * 40)
+        self.object("b" * 64, b"new", 20)
+        env = {
+            "GITHUB_EVENT_NAME": "push", "GITHUB_REF": "refs/heads/master",
+            "GENARRATIVE_CI_RUST_CACHE_EXPORT_READY": "1",
+            "GITHUB_JOB": "backend-tests", "GITHUB_SHA": "b" * 40,
+            "GITHUB_RUN_ID": "123", "GITHUB_RUN_ATTEMPT": "1",
+            "GENARRATIVE_GITEA_TOKEN": "ephemeral",
+            "GITHUB_REPOSITORY": "owner/repo",
+            "GENARRATIVE_GITEA_REPOSITORY_URL": "http://gitea/owner/repo.git",
+            "GENARRATIVE_CI_RUST_CACHE_ROOT": str(self.root),
+        }
+        output = io.StringIO()
+        with patch.object(exporter.subprocess, "check_output", side_effect=["rustc fixture\n", "sccache 0.18.0\n"]), \
+                patch.object(exporter, "upload_snapshot", side_effect=RuntimeError("upload failed")), \
+                redirect_stdout(output):
+            with self.assertRaisesRegex(RuntimeError, "upload failed"):
+                exporter.export(env)
+        self.assertNotIn("complete=true", output.getvalue())
+        self.assertFalse((self.root / "export-baseline.json").exists())
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_gate.py b/scripts/test_gitea_cache_gate.py
new file mode 100644
index 000000000..ddc3a4a2c
--- /dev/null
+++ b/scripts/test_gitea_cache_gate.py
@@ -0,0 +1,347 @@
+"""使用真实 HTTP/socket 验证领取屏障，不连接线上 Gitea。"""
+
+import http.client
+import http.server
+import gzip
+import importlib.util
+import json
+import os
+from pathlib import Path
+import socket
+import tempfile
+import threading
+import time
+import unittest
+
+if os.name != "posix":
+    raise unittest.SkipTest("领取屏障使用 Linux Unix socket 和目录 fsync；在 Linux/WSL 运行")
+
+SPEC = importlib.util.spec_from_file_location(
+    "gitea_cache_gate", Path(__file__).with_name("gitea-runner-fetch-gate.py"))
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+FETCH = "/api/actions/runner.v1.RunnerService/FetchTask"
+UPDATE = "/api/actions/runner.v1.RunnerService/UpdateTask"
+LOG = "/api/actions/runner.v1.RunnerService/UpdateLog"
+PING = "/api/actions/ping.v1.PingService/Ping"
+
+
+def varint(value):
+    data = bytearray()
+    while value > 127:
+        data.append((value & 127) | 128)
+        value >>= 7
+    data.append(value)
+    return bytes(data)
+
+
+def field(number, value):
+    # actions-proto-go v0.4.1: task/state ID=1; result=2; log task_id=1,
+    # index=2, rows=3, no_more=4; log response ack_index=1.
+    if isinstance(value, bytes):
+        return varint(number * 8 + 2) + varint(len(value)) + value
+    return varint(number * 8) + varint(value)
+
+
+def state(task_id, result=0):
+    return field(1, field(1, task_id) + field(2, result))
+
+
+def core_state(state):
+    return {key: state[key] for key in ("paused", "inflight", "uncertain")}
+
+
+class Upstream(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *_args):
+        pass
+
+    def do_POST(self):
+        data = self.rfile.read(int(self.headers.get("Content-Length", 0)))
+        self.server.requests.append((self.path, data))
+        if self.path.endswith("/Redirect"):
+            self.send_response(302)
+            self.send_header("Location", "/api/actions/runner.v1.RunnerService/FetchTask")
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+            return
+        if self.path == FETCH:
+            self.server.entered.set()
+            self.server.release.wait(10)
+        if self.server.truncated and self.path == FETCH:
+            self.send_response(200)
+            self.send_header("Content-Length", "100")
+            self.end_headers()
+            self.wfile.write(b"incomplete")
+            self.close_connection = True
+            return
+        body = self.server.responses.get(self.path, b"")
+        if self.path == UPDATE and self.path not in self.server.responses:
+            body = state(*map(int, MODULE.task_state(MODULE.protobuf_fields(data))))
+        if self.path == LOG and self.path not in self.server.responses:
+            fields = MODULE.protobuf_fields(data)
+            body = field(1, MODULE.single(fields, 2, 0) + len(fields.get(3, [])))
+        self.send_response(self.server.statuses.get(self.path, 200))
+        self.send_header("Content-Type", self.server.content_type)
+        if self.server.compressed:
+            body = gzip.compress(body)
+            self.send_header("Content-Encoding", "gzip")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+class GateTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.gate = MODULE.Gate(self.temp.name)
+        self.upstream = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Upstream)
+        self.upstream.requests = []
+        self.upstream.entered = threading.Event()
+        self.upstream.release = threading.Event()
+        self.upstream.truncated = False
+        self.upstream.responses = {}
+        self.upstream.statuses = {}
+        self.upstream.content_type = "application/proto"
+        self.upstream.compressed = False
+        self.proxy = MODULE.create_proxy(("127.0.0.1", 0),
+            f"http://127.0.0.1:{self.upstream.server_port}", self.gate)
+        self.servers = [self.upstream, self.proxy]
+        for server in self.servers:
+            threading.Thread(target=server.serve_forever, daemon=True).start()
+
+    def tearDown(self):
+        self.upstream.release.set()
+        for server in reversed(self.servers):
+            server.shutdown()
+            server.server_close()
+        self.temp.cleanup()
+
+    def request(self, path, body=b"", chunked=False):
+        connection = http.client.HTTPConnection("127.0.0.1", self.proxy.server_port, timeout=5)
+        try:
+            if chunked:
+                connection.request("POST", path, body=[body], encode_chunked=True,
+                                   headers={"Content-Type": "application/proto"})
+            else:
+                connection.request("POST", path, body=body,
+                                   headers={"Content-Type": "application/proto"})
+            response = connection.getresponse()
+            result = response.status, response.read()
+            return result
+        finally:
+            connection.close()
+
+    def wait_for(self, predicate):
+        deadline = time.monotonic() + 3
+        while time.monotonic() < deadline:
+            if predicate():
+                return
+            time.sleep(0.01)
+        self.fail("condition did not become true")
+
+    def start_fetch(self):
+        self.result = []
+        thread = threading.Thread(target=lambda: self.result.append(self.request(FETCH)))
+        thread.start()
+        self.assertTrue(self.upstream.entered.wait(3))
+        return thread
+
+    def test_pause_holds_inflight_and_allows_reporting(self):
+        thread = self.start_fetch()
+        self.assertEqual(core_state(self.gate.control("pause")),
+            {"paused": True, "inflight": 1, "uncertain": False})
+        self.assertEqual(self.request(FETCH)[0], 503)
+        self.assertEqual(self.request(PING)[0], 200)
+        self.assertEqual(sum(path == FETCH for path, _ in self.upstream.requests), 1)
+        self.upstream.release.set()
+        thread.join(3)
+        self.assertFalse(thread.is_alive())
+        self.assertEqual(self.result[0][0], 200)
+        self.assertEqual(self.gate.control("status")["inflight"], 0)
+        self.assertEqual(self.gate.control("resume")["paused"], False)
+        self.assertEqual(self.request(FETCH)[0], 200)
+
+    def test_disconnected_client_does_not_release_upstream_request(self):
+        client = socket.create_connection(self.proxy.server_address, timeout=3)
+        client.sendall(f"POST {FETCH} HTTP/1.1\r\nHost: localhost\r\nContent-Length: 2\r\n\r\n{{}}".encode())
+        self.assertTrue(self.upstream.entered.wait(3))
+        client.close()
+        state = self.gate.control("pause")
+        self.assertEqual(state["inflight"], 1)
+        self.upstream.release.set()
+        self.wait_for(lambda: self.gate.control("status")["inflight"] == 0)
+        self.assertFalse(self.gate.control("status")["uncertain"])
+
+    def test_truncated_upstream_latches_uncertainty_across_restart(self):
+        self.upstream.truncated = True
+        self.upstream.release.set()
+        self.assertEqual(self.request(FETCH)[0], 502)
+        self.wait_for(lambda: self.gate.control("status")["uncertain"])
+        self.assertTrue(self.gate.control("resume")["paused"])
+        restored = MODULE.Gate(self.temp.name)
+        self.assertTrue(restored.control("status")["uncertain"])
+        self.assertFalse(restored.enter())
+
+    def test_crashed_inflight_is_not_treated_as_successful_drain(self):
+        self.assertTrue(self.gate.enter())
+        restored = MODULE.Gate(self.temp.name)
+        self.assertTrue(restored.control("status")["uncertain"])
+        self.assertIn("error", restored.control("resume"))
+        self.gate.leave(True)
+
+    def test_pause_marker_survives_restart(self):
+        self.gate.control("pause")
+        restored = MODULE.Gate(self.temp.name)
+        self.assertEqual(core_state(restored.control("status")),
+            {"paused": True, "inflight": 0, "uncertain": False})
+        restored.control("resume")
+        self.assertFalse(MODULE.Gate(self.temp.name).control("status")["paused"])
+
+    def test_chunked_body_is_decoded_and_non_rpc_path_rejected(self):
+        self.assertEqual(self.request(PING, b"ping", chunked=True)[0], 200)
+        self.assertEqual(self.upstream.requests[-1], (PING, b"ping"))
+        self.assertEqual(self.request("/api/v1/repos")[0], 404)
+        self.assertEqual(self.request("/api/actions/../v1/repos")[0], 404)
+
+    def test_upstream_redirect_is_not_followed(self):
+        self.assertEqual(self.request("/api/actions/runner.v1.RunnerService/Redirect")[0], 302)
+        self.assertFalse(self.upstream.entered.is_set())
+        self.assertEqual(len(self.upstream.requests), 1)
+
+    def test_connection_refused_before_rpc_does_not_latch_uncertainty(self):
+        with socket.socket() as unused:
+            unused.bind(("127.0.0.1", 0))
+            port = unused.getsockname()[1]
+            self.proxy.upstream = MODULE.urllib.parse.urlsplit(f"http://127.0.0.1:{port}")
+            self.assertEqual(self.request(FETCH)[0], 502)
+        self.assertEqual(core_state(self.gate.control("status")),
+            {"paused": False, "inflight": 0, "uncertain": False})
+
+    @unittest.skipUnless(hasattr(socket, "AF_UNIX"), "Unix control socket required")
+    def test_control_socket_uses_newline_json(self):
+        path = str(Path(self.temp.name) / "gate.sock")
+        control = MODULE.ControlServer(path, MODULE.Control)
+        control.gate = self.gate
+        self.servers.append(control)
+        threading.Thread(target=control.serve_forever, daemon=True).start()
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.connect(path)
+            client.sendall(b'{"action":"pause"}\n')
+            payload = client.makefile("rb").readline()
+        self.assertEqual(core_state(json.loads(payload)),
+            {"paused": True, "inflight": 0, "uncertain": False})
+
+    def test_paused_fetch_records_live_route_and_restart_discards_proof(self):
+        self.gate.control("pause")
+        before = time.time()
+        self.assertEqual(self.request(FETCH)[0], 503)
+        state = self.gate.control("status")
+        self.assertEqual(state["last_fetch_peer"], "127.0.0.1")
+        self.assertGreaterEqual(state["last_fetch_at"], before)
+        self.assertEqual(self.upstream.requests, [])
+        self.assertEqual(self.request(PING)[0], 200)
+        self.assertEqual(self.gate.control("status")["last_fetch_at"], state["last_fetch_at"])
+        restarted = MODULE.Gate(self.temp.name).control("status")
+        self.assertIsNone(restarted["last_fetch_peer"])
+        self.assertIsNone(restarted["last_fetch_at"])
+
+    def fetch_task(self, task_id=42):
+        self.upstream.responses[FETCH] = field(1, field(1, task_id)) + field(2, 10)
+        self.upstream.release.set()
+        self.assertEqual(self.request(FETCH)[0], 200)
+        self.assertEqual(self.gate.control("status")["task_ids"], [str(task_id)])
+
+    def finalize_log(self, task_id=42):
+        self.assertEqual(self.request(LOG, field(1, task_id) + field(2, 3)
+                                      + field(3, b"log row") + field(4, 1))[0], 200)
+        self.wait_for(lambda: self.gate.tasks.get(str(task_id)) is True)
+
+    def test_assigned_task_survives_pause_until_runner_finished_reporting(self):
+        self.fetch_task()
+        self.assertEqual(self.gate.control("pause")["active_tasks"], 1)
+        self.assertEqual(self.request(FETCH)[0], 503)
+        self.assertEqual(self.request(UPDATE, state(42, 1))[0], 200)
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.finalize_log()
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.assertEqual(self.request(UPDATE, state(42, 1))[0], 200)
+        self.wait_for(lambda: self.gate.control("status")["active_tasks"] == 0)
+        self.assertFalse(self.gate.control("status")["uncertain"])
+        # 终态响应在客户端超时后重试，不应再次阻断后续任务领取。
+        self.request(UPDATE, state(42, 1))
+        self.assertFalse(self.gate.control("status")["uncertain"])
+
+    def test_compressed_fetch_and_task_ledger_survive_restart(self):
+        self.upstream.compressed = True
+        self.fetch_task()
+        restored = MODULE.Gate(self.temp.name)
+        self.assertEqual(restored.control("status")["task_ids"], ["42"])
+        self.assertFalse(restored.control("status")["uncertain"])
+        self.proxy.gate = self.gate = restored
+        self.finalize_log()
+        self.request(UPDATE, state(42, 2))
+        self.wait_for(lambda: self.gate.control("status")["active_tasks"] == 0)
+        self.assertEqual(MODULE.Gate(self.temp.name).control("status")["active_tasks"], 0)
+
+    def test_server_cancellation_does_not_retire_executing_task(self):
+        self.fetch_task()
+        self.upstream.responses[UPDATE] = state(42, 3)
+        self.request(UPDATE, state(42))
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.finalize_log()
+        self.request(UPDATE, state(42))
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.request(UPDATE, state(42, 3))
+        self.wait_for(lambda: self.gate.control("status")["active_tasks"] == 0)
+
+    def test_partial_final_log_acknowledgement_keeps_task_active(self):
+        self.fetch_task()
+        self.upstream.responses[LOG] = field(1, 3)
+        self.request(LOG, field(1, 42) + field(2, 3) + field(3, b"row") + field(4, 1))
+        self.request(UPDATE, state(42, 1))
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        del self.upstream.responses[LOG]
+        self.finalize_log()
+        self.request(UPDATE, state(42, 1))
+        self.wait_for(lambda: self.gate.control("status")["active_tasks"] == 0)
+
+    def test_final_state_waits_for_success_and_output_acknowledgement(self):
+        self.fetch_task()
+        self.finalize_log()
+        self.upstream.statuses[UPDATE] = 500
+        self.request(UPDATE, state(42, 1))
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.upstream.statuses[UPDATE] = 200
+        output = field(2, field(1, b"key") + field(2, b"value"))
+        self.request(UPDATE, state(42, 1) + output)
+        self.assertEqual(self.gate.control("status")["active_tasks"], 1)
+        self.upstream.responses[UPDATE] = state(42, 1) + field(2, b"key")
+        self.request(UPDATE, state(42, 1) + output)
+        self.wait_for(lambda: self.gate.control("status")["active_tasks"] == 0)
+
+    def test_unknown_or_invalid_fetch_result_prevents_idle(self):
+        self.upstream.release.set()
+        self.upstream.responses[FETCH] = b"not protobuf"
+        self.assertEqual(self.request(FETCH)[0], 200)
+        self.assertTrue(self.gate.control("status")["uncertain"])
+        self.assertTrue(MODULE.Gate(self.temp.name).control("status")["uncertain"])
+
+    def test_task_report_without_observed_assignment_requires_idle_bootstrap(self):
+        self.assertEqual(self.request(UPDATE, state(42))[0], 200)
+        self.wait_for(lambda: self.gate.control("status")["uncertain"])
+        self.assertIn("error", self.gate.control("resume"))
+
+    def test_disconnected_fetch_client_still_leaves_assigned_task_busy(self):
+        self.upstream.responses[FETCH] = field(1, field(1, 42))
+        client = socket.create_connection(self.proxy.server_address, timeout=3)
+        client.sendall(f"POST {FETCH} HTTP/1.1\r\nHost: localhost\r\nContent-Length: 0\r\n\r\n".encode())
+        self.assertTrue(self.upstream.entered.wait(3))
+        client.close()
+        self.gate.control("pause")
+        self.upstream.release.set()
+        self.wait_for(lambda: self.gate.control("status")["inflight"] == 0)
+        self.assertEqual(self.gate.control("status")["task_ids"], ["42"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_image_context.py b/scripts/test_gitea_cache_image_context.py
new file mode 100644
index 000000000..82e6ec75f
--- /dev/null
+++ b/scripts/test_gitea_cache_image_context.py
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Regression tests for the minimal trusted Gitea CI download-cache build context."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import shlex
+import stat
+import subprocess
+import tarfile
+import tempfile
+import textwrap
+import tomllib
+import unittest
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parent.parent
+IMAGE_SCRIPT = REPOSITORY_ROOT / "scripts" / "gitea-ci-job-image.sh"
+STATIC_CONTEXT_FILES = (
+    "deploy/container/gitea-ci-job.Dockerfile",
+    "deploy/container/gitea-ci-job.Dockerfile.dockerignore",
+    "deploy/container/gitea-ci-buildkitd.toml",
+    "deploy/container/gitea-ci-checkout.sh",
+    "scripts/export-ci-npm-download-cache.mjs",
+    "package.json",
+    "package-lock.json",
+    "apps/admin-web/package.json",
+    "apps/ai-game-creator-shell/package.json",
+    "apps/desktop-shell/package.json",
+    "apps/mobile-shell/package.json",
+    "apps/preview-deployer-web/package.json",
+    "packages/image-canvas-core/package.json",
+    "packages/image-canvas-react/package.json",
+    "packages/shared/package.json",
+    "tools/spine-json-export-validator/package.json",
+    "apps/ai-game-creator-shell/src-tauri/Cargo.toml",
+    "apps/ai-game-creator-shell/src-tauri/Cargo.lock",
+    "server-rs/Cargo.toml",
+    "server-rs/Cargo.lock",
+    "apps/desktop-shell/src-tauri/Cargo.toml",
+    "apps/desktop-shell/src-tauri/Cargo.lock",
+)
+
+
+class GiteaCiImageContextTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory(ignore_cleanup_errors=True)
+        self.root = Path(self.temporary_directory.name)
+        self.context_archive = self.root / "context.tar"
+        self.bin = self.root / "bin"
+        self.bin.mkdir()
+        self.write_fake_docker()
+        self.execution_bin = self.wsl_path(self.bin)
+        self.wsl_fake_root: str | None = None
+        if os.name == "nt":
+            self.wsl_fake_root = f"/tmp/gitea-ci-image-context-{self.root.name}"
+            subprocess.run(
+                [
+                    "bash",
+                    "-c",
+                    "rm -rf {root}; mkdir -p {root}/bin; cp {source}/* {root}/bin/; chmod +x {root}/bin/*".format(
+                        root=shlex.quote(self.wsl_fake_root),
+                        source=shlex.quote(self.wsl_path(self.bin)),
+                    ),
+                ],
+                check=True,
+            )
+            self.execution_bin = f"{self.wsl_fake_root}/bin"
+
+    def tearDown(self) -> None:
+        if self.wsl_fake_root is not None:
+            subprocess.run(
+                ["bash", "-c", f"rm -rf {shlex.quote(self.wsl_fake_root)}"], check=False
+            )
+        self.temporary_directory.cleanup()
+
+    @staticmethod
+    def wsl_path(path: Path) -> str:
+        value = path.resolve().as_posix()
+        if len(value) >= 3 and value[1] == ":":
+            return f"/mnt/{value[0].lower()}{value[2:]}"
+        return value
+
+    def write_fake_docker(self) -> None:
+        docker = self.bin / "docker"
+        docker.write_bytes(textwrap.dedent(
+            """#!/usr/bin/env bash
+            set -eu
+            if [[ "$1" == buildx && "$2" == version ]]; then exit 0; fi
+            if [[ "$1" == buildx && "$2" == inspect ]]; then
+              if [[ " $* " == *" --format "* ]]; then printf 'docker-container\\n'; fi
+              exit 0
+            fi
+            if [[ "$1" == buildx && "$2" == build ]]; then
+              cat > "$TAR_CAPTURE"
+              exit 0
+            fi
+            if [[ "$1" == image && "$2" == inspect ]]; then
+              printf 'sha256:%064d\\n' 0
+              exit 0
+            fi
+            if [[ "$1" == run ]]; then exit 0; fi
+            echo "unexpected docker invocation" >&2
+            exit 9
+            """
+        ).encode("utf-8"))
+        docker.chmod(docker.stat().st_mode | stat.S_IXUSR)
+
+    def run_script(self, script: Path, *arguments: str, capture_context: bool = False) -> subprocess.CompletedProcess[str]:
+        exports = [f"export PATH={shlex.quote(self.execution_bin)}:\"$PATH\""]
+        if capture_context:
+            exports.append(f"export TAR_CAPTURE={shlex.quote(self.wsl_path(self.context_archive))}")
+        command = "; ".join(exports) + "; cd /; exec bash " + shlex.quote(self.wsl_path(script))
+        command += " " + " ".join(shlex.quote(argument) for argument in arguments)
+        return subprocess.run(
+            ["bash", "-c", command], env=os.environ, text=True, capture_output=True, check=False
+        )
+
+    @staticmethod
+    def dependency_paths(value):
+        if not isinstance(value, dict):
+            return
+        for key, child in value.items():
+            if key in {"dependencies", "build-dependencies", "dev-dependencies"} and isinstance(child, dict):
+                for dependency in child.values():
+                    if isinstance(dependency, dict) and isinstance(dependency.get("path"), str):
+                        yield dependency["path"]
+            yield from GiteaCiImageContextTest.dependency_paths(child)
+
+    def test_build_context_contains_all_local_dependency_manifests_and_no_source(self) -> None:
+        result = self.run_script(IMAGE_SCRIPT, "build", capture_context=True)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        with tarfile.open(self.context_archive) as archive:
+            names = {member.name.removeprefix("./") for member in archive.getmembers() if member.isfile()}
+
+        manifests = {Path(name) for name in names if name.endswith("Cargo.toml")}
+        self.assertTrue(manifests)
+        expected = set()
+        for manifest in manifests:
+            data = tomllib.loads((REPOSITORY_ROOT / manifest).read_text(encoding="utf-8"))
+            for path in self.dependency_paths(data):
+                dependency = (REPOSITORY_ROOT / manifest.parent / path).resolve()
+                try:
+                    cargo_toml = (dependency / "Cargo.toml").relative_to(REPOSITORY_ROOT)
+                except ValueError:
+                    continue
+                expected.add(cargo_toml)
+        self.assertTrue(expected)
+        self.assertTrue(expected.issubset(manifests), sorted(expected - manifests))
+
+        self.assertFalse(any(Path(name).suffix in {".rs", ".c", ".cc", ".cpp", ".h"} for name in names))
+        self.assertFalse(any("target" in Path(name).parts for name in names))
+        self.assertFalse(any(
+            Path(name).name.startswith(".env") or Path(name).suffix in {".pem", ".key"}
+            for name in names
+        ))
+
+    def test_revision_tracks_vendor_manifests_but_ignores_regular_source(self) -> None:
+        fixture = self.root / "revision-fixture"
+        script = fixture / "scripts" / "gitea-ci-job-image.sh"
+        script.parent.mkdir(parents=True)
+        shutil.copy2(IMAGE_SCRIPT, script)
+        script.chmod(script.stat().st_mode | stat.S_IXUSR)
+        for name in STATIC_CONTEXT_FILES:
+            target = fixture / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text("fixture\n", encoding="utf-8")
+        vendor_manifest = fixture / "apps/ai-game-creator-shell/src-tauri/vendor/example/Cargo.toml"
+        vendor_manifest.parent.mkdir(parents=True)
+        vendor_manifest.write_text('[package]\nname = "example"\nversion = "0.1.0"\n', encoding="utf-8")
+        bridge_manifest = fixture / "plugins/agc-example-editor/native/example-editor-bridge/Cargo.toml"
+        bridge_manifest.parent.mkdir(parents=True)
+        bridge_manifest.write_text('[package]\nname = "bridge"\nversion = "0.1.0"\n', encoding="utf-8")
+        (fixture / "server-rs/crates").mkdir(parents=True)
+
+        first = self.run_script(script, "revision")
+        self.assertEqual(first.returncode, 0, first.stderr)
+        source = fixture / "apps/ai-game-creator-shell/src-tauri/src/lib.rs"
+        source.parent.mkdir(parents=True)
+        source.write_text("pub fn ignored() {}\n", encoding="utf-8")
+        self.assertEqual(self.run_script(script, "revision").stdout, first.stdout)
+        vendor_manifest.write_text('[package]\nname = "example"\nversion = "0.2.0"\n', encoding="utf-8")
+        changed = self.run_script(script, "revision")
+        self.assertEqual(changed.returncode, 0, changed.stderr)
+        self.assertNotEqual(changed.stdout, first.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_maintenance.py b/scripts/test_gitea_cache_maintenance.py
new file mode 100644
index 000000000..730e44049
--- /dev/null
+++ b/scripts/test_gitea_cache_maintenance.py
@@ -0,0 +1,650 @@
+#!/usr/bin/env python3
+"""High-risk state-transition tests for the host-only Rust cache maintainer."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+from pathlib import Path
+import re
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+SCRIPT = Path(__file__).with_name("maintain-gitea-rust-cache.py")
+SPEC = importlib.util.spec_from_file_location("gitea_cache_maintenance", SCRIPT)
+assert SPEC and SPEC.loader
+maintenance_module = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(maintenance_module)
+
+IMAGE = "sha256:" + "1" * 64
+OLD_IMAGE = "sha256:" + "2" * 64
+BASE_IMAGE = "sha256:" + "3" * 64
+SHA = "a" * 40
+
+
+def runner_config(image: str) -> str:
+    return f'runners:\n  - "genarrative-ci:docker://{image}"\n'
+
+
+class FakeApi:
+    def __init__(self):
+        self.requests: list[str] = []
+
+    def request(self, path, *, method, body=None, raw=False):
+        self.requests.append(path)
+        raise AssertionError(f"unexpected API request: {path}")
+
+
+class GiteaCacheMaintenanceTest(unittest.TestCase):
+    def setUp(self):
+        self.temporary_directory = tempfile.TemporaryDirectory()
+        self.root = Path(self.temporary_directory.name)
+        self.token = self.root / "token"
+        self.token.write_text("test-token\n", encoding="utf-8")
+        self.config = {
+            "state_dir": str((self.root / "state").resolve()),
+            "api_url": "https://gitea.example.test/api/v1",
+            "token_file": str(self.token),
+            "repository": "team/project",
+            "repository_url": "http://gitea:3000/team/project.git",
+            "runner_container": "gitea-runner",
+            "gate_socket": str(self.root / "gate.sock"),
+            "gate_url": "https://gitea.example.test",
+            "clone_url": "https://gitea.example.test/team/project.git",
+        }
+
+    def tearDown(self):
+        self.temporary_directory.cleanup()
+
+    def test_api_requires_explicit_method_and_preserves_it_with_body(self):
+        api = maintenance_module.Api(self.config["api_url"], self.token)
+        with self.assertRaises(TypeError):
+            api.request("example", body={"value": 1})
+        with self.assertRaises(TypeError):
+            api.request("example")
+        with patch.object(maintenance_module.urllib.request, "build_opener") as build_opener:
+            for method in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+                with self.subTest(method=method):
+                    build_opener.return_value.open.return_value = io.BytesIO(b'{}')
+                    body = {"value": 1} if method in {"POST", "PUT", "PATCH"} else None
+                    self.assertEqual(api.request("example", method=method, body=body), {})
+                    request = build_opener.return_value.open.call_args.args[0]
+                    self.assertEqual(request.get_method(), method)
+                    self.assertEqual(request.data, None if body is None else json.dumps(body).encode())
+
+    def test_operation_logs_duration_and_build_log_without_exception_secrets(self):
+        build_log = self.root / "artifacts" / SHA / "build.log"
+        with patch.object(maintenance_module.time, "monotonic", side_effect=[10.0, 13.25]), \
+             patch("builtins.print") as printed:
+            with self.assertRaisesRegex(RuntimeError, "test failure"):
+                with maintenance_module.operation("merge cache artifacts", build_log=build_log):
+                    raise RuntimeError("test failure")
+        messages = [call.args[0] for call in printed.call_args_list]
+        self.assertEqual(messages[0], f"[cache-maintenance] merge cache artifacts: started; build log={build_log}")
+        self.assertEqual(messages[1],
+                         f"[cache-maintenance] merge cache artifacts: failed after 3.2s; build log={build_log}")
+
+    def test_workflow_jobs_and_cache_producers_match_maintenance_contract(self):
+        workflow = (SCRIPT.parent.parent / ".gitea/workflows/project-ci.yml").read_text(encoding="utf-8")
+        # 沿用 workflow 的显式 job/step 格式，枚举实际 job，避免另一份名单漏掉新增项。
+        sections = re.split(r"(?m)^  ([\w-]+):\s*$", workflow.split("\njobs:\n", 1)[1])
+        jobs, producers = {}, {}
+        for job_id, section in zip(sections[1::2], sections[2::2]):
+            names = re.findall(r"(?m)^    name: (.+)$", section)
+            self.assertEqual(len(names), 1, f"{job_id}: expected one explicit job name")
+            name = names[0].strip().strip("\"'")
+            self.assertNotIn(name, jobs, f"duplicate workflow job name: {name}")
+            jobs[name] = job_id
+            if "run: python3 scripts/export-gitea-rust-cache.py" in section:
+                self.assertIn(f"      - name: {maintenance_module.EXPORT_STEP}\n", section)
+                producers[name] = job_id
+        self.assertEqual(set(jobs), maintenance_module.JOBS,
+                         "workflow job names drifted from maintainer JOBS")
+        self.assertEqual(producers, maintenance_module.RUST_JOB_IDS,
+                         "workflow cache producer names/IDs drifted from maintainer RUST_JOB_IDS")
+
+    def record(self, image, *, source=SHA, owned=True, verified_run=None, base=BASE_IMAGE):
+        return {
+            "image": image,
+            "tag": (
+                "genarrative/gitea-project-ci:rust-cache-auto-" + source
+                if source is not None else None
+            ),
+            "source": source,
+            "inputs": "inputs",
+            "base": base,
+            "owned": owned,
+            "activated": "2026-01-01T00:00:00+00:00",
+            "verified_run": verified_run,
+            "artifact": str(self.root / "state" / "artifacts" / (source or "manual")),
+        }
+
+    def maintenance(self, state):
+        state_root = Path(self.config["state_dir"])
+        state_root.mkdir(parents=True, exist_ok=True)
+        (state_root / "state.json").write_text(json.dumps(state), encoding="utf-8")
+        instance = maintenance_module.Maintenance(self.config)
+        instance.api = FakeApi()
+        return instance
+
+    def activation_maintenance(self, *, idle_values, switch=None):
+        old = self.record(OLD_IMAGE, owned=False, verified_run=1)
+        candidate = self.record(IMAGE)
+        state = {
+            "versions": [old, candidate],
+            "current": OLD_IMAGE,
+            "rollback": None,
+            "candidate": IMAGE,
+        }
+        if switch is not None:
+            state["switch"] = switch
+        instance = self.maintenance(state)
+        config = {"value": runner_config(OLD_IMAGE)}
+        writes: list[str] = []
+        restarts: list[tuple] = []
+        statuses = 0
+
+        instance.check_gate_route = lambda: None
+        instance.read_config = lambda: config["value"]
+        instance.write_config = lambda value: (writes.append(value), config.__setitem__("value", value))
+        instance.image_info = lambda image, inner=False: {"Id": image}
+
+        def docker(*args, inner=False, **kwargs):
+            if args[:1] == ("restart",):
+                restarts.append(args)
+                return ""
+            if args[:2] == ("inspect", "--format"):
+                if args[2] == "{{.State.StartedAt}}":
+                    return "2026-01-01T00:00:00+00:00"
+                if args[2] == "{{.State.Status}}":
+                    return "running"
+            if args[:1] == ("logs",):
+                return "declare successfully"
+            raise AssertionError(f"unexpected docker call: {args}, inner={inner}")
+
+        instance.docker = docker
+        iterator = iter(idle_values)
+        instance.idle = lambda: next(iterator)
+
+        def gate(action):
+            nonlocal statuses
+            if action == "pause":
+                return {"paused": True}
+            if action == "resume":
+                return {"paused": False}
+            if action == "status":
+                statuses += 1
+                return {"paused": False} if statuses == 1 else {"paused": True, "inflight": 0}
+            raise AssertionError(action)
+
+        instance.gate = gate
+        return instance, writes, restarts
+
+    def test_cache_inputs_keeps_openapi_and_embedded_skill_text(self):
+        tree = "\n".join(
+            [
+                "100644 blob a\tdocs/guide.md",
+                "100644 blob b\tdocs/openapi/external.json",
+                "100644 blob c\t.codex/skills/example/SKILL.md",
+                "100644 blob d\tREADME.md",
+            ]
+        )
+        digest = maintenance_module.cache_inputs(tree)
+        self.assertEqual(digest, maintenance_module.cache_inputs(
+            tree.replace("guide.md", "【说明】中文文档.md").replace("\n", "\0") + "\0"))
+        self.assertEqual(digest, maintenance_module.cache_inputs(tree.replace("guide.md", "other.md")))
+        self.assertNotEqual(digest, maintenance_module.cache_inputs(tree.replace("external.json", "changed.json")))
+        self.assertNotEqual(digest, maintenance_module.cache_inputs(tree.replace("SKILL.md", "PROMPT.md")))
+
+    def test_gate_route_requires_independent_checkout_and_live_runner_proof(self):
+        instance = self.maintenance({"versions": [], "current": None, "rollback": None, "candidate": None})
+        instance.read_config = lambda: runner_config(OLD_IMAGE)
+        with self.assertRaisesRegex(RuntimeError, "GENARRATIVE_GITEA_REPOSITORY_URL"):
+            instance.check_gate_route()
+        instance.read_config = lambda: runner_config(OLD_IMAGE) + (
+            '  envs:\n    GENARRATIVE_GITEA_REPOSITORY_URL: "http://gitea:3000/team/project.git"\n')
+        started = "2026-01-01T00:00:00Z"
+        def docker(*args, **kwargs):
+            if args[0] == "exec":
+                return json.dumps({"address": self.config["gate_url"]})
+            return json.dumps([{"State": {"StartedAt": started}, "NetworkSettings": {
+                "Networks": {"internal": {"IPAddress": "10.0.0.2"}}}}])
+        instance.docker = docker
+        proof = {"last_fetch_peer": "10.0.0.2", "last_fetch_at": maintenance_module.timestamp(started).timestamp() + 1,
+                 "active_tasks": 0}
+        instance.gate = lambda action: proof
+        instance.check_gate_route()
+        proof["last_fetch_at"] -= 2
+        with self.assertRaisesRegex(RuntimeError, "this runner startup"):
+            instance.check_gate_route()
+        proof.update(last_fetch_peer="10.0.0.3", last_fetch_at=9999999999)
+        with self.assertRaisesRegex(RuntimeError, "this runner startup"):
+            instance.check_gate_route()
+
+    def test_complete_nine_job_run_requires_real_rust_cache_statistics(self):
+        run = {"status": "completed", "conclusion": "success"}
+        jobs = [{"name": name, "conclusion": "success"} for name in maintenance_module.JOBS]
+        self.assertTrue(maintenance_module.fully_passed(run, jobs))
+        self.assertFalse(maintenance_module.fully_passed(run, jobs[:-1]))
+        good = (
+            f"worker image: {IMAGE}\n[rust-cache] mode=sccache\n"
+            "Cache hits 7\nCache errors 0\nCache read errors 0\nCache write errors 0\n"
+        )
+        self.assertTrue(maintenance_module.verifies_image({"name": "Backend tests"}, good, IMAGE))
+        self.assertFalse(maintenance_module.verifies_image({"name": "Backend tests"}, good.replace("Cache hits 7", "Cache hits 0"), IMAGE))
+        self.assertFalse(maintenance_module.verifies_image({"name": "Backend tests"}, good.replace("Cache write errors 0", "Cache write errors 1"), IMAGE))
+
+    def test_fetches_latest_master_without_ci_green_gate(self):
+        instance = self.maintenance({"versions": [], "current": None, "rollback": None, "candidate": None})
+        instance.repo.mkdir(parents=True)
+        (instance.repo / ".git").mkdir()
+        (instance.repo / ".git" / "genarrative-cache-maintenance").write_text("owned source checkout\n")
+        calls = []
+
+        def fake_command(*args, **kwargs):
+            calls.append(args)
+            if args[1:4] == ("remote", "get-url", "origin"):
+                return instance.config["clone_url"] + "\n"
+            if args[1:3] == ("rev-parse", "FETCH_HEAD^{commit}"):
+                return SHA + "\n"
+            if args[1:3] == ("ls-tree", "-rz"):
+                return "100644 blob x\tdocs/openapi/current.json\n"
+            return ""
+
+        with patch.object(maintenance_module, "command", fake_command):
+            self.assertEqual(instance.fetch_source()[0], SHA)
+        self.assertIn(("git", "remote", "get-url", "origin"), calls)
+        self.assertIn(("git", "fetch", "--no-tags", "origin", "refs/heads/master"), calls)
+        self.assertIn(("git", "clean", "-ffdx"), calls)
+        self.assertFalse(any("runs" in " ".join(call) for call in calls))
+
+    def test_idle_race_after_pause_restores_without_restart(self):
+        instance, writes, restarts = self.activation_maintenance(idle_values=[True, False])
+        with patch.object(maintenance_module.time, "sleep", lambda _: None):
+            self.assertFalse(instance.activate())
+        self.assertEqual(restarts, [])
+        self.assertEqual(writes, [])
+        self.assertEqual(instance.state["current"], OLD_IMAGE)
+        self.assertEqual(instance.state["candidate"], IMAGE)
+        self.assertNotIn("pause_owned", instance.state)
+
+    def test_idle_requires_task_ledger_and_all_live_container_states(self):
+        instance = self.maintenance({"versions": [], "current": None})
+        state = {"uncertain": False, "active_tasks": 1}
+        instance.gate = lambda _: state
+        calls = []
+        instance.docker = lambda *args, **kw: calls.append((args, kw)) or ""
+        self.assertFalse(instance.idle())  # assigned task before its first container
+        self.assertEqual(calls, [])
+        state["active_tasks"] = 0
+        self.assertTrue(instance.idle())
+        self.assertIn("status=created", calls[-1][0])
+        self.assertTrue(calls[-1][1]["inner"])
+        instance.docker = lambda *_a, **_k: "created-container\n"
+        self.assertFalse(instance.idle())
+        del state["active_tasks"]
+        with self.assertRaisesRegex(RuntimeError, "durable task tracking"):
+            instance.idle()
+
+    def source_fixture(self):
+        old = self.record(OLD_IMAGE, source="b" * 40, owned=False, verified_run=1)
+        instance = self.maintenance({"versions": [old], "current": OLD_IMAGE})
+        run = {"id": 44, "status": "completed", "conclusion": "failure", "event": "push",
+               "path": "project-ci.yml@refs/heads/master", "head_branch": "master", "head_sha": SHA}
+        jobs = [{"id": i, "name": name, "status": "completed", "conclusion": "failure",
+                 "head_sha": SHA, "run_attempt": 1,
+                 "steps": [{"name": maintenance_module.EXPORT_STEP, "conclusion": "success"}]}
+                for i, name in enumerate(maintenance_module.RUST_JOB_IDS, start=1)]
+        artifacts = [{"id": job["id"], "name": "rust-cache-v1-" + maintenance_module.RUST_JOB_IDS[job["name"]]
+                      + "-attempt-1", "expired": False, "workflow_run": run} for job in jobs]
+        class Api:
+            def pages(self, path, key):
+                return iter({"workflow_runs": [run], "jobs": jobs, "artifacts": artifacts}[key])
+            def request(self, path, *, method, raw=False):
+                job_id = int(path.split("/jobs/")[1].split("/")[0])
+                name = next(item["name"] for item in artifacts if item["id"] == job_id)
+                return f"worker image: {OLD_IMAGE}\n[rust-cache] artifact={name} objects=1 bytes=10 complete=true\n"
+        instance.api = Api()
+        return instance, run, jobs, artifacts
+
+    def select_source(self, instance):
+        with patch.object(maintenance_module.subprocess, "run", return_value=type("Result", (), {"returncode": 0})()), \
+             patch.object(maintenance_module, "command", lambda *args, **kw: "100644 blob " + args[-1] + "\tsrc.rs\0"):
+            return instance.source_run()
+
+    def test_complete_failed_master_can_supply_cache_but_pr_and_missing_groups_cannot(self):
+        instance, run, jobs, artifacts = self.source_fixture()
+        result = self.select_source(instance)
+        self.assertEqual(result["run_id"], 44)
+        self.assertEqual(len(result["exports"]), 6)
+        run["event"] = "pull_request"
+        self.assertIsNone(self.select_source(instance))
+        run["event"] = "push"
+        artifacts.pop()
+        self.assertIsNone(self.select_source(instance))
+
+    def test_stale_attempt_cancelled_job_or_failed_export_cannot_supply_cache(self):
+        instance, run, jobs, artifacts = self.source_fixture()
+        run["conclusion"] = "cancelled"
+        self.assertIsNone(self.select_source(instance))  # all six artifacts may already exist
+        run["conclusion"] = "failure"
+        jobs[0]["run_attempt"] = 2
+        self.assertIsNone(self.select_source(instance))
+        jobs[0]["run_attempt"] = 1
+        jobs[0]["conclusion"] = "cancelled"
+        self.assertIsNone(self.select_source(instance))
+        jobs[0]["conclusion"] = "success"
+        jobs[0]["steps"][0]["conclusion"] = "failure"
+        self.assertIsNone(self.select_source(instance))
+
+    def test_exports_using_different_images_are_not_combined(self):
+        instance, _, _, _ = self.source_fixture()
+        original = instance.api.request
+        instance.api.request = lambda path, **kwargs: original(path, **kwargs).replace(OLD_IMAGE, IMAGE) if '/jobs/1/' in path else original(path, **kwargs)
+        self.assertIsNone(self.select_source(instance))
+
+    def test_completed_artifact_without_upload_completion_log_is_not_used(self):
+        instance, _, _, _ = self.source_fixture()
+        instance.api.request = lambda *_a, **_k: f"worker image: {OLD_IMAGE}\n"
+        self.assertIsNone(self.select_source(instance))
+
+    def test_assembly_uses_ci_objects_and_trusted_binary_without_warming_compiler(self):
+        instance, _, _, _ = self.source_fixture()
+        source = self.select_source(instance)
+        shell_calls, docker_calls = [], []
+        instance.build_command = lambda log, script, *args, **kw: shell_calls.append((script, args))
+        def info(image, inner=False):
+            return {"Id": IMAGE if image.startswith("genarrative/") else image, "Config": {"Labels": {
+                "world.genarrative.ci.rust-cache-source": "b" * 40,
+                "world.genarrative.ci.rust-cache-base": BASE_IMAGE,
+                "com.genarrative.ci.definition-sha256": "definition",
+            }}}
+        instance.image_info = info
+        def docker(*args, **kw):
+            docker_calls.append(args)
+            if args[0] == "create":
+                return "temporary-copy-container"
+            if args[0] == "cp":
+                root = Path(args[-1])
+                (root / "objects").mkdir()
+                (root / "sccache").write_bytes(b"trusted binary")
+            if args[-2:] == ("rustc", "-vV"):
+                return "rustc test\n"
+            return ""
+        instance.docker = docker
+        instance.api.download = lambda path, destination: destination.write_bytes(b"download")
+        def merge(inputs, output, **kwargs):
+            self.assertEqual(len(inputs), 6)
+            self.assertEqual(kwargs["expected_inherited_source_sha"], "b" * 40)
+            output.mkdir()
+            (output / "objects").mkdir()
+            return type("Merged", (), {"sccache_version": "sccache 0.18.0", "rustc": "rustc test\n",
+                "workspace": "/workspace/team/project", "base_image": BASE_IMAGE})()
+        with patch.object(maintenance_module, "command", return_value="definition\n"), \
+             patch.object(maintenance_module, "merge_snapshots", merge):
+            instance.build(source)
+        self.assertEqual(shell_calls, [("gitea-ci-job-image.sh", ("verify", "genarrative/gitea-project-ci:rust-cache-auto-" + SHA))])
+        self.assertIn(("create", OLD_IMAGE), docker_calls)
+        self.assertIn(("rm", "--volumes", "temporary-copy-container"), docker_calls)
+        self.assertEqual(instance.state["candidate"], IMAGE)
+        self.assertEqual(instance.version(IMAGE)["run_id"], 44)
+
+    def test_export_cleanup_only_deletes_collected_or_expired_owned_master_artifacts(self):
+        current = self.record(OLD_IMAGE, owned=False, verified_run=1)
+        current.update(staged=True, run_id=44, exports=[{"id": 1}])
+        instance = self.maintenance({"versions": [current], "current": OLD_IMAGE})
+        old_run = {"id": 9, "status": "completed", "path": "project-ci.yml@refs/heads/master",
+                   "event": "push", "head_branch": "master", "head_sha": SHA}
+        artifact = {"id": 2, "name": "rust-cache-v1-backend-tests-attempt-1",
+                    "workflow_run": {"id": 9}, "created_at": "2020-01-01T00:00:00Z"}
+        rows = [artifact, {**artifact, "id": 3, "name": "release-binary"},
+                {**artifact, "id": 4, "workflow_run": {"id": 10}},
+                {**artifact, "id": 5, "workflow_run": {"id": 11}}]
+        deleted = []
+        instance.api.pages = lambda *_: iter(rows)
+        def request(path, *, method):
+            if method == "DELETE":
+                return deleted.append((path, method))
+            return {9: old_run, 10: {**old_run, "event": "pull_request"},
+                    11: {**old_run, "status": "in_progress"}}[int(path.rsplit("/", 1)[1])]
+        instance.api.request = request
+        instance.cleanup_exports()
+        self.assertEqual(deleted, [(instance.repo_api + "/actions/artifacts/1", "DELETE"),
+                                   (instance.repo_api + "/actions/artifacts/2", "DELETE")])
+        self.assertTrue(instance.version(OLD_IMAGE)["exports"][0]["deleted"])
+
+    def test_signed_download_drops_token_and_rejects_other_origins(self):
+        api = maintenance_module.Api(self.config["api_url"], self.token)
+        destination = self.root / "artifact.zip"
+        seen = []
+        target = ["https://gitea.example.test/api/v1/repos/team/project/actions/artifacts/1/zip/raw?sig=test"]
+        class Opener:
+            def open(self, request, timeout):
+                seen.append(request)
+                if not isinstance(request, str):
+                    raise maintenance_module.urllib.error.HTTPError(request.full_url, 302, "Found", {"Location": target[0]}, None)
+                return io.BytesIO(b"archive")
+        with patch.object(maintenance_module.urllib.request, "build_opener", return_value=Opener()):
+            api.download("repos/team/project/actions/artifacts/1/zip", destination)
+            self.assertEqual(destination.read_bytes(), b"archive")
+            self.assertEqual(seen[0].get_header("Authorization"), "token test-token")
+            self.assertIsInstance(seen[1], str)  # signed URL request has no Authorization header
+            target[0] = "https://other.example.test/download"
+            with self.assertRaisesRegex(RuntimeError, "configured HTTPS Gitea origin"):
+                api.download("repos/team/project/actions/artifacts/1/zip", self.root / "rejected.zip")
+        self.assertFalse((self.root / "rejected.zip").exists())
+
+    def test_pending_chunk_cleanup_requires_old_terminal_master_run(self):
+        instance = self.maintenance({"versions": [], "current": None, "attempts": [{"run_id": 4}]})
+        instance.config["artifact_storage_dir"] = str(self.root / "storage")
+        run = {"id": 1, "status": "completed", "path": "project-ci.yml@refs/heads/master",
+               "event": "push", "head_branch": "master", "head_sha": SHA,
+               "completed_at": "2020-01-01T00:00:00Z"}
+        rows = [run, {**run, "id": 2, "event": "pull_request"},
+                {**run, "id": 3, "status": "in_progress"}, {**run, "id": 4},
+                {**run, "id": 5, "completed_at": "2999-01-01T00:00:00Z"}]
+        instance.api.pages = lambda *_: iter(rows)
+        with patch.object(maintenance_module, "cleanup_upload_chunks", return_value=0) as cleanup:
+            instance.cleanup_pending_uploads()
+        self.assertEqual(cleanup.call_args.args[1], {1})
+
+    def test_uncertain_or_inflight_gate_never_restarts(self):
+        instance, _, restarts = self.activation_maintenance(idle_values=[True])
+        statuses = 0
+
+        def uncertain_gate(action):
+            nonlocal statuses
+            if action == "pause":
+                return {"paused": True}
+            if action == "resume":
+                return {"paused": False}
+            statuses += 1
+            return {"paused": False} if statuses == 1 else {"paused": True, "uncertain": True, "inflight": 1}
+
+        instance.gate = uncertain_gate
+        with patch.object(maintenance_module.time, "sleep", lambda _: None):
+            with self.assertRaisesRegex(RuntimeError, "uncertain"):
+                instance.activate()
+        self.assertEqual(restarts, [])
+        self.assertEqual(instance.state["candidate"], IMAGE)
+        self.assertEqual(instance.state["current"], OLD_IMAGE)
+        self.assertNotIn("pause_owned", instance.state)
+
+    def test_inflight_gate_defers_without_restart_and_resumes(self):
+        instance, _, restarts = self.activation_maintenance(idle_values=[True])
+        statuses = 0
+
+        def inflight_gate(action):
+            nonlocal statuses
+            if action == "pause":
+                return {"paused": True}
+            if action == "resume":
+                return {"paused": False}
+            statuses += 1
+            return {"paused": False} if statuses == 1 else {"paused": True, "inflight": 1}
+
+        instance.gate = inflight_gate
+        with patch.object(maintenance_module.time, "sleep", lambda _: None):
+            self.assertFalse(instance.activate())
+        self.assertEqual(restarts, [])
+        self.assertEqual(instance.state["candidate"], IMAGE)
+        self.assertEqual(instance.state["current"], OLD_IMAGE)
+        self.assertNotIn("pause_owned", instance.state)
+
+    def test_interrupted_switch_recovers_current_candidate_and_rollback(self):
+        backup = self.root / "state" / "backups" / "switch.yaml"
+        backup.parent.mkdir(parents=True)
+        backup.write_text(runner_config(OLD_IMAGE), encoding="utf-8")
+        instance, _, restarts = self.activation_maintenance(
+            idle_values=[True, True],
+            switch={"old": OLD_IMAGE, "new": IMAGE, "backup": str(backup)},
+        )
+        with patch.object(maintenance_module.time, "sleep", lambda _: None):
+            self.assertTrue(instance.recover_switch())
+        self.assertEqual(len(restarts), 1)
+        self.assertEqual(instance.state["current"], IMAGE)
+        self.assertIsNone(instance.state["candidate"])
+        self.assertEqual(instance.state["rollback"], OLD_IMAGE)
+        self.assertNotIn("switch", instance.state)
+
+    def test_protected_images_include_state_bases_config_and_container_references(self):
+        current = self.record(OLD_IMAGE, owned=False, verified_run=1, base=BASE_IMAGE)
+        candidate = self.record(IMAGE, base=BASE_IMAGE)
+        container_image = "sha256:" + "4" * 64
+        instance = self.maintenance({"versions": [current, candidate], "current": OLD_IMAGE, "rollback": OLD_IMAGE, "candidate": IMAGE})
+        instance.read_config = lambda: runner_config(OLD_IMAGE)
+
+        def docker(*args, inner=False, **kwargs):
+            if args[:2] == ("ps", "-aq"):
+                return "container-1\n"
+            if args[:2] == ("inspect", "--format"):
+                return container_image + "\n"
+            raise AssertionError(args)
+
+        instance.docker = docker
+        protected = instance.protected_images()
+        self.assertTrue({OLD_IMAGE, IMAGE, BASE_IMAGE, container_image}.issubset(protected))
+
+    def test_cleanup_keeps_manual_images_and_rejects_outside_artifacts(self):
+        current = self.record(OLD_IMAGE, owned=False, verified_run=1)
+        manual = self.record(IMAGE, owned=False)
+        stale = self.record("sha256:" + "5" * 64, source="b" * 40)
+        stale["artifact"] = str(self.root / "outside")
+        instance = self.maintenance({"versions": [current, manual, stale], "current": OLD_IMAGE, "rollback": None, "candidate": None})
+        instance.protected_images = lambda: set()
+        instance.remove_owned_image = lambda *_: True
+        with self.assertRaisesRegex(RuntimeError, "outside"):
+            instance.cleanup()
+        self.assertIn(manual, instance.state["versions"])
+        self.assertIn(stale, instance.state["versions"])
+
+    def test_additional_tags_are_never_deleted(self):
+        instance = self.maintenance({"versions": [], "current": None, "rollback": None, "candidate": None})
+        removals = []
+        tag = "genarrative/gitea-project-ci:rust-cache-auto-" + SHA
+        instance.image_info = lambda image, inner=False: {"RepoTags": [tag, "operator:keep"]}
+        instance.docker = lambda *args, inner=False, **kwargs: (
+            IMAGE + "\n" if args[:2] == ("image", "ls") else removals.append(args) or ""
+        )
+        self.assertFalse(instance.remove_owned_image(IMAGE, tag, set()))
+        self.assertEqual(removals, [])
+
+    def test_owned_image_removal_handles_dangling_and_already_absent_images(self):
+        instance = self.maintenance({"versions": [], "current": None, "rollback": None, "candidate": None})
+        tag = "genarrative/gitea-project-ci:rust-cache-auto-" + SHA
+        present = {True: True, False: True}
+        removals = []
+
+        def docker(*args, inner=False, **kwargs):
+            if args[:2] == ("image", "ls"):
+                return IMAGE + "\n" if present[inner] else ""
+            if args[:3] == ("image", "rm", IMAGE):
+                removals.append((args, inner))
+                present[inner] = False
+                return IMAGE + "\n"
+            raise AssertionError(args)
+
+        instance.docker = docker
+        instance.image_info = lambda image, inner=False: {"RepoTags": []}
+        self.assertTrue(instance.remove_owned_image(IMAGE, tag, set()))
+        self.assertEqual({inner for _, inner in removals}, {True, False})
+        calls = []
+        instance.docker = lambda *args, inner=False, **kwargs: calls.append((args, inner)) or ""
+        self.assertTrue(instance.remove_owned_image(
+            IMAGE, "genarrative/gitea-project-ci:rust-cache-auto-" + SHA, set()))
+        self.assertFalse(any(args[:3] == ("image", "rm", IMAGE) for args, _ in calls))
+
+    def test_manual_current_without_cache_stats_can_be_verified(self):
+        current = self.record(OLD_IMAGE, source=None, owned=False)
+        instance = self.maintenance({"versions": [current], "current": OLD_IMAGE, "rollback": None, "candidate": None})
+        jobs = [
+            {"id": index, "name": name, "conclusion": "success"}
+            for index, name in enumerate(sorted(maintenance_module.JOBS), start=1)
+        ]
+        run = {
+            "id": 44,
+            "status": "completed",
+            "conclusion": "success",
+            "event": "push",
+            "path": "project-ci.yml@refs/heads/master",
+            "head_sha": SHA,
+            "started_at": "2026-01-02T00:00:00Z",
+        }
+
+        class VerificationApi:
+            def pages(self, path, key):
+                if path.endswith("/actions/runs?status=success&branch=master&event=push"):
+                    return iter([run])
+                if path.endswith("/actions/runs/44/jobs"):
+                    return iter(jobs)
+                raise AssertionError(path)
+
+            def request(self, path, *, method, body=None, raw=False):
+                if not raw or "/actions/jobs/" not in path:
+                    raise AssertionError(path)
+                return f"runner image: {OLD_IMAGE}\n"
+
+        instance.api = VerificationApi()
+        with patch.object(maintenance_module.subprocess, "run", return_value=type("Result", (), {"returncode": 0})()):
+            self.assertTrue(instance.verify_current())
+        self.assertEqual(instance.version(OLD_IMAGE)["verified_run"], 44)
+        self.assertEqual(instance.version(OLD_IMAGE)["verified_sha"], SHA)
+
+    def test_recover_builds_adopts_only_pre_registered_attempt_tags(self):
+        tag = "genarrative/gitea-project-ci:rust-cache-auto-" + SHA
+        base_tag = "genarrative/gitea-project-ci:base-auto-" + SHA
+        artifact = self.root / "state" / "artifacts" / SHA
+        attempt = {"source": SHA, "inputs": "inputs", "tag": tag, "base_tag": base_tag, "artifact": str(artifact)}
+        instance = self.maintenance({
+            "versions": [], "current": None, "rollback": None, "candidate": None,
+            "attempts": [attempt],
+        })
+        queries = []
+
+        def docker(*args, inner=False, **kwargs):
+            if args[:3] == ("image", "ls", "--no-trunc"):
+                queries.append(args[-1])
+                return BASE_IMAGE + "\n" if args[-1] == base_tag else IMAGE + "\n"
+            raise AssertionError(args)
+
+        instance.docker = docker
+        instance.image_info = lambda image, inner=False: {
+            "Config": {"Labels": {
+                "world.genarrative.ci.rust-cache-source": SHA,
+                "world.genarrative.ci.rust-cache-base": BASE_IMAGE,
+            }}
+        }
+        instance.recover_builds()
+        self.assertEqual(queries, [base_tag, tag])
+        self.assertEqual(instance.state["attempts"], [])
+        self.assertEqual(instance.state["bases"], {BASE_IMAGE: base_tag})
+        self.assertEqual(instance.state["versions"][0]["image"], IMAGE)
+        self.assertTrue(instance.state["versions"][0]["owned"])
+        self.assertEqual(instance.state["candidate"], IMAGE)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_snapshot.py b/scripts/test_gitea_cache_snapshot.py
new file mode 100644
index 000000000..135cd903b
--- /dev/null
+++ b/scripts/test_gitea_cache_snapshot.py
@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""Tests for streamed Gitea sccache snapshot validation and merging."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import io
+import json
+from pathlib import Path
+import os
+import sys
+import tarfile
+import tempfile
+import unittest
+import zipfile
+
+
+SCRIPT = Path(__file__).with_name("gitea_cache_snapshot.py")
+SPEC = importlib.util.spec_from_file_location("gitea_cache_snapshot", SCRIPT)
+assert SPEC and SPEC.loader
+snapshot = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = snapshot
+SPEC.loader.exec_module(snapshot)
+
+REPOSITORY = "team/project"
+SOURCE_SHA = "a" * 40
+INHERITED_SOURCE_SHA = "c" * 40
+BASE_IMAGE = "sha256:" + "b" * 64
+RUSTC = "rustc 1.90.0\nbinary: rustc\n"
+WORKSPACE = "/workspace/GenarrativeAI/Genarrative"
+SCCACHE_VERSION = "0.18.0"
+
+
+def object_path(character: str) -> str:
+    key = character * 64
+    return f"objects/{key[0]}/{key[1]}/{key}"
+
+
+class SnapshotMergeTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory(ignore_cleanup_errors=True)
+        self.root = Path(self.temporary_directory.name).resolve()
+        self.base = self.root / "base-objects"
+        self.base.mkdir()
+
+    def tearDown(self) -> None:
+        self.temporary_directory.cleanup()
+
+    def identity(self, job: str, run_id: int) -> object:
+        return snapshot.ArtifactIdentity(REPOSITORY, run_id, 1, job, SOURCE_SHA)
+
+    def archive(
+        self,
+        name: str,
+        job: str,
+        run_id: int,
+        objects: list[tuple[str, bytes, int]],
+        *,
+        prefix: bool = True,
+        manifest_update=None,
+        extra_member: tuple[str, bytes, str] | None = None,
+        touched: list[tuple[str, int]] | None = None,
+    ) -> object:
+        rows = [
+            {
+                "path": path,
+                "size": len(contents),
+                "sha256": hashlib.sha256(contents).hexdigest(),
+                "mtime_ns": mtime_ns,
+            }
+            for path, contents, mtime_ns in objects
+        ]
+        manifest = {
+            "schema": 1,
+            "repository": REPOSITORY,
+            "run_id": run_id,
+            "run_attempt": 1,
+            "job": job,
+            "source_sha": SOURCE_SHA,
+            "base_image": BASE_IMAGE,
+            "rustc": RUSTC,
+            "workspace": WORKSPACE,
+            "sccache_version": SCCACHE_VERSION,
+            "mode": "delta",
+            "inherited_source_sha": INHERITED_SOURCE_SHA,
+            "objects": rows,
+            "touched": [
+                {"path": path, "mtime_ns": mtime_ns}
+                for path, mtime_ns in (touched or [])
+            ],
+        }
+        if manifest_update is not None:
+            manifest_update(manifest)
+
+        tar_bytes = io.BytesIO()
+        with tarfile.open(fileobj=tar_bytes, mode="w") as bundle:
+            for path, contents, _ in objects:
+                info = tarfile.TarInfo(path)
+                info.size = len(contents)
+                bundle.addfile(info, io.BytesIO(contents))
+            if extra_member is not None:
+                path, contents, kind = extra_member
+                info = tarfile.TarInfo(path)
+                if kind == "symlink":
+                    info.type = tarfile.SYMTYPE
+                    info.linkname = "manifest.json"
+                    bundle.addfile(info)
+                else:
+                    info.size = len(contents)
+                    bundle.addfile(info, io.BytesIO(contents))
+            manifest_bytes = json.dumps(manifest, separators=(",", ":")).encode()
+            info = tarfile.TarInfo("manifest.json")
+            info.size = len(manifest_bytes)
+            bundle.addfile(info, io.BytesIO(manifest_bytes))
+
+        archive = self.root / f"{name}.zip"
+        member = f"{name}/snapshot.tar" if prefix else "snapshot.tar"
+        with zipfile.ZipFile(archive, "w", compression=zipfile.ZIP_STORED) as bundle:
+            bundle.writestr(member, tar_bytes.getvalue())
+        return snapshot.ArtifactInput(archive, self.identity(job, run_id))
+
+    def base_object(self, path: str, contents: bytes, mtime_ns: int) -> None:
+        target = self.base.joinpath(*Path(path).parts[1:])
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(contents)
+        os.utime(target, ns=(mtime_ns, mtime_ns))
+
+    def merge(self, inputs, output=None, maximum=1024 ** 3):
+        return snapshot.merge_snapshots(
+            inputs,
+            output or self.root / "merged",
+            base_objects=self.base,
+            expected_inherited_source_sha=INHERITED_SOURCE_SHA,
+            max_combined_bytes=maximum,
+        )
+
+    def test_merges_groups_deduplicates_newest_mtime_and_prunes_to_bound(self) -> None:
+        first_path = object_path("a")
+        second_path = object_path("b")
+        third_path = object_path("c")
+        inherited_path = object_path("d")
+        self.base_object(inherited_path, b"dd", 50)
+        inputs = [
+            self.archive("first", "Backend tests", 41, [
+                (first_path, b"aaaa", 100),
+                (second_path, b"bbbb", 200),
+            ]),
+            self.archive("second", "Native shell tests", 41, [
+                (first_path, b"aaaa", 300),
+                (third_path, b"ccc", 250),
+            ], prefix=False, touched=[(inherited_path, 400)]),
+        ]
+
+        output = self.root / "merged"
+        result = self.merge(inputs, output, maximum=9)
+
+        self.assertEqual((result.object_count, result.total_bytes), (3, 9))
+        self.assertEqual((output / inherited_path).read_bytes(), b"dd")
+        self.assertEqual((output / first_path).read_bytes(), b"aaaa")
+        self.assertEqual((output / third_path).read_bytes(), b"ccc")
+        self.assertFalse((output / second_path).exists())
+        self.assertEqual((output / "rustc.txt").read_text(), RUSTC)
+        self.assertEqual((output / "workspace.txt").read_text(), WORKSPACE + "\n")
+        self.assertEqual((output / "source-commit.txt").read_text(), SOURCE_SHA + "\n")
+        self.assertEqual((output / "base-image.txt").read_text(), BASE_IMAGE + "\n")
+        self.assertFalse((output / "sccache").exists())
+
+    def test_rejects_traversal_member_without_creating_output(self) -> None:
+        item = self.archive(
+            "traversal", "Backend tests", 42, [],
+            extra_member=("../outside", b"bad", "file"),
+        )
+        output = self.root / "merged"
+        with self.assertRaisesRegex(snapshot.SnapshotError, "invalid sccache object path"):
+            self.merge([item], output)
+        self.assertFalse(output.exists())
+        self.assertFalse((self.root / "outside").exists())
+
+    def test_rejects_checksum_mismatch(self) -> None:
+        path = object_path("d")
+
+        def corrupt(manifest):
+            manifest["objects"][0]["sha256"] = "0" * 64
+
+        item = self.archive(
+            "checksum", "Backend tests", 43, [(path, b"content", 1)],
+            manifest_update=corrupt,
+        )
+        with self.assertRaisesRegex(snapshot.SnapshotError, "checksums do not match"):
+            self.merge([item])
+
+    def test_rejects_manifest_identity_mismatch(self) -> None:
+        item = self.archive(
+            "identity", "Backend tests", 44, [],
+            manifest_update=lambda manifest: manifest.update(run_id=999),
+        )
+        with self.assertRaisesRegex(snapshot.SnapshotError, "run_id does not match"):
+            self.merge([item])
+
+    def test_rejects_conflicting_duplicate_key(self) -> None:
+        path = object_path("e")
+        inputs = [
+            self.archive("conflict-one", "Backend tests", 45, [(path, b"one", 1)]),
+            self.archive("conflict-two", "Native shell tests", 45, [(path, b"two", 2)]),
+        ]
+        with self.assertRaisesRegex(snapshot.SnapshotError, "conflicting content"):
+            self.merge(inputs)
+
+    def test_rejects_delta_that_conflicts_with_inherited_key(self) -> None:
+        path = object_path("f")
+        self.base_object(path, b"base", 1)
+        item = self.archive("base-conflict", "Backend tests", 46, [(path, b"evil", 2)])
+        with self.assertRaisesRegex(snapshot.SnapshotError, "conflicting content"):
+            self.merge([item])
+
+    def test_accepts_empty_delta(self) -> None:
+        item = self.archive("empty", "Backend tests", 47, [])
+        output = self.root / "merged"
+        result = self.merge([item], output)
+        self.assertEqual((result.object_count, result.total_bytes), (0, 0))
+        self.assertEqual(list((output / "objects").iterdir()), [])
+
+    def test_rejects_noncanonical_base_entry(self) -> None:
+        (self.base / "unexpected").write_bytes(b"not an object")
+        item = self.archive("base-path", "Backend tests", 48, [])
+        with self.assertRaisesRegex(snapshot.SnapshotError, "noncanonical entry"):
+            self.merge([item])
+
+    def test_rejects_tar_links(self) -> None:
+        item = self.archive(
+            "link", "Backend tests", 49, [],
+            extra_member=(object_path("9"), b"", "symlink"),
+        )
+        with self.assertRaisesRegex(snapshot.SnapshotError, "regular file"):
+            self.merge([item])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_gitea_cache_upload_cleanup.py b/scripts/test_gitea_cache_upload_cleanup.py
new file mode 100644
index 000000000..6ebe0d200
--- /dev/null
+++ b/scripts/test_gitea_cache_upload_cleanup.py
@@ -0,0 +1,90 @@
+"""缓存上传残块清理只触碰已确认结束的过期自有文件。"""
+
+import base64
+import os
+from pathlib import Path
+import tempfile
+import unittest
+
+from gitea_cache_upload_cleanup import cleanup_upload_chunks, decode_owner
+
+
+class UploadCleanupTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name).resolve()
+
+    def file(self, name, run=12, age=10):
+        directory = self.root / "tmp-upload" / f"run-{run}-v4"
+        directory.mkdir(parents=True, exist_ok=True)
+        path = directory / name
+        path.write_bytes(b"block data")
+        os.utime(path, (age, age))
+        return path
+
+    def block(self, artifact=34, run=12, age=10, marker="genarrative-rust-cache-v1:backend-tests:1:00000000"):
+        encoded = base64.urlsafe_b64encode(base64.b64encode(marker.encode())).decode()
+        return self.file(f"block-{run}-{artifact}-10-{encoded}", run, age)
+
+    def test_old_owned_blocks_and_associated_blocklist_are_deleted(self):
+        block = self.block()
+        blocklist = self.file("12-34-blocklist")
+        self.assertEqual(cleanup_upload_chunks(self.root, {12}, 20), 2)
+        self.assertFalse(block.exists())
+        self.assertFalse(blocklist.exists())
+        self.assertTrue(block.parent.is_dir())
+
+    def test_other_runs_artifacts_and_unproven_blocklists_remain(self):
+        own = self.block()
+        other_run = self.block(run=13)
+        other_artifact = self.block(artifact=35, marker="unrelated-upload")
+        unproven = self.file("12-36-blocklist")
+        self.assertEqual(cleanup_upload_chunks(self.root, {12}, 20), 1)
+        self.assertFalse(own.exists())
+        self.assertTrue(all(path.exists() for path in (other_run, other_artifact, unproven)))
+
+    def test_young_or_unknown_member_protects_entire_artifact_group(self):
+        own = self.block()
+        young = self.file("12-34-blocklist", age=20)
+        other = self.block(artifact=35)
+        unknown = self.file("block-12-35-invalid-size-unknown")
+        self.assertEqual(cleanup_upload_chunks(self.root, {12}, 20), 0)
+        self.assertTrue(all(path.exists() for path in (own, young, other, unknown)))
+
+    def test_completely_unknown_file_protects_entire_run(self):
+        block = self.block()
+        self.file("unknown")
+        self.assertEqual(cleanup_upload_chunks(self.root, {12}, 20), 0)
+        self.assertTrue(block.exists())
+
+    @unittest.skipUnless(os.name == "posix", "symlink fixture requires POSIX")
+    def test_symlinks_never_traversed_or_deleted(self):
+        block = self.block()
+        outside = self.root / "secret"
+        outside.write_text("keep")
+        (block.parent / "12-34-blocklist").symlink_to(outside)
+        (self.root / "tmp-upload" / "run-13-v4").symlink_to(block.parent, target_is_directory=True)
+        self.assertEqual(cleanup_upload_chunks(self.root, {12, 13}, 20), 0)
+        self.assertTrue(block.exists())
+        self.assertEqual(outside.read_text(), "keep")
+        linked = self.root / "root-link"
+        linked.symlink_to(self.root, target_is_directory=True)
+        with self.assertRaises(ValueError):
+            cleanup_upload_chunks(linked, {12}, 20)
+
+    def test_root_missing_or_relative_is_an_error(self):
+        with self.assertRaises(FileNotFoundError):
+            cleanup_upload_chunks(self.root / "missing", {12}, 20)
+        with self.assertRaises(ValueError):
+            cleanup_upload_chunks(Path("relative"), {12}, 20)
+
+    def test_noncanonical_encoding_and_unknown_job_are_not_owned(self):
+        for marker in ("genarrative-rust-cache-v1:other-job:1:00000000", "genarrative-rust-cache-v1:backend-tests:01:00000000"):
+            encoded = base64.urlsafe_b64encode(base64.b64encode(marker.encode())).decode()
+            self.assertIsNone(decode_owner(encoded))
+        self.assertIsNone(decode_owner("not-base64"))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/server-rs/Cargo.lock b/server-rs/Cargo.lock
index 785804027..ac57523c6 100644
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -217,6 +217,7 @@ dependencies = [
  "module-assets",
  "module-auth",
  "module-editor-agent",
+ "module-game-distribution",
  "module-runtime",
  "opentelemetry",
  "platform-audio",
@@ -2898,6 +2899,17 @@ dependencies = [
  "spacetimedb",
 ]
 
+[[package]]
+name = "module-game-distribution"
+version = "0.1.0"
+dependencies = [
+ "hex",
+ "serde",
+ "sha2",
+ "shared-kernel",
+ "zip",
+]
+
 [[package]]
 name = "module-runtime"
 version = "0.1.0"
diff --git a/server-rs/Cargo.toml b/server-rs/Cargo.toml
index 6f312b2ed..33df718b3 100644
--- a/server-rs/Cargo.toml
+++ b/server-rs/Cargo.toml
@@ -18,6 +18,7 @@ members = [
     "crates/module-assets",
     "crates/module-auth",
     "crates/module-editor-agent",
+    "crates/module-game-distribution",
     "crates/module-runtime",
     "crates/platform-oss",
     "crates/platform-auth",
@@ -52,6 +53,7 @@ module-ai = { path = "crates/module-ai", default-features = false }
 module-assets = { path = "crates/module-assets", default-features = false }
 module-auth = { path = "crates/module-auth", default-features = false }
 module-editor-agent = { path = "crates/module-editor-agent", default-features = false }
+module-game-distribution = { path = "crates/module-game-distribution", default-features = false }
 module-runtime = { path = "crates/module-runtime", default-features = false }
 platform-agent-harness = { path = "crates/platform-agent-harness", default-features = false }
 platform-editor-agent = { path = "crates/platform-editor-agent", default-features = false }
diff --git a/server-rs/crates/api-server/Cargo.toml b/server-rs/crates/api-server/Cargo.toml
index d7587be2d..6292a9490 100644
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -23,6 +23,7 @@ module-ai = { workspace = true }
 module-assets = { workspace = true, features = ["server-service"] }
 module-auth = { workspace = true }
 module-editor-agent = { workspace = true }
+module-game-distribution = { workspace = true }
 module-runtime = { workspace = true }
 platform-editor-agent = { workspace = true }
 platform-audio = { workspace = true }
diff --git a/server-rs/crates/api-server/src/admin.rs b/server-rs/crates/api-server/src/admin.rs
index ea371e078..2f9838531 100644
--- a/server-rs/crates/api-server/src/admin.rs
+++ b/server-rs/crates/api-server/src/admin.rs
@@ -2206,6 +2206,7 @@ fn admin_permission_requirement(_method: &Method, path: &str) -> AdminPermission
         "/admin/api/editor-assets" => AnyTab(&["editor-assets"]),
         "/admin/api/assets/read-url" => AnyTab(&["editor-assets", "editor-showcase"]),
         path if path.starts_with("/admin/api/editor-showcase/") => AnyTab(&["editor-showcase"]),
+        path if path.starts_with("/admin/api/game-distribution/") => AnyTab(&["editor-showcase"]),
         "/admin/api/profile/redeem-codes" | "/admin/api/profile/redeem-codes/disable" => {
             AnyTab(&["redeem"])
         }
diff --git a/server-rs/crates/api-server/src/app.rs b/server-rs/crates/api-server/src/app.rs
index 74bee3b24..d23316068 100644
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -48,6 +48,7 @@ pub fn build_router(state: AppState) -> Router {
         .merge(modules::profile::router(state.clone()))
         .merge(modules::external_api::router(state.clone()))
         .merge(modules::frontend_runtime_config::router(state.clone()))
+        .merge(modules::game_distribution::router(state.clone()))
         .merge(modules::assets::router(state.clone()))
         .merge(modules::editor_project::router(state.clone()))
         .merge(modules::platform::router(state.clone()))
@@ -1233,6 +1234,11 @@ mod tests {
             payload["imageEditorAgentSidebarEnabled"],
             Value::Bool(false)
         );
+        // 未登录不开放发布入口，避免灰度对游客下发可用状态。
+        assert_eq!(
+            payload["gameDistributionPublishEnabled"],
+            Value::Bool(false)
+        );
     }
 
     #[tokio::test]
@@ -1280,6 +1286,50 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn frontend_runtime_config_game_distribution_publish_is_scoped_to_authenticated_gate() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let user = seed_phone_user_with_password(&state, "13800138195", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &user, "sess_game_distribution_publish_gate");
+        let mut gate = test_feature_gate(module_runtime::GAME_DISTRIBUTION_PUBLISH_GATE_KEY);
+        // 无 gate 行时默认开放：已登录作者拿到 true，匿名仍为 false。
+        let mut cases = vec![(vec![], true)];
+        cases.push((vec![gate.clone()], false));
+        gate.allow_user_ids = vec![user.id.clone()];
+        cases.push((vec![gate.clone()], true));
+        gate.deny_user_ids = vec![user.id.clone()];
+        cases.push((vec![gate.clone()], false));
+        gate.enabled = false;
+        cases.push((vec![gate.clone()], true));
+        gate.enabled = true;
+        gate.allow_user_ids.clear();
+        gate.deny_user_ids.clear();
+        gate.rollout_percent = 100;
+        cases.push((vec![gate], true));
+
+        for (gates, expected) in cases {
+            state.set_test_feature_gate_config(gates);
+            let app = build_router(state.clone());
+            for authenticated in [false, true] {
+                let mut request = Request::builder().uri("/api/runtime/frontend-config");
+                if authenticated {
+                    request = request.header("authorization", format!("Bearer {token}"));
+                }
+                let response = app
+                    .clone()
+                    .oneshot(request.body(Body::empty()).unwrap())
+                    .await
+                    .unwrap();
+                assert_eq!(response.status(), StatusCode::OK);
+                let payload = read_json_response(response).await;
+                assert_eq!(
+                    payload["gameDistributionPublishEnabled"],
+                    Value::Bool(authenticated && expected)
+                );
+            }
+        }
+    }
+
     #[tokio::test]
     async fn frontend_runtime_config_returns_agent_sidebar_env_flag() {
         let config = AppConfig {
@@ -1540,6 +1590,91 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn game_distribution_publish_switch_blocks_writes_but_keeps_reads_and_allowlist() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let user = seed_phone_user_with_password(&state, "13800138112", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &user, "sess_game_publish_switch");
+        let payload = serde_json::json!({
+            "title": "开关验证",
+            "summary": "发布开关验证",
+            "description": "发布开关验证",
+            "category": "其他",
+            "tags": ["验证"],
+            "deviceSupport": { "desktop": true, "mobile": false, "touch": false },
+            "inputModes": ["keyboard"],
+            "orientation": "responsive",
+            "localProjectId": "publish-switch-test"
+        })
+        .to_string();
+        let app = build_router(state.clone());
+        let publish_request = || {
+            Request::builder()
+                .method("POST")
+                .uri("/api/game-distribution/games")
+                .header("authorization", format!("Bearer {token}"))
+                .header("content-type", "application/json")
+                .header("idempotency-key", "publish-switch-test-1")
+                .body(Body::from(payload.clone()))
+                .expect("request should build")
+        };
+
+        // 默认没有 gate 行：写入进入业务，不能被发布开关拦下。
+        let open = app
+            .clone()
+            .oneshot(publish_request())
+            .await
+            .expect("request should succeed");
+        assert_ne!(
+            open.status(),
+            StatusCode::SERVICE_UNAVAILABLE,
+            "默认状态不应拦截发布"
+        );
+
+        // 运营收紧到 rollout 0 且无白名单：作者写入 503 + 专用错误码。
+        state.set_test_feature_gate_config(vec![test_feature_gate(
+            module_runtime::GAME_DISTRIBUTION_PUBLISH_GATE_KEY,
+        )]);
+        let blocked = app
+            .clone()
+            .oneshot(publish_request())
+            .await
+            .expect("request should succeed");
+        assert_eq!(blocked.status(), StatusCode::SERVICE_UNAVAILABLE);
+        let blocked_payload = read_json_response(blocked).await;
+        assert_eq!(
+            blocked_payload["error"]["code"],
+            "GAME_DISTRIBUTION_PUBLISH_DISABLED"
+        );
+
+        // 读取不受影响：公开目录仍走业务路径，不是发布关闭。
+        let catalog = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri("/api/game-distribution/games")
+                    .body(Body::empty())
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+        assert_ne!(catalog.status(), StatusCode::SERVICE_UNAVAILABLE);
+
+        // 白名单内用户仍可发布（灰度放行）。
+        let mut gate = test_feature_gate(module_runtime::GAME_DISTRIBUTION_PUBLISH_GATE_KEY);
+        gate.allow_user_ids = vec![user.id.clone()];
+        state.set_test_feature_gate_config(vec![gate]);
+        let allowed = app
+            .oneshot(publish_request())
+            .await
+            .expect("request should succeed");
+        assert_ne!(
+            allowed.status(),
+            StatusCode::SERVICE_UNAVAILABLE,
+            "白名单用户不应被发布开关拦截"
+        );
+    }
+
     fn test_feature_gate(gate_key: &str) -> module_runtime::FeatureGateConfigSnapshot {
         module_runtime::FeatureGateConfigSnapshot {
             gate_key: gate_key.to_string(),
diff --git a/server-rs/crates/api-server/src/frontend_runtime_config.rs b/server-rs/crates/api-server/src/frontend_runtime_config.rs
index 28ab6bd31..dea103eca 100644
--- a/server-rs/crates/api-server/src/frontend_runtime_config.rs
+++ b/server-rs/crates/api-server/src/frontend_runtime_config.rs
@@ -16,6 +16,9 @@ use crate::{
 pub struct FrontendRuntimeConfigResponse {
     pub image_editor_agent_sidebar_enabled: bool,
     pub agc_template_library_enabled: bool,
+    /// 游戏发布灰度：运营未配置 `game-distribution:publish` 时对已登录作者默认开放，
+    /// 显式收紧后只有白名单/灰度命中的作者拿到 `true`；匿名一律 `false`（发布必须先登录）。
+    pub game_distribution_publish_enabled: bool,
 }
 
 pub async fn get_frontend_runtime_config(
@@ -57,6 +60,22 @@ pub async fn get_frontend_runtime_config(
                 }))
         })?;
 
+    let game_distribution_publish_enabled = match user_id {
+        Some(user_id) => state
+            .is_game_distribution_publish_enabled_for_user(Some(user_id))
+            .await
+            .map_err(|error| {
+                AppError::from_status(StatusCode::BAD_GATEWAY)
+                    .with_message("读取前端运行时配置失败")
+                    .with_details(json!({
+                        "provider": "spacetimedb",
+                        "message": error.to_string(),
+                    }))
+            })?,
+        // 未登录时发布入口不开放：灰度只面向已登录作者，写入口也要求 Bearer 会话。
+        None => false,
+    };
+
     Ok((
         [
             (header::CACHE_CONTROL, "no-store"),
@@ -67,6 +86,7 @@ pub async fn get_frontend_runtime_config(
             FrontendRuntimeConfigResponse {
                 image_editor_agent_sidebar_enabled,
                 agc_template_library_enabled,
+                game_distribution_publish_enabled,
             },
         ),
     )
diff --git a/server-rs/crates/api-server/src/modules.rs b/server-rs/crates/api-server/src/modules.rs
index 1f9143d47..f03412553 100644
--- a/server-rs/crates/api-server/src/modules.rs
+++ b/server-rs/crates/api-server/src/modules.rs
@@ -6,6 +6,7 @@ pub mod editor_project;
 pub mod external_api;
 pub mod external_generation;
 pub mod frontend_runtime_config;
+pub mod game_distribution;
 pub mod health;
 pub mod internal;
 pub mod platform;
diff --git a/server-rs/crates/api-server/src/modules/game_distribution.rs b/server-rs/crates/api-server/src/modules/game_distribution.rs
new file mode 100644
index 000000000..5ed4b8608
--- /dev/null
+++ b/server-rs/crates/api-server/src/modules/game_distribution.rs
@@ -0,0 +1,2195 @@
+use std::{
+    collections::{BTreeMap, HashMap, VecDeque},
+    sync::{Arc, Mutex, OnceLock},
+    time::{SystemTime, UNIX_EPOCH},
+};
+
+use axum::{
+    Json, Router,
+    body::{Body, Bytes},
+    extract::{DefaultBodyLimit, Extension, Path, Query, State},
+    http::{HeaderMap, HeaderValue, StatusCode, header},
+    middleware,
+    response::Response,
+    routing::{get, post, put},
+};
+use module_game_distribution::{
+    MAX_PACKAGE_BYTES, ReleaseAssetError, ReleasePackageError, ReleasePackageManifest,
+    compute_request_digest, extract_release_asset, release_asset_content_type,
+    validate_release_zip,
+};
+use platform_oss::{OssGetObjectRequest, OssInternalPutObjectRequest, OssObjectAccess};
+use serde::Deserialize;
+use serde_json::{Value, json};
+use shared_contracts::game_distribution::{
+    GAME_DISTRIBUTION_CATEGORIES, GameDistributionCreateGameRequest,
+    GameDistributionCreateVersionRequest, GameDistributionInputMode,
+};
+use spacetime_client::{
+    GameDistributionApproveRecordInput, GameDistributionCancelVersionRecordInput,
+    GameDistributionGameRecord, GameDistributionGetGameRecordInput,
+    GameDistributionPublicGameListRecordInput, GameDistributionPublicGameRecord,
+    GameDistributionRejectRecordInput, GameDistributionSubmitReviewRecordInput,
+    GameDistributionSuspendRecordInput, GameDistributionUnpublishRecordInput,
+    GameDistributionVersionRecord, SpacetimeClientError,
+};
+use tracing::{debug, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    admin::{AuthenticatedAdmin, require_admin_auth},
+    api_response::json_success_body,
+    auth::{AuthenticatedAccessToken, require_bearer_auth},
+    http_error::AppError,
+    platform_errors::map_oss_error,
+    request_context::RequestContext,
+    state::AppState,
+};
+
+pub(crate) const MAX_PACKAGE_REQUEST_BODY_BYTES: usize = MAX_PACKAGE_BYTES as usize + 1024;
+const MAX_LIST_LIMIT: u32 = 48;
+const MAX_IDEMPOTENCY_KEY_CHARS: usize = 128;
+const MAX_PACKAGE_MANIFEST_JSON_BYTES: usize = 2 * 1024 * 1024;
+/// 首版截图上限，与主规范冻结口径一致。
+const MAX_GAME_SCREENSHOTS: usize = 6;
+const GAME_DISTRIBUTION_OBJECT_PREFIX: &str = "agc/project-snapshots/v1/game-distribution/";
+const GAME_DISTRIBUTION_PUBLISHED_STATUS: &str = "published";
+/// 发行包 PUT 的尝试次数与退避，口径与 `platform-oss` 的可重试分类一致。
+const GAME_DISTRIBUTION_OSS_PUT_MAX_ATTEMPTS: usize = 3;
+const GAME_DISTRIBUTION_OSS_PUT_RETRY_DELAYS_MS: [u64; 2] = [250, 500];
+const RELEASE_PACKAGE_CACHE_MAX_ENTRIES: usize = 4;
+const RELEASE_PACKAGE_CACHE_MAX_BYTES: usize = 200 * 1024 * 1024;
+
+/// 发行静态资源的进程内缓存。
+///
+/// 单个资源取自整个 ZIP，若每个请求都重新下载整包会拖垮发行网关；缓存只保存已通过
+/// 校验的私有包字节，键是对象键，超出条目或字节预算时按插入顺序淘汰。
+static RELEASE_PACKAGE_CACHE: OnceLock<Mutex<ReleasePackageCache>> = OnceLock::new();
+
+#[derive(Default)]
+struct ReleasePackageCache {
+    packages: HashMap<String, Arc<Vec<u8>>>,
+    order: VecDeque<String>,
+    total_bytes: usize,
+}
+
+impl ReleasePackageCache {
+    fn get(&self, object_key: &str) -> Option<Arc<Vec<u8>>> {
+        self.packages.get(object_key).cloned()
+    }
+
+    fn insert(&mut self, object_key: String, bytes: Arc<Vec<u8>>) {
+        self.insert_with_limits(
+            object_key,
+            bytes,
+            RELEASE_PACKAGE_CACHE_MAX_ENTRIES,
+            RELEASE_PACKAGE_CACHE_MAX_BYTES,
+        );
+    }
+
+    fn insert_with_limits(
+        &mut self,
+        object_key: String,
+        bytes: Arc<Vec<u8>>,
+        max_entries: usize,
+        max_bytes: usize,
+    ) {
+        if self.packages.contains_key(&object_key) {
+            return;
+        }
+        // 单个包超过缓存预算时直接不缓存，避免一次插入把整个进程内存顶满。
+        if bytes.len() > max_bytes {
+            return;
+        }
+        while self.order.len() >= max_entries
+            || self.total_bytes.saturating_add(bytes.len()) > max_bytes
+        {
+            let Some(evicted) = self.order.pop_front() else {
+                break;
+            };
+            if let Some(previous) = self.packages.remove(&evicted) {
+                self.total_bytes = self.total_bytes.saturating_sub(previous.len());
+            }
+        }
+        self.total_bytes = self.total_bytes.saturating_add(bytes.len());
+        self.order.push_back(object_key.clone());
+        self.packages.insert(object_key, bytes);
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct GameListQuery {
+    #[serde(alias = "keyword")]
+    search: Option<String>,
+    category: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AdminReviewListQuery {
+    limit: Option<u32>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PublicationRevisionRequest {
+    expected_publication_revision: u64,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AdminReviewRequest {
+    decision: String,
+    expected_publication_revision: u64,
+    #[serde(default)]
+    review_reason: Option<String>,
+    #[serde(default)]
+    entry_url: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct CancelVersionRequest {
+    expected_publication_revision: u64,
+    #[serde(default)]
+    reason: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AdminSuspendRequest {
+    expected_publication_revision: u64,
+    #[serde(default)]
+    reason: Option<String>,
+}
+
+pub fn router(state: AppState) -> Router<AppState> {
+    let protected = Router::new()
+        .route("/api/game-distribution/games", post(create_game))
+        .route(
+            "/api/game-distribution/games/{game_id}/versions",
+            post(create_version),
+        )
+        .route(
+            "/api/game-distribution/versions/{version_id}/package",
+            put(upload_package).layer(DefaultBodyLimit::max(MAX_PACKAGE_REQUEST_BODY_BYTES)),
+        )
+        .route(
+            "/api/game-distribution/versions/{version_id}/submit",
+            post(submit_version),
+        )
+        .route(
+            "/api/game-distribution/versions/{version_id}",
+            get(get_owner_version),
+        )
+        .route(
+            "/api/game-distribution/versions/{version_id}/cancel",
+            post(cancel_version),
+        )
+        .route("/api/game-distribution/my-games", get(list_my_games))
+        .route(
+            "/api/game-distribution/games/{game_id}/unpublish",
+            post(unpublish_game),
+        )
+        .route_layer(middleware::from_fn_with_state(
+            state.clone(),
+            require_bearer_auth,
+        ));
+
+    let admin = Router::new()
+        .route(
+            "/admin/api/game-distribution/reviews",
+            get(admin_list_reviews),
+        )
+        .route(
+            "/admin/api/game-distribution/versions/{version_id}/review",
+            post(admin_review_version),
+        )
+        .route(
+            "/admin/api/game-distribution/versions/{version_id}",
+            get(admin_get_version),
+        )
+        .route(
+            "/admin/api/game-distribution/games/{game_id}/suspend",
+            post(admin_suspend_game),
+        )
+        .route_layer(middleware::from_fn_with_state(
+            state.clone(),
+            require_admin_auth,
+        ));
+
+    Router::new()
+        .route("/api/game-distribution/games", get(list_games))
+        .route("/api/game-distribution/games/{game_id}", get(get_game))
+        .route(
+            "/api/game-distribution/releases/{game_id}/{*asset_path}",
+            get(serve_release_asset),
+        )
+        .merge(protected)
+        .merge(admin)
+}
+
+/// 公开发行网关。
+///
+/// 只服务当前已公开版本的游戏文件，路径必须在白名单内容类型内；私有 ZIP 对象和
+/// 未公开版本不会因为知道 ID 而可读。
+async fn serve_release_asset(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    Path((game_id, asset_path)): Path<(String, String)>,
+) -> Result<Response, AppError> {
+    // 发行文件必须由独立来源提供。带上平台 Cookie 的请求说明它正落在主站来源上，
+    // 此时同源脚本可以读到平台会话，必须直接关闭而不是降级服务。
+    if headers.contains_key(header::COOKIE) {
+        debug!(
+            operation = "release_rejected",
+            game_id = %game_id,
+            reason = "cookie_present",
+            "发行资源请求带平台 Cookie，已拒绝"
+        );
+        return Err(AppError::from_status(StatusCode::FORBIDDEN)
+            .with_message("发行资源必须在独立来源上请求"));
+    }
+    let asset_path = asset_path.trim_start_matches('/').to_string();
+    let content_type = release_asset_content_type(&asset_path).ok_or_else(|| {
+        debug!(
+            operation = "release_rejected",
+            game_id = %game_id,
+            asset_path = %asset_path,
+            reason = "unsupported_extension",
+            "发行资源扩展名不在白名单内"
+        );
+        AppError::from_status(StatusCode::NOT_FOUND)
+    })?;
+    let public_game = state
+        .spacetime_client()
+        .get_public_game_distribution_game(game_id.clone())
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| {
+            debug!(
+                operation = "release_rejected",
+                game_id = %game_id,
+                asset_path = %asset_path,
+                reason = "not_public",
+                "游戏没有公开可玩版本"
+            );
+            AppError::from_status(StatusCode::NOT_FOUND)
+        })?;
+    let version = public_game.current_version.ok_or_else(|| {
+        debug!(
+            operation = "release_rejected",
+            game_id = %game_id,
+            asset_path = %asset_path,
+            reason = "no_active_version",
+            "游戏缺少当前公开版本"
+        );
+        AppError::from_status(StatusCode::NOT_FOUND)
+    })?;
+    if version.status != GAME_DISTRIBUTION_PUBLISHED_STATUS {
+        debug!(
+            operation = "release_rejected",
+            game_id = %game_id,
+            version_id = %version.version_id,
+            asset_path = %asset_path,
+            reason = "version_not_published",
+            status = %version.status,
+            "请求的版本不是公开状态"
+        );
+        return Err(AppError::from_status(StatusCode::NOT_FOUND));
+    }
+    let package = release_package_bytes(&state, &game_id, &version.version_id).await?;
+    let content = match extract_release_asset(&package, &asset_path) {
+        Ok(content) => content,
+        Err(ReleaseAssetError::FileTooLarge) => {
+            return Err(AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE)
+                .with_message("发行资源超过响应上限"));
+        }
+        Err(_) => return Err(AppError::from_status(StatusCode::NOT_FOUND)),
+    };
+    Ok(release_asset_response(content, content_type))
+}
+
+/// 读取（并按对象键缓存）已确认的私有发行包。
+async fn release_package_bytes(
+    state: &AppState,
+    game_id: &str,
+    version_id: &str,
+) -> Result<Arc<Vec<u8>>, AppError> {
+    let object_key = format!("{GAME_DISTRIBUTION_OBJECT_PREFIX}{game_id}/{version_id}.zip");
+    let cache = RELEASE_PACKAGE_CACHE.get_or_init(|| Mutex::new(ReleasePackageCache::default()));
+    if let Some(cached) = cache.lock().ok().and_then(|guard| guard.get(&object_key)) {
+        return Ok(cached);
+    }
+    let oss = state.project_snapshot_oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_message("游戏发行包 OSS 未配置")
+    })?;
+    let bytes = oss
+        .get_object(
+            state.editor_oss_http_client(),
+            OssGetObjectRequest {
+                object_key: object_key.clone(),
+                max_bytes: MAX_PACKAGE_BYTES as usize,
+            },
+        )
+        .await
+        .map_err(|error| {
+            if matches!(error, platform_oss::OssError::ObjectNotFound(_)) {
+                AppError::from_status(StatusCode::NOT_FOUND)
+            } else {
+                map_oss_error(error, "aliyun-oss")
+            }
+        })?;
+    let bytes = Arc::new(bytes);
+    if let Ok(mut guard) = cache.lock() {
+        guard.insert(object_key, bytes.clone());
+    }
+    Ok(bytes)
+}
+
+fn release_asset_response(content: Vec<u8>, content_type: &'static str) -> Response {
+    let mut response = Response::new(Body::from(content));
+    let headers = response.headers_mut();
+    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static(content_type));
+    headers.insert(
+        header::X_CONTENT_TYPE_OPTIONS,
+        HeaderValue::from_static("nosniff"),
+    );
+    headers.insert(
+        header::REFERRER_POLICY,
+        HeaderValue::from_static("no-referrer"),
+    );
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("public, max-age=60, must-revalidate"),
+    );
+    // 发行文档运行在 allow-scripts 的 opaque origin 沙箱里，其同包资源请求不再与
+    // 网关同源；CORP 必须允许跨来源，ES modules 还需要不带 credentials 的 CORS，
+    // 否则游戏自己的脚本会被浏览器拦下（实测 net::ERR_BLOCKED_BY_RESPONSE）。
+    // 这些是公开静态文件，放宽 CORP 不涉及凭据。
+    headers.insert(
+        header::HeaderName::from_static("cross-origin-resource-policy"),
+        HeaderValue::from_static("cross-origin"),
+    );
+    headers.insert(
+        header::ACCESS_CONTROL_ALLOW_ORIGIN,
+        HeaderValue::from_static("*"),
+    );
+    if content_type.starts_with("text/html") {
+        // 发行 HTML 走与主站不同的来源并强制最小权限策略；包内 meta 不能放宽。
+        headers.insert(
+            header::CONTENT_SECURITY_POLICY,
+            HeaderValue::from_static(
+                "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';                  img-src 'self' data: blob:; media-src 'self' data: blob:; font-src 'self' data:;                  connect-src 'self'; worker-src 'none'; object-src 'none'; frame-src 'none';                  form-action 'none'; base-uri 'none'",
+            ),
+        );
+    }
+    response
+}
+
+async fn list_games(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Query(query): Query<GameListQuery>,
+) -> Result<Json<Value>, AppError> {
+    let games = state
+        .spacetime_client()
+        .list_game_distribution_games(GameDistributionPublicGameListRecordInput {
+            search: normalize_optional(query.search),
+            category: normalize_optional(query.category),
+            limit: MAX_LIST_LIMIT,
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    let games = games
+        .into_iter()
+        .map(public_game_payload)
+        .collect::<Vec<_>>();
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({ "games": games, "nextCursor": Value::Null }),
+    ))
+}
+
+async fn get_game(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Path(game_id): Path<String>,
+) -> Result<Json<Value>, AppError> {
+    let game = state
+        .spacetime_client()
+        .get_public_game_distribution_game(game_id)
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    Ok(json_success_body(Some(&ctx), public_game_payload(game)))
+}
+
+/// 作者自有游戏列表：只返回当前认证主体名下的游戏与最近版本状态。
+async fn list_my_games(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let games = state
+        .spacetime_client()
+        .list_owner_game_distribution_games(
+            spacetime_client::GameDistributionOwnerGameListRecordInput {
+                owner_user_id: auth.claims().user_id().to_string(),
+                limit: MAX_LIST_LIMIT,
+            },
+        )
+        .await
+        .map_err(map_spacetime_error)?;
+    let payload = games
+        .into_iter()
+        .map(|entry| {
+            let mut value = game_payload(&entry.game);
+            let versions = entry
+                .versions
+                .iter()
+                .map(private_version_payload)
+                .collect::<Vec<_>>();
+            if let Value::Object(ref mut object) = value {
+                object.insert(
+                    "latestVersion".to_string(),
+                    versions.first().cloned().unwrap_or(Value::Null),
+                );
+                object.insert("versions".to_string(), Value::Array(versions));
+            }
+            value
+        })
+        .collect::<Vec<_>>();
+    Ok(json_success_body(Some(&ctx), json!({ "games": payload })))
+}
+
+async fn create_game(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Json(payload): Json<GameDistributionCreateGameRequest>,
+) -> Result<Json<Value>, AppError> {
+    ensure_publish_enabled(&state, Some(auth.claims().user_id())).await?;
+    let idempotency_key = idempotency_key(&headers)?;
+    validate_game_metadata(&payload)?;
+    // 创建游戏时就把封面/截图的归属与类型校验掉：否则游戏行会先落一个不属于当前作者
+    // 或根本不存在的素材 ID，直到创建版本才失败，留下无法解释的半成品资料。
+    resolve_owned_game_media(&state, auth.claims().user_id(), &payload).await?;
+    let now = now_micros();
+    let game_id = format!("game_{}", Uuid::new_v4().simple());
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&payload).map_err(|error| internal(error.to_string()))?,
+    );
+    let game = state
+        .spacetime_client()
+        .create_game_distribution_game(spacetime_client::GameDistributionCreateGameRecordInput {
+            game_id,
+            owner_user_id: auth.claims().user_id().to_string(),
+            title: payload.title,
+            summary: payload.summary,
+            description: payload.description,
+            category: payload.category,
+            tags_json: serde_json::to_string(&payload.tags)
+                .map_err(|error| internal(error.to_string()))?,
+            cover_asset_id: payload.cover_asset_id,
+            author_name: None,
+            author_avatar_url: None,
+            device_support_desktop: payload.device_support.desktop,
+            device_support_mobile: payload.device_support.mobile,
+            device_support_touch: payload.device_support.touch,
+            input_modes_json: serde_json::to_string(&payload.input_modes)
+                .map_err(|error| internal(error.to_string()))?,
+            orientation: serde_json::to_string(&payload.orientation)
+                .map_err(|error| internal(error.to_string()))?
+                .trim_matches('"')
+                .to_string(),
+            idempotency_key,
+            request_digest,
+            now_micros: now,
+            local_project_id: normalize_local_project_id(payload.local_project_id.as_deref())?,
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    Ok(json_success_body(Some(&ctx), game_payload(&game.0)))
+}
+
+async fn create_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Path(game_id): Path<String>,
+    Json(payload): Json<GameDistributionCreateVersionRequest>,
+) -> Result<Json<Value>, AppError> {
+    ensure_publish_enabled(&state, Some(auth.claims().user_id())).await?;
+    let idempotency_key = idempotency_key(&headers)?;
+    validate_version_declaration(&payload)?;
+    let now = now_micros();
+    let version_id = format!("gamever_{}", Uuid::new_v4().simple());
+    let metadata_json =
+        resolve_version_metadata_json(&state, auth.claims().user_id(), &payload.game_metadata)
+            .await?;
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(game_id.as_str(), &payload, metadata_json.as_str()))
+            .map_err(|error| internal(error.to_string()))?,
+    );
+    let version = state
+        .spacetime_client()
+        .create_game_distribution_version(
+            spacetime_client::GameDistributionCreateVersionRecordInput {
+                game_id,
+                owner_user_id: auth.claims().user_id().to_string(),
+                version_id,
+                metadata_json,
+                package_sha256: payload.package_sha256,
+                package_bytes: payload.package_bytes,
+                package_file_count: payload.package_file_count,
+                package_entry_path: payload.package_entry_path,
+                local_project_id: normalize_local_project_id(payload.local_project_id.as_deref())?,
+                idempotency_key,
+                request_digest,
+                now_micros: now,
+            },
+        )
+        .await
+        .map_err(map_spacetime_error)?;
+    Ok(json_success_body(
+        Some(&ctx),
+        private_version_payload(&version.0),
+    ))
+}
+
+async fn upload_package(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Path(version_id): Path<String>,
+    body: Bytes,
+) -> Result<Json<Value>, AppError> {
+    require_zip_content_type(&headers)?;
+    let owner_user_id = auth.claims().user_id().to_string();
+    ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+    let idempotency_key = idempotency_key(&headers)?;
+    let expected = state
+        .spacetime_client()
+        .get_owner_game_distribution_version(owner_user_id.clone(), version_id.clone())
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    let manifest = match validate_release_zip(&body) {
+        Ok(manifest) => manifest,
+        Err(error) => {
+            let reason = format!("{error:?}");
+            warn!(
+                request_id = ctx.request_id(),
+                operation = "package_rejected",
+                game_id = %expected.game_id,
+                version_id = %version_id,
+                code = "PACKAGE_VALIDATION_FAILED",
+                reason = %reason,
+                uploaded_bytes = body.len(),
+                elapsed_ms = ctx.elapsed(),
+                "发行包校验失败"
+            );
+            let mapped = map_package_error(error);
+            record_upload_failure(
+                &state,
+                &owner_user_id,
+                &version_id,
+                &idempotency_key,
+                "PACKAGE_VALIDATION_FAILED",
+                reason,
+            )
+            .await;
+            return Err(mapped);
+        }
+    };
+    if manifest.package_sha256 != expected.package_sha256
+        || manifest.package_bytes != expected.package_bytes
+        || u32::try_from(manifest.files.len()).unwrap_or(u32::MAX) != expected.package_file_count
+        || expected.package_entry_path != "index.html"
+    {
+        warn!(
+            request_id = ctx.request_id(),
+            operation = "package_rejected",
+            game_id = %expected.game_id,
+            version_id = %version_id,
+            code = "PACKAGE_MISMATCH",
+            declared_bytes = expected.package_bytes,
+            actual_bytes = manifest.package_bytes,
+            declared_file_count = expected.package_file_count,
+            actual_file_count = u32::try_from(manifest.files.len()).unwrap_or(u32::MAX),
+            elapsed_ms = ctx.elapsed(),
+            "发行包与版本声明不一致"
+        );
+        let error = AppError::from_status(StatusCode::CONFLICT)
+            .with_code("PACKAGE_MISMATCH")
+            .with_details(json!({
+                "provider": "game-distribution",
+                "message": "发行包摘要、体积、文件数或入口与版本声明不一致",
+            }));
+        record_upload_failure(
+            &state,
+            &owner_user_id,
+            &version_id,
+            &idempotency_key,
+            "PACKAGE_MISMATCH",
+            "发行包摘要、体积、文件数或入口与版本声明不一致".to_string(),
+        )
+        .await;
+        return Err(error);
+    }
+    let package_object_key = format!(
+        "{GAME_DISTRIBUTION_OBJECT_PREFIX}{}/{version_id}.zip",
+        expected.game_id
+    );
+    let package_manifest_json = package_manifest_json(&manifest)?;
+    let oss = state.project_snapshot_oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_message("游戏发行包 OSS 未配置")
+    })?;
+    let existing = oss
+        .head_internal_object(state.editor_oss_http_client(), &package_object_key)
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    let skipped = match existing {
+        Some(existing) if existing.content_length == manifest.package_bytes => true,
+        Some(_) => {
+            let error = AppError::from_status(StatusCode::CONFLICT)
+                .with_code("PACKAGE_OBJECT_MISMATCH")
+                .with_message("发行包对象已存在但体积不一致");
+            record_upload_failure(
+                &state,
+                &owner_user_id,
+                &version_id,
+                &idempotency_key,
+                "PACKAGE_OBJECT_MISMATCH",
+                "发行包对象已存在但体积不一致".to_string(),
+            )
+            .await;
+            return Err(error);
+        }
+        None => false,
+    };
+    if !skipped {
+        // 单次 100 MiB PUT 在本机实测 12 秒上下，偶发传输失败会让作者白传一次；
+        // 这里按 platform-oss 既有的可重试分类做受控重试（只重试传输/超时/408/429/5xx）。
+        oss.put_internal_object_with_retry(
+            state.editor_oss_http_client(),
+            OssInternalPutObjectRequest {
+                object_key: package_object_key.clone(),
+                content_type: Some("application/zip".to_string()),
+                access: OssObjectAccess::Private,
+                metadata: BTreeMap::new(),
+                body: body.to_vec(),
+            },
+            GAME_DISTRIBUTION_OSS_PUT_MAX_ATTEMPTS,
+            &GAME_DISTRIBUTION_OSS_PUT_RETRY_DELAYS_MS,
+        )
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    }
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(version_id.as_str(), manifest.package_sha256.as_str()))
+            .map_err(|error| internal(error.to_string()))?,
+    );
+    let log_game_id = expected.game_id.clone();
+    let log_package_bytes = manifest.package_bytes;
+    let log_file_count = u32::try_from(manifest.files.len()).unwrap_or(u32::MAX);
+    let log_sha_prefix = manifest.package_sha256.chars().take(12).collect::<String>();
+    let log_oss_put_skipped = skipped;
+    let confirmed = state
+        .spacetime_client()
+        .confirm_game_distribution_package(
+            spacetime_client::GameDistributionConfirmPackageRecordInput {
+                version_id,
+                owner_user_id,
+                package_sha256: manifest.package_sha256,
+                package_bytes: manifest.package_bytes,
+                package_file_count: u32::try_from(manifest.files.len()).unwrap_or(u32::MAX),
+                package_entry_path: "index.html".to_string(),
+                package_object_key,
+                package_manifest_json,
+                idempotency_key,
+                request_digest,
+                updated_at_micros: now_micros(),
+            },
+        )
+        .await
+        .map_err(map_spacetime_error)?;
+    info!(
+        request_id = ctx.request_id(),
+        operation = "package_confirmed",
+        game_id = %log_game_id,
+        version_id = %confirmed.0.version_id,
+        package_bytes = log_package_bytes,
+        file_count = log_file_count,
+        sha256_prefix = %log_sha_prefix,
+        oss_put_skipped = log_oss_put_skipped,
+        elapsed_ms = ctx.elapsed(),
+        "发行包已确认"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({ "versionId": confirmed.0.version_id, "status": confirmed.0.status }),
+    ))
+}
+
+async fn submit_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Path(version_id): Path<String>,
+    Json(payload): Json<PublicationRevisionRequest>,
+) -> Result<(StatusCode, Json<Value>), AppError> {
+    let owner_user_id = auth.claims().user_id().to_string();
+    ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+    let idempotency_key = idempotency_key(&headers)?;
+    let version = state
+        .spacetime_client()
+        .get_owner_game_distribution_version(owner_user_id.clone(), version_id.clone())
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    let game = state
+        .spacetime_client()
+        .get_game_distribution_game(GameDistributionGetGameRecordInput {
+            game_id: version.game_id.clone(),
+            owner_user_id: Some(owner_user_id.clone()),
+        })
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(version_id.as_str(), payload.expected_publication_revision))
+            .map_err(|error| internal(error.to_string()))?,
+    );
+    let log_game_id = version.game_id.clone();
+    let log_version_number = version.version_number;
+    let log_revision = payload.expected_publication_revision;
+    let submitted = state
+        .spacetime_client()
+        .submit_game_distribution_version_for_review(GameDistributionSubmitReviewRecordInput {
+            version_id,
+            owner_user_id,
+            expected_publication_revision: payload.expected_publication_revision,
+            idempotency_key,
+            request_digest,
+            now_micros: now_micros(),
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    info!(
+        request_id = ctx.request_id(),
+        operation = "version_submitted",
+        game_id = %log_game_id,
+        version_id = %submitted.0.version_id,
+        version_number = log_version_number,
+        publication_revision = log_revision,
+        replayed = submitted.1,
+        elapsed_ms = ctx.elapsed(),
+        "版本已送审"
+    );
+    Ok((
+        StatusCode::ACCEPTED,
+        json_success_body(
+            Some(&ctx),
+            json!({
+                "game": game_payload(&game),
+                "version": private_version_payload(&submitted.0),
+                "replayed": submitted.1,
+            }),
+        ),
+    ))
+}
+
+/// 作者回读单个版本的私有状态与恢复动作。
+///
+/// 版本不存在或不属于当前主体都返回 404，避免用错误码区分“别人的版本”和“不存在的版本”。
+async fn get_owner_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    Path(version_id): Path<String>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = auth.claims().user_id().to_string();
+    let version = load_owner_version_or_404(&state, owner_user_id.clone(), version_id).await?;
+    let game = state
+        .spacetime_client()
+        .get_game_distribution_game(GameDistributionGetGameRecordInput {
+            game_id: version.game_id.clone(),
+            owner_user_id: Some(owner_user_id),
+        })
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    Ok(json_success_body(
+        Some(&ctx),
+        version_detail_payload(&version, &game),
+    ))
+}
+
+/// 作者撤回尚未公开的版本。
+///
+/// 只能撤回自己名下、且未参与当前公开投影的版本；`expectedPublicationRevision` 以
+/// 游戏公开修订号做 CAS，过期请求返回 409，已公开版本改用下架。
+async fn cancel_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Path(version_id): Path<String>,
+    Json(payload): Json<CancelVersionRequest>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = auth.claims().user_id().to_string();
+    ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+    let idempotency_key = idempotency_key(&headers)?;
+    let version =
+        load_owner_version_or_404(&state, owner_user_id.clone(), version_id.clone()).await?;
+    if version.publication_revision != payload.expected_publication_revision {
+        return Err(
+            AppError::from_status(StatusCode::CONFLICT).with_details(json!({
+                "provider": "game-distribution",
+                "code": "PUBLICATION_CONFLICT",
+                "message": "游戏的公开修订号已变化，请刷新后重试",
+            })),
+        );
+    }
+    let game = state
+        .spacetime_client()
+        .get_game_distribution_game(GameDistributionGetGameRecordInput {
+            game_id: version.game_id.clone(),
+            owner_user_id: Some(owner_user_id.clone()),
+        })
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    let reason = payload
+        .reason
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(
+            version_id.as_str(),
+            payload.expected_publication_revision,
+            reason,
+        ))
+        .map_err(|error| internal(error.to_string()))?,
+    );
+    let (version, replayed) = state
+        .spacetime_client()
+        .cancel_game_distribution_version(GameDistributionCancelVersionRecordInput {
+            version_id,
+            owner_user_id,
+            expected_publication_revision: payload.expected_publication_revision,
+            idempotency_key,
+            request_digest,
+            now_micros: now_micros(),
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    info!(
+        request_id = ctx.request_id(),
+        operation = "version_cancelled",
+        game_id = %version.game_id,
+        version_id = %version.version_id,
+        version_number = version.version_number,
+        replayed,
+        elapsed_ms = ctx.elapsed(),
+        "版本已撤回"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({
+            "game": game_payload(&game),
+            "version": private_version_payload(&version),
+            "replayed": replayed,
+        }),
+    ))
+}
+
+async fn unpublish_game(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(auth): Extension<AuthenticatedAccessToken>,
+    headers: HeaderMap,
+    Path(game_id): Path<String>,
+    Json(payload): Json<PublicationRevisionRequest>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = auth.claims().user_id().to_string();
+    ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+    let log_expected_revision = payload.expected_publication_revision;
+    let log_game_id = game_id.clone();
+    let idempotency_key = idempotency_key(&headers)?;
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(game_id.as_str(), payload.expected_publication_revision))
+            .map_err(|error| internal(error.to_string()))?,
+    );
+    let game = state
+        .spacetime_client()
+        .unpublish_game_distribution_game(GameDistributionUnpublishRecordInput {
+            game_id,
+            owner_user_id,
+            expected_publication_revision: payload.expected_publication_revision,
+            idempotency_key,
+            request_digest,
+            now_micros: now_micros(),
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    info!(
+        request_id = ctx.request_id(),
+        operation = "game_unpublished",
+        game_id = %log_game_id,
+        expected_publication_revision = log_expected_revision,
+        visibility = %game.0.visibility,
+        publication_revision = game.0.publication_revision,
+        active_version_id = game.0.active_version_id.as_deref().unwrap_or(""),
+        replayed = game.1,
+        elapsed_ms = ctx.elapsed(),
+        "作者下架游戏，公开入口已关闭"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({ "game": game_payload(&game.0), "replayed": game.1 }),
+    ))
+}
+
+async fn admin_list_reviews(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(_admin): Extension<AuthenticatedAdmin>,
+    Query(query): Query<AdminReviewListQuery>,
+) -> Result<Json<Value>, AppError> {
+    let limit = query.limit.unwrap_or(MAX_LIST_LIMIT).min(MAX_LIST_LIMIT);
+    let reviews = state
+        .spacetime_client()
+        .list_game_distribution_reviews(limit)
+        .await
+        .map_err(map_spacetime_error)?;
+    info!(
+        request_id = ctx.request_id(),
+        operation = "review_backlog_listed",
+        pending_versions = reviews.len(),
+        limit,
+        elapsed_ms = ctx.elapsed(),
+        "后台读取待审发行版本"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({
+            "entries": reviews.iter().map(private_version_payload).collect::<Vec<_>>(),
+            "nextCursor": Value::Null,
+        }),
+    ))
+}
+
+async fn admin_review_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(admin): Extension<AuthenticatedAdmin>,
+    headers: HeaderMap,
+    Path(version_id): Path<String>,
+    Json(payload): Json<AdminReviewRequest>,
+) -> Result<Json<Value>, AppError> {
+    let idempotency_key = idempotency_key(&headers)?;
+    let decision = payload.decision.trim().to_ascii_lowercase();
+    if decision != "approve" && decision != "reject" {
+        return Err(bad_request("审核结论必须是 approve 或 reject"));
+    }
+    let admin_user_id = admin.session().subject.clone();
+    let log_admin_user_id = admin_user_id.clone();
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(
+            version_id.as_str(),
+            decision.as_str(),
+            payload.expected_publication_revision,
+            payload.review_reason.as_deref(),
+            payload.entry_url.as_deref(),
+        ))
+        .map_err(|error| internal(error.to_string()))?,
+    );
+    let (version, replayed) = if decision == "approve" {
+        // 回滚窗口里“关闭新版本激活”，但拒绝审核与安全下架必须始终可用。
+        ensure_publish_enabled(&state, None).await?;
+        let entry_url = payload
+            .entry_url
+            .as_deref()
+            .ok_or_else(|| bad_request("审核通过必须提供发行网关 HTTPS 入口"))?;
+        validate_release_entry_url(entry_url, !state.config.is_production())?;
+        state
+            .spacetime_client()
+            .approve_game_distribution_version(GameDistributionApproveRecordInput {
+                version_id,
+                admin_user_id,
+                expected_publication_revision: payload.expected_publication_revision,
+                entry_url: entry_url.to_string(),
+                idempotency_key,
+                request_digest,
+                now_micros: now_micros(),
+            })
+            .await
+            .map_err(map_spacetime_error)?
+    } else {
+        let review_reason = payload
+            .review_reason
+            .filter(|value| !value.trim().is_empty())
+            .ok_or_else(|| bad_request("拒绝审核必须填写 reviewReason"))?;
+        state
+            .spacetime_client()
+            .reject_game_distribution_version(GameDistributionRejectRecordInput {
+                version_id,
+                admin_user_id,
+                expected_publication_revision: payload.expected_publication_revision,
+                review_reason,
+                idempotency_key,
+                request_digest,
+                now_micros: now_micros(),
+            })
+            .await
+            .map_err(map_spacetime_error)?
+    };
+    info!(
+        request_id = ctx.request_id(),
+        operation = "review_decided",
+        version_id = %version.version_id,
+        game_id = %version.game_id,
+        decision = %decision,
+        admin_user_id = %log_admin_user_id,
+        publication_revision = version.publication_revision,
+        replayed,
+        elapsed_ms = ctx.elapsed(),
+        "管理员完成发行版本审核"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({ "version": private_version_payload(&version), "replayed": replayed }),
+    ))
+}
+
+/// 管理员回读任意版本，用于审核时确认状态、错误和恢复动作。
+async fn admin_get_version(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(_admin): Extension<AuthenticatedAdmin>,
+    Path(version_id): Path<String>,
+) -> Result<Json<Value>, AppError> {
+    let version = state
+        .spacetime_client()
+        .get_game_distribution_version(version_id)
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    let game = state
+        .spacetime_client()
+        .get_game_distribution_game(GameDistributionGetGameRecordInput {
+            game_id: version.game_id.clone(),
+            owner_user_id: Some(version.owner_user_id.clone()),
+        })
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| AppError::from_status(StatusCode::NOT_FOUND))?;
+    Ok(json_success_body(
+        Some(&ctx),
+        version_detail_payload(&version, &game),
+    ))
+}
+
+/// 校验管理员提交的发行入口。
+///
+/// 生产环境只接受绝对 HTTPS 地址；非生产环境额外允许 http 回环地址，口径与前端
+/// `normalizeGameEntryUrl` 一致，便于本地把发行网关跑在 127.0.0.1 上验证内嵌游玩。
+/// 任何环境都拒绝凭据、query 和 fragment，也不允许服务端自行拼默认地址。
+fn validate_release_entry_url(value: &str, allow_loopback_http: bool) -> Result<(), AppError> {
+    let parsed =
+        url::Url::parse(value.trim()).map_err(|_| bad_request("发行入口必须是有效 URL"))?;
+    let host = parsed.host_str();
+    let scheme_allowed = parsed.scheme() == "https"
+        || (allow_loopback_http
+            && parsed.scheme() == "http"
+            && matches!(
+                host,
+                Some("127.0.0.1") | Some("localhost") | Some("[::1]") | Some("::1")
+            ));
+    if !scheme_allowed
+        || host.is_none()
+        || parsed.username() != ""
+        || parsed.password().is_some()
+        || parsed.query().is_some()
+        || parsed.fragment().is_some()
+    {
+        return Err(bad_request(
+            "发行入口必须是无凭据、无查询参数的 HTTPS URL；仅非生产环境允许回环 http",
+        ));
+    }
+    Ok(())
+}
+
+async fn admin_suspend_game(
+    State(state): State<AppState>,
+    Extension(ctx): Extension<RequestContext>,
+    Extension(admin): Extension<AuthenticatedAdmin>,
+    headers: HeaderMap,
+    Path(game_id): Path<String>,
+    Json(payload): Json<AdminSuspendRequest>,
+) -> Result<Json<Value>, AppError> {
+    let idempotency_key = idempotency_key(&headers)?;
+    let admin_user_id = admin.session().subject.clone();
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(
+            game_id.as_str(),
+            payload.expected_publication_revision,
+            payload.reason.as_deref(),
+        ))
+        .map_err(|error| internal(error.to_string()))?,
+    );
+    let log_game_id = game_id.clone();
+    let log_admin_user_id = admin_user_id.clone();
+    let log_expected_revision = payload.expected_publication_revision;
+    let log_reason = payload
+        .reason
+        .as_deref()
+        .map(str::trim)
+        .unwrap_or("")
+        .chars()
+        .take(120)
+        .collect::<String>();
+    let game = state
+        .spacetime_client()
+        .suspend_game_distribution_game(GameDistributionSuspendRecordInput {
+            game_id,
+            admin_user_id,
+            expected_publication_revision: payload.expected_publication_revision,
+            reason: payload.reason,
+            idempotency_key,
+            request_digest,
+            now_micros: now_micros(),
+        })
+        .await
+        .map_err(map_spacetime_error)?;
+    warn!(
+        request_id = ctx.request_id(),
+        operation = "game_suspended",
+        game_id = %log_game_id,
+        admin_user_id = %log_admin_user_id,
+        expected_publication_revision = log_expected_revision,
+        publication_revision = game.0.publication_revision,
+        visibility = %game.0.visibility,
+        reason = %log_reason,
+        replayed = game.1,
+        elapsed_ms = ctx.elapsed(),
+        "管理员安全下架游戏"
+    );
+    Ok(json_success_body(
+        Some(&ctx),
+        json!({ "game": game_payload(&game.0), "replayed": game.1 }),
+    ))
+}
+
+async fn record_upload_failure(
+    state: &AppState,
+    owner_user_id: &str,
+    version_id: &str,
+    idempotency_key: &str,
+    error_code: &str,
+    error_message: String,
+) {
+    let request_digest = compute_request_digest(
+        &serde_json::to_vec(&(version_id, error_code, error_message.as_str())).unwrap_or_default(),
+    );
+    let _ = state
+        .spacetime_client()
+        .fail_game_distribution_upload(spacetime_client::GameDistributionFailUploadRecordInput {
+            version_id: version_id.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+            idempotency_key: idempotency_key.to_string(),
+            request_digest,
+            error_code: error_code.to_string(),
+            error_message,
+            now_micros: now_micros(),
+        })
+        .await;
+}
+
+/// 本地项目标识只用于同一作者复用游戏身份；它必须是短标识，不能充当路径或所有权凭证。
+fn normalize_local_project_id(value: Option<&str>) -> Result<Option<String>, AppError> {
+    let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(None);
+    };
+    if value.chars().count() > 128 {
+        return Err(bad_request("localProjectId 不能超过 128 个字符"));
+    }
+    if value.chars().any(|character| character.is_control())
+        || value.contains('/')
+        || value.contains('\\')
+        || value == "."
+        || value == ".."
+    {
+        return Err(bad_request(
+            "localProjectId 只能是短标识，不能包含路径分隔符",
+        ));
+    }
+    Ok(Some(value.to_string()))
+}
+
+fn validate_game_metadata(payload: &GameDistributionCreateGameRequest) -> Result<(), AppError> {
+    if payload.title.trim().is_empty() || payload.title.chars().count() > 40 {
+        return Err(bad_request("游戏标题必须为 1 到 40 个字符"));
+    }
+    if payload.summary.trim().is_empty() || payload.summary.chars().count() > 120 {
+        return Err(bad_request("游戏简介必须为 1 到 120 个字符"));
+    }
+    if payload.description.as_deref().unwrap_or("").chars().count() > 2_000 {
+        return Err(bad_request("游戏详细介绍不能超过 2000 个字符"));
+    }
+    if !GAME_DISTRIBUTION_CATEGORIES.contains(&payload.category.as_str()) {
+        return Err(bad_request("游戏分类不受支持"));
+    }
+    if payload.tags.len() > 5
+        || payload
+            .tags
+            .iter()
+            .any(|tag| tag.trim().is_empty() || tag.chars().count() > 20)
+    {
+        return Err(bad_request("游戏标签最多 5 个且每个不能超过 20 个字符"));
+    }
+    if !payload.device_support.desktop && !payload.device_support.mobile {
+        return Err(bad_request("游戏至少需要声明支持桌面端或移动端"));
+    }
+    if payload.device_support.mobile && !payload.device_support.touch {
+        return Err(bad_request("声明支持移动端时必须支持触控"));
+    }
+    if payload
+        .cover_asset_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .is_none()
+    {
+        return Err(bad_request("发布游戏必须提供封面"));
+    }
+    if payload.screenshots.len() > MAX_GAME_SCREENSHOTS {
+        return Err(bad_request("游戏截图最多 6 张"));
+    }
+    if payload
+        .screenshots
+        .iter()
+        .any(|screenshot| screenshot.trim().is_empty())
+    {
+        return Err(bad_request("游戏截图素材 ID 不能为空"));
+    }
+    Ok(())
+}
+
+fn validate_version_declaration(
+    payload: &GameDistributionCreateVersionRequest,
+) -> Result<(), AppError> {
+    if payload.package_entry_path != "index.html" {
+        return Err(bad_request("发行包入口必须是 index.html"));
+    }
+    if payload.package_bytes == 0 || payload.package_bytes > MAX_PACKAGE_BYTES {
+        return Err(
+            AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE).with_message("发行包大小超出限制")
+        );
+    }
+    if payload.package_file_count == 0 {
+        return Err(bad_request("发行包至少需要包含一个文件"));
+    }
+    if payload.package_sha256.len() != 64
+        || !payload
+            .package_sha256
+            .chars()
+            .all(|value| value.is_ascii_hexdigit())
+    {
+        return Err(bad_request("发行包 SHA-256 格式不合法"));
+    }
+    validate_game_metadata(&payload.game_metadata)
+}
+
+fn require_zip_content_type(headers: &HeaderMap) -> Result<(), AppError> {
+    let content_type = headers
+        .get(header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(|value| {
+            value
+                .split(';')
+                .next()
+                .unwrap_or_default()
+                .trim()
+                .to_ascii_lowercase()
+        });
+    if content_type.as_deref() != Some("application/zip") {
+        return Err(bad_request("发行包必须使用 application/zip"));
+    }
+    Ok(())
+}
+
+fn package_manifest_json(manifest: &ReleasePackageManifest) -> Result<String, AppError> {
+    let serialized = serde_json::to_string(&json!({
+        "packageBytes": manifest.package_bytes,
+        "packageSha256": manifest.package_sha256,
+        "files": manifest.files.iter().map(|file| json!({
+            "path": file.path,
+            "sizeBytes": file.size_bytes,
+            "sha256": file.sha256,
+        })).collect::<Vec<_>>(),
+    }))
+    .map_err(|error| internal(error.to_string()))?;
+    if serialized.len() > MAX_PACKAGE_MANIFEST_JSON_BYTES {
+        return Err(AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE)
+            .with_message("发行包文件清单超过大小限制"));
+    }
+    Ok(serialized)
+}
+
+fn public_game_payload(game: GameDistributionPublicGameRecord) -> Value {
+    let mut payload = game_payload(&game.game);
+    if let Value::Object(ref mut object) = payload {
+        object.insert(
+            "currentVersion".to_string(),
+            game.current_version
+                .map(|version| version_summary_payload(&version))
+                .unwrap_or(Value::Null),
+        );
+    }
+    payload
+}
+
+fn game_payload(game: &GameDistributionGameRecord) -> Value {
+    let tags = serde_json::from_str::<Vec<String>>(&game.tags_json).unwrap_or_default();
+    let screenshots = game
+        .screenshots_json
+        .as_deref()
+        .and_then(|json| serde_json::from_str::<Vec<FrozenGameScreenshot>>(json).ok())
+        .unwrap_or_default()
+        .into_iter()
+        .map(|screenshot| screenshot.object_key)
+        .collect::<Vec<_>>();
+    let input_modes =
+        serde_json::from_str::<Vec<GameDistributionInputMode>>(&game.input_modes_json)
+            .unwrap_or_default();
+    json!({
+        "id": game.game_id,
+        "title": game.title,
+        "summary": game.summary,
+        "description": game.description,
+        "category": game.category,
+        "tags": tags,
+        "coverColor": "#F3E4D0",
+        "icon": "🎮",
+        "coverObjectKey": game.cover_object_key,
+        "screenshots": screenshots,
+        "author": { "id": game.owner_user_id, "name": game.author_name.as_deref().unwrap_or("创作者"), "avatarUrl": game.author_avatar_url },
+        "deviceSupport": { "desktop": game.device_support_desktop, "mobile": game.device_support_mobile, "touch": game.device_support_touch },
+        "inputModes": input_modes,
+        "orientation": game.orientation,
+        "status": game.visibility,
+        "publicationRevision": game.publication_revision,
+        "playCount": game.play_count,
+        "createdAt": game.created_at,
+    })
+}
+
+fn version_summary_payload(version: &GameDistributionVersionRecord) -> Value {
+    json!({
+        "id": version.version_id,
+        "version": version.version_number.to_string(),
+        "entryUrl": version.entry_url,
+        "sha256": version.package_sha256,
+        "publishedAt": version.updated_at,
+        "controls": [],
+    })
+}
+
+fn private_version_payload(version: &GameDistributionVersionRecord) -> Value {
+    json!({
+        "versionId": version.version_id,
+        "gameId": version.game_id,
+        "versionNumber": version.version_number,
+        "packageSha256": version.package_sha256,
+        "packageBytes": version.package_bytes,
+        "status": version.status,
+        "publicationRevision": version.publication_revision,
+        "reviewReason": version.review_reason,
+        "createdAt": version.created_at,
+        "updatedAt": version.updated_at,
+    })
+}
+
+/// 游戏分发写入开关。
+///
+/// 运营在灰度配置里把 `game-distribution:publish` 收紧后，作者写入与新版本激活会返回
+/// 503 `GAME_DISTRIBUTION_PUBLISH_DISABLED`；目录、详情、版本回读、发行网关、审核队列读取、
+/// 拒绝审核与安全下架都不受影响，用于发布事故或回滚窗口期间“关投稿、保在线”。
+/// 开关状态读取失败时按关闭处理，避免绕过运营刚下的收紧动作。
+async fn ensure_publish_enabled(state: &AppState, user_id: Option<&str>) -> Result<(), AppError> {
+    match state
+        .is_game_distribution_publish_enabled_for_user(user_id)
+        .await
+    {
+        Ok(true) => Ok(()),
+        Ok(false) => {
+            warn!(
+                operation = "publish_switch_blocked",
+                user_id = user_id.unwrap_or(""),
+                "游戏发布开关已收紧，写入被拦截"
+            );
+            Err(AppError::from_status(StatusCode::SERVICE_UNAVAILABLE)
+                .with_code("GAME_DISTRIBUTION_PUBLISH_DISABLED")
+                .with_message("游戏发布暂已关闭，已公开游戏仍可继续游玩"))
+        }
+        Err(error) => {
+            warn!(
+                operation = "publish_switch_unavailable",
+                user_id = user_id.unwrap_or(""),
+                error = %error,
+                "无法读取游戏发布开关，按关闭处理"
+            );
+            Err(AppError::from_status(StatusCode::SERVICE_UNAVAILABLE)
+                .with_code("GAME_DISTRIBUTION_PUBLISH_DISABLED")
+                .with_message("无法确认游戏发布开关，已按关闭处理"))
+        }
+    }
+}
+
+/// 冻结资料快照里的截图素材。
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct FrozenGameScreenshot {
+    asset_id: String,
+    object_key: String,
+}
+
+/// 校验封面/截图素材归属并生成版本冻结资料 JSON。
+///
+/// 对象键由服务端从素材记录派生，客户端只能提供素材 ID；素材必须属于当前作者且是图片。
+async fn resolve_owned_game_media(
+    state: &AppState,
+    owner_user_id: &str,
+    metadata: &GameDistributionCreateGameRequest,
+) -> Result<(String, String, Vec<FrozenGameScreenshot>), AppError> {
+    let cover_asset_id = metadata
+        .cover_asset_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| bad_request("发布游戏必须提供封面"))?
+        .to_string();
+    let cover_object_key =
+        resolve_owned_image_object_key(state, owner_user_id, cover_asset_id.as_str()).await?;
+    let mut screenshots = Vec::with_capacity(metadata.screenshots.len());
+    for asset_id in &metadata.screenshots {
+        let asset_id = asset_id.trim();
+        if asset_id.is_empty() {
+            return Err(bad_request("游戏截图素材 ID 不能为空"));
+        }
+        let object_key = resolve_owned_image_object_key(state, owner_user_id, asset_id).await?;
+        screenshots.push(FrozenGameScreenshot {
+            asset_id: asset_id.to_string(),
+            object_key,
+        });
+    }
+    Ok((cover_asset_id, cover_object_key, screenshots))
+}
+
+async fn resolve_version_metadata_json(
+    state: &AppState,
+    owner_user_id: &str,
+    metadata: &GameDistributionCreateGameRequest,
+) -> Result<String, AppError> {
+    let (cover_asset_id, cover_object_key, screenshots) =
+        resolve_owned_game_media(state, owner_user_id, metadata).await?;
+    let tags = metadata
+        .tags
+        .iter()
+        .map(|tag| tag.trim())
+        .filter(|tag| !tag.is_empty())
+        .collect::<Vec<_>>();
+    let snapshot = json!({
+        "title": metadata.title.trim(),
+        "summary": metadata.summary.trim(),
+        "description": metadata
+            .description
+            .clone()
+            .unwrap_or_else(|| metadata.summary.trim().to_string()),
+        "category": metadata.category,
+        "tags": tags,
+        "coverAssetId": cover_asset_id,
+        "coverObjectKey": cover_object_key,
+        "screenshots": screenshots,
+        "deviceSupport": {
+            "desktop": metadata.device_support.desktop,
+            "mobile": metadata.device_support.mobile,
+            "touch": metadata.device_support.touch,
+        },
+        "inputModes": metadata.input_modes,
+        "orientation": metadata.orientation,
+    });
+    serde_json::to_string(&snapshot).map_err(|error| internal(error.to_string()))
+}
+
+async fn resolve_owned_image_object_key(
+    state: &AppState,
+    owner_user_id: &str,
+    asset_object_id: &str,
+) -> Result<String, AppError> {
+    let asset = state
+        .spacetime_client()
+        .get_asset_object(asset_object_id.to_string())
+        .await
+        .map_err(map_spacetime_error)?
+        .ok_or_else(|| bad_request("封面或截图素材不存在"))?;
+    if asset.owner_user_id.as_deref() != Some(owner_user_id) {
+        return Err(AppError::from_status(StatusCode::FORBIDDEN)
+            .with_message("封面或截图素材不属于当前账号"));
+    }
+    let content_type = asset.content_type.as_deref().unwrap_or("");
+    if !content_type.starts_with("image/") {
+        return Err(bad_request("封面和截图必须是图片素材"));
+    }
+    Ok(asset.object_key)
+}
+
+/// 读取当前主体名下的版本；未知版本和别人的版本都按不可见处理（404）。
+async fn load_owner_version_or_404(
+    state: &AppState,
+    owner_user_id: String,
+    version_id: String,
+) -> Result<GameDistributionVersionRecord, AppError> {
+    match state
+        .spacetime_client()
+        .get_owner_game_distribution_version(owner_user_id, version_id)
+        .await
+    {
+        Ok(Some(version)) => Ok(version),
+        Ok(None) => Err(AppError::from_status(StatusCode::NOT_FOUND)),
+        Err(SpacetimeClientError::Procedure(message)) if message.contains("owner 不匹配") => {
+            Err(AppError::from_status(StatusCode::NOT_FOUND))
+        }
+        Err(error) => Err(map_spacetime_error(error)),
+    }
+}
+
+/// 版本私有投影：在通用私有字段上追加客户端恢复动作与随版本冻结的资料快照。
+///
+/// 该投影只用于作者本人与管理员回读，因此可以带上冻结资料里的素材 ID：作者更新游戏时
+/// 复用同一批素材，不需要为了沿用封面重新上传一次；快照缺失（历史版本）时按空值返回。
+fn version_detail_payload(
+    version: &GameDistributionVersionRecord,
+    game: &GameDistributionGameRecord,
+) -> Value {
+    let mut payload = private_version_payload(version);
+    let frozen_metadata = version
+        .metadata_json
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .and_then(|value| serde_json::from_str::<Value>(value).ok())
+        .unwrap_or(Value::Null);
+    if let Value::Object(ref mut object) = payload {
+        object.insert(
+            "recoveryAction".to_string(),
+            Value::String(recovery_action_for_status(version.status.as_str()).to_string()),
+        );
+        object.insert("frozenMetadata".to_string(), frozen_metadata);
+    }
+    json!({ "game": game_payload(game), "version": payload })
+}
+
+/// 客户端可执行的下一步；状态是唯一事实源，前端不自行推断。
+fn recovery_action_for_status(status: &str) -> &'static str {
+    match status {
+        "awaiting_upload" => "upload",
+        "uploaded" => "submit",
+        "validating" | "pending_review" => "wait",
+        "upload_failed" => "reupload",
+        "validation_failed" => "fix_package",
+        "rejected" => "fix_metadata",
+        _ => "none",
+    }
+}
+
+fn idempotency_key(headers: &HeaderMap) -> Result<String, AppError> {
+    let value = headers
+        .get("idempotency-key")
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| bad_request("缺少 Idempotency-Key"))?;
+    if value.chars().count() > MAX_IDEMPOTENCY_KEY_CHARS {
+        return Err(bad_request("Idempotency-Key 过长"));
+    }
+    Ok(value.to_string())
+}
+
+fn normalize_optional(value: Option<String>) -> Option<String> {
+    value
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn now_micros() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|value| value.as_micros() as i64)
+        .unwrap_or(0)
+}
+
+fn bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_message(message)
+}
+
+fn internal(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_message(message)
+}
+
+fn map_package_error(error: ReleasePackageError) -> AppError {
+    AppError::from_status(StatusCode::UNPROCESSABLE_ENTITY)
+        .with_code("PACKAGE_VALIDATION_FAILED")
+        .with_details(json!({ "provider": "game-distribution", "reason": format!("{error:?}") }))
+}
+
+fn map_spacetime_error(error: SpacetimeClientError) -> AppError {
+    match error {
+        SpacetimeClientError::Procedure(message) if message.contains("owner 不匹配") => {
+            AppError::from_status(StatusCode::FORBIDDEN)
+                .with_details(json!({ "provider": "game-distribution", "message": message }))
+        }
+        SpacetimeClientError::Procedure(message)
+            if message.contains("不存在") || message.contains("已不存在") =>
+        {
+            AppError::from_status(StatusCode::NOT_FOUND)
+                .with_details(json!({ "provider": "game-distribution", "message": message }))
+        }
+        SpacetimeClientError::Procedure(message)
+            if message.contains("幂等")
+                || message.contains("不匹配")
+                || message.contains("PUBLICATION_CONFLICT")
+                || message.contains("已存在")
+                || message.contains("状态") =>
+        {
+            AppError::from_status(StatusCode::CONFLICT)
+                .with_details(json!({ "provider": "game-distribution", "message": message }))
+        }
+        SpacetimeClientError::Procedure(message) | SpacetimeClientError::Runtime(message) => {
+            AppError::from_status(StatusCode::BAD_REQUEST)
+                .with_details(json!({ "provider": "game-distribution", "message": message }))
+        }
+        other => AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "spacetimedb",
+            "message": other.to_string(),
+        })),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use shared_contracts::game_distribution::{
+        GameDistributionDeviceSupport, GameDistributionOrientation,
+    };
+
+    fn metadata() -> GameDistributionCreateGameRequest {
+        GameDistributionCreateGameRequest {
+            local_project_id: None,
+            title: "测试游戏".to_string(),
+            screenshots: Vec::new(),
+            summary: "用于验证发行合同".to_string(),
+            description: Some("描述".to_string()),
+            category: "益智".to_string(),
+            tags: vec!["测试".to_string()],
+            cover_asset_id: None,
+            device_support: GameDistributionDeviceSupport {
+                desktop: true,
+                mobile: false,
+                touch: false,
+            },
+            input_modes: vec![GameDistributionInputMode::Keyboard],
+            orientation: GameDistributionOrientation::Landscape,
+        }
+    }
+
+    #[test]
+    fn metadata_rejects_mobile_games_without_touch_support() {
+        let mut payload = metadata();
+        payload.device_support.mobile = true;
+        assert_eq!(
+            validate_game_metadata(&payload)
+                .expect_err("移动端声明缺少触控应被拒绝")
+                .status_code(),
+            StatusCode::BAD_REQUEST
+        );
+    }
+
+    #[test]
+    fn metadata_requires_cover_and_limits_screenshots() {
+        let mut payload = metadata();
+        payload.cover_asset_id = None;
+        assert_eq!(
+            validate_game_metadata(&payload)
+                .expect_err("缺少封面必须被拒")
+                .status_code(),
+            StatusCode::BAD_REQUEST
+        );
+
+        let mut payload = metadata();
+        payload.cover_asset_id = Some("asset_cover".to_string());
+        payload.screenshots = (0..7).map(|index| format!("asset_{index}")).collect();
+        assert_eq!(
+            validate_game_metadata(&payload)
+                .expect_err("超过 6 张截图必须被拒")
+                .status_code(),
+            StatusCode::BAD_REQUEST
+        );
+
+        let mut payload = metadata();
+        payload.cover_asset_id = Some("asset_cover".to_string());
+        payload.screenshots = (0..6).map(|index| format!("asset_{index}")).collect();
+        validate_game_metadata(&payload).expect("封面 + 6 张截图应通过校验");
+    }
+
+    #[test]
+    fn public_payload_exposes_cover_and_screenshot_object_keys() {
+        let game = GameDistributionGameRecord {
+            game_id: "game_1".to_string(),
+            owner_user_id: "user_1".to_string(),
+            title: "封面游戏".to_string(),
+            summary: "摘要".to_string(),
+            description: "描述".to_string(),
+            category: "益智".to_string(),
+            tags_json: "[]".to_string(),
+            cover_asset_id: Some("asset_cover".to_string()),
+            author_name: None,
+            author_avatar_url: None,
+            device_support_desktop: true,
+            device_support_mobile: false,
+            device_support_touch: false,
+            input_modes_json: "[]".to_string(),
+            orientation: "responsive".to_string(),
+            publication_revision: 1,
+            active_version_id: Some("version_1".to_string()),
+            visibility: "published".to_string(),
+            play_count: 0,
+            created_at: "2026-09-20T00:00:00Z".to_string(),
+            updated_at: "2026-09-20T00:00:00Z".to_string(),
+            cover_object_key: Some("generated/game-cover.png".to_string()),
+            screenshots_json: Some(
+                r#"[{"assetId":"asset_1","objectKey":"generated/shot-1.png"}]"#.to_string(),
+            ),
+        };
+        let payload = game_payload(&game);
+        assert_eq!(
+            payload["coverObjectKey"],
+            Value::String("generated/game-cover.png".to_string())
+        );
+        assert_eq!(
+            payload["screenshots"][0],
+            Value::String("generated/shot-1.png".to_string())
+        );
+    }
+
+    #[test]
+    fn version_detail_payload_exposes_frozen_metadata_to_owner() {
+        let game = GameDistributionGameRecord {
+            game_id: "game_1".to_string(),
+            owner_user_id: "user_1".to_string(),
+            title: "封面游戏".to_string(),
+            summary: "摘要".to_string(),
+            description: "描述".to_string(),
+            category: "益智".to_string(),
+            tags_json: "[]".to_string(),
+            cover_asset_id: Some("asset_cover".to_string()),
+            author_name: None,
+            author_avatar_url: None,
+            device_support_desktop: true,
+            device_support_mobile: false,
+            device_support_touch: false,
+            input_modes_json: "[]".to_string(),
+            orientation: "responsive".to_string(),
+            publication_revision: 1,
+            active_version_id: Some("version_1".to_string()),
+            visibility: "published".to_string(),
+            play_count: 0,
+            created_at: "2026-09-20T00:00:00Z".to_string(),
+            updated_at: "2026-09-20T00:00:00Z".to_string(),
+            cover_object_key: Some("generated/game-cover.png".to_string()),
+            screenshots_json: None,
+        };
+        let mut version = GameDistributionVersionRecord {
+            version_id: "version_2".to_string(),
+            game_id: "game_1".to_string(),
+            owner_user_id: "user_1".to_string(),
+            version_number: 2,
+            package_sha256: "a".repeat(64),
+            package_bytes: 1024,
+            package_file_count: 1,
+            package_entry_path: "index.html".to_string(),
+            status: "pending_review".to_string(),
+            review_reason: None,
+            entry_url: None,
+            publication_revision: 1,
+            created_at: "2026-09-20T00:00:00Z".to_string(),
+            updated_at: "2026-09-20T00:00:00Z".to_string(),
+            metadata_json: Some(
+                r#"{"coverAssetId":"asset_cover","coverObjectKey":"generated/game-cover.png","screenshots":[{"assetId":"asset_shot","objectKey":"generated/shot.png"}]}"#
+                    .to_string(),
+            ),
+        };
+
+        let payload = version_detail_payload(&version, &game);
+        assert_eq!(
+            payload["version"]["frozenMetadata"]["coverAssetId"],
+            Value::String("asset_cover".to_string())
+        );
+        assert_eq!(
+            payload["version"]["frozenMetadata"]["screenshots"][0]["assetId"],
+            Value::String("asset_shot".to_string())
+        );
+
+        // 历史版本没有冻结资料时按 null 返回，客户端必须按空值处理。
+        version.metadata_json = None;
+        let legacy_payload = version_detail_payload(&version, &game);
+        assert!(legacy_payload["version"]["frozenMetadata"].is_null());
+    }
+
+    #[test]
+    fn package_validation_errors_are_unprocessable() {
+        let error = map_package_error(ReleasePackageError::MissingEntry);
+        assert_eq!(error.status_code(), StatusCode::UNPROCESSABLE_ENTITY);
+        assert_eq!(error.code(), "PACKAGE_VALIDATION_FAILED");
+    }
+
+    #[test]
+    fn idempotency_key_requires_a_bounded_non_empty_header() {
+        let mut headers = HeaderMap::new();
+        assert_eq!(
+            idempotency_key(&headers)
+                .expect_err("缺少幂等键应失败")
+                .status_code(),
+            StatusCode::BAD_REQUEST
+        );
+        headers.insert("idempotency-key", "operation-1".parse().unwrap());
+        assert_eq!(idempotency_key(&headers).expect("幂等键"), "operation-1");
+    }
+
+    #[tokio::test]
+    async fn release_gateway_is_mounted_and_never_serves_cookie_bearing_requests() {
+        use axum::{body::Body, http::Request};
+        use tower::ServiceExt;
+
+        let app = crate::app::build_router(
+            crate::state::AppState::new(crate::config::AppConfig::default())
+                .expect("测试状态应可构建"),
+        );
+        let with_cookie = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri("/api/game-distribution/releases/game_1/index.html")
+                    .header("cookie", "genarrative.refresh-token=1")
+                    .body(Body::empty())
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(
+            with_cookie.status(),
+            StatusCode::FORBIDDEN,
+            "带平台 Cookie 的发行请求必须在读对象存储前关闭"
+        );
+
+        // 未在白名单内的扩展名直接 404，不进入 SpacetimeDB 与对象存储。
+        let unknown_extension = app
+            .oneshot(
+                Request::builder()
+                    .uri("/api/game-distribution/releases/game_1/payload.bin")
+                    .body(Body::empty())
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(unknown_extension.status(), StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn catalog_and_publish_routes_are_mounted() {
+        use axum::{body::Body, http::Request};
+        use tower::ServiceExt;
+
+        let app = crate::app::build_router(
+            crate::state::AppState::new(crate::config::AppConfig::default())
+                .expect("测试状态应可构建"),
+        );
+
+        // 目录路由存在且走到了 SpacetimeDB 调用：测试态没有可用数据库，应是网关错误而不是 404。
+        let catalog = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri("/api/game-distribution/games")
+                    .body(Body::empty())
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(catalog.status(), StatusCode::BAD_GATEWAY);
+
+        // 发布写入必须要求登录态，未带 Bearer 时在进入业务前就被拒绝。
+        let unauthenticated_create = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/game-distribution/games")
+                    .header("content-type", "application/json")
+                    .body(Body::from("{}"))
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(unauthenticated_create.status(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[test]
+    fn recovery_action_covers_every_version_status() {
+        for (status, expected) in [
+            ("awaiting_upload", "upload"),
+            ("uploaded", "submit"),
+            ("validating", "wait"),
+            ("pending_review", "wait"),
+            ("published", "none"),
+            ("upload_failed", "reupload"),
+            ("validation_failed", "fix_package"),
+            ("rejected", "fix_metadata"),
+            ("cancelled", "none"),
+            ("revoked", "none"),
+        ] {
+            assert_eq!(
+                recovery_action_for_status(status),
+                expected,
+                "版本状态 {status} 的恢复动作不正确"
+            );
+        }
+        assert_eq!(recovery_action_for_status("unknown_status"), "none");
+    }
+
+    #[tokio::test]
+    async fn version_readback_and_cancel_routes_are_mounted() {
+        use axum::{body::Body, http::Request};
+        use tower::ServiceExt;
+
+        let app = crate::app::build_router(
+            crate::state::AppState::new(crate::config::AppConfig::default())
+                .expect("测试状态应可构建"),
+        );
+
+        // 作者回读与撤回都必须要求登录态。
+        let unauthenticated_read = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .uri("/api/game-distribution/versions/version_1")
+                    .body(Body::empty())
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(unauthenticated_read.status(), StatusCode::UNAUTHORIZED);
+
+        let unauthenticated_cancel = app
+            .clone()
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/game-distribution/versions/version_1/cancel")
+                    .header("content-type", "application/json")
+                    .body(Body::from("{}"))
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        assert_eq!(unauthenticated_cancel.status(), StatusCode::UNAUTHORIZED);
+
+        // 管理员读版本同样先过管理员鉴权，匿名请求不得触达业务。
+        let unauthenticated_admin_read = app
+            .oneshot(
+                Request::builder()
+                    .uri("/admin/api/game-distribution/versions/version_1")
+                    .body(Body::empty())
+                    .expect("请求"),
+            )
+            .await
+            .expect("路由响应");
+        // 测试态没有可用的管理员鉴权后端，请求必须在进入业务前失败关闭；
+        // 关键是路由已挂载且不会匿名返回业务结果。
+        assert_ne!(
+            unauthenticated_admin_read.status(),
+            StatusCode::NOT_FOUND,
+            "管理员读版本路由未挂载"
+        );
+        assert_ne!(
+            unauthenticated_admin_read.status(),
+            StatusCode::OK,
+            "匿名请求不得读到版本私有状态"
+        );
+    }
+
+    #[test]
+    fn local_project_id_is_a_short_identifier_or_empty() {
+        assert_eq!(normalize_local_project_id(None).expect("空值"), None);
+        assert_eq!(
+            normalize_local_project_id(Some("   ")).expect("空白按空处理"),
+            None
+        );
+        assert_eq!(
+            normalize_local_project_id(Some(" proj-1 ")).expect("合法标识"),
+            Some("proj-1".to_string())
+        );
+        for invalid in ["../escape", "a/b", "a\\b", ".", ".."] {
+            assert_eq!(
+                normalize_local_project_id(Some(invalid))
+                    .expect_err("非法本地项目标识应被拒绝")
+                    .status_code(),
+                StatusCode::BAD_REQUEST,
+                "未拒绝的本地项目标识：{invalid}"
+            );
+        }
+        assert_eq!(
+            normalize_local_project_id(Some(&"x".repeat(129)))
+                .expect_err("超长标识应被拒绝")
+                .status_code(),
+            StatusCode::BAD_REQUEST
+        );
+    }
+
+    #[test]
+    fn approve_requires_credential_free_https_entry_url() {
+        validate_release_entry_url(
+            "https://games.example.test/releases/game_1/index.html",
+            false,
+        )
+        .expect("发行入口");
+        for invalid in [
+            "/releases/game_1/index.html",
+            "http://games.example.test/releases/game_1/index.html",
+            "http://127.0.0.1:10001/releases/game_1/index.html",
+            "https://user:pass@games.example.test/index.html",
+            "https://games.example.test/index.html?token=1",
+            "https://games.example.test/index.html#x",
+        ] {
+            assert_eq!(
+                validate_release_entry_url(invalid, false)
+                    .expect_err("生产环境非法发行入口应被拒绝")
+                    .status_code(),
+                StatusCode::BAD_REQUEST,
+                "未拒绝的发行入口：{invalid}"
+            );
+        }
+    }
+
+    #[test]
+    fn non_production_release_entry_allows_loopback_http_only() {
+        for allowed in [
+            "http://127.0.0.1:10001/api/game-distribution/releases/game_1/index.html",
+            "http://localhost:10001/api/game-distribution/releases/game_1/index.html",
+            "https://games.example.test/releases/game_1/index.html",
+        ] {
+            validate_release_entry_url(allowed, true).expect("非生产环境应接受回环 http");
+        }
+        for invalid in [
+            "http://games.example.test/releases/game_1/index.html",
+            "http://192.168.1.10:10001/index.html",
+            "http://127.0.0.1:10001/index.html?token=1",
+            "http://user:pass@127.0.0.1:10001/index.html",
+        ] {
+            assert_eq!(
+                validate_release_entry_url(invalid, true)
+                    .expect_err("非生产环境也不能放宽回环之外的地址")
+                    .status_code(),
+                StatusCode::BAD_REQUEST,
+                "未拒绝的发行入口：{invalid}"
+            );
+        }
+    }
+
+    #[test]
+    fn release_response_allows_opaque_sandbox_asset_loads() {
+        // 发行文档在 allow-scripts 沙箱里是 opaque origin；CORP same-origin 会让游戏
+        // 自己的脚本被浏览器拦下。
+        let response = release_asset_response(b"x".to_vec(), "text/javascript; charset=utf-8");
+        assert_eq!(
+            response
+                .headers()
+                .get(header::HeaderName::from_static(
+                    "cross-origin-resource-policy"
+                ))
+                .unwrap(),
+            "cross-origin"
+        );
+        assert_eq!(
+            response
+                .headers()
+                .get(header::ACCESS_CONTROL_ALLOW_ORIGIN)
+                .unwrap(),
+            "*"
+        );
+        assert_eq!(
+            response
+                .headers()
+                .get(header::X_CONTENT_TYPE_OPTIONS)
+                .unwrap(),
+            "nosniff"
+        );
+    }
+
+    #[test]
+    fn release_response_sets_nosniff_and_scopes_csp_to_html() {
+        let html = release_asset_response(b"<html></html>".to_vec(), "text/html; charset=utf-8");
+        assert_eq!(
+            html.headers().get(header::X_CONTENT_TYPE_OPTIONS).unwrap(),
+            "nosniff"
+        );
+        assert!(html.headers().contains_key(header::CONTENT_SECURITY_POLICY));
+
+        let image = release_asset_response(vec![1, 2, 3], "image/png");
+        assert_eq!(
+            image.headers().get(header::CONTENT_TYPE).unwrap(),
+            "image/png"
+        );
+        assert!(
+            !image
+                .headers()
+                .contains_key(header::CONTENT_SECURITY_POLICY)
+        );
+    }
+
+    #[test]
+    fn release_package_cache_evicts_by_entry_and_byte_budget() {
+        let mut cache = ReleasePackageCache::default();
+        for index in 0..RELEASE_PACKAGE_CACHE_MAX_ENTRIES {
+            cache.insert(format!("key-{index}"), Arc::new(vec![0_u8; 8]));
+        }
+        assert!(cache.get("key-0").is_some());
+        cache.insert("overflow".to_string(), Arc::new(vec![0_u8; 8]));
+        assert!(cache.get("key-0").is_none(), "最旧条目应被淘汰");
+        assert!(cache.get("overflow").is_some());
+
+        let mut byte_budget = ReleasePackageCache::default();
+        byte_budget.insert_with_limits("big".to_string(), Arc::new(vec![0_u8; 8]), 8, 16);
+        byte_budget.insert_with_limits("second".to_string(), Arc::new(vec![0_u8; 8]), 8, 16);
+        byte_budget.insert_with_limits("third".to_string(), Arc::new(vec![0_u8; 8]), 8, 16);
+        assert!(byte_budget.get("big").is_none(), "超出字节预算时应淘汰旧包");
+        assert_eq!(byte_budget.total_bytes, 16);
+
+        let mut oversized = ReleasePackageCache::default();
+        oversized.insert_with_limits("kept".to_string(), Arc::new(vec![0_u8; 4]), 8, 16);
+        oversized.insert_with_limits("huge".to_string(), Arc::new(vec![0_u8; 17]), 8, 16);
+        assert!(oversized.get("huge").is_none(), "超预算包本身不得进入缓存");
+        assert!(
+            oversized.get("kept").is_some(),
+            "超预算包不应连带淘汰已有条目"
+        );
+        assert_eq!(oversized.total_bytes, 4);
+    }
+}
diff --git a/server-rs/crates/api-server/src/state.rs b/server-rs/crates/api-server/src/state.rs
index bf96f65c3..d2a4208a3 100644
--- a/server-rs/crates/api-server/src/state.rs
+++ b/server-rs/crates/api-server/src/state.rs
@@ -1181,6 +1181,25 @@ impl AppState {
         Ok(module_runtime::is_feature_gate_allowed(gate, &user_context))
     }
 
+    /// 游戏分发写入开关：默认开放，只有运营在灰度配置里显式收紧（白名单/灰度/全关）才拦截。
+    /// 读取、目录、详情、发行网关与安全下架不经过这里。
+    pub async fn is_game_distribution_publish_enabled_for_user(
+        &self,
+        user_id: Option<&str>,
+    ) -> Result<bool, SpacetimeClientError> {
+        let gates = self.get_feature_gate_config().await?;
+        let gate = gates
+            .iter()
+            .find(|item| item.gate_key == module_runtime::GAME_DISTRIBUTION_PUBLISH_GATE_KEY);
+        let user_context = self
+            .feature_gate_user_context(
+                user_id,
+                gate.map(feature_gate_requires_user_tags).unwrap_or(false),
+            )
+            .await;
+        Ok(module_runtime::is_feature_gate_allowed(gate, &user_context))
+    }
+
     pub async fn is_agc_template_library_enabled_for_user(
         &self,
         user_id: Option<&str>,
diff --git a/server-rs/crates/module-game-distribution/Cargo.toml b/server-rs/crates/module-game-distribution/Cargo.toml
new file mode 100644
index 000000000..10fd80369
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "module-game-distribution"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[dependencies]
+hex = { workspace = true }
+serde = { workspace = true }
+sha2 = { workspace = true }
+shared-kernel = { workspace = true }
+zip = { workspace = true, features = ["deflate"] }
diff --git a/server-rs/crates/module-game-distribution/src/application.rs b/server-rs/crates/module-game-distribution/src/application.rs
new file mode 100644
index 000000000..89276f1e7
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/application.rs
@@ -0,0 +1,1113 @@
+use std::{
+    collections::HashMap,
+    sync::{Arc, Mutex},
+};
+
+use crate::{
+    commands::{CreateGameInput, CreateVersionInput, IdempotencyRequest, ReviewDecision},
+    domain::{
+        GameDistributionAction, GameSnapshot, GameVersionSnapshot, GameVersionStatus,
+        GameVisibility, normalize_id,
+    },
+    errors::{GameDistributionError, GameDistributionFieldError},
+};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameOperationResult<T> {
+    pub snapshot: T,
+    pub replayed: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PublicationOperationResult {
+    pub game: GameSnapshot,
+    pub version: GameVersionSnapshot,
+    pub replayed: bool,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct InMemoryGameDistributionStore {
+    inner: Arc<Mutex<GameDistributionState>>,
+}
+
+#[derive(Debug, Default)]
+struct GameDistributionState {
+    games: HashMap<String, GameSnapshot>,
+    versions: HashMap<String, GameVersionSnapshot>,
+    idempotency: HashMap<IdempotencyScope, IdempotencyRecord>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+struct IdempotencyScope {
+    principal_id: String,
+    action: GameDistributionAction,
+    key: String,
+}
+
+#[derive(Clone, Debug)]
+struct IdempotencyRecord {
+    request_digest: String,
+    outcome: StoredOutcome,
+}
+
+#[derive(Clone, Debug)]
+enum StoredOutcome {
+    Game(GameSnapshot),
+    Version(GameVersionSnapshot),
+    Publication {
+        game: GameSnapshot,
+        version: GameVersionSnapshot,
+    },
+}
+
+#[derive(Clone, Debug)]
+pub struct GameDistributionService {
+    store: InMemoryGameDistributionStore,
+}
+
+impl GameDistributionService {
+    pub fn new(store: InMemoryGameDistributionStore) -> Self {
+        Self { store }
+    }
+
+    pub fn store(&self) -> InMemoryGameDistributionStore {
+        self.store.clone()
+    }
+
+    pub fn create_game(
+        &self,
+        input: CreateGameInput,
+    ) -> Result<GameOperationResult<GameSnapshot>, GameDistributionError> {
+        let game_id = required(input.game_id, GameDistributionFieldError::MissingGameId)?;
+        let owner_user_id = required(
+            input.owner_user_id,
+            GameDistributionFieldError::MissingOwnerUserId,
+        )?;
+        let idem = normalize_idempotency(input.idempotency)?;
+        let scope = scope(&owner_user_id, GameDistributionAction::CreateGame, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return game_result(outcome, true);
+        }
+        if state.games.contains_key(&game_id) {
+            return Err(GameDistributionError::GameAlreadyExists);
+        }
+        let snapshot = GameSnapshot {
+            game_id: game_id.clone(),
+            owner_user_id,
+            publication_revision: 0,
+            active_version_id: None,
+            visibility: GameVisibility::Unpublished,
+            created_at_micros: input.created_at_micros,
+            updated_at_micros: input.created_at_micros,
+        };
+        state.games.insert(game_id, snapshot.clone());
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Game(snapshot.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot,
+            replayed: false,
+        })
+    }
+
+    pub fn create_version(
+        &self,
+        input: CreateVersionInput,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        let game_id = required(input.game_id, GameDistributionFieldError::MissingGameId)?;
+        let owner_user_id = required(
+            input.owner_user_id,
+            GameDistributionFieldError::MissingOwnerUserId,
+        )?;
+        let version_id = required(
+            input.version_id,
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let package_sha256 = normalize_package_digest(&input.package_sha256)?;
+        validate_package_bytes(input.package_bytes)?;
+        let idem = normalize_idempotency(input.idempotency)?;
+        let scope = scope(&owner_user_id, GameDistributionAction::CreateVersion, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return version_result(outcome, true);
+        }
+        let game = state
+            .games
+            .get(&game_id)
+            .ok_or(GameDistributionError::GameNotFound)?;
+        ensure_owner(game, &owner_user_id)?;
+        if game.visibility == GameVisibility::Suspended {
+            return Err(GameDistributionError::GameSuspended);
+        }
+        if state.versions.contains_key(&version_id) {
+            return Err(GameDistributionError::VersionAlreadyExists);
+        }
+        let version_number = state
+            .versions
+            .values()
+            .filter(|version| version.game_id == game_id)
+            .map(|version| version.version_number)
+            .max()
+            .unwrap_or(0)
+            .saturating_add(1);
+        let snapshot = GameVersionSnapshot {
+            version_id: version_id.clone(),
+            game_id,
+            version_number,
+            package_sha256,
+            package_bytes: input.package_bytes,
+            status: GameVersionStatus::AwaitingUpload,
+            review_reason: None,
+            created_at_micros: input.created_at_micros,
+            updated_at_micros: input.created_at_micros,
+        };
+        state.versions.insert(version_id, snapshot.clone());
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Version(snapshot.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot,
+            replayed: false,
+        })
+    }
+
+    pub fn confirm_package(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        package_sha256: &str,
+        package_bytes: u64,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        let owner_user_id = required(
+            owner_user_id.to_string(),
+            GameDistributionFieldError::MissingOwnerUserId,
+        )?;
+        let version_id = required(
+            version_id.to_string(),
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let package_sha256 = normalize_package_digest(package_sha256)?;
+        validate_package_bytes(package_bytes)?;
+        let idem = normalize_idempotency(idempotency)?;
+        let scope = scope(
+            &owner_user_id,
+            GameDistributionAction::ConfirmPackage,
+            &idem,
+        );
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return version_result(outcome, true);
+        }
+        let game_id = state
+            .versions
+            .get(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?
+            .game_id
+            .clone();
+        let game = state
+            .games
+            .get(&game_id)
+            .ok_or(GameDistributionError::GameNotFound)?;
+        ensure_owner(game, &owner_user_id)?;
+        let version = state
+            .versions
+            .get_mut(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?;
+        if version.package_sha256 != package_sha256 || version.package_bytes != package_bytes {
+            return Err(GameDistributionError::PackageMismatch);
+        }
+        if version.status != GameVersionStatus::AwaitingUpload
+            && version.status != GameVersionStatus::UploadFailed
+        {
+            if version.status == GameVersionStatus::Uploaded {
+                let snapshot = version.clone();
+                remember(
+                    &mut state,
+                    scope,
+                    idem.request_digest,
+                    StoredOutcome::Version(snapshot.clone()),
+                );
+                return Ok(GameOperationResult {
+                    snapshot,
+                    replayed: false,
+                });
+            }
+            return Err(invalid_transition(
+                version.status,
+                GameVersionStatus::Uploaded,
+            ));
+        }
+        version.status = GameVersionStatus::Uploaded;
+        version.updated_at_micros = at_micros;
+        let snapshot = version.clone();
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Version(snapshot.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot,
+            replayed: false,
+        })
+    }
+
+    pub fn fail_upload(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        self.transition_owned_version(
+            owner_user_id,
+            version_id,
+            idempotency,
+            GameDistributionAction::FailUpload,
+            &[GameVersionStatus::AwaitingUpload],
+            GameVersionStatus::UploadFailed,
+            at_micros,
+            None,
+        )
+    }
+
+    pub fn submit_version(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        self.transition_owned_version(
+            owner_user_id,
+            version_id,
+            idempotency,
+            GameDistributionAction::SubmitVersion,
+            &[
+                GameVersionStatus::Uploaded,
+                GameVersionStatus::ValidationFailed,
+            ],
+            GameVersionStatus::Validating,
+            at_micros,
+            None,
+        )
+    }
+
+    pub fn pass_validation(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        self.transition_owned_version(
+            owner_user_id,
+            version_id,
+            idempotency,
+            GameDistributionAction::PassValidation,
+            &[GameVersionStatus::Validating],
+            GameVersionStatus::PendingReview,
+            at_micros,
+            None,
+        )
+    }
+
+    pub fn fail_validation(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        reason: String,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        let reason = required(reason, GameDistributionFieldError::MissingReviewReason)?;
+        self.transition_owned_version(
+            owner_user_id,
+            version_id,
+            idempotency,
+            GameDistributionAction::FailValidation,
+            &[GameVersionStatus::Validating],
+            GameVersionStatus::ValidationFailed,
+            at_micros,
+            Some(reason),
+        )
+    }
+
+    pub fn cancel_version(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        let owner_user_id = required(
+            owner_user_id.to_string(),
+            GameDistributionFieldError::MissingOwnerUserId,
+        )?;
+        let version_id = required(
+            version_id.to_string(),
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let idem = normalize_idempotency(idempotency)?;
+        let scope = scope(&owner_user_id, GameDistributionAction::CancelVersion, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return version_result(outcome, true);
+        }
+        let game_id = state
+            .versions
+            .get(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?
+            .game_id
+            .clone();
+        let game = state
+            .games
+            .get(&game_id)
+            .ok_or(GameDistributionError::GameNotFound)?;
+        ensure_owner(game, &owner_user_id)?;
+        let version = state
+            .versions
+            .get_mut(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?;
+        if !version.status.can_cancel() {
+            return Err(invalid_transition(
+                version.status,
+                GameVersionStatus::Cancelled,
+            ));
+        }
+        version.status = GameVersionStatus::Cancelled;
+        version.updated_at_micros = at_micros;
+        let snapshot = version.clone();
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Version(snapshot.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot,
+            replayed: false,
+        })
+    }
+
+    pub fn review_version(
+        &self,
+        reviewer_user_id: &str,
+        version_id: &str,
+        decision: ReviewDecision,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<PublicationOperationResult, GameDistributionError> {
+        let reviewer_user_id = required(
+            reviewer_user_id.to_string(),
+            GameDistributionFieldError::MissingActorUserId,
+        )?;
+        let version_id = required(
+            version_id.to_string(),
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let idem = normalize_idempotency(idempotency)?;
+        let action = match decision {
+            ReviewDecision::Approve { .. } => GameDistributionAction::ApproveVersion,
+            ReviewDecision::Reject { .. } => GameDistributionAction::RejectVersion,
+        };
+        let scope = scope(&reviewer_user_id, action, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return publication_result(outcome, true);
+        }
+        let (expected_revision, reject_reason) = match decision {
+            ReviewDecision::Approve {
+                expected_publication_revision,
+            } => (expected_publication_revision, None),
+            ReviewDecision::Reject {
+                expected_publication_revision,
+                reason,
+            } => (
+                expected_publication_revision,
+                Some(required(
+                    reason,
+                    GameDistributionFieldError::MissingReviewReason,
+                )?),
+            ),
+        };
+        let version = state
+            .versions
+            .get(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?
+            .clone();
+        let game = state
+            .games
+            .get(&version.game_id)
+            .ok_or(GameDistributionError::GameNotFound)?
+            .clone();
+        if game.publication_revision != expected_revision {
+            return Err(GameDistributionError::PublicationConflict {
+                expected: expected_revision,
+                actual: game.publication_revision,
+            });
+        }
+        if version.status != GameVersionStatus::PendingReview {
+            return Err(GameDistributionError::ReviewActionNotAllowed);
+        }
+        if game.visibility == GameVisibility::Suspended {
+            return Err(GameDistributionError::GameSuspended);
+        }
+        let mut next_game = game;
+        let mut next_version = version;
+        next_game.publication_revision = next_game.publication_revision.saturating_add(1);
+        next_game.updated_at_micros = at_micros;
+        next_version.updated_at_micros = at_micros;
+        match reject_reason {
+            Some(reason) => {
+                next_version.status = GameVersionStatus::Rejected;
+                next_version.review_reason = Some(reason);
+            }
+            None => {
+                next_version.status = GameVersionStatus::Published;
+                next_version.review_reason = None;
+                next_game.visibility = GameVisibility::Published;
+                next_game.active_version_id = Some(next_version.version_id.clone());
+            }
+        }
+        state
+            .games
+            .insert(next_game.game_id.clone(), next_game.clone());
+        state
+            .versions
+            .insert(next_version.version_id.clone(), next_version.clone());
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Publication {
+                game: next_game.clone(),
+                version: next_version.clone(),
+            },
+        );
+        Ok(PublicationOperationResult {
+            game: next_game,
+            version: next_version,
+            replayed: false,
+        })
+    }
+
+    pub fn unpublish_game(
+        &self,
+        owner_user_id: &str,
+        game_id: &str,
+        expected_publication_revision: u64,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameSnapshot>, GameDistributionError> {
+        self.mutate_game_visibility(
+            owner_user_id,
+            game_id,
+            expected_publication_revision,
+            idempotency,
+            GameDistributionAction::UnpublishGame,
+            GameVisibility::Unpublished,
+            at_micros,
+        )
+    }
+
+    pub fn suspend_game(
+        &self,
+        actor_user_id: &str,
+        game_id: &str,
+        expected_publication_revision: u64,
+        idempotency: IdempotencyRequest,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameSnapshot>, GameDistributionError> {
+        self.mutate_game_visibility(
+            actor_user_id,
+            game_id,
+            expected_publication_revision,
+            idempotency,
+            GameDistributionAction::SuspendGame,
+            GameVisibility::Suspended,
+            at_micros,
+        )
+    }
+
+    pub fn get_game(&self, game_id: &str) -> Result<GameSnapshot, GameDistributionError> {
+        let game_id = required(
+            game_id.to_string(),
+            GameDistributionFieldError::MissingGameId,
+        )?;
+        let state = lock(&self.store)?;
+        state
+            .games
+            .get(&game_id)
+            .cloned()
+            .ok_or(GameDistributionError::GameNotFound)
+    }
+
+    pub fn get_version(
+        &self,
+        version_id: &str,
+    ) -> Result<GameVersionSnapshot, GameDistributionError> {
+        let version_id = required(
+            version_id.to_string(),
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let state = lock(&self.store)?;
+        state
+            .versions
+            .get(&version_id)
+            .cloned()
+            .ok_or(GameDistributionError::VersionNotFound)
+    }
+
+    fn transition_owned_version(
+        &self,
+        owner_user_id: &str,
+        version_id: &str,
+        idempotency: IdempotencyRequest,
+        action: GameDistributionAction,
+        from: &[GameVersionStatus],
+        to: GameVersionStatus,
+        at_micros: i64,
+        reason: Option<String>,
+    ) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+        let owner_user_id = required(
+            owner_user_id.to_string(),
+            GameDistributionFieldError::MissingOwnerUserId,
+        )?;
+        let version_id = required(
+            version_id.to_string(),
+            GameDistributionFieldError::MissingVersionId,
+        )?;
+        let idem = normalize_idempotency(idempotency)?;
+        let scope = scope(&owner_user_id, action, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return version_result(outcome, true);
+        }
+        let game_id = state
+            .versions
+            .get(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?
+            .game_id
+            .clone();
+        let game = state
+            .games
+            .get(&game_id)
+            .ok_or(GameDistributionError::GameNotFound)?;
+        ensure_owner(game, &owner_user_id)?;
+        let version = state
+            .versions
+            .get_mut(&version_id)
+            .ok_or(GameDistributionError::VersionNotFound)?;
+        if !from.contains(&version.status) {
+            return Err(invalid_transition(version.status, to));
+        }
+        version.status = to;
+        version.review_reason = reason;
+        version.updated_at_micros = at_micros;
+        let snapshot = version.clone();
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Version(snapshot.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot,
+            replayed: false,
+        })
+    }
+
+    fn mutate_game_visibility(
+        &self,
+        actor_user_id: &str,
+        game_id: &str,
+        expected_publication_revision: u64,
+        idempotency: IdempotencyRequest,
+        action: GameDistributionAction,
+        visibility: GameVisibility,
+        at_micros: i64,
+    ) -> Result<GameOperationResult<GameSnapshot>, GameDistributionError> {
+        let actor_user_id = required(
+            actor_user_id.to_string(),
+            GameDistributionFieldError::MissingActorUserId,
+        )?;
+        let game_id = required(
+            game_id.to_string(),
+            GameDistributionFieldError::MissingGameId,
+        )?;
+        let idem = normalize_idempotency(idempotency)?;
+        let scope = scope(&actor_user_id, action, &idem);
+        let mut state = lock(&self.store)?;
+        if let Some(outcome) = replay_outcome(&state, &scope, &idem.request_digest)? {
+            return game_result(outcome, true);
+        }
+        let game = state
+            .games
+            .get(&game_id)
+            .ok_or(GameDistributionError::GameNotFound)?
+            .clone();
+        if action == GameDistributionAction::UnpublishGame {
+            ensure_owner(&game, &actor_user_id)?;
+            if game.visibility != GameVisibility::Published {
+                return Err(GameDistributionError::GameNotPublished);
+            }
+        }
+        if game.publication_revision != expected_publication_revision {
+            return Err(GameDistributionError::PublicationConflict {
+                expected: expected_publication_revision,
+                actual: game.publication_revision,
+            });
+        }
+        if action == GameDistributionAction::SuspendGame
+            && game.visibility == GameVisibility::Suspended
+        {
+            return Err(GameDistributionError::GameSuspended);
+        }
+        let active_version_id = game.active_version_id.clone();
+        let mut next_game = game;
+        next_game.visibility = visibility;
+        next_game.publication_revision = next_game.publication_revision.saturating_add(1);
+        next_game.updated_at_micros = at_micros;
+        if visibility == GameVisibility::Unpublished {
+            next_game.active_version_id = None;
+            if let Some(version_id) = active_version_id {
+                if let Some(version) = state.versions.get_mut(&version_id) {
+                    if version.status == GameVersionStatus::Published {
+                        version.status = GameVersionStatus::Revoked;
+                        version.updated_at_micros = at_micros;
+                    }
+                }
+            }
+        }
+        state
+            .games
+            .insert(next_game.game_id.clone(), next_game.clone());
+        remember(
+            &mut state,
+            scope,
+            idem.request_digest,
+            StoredOutcome::Game(next_game.clone()),
+        );
+        Ok(GameOperationResult {
+            snapshot: next_game,
+            replayed: false,
+        })
+    }
+}
+
+fn required(
+    value: String,
+    error: GameDistributionFieldError,
+) -> Result<String, GameDistributionError> {
+    normalize_id(value).ok_or(GameDistributionError::Field(error))
+}
+
+fn normalize_idempotency(
+    value: IdempotencyRequest,
+) -> Result<IdempotencyRequest, GameDistributionError> {
+    value.validate().map_err(GameDistributionError::Field)?;
+    Ok(IdempotencyRequest {
+        key: normalize_id(value.key).ok_or(GameDistributionError::Field(
+            GameDistributionFieldError::MissingIdempotencyKey,
+        ))?,
+        request_digest: normalize_id(value.request_digest).ok_or(GameDistributionError::Field(
+            GameDistributionFieldError::MissingRequestDigest,
+        ))?,
+    })
+}
+
+fn normalize_package_digest(value: &str) -> Result<String, GameDistributionError> {
+    let normalized = value.trim().to_ascii_lowercase();
+    if normalized.len() != 64 || !normalized.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return Err(GameDistributionError::Field(
+            GameDistributionFieldError::InvalidPackageDigest,
+        ));
+    }
+    Ok(normalized)
+}
+
+fn validate_package_bytes(value: u64) -> Result<(), GameDistributionError> {
+    if value == 0 {
+        Err(GameDistributionError::Field(
+            GameDistributionFieldError::InvalidPackageBytes,
+        ))
+    } else {
+        Ok(())
+    }
+}
+
+fn scope(
+    principal_id: &str,
+    action: GameDistributionAction,
+    idem: &IdempotencyRequest,
+) -> IdempotencyScope {
+    IdempotencyScope {
+        principal_id: principal_id.to_string(),
+        action,
+        key: idem.key.clone(),
+    }
+}
+
+fn lock(
+    store: &InMemoryGameDistributionStore,
+) -> Result<std::sync::MutexGuard<'_, GameDistributionState>, GameDistributionError> {
+    store
+        .inner
+        .lock()
+        .map_err(|_| GameDistributionError::IdempotencyOutcomeMismatch)
+}
+
+fn replay_outcome(
+    state: &GameDistributionState,
+    scope: &IdempotencyScope,
+    request_digest: &str,
+) -> Result<Option<StoredOutcome>, GameDistributionError> {
+    let Some(record) = state.idempotency.get(scope) else {
+        return Ok(None);
+    };
+    if record.request_digest != request_digest {
+        return Err(GameDistributionError::IdempotencyConflict);
+    }
+    Ok(Some(record.outcome.clone()))
+}
+
+fn remember(
+    state: &mut GameDistributionState,
+    scope: IdempotencyScope,
+    request_digest: String,
+    outcome: StoredOutcome,
+) {
+    state.idempotency.insert(
+        scope,
+        IdempotencyRecord {
+            request_digest,
+            outcome,
+        },
+    );
+}
+
+fn game_result(
+    outcome: StoredOutcome,
+    replayed: bool,
+) -> Result<GameOperationResult<GameSnapshot>, GameDistributionError> {
+    match outcome {
+        StoredOutcome::Game(snapshot) => Ok(GameOperationResult { snapshot, replayed }),
+        _ => Err(GameDistributionError::IdempotencyOutcomeMismatch),
+    }
+}
+
+fn version_result(
+    outcome: StoredOutcome,
+    replayed: bool,
+) -> Result<GameOperationResult<GameVersionSnapshot>, GameDistributionError> {
+    match outcome {
+        StoredOutcome::Version(snapshot) => Ok(GameOperationResult { snapshot, replayed }),
+        _ => Err(GameDistributionError::IdempotencyOutcomeMismatch),
+    }
+}
+
+fn publication_result(
+    outcome: StoredOutcome,
+    replayed: bool,
+) -> Result<PublicationOperationResult, GameDistributionError> {
+    match outcome {
+        StoredOutcome::Publication { game, version } => Ok(PublicationOperationResult {
+            game,
+            version,
+            replayed,
+        }),
+        _ => Err(GameDistributionError::IdempotencyOutcomeMismatch),
+    }
+}
+
+fn ensure_owner(game: &GameSnapshot, owner_user_id: &str) -> Result<(), GameDistributionError> {
+    if game.owner_user_id == owner_user_id {
+        Ok(())
+    } else {
+        Err(GameDistributionError::Forbidden)
+    }
+}
+
+fn invalid_transition(from: GameVersionStatus, to: GameVersionStatus) -> GameDistributionError {
+    GameDistributionError::InvalidVersionTransition { from, to }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{
+        CreateGameInput, CreateVersionInput, IdempotencyRequest, ReviewDecision,
+        compute_request_digest,
+    };
+
+    fn idem(key: &str, body: &str) -> IdempotencyRequest {
+        IdempotencyRequest {
+            key: key.to_string(),
+            request_digest: compute_request_digest(body),
+        }
+    }
+
+    fn service() -> GameDistributionService {
+        GameDistributionService::new(InMemoryGameDistributionStore::default())
+    }
+
+    fn create_game(service: &GameDistributionService) -> GameSnapshot {
+        service
+            .create_game(CreateGameInput {
+                game_id: "game-1".to_string(),
+                owner_user_id: "owner-1".to_string(),
+                idempotency: idem("create-game-1", "game-1"),
+                created_at_micros: 1,
+            })
+            .expect("game should be created")
+            .snapshot
+    }
+
+    fn create_version(service: &GameDistributionService) -> GameVersionSnapshot {
+        create_game(service);
+        service
+            .create_version(CreateVersionInput {
+                game_id: "game-1".to_string(),
+                owner_user_id: "owner-1".to_string(),
+                version_id: "version-1".to_string(),
+                package_sha256: "a".repeat(64),
+                package_bytes: 42,
+                idempotency: idem("create-version-1", "version-1"),
+                created_at_micros: 2,
+            })
+            .expect("version should be created")
+            .snapshot
+    }
+
+    #[test]
+    fn idempotency_replays_same_snapshot_and_rejects_digest_conflict() {
+        let service = service();
+        let first = service
+            .create_game(CreateGameInput {
+                game_id: "game-1".to_string(),
+                owner_user_id: "owner-1".to_string(),
+                idempotency: idem("same-key", "first"),
+                created_at_micros: 1,
+            })
+            .expect("first create should succeed");
+        let replay = service
+            .create_game(CreateGameInput {
+                game_id: "game-2".to_string(),
+                owner_user_id: "owner-1".to_string(),
+                idempotency: idem("same-key", "first"),
+                created_at_micros: 99,
+            })
+            .expect("same request should replay");
+        assert!(replay.replayed);
+        assert_eq!(replay.snapshot, first.snapshot);
+        let conflict = service
+            .create_game(CreateGameInput {
+                game_id: "game-3".to_string(),
+                owner_user_id: "owner-1".to_string(),
+                idempotency: idem("same-key", "different"),
+                created_at_micros: 3,
+            })
+            .expect_err("same key with another digest must fail");
+        assert_eq!(conflict, GameDistributionError::IdempotencyConflict);
+    }
+
+    #[test]
+    fn owner_is_required_for_version_and_package_mutations() {
+        let service = service();
+        create_version(&service);
+        let error = service
+            .confirm_package(
+                "other-owner",
+                "version-1",
+                &"a".repeat(64),
+                42,
+                idem("upload-1", "upload"),
+                3,
+            )
+            .expect_err("other owner must be denied");
+        assert_eq!(error, GameDistributionError::Forbidden);
+    }
+
+    #[test]
+    fn version_state_machine_reaches_pending_review_only_after_package_validation() {
+        let service = service();
+        create_version(&service);
+        let invalid = service
+            .pass_validation(
+                "owner-1",
+                "version-1",
+                idem("pass-before-submit", "pass"),
+                3,
+            )
+            .expect_err("validation cannot start before upload");
+        assert_eq!(
+            invalid,
+            GameDistributionError::InvalidVersionTransition {
+                from: GameVersionStatus::AwaitingUpload,
+                to: GameVersionStatus::PendingReview
+            }
+        );
+        service
+            .confirm_package(
+                "owner-1",
+                "version-1",
+                &"a".repeat(64),
+                42,
+                idem("upload-1", "upload"),
+                3,
+            )
+            .expect("upload should succeed");
+        service
+            .submit_version("owner-1", "version-1", idem("submit-1", "submit"), 4)
+            .expect("submit should start validation");
+        let pending = service
+            .pass_validation("owner-1", "version-1", idem("pass-1", "pass"), 5)
+            .expect("validation should pass");
+        assert_eq!(pending.snapshot.status, GameVersionStatus::PendingReview);
+    }
+
+    #[test]
+    fn validation_failure_can_retry_same_confirmed_package() {
+        let service = service();
+        create_version(&service);
+        service
+            .confirm_package(
+                "owner-1",
+                "version-1",
+                &"a".repeat(64),
+                42,
+                idem("upload-1", "upload"),
+                3,
+            )
+            .expect("upload should succeed");
+        service
+            .submit_version("owner-1", "version-1", idem("submit-1", "submit"), 4)
+            .expect("submit should start validation");
+        service
+            .fail_validation(
+                "owner-1",
+                "version-1",
+                "校验器暂时失败".to_string(),
+                idem("fail-validation-1", "fail"),
+                5,
+            )
+            .expect("validation failure should be recorded");
+        let retried = service
+            .submit_version("owner-1", "version-1", idem("submit-2", "retry"), 6)
+            .expect("same confirmed package should be retryable");
+        assert_eq!(retried.snapshot.status, GameVersionStatus::Validating);
+    }
+
+    #[test]
+    fn publication_cas_rejects_stale_review_and_unpublish() {
+        let service = service();
+        create_version(&service);
+        service
+            .confirm_package(
+                "owner-1",
+                "version-1",
+                &"a".repeat(64),
+                42,
+                idem("upload-1", "upload"),
+                3,
+            )
+            .expect("upload should succeed");
+        service
+            .submit_version("owner-1", "version-1", idem("submit-1", "submit"), 4)
+            .expect("submit should start validation");
+        service
+            .pass_validation("owner-1", "version-1", idem("pass-1", "pass"), 5)
+            .expect("validation should pass");
+        let published = service
+            .review_version(
+                "reviewer-1",
+                "version-1",
+                ReviewDecision::Approve {
+                    expected_publication_revision: 0,
+                },
+                idem("review-1", "approve"),
+                6,
+            )
+            .expect("review should publish");
+        assert_eq!(published.game.publication_revision, 1);
+        assert_eq!(published.game.visibility, GameVisibility::Published);
+        let stale = service
+            .unpublish_game(
+                "owner-1",
+                "game-1",
+                0,
+                idem("unpublish-stale", "unpublish"),
+                7,
+            )
+            .expect_err("stale publication revision must fail");
+        assert_eq!(
+            stale,
+            GameDistributionError::PublicationConflict {
+                expected: 0,
+                actual: 1
+            }
+        );
+        let unpublished = service
+            .unpublish_game("owner-1", "game-1", 1, idem("unpublish-1", "unpublish"), 8)
+            .expect("current revision should unpublish");
+        assert_eq!(unpublished.snapshot.visibility, GameVisibility::Unpublished);
+        assert_eq!(
+            service
+                .get_version("version-1")
+                .expect("version should exist")
+                .status,
+            GameVersionStatus::Revoked
+        );
+    }
+
+    #[test]
+    fn rejected_review_preserves_reason_and_advances_publication_revision() {
+        let service = service();
+        create_version(&service);
+        service
+            .confirm_package(
+                "owner-1",
+                "version-1",
+                &"a".repeat(64),
+                42,
+                idem("upload-1", "upload"),
+                3,
+            )
+            .expect("upload should succeed");
+        service
+            .submit_version("owner-1", "version-1", idem("submit-1", "submit"), 4)
+            .expect("submit should start validation");
+        service
+            .pass_validation("owner-1", "version-1", idem("pass-1", "pass"), 5)
+            .expect("validation should pass");
+        let rejected = service
+            .review_version(
+                "reviewer-1",
+                "version-1",
+                ReviewDecision::Reject {
+                    expected_publication_revision: 0,
+                    reason: "需要修复资源".to_string(),
+                },
+                idem("review-1", "reject"),
+                6,
+            )
+            .expect("review rejection should succeed");
+        assert_eq!(rejected.version.status, GameVersionStatus::Rejected);
+        assert_eq!(
+            rejected.version.review_reason.as_deref(),
+            Some("需要修复资源")
+        );
+        assert_eq!(rejected.game.publication_revision, 1);
+        assert_eq!(rejected.game.visibility, GameVisibility::Unpublished);
+    }
+}
diff --git a/server-rs/crates/module-game-distribution/src/commands.rs b/server-rs/crates/module-game-distribution/src/commands.rs
new file mode 100644
index 000000000..0cd47fb43
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/commands.rs
@@ -0,0 +1,52 @@
+use serde::{Deserialize, Serialize};
+
+use crate::domain::normalize_id;
+use crate::errors::GameDistributionFieldError;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IdempotencyRequest {
+    pub key: String,
+    pub request_digest: String,
+}
+
+impl IdempotencyRequest {
+    pub fn validate(&self) -> Result<(), GameDistributionFieldError> {
+        if normalize_id(&self.key).is_none() {
+            return Err(GameDistributionFieldError::MissingIdempotencyKey);
+        }
+        if normalize_id(&self.request_digest).is_none() {
+            return Err(GameDistributionFieldError::MissingRequestDigest);
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CreateGameInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub idempotency: IdempotencyRequest,
+    pub created_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CreateVersionInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_id: String,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub idempotency: IdempotencyRequest,
+    pub created_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ReviewDecision {
+    Approve {
+        expected_publication_revision: u64,
+    },
+    Reject {
+        expected_publication_revision: u64,
+        reason: String,
+    },
+}
diff --git a/server-rs/crates/module-game-distribution/src/domain.rs b/server-rs/crates/module-game-distribution/src/domain.rs
new file mode 100644
index 000000000..4607a2013
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/domain.rs
@@ -0,0 +1,115 @@
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use shared_kernel::{build_prefixed_seed_id, normalize_required_string};
+
+pub const GAME_ID_PREFIX: &str = "game_";
+pub const GAME_VERSION_ID_PREFIX: &str = "gamever_";
+
+pub fn generate_game_id(seed_micros: i64) -> String {
+    build_prefixed_seed_id(GAME_ID_PREFIX, seed_micros)
+}
+
+pub fn generate_game_version_id(seed_micros: i64, version_number: u64) -> String {
+    format!(
+        "{}{seed_micros:x}_{version_number:x}",
+        GAME_VERSION_ID_PREFIX
+    )
+}
+
+/// Computes the lowercase SHA-256 digest used by the idempotency contract.
+pub fn compute_request_digest(payload: impl AsRef<[u8]>) -> String {
+    let digest = Sha256::digest(payload.as_ref());
+    hex::encode(digest)
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum GameVisibility {
+    Unpublished,
+    Published,
+    Suspended,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum GameVersionStatus {
+    AwaitingUpload,
+    Uploaded,
+    Validating,
+    PendingReview,
+    Published,
+    UploadFailed,
+    ValidationFailed,
+    Rejected,
+    Cancelled,
+    Revoked,
+}
+
+impl GameVersionStatus {
+    pub fn is_terminal(self) -> bool {
+        matches!(
+            self,
+            Self::Published
+                | Self::UploadFailed
+                | Self::ValidationFailed
+                | Self::Rejected
+                | Self::Cancelled
+                | Self::Revoked
+        )
+    }
+
+    pub fn can_cancel(self) -> bool {
+        matches!(
+            self,
+            Self::AwaitingUpload
+                | Self::Uploaded
+                | Self::Validating
+                | Self::PendingReview
+                | Self::UploadFailed
+                | Self::ValidationFailed
+        )
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct GameSnapshot {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub publication_revision: u64,
+    pub active_version_id: Option<String>,
+    pub visibility: GameVisibility,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct GameVersionSnapshot {
+    pub version_id: String,
+    pub game_id: String,
+    pub version_number: u64,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub status: GameVersionStatus,
+    pub review_reason: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum GameDistributionAction {
+    CreateGame,
+    CreateVersion,
+    ConfirmPackage,
+    FailUpload,
+    SubmitVersion,
+    PassValidation,
+    FailValidation,
+    CancelVersion,
+    ApproveVersion,
+    RejectVersion,
+    UnpublishGame,
+    SuspendGame,
+}
+
+pub(crate) fn normalize_id(value: impl AsRef<str>) -> Option<String> {
+    normalize_required_string(value)
+}
diff --git a/server-rs/crates/module-game-distribution/src/errors.rs b/server-rs/crates/module-game-distribution/src/errors.rs
new file mode 100644
index 000000000..e3cb17a65
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/errors.rs
@@ -0,0 +1,105 @@
+use std::{error::Error, fmt};
+
+use crate::{GameVersionStatus, GameVisibility};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum GameDistributionFieldError {
+    MissingGameId,
+    MissingVersionId,
+    MissingOwnerUserId,
+    MissingActorUserId,
+    MissingIdempotencyKey,
+    MissingRequestDigest,
+    InvalidPackageDigest,
+    InvalidPackageBytes,
+    MissingReviewReason,
+}
+
+impl fmt::Display for GameDistributionFieldError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::MissingGameId => "gameId 不能为空",
+            Self::MissingVersionId => "versionId 不能为空",
+            Self::MissingOwnerUserId => "ownerUserId 不能为空",
+            Self::MissingActorUserId => "actorUserId 不能为空",
+            Self::MissingIdempotencyKey => "Idempotency-Key 不能为空",
+            Self::MissingRequestDigest => "request digest 不能为空",
+            Self::InvalidPackageDigest => "packageSha256 必须是 64 位十六进制摘要",
+            Self::InvalidPackageBytes => "packageBytes 必须大于 0",
+            Self::MissingReviewReason => "拒绝审核必须提供理由",
+        };
+        formatter.write_str(message)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum GameDistributionError {
+    Field(GameDistributionFieldError),
+    GameNotFound,
+    VersionNotFound,
+    GameAlreadyExists,
+    VersionAlreadyExists,
+    Forbidden,
+    IdempotencyConflict,
+    IdempotencyOutcomeMismatch,
+    InvalidVersionTransition {
+        from: GameVersionStatus,
+        to: GameVersionStatus,
+    },
+    PublicationConflict {
+        expected: u64,
+        actual: u64,
+    },
+    PackageMismatch,
+    GameSuspended,
+    GameNotPublished,
+    VersionNotPublished,
+    VersionAlreadyPublished,
+    ReviewActionNotAllowed,
+}
+
+impl fmt::Display for GameDistributionError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Field(field) => field.fmt(formatter),
+            Self::GameNotFound => formatter.write_str("游戏不存在"),
+            Self::VersionNotFound => formatter.write_str("游戏版本不存在"),
+            Self::GameAlreadyExists => formatter.write_str("游戏已存在"),
+            Self::VersionAlreadyExists => formatter.write_str("游戏版本已存在"),
+            Self::Forbidden => formatter.write_str("无权操作该游戏"),
+            Self::IdempotencyConflict => formatter.write_str("幂等键对应的请求摘要不一致"),
+            Self::IdempotencyOutcomeMismatch => formatter.write_str("幂等记录结果类型不一致"),
+            Self::InvalidVersionTransition { from, to } => {
+                write!(formatter, "版本状态不能从 {from:?} 变为 {to:?}")
+            }
+            Self::PublicationConflict { expected, actual } => {
+                write!(
+                    formatter,
+                    "公开状态版本冲突：期望 {expected}，实际 {actual}"
+                )
+            }
+            Self::PackageMismatch => formatter.write_str("发行包摘要或字节数与版本声明不一致"),
+            Self::GameSuspended => formatter.write_str("游戏已被管理员下架"),
+            Self::GameNotPublished => formatter.write_str("游戏当前未公开"),
+            Self::VersionNotPublished => formatter.write_str("游戏版本当前未公开"),
+            Self::VersionAlreadyPublished => formatter.write_str("游戏版本已经公开"),
+            Self::ReviewActionNotAllowed => formatter.write_str("当前版本不允许审核操作"),
+        }
+    }
+}
+
+impl Error for GameDistributionError {}
+
+impl From<GameDistributionFieldError> for GameDistributionError {
+    fn from(value: GameDistributionFieldError) -> Self {
+        Self::Field(value)
+    }
+}
+
+#[allow(dead_code)]
+fn _visibility_is_exhaustive(visibility: GameVisibility) -> bool {
+    matches!(
+        visibility,
+        GameVisibility::Unpublished | GameVisibility::Published | GameVisibility::Suspended
+    )
+}
diff --git a/server-rs/crates/module-game-distribution/src/events.rs b/server-rs/crates/module-game-distribution/src/events.rs
new file mode 100644
index 000000000..eebdb8406
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/events.rs
@@ -0,0 +1,21 @@
+//! 游戏分发领域事件类型预留。
+//!
+//! 当前阶段的持久化 procedure 直接返回版本/游戏快照；审核和公开切换事件在
+//! 后续人工审核里程碑接入事件审计前，先保留明确的领域落位，避免把事件规则
+//! 下沉到 api-server。
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum GameDistributionEvent {
+    GameCreated {
+        game_id: String,
+        owner_user_id: String,
+    },
+    VersionCreated {
+        game_id: String,
+        version_id: String,
+    },
+    PackageConfirmed {
+        version_id: String,
+        package_sha256: String,
+    },
+}
diff --git a/server-rs/crates/module-game-distribution/src/lib.rs b/server-rs/crates/module-game-distribution/src/lib.rs
new file mode 100644
index 000000000..15b9d726e
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/lib.rs
@@ -0,0 +1,27 @@
+mod application;
+mod commands;
+mod domain;
+mod errors;
+mod events;
+mod package;
+mod release;
+
+pub use application::{
+    GameDistributionService, GameOperationResult, InMemoryGameDistributionStore,
+    PublicationOperationResult,
+};
+pub use commands::{CreateGameInput, CreateVersionInput, IdempotencyRequest, ReviewDecision};
+pub use domain::{
+    GameDistributionAction, GameSnapshot, GameVersionSnapshot, GameVersionStatus, GameVisibility,
+    compute_request_digest, generate_game_id, generate_game_version_id,
+};
+pub use errors::{GameDistributionError, GameDistributionFieldError};
+pub use events::GameDistributionEvent;
+pub use package::{
+    MAX_COMPRESSION_RATIO, MAX_EXPANDED_BYTES, MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_PACKAGE_BYTES,
+    ReleaseFileManifest, ReleasePackageError, ReleasePackageManifest, validate_release_zip,
+};
+pub use release::{
+    MAX_RELEASE_ASSET_BYTES, ReleaseAssetError, extract_release_asset,
+    normalize_release_asset_path, release_asset_content_type,
+};
diff --git a/server-rs/crates/module-game-distribution/src/package.rs b/server-rs/crates/module-game-distribution/src/package.rs
new file mode 100644
index 000000000..5e8faf9f5
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/package.rs
@@ -0,0 +1,225 @@
+use std::{
+    collections::HashSet,
+    io::{Cursor, Read},
+    path::Path,
+};
+
+use sha2::{Digest, Sha256};
+
+pub const MAX_PACKAGE_BYTES: u64 = 100 * 1024 * 1024;
+pub const MAX_EXPANDED_BYTES: u64 = 250 * 1024 * 1024;
+pub const MAX_FILE_BYTES: u64 = 64 * 1024 * 1024;
+pub const MAX_FILE_COUNT: usize = 10_000;
+pub const MAX_COMPRESSION_RATIO: u64 = 100;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ReleaseFileManifest {
+    pub path: String,
+    pub size_bytes: u64,
+    pub sha256: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ReleasePackageManifest {
+    pub package_bytes: u64,
+    pub package_sha256: String,
+    pub files: Vec<ReleaseFileManifest>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ReleasePackageError {
+    EmptyPackage,
+    PackageTooLarge,
+    InvalidArchive,
+    MissingEntry,
+    TooManyFiles,
+    InvalidPath,
+    SymlinkNotAllowed,
+    EncryptedFileNotAllowed,
+    SensitiveFileNotAllowed,
+    NestedArchiveNotAllowed,
+    FileTooLarge,
+    ExpandedPackageTooLarge,
+    CompressionRatioTooHigh,
+    ReadFailed,
+}
+
+pub fn validate_release_zip(bytes: &[u8]) -> Result<ReleasePackageManifest, ReleasePackageError> {
+    if bytes.is_empty() {
+        return Err(ReleasePackageError::EmptyPackage);
+    }
+    let package_bytes = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
+    if package_bytes > MAX_PACKAGE_BYTES {
+        return Err(ReleasePackageError::PackageTooLarge);
+    }
+
+    let mut archive = zip::ZipArchive::new(Cursor::new(bytes))
+        .map_err(|_| ReleasePackageError::InvalidArchive)?;
+    if archive.len() > MAX_FILE_COUNT {
+        return Err(ReleasePackageError::TooManyFiles);
+    }
+
+    let mut paths = HashSet::with_capacity(archive.len());
+    let mut case_folded_paths = HashSet::with_capacity(archive.len());
+    let mut files = Vec::with_capacity(archive.len());
+    let mut expanded_bytes = 0_u64;
+    let mut has_entry = false;
+    for index in 0..archive.len() {
+        let mut file = archive
+            .by_index(index)
+            .map_err(|_| ReleasePackageError::InvalidArchive)?;
+        if file.encrypted() {
+            return Err(ReleasePackageError::EncryptedFileNotAllowed);
+        }
+        if file.is_symlink() {
+            return Err(ReleasePackageError::SymlinkNotAllowed);
+        }
+        let path = file
+            .enclosed_name()
+            .ok_or(ReleasePackageError::InvalidPath)?;
+        let path = normalize_archive_path(&path)?;
+        if !paths.insert(path.clone()) || !case_folded_paths.insert(path.to_ascii_lowercase()) {
+            return Err(ReleasePackageError::InvalidPath);
+        }
+        if path == "index.html" {
+            has_entry = true;
+        }
+        if is_sensitive_path(&path) {
+            return Err(ReleasePackageError::SensitiveFileNotAllowed);
+        }
+        if path.to_ascii_lowercase().ends_with(".zip") {
+            return Err(ReleasePackageError::NestedArchiveNotAllowed);
+        }
+        if file.is_dir() {
+            continue;
+        }
+        let declared_size = file.size();
+        if declared_size > MAX_FILE_BYTES {
+            return Err(ReleasePackageError::FileTooLarge);
+        }
+        expanded_bytes = expanded_bytes.saturating_add(declared_size);
+        if expanded_bytes > MAX_EXPANDED_BYTES {
+            return Err(ReleasePackageError::ExpandedPackageTooLarge);
+        }
+        if declared_size > package_bytes.saturating_mul(MAX_COMPRESSION_RATIO) {
+            return Err(ReleasePackageError::CompressionRatioTooHigh);
+        }
+
+        let mut content = Vec::with_capacity(usize::try_from(declared_size).unwrap_or(0));
+        file.read_to_end(&mut content)
+            .map_err(|_| ReleasePackageError::ReadFailed)?;
+        if u64::try_from(content.len()).unwrap_or(u64::MAX) != declared_size {
+            return Err(ReleasePackageError::ReadFailed);
+        }
+        let digest = Sha256::digest(&content);
+        files.push(ReleaseFileManifest {
+            path,
+            size_bytes: declared_size,
+            sha256: hex::encode(digest),
+        });
+    }
+    if !has_entry {
+        return Err(ReleasePackageError::MissingEntry);
+    }
+
+    let package_digest = Sha256::digest(bytes);
+    Ok(ReleasePackageManifest {
+        package_bytes,
+        package_sha256: hex::encode(package_digest),
+        files,
+    })
+}
+
+pub(crate) fn normalize_archive_path(path: &Path) -> Result<String, ReleasePackageError> {
+    let path = path
+        .to_str()
+        .ok_or(ReleasePackageError::InvalidPath)?
+        .trim_end_matches('/');
+    if path.is_empty() || path.contains('\\') || path.starts_with('/') {
+        return Err(ReleasePackageError::InvalidPath);
+    }
+    let mut parts = Vec::new();
+    for part in path.split('/') {
+        if part.is_empty()
+            || part == "."
+            || part == ".."
+            || part.ends_with(' ')
+            || part.ends_with('.')
+            || part
+                .chars()
+                .any(|character| matches!(character, ':' | '<' | '>' | '"' | '|' | '?' | '*'))
+        {
+            return Err(ReleasePackageError::InvalidPath);
+        }
+        parts.push(part);
+    }
+    Ok(parts.join("/"))
+}
+
+fn is_sensitive_path(path: &str) -> bool {
+    path.split('/').any(|part| {
+        matches!(part, ".git" | ".agent" | "node_modules")
+            || part.starts_with(".env")
+            || part.ends_with(".map")
+            || part.ends_with(".pem")
+            || part.ends_with(".key")
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::Write;
+
+    use zip::{ZipWriter, write::SimpleFileOptions};
+
+    use super::*;
+
+    fn archive(files: &[(&str, &[u8])]) -> Vec<u8> {
+        let mut output = Cursor::new(Vec::new());
+        let mut writer = ZipWriter::new(&mut output);
+        for (path, content) in files {
+            writer
+                .start_file(*path, SimpleFileOptions::default())
+                .expect("zip entry");
+            writer.write_all(content).expect("zip content");
+        }
+        writer.finish().expect("finish zip");
+        output.into_inner()
+    }
+
+    #[test]
+    fn accepts_root_entry_and_returns_file_manifest() {
+        let bytes = archive(&[("index.html", b"<html></html>"), ("assets/a.txt", b"a")]);
+        let manifest = validate_release_zip(&bytes).expect("valid archive");
+        assert_eq!(manifest.files.len(), 2);
+        assert_eq!(manifest.files[0].path, "index.html");
+    }
+
+    #[test]
+    fn rejects_missing_entry_sensitive_and_traversal_paths() {
+        let missing = archive(&[("game.html", b"x")]);
+        assert_eq!(
+            validate_release_zip(&missing),
+            Err(ReleasePackageError::MissingEntry)
+        );
+        let sensitive = archive(&[("index.html", b"x"), (".env", b"secret")]);
+        assert_eq!(
+            validate_release_zip(&sensitive),
+            Err(ReleasePackageError::SensitiveFileNotAllowed)
+        );
+        let traversal = archive(&[("index.html", b"x"), ("../escape.txt", b"x")]);
+        assert_eq!(
+            validate_release_zip(&traversal),
+            Err(ReleasePackageError::InvalidPath)
+        );
+        let case_collision = archive(&[
+            ("index.html", b"x"),
+            ("ASSETS/a.txt", b"x"),
+            ("assets/A.txt", b"x"),
+        ]);
+        assert_eq!(
+            validate_release_zip(&case_collision),
+            Err(ReleasePackageError::InvalidPath)
+        );
+    }
+}
diff --git a/server-rs/crates/module-game-distribution/src/release.rs b/server-rs/crates/module-game-distribution/src/release.rs
new file mode 100644
index 000000000..4cfdd7d29
--- /dev/null
+++ b/server-rs/crates/module-game-distribution/src/release.rs
@@ -0,0 +1,179 @@
+use std::io::{Cursor, Read};
+
+use crate::package::{MAX_FILE_BYTES, normalize_archive_path};
+
+/// 单次发行资源响应的字节上限，与单文件上限同口径。
+pub const MAX_RELEASE_ASSET_BYTES: u64 = MAX_FILE_BYTES;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ReleaseAssetError {
+    InvalidPath,
+    NotInPackage,
+    FileTooLarge,
+    InvalidArchive,
+    ReadFailed,
+}
+
+/// 归一化发行资源路径。
+///
+/// 路径来自公开 URL，必须在查表前完成归一化并拒绝相对段、控制字符和 Windows
+/// 保留字符，不能依赖 ZIP 条目的原始写法。
+pub fn normalize_release_asset_path(raw: &str) -> Result<String, ReleaseAssetError> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() || trimmed.len() > 1024 {
+        return Err(ReleaseAssetError::InvalidPath);
+    }
+    if trimmed.contains('\\') || trimmed.starts_with('/') || trimmed.contains('\0') {
+        return Err(ReleaseAssetError::InvalidPath);
+    }
+    normalize_archive_path(std::path::Path::new(trimmed))
+        .map_err(|_| ReleaseAssetError::InvalidPath)
+}
+
+/// 发行资源的响应内容类型白名单。
+///
+/// 未知扩展名返回 `None` 并让调用方失败关闭，避免把未知内容当作 HTML 返回。
+pub fn release_asset_content_type(path: &str) -> Option<&'static str> {
+    let extension = path.rsplit_once('.').map(|(_, value)| value)?;
+    let extension = extension.to_ascii_lowercase();
+    Some(match extension.as_str() {
+        "html" | "htm" => "text/html; charset=utf-8",
+        "js" | "mjs" => "text/javascript; charset=utf-8",
+        "css" => "text/css; charset=utf-8",
+        "json" => "application/json; charset=utf-8",
+        "wasm" => "application/wasm",
+        "svg" => "image/svg+xml",
+        "png" => "image/png",
+        "jpg" | "jpeg" => "image/jpeg",
+        "webp" => "image/webp",
+        "gif" => "image/gif",
+        "avif" => "image/avif",
+        "ico" => "image/x-icon",
+        "mp3" => "audio/mpeg",
+        "ogg" => "audio/ogg",
+        "wav" => "audio/wav",
+        "m4a" => "audio/mp4",
+        "mp4" => "video/mp4",
+        "webm" => "video/webm",
+        "woff" => "font/woff",
+        "woff2" => "font/woff2",
+        "ttf" => "font/ttf",
+        "otf" => "font/otf",
+        "txt" => "text/plain; charset=utf-8",
+        "xml" => "application/xml",
+        _ => return None,
+    })
+}
+
+/// 从已确认的发行包中取出单个资源。
+///
+/// 只按归一化后的精确路径命中，不做大小写折叠或前缀匹配，避免一个资源伪装成另一个。
+pub fn extract_release_asset(
+    package: &[u8],
+    asset_path: &str,
+) -> Result<Vec<u8>, ReleaseAssetError> {
+    let asset_path = normalize_release_asset_path(asset_path)?;
+    let mut archive = zip::ZipArchive::new(Cursor::new(package))
+        .map_err(|_| ReleaseAssetError::InvalidArchive)?;
+    for index in 0..archive.len() {
+        let mut file = archive
+            .by_index(index)
+            .map_err(|_| ReleaseAssetError::InvalidArchive)?;
+        if file.is_dir() || file.is_symlink() || file.encrypted() {
+            continue;
+        }
+        let Ok(candidate) =
+            normalize_archive_path(&file.enclosed_name().ok_or(ReleaseAssetError::InvalidPath)?)
+        else {
+            continue;
+        };
+        if candidate != asset_path {
+            continue;
+        }
+        let size = file.size();
+        if size > MAX_RELEASE_ASSET_BYTES {
+            return Err(ReleaseAssetError::FileTooLarge);
+        }
+        let mut content = Vec::with_capacity(usize::try_from(size).unwrap_or(0));
+        file.read_to_end(&mut content)
+            .map_err(|_| ReleaseAssetError::ReadFailed)?;
+        if u64::try_from(content.len()).unwrap_or(u64::MAX) != size {
+            return Err(ReleaseAssetError::ReadFailed);
+        }
+        return Ok(content);
+    }
+    Err(ReleaseAssetError::NotInPackage)
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::Write;
+
+    use zip::{ZipWriter, write::SimpleFileOptions};
+
+    use super::*;
+
+    fn archive(files: &[(&str, &[u8])]) -> Vec<u8> {
+        let mut output = Cursor::new(Vec::new());
+        let mut writer = ZipWriter::new(&mut output);
+        for (path, content) in files {
+            writer
+                .start_file(*path, SimpleFileOptions::default())
+                .expect("zip entry");
+            writer.write_all(content).expect("zip content");
+        }
+        writer.finish().expect("finish zip");
+        output.into_inner()
+    }
+
+    #[test]
+    fn content_type_allowlist_fails_closed_for_unknown_extensions() {
+        assert_eq!(
+            release_asset_content_type("index.html"),
+            Some("text/html; charset=utf-8")
+        );
+        assert_eq!(
+            release_asset_content_type("app.js"),
+            Some("text/javascript; charset=utf-8")
+        );
+        assert_eq!(release_asset_content_type("payload"), None);
+        assert_eq!(release_asset_content_type("evil.php"), None);
+    }
+
+    #[test]
+    fn asset_path_rejects_traversal_and_absolute_input() {
+        assert_eq!(
+            normalize_release_asset_path("../secret").expect_err("相对段应拒绝"),
+            ReleaseAssetError::InvalidPath
+        );
+        assert_eq!(
+            normalize_release_asset_path("/etc/passwd").expect_err("绝对路径应拒绝"),
+            ReleaseAssetError::InvalidPath
+        );
+        assert_eq!(
+            normalize_release_asset_path("assets/./a.png").expect_err("点段应拒绝"),
+            ReleaseAssetError::InvalidPath
+        );
+        assert_eq!(
+            normalize_release_asset_path("assets/app.js").expect("合法路径"),
+            "assets/app.js"
+        );
+    }
+
+    #[test]
+    fn extraction_only_returns_the_exact_declared_entry() {
+        let bytes = archive(&[("index.html", b"<html></html>"), ("assets/app.js", b"1")]);
+        assert_eq!(
+            extract_release_asset(&bytes, "assets/app.js").expect("命中"),
+            b"1".to_vec()
+        );
+        assert_eq!(
+            extract_release_asset(&bytes, "assets/./app.js").expect_err("归一化后拒绝"),
+            ReleaseAssetError::InvalidPath
+        );
+        assert_eq!(
+            extract_release_asset(&bytes, "assets/missing.js").expect_err("未命中"),
+            ReleaseAssetError::NotInPackage
+        );
+    }
+}
diff --git a/server-rs/crates/module-runtime/src/application.rs b/server-rs/crates/module-runtime/src/application.rs
index bf3e51bb1..e7f1ead08 100644
--- a/server-rs/crates/module-runtime/src/application.rs
+++ b/server-rs/crates/module-runtime/src/application.rs
@@ -84,6 +84,9 @@ pub fn creation_entry_feature_gate_key(creation_type_id: &str) -> String {
 
 pub const IMAGE_EDITOR_AGENT_SIDEBAR_GATE_KEY: &str = "image-editor:agent-sidebar";
 pub const AGC_TEMPLATE_LIBRARY_GATE_KEY: &str = "agc:template-library";
+/// 游戏分发写入开关：gate 行缺失或 `enabled=false` 时默认开放；`enabled=true` 时
+/// 只有白名单/灰度命中的用户能发布新版本（`rollout_percent=0` 且无白名单即全部关闭）。
+pub const GAME_DISTRIBUTION_PUBLISH_GATE_KEY: &str = "game-distribution:publish";
 
 #[cfg(any())]
 pub fn apply_feature_gates_to_creation_entry_config(
diff --git a/server-rs/crates/platform-oss/src/client_downloads.rs b/server-rs/crates/platform-oss/src/client_downloads.rs
index d8476fc44..b9bc5f0aa 100644
--- a/server-rs/crates/platform-oss/src/client_downloads.rs
+++ b/server-rs/crates/platform-oss/src/client_downloads.rs
@@ -304,7 +304,8 @@ fn has_safe_percent_encoding(file_name: &str) -> bool {
         let Ok(byte) = u8::from_str_radix(hex, 16) else {
             return false;
         };
-        if byte <= b' ' || matches!(byte, b'/' | b'\\' | 127) {
+        // 渠道安装身份可以包含空格，OSS 清单中的文件名会将空格编码为 `%20`。
+        if byte < b' ' || matches!(byte, b'/' | b'\\' | 127) {
             return false;
         }
         remaining = &encoded[2..];
@@ -541,6 +542,29 @@ mod tests {
         }
     }
 
+    #[test]
+    fn percent_encoded_spaces_in_release_installer_names_are_allowed() {
+        let version = "0.1.110";
+        let installer = download_url(
+            DownloadPlatform::Windows,
+            version,
+            "%E9%99%B6%E6%B3%A5%E5%84%BF%20Release_0.1.110_x64-setup.exe",
+        )
+        .replace("/dev-win/", "/release-win/");
+        let manifest = manifest_with_downloads(
+            version,
+            json!({
+                "windows-x86_64": { "url": installer }
+            }),
+        );
+
+        let parsed =
+            super::parse_manifest(&manifest, DownloadPlatform::Windows, "release").unwrap();
+
+        assert_eq!(parsed.len(), 1);
+        assert_eq!(parsed[0].download_url, installer);
+    }
+
     #[test]
     fn macos_requires_explicit_dmg_metadata_and_preserves_available_architectures() {
         let updater_only = json!({
diff --git a/server-rs/crates/platform-oss/src/lib.rs b/server-rs/crates/platform-oss/src/lib.rs
index 61b6cc213..32b3d02f6 100644
--- a/server-rs/crates/platform-oss/src/lib.rs
+++ b/server-rs/crates/platform-oss/src/lib.rs
@@ -953,14 +953,87 @@ impl OssClient {
         client: &reqwest::Client,
         request: OssInternalPutObjectRequest,
     ) -> Result<OssPutObjectResponse, OssError> {
+        let object_key = normalize_internal_object_key(&request.object_key)?;
+        self.put_internal_object_bytes(
+            client,
+            object_key,
+            request.content_type,
+            request.access,
+            request.metadata,
+            Bytes::from(request.body),
+        )
+        .await
+    }
+
+    /// 内部对象 PUT 的受控重试：只重试可判定的传输/超时/408/429/5xx，body 只复制一次
+    /// 到引用计数的 `Bytes`，每次 attempt 复用同一份字节。
+    ///
+    /// `max_attempts` 至少为 1，`retry_delays_ms` 至少提供 `max_attempts - 1` 个退避值；
+    /// 参数不满足时按配置错误失败关闭，不静默降级成单次请求。
+    pub async fn put_internal_object_with_retry(
+        &self,
+        client: &reqwest::Client,
+        request: OssInternalPutObjectRequest,
+        max_attempts: usize,
+        retry_delays_ms: &[u64],
+    ) -> Result<OssPutObjectResponse, OssError> {
+        if max_attempts == 0 {
+            return Err(OssError::InvalidConfig(
+                "内部对象 PUT 重试次数至少为 1".to_string(),
+            ));
+        }
+        if retry_delays_ms.len() < max_attempts.saturating_sub(1) {
+            return Err(OssError::InvalidConfig(
+                "内部对象 PUT 重试缺少退避配置".to_string(),
+            ));
+        }
         let object_key = normalize_internal_object_key(&request.object_key)?;
         if request.body.is_empty() && !project_snapshots::is_snapshot_file_key(&object_key) {
             return Err(OssError::InvalidRequest(
                 "服务端内部对象内容不能为空".to_string(),
             ));
         }
-        let content_type = normalize_optional_value(request.content_type);
-        let headers = build_put_object_headers(request.metadata)?;
+        let content_type = request.content_type;
+        let access = request.access;
+        let metadata = request.metadata;
+        let body = Bytes::from(request.body);
+        let retry_log_key = object_key.clone();
+        run_internal_put_with_retry(max_attempts, retry_delays_ms, &retry_log_key, move || {
+            let object_key = object_key.clone();
+            let content_type = content_type.clone();
+            let metadata = metadata.clone();
+            let body = body.clone();
+            async move {
+                self.put_internal_object_bytes(
+                    client,
+                    object_key,
+                    content_type,
+                    access,
+                    metadata,
+                    body,
+                )
+                .await
+            }
+        })
+        .await
+    }
+
+    async fn put_internal_object_bytes(
+        &self,
+        client: &reqwest::Client,
+        object_key: String,
+        content_type: Option<String>,
+        access: OssObjectAccess,
+        metadata: BTreeMap<String, String>,
+        body: Bytes,
+    ) -> Result<OssPutObjectResponse, OssError> {
+        if body.is_empty() && !project_snapshots::is_snapshot_file_key(&object_key) {
+            return Err(OssError::InvalidRequest(
+                "服务端内部对象内容不能为空".to_string(),
+            ));
+        }
+        let content_type = normalize_optional_value(content_type);
+        let headers = build_put_object_headers(metadata)?;
         let target_url = build_object_url(&self.config.bucket, &self.config.endpoint, &object_key)
             .map_err(|error| {
                 request_error(
@@ -968,7 +1041,7 @@ impl OssClient {
                     &format!("构造 OSS 对象 URL 失败：{error}"),
                 )
             })?;
-        let content_length = u64::try_from(request.body.len())
+        let content_length = u64::try_from(body.len())
             .map_err(|_| OssError::InvalidRequest("上传对象大小超出可支持范围".to_string()))?;
         let builder = signed_request_builder(
             client,
@@ -980,7 +1053,7 @@ impl OssClient {
             &headers,
         )?
         .header(reqwest::header::CONTENT_LENGTH, content_length)
-        .body(request.body);
+        .body(body);
         let response = builder
             .send()
             .await
@@ -1010,7 +1083,7 @@ impl OssClient {
             object_key,
             content_type,
             content_length,
-            access: request.access,
+            access,
             etag,
             last_modified,
         })
@@ -1608,6 +1681,45 @@ where
     unreachable!("角色动画 OSS 重试循环必须返回结果")
 }
 
+/// 内部对象 PUT 的重试循环。判定与退避规则集中在 `oss_error_is_retryable`：
+/// 传输/超时/connect、408、429、5xx 以及 400+RequestTimeout 可重试，确定性 4xx 直接失败。
+async fn run_internal_put_with_retry<T, F, Fut>(
+    max_attempts: usize,
+    retry_delays_ms: &[u64],
+    object_key: &str,
+    mut attempt_request: F,
+) -> Result<T, OssError>
+where
+    F: FnMut() -> Fut,
+    Fut: Future<Output = Result<T, OssError>>,
+{
+    let mut attempt = 1_usize;
+    let mut retry_index = 0_usize;
+    loop {
+        let result = attempt_request().await;
+        let retryable = result.as_ref().err().is_some_and(oss_error_is_retryable);
+        let will_retry = retryable && attempt < max_attempts;
+        match result {
+            Ok(response) => return Ok(response),
+            Err(error) if will_retry => {
+                let delay_ms = retry_delays_ms[retry_index];
+                warn!(
+                    object_key = %object_key,
+                    attempt,
+                    max_attempts,
+                    retry_delay_ms = delay_ms,
+                    error = %error,
+                    "OSS 内部对象 PUT 失败，按退避重试"
+                );
+                sleep(std::time::Duration::from_millis(delay_ms)).await;
+                attempt += 1;
+                retry_index += 1;
+            }
+            Err(error) => return Err(error),
+        }
+    }
+}
+
 fn request_error_from_reqwest(operation: OssRequestOperation, error: reqwest::Error) -> OssError {
     let status = error.status().map(|status| status.as_u16());
     let timeout = error.is_timeout();
@@ -2903,6 +3015,86 @@ mod tests {
         assert!(!oss_error_is_retryable(&error));
     }
 
+    #[tokio::test]
+    async fn internal_put_retry_retries_transport_then_succeeds() {
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let attempts_for_request = attempts.clone();
+        let result = run_internal_put_with_retry(
+            3,
+            &[1, 1],
+            "agc/project-snapshots/v1/game-distribution/game_1/gamever_1.zip",
+            move || {
+                let attempts = attempts_for_request.clone();
+                async move {
+                    if attempts.fetch_add(1, Ordering::SeqCst) == 0 {
+                        Err(retryable_request_error(None, false, false, true))
+                    } else {
+                        Ok("uploaded")
+                    }
+                }
+            },
+        )
+        .await;
+
+        assert_eq!(result.expect("第二次尝试应成功"), "uploaded");
+        assert_eq!(attempts.load(Ordering::SeqCst), 2);
+    }
+
+    #[tokio::test]
+    async fn internal_put_retry_stops_on_deterministic_statuses() {
+        for status in [400_u16, 401, 403, 404] {
+            let attempts = Arc::new(AtomicUsize::new(0));
+            let attempts_for_request = attempts.clone();
+            let error = run_internal_put_with_retry::<(), _, _>(
+                3,
+                &[1, 1],
+                "agc/project-snapshots/v1/game-distribution/game_1/gamever_1.zip",
+                move || {
+                    let attempts = attempts_for_request.clone();
+                    async move {
+                        attempts.fetch_add(1, Ordering::SeqCst);
+                        Err::<(), _>(retryable_request_error(Some(status), false, false, false))
+                    }
+                },
+            )
+            .await
+            .expect_err("确定性状态码不应重试");
+
+            assert_eq!(error.kind(), OssErrorKind::Request);
+            assert_eq!(
+                attempts.load(Ordering::SeqCst),
+                1,
+                "status={status} 必须只尝试一次"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn internal_put_retry_returns_last_error_after_budget() {
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let attempts_for_request = attempts.clone();
+        let error = run_internal_put_with_retry::<(), _, _>(
+            3,
+            &[1, 1],
+            "agc/project-snapshots/v1/game-distribution/game_1/gamever_1.zip",
+            move || {
+                let attempts = attempts_for_request.clone();
+                async move {
+                    attempts.fetch_add(1, Ordering::SeqCst);
+                    Err::<(), _>(retryable_request_error(Some(503), false, false, false))
+                }
+            },
+        )
+        .await
+        .expect_err("重试用尽后必须返回最后一次错误");
+
+        assert_eq!(attempts.load(Ordering::SeqCst), 3);
+        let OssError::Request(request_error) = &error else {
+            panic!("应保留 OSS 请求错误");
+        };
+        assert_eq!(request_error.status, Some(503));
+    }
+
     #[tokio::test]
     async fn animation_retry_retries_transport_then_succeeds() {
         let attempts = Arc::new(AtomicUsize::new(0));
diff --git a/server-rs/crates/shared-contracts/src/game_distribution.rs b/server-rs/crates/shared-contracts/src/game_distribution.rs
new file mode 100644
index 000000000..c9ef77987
--- /dev/null
+++ b/server-rs/crates/shared-contracts/src/game_distribution.rs
@@ -0,0 +1,216 @@
+//! 游戏分发 API 的跨端 DTO。
+//!
+//! 领域状态机位于 `module-game-distribution`；本文件只描述 HTTP/客户端可见的
+//! 数据形状，不能承载 owner、审核或公开切换规则。
+
+use serde::{Deserialize, Serialize};
+
+pub const GAME_DISTRIBUTION_CATEGORIES: [&str; 7] =
+    ["休闲", "益智", "动作", "冒险", "模拟", "策略", "其他"];
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GameDistributionVersionStatus {
+    AwaitingUpload,
+    Uploaded,
+    Validating,
+    PendingReview,
+    Published,
+    UploadFailed,
+    ValidationFailed,
+    Rejected,
+    Cancelled,
+    Revoked,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GameDistributionVisibility {
+    Unpublished,
+    Published,
+    Suspended,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GameDistributionInputMode {
+    Keyboard,
+    Mouse,
+    Touch,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GameDistributionOrientation {
+    Landscape,
+    Portrait,
+    Responsive,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionDeviceSupport {
+    pub desktop: bool,
+    pub mobile: bool,
+    pub touch: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionAuthor {
+    pub id: String,
+    pub name: String,
+    #[serde(default)]
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionVersionSummary {
+    pub id: String,
+    pub version: String,
+    pub entry_url: String,
+    pub sha256: String,
+    pub published_at: String,
+    pub controls: Vec<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionGameSummary {
+    pub id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: String,
+    pub category: String,
+    pub tags: Vec<String>,
+    pub cover_color: String,
+    pub icon: String,
+    pub author: GameDistributionAuthor,
+    pub device_support: GameDistributionDeviceSupport,
+    #[serde(default)]
+    pub input_modes: Vec<GameDistributionInputMode>,
+    #[serde(default)]
+    pub orientation: Option<GameDistributionOrientation>,
+    pub status: GameDistributionVisibility,
+    pub current_version: Option<GameDistributionVersionSummary>,
+    pub play_count: u64,
+    pub created_at: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionListResponse {
+    pub games: Vec<GameDistributionGameSummary>,
+    #[serde(default)]
+    pub next_cursor: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionCreateGameRequest {
+    #[serde(default)]
+    pub local_project_id: Option<String>,
+    pub title: String,
+    pub summary: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    pub category: String,
+    #[serde(default)]
+    pub tags: Vec<String>,
+    #[serde(default)]
+    pub cover_asset_id: Option<String>,
+    /// 截图素材 ID（最多 6 张，复用平台图片上传与归属校验）。
+    #[serde(default)]
+    pub screenshots: Vec<String>,
+    pub device_support: GameDistributionDeviceSupport,
+    pub input_modes: Vec<GameDistributionInputMode>,
+    pub orientation: GameDistributionOrientation,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionCreateVersionRequest {
+    #[serde(default)]
+    pub local_project_id: Option<String>,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub game_metadata: GameDistributionCreateGameRequest,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameDistributionPrivateVersion {
+    pub version_id: String,
+    pub game_id: String,
+    pub version_number: u64,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub status: GameDistributionVersionStatus,
+    #[serde(default)]
+    pub review_reason: Option<String>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn create_game_request_round_trips_local_project_id() {
+        let payload: GameDistributionCreateGameRequest =
+            serde_json::from_value(serde_json::json!({
+                "localProjectId": "proj-1",
+                "title": "游戏",
+                "summary": "简介",
+                "category": "益智",
+                "deviceSupport": { "desktop": true, "mobile": false, "touch": false },
+                "inputModes": ["keyboard"],
+                "orientation": "responsive",
+            }))
+            .expect("请求应可解析");
+        assert_eq!(payload.local_project_id.as_deref(), Some("proj-1"));
+        let serialized = serde_json::to_value(&payload).expect("请求应可序列化");
+        assert_eq!(serialized["localProjectId"], "proj-1");
+    }
+
+    #[test]
+    fn legacy_create_game_request_without_local_project_id_stays_compatible() {
+        let payload: GameDistributionCreateGameRequest =
+            serde_json::from_value(serde_json::json!({
+                "title": "游戏",
+                "summary": "简介",
+                "category": "益智",
+                "deviceSupport": { "desktop": true, "mobile": false, "touch": false },
+                "inputModes": ["keyboard"],
+                "orientation": "responsive",
+            }))
+            .expect("旧请求应继续可解析");
+        assert_eq!(payload.local_project_id, None);
+    }
+
+    #[test]
+    fn create_version_request_accepts_local_project_id() {
+        let payload: GameDistributionCreateVersionRequest =
+            serde_json::from_value(serde_json::json!({
+                "localProjectId": "proj-1",
+                "packageSha256": "a".repeat(64),
+                "packageBytes": 10,
+                "packageFileCount": 1,
+                "packageEntryPath": "index.html",
+                "gameMetadata": {
+                    "title": "游戏",
+                    "summary": "简介",
+                    "category": "益智",
+                    "deviceSupport": { "desktop": true, "mobile": false, "touch": false },
+                    "inputModes": ["keyboard"],
+                    "orientation": "responsive",
+                },
+            }))
+            .expect("版本请求应可解析");
+        assert_eq!(payload.local_project_id.as_deref(), Some("proj-1"));
+    }
+}
diff --git a/server-rs/crates/shared-contracts/src/lib.rs b/server-rs/crates/shared-contracts/src/lib.rs
index b66e022ef..377e9d75f 100644
--- a/server-rs/crates/shared-contracts/src/lib.rs
+++ b/server-rs/crates/shared-contracts/src/lib.rs
@@ -32,6 +32,7 @@ pub use editor_generation::{
 };
 pub mod external_generation;
 pub mod game_creation_app;
+pub mod game_distribution;
 pub mod hyper3d;
 pub mod llm;
 #[cfg(any())]
diff --git a/server-rs/crates/spacetime-client/src/active.rs b/server-rs/crates/spacetime-client/src/active.rs
index eefb1d7a2..f53356bed 100644
--- a/server-rs/crates/spacetime-client/src/active.rs
+++ b/server-rs/crates/spacetime-client/src/active.rs
@@ -20,6 +20,16 @@ pub mod editor_project;
 #[path = "active/error_reports.rs"]
 mod error_reports;
 pub mod external_api_key;
+pub mod game_distribution;
+pub use game_distribution::{
+    GameDistributionApproveRecordInput, GameDistributionCancelVersionRecordInput,
+    GameDistributionConfirmPackageRecordInput, GameDistributionCreateGameRecordInput,
+    GameDistributionCreateVersionRecordInput, GameDistributionFailUploadRecordInput,
+    GameDistributionGetGameRecordInput, GameDistributionOwnerGameListRecordInput,
+    GameDistributionPublicGameListRecordInput, GameDistributionRejectRecordInput,
+    GameDistributionSubmitReviewRecordInput, GameDistributionSuspendRecordInput,
+    GameDistributionUnpublishRecordInput,
+};
 #[path = "active/external_generation.rs"]
 pub mod external_generation;
 pub mod llm_router_account;
diff --git a/server-rs/crates/spacetime-client/src/active/mapper.rs b/server-rs/crates/spacetime-client/src/active/mapper.rs
index 1f725e294..117980ebd 100644
--- a/server-rs/crates/spacetime-client/src/active/mapper.rs
+++ b/server-rs/crates/spacetime-client/src/active/mapper.rs
@@ -20,6 +20,8 @@ mod error_reports;
 mod external_api_key;
 #[path = "mapper/external_generation.rs"]
 mod external_generation;
+#[path = "mapper/game_distribution.rs"]
+mod game_distribution;
 #[path = "mapper/llm_router_account.rs"]
 pub(crate) mod llm_router_account;
 #[path = "mapper/runtime.rs"]
@@ -89,6 +91,10 @@ pub use self::external_generation::{
     ExternalGenerationJobSummaryListRecord, ExternalGenerationJobSummaryRecord,
     ExternalGenerationQueueStatsRecord,
 };
+pub use self::game_distribution::{
+    GameDistributionGameRecord, GameDistributionOwnerGameRecord, GameDistributionPublicGameRecord,
+    GameDistributionVersionRecord,
+};
 pub use self::llm_router_account::{LlmRouterAccountRecord, LlmRouterAccountUpsertRecordInput};
 pub use self::runtime::FeatureGateConfigRecord;
 
@@ -141,6 +147,11 @@ pub(crate) use self::external_generation::{
     map_external_generation_job_summary_procedure_result,
     map_external_generation_queue_stats_result,
 };
+pub(crate) use self::game_distribution::{
+    map_game_distribution_game_result, map_game_distribution_owner_game_list_result,
+    map_game_distribution_public_game_list_result, map_game_distribution_public_game_result,
+    map_game_distribution_review_list_result, map_game_distribution_version_result,
+};
 pub(crate) use self::runtime::{
     map_feature_gate_config_procedure_result, map_runtime_setting_procedure_result,
     map_runtime_tracking_event_batch_procedure_result, map_runtime_tracking_event_procedure_result,
diff --git a/server-rs/crates/spacetime-client/src/active/mapper/game_distribution.rs b/server-rs/crates/spacetime-client/src/active/mapper/game_distribution.rs
new file mode 100644
index 000000000..72d04d537
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/active/mapper/game_distribution.rs
@@ -0,0 +1,194 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct GameDistributionGameRecord {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: String,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub publication_revision: u64,
+    pub active_version_id: Option<String>,
+    pub visibility: String,
+    pub play_count: u64,
+    pub created_at: String,
+    pub updated_at: String,
+    pub cover_object_key: Option<String>,
+    pub screenshots_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct GameDistributionVersionRecord {
+    pub version_id: String,
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_number: u64,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub status: String,
+    pub review_reason: Option<String>,
+    pub entry_url: Option<String>,
+    pub publication_revision: u64,
+    pub created_at: String,
+    pub updated_at: String,
+    /// 创建版本时冻结的资料快照；历史版本可能为空，读取方必须容忍。
+    pub metadata_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct GameDistributionOwnerGameRecord {
+    pub game: GameDistributionGameRecord,
+    pub versions: Vec<GameDistributionVersionRecord>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct GameDistributionPublicGameRecord {
+    pub game: GameDistributionGameRecord,
+    pub current_version: Option<GameDistributionVersionRecord>,
+}
+
+fn map_game(
+    value: crate::module_bindings::GameDistributionGameSnapshot,
+) -> GameDistributionGameRecord {
+    GameDistributionGameRecord {
+        game_id: value.game_id,
+        owner_user_id: value.owner_user_id,
+        title: value.title,
+        summary: value.summary,
+        description: value.description,
+        category: value.category,
+        tags_json: value.tags_json,
+        cover_asset_id: value.cover_asset_id,
+        author_name: value.author_name,
+        author_avatar_url: value.author_avatar_url,
+        device_support_desktop: value.device_support_desktop,
+        device_support_mobile: value.device_support_mobile,
+        device_support_touch: value.device_support_touch,
+        input_modes_json: value.input_modes_json,
+        orientation: value.orientation,
+        publication_revision: value.publication_revision,
+        active_version_id: value.active_version_id,
+        visibility: value.visibility,
+        play_count: value.play_count,
+        created_at: shared_kernel::format_timestamp_micros(value.created_at_micros),
+        updated_at: shared_kernel::format_timestamp_micros(value.updated_at_micros),
+        cover_object_key: value.cover_object_key,
+        screenshots_json: value.screenshots_json,
+    }
+}
+
+fn map_version(
+    value: crate::module_bindings::GameDistributionVersionSnapshot,
+) -> GameDistributionVersionRecord {
+    GameDistributionVersionRecord {
+        version_id: value.version_id,
+        game_id: value.game_id,
+        owner_user_id: value.owner_user_id,
+        version_number: value.version_number,
+        package_sha256: value.package_sha_256,
+        package_bytes: value.package_bytes,
+        package_file_count: value.package_file_count,
+        package_entry_path: value.package_entry_path,
+        status: value.status,
+        review_reason: value.review_reason,
+        entry_url: value.entry_url,
+        publication_revision: value.publication_revision,
+        created_at: shared_kernel::format_timestamp_micros(value.created_at_micros),
+        updated_at: shared_kernel::format_timestamp_micros(value.updated_at_micros),
+        metadata_json: value.metadata_json,
+    }
+}
+
+pub(crate) fn map_game_distribution_game_result(
+    result: crate::module_bindings::GameDistributionProcedureResult,
+) -> Result<
+    (
+        Option<GameDistributionGameRecord>,
+        Option<GameDistributionVersionRecord>,
+        bool,
+    ),
+    SpacetimeClientError,
+> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok((
+        result.game.map(map_game),
+        result.version.map(map_version),
+        result.replayed,
+    ))
+}
+
+pub(crate) fn map_game_distribution_owner_game_list_result(
+    result: crate::module_bindings::GameDistributionOwnerGameListProcedureResult,
+) -> Result<Vec<GameDistributionOwnerGameRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok(result
+        .games
+        .into_iter()
+        .map(|value| GameDistributionOwnerGameRecord {
+            game: map_game(value.game),
+            versions: value.versions.into_iter().map(map_version).collect(),
+        })
+        .collect())
+}
+
+pub(crate) fn map_game_distribution_public_game_list_result(
+    result: crate::module_bindings::GameDistributionGameListProcedureResult,
+) -> Result<Vec<GameDistributionPublicGameRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok(result
+        .games
+        .into_iter()
+        .map(|value| GameDistributionPublicGameRecord {
+            game: map_game(value.game),
+            current_version: value.current_version.map(map_version),
+        })
+        .collect())
+}
+
+pub(crate) fn map_game_distribution_version_result(
+    result: crate::module_bindings::GameDistributionVersionProcedureResult,
+) -> Result<Option<GameDistributionVersionRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok(result.version.map(map_version))
+}
+
+pub(crate) fn map_game_distribution_public_game_result(
+    result: crate::module_bindings::GameDistributionGameProcedureResult,
+) -> Result<Option<GameDistributionPublicGameRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok(result.game.map(|value| GameDistributionPublicGameRecord {
+        game: map_game(value.game),
+        current_version: value.current_version.map(map_version),
+    }))
+}
+
+pub(crate) fn map_game_distribution_review_list_result(
+    result: crate::module_bindings::GameDistributionProcedureResult,
+) -> Result<Vec<GameDistributionVersionRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+    Ok(result.versions.into_iter().map(map_version).collect())
+}
diff --git a/server-rs/crates/spacetime-client/src/game_distribution.rs b/server-rs/crates/spacetime-client/src/game_distribution.rs
new file mode 100644
index 000000000..a9feb2ce9
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/game_distribution.rs
@@ -0,0 +1,691 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionPublicGameListRecordInput {
+    pub search: Option<String>,
+    pub category: Option<String>,
+    pub limit: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionOwnerGameListRecordInput {
+    pub owner_user_id: String,
+    pub limit: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionGetGameRecordInput {
+    pub game_id: String,
+    pub owner_user_id: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionCreateGameRecordInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: Option<String>,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+    /// 同一作者的本地项目标识；重复发布会复用既有 game_id。
+    pub local_project_id: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionCreateVersionRecordInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_id: String,
+    /// api-server 校验并解析素材后生成的资料快照 JSON。
+    pub metadata_json: String,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub local_project_id: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionConfirmPackageRecordInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub package_object_key: String,
+    pub package_manifest_json: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionFailUploadRecordInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub error_code: String,
+    pub error_message: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionSubmitReviewRecordInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionCancelVersionRecordInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionApproveRecordInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub entry_url: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionRejectRecordInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub review_reason: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionUnpublishRecordInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GameDistributionSuspendRecordInput {
+    pub game_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub reason: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl SpacetimeClient {
+    pub async fn list_game_distribution_games(
+        &self,
+        input: GameDistributionPublicGameListRecordInput,
+    ) -> Result<Vec<GameDistributionPublicGameRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionPublicGameListInput {
+            search: input.search,
+            category: input.category,
+            limit: input.limit,
+        };
+        self.call_after_connect("list_game_distribution_games", move |connection, sender| {
+            connection
+                .procedures()
+                .list_public_game_distribution_games_and_return_then(input, move |_, result| {
+                    let mapped = result
+                        .map_err(SpacetimeClientError::from_sdk_error)
+                        .and_then(map_game_distribution_public_game_list_result);
+                    send_once(&sender, mapped);
+                });
+        })
+        .await
+    }
+
+    pub async fn list_owner_game_distribution_games(
+        &self,
+        input: GameDistributionOwnerGameListRecordInput,
+    ) -> Result<Vec<GameDistributionOwnerGameRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionOwnerGameListInput {
+            owner_user_id: input.owner_user_id,
+            limit: input.limit,
+        };
+        self.call_after_connect(
+            "list_owner_game_distribution_games",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .list_owner_game_distribution_games_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_owner_game_list_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn get_game_distribution_game(
+        &self,
+        input: GameDistributionGetGameRecordInput,
+    ) -> Result<Option<GameDistributionGameRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionGetGameInput {
+            game_id: input.game_id,
+            owner_user_id: input.owner_user_id,
+        };
+        self.call_after_connect("get_game_distribution_game", move |connection, sender| {
+            connection
+                .procedures()
+                .get_game_distribution_game_and_return_then(input, move |_, result| {
+                    let mapped = result
+                        .map_err(SpacetimeClientError::from_sdk_error)
+                        .and_then(|result| {
+                            map_game_distribution_game_result(result).map(|(game, _, _)| game)
+                        });
+                    send_once(&sender, mapped);
+                });
+        })
+        .await
+    }
+
+    pub async fn get_public_game_distribution_game(
+        &self,
+        game_id: String,
+    ) -> Result<Option<GameDistributionPublicGameRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionPublicGameInput { game_id };
+        self.call_after_connect(
+            "get_public_game_distribution_game",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_public_game_distribution_game_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_public_game_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn create_game_distribution_game(
+        &self,
+        input: GameDistributionCreateGameRecordInput,
+    ) -> Result<(GameDistributionGameRecord, bool), SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionCreateGameInput {
+            game_id: input.game_id,
+            owner_user_id: input.owner_user_id,
+            title: input.title,
+            summary: input.summary,
+            description: input.description,
+            category: input.category,
+            tags_json: input.tags_json,
+            cover_asset_id: input.cover_asset_id,
+            author_name: input.author_name,
+            author_avatar_url: input.author_avatar_url,
+            device_support_desktop: input.device_support_desktop,
+            device_support_mobile: input.device_support_mobile,
+            device_support_touch: input.device_support_touch,
+            input_modes_json: input.input_modes_json,
+            orientation: input.orientation,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+            local_project_id: input.local_project_id,
+        };
+        self.call_after_connect(
+            "create_game_distribution_game",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_game_distribution_game_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_game_result)
+                            .and_then(|(game, _, replayed)| {
+                                game.map(|game| (game, replayed)).ok_or_else(|| {
+                                    SpacetimeClientError::missing_snapshot("游戏创建结果")
+                                })
+                            });
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn create_game_distribution_version(
+        &self,
+        input: GameDistributionCreateVersionRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionCreateVersionInput {
+            game_id: input.game_id,
+            owner_user_id: input.owner_user_id,
+            version_id: input.version_id,
+            metadata_json: input.metadata_json,
+            package_sha_256: input.package_sha256,
+            package_bytes: input.package_bytes,
+            package_file_count: input.package_file_count,
+            package_entry_path: input.package_entry_path,
+            local_project_id: input.local_project_id,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "create_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_game_distribution_version_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_game_result)
+                            .and_then(|(_, version, replayed)| {
+                                version.map(|version| (version, replayed)).ok_or_else(|| {
+                                    SpacetimeClientError::missing_snapshot("游戏版本创建结果")
+                                })
+                            });
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn confirm_game_distribution_package(
+        &self,
+        input: GameDistributionConfirmPackageRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionConfirmPackageInput {
+            version_id: input.version_id,
+            owner_user_id: input.owner_user_id,
+            package_sha_256: input.package_sha256,
+            package_bytes: input.package_bytes,
+            package_file_count: input.package_file_count,
+            package_entry_path: input.package_entry_path,
+            package_object_key: input.package_object_key,
+            package_manifest_json: input.package_manifest_json,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            updated_at_micros: input.updated_at_micros,
+        };
+        self.call_after_connect(
+            "confirm_game_distribution_package",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .confirm_game_distribution_package_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_game_result)
+                            .and_then(|(_, version, replayed)| {
+                                version.map(|version| (version, replayed)).ok_or_else(|| {
+                                    SpacetimeClientError::missing_snapshot("游戏发行包确认结果")
+                                })
+                            });
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn get_owner_game_distribution_version(
+        &self,
+        owner_user_id: String,
+        version_id: String,
+    ) -> Result<Option<GameDistributionVersionRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionOwnerVersionInput {
+            owner_user_id,
+            version_id,
+        };
+        self.call_after_connect(
+            "get_owner_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_owner_game_distribution_version_and_return_then(
+                        input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_version_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn get_game_distribution_version(
+        &self,
+        version_id: String,
+    ) -> Result<Option<GameDistributionVersionRecord>, SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionVersionLookupInput { version_id };
+        self.call_after_connect(
+            "get_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_game_distribution_version_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_version_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn fail_game_distribution_upload(
+        &self,
+        input: GameDistributionFailUploadRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let input = crate::module_bindings::GameDistributionFailUploadInput {
+            version_id: input.version_id,
+            owner_user_id: input.owner_user_id,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            error_code: input.error_code,
+            error_message: input.error_message,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "fail_game_distribution_upload",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .fail_game_distribution_upload_and_return_then(input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_game_distribution_game_result)
+                            .and_then(|(_, version, replayed)| {
+                                version.map(|version| (version, replayed)).ok_or_else(|| {
+                                    SpacetimeClientError::missing_snapshot("游戏发行失败结果")
+                                })
+                            });
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn submit_game_distribution_version_for_review(
+        &self,
+        input: GameDistributionSubmitReviewRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionSubmitReviewInput {
+            version_id: input.version_id,
+            owner_user_id: input.owner_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "submit_game_distribution_version_for_review",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .submit_game_distribution_version_for_review_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(_, version, replayed)| {
+                                    version.map(|version| (version, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏送审结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn cancel_game_distribution_version(
+        &self,
+        input: GameDistributionCancelVersionRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionCancelVersionInput {
+            version_id: input.version_id,
+            owner_user_id: input.owner_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "cancel_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .cancel_game_distribution_version_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(_, version, replayed)| {
+                                    version.map(|version| (version, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏撤回结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn approve_game_distribution_version(
+        &self,
+        input: GameDistributionApproveRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionApproveInput {
+            version_id: input.version_id,
+            admin_user_id: input.admin_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            entry_url: input.entry_url,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "approve_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .approve_game_distribution_version_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(_, version, replayed)| {
+                                    version.map(|version| (version, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏审核批准结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn reject_game_distribution_version(
+        &self,
+        input: GameDistributionRejectRecordInput,
+    ) -> Result<(GameDistributionVersionRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionRejectInput {
+            version_id: input.version_id,
+            admin_user_id: input.admin_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            review_reason: input.review_reason,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "reject_game_distribution_version",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .reject_game_distribution_version_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(_, version, replayed)| {
+                                    version.map(|version| (version, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏审核拒绝结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn unpublish_game_distribution_game(
+        &self,
+        input: GameDistributionUnpublishRecordInput,
+    ) -> Result<(GameDistributionGameRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionUnpublishInput {
+            game_id: input.game_id,
+            owner_user_id: input.owner_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "unpublish_game_distribution_game",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .unpublish_game_distribution_game_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(game, _, replayed)| {
+                                    game.map(|game| (game, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏下架结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn suspend_game_distribution_game(
+        &self,
+        input: GameDistributionSuspendRecordInput,
+    ) -> Result<(GameDistributionGameRecord, bool), SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionSuspendInput {
+            game_id: input.game_id,
+            admin_user_id: input.admin_user_id,
+            expected_publication_revision: input.expected_publication_revision,
+            reason: input.reason,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            now_micros: input.now_micros,
+        };
+        self.call_after_connect(
+            "suspend_game_distribution_game",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .suspend_game_distribution_game_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_game_result)
+                                .and_then(|(game, _, replayed)| {
+                                    game.map(|game| (game, replayed)).ok_or_else(|| {
+                                        SpacetimeClientError::missing_snapshot("游戏暂停结果")
+                                    })
+                                });
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn list_game_distribution_reviews(
+        &self,
+        limit: u32,
+    ) -> Result<Vec<GameDistributionVersionRecord>, SpacetimeClientError> {
+        let procedure_input = crate::module_bindings::GameDistributionReviewListInput { limit };
+        self.call_after_connect(
+            "list_game_distribution_reviews",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .list_game_distribution_reviews_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_game_distribution_review_list_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings.rs b/server-rs/crates/spacetime-client/src/module_bindings.rs
index f63694522..d52b82b3d 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings.rs
@@ -95,6 +95,7 @@ pub mod analytics_granularity_type;
 pub mod analytics_metric_query_input_type;
 pub mod analytics_metric_query_procedure_result_type;
 pub mod append_ai_text_chunk_and_return_procedure;
+pub mod approve_game_distribution_version_and_return_procedure;
 pub mod asset_entity_binding_input_type;
 pub mod asset_entity_binding_procedure_result_type;
 pub mod asset_entity_binding_snapshot_type;
@@ -174,6 +175,7 @@ pub mod big_fish_runtime_run_type;
 pub mod bind_asset_object_to_entity_and_return_procedure;
 pub mod bind_asset_object_to_entity_reducer;
 pub mod cancel_ai_task_and_return_procedure;
+pub mod cancel_game_distribution_version_and_return_procedure;
 pub mod chapter_pace_band_type;
 pub mod chapter_progression_table;
 pub mod chapter_progression_type;
@@ -193,6 +195,7 @@ pub mod complete_external_generation_job_and_return_procedure;
 pub mod complete_profile_recharge_order_expiration_schedule_and_return_procedure;
 pub mod confirm_asset_object_and_return_procedure;
 pub mod confirm_asset_object_reducer;
+pub mod confirm_game_distribution_package_and_return_procedure;
 pub mod consume_profile_wallet_points_and_return_procedure;
 pub mod create_admin_account_and_return_procedure;
 pub mod create_ai_task_and_return_procedure;
@@ -204,6 +207,8 @@ pub mod create_editor_project_and_return_procedure;
 pub mod create_editor_project_resource_and_return_procedure;
 pub mod create_error_report_and_return_procedure;
 pub mod create_external_api_key_and_return_procedure;
+pub mod create_game_distribution_game_and_return_procedure;
+pub mod create_game_distribution_version_and_return_procedure;
 pub mod create_profile_recharge_order_and_return_procedure;
 pub mod creation_entry_config_table;
 pub mod creation_entry_config_type;
@@ -448,12 +453,45 @@ pub mod external_generation_queue_stats_procedure_result_type;
 pub mod external_generation_queue_stats_snapshot_type;
 pub mod fail_ai_task_and_return_procedure;
 pub mod fail_external_generation_job_and_return_procedure;
+pub mod fail_game_distribution_upload_and_return_procedure;
 pub mod feature_gate_config_admin_upsert_input_type;
 pub mod feature_gate_config_procedure_result_type;
 pub mod feature_gate_config_snapshot_type;
 pub mod feature_gate_config_table;
 pub mod feature_gate_config_type;
 pub mod find_editor_asset_group_source_and_return_procedure;
+pub mod game_distribution_approve_input_type;
+pub mod game_distribution_cancel_version_input_type;
+pub mod game_distribution_confirm_package_input_type;
+pub mod game_distribution_create_game_input_type;
+pub mod game_distribution_create_version_input_type;
+pub mod game_distribution_fail_upload_input_type;
+pub mod game_distribution_game_list_procedure_result_type;
+pub mod game_distribution_game_procedure_result_type;
+pub mod game_distribution_game_snapshot_type;
+pub mod game_distribution_game_table;
+pub mod game_distribution_game_type;
+pub mod game_distribution_get_game_input_type;
+pub mod game_distribution_idempotency_receipt_table;
+pub mod game_distribution_idempotency_receipt_type;
+pub mod game_distribution_owner_game_list_input_type;
+pub mod game_distribution_owner_game_list_procedure_result_type;
+pub mod game_distribution_owner_game_snapshot_type;
+pub mod game_distribution_owner_version_input_type;
+pub mod game_distribution_procedure_result_type;
+pub mod game_distribution_public_game_input_type;
+pub mod game_distribution_public_game_list_input_type;
+pub mod game_distribution_public_game_snapshot_type;
+pub mod game_distribution_reject_input_type;
+pub mod game_distribution_review_list_input_type;
+pub mod game_distribution_submit_review_input_type;
+pub mod game_distribution_suspend_input_type;
+pub mod game_distribution_unpublish_input_type;
+pub mod game_distribution_version_lookup_input_type;
+pub mod game_distribution_version_procedure_result_type;
+pub mod game_distribution_version_snapshot_type;
+pub mod game_distribution_version_table;
+pub mod game_distribution_version_type;
 pub mod get_admin_account_by_id_and_return_procedure;
 pub mod get_admin_account_by_username_and_return_procedure;
 pub mod get_admin_dashboard_stats_and_return_procedure;
@@ -471,7 +509,10 @@ pub mod get_external_generation_job_result_and_return_procedure;
 pub mod get_external_generation_job_summary_and_return_procedure;
 pub mod get_external_generation_queue_stats_and_return_procedure;
 pub mod get_feature_gate_config_procedure;
+pub mod get_game_distribution_game_and_return_procedure;
+pub mod get_game_distribution_version_and_return_procedure;
 pub mod get_llm_router_account_and_return_procedure;
+pub mod get_owner_game_distribution_version_and_return_procedure;
 pub mod get_profile_dashboard_procedure;
 pub mod get_profile_recharge_center_procedure;
 pub mod get_profile_recharge_order_and_return_procedure;
@@ -479,6 +520,7 @@ pub mod get_profile_recharge_refund_and_return_procedure;
 pub mod get_profile_recharge_refund_bill_checkpoint_and_return_procedure;
 pub mod get_profile_referral_invite_center_procedure;
 pub mod get_profile_task_center_procedure;
+pub mod get_public_game_distribution_game_and_return_procedure;
 pub mod get_recent_editor_project_and_return_procedure;
 pub mod get_runtime_setting_or_default_procedure;
 pub mod grant_new_user_registration_wallet_reward_procedure;
@@ -512,12 +554,16 @@ pub mod list_error_reports_and_return_procedure;
 pub mod list_external_api_keys_and_return_procedure;
 pub mod list_external_generation_job_summaries_and_return_procedure;
 pub mod list_external_generation_jobs_and_return_procedure;
+pub mod list_game_distribution_games_and_return_procedure;
+pub mod list_game_distribution_reviews_and_return_procedure;
+pub mod list_owner_game_distribution_games_and_return_procedure;
 pub mod list_profile_recharge_refund_holds_for_reconciliation_procedure;
 pub mod list_profile_recharge_refunds_for_reconciliation_procedure;
 pub mod list_profile_wallet_ledger_procedure;
 pub mod list_public_editor_project_resources_and_return_procedure;
 pub mod list_public_editor_showcase_assets_and_return_procedure;
 pub mod list_public_editor_showcase_assets_for_viewer_and_return_procedure;
+pub mod list_public_game_distribution_games_and_return_procedure;
 pub mod list_unchecked_expired_profile_recharge_orders_procedure;
 pub mod llm_router_account_get_input_type;
 pub mod llm_router_account_procedure_result_type;
@@ -682,6 +728,7 @@ pub mod redeem_profile_reward_code_procedure;
 pub mod refresh_session_table;
 pub mod refresh_session_type;
 pub mod refund_profile_wallet_points_and_return_procedure;
+pub mod reject_game_distribution_version_and_return_procedure;
 pub mod release_profile_recharge_refund_hold_and_return_procedure;
 pub mod rename_editor_project_and_return_procedure;
 pub mod renew_external_generation_job_lease_and_return_procedure;
@@ -870,7 +917,9 @@ pub mod story_session_status_type;
 pub mod story_session_table;
 pub mod story_session_type;
 pub mod submit_editor_showcase_asset_and_return_procedure;
+pub mod submit_game_distribution_version_for_review_and_return_procedure;
 pub mod submit_profile_feedback_and_return_procedure;
+pub mod suspend_game_distribution_game_and_return_procedure;
 pub mod sync_auth_store_projection_procedure;
 pub mod touch_editor_agent_conversation_and_return_procedure;
 pub mod tracking_daily_stat_table;
@@ -880,6 +929,7 @@ pub mod tracking_event_type;
 pub mod treasure_interaction_action_type;
 pub mod treasure_record_table;
 pub mod treasure_record_type;
+pub mod unpublish_game_distribution_game_and_return_procedure;
 pub mod update_admin_account_and_return_procedure;
 pub mod update_editor_asset_and_return_procedure;
 pub mod update_editor_asset_folder_and_return_procedure;
@@ -1008,6 +1058,7 @@ pub use analytics_granularity_type::AnalyticsGranularity;
 pub use analytics_metric_query_input_type::AnalyticsMetricQueryInput;
 pub use analytics_metric_query_procedure_result_type::AnalyticsMetricQueryProcedureResult;
 pub use append_ai_text_chunk_and_return_procedure::append_ai_text_chunk_and_return;
+pub use approve_game_distribution_version_and_return_procedure::approve_game_distribution_version_and_return;
 pub use asset_entity_binding_input_type::AssetEntityBindingInput;
 pub use asset_entity_binding_procedure_result_type::AssetEntityBindingProcedureResult;
 pub use asset_entity_binding_snapshot_type::AssetEntityBindingSnapshot;
@@ -1087,6 +1138,7 @@ pub use big_fish_runtime_run_type::BigFishRuntimeRun;
 pub use bind_asset_object_to_entity_and_return_procedure::bind_asset_object_to_entity_and_return;
 pub use bind_asset_object_to_entity_reducer::bind_asset_object_to_entity;
 pub use cancel_ai_task_and_return_procedure::cancel_ai_task_and_return;
+pub use cancel_game_distribution_version_and_return_procedure::cancel_game_distribution_version_and_return;
 pub use chapter_pace_band_type::ChapterPaceBand;
 pub use chapter_progression_table::*;
 pub use chapter_progression_type::ChapterProgression;
@@ -1106,6 +1158,7 @@ pub use complete_external_generation_job_and_return_procedure::complete_external
 pub use complete_profile_recharge_order_expiration_schedule_and_return_procedure::complete_profile_recharge_order_expiration_schedule_and_return;
 pub use confirm_asset_object_and_return_procedure::confirm_asset_object_and_return;
 pub use confirm_asset_object_reducer::confirm_asset_object;
+pub use confirm_game_distribution_package_and_return_procedure::confirm_game_distribution_package_and_return;
 pub use consume_profile_wallet_points_and_return_procedure::consume_profile_wallet_points_and_return;
 pub use create_admin_account_and_return_procedure::create_admin_account_and_return;
 pub use create_ai_task_and_return_procedure::create_ai_task_and_return;
@@ -1117,6 +1170,8 @@ pub use create_editor_project_and_return_procedure::create_editor_project_and_re
 pub use create_editor_project_resource_and_return_procedure::create_editor_project_resource_and_return;
 pub use create_error_report_and_return_procedure::create_error_report_and_return;
 pub use create_external_api_key_and_return_procedure::create_external_api_key_and_return;
+pub use create_game_distribution_game_and_return_procedure::create_game_distribution_game_and_return;
+pub use create_game_distribution_version_and_return_procedure::create_game_distribution_version_and_return;
 pub use create_profile_recharge_order_and_return_procedure::create_profile_recharge_order_and_return;
 pub use creation_entry_config_table::*;
 pub use creation_entry_config_type::CreationEntryConfig;
@@ -1361,12 +1416,45 @@ pub use external_generation_queue_stats_procedure_result_type::ExternalGeneratio
 pub use external_generation_queue_stats_snapshot_type::ExternalGenerationQueueStatsSnapshot;
 pub use fail_ai_task_and_return_procedure::fail_ai_task_and_return;
 pub use fail_external_generation_job_and_return_procedure::fail_external_generation_job_and_return;
+pub use fail_game_distribution_upload_and_return_procedure::fail_game_distribution_upload_and_return;
 pub use feature_gate_config_admin_upsert_input_type::FeatureGateConfigAdminUpsertInput;
 pub use feature_gate_config_procedure_result_type::FeatureGateConfigProcedureResult;
 pub use feature_gate_config_snapshot_type::FeatureGateConfigSnapshot;
 pub use feature_gate_config_table::*;
 pub use feature_gate_config_type::FeatureGateConfig;
 pub use find_editor_asset_group_source_and_return_procedure::find_editor_asset_group_source_and_return;
+pub use game_distribution_approve_input_type::GameDistributionApproveInput;
+pub use game_distribution_cancel_version_input_type::GameDistributionCancelVersionInput;
+pub use game_distribution_confirm_package_input_type::GameDistributionConfirmPackageInput;
+pub use game_distribution_create_game_input_type::GameDistributionCreateGameInput;
+pub use game_distribution_create_version_input_type::GameDistributionCreateVersionInput;
+pub use game_distribution_fail_upload_input_type::GameDistributionFailUploadInput;
+pub use game_distribution_game_list_procedure_result_type::GameDistributionGameListProcedureResult;
+pub use game_distribution_game_procedure_result_type::GameDistributionGameProcedureResult;
+pub use game_distribution_game_snapshot_type::GameDistributionGameSnapshot;
+pub use game_distribution_game_table::*;
+pub use game_distribution_game_type::GameDistributionGame;
+pub use game_distribution_get_game_input_type::GameDistributionGetGameInput;
+pub use game_distribution_idempotency_receipt_table::*;
+pub use game_distribution_idempotency_receipt_type::GameDistributionIdempotencyReceipt;
+pub use game_distribution_owner_game_list_input_type::GameDistributionOwnerGameListInput;
+pub use game_distribution_owner_game_list_procedure_result_type::GameDistributionOwnerGameListProcedureResult;
+pub use game_distribution_owner_game_snapshot_type::GameDistributionOwnerGameSnapshot;
+pub use game_distribution_owner_version_input_type::GameDistributionOwnerVersionInput;
+pub use game_distribution_procedure_result_type::GameDistributionProcedureResult;
+pub use game_distribution_public_game_input_type::GameDistributionPublicGameInput;
+pub use game_distribution_public_game_list_input_type::GameDistributionPublicGameListInput;
+pub use game_distribution_public_game_snapshot_type::GameDistributionPublicGameSnapshot;
+pub use game_distribution_reject_input_type::GameDistributionRejectInput;
+pub use game_distribution_review_list_input_type::GameDistributionReviewListInput;
+pub use game_distribution_submit_review_input_type::GameDistributionSubmitReviewInput;
+pub use game_distribution_suspend_input_type::GameDistributionSuspendInput;
+pub use game_distribution_unpublish_input_type::GameDistributionUnpublishInput;
+pub use game_distribution_version_lookup_input_type::GameDistributionVersionLookupInput;
+pub use game_distribution_version_procedure_result_type::GameDistributionVersionProcedureResult;
+pub use game_distribution_version_snapshot_type::GameDistributionVersionSnapshot;
+pub use game_distribution_version_table::*;
+pub use game_distribution_version_type::GameDistributionVersion;
 pub use get_admin_account_by_id_and_return_procedure::get_admin_account_by_id_and_return;
 pub use get_admin_account_by_username_and_return_procedure::get_admin_account_by_username_and_return;
 pub use get_admin_dashboard_stats_and_return_procedure::get_admin_dashboard_stats_and_return;
@@ -1384,7 +1472,10 @@ pub use get_external_generation_job_result_and_return_procedure::get_external_ge
 pub use get_external_generation_job_summary_and_return_procedure::get_external_generation_job_summary_and_return;
 pub use get_external_generation_queue_stats_and_return_procedure::get_external_generation_queue_stats_and_return;
 pub use get_feature_gate_config_procedure::get_feature_gate_config;
+pub use get_game_distribution_game_and_return_procedure::get_game_distribution_game_and_return;
+pub use get_game_distribution_version_and_return_procedure::get_game_distribution_version_and_return;
 pub use get_llm_router_account_and_return_procedure::get_llm_router_account_and_return;
+pub use get_owner_game_distribution_version_and_return_procedure::get_owner_game_distribution_version_and_return;
 pub use get_profile_dashboard_procedure::get_profile_dashboard;
 pub use get_profile_recharge_center_procedure::get_profile_recharge_center;
 pub use get_profile_recharge_order_and_return_procedure::get_profile_recharge_order_and_return;
@@ -1392,6 +1483,7 @@ pub use get_profile_recharge_refund_and_return_procedure::get_profile_recharge_r
 pub use get_profile_recharge_refund_bill_checkpoint_and_return_procedure::get_profile_recharge_refund_bill_checkpoint_and_return;
 pub use get_profile_referral_invite_center_procedure::get_profile_referral_invite_center;
 pub use get_profile_task_center_procedure::get_profile_task_center;
+pub use get_public_game_distribution_game_and_return_procedure::get_public_game_distribution_game_and_return;
 pub use get_recent_editor_project_and_return_procedure::get_recent_editor_project_and_return;
 pub use get_runtime_setting_or_default_procedure::get_runtime_setting_or_default;
 pub use grant_new_user_registration_wallet_reward_procedure::grant_new_user_registration_wallet_reward;
@@ -1425,12 +1517,16 @@ pub use list_error_reports_and_return_procedure::list_error_reports_and_return;
 pub use list_external_api_keys_and_return_procedure::list_external_api_keys_and_return;
 pub use list_external_generation_job_summaries_and_return_procedure::list_external_generation_job_summaries_and_return;
 pub use list_external_generation_jobs_and_return_procedure::list_external_generation_jobs_and_return;
+pub use list_game_distribution_games_and_return_procedure::list_game_distribution_games_and_return;
+pub use list_game_distribution_reviews_and_return_procedure::list_game_distribution_reviews_and_return;
+pub use list_owner_game_distribution_games_and_return_procedure::list_owner_game_distribution_games_and_return;
 pub use list_profile_recharge_refund_holds_for_reconciliation_procedure::list_profile_recharge_refund_holds_for_reconciliation;
 pub use list_profile_recharge_refunds_for_reconciliation_procedure::list_profile_recharge_refunds_for_reconciliation;
 pub use list_profile_wallet_ledger_procedure::list_profile_wallet_ledger;
 pub use list_public_editor_project_resources_and_return_procedure::list_public_editor_project_resources_and_return;
 pub use list_public_editor_showcase_assets_and_return_procedure::list_public_editor_showcase_assets_and_return;
 pub use list_public_editor_showcase_assets_for_viewer_and_return_procedure::list_public_editor_showcase_assets_for_viewer_and_return;
+pub use list_public_game_distribution_games_and_return_procedure::list_public_game_distribution_games_and_return;
 pub use list_unchecked_expired_profile_recharge_orders_procedure::list_unchecked_expired_profile_recharge_orders;
 pub use llm_router_account_get_input_type::LlmRouterAccountGetInput;
 pub use llm_router_account_procedure_result_type::LlmRouterAccountProcedureResult;
@@ -1595,6 +1691,7 @@ pub use redeem_profile_reward_code_procedure::redeem_profile_reward_code;
 pub use refresh_session_table::*;
 pub use refresh_session_type::RefreshSession;
 pub use refund_profile_wallet_points_and_return_procedure::refund_profile_wallet_points_and_return;
+pub use reject_game_distribution_version_and_return_procedure::reject_game_distribution_version_and_return;
 pub use release_profile_recharge_refund_hold_and_return_procedure::release_profile_recharge_refund_hold_and_return;
 pub use rename_editor_project_and_return_procedure::rename_editor_project_and_return;
 pub use renew_external_generation_job_lease_and_return_procedure::renew_external_generation_job_lease_and_return;
@@ -1783,7 +1880,9 @@ pub use story_session_status_type::StorySessionStatus;
 pub use story_session_table::*;
 pub use story_session_type::StorySession;
 pub use submit_editor_showcase_asset_and_return_procedure::submit_editor_showcase_asset_and_return;
+pub use submit_game_distribution_version_for_review_and_return_procedure::submit_game_distribution_version_for_review_and_return;
 pub use submit_profile_feedback_and_return_procedure::submit_profile_feedback_and_return;
+pub use suspend_game_distribution_game_and_return_procedure::suspend_game_distribution_game_and_return;
 pub use sync_auth_store_projection_procedure::sync_auth_store_projection;
 pub use touch_editor_agent_conversation_and_return_procedure::touch_editor_agent_conversation_and_return;
 pub use tracking_daily_stat_table::*;
@@ -1793,6 +1892,7 @@ pub use tracking_event_type::TrackingEvent;
 pub use treasure_interaction_action_type::TreasureInteractionAction;
 pub use treasure_record_table::*;
 pub use treasure_record_type::TreasureRecord;
+pub use unpublish_game_distribution_game_and_return_procedure::unpublish_game_distribution_game_and_return;
 pub use update_admin_account_and_return_procedure::update_admin_account_and_return;
 pub use update_editor_asset_and_return_procedure::update_editor_asset_and_return;
 pub use update_editor_asset_folder_and_return_procedure::update_editor_asset_folder_and_return;
@@ -2005,6 +2105,9 @@ pub struct DbUpdate {
     external_generation_job_event: __sdk::TableUpdate<ExternalGenerationJobEvent>,
     external_generation_job_summary: __sdk::TableUpdate<ExternalGenerationJobSummary>,
     feature_gate_config: __sdk::TableUpdate<FeatureGateConfig>,
+    game_distribution_game: __sdk::TableUpdate<GameDistributionGame>,
+    game_distribution_idempotency_receipt: __sdk::TableUpdate<GameDistributionIdempotencyReceipt>,
+    game_distribution_version: __sdk::TableUpdate<GameDistributionVersion>,
     inventory_slot: __sdk::TableUpdate<InventorySlot>,
     jump_hop_agent_session: __sdk::TableUpdate<JumpHopAgentSessionRow>,
     jump_hop_event: __sdk::TableUpdate<JumpHopEventRow>,
@@ -2320,6 +2423,19 @@ impl TryFrom<__ws::v2::TransactionUpdate> for DbUpdate {
                 "feature_gate_config" => db_update
                     .feature_gate_config
                     .append(feature_gate_config_table::parse_table_update(table_update)?),
+                "game_distribution_game" => db_update.game_distribution_game.append(
+                    game_distribution_game_table::parse_table_update(table_update)?,
+                ),
+                "game_distribution_idempotency_receipt" => {
+                    db_update.game_distribution_idempotency_receipt.append(
+                        game_distribution_idempotency_receipt_table::parse_table_update(
+                            table_update,
+                        )?,
+                    )
+                }
+                "game_distribution_version" => db_update.game_distribution_version.append(
+                    game_distribution_version_table::parse_table_update(table_update)?,
+                ),
                 "inventory_slot" => db_update
                     .inventory_slot
                     .append(inventory_slot_table::parse_table_update(table_update)?),
@@ -2946,6 +3062,24 @@ impl __sdk::DbUpdate for DbUpdate {
                 &self.feature_gate_config,
             )
             .with_updates_by_pk(|row| &row.gate_key);
+        diff.game_distribution_game = cache
+            .apply_diff_to_table::<GameDistributionGame>(
+                "game_distribution_game",
+                &self.game_distribution_game,
+            )
+            .with_updates_by_pk(|row| &row.game_id);
+        diff.game_distribution_idempotency_receipt = cache
+            .apply_diff_to_table::<GameDistributionIdempotencyReceipt>(
+                "game_distribution_idempotency_receipt",
+                &self.game_distribution_idempotency_receipt,
+            )
+            .with_updates_by_pk(|row| &row.receipt_id);
+        diff.game_distribution_version = cache
+            .apply_diff_to_table::<GameDistributionVersion>(
+                "game_distribution_version",
+                &self.game_distribution_version,
+            )
+            .with_updates_by_pk(|row| &row.version_id);
         diff.inventory_slot = cache
             .apply_diff_to_table::<InventorySlot>("inventory_slot", &self.inventory_slot)
             .with_updates_by_pk(|row| &row.slot_id);
@@ -3573,6 +3707,15 @@ impl __sdk::DbUpdate for DbUpdate {
                 "feature_gate_config" => db_update
                     .feature_gate_config
                     .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "game_distribution_game" => db_update
+                    .game_distribution_game
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "game_distribution_idempotency_receipt" => db_update
+                    .game_distribution_idempotency_receipt
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "game_distribution_version" => db_update
+                    .game_distribution_version
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
                 "inventory_slot" => db_update
                     .inventory_slot
                     .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
@@ -4021,6 +4164,15 @@ impl __sdk::DbUpdate for DbUpdate {
                 "feature_gate_config" => db_update
                     .feature_gate_config
                     .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "game_distribution_game" => db_update
+                    .game_distribution_game
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "game_distribution_idempotency_receipt" => db_update
+                    .game_distribution_idempotency_receipt
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "game_distribution_version" => db_update
+                    .game_distribution_version
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
                 "inventory_slot" => db_update
                     .inventory_slot
                     .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
@@ -4347,6 +4499,10 @@ pub struct AppliedDiff<'r> {
     external_generation_job_event: __sdk::TableAppliedDiff<'r, ExternalGenerationJobEvent>,
     external_generation_job_summary: __sdk::TableAppliedDiff<'r, ExternalGenerationJobSummary>,
     feature_gate_config: __sdk::TableAppliedDiff<'r, FeatureGateConfig>,
+    game_distribution_game: __sdk::TableAppliedDiff<'r, GameDistributionGame>,
+    game_distribution_idempotency_receipt:
+        __sdk::TableAppliedDiff<'r, GameDistributionIdempotencyReceipt>,
+    game_distribution_version: __sdk::TableAppliedDiff<'r, GameDistributionVersion>,
     inventory_slot: __sdk::TableAppliedDiff<'r, InventorySlot>,
     jump_hop_agent_session: __sdk::TableAppliedDiff<'r, JumpHopAgentSessionRow>,
     jump_hop_event: __sdk::TableAppliedDiff<'r, JumpHopEventRow>,
@@ -4759,6 +4915,21 @@ impl<'r> __sdk::AppliedDiff<'r> for AppliedDiff<'r> {
             &self.feature_gate_config,
             event,
         );
+        callbacks.invoke_table_row_callbacks::<GameDistributionGame>(
+            "game_distribution_game",
+            &self.game_distribution_game,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<GameDistributionIdempotencyReceipt>(
+            "game_distribution_idempotency_receipt",
+            &self.game_distribution_idempotency_receipt,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<GameDistributionVersion>(
+            "game_distribution_version",
+            &self.game_distribution_version,
+            event,
+        );
         callbacks.invoke_table_row_callbacks::<InventorySlot>(
             "inventory_slot",
             &self.inventory_slot,
@@ -5876,6 +6047,9 @@ impl __sdk::SpacetimeModule for RemoteModule {
         external_generation_job_event_table::register_table(client_cache);
         external_generation_job_summary_table::register_table(client_cache);
         feature_gate_config_table::register_table(client_cache);
+        game_distribution_game_table::register_table(client_cache);
+        game_distribution_idempotency_receipt_table::register_table(client_cache);
+        game_distribution_version_table::register_table(client_cache);
         inventory_slot_table::register_table(client_cache);
         jump_hop_agent_session_table::register_table(client_cache);
         jump_hop_event_table::register_table(client_cache);
@@ -6023,6 +6197,9 @@ impl __sdk::SpacetimeModule for RemoteModule {
         "external_generation_job_event",
         "external_generation_job_summary",
         "feature_gate_config",
+        "game_distribution_game",
+        "game_distribution_idempotency_receipt",
+        "game_distribution_version",
         "inventory_slot",
         "jump_hop_agent_session",
         "jump_hop_event",
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/approve_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/approve_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..7a42c9ec4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/approve_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_approve_input_type::GameDistributionApproveInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ApproveGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionApproveInput,
+}
+
+impl __sdk::InModule for ApproveGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `approve_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait approve_game_distribution_version_and_return {
+    fn approve_game_distribution_version_and_return(&self, input: GameDistributionApproveInput) {
+        self.approve_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn approve_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionApproveInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl approve_game_distribution_version_and_return for super::RemoteProcedures {
+    fn approve_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionApproveInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "approve_game_distribution_version_and_return",
+                ApproveGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/cancel_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/cancel_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..0f4e6f6d5
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/cancel_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_cancel_version_input_type::GameDistributionCancelVersionInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CancelGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionCancelVersionInput,
+}
+
+impl __sdk::InModule for CancelGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `cancel_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait cancel_game_distribution_version_and_return {
+    fn cancel_game_distribution_version_and_return(
+        &self,
+        input: GameDistributionCancelVersionInput,
+    ) {
+        self.cancel_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn cancel_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionCancelVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl cancel_game_distribution_version_and_return for super::RemoteProcedures {
+    fn cancel_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionCancelVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "cancel_game_distribution_version_and_return",
+                CancelGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/confirm_game_distribution_package_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/confirm_game_distribution_package_and_return_procedure.rs
new file mode 100644
index 000000000..c6e881e84
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/confirm_game_distribution_package_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_confirm_package_input_type::GameDistributionConfirmPackageInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ConfirmGameDistributionPackageAndReturnArgs {
+    pub input: GameDistributionConfirmPackageInput,
+}
+
+impl __sdk::InModule for ConfirmGameDistributionPackageAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `confirm_game_distribution_package_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait confirm_game_distribution_package_and_return {
+    fn confirm_game_distribution_package_and_return(
+        &self,
+        input: GameDistributionConfirmPackageInput,
+    ) {
+        self.confirm_game_distribution_package_and_return_then(input, |_, _| {});
+    }
+
+    fn confirm_game_distribution_package_and_return_then(
+        &self,
+        input: GameDistributionConfirmPackageInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl confirm_game_distribution_package_and_return for super::RemoteProcedures {
+    fn confirm_game_distribution_package_and_return_then(
+        &self,
+        input: GameDistributionConfirmPackageInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "confirm_game_distribution_package_and_return",
+                ConfirmGameDistributionPackageAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_game_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_game_and_return_procedure.rs
new file mode 100644
index 000000000..945777c57
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_game_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_create_game_input_type::GameDistributionCreateGameInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateGameDistributionGameAndReturnArgs {
+    pub input: GameDistributionCreateGameInput,
+}
+
+impl __sdk::InModule for CreateGameDistributionGameAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_game_distribution_game_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_game_distribution_game_and_return {
+    fn create_game_distribution_game_and_return(&self, input: GameDistributionCreateGameInput) {
+        self.create_game_distribution_game_and_return_then(input, |_, _| {});
+    }
+
+    fn create_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionCreateGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_game_distribution_game_and_return for super::RemoteProcedures {
+    fn create_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionCreateGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "create_game_distribution_game_and_return",
+                CreateGameDistributionGameAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..ccb8a9cc8
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_create_version_input_type::GameDistributionCreateVersionInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionCreateVersionInput,
+}
+
+impl __sdk::InModule for CreateGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_game_distribution_version_and_return {
+    fn create_game_distribution_version_and_return(
+        &self,
+        input: GameDistributionCreateVersionInput,
+    ) {
+        self.create_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn create_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionCreateVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_game_distribution_version_and_return for super::RemoteProcedures {
+    fn create_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionCreateVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "create_game_distribution_version_and_return",
+                CreateGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/fail_game_distribution_upload_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/fail_game_distribution_upload_and_return_procedure.rs
new file mode 100644
index 000000000..65235c650
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/fail_game_distribution_upload_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_fail_upload_input_type::GameDistributionFailUploadInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct FailGameDistributionUploadAndReturnArgs {
+    pub input: GameDistributionFailUploadInput,
+}
+
+impl __sdk::InModule for FailGameDistributionUploadAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `fail_game_distribution_upload_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait fail_game_distribution_upload_and_return {
+    fn fail_game_distribution_upload_and_return(&self, input: GameDistributionFailUploadInput) {
+        self.fail_game_distribution_upload_and_return_then(input, |_, _| {});
+    }
+
+    fn fail_game_distribution_upload_and_return_then(
+        &self,
+        input: GameDistributionFailUploadInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl fail_game_distribution_upload_and_return for super::RemoteProcedures {
+    fn fail_game_distribution_upload_and_return_then(
+        &self,
+        input: GameDistributionFailUploadInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "fail_game_distribution_upload_and_return",
+                FailGameDistributionUploadAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_approve_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_approve_input_type.rs
new file mode 100644
index 000000000..10cce03d8
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_approve_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionApproveInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub entry_url: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionApproveInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_cancel_version_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_cancel_version_input_type.rs
new file mode 100644
index 000000000..0f5eb5472
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_cancel_version_input_type.rs
@@ -0,0 +1,20 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionCancelVersionInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionCancelVersionInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_confirm_package_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_confirm_package_input_type.rs
new file mode 100644
index 000000000..f60c14cb8
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_confirm_package_input_type.rs
@@ -0,0 +1,25 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionConfirmPackageInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub package_sha_256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub package_object_key: String,
+    pub package_manifest_json: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionConfirmPackageInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_game_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_game_input_type.rs
new file mode 100644
index 000000000..c9279cef3
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_game_input_type.rs
@@ -0,0 +1,33 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionCreateGameInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: Option<String>,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+    pub local_project_id: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionCreateGameInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_version_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_version_input_type.rs
new file mode 100644
index 000000000..86e199c18
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_create_version_input_type.rs
@@ -0,0 +1,26 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionCreateVersionInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_id: String,
+    pub metadata_json: String,
+    pub package_sha_256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub local_project_id: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionCreateVersionInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_fail_upload_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_fail_upload_input_type.rs
new file mode 100644
index 000000000..26323e915
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_fail_upload_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionFailUploadInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub error_code: String,
+    pub error_message: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionFailUploadInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_list_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_list_procedure_result_type.rs
new file mode 100644
index 000000000..fb6d59a54
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_list_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_public_game_snapshot_type::GameDistributionPublicGameSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionGameListProcedureResult {
+    pub ok: bool,
+    pub games: Vec<GameDistributionPublicGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionGameListProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_procedure_result_type.rs
new file mode 100644
index 000000000..fa4be5cca
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_public_game_snapshot_type::GameDistributionPublicGameSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionGameProcedureResult {
+    pub ok: bool,
+    pub game: Option<GameDistributionPublicGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionGameProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_snapshot_type.rs
new file mode 100644
index 000000000..555f390bf
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_snapshot_type.rs
@@ -0,0 +1,37 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionGameSnapshot {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: String,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub publication_revision: u64,
+    pub active_version_id: Option<String>,
+    pub visibility: String,
+    pub play_count: u64,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+    pub cover_object_key: Option<String>,
+    pub screenshots_json: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionGameSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_table.rs
new file mode 100644
index 000000000..6c7d304a8
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_table.rs
@@ -0,0 +1,230 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::game_distribution_game_type::GameDistributionGame;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `game_distribution_game`.
+///
+/// Obtain a handle from the [`GameDistributionGameTableAccess::game_distribution_game`] method on [`super::RemoteTables`],
+/// like `ctx.db.game_distribution_game()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_game().on_insert(...)`.
+pub struct GameDistributionGameTableHandle<'ctx> {
+    imp: __sdk::TableHandle<GameDistributionGame>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+/// Lifetime-aware accessor marker for the table `game_distribution_game`.
+pub struct GameDistributionGameTableAccessor;
+
+impl __sdk::TableAccessor<super::RemoteTables> for GameDistributionGameTableAccessor {
+    type Row = GameDistributionGame;
+    type Handle<'db> = GameDistributionGameTableHandle<'db>;
+
+    fn get<'db>(db: &'db super::RemoteTables) -> Self::Handle<'db> {
+        db.game_distribution_game()
+    }
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `game_distribution_game`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait GameDistributionGameTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`GameDistributionGameTableHandle`], which mediates access to the table `game_distribution_game`.
+    fn game_distribution_game(&self) -> GameDistributionGameTableHandle<'_>;
+}
+
+impl GameDistributionGameTableAccess for super::RemoteTables {
+    fn game_distribution_game(&self) -> GameDistributionGameTableHandle<'_> {
+        GameDistributionGameTableHandle {
+            imp: self
+                .imp
+                .get_table::<GameDistributionGame>("game_distribution_game"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct GameDistributionGameInsertCallbackId(__sdk::CallbackId);
+pub struct GameDistributionGameDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableLike for GameDistributionGameTableHandle<'ctx> {
+    type Row = GameDistributionGame;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionGame> + '_ {
+        self.imp.iter()
+    }
+}
+
+impl<'ctx> __sdk::Table for GameDistributionGameTableHandle<'ctx> {
+    type Row = GameDistributionGame;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionGame> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = GameDistributionGameInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameInsertCallbackId {
+        GameDistributionGameInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionGameInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = GameDistributionGameDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameDeleteCallbackId {
+        GameDistributionGameDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionGameDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithInsert for GameDistributionGameTableHandle<'ctx> {
+    type InsertCallbackId = GameDistributionGameInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameInsertCallbackId {
+        GameDistributionGameInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionGameInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithDelete for GameDistributionGameTableHandle<'ctx> {
+    type DeleteCallbackId = GameDistributionGameDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameDeleteCallbackId {
+        GameDistributionGameDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionGameDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct GameDistributionGameUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for GameDistributionGameTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionGameUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameUpdateCallbackId {
+        GameDistributionGameUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionGameUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithUpdate for GameDistributionGameTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionGameUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionGameUpdateCallbackId {
+        GameDistributionGameUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionGameUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `game_id` unique index on the table `game_distribution_game`,
+/// which allows point queries on the field of the same name
+/// via the [`GameDistributionGameGameIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_game().game_id().find(...)`.
+pub struct GameDistributionGameGameIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<GameDistributionGame, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> GameDistributionGameTableHandle<'ctx> {
+    /// Get a handle on the `game_id` unique index on the table `game_distribution_game`.
+    pub fn game_id(&self) -> GameDistributionGameGameIdUnique<'ctx> {
+        GameDistributionGameGameIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("game_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> GameDistributionGameGameIdUnique<'ctx> {
+    /// Find the subscribed row whose `game_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<GameDistributionGame> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<GameDistributionGame>("game_distribution_game");
+    _table.add_unique_constraint::<String>("game_id", |row| &row.game_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<GameDistributionGame>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<GameDistributionGame>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `GameDistributionGame`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait game_distribution_gameQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `GameDistributionGame`.
+    fn game_distribution_game(&self) -> __sdk::__query_builder::Table<GameDistributionGame>;
+}
+
+impl game_distribution_gameQueryTableAccess for __sdk::QueryTableAccessor {
+    fn game_distribution_game(&self) -> __sdk::__query_builder::Table<GameDistributionGame> {
+        __sdk::__query_builder::Table::new("game_distribution_game")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_type.rs
new file mode 100644
index 000000000..7236ad64b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_type.rs
@@ -0,0 +1,132 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionGame {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: String,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub publication_revision: u64,
+    pub active_version_id: Option<String>,
+    pub visibility: String,
+    pub play_count: u64,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+    pub local_project_id: Option<String>,
+    pub cover_object_key: Option<String>,
+    pub screenshots_json: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionGame {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `GameDistributionGame`.
+///
+/// Provides typed access to columns for query building.
+pub struct GameDistributionGameCols {
+    pub game_id: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub title: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub summary: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub description: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub category: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub tags_json: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub cover_asset_id: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub author_name: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub author_avatar_url: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub device_support_desktop: __sdk::__query_builder::Col<GameDistributionGame, bool>,
+    pub device_support_mobile: __sdk::__query_builder::Col<GameDistributionGame, bool>,
+    pub device_support_touch: __sdk::__query_builder::Col<GameDistributionGame, bool>,
+    pub input_modes_json: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub orientation: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub publication_revision: __sdk::__query_builder::Col<GameDistributionGame, u64>,
+    pub active_version_id: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub visibility: __sdk::__query_builder::Col<GameDistributionGame, String>,
+    pub play_count: __sdk::__query_builder::Col<GameDistributionGame, u64>,
+    pub created_at: __sdk::__query_builder::Col<GameDistributionGame, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<GameDistributionGame, __sdk::Timestamp>,
+    pub local_project_id: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub cover_object_key: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+    pub screenshots_json: __sdk::__query_builder::Col<GameDistributionGame, Option<String>>,
+}
+
+impl __sdk::__query_builder::HasCols for GameDistributionGame {
+    type Cols = GameDistributionGameCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        GameDistributionGameCols {
+            game_id: __sdk::__query_builder::Col::new(table_name, "game_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            title: __sdk::__query_builder::Col::new(table_name, "title"),
+            summary: __sdk::__query_builder::Col::new(table_name, "summary"),
+            description: __sdk::__query_builder::Col::new(table_name, "description"),
+            category: __sdk::__query_builder::Col::new(table_name, "category"),
+            tags_json: __sdk::__query_builder::Col::new(table_name, "tags_json"),
+            cover_asset_id: __sdk::__query_builder::Col::new(table_name, "cover_asset_id"),
+            author_name: __sdk::__query_builder::Col::new(table_name, "author_name"),
+            author_avatar_url: __sdk::__query_builder::Col::new(table_name, "author_avatar_url"),
+            device_support_desktop: __sdk::__query_builder::Col::new(
+                table_name,
+                "device_support_desktop",
+            ),
+            device_support_mobile: __sdk::__query_builder::Col::new(
+                table_name,
+                "device_support_mobile",
+            ),
+            device_support_touch: __sdk::__query_builder::Col::new(
+                table_name,
+                "device_support_touch",
+            ),
+            input_modes_json: __sdk::__query_builder::Col::new(table_name, "input_modes_json"),
+            orientation: __sdk::__query_builder::Col::new(table_name, "orientation"),
+            publication_revision: __sdk::__query_builder::Col::new(
+                table_name,
+                "publication_revision",
+            ),
+            active_version_id: __sdk::__query_builder::Col::new(table_name, "active_version_id"),
+            visibility: __sdk::__query_builder::Col::new(table_name, "visibility"),
+            play_count: __sdk::__query_builder::Col::new(table_name, "play_count"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            local_project_id: __sdk::__query_builder::Col::new(table_name, "local_project_id"),
+            cover_object_key: __sdk::__query_builder::Col::new(table_name, "cover_object_key"),
+            screenshots_json: __sdk::__query_builder::Col::new(table_name, "screenshots_json"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `GameDistributionGame`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct GameDistributionGameIxCols {
+    pub game_id: __sdk::__query_builder::IxCol<GameDistributionGame, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<GameDistributionGame, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for GameDistributionGame {
+    type IxCols = GameDistributionGameIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        GameDistributionGameIxCols {
+            game_id: __sdk::__query_builder::IxCol::new(table_name, "game_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for GameDistributionGame {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_get_game_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_get_game_input_type.rs
new file mode 100644
index 000000000..e775ab26e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_get_game_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionGetGameInput {
+    pub game_id: String,
+    pub owner_user_id: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionGetGameInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_table.rs
new file mode 100644
index 000000000..582ea41cc
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_table.rs
@@ -0,0 +1,243 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::game_distribution_idempotency_receipt_type::GameDistributionIdempotencyReceipt;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `game_distribution_idempotency_receipt`.
+///
+/// Obtain a handle from the [`GameDistributionIdempotencyReceiptTableAccess::game_distribution_idempotency_receipt`] method on [`super::RemoteTables`],
+/// like `ctx.db.game_distribution_idempotency_receipt()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_idempotency_receipt().on_insert(...)`.
+pub struct GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    imp: __sdk::TableHandle<GameDistributionIdempotencyReceipt>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+/// Lifetime-aware accessor marker for the table `game_distribution_idempotency_receipt`.
+pub struct GameDistributionIdempotencyReceiptTableAccessor;
+
+impl __sdk::TableAccessor<super::RemoteTables> for GameDistributionIdempotencyReceiptTableAccessor {
+    type Row = GameDistributionIdempotencyReceipt;
+    type Handle<'db> = GameDistributionIdempotencyReceiptTableHandle<'db>;
+
+    fn get<'db>(db: &'db super::RemoteTables) -> Self::Handle<'db> {
+        db.game_distribution_idempotency_receipt()
+    }
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `game_distribution_idempotency_receipt`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait GameDistributionIdempotencyReceiptTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`GameDistributionIdempotencyReceiptTableHandle`], which mediates access to the table `game_distribution_idempotency_receipt`.
+    fn game_distribution_idempotency_receipt(
+        &self,
+    ) -> GameDistributionIdempotencyReceiptTableHandle<'_>;
+}
+
+impl GameDistributionIdempotencyReceiptTableAccess for super::RemoteTables {
+    fn game_distribution_idempotency_receipt(
+        &self,
+    ) -> GameDistributionIdempotencyReceiptTableHandle<'_> {
+        GameDistributionIdempotencyReceiptTableHandle {
+            imp: self.imp.get_table::<GameDistributionIdempotencyReceipt>(
+                "game_distribution_idempotency_receipt",
+            ),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct GameDistributionIdempotencyReceiptInsertCallbackId(__sdk::CallbackId);
+pub struct GameDistributionIdempotencyReceiptDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableLike for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type Row = GameDistributionIdempotencyReceipt;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionIdempotencyReceipt> + '_ {
+        self.imp.iter()
+    }
+}
+
+impl<'ctx> __sdk::Table for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type Row = GameDistributionIdempotencyReceipt;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionIdempotencyReceipt> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = GameDistributionIdempotencyReceiptInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptInsertCallbackId {
+        GameDistributionIdempotencyReceiptInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionIdempotencyReceiptInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = GameDistributionIdempotencyReceiptDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptDeleteCallbackId {
+        GameDistributionIdempotencyReceiptDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionIdempotencyReceiptDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithInsert for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type InsertCallbackId = GameDistributionIdempotencyReceiptInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptInsertCallbackId {
+        GameDistributionIdempotencyReceiptInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionIdempotencyReceiptInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithDelete for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type DeleteCallbackId = GameDistributionIdempotencyReceiptDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptDeleteCallbackId {
+        GameDistributionIdempotencyReceiptDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionIdempotencyReceiptDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct GameDistributionIdempotencyReceiptUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionIdempotencyReceiptUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptUpdateCallbackId {
+        GameDistributionIdempotencyReceiptUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionIdempotencyReceiptUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithUpdate for GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionIdempotencyReceiptUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionIdempotencyReceiptUpdateCallbackId {
+        GameDistributionIdempotencyReceiptUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionIdempotencyReceiptUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `receipt_id` unique index on the table `game_distribution_idempotency_receipt`,
+/// which allows point queries on the field of the same name
+/// via the [`GameDistributionIdempotencyReceiptReceiptIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_idempotency_receipt().receipt_id().find(...)`.
+pub struct GameDistributionIdempotencyReceiptReceiptIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<GameDistributionIdempotencyReceipt, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> GameDistributionIdempotencyReceiptTableHandle<'ctx> {
+    /// Get a handle on the `receipt_id` unique index on the table `game_distribution_idempotency_receipt`.
+    pub fn receipt_id(&self) -> GameDistributionIdempotencyReceiptReceiptIdUnique<'ctx> {
+        GameDistributionIdempotencyReceiptReceiptIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("receipt_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> GameDistributionIdempotencyReceiptReceiptIdUnique<'ctx> {
+    /// Find the subscribed row whose `receipt_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<GameDistributionIdempotencyReceipt> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<GameDistributionIdempotencyReceipt>(
+        "game_distribution_idempotency_receipt",
+    );
+    _table.add_unique_constraint::<String>("receipt_id", |row| &row.receipt_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<GameDistributionIdempotencyReceipt>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse(
+            "TableUpdate<GameDistributionIdempotencyReceipt>",
+            "TableUpdate",
+        )
+        .with_cause(e)
+        .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `GameDistributionIdempotencyReceipt`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait game_distribution_idempotency_receiptQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `GameDistributionIdempotencyReceipt`.
+    fn game_distribution_idempotency_receipt(
+        &self,
+    ) -> __sdk::__query_builder::Table<GameDistributionIdempotencyReceipt>;
+}
+
+impl game_distribution_idempotency_receiptQueryTableAccess for __sdk::QueryTableAccessor {
+    fn game_distribution_idempotency_receipt(
+        &self,
+    ) -> __sdk::__query_builder::Table<GameDistributionIdempotencyReceipt> {
+        __sdk::__query_builder::Table::new("game_distribution_idempotency_receipt")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_type.rs
new file mode 100644
index 000000000..eb58a1ff4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_idempotency_receipt_type.rs
@@ -0,0 +1,101 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionIdempotencyReceipt {
+    pub receipt_id: String,
+    pub owner_user_id: String,
+    pub action: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub game_id: Option<String>,
+    pub version_id: Option<String>,
+    pub outcome_kind: String,
+    pub outcome_game_id: Option<String>,
+    pub outcome_version_id: Option<String>,
+    pub outcome_json: Option<String>,
+    pub created_at: __sdk::Timestamp,
+    pub expires_at: __sdk::Timestamp,
+    pub completed_at: Option<__sdk::Timestamp>,
+}
+
+impl __sdk::InModule for GameDistributionIdempotencyReceipt {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `GameDistributionIdempotencyReceipt`.
+///
+/// Provides typed access to columns for query building.
+pub struct GameDistributionIdempotencyReceiptCols {
+    pub receipt_id: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub action: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub idempotency_key: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub request_digest: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub game_id: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub version_id: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub outcome_kind: __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, String>,
+    pub outcome_game_id:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub outcome_version_id:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub outcome_json:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub created_at:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, __sdk::Timestamp>,
+    pub expires_at:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, __sdk::Timestamp>,
+    pub completed_at:
+        __sdk::__query_builder::Col<GameDistributionIdempotencyReceipt, Option<__sdk::Timestamp>>,
+}
+
+impl __sdk::__query_builder::HasCols for GameDistributionIdempotencyReceipt {
+    type Cols = GameDistributionIdempotencyReceiptCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        GameDistributionIdempotencyReceiptCols {
+            receipt_id: __sdk::__query_builder::Col::new(table_name, "receipt_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            action: __sdk::__query_builder::Col::new(table_name, "action"),
+            idempotency_key: __sdk::__query_builder::Col::new(table_name, "idempotency_key"),
+            request_digest: __sdk::__query_builder::Col::new(table_name, "request_digest"),
+            game_id: __sdk::__query_builder::Col::new(table_name, "game_id"),
+            version_id: __sdk::__query_builder::Col::new(table_name, "version_id"),
+            outcome_kind: __sdk::__query_builder::Col::new(table_name, "outcome_kind"),
+            outcome_game_id: __sdk::__query_builder::Col::new(table_name, "outcome_game_id"),
+            outcome_version_id: __sdk::__query_builder::Col::new(table_name, "outcome_version_id"),
+            outcome_json: __sdk::__query_builder::Col::new(table_name, "outcome_json"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            expires_at: __sdk::__query_builder::Col::new(table_name, "expires_at"),
+            completed_at: __sdk::__query_builder::Col::new(table_name, "completed_at"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `GameDistributionIdempotencyReceipt`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct GameDistributionIdempotencyReceiptIxCols {
+    pub game_id: __sdk::__query_builder::IxCol<GameDistributionIdempotencyReceipt, Option<String>>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<GameDistributionIdempotencyReceipt, String>,
+    pub receipt_id: __sdk::__query_builder::IxCol<GameDistributionIdempotencyReceipt, String>,
+    pub version_id:
+        __sdk::__query_builder::IxCol<GameDistributionIdempotencyReceipt, Option<String>>,
+}
+
+impl __sdk::__query_builder::HasIxCols for GameDistributionIdempotencyReceipt {
+    type IxCols = GameDistributionIdempotencyReceiptIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        GameDistributionIdempotencyReceiptIxCols {
+            game_id: __sdk::__query_builder::IxCol::new(table_name, "game_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+            receipt_id: __sdk::__query_builder::IxCol::new(table_name, "receipt_id"),
+            version_id: __sdk::__query_builder::IxCol::new(table_name, "version_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for GameDistributionIdempotencyReceipt {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_input_type.rs
new file mode 100644
index 000000000..0eff02fb8
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionOwnerGameListInput {
+    pub owner_user_id: String,
+    pub limit: u32,
+}
+
+impl __sdk::InModule for GameDistributionOwnerGameListInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_procedure_result_type.rs
new file mode 100644
index 000000000..4bedf5e9f
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_list_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_owner_game_snapshot_type::GameDistributionOwnerGameSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionOwnerGameListProcedureResult {
+    pub ok: bool,
+    pub games: Vec<GameDistributionOwnerGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionOwnerGameListProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_snapshot_type.rs
new file mode 100644
index 000000000..67a5946db
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_game_snapshot_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_game_snapshot_type::GameDistributionGameSnapshot;
+use super::game_distribution_version_snapshot_type::GameDistributionVersionSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionOwnerGameSnapshot {
+    pub game: GameDistributionGameSnapshot,
+    pub versions: Vec<GameDistributionVersionSnapshot>,
+}
+
+impl __sdk::InModule for GameDistributionOwnerGameSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_version_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_version_input_type.rs
new file mode 100644
index 000000000..5c8a1316d
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_owner_version_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionOwnerVersionInput {
+    pub owner_user_id: String,
+    pub version_id: String,
+}
+
+impl __sdk::InModule for GameDistributionOwnerVersionInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_procedure_result_type.rs
new file mode 100644
index 000000000..e27d1fad4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_procedure_result_type.rs
@@ -0,0 +1,25 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_game_snapshot_type::GameDistributionGameSnapshot;
+use super::game_distribution_version_snapshot_type::GameDistributionVersionSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionProcedureResult {
+    pub ok: bool,
+    pub replayed: bool,
+    pub game: Option<GameDistributionGameSnapshot>,
+    pub games: Vec<GameDistributionGameSnapshot>,
+    pub version: Option<GameDistributionVersionSnapshot>,
+    pub versions: Vec<GameDistributionVersionSnapshot>,
+    pub next_cursor: Option<String>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_input_type.rs
new file mode 100644
index 000000000..1315ec6a3
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionPublicGameInput {
+    pub game_id: String,
+}
+
+impl __sdk::InModule for GameDistributionPublicGameInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_list_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_list_input_type.rs
new file mode 100644
index 000000000..1d02c17ab
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_list_input_type.rs
@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionPublicGameListInput {
+    pub search: Option<String>,
+    pub category: Option<String>,
+    pub limit: u32,
+}
+
+impl __sdk::InModule for GameDistributionPublicGameListInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_snapshot_type.rs
new file mode 100644
index 000000000..554c13887
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_public_game_snapshot_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_game_snapshot_type::GameDistributionGameSnapshot;
+use super::game_distribution_version_snapshot_type::GameDistributionVersionSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionPublicGameSnapshot {
+    pub game: GameDistributionGameSnapshot,
+    pub current_version: Option<GameDistributionVersionSnapshot>,
+}
+
+impl __sdk::InModule for GameDistributionPublicGameSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_reject_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_reject_input_type.rs
new file mode 100644
index 000000000..f347cb694
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_reject_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionRejectInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub review_reason: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionRejectInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_review_list_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_review_list_input_type.rs
new file mode 100644
index 000000000..dd4933377
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_review_list_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionReviewListInput {
+    pub limit: u32,
+}
+
+impl __sdk::InModule for GameDistributionReviewListInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_submit_review_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_submit_review_input_type.rs
new file mode 100644
index 000000000..a85ca148d
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_submit_review_input_type.rs
@@ -0,0 +1,20 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionSubmitReviewInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionSubmitReviewInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_suspend_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_suspend_input_type.rs
new file mode 100644
index 000000000..192323a50
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_suspend_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionSuspendInput {
+    pub game_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub reason: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionSuspendInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_unpublish_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_unpublish_input_type.rs
new file mode 100644
index 000000000..7439906ee
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_unpublish_input_type.rs
@@ -0,0 +1,20 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionUnpublishInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for GameDistributionUnpublishInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_lookup_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_lookup_input_type.rs
new file mode 100644
index 000000000..df63e6f7f
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_lookup_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionVersionLookupInput {
+    pub version_id: String,
+}
+
+impl __sdk::InModule for GameDistributionVersionLookupInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_procedure_result_type.rs
new file mode 100644
index 000000000..5e5cb747e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_version_snapshot_type::GameDistributionVersionSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionVersionProcedureResult {
+    pub ok: bool,
+    pub version: Option<GameDistributionVersionSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionVersionProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_snapshot_type.rs
new file mode 100644
index 000000000..7acae2d7c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_snapshot_type.rs
@@ -0,0 +1,29 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionVersionSnapshot {
+    pub version_id: String,
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_number: u64,
+    pub package_sha_256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub status: String,
+    pub review_reason: Option<String>,
+    pub entry_url: Option<String>,
+    pub publication_revision: u64,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+    pub metadata_json: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionVersionSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_table.rs
new file mode 100644
index 000000000..e73257b66
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_table.rs
@@ -0,0 +1,231 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::game_distribution_version_type::GameDistributionVersion;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `game_distribution_version`.
+///
+/// Obtain a handle from the [`GameDistributionVersionTableAccess::game_distribution_version`] method on [`super::RemoteTables`],
+/// like `ctx.db.game_distribution_version()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_version().on_insert(...)`.
+pub struct GameDistributionVersionTableHandle<'ctx> {
+    imp: __sdk::TableHandle<GameDistributionVersion>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+/// Lifetime-aware accessor marker for the table `game_distribution_version`.
+pub struct GameDistributionVersionTableAccessor;
+
+impl __sdk::TableAccessor<super::RemoteTables> for GameDistributionVersionTableAccessor {
+    type Row = GameDistributionVersion;
+    type Handle<'db> = GameDistributionVersionTableHandle<'db>;
+
+    fn get<'db>(db: &'db super::RemoteTables) -> Self::Handle<'db> {
+        db.game_distribution_version()
+    }
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `game_distribution_version`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait GameDistributionVersionTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`GameDistributionVersionTableHandle`], which mediates access to the table `game_distribution_version`.
+    fn game_distribution_version(&self) -> GameDistributionVersionTableHandle<'_>;
+}
+
+impl GameDistributionVersionTableAccess for super::RemoteTables {
+    fn game_distribution_version(&self) -> GameDistributionVersionTableHandle<'_> {
+        GameDistributionVersionTableHandle {
+            imp: self
+                .imp
+                .get_table::<GameDistributionVersion>("game_distribution_version"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct GameDistributionVersionInsertCallbackId(__sdk::CallbackId);
+pub struct GameDistributionVersionDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableLike for GameDistributionVersionTableHandle<'ctx> {
+    type Row = GameDistributionVersion;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionVersion> + '_ {
+        self.imp.iter()
+    }
+}
+
+impl<'ctx> __sdk::Table for GameDistributionVersionTableHandle<'ctx> {
+    type Row = GameDistributionVersion;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = GameDistributionVersion> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = GameDistributionVersionInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionInsertCallbackId {
+        GameDistributionVersionInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionVersionInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = GameDistributionVersionDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionDeleteCallbackId {
+        GameDistributionVersionDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionVersionDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithInsert for GameDistributionVersionTableHandle<'ctx> {
+    type InsertCallbackId = GameDistributionVersionInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionInsertCallbackId {
+        GameDistributionVersionInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: GameDistributionVersionInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithDelete for GameDistributionVersionTableHandle<'ctx> {
+    type DeleteCallbackId = GameDistributionVersionDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionDeleteCallbackId {
+        GameDistributionVersionDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: GameDistributionVersionDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct GameDistributionVersionUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for GameDistributionVersionTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionVersionUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionUpdateCallbackId {
+        GameDistributionVersionUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionVersionUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+impl<'ctx> __sdk::WithUpdate for GameDistributionVersionTableHandle<'ctx> {
+    type UpdateCallbackId = GameDistributionVersionUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> GameDistributionVersionUpdateCallbackId {
+        GameDistributionVersionUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: GameDistributionVersionUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `version_id` unique index on the table `game_distribution_version`,
+/// which allows point queries on the field of the same name
+/// via the [`GameDistributionVersionVersionIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.game_distribution_version().version_id().find(...)`.
+pub struct GameDistributionVersionVersionIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<GameDistributionVersion, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> GameDistributionVersionTableHandle<'ctx> {
+    /// Get a handle on the `version_id` unique index on the table `game_distribution_version`.
+    pub fn version_id(&self) -> GameDistributionVersionVersionIdUnique<'ctx> {
+        GameDistributionVersionVersionIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("version_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> GameDistributionVersionVersionIdUnique<'ctx> {
+    /// Find the subscribed row whose `version_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<GameDistributionVersion> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table =
+        client_cache.get_or_make_table::<GameDistributionVersion>("game_distribution_version");
+    _table.add_unique_constraint::<String>("version_id", |row| &row.version_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<GameDistributionVersion>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<GameDistributionVersion>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `GameDistributionVersion`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait game_distribution_versionQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `GameDistributionVersion`.
+    fn game_distribution_version(&self) -> __sdk::__query_builder::Table<GameDistributionVersion>;
+}
+
+impl game_distribution_versionQueryTableAccess for __sdk::QueryTableAccessor {
+    fn game_distribution_version(&self) -> __sdk::__query_builder::Table<GameDistributionVersion> {
+        __sdk::__query_builder::Table::new("game_distribution_version")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_type.rs
new file mode 100644
index 000000000..05d3c3cdb
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/game_distribution_version_type.rs
@@ -0,0 +1,133 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct GameDistributionVersion {
+    pub version_id: String,
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_number: u64,
+    pub package_sha_256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub status: String,
+    pub review_reason: Option<String>,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+    pub local_project_id: Option<String>,
+    pub package_object_key: Option<String>,
+    pub package_manifest_json: Option<String>,
+    pub entry_url: Option<String>,
+    pub reviewed_by_user_id: Option<String>,
+    pub uploaded_at: Option<__sdk::Timestamp>,
+    pub submitted_at: Option<__sdk::Timestamp>,
+    pub reviewed_at: Option<__sdk::Timestamp>,
+    pub published_at: Option<__sdk::Timestamp>,
+    pub revoked_at: Option<__sdk::Timestamp>,
+    pub last_error_code: Option<String>,
+    pub last_error_message: Option<String>,
+    pub metadata_json: Option<String>,
+}
+
+impl __sdk::InModule for GameDistributionVersion {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `GameDistributionVersion`.
+///
+/// Provides typed access to columns for query building.
+pub struct GameDistributionVersionCols {
+    pub version_id: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub game_id: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub version_number: __sdk::__query_builder::Col<GameDistributionVersion, u64>,
+    pub package_sha_256: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub package_bytes: __sdk::__query_builder::Col<GameDistributionVersion, u64>,
+    pub package_file_count: __sdk::__query_builder::Col<GameDistributionVersion, u32>,
+    pub package_entry_path: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub status: __sdk::__query_builder::Col<GameDistributionVersion, String>,
+    pub review_reason: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub created_at: __sdk::__query_builder::Col<GameDistributionVersion, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<GameDistributionVersion, __sdk::Timestamp>,
+    pub local_project_id: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub package_object_key: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub package_manifest_json: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub entry_url: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub reviewed_by_user_id: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub uploaded_at: __sdk::__query_builder::Col<GameDistributionVersion, Option<__sdk::Timestamp>>,
+    pub submitted_at:
+        __sdk::__query_builder::Col<GameDistributionVersion, Option<__sdk::Timestamp>>,
+    pub reviewed_at: __sdk::__query_builder::Col<GameDistributionVersion, Option<__sdk::Timestamp>>,
+    pub published_at:
+        __sdk::__query_builder::Col<GameDistributionVersion, Option<__sdk::Timestamp>>,
+    pub revoked_at: __sdk::__query_builder::Col<GameDistributionVersion, Option<__sdk::Timestamp>>,
+    pub last_error_code: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub last_error_message: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+    pub metadata_json: __sdk::__query_builder::Col<GameDistributionVersion, Option<String>>,
+}
+
+impl __sdk::__query_builder::HasCols for GameDistributionVersion {
+    type Cols = GameDistributionVersionCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        GameDistributionVersionCols {
+            version_id: __sdk::__query_builder::Col::new(table_name, "version_id"),
+            game_id: __sdk::__query_builder::Col::new(table_name, "game_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            version_number: __sdk::__query_builder::Col::new(table_name, "version_number"),
+            package_sha_256: __sdk::__query_builder::Col::new(table_name, "package_sha_256"),
+            package_bytes: __sdk::__query_builder::Col::new(table_name, "package_bytes"),
+            package_file_count: __sdk::__query_builder::Col::new(table_name, "package_file_count"),
+            package_entry_path: __sdk::__query_builder::Col::new(table_name, "package_entry_path"),
+            status: __sdk::__query_builder::Col::new(table_name, "status"),
+            review_reason: __sdk::__query_builder::Col::new(table_name, "review_reason"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            local_project_id: __sdk::__query_builder::Col::new(table_name, "local_project_id"),
+            package_object_key: __sdk::__query_builder::Col::new(table_name, "package_object_key"),
+            package_manifest_json: __sdk::__query_builder::Col::new(
+                table_name,
+                "package_manifest_json",
+            ),
+            entry_url: __sdk::__query_builder::Col::new(table_name, "entry_url"),
+            reviewed_by_user_id: __sdk::__query_builder::Col::new(
+                table_name,
+                "reviewed_by_user_id",
+            ),
+            uploaded_at: __sdk::__query_builder::Col::new(table_name, "uploaded_at"),
+            submitted_at: __sdk::__query_builder::Col::new(table_name, "submitted_at"),
+            reviewed_at: __sdk::__query_builder::Col::new(table_name, "reviewed_at"),
+            published_at: __sdk::__query_builder::Col::new(table_name, "published_at"),
+            revoked_at: __sdk::__query_builder::Col::new(table_name, "revoked_at"),
+            last_error_code: __sdk::__query_builder::Col::new(table_name, "last_error_code"),
+            last_error_message: __sdk::__query_builder::Col::new(table_name, "last_error_message"),
+            metadata_json: __sdk::__query_builder::Col::new(table_name, "metadata_json"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `GameDistributionVersion`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct GameDistributionVersionIxCols {
+    pub game_id: __sdk::__query_builder::IxCol<GameDistributionVersion, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<GameDistributionVersion, String>,
+    pub version_id: __sdk::__query_builder::IxCol<GameDistributionVersion, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for GameDistributionVersion {
+    type IxCols = GameDistributionVersionIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        GameDistributionVersionIxCols {
+            game_id: __sdk::__query_builder::IxCol::new(table_name, "game_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+            version_id: __sdk::__query_builder::IxCol::new(table_name, "version_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for GameDistributionVersion {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_game_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_game_and_return_procedure.rs
new file mode 100644
index 000000000..823d4f2e3
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_game_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_get_game_input_type::GameDistributionGetGameInput;
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetGameDistributionGameAndReturnArgs {
+    pub input: GameDistributionGetGameInput,
+}
+
+impl __sdk::InModule for GetGameDistributionGameAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_game_distribution_game_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_game_distribution_game_and_return {
+    fn get_game_distribution_game_and_return(&self, input: GameDistributionGetGameInput) {
+        self.get_game_distribution_game_and_return_then(input, |_, _| {});
+    }
+
+    fn get_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionGetGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_game_distribution_game_and_return for super::RemoteProcedures {
+    fn get_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionGetGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "get_game_distribution_game_and_return",
+                GetGameDistributionGameAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..41de8b95f
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_version_lookup_input_type::GameDistributionVersionLookupInput;
+use super::game_distribution_version_procedure_result_type::GameDistributionVersionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionVersionLookupInput,
+}
+
+impl __sdk::InModule for GetGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_game_distribution_version_and_return {
+    fn get_game_distribution_version_and_return(&self, input: GameDistributionVersionLookupInput) {
+        self.get_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn get_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionVersionLookupInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionVersionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_game_distribution_version_and_return for super::RemoteProcedures {
+    fn get_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionVersionLookupInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionVersionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionVersionProcedureResult>(
+                "get_game_distribution_version_and_return",
+                GetGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_owner_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_owner_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..d4cd499f9
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_owner_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_owner_version_input_type::GameDistributionOwnerVersionInput;
+use super::game_distribution_version_procedure_result_type::GameDistributionVersionProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetOwnerGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionOwnerVersionInput,
+}
+
+impl __sdk::InModule for GetOwnerGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_owner_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_owner_game_distribution_version_and_return {
+    fn get_owner_game_distribution_version_and_return(
+        &self,
+        input: GameDistributionOwnerVersionInput,
+    ) {
+        self.get_owner_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn get_owner_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionOwnerVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionVersionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_owner_game_distribution_version_and_return for super::RemoteProcedures {
+    fn get_owner_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionOwnerVersionInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionVersionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionVersionProcedureResult>(
+                "get_owner_game_distribution_version_and_return",
+                GetOwnerGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_public_game_distribution_game_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_public_game_distribution_game_and_return_procedure.rs
new file mode 100644
index 000000000..7ed9a62a0
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_public_game_distribution_game_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_game_procedure_result_type::GameDistributionGameProcedureResult;
+use super::game_distribution_public_game_input_type::GameDistributionPublicGameInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetPublicGameDistributionGameAndReturnArgs {
+    pub input: GameDistributionPublicGameInput,
+}
+
+impl __sdk::InModule for GetPublicGameDistributionGameAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_public_game_distribution_game_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_public_game_distribution_game_and_return {
+    fn get_public_game_distribution_game_and_return(&self, input: GameDistributionPublicGameInput) {
+        self.get_public_game_distribution_game_and_return_then(input, |_, _| {});
+    }
+
+    fn get_public_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionPublicGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionGameProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_public_game_distribution_game_and_return for super::RemoteProcedures {
+    fn get_public_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionPublicGameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionGameProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionGameProcedureResult>(
+                "get_public_game_distribution_game_and_return",
+                GetPublicGameDistributionGameAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_games_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_games_and_return_procedure.rs
new file mode 100644
index 000000000..7c75774e5
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_games_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_public_game_list_input_type::GameDistributionPublicGameListInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListGameDistributionGamesAndReturnArgs {
+    pub input: GameDistributionPublicGameListInput,
+}
+
+impl __sdk::InModule for ListGameDistributionGamesAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_game_distribution_games_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_game_distribution_games_and_return {
+    fn list_game_distribution_games_and_return(&self, input: GameDistributionPublicGameListInput) {
+        self.list_game_distribution_games_and_return_then(input, |_, _| {});
+    }
+
+    fn list_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionPublicGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_game_distribution_games_and_return for super::RemoteProcedures {
+    fn list_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionPublicGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "list_game_distribution_games_and_return",
+                ListGameDistributionGamesAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_reviews_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_reviews_and_return_procedure.rs
new file mode 100644
index 000000000..0edb574ed
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_game_distribution_reviews_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_review_list_input_type::GameDistributionReviewListInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListGameDistributionReviewsAndReturnArgs {
+    pub input: GameDistributionReviewListInput,
+}
+
+impl __sdk::InModule for ListGameDistributionReviewsAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_game_distribution_reviews_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_game_distribution_reviews_and_return {
+    fn list_game_distribution_reviews_and_return(&self, input: GameDistributionReviewListInput) {
+        self.list_game_distribution_reviews_and_return_then(input, |_, _| {});
+    }
+
+    fn list_game_distribution_reviews_and_return_then(
+        &self,
+        input: GameDistributionReviewListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_game_distribution_reviews_and_return for super::RemoteProcedures {
+    fn list_game_distribution_reviews_and_return_then(
+        &self,
+        input: GameDistributionReviewListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "list_game_distribution_reviews_and_return",
+                ListGameDistributionReviewsAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_owner_game_distribution_games_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_owner_game_distribution_games_and_return_procedure.rs
new file mode 100644
index 000000000..9e495141d
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_owner_game_distribution_games_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_owner_game_list_input_type::GameDistributionOwnerGameListInput;
+use super::game_distribution_owner_game_list_procedure_result_type::GameDistributionOwnerGameListProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListOwnerGameDistributionGamesAndReturnArgs {
+    pub input: GameDistributionOwnerGameListInput,
+}
+
+impl __sdk::InModule for ListOwnerGameDistributionGamesAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_owner_game_distribution_games_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_owner_game_distribution_games_and_return {
+    fn list_owner_game_distribution_games_and_return(
+        &self,
+        input: GameDistributionOwnerGameListInput,
+    ) {
+        self.list_owner_game_distribution_games_and_return_then(input, |_, _| {});
+    }
+
+    fn list_owner_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionOwnerGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionOwnerGameListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_owner_game_distribution_games_and_return for super::RemoteProcedures {
+    fn list_owner_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionOwnerGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionOwnerGameListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionOwnerGameListProcedureResult>(
+                "list_owner_game_distribution_games_and_return",
+                ListOwnerGameDistributionGamesAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_public_game_distribution_games_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_public_game_distribution_games_and_return_procedure.rs
new file mode 100644
index 000000000..90efdc26b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_public_game_distribution_games_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_game_list_procedure_result_type::GameDistributionGameListProcedureResult;
+use super::game_distribution_public_game_list_input_type::GameDistributionPublicGameListInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListPublicGameDistributionGamesAndReturnArgs {
+    pub input: GameDistributionPublicGameListInput,
+}
+
+impl __sdk::InModule for ListPublicGameDistributionGamesAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_public_game_distribution_games_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_public_game_distribution_games_and_return {
+    fn list_public_game_distribution_games_and_return(
+        &self,
+        input: GameDistributionPublicGameListInput,
+    ) {
+        self.list_public_game_distribution_games_and_return_then(input, |_, _| {});
+    }
+
+    fn list_public_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionPublicGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionGameListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_public_game_distribution_games_and_return for super::RemoteProcedures {
+    fn list_public_game_distribution_games_and_return_then(
+        &self,
+        input: GameDistributionPublicGameListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionGameListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionGameListProcedureResult>(
+                "list_public_game_distribution_games_and_return",
+                ListPublicGameDistributionGamesAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/reject_game_distribution_version_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/reject_game_distribution_version_and_return_procedure.rs
new file mode 100644
index 000000000..c1a720f7b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/reject_game_distribution_version_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_reject_input_type::GameDistributionRejectInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct RejectGameDistributionVersionAndReturnArgs {
+    pub input: GameDistributionRejectInput,
+}
+
+impl __sdk::InModule for RejectGameDistributionVersionAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `reject_game_distribution_version_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait reject_game_distribution_version_and_return {
+    fn reject_game_distribution_version_and_return(&self, input: GameDistributionRejectInput) {
+        self.reject_game_distribution_version_and_return_then(input, |_, _| {});
+    }
+
+    fn reject_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionRejectInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl reject_game_distribution_version_and_return for super::RemoteProcedures {
+    fn reject_game_distribution_version_and_return_then(
+        &self,
+        input: GameDistributionRejectInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "reject_game_distribution_version_and_return",
+                RejectGameDistributionVersionAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/submit_game_distribution_version_for_review_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/submit_game_distribution_version_for_review_and_return_procedure.rs
new file mode 100644
index 000000000..f68aeb183
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/submit_game_distribution_version_for_review_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_submit_review_input_type::GameDistributionSubmitReviewInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct SubmitGameDistributionVersionForReviewAndReturnArgs {
+    pub input: GameDistributionSubmitReviewInput,
+}
+
+impl __sdk::InModule for SubmitGameDistributionVersionForReviewAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `submit_game_distribution_version_for_review_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait submit_game_distribution_version_for_review_and_return {
+    fn submit_game_distribution_version_for_review_and_return(
+        &self,
+        input: GameDistributionSubmitReviewInput,
+    ) {
+        self.submit_game_distribution_version_for_review_and_return_then(input, |_, _| {});
+    }
+
+    fn submit_game_distribution_version_for_review_and_return_then(
+        &self,
+        input: GameDistributionSubmitReviewInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl submit_game_distribution_version_for_review_and_return for super::RemoteProcedures {
+    fn submit_game_distribution_version_for_review_and_return_then(
+        &self,
+        input: GameDistributionSubmitReviewInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "submit_game_distribution_version_for_review_and_return",
+                SubmitGameDistributionVersionForReviewAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/suspend_game_distribution_game_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/suspend_game_distribution_game_and_return_procedure.rs
new file mode 100644
index 000000000..e13060da1
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/suspend_game_distribution_game_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_suspend_input_type::GameDistributionSuspendInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct SuspendGameDistributionGameAndReturnArgs {
+    pub input: GameDistributionSuspendInput,
+}
+
+impl __sdk::InModule for SuspendGameDistributionGameAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `suspend_game_distribution_game_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait suspend_game_distribution_game_and_return {
+    fn suspend_game_distribution_game_and_return(&self, input: GameDistributionSuspendInput) {
+        self.suspend_game_distribution_game_and_return_then(input, |_, _| {});
+    }
+
+    fn suspend_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionSuspendInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl suspend_game_distribution_game_and_return for super::RemoteProcedures {
+    fn suspend_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionSuspendInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "suspend_game_distribution_game_and_return",
+                SuspendGameDistributionGameAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/unpublish_game_distribution_game_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/unpublish_game_distribution_game_and_return_procedure.rs
new file mode 100644
index 000000000..190b12f0c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/unpublish_game_distribution_game_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::game_distribution_procedure_result_type::GameDistributionProcedureResult;
+use super::game_distribution_unpublish_input_type::GameDistributionUnpublishInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct UnpublishGameDistributionGameAndReturnArgs {
+    pub input: GameDistributionUnpublishInput,
+}
+
+impl __sdk::InModule for UnpublishGameDistributionGameAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `unpublish_game_distribution_game_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait unpublish_game_distribution_game_and_return {
+    fn unpublish_game_distribution_game_and_return(&self, input: GameDistributionUnpublishInput) {
+        self.unpublish_game_distribution_game_and_return_then(input, |_, _| {});
+    }
+
+    fn unpublish_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionUnpublishInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl unpublish_game_distribution_game_and_return for super::RemoteProcedures {
+    fn unpublish_game_distribution_game_and_return_then(
+        &self,
+        input: GameDistributionUnpublishInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<GameDistributionProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, GameDistributionProcedureResult>(
+                "unpublish_game_distribution_game_and_return",
+                UnpublishGameDistributionGameAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-module/src/active.rs b/server-rs/crates/spacetime-module/src/active.rs
index 837fd2f67..b99d7062f 100644
--- a/server-rs/crates/spacetime-module/src/active.rs
+++ b/server-rs/crates/spacetime-module/src/active.rs
@@ -32,6 +32,7 @@ mod editor_project_storage;
 mod error_reports_schema;
 mod external_api_key_storage;
 mod external_generation;
+mod game_distribution;
 #[path = "legacy_schema/gameplay.rs"]
 mod gameplay;
 #[path = "legacy_schema/jump_hop.rs"]
@@ -67,6 +68,7 @@ pub use editor_project_storage::*;
 pub use error_reports_schema::*;
 pub use external_api_key_storage::*;
 pub use external_generation::*;
+pub use game_distribution::*;
 pub use gameplay::*;
 pub use jump_hop::*;
 pub use llm_router_account_storage::*;
diff --git a/server-rs/crates/spacetime-module/src/editor_project_storage.rs b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
index 1f506eed4..c2de622d6 100644
--- a/server-rs/crates/spacetime-module/src/editor_project_storage.rs
+++ b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
@@ -6329,7 +6329,13 @@ pub(crate) fn asset_location_has_public_showcase_read_grant(
     asset_object: Option<&module_assets::AssetObjectUpsertSnapshot>,
 ) -> bool {
     let asset_object_granted = asset_object
-        .is_some_and(|asset_object| asset_object_has_public_showcase_read_grant(ctx, asset_object));
+        .is_some_and(|asset_object| asset_object_has_public_showcase_read_grant(ctx, asset_object))
+        || asset_object.is_some_and(|asset_object| {
+            crate::game_distribution::game_distribution_asset_has_public_read_grant(
+                ctx,
+                asset_object.asset_object_id.as_str(),
+            )
+        });
     let campaign_config = ctx
         .db
         .editor_showcase_campaign_config()
diff --git a/server-rs/crates/spacetime-module/src/game_distribution.rs b/server-rs/crates/spacetime-module/src/game_distribution.rs
new file mode 100644
index 000000000..53ef0d7d8
--- /dev/null
+++ b/server-rs/crates/spacetime-module/src/game_distribution.rs
@@ -0,0 +1,2333 @@
+use crate::*;
+
+// 游戏分发的持久化事实。状态机和输入校验位于 `module-game-distribution`；这些表只保存
+// owner、版本内容摘要、公开版本 CAS 和可恢复操作收据，HTTP / 对象存储编排留在 api-server。
+
+/// 作者创建的游戏身份及当前公开版本指针。
+///
+/// 资料字段使用 JSON 保存数组，避免为尚未冻结的展示 DTO 引入可破坏的 schema 变更。
+#[spacetimedb::table(
+    accessor = game_distribution_game,
+    index(
+        accessor = by_game_distribution_game_owner_user_id,
+        btree(columns = [owner_user_id])
+    )
+)]
+#[derive(Clone)]
+pub struct GameDistributionGame {
+    #[primary_key]
+    pub(crate) game_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) title: String,
+    pub(crate) summary: String,
+    pub(crate) description: String,
+    pub(crate) category: String,
+    pub(crate) tags_json: String,
+    pub(crate) cover_asset_id: Option<String>,
+    pub(crate) author_name: Option<String>,
+    pub(crate) author_avatar_url: Option<String>,
+    pub(crate) device_support_desktop: bool,
+    pub(crate) device_support_mobile: bool,
+    pub(crate) device_support_touch: bool,
+    pub(crate) input_modes_json: String,
+    pub(crate) orientation: String,
+    pub(crate) publication_revision: u64,
+    pub(crate) active_version_id: Option<String>,
+    pub(crate) visibility: String,
+    pub(crate) play_count: u64,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+    /// AGC / 网页发布方的本地项目标识。只用于同一作者复用游戏身份，不构成所有权证明。
+    #[default(None::<String>)]
+    pub(crate) local_project_id: Option<String>,
+    /// 审核通过后生效的封面对象键；客户端用它换平台签名读地址。
+    #[default(None::<String>)]
+    pub(crate) cover_object_key: Option<String>,
+    /// 审核通过后生效的截图对象键 JSON 数组（与 `cover_asset_id` 同源，来自版本冻结资料）。
+    #[default(None::<String>)]
+    pub(crate) screenshots_json: Option<String>,
+}
+
+/// 游戏发行版本。包摘要、确认字节数和送审资料在创建后作为不可变快照保留；状态和
+/// 审核/对象安装时间由后续事务推进。
+#[spacetimedb::table(
+    accessor = game_distribution_version,
+    index(
+        accessor = by_game_distribution_version_game_id,
+        btree(columns = [game_id])
+    ),
+    index(
+        accessor = by_game_distribution_version_owner_user_id,
+        btree(columns = [owner_user_id])
+    )
+)]
+#[derive(Clone)]
+pub struct GameDistributionVersion {
+    #[primary_key]
+    pub(crate) version_id: String,
+    pub(crate) game_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) version_number: u64,
+    pub(crate) package_sha256: String,
+    pub(crate) package_bytes: u64,
+    pub(crate) package_file_count: u32,
+    pub(crate) package_entry_path: String,
+    pub(crate) status: String,
+    pub(crate) review_reason: Option<String>,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+    #[default(None::<String>)]
+    pub(crate) local_project_id: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) package_object_key: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) package_manifest_json: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) entry_url: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) reviewed_by_user_id: Option<String>,
+    #[default(None::<Timestamp>)]
+    pub(crate) uploaded_at: Option<Timestamp>,
+    #[default(None::<Timestamp>)]
+    pub(crate) submitted_at: Option<Timestamp>,
+    #[default(None::<Timestamp>)]
+    pub(crate) reviewed_at: Option<Timestamp>,
+    #[default(None::<Timestamp>)]
+    pub(crate) published_at: Option<Timestamp>,
+    #[default(None::<Timestamp>)]
+    pub(crate) revoked_at: Option<Timestamp>,
+    #[default(None::<String>)]
+    pub(crate) last_error_code: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) last_error_message: Option<String>,
+    /// 该版本冻结的作者资料快照（JSON，含封面与截图素材键）。审核通过时整体生效。
+    #[default(None::<String>)]
+    pub(crate) metadata_json: Option<String>,
+}
+
+/// 创建、提交、审核、撤回和下架等写操作的幂等收据。
+///
+/// `receipt_id` 由 api-server 按 owner、动作和 key 生成；组合索引供冲突检查和恢复查询
+/// 使用。结果字段只保存可回读的业务 ID，不保存对象存储凭据或完整上传内容。
+#[spacetimedb::table(
+    accessor = game_distribution_idempotency_receipt,
+    index(
+        accessor = by_game_distribution_receipt_owner_user_id,
+        btree(columns = [owner_user_id])
+    ),
+    index(
+        accessor = by_game_distribution_receipt_game_id,
+        btree(columns = [game_id])
+    ),
+    index(
+        accessor = by_game_distribution_receipt_version_id,
+        btree(columns = [version_id])
+    ),
+    index(
+        accessor = by_game_distribution_receipt_scope,
+        btree(columns = [owner_user_id, action, idempotency_key])
+    )
+)]
+pub struct GameDistributionIdempotencyReceipt {
+    #[primary_key]
+    pub(crate) receipt_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) action: String,
+    pub(crate) idempotency_key: String,
+    pub(crate) request_digest: String,
+    pub(crate) game_id: Option<String>,
+    pub(crate) version_id: Option<String>,
+    pub(crate) outcome_kind: String,
+    pub(crate) outcome_game_id: Option<String>,
+    pub(crate) outcome_version_id: Option<String>,
+    pub(crate) outcome_json: Option<String>,
+    pub(crate) created_at: Timestamp,
+    pub(crate) expires_at: Timestamp,
+    #[default(None::<Timestamp>)]
+    pub(crate) completed_at: Option<Timestamp>,
+}
+
+const GAME_DISTRIBUTION_VISIBILITY_UNPUBLISHED: &str = "unpublished";
+const GAME_DISTRIBUTION_VISIBILITY_PUBLISHED: &str = "published";
+const GAME_DISTRIBUTION_VISIBILITY_SUSPENDED: &str = "suspended";
+const GAME_DISTRIBUTION_VERSION_AWAITING_UPLOAD: &str = "awaiting_upload";
+const GAME_DISTRIBUTION_VERSION_UPLOADED: &str = "uploaded";
+const GAME_DISTRIBUTION_VERSION_PUBLISHED: &str = "published";
+const GAME_DISTRIBUTION_VERSION_PENDING_REVIEW: &str = "pending_review";
+const GAME_DISTRIBUTION_VERSION_REJECTED: &str = "rejected";
+const GAME_DISTRIBUTION_VERSION_REVOKED: &str = "revoked";
+const GAME_DISTRIBUTION_VERSION_CANCELLED: &str = "cancelled";
+const GAME_DISTRIBUTION_VERSION_VALIDATING: &str = "validating";
+const GAME_DISTRIBUTION_VERSION_UPLOAD_FAILED: &str = "upload_failed";
+const GAME_DISTRIBUTION_VERSION_VALIDATION_FAILED: &str = "validation_failed";
+const GAME_DISTRIBUTION_ACTION_CREATE_GAME: &str = "create_game";
+const GAME_DISTRIBUTION_ACTION_CREATE_VERSION: &str = "create_version";
+const GAME_DISTRIBUTION_ACTION_CONFIRM_PACKAGE: &str = "confirm_package";
+const GAME_DISTRIBUTION_ACTION_FAIL_UPLOAD: &str = "fail_upload";
+const GAME_DISTRIBUTION_ACTION_SUBMIT_REVIEW: &str = "submit_review";
+const GAME_DISTRIBUTION_ACTION_CANCEL_VERSION: &str = "cancel_version";
+const GAME_DISTRIBUTION_ACTION_APPROVE: &str = "approve";
+const GAME_DISTRIBUTION_ACTION_REJECT: &str = "reject";
+const GAME_DISTRIBUTION_ACTION_UNPUBLISH: &str = "unpublish";
+const GAME_DISTRIBUTION_ACTION_SUSPEND: &str = "suspend";
+const GAME_DISTRIBUTION_RECEIPT_RETENTION_MICROS: i64 = 30 * 24 * 60 * 60 * 1_000_000;
+const GAME_DISTRIBUTION_MAX_LIST_LIMIT: u32 = 48;
+const GAME_DISTRIBUTION_MAX_OWNER_VERSIONS_PER_GAME: usize = 10;
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionCreateGameInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: Option<String>,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+    /// 同一作者的本地项目标识；重复发布会复用既有 game_id 而不是新建游戏。
+    pub local_project_id: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionCreateVersionInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_id: String,
+    /// 由 api-server 校验并解析素材后生成的资料快照 JSON。
+    pub metadata_json: String,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub local_project_id: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionConfirmPackageInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub package_object_key: String,
+    pub package_manifest_json: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionFailUploadInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub error_code: String,
+    pub error_message: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionSubmitReviewInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionCancelVersionInput {
+    pub version_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionApproveInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub entry_url: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionRejectInput {
+    pub version_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub review_reason: String,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionUnpublishInput {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub expected_publication_revision: u64,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionSuspendInput {
+    pub game_id: String,
+    pub admin_user_id: String,
+    pub expected_publication_revision: u64,
+    pub reason: Option<String>,
+    pub idempotency_key: String,
+    pub request_digest: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionReviewListInput {
+    pub limit: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionOwnerGameListInput {
+    pub owner_user_id: String,
+    pub limit: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionPublicGameListInput {
+    pub search: Option<String>,
+    pub category: Option<String>,
+    pub limit: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionPublicGameInput {
+    pub game_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionOwnerVersionInput {
+    pub owner_user_id: String,
+    pub version_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionVersionLookupInput {
+    pub version_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionGameSnapshot {
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub summary: String,
+    pub description: String,
+    pub category: String,
+    pub tags_json: String,
+    pub cover_asset_id: Option<String>,
+    pub author_name: Option<String>,
+    pub author_avatar_url: Option<String>,
+    pub device_support_desktop: bool,
+    pub device_support_mobile: bool,
+    pub device_support_touch: bool,
+    pub input_modes_json: String,
+    pub orientation: String,
+    pub publication_revision: u64,
+    pub active_version_id: Option<String>,
+    pub visibility: String,
+    pub play_count: u64,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+    pub cover_object_key: Option<String>,
+    pub screenshots_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionVersionSnapshot {
+    pub version_id: String,
+    pub game_id: String,
+    pub owner_user_id: String,
+    pub version_number: u64,
+    pub package_sha256: String,
+    pub package_bytes: u64,
+    pub package_file_count: u32,
+    pub package_entry_path: String,
+    pub status: String,
+    pub review_reason: Option<String>,
+    pub entry_url: Option<String>,
+    pub publication_revision: u64,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+    /// 该版本冻结的资料快照 JSON；旧版本为 None。
+    pub metadata_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionPublicGameSnapshot {
+    pub game: GameDistributionGameSnapshot,
+    pub current_version: Option<GameDistributionVersionSnapshot>,
+}
+
+/// 作者自有游戏的聚合快照：游戏身份 + 最近若干版本，供作者管理页展示状态与驳回理由。
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionOwnerGameSnapshot {
+    pub game: GameDistributionGameSnapshot,
+    pub versions: Vec<GameDistributionVersionSnapshot>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionOwnerGameListProcedureResult {
+    pub ok: bool,
+    pub games: Vec<GameDistributionOwnerGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionGameProcedureResult {
+    pub ok: bool,
+    pub game: Option<GameDistributionPublicGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionGameListProcedureResult {
+    pub ok: bool,
+    pub games: Vec<GameDistributionPublicGameSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionVersionProcedureResult {
+    pub ok: bool,
+    pub version: Option<GameDistributionVersionSnapshot>,
+    pub error_message: Option<String>,
+}
+
+/// Facade 使用的统一结果合同。列表和公开详情只填 `games` / `game`，写操作只填
+/// `game` 或 `version`；其余字段保留为空，避免为每个 procedure 建立平行结果类型。
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionProcedureResult {
+    pub ok: bool,
+    pub replayed: bool,
+    pub game: Option<GameDistributionGameSnapshot>,
+    pub games: Vec<GameDistributionGameSnapshot>,
+    pub version: Option<GameDistributionVersionSnapshot>,
+    pub versions: Vec<GameDistributionVersionSnapshot>,
+    pub next_cursor: Option<String>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct GameDistributionGetGameInput {
+    pub game_id: String,
+    pub owner_user_id: Option<String>,
+}
+
+fn game_distribution_result_error(error: String) -> GameDistributionProcedureResult {
+    GameDistributionProcedureResult {
+        ok: false,
+        replayed: false,
+        game: None,
+        games: Vec::new(),
+        version: None,
+        versions: Vec::new(),
+        next_cursor: None,
+        error_message: Some(error),
+    }
+}
+
+fn game_distribution_version_result(
+    version: GameDistributionVersionSnapshot,
+    replayed: bool,
+) -> GameDistributionProcedureResult {
+    GameDistributionProcedureResult {
+        ok: true,
+        replayed,
+        game: None,
+        games: Vec::new(),
+        version: Some(version),
+        versions: Vec::new(),
+        next_cursor: None,
+        error_message: None,
+    }
+}
+
+fn game_distribution_game_result(
+    game: GameDistributionGameSnapshot,
+    replayed: bool,
+) -> GameDistributionProcedureResult {
+    GameDistributionProcedureResult {
+        ok: true,
+        replayed,
+        game: Some(game),
+        games: Vec::new(),
+        version: None,
+        versions: Vec::new(),
+        next_cursor: None,
+        error_message: None,
+    }
+}
+
+/// 创建作者名下的游戏身份并在同一事务内写入幂等收据。
+#[spacetimedb::procedure]
+pub fn create_game_distribution_game_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionCreateGameInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        create_game_distribution_game_tx(tx, input.clone())
+    }) {
+        Ok((game, replayed)) => game_distribution_game_result(game, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 创建待上传发行版本；资料和包摘要先冻结，真实 ZIP 确认由 confirm procedure 完成。
+#[spacetimedb::procedure]
+pub fn create_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionCreateVersionInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        create_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 确认对象存储中的包摘要和校验清单。procedure 不读取、不执行上传内容。
+#[spacetimedb::procedure]
+pub fn confirm_game_distribution_package_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionConfirmPackageInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        confirm_game_distribution_package_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 记录上传或包校验失败，供客户端在原版本上恢复重试；不改变版本的冻结摘要。
+#[spacetimedb::procedure]
+pub fn fail_game_distribution_upload_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionFailUploadInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        fail_game_distribution_upload_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 作者提交已确认的发行包进入人工审核。提交动作只改变版本状态，不改变当前公开版本。
+#[spacetimedb::procedure]
+pub fn submit_game_distribution_version_for_review_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionSubmitReviewInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        submit_game_distribution_version_for_review_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 作者撤回尚未公开的版本；撤回保留幂等收据，不影响仍在服务的旧公开版本。
+#[spacetimedb::procedure]
+pub fn cancel_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionCancelVersionInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        cancel_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 管理员批准待审版本，并在同一事务内以 publication_revision CAS 切换公开版本。
+#[spacetimedb::procedure]
+pub fn approve_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionApproveInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        approve_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 管理员拒绝待审版本；拒绝不会影响仍在服务中的旧公开版本。
+#[spacetimedb::procedure]
+pub fn reject_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionRejectInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        reject_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok((version, replayed)) => game_distribution_version_result(version, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 作者关闭自己的公开游戏；CAS 失败时不会覆盖管理员或其他版本的最新状态。
+#[spacetimedb::procedure]
+pub fn unpublish_game_distribution_game_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionUnpublishInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        unpublish_game_distribution_game_tx(tx, input.clone())
+    }) {
+        Ok((game, replayed)) => game_distribution_game_result(game, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 管理员安全下架整个游戏。暂停状态只能由后续明确的管理员审核动作解除。
+#[spacetimedb::procedure]
+pub fn suspend_game_distribution_game_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionSuspendInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        suspend_game_distribution_game_tx(tx, input.clone())
+    }) {
+        Ok((game, replayed)) => game_distribution_game_result(game, replayed),
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 返回待审版本给后台；只返回已确认完整包的版本，普通作者不会触达该 procedure。
+#[spacetimedb::procedure]
+pub fn list_game_distribution_reviews_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionReviewListInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        list_game_distribution_reviews_tx(tx, input.clone())
+    }) {
+        Ok(versions) => GameDistributionProcedureResult {
+            ok: true,
+            replayed: false,
+            game: None,
+            games: Vec::new(),
+            version: None,
+            versions,
+            next_cursor: None,
+            error_message: None,
+        },
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 返回作者名下的游戏与最近版本；owner 来自 api-server 的认证主体，调用方不能指定他人。
+#[spacetimedb::procedure]
+pub fn list_owner_game_distribution_games_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionOwnerGameListInput,
+) -> GameDistributionOwnerGameListProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        list_owner_game_distribution_games_tx(tx, input.clone())
+    }) {
+        Ok(games) => GameDistributionOwnerGameListProcedureResult {
+            ok: true,
+            games,
+            error_message: None,
+        },
+        Err(error) => GameDistributionOwnerGameListProcedureResult {
+            ok: false,
+            games: Vec::new(),
+            error_message: Some(error),
+        },
+    }
+}
+
+/// Facade 约定的公开游戏列表名称；公开筛选和排序均在事务内执行。
+#[spacetimedb::procedure]
+pub fn list_game_distribution_games_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionPublicGameListInput,
+) -> GameDistributionProcedureResult {
+    match ctx.try_with_tx(|tx| list_public_game_distribution_games_tx(tx, input.clone())) {
+        Ok(games) => GameDistributionProcedureResult {
+            ok: true,
+            replayed: false,
+            game: None,
+            games: games.into_iter().map(|item| item.game).collect(),
+            version: None,
+            versions: Vec::new(),
+            next_cursor: None,
+            error_message: None,
+        },
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// Facade 约定的游戏详情名称；带 owner 时允许作者读取私有游戏，否则只返回公开版本。
+#[spacetimedb::procedure]
+pub fn get_game_distribution_game_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionGetGameInput,
+) -> GameDistributionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        get_game_distribution_game_for_owner_or_public_tx(tx, input.clone())
+    }) {
+        Ok(game) => GameDistributionProcedureResult {
+            ok: true,
+            replayed: false,
+            game,
+            games: Vec::new(),
+            version: None,
+            versions: Vec::new(),
+            next_cursor: None,
+            error_message: None,
+        },
+        Err(error) => game_distribution_result_error(error),
+    }
+}
+
+/// 返回当前公开且已发布版本的游戏目录；审核待处理或已暂停游戏不会出现在结果中。
+#[spacetimedb::procedure]
+pub fn list_public_game_distribution_games_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionPublicGameListInput,
+) -> GameDistributionGameListProcedureResult {
+    match ctx.try_with_tx(|tx| list_public_game_distribution_games_tx(tx, input.clone())) {
+        Ok(games) => GameDistributionGameListProcedureResult {
+            ok: true,
+            games,
+            error_message: None,
+        },
+        Err(error) => GameDistributionGameListProcedureResult {
+            ok: false,
+            games: Vec::new(),
+            error_message: Some(error),
+        },
+    }
+}
+
+/// 按游戏 ID读取当前公开版本；不可见或无可玩版本时返回空结果。
+#[spacetimedb::procedure]
+pub fn get_public_game_distribution_game_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionPublicGameInput,
+) -> GameDistributionGameProcedureResult {
+    match ctx.try_with_tx(|tx| get_public_game_distribution_game_tx(tx, input.clone())) {
+        Ok(game) => GameDistributionGameProcedureResult {
+            ok: true,
+            game,
+            error_message: None,
+        },
+        Err(error) => GameDistributionGameProcedureResult {
+            ok: false,
+            game: None,
+            error_message: Some(error),
+        },
+    }
+}
+
+/// 管理员读取任意版本状态；admin 权限由 api-server 在调用前校验，procedure 只接受受信服务身份。
+#[spacetimedb::procedure]
+pub fn get_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionVersionLookupInput,
+) -> GameDistributionVersionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        get_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok(version) => GameDistributionVersionProcedureResult {
+            ok: true,
+            version,
+            error_message: None,
+        },
+        Err(error) => GameDistributionVersionProcedureResult {
+            ok: false,
+            version: None,
+            error_message: Some(error),
+        },
+    }
+}
+
+/// 作者读取自己的版本状态；owner 在 procedure 内与持久化行再次比对。
+#[spacetimedb::procedure]
+pub fn get_owner_game_distribution_version_and_return(
+    ctx: &mut ProcedureContext,
+    input: GameDistributionOwnerVersionInput,
+) -> GameDistributionVersionProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        require_editor_generation_runtime_service_identity(tx, caller)?;
+        get_owner_game_distribution_version_tx(tx, input.clone())
+    }) {
+        Ok(version) => GameDistributionVersionProcedureResult {
+            ok: true,
+            version,
+            error_message: None,
+        },
+        Err(error) => GameDistributionVersionProcedureResult {
+            ok: false,
+            version: None,
+            error_message: Some(error),
+        },
+    }
+}
+
+fn create_game_distribution_game_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionCreateGameInput,
+) -> Result<(GameDistributionGameSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let title = required_game_distribution_text(input.title, "title")?;
+    let summary = required_game_distribution_text(input.summary, "summary")?;
+    let category = required_game_distribution_text(input.category, "category")?;
+    let orientation = required_game_distribution_text(input.orientation, "orientation")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_CREATE_GAME,
+        idempotency_key.as_str(),
+    );
+    let local_project_id = input
+        .local_project_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string);
+
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let existing_game_id = receipt
+            .outcome_game_id
+            .ok_or_else(|| "幂等收据缺少游戏 ID".to_string())?;
+        let game = ctx
+            .db
+            .game_distribution_game()
+            .game_id()
+            .find(&existing_game_id)
+            .ok_or_else(|| "幂等收据对应的游戏已不存在".to_string())?;
+        if game.owner_user_id != owner_user_id {
+            return Err("游戏 owner 不匹配".to_string());
+        }
+        return Ok((game_distribution_game_snapshot(&game), true));
+    }
+
+    // 同一作者同一本地项目再次发布只新增版本，不新建游戏身份。
+    if let Some(local_project_id) = local_project_id.as_deref() {
+        let existing = ctx
+            .db
+            .game_distribution_game()
+            .by_game_distribution_game_owner_user_id()
+            .filter(&owner_user_id)
+            .find(|game| game.local_project_id.as_deref() == Some(local_project_id));
+        if let Some(game) = existing {
+            insert_game_distribution_receipt(
+                ctx,
+                GameDistributionReceiptInput {
+                    receipt_id,
+                    owner_user_id,
+                    action: GAME_DISTRIBUTION_ACTION_CREATE_GAME.to_string(),
+                    idempotency_key,
+                    request_digest,
+                    game_id: Some(game.game_id.clone()),
+                    version_id: None,
+                    outcome_kind: "game".to_string(),
+                    outcome_game_id: Some(game.game_id.clone()),
+                    outcome_version_id: None,
+                    outcome_json: None,
+                    now_micros: input.now_micros,
+                },
+            )?;
+            return Ok((game_distribution_game_snapshot(&game), false));
+        }
+    }
+
+    if ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&game_id)
+        .is_some()
+    {
+        return Err("游戏 ID 已存在".to_string());
+    }
+
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ctx.db
+        .game_distribution_game()
+        .insert(GameDistributionGame {
+            game_id: game_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            title,
+            summary,
+            description: input.description.unwrap_or_default(),
+            category,
+            tags_json: input.tags_json,
+            cover_asset_id: input.cover_asset_id,
+            author_name: input.author_name,
+            author_avatar_url: input.author_avatar_url,
+            device_support_desktop: input.device_support_desktop,
+            device_support_mobile: input.device_support_mobile,
+            device_support_touch: input.device_support_touch,
+            input_modes_json: input.input_modes_json,
+            orientation,
+            publication_revision: 0,
+            active_version_id: None,
+            visibility: GAME_DISTRIBUTION_VISIBILITY_UNPUBLISHED.to_string(),
+            play_count: 0,
+            created_at: now,
+            updated_at: now,
+            local_project_id,
+            cover_object_key: None,
+            screenshots_json: None,
+        });
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_CREATE_GAME.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(game_id.clone()),
+            version_id: None,
+            outcome_kind: "game".to_string(),
+            outcome_game_id: Some(game_id.clone()),
+            outcome_version_id: None,
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+
+    let game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&game_id)
+        .ok_or_else(|| "创建游戏后读取失败".to_string())?;
+    Ok((game_distribution_game_snapshot(&game), false))
+}
+
+fn create_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionCreateVersionInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let package_sha256 = required_game_distribution_text(input.package_sha256, "package_sha256")?;
+    let metadata_json = required_game_distribution_text(input.metadata_json, "metadata_json")?;
+    let package_entry_path =
+        required_game_distribution_text(input.package_entry_path, "package_entry_path")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_CREATE_VERSION,
+        idempotency_key.as_str(),
+    );
+
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let existing_version_id = receipt
+            .outcome_version_id
+            .ok_or_else(|| "幂等收据缺少版本 ID".to_string())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&existing_version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        if version.owner_user_id != owner_user_id {
+            return Err("版本 owner 不匹配".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    if game.owner_user_id != owner_user_id {
+        return Err("游戏 owner 不匹配".to_string());
+    }
+    if game.visibility == GAME_DISTRIBUTION_VISIBILITY_SUSPENDED {
+        return Err("游戏已被暂停，不能创建版本".to_string());
+    }
+    if ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .is_some()
+    {
+        return Err("版本 ID 已存在".to_string());
+    }
+
+    let version_number = ctx
+        .db
+        .game_distribution_version()
+        .iter()
+        .filter(|version| version.game_id == game_id)
+        .map(|version| version.version_number)
+        .max()
+        .unwrap_or(0)
+        .checked_add(1)
+        .ok_or_else(|| "版本号溢出".to_string())?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ctx.db
+        .game_distribution_version()
+        .insert(GameDistributionVersion {
+            version_id: version_id.clone(),
+            game_id: game_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            version_number,
+            package_sha256,
+            package_bytes: input.package_bytes,
+            package_file_count: input.package_file_count,
+            package_entry_path,
+            status: GAME_DISTRIBUTION_VERSION_AWAITING_UPLOAD.to_string(),
+            review_reason: None,
+            created_at: now,
+            updated_at: now,
+            local_project_id: input.local_project_id,
+            package_object_key: None,
+            package_manifest_json: None,
+            entry_url: None,
+            reviewed_by_user_id: None,
+            uploaded_at: None,
+            submitted_at: None,
+            reviewed_at: None,
+            published_at: None,
+            revoked_at: None,
+            last_error_code: None,
+            last_error_message: None,
+            metadata_json: Some(metadata_json),
+        });
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_CREATE_VERSION.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(game_id),
+            version_id: Some(version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    let version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "创建版本后读取失败".to_string())?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn confirm_game_distribution_package_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionConfirmPackageInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let package_sha256 = required_game_distribution_text(input.package_sha256, "package_sha256")?;
+    let package_entry_path =
+        required_game_distribution_text(input.package_entry_path, "package_entry_path")?;
+    let package_object_key =
+        required_game_distribution_text(input.package_object_key, "package_object_key")?;
+    let package_manifest_json =
+        required_game_distribution_text(input.package_manifest_json, "package_manifest_json")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_CONFIRM_PACKAGE,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        if version.owner_user_id != owner_user_id {
+            return Err("版本 owner 不匹配".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    if version.owner_user_id != owner_user_id {
+        return Err("版本 owner 不匹配".to_string());
+    }
+    if version.package_sha256 != package_sha256
+        || version.package_bytes != input.package_bytes
+        || version.package_file_count != input.package_file_count
+        || version.package_entry_path != package_entry_path
+    {
+        return Err("上传包摘要与待上传版本不匹配".to_string());
+    }
+    if version.status == GAME_DISTRIBUTION_VERSION_UPLOADED {
+        if version.package_object_key.as_deref() != Some(package_object_key.as_str())
+            || version.package_manifest_json.as_deref() != Some(package_manifest_json.as_str())
+        {
+            return Err("同一版本已确认不同的对象或校验清单".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+    if version.status != GAME_DISTRIBUTION_VERSION_AWAITING_UPLOAD
+        && version.status != "upload_failed"
+    {
+        return Err(format!("版本状态 {} 不允许确认上传", version.status));
+    }
+
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    version.status = GAME_DISTRIBUTION_VERSION_UPLOADED.to_string();
+    version.package_object_key = Some(package_object_key);
+    version.package_manifest_json = Some(package_manifest_json);
+    version.uploaded_at = Some(now);
+    version.updated_at = now;
+    version.last_error_code = None;
+    version.last_error_message = None;
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_CONFIRM_PACKAGE.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.updated_at_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn fail_game_distribution_upload_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionFailUploadInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let error_code = required_game_distribution_text(input.error_code, "error_code")?;
+    let error_message = required_game_distribution_text(input.error_message, "error_message")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_FAIL_UPLOAD,
+        idempotency_key.as_str(),
+    );
+
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        if version.owner_user_id != owner_user_id {
+            return Err("版本 owner 不匹配".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    if version.owner_user_id != owner_user_id {
+        return Err("版本 owner 不匹配".to_string());
+    }
+    if version.status != GAME_DISTRIBUTION_VERSION_AWAITING_UPLOAD
+        && version.status != "validation_failed"
+    {
+        return Err(format!("版本状态 {} 不允许记录上传失败", version.status));
+    }
+
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    version.status = "upload_failed".to_string();
+    version.updated_at = now;
+    version.last_error_code = Some(error_code);
+    version.last_error_message = Some(error_message);
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_FAIL_UPLOAD.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn submit_game_distribution_version_for_review_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionSubmitReviewInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_SUBMIT_REVIEW,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        if version.owner_user_id != owner_user_id {
+            return Err("版本 owner 不匹配".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    if version.owner_user_id != owner_user_id {
+        return Err("版本 owner 不匹配".to_string());
+    }
+    let game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&version.game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    if game.owner_user_id != owner_user_id {
+        return Err("游戏 owner 不匹配".to_string());
+    }
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    if game.visibility == GAME_DISTRIBUTION_VISIBILITY_SUSPENDED {
+        return Err("游戏已被暂停，不能提交审核".to_string());
+    }
+    if version.status != GAME_DISTRIBUTION_VERSION_UPLOADED {
+        return Err(format!("版本状态 {} 不允许提交审核", version.status));
+    }
+    if version.package_object_key.is_none() || version.package_manifest_json.is_none() {
+        return Err("发行包尚未完成对象确认，不能提交审核".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    version.status = GAME_DISTRIBUTION_VERSION_PENDING_REVIEW.to_string();
+    version.submitted_at = Some(now);
+    version.updated_at = now;
+    version.review_reason = None;
+    version.last_error_code = None;
+    version.last_error_message = None;
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_SUBMIT_REVIEW.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn cancel_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionCancelVersionInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_CANCEL_VERSION,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        if version.owner_user_id != owner_user_id {
+            return Err("版本 owner 不匹配".to_string());
+        }
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    if version.owner_user_id != owner_user_id {
+        return Err("版本 owner 不匹配".to_string());
+    }
+    let game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&version.game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    if game.owner_user_id != owner_user_id {
+        return Err("游戏 owner 不匹配".to_string());
+    }
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    if !game_distribution_version_can_cancel(version.status.as_str()) {
+        return Err(format!("版本状态 {} 不允许撤回", version.status));
+    }
+    if game.active_version_id.as_deref() == Some(version_id.as_str()) {
+        return Err("已公开版本不能撤回，请改用下架".to_string());
+    }
+
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    version.status = GAME_DISTRIBUTION_VERSION_CANCELLED.to_string();
+    version.updated_at = now;
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_CANCEL_VERSION.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn game_distribution_version_can_cancel(status: &str) -> bool {
+    matches!(
+        status,
+        GAME_DISTRIBUTION_VERSION_AWAITING_UPLOAD
+            | GAME_DISTRIBUTION_VERSION_UPLOADED
+            | GAME_DISTRIBUTION_VERSION_VALIDATING
+            | GAME_DISTRIBUTION_VERSION_PENDING_REVIEW
+            | GAME_DISTRIBUTION_VERSION_UPLOAD_FAILED
+            | GAME_DISTRIBUTION_VERSION_VALIDATION_FAILED
+    )
+}
+
+fn approve_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionApproveInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let admin_user_id = required_game_distribution_text(input.admin_user_id, "admin_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let entry_url = required_game_distribution_text(input.entry_url, "entry_url")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        admin_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_APPROVE,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    let mut game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&version.game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    if game.visibility == GAME_DISTRIBUTION_VISIBILITY_SUSPENDED {
+        return Err("游戏已被暂停，不能批准版本".to_string());
+    }
+    if version.status != GAME_DISTRIBUTION_VERSION_PENDING_REVIEW {
+        return Err(format!("版本状态 {} 不允许批准", version.status));
+    }
+    if version.package_object_key.is_none() || version.package_manifest_json.is_none() {
+        return Err("发行包对象尚未确认，不能批准版本".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    if let Some(previous_version_id) = game.active_version_id.clone() {
+        if previous_version_id != version.version_id {
+            if let Some(mut previous) = ctx
+                .db
+                .game_distribution_version()
+                .version_id()
+                .find(&previous_version_id)
+            {
+                previous.status = GAME_DISTRIBUTION_VERSION_REVOKED.to_string();
+                previous.revoked_at = Some(now);
+                previous.updated_at = now;
+                ctx.db
+                    .game_distribution_version()
+                    .version_id()
+                    .update(previous);
+            }
+        }
+    }
+    version.status = GAME_DISTRIBUTION_VERSION_PUBLISHED.to_string();
+    version.entry_url = Some(entry_url);
+    version.review_reason = None;
+    version.reviewed_by_user_id = Some(admin_user_id.clone());
+    version.reviewed_at = Some(now);
+    version.published_at = Some(now);
+    version.updated_at = now;
+    version.revoked_at = None;
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    // 资料随版本冻结：审核通过时把该版本的资料快照整体生效到公开投影。
+    if let Some(metadata_json) = version.metadata_json.as_deref() {
+        let frozen = parse_game_distribution_frozen_metadata(metadata_json)?;
+        apply_game_distribution_frozen_metadata(&mut game, &frozen);
+    }
+    game.active_version_id = Some(version.version_id.clone());
+    game.visibility = GAME_DISTRIBUTION_VISIBILITY_PUBLISHED.to_string();
+    game.publication_revision = game
+        .publication_revision
+        .checked_add(1)
+        .ok_or_else(|| "publication_revision 溢出".to_string())?;
+    game.updated_at = now;
+    ctx.db.game_distribution_game().game_id().update(game);
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id: admin_user_id,
+            action: GAME_DISTRIBUTION_ACTION_APPROVE.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn reject_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionRejectInput,
+) -> Result<(GameDistributionVersionSnapshot, bool), String> {
+    let admin_user_id = required_game_distribution_text(input.admin_user_id, "admin_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let review_reason = required_game_distribution_text(input.review_reason, "review_reason")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        admin_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_REJECT,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let version = ctx
+            .db
+            .game_distribution_version()
+            .version_id()
+            .find(&version_id)
+            .ok_or_else(|| "幂等收据对应的版本已不存在".to_string())?;
+        return Ok((
+            game_distribution_version_snapshot_for_game(ctx, &version),
+            true,
+        ));
+    }
+    let mut version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+        .ok_or_else(|| "版本不存在".to_string())?;
+    let game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&version.game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    if version.status != GAME_DISTRIBUTION_VERSION_PENDING_REVIEW {
+        return Err(format!("版本状态 {} 不允许拒绝", version.status));
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    version.status = GAME_DISTRIBUTION_VERSION_REJECTED.to_string();
+    version.review_reason = Some(review_reason);
+    version.reviewed_by_user_id = Some(admin_user_id.clone());
+    version.reviewed_at = Some(now);
+    version.updated_at = now;
+    ctx.db
+        .game_distribution_version()
+        .version_id()
+        .update(version.clone());
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id: admin_user_id,
+            action: GAME_DISTRIBUTION_ACTION_REJECT.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(version.game_id.clone()),
+            version_id: Some(version.version_id.clone()),
+            outcome_kind: "version".to_string(),
+            outcome_game_id: None,
+            outcome_version_id: Some(version.version_id.clone()),
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((
+        game_distribution_version_snapshot_for_game(ctx, &version),
+        false,
+    ))
+}
+
+fn unpublish_game_distribution_game_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionUnpublishInput,
+) -> Result<(GameDistributionGameSnapshot, bool), String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        owner_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_UNPUBLISH,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let game = ctx
+            .db
+            .game_distribution_game()
+            .game_id()
+            .find(&game_id)
+            .ok_or_else(|| "幂等收据对应的游戏已不存在".to_string())?;
+        return Ok((game_distribution_game_snapshot(&game), true));
+    }
+    let mut game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    if game.owner_user_id != owner_user_id {
+        return Err("游戏 owner 不匹配".to_string());
+    }
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    if game.visibility == GAME_DISTRIBUTION_VISIBILITY_SUSPENDED {
+        return Err("游戏已被管理员暂停，作者不能解除暂停".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    let changed = game.visibility != GAME_DISTRIBUTION_VISIBILITY_UNPUBLISHED
+        || game.active_version_id.is_some();
+    if changed {
+        if let Some(active_version_id) = game.active_version_id.clone() {
+            if let Some(mut version) = ctx
+                .db
+                .game_distribution_version()
+                .version_id()
+                .find(&active_version_id)
+            {
+                version.status = GAME_DISTRIBUTION_VERSION_REVOKED.to_string();
+                version.revoked_at = Some(now);
+                version.updated_at = now;
+                ctx.db
+                    .game_distribution_version()
+                    .version_id()
+                    .update(version);
+            }
+        }
+        game.visibility = GAME_DISTRIBUTION_VISIBILITY_UNPUBLISHED.to_string();
+        game.active_version_id = None;
+        game.publication_revision = game
+            .publication_revision
+            .checked_add(1)
+            .ok_or_else(|| "publication_revision 溢出".to_string())?;
+        game.updated_at = now;
+        ctx.db
+            .game_distribution_game()
+            .game_id()
+            .update(game.clone());
+    }
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id,
+            action: GAME_DISTRIBUTION_ACTION_UNPUBLISH.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(game_id),
+            version_id: None,
+            outcome_kind: "game".to_string(),
+            outcome_game_id: Some(game.game_id.clone()),
+            outcome_version_id: None,
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((game_distribution_game_snapshot(&game), false))
+}
+
+fn suspend_game_distribution_game_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionSuspendInput,
+) -> Result<(GameDistributionGameSnapshot, bool), String> {
+    let admin_user_id = required_game_distribution_text(input.admin_user_id, "admin_user_id")?;
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let idempotency_key =
+        required_game_distribution_text(input.idempotency_key, "idempotency_key")?;
+    let request_digest = required_game_distribution_text(input.request_digest, "request_digest")?;
+    let receipt_id = game_distribution_receipt_id(
+        admin_user_id.as_str(),
+        GAME_DISTRIBUTION_ACTION_SUSPEND,
+        idempotency_key.as_str(),
+    );
+    if let Some(receipt) = find_game_distribution_receipt(ctx, receipt_id.as_str()) {
+        ensure_game_distribution_receipt_digest(&receipt, request_digest.as_str())?;
+        let game = ctx
+            .db
+            .game_distribution_game()
+            .game_id()
+            .find(&game_id)
+            .ok_or_else(|| "幂等收据对应的游戏已不存在".to_string())?;
+        return Ok((game_distribution_game_snapshot(&game), true));
+    }
+    let mut game = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&game_id)
+        .ok_or_else(|| "游戏不存在".to_string())?;
+    ensure_game_distribution_publication_revision(&game, input.expected_publication_revision)?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    if game.visibility != GAME_DISTRIBUTION_VISIBILITY_SUSPENDED {
+        if let Some(active_version_id) = game.active_version_id.clone() {
+            if let Some(mut version) = ctx
+                .db
+                .game_distribution_version()
+                .version_id()
+                .find(&active_version_id)
+            {
+                version.status = GAME_DISTRIBUTION_VERSION_REVOKED.to_string();
+                version.revoked_at = Some(now);
+                version.reviewed_by_user_id = Some(admin_user_id.clone());
+                version.review_reason = input.reason.clone();
+                version.reviewed_at = Some(now);
+                version.updated_at = now;
+                ctx.db
+                    .game_distribution_version()
+                    .version_id()
+                    .update(version);
+            }
+        }
+        game.visibility = GAME_DISTRIBUTION_VISIBILITY_SUSPENDED.to_string();
+        game.active_version_id = None;
+        game.publication_revision = game
+            .publication_revision
+            .checked_add(1)
+            .ok_or_else(|| "publication_revision 溢出".to_string())?;
+        game.updated_at = now;
+        ctx.db
+            .game_distribution_game()
+            .game_id()
+            .update(game.clone());
+    }
+    insert_game_distribution_receipt(
+        ctx,
+        GameDistributionReceiptInput {
+            receipt_id,
+            owner_user_id: admin_user_id,
+            action: GAME_DISTRIBUTION_ACTION_SUSPEND.to_string(),
+            idempotency_key,
+            request_digest,
+            game_id: Some(game_id),
+            version_id: None,
+            outcome_kind: "game".to_string(),
+            outcome_game_id: Some(game.game_id.clone()),
+            outcome_version_id: None,
+            outcome_json: None,
+            now_micros: input.now_micros,
+        },
+    )?;
+    Ok((game_distribution_game_snapshot(&game), false))
+}
+
+fn list_game_distribution_reviews_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionReviewListInput,
+) -> Result<Vec<GameDistributionVersionSnapshot>, String> {
+    let limit = if input.limit == 0 {
+        GAME_DISTRIBUTION_MAX_LIST_LIMIT
+    } else {
+        input.limit.min(GAME_DISTRIBUTION_MAX_LIST_LIMIT)
+    } as usize;
+    let mut versions = ctx
+        .db
+        .game_distribution_version()
+        .iter()
+        .filter(|version| {
+            version.status == GAME_DISTRIBUTION_VERSION_PENDING_REVIEW
+                && version.package_object_key.is_some()
+                && version.package_manifest_json.is_some()
+        })
+        .collect::<Vec<_>>();
+    versions.sort_by(|left, right| {
+        left.submitted_at
+            .cmp(&right.submitted_at)
+            .then_with(|| left.version_id.cmp(&right.version_id))
+    });
+    versions.truncate(limit);
+    Ok(versions
+        .iter()
+        .map(game_distribution_version_snapshot)
+        .collect())
+}
+
+fn ensure_game_distribution_publication_revision(
+    game: &GameDistributionGame,
+    expected: u64,
+) -> Result<(), String> {
+    if game.publication_revision == expected {
+        Ok(())
+    } else {
+        Err(format!(
+            "PUBLICATION_CONFLICT: expected publication_revision {}, actual {}",
+            expected, game.publication_revision
+        ))
+    }
+}
+
+fn list_owner_game_distribution_games_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionOwnerGameListInput,
+) -> Result<Vec<GameDistributionOwnerGameSnapshot>, String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let limit = if input.limit == 0 {
+        GAME_DISTRIBUTION_MAX_LIST_LIMIT
+    } else {
+        input.limit.min(GAME_DISTRIBUTION_MAX_LIST_LIMIT)
+    } as usize;
+    let mut games = ctx
+        .db
+        .game_distribution_game()
+        .by_game_distribution_game_owner_user_id()
+        .filter(&owner_user_id)
+        .collect::<Vec<_>>();
+    games.sort_by(|left, right| {
+        right
+            .updated_at
+            .to_micros_since_unix_epoch()
+            .cmp(&left.updated_at.to_micros_since_unix_epoch())
+            .then_with(|| right.game_id.cmp(&left.game_id))
+    });
+    games.truncate(limit);
+    Ok(games
+        .into_iter()
+        .map(|game| {
+            let mut versions = ctx
+                .db
+                .game_distribution_version()
+                .by_game_distribution_version_game_id()
+                .filter(&game.game_id)
+                .collect::<Vec<_>>();
+            versions.sort_by(|left, right| {
+                right
+                    .version_number
+                    .cmp(&left.version_number)
+                    .then_with(|| right.version_id.cmp(&left.version_id))
+            });
+            versions.truncate(GAME_DISTRIBUTION_MAX_OWNER_VERSIONS_PER_GAME);
+            GameDistributionOwnerGameSnapshot {
+                versions: versions
+                    .iter()
+                    .map(|version| game_distribution_version_snapshot(version))
+                    .collect(),
+                game: game_distribution_game_snapshot(&game),
+            }
+        })
+        .collect())
+}
+
+fn list_public_game_distribution_games_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionPublicGameListInput,
+) -> Result<Vec<GameDistributionPublicGameSnapshot>, String> {
+    let limit = if input.limit == 0 {
+        GAME_DISTRIBUTION_MAX_LIST_LIMIT
+    } else {
+        input.limit.min(GAME_DISTRIBUTION_MAX_LIST_LIMIT)
+    } as usize;
+    let search = input
+        .search
+        .and_then(|value| normalize_game_distribution_optional(value));
+    let category = input
+        .category
+        .and_then(|value| normalize_game_distribution_optional(value));
+    let mut games = ctx
+        .db
+        .game_distribution_game()
+        .iter()
+        .filter(|game| game.visibility == GAME_DISTRIBUTION_VISIBILITY_PUBLISHED)
+        .filter(|game| game.active_version_id.is_some())
+        .filter(|game| {
+            category
+                .as_deref()
+                .is_none_or(|value| game.category == value)
+        })
+        .filter(|game| {
+            search.as_deref().is_none_or(|value| {
+                game.title.contains(value)
+                    || game.summary.contains(value)
+                    || game.tags_json.contains(value)
+            })
+        })
+        .filter_map(|game| public_game_distribution_snapshot(ctx, &game))
+        .collect::<Vec<_>>();
+    games.sort_by(|left, right| {
+        right
+            .game
+            .created_at_micros
+            .cmp(&left.game.created_at_micros)
+            .then_with(|| left.game.game_id.cmp(&right.game.game_id))
+    });
+    games.truncate(limit);
+    Ok(games)
+}
+
+fn get_public_game_distribution_game_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionPublicGameInput,
+) -> Result<Option<GameDistributionPublicGameSnapshot>, String> {
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let Some(game) = ctx.db.game_distribution_game().game_id().find(&game_id) else {
+        return Ok(None);
+    };
+    if game.visibility != GAME_DISTRIBUTION_VISIBILITY_PUBLISHED || game.active_version_id.is_none()
+    {
+        return Ok(None);
+    }
+    Ok(public_game_distribution_snapshot(ctx, &game))
+}
+
+fn get_game_distribution_game_for_owner_or_public_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionGetGameInput,
+) -> Result<Option<GameDistributionGameSnapshot>, String> {
+    let game_id = required_game_distribution_text(input.game_id, "game_id")?;
+    let Some(game) = ctx.db.game_distribution_game().game_id().find(&game_id) else {
+        return Ok(None);
+    };
+    if let Some(owner_user_id) = input
+        .owner_user_id
+        .and_then(normalize_game_distribution_optional)
+    {
+        if game.owner_user_id != owner_user_id {
+            return Err("游戏 owner 不匹配".to_string());
+        }
+        return Ok(Some(game_distribution_game_snapshot(&game)));
+    }
+    Ok(public_game_distribution_snapshot(ctx, &game).map(|item| item.game))
+}
+
+fn get_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionVersionLookupInput,
+) -> Result<Option<GameDistributionVersionSnapshot>, String> {
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let Some(version) = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+    else {
+        return Ok(None);
+    };
+    Ok(Some(game_distribution_version_snapshot_for_game(
+        ctx, &version,
+    )))
+}
+
+fn get_owner_game_distribution_version_tx(
+    ctx: &ReducerContext,
+    input: GameDistributionOwnerVersionInput,
+) -> Result<Option<GameDistributionVersionSnapshot>, String> {
+    let owner_user_id = required_game_distribution_text(input.owner_user_id, "owner_user_id")?;
+    let version_id = required_game_distribution_text(input.version_id, "version_id")?;
+    let Some(version) = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(&version_id)
+    else {
+        return Ok(None);
+    };
+    if version.owner_user_id != owner_user_id {
+        return Err("版本 owner 不匹配".to_string());
+    }
+    Ok(Some(game_distribution_version_snapshot_for_game(
+        ctx, &version,
+    )))
+}
+
+struct GameDistributionReceiptInput {
+    receipt_id: String,
+    owner_user_id: String,
+    action: String,
+    idempotency_key: String,
+    request_digest: String,
+    game_id: Option<String>,
+    version_id: Option<String>,
+    outcome_kind: String,
+    outcome_game_id: Option<String>,
+    outcome_version_id: Option<String>,
+    outcome_json: Option<String>,
+    now_micros: i64,
+}
+
+fn insert_game_distribution_receipt(
+    ctx: &ReducerContext,
+    input: GameDistributionReceiptInput,
+) -> Result<(), String> {
+    if ctx
+        .db
+        .game_distribution_idempotency_receipt()
+        .receipt_id()
+        .find(&input.receipt_id)
+        .is_some()
+    {
+        return Err("幂等收据已存在".to_string());
+    }
+    let created_at = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    let expires_at = Timestamp::from_micros_since_unix_epoch(
+        input
+            .now_micros
+            .saturating_add(GAME_DISTRIBUTION_RECEIPT_RETENTION_MICROS),
+    );
+    ctx.db
+        .game_distribution_idempotency_receipt()
+        .insert(GameDistributionIdempotencyReceipt {
+            receipt_id: input.receipt_id,
+            owner_user_id: input.owner_user_id,
+            action: input.action,
+            idempotency_key: input.idempotency_key,
+            request_digest: input.request_digest,
+            game_id: input.game_id,
+            version_id: input.version_id,
+            outcome_kind: input.outcome_kind,
+            outcome_game_id: input.outcome_game_id,
+            outcome_version_id: input.outcome_version_id,
+            outcome_json: input.outcome_json,
+            created_at,
+            expires_at,
+            completed_at: Some(created_at),
+        });
+    Ok(())
+}
+
+fn find_game_distribution_receipt(
+    ctx: &ReducerContext,
+    receipt_id: &str,
+) -> Option<GameDistributionIdempotencyReceipt> {
+    ctx.db
+        .game_distribution_idempotency_receipt()
+        .receipt_id()
+        .find(&receipt_id.to_string())
+}
+
+fn ensure_game_distribution_receipt_digest(
+    receipt: &GameDistributionIdempotencyReceipt,
+    request_digest: &str,
+) -> Result<(), String> {
+    if receipt.request_digest == request_digest {
+        Ok(())
+    } else {
+        Err("幂等键对应的请求摘要不一致".to_string())
+    }
+}
+
+fn game_distribution_receipt_id(
+    owner_user_id: &str,
+    action: &str,
+    idempotency_key: &str,
+) -> String {
+    format!("game-distribution:{owner_user_id}:{action}:{idempotency_key}")
+}
+
+fn required_game_distribution_text(value: String, field: &str) -> Result<String, String> {
+    normalize_game_distribution_optional(value).ok_or_else(|| format!("{field} 不能为空"))
+}
+
+fn normalize_game_distribution_optional(value: String) -> Option<String> {
+    let value = value.trim();
+    (!value.is_empty()).then(|| value.to_string())
+}
+
+fn game_distribution_game_snapshot(game: &GameDistributionGame) -> GameDistributionGameSnapshot {
+    GameDistributionGameSnapshot {
+        game_id: game.game_id.clone(),
+        owner_user_id: game.owner_user_id.clone(),
+        title: game.title.clone(),
+        summary: game.summary.clone(),
+        description: game.description.clone(),
+        category: game.category.clone(),
+        tags_json: game.tags_json.clone(),
+        cover_asset_id: game.cover_asset_id.clone(),
+        author_name: game.author_name.clone(),
+        author_avatar_url: game.author_avatar_url.clone(),
+        device_support_desktop: game.device_support_desktop,
+        device_support_mobile: game.device_support_mobile,
+        device_support_touch: game.device_support_touch,
+        input_modes_json: game.input_modes_json.clone(),
+        orientation: game.orientation.clone(),
+        publication_revision: game.publication_revision,
+        active_version_id: game.active_version_id.clone(),
+        visibility: game.visibility.clone(),
+        play_count: game.play_count,
+        created_at_micros: game.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: game.updated_at.to_micros_since_unix_epoch(),
+        cover_object_key: game.cover_object_key.clone(),
+        screenshots_json: game.screenshots_json.clone(),
+    }
+}
+
+/// 版本冻结资料的 JSON 形状；由 api-server 在创建版本前校验并解析素材后写入。
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct GameDistributionFrozenMetadata {
+    pub title: String,
+    pub summary: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    pub category: String,
+    #[serde(default)]
+    pub tags: Vec<String>,
+    pub cover_asset_id: String,
+    pub cover_object_key: String,
+    #[serde(default)]
+    pub screenshots: Vec<GameDistributionFrozenScreenshot>,
+    pub device_support: GameDistributionFrozenDeviceSupport,
+    #[serde(default)]
+    pub input_modes: Vec<String>,
+    pub orientation: String,
+}
+
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct GameDistributionFrozenScreenshot {
+    pub asset_id: String,
+    pub object_key: String,
+}
+
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+pub(crate) struct GameDistributionFrozenDeviceSupport {
+    pub desktop: bool,
+    pub mobile: bool,
+    pub touch: bool,
+}
+
+fn parse_game_distribution_frozen_metadata(
+    metadata_json: &str,
+) -> Result<GameDistributionFrozenMetadata, String> {
+    serde_json::from_str(metadata_json).map_err(|_| "版本冻结资料格式无效".to_string())
+}
+
+fn apply_game_distribution_frozen_metadata(
+    game: &mut GameDistributionGame,
+    frozen: &GameDistributionFrozenMetadata,
+) {
+    game.title = frozen.title.clone();
+    game.summary = frozen.summary.clone();
+    game.description = frozen.description.clone().unwrap_or_default();
+    game.category = frozen.category.clone();
+    game.tags_json = serde_json::to_string(&frozen.tags).unwrap_or_else(|_| "[]".to_string());
+    game.cover_asset_id = Some(frozen.cover_asset_id.clone());
+    game.cover_object_key = Some(frozen.cover_object_key.clone());
+    game.screenshots_json = serde_json::to_string(&frozen.screenshots).ok();
+    game.device_support_desktop = frozen.device_support.desktop;
+    game.device_support_mobile = frozen.device_support.mobile;
+    game.device_support_touch = frozen.device_support.touch;
+    game.input_modes_json =
+        serde_json::to_string(&frozen.input_modes).unwrap_or_else(|_| "[]".to_string());
+    game.orientation = frozen.orientation.clone();
+}
+
+/// 已公开游戏的封面/截图素材允许匿名读者换取签名读地址。
+pub(crate) fn game_distribution_asset_has_public_read_grant(
+    ctx: &ReducerContext,
+    asset_object_id: &str,
+) -> bool {
+    ctx.db.game_distribution_game().iter().any(|game| {
+        if game.visibility != GAME_DISTRIBUTION_VISIBILITY_PUBLISHED
+            || game.active_version_id.is_none()
+        {
+            return false;
+        }
+        if game.cover_asset_id.as_deref() == Some(asset_object_id) {
+            return true;
+        }
+        game.screenshots_json
+            .as_deref()
+            .and_then(|json| {
+                serde_json::from_str::<Vec<GameDistributionFrozenScreenshot>>(json).ok()
+            })
+            .is_some_and(|screenshots| {
+                screenshots
+                    .iter()
+                    .any(|screenshot| screenshot.asset_id == asset_object_id)
+            })
+    })
+}
+
+fn game_distribution_version_snapshot(
+    version: &GameDistributionVersion,
+) -> GameDistributionVersionSnapshot {
+    GameDistributionVersionSnapshot {
+        version_id: version.version_id.clone(),
+        game_id: version.game_id.clone(),
+        owner_user_id: version.owner_user_id.clone(),
+        version_number: version.version_number,
+        package_sha256: version.package_sha256.clone(),
+        package_bytes: version.package_bytes,
+        package_file_count: version.package_file_count,
+        package_entry_path: version.package_entry_path.clone(),
+        status: version.status.clone(),
+        review_reason: version.review_reason.clone(),
+        entry_url: version.entry_url.clone(),
+        publication_revision: 0,
+        created_at_micros: version.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: version.updated_at.to_micros_since_unix_epoch(),
+        metadata_json: version.metadata_json.clone(),
+    }
+}
+
+fn game_distribution_version_snapshot_for_game(
+    ctx: &ReducerContext,
+    version: &GameDistributionVersion,
+) -> GameDistributionVersionSnapshot {
+    let mut snapshot = game_distribution_version_snapshot(version);
+    snapshot.publication_revision = ctx
+        .db
+        .game_distribution_game()
+        .game_id()
+        .find(&version.game_id)
+        .map(|game| game.publication_revision)
+        .unwrap_or_default();
+    snapshot
+}
+
+fn public_game_distribution_snapshot(
+    ctx: &ReducerContext,
+    game: &GameDistributionGame,
+) -> Option<GameDistributionPublicGameSnapshot> {
+    let version_id = game.active_version_id.as_ref()?;
+    let version = ctx
+        .db
+        .game_distribution_version()
+        .version_id()
+        .find(version_id)
+        .filter(|version| {
+            version.game_id == game.game_id && version.status == GAME_DISTRIBUTION_VERSION_PUBLISHED
+        })?;
+    Some(GameDistributionPublicGameSnapshot {
+        game: game_distribution_game_snapshot(game),
+        current_version: Some(game_distribution_version_snapshot_for_game(ctx, &version)),
+    })
+}
diff --git a/server-rs/crates/spacetime-module/src/migration.rs b/server-rs/crates/spacetime-module/src/migration.rs
index eda3e5a35..968dfa4c0 100644
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -253,6 +253,13 @@ macro_rules! migration_tables {
             asset_entity_binding,
             asset_event,
             external_api_key,
+            // 游戏分发：游戏身份、不可变发行版本和幂等收据都属于业务事实，
+            // 随迁移导出/导入；私有 ZIP 与展开内容保存在对象存储，不进入这两张表。
+            // 资料随版本冻结：版本表末尾追加 metadata_json，游戏表末尾追加
+            // cover_object_key / screenshots_json，均为可空列，旧行按“未冻结资料”处理。
+            game_distribution_game,
+            game_distribution_version,
+            game_distribution_idempotency_receipt,
             llm_router_account,
             llm_router_billing_checkpoint,
             agc_model_catalog,
diff --git a/src/components/game-distribution/GameDetailPage.tsx b/src/components/game-distribution/GameDetailPage.tsx
new file mode 100644
index 000000000..243c052e9
--- /dev/null
+++ b/src/components/game-distribution/GameDetailPage.tsx
@@ -0,0 +1,298 @@
+import './gameDistribution.css';
+import './gameDistributionShowcase.css';
+
+import {
+  ArrowLeft,
+  Gamepad2,
+  Maximize2,
+  Smartphone,
+  Sparkles,
+} from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
+import {
+  type GameDistributionGame,
+  type GameDistributionInputMode,
+  getGame,
+} from '../../services/gameDistributionClient';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import {
+  normalizeGameEntryUrl,
+  normalizeGameId,
+  useIsMobileViewport,
+} from './gameDistributionGuards';
+import { GameCover } from './GameGalleryPage';
+
+type GameDetailPageProps = {
+  gameId: string | null;
+  onBack: () => void;
+  onPlay: (gameId: string) => void;
+};
+
+const INPUT_MODE_LABELS: Record<GameDistributionInputMode, string> = {
+  keyboard: '键盘',
+  mouse: '鼠标',
+  touch: '触屏',
+};
+
+/**
+ * 游玩方式优先取版本冻结时声明的输入方式（公开投影里的 `inputModes`），
+ * 再退回版本自由文本 `controls`；两者都没有才显示“未标注操作方式”。
+ */
+function resolveControlsLabel(
+  version: GameDistributionGame['currentVersion'],
+  inputModes?: GameDistributionInputMode[],
+) {
+  if (!version) return '暂未发布可玩版本';
+  const declared = Array.from(
+    new Set((inputModes ?? []).map((mode) => INPUT_MODE_LABELS[mode] ?? mode)),
+  ).filter(Boolean);
+  if (declared.length > 0) return declared.join(' · ');
+  const controls = version.controls.join(' · ').trim();
+  return controls || '未标注操作方式';
+}
+
+/** 缩略图自己换签，失败时退回空占位，不阻塞 hero 与主行动作。 */
+function GameShowcaseThumb({
+  objectKey,
+  label,
+  isActive,
+  onSelect,
+}: {
+  objectKey: string;
+  label: string;
+  isActive: boolean;
+  onSelect: () => void;
+}) {
+  const { resolvedUrl } = useResolvedAssetReadUrl(null, { objectKey });
+  return (
+    <button
+      type="button"
+      className="game-detail-thumb"
+      aria-pressed={isActive}
+      aria-label={label}
+      onClick={onSelect}
+    >
+      {resolvedUrl ? (
+        <img src={resolvedUrl} alt="" loading="lazy" decoding="async" />
+      ) : (
+        <span className="game-detail-thumb__placeholder" />
+      )}
+    </button>
+  );
+}
+
+/**
+ * 详情页封面区：默认展示封面，存在截图时在下方给出可点击的缩略图条。
+ *
+ * 缩略图第一项固定是封面本身，方便作者/玩家从截图切回封面；只有封面时整条不渲染。
+ */
+function GameShowcase({ game }: { game: GameDistributionGame }) {
+  const coverKey = (game.coverObjectKey ?? '').trim();
+  const screenshotKeys = (game.screenshots ?? [])
+    .map((key) => key.trim())
+    .filter(Boolean)
+    .slice(0, 6);
+  const items = [
+    ...(coverKey ? [{ key: coverKey, label: '封面' }] : []),
+    ...screenshotKeys.map((key, index) => ({
+      key,
+      label: `截图 ${index + 1}`,
+    })),
+  ];
+  const [activeIndex, setActiveIndex] = useState(0);
+  const activeKey = items[activeIndex]?.key ?? coverKey;
+
+  return (
+    <div className="game-detail-showcase">
+      <GameCover game={game} priority objectKey={activeKey} />
+      {items.length > 1 ? (
+        <div className="game-detail-thumbs" role="group" aria-label="游戏截图">
+          {items.map((item, index) => (
+            <GameShowcaseThumb
+              key={item.key}
+              objectKey={item.key}
+              label={`${item.label}（查看大图）`}
+              isActive={index === activeIndex}
+              onSelect={() => setActiveIndex(index)}
+            />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function GameDetailPage({
+  gameId,
+  onBack,
+  onPlay,
+}: GameDetailPageProps) {
+  const [game, setGame] = useState<GameDistributionGame | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState('');
+  const requestSerialRef = useRef(0);
+  const isMobileViewport = useIsMobileViewport();
+
+  const loadGame = useCallback(() => {
+    const requestSerial = ++requestSerialRef.current;
+    const normalizedGameId = normalizeGameId(gameId);
+    setGame(null);
+    setError('');
+    if (!normalizedGameId) {
+      setIsLoading(false);
+      setError('游戏编号无效');
+      return;
+    }
+    setIsLoading(true);
+    void getGame(normalizedGameId)
+      .then((value) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        if (value?.currentVersion) {
+          const entryUrl = normalizeGameEntryUrl(value.currentVersion.entryUrl);
+          if (!entryUrl) {
+            setError('游戏入口地址无效');
+            return;
+          }
+          setGame({
+            ...value,
+            currentVersion: { ...value.currentVersion, entryUrl },
+          });
+          return;
+        }
+        setGame(value);
+        if (!value) setError('找不到这款游戏');
+      })
+      .catch((loadError: unknown) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        setError(
+          loadError instanceof Error ? loadError.message : '游戏详情加载失败',
+        );
+      })
+      .finally(() => {
+        if (requestSerial === requestSerialRef.current) setIsLoading(false);
+      });
+  }, [gameId]);
+
+  useEffect(() => {
+    void loadGame();
+    return () => {
+      requestSerialRef.current += 1;
+    };
+  }, [loadGame]);
+
+  if (isLoading)
+    return (
+      <div className="game-detail-page">
+        <div className="game-loading-panel">正在加载游戏详情…</div>
+      </div>
+    );
+  if (error || !game)
+    return (
+      <div className="game-detail-page">
+        <button type="button" className="game-back-button" onClick={onBack}>
+          <ArrowLeft /> 返回游戏广场
+        </button>
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          className="game-status-message"
+        >
+          <span>{error || '找不到这款游戏'}</span>
+          <button type="button" onClick={loadGame}>
+            重新加载
+          </button>
+        </PlatformStatusMessage>
+      </div>
+    );
+
+  const version = game.currentVersion;
+  const mobilePlaybackBlocked = isMobileViewport && !game.deviceSupport.mobile;
+  const playbackBlocked = !version || mobilePlaybackBlocked;
+  return (
+    <div className="game-detail-page">
+      <button type="button" className="game-back-button" onClick={onBack}>
+        <ArrowLeft /> 返回游戏广场
+      </button>
+      <section className="game-detail-hero">
+        <GameShowcase game={game} />
+        <div className="game-detail-hero__copy">
+          <span className="game-eyebrow">
+            <Sparkles aria-hidden="true" /> {game.category}
+          </span>
+          <h1>{game.title}</h1>
+          <p className="game-detail-hero__summary">{game.summary}</p>
+          <div className="game-detail-hero__author">
+            <span className="game-avatar">{game.author.name.slice(0, 1)}</span>
+            <span>由 {game.author.name} 制作</span>
+          </div>
+          <div className="game-detail-hero__actions">
+            <PlatformActionButton
+              size="lg"
+              shape="pill"
+              onClick={() => onPlay(game.id)}
+              disabled={playbackBlocked}
+              aria-describedby={
+                mobilePlaybackBlocked
+                  ? 'game-mobile-playback-warning'
+                  : undefined
+              }
+            >
+              <Gamepad2 /> 立即玩
+            </PlatformActionButton>
+            {mobilePlaybackBlocked ? (
+              <span
+                id="game-mobile-playback-warning"
+                className="game-device-warning"
+                role="status"
+              >
+                请在电脑上游玩
+              </span>
+            ) : null}
+            <span className="game-detail-hero__play-count">
+              {game.playCount.toLocaleString()} 次游玩
+            </span>
+          </div>
+        </div>
+      </section>
+      <section className="game-detail-body">
+        <div className="game-detail-main">
+          <h2>关于这款游戏</h2>
+          <p>{game.description}</p>
+          <div className="game-tag-list">
+            {game.tags.map((tag) => (
+              <span key={tag}>{tag}</span>
+            ))}
+          </div>
+        </div>
+        <aside className="game-detail-side">
+          <div className="game-info-card">
+            <strong>游玩方式</strong>
+            <span>{resolveControlsLabel(version, game.inputModes)}</span>
+          </div>
+          <div className="game-info-card">
+            <strong>设备支持</strong>
+            <span>
+              <Smartphone aria-hidden="true" />{' '}
+              {game.deviceSupport.mobile ? '移动端' : ''}
+              {game.deviceSupport.desktop ? ' · 桌面端' : ''}
+              {game.deviceSupport.touch ? ' · 支持触屏' : ''}
+            </span>
+          </div>
+          <div className="game-info-card">
+            <strong>当前版本</strong>
+            <span>{version?.version || '—'}</span>
+          </div>
+        </aside>
+      </section>
+      <p className="game-detail-footnote">
+        <Maximize2 aria-hidden="true" />{' '}
+        游玩时可以切换全屏，游戏运行在独立的安全容器中。
+      </p>
+    </div>
+  );
+}
+
+export default GameDetailPage;
diff --git a/src/components/game-distribution/GameDistributionPages.test.tsx b/src/components/game-distribution/GameDistributionPages.test.tsx
new file mode 100644
index 000000000..15b3b8720
--- /dev/null
+++ b/src/components/game-distribution/GameDistributionPages.test.tsx
@@ -0,0 +1,550 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { GameDistributionGame } from '../../services/gameDistributionClient';
+import { GameDetailPage } from './GameDetailPage';
+import { GameGalleryPage } from './GameGalleryPage';
+import { GAME_PLAY_STARTUP_TIMEOUT_MS, GamePlayPage } from './GamePlayPage';
+
+const listGamesMock = vi.hoisted(() => vi.fn());
+const getGameMock = vi.hoisted(() => vi.fn());
+const resolvedAssetUrlMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/gameDistributionClient', () => ({
+  listGames: listGamesMock,
+  getGame: getGameMock,
+}));
+
+// 只替换换签结果，测试不发起任何真实请求；返回空串即代表签名失败或字段为空。
+vi.mock('../../hooks/useResolvedAssetReadUrl', () => ({
+  useResolvedAssetReadUrl: (
+    source: string | null | undefined,
+    options: { objectKey?: string | null } = {},
+  ) => {
+    const objectKey = (options.objectKey ?? '').trim();
+    return {
+      resolvedUrl: resolvedAssetUrlMock(objectKey || (source ?? '').trim()),
+      isResolving: false,
+      shouldResolve: Boolean(objectKey || (source ?? '').trim()),
+    };
+  },
+}));
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, reject, resolve };
+}
+
+function createGame(
+  overrides: Partial<GameDistributionGame> = {},
+): GameDistributionGame {
+  return {
+    id: 'game-1',
+    title: '星轨防线',
+    summary: '守住最后一条航线。',
+    description: '一款测试游戏。',
+    category: '动作',
+    tags: ['测试'],
+    coverColor: '#d77a51',
+    icon: '✦',
+    author: { id: 'author-1', name: '测试作者' },
+    deviceSupport: { desktop: true, mobile: true, touch: true },
+    status: 'published',
+    currentVersion: {
+      id: 'version-1',
+      version: '1.0.0',
+      entryUrl: 'https://play.example.test/releases/version-1/index.html',
+      sha256: 'sha256',
+      publishedAt: '2026-09-18T00:00:00.000Z',
+      controls: ['键盘'],
+    },
+    playCount: 12,
+    createdAt: '2026-09-18T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function setViewportWidth(width: number) {
+  Object.defineProperty(window, 'innerWidth', {
+    configurable: true,
+    value: width,
+    writable: true,
+  });
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    value: () => ({
+      addEventListener: vi.fn(),
+      matches: width <= 820,
+      removeEventListener: vi.fn(),
+    }),
+    writable: true,
+  });
+}
+
+afterEach(() => {
+  cleanup();
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  setViewportWidth(1024);
+  listGamesMock.mockResolvedValue([]);
+  getGameMock.mockResolvedValue(createGame());
+  resolvedAssetUrlMock.mockImplementation((objectKey: string) =>
+    objectKey ? `https://assets.example.test/${objectKey}` : '',
+  );
+});
+
+describe('GameGalleryPage', () => {
+  it('ignores a stale response after search keyword changes', async () => {
+    const first = deferred<GameDistributionGame[]>();
+    const second = deferred<GameDistributionGame[]>();
+    listGamesMock
+      .mockImplementationOnce(() => first.promise)
+      .mockImplementationOnce(() => second.promise);
+    const onOpenDetail = vi.fn();
+    const { rerender } = render(
+      <GameGalleryPage searchKeyword="" onOpenDetail={onOpenDetail} />,
+    );
+
+    await waitFor(() => expect(listGamesMock).toHaveBeenCalledTimes(1));
+    rerender(
+      <GameGalleryPage searchKeyword="新搜索" onOpenDetail={onOpenDetail} />,
+    );
+    await waitFor(() => expect(listGamesMock).toHaveBeenCalledTimes(2));
+
+    const newerGame = createGame({ id: 'game-new', title: '新搜索结果' });
+    second.resolve([newerGame]);
+    await screen.findByText('新搜索结果');
+    first.resolve([createGame({ id: 'game-old', title: '旧搜索结果' })]);
+    await waitFor(() => expect(screen.queryByText('旧搜索结果')).toBeNull());
+  });
+});
+
+describe('GameDetailPage', () => {
+  it('blocks desktop-only games on a mobile viewport', async () => {
+    setViewportWidth(375);
+    getGameMock.mockResolvedValueOnce(
+      createGame({
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+      }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    const playButton = await screen.findByRole('button', { name: /立即玩/u });
+    expect((playButton as HTMLButtonElement).disabled).toBe(true);
+    expect(screen.getByText('请在电脑上游玩')).toBeTruthy();
+  });
+
+  it('rejects an invalid query id without requesting the API', async () => {
+    render(<GameDetailPage gameId="" onBack={vi.fn()} onPlay={vi.fn()} />);
+
+    expect(await screen.findByText('游戏编号无效')).toBeTruthy();
+    expect(getGameMock).not.toHaveBeenCalled();
+  });
+  it('已发布但未标注操作方式时不谎称没有可玩版本', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({
+        currentVersion: { ...createGame().currentVersion!, controls: [] },
+      }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    expect(await screen.findByText('未标注操作方式')).toBeTruthy();
+    expect(screen.queryByText('暂未发布可玩版本')).toBeNull();
+  });
+
+  it('优先展示版本声明的输入方式', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({
+        inputModes: ['keyboard', 'touch'],
+        currentVersion: { ...createGame().currentVersion!, controls: [] },
+      }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    expect(await screen.findByText('键盘 · 触屏')).toBeTruthy();
+    expect(screen.queryByText('未标注操作方式')).toBeNull();
+  });
+
+  it('没有当前版本时才显示暂未发布可玩版本', async () => {
+    getGameMock.mockResolvedValueOnce(createGame({ currentVersion: null }));
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    expect(await screen.findByText('暂未发布可玩版本')).toBeTruthy();
+  });
+});
+
+describe('GamePlayPage', () => {
+  it('waits for an explicit start before mounting the sandbox iframe', async () => {
+    render(<GamePlayPage gameId="game-1" onBack={vi.fn()} />);
+
+    await screen.findByRole('button', { name: /开始游戏/u });
+    expect(screen.queryByTitle('星轨防线 在线游玩')).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: /开始游戏/u }));
+    const iframe = await screen.findByTitle('星轨防线 在线游玩');
+    expect(iframe.getAttribute('sandbox')).toBe('allow-scripts');
+  });
+
+  it('rejects an unsafe release entry URL before rendering an iframe', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({
+        currentVersion: {
+          ...createGame().currentVersion!,
+          entryUrl: 'javascript:alert(1)',
+        },
+      }),
+    );
+    render(<GamePlayPage gameId="game-1" onBack={vi.fn()} />);
+
+    expect(await screen.findByText('游戏入口地址无效')).toBeTruthy();
+    expect(screen.queryByTitle('星轨防线 在线游玩')).toBeNull();
+  });
+});
+
+describe('GameGalleryPage 筛选与返回上下文', () => {
+  function resetGalleryContext() {
+    window.sessionStorage.clear();
+    window.history.replaceState({}, '', '/games');
+  }
+
+  function openGame(title: string) {
+    fireEvent.click(screen.getByText(title).closest('button')!);
+  }
+
+  it('设备筛选按真实 deviceSupport 过滤，并写回地址栏', async () => {
+    resetGalleryContext();
+    listGamesMock.mockResolvedValue([
+      createGame({
+        id: 'game-desktop',
+        title: '桌面专属',
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+      }),
+      createGame({
+        id: 'game-mobile',
+        title: '移动可玩',
+        deviceSupport: { desktop: false, mobile: true, touch: true },
+      }),
+    ]);
+    render(<GameGalleryPage onOpenDetail={vi.fn()} />);
+
+    expect(await screen.findByText('桌面专属')).toBeTruthy();
+    const deviceTabs = within(
+      screen.getByRole('tablist', { name: '设备筛选' }),
+    );
+    fireEvent.click(deviceTabs.getByRole('tab', { name: /移动/u }));
+
+    await waitFor(() => expect(screen.queryByText('桌面专属')).toBeNull());
+    expect(screen.getByText('移动可玩')).toBeTruthy();
+    expect(window.location.search).toContain('device=');
+    expect(decodeURIComponent(window.location.search)).toContain('device=移动');
+  });
+
+  it('筛选结果为空时提供重置筛选，并清理地址栏条件', async () => {
+    resetGalleryContext();
+    listGamesMock.mockResolvedValue([
+      createGame({
+        id: 'game-desktop',
+        title: '桌面专属',
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+      }),
+    ]);
+    render(<GameGalleryPage onOpenDetail={vi.fn()} />);
+    expect(await screen.findByText('桌面专属')).toBeTruthy();
+
+    fireEvent.click(
+      within(screen.getByRole('tablist', { name: '设备筛选' })).getByRole(
+        'tab',
+        { name: /移动/u },
+      ),
+    );
+    expect(await screen.findByText('还没有找到对应游戏')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '重置筛选' }));
+    expect(await screen.findByText('桌面专属')).toBeTruthy();
+    expect(window.location.search).not.toContain('device=');
+  });
+
+  it('从地址栏恢复筛选条件', async () => {
+    resetGalleryContext();
+    window.history.replaceState(
+      {},
+      '',
+      '/games?keyword=%E6%98%9F%E8%BD%A8&category=%E5%8A%A8%E4%BD%9C&device=%E7%A7%BB%E5%8A%A8',
+    );
+    listGamesMock.mockResolvedValue([createGame({ title: '星轨防线' })]);
+    render(<GameGalleryPage onOpenDetail={vi.fn()} />);
+
+    await waitFor(() =>
+      expect(listGamesMock).toHaveBeenCalledWith({
+        keyword: '星轨',
+        category: '动作',
+      }),
+    );
+    const search = screen.getByLabelText('搜索游戏') as HTMLInputElement;
+    expect(search.value).toBe('星轨');
+    const deviceTabs = within(
+      screen.getByRole('tablist', { name: '设备筛选' }),
+    );
+    expect(
+      deviceTabs
+        .getByRole('tab', { name: /移动/u })
+        .getAttribute('aria-selected'),
+    ).toBe('true');
+  });
+
+  it('返回游戏广场时按上次筛选恢复列表与滚动位置', async () => {
+    resetGalleryContext();
+    window.sessionStorage.setItem(
+      'game-gallery-filters',
+      JSON.stringify({ keyword: '', category: '全部', device: '移动' }),
+    );
+    window.sessionStorage.setItem('game-gallery-scroll:|全部|移动', '320');
+    listGamesMock.mockResolvedValue([
+      createGame({
+        id: 'game-desktop',
+        title: '桌面专属',
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+      }),
+      createGame({
+        id: 'game-mobile',
+        title: '移动可玩',
+        deviceSupport: { desktop: false, mobile: true, touch: true },
+      }),
+    ]);
+
+    const { container } = render(
+      <div className="platform-tab-panel">
+        <GameGalleryPage onOpenDetail={vi.fn()} />
+      </div>,
+    );
+    const scroller = container.querySelector(
+      '.platform-tab-panel',
+    ) as HTMLElement;
+
+    expect(await screen.findByText('移动可玩')).toBeTruthy();
+    await waitFor(() => expect(scroller.scrollTop).toBe(320));
+    expect(screen.queryByText('桌面专属')).toBeNull();
+  });
+
+  it('打开详情时保存目录滚动位置，返回后按同一容器复位', async () => {
+    resetGalleryContext();
+    const onOpenDetail = vi.fn();
+    listGamesMock.mockResolvedValue([createGame({ title: '星轨防线' })]);
+    const { container } = render(
+      <div className="platform-tab-panel">
+        <GameGalleryPage onOpenDetail={onOpenDetail} />
+      </div>,
+    );
+    const scroller = container.querySelector(
+      '.platform-tab-panel',
+    ) as HTMLElement;
+    expect(await screen.findByText('星轨防线')).toBeTruthy();
+
+    scroller.scrollTop = 180;
+    openGame('星轨防线');
+
+    expect(onOpenDetail).toHaveBeenCalledWith('game-1');
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem('game-gallery-scroll:|全部|全部'),
+      ).toBe('180'),
+    );
+  });
+});
+
+describe('GamePlayPage 启动超时与旋转提示', () => {
+  it('启动超时后给出重试与返回详情，重试可恢复可玩', async () => {
+    vi.useFakeTimers();
+    try {
+      const onBack = vi.fn();
+      getGameMock.mockResolvedValue(createGame());
+      render(<GamePlayPage gameId="game-1" onBack={onBack} />);
+      await act(async () => {
+        await Promise.resolve();
+      });
+
+      fireEvent.click(screen.getByRole('button', { name: /开始游戏/u }));
+      const firstFrame = screen.getByTitle('星轨防线 在线游玩');
+
+      act(() => {
+        vi.advanceTimersByTime(GAME_PLAY_STARTUP_TIMEOUT_MS);
+      });
+      expect(screen.getByText(/启动超时/u)).toBeTruthy();
+      expect(screen.getByRole('button', { name: /返回详情/u })).toBeTruthy();
+
+      fireEvent.click(screen.getByRole('button', { name: /^重试$/u }));
+      const retriedFrame = screen.getByTitle('星轨防线 在线游玩');
+      expect(retriedFrame).not.toBe(firstFrame);
+      expect(screen.queryByText(/启动超时/u)).toBeNull();
+
+      fireEvent.load(retriedFrame);
+      expect(retriedFrame.className.includes('game-player-frame--ready')).toBe(
+        true,
+      );
+
+      act(() => {
+        vi.advanceTimersByTime(GAME_PLAY_STARTUP_TIMEOUT_MS);
+      });
+      expect(screen.queryByText(/启动超时/u)).toBeNull();
+
+      fireEvent.click(screen.getByRole('button', { name: /星轨防线/u }));
+      expect(onBack).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('横屏游戏只在竖屏视口提示旋转', async () => {
+    setViewportWidth(390);
+    getGameMock.mockResolvedValue(createGame({ orientation: 'landscape' }));
+    const { unmount } = render(
+      <GamePlayPage gameId="game-1" onBack={vi.fn()} />,
+    );
+
+    expect(await screen.findByText(/旋转设备/u)).toBeTruthy();
+    unmount();
+
+    setViewportWidth(1280);
+    getGameMock.mockResolvedValue(createGame({ orientation: 'landscape' }));
+    render(<GamePlayPage gameId="game-1" onBack={vi.fn()} />);
+
+    await screen.findByRole('button', { name: /开始游戏/u });
+    expect(screen.queryByText(/旋转设备/u)).toBeNull();
+  });
+});
+
+describe('游戏封面与截图展示', () => {
+  function resetGalleryContext() {
+    window.sessionStorage.clear();
+    window.history.replaceState({}, '', '/games');
+  }
+
+  it('广场卡片用签名地址展示真实封面', async () => {
+    resetGalleryContext();
+    listGamesMock.mockResolvedValue([
+      createGame({ coverObjectKey: 'game-distribution/cover/alpha.png' }),
+    ]);
+    render(<GameGalleryPage onOpenDetail={vi.fn()} />);
+
+    const card = (await screen.findByText('星轨防线')).closest('button');
+    const cover = card?.querySelector('img.game-cover__image');
+    expect(cover?.getAttribute('src')).toBe(
+      'https://assets.example.test/game-distribution/cover/alpha.png',
+    );
+    expect(cover?.getAttribute('loading')).toBe('lazy');
+  });
+
+  it('没有封面或换签失败时保留占位而不渲染图片', async () => {
+    resetGalleryContext();
+    resolvedAssetUrlMock.mockImplementation((objectKey: string) =>
+      objectKey && objectKey !== 'game-distribution/cover/broken.png'
+        ? `https://assets.example.test/${objectKey}`
+        : '',
+    );
+    listGamesMock.mockResolvedValue([
+      createGame({ id: 'game-none', title: '没有封面', coverObjectKey: null }),
+      createGame({
+        id: 'game-broken',
+        title: '换签失败',
+        coverObjectKey: 'game-distribution/cover/broken.png',
+      }),
+    ]);
+    render(<GameGalleryPage onOpenDetail={vi.fn()} />);
+
+    expect(await screen.findByText('没有封面')).toBeTruthy();
+    expect(screen.getByText('换签失败')).toBeTruthy();
+    expect(document.querySelectorAll('img.game-cover__image')).toHaveLength(0);
+    expect(document.querySelectorAll('.game-cover__icon')).toHaveLength(2);
+  });
+
+  it('详情页展示封面与截图缩略图，并可切换 hero', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({
+        coverObjectKey: 'game-distribution/cover/alpha.png',
+        screenshots: [
+          'game-distribution/screenshot/one.png',
+          'game-distribution/screenshot/two.png',
+        ],
+      }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    await screen.findByRole('heading', { name: '星轨防线' });
+    const heroImage = () =>
+      document
+        .querySelector('.game-detail-showcase img.game-cover__image')
+        ?.getAttribute('src');
+    expect(heroImage()).toBe(
+      'https://assets.example.test/game-distribution/cover/alpha.png',
+    );
+
+    const thumbs = screen.getAllByRole('button', { name: /（查看大图）/u });
+    expect(thumbs).toHaveLength(3);
+    expect(thumbs[0]?.getAttribute('aria-pressed')).toBe('true');
+    expect(thumbs[2]?.getAttribute('aria-pressed')).toBe('false');
+
+    fireEvent.click(thumbs[2]!);
+    await waitFor(() =>
+      expect(heroImage()).toBe(
+        'https://assets.example.test/game-distribution/screenshot/two.png',
+      ),
+    );
+    expect(thumbs[2]?.getAttribute('aria-pressed')).toBe('true');
+    expect(thumbs[0]?.getAttribute('aria-pressed')).toBe('false');
+  });
+
+  it('只有封面时不渲染缩略图条', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({ coverObjectKey: 'game-distribution/cover/only.png' }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    await screen.findByRole('heading', { name: '星轨防线' });
+    expect(
+      screen.queryAllByRole('button', { name: /（查看大图）/u }),
+    ).toHaveLength(0);
+    expect(screen.queryByRole('group', { name: '游戏截图' })).toBeNull();
+  });
+
+  it('既没有封面也没有截图时退回原占位视觉', async () => {
+    getGameMock.mockResolvedValueOnce(
+      createGame({ coverObjectKey: null, screenshots: [] }),
+    );
+    render(
+      <GameDetailPage gameId="game-1" onBack={vi.fn()} onPlay={vi.fn()} />,
+    );
+
+    await screen.findByRole('heading', { name: '星轨防线' });
+    expect(document.querySelectorAll('img.game-cover__image')).toHaveLength(0);
+    expect(document.querySelectorAll('.game-cover__icon')).toHaveLength(1);
+  });
+});
diff --git a/src/components/game-distribution/GameGalleryPage.tsx b/src/components/game-distribution/GameGalleryPage.tsx
new file mode 100644
index 000000000..4b12ba5a4
--- /dev/null
+++ b/src/components/game-distribution/GameGalleryPage.tsx
@@ -0,0 +1,419 @@
+import './gameDistribution.css';
+import './gameDistributionShowcase.css';
+
+import { Gamepad2, Monitor, Search, Smartphone, Sparkles } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
+import {
+  type GameCategory,
+  type GameDistributionGame,
+  listGames,
+} from '../../services/gameDistributionClient';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import {
+  GAME_GALLERY_CATEGORIES as CATEGORIES,
+  GAME_GALLERY_DEVICE_FILTERS as DEVICE_FILTERS,
+  GAME_GALLERY_SCROLL_CONTAINER_SELECTOR,
+  type GameDeviceFilter,
+  type GameGalleryFilters,
+  gameGalleryScrollKey,
+  matchesGameDeviceFilter,
+  readGameGalleryQueryFilters,
+  readStoredGameGalleryFilters,
+  readStoredGameGalleryScrollTop,
+  syncGameGalleryQuery,
+  writeStoredGameGalleryFilters,
+  writeStoredGameGalleryScrollTop,
+} from './gameGalleryViewState';
+
+type GameGalleryPageProps = {
+  searchKeyword?: string;
+  onOpenDetail: (gameId: string) => void;
+  onOpenMyGames?: () => void;
+  onOpenPublish?: () => void;
+};
+
+/**
+ * 游戏封面。
+ *
+ * 有平台封面素材时换签名地址后显示真实封面，未上传、换签失败或还在解析时保留原有的
+ * 渐变色 + 图标占位，保证首屏不出现空框或布局跳动；`objectKey` 允许详情页把封面位临时
+ * 展示成选中的截图。
+ */
+export function GameCover({
+  game,
+  compact = false,
+  priority = false,
+  objectKey,
+}: {
+  game: GameDistributionGame;
+  compact?: boolean;
+  /** 首屏 hero 用的封面立即加载，列表卡片保持延迟加载。 */
+  priority?: boolean;
+  objectKey?: string | null;
+}) {
+  const targetKey = (objectKey ?? game.coverObjectKey ?? '').trim();
+  const { resolvedUrl } = useResolvedAssetReadUrl(null, {
+    objectKey: targetKey,
+  });
+  return (
+    <div
+      className={`game-cover ${compact ? 'game-cover--compact' : ''}`}
+      style={{
+        background: `linear-gradient(145deg, ${game.coverColor}, #16151c)`,
+      }}
+      aria-hidden="true"
+    >
+      {resolvedUrl ? (
+        <img
+          className="game-cover__image"
+          src={resolvedUrl}
+          alt=""
+          loading={priority ? 'eager' : 'lazy'}
+          decoding="async"
+        />
+      ) : (
+        <>
+          <span className="game-cover__glow" />
+          <span className="game-cover__icon">{game.icon}</span>
+          <span className="game-cover__grid" />
+        </>
+      )}
+    </div>
+  );
+}
+
+function GameCard({
+  game,
+  onOpen,
+}: {
+  game: GameDistributionGame;
+  onOpen: () => void;
+}) {
+  return (
+    <button type="button" className="game-card" onClick={onOpen}>
+      <GameCover game={game} />
+      <span className="game-card__body">
+        <span className="game-card__title-row">
+          <strong>{game.title}</strong>
+          <span className="game-card__play-count">
+            {game.playCount.toLocaleString()} 次游玩
+          </span>
+        </span>
+        <span className="game-card__summary">{game.summary}</span>
+        <span className="game-card__meta">
+          <span>{game.category}</span>
+          <span>·</span>
+          <span>{game.author.name}</span>
+        </span>
+      </span>
+    </button>
+  );
+}
+
+export function GameGalleryPage({
+  searchKeyword = '',
+  onOpenDetail,
+  onOpenMyGames,
+  onOpenPublish,
+}: GameGalleryPageProps) {
+  const initialFiltersRef = useRef<GameGalleryFilters | null>(null);
+  if (initialFiltersRef.current === null) {
+    const queryFilters =
+      typeof window === 'undefined'
+        ? {}
+        : readGameGalleryQueryFilters(window.location.search);
+    const storedFilters = readStoredGameGalleryFilters();
+    initialFiltersRef.current = {
+      keyword: queryFilters.keyword ?? storedFilters.keyword ?? searchKeyword,
+      category: queryFilters.category ?? storedFilters.category ?? '全部',
+      device: queryFilters.device ?? storedFilters.device ?? '全部',
+    };
+  }
+  const initialFilters = initialFiltersRef.current;
+  const [category, setCategory] = useState<GameCategory | '全部'>(
+    initialFilters.category,
+  );
+  const [device, setDevice] = useState<GameDeviceFilter>(initialFilters.device);
+  const [keywordInput, setKeywordInput] = useState(initialFilters.keyword);
+  const [activeKeyword, setActiveKeyword] = useState(initialFilters.keyword);
+  const [games, setGames] = useState<GameDistributionGame[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState('');
+  const requestSerialRef = useRef(0);
+  const scrollContainerRef = useRef<HTMLElement | null>(null);
+  const hasRestoredScrollRef = useRef(false);
+  const didSyncPropKeywordRef = useRef(false);
+
+  const filters = useMemo<GameGalleryFilters>(
+    () => ({ keyword: activeKeyword, category, device }),
+    [activeKeyword, category, device],
+  );
+  const scrollKey = gameGalleryScrollKey(filters);
+
+  const attachPageRoot = useCallback((node: HTMLDivElement | null) => {
+    if (!node) return;
+    const container = node.closest(GAME_GALLERY_SCROLL_CONTAINER_SELECTOR);
+    scrollContainerRef.current =
+      container instanceof HTMLElement ? container : null;
+  }, []);
+
+  const loadGames = useCallback(() => {
+    const requestSerial = ++requestSerialRef.current;
+    setIsLoading(true);
+    setError('');
+    void listGames({ keyword: activeKeyword, category })
+      .then((nextGames) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        setGames(nextGames);
+      })
+      .catch((loadError: unknown) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        setError(
+          loadError instanceof Error ? loadError.message : '游戏目录加载失败',
+        );
+      })
+      .finally(() => {
+        if (requestSerial === requestSerialRef.current) setIsLoading(false);
+      });
+  }, [activeKeyword, category]);
+
+  useEffect(() => {
+    if (!didSyncPropKeywordRef.current) {
+      didSyncPropKeywordRef.current = true;
+      return;
+    }
+    setKeywordInput(searchKeyword);
+    setActiveKeyword(searchKeyword);
+  }, [searchKeyword]);
+
+  useEffect(() => {
+    void loadGames();
+    return () => {
+      requestSerialRef.current += 1;
+    };
+  }, [loadGames]);
+
+  useEffect(() => {
+    writeStoredGameGalleryFilters(filters);
+    syncGameGalleryQuery(filters);
+  }, [filters]);
+
+  useEffect(() => {
+    hasRestoredScrollRef.current = false;
+  }, [scrollKey]);
+
+  useEffect(() => {
+    if (hasRestoredScrollRef.current || isLoading || games.length === 0) return;
+    hasRestoredScrollRef.current = true;
+    const container = scrollContainerRef.current;
+    const storedScrollTop = readStoredGameGalleryScrollTop(scrollKey);
+    if (!container || storedScrollTop <= 0) return;
+    container.scrollTop = storedScrollTop;
+  }, [games.length, isLoading, scrollKey]);
+
+  useEffect(() => {
+    const key = scrollKey;
+    return () => {
+      const container = scrollContainerRef.current;
+      if (container) writeStoredGameGalleryScrollTop(key, container.scrollTop);
+    };
+  }, [scrollKey]);
+
+  const visibleGames = useMemo(
+    () => games.filter((game) => matchesGameDeviceFilter(game, device)),
+    [device, games],
+  );
+  const featuredGame = useMemo(() => visibleGames[0] ?? null, [visibleGames]);
+  const hasActiveFilters =
+    activeKeyword.trim().length > 0 || category !== '全部' || device !== '全部';
+  const resetFilters = () => {
+    setKeywordInput('');
+    setActiveKeyword('');
+    setCategory('全部');
+    setDevice('全部');
+  };
+  const openDetail = useCallback(
+    (gameId: string) => {
+      const container = scrollContainerRef.current;
+      if (container)
+        writeStoredGameGalleryScrollTop(scrollKey, container.scrollTop);
+      onOpenDetail(gameId);
+    },
+    [onOpenDetail, scrollKey],
+  );
+
+  return (
+    <div className="game-page" ref={attachPageRoot}>
+      <section className="game-hero">
+        <div className="game-hero__copy">
+          <span className="game-eyebrow">
+            <Sparkles aria-hidden="true" /> 陶泥儿游戏分发
+          </span>
+          <h1>
+            把灵感做成游戏，
+            <br />
+            <em>现在就开始玩。</em>
+          </h1>
+          <p>
+            来自 AGC
+            创作者的轻量游戏集合。打开网页即可游玩，每一次尝试都值得被看见。
+          </p>
+          <div className="game-hero__actions">
+            <PlatformActionButton
+              size="md"
+              shape="pill"
+              onClick={() => featuredGame && openDetail(featuredGame.id)}
+            >
+              <Gamepad2 aria-hidden="true" /> 立即试玩
+            </PlatformActionButton>
+            <span className="game-hero__hint">支持桌面端与移动端</span>
+          </div>
+        </div>
+        <div className="game-hero__orb" aria-hidden="true">
+          <span>✦</span>
+        </div>
+      </section>
+
+      <div className="game-toolbar">
+        <div className="game-toolbar__title">
+          <span className="game-eyebrow">发现好玩的</span>
+          <h2>游戏广场</h2>
+        </div>
+        <div className="game-toolbar__actions">
+          {onOpenPublish ? (
+            <PlatformActionButton
+              size="sm"
+              shape="pill"
+              onClick={onOpenPublish}
+            >
+              发布游戏
+            </PlatformActionButton>
+          ) : null}
+          {onOpenMyGames ? (
+            <PlatformActionButton
+              tone="secondary"
+              size="sm"
+              shape="pill"
+              onClick={onOpenMyGames}
+            >
+              我的游戏
+            </PlatformActionButton>
+          ) : null}
+          <label className="game-search">
+            <Search aria-hidden="true" />
+            <input
+              value={keywordInput}
+              placeholder="搜索游戏、作者或标签"
+              aria-label="搜索游戏"
+              onChange={(event) => {
+                const nextKeyword = event.target.value;
+                setKeywordInput(nextKeyword);
+                setActiveKeyword(nextKeyword);
+              }}
+            />
+          </label>
+        </div>
+      </div>
+      <div className="game-category-tabs" role="tablist" aria-label="游戏分类">
+        {CATEGORIES.map((item) => (
+          <button
+            key={item}
+            type="button"
+            role="tab"
+            aria-selected={category === item}
+            className={
+              category === item
+                ? 'game-category-tab game-category-tab--active'
+                : 'game-category-tab'
+            }
+            onClick={() => setCategory(item)}
+          >
+            {item}
+          </button>
+        ))}
+      </div>
+      <div
+        className="game-category-tabs game-category-tabs--device"
+        role="tablist"
+        aria-label="设备筛选"
+      >
+        {DEVICE_FILTERS.map((item) => (
+          <button
+            key={item}
+            type="button"
+            role="tab"
+            aria-selected={device === item}
+            className={
+              device === item
+                ? 'game-category-tab game-category-tab--active'
+                : 'game-category-tab'
+            }
+            onClick={() => setDevice(item)}
+          >
+            {item === '桌面' ? <Monitor aria-hidden="true" /> : null}
+            {item === '移动' ? <Smartphone aria-hidden="true" /> : null}
+            {item}
+          </button>
+        ))}
+      </div>
+
+      {isLoading ? (
+        <div className="game-loading-grid" aria-label="正在加载游戏">
+          <span />
+          <span />
+          <span />
+        </div>
+      ) : null}
+      {!isLoading && error ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          className="game-status-message"
+        >
+          <span>{error}</span>
+          <button type="button" onClick={loadGames}>
+            重新加载
+          </button>
+        </PlatformStatusMessage>
+      ) : null}
+      {!isLoading && !error && visibleGames.length === 0 ? (
+        <PlatformEmptyState surface="subpanel" size="panel">
+          <strong>还没有找到对应游戏</strong>
+          <br />
+          <span>
+            {hasActiveFilters
+              ? '换个关键词、分类或设备条件再试试。'
+              : '新的游戏正在路上，稍后再来看看。'}
+          </span>
+          {hasActiveFilters ? (
+            <div className="game-empty-actions">
+              <PlatformActionButton
+                tone="secondary"
+                size="sm"
+                shape="pill"
+                onClick={resetFilters}
+              >
+                重置筛选
+              </PlatformActionButton>
+            </div>
+          ) : null}
+        </PlatformEmptyState>
+      ) : null}
+      {!isLoading && !error && visibleGames.length > 0 ? (
+        <div className="game-grid">
+          {visibleGames.map((game) => (
+            <GameCard
+              key={game.id}
+              game={game}
+              onOpen={() => openDetail(game.id)}
+            />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/components/game-distribution/GamePlayPage.tsx b/src/components/game-distribution/GamePlayPage.tsx
new file mode 100644
index 000000000..615af9d18
--- /dev/null
+++ b/src/components/game-distribution/GamePlayPage.tsx
@@ -0,0 +1,247 @@
+import './gameDistribution.css';
+
+import {
+  ArrowLeft,
+  Expand,
+  Gamepad2,
+  RotateCcw,
+  Smartphone,
+} from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  type GameDistributionGame,
+  getGame,
+} from '../../services/gameDistributionClient';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import {
+  normalizeGameEntryUrl,
+  normalizeGameId,
+  useIsMobileViewport,
+  useIsPortraitViewport,
+} from './gameDistributionGuards';
+import { GameCover } from './GameGalleryPage';
+
+type GamePlayPageProps = { gameId: string | null; onBack: () => void };
+
+/** 发行包首屏加载上限：超过后给出显式超时与重试，不用无限期“正在启动”。 */
+export const GAME_PLAY_STARTUP_TIMEOUT_MS = 20_000;
+
+type GameStartupState = 'idle' | 'loading' | 'ready' | 'timeout';
+
+export function GamePlayPage({ gameId, onBack }: GamePlayPageProps) {
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const [game, setGame] = useState<GameDistributionGame | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [startupState, setStartupState] = useState<GameStartupState>('idle');
+  const [hasStarted, setHasStarted] = useState(false);
+  const [frameRunId, setFrameRunId] = useState(0);
+  const [error, setError] = useState('');
+  const requestSerialRef = useRef(0);
+  const isMobileViewport = useIsMobileViewport();
+  const isPortraitViewport = useIsPortraitViewport();
+
+  const loadGame = useCallback(() => {
+    const requestSerial = ++requestSerialRef.current;
+    const normalizedGameId = normalizeGameId(gameId);
+    setGame(null);
+    setHasStarted(false);
+    setStartupState('idle');
+    setError('');
+    if (!normalizedGameId) {
+      setError('缺少游戏编号');
+      setIsLoading(false);
+      return;
+    }
+    setIsLoading(true);
+    void getGame(normalizedGameId)
+      .then((value) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        if (!value?.currentVersion?.entryUrl) {
+          throw new Error('这款游戏暂时没有可玩的版本');
+        }
+        const entryUrl = normalizeGameEntryUrl(value.currentVersion.entryUrl);
+        if (!entryUrl) throw new Error('游戏入口地址无效');
+        setGame({
+          ...value,
+          currentVersion: { ...value.currentVersion, entryUrl },
+        });
+      })
+      .catch((loadError: unknown) => {
+        if (requestSerial !== requestSerialRef.current) return;
+        setError(
+          loadError instanceof Error ? loadError.message : '游戏加载失败',
+        );
+      })
+      .finally(() => {
+        if (requestSerial === requestSerialRef.current) setIsLoading(false);
+      });
+  }, [gameId]);
+
+  useEffect(() => {
+    void loadGame();
+    return () => {
+      requestSerialRef.current += 1;
+    };
+  }, [loadGame]);
+
+  useEffect(() => {
+    if (!hasStarted || startupState !== 'loading') return undefined;
+    const timeoutId = window.setTimeout(() => {
+      setStartupState((current) =>
+        current === 'loading' ? 'timeout' : current,
+      );
+    }, GAME_PLAY_STARTUP_TIMEOUT_MS);
+    return () => window.clearTimeout(timeoutId);
+  }, [hasStarted, startupState]);
+
+  const enterFullscreen = () => {
+    void frameRef.current?.requestFullscreen?.();
+  };
+
+  const mobilePlaybackBlocked = isMobileViewport && !game?.deviceSupport.mobile;
+  const showRotationHint =
+    Boolean(game) && game?.orientation === 'landscape' && isPortraitViewport;
+  const startGame = () => {
+    if (mobilePlaybackBlocked) return;
+    setHasStarted(true);
+    setStartupState('loading');
+    setFrameRunId((runId) => runId + 1);
+  };
+
+  /** 重试只重挂载发行页，不改变已开始的会话，也不会在退出后自动重启。 */
+  const retryGame = () => {
+    setStartupState('loading');
+    setFrameRunId((runId) => runId + 1);
+  };
+
+  if (isLoading)
+    return (
+      <div className="game-play-page">
+        <div className="game-loading-panel">正在准备游戏…</div>
+      </div>
+    );
+  if (error || !game?.currentVersion)
+    return (
+      <div className="game-play-page">
+        <button type="button" className="game-back-button" onClick={onBack}>
+          <ArrowLeft /> 返回详情
+        </button>
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          className="game-status-message"
+        >
+          <span>{error || '游戏版本不可用'}</span>
+          <button type="button" onClick={loadGame}>
+            重新加载
+          </button>
+        </PlatformStatusMessage>
+      </div>
+    );
+
+  return (
+    <div className="game-play-page">
+      <div className="game-play-toolbar">
+        <button type="button" className="game-back-button" onClick={onBack}>
+          <ArrowLeft /> {game.title}
+        </button>
+        <div className="game-play-toolbar__actions">
+          <span className="game-play-device-hint">
+            <Smartphone aria-hidden="true" />{' '}
+            {game.deviceSupport.touch ? '支持触屏' : '桌面端游戏'}
+          </span>
+          <button
+            type="button"
+            className="game-icon-button"
+            aria-label="重新加载游戏"
+            onClick={loadGame}
+          >
+            <RotateCcw />
+          </button>
+          <PlatformActionButton
+            size="sm"
+            shape="pill"
+            onClick={enterFullscreen}
+            disabled={!hasStarted}
+          >
+            <Expand /> 全屏
+          </PlatformActionButton>
+        </div>
+      </div>
+      {showRotationHint ? (
+        <p className="game-device-warning" role="status">
+          这款游戏以横屏设计，旋转设备即可获得完整画面。
+        </p>
+      ) : null}
+      <div className="game-player-shell">
+        {!hasStarted ? (
+          <div className="game-player-launch">
+            <GameCover game={game} compact />
+            <div className="game-player-launch__copy">
+              <h1>{game.title}</h1>
+              <p>{game.summary}</p>
+              {mobilePlaybackBlocked ? (
+                <p
+                  className="game-device-warning"
+                  role="status"
+                  id="game-play-mobile-warning"
+                >
+                  请在电脑上游玩
+                </p>
+              ) : null}
+              <PlatformActionButton
+                size="lg"
+                shape="pill"
+                onClick={startGame}
+                disabled={mobilePlaybackBlocked}
+                aria-describedby={
+                  mobilePlaybackBlocked ? 'game-play-mobile-warning' : undefined
+                }
+              >
+                <Gamepad2 aria-hidden="true" /> 开始游戏
+              </PlatformActionButton>
+            </div>
+          </div>
+        ) : null}
+        {hasStarted && startupState === 'loading' ? (
+          <div className="game-player-loading">游戏正在启动…</div>
+        ) : null}
+        {hasStarted && startupState === 'timeout' ? (
+          <PlatformStatusMessage
+            tone="error"
+            surface="platform"
+            className="game-status-message game-player-timeout"
+          >
+            <span>游戏启动超时，可能是网络较慢或发行包暂时不可用。</span>
+            <button type="button" onClick={retryGame}>
+              重试
+            </button>
+            <button type="button" onClick={onBack}>
+              返回详情
+            </button>
+          </PlatformStatusMessage>
+        ) : null}
+        {hasStarted ? (
+          <iframe
+            ref={frameRef}
+            key={`${game.currentVersion.id}:${frameRunId}`}
+            title={`${game.title} 在线游玩`}
+            src={game.currentVersion.entryUrl}
+            className={`game-player-frame ${startupState === 'ready' ? 'game-player-frame--ready' : ''}`}
+            sandbox="allow-scripts"
+            allow="fullscreen"
+            referrerPolicy="no-referrer"
+            onLoad={() => setStartupState('ready')}
+          />
+        ) : null}
+      </div>
+      <p className="game-play-safety-note">
+        游戏运行在隔离容器中，不会读取你的账号信息或平台数据。
+      </p>
+    </div>
+  );
+}
+
+export default GamePlayPage;
diff --git a/src/components/game-distribution/GamePublishPage.test.tsx b/src/components/game-distribution/GamePublishPage.test.tsx
new file mode 100644
index 000000000..eccce8320
--- /dev/null
+++ b/src/components/game-distribution/GamePublishPage.test.tsx
@@ -0,0 +1,670 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import JSZip from 'jszip';
+import type { ContextType } from 'react';
+import { beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  createGame,
+  createGameVersion,
+  getGameVersion,
+  listMyGames,
+  submitGameVersion,
+  uploadGamePackage,
+} from '../../services/gameDistributionClient';
+import { AuthUiContext } from '../auth/AuthUiContext';
+import {
+  resolveGamePublishImagePreview,
+  uploadGamePublishImageAsset,
+} from './gamePublishAssets';
+import { resolvePublishMetadataError } from './gamePublishMetadata';
+import { GamePublishPage } from './GamePublishPage';
+
+const loadFrontendRuntimeConfigMock = vi.hoisted(() => vi.fn());
+
+// 发布灰度由后端运行时配置决定；这里默认放行，灰度用例单独覆盖。
+vi.mock('../../services/frontendRuntimeConfigService', () => ({
+  loadFrontendRuntimeConfig: (...args: unknown[]) =>
+    loadFrontendRuntimeConfigMock(...args),
+}));
+
+// 只替换真实上传与换签，保留常量与本地校验，避免测试真的打 OSS。
+vi.mock('./gamePublishAssets', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./gamePublishAssets')>();
+  return {
+    ...actual,
+    uploadGamePublishImageAsset: vi.fn(),
+    resolveGamePublishImagePreview: vi.fn(),
+  };
+});
+
+vi.mock('../../services/gameDistributionClient', () => ({
+  createGame: vi.fn(),
+  createGameVersion: vi.fn(),
+  getGameVersion: vi.fn(),
+  listMyGames: vi.fn(),
+  submitGameVersion: vi.fn(),
+  uploadGamePackage: vi.fn(),
+}));
+
+type AuthValue = NonNullable<ContextType<typeof AuthUiContext>>;
+
+function createAuthValue(overrides: Partial<AuthValue> = {}): AuthValue {
+  return {
+    user: {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试作者',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    },
+    canAccessProtectedData: true,
+    openLoginModal: vi.fn(),
+    requireAuth: vi.fn((action: () => void) => action()),
+    openSettingsModal: vi.fn(),
+    openAccountModal: vi.fn(),
+    setCurrentUser: vi.fn(),
+    logout: vi.fn(),
+    musicVolume: 0.5,
+    setMusicVolume: vi.fn(),
+    platformTheme: 'light',
+    setPlatformTheme: vi.fn(),
+    isHydratingSettings: false,
+    isPersistingSettings: false,
+    settingsError: null,
+    ...overrides,
+  };
+}
+
+async function buildZipFile() {
+  const zip = new JSZip();
+  zip.file('index.html', '<html><body>ok</body></html>');
+  zip.file('assets/app.js', 'console.log(1)');
+  const bytes = await zip.generateAsync({ type: 'uint8array' });
+  return new File([bytes as unknown as BlobPart], 'game.zip', {
+    type: 'application/zip',
+  });
+}
+
+function renderPublishPage(
+  authValue: AuthValue | null,
+  updateGameId: string | null = null,
+) {
+  return render(
+    <AuthUiContext.Provider value={authValue}>
+      <GamePublishPage
+        onBack={vi.fn()}
+        onOpenMyGames={vi.fn()}
+        updateGameId={updateGameId}
+      />
+    </AuthUiContext.Provider>,
+  );
+}
+
+/** 渲染并等待发布灰度检查结束（放行后才渲染表单）。 */
+async function renderPage(authValue: AuthValue | null = createAuthValue()) {
+  const result = renderPublishPage(authValue);
+  if (authValue) {
+    await screen.findByLabelText('游戏名称');
+  }
+  return result;
+}
+
+function buildImageFile(name: string, type = 'image/png') {
+  return new File(['image-bytes'], name, { type });
+}
+
+beforeEach(() => {
+  loadFrontendRuntimeConfigMock.mockReset();
+  loadFrontendRuntimeConfigMock.mockResolvedValue({
+    imageEditorAgentSidebarEnabled: false,
+    agcTemplateLibraryEnabled: false,
+    gameDistributionPublishEnabled: true,
+  });
+  vi.mocked(uploadGamePublishImageAsset).mockReset();
+  vi.mocked(resolveGamePublishImagePreview).mockReset();
+  vi.mocked(resolveGamePublishImagePreview).mockResolvedValue('');
+  vi.mocked(uploadGamePublishImageAsset).mockImplementation(
+    async (file: File) => ({
+      assetObjectId: `asset-${file.name}`,
+      objectKey: `game-distribution/uploads/${file.name}`,
+      src: `https://cdn.example.com/${file.name}`,
+      name: file.name,
+    }),
+  );
+  vi.mocked(createGame).mockReset();
+  vi.mocked(createGameVersion).mockReset();
+  vi.mocked(getGameVersion).mockReset();
+  vi.mocked(listMyGames).mockReset();
+  vi.mocked(uploadGamePackage).mockReset();
+  vi.mocked(submitGameVersion).mockReset();
+  window.localStorage.clear();
+});
+
+async function selectCover() {
+  fireEvent.change(screen.getByLabelText(/游戏封面/u), {
+    target: { files: [buildImageFile('cover.png')] },
+  });
+  await screen.findByText(/已选择「cover.png」/u);
+}
+
+async function selectScreenshots(names: string[]) {
+  fireEvent.change(screen.getByLabelText(/游戏截图/u), {
+    target: { files: names.map((name) => buildImageFile(name)) },
+  });
+  for (const name of names) {
+    await screen.findByText(new RegExp(`截图 ${names.indexOf(name) + 1}`, 'u'));
+  }
+}
+
+function writeDraft(ownerUserId: string) {
+  window.localStorage.setItem(
+    'genarrative.game-distribution.publish-draft.v1',
+    JSON.stringify({
+      ownerUserId,
+      gameId: 'game-1',
+      versionId: 'gamever-1',
+      versionNumber: 1,
+      title: '上次的游戏',
+      updatedAt: '2026-09-20T09:00:00.000Z',
+    }),
+  );
+}
+
+test('元数据校验与服务端口径一致', () => {
+  const desktop = { desktop: true, mobile: false, touch: false };
+  expect(
+    resolvePublishMetadataError({
+      title: '   ',
+      summary: '简介',
+      deviceSupport: desktop,
+      coverAssetId: 'asset-cover',
+    }),
+  ).toBe('游戏标题必须为 1 到 40 个字符');
+  expect(
+    resolvePublishMetadataError({
+      title: '游戏',
+      summary: '简介',
+      deviceSupport: { desktop: false, mobile: true, touch: false },
+      coverAssetId: 'asset-cover',
+    }),
+  ).toBe('选择移动端时必须支持触控');
+  expect(
+    resolvePublishMetadataError({
+      title: '游戏',
+      summary: '简介',
+      deviceSupport: { desktop: false, mobile: false, touch: false },
+      coverAssetId: 'asset-cover',
+    }),
+  ).toBe('至少选择桌面端或移动端');
+  // 服务端要求发布必须带封面，且截图上限 6 张。
+  expect(
+    resolvePublishMetadataError({
+      title: '游戏',
+      summary: '简介',
+      deviceSupport: desktop,
+    }),
+  ).toBe('发布游戏必须提供封面');
+  expect(
+    resolvePublishMetadataError({
+      title: '游戏',
+      summary: '简介',
+      deviceSupport: desktop,
+      coverAssetId: 'asset-cover',
+      screenshotCount: 7,
+    }),
+  ).toBe('游戏截图最多 6 张');
+  expect(
+    resolvePublishMetadataError({
+      title: '游戏',
+      summary: '简介',
+      deviceSupport: desktop,
+      coverAssetId: 'asset-cover',
+      screenshotCount: 6,
+    }),
+  ).toBe('');
+});
+
+test('未登录时不提交且提示登录', async () => {
+  await renderPage(null);
+  expect(screen.getByText('登录后才能发布游戏。')).toBeTruthy();
+  fireEvent.click(screen.getByRole('button', { name: /提交审核/u }));
+  expect(createGame).not.toHaveBeenCalled();
+});
+
+test('缺少发行包时不上传', async () => {
+  await renderPage();
+  fireEvent.change(screen.getByLabelText('游戏名称'), {
+    target: { value: '测试游戏' },
+  });
+  fireEvent.change(screen.getByLabelText('一句话简介'), {
+    target: { value: '测试简介' },
+  });
+  await selectCover();
+  fireEvent.click(screen.getByRole('button', { name: /提交审核/u }));
+  expect(await screen.findByText('请选择发行包 ZIP')).toBeTruthy();
+  expect(createGame).not.toHaveBeenCalled();
+});
+
+test('缺少封面时本地先拦截且不创建游戏', async () => {
+  await renderPage();
+  const file = await buildZipFile();
+  fireEvent.change(screen.getByLabelText('游戏名称'), {
+    target: { value: '测试游戏' },
+  });
+  fireEvent.change(screen.getByLabelText('一句话简介'), {
+    target: { value: '测试简介' },
+  });
+  fireEvent.change(screen.getByLabelText(/发行包 ZIP/u), {
+    target: { files: [file] },
+  });
+  fireEvent.click(screen.getByRole('button', { name: /提交审核/u }));
+
+  expect(await screen.findByText('发布游戏必须提供封面')).toBeTruthy();
+  expect(createGame).not.toHaveBeenCalled();
+  expect(uploadGamePackage).not.toHaveBeenCalled();
+});
+
+test('封面上传失败时给出原因且不提交', async () => {
+  vi.mocked(uploadGamePublishImageAsset).mockRejectedValue(
+    new Error('游戏封面过大，请压缩后再上传（当前 9.0MB，最多 6MB）。'),
+  );
+  await renderPage();
+  fireEvent.change(screen.getByLabelText(/游戏封面/u), {
+    target: { files: [buildImageFile('huge.png')] },
+  });
+
+  expect(
+    await screen.findByText(
+      '游戏封面过大，请压缩后再上传（当前 9.0MB，最多 6MB）。',
+    ),
+  ).toBeTruthy();
+  expect(createGame).not.toHaveBeenCalled();
+});
+
+test('截图超过 6 张时本地拦截', async () => {
+  await renderPage();
+  const files = Array.from({ length: 7 }, (_, index) =>
+    buildImageFile(`shot-${index}.png`),
+  );
+  fireEvent.change(screen.getByLabelText(/游戏截图/u), {
+    target: { files },
+  });
+
+  expect(await screen.findByText(/游戏截图最多 6 张/u)).toBeTruthy();
+  expect(uploadGamePublishImageAsset).not.toHaveBeenCalled();
+  expect(createGame).not.toHaveBeenCalled();
+});
+
+test('按创建游戏、创建版本、上传、送审顺序提交并展示审核中', async () => {
+  vi.mocked(createGame).mockResolvedValue({
+    id: 'game-1',
+    publicationRevision: 0,
+  } as never);
+  vi.mocked(createGameVersion).mockResolvedValue({
+    gameId: 'game-1',
+    versionId: 'gamever-1',
+    versionNumber: 1,
+    status: 'awaiting_upload',
+  });
+  vi.mocked(uploadGamePackage).mockResolvedValue({
+    versionId: 'gamever-1',
+    status: 'uploaded',
+  });
+  vi.mocked(submitGameVersion).mockResolvedValue({
+    version: { status: 'pending_review' },
+  });
+
+  await renderPage();
+  const file = await buildZipFile();
+  fireEvent.change(screen.getByLabelText('游戏名称'), {
+    target: { value: '测试游戏' },
+  });
+  fireEvent.change(screen.getByLabelText('一句话简介'), {
+    target: { value: '测试简介' },
+  });
+  fireEvent.change(screen.getByLabelText(/发行包 ZIP/u), {
+    target: { files: [file] },
+  });
+  await selectCover();
+  await selectScreenshots(['shot-1.png', 'shot-2.png']);
+  fireEvent.click(screen.getByRole('button', { name: /提交审核/u }));
+
+  await waitFor(() => expect(submitGameVersion).toHaveBeenCalledTimes(1));
+  expect(vi.mocked(createGame).mock.calls[0]?.[0]).toEqual(
+    expect.objectContaining({
+      title: '测试游戏',
+      summary: '测试简介',
+      category: '休闲',
+      inputModes: ['keyboard', 'mouse', 'touch'],
+      coverAssetId: 'asset-cover.png',
+      screenshots: ['asset-shot-1.png', 'asset-shot-2.png'],
+    }),
+  );
+  expect(vi.mocked(createGameVersion).mock.calls[0]?.[0]).toBe('game-1');
+  const versionPayload = vi.mocked(createGameVersion).mock.calls[0]?.[1];
+  expect(versionPayload?.packageEntryPath).toBe('index.html');
+  expect(versionPayload?.packageFileCount).toBe(2);
+  expect(versionPayload?.packageSha256).toMatch(/^[0-9a-f]{64}$/u);
+  expect(vi.mocked(uploadGamePackage).mock.calls[0]?.[0]).toBe('gamever-1');
+  expect(vi.mocked(submitGameVersion).mock.calls[0]?.[1]).toBe(0);
+
+  expect(
+    await screen.findByText('已提交审核，审核通过后会自动出现在游戏广场。'),
+  ).toBeTruthy();
+});
+
+test('后端失败时不伪造成功', async () => {
+  vi.mocked(createGame).mockRejectedValue(
+    new Error('游戏分发服务暂不可用（503）'),
+  );
+  await renderPage();
+  const file = await buildZipFile();
+  fireEvent.change(screen.getByLabelText('游戏名称'), {
+    target: { value: '测试游戏' },
+  });
+  fireEvent.change(screen.getByLabelText('一句话简介'), {
+    target: { value: '测试简介' },
+  });
+  fireEvent.change(screen.getByLabelText(/发行包 ZIP/u), {
+    target: { files: [file] },
+  });
+  await selectCover();
+  fireEvent.click(screen.getByRole('button', { name: /提交审核/u }));
+
+  expect(await screen.findByText('游戏分发服务暂不可用（503）')).toBeTruthy();
+  expect(
+    screen.queryByText('已提交审核，审核通过后会自动出现在游戏广场。'),
+  ).toBeNull();
+});
+
+test('同一账号回到发布页可以沿用原版本继续送审', async () => {
+  writeDraft('user-1');
+  vi.mocked(getGameVersion).mockResolvedValue({
+    game: {
+      id: 'game-1',
+      title: '上次的游戏',
+      summary: '上次的简介',
+      description: '上次的详细介绍',
+      publicationRevision: 2,
+    },
+    version: {
+      versionId: 'gamever-1',
+      versionNumber: 1,
+      status: 'uploaded',
+      recoveryAction: 'submit',
+    },
+  } as never);
+  vi.mocked(submitGameVersion).mockResolvedValue({
+    version: { status: 'pending_review' },
+  });
+
+  await renderPage();
+
+  expect(await screen.findByText(/上次发布未完成|发行包已上传/u)).toBeTruthy();
+  fireEvent.click(await screen.findByRole('button', { name: '继续送审' }));
+
+  // 已上传的版本不再重复创建游戏、创建版本或上传发行包。
+  expect(createGame).not.toHaveBeenCalled();
+  expect(createGameVersion).not.toHaveBeenCalled();
+  expect(uploadGamePackage).not.toHaveBeenCalled();
+  await waitFor(() => expect(submitGameVersion).toHaveBeenCalledTimes(1));
+  expect(vi.mocked(submitGameVersion).mock.calls[0]?.[0]).toBe('gamever-1');
+  expect(vi.mocked(submitGameVersion).mock.calls[0]?.[1]).toBe(2);
+  expect(
+    await screen.findByText('已提交审核，审核通过后会自动出现在游戏广场。'),
+  ).toBeTruthy();
+  expect(
+    window.localStorage.getItem(
+      'genarrative.game-distribution.publish-draft.v1',
+    ),
+  ).toBeNull();
+});
+
+test('换账号不回读上一账号的发布草稿', async () => {
+  writeDraft('user-1');
+  await renderPage(
+    createAuthValue({
+      user: { ...createAuthValue().user!, id: 'user-2' },
+    }),
+  );
+
+  await waitFor(() => expect(screen.queryByText(/上次发布未完成/u)).toBeNull());
+  expect(getGameVersion).not.toHaveBeenCalled();
+  // 草稿仍属于原账号，换账号只忽略、不删除。
+  expect(
+    window.localStorage.getItem(
+      'genarrative.game-distribution.publish-draft.v1',
+    ),
+  ).not.toBeNull();
+});
+
+test('更新模式在既有 gameId 下创建新版本并沿用公开修订号', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    {
+      id: 'game-1',
+      title: '星轨防线',
+      summary: '守住轨道城',
+      description: '旧版资料',
+      category: '动作',
+      tags: ['塔防'],
+      publicationRevision: 4,
+      latestVersion: {
+        versionId: 'gamever-2',
+        gameId: 'game-1',
+        versionNumber: 2,
+        packageSha256: 'd'.repeat(64),
+        packageBytes: 1024,
+        status: 'published',
+        publicationRevision: 4,
+        reviewReason: null,
+        createdAt: '2026-09-20T08:00:00Z',
+        updatedAt: '2026-09-20T09:00:00Z',
+      },
+      versions: [],
+    } as never,
+  ]);
+  vi.mocked(getGameVersion).mockResolvedValue({
+    game: {
+      id: 'game-1',
+      title: '星轨防线',
+      summary: '守住轨道城',
+      description: '旧版资料',
+      category: '动作',
+      tags: ['塔防'],
+      publicationRevision: 4,
+    },
+    version: {
+      versionId: 'gamever-2',
+      versionNumber: 2,
+      status: 'published',
+      publicationRevision: 4,
+      recoveryAction: 'none',
+      frozenMetadata: {
+        coverAssetId: 'asset-cover-old',
+        coverObjectKey: 'game-distribution/cover/old.png',
+        screenshots: [
+          {
+            assetId: 'asset-shot-old',
+            objectKey: 'game-distribution/screenshot/old.png',
+          },
+        ],
+      },
+    },
+  } as never);
+  vi.mocked(createGameVersion).mockResolvedValue({
+    gameId: 'game-1',
+    versionId: 'gamever-3',
+    versionNumber: 3,
+    status: 'awaiting_upload',
+  });
+  vi.mocked(uploadGamePackage).mockResolvedValue({
+    versionId: 'gamever-3',
+    status: 'uploaded',
+  });
+  vi.mocked(submitGameVersion).mockResolvedValue({
+    version: { status: 'pending_review' },
+  });
+
+  renderPublishPage(createAuthValue(), 'game-1');
+
+  expect(
+    await screen.findByText(/正在为《星轨防线》发布新版本 v3/u),
+  ).toBeTruthy();
+  await screen.findByLabelText('游戏名称');
+  expect(screen.getByLabelText('游戏名称')).toHaveProperty('value', '星轨防线');
+  expect(screen.getByLabelText('分类')).toHaveProperty('value', '动作');
+
+  // 冻结资料直接回填封面与截图，作者不需要为了沿用封面重新上传一次。
+  await waitFor(() =>
+    expect(resolveGamePublishImagePreview).toHaveBeenCalledWith(
+      'game-distribution/cover/old.png',
+    ),
+  );
+  expect(uploadGamePublishImageAsset).not.toHaveBeenCalled();
+
+  const file = await buildZipFile();
+  fireEvent.change(screen.getByLabelText(/发行包 ZIP/u), {
+    target: { files: [file] },
+  });
+  fireEvent.click(screen.getByRole('button', { name: '提交新版本审核' }));
+
+  await waitFor(() => expect(submitGameVersion).toHaveBeenCalledTimes(1));
+  // 更新模式不得新建游戏，必须在同一个 gameId 下创建新版本。
+  expect(createGame).not.toHaveBeenCalled();
+  expect(vi.mocked(createGameVersion).mock.calls[0]?.[0]).toBe('game-1');
+  expect(vi.mocked(createGameVersion).mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      packageEntryPath: 'index.html',
+      gameMetadata: expect.objectContaining({
+        title: '星轨防线',
+        category: '动作',
+        tags: ['塔防'],
+        coverAssetId: 'asset-cover-old',
+        screenshots: ['asset-shot-old'],
+      }),
+    }),
+  );
+  expect(vi.mocked(submitGameVersion).mock.calls[0]?.[0]).toBe('gamever-3');
+  expect(vi.mocked(submitGameVersion).mock.calls[0]?.[1]).toBe(4);
+  expect(
+    await screen.findByText('已提交审核，审核通过后会自动出现在游戏广场。'),
+  ).toBeTruthy();
+});
+
+test('线上封面没有冻结素材时要求重新选择封面', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    {
+      id: 'game-1',
+      title: '星轨防线',
+      summary: '守住轨道城',
+      description: '旧版资料',
+      category: '动作',
+      tags: ['塔防'],
+      publicationRevision: 4,
+      latestVersion: {
+        versionId: 'gamever-2',
+        gameId: 'game-1',
+        versionNumber: 2,
+        packageSha256: 'd'.repeat(64),
+        packageBytes: 1024,
+        status: 'published',
+        publicationRevision: 4,
+        reviewReason: null,
+        createdAt: '2026-09-20T08:00:00Z',
+        updatedAt: '2026-09-20T09:00:00Z',
+      },
+      versions: [],
+    } as never,
+  ]);
+  // 历史版本没有冻结快照：只能看到线上封面，但没有可复用的素材 ID。
+  vi.mocked(getGameVersion).mockResolvedValue({
+    game: {
+      id: 'game-1',
+      title: '星轨防线',
+      summary: '守住轨道城',
+      description: '旧版资料',
+      category: '动作',
+      tags: ['塔防'],
+      publicationRevision: 4,
+      coverObjectKey: 'game-distribution/cover/legacy.png',
+    },
+    version: {
+      versionId: 'gamever-2',
+      versionNumber: 2,
+      status: 'published',
+      publicationRevision: 4,
+      recoveryAction: 'none',
+      frozenMetadata: null,
+    },
+  } as never);
+
+  renderPublishPage(createAuthValue(), 'game-1');
+
+  expect(
+    await screen.findByText(/本次发布需要重新选择一次封面图片/u),
+  ).toBeTruthy();
+  await screen.findByLabelText('游戏名称');
+  const file = await buildZipFile();
+  fireEvent.change(screen.getByLabelText(/发行包 ZIP/u), {
+    target: { files: [file] },
+  });
+  fireEvent.click(screen.getByRole('button', { name: '提交新版本审核' }));
+
+  expect(
+    await screen.findByText(
+      '本次发布需要重新选择一次封面图片（当前展示的是线上封面）',
+    ),
+  ).toBeTruthy();
+  expect(createGameVersion).not.toHaveBeenCalled();
+});
+
+test('更新模式读不到归属游戏时失败关闭且不提交', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([]);
+
+  renderPublishPage(createAuthValue(), 'game-missing');
+
+  expect(
+    await screen.findByText('找不到这个游戏，或它不属于当前账号'),
+  ).toBeTruthy();
+  expect(screen.getByRole('button', { name: '提交新版本审核' })).toHaveProperty(
+    'disabled',
+    true,
+  );
+  expect(createGameVersion).not.toHaveBeenCalled();
+});
+
+test('灰度未命中时隐藏发布表单并给出可操作提示', async () => {
+  loadFrontendRuntimeConfigMock.mockResolvedValue({
+    imageEditorAgentSidebarEnabled: false,
+    agcTemplateLibraryEnabled: false,
+    gameDistributionPublishEnabled: false,
+  });
+  renderPublishPage(createAuthValue());
+
+  expect(await screen.findByText('发布功能正在灰度中')).toBeTruthy();
+  expect(screen.getByText(/当前账号还没有发布入口/u)).not.toBeNull();
+  expect(screen.queryByLabelText('游戏名称')).toBeNull();
+  expect(createGame).not.toHaveBeenCalled();
+
+  // 灰度开放后「重新检查」应放行并渲染表单。
+  loadFrontendRuntimeConfigMock.mockResolvedValue({
+    imageEditorAgentSidebarEnabled: false,
+    agcTemplateLibraryEnabled: false,
+    gameDistributionPublishEnabled: true,
+  });
+  fireEvent.click(screen.getByRole('button', { name: '重新检查' }));
+  expect(await screen.findByLabelText('游戏名称')).not.toBeNull();
+});
+
+test('灰度配置读取失败时不拦前端，由后端写入口把关', async () => {
+  loadFrontendRuntimeConfigMock.mockRejectedValue(new Error('network down'));
+  await renderPage();
+
+  expect(screen.getByLabelText('游戏名称')).not.toBeNull();
+  expect(screen.queryByText('发布功能正在灰度中')).toBeNull();
+});
diff --git a/src/components/game-distribution/GamePublishPage.tsx b/src/components/game-distribution/GamePublishPage.tsx
new file mode 100644
index 000000000..3c92099be
--- /dev/null
+++ b/src/components/game-distribution/GamePublishPage.tsx
@@ -0,0 +1,1076 @@
+import './gameDistribution.css';
+
+import { ArrowLeft, Upload } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+import type {
+  GameDistributionCategory,
+  GameDistributionDeviceSupport,
+  GameDistributionInputMode,
+  GameDistributionOrientation,
+  GameDistributionVersionDetail,
+} from '../../../packages/shared/src/contracts/gameDistribution';
+import { loadFrontendRuntimeConfig } from '../../services/frontendRuntimeConfigService';
+import {
+  createGame,
+  createGameVersion,
+  getGameVersion,
+  listMyGames,
+  submitGameVersion,
+  uploadGamePackage,
+} from '../../services/gameDistributionClient';
+import { useAuthUi } from '../auth/AuthUiContext';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import {
+  GAME_PUBLISH_IMAGE_ACCEPT,
+  type GamePublishImageAsset,
+  MAX_GAME_SCREENSHOTS,
+  resolveGamePublishImagePreview,
+  uploadGamePublishImageAsset,
+} from './gamePublishAssets';
+import {
+  clearPublishDraft,
+  type GamePublishDraft,
+  readPublishDraft,
+  resolvePublishDraftRecoveryCopy,
+  writePublishDraft,
+} from './gamePublishDraft';
+import { resolvePublishMetadataError } from './gamePublishMetadata';
+import { prepareGamePackage } from './gameZipPackage';
+
+const CATEGORIES: GameDistributionCategory[] = [
+  '休闲',
+  '益智',
+  '动作',
+  '冒险',
+  '模拟',
+  '策略',
+  '其他',
+];
+
+const ORIENTATIONS: Array<{
+  value: GameDistributionOrientation;
+  label: string;
+}> = [
+  { value: 'responsive', label: '自适应' },
+  { value: 'landscape', label: '横屏' },
+  { value: 'portrait', label: '竖屏' },
+];
+
+type GamePublishPageProps = {
+  onBack: () => void;
+  onOpenMyGames: () => void;
+  /** 设置后进入“为既有游戏发布新版本”模式，沿用同一个 gameId。 */
+  updateGameId?: string | null;
+};
+
+type GameUpdateContext = {
+  gameId: string;
+  publicationRevision: number;
+  versionNumber: number;
+  title: string;
+};
+
+let publishKeySeed = 0;
+function createPublishKey() {
+  publishKeySeed += 1;
+  const random =
+    typeof crypto !== 'undefined' && 'randomUUID' in crypto
+      ? crypto.randomUUID()
+      : `${Date.now()}-${publishKeySeed}`;
+  return `web-publish-${random}`;
+}
+
+type VersionMediaApplyTarget = {
+  setCover: (
+    updater: (
+      current: GamePublishImageAsset | null,
+    ) => GamePublishImageAsset | null,
+  ) => void;
+  setScreenshots: (
+    updater: (current: GamePublishImageAsset[]) => GamePublishImageAsset[],
+  ) => void;
+  isCancelled: () => boolean;
+};
+
+/**
+ * 用版本冻结资料回填封面与截图。
+ *
+ * 快照缺失（或旧版本没存素材 ID）时只回填线上封面预览：此时创作者必须重新选择一次封面，
+ * 因为服务端只接受素材 ID 作为冻结输入，前端不能凭对象键猜素材身份。
+ */
+async function applyVersionMediaDefaults(
+  detail: GameDistributionVersionDetail,
+  apply: VersionMediaApplyTarget,
+) {
+  const frozen = detail.version.frozenMetadata ?? null;
+  const coverAssetId = frozen?.coverAssetId?.trim() ?? '';
+  const coverObjectKey =
+    frozen?.coverObjectKey?.trim() ?? detail.game.coverObjectKey?.trim() ?? '';
+  const coverName = detail.game.title.trim() || '当前封面';
+  const buildCover = (src: string): GamePublishImageAsset => ({
+    assetObjectId: coverAssetId,
+    objectKey: coverObjectKey,
+    src,
+    name: coverName,
+  });
+
+  const screenshots = (frozen?.screenshots ?? []).filter((screenshot) =>
+    Boolean(screenshot?.assetId?.trim()),
+  );
+  if (apply.isCancelled()) return;
+  apply.setCover(() =>
+    coverAssetId || coverObjectKey ? buildCover('') : null,
+  );
+  apply.setScreenshots(() =>
+    screenshots.map((screenshot, index) => ({
+      assetObjectId: screenshot.assetId.trim(),
+      objectKey: screenshot.objectKey?.trim() ?? '',
+      src: '',
+      name: `截图 ${index + 1}`,
+    })),
+  );
+
+  const coverPreview = await resolveGamePublishImagePreview(coverObjectKey);
+  if (apply.isCancelled()) return;
+  if (coverPreview) {
+    // 只在作者还没换图、且预览仍为空时补上签名地址，避免覆盖作者的新选择。
+    apply.setCover((current) =>
+      current && !current.src && current.objectKey === coverObjectKey
+        ? { ...current, src: coverPreview }
+        : current,
+    );
+  }
+  for (const [index, screenshot] of screenshots.entries()) {
+    const preview = await resolveGamePublishImagePreview(
+      screenshot.objectKey ?? '',
+    );
+    if (apply.isCancelled() || !preview) continue;
+    apply.setScreenshots((current) =>
+      current.map((item, itemIndex) =>
+        itemIndex === index && item.assetObjectId === screenshot.assetId
+          ? { ...item, src: preview }
+          : item,
+      ),
+    );
+  }
+}
+
+export function GamePublishPage({
+  onBack,
+  onOpenMyGames,
+  updateGameId = null,
+}: GamePublishPageProps) {
+  const authUi = useAuthUi();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const coverInputRef = useRef<HTMLInputElement>(null);
+  const screenshotInputRef = useRef<HTMLInputElement>(null);
+  const [title, setTitle] = useState('');
+  const [summary, setSummary] = useState('');
+  const [description, setDescription] = useState('');
+  const [category, setCategory] = useState<GameDistributionCategory>('休闲');
+  const [tagsInput, setTagsInput] = useState('');
+  const [deviceSupport, setDeviceSupport] =
+    useState<GameDistributionDeviceSupport>({
+      desktop: true,
+      mobile: true,
+      touch: true,
+    });
+  const [orientation, setOrientation] =
+    useState<GameDistributionOrientation>('responsive');
+  const [packageFile, setPackageFile] = useState<File | null>(null);
+  // 封面与截图都先上传成平台素材，再把素材 ID 交给服务端冻结；页面只保存素材标识与预览地址。
+  const [coverAsset, setCoverAsset] = useState<GamePublishImageAsset | null>(
+    null,
+  );
+  const [screenshotAssets, setScreenshotAssets] = useState<
+    GamePublishImageAsset[]
+  >([]);
+  const [isUploadingAsset, setIsUploadingAsset] = useState(false);
+  // 发布灰度：`checking` 期间不渲染表单，避免白名单外的作者先上传再被后端拒绝。
+  const [publishGate, setPublishGate] = useState<
+    'checking' | 'allowed' | 'blocked'
+  >('checking');
+  const [publishGateReloadSeed, setPublishGateReloadSeed] = useState(0);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState('');
+  const [publishedGameId, setPublishedGameId] = useState('');
+  const [draft, setDraft] = useState<GamePublishDraft | null>(null);
+  const [draftDetail, setDraftDetail] =
+    useState<GameDistributionVersionDetail | null>(null);
+  const [isResumingDraft, setIsResumingDraft] = useState(false);
+  const [updateContext, setUpdateContext] = useState<GameUpdateContext | null>(
+    null,
+  );
+  const [updateContextError, setUpdateContextError] = useState('');
+  const canPublish = Boolean(authUi?.user && authUi.canAccessProtectedData);
+  const currentUserId = authUi?.user?.id ?? '';
+
+  // 更新模式：先按 gameId 从作者中心定位最近版本，再回读它冻结的资料与公开修订号。
+  useEffect(() => {
+    if (!canPublish || !updateGameId) {
+      setUpdateContext(null);
+      setUpdateContextError('');
+      return;
+    }
+    let cancelled = false;
+    setUpdateContextError('');
+    listMyGames()
+      .then(async (games) => {
+        const game = games.find((item) => item.id === updateGameId);
+        if (!game) {
+          throw new Error('找不到这个游戏，或它不属于当前账号');
+        }
+        const latestVersionId = game.latestVersion?.versionId;
+        if (!latestVersionId) {
+          throw new Error('这个游戏还没有可续发的版本，请直接发布新游戏');
+        }
+        const detail = await getGameVersion(latestVersionId);
+        if (cancelled) return;
+        setTitle(detail.game.title);
+        setSummary(detail.game.summary);
+        setDescription(detail.game.description);
+        setCategory(detail.game.category);
+        setTagsInput(detail.game.tags.join('，'));
+        setUpdateContext({
+          gameId: game.id,
+          publicationRevision: detail.version.publicationRevision,
+          versionNumber: detail.version.versionNumber,
+          title: detail.game.title,
+        });
+        void applyVersionMediaDefaults(detail, {
+          setCover: setCoverAsset,
+          setScreenshots: setScreenshotAssets,
+          isCancelled: () => cancelled,
+        });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setUpdateContext(null);
+        setUpdateContextError(
+          error instanceof Error ? error.message : '读取待更新游戏失败',
+        );
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [canPublish, updateGameId]);
+
+  // 发布灰度：读后端运行时配置判定当前账号是否在灰度内；未登录时交给登录提示处理。
+  useEffect(() => {
+    if (!canPublish) {
+      setPublishGate('allowed');
+      return;
+    }
+    let cancelled = false;
+    setPublishGate('checking');
+    loadFrontendRuntimeConfig()
+      .then((config) => {
+        if (cancelled) return;
+        setPublishGate(
+          config.gameDistributionPublishEnabled === false
+            ? 'blocked'
+            : 'allowed',
+        );
+      })
+      .catch(() => {
+        if (cancelled) return;
+        // 读不到灰度配置时按“不拦前端、由后端写入口把关”处理：后端仍是唯一事实源，
+        // 收紧期间会在提交时返回 503 与可读文案，不会静默写入。
+        setPublishGate('allowed');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [canPublish, currentUserId, publishGateReloadSeed]);
+
+  // 只在当前账号与草稿 owner 一致时回读版本；换账号时忽略草稿，绝不展示上一账号状态。
+  useEffect(() => {
+    if (updateGameId) return undefined;
+    if (!canPublish || !currentUserId) {
+      setDraft(null);
+      setDraftDetail(null);
+      setIsResumingDraft(false);
+      return;
+    }
+    const stored = readPublishDraft();
+    if (!stored || stored.ownerUserId !== currentUserId) {
+      setDraft(null);
+      setDraftDetail(null);
+      setIsResumingDraft(false);
+      return;
+    }
+    let cancelled = false;
+    setDraft(stored);
+    getGameVersion(stored.versionId)
+      .then((detail) => {
+        if (cancelled) return;
+        setDraftDetail(detail);
+        setTitle(detail.game.title);
+        setSummary(detail.game.summary);
+        setDescription(detail.game.description);
+        void applyVersionMediaDefaults(detail, {
+          setCover: setCoverAsset,
+          setScreenshots: setScreenshotAssets,
+          isCancelled: () => cancelled,
+        });
+      })
+      .catch(() => {
+        if (cancelled) return;
+        setDraftDetail(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [canPublish, currentUserId, updateGameId]);
+
+  const resumeNeedsPackage =
+    isResumingDraft &&
+    draftDetail !== null &&
+    draftDetail.version.recoveryAction !== 'submit';
+
+  async function handleCoverSelected(file: File | null) {
+    if (!file) return;
+    setError('');
+    setIsUploadingAsset(true);
+    try {
+      const uploaded = await uploadGamePublishImageAsset(file, {
+        kind: 'cover',
+      });
+      setCoverAsset(uploaded);
+    } catch (uploadError: unknown) {
+      setError(
+        uploadError instanceof Error
+          ? uploadError.message
+          : '封面上传失败，请重试',
+      );
+    } finally {
+      setIsUploadingAsset(false);
+      // 清空 input 才能让作者重新选择同一张图。
+      if (coverInputRef.current) coverInputRef.current.value = '';
+    }
+  }
+
+  async function handleScreenshotsSelected(files: File[]) {
+    if (files.length === 0) return;
+    const remaining = MAX_GAME_SCREENSHOTS - screenshotAssets.length;
+    if (files.length > remaining) {
+      setError(
+        remaining > 0
+          ? `游戏截图最多 6 张，还可以再选 ${remaining} 张`
+          : '游戏截图最多 6 张',
+      );
+      if (screenshotInputRef.current) screenshotInputRef.current.value = '';
+      return;
+    }
+    setError('');
+    setIsUploadingAsset(true);
+    try {
+      for (const file of files) {
+        const uploaded = await uploadGamePublishImageAsset(file, {
+          kind: 'screenshot',
+        });
+        // 逐张入库：中途失败时已经传好的截图仍然保留，作者不用重新选择。
+        setScreenshotAssets((current) =>
+          current.length >= MAX_GAME_SCREENSHOTS
+            ? current
+            : [...current, uploaded],
+        );
+      }
+    } catch (uploadError: unknown) {
+      setError(
+        uploadError instanceof Error
+          ? uploadError.message
+          : '截图上传失败，请重试',
+      );
+    } finally {
+      setIsUploadingAsset(false);
+      if (screenshotInputRef.current) screenshotInputRef.current.value = '';
+    }
+  }
+
+  function removeScreenshotAsset(index: number) {
+    setScreenshotAssets((current) =>
+      current.filter((_, itemIndex) => itemIndex !== index),
+    );
+  }
+
+  /** 展示中的线上封面没有素材 ID 时无法冻结进新版本，必须先本地拦一次并说明原因。 */
+  function resolveMediaSubmitError() {
+    if (coverAsset && !coverAsset.assetObjectId.trim()) {
+      return '本次发布需要重新选择一次封面图片（当前展示的是线上封面）';
+    }
+    return '';
+  }
+
+  function dismissDraft() {
+    clearPublishDraft();
+    setDraft(null);
+    setDraftDetail(null);
+    setIsResumingDraft(false);
+  }
+
+  async function handleResumeSubmit() {
+    if (!draftDetail) {
+      setError('恢复的版本状态不可用，请重新选择发行包。');
+      return;
+    }
+    if (!packageFile && draftDetail.version.recoveryAction !== 'submit') {
+      setError('请选择上次那个发行包 ZIP 继续上传');
+      return;
+    }
+    setIsSubmitting(true);
+    setError('');
+    try {
+      const resumeKey = createPublishKey();
+      if (draftDetail.version.recoveryAction !== 'submit') {
+        const prepared = await prepareGamePackage(packageFile as File);
+        await uploadGamePackage(
+          draftDetail.version.versionId,
+          new Blob([prepared.bytes as unknown as BlobPart], {
+            type: 'application/zip',
+          }),
+          `${resumeKey}:upload`,
+        );
+      }
+      await submitGameVersion(
+        draftDetail.version.versionId,
+        draftDetail.game.publicationRevision,
+        `${resumeKey}:submit`,
+      );
+      clearPublishDraft();
+      setDraft(null);
+      setDraftDetail(null);
+      setIsResumingDraft(false);
+      setPublishedGameId(draftDetail.game.id);
+    } catch (resumeError: unknown) {
+      setError(
+        resumeError instanceof Error ? resumeError.message : '继续发布失败',
+      );
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  /**
+   * 更新模式：不调用创建游戏接口，直接在既有 `gameId` 下创建不可变新版本并送审；
+   * 公开版本只在管理员通过后切换，期间旧版本继续在线。
+   */
+  async function handleUpdateSubmit() {
+    if (!updateContext) {
+      setError(updateContextError || '待更新游戏尚未就绪，请稍后重试');
+      return;
+    }
+    const mediaError = resolveMediaSubmitError();
+    if (mediaError) {
+      setError(mediaError);
+      return;
+    }
+    const metadataError = resolvePublishMetadataError({
+      title,
+      summary,
+      deviceSupport,
+      coverAssetId: coverAsset?.assetObjectId,
+      screenshotCount: screenshotAssets.length,
+    });
+    if (metadataError) {
+      setError(metadataError);
+      return;
+    }
+    if (!packageFile) {
+      setError('请选择发行包 ZIP');
+      return;
+    }
+    setIsSubmitting(true);
+    setError('');
+    try {
+      const prepared = await prepareGamePackage(packageFile);
+      const updateKey = createPublishKey();
+      const inputModes: GameDistributionInputMode[] = ['keyboard', 'mouse'];
+      if (deviceSupport.touch) inputModes.push('touch');
+      const tags = tagsInput
+        .split(/[,，]/u)
+        .map((tag) => tag.trim())
+        .filter(Boolean)
+        .slice(0, 5);
+      const gameMetadata = {
+        title: title.trim(),
+        summary: summary.trim(),
+        description: description.trim() || summary.trim(),
+        category,
+        tags,
+        coverAssetId: coverAsset?.assetObjectId ?? '',
+        screenshots: screenshotAssets.map((asset) => asset.assetObjectId),
+        deviceSupport,
+        inputModes,
+        orientation,
+      };
+      const version = await createGameVersion(
+        updateContext.gameId,
+        {
+          packageSha256: prepared.sha256,
+          packageBytes: prepared.totalBytes,
+          packageFileCount: prepared.fileCount,
+          packageEntryPath: 'index.html',
+          gameMetadata,
+        },
+        `${updateKey}:version`,
+      );
+      await uploadGamePackage(
+        version.versionId,
+        new Blob([prepared.bytes as unknown as BlobPart], {
+          type: 'application/zip',
+        }),
+        `${updateKey}:upload`,
+      );
+      await submitGameVersion(
+        version.versionId,
+        updateContext.publicationRevision,
+        `${updateKey}:submit`,
+      );
+      setPublishedGameId(updateContext.gameId);
+      setUpdateContext((current) =>
+        current
+          ? { ...current, versionNumber: version.versionNumber }
+          : current,
+      );
+    } catch (updateError: unknown) {
+      setError(
+        updateError instanceof Error ? updateError.message : '发布新版本失败',
+      );
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  async function handleSubmit() {
+    if (updateGameId) {
+      await handleUpdateSubmit();
+      return;
+    }
+    if (isResumingDraft) {
+      await handleResumeSubmit();
+      return;
+    }
+    const mediaError = resolveMediaSubmitError();
+    if (mediaError) {
+      setError(mediaError);
+      return;
+    }
+    const metadataError = resolvePublishMetadataError({
+      title,
+      summary,
+      deviceSupport,
+      coverAssetId: coverAsset?.assetObjectId,
+      screenshotCount: screenshotAssets.length,
+    });
+    if (metadataError) {
+      setError(metadataError);
+      return;
+    }
+    if (!packageFile) {
+      setError('请选择发行包 ZIP');
+      return;
+    }
+    setIsSubmitting(true);
+    setError('');
+    try {
+      const prepared = await prepareGamePackage(packageFile);
+      const inputModes: GameDistributionInputMode[] = ['keyboard', 'mouse'];
+      if (deviceSupport.touch) inputModes.push('touch');
+      const tags = tagsInput
+        .split(/[,，]/u)
+        .map((tag) => tag.trim())
+        .filter(Boolean)
+        .slice(0, 5);
+      const gameMetadata = {
+        title: title.trim(),
+        summary: summary.trim(),
+        description: description.trim() || summary.trim(),
+        category,
+        tags,
+        coverAssetId: coverAsset?.assetObjectId ?? '',
+        screenshots: screenshotAssets.map((asset) => asset.assetObjectId),
+        deviceSupport,
+        inputModes,
+        orientation,
+      };
+      const publishKey = createPublishKey();
+      const game = await createGame(gameMetadata, `${publishKey}:game`);
+      const version = await createGameVersion(
+        game.id,
+        {
+          packageSha256: prepared.sha256,
+          packageBytes: prepared.totalBytes,
+          packageFileCount: prepared.fileCount,
+          packageEntryPath: 'index.html',
+          gameMetadata,
+        },
+        `${publishKey}:version`,
+      );
+      writePublishDraft({
+        ownerUserId: currentUserId,
+        gameId: game.id,
+        versionId: version.versionId,
+        versionNumber: version.versionNumber,
+        title: game.title,
+        updatedAt: new Date().toISOString(),
+      });
+      await uploadGamePackage(
+        version.versionId,
+        new Blob([prepared.bytes as unknown as BlobPart], {
+          type: 'application/zip',
+        }),
+        `${publishKey}:upload`,
+      );
+      await submitGameVersion(
+        version.versionId,
+        game.publicationRevision,
+        `${publishKey}:submit`,
+      );
+      clearPublishDraft();
+      setPublishedGameId(game.id);
+    } catch (submitError: unknown) {
+      setError(
+        submitError instanceof Error ? submitError.message : '发布游戏失败',
+      );
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  // 灰度检查期间与未命中时都不渲染表单：避免白名单外的作者先上传素材再被写入口拒绝。
+  if (canPublish && publishGate === 'checking') {
+    return (
+      <div className="game-page game-publish-page">
+        <button type="button" className="game-back-button" onClick={onBack}>
+          <ArrowLeft /> 返回游戏广场
+        </button>
+        <PlatformStatusMessage tone="info" surface="platform">
+          <span>正在检查发布灰度…</span>
+        </PlatformStatusMessage>
+      </div>
+    );
+  }
+
+  if (canPublish && publishGate === 'blocked') {
+    return (
+      <div className="game-page game-publish-page">
+        <button type="button" className="game-back-button" onClick={onBack}>
+          <ArrowLeft /> 返回游戏广场
+        </button>
+        <div className="game-toolbar">
+          <div className="game-toolbar__title">
+            <span className="game-eyebrow">发布游戏</span>
+            <h2>发布功能正在灰度中</h2>
+          </div>
+        </div>
+        <PlatformStatusMessage tone="info" surface="platform">
+          <span>
+            当前账号还没有发布入口，开放后可以直接在这里上传游戏；已公开的游戏不受影响，仍可正常游玩。
+          </span>
+          <button
+            type="button"
+            onClick={() => setPublishGateReloadSeed((current) => current + 1)}
+          >
+            重新检查
+          </button>
+        </PlatformStatusMessage>
+      </div>
+    );
+  }
+
+  return (
+    <div className="game-page game-publish-page">
+      <button type="button" className="game-back-button" onClick={onBack}>
+        <ArrowLeft /> 返回游戏广场
+      </button>
+      <div className="game-toolbar">
+        <div className="game-toolbar__title">
+          <span className="game-eyebrow">
+            {updateGameId ? '发布新版本' : '发布游戏'}
+          </span>
+          <h2>
+            {updateGameId
+              ? updateContext
+                ? `为《${updateContext.title}》发布 v${updateContext.versionNumber + 1}`
+                : '读取待更新游戏…'
+              : '上传可在线游玩的网页游戏'}
+          </h2>
+        </div>
+      </div>
+
+      {error ? (
+        <PlatformStatusMessage tone="error" surface="platform">
+          {error}
+        </PlatformStatusMessage>
+      ) : null}
+
+      {canPublish && updateGameId && !publishedGameId ? (
+        <PlatformStatusMessage
+          tone={updateContextError ? 'error' : 'info'}
+          surface="platform"
+        >
+          {updateContextError ? (
+            <span>{updateContextError}</span>
+          ) : updateContext ? (
+            <span>
+              正在为《{updateContext.title}》发布新版本 v
+              {updateContext.versionNumber + 1}
+              ：沿用同一个游戏身份，审核通过后才会替换线上版本。
+            </span>
+          ) : (
+            <span>正在读取待更新游戏…</span>
+          )}
+        </PlatformStatusMessage>
+      ) : null}
+
+      {!updateGameId &&
+      canPublish &&
+      draft &&
+      draftDetail &&
+      !publishedGameId ? (
+        <PlatformStatusMessage tone="info" surface="platform">
+          <span>
+            {
+              resolvePublishDraftRecoveryCopy(
+                draftDetail.version.recoveryAction,
+                draftDetail.version.versionNumber,
+              ).title
+            }
+            {'：'}
+            {
+              resolvePublishDraftRecoveryCopy(
+                draftDetail.version.recoveryAction,
+                draftDetail.version.versionNumber,
+              ).description
+            }
+          </span>
+          <span className="game-publish-recovery-actions">
+            {resolvePublishDraftRecoveryCopy(
+              draftDetail.version.recoveryAction,
+              draftDetail.version.versionNumber,
+            ).actionLabel ? (
+              <button
+                type="button"
+                onClick={() => {
+                  setError('');
+                  setIsResumingDraft(true);
+                  // 发行包已确认的版本不需要重新选包，直接续做送审。
+                  if (draftDetail.version.recoveryAction === 'submit') {
+                    void handleResumeSubmit();
+                  }
+                }}
+                disabled={isSubmitting}
+              >
+                {
+                  resolvePublishDraftRecoveryCopy(
+                    draftDetail.version.recoveryAction,
+                    draftDetail.version.versionNumber,
+                  ).actionLabel
+                }
+              </button>
+            ) : null}
+            <button type="button" onClick={onOpenMyGames}>
+              我的游戏
+            </button>
+            <button type="button" onClick={dismissDraft}>
+              不再提醒
+            </button>
+          </span>
+        </PlatformStatusMessage>
+      ) : null}
+
+      {publishedGameId ? (
+        <PlatformStatusMessage tone="success" surface="platform">
+          <span>已提交审核，审核通过后会自动出现在游戏广场。</span>
+          <button type="button" onClick={onOpenMyGames}>
+            查看我的游戏
+          </button>
+        </PlatformStatusMessage>
+      ) : null}
+
+      {!canPublish ? (
+        <PlatformStatusMessage tone="info" surface="platform">
+          <span>登录后才能发布游戏。</span>
+          <button type="button" onClick={() => authUi?.openLoginModal()}>
+            登录
+          </button>
+        </PlatformStatusMessage>
+      ) : null}
+
+      {isResumingDraft && !updateGameId ? (
+        <PlatformStatusMessage tone="info" surface="platform">
+          <span>
+            继续发布沿用上次冻结的资料与版本号，资料要改就撤回后在「我的游戏」重新发布。
+          </span>
+        </PlatformStatusMessage>
+      ) : null}
+
+      <form
+        className={`game-publish-form${isResumingDraft ? ' game-publish-form--resume' : ''}`}
+        onSubmit={(event) => {
+          event.preventDefault();
+          void handleSubmit();
+        }}
+      >
+        <label className="game-publish-field">
+          游戏名称
+          <input
+            value={title}
+            maxLength={40}
+            disabled={isResumingDraft}
+            onChange={(e) => setTitle(e.target.value)}
+          />
+        </label>
+        <label className="game-publish-field">
+          一句话简介
+          <input
+            value={summary}
+            maxLength={120}
+            disabled={isResumingDraft}
+            onChange={(e) => setSummary(e.target.value)}
+          />
+        </label>
+        <label className="game-publish-field">
+          详细介绍
+          <textarea
+            value={description}
+            rows={3}
+            maxLength={2000}
+            disabled={isResumingDraft}
+            onChange={(e) => setDescription(e.target.value)}
+          />
+        </label>
+        <div className="game-publish-row">
+          <label className="game-publish-field">
+            分类
+            <select
+              value={category}
+              disabled={isResumingDraft}
+              onChange={(e) =>
+                setCategory(e.target.value as GameDistributionCategory)
+              }
+            >
+              {CATEGORIES.map((item) => (
+                <option key={item} value={item}>
+                  {item}
+                </option>
+              ))}
+            </select>
+          </label>
+          <label className="game-publish-field">
+            标签
+            <input
+              value={tagsInput}
+              placeholder="用逗号分隔，最多 5 个"
+              disabled={isResumingDraft}
+              onChange={(e) => setTagsInput(e.target.value)}
+            />
+          </label>
+          <label className="game-publish-field">
+            画面方向
+            <select
+              value={orientation}
+              disabled={isResumingDraft}
+              onChange={(e) =>
+                setOrientation(e.target.value as GameDistributionOrientation)
+              }
+            >
+              {ORIENTATIONS.map((item) => (
+                <option key={item.value} value={item.value}>
+                  {item.label}
+                </option>
+              ))}
+            </select>
+          </label>
+        </div>
+        <fieldset className="game-publish-fieldset">
+          <legend>支持设备</legend>
+          {(
+            [
+              ['desktop', '桌面端'],
+              ['mobile', '移动端'],
+              ['touch', '触控'],
+            ] as const
+          ).map(([key, label]) => (
+            <label key={key} className="game-publish-checkbox">
+              <input
+                type="checkbox"
+                checked={deviceSupport[key]}
+                disabled={isResumingDraft}
+                onChange={(e) =>
+                  setDeviceSupport((current) => ({
+                    ...current,
+                    [key]: e.target.checked,
+                  }))
+                }
+              />
+              {label}
+            </label>
+          ))}
+        </fieldset>
+        <fieldset className="game-publish-fieldset game-publish-media">
+          <legend>封面与截图</legend>
+          <div className="game-publish-media__cover">
+            <div className="game-publish-media__preview">
+              {coverAsset?.src ? (
+                <img src={coverAsset.src} alt="游戏封面预览" />
+              ) : (
+                <span className="game-publish-media__placeholder">
+                  {coverAsset ? '封面预览加载中' : '还没有封面'}
+                </span>
+              )}
+            </div>
+            <div className="game-publish-media__copy">
+              <label className="game-publish-field">
+                游戏封面（必需）
+                {/*
+                  原生 file 控件在清空 value 后会显示“未选择任何文件”，与下方的“已选择”提示互相
+                  矛盾；上传后必须清空 value 才能重选同一张图，所以这里改用自定义触发按钮。
+                */}
+                <span className="game-publish-media__picker">
+                  <input
+                    ref={coverInputRef}
+                    type="file"
+                    accept={GAME_PUBLISH_IMAGE_ACCEPT}
+                    disabled={
+                      isResumingDraft || isSubmitting || isUploadingAsset
+                    }
+                    onChange={(event) => {
+                      void handleCoverSelected(event.target.files?.[0] ?? null);
+                    }}
+                  />
+                  <span className="game-publish-media__pick">
+                    {coverAsset ? '更换封面图片' : '选择封面图片'}
+                  </span>
+                </span>
+                <span className="game-publish-hint">
+                  {coverAsset?.assetObjectId
+                    ? `已选择「${coverAsset.name}」；重新选择即可替换本次发布的封面。`
+                    : coverAsset
+                      ? '本次发布需要重新选择一次封面图片，才能沿用这张线上封面。'
+                      : '封面会作为广场卡片与详情页首图，建议 16:9 的 JPG/PNG/WebP，最大 6MB。'}
+                </span>
+              </label>
+              {coverAsset ? (
+                <button
+                  type="button"
+                  className="game-publish-media__remove"
+                  disabled={isResumingDraft || isSubmitting || isUploadingAsset}
+                  onClick={() => setCoverAsset(null)}
+                >
+                  移除封面
+                </button>
+              ) : null}
+            </div>
+          </div>
+          <div className="game-publish-media__screenshots">
+            <label className="game-publish-field">
+              {`游戏截图（可选，最多 ${MAX_GAME_SCREENSHOTS} 张）`}
+              <span className="game-publish-media__picker">
+                <input
+                  ref={screenshotInputRef}
+                  type="file"
+                  accept={GAME_PUBLISH_IMAGE_ACCEPT}
+                  multiple
+                  disabled={
+                    isResumingDraft ||
+                    isSubmitting ||
+                    isUploadingAsset ||
+                    screenshotAssets.length >= MAX_GAME_SCREENSHOTS
+                  }
+                  onChange={(event) => {
+                    void handleScreenshotsSelected(
+                      Array.from(event.target.files ?? []),
+                    );
+                  }}
+                />
+                <span className="game-publish-media__pick">
+                  {screenshotAssets.length >= MAX_GAME_SCREENSHOTS
+                    ? '截图已满 6 张'
+                    : '添加截图'}
+                </span>
+              </span>
+              <span className="game-publish-hint">
+                截图会按选择顺序展示在详情页；不需要可以留空。
+              </span>
+            </label>
+            {screenshotAssets.length > 0 ? (
+              <ul className="game-publish-media__strip">
+                {screenshotAssets.map((asset, index) => (
+                  <li
+                    key={`${asset.assetObjectId || asset.objectKey}-${index}`}
+                    className="game-publish-media__shot"
+                  >
+                    {asset.src ? (
+                      <img src={asset.src} alt={`截图 ${index + 1} 预览`} />
+                    ) : (
+                      <span className="game-publish-media__placeholder">
+                        {`截图 ${index + 1}`}
+                      </span>
+                    )}
+                    <button
+                      type="button"
+                      className="game-publish-media__remove"
+                      disabled={
+                        isResumingDraft || isSubmitting || isUploadingAsset
+                      }
+                      onClick={() => removeScreenshotAsset(index)}
+                    >
+                      {`移除截图 ${index + 1}`}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+          </div>
+          {isUploadingAsset ? (
+            <span className="game-publish-hint">正在上传图片，请稍候…</span>
+          ) : null}
+        </fieldset>
+        <label className="game-publish-field">
+          {resumeNeedsPackage ? '重新选择发行包 ZIP' : '发行包 ZIP'}
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept=".zip,application/zip"
+            onChange={(e) => setPackageFile(e.target.files?.[0] ?? null)}
+          />
+          <span className="game-publish-hint">
+            {resumeNeedsPackage
+              ? '选择与上次相同内容会续用同一个版本，不需要重新创建游戏'
+              : '包内根目录需要包含 index.html，所有素材都要在包内'}
+          </span>
+        </label>
+        <div className="game-publish-actions">
+          <PlatformActionButton
+            type="submit"
+            size="md"
+            shape="pill"
+            disabled={
+              !canPublish ||
+              isSubmitting ||
+              isUploadingAsset ||
+              (Boolean(updateGameId) && !updateContext)
+            }
+          >
+            <Upload aria-hidden="true" />{' '}
+            {isSubmitting
+              ? '正在提交…'
+              : isResumingDraft && !updateGameId
+                ? resumeNeedsPackage
+                  ? '继续上传并送审'
+                  : '提交审核'
+                : updateGameId
+                  ? '提交新版本审核'
+                  : '提交审核'}
+          </PlatformActionButton>
+        </div>
+      </form>
+    </div>
+  );
+}
+
+export default GamePublishPage;
diff --git a/src/components/game-distribution/MyGamesPage.test.tsx b/src/components/game-distribution/MyGamesPage.test.tsx
new file mode 100644
index 000000000..3856613ff
--- /dev/null
+++ b/src/components/game-distribution/MyGamesPage.test.tsx
@@ -0,0 +1,252 @@
+/* @vitest-environment jsdom */
+
+import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent } from '@testing-library/react';
+import type { ContextType } from 'react';
+import { beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  cancelGameVersion,
+  type GameDistributionMyGame,
+  listMyGames,
+  unpublishGame,
+} from '../../services/gameDistributionClient';
+import { AuthUiContext } from '../auth/AuthUiContext';
+import { MyGamesPage } from './MyGamesPage';
+
+vi.mock('../../services/gameDistributionClient', () => ({
+  cancelGameVersion: vi.fn(),
+  listMyGames: vi.fn(),
+  unpublishGame: vi.fn(),
+}));
+
+type AuthValue = NonNullable<ContextType<typeof AuthUiContext>>;
+
+function createAuthValue(overrides: Partial<AuthValue> = {}): AuthValue {
+  return {
+    user: {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试作者',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    },
+    canAccessProtectedData: true,
+    openLoginModal: vi.fn(),
+    requireAuth: vi.fn((action: () => void) => action()),
+    openSettingsModal: vi.fn(),
+    openAccountModal: vi.fn(),
+    setCurrentUser: vi.fn(),
+    logout: vi.fn(),
+    musicVolume: 0.5,
+    setMusicVolume: vi.fn(),
+    platformTheme: 'light',
+    setPlatformTheme: vi.fn(),
+    isHydratingSettings: false,
+    isPersistingSettings: false,
+    settingsError: null,
+    ...overrides,
+  };
+}
+
+function createGame(
+  overrides: Partial<GameDistributionMyGame> = {},
+): GameDistributionMyGame {
+  return {
+    id: 'game-1',
+    title: '我的游戏',
+    summary: '作者自有游戏',
+    description: '',
+    category: '益智',
+    tags: [],
+    coverColor: '#49316d',
+    icon: '✦',
+    author: { id: 'user-1', name: '测试作者' },
+    deviceSupport: { desktop: true, mobile: false, touch: false },
+    status: 'unpublished',
+    publicationRevision: 2,
+    currentVersion: null,
+    playCount: 3,
+    createdAt: '2026-09-20T08:00:00Z',
+    ...overrides,
+  } as GameDistributionMyGame;
+}
+
+function renderPage(
+  authValue: AuthValue | null,
+  overrides: { onPublishVersion?: (gameId: string) => void } = {},
+) {
+  return render(
+    <AuthUiContext.Provider value={authValue}>
+      <MyGamesPage
+        onBack={vi.fn()}
+        onOpenDetail={vi.fn()}
+        onPublishVersion={overrides.onPublishVersion}
+      />
+    </AuthUiContext.Provider>,
+  );
+}
+
+beforeEach(() => {
+  vi.mocked(cancelGameVersion).mockReset();
+  vi.mocked(listMyGames).mockReset();
+  vi.mocked(unpublishGame).mockReset();
+  vi.mocked(listMyGames).mockResolvedValue([]);
+});
+
+test('未登录时提示登录且不请求作者接口', () => {
+  renderPage(null);
+  expect(
+    screen.getByText('登录后可以查看已发布的游戏与审核状态。'),
+  ).toBeTruthy();
+  expect(listMyGames).not.toHaveBeenCalled();
+});
+
+test('展示审核中状态与驳回理由', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    createGame({
+      status: 'unpublished',
+      latestVersion: {
+        versionId: 'version-1',
+        gameId: 'game-1',
+        versionNumber: 3,
+        packageSha256: 'a'.repeat(64),
+        packageBytes: 1024,
+        status: 'rejected',
+        publicationRevision: 2,
+        reviewReason: '封面需要替换',
+        createdAt: '2026-09-20T08:00:00Z',
+        updatedAt: '2026-09-20T09:00:00Z',
+      },
+      versions: [],
+    }),
+  ]);
+
+  renderPage(createAuthValue());
+
+  expect(await screen.findByText('我的游戏')).toBeTruthy();
+  expect(screen.getByText(/版本 v3 · 已拒绝/)).toBeTruthy();
+  expect(screen.getByText('驳回理由：封面需要替换')).toBeTruthy();
+});
+
+test('下架已公开游戏会带上当前 publicationRevision', async () => {
+  const game = createGame({
+    status: 'published',
+    publicationRevision: 7,
+    latestVersion: null,
+    versions: [],
+  });
+  vi.mocked(listMyGames).mockResolvedValue([game]);
+  vi.mocked(unpublishGame).mockResolvedValue({
+    game: { id: 'game-1', status: 'unpublished' },
+  });
+
+  renderPage(createAuthValue());
+
+  fireEvent.click(await screen.findByRole('button', { name: '下架' }));
+
+  await waitFor(() => expect(unpublishGame).toHaveBeenCalledTimes(1));
+  const [gameId, revision, idempotencyKey] =
+    vi.mocked(unpublishGame).mock.calls[0] ?? [];
+  expect(gameId).toBe('game-1');
+  expect(revision).toBe(7);
+  expect(String(idempotencyKey)).toContain('game-1');
+  await waitFor(() => expect(listMyGames).toHaveBeenCalledTimes(2));
+});
+
+test('未公开游戏不提供下架动作', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    createGame({ status: 'unpublished' }),
+  ]);
+  renderPage(createAuthValue());
+  await screen.findByText('我的游戏');
+  expect(screen.queryByRole('button', { name: '下架' })).toBeNull();
+});
+
+test('审核中的版本二次确认后撤回并带上 publicationRevision', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    createGame({
+      status: 'unpublished',
+      publicationRevision: 5,
+      latestVersion: {
+        versionId: 'version-9',
+        gameId: 'game-1',
+        versionNumber: 2,
+        packageSha256: 'b'.repeat(64),
+        packageBytes: 2048,
+        status: 'pending_review',
+        publicationRevision: 5,
+        reviewReason: null,
+        createdAt: '2026-09-20T08:00:00Z',
+        updatedAt: '2026-09-20T09:00:00Z',
+      },
+      versions: [],
+    }),
+  ]);
+  vi.mocked(cancelGameVersion).mockResolvedValue({
+    game: {} as never,
+    version: {} as never,
+    replayed: false,
+  });
+
+  renderPage(createAuthValue());
+
+  fireEvent.click(await screen.findByRole('button', { name: '撤回审核' }));
+  // 首次点击只进入确认态，不发送请求。
+  expect(cancelGameVersion).not.toHaveBeenCalled();
+  expect(screen.getByRole('button', { name: '取消' })).toBeTruthy();
+
+  fireEvent.click(screen.getByRole('button', { name: '确认撤回' }));
+
+  await waitFor(() => expect(cancelGameVersion).toHaveBeenCalledTimes(1));
+  const [versionId, revision, idempotencyKey] =
+    vi.mocked(cancelGameVersion).mock.calls[0] ?? [];
+  expect(versionId).toBe('version-9');
+  expect(revision).toBe(5);
+  expect(String(idempotencyKey)).toContain('version-9');
+  await waitFor(() => expect(listMyGames).toHaveBeenCalledTimes(2));
+});
+
+test('已公开版本只能下架，不显示撤回审核', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    createGame({
+      status: 'published',
+      publicationRevision: 4,
+      latestVersion: {
+        versionId: 'version-3',
+        gameId: 'game-1',
+        versionNumber: 3,
+        packageSha256: 'c'.repeat(64),
+        packageBytes: 4096,
+        status: 'published',
+        publicationRevision: 4,
+        reviewReason: null,
+        createdAt: '2026-09-20T08:00:00Z',
+        updatedAt: '2026-09-20T09:00:00Z',
+      },
+      versions: [],
+    }),
+  ]);
+
+  renderPage(createAuthValue());
+
+  await screen.findByText('我的游戏');
+  expect(screen.queryByRole('button', { name: '撤回审核' })).toBeNull();
+  expect(screen.getByRole('button', { name: '下架' })).toBeTruthy();
+});
+
+test('作者中心提供发布新版本入口并回传同一个 gameId', async () => {
+  vi.mocked(listMyGames).mockResolvedValue([
+    createGame({ id: 'game-42', status: 'published', publicationRevision: 3 }),
+  ]);
+  const onPublishVersion = vi.fn();
+
+  renderPage(createAuthValue(), { onPublishVersion });
+
+  fireEvent.click(await screen.findByRole('button', { name: '发布新版本' }));
+
+  expect(onPublishVersion).toHaveBeenCalledWith('game-42');
+});
diff --git a/src/components/game-distribution/MyGamesPage.tsx b/src/components/game-distribution/MyGamesPage.tsx
new file mode 100644
index 000000000..2cfd1ed06
--- /dev/null
+++ b/src/components/game-distribution/MyGamesPage.tsx
@@ -0,0 +1,346 @@
+import './gameDistribution.css';
+
+import { ArrowLeft, RefreshCcw } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+
+import {
+  cancelGameVersion,
+  type GameDistributionMyGame,
+  type GameDistributionVersionStatusEntry,
+  listMyGames,
+  unpublishGame,
+} from '../../services/gameDistributionClient';
+import { useAuthUi } from '../auth/AuthUiContext';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { GameCover } from './GameGalleryPage';
+
+const STATUS_LABEL: Record<string, string> = {
+  unpublished: '未公开',
+  published: '已公开',
+  suspended: '已被封禁',
+};
+
+const VERSION_STATUS_LABEL: Record<string, string> = {
+  awaiting_upload: '待上传',
+  uploaded: '已上传',
+  validating: '校验中',
+  pending_review: '审核中',
+  published: '已发布',
+  upload_failed: '上传失败',
+  validation_failed: '校验失败',
+  rejected: '已拒绝',
+  cancelled: '已撤回',
+  revoked: '已撤回',
+};
+
+type MyGamesPageProps = {
+  onBack: () => void;
+  onOpenDetail: (gameId: string) => void;
+  /** 进入发布页的“新版本”模式；回调缺失时不显示该动作。 */
+  onPublishVersion?: (gameId: string) => void;
+};
+
+let unpublishKeySeed = 0;
+function createUnpublishKey(gameId: string) {
+  unpublishKeySeed += 1;
+  return `game-unpublish-${gameId}-${Date.now()}-${unpublishKeySeed}`;
+}
+
+/** 与服务端 `can_cancel` 保持一致：已公开版本只能下架，不能撤回。 */
+const CANCELLABLE_VERSION_STATUS = new Set([
+  'awaiting_upload',
+  'uploaded',
+  'validating',
+  'pending_review',
+  'upload_failed',
+  'validation_failed',
+]);
+
+let cancelKeySeed = 0;
+function createCancelKey(versionId: string) {
+  cancelKeySeed += 1;
+  return `game-cancel-${versionId}-${Date.now()}-${cancelKeySeed}`;
+}
+
+function resolveVersionStatus(game: GameDistributionMyGame) {
+  const latest = game.latestVersion;
+  if (!latest) return null;
+  return {
+    label: VERSION_STATUS_LABEL[latest.status] ?? latest.status,
+    versionNumber: latest.versionNumber,
+    reviewReason: latest.reviewReason?.trim() || '',
+  };
+}
+
+export function MyGamesPage({
+  onBack,
+  onOpenDetail,
+  onPublishVersion,
+}: MyGamesPageProps) {
+  const authUi = useAuthUi();
+  const [games, setGames] = useState<GameDistributionMyGame[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [busyGameId, setBusyGameId] = useState('');
+  const [cancellingVersionId, setCancellingVersionId] = useState('');
+  const [confirmingVersionId, setConfirmingVersionId] = useState('');
+  const [notice, setNotice] = useState('');
+  const [error, setError] = useState('');
+  const canLoad = Boolean(authUi?.user && authUi.canAccessProtectedData);
+
+  const loadGames = useCallback(async () => {
+    if (!canLoad) {
+      setGames([]);
+      return;
+    }
+    setIsLoading(true);
+    setError('');
+    try {
+      setGames(await listMyGames());
+    } catch (loadError: unknown) {
+      setError(
+        loadError instanceof Error ? loadError.message : '读取我的游戏失败',
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [canLoad]);
+
+  useEffect(() => {
+    void loadGames();
+  }, [loadGames]);
+
+  async function handleCancelVersion(
+    game: GameDistributionMyGame,
+    version: GameDistributionVersionStatusEntry,
+  ) {
+    setCancellingVersionId(version.versionId);
+    setConfirmingVersionId('');
+    setError('');
+    setNotice('');
+    try {
+      await cancelGameVersion(
+        version.versionId,
+        version.publicationRevision,
+        createCancelKey(version.versionId),
+      );
+      setNotice(`版本 v${version.versionNumber} 已撤回，可以重新上传发行包。`);
+      await loadGames();
+    } catch (cancelError: unknown) {
+      setError(
+        cancelError instanceof Error ? cancelError.message : '撤回版本失败',
+      );
+    } finally {
+      setCancellingVersionId('');
+    }
+  }
+
+  async function handleUnpublish(game: GameDistributionMyGame) {
+    setBusyGameId(game.id);
+    setError('');
+    try {
+      await unpublishGame(
+        game.id,
+        game.publicationRevision,
+        createUnpublishKey(game.id),
+      );
+      await loadGames();
+    } catch (unpublishError: unknown) {
+      setError(
+        unpublishError instanceof Error
+          ? unpublishError.message
+          : '下架游戏失败',
+      );
+    } finally {
+      setBusyGameId('');
+    }
+  }
+
+  return (
+    <div className="game-page">
+      <button type="button" className="game-back-button" onClick={onBack}>
+        <ArrowLeft /> 返回游戏广场
+      </button>
+      <div className="game-toolbar">
+        <div className="game-toolbar__title">
+          <span className="game-eyebrow">作者中心</span>
+          <h2>我的游戏</h2>
+        </div>
+        {canLoad ? (
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            shape="pill"
+            onClick={() => void loadGames()}
+            disabled={isLoading}
+          >
+            <RefreshCcw aria-hidden="true" /> 刷新
+          </PlatformActionButton>
+        ) : null}
+      </div>
+
+      {error ? (
+        <PlatformStatusMessage tone="error" surface="platform">
+          {error}
+        </PlatformStatusMessage>
+      ) : null}
+
+      {notice ? (
+        <PlatformStatusMessage tone="success" surface="platform">
+          {notice}
+        </PlatformStatusMessage>
+      ) : null}
+
+      {!canLoad ? (
+        <PlatformEmptyState surface="subpanel" size="panel">
+          <span>登录后可以查看已发布的游戏与审核状态。</span>
+          <PlatformActionButton
+            size="sm"
+            shape="pill"
+            onClick={() => authUi?.openLoginModal(() => void loadGames())}
+          >
+            登录
+          </PlatformActionButton>
+        </PlatformEmptyState>
+      ) : null}
+
+      {canLoad && isLoading ? (
+        <div className="game-loading-panel">正在加载我的游戏…</div>
+      ) : null}
+
+      {canLoad && !isLoading && games.length === 0 && !error ? (
+        <PlatformEmptyState surface="subpanel" size="panel">
+          <span>还没有在平台上发布过游戏。</span>
+        </PlatformEmptyState>
+      ) : null}
+
+      {canLoad && games.length > 0 ? (
+        <div className="my-game-list">
+          {games.map((game) => {
+            const version = resolveVersionStatus(game);
+            const latestVersion = game.latestVersion;
+            return (
+              <article key={game.id} className="my-game-card">
+                <GameCover game={game} compact />
+                <div className="my-game-card__body">
+                  <div className="my-game-card__heading">
+                    <button
+                      type="button"
+                      className="my-game-card__title"
+                      onClick={() => onOpenDetail(game.id)}
+                    >
+                      {game.title}
+                    </button>
+                    <span
+                      className={`my-game-status my-game-status--${game.status}`}
+                    >
+                      {STATUS_LABEL[game.status] ?? game.status}
+                    </span>
+                  </div>
+                  <p className="my-game-card__summary">{game.summary}</p>
+                  <div className="my-game-card__meta">
+                    <span>{game.category}</span>
+                    <span>·</span>
+                    <span>{game.playCount.toLocaleString()} 次游玩</span>
+                    {version ? (
+                      <>
+                        <span>·</span>
+                        <span>
+                          版本 v{version.versionNumber} · {version.label}
+                        </span>
+                      </>
+                    ) : null}
+                  </div>
+                  {version?.reviewReason ? (
+                    <p className="my-game-card__reason">
+                      驳回理由：{version.reviewReason}
+                    </p>
+                  ) : null}
+                  <div className="my-game-card__actions">
+                    <PlatformActionButton
+                      tone="secondary"
+                      size="sm"
+                      shape="pill"
+                      onClick={() => onOpenDetail(game.id)}
+                    >
+                      查看详情
+                    </PlatformActionButton>
+                    {onPublishVersion ? (
+                      <PlatformActionButton
+                        tone="primary"
+                        size="sm"
+                        shape="pill"
+                        onClick={() => onPublishVersion(game.id)}
+                      >
+                        发布新版本
+                      </PlatformActionButton>
+                    ) : null}
+                    {game.status === 'published' ? (
+                      <PlatformActionButton
+                        tone="secondary"
+                        size="sm"
+                        shape="pill"
+                        disabled={busyGameId === game.id}
+                        onClick={() => void handleUnpublish(game)}
+                      >
+                        下架
+                      </PlatformActionButton>
+                    ) : null}
+                    {latestVersion &&
+                    CANCELLABLE_VERSION_STATUS.has(latestVersion.status) ? (
+                      confirmingVersionId === latestVersion.versionId ? (
+                        <>
+                          <PlatformActionButton
+                            tone="danger"
+                            size="sm"
+                            shape="pill"
+                            disabled={
+                              cancellingVersionId === latestVersion.versionId
+                            }
+                            onClick={() =>
+                              void handleCancelVersion(game, latestVersion)
+                            }
+                          >
+                            确认撤回
+                          </PlatformActionButton>
+                          <PlatformActionButton
+                            tone="secondary"
+                            size="sm"
+                            shape="pill"
+                            disabled={
+                              cancellingVersionId === latestVersion.versionId
+                            }
+                            onClick={() => setConfirmingVersionId('')}
+                          >
+                            取消
+                          </PlatformActionButton>
+                        </>
+                      ) : (
+                        <PlatformActionButton
+                          tone="secondary"
+                          size="sm"
+                          shape="pill"
+                          disabled={
+                            cancellingVersionId === latestVersion.versionId
+                          }
+                          onClick={() =>
+                            setConfirmingVersionId(latestVersion.versionId)
+                          }
+                        >
+                          撤回审核
+                        </PlatformActionButton>
+                      )
+                    ) : null}
+                  </div>
+                </div>
+              </article>
+            );
+          })}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export default MyGamesPage;
diff --git a/src/components/game-distribution/gameDistribution.css b/src/components/game-distribution/gameDistribution.css
new file mode 100644
index 000000000..c24e193f5
--- /dev/null
+++ b/src/components/game-distribution/gameDistribution.css
@@ -0,0 +1,1059 @@
+.game-page,
+.game-detail-page,
+.game-play-page {
+  width: 100%;
+  min-height: 100%;
+  box-sizing: border-box;
+  padding: clamp(1rem, 2.4vw, 2.75rem);
+  color: var(--platform-text-strong);
+}
+
+.game-page {
+  max-width: 92rem;
+  margin: 0 auto;
+}
+
+.game-hero {
+  position: relative;
+  display: flex;
+  min-height: 17rem;
+  align-items: center;
+  justify-content: space-between;
+  overflow: hidden;
+  border: 1px solid rgba(199, 101, 61, 0.25);
+  border-radius: 2rem;
+  padding: clamp(1.5rem, 4vw, 3.5rem);
+  background: radial-gradient(
+      circle at 75% 15%,
+      rgba(241, 159, 95, 0.28),
+      transparent 30%
+    ),
+    linear-gradient(120deg, rgba(91, 49, 42, 0.98), rgba(43, 29, 34, 0.96));
+  box-shadow: 0 1.25rem 3rem rgba(72, 35, 26, 0.18);
+  color: #fff8f0;
+}
+
+.game-hero__copy {
+  position: relative;
+  z-index: 1;
+  max-width: 36rem;
+}
+.game-eyebrow {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.38rem;
+  color: var(--platform-accent-strong);
+  font-size: 0.72rem;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+.game-hero .game-eyebrow {
+  color: #ffd3b0;
+}
+.game-eyebrow svg {
+  width: 0.9rem;
+  height: 0.9rem;
+}
+.game-hero h1 {
+  margin: 0.8rem 0 0;
+  font-size: clamp(2rem, 4.1vw, 3.4rem);
+  line-height: 1.08;
+  letter-spacing: -0.05em;
+}
+.game-hero h1 em {
+  color: #ffb77c;
+  font-style: normal;
+}
+.game-hero p {
+  max-width: 31rem;
+  margin: 1rem 0 0;
+  color: rgba(255, 241, 227, 0.74);
+  font-size: 0.95rem;
+  line-height: 1.75;
+}
+.game-hero__actions {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-top: 1.4rem;
+}
+.game-hero__hint {
+  color: rgba(255, 241, 227, 0.66);
+  font-size: 0.75rem;
+}
+.game-hero__orb {
+  display: grid;
+  width: clamp(9rem, 19vw, 16rem);
+  aspect-ratio: 1;
+  place-items: center;
+  margin-right: 4%;
+  border: 1px solid rgba(255, 208, 171, 0.3);
+  border-radius: 50%;
+  background: radial-gradient(
+    circle at 40% 35%,
+    #ef9b68,
+    #7e3b44 46%,
+    rgba(37, 25, 35, 0.25) 70%
+  );
+  box-shadow:
+    0 0 0 1.5rem rgba(245, 141, 90, 0.05),
+    0 0 5rem rgba(245, 141, 90, 0.26);
+  color: #fff4df;
+  font-size: clamp(3rem, 6vw, 5rem);
+}
+.game-hero__orb::after {
+  position: absolute;
+  width: 8rem;
+  height: 1px;
+  content: '';
+  background: rgba(255, 203, 161, 0.35);
+  transform: rotate(-24deg) translate(6rem, -3rem);
+}
+.game-toolbar {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: 1.25rem;
+  margin: 2.3rem 0 1.15rem;
+}
+.game-toolbar h2 {
+  margin: 0.2rem 0 0;
+  font-size: clamp(1.55rem, 3vw, 2.15rem);
+  letter-spacing: -0.04em;
+}
+.game-search {
+  display: flex;
+  min-width: min(100%, 19rem);
+  align-items: center;
+  gap: 0.55rem;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 999px;
+  padding: 0.68rem 0.95rem;
+  background: var(--platform-panel-fill);
+  color: var(--platform-text-soft);
+}
+.game-search svg {
+  width: 1rem;
+  flex: none;
+}
+.game-search input {
+  width: 100%;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  color: var(--platform-text-strong);
+  font: inherit;
+  font-size: 0.82rem;
+}
+.game-category-tabs {
+  display: flex;
+  gap: 0.45rem;
+  overflow-x: auto;
+  padding: 0.15rem 0 1.45rem;
+  scrollbar-width: none;
+}
+.game-category-tab {
+  flex: none;
+  min-height: 2.75rem;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  padding: 0.52rem 0.95rem;
+  background: transparent;
+  color: var(--platform-text-soft);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.8rem;
+  font-weight: 700;
+  transition: 160ms ease;
+}
+.game-category-tab:hover {
+  color: var(--platform-text-strong);
+  background: var(--platform-surface-fill);
+}
+.game-category-tab--active {
+  border-color: rgba(199, 101, 61, 0.25);
+  background: rgba(199, 101, 61, 0.12);
+  color: var(--platform-accent-strong);
+}
+.game-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 1.1rem;
+}
+.game-card {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 1.45rem;
+  padding: 0;
+  background: var(--platform-panel-fill);
+  color: inherit;
+  cursor: pointer;
+  text-align: left;
+  box-shadow: var(--platform-panel-shadow);
+  transition: 180ms ease;
+}
+.game-card:hover {
+  border-color: rgba(199, 101, 61, 0.38);
+  box-shadow: 0 1rem 2.4rem rgba(104, 54, 36, 0.14);
+  transform: translateY(-3px);
+}
+.game-card__body {
+  display: block;
+  padding: 0.95rem 1rem 1.1rem;
+}
+.game-card__title-row {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+.game-card__title-row strong {
+  overflow: hidden;
+  font-size: 1rem;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.game-card__play-count {
+  flex: none;
+  color: var(--platform-text-soft);
+  font-size: 0.66rem;
+}
+.game-card__summary {
+  display: block;
+  overflow: hidden;
+  margin-top: 0.42rem;
+  color: var(--platform-text-base);
+  font-size: 0.78rem;
+  line-height: 1.55;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.game-card__meta {
+  display: flex;
+  gap: 0.38rem;
+  margin-top: 0.85rem;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+}
+.game-cover {
+  position: relative;
+  display: flex;
+  min-height: 12rem;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  isolation: isolate;
+}
+.game-cover--compact {
+  min-height: 7rem;
+}
+.game-cover__grid {
+  position: absolute;
+  inset: 0;
+  opacity: 0.22;
+  background-image: linear-gradient(
+      rgba(255, 255, 255, 0.2) 1px,
+      transparent 1px
+    ),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.2) 1px, transparent 1px);
+  background-size: 2rem 2rem;
+  transform: perspective(12rem) rotateX(58deg) scale(1.7) translateY(25%);
+}
+.game-cover__glow {
+  position: absolute;
+  width: 70%;
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background: radial-gradient(
+    circle,
+    rgba(255, 236, 204, 0.5),
+    transparent 66%
+  );
+  filter: blur(0.6rem);
+}
+.game-cover__icon {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  width: 5.4rem;
+  aspect-ratio: 1;
+  place-items: center;
+  border: 1px solid rgba(255, 255, 255, 0.4);
+  border-radius: 1.5rem;
+  background: rgba(255, 255, 255, 0.13);
+  box-shadow: 0 1rem 2rem rgba(0, 0, 0, 0.2);
+  color: #fff5dc;
+  font-size: 3rem;
+  backdrop-filter: blur(8px);
+}
+.game-loading-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 1.1rem;
+}
+.game-loading-grid span {
+  height: 17rem;
+  border-radius: 1.45rem;
+  background: linear-gradient(
+    100deg,
+    var(--platform-panel-fill),
+    var(--platform-surface-fill),
+    var(--platform-panel-fill)
+  );
+  background-size: 220% 100%;
+  animation: game-shimmer 1.2s ease-in-out infinite;
+}
+@keyframes game-shimmer {
+  from {
+    background-position: 100% 0;
+  }
+  to {
+    background-position: -100% 0;
+  }
+}
+
+.game-detail-page {
+  max-width: 70rem;
+  margin: 0 auto;
+}
+.game-back-button {
+  display: inline-flex;
+  min-height: 2.75rem;
+  align-items: center;
+  gap: 0.4rem;
+  border: 0;
+  padding: 0.25rem 0;
+  background: transparent;
+  color: var(--platform-text-soft);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.82rem;
+  font-weight: 700;
+}
+.game-back-button svg {
+  width: 1rem;
+}
+.game-detail-hero {
+  display: grid;
+  grid-template-columns: minmax(13rem, 21rem) minmax(0, 1fr);
+  align-items: center;
+  gap: clamp(1.4rem, 4vw, 3.5rem);
+  margin-top: 1.5rem;
+}
+.game-detail-hero .game-cover {
+  border-radius: 1.7rem;
+  box-shadow: 0 1.25rem 2.5rem rgba(70, 42, 34, 0.18);
+}
+.game-detail-hero h1 {
+  margin: 0.65rem 0 0;
+  font-size: clamp(2rem, 4.8vw, 3.7rem);
+  letter-spacing: -0.055em;
+}
+.game-detail-hero__summary {
+  max-width: 32rem;
+  margin: 0.8rem 0 0;
+  color: var(--platform-text-base);
+  font-size: 1rem;
+  line-height: 1.75;
+}
+.game-detail-hero__author {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+  margin-top: 1.15rem;
+  color: var(--platform-text-soft);
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+.game-avatar {
+  display: grid;
+  width: 1.8rem;
+  height: 1.8rem;
+  place-items: center;
+  border-radius: 50%;
+  background: rgba(199, 101, 61, 0.18);
+  color: var(--platform-accent-strong);
+  font-weight: 900;
+}
+.game-detail-hero__actions {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-top: 1.4rem;
+}
+.game-detail-hero__play-count {
+  color: var(--platform-text-soft);
+  font-size: 0.75rem;
+}
+.game-device-warning {
+  color: var(--platform-accent-strong);
+  font-size: 0.75rem;
+  font-weight: 800;
+}
+.game-detail-body {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 17rem;
+  gap: 3rem;
+  margin-top: 3rem;
+  border-top: 1px solid var(--platform-surface-border);
+  padding-top: 2rem;
+}
+.game-detail-main h2 {
+  margin: 0;
+  font-size: 1.25rem;
+}
+.game-detail-main p {
+  max-width: 45rem;
+  margin: 0.75rem 0 0;
+  color: var(--platform-text-base);
+  line-height: 1.9;
+}
+.game-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.45rem;
+  margin-top: 1.3rem;
+}
+.game-tag-list span {
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 999px;
+  padding: 0.35rem 0.65rem;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+  font-weight: 700;
+}
+.game-detail-side {
+  display: grid;
+  gap: 0.7rem;
+  align-content: start;
+}
+.game-info-card {
+  display: grid;
+  gap: 0.3rem;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 1rem;
+  padding: 0.8rem 0.9rem;
+  background: var(--platform-panel-fill);
+}
+.game-info-card strong {
+  font-size: 0.72rem;
+}
+.game-info-card span {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.28rem;
+  color: var(--platform-text-soft);
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+.game-info-card svg {
+  width: 0.85rem;
+}
+.game-detail-footnote {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-top: 2.2rem;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+}
+.game-detail-footnote svg {
+  width: 0.9rem;
+}
+.game-loading-panel {
+  display: grid;
+  min-height: 18rem;
+  place-items: center;
+  color: var(--platform-text-soft);
+  font-weight: 700;
+}
+.game-status-message {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-top: 1.2rem;
+}
+.game-status-message button {
+  border: 0;
+  border-radius: 999px;
+  min-height: 2.75rem;
+  padding: 0.38rem 0.7rem;
+  background: rgba(199, 101, 61, 0.14);
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 800;
+}
+
+.game-play-page {
+  display: flex;
+  flex-direction: column;
+  gap: 0.9rem;
+  min-height: 100%;
+  padding: clamp(0.7rem, 1.8vw, 1.5rem);
+}
+.game-play-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+.game-play-toolbar__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+}
+.game-play-device-hint {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+}
+.game-play-device-hint svg {
+  width: 0.85rem;
+}
+.game-icon-button {
+  display: grid;
+  width: 2.1rem;
+  height: 2.1rem;
+  min-width: 2.75rem;
+  min-height: 2.75rem;
+  place-items: center;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 50%;
+  background: var(--platform-panel-fill);
+  color: var(--platform-text-base);
+  cursor: pointer;
+}
+.game-icon-button svg {
+  width: 0.9rem;
+}
+.game-player-shell {
+  position: relative;
+  flex: 1;
+  min-height: min(72vh, 48rem);
+  overflow: hidden;
+  border: 1px solid rgba(199, 101, 61, 0.24);
+  border-radius: 1.5rem;
+  background: #17131b;
+  box-shadow: 0 1.4rem 3rem rgba(34, 21, 20, 0.2);
+}
+.game-player-launch {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  grid-template-columns: minmax(8rem, 15rem) minmax(0, 1fr);
+  align-items: center;
+  gap: clamp(1.1rem, 4vw, 2.8rem);
+  padding: clamp(1rem, 4vw, 2.5rem);
+  background: linear-gradient(135deg, #1e1820, #302329);
+  color: #fff8f0;
+}
+.game-player-launch .game-cover {
+  border-radius: 1.1rem;
+}
+.game-player-launch__copy {
+  min-width: 0;
+}
+.game-player-launch__copy h1 {
+  margin: 0;
+  overflow: hidden;
+  font-size: clamp(1.4rem, 3vw, 2.2rem);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.game-player-launch__copy p {
+  margin: 0.6rem 0 1.1rem;
+  color: rgba(255, 241, 227, 0.7);
+  font-size: 0.82rem;
+  line-height: 1.65;
+}
+.game-player-launch__copy .game-device-warning {
+  margin-top: -0.4rem;
+}
+.game-player-frame {
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: min(72vh, 48rem);
+  border: 0;
+  opacity: 0;
+  transition: opacity 220ms ease;
+}
+.game-player-frame--ready {
+  opacity: 1;
+}
+.game-player-loading {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  color: rgba(255, 241, 227, 0.75);
+  font-size: 0.88rem;
+  font-weight: 700;
+}
+.game-play-safety-note {
+  margin: 0;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+  text-align: center;
+}
+
+@media (max-width: 820px) {
+  .game-hero {
+    min-height: 19rem;
+  }
+  .game-hero__orb {
+    position: absolute;
+    right: -2.5rem;
+    bottom: -3rem;
+    width: 11rem;
+    opacity: 0.62;
+  }
+  .game-hero__copy {
+    max-width: 80%;
+  }
+  .game-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .game-detail-hero {
+    grid-template-columns: 9rem minmax(0, 1fr);
+    gap: 1.15rem;
+  }
+  .game-detail-hero .game-cover {
+    min-height: 9rem;
+  }
+  .game-cover__icon {
+    width: 3.7rem;
+    border-radius: 1rem;
+    font-size: 2rem;
+  }
+  .game-detail-body {
+    grid-template-columns: 1fr;
+    gap: 1.5rem;
+  }
+  .game-detail-side {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 560px) {
+  .game-page,
+  .game-detail-page {
+    padding: 1rem;
+  }
+  .game-hero {
+    border-radius: 1.5rem;
+    padding: 1.35rem;
+  }
+  .game-hero h1 {
+    font-size: 2rem;
+  }
+  .game-hero p {
+    font-size: 0.82rem;
+  }
+  .game-hero__copy {
+    max-width: 100%;
+  }
+  .game-hero__orb {
+    opacity: 0.3;
+  }
+  .game-hero__hint {
+    display: none;
+  }
+  .game-toolbar {
+    display: block;
+    margin-top: 1.7rem;
+  }
+  .game-search {
+    margin-top: 0.9rem;
+  }
+  .game-grid {
+    grid-template-columns: 1fr;
+  }
+  .game-cover {
+    min-height: 10.5rem;
+  }
+  .game-detail-hero {
+    display: block;
+  }
+  .game-detail-hero .game-cover {
+    min-height: 13rem;
+    margin-top: 1.2rem;
+  }
+  .game-detail-hero h1 {
+    margin-top: 1.4rem;
+  }
+  .game-detail-side {
+    grid-template-columns: 1fr;
+  }
+  .game-play-page {
+    padding: 0.7rem;
+  }
+  .game-player-launch {
+    grid-template-columns: 1fr;
+    align-content: center;
+    gap: 1rem;
+    text-align: center;
+  }
+  .game-player-launch .game-cover {
+    width: min(12rem, 65vw);
+    min-height: 8rem;
+    margin: 0 auto;
+  }
+  .game-player-launch__copy p {
+    margin-bottom: 0.8rem;
+  }
+  .game-player-launch__copy .platform-button {
+    min-height: 2.75rem;
+  }
+  .game-play-toolbar__actions .game-play-device-hint {
+    display: none;
+  }
+  .game-player-shell,
+  .game-player-frame {
+    min-height: calc(100dvh - 8rem);
+  }
+}
+
+.my-game-list {
+  display: grid;
+  gap: 0.9rem;
+}
+.my-game-card {
+  display: flex;
+  gap: 1rem;
+  align-items: stretch;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 1.2rem;
+  padding: 0.85rem;
+  background: var(--platform-panel-fill);
+  box-shadow: var(--platform-panel-shadow);
+}
+.my-game-card .game-cover {
+  flex: none;
+  width: 8.5rem;
+  min-height: 6rem;
+  border-radius: 0.9rem;
+}
+.my-game-card__body {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+.my-game-card__heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+}
+.my-game-card__title {
+  border: 0;
+  padding: 0;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-size: 1rem;
+  font-weight: 800;
+  text-align: left;
+}
+.my-game-card__summary {
+  margin: 0;
+  overflow: hidden;
+  color: var(--platform-text-base);
+  font-size: 0.78rem;
+  line-height: 1.5;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.my-game-card__meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+}
+.my-game-card__reason {
+  margin: 0;
+  color: var(--platform-button-danger-text);
+  font-size: 0.72rem;
+}
+.my-game-card__actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: auto;
+  padding-top: 0.35rem;
+}
+.my-game-status {
+  flex: none;
+  border-radius: 999px;
+  padding: 0.25rem 0.6rem;
+  font-size: 0.68rem;
+  font-weight: 800;
+  background: var(--platform-surface-fill);
+  color: var(--platform-text-soft);
+}
+.my-game-status--published {
+  background: var(--platform-success-bg);
+  color: var(--platform-success-text);
+}
+.my-game-status--suspended {
+  background: var(--platform-button-danger-fill);
+  color: var(--platform-button-danger-text);
+}
+@media (max-width: 560px) {
+  .my-game-card {
+    flex-direction: column;
+  }
+  .my-game-card .game-cover {
+    width: 100%;
+  }
+}
+
+.game-publish-page {
+  max-width: 54rem;
+}
+.game-publish-form {
+  display: grid;
+  gap: 0.85rem;
+  margin-top: 0.4rem;
+}
+.game-publish-field {
+  display: grid;
+  gap: 0.3rem;
+  font-size: 0.76rem;
+  font-weight: 700;
+  color: var(--platform-text-base);
+}
+.game-publish-field input,
+.game-publish-field select,
+.game-publish-field textarea {
+  width: 100%;
+  box-sizing: border-box;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 0.7rem;
+  padding: 0.55rem 0.7rem;
+  background: var(--platform-panel-fill);
+  color: var(--platform-text-strong);
+  font: inherit;
+  font-weight: 500;
+}
+.game-publish-field textarea {
+  resize: vertical;
+}
+.game-publish-row {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.7rem;
+}
+.game-publish-fieldset {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.9rem;
+  margin: 0;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 0.7rem;
+  padding: 0.6rem 0.8rem;
+}
+.game-publish-fieldset legend {
+  padding: 0 0.3rem;
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+.game-publish-checkbox {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-size: 0.76rem;
+}
+.game-publish-hint {
+  color: var(--platform-text-soft);
+  font-size: 0.7rem;
+  font-weight: 500;
+}
+.game-publish-media {
+  display: grid;
+  gap: 0.9rem;
+}
+.game-publish-media__cover {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.9rem;
+  align-items: flex-start;
+}
+.game-publish-media__copy {
+  display: grid;
+  flex: 1 1 16rem;
+  gap: 0.45rem;
+  min-width: 0;
+}
+.game-publish-media__preview {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: min(15rem, 100%);
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 0.7rem;
+  background: linear-gradient(
+    135deg,
+    rgba(241, 159, 95, 0.22),
+    rgba(91, 49, 42, 0.14)
+  );
+}
+.game-publish-media__preview img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.game-publish-media__placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--platform-text-soft);
+  font-size: 0.72rem;
+  font-weight: 600;
+}
+.game-publish-media__picker {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+/* 透明 input 覆盖在触发按钮上：真实点击永远命中原生控件，自定义文案只负责显示。 */
+.game-publish-media__picker input[type='file'] {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+.game-publish-media__pick {
+  display: inline-flex;
+  pointer-events: none;
+  align-items: center;
+  padding: 0.35rem 0.85rem;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 999px;
+  background: var(--platform-panel-fill);
+  color: var(--platform-text-strong);
+  font-size: 0.74rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: 160ms ease;
+}
+.game-publish-media__picker:hover .game-publish-media__pick {
+  border-color: rgba(199, 101, 61, 0.45);
+}
+.game-publish-media__picker
+  input[type='file']:focus-visible
+  + .game-publish-media__pick {
+  outline: 2px solid rgba(199, 101, 61, 0.35);
+  outline-offset: 2px;
+}
+.game-publish-media__picker
+  input[type='file']:disabled
+  + .game-publish-media__pick {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.game-publish-media__screenshots {
+  display: grid;
+  gap: 0.6rem;
+}
+.game-publish-media__strip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.game-publish-media__shot {
+  display: grid;
+  gap: 0.3rem;
+  width: 8.5rem;
+}
+.game-publish-media__shot img {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 0.55rem;
+}
+.game-publish-media__shot .game-publish-media__placeholder {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border: 1px dashed var(--platform-surface-border);
+  border-radius: 0.55rem;
+}
+.game-publish-media__remove {
+  justify-self: start;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 999px;
+  padding: 0.25rem 0.6rem;
+  background: transparent;
+  color: var(--platform-text-soft);
+  font: inherit;
+  font-size: 0.7rem;
+  cursor: pointer;
+}
+.game-publish-media__remove:hover:not(:disabled) {
+  color: var(--platform-text-strong);
+}
+.game-publish-media__remove:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.game-publish-actions {
+  display: flex;
+  justify-content: flex-end;
+}
+@media (max-width: 560px) {
+  .game-publish-row {
+    grid-template-columns: 1fr;
+  }
+  .game-publish-media__preview {
+    width: 100%;
+  }
+  .game-publish-media__shot {
+    width: calc(50% - 0.3rem);
+  }
+}
+
+/* 桌面端首屏：压缩 hero 高度，让第一排游戏卡片在 900px 视口内就能看到。 */
+@media (min-width: 1024px) {
+  .game-hero {
+    min-height: 13rem;
+    padding: clamp(1.5rem, 3vw, 2.5rem) clamp(1.5rem, 3.5vw, 3rem);
+  }
+  .game-hero h1 {
+    margin-top: 0.6rem;
+    font-size: clamp(1.8rem, 3.2vw, 2.6rem);
+  }
+  .game-hero p {
+    margin-top: 0.7rem;
+    max-width: 30rem;
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+  .game-hero__actions {
+    margin-top: 1rem;
+  }
+  .game-hero__orb {
+    width: clamp(7rem, 14vw, 12rem);
+  }
+}
diff --git a/src/components/game-distribution/gameDistributionGuards.ts b/src/components/game-distribution/gameDistributionGuards.ts
new file mode 100644
index 000000000..bb11a1059
--- /dev/null
+++ b/src/components/game-distribution/gameDistributionGuards.ts
@@ -0,0 +1,152 @@
+import { useEffect, useState } from 'react';
+
+const MAX_GAME_ID_LENGTH = 128;
+const MAX_ENTRY_URL_LENGTH = 4096;
+
+function containsControlCharacter(value: string) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint !== undefined && (codePoint < 0x20 || codePoint === 0x7f)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Route query values are untrusted input. Keep the client side guard small and
+ * permissive enough for server assigned ids while rejecting values that can
+ * become ambiguous path segments or control characters in diagnostics.
+ */
+export function normalizeGameId(value: string | null | undefined) {
+  const normalized = value?.trim() ?? '';
+  if (
+    !normalized ||
+    normalized.length > MAX_GAME_ID_LENGTH ||
+    containsControlCharacter(normalized)
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+/**
+ * The API is the authority for which release host is allowed. The browser
+ * still refuses executable URL schemes and credential-bearing URLs before a
+ * value can reach an iframe.
+ */
+export function normalizeGameEntryUrl(value: string | null | undefined) {
+  const normalized = value?.trim() ?? '';
+  if (
+    !normalized ||
+    normalized.length > MAX_ENTRY_URL_LENGTH ||
+    containsControlCharacter(normalized)
+  ) {
+    return null;
+  }
+
+  try {
+    const url = new URL(
+      normalized,
+      typeof window === 'undefined'
+        ? 'http://localhost'
+        : window.location.origin,
+    );
+    const isLocalDevelopmentHttp =
+      url.protocol === 'http:' &&
+      (url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '[::1]');
+    if (
+      (url.protocol !== 'https:' && !isLocalDevelopmentHttp) ||
+      url.username ||
+      url.password ||
+      (typeof window !== 'undefined' &&
+        url.origin === window.location.origin &&
+        !import.meta.env.DEV)
+    ) {
+      return null;
+    }
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+function readMobileViewport() {
+  if (typeof window === 'undefined') return false;
+  if (typeof window.matchMedia === 'function') {
+    return window.matchMedia('(max-width: 820px)').matches;
+  }
+  return window.innerWidth <= 820;
+}
+
+export function useIsMobileViewport() {
+  const [isMobileViewport, setIsMobileViewport] = useState(readMobileViewport);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+
+    const mediaQuery =
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia('(max-width: 820px)')
+        : null;
+    const update = () => setIsMobileViewport(readMobileViewport());
+    update();
+    window.addEventListener('resize', update);
+    mediaQuery?.addEventListener?.('change', update);
+
+    return () => {
+      window.removeEventListener('resize', update);
+      mediaQuery?.removeEventListener?.('change', update);
+    };
+  }, []);
+
+  return isMobileViewport;
+}
+
+function readPortraitViewport() {
+  if (typeof window === 'undefined') return false;
+  const { innerHeight, innerWidth } = window;
+  if (
+    typeof innerHeight === 'number' &&
+    typeof innerWidth === 'number' &&
+    innerHeight > 0 &&
+    innerWidth > 0 &&
+    innerHeight !== innerWidth
+  ) {
+    return innerHeight > innerWidth;
+  }
+  if (typeof window.matchMedia === 'function') {
+    return window.matchMedia('(orientation: portrait)').matches;
+  }
+  return false;
+}
+
+/**
+ * 横屏游戏的旋转提示只在竖屏视口出现；视口比例优先，matchMedia 作为兜底，
+ * 让没有方向查询能力的嵌入浏览器也能给出提示。
+ */
+export function useIsPortraitViewport() {
+  const [isPortrait, setIsPortrait] = useState(readPortraitViewport);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+
+    const mediaQuery =
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia('(orientation: portrait)')
+        : null;
+    const update = () => setIsPortrait(readPortraitViewport());
+    update();
+    window.addEventListener('resize', update);
+    mediaQuery?.addEventListener?.('change', update);
+
+    return () => {
+      window.removeEventListener('resize', update);
+      mediaQuery?.removeEventListener?.('change', update);
+    };
+  }, []);
+
+  return isPortrait;
+}
diff --git a/src/components/game-distribution/gameDistributionShowcase.css b/src/components/game-distribution/gameDistributionShowcase.css
new file mode 100644
index 000000000..5cd687181
--- /dev/null
+++ b/src/components/game-distribution/gameDistributionShowcase.css
@@ -0,0 +1,75 @@
+/*
+ * 游戏分发封面与截图的展示层补充样式。
+ *
+ * 真实封面/截图换签成功后覆盖原有渐变占位；未上传、换签失败或仍在解析时保持
+ * gameDistribution.css 里的占位视觉，因此这里的规则只负责“图片已就绪”这一态。
+ */
+.game-cover__image {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.game-detail-showcase {
+  display: grid;
+  gap: 0.7rem;
+  min-width: 0;
+}
+
+.game-detail-thumbs {
+  display: flex;
+  gap: 0.5rem;
+  overflow-x: auto;
+  padding-bottom: 0.15rem;
+  scroll-snap-type: x proximity;
+  scrollbar-width: thin;
+}
+
+.game-detail-thumb {
+  flex: 0 0 auto;
+  width: 5.4rem;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid var(--platform-surface-border);
+  border-radius: 0.7rem;
+  padding: 0;
+  background: linear-gradient(
+    135deg,
+    rgba(241, 159, 95, 0.24),
+    rgba(91, 49, 42, 0.16)
+  );
+  cursor: pointer;
+  scroll-snap-align: start;
+  transition: 160ms ease;
+}
+
+.game-detail-thumb:hover {
+  border-color: rgba(199, 101, 61, 0.45);
+}
+
+.game-detail-thumb[aria-pressed='true'] {
+  border-color: rgba(199, 101, 61, 0.62);
+  box-shadow: 0 0 0 2px rgba(199, 101, 61, 0.22);
+}
+
+.game-detail-thumb img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.game-detail-thumb__placeholder {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+@media (max-width: 560px) {
+  .game-detail-thumb {
+    width: 4.6rem;
+  }
+}
diff --git a/src/components/game-distribution/gameGalleryViewState.ts b/src/components/game-distribution/gameGalleryViewState.ts
new file mode 100644
index 000000000..d2f8439aa
--- /dev/null
+++ b/src/components/game-distribution/gameGalleryViewState.ts
@@ -0,0 +1,183 @@
+import type {
+  GameCategory,
+  GameDistributionGame,
+} from '../../services/gameDistributionClient';
+
+export const GAME_GALLERY_CATEGORIES: Array<GameCategory | '全部'> = [
+  '全部',
+  '动作',
+  '益智',
+  '冒险',
+  '休闲',
+  '模拟',
+  '策略',
+  '其他',
+];
+
+export type GameDeviceFilter = '全部' | '桌面' | '移动';
+
+export const GAME_GALLERY_DEVICE_FILTERS: GameDeviceFilter[] = [
+  '全部',
+  '桌面',
+  '移动',
+];
+
+/** 目录筛选写入地址栏，分享和刷新都能回到同一份上下文。 */
+const GALLERY_QUERY_KEYS = {
+  keyword: 'keyword',
+  category: 'category',
+  device: 'device',
+} as const;
+
+const GALLERY_STORAGE_KEYS = {
+  filters: 'game-gallery-filters',
+  scroll: 'game-gallery-scroll',
+} as const;
+
+/** 画廊挂在平台页签的滚动容器里，返回时按同一容器恢复位置。 */
+export const GAME_GALLERY_SCROLL_CONTAINER_SELECTOR = '.platform-tab-panel';
+
+export type GameGalleryFilters = {
+  keyword: string;
+  category: GameCategory | '全部';
+  device: GameDeviceFilter;
+};
+
+function readGalleryStorage() {
+  try {
+    return globalThis.sessionStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeCategory(value: string | null | undefined) {
+  const normalized = value?.trim() ?? '';
+  return (
+    GAME_GALLERY_CATEGORIES.find(
+      (item) => item !== '全部' && item === normalized,
+    ) ?? '全部'
+  );
+}
+
+function normalizeDevice(value: string | null | undefined) {
+  const normalized = value?.trim() ?? '';
+  return (
+    GAME_GALLERY_DEVICE_FILTERS.find((item) => item === normalized) ?? '全部'
+  );
+}
+
+export function gameGalleryScrollKey(filters: GameGalleryFilters) {
+  return `${GALLERY_STORAGE_KEYS.scroll}:${filters.keyword.trim()}|${filters.category}|${filters.device}`;
+}
+
+/**
+ * 只有地址栏里明确出现的筛选项才覆盖返回上下文，避免把用户分享的
+ * `?category=动作` 当成“其他筛选项已被清空”。
+ */
+export function readGameGalleryQueryFilters(
+  search: string,
+): Partial<GameGalleryFilters> {
+  const params = new URLSearchParams(search);
+  const filters: Partial<GameGalleryFilters> = {};
+  const keyword = params.get(GALLERY_QUERY_KEYS.keyword);
+  if (keyword !== null) filters.keyword = keyword;
+  const category = params.get(GALLERY_QUERY_KEYS.category);
+  if (category !== null) filters.category = normalizeCategory(category);
+  const device = params.get(GALLERY_QUERY_KEYS.device);
+  if (device !== null) filters.device = normalizeDevice(device);
+  return filters;
+}
+
+export function readStoredGameGalleryFilters(): Partial<GameGalleryFilters> {
+  const storage = readGalleryStorage();
+  if (!storage) return {};
+  try {
+    const raw = storage.getItem(GALLERY_STORAGE_KEYS.filters);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Partial<GameGalleryFilters> | null;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const filters: Partial<GameGalleryFilters> = {};
+    if (typeof parsed.keyword === 'string') filters.keyword = parsed.keyword;
+    if (typeof parsed.category === 'string') {
+      filters.category = normalizeCategory(parsed.category);
+    }
+    if (typeof parsed.device === 'string') {
+      filters.device = normalizeDevice(parsed.device);
+    }
+    return filters;
+  } catch {
+    return {};
+  }
+}
+
+export function writeStoredGameGalleryFilters(filters: GameGalleryFilters) {
+  const storage = readGalleryStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(GALLERY_STORAGE_KEYS.filters, JSON.stringify(filters));
+  } catch {
+    // 存储被禁用时筛选仍在本页生效，只是刷新后不再恢复。
+  }
+}
+
+export function readStoredGameGalleryScrollTop(key: string) {
+  const storage = readGalleryStorage();
+  if (!storage) return 0;
+  try {
+    const value = Number(storage.getItem(key));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function writeStoredGameGalleryScrollTop(
+  key: string,
+  scrollTop: number,
+) {
+  const storage = readGalleryStorage();
+  if (!storage) return;
+  try {
+    if (scrollTop > 0) storage.setItem(key, String(Math.round(scrollTop)));
+    else storage.removeItem(key);
+  } catch {
+    // 忽略存储失败，滚动位置不是业务状态。
+  }
+}
+
+export function syncGameGalleryQuery(filters: GameGalleryFilters) {
+  if (typeof window === 'undefined' || !window.history?.replaceState) return;
+  try {
+    const url = new URL(window.location.href);
+    const assign = (key: string, value: string) => {
+      if (value) url.searchParams.set(key, value);
+      else url.searchParams.delete(key);
+    };
+    assign(GALLERY_QUERY_KEYS.keyword, filters.keyword.trim());
+    assign(
+      GALLERY_QUERY_KEYS.category,
+      filters.category === '全部' ? '' : filters.category,
+    );
+    assign(
+      GALLERY_QUERY_KEYS.device,
+      filters.device === '全部' ? '' : filters.device,
+    );
+    window.history.replaceState(
+      window.history.state,
+      '',
+      `${url.pathname}${url.search}${url.hash}`,
+    );
+  } catch {
+    // 地址栏同步失败不影响筛选本身。
+  }
+}
+
+export function matchesGameDeviceFilter(
+  game: GameDistributionGame,
+  device: GameDeviceFilter,
+) {
+  if (device === '桌面') return game.deviceSupport.desktop;
+  if (device === '移动') return game.deviceSupport.mobile;
+  return true;
+}
diff --git a/src/components/game-distribution/gamePublishAssets.ts b/src/components/game-distribution/gamePublishAssets.ts
new file mode 100644
index 000000000..69f5b00eb
--- /dev/null
+++ b/src/components/game-distribution/gamePublishAssets.ts
@@ -0,0 +1,90 @@
+import { getSignedAssetReadUrl } from '../../services/assetReadUrlService';
+import { uploadEditorMediaAssetFile } from '../../services/image-editor/editorMediaAssetUploadClient';
+
+/** 游戏截图数量上限与服务端 `MAX_GAME_SCREENSHOTS` 保持一致。 */
+export const MAX_GAME_SCREENSHOTS = 6;
+/** 封面与截图都是公开展示素材，限制单张体积，避免手机原图直传拖垮发布流程。 */
+export const GAME_PUBLISH_IMAGE_MAX_BYTES = 6 * 1024 * 1024;
+export const GAME_PUBLISH_IMAGE_ACCEPT =
+  'image/png,image/jpeg,image/webp,image/gif';
+
+const GAME_PUBLISH_IMAGE_PREVIEW_EXPIRE_SECONDS = 60 * 60;
+
+export type GamePublishImageKind = 'cover' | 'screenshot';
+
+/** 已上传到平台的封面/截图素材：素材 ID 用于冻结资料，对象键用于换签展示。 */
+export type GamePublishImageAsset = {
+  assetObjectId: string;
+  objectKey: string;
+  /** 签名预览地址；换签失败时为空字符串，此时只显示占位，不影响继续发布。 */
+  src: string;
+  name: string;
+};
+
+function formatBytes(bytes: number) {
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+export function resolveGamePublishImageKindLabel(kind: GamePublishImageKind) {
+  return kind === 'cover' ? '游戏封面' : '游戏截图';
+}
+
+/** 本地预检；服务端仍会校验素材归属与图片类型，这里只拦掉明显不合规的文件。 */
+export function validateGamePublishImageFile(
+  file: File,
+  kind: GamePublishImageKind,
+) {
+  const label = resolveGamePublishImageKindLabel(kind);
+  if (file.size <= 0) {
+    throw new Error(`${label}文件为空，请重新选择。`);
+  }
+  if (file.size > GAME_PUBLISH_IMAGE_MAX_BYTES) {
+    throw new Error(
+      `${label}过大，请压缩后再上传（当前 ${formatBytes(file.size)}，最多 6MB）。`,
+    );
+  }
+  const contentType = file.type.trim();
+  if (contentType && !contentType.startsWith('image/')) {
+    throw new Error(`${label}必须是图片文件。`);
+  }
+}
+
+/**
+ * 上传一张封面/截图并返回可用于冻结资料的素材标识。
+ *
+ * 复用平台图片上传通道（直传凭证 + 直传 + confirm），对象键由服务端派生；这里不把
+ * 本地文件路径或外链写进资料，避免资料冻结时引用到平台之外的内容。
+ */
+export async function uploadGamePublishImageAsset(
+  file: File,
+  options: { kind: GamePublishImageKind; signal?: AbortSignal },
+): Promise<GamePublishImageAsset> {
+  validateGamePublishImageFile(file, options.kind);
+  const uploaded = await uploadEditorMediaAssetFile(file, 'image', {
+    assetKind: `game_distribution_${options.kind}`,
+    pathSegments: ['game-distribution', options.kind, `${Date.now()}`],
+    entityId: `game-distribution-${options.kind}`,
+    metadata: { game_distribution_media: options.kind },
+    signal: options.signal,
+  });
+  return {
+    assetObjectId: uploaded.assetObjectId,
+    objectKey: uploaded.objectKey,
+    src: uploaded.src,
+    name: file.name.trim() || resolveGamePublishImageKindLabel(options.kind),
+  };
+}
+
+/** 作者续发时按冻结资料里的对象键换签预览；失败返回空字符串，由调用方回退占位。 */
+export async function resolveGamePublishImagePreview(objectKey: string) {
+  const normalizedKey = objectKey.trim();
+  if (!normalizedKey) return '';
+  try {
+    return await getSignedAssetReadUrl({
+      objectKey: normalizedKey,
+      expireSeconds: GAME_PUBLISH_IMAGE_PREVIEW_EXPIRE_SECONDS,
+    });
+  } catch {
+    return '';
+  }
+}
diff --git a/src/components/game-distribution/gamePublishDraft.ts b/src/components/game-distribution/gamePublishDraft.ts
new file mode 100644
index 000000000..e3185e6f4
--- /dev/null
+++ b/src/components/game-distribution/gamePublishDraft.ts
@@ -0,0 +1,118 @@
+import type { GameDistributionRecoveryAction } from '../../../packages/shared/src/contracts/gameDistribution';
+
+/**
+ * 网页发布的恢复标识。
+ *
+ * 只保存服务端已经分配的游戏/版本标识与本地标题，用于窗口关闭或网络中断后回到同一
+ * 版本继续上传；不保存 ZIP 字节、凭据或账号资料。`ownerUserId` 用于换账号时拒绝恢复，
+ * 避免把上一个账号的私有状态展示给新账号。
+ */
+export type GamePublishDraft = {
+  ownerUserId: string;
+  gameId: string;
+  versionId: string;
+  versionNumber: number;
+  title: string;
+  updatedAt: string;
+};
+
+export const GAME_PUBLISH_DRAFT_STORAGE_KEY =
+  'genarrative.game-distribution.publish-draft.v1';
+
+type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+function resolveStorage(storage?: StorageLike): StorageLike | null {
+  if (storage) return storage;
+  if (typeof window === 'undefined') return null;
+  try {
+    // 某些隐私模式会直接抛 SecurityError，读不到存储时放弃恢复能力而不是让页面崩溃。
+    return window.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isDraft(value: unknown): value is GamePublishDraft {
+  if (!value || typeof value !== 'object') return false;
+  const draft = value as Partial<GamePublishDraft>;
+  return Boolean(
+    draft.ownerUserId &&
+      draft.gameId &&
+      draft.versionId &&
+      typeof draft.versionNumber === 'number' &&
+      typeof draft.title === 'string',
+  );
+}
+
+export function readPublishDraft(
+  storage?: StorageLike,
+): GamePublishDraft | null {
+  const target = resolveStorage(storage);
+  if (!target) return null;
+  try {
+    const raw = target.getItem(GAME_PUBLISH_DRAFT_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    return isDraft(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writePublishDraft(
+  draft: GamePublishDraft,
+  storage?: StorageLike,
+): void {
+  const target = resolveStorage(storage);
+  if (!target) return;
+  try {
+    target.setItem(GAME_PUBLISH_DRAFT_STORAGE_KEY, JSON.stringify(draft));
+  } catch {
+    // 隐私模式或配额不足时放弃恢复能力，不影响本次发布。
+  }
+}
+
+export function clearPublishDraft(storage?: StorageLike): void {
+  const target = resolveStorage(storage);
+  if (!target) return;
+  try {
+    target.removeItem(GAME_PUBLISH_DRAFT_STORAGE_KEY);
+  } catch {
+    // 清理失败时保留草稿，最多多显示一次恢复提示。
+  }
+}
+
+export type PublishDraftRecoveryCopy = {
+  title: string;
+  description: string;
+  actionLabel: string | null;
+};
+
+/** 恢复提示的文案完全由服务端 recoveryAction 派生，前端不推断版本状态。 */
+export function resolvePublishDraftRecoveryCopy(
+  action: GameDistributionRecoveryAction,
+  versionNumber: number,
+): PublishDraftRecoveryCopy {
+  switch (action) {
+    case 'upload':
+    case 'reupload':
+      return {
+        title: `上次发布未完成（版本 v${versionNumber}）`,
+        description: '重新选择同一个发行包 ZIP，会沿用原版本继续上传并送审。',
+        actionLabel: '继续上传',
+      };
+    case 'submit':
+      return {
+        title: `发行包已上传（版本 v${versionNumber}）`,
+        description: '可以直接继续提交审核，不需要重新上传。',
+        actionLabel: '继续送审',
+      };
+    default:
+      return {
+        title: `上次发布已交接（版本 v${versionNumber}）`,
+        description:
+          '该版本已经进入服务端流程，可以在「我的游戏」查看最新状态。',
+        actionLabel: null,
+      };
+  }
+}
diff --git a/src/components/game-distribution/gamePublishMetadata.ts b/src/components/game-distribution/gamePublishMetadata.ts
new file mode 100644
index 000000000..e92f06414
--- /dev/null
+++ b/src/components/game-distribution/gamePublishMetadata.ts
@@ -0,0 +1,35 @@
+import type { GameDistributionDeviceSupport } from '../../../packages/shared/src/contracts/gameDistribution';
+import { MAX_GAME_SCREENSHOTS } from './gamePublishAssets';
+
+/** 作者侧元数据校验；口径与服务端 `validate_game_metadata` 保持一致。 */
+export function resolvePublishMetadataError(input: {
+  title: string;
+  summary: string;
+  deviceSupport: GameDistributionDeviceSupport;
+  /** 封面素材 ID；服务端要求发布必须带封面，缺失时在本地先拦一次。 */
+  coverAssetId?: string | null;
+  /** 已选截图数量；上限与服务端 `MAX_GAME_SCREENSHOTS` 一致。 */
+  screenshotCount?: number;
+}) {
+  const title = input.title.trim();
+  const summary = input.summary.trim();
+  if (!title || Array.from(title).length > 40) {
+    return '游戏标题必须为 1 到 40 个字符';
+  }
+  if (!summary || Array.from(summary).length > 120) {
+    return '游戏简介必须为 1 到 120 个字符';
+  }
+  if (!input.deviceSupport.desktop && !input.deviceSupport.mobile) {
+    return '至少选择桌面端或移动端';
+  }
+  if (input.deviceSupport.mobile && !input.deviceSupport.touch) {
+    return '选择移动端时必须支持触控';
+  }
+  if (!input.coverAssetId?.trim()) {
+    return '发布游戏必须提供封面';
+  }
+  if ((input.screenshotCount ?? 0) > MAX_GAME_SCREENSHOTS) {
+    return '游戏截图最多 6 张';
+  }
+  return '';
+}
diff --git a/src/components/game-distribution/gameZipPackage.test.ts b/src/components/game-distribution/gameZipPackage.test.ts
new file mode 100644
index 000000000..d4f4181a0
--- /dev/null
+++ b/src/components/game-distribution/gameZipPackage.test.ts
@@ -0,0 +1,55 @@
+/* @vitest-environment jsdom */
+
+import JSZip from 'jszip';
+import { describe, expect, it } from 'vitest';
+
+import { prepareGamePackage } from './gameZipPackage';
+
+async function buildZip(files: Record<string, string>) {
+  const zip = new JSZip();
+  for (const [name, content] of Object.entries(files)) {
+    zip.file(name, content);
+  }
+  const bytes = await zip.generateAsync({ type: 'uint8array' });
+  return new File([bytes as unknown as BlobPart], 'game.zip', {
+    type: 'application/zip',
+  });
+}
+
+describe('prepareGamePackage', () => {
+  it('读取根 index.html、统计文件数并给出稳定摘要', async () => {
+    const file = await buildZip({
+      'index.html': '<html></html>',
+      'assets/app.js': 'console.log(1)',
+    });
+    const prepared = await prepareGamePackage(file);
+    expect(prepared.fileCount).toBe(2);
+    expect(prepared.totalBytes).toBe(file.size);
+    expect(prepared.sha256).toMatch(/^[0-9a-f]{64}$/u);
+    const again = await prepareGamePackage(file);
+    expect(again.sha256).toBe(prepared.sha256);
+  });
+
+  it('缺少根 index.html 时失败关闭', async () => {
+    const file = await buildZip({ 'game/index.html': '<html></html>' });
+    await expect(prepareGamePackage(file)).rejects.toThrow(
+      '发行包根目录必须包含 index.html',
+    );
+  });
+
+  it('拒绝空文件与非 ZIP 内容', async () => {
+    await expect(
+      prepareGamePackage(
+        new File([], 'empty.zip', { type: 'application/zip' }),
+      ),
+    ).rejects.toThrow('请选择非空的发行包 ZIP');
+
+    await expect(
+      prepareGamePackage(
+        new File(['not a zip' as unknown as BlobPart], 'bad.zip', {
+          type: 'application/zip',
+        }),
+      ),
+    ).rejects.toThrow('发行包不是有效的 ZIP');
+  });
+});
diff --git a/src/components/game-distribution/gameZipPackage.ts b/src/components/game-distribution/gameZipPackage.ts
new file mode 100644
index 000000000..eb8497f18
--- /dev/null
+++ b/src/components/game-distribution/gameZipPackage.ts
@@ -0,0 +1,92 @@
+import JSZip from 'jszip';
+
+export const GAME_PACKAGE_MAX_BYTES = 100 * 1024 * 1024;
+export const GAME_PACKAGE_MAX_FILE_COUNT = 10_000;
+
+export type PreparedGamePackage = {
+  bytes: Uint8Array;
+  sha256: string;
+  fileCount: number;
+  totalBytes: number;
+};
+
+function toHex(buffer: ArrayBuffer) {
+  return Array.from(new Uint8Array(buffer))
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/** 浏览器端发行包摘要；与服务端 `packageSha256` 同口径。 */
+export async function computeGamePackageSha256(bytes: Uint8Array) {
+  const digest = globalThis.crypto?.subtle;
+  if (!digest) {
+    throw new Error('当前浏览器无法计算发行包摘要，请升级浏览器后重试');
+  }
+  const copy = new Uint8Array(bytes);
+  return toHex(await digest.digest('SHA-256', copy.buffer as ArrayBuffer));
+}
+
+/**
+ * 上传前读取并校验 ZIP。
+ *
+ * 这里只做作者侧的前置校验，服务端仍会独立重算摘要与文件清单；两边口径必须一致，
+ * 前端校验通过不代表服务端一定接受。
+ */
+/** 读取 Blob 字节；FileReader 兜底覆盖不实现 `Blob.arrayBuffer()` 的旧 WebView 与 jsdom。 */
+export function readGamePackageBytes(blob: Blob): Promise<Uint8Array> {
+  if (typeof blob.arrayBuffer === 'function') {
+    return blob.arrayBuffer().then((buffer) => new Uint8Array(buffer));
+  }
+  return new Promise<Uint8Array>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const result = reader.result;
+      if (result instanceof ArrayBuffer) {
+        resolve(new Uint8Array(result));
+        return;
+      }
+      reject(new Error('读取发行包失败'));
+    };
+    reader.onerror = () => reject(new Error('读取发行包失败'));
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+export async function prepareGamePackage(
+  file: Blob,
+): Promise<PreparedGamePackage> {
+  if (!file || file.size === 0) {
+    throw new Error('请选择非空的发行包 ZIP');
+  }
+  if (file.size > GAME_PACKAGE_MAX_BYTES) {
+    throw new Error('发行包不能超过 100 MiB');
+  }
+  const bytes = await readGamePackageBytes(file);
+  let archive: JSZip;
+  try {
+    archive = await JSZip.loadAsync(bytes);
+  } catch {
+    throw new Error('发行包不是有效的 ZIP');
+  }
+
+  const entries = Object.values(archive.files).filter((entry) => !entry.dir);
+  if (entries.length === 0) {
+    throw new Error('发行包至少需要一个文件');
+  }
+  if (entries.length > GAME_PACKAGE_MAX_FILE_COUNT) {
+    throw new Error(`发行包文件数量不能超过 ${GAME_PACKAGE_MAX_FILE_COUNT} 个`);
+  }
+  if (!entries.some((entry) => entry.name === 'index.html')) {
+    throw new Error('发行包根目录必须包含 index.html');
+  }
+
+  // 展开总量、单文件上限与压缩比由服务端 ZIP 校验独立判定；前端不在浏览器里解压
+  // 整包，避免大包在客户端产生额外内存与耗时。
+
+  return {
+    bytes,
+    sha256: await computeGamePackageSha256(bytes),
+    fileCount: entries.length,
+    totalBytes: bytes.byteLength,
+  };
+}
diff --git a/src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx b/src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx
index 1b71fc729..92c5cbd8f 100644
--- a/src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx
+++ b/src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx
@@ -43,6 +43,30 @@ const profileCenterMock = vi.hoisted(() => ({
   rechargeCenter: null as { walletBalance: number } | null,
 }));
 
+const gameDistributionMock = vi.hoisted(() => ({
+  cancelGameVersion: vi.fn(),
+  createGame: vi.fn(),
+  createGameVersion: vi.fn(),
+  getGame: vi.fn(),
+  getGameVersion: vi.fn(),
+  listGames: vi.fn(),
+  listMyGames: vi.fn(),
+  submitGameVersion: vi.fn(),
+  unpublishGame: vi.fn(),
+  uploadGamePackage: vi.fn(),
+}));
+
+vi.mock('../../services/gameDistributionClient', () => gameDistributionMock);
+
+const frontendRuntimeConfigMock = vi.hoisted(() => ({
+  loadFrontendRuntimeConfig: vi.fn(),
+}));
+
+vi.mock('../../services/frontendRuntimeConfigService', () => ({
+  loadFrontendRuntimeConfig: (...args: unknown[]) =>
+    frontendRuntimeConfigMock.loadFrontendRuntimeConfig(...args),
+}));
+
 vi.mock('../auth/AuthUiContext', () => ({
   useAuthUi: () => authUiMock.value,
 }));
@@ -187,6 +211,16 @@ describe('PlatformEntryActiveFlowShell', () => {
     profileCenterMock.rechargeCenter = null;
     authUiMock.value.user = null;
     authUiMock.value.canAccessProtectedData = false;
+    window.history.replaceState(null, '', '/creation');
+    for (const mock of Object.values(gameDistributionMock)) {
+      mock.mockReset();
+    }
+    frontendRuntimeConfigMock.loadFrontendRuntimeConfig.mockReset();
+    frontendRuntimeConfigMock.loadFrontendRuntimeConfig.mockResolvedValue({
+      imageEditorAgentSidebarEnabled: false,
+      agcTemplateLibraryEnabled: false,
+      gameDistributionPublishEnabled: true,
+    });
     authUiMock.value.openLoginModal.mockReset();
     responsiveMock.isDesktopLayout = true;
   });
@@ -417,7 +451,7 @@ describe('PlatformEntryActiveFlowShell', () => {
       within(navigation)
         .getAllByRole('button')
         .map((button) => button.getAttribute('aria-label')),
-    ).toEqual(['创作', '项目', '我的']);
+    ).toEqual(['创作', '项目', '游戏', '我的']);
     expect(
       within(navigation)
         .getByRole('button', { name: '创作' })
@@ -466,7 +500,7 @@ describe('PlatformEntryActiveFlowShell', () => {
     ).toBe('page');
   });
 
-  it('keeps only profile reachable from the mobile dock', async () => {
+  it('keeps only games and profile reachable from the mobile dock', async () => {
     responsiveMock.isDesktopLayout = false;
     const setSelectionStage = vi.fn();
     render(
@@ -483,7 +517,7 @@ describe('PlatformEntryActiveFlowShell', () => {
       within(navigation)
         .getAllByRole('button')
         .map((button) => button.getAttribute('aria-label')),
-    ).toEqual(['我的']);
+    ).toEqual(['游戏', '我的']);
     expect(await screen.findByRole('main', { name: '我的' })).toBeTruthy();
     expect(screen.getByRole('button', { name: '下载客户端' })).toBeTruthy();
     expect(
@@ -568,7 +602,7 @@ describe('PlatformEntryActiveFlowShell', () => {
         within(navigation)
           .getAllByRole('button')
           .map((button) => button.getAttribute('aria-label')),
-      ).toEqual(['我的']);
+      ).toEqual(['游戏', '我的']);
       expect(
         within(navigation)
           .getByRole('button', { name: '我的' })
@@ -653,6 +687,146 @@ describe('PlatformEntryActiveFlowShell', () => {
     });
   });
 
+  it('在我的游戏里进入发布新版本时沿用同一个 gameId', async () => {
+    authUiMock.value.user = {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试用户',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    };
+    authUiMock.value.canAccessProtectedData = true;
+    gameDistributionMock.listMyGames.mockResolvedValue([
+      {
+        id: 'game-1',
+        title: '星轨防线',
+        summary: '守住轨道城',
+        description: '旧版资料',
+        category: '动作',
+        tags: ['塔防'],
+        coverColor: '#d77a51',
+        icon: '✦',
+        author: { id: 'user-1', name: '测试用户' },
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+        status: 'published',
+        publicationRevision: 3,
+        currentVersion: null,
+        playCount: 1,
+        createdAt: '2026-09-20T08:00:00Z',
+        latestVersion: {
+          versionId: 'gamever-2',
+          gameId: 'game-1',
+          versionNumber: 2,
+          packageSha256: 'e'.repeat(64),
+          packageBytes: 1024,
+          status: 'published',
+          publicationRevision: 3,
+          reviewReason: null,
+          createdAt: '2026-09-20T08:00:00Z',
+          updatedAt: '2026-09-20T09:00:00Z',
+        },
+        versions: [],
+      },
+    ]);
+    const setSelectionStage = vi.fn();
+
+    render(
+      <PlatformEntryFlowShellImpl
+        selectionStage="game-mine"
+        setSelectionStage={setSelectionStage}
+      />,
+    );
+
+    fireEvent.click(await screen.findByRole('button', { name: '发布新版本' }));
+
+    expect(setSelectionStage).toHaveBeenCalledWith('game-publish', {
+      path: '/games/publish?game=game-1',
+    });
+  });
+
+  it('发布页带 game 参数时进入更新模式并预填既有资料', async () => {
+    authUiMock.value.user = {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试用户',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    };
+    authUiMock.value.canAccessProtectedData = true;
+    gameDistributionMock.listMyGames.mockResolvedValue([
+      {
+        id: 'game-9',
+        title: '星轨防线',
+        summary: '守住轨道城',
+        description: '旧版资料',
+        category: '动作',
+        tags: ['塔防'],
+        coverColor: '#d77a51',
+        icon: '✦',
+        author: { id: 'user-1', name: '测试用户' },
+        deviceSupport: { desktop: true, mobile: false, touch: false },
+        status: 'published',
+        publicationRevision: 5,
+        currentVersion: null,
+        playCount: 1,
+        createdAt: '2026-09-20T08:00:00Z',
+        latestVersion: {
+          versionId: 'gamever-9',
+          gameId: 'game-9',
+          versionNumber: 4,
+          packageSha256: 'f'.repeat(64),
+          packageBytes: 2048,
+          status: 'published',
+          publicationRevision: 5,
+          reviewReason: null,
+          createdAt: '2026-09-20T08:00:00Z',
+          updatedAt: '2026-09-20T09:00:00Z',
+        },
+        versions: [],
+      },
+    ]);
+    gameDistributionMock.getGameVersion.mockResolvedValue({
+      game: {
+        id: 'game-9',
+        title: '星轨防线',
+        summary: '守住轨道城',
+        description: '旧版资料',
+        category: '动作',
+        tags: ['塔防'],
+        publicationRevision: 5,
+      },
+      version: {
+        versionId: 'gamever-9',
+        versionNumber: 4,
+        status: 'published',
+        publicationRevision: 5,
+        recoveryAction: 'none',
+      },
+    });
+    window.history.replaceState(null, '', '/games/publish?game=game-9');
+
+    render(
+      <PlatformEntryFlowShellImpl
+        selectionStage="game-publish"
+        setSelectionStage={vi.fn()}
+      />,
+    );
+
+    expect(
+      await screen.findByText(/正在为《星轨防线》发布新版本 v5/u),
+    ).toBeTruthy();
+    expect(screen.getByLabelText('游戏名称')).toHaveProperty(
+      'value',
+      '星轨防线',
+    );
+  });
+
   it('keeps guide and tool intent in editor navigation URLs', async () => {
     const setSelectionStage = vi.fn();
     const { rerender } = render(
@@ -691,3 +865,47 @@ describe('PlatformEntryActiveFlowShell', () => {
     });
   });
 });
+
+describe('游戏发布灰度入口', () => {
+  function loginAsAuthor() {
+    authUiMock.value.user = {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试作者',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    };
+    authUiMock.value.canAccessProtectedData = true;
+  }
+
+  it('灰度未命中时广场不展示发布入口', async () => {
+    loginAsAuthor();
+    frontendRuntimeConfigMock.loadFrontendRuntimeConfig.mockResolvedValue({
+      imageEditorAgentSidebarEnabled: false,
+      agcTemplateLibraryEnabled: false,
+      gameDistributionPublishEnabled: false,
+    });
+    gameDistributionMock.listGames.mockResolvedValue([]);
+
+    render(<StatefulPlatformEntryFlowShell initialStage="games" />);
+
+    expect(await screen.findByText('游戏广场')).toBeTruthy();
+    await waitFor(() =>
+      expect(screen.queryByRole('button', { name: '发布游戏' })).toBeNull(),
+    );
+  });
+
+  it('灰度命中时广场展示发布入口', async () => {
+    loginAsAuthor();
+    gameDistributionMock.listGames.mockResolvedValue([]);
+
+    render(<StatefulPlatformEntryFlowShell initialStage="games" />);
+
+    expect(
+      await screen.findByRole('button', { name: '发布游戏' }),
+    ).not.toBeNull();
+  });
+});
diff --git a/src/components/platform-entry/PlatformEntryActiveFlowShell.tsx b/src/components/platform-entry/PlatformEntryActiveFlowShell.tsx
index b0073d6a4..c5029d2e0 100644
--- a/src/components/platform-entry/PlatformEntryActiveFlowShell.tsx
+++ b/src/components/platform-entry/PlatformEntryActiveFlowShell.tsx
@@ -1,5 +1,6 @@
 import {
   FolderKanban,
+  Gamepad2,
   Home,
   Monitor,
   Palette,
@@ -24,6 +25,7 @@ import {
   pushAppHistoryPath,
   replaceAppHistoryPath,
 } from '../../routing/activeAppPageRoutes';
+import { loadFrontendRuntimeConfig } from '../../services/frontendRuntimeConfigService';
 import { getPlatformProfileDashboard } from '../../services/platform-entry/platformProfileClient';
 import { usePlatformWalletStore } from '../../stores/usePlatformWalletStore';
 import { useAuthUi } from '../auth/AuthUiContext';
@@ -66,6 +68,31 @@ const ProjectGalleryView = lazy(async () => {
   return { default: module.ProjectGalleryView };
 });
 
+const GameGalleryPage = lazy(async () => {
+  const module = await import('../game-distribution/GameGalleryPage');
+  return { default: module.GameGalleryPage };
+});
+
+const GameDetailPage = lazy(async () => {
+  const module = await import('../game-distribution/GameDetailPage');
+  return { default: module.GameDetailPage };
+});
+
+const GamePublishPage = lazy(async () => {
+  const module = await import('../game-distribution/GamePublishPage');
+  return { default: module.GamePublishPage };
+});
+
+const MyGamesPage = lazy(async () => {
+  const module = await import('../game-distribution/MyGamesPage');
+  return { default: module.MyGamesPage };
+});
+
+const GamePlayPage = lazy(async () => {
+  const module = await import('../game-distribution/GamePlayPage');
+  return { default: module.GamePlayPage };
+});
+
 type ActiveRailButtonProps = {
   active: boolean;
   emphasized?: boolean;
@@ -145,16 +172,26 @@ function ActiveBottomNavButton({
 function MobileProfileDock({
   active,
   onOpenProfile,
+  gameActive,
+  onOpenGames,
 }: {
   active: boolean;
   onOpenProfile: () => void;
+  gameActive: boolean;
+  onOpenGames: () => void;
 }) {
   return (
     <div className="platform-mobile-bottom-dock min-w-0 shrink-0 lg:hidden">
       <nav
-        className="platform-bottom-nav grid grid-cols-1"
+        className="platform-bottom-nav grid grid-cols-2"
         aria-label="移动平台导航"
       >
+        <ActiveBottomNavButton
+          active={gameActive}
+          icon={Gamepad2}
+          label="游戏"
+          onClick={onOpenGames}
+        />
         <ActiveBottomNavButton
           active={active}
           icon={UserRound}
@@ -244,6 +281,9 @@ export function PlatformEntryFlowShellImpl({
   setSelectionStage,
 }: PlatformEntryFlowShellProps) {
   const authUi = useAuthUi();
+  // 发布灰度：命中才暴露「发布游戏 / 发布新版本」入口；读取失败按放行处理，由后端写入口把关。
+  const [gamePublishGateAllowed, setGamePublishGateAllowed] = useState(true);
+  const gamePublishGateUserId = authUi?.user?.id ?? '';
   const [dashboard, setDashboard] = useState<ProfileDashboardSummary | null>(
     null,
   );
@@ -358,6 +398,65 @@ export function PlatformEntryFlowShellImpl({
     setSelectionStage('profile', { path: '/profile' });
   }, [setSelectionStage]);
 
+  const openGames = useCallback(() => {
+    setSelectionStage('games', { path: '/games' });
+  }, [setSelectionStage]);
+
+  useEffect(() => {
+    if (!gamePublishGateUserId) {
+      // 未登录时不展示发布入口，登录后由 authUi 变化触发重新读取。
+      setGamePublishGateAllowed(false);
+      return;
+    }
+    let cancelled = false;
+    loadFrontendRuntimeConfig()
+      .then((config) => {
+        if (!cancelled) {
+          setGamePublishGateAllowed(
+            config.gameDistributionPublishEnabled !== false,
+          );
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setGamePublishGateAllowed(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [gamePublishGateUserId]);
+
+  const openGamePublish = useCallback(() => {
+    setSelectionStage('game-publish', { path: '/games/publish' });
+  }, [setSelectionStage]);
+
+  const openGamePublishVersion = useCallback(
+    (gameId: string) => {
+      const path = `/games/publish?game=${encodeURIComponent(gameId)}`;
+      setSelectionStage('game-publish', { path });
+    },
+    [setSelectionStage],
+  );
+
+  const openMyGames = useCallback(() => {
+    setSelectionStage('game-mine', { path: '/games/mine' });
+  }, [setSelectionStage]);
+
+  const openGameDetail = useCallback(
+    (gameId: string) => {
+      const path = `/games/detail?id=${encodeURIComponent(gameId)}`;
+      setSelectionStage('game-detail', { path });
+    },
+    [setSelectionStage],
+  );
+
+  const openGamePlay = useCallback(
+    (gameId: string) => {
+      const path = `/games/play?id=${encodeURIComponent(gameId)}`;
+      setSelectionStage('game-play', { path });
+    },
+    [setSelectionStage],
+  );
+
   const openEditorProject = useCallback(
     (projectId: string, options?: { guide?: boolean; tool?: string }) => {
       if (!isDesktopLayout) {
@@ -402,7 +501,12 @@ export function PlatformEntryFlowShellImpl({
             setSelectionStage('platform', { path: '/' });
           }}
         />
-        <MobileProfileDock active={false} onOpenProfile={openProfile} />
+        <MobileProfileDock
+          active={false}
+          gameActive={false}
+          onOpenProfile={openProfile}
+          onOpenGames={openGames}
+        />
         <PlatformActiveMobileWelcomeDialog
           open={shouldOpenMobileHomeWelcome}
           platformThemeClass={platformThemeClass}
@@ -430,6 +534,17 @@ export function PlatformEntryFlowShellImpl({
   const isCreationStage =
     !isProfileStage &&
     (selectionStage === 'platform' || selectionStage === 'creation-home');
+  const isGamesStage =
+    selectionStage === 'games' ||
+    selectionStage === 'game-detail' ||
+    selectionStage === 'game-play' ||
+    selectionStage === 'game-mine' ||
+    selectionStage === 'game-publish';
+  const gameSearchParams = new URLSearchParams(
+    typeof window === 'undefined' ? '' : window.location.search,
+  );
+  const gameId = gameSearchParams.get('id');
+  const publishGameId = gameSearchParams.get('game');
   const avatarUrl = authUi?.user?.avatarUrl?.trim() || null;
   const avatarLabel = resolveActiveUserAvatarLabel(authUi?.user);
   const publicUserCode = resolveActivePublicUserCode(authUi?.user);
@@ -484,6 +599,14 @@ export function PlatformEntryFlowShellImpl({
                   label="项目"
                   onClick={openProjects}
                 />
+                <ActiveRailButton
+                  active={isGamesStage}
+                  emphasized={isGamesStage}
+                  icon={Gamepad2}
+                  iconSrc="/creation-home/nav-projects.png"
+                  label="游戏"
+                  onClick={openGames}
+                />
                 <ActiveRailButton
                   active={isProfileStage}
                   icon={UserRound}
@@ -515,8 +638,12 @@ export function PlatformEntryFlowShellImpl({
                     <input
                       type="search"
                       value={searchInput}
-                      placeholder="搜索项目、素材、作者或描述"
-                      aria-label="搜索项目和素材"
+                      placeholder={
+                        isGamesStage
+                          ? '搜索游戏、作者或标签'
+                          : '搜索项目、素材、作者或描述'
+                      }
+                      aria-label={isGamesStage ? '搜索游戏' : '搜索项目和素材'}
                       className="min-w-0 flex-1 bg-transparent text-sm text-[var(--platform-text-strong)] outline-none placeholder:text-[var(--platform-text-soft)]"
                       onChange={(event) => {
                         const value = event.target.value;
@@ -622,6 +749,50 @@ export function PlatformEntryFlowShellImpl({
                       searchKeyword={activeSearchKeyword}
                     />
                   </Suspense>
+                ) : isGamesStage ? (
+                  <Suspense
+                    fallback={<LoadingPanel label="正在加载游戏广场..." />}
+                  >
+                    {selectionStage === 'games' ? (
+                      <GameGalleryPage
+                        searchKeyword={activeSearchKeyword}
+                        onOpenDetail={openGameDetail}
+                        onOpenMyGames={openMyGames}
+                        onOpenPublish={
+                          gamePublishGateAllowed ? openGamePublish : undefined
+                        }
+                      />
+                    ) : selectionStage === 'game-publish' ? (
+                      <GamePublishPage
+                        onBack={openGames}
+                        onOpenMyGames={openMyGames}
+                        updateGameId={publishGameId}
+                      />
+                    ) : selectionStage === 'game-mine' ? (
+                      <MyGamesPage
+                        onBack={openGames}
+                        onOpenDetail={openGameDetail}
+                        onPublishVersion={
+                          gamePublishGateAllowed
+                            ? openGamePublishVersion
+                            : undefined
+                        }
+                      />
+                    ) : selectionStage === 'game-detail' ? (
+                      <GameDetailPage
+                        gameId={gameId}
+                        onBack={openGames}
+                        onPlay={openGamePlay}
+                      />
+                    ) : (
+                      <GamePlayPage
+                        gameId={gameId}
+                        onBack={() =>
+                          gameId ? openGameDetail(gameId) : openGames()
+                        }
+                      />
+                    )}
+                  </Suspense>
                 ) : (
                   <Suspense fallback={<LoadingPanel label="正在加载项目..." />}>
                     <ProjectGalleryView
@@ -635,7 +806,9 @@ export function PlatformEntryFlowShellImpl({
           </div>
           <MobileProfileDock
             active={isProfileStage}
+            gameActive={isGamesStage}
             onOpenProfile={openProfile}
+            onOpenGames={openGames}
           />
         </div>
       </div>
diff --git a/src/components/platform-entry/platformEntryActiveTypes.ts b/src/components/platform-entry/platformEntryActiveTypes.ts
index 694a9e31d..862fbe957 100644
--- a/src/components/platform-entry/platformEntryActiveTypes.ts
+++ b/src/components/platform-entry/platformEntryActiveTypes.ts
@@ -3,7 +3,12 @@ export type SelectionStage =
   | 'creation-home'
   | 'project'
   | 'profile'
-  | 'image-editor';
+  | 'image-editor'
+  | 'games'
+  | 'game-detail'
+  | 'game-play'
+  | 'game-mine'
+  | 'game-publish';
 
 export type PlatformEntryFlowShellProps = {
   selectionStage: SelectionStage;
diff --git a/src/config/viteProxyConfig.test.ts b/src/config/viteProxyConfig.test.ts
index 3d367e130..3ed2116b7 100644
--- a/src/config/viteProxyConfig.test.ts
+++ b/src/config/viteProxyConfig.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import viteConfig from '../../vite.config';
+import viteConfig, { isRetiredApiPath } from '../../vite.config';
 
 describe('vite dev api proxy', () => {
   it('forwards the profile main route to the Rust API server', async () => {
@@ -22,22 +22,19 @@ describe('vite dev api proxy', () => {
     );
   });
 
-  it('forwards the public creation entry config route to the Rust API server', async () => {
+  it('keeps the retired creation entry config route out of the dev proxy', async () => {
     const resolvedConfig =
       typeof viteConfig === 'function'
         ? await viteConfig({ command: 'serve', mode: 'test' })
         : viteConfig;
 
-    // 中文注释：创作入口配置是底部加号入口的首屏事实源，漏配代理会回退 index.html。
-    expect(resolvedConfig.server?.proxy).toEqual(
-      expect.objectContaining({
-        '/api/creation-entry': expect.objectContaining({
-          target: expect.any(String),
-          changeOrigin: true,
-          secure: false,
-        }),
-      }),
+    // 中文注释：`/api/creation-entry/config` 已在 api-server 侧退役（见
+    // `app.rs` 的 retired_creation_template_routes_are_not_mounted），dev 中间件按
+    // 退役路径返回 404；这里断言它不会被代理回真实 API，避免把已退役接口重新接上。
+    expect(resolvedConfig.server?.proxy).not.toHaveProperty(
+      '/api/creation-entry',
     );
+    expect(isRetiredApiPath('/api/creation-entry/config')).toBe(true);
   });
 
   it('forwards the admin route to the admin dev server', async () => {
@@ -57,4 +54,23 @@ describe('vite dev api proxy', () => {
       }),
     );
   });
+
+  it('forwards the game distribution route to the Rust API server', async () => {
+    const resolvedConfig =
+      typeof viteConfig === 'function'
+        ? await viteConfig({ command: 'serve', mode: 'test' })
+        : viteConfig;
+
+    // 中文注释：游戏目录、详情、发行网关和发布写入都在 `/api/game-distribution/*`；
+    // 漏配代理会回退 index.html，前端解析 JSON 时直接失败。
+    expect(resolvedConfig.server?.proxy).toEqual(
+      expect.objectContaining({
+        '/api/game-distribution': expect.objectContaining({
+          target: expect.any(String),
+          changeOrigin: true,
+          secure: false,
+        }),
+      }),
+    );
+  });
 });
diff --git a/src/routing/activeAppPageRoutes.test.ts b/src/routing/activeAppPageRoutes.test.ts
index 0f9e44fc4..d4512bd42 100644
--- a/src/routing/activeAppPageRoutes.test.ts
+++ b/src/routing/activeAppPageRoutes.test.ts
@@ -22,6 +22,13 @@ describe('appPageRoutes', () => {
     expect(resolveSelectionStageFromPath('/EDITOR/CANVAS/')).toBe(
       'image-editor',
     );
+    expect(resolveSelectionStageFromPath('/games')).toBe('games');
+    expect(resolveSelectionStageFromPath('/games/detail/')).toBe('game-detail');
+    expect(resolveSelectionStageFromPath('/games/play')).toBe('game-play');
+    expect(resolveSelectionStageFromPath('/games/mine')).toBe('game-mine');
+    expect(resolveSelectionStageFromPath('/games/publish')).toBe(
+      'game-publish',
+    );
     expect(resolveSelectionStageFromPath('/creation/rpg')).toBe('platform');
     expect(resolveSelectionStageFromPath('/runtime/puzzle')).toBe('platform');
     expect(isKnownMainAppPagePath('/creation')).toBe(true);
@@ -31,6 +38,9 @@ describe('appPageRoutes', () => {
     expect(resolvePathForSelectionStage('creation-home')).toBe('/creation');
     expect(resolvePathForSelectionStage('project')).toBe('/project');
     expect(resolvePathForSelectionStage('profile')).toBe('/profile');
+    expect(resolvePathForSelectionStage('games')).toBe('/games');
+    expect(resolvePathForSelectionStage('game-mine')).toBe('/games/mine');
+    expect(resolvePathForSelectionStage('game-publish')).toBe('/games/publish');
   });
 
   it('requires a project id for direct editor navigation', () => {
diff --git a/src/routing/activeAppPageRoutes.ts b/src/routing/activeAppPageRoutes.ts
index fd94eeeb2..edba4f6b2 100644
--- a/src/routing/activeAppPageRoutes.ts
+++ b/src/routing/activeAppPageRoutes.ts
@@ -9,6 +9,11 @@ const STAGE_ROUTE_ENTRIES = [
   ['project', '/project'],
   ['profile', '/profile'],
   ['image-editor', '/editor/canvas'],
+  ['games', '/games'],
+  ['game-detail', '/games/detail'],
+  ['game-play', '/games/play'],
+  ['game-mine', '/games/mine'],
+  ['game-publish', '/games/publish'],
 ] as const satisfies readonly (readonly [SelectionStage, string])[];
 
 export const APP_STAGE_ROUTES: Record<SelectionStage, string> =
diff --git a/src/services/activeAppTitle.test.ts b/src/services/activeAppTitle.test.ts
index fb4cb9ee4..b99dc1cff 100644
--- a/src/services/activeAppTitle.test.ts
+++ b/src/services/activeAppTitle.test.ts
@@ -32,6 +32,13 @@ describe('activeAppTitle', () => {
     expect(resolveAppTitleForSelectionStage('image-editor')).toBe(
       '美术编辑器 - 陶泥儿',
     );
+    expect(resolveAppTitleForSelectionStage('games')).toBe('游戏 - 陶泥儿');
+    expect(resolveAppTitleForSelectionStage('game-mine')).toBe(
+      '我的游戏 - 陶泥儿',
+    );
+    expect(resolveAppTitleForSelectionStage('game-publish')).toBe(
+      '发布游戏 - 陶泥儿',
+    );
   });
 
   test('syncs browser and host titles', () => {
diff --git a/src/services/activeAppTitle.ts b/src/services/activeAppTitle.ts
index 946f0054a..618713eab 100644
--- a/src/services/activeAppTitle.ts
+++ b/src/services/activeAppTitle.ts
@@ -10,6 +10,11 @@ const APP_TITLE_BY_SELECTION_STAGE: Record<SelectionStage, string> = {
   project: '项目 - 陶泥儿',
   profile: '我的 - 陶泥儿',
   'image-editor': '美术编辑器 - 陶泥儿',
+  games: '游戏 - 陶泥儿',
+  'game-detail': '游戏详情 - 陶泥儿',
+  'game-play': '正在游玩 - 陶泥儿',
+  'game-mine': '我的游戏 - 陶泥儿',
+  'game-publish': '发布游戏 - 陶泥儿',
 };
 
 export function resolveAppTitleForSelectionStage(stage: SelectionStage) {
diff --git a/src/services/frontendRuntimeConfigService.ts b/src/services/frontendRuntimeConfigService.ts
index 4be526523..d507b498d 100644
--- a/src/services/frontendRuntimeConfigService.ts
+++ b/src/services/frontendRuntimeConfigService.ts
@@ -5,6 +5,11 @@ const FRONTEND_RUNTIME_CONFIG_API = '/api/runtime/frontend-config';
 export type FrontendRuntimeConfig = {
   imageEditorAgentSidebarEnabled: boolean;
   agcTemplateLibraryEnabled: boolean;
+  /**
+   * 游戏发布灰度开关：后端未配置 `game-distribution:publish` 时对已登录作者默认开放，
+   * 显式收紧后只有白名单/灰度命中的作者为 `true`，匿名恒为 `false`。
+   */
+  gameDistributionPublishEnabled: boolean;
 };
 
 export async function loadFrontendRuntimeConfig() {
diff --git a/src/services/gameDistributionClient.test.ts b/src/services/gameDistributionClient.test.ts
new file mode 100644
index 000000000..5f4df129b
--- /dev/null
+++ b/src/services/gameDistributionClient.test.ts
@@ -0,0 +1,250 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearStoredAccessToken, setStoredAccessToken } from './apiClient';
+import {
+  cancelGameVersion,
+  createGameVersion,
+  getGame,
+  getGameVersion,
+  listGames,
+  listMyGames,
+  unpublishGame,
+  uploadGamePackage,
+} from './gameDistributionClient';
+
+describe('gameDistributionClient', () => {
+  beforeEach(() => {
+    clearStoredAccessToken({ emit: false });
+  });
+
+  it('按关键词和分类读取后端目录', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            games: [
+              {
+                id: 'game-1',
+                title: '星轨防线',
+                summary: '测试游戏',
+                currentVersion: { id: 'v1' },
+              },
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+      ),
+    );
+    const games = await listGames({ keyword: '星轨', category: '动作' });
+    expect(games).toHaveLength(1);
+    expect(games[0]?.id).toBe('game-1');
+  });
+
+  it('读取详情时拒绝空 id', async () => {
+    expect(await getGame('')).toBeNull();
+  });
+
+  it('版本创建携带幂等键并保留后端失败状态', async () => {
+    setStoredAccessToken('test-access-token', { emit: false });
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockImplementation(
+        () =>
+          new Response(JSON.stringify({ message: '包校验失败' }), {
+            status: 422,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+      ),
+    );
+    await expect(
+      createGameVersion(
+        'game-1',
+        {
+          packageSha256: 'x',
+          packageBytes: 1,
+          packageFileCount: 1,
+          packageEntryPath: 'index.html',
+          gameMetadata: {
+            title: '测试游戏',
+            summary: '测试',
+            category: '益智',
+            deviceSupport: { desktop: true, mobile: false, touch: false },
+            inputModes: ['keyboard'],
+            orientation: 'responsive',
+          },
+        },
+        'idem-1',
+      ),
+    ).rejects.toMatchObject({ status: 422 });
+  });
+
+  it('发行包上传使用独立版本资源和幂等键', async () => {
+    const fetchMock = vi.fn().mockImplementation(
+      () =>
+        new Response(
+          JSON.stringify({ versionId: 'version-1', status: 'uploaded' }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    setStoredAccessToken('test-access-token', { emit: false });
+    await uploadGamePackage('version-1', new ArrayBuffer(2), 'idem-upload');
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/game-distribution/versions/version-1/package',
+      expect.objectContaining({
+        method: 'PUT',
+        body: expect.any(ArrayBuffer),
+        headers: expect.objectContaining({
+          'Content-Type': 'application/zip',
+          'Idempotency-Key': 'idem-upload',
+        }),
+      }),
+    );
+  });
+});
+
+describe('gameDistributionClient 作者接口', () => {
+  beforeEach(() => {
+    clearStoredAccessToken({ emit: false });
+  });
+
+  it('读取我的游戏只返回带 id 的条目', async () => {
+    setStoredAccessToken('author-token', { emit: false });
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockImplementation(() =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              ok: true,
+              data: { games: [{ id: 'game-1' }, {}, null] },
+              error: null,
+              meta: { apiVersion: 'v1' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        ),
+      ),
+    );
+    const games = await listMyGames();
+    expect(games.map((game) => game.id)).toEqual(['game-1']);
+    const myGamesCall = vi
+      .mocked(fetch)
+      .mock.calls.find(([url]) => String(url).includes('/my-games'));
+    expect(myGamesCall?.[0]).toBe('/api/game-distribution/my-games');
+  });
+
+  it('下架请求携带 CAS 版本与幂等键，空入参在本地失败关闭', async () => {
+    setStoredAccessToken('author-token', { emit: false });
+    const fetchMock = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            ok: true,
+            data: { game: { id: 'game-1', status: 'unpublished' } },
+            error: null,
+            meta: { apiVersion: 'v1' },
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await unpublishGame('game-1', 4, 'unpublish-key-1');
+    const unpublishCalls = () =>
+      fetchMock.mock.calls.filter(([url]) =>
+        String(url).includes('/unpublish'),
+      );
+    expect(unpublishCalls()).toHaveLength(1);
+    expect(unpublishCalls()[0]?.[0]).toBe(
+      '/api/game-distribution/games/game-1/unpublish',
+    );
+    expect(unpublishCalls()[0]?.[1]).toEqual(
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ expectedPublicationRevision: 4 }),
+        headers: expect.objectContaining({
+          'Idempotency-Key': 'unpublish-key-1',
+        }),
+      }),
+    );
+
+    await expect(unpublishGame('   ', 1, 'k')).rejects.toThrow('缺少游戏编号');
+    await expect(unpublishGame('game-1', 1, '   ')).rejects.toThrow(
+      '缺少幂等键',
+    );
+    // 本地校验失败不得发出任何下架请求。
+    expect(unpublishCalls()).toHaveLength(1);
+  });
+
+  it('回读单个版本状态与服务端恢复动作', async () => {
+    setStoredAccessToken('test-access-token', { emit: false });
+    const fetchMock = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            game: { id: 'game-1' },
+            version: {
+              versionId: 'version-1',
+              status: 'upload_failed',
+              recoveryAction: 'reupload',
+            },
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const detail = await getGameVersion('version-1');
+    expect(detail.version.recoveryAction).toBe('reupload');
+    const readCall = fetchMock.mock.calls.find(([url]) =>
+      String(url).includes('/api/game-distribution/versions/version-1'),
+    );
+    expect(readCall?.[0]).toBe('/api/game-distribution/versions/version-1');
+    expect(readCall?.[1]?.method).toBe('GET');
+  });
+
+  it('撤回版本带幂等键与公开修订号，并拒绝空标识', async () => {
+    setStoredAccessToken('test-access-token', { emit: false });
+    const fetchMock = vi.fn().mockImplementation(() =>
+      Promise.resolve(
+        new Response(JSON.stringify({ replayed: false }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await cancelGameVersion('version-1', 3, 'idem-1', '看错了');
+    const cancelCalls = () =>
+      fetchMock.mock.calls.filter(([url]) =>
+        String(url).includes('/versions/version-1/cancel'),
+      );
+    expect(cancelCalls()).toHaveLength(1);
+    const cancelCall = cancelCalls()[0];
+    expect(cancelCall?.[1]?.method).toBe('POST');
+    expect(
+      (cancelCall?.[1]?.headers as Record<string, string>)['Idempotency-Key'],
+    ).toBe('idem-1');
+    expect(JSON.parse(String(cancelCall?.[1]?.body))).toEqual({
+      expectedPublicationRevision: 3,
+      reason: '看错了',
+    });
+
+    await expect(cancelGameVersion('', 1, 'idem-2')).rejects.toThrow(
+      '撤回版本缺少版本编号',
+    );
+    await expect(cancelGameVersion('version-1', 1, ' ')).rejects.toThrow(
+      '撤回版本缺少幂等键',
+    );
+    // 本地校验失败不得发出任何撤回请求。
+    expect(cancelCalls()).toHaveLength(1);
+  });
+});
diff --git a/src/services/gameDistributionClient.ts b/src/services/gameDistributionClient.ts
new file mode 100644
index 000000000..a18e05605
--- /dev/null
+++ b/src/services/gameDistributionClient.ts
@@ -0,0 +1,284 @@
+import type {
+  GameDistributionAuthor,
+  GameDistributionCancelVersionResponse,
+  GameDistributionCategory,
+  GameDistributionCreateGameRequest,
+  GameDistributionCreateVersionRequest,
+  GameDistributionDeviceSupport,
+  GameDistributionGame,
+  GameDistributionVersionDetail,
+  GameDistributionVersionStatus as GameDistributionVersionStatusValue,
+  GameDistributionVersionSummary,
+} from '../../packages/shared/src/contracts/gameDistribution';
+import {
+  type ApiRequestOptions,
+  requestJson as requestApiJson,
+} from './apiClient';
+
+export type {
+  GameDistributionAuthor,
+  GameDistributionDeviceSupport,
+  GameDistributionGame,
+  GameDistributionInputMode,
+  GameDistributionRecoveryAction,
+  GameDistributionVersionDetail,
+  GameDistributionVersionSummary,
+} from '../../packages/shared/src/contracts/gameDistribution';
+
+export type GameCategory = GameDistributionCategory;
+export type GameDeviceSupport = GameDistributionDeviceSupport;
+export type GameAuthor = GameDistributionAuthor;
+export type GameVersionSummary = GameDistributionVersionSummary;
+
+export type GameListQuery = {
+  keyword?: string;
+  category?: GameCategory | '全部';
+};
+
+export type GameVersionCreateResult = {
+  gameId: string;
+  versionId: string;
+  versionNumber: number;
+  status: 'awaiting_upload';
+};
+
+const API_BASE = '/api/game-distribution';
+
+function normalizeGameList(value: unknown): GameDistributionGame[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is GameDistributionGame => {
+    if (!item || typeof item !== 'object') return false;
+    const game = item as Partial<GameDistributionGame>;
+    return Boolean(game.id && game.title && game.currentVersion);
+  });
+}
+
+const PUBLIC_GAME_REQUEST_OPTIONS: ApiRequestOptions = {
+  skipAuth: true,
+  skipRefresh: true,
+  notifyAuthStateChange: false,
+  clearAuthOnUnauthorized: false,
+};
+
+async function requestJson<T>(
+  path: string,
+  init: RequestInit,
+  fallbackMessage: string,
+  options?: ApiRequestOptions,
+) {
+  return requestApiJson<T>(
+    `${API_BASE}${path}`,
+    {
+      ...init,
+      headers: {
+        Accept: 'application/json',
+        ...(init.body instanceof FormData ||
+        (typeof Blob !== 'undefined' && init.body instanceof Blob) ||
+        init.body instanceof ArrayBuffer
+          ? {}
+          : init.body
+            ? { 'Content-Type': 'application/json' }
+            : {}),
+        ...init.headers,
+      },
+    },
+    fallbackMessage,
+    options,
+  );
+}
+
+export async function listGames(query: GameListQuery = {}) {
+  const params = new URLSearchParams();
+  if (query.keyword?.trim()) params.set('keyword', query.keyword.trim());
+  if (query.category && query.category !== '全部')
+    params.set('category', query.category);
+  const payload = await requestJson<unknown>(
+    `/games${params.size ? `?${params.toString()}` : ''}`,
+    { method: 'GET' },
+    '读取游戏目录失败',
+    PUBLIC_GAME_REQUEST_OPTIONS,
+  );
+  return normalizeGameList(
+    Array.isArray(payload) ? payload : (payload as { games?: unknown[] }).games,
+  );
+}
+
+export type GameDistributionMyGame = GameDistributionGame & {
+  latestVersion: GameDistributionVersionStatusEntry | null;
+  versions: GameDistributionVersionStatusEntry[];
+};
+
+export type GameDistributionVersionStatusEntry = {
+  versionId: string;
+  gameId: string;
+  versionNumber: number;
+  packageSha256: string;
+  packageBytes: number;
+  status: GameDistributionVersionStatusValue;
+  publicationRevision: number;
+  reviewReason?: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export async function listMyGames() {
+  const payload = await requestJson<{ games?: unknown[] }>(
+    '/my-games',
+    { method: 'GET' },
+    '读取我的游戏失败',
+  );
+  const games = Array.isArray(payload?.games) ? payload.games : [];
+  return games.filter((item): item is GameDistributionMyGame =>
+    Boolean(item && typeof item === 'object' && (item as { id?: string }).id),
+  );
+}
+
+export async function unpublishGame(
+  gameId: string,
+  expectedPublicationRevision: number,
+  idempotencyKey: string,
+) {
+  const normalizedGameId = gameId.trim();
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedGameId) throw new Error('缺少游戏编号');
+  if (!normalizedKey) throw new Error('缺少幂等键');
+  return requestJson<{ game: { id: string; status: string } }>(
+    `/games/${encodeURIComponent(normalizedGameId)}/unpublish`,
+    {
+      method: 'POST',
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: JSON.stringify({ expectedPublicationRevision }),
+    },
+    '下架游戏失败',
+  );
+}
+
+export async function getGame(gameId: string) {
+  const normalizedId = gameId.trim();
+  if (!normalizedId) return null;
+  return requestJson<GameDistributionGame>(
+    `/games/${encodeURIComponent(normalizedId)}`,
+    { method: 'GET' },
+    '读取游戏详情失败',
+    PUBLIC_GAME_REQUEST_OPTIONS,
+  );
+}
+
+export async function createGame(
+  payload: GameDistributionCreateGameRequest,
+  idempotencyKey: string,
+) {
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedKey) throw new Error('创建游戏缺少幂等键');
+  return requestJson<GameDistributionGame>(
+    '/games',
+    {
+      method: 'POST',
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: JSON.stringify(payload),
+    },
+    '创建游戏失败',
+  );
+}
+
+export async function createGameVersion(
+  gameId: string,
+  payload: GameDistributionCreateVersionRequest,
+  idempotencyKey: string,
+) {
+  const normalizedGameId = gameId.trim();
+  const normalizedIdempotencyKey = idempotencyKey.trim();
+  if (!normalizedGameId || !normalizedIdempotencyKey) {
+    throw new Error('游戏版本创建缺少必要标识');
+  }
+  return requestJson<GameVersionCreateResult>(
+    `/games/${encodeURIComponent(normalizedGameId)}/versions`,
+    {
+      method: 'POST',
+      headers: { 'Idempotency-Key': normalizedIdempotencyKey },
+      body: JSON.stringify(payload),
+    },
+    '创建游戏版本失败',
+  );
+}
+
+/** 回读单个版本状态、驳回理由与服务端给出的恢复动作。 */
+export async function getGameVersion(versionId: string) {
+  const normalizedVersionId = versionId.trim();
+  if (!normalizedVersionId) throw new Error('缺少版本编号');
+  return requestJson<GameDistributionVersionDetail>(
+    `/versions/${encodeURIComponent(normalizedVersionId)}`,
+    { method: 'GET' },
+    '读取版本状态失败',
+  );
+}
+
+/** 撤回尚未公开的版本；幂等键由调用方生成，重复提交返回同一结果。 */
+export async function cancelGameVersion(
+  versionId: string,
+  expectedPublicationRevision: number,
+  idempotencyKey: string,
+  reason?: string,
+) {
+  const normalizedVersionId = versionId.trim();
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedVersionId) throw new Error('撤回版本缺少版本编号');
+  if (!normalizedKey) throw new Error('撤回版本缺少幂等键');
+  const normalizedReason = reason?.trim();
+  return requestJson<GameDistributionCancelVersionResponse>(
+    `/versions/${encodeURIComponent(normalizedVersionId)}/cancel`,
+    {
+      method: 'POST',
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: JSON.stringify({
+        expectedPublicationRevision,
+        ...(normalizedReason ? { reason: normalizedReason } : {}),
+      }),
+    },
+    '撤回版本失败',
+  );
+}
+
+export async function submitGameVersion(
+  versionId: string,
+  expectedPublicationRevision: number,
+  idempotencyKey: string,
+) {
+  const normalizedVersionId = versionId.trim();
+  const normalizedKey = idempotencyKey.trim();
+  if (!normalizedVersionId) throw new Error('提交审核缺少版本 ID');
+  if (!normalizedKey) throw new Error('提交审核缺少幂等键');
+  return requestJson<{ version?: { status?: string } }>(
+    `/versions/${encodeURIComponent(normalizedVersionId)}/submit`,
+    {
+      method: 'POST',
+      headers: { 'Idempotency-Key': normalizedKey },
+      body: JSON.stringify({ expectedPublicationRevision }),
+    },
+    '提交审核失败',
+  );
+}
+
+export async function uploadGamePackage(
+  versionId: string,
+  packageBody: Blob | ArrayBuffer,
+  idempotencyKey: string,
+) {
+  const normalizedVersionId = versionId.trim();
+  const normalizedIdempotencyKey = idempotencyKey.trim();
+  if (!normalizedVersionId || !normalizedIdempotencyKey) {
+    throw new Error('游戏发行包上传缺少必要标识');
+  }
+  return requestJson<{ versionId: string; status: 'uploaded' }>(
+    `/versions/${encodeURIComponent(normalizedVersionId)}/package`,
+    {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/zip',
+        'Idempotency-Key': normalizedIdempotencyKey,
+      },
+      body: packageBody,
+    },
+    '上传游戏发行包失败',
+  );
+}
diff --git a/vite.config.ts b/vite.config.ts
index 0cff4f5c4..d3d92d118 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -87,6 +87,7 @@ const ACTIVE_TOP_LEVEL_SOURCE_MODULES = new Map<string, ReadonlySet<string>>([
       'authService.ts',
       'clipboard.ts',
       'frontendRuntimeConfigService.ts',
+      'gameDistributionClient.ts',
       'sseStream.ts',
     ]),
   ],
@@ -179,6 +180,7 @@ const ACTIVE_TAILWIND_SOURCES = `@import 'tailwindcss' source(none);
 @source "./components/auth";
 @source "./components/common";
 @source "./components/creation-home";
+@source "./components/game-distribution";
 @source "./components/image-editor";
 @source "./components/project";
 @source "./components/platform-entry/PlatformEntryFlowShell.tsx";
@@ -695,6 +697,11 @@ export default defineConfig(({ mode }) => {
           changeOrigin: true,
           secure: false,
         },
+        '/api/game-distribution': {
+          target: runtimeServerTarget,
+          changeOrigin: true,
+          secure: false,
+        },
         '/api/llm': {
           target: runtimeServerTarget,
           changeOrigin: true,
diff --git a/vitest.config.ts b/vitest.config.ts
index b017131fc..89e218467 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -106,9 +106,11 @@ export default defineConfig({
     },
     include: [
       'src/index.test.ts',
+      'src/config/**/*.test.ts',
       'src/routing/activeAppPageRoutes.test.ts',
       'src/routing/activeAppRoutes.test.ts',
       'src/services/activeAppTitle.test.ts',
+      'src/services/gameDistributionClient.test.ts',
       'src/services/assetReadUrlService.test.ts',
       'src/services/authService.test.ts',
       'src/services/apiClient.test.ts',
@@ -124,6 +126,8 @@ export default defineConfig({
       'src/components/auth/**/*.test.tsx',
       'src/components/creation-home/**/*.test.ts',
       'src/components/creation-home/**/*.test.tsx',
+      'src/components/game-distribution/**/*.test.ts',
+      'src/components/game-distribution/**/*.test.tsx',
       'src/components/shared-components/**/*.test.tsx',
       'src/components/common/AutoGrowTextArea.test.tsx',
       'src/components/common/CreativeImageInputPanel.test.tsx',