合并 master 并保留游戏分发功能

- 合并 origin/master（含 429f991bd 定向回滚、Godot 原生绑定迁移与策划 Agent 模型控件）。 - 回滚提交删除的游戏分发代码按功能面补回：SpacetimeDB 模块注册与迁移表、api-server 路由与权限映射、后台审核页、AGC 发布命令与 payload 类型、SelectionStage 的 games 阶段、ProjectSupervisorView 的 overlay 挂载点、主站路由与标题、Cargo 依赖与锁、vite/vitest 代理与 tailwind source。 - 保留 master 的 Godot C++ 迁移（移除旧 vendored GDExtension、新的 composer 控件布局）与其它 master 侧改动。 - 修正 master 自带的红灯断言：/api/creation-entry 已被 api-server 列入退役路由，dev 中间件按退役路径 404，测试改为断言不进入代理。 - 验证：cargo check（api-server / spacetime-module / spacetime-client / AGC 壳）、cargo test（api-server 游戏分发 17、module-game-distribution 11、AGC 本地导出 7）、全量 vitest 4557 passed、两端 typecheck、eslint、rustfmt、编码、文档索引与 SpacetimeDB schema guard。
策划agent可设置模型和推理挡 (#436 )
2026-09-21 00:20:45 +08:00 · 2026-09-20 23:46:33 +08:00 · 2026-09-20 22:56:43 +08:00 · 2026-09-20 22:49:56 +08:00 · 2026-09-20 22:45:50 +08:00 · 2026-09-20 22:34:33 +08:00
948 changed files with 114287 additions and 26498 deletions
@@ -32,7 +32,7 @@ Prefer `scripts/genarrative_external_api.py` for runnable REST calls. It uses on
 - Use stable references such as `objectKey`, project resource ID, or asset ID where each operation permits them. Image edit/redraw is stricter: `sourceReferenceId` accepts only a registered project resource ID or asset ID; upload confirmation alone is not enough. Use `/assets/read-url` only for temporary preview/download access.
 - Preserve both warning channels after completion. A general `warning` can coexist with `sliceWarning`; do not discard either.
 - Do not invent missing derivatives. A source-preserved warning means the main source remains usable but requested post-processing failed. A slice warning means the complete transparent sheet is usable but individual slices are absent.
- Icon spritesheet generation accepts `sliceMode="connected-components"` (default alpha-connectivity detection) or `sliceMode="grid"`. Grid mode requires `gridX` and `gridY` (1-32); use `sliceCount` only to constrain connected-component output.
+- Icon spritesheet generation requires an explicit `sliceMode` and has no default. Use `sliceMode="grid"` with the `gridX` and `gridY` the requirement actually names (1-32 each) only for equal grid cells or fixed slots; use `sliceMode="connected-components"` for free-form sheets or an open number of subjects, and constrain the count with `sliceCount` instead of inventing grid dimensions. `connected-components` must not carry `gridX`/`gridY`; an omitted, contradictory, or misapplied declaration returns 400 before billing.
 - For successful `style="pixelArt"`, treat completed-result and nested resource/asset dimensions as the final logical-grid PNG dimensions. They may differ from `size`, `imageSize`, the provider image, and `canvasCompletion.placeholder`; do not rescale or reject the artifact to match those inputs.
 - Keep generated artifacts in the canvas and asset library together. Character animation accepts `assetFolderId` and `assetLabel`; its completed result directly returns the final `assetKind="character-animation"` resource and asset with formal sequence fields. Do not create a duplicate first-frame record.
@@ -94,7 +94,7 @@ For image edit/redraw, confirming an upload is not sufficient: create a project
 The icon-spritesheet primary `referenceId` is intentionally stricter than ordinary image references: it accepts only a current-owner project resource ID or asset ID whose authoritative `assetKind` is `icon-spec`. It does not accept an `objectKey`, URL, Data URL, or Blob URL.
-`sliceMode` controls atlas splitting. Use `"connected-components"` (default) to detect independent opaque regions by alpha connectivity, or `"grid"` with positive `gridX` and `gridY` values (maximum 32 each). `sliceCount` optionally constrains the connected-component result.
+`sliceMode` is required and has no default, so every request must state it. Use `"connected-components"` to detect independent opaque regions by alpha connectivity, or `"grid"` with positive `gridX` and `gridY` values (maximum 32 each) only when the requirement names equal grid cells or fixed slots; the dimensions must come from that requirement. `connected-components` must not carry `gridX`/`gridY`, and `sliceCount` constrains the connected-component result instead of expressing a grid. Omitting `sliceMode`, or contradicting the declared mode with grid dimensions, returns 400 before pricing, enqueueing, or any provider call.
 ## Common Values
@@ -79,9 +79,9 @@ Keep the existing autonomous-build task graph. Do not add a parallel task system
 1. `art-director` generates `assets/art-spec.png` with image generation, `kind: "spec"`, then registers it as `assetKind: "icon-spec"`. This image is the authoritative visual spec; `generationInputs.artSpec` is supporting structured context.
 2. `design-foundation` generates `assets/ui-prototype.png` with `kind: "ui-design"`, using the registered art-spec resource ID in `referenceImageSrcs`.
-3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. For a fixed four-category game contract it may send `sliceMode: "grid"`; for free-form assets use `sliceMode: "connected-components"` (the default).
+3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. `sliceMode` is required and has no default: send `sliceMode: "grid"` with `gridX`/`gridY` only when the requirement itself fixes the slots or names the column/row count, and otherwise send `sliceMode: "connected-components"` (with `sliceCount` when a subject count must be constrained); never invent a grid to express "kinds of assets", and never send `gridX`/`gridY` with `connected-components`.
-For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. When using the fixed four-category contract, require response `sliceMode: "grid"` and exactly four slices before registering the local runtime sheet; both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet `<img>`, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation.
+For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. When the requirement fixes grid slots, require the response `sliceMode` to match the declared `grid` request and exactly `gridX × gridY` slices before registering the local runtime sheet; a connected-components request is instead judged by its own `sliceCount` or by the requirement, and both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet `<img>`, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation.
 Never use `assets/ui-prototype.png` as the spritesheet visual-spec reference. UI extraction is outside this canonical DAG.
@@ -617,6 +617,7 @@ class GenarrativeExternalClient:
        self,
        reference_id: str,
        icon_descriptions: list[str],
        slice_mode: str,
        **fields: Any,
    ) -> Any:
        reference_id = normalize_optional_text(reference_id)
@@ -625,6 +626,20 @@ class GenarrativeExternalClient:
        descriptions = [item.strip() for item in icon_descriptions if item.strip()]
        if not descriptions:
            raise GenarrativeApiError("icon_descriptions must contain at least one non-empty item")
        slice_mode = normalize_optional_text(slice_mode)
        if slice_mode not in ("connected-components", "grid"):
            raise GenarrativeApiError(
                "slice_mode must be declared explicitly as 'connected-components' or 'grid'; the API has no default"
            )
        grid_x = fields.get("gridX")
        grid_y = fields.get("gridY")
        if slice_mode == "grid":
            if grid_x is None or grid_y is None:
                raise GenarrativeApiError("slice_mode='grid' requires both gridX and gridY")
        elif grid_x is not None or grid_y is not None:
            raise GenarrativeApiError(
                "slice_mode='connected-components' must not carry gridX/gridY"
            )
        label = fields.get("assetLabel", "图标图集")
        self._apply_canvas_session_fields(fields, label, 1024, 1024)
        fields.setdefault("screenColor", "auto")
@@ -635,6 +650,7 @@ class GenarrativeExternalClient:
                **fields,
                "referenceId": reference_id,
                "iconDescriptions": descriptions,
                "sliceMode": slice_mode,
            },
            idempotency_key=idempotency_key,
        )
@@ -879,9 +895,9 @@ def _self_test() -> None:
    client.generate_icon_spritesheet(
        "editor-resource-spec",
        ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"],
        "connected-components",
        canvasSession=session,
        assetLabel="贪吃蛇透明图集",
        sliceMode="connected-components",
        referenceId="must-not-override-explicit-reference",
        iconDescriptions=["不得覆盖显式图标描述"],
    )
@@ -158,6 +158,15 @@ ALIYUN_OSS_POST_EXPIRE_SECONDS="600"
 ALIYUN_OSS_POST_MAX_SIZE_BYTES="20971520"
 ALIYUN_OSS_SUCCESS_ACTION_STATUS="200"
 # AGC 项目定时快照上传目标。对象只落在服务端私有前缀
 # `agc/project-snapshots/v1/{user}/{project}/` 下，客户端直传票据不覆盖该前缀。
 # bucket 与凭据可以与资源 bucket 分离；凭据未设置时回退使用 ALIYUN_OSS_ACCESS_KEY_*，
 # 但 bucket / endpoint 默认指向 AGC 发行 bucket，需要该凭据具备目标 bucket 的 PutObject 权限。
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET="agc-dev"
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ENDPOINT="oss-rg-china-mainland.aliyuncs.com"
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_ID=""
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_SECRET=""
 # BgFilter 受限资源 worker。父 api-server / external-generation-worker 与唯一的
 # `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 进程必须使用同一个内部 Token。
 # `npm run dev` 与 `npm run dev:api-server` 都会自动带起并验活唯一 worker，不要再开第二个终端重复启动。
@@ -226,6 +235,10 @@ VITE_DEBUG_MODE=""
 # This is read by api-server and exposed through /api/runtime/frontend-config.
 GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 # 官网客户端下载检测渠道：dev、release 或自定义渠道；修改后重启 API 服务。
 # Windows/macOS 是系统维度，不填写 dev-win/dev-mac。
 GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL="dev"
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.
@@ -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',
@@ -23,3 +23,6 @@
 *.meta text
 *.anim text
 *.controller text
 # Rust ts-rs 生成的共享契约：保留在仓库中供 TS 消费，但不作为手写源文件统计。
 packages/shared/src/contracts/generated/** linguist-generated=true
@@ -7,6 +7,10 @@ on:
  pull_request:
  workflow_dispatch:
 concurrency:
  group: project-ci-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
 permissions:
  contents: read
@@ -217,8 +221,7 @@ jobs:
      - name: Run AI game creator shell agent-run smoke
        run: npm run check:native-shells:agc-rust-smoke
-  # AGC 壳依赖的共享 / 平台 crate 测试用的是 server-rs workspace 与两个无锁独立 crate
+  # AGC 壳依赖的共享 / 平台和编辑器插件 crate 各自预热独立 manifest，再运行对应测试。
  # 的 manifest，属另一套依赖图，因此单独一个 job 预热、单独跑。
  ai-game-creator-shell-rust-crates:
    name: AI game creator shell Rust crates
    runs-on: genarrative-ci
@@ -259,13 +262,15 @@ jobs:
          # `cargo test --manifest-path` 单独跑这两个 crate。不在这里预热的话，这两条测试
          # 会在测试阶段自己 `Updating crates.io index`，crates.io 一抖动整条 job 就红
          # （见 #327 / PR #316 run 1950）。
-          # 两个 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
+          # Cocos 插件也使用独立且未提交的锁文件，一并预热。
          # 这些 crate 都没有提交 Cargo.lock，所以这里只能做不带锁标志的 fetch：
          # 加锁标志会因为缺少锁文件直接失败。生成的 Cargo.lock 落在两个 crate 目录内，
          # 已被各自的 .gitignore 忽略，只留在容器里；随后的测试阶段因此能用锁定版本
          # 解析，不再触碰 registry index。
          for manifest_path in \
            server-rs/crates/agent-runtime-core/Cargo.toml \
-            server-rs/crates/agent-runtime-orchestration/Cargo.toml; do
+            server-rs/crates/agent-runtime-orchestration/Cargo.toml \
            plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml; do
            for attempt in $(seq 1 5); do
              if cargo fetch \
                --target x86_64-unknown-linux-gnu \
@@ -280,6 +285,40 @@ jobs:
            done
          done
      - name: Prepare Unity plugin Rust dependencies
        shell: bash
        run: |
          set -euo pipefail
          for attempt in $(seq 1 5); do
            if cargo fetch --locked \
              --target x86_64-unknown-linux-gnu \
              --manifest-path plugins/agc-unity-editor/native/unity-editor-bridge/Cargo.toml; then
              break
            fi
            if [[ "${attempt}" -eq 5 ]]; then
              echo 'Unity plugin Cargo dependency fetch failed after 5 attempts.' >&2
              exit 1
            fi
            sleep $((attempt * 2))
          done
      - name: Prepare Godot plugin Rust dependencies
        shell: bash
        run: |
          set -euo pipefail
          for attempt in $(seq 1 5); do
            if cargo fetch --locked \
              --target x86_64-unknown-linux-gnu \
              --manifest-path plugins/agc-godot-editor/native/godot-editor-bridge/Cargo.toml; then
              break
            fi
            if [[ "${attempt}" -eq 5 ]]; then
              echo 'Godot plugin Cargo dependency fetch failed after 5 attempts.' >&2
              exit 1
            fi
            sleep $((attempt * 2))
          done
      - name: Run AI game creator shell shared crate gates
        run: npm run check:native-shells:agc-rust-crates
@@ -41,7 +41,17 @@ temp*build*/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/codex-resources/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/codex-package.json
 /apps/ai-game-creator-shell/src-tauri/resources/plugins/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/bin/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-path/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-resources/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/codex-package.json
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/manifest.json
 /apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/NOTICE.md
 /plugins/agc-cocos-editor/native/payload/
 /plugins/agc-unity-editor/dotnet/**/bin/
 /plugins/agc-unity-editor/dotnet/**/obj/
 /plugins/agc-unity-editor/dotnet/publish/
 /plugins/agc-unity-editor/dotnet/native-build/
 /apps/ai-game-creator-shell/logs/
 /apps/ai-game-creator-shell/.llm-drafts/
 /apps/ai-game-creator-shell/game-creator.config.local.json
@@ -1,5 +1,14 @@
 {
  "singleQuote": true,
  "semi": true,
-  "trailingComma": "all"
+  "trailingComma": "all",
  "overrides": [
    {
      "files": "packages/shared/src/contracts/generated/**/*.ts",
      "options": {
        "printWidth": 1000,
        "singleQuote": false
      }
    }
  ]
 }
@@ -4,12 +4,13 @@
 - 本文件只保留 Agent 进入仓库后必须立即遵守的最高优先级规则；完整执行细则见 [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。
 - 团队级长期项目记忆位于 [`docs/project-memory/`](docs/project-memory/)，供 3 名开发人员和各自本地 Agent 通过 Git 同步。
- [`.codex/`](.codex/) 只保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识不要写入 `.codex/`。
+- [`.codex/`](.codex/) 保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识写入 `docs/` 与 `docs/project-memory/`。
 - 若 `docs/project-memory/shared-memory/` 与当前代码或最新 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正过期共享记忆。
 ## 开始任务前
- 先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项；工具探测、历史整理或验证便利不能自行改变任务目标。
+- 先写清一句话交付结果、验收判据和修改范围，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，其余记录为后续事项。
 - Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
 - 简单自包含任务可以直接执行；复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按顺序读取：
  1. 本文件。
  2. [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。
@@ -23,24 +24,20 @@
 - 禁止提交个人 `~/.codex` 配置、`.env`、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
 - 不要在 `.gitignore` 中新增 `.env.local`。
- 不要擅自把现有中文文案、注释、剧情或文档改写成英文；看到中文乱码时先确认真实编码，不要沿用乱码或用英文替换。
+- 现有中文文案、注释、剧情和文档保持中文；看到乱码时先确认真实编码并恢复正确中文。
- 修改包含中文的文件时优先局部补丁，避免整文件重写；修改后优先运行仓库编码检查。
+- 修改包含中文的文件时优先局部补丁；修改后优先运行仓库编码检查。
- 后续新增 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；历史文档不要求批量重命名，除非本次任务明确涉及。
+- 新增 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。
 - 工程修改要同步更新对应 `docs/` 文档；产生长期有效的架构约定、接口变化、排障经验、开发流程或协作规则时，同步更新 `docs/project-memory/shared-memory/`。
- 默认保持系统简洁：优先复用、修改、扩展现有系统、页面和公共组件，不新建平行系统或平行页面。
+- 默认保持系统简洁：优先复用、修改、扩展现有系统、页面和公共组件。
- UI 开发优先复用现有公共组件；发现跨页面或跨端重复的视觉/交互模式时，先抽取到 `packages/shared` 共享组件库并让现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
+- UI 开发优先复用现有公共组件；发现跨页面或跨端重复的视觉/交互模式时，先抽取到 `packages/shared` 共享组件库并让现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
- 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，坚持“四不写”：
+- 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。
-  1. 不写历史兼容代码。
+- 公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移按实际需求保留最小、白名单化的兼容，并配套契约或迁移测试；迁移完成后同步删除兼容实现与对应测试。
-  2. 不写用于维持退役行为的防御性兼容测试。
+- UI 面板优先呈现任务内容与操作，说明按当前操作需要提供；移动端优先，同时保证网页端可正常显示和操作。
-  3. 不写仅说明其曾存在或已删除的墓碑注释。
+- 点击按钮弹出的独立面板使用弹窗、抽屉、popover 或页面级 portal。
  4. 不写仅记录其已删除的墓碑文档；直接将权威文档更新为当前状态。
 - 公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移不适用“四不写”；必要兼容应最小化、白名单化并配套契约或迁移测试，迁移完成后同步删除兼容实现与对应测试。
 - UI 面板中不要默认写功能说明、规则描述或开发解释文案；移动端优先，同时保证网页端可正常显示和操作。
 - 点击按钮弹出独立面板的设计，不要实现成在当前面板下面追加内容。
 ## 任务路由
- Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 `tea` CLI，不使用 GitHub `gh` 或 GitLab `glab`，除非仓库已迁移。默认 triage 标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
+- Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 `tea` CLI。默认 triage 标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
 - 需要仓库级 Codex skills/plugins 时，再读取 [`.codex/README.md`](.codex/README.md)。
 - 涉及 AI 游戏创作独立 App、多智能体 Runtime、本地项目产物或本地 HTTP 预览时，先读取 [`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`](docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
 - 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 前，必须读取并按 [`genarrative-play-type-integration`](.codex/skills/genarrative-play-type-integration/SKILL.md) 执行。
@@ -50,10 +47,10 @@
 ## 后端红线
 - 后端最新技术约束以 [`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`](docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md) 为准。
- 后端路线固定为 `server-rs + Axum + SpacetimeDB`；旧 `server-node`、Express、PostgreSQL、Go 服务端、`maincloud` / `Maincloud` / `MAINCLOUD` 只作为历史残留，不作为兼容目标。
+- 后端路线固定为 `server-rs + Axum + SpacetimeDB`。
 - DDD 分层边界按总纲执行：领域规则沉到 `module-*`，SpacetimeDB 表和事务编排留在 `spacetime-module`，后端访问 SpacetimeDB 统一经 `spacetime-client` facade，HTTP/SSE/BFF 留在 `api-server`，外部副作用留在 `platform-*`，前后端 DTO 留在 `shared-contracts`。
- 前端只做表现、交互和临时 UI 状态，不承接正式业务真相，不绕过后端投影或后端 API 直接实现业务规则。
+- 前端负责表现、交互和临时 UI 状态；正式业务状态与规则以后端投影和后端 API 为准。
- 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、`server-rs/crates/api-server/src/app.rs`、`shared-contracts` 和 `packages/shared` 为准；不得在前端、`api-server` 或临时兼容层中重新发明旧接口。
+- 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、`server-rs/crates/api-server/src/app.rs`、`shared-contracts` 和 `packages/shared` 为准。
 - 凡修改 `/api/external/v1` 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义，必须在同一次变更中同步更新权威契约 [`docs/openapi/genarrative-external-v1.openapi.json`](docs/openapi/genarrative-external-v1.openapi.json) 及对应契约测试；Rust 实现与 OpenAPI 未保持一致时任务不得视为完成。
 - SpacetimeDB 已有表新增字段时，字段必须放在 Rust 表结构体最后，并设置明确默认值；需要删除、改名、重排或改类型时，必须先询问用户并确认迁移计划。
 - 修改 SpacetimeDB schema 后必须同步 `migration.rs`、表目录和生成绑定，并运行 `npm run check:spacetime-schema`。
@@ -172,6 +172,20 @@ _Avoid_: 多步骤向导、完整规则编辑器、拖拽编辑器
 Bark Battle 平台作品闭环按契约与领域规则、后端存储/API、最小前端纵切、投影体验、收口验证的顺序推进。
 _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 ## 项目开发对话（DirectProject）
 **项目对话历史**:
 AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
 _Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
 **运行态事件**:
 Thread Manager 向订阅者推送的当前回合原始事件流，只服务运行期间与短期断线恢复，不替代项目对话历史。
 _Avoid_: 进度通知、快照轮询、第二套历史
 **聊天投影**:
 把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
 _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 ## Relationships
 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -206,3 +220,5 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 - “入口闭环”曾可能只指内部 demo 或单个详情 CTA；已解析为 **正式作品入口闭环**，不新增独立专区或活动页。
 - “创作编辑”曾可能指多步骤向导或完整编辑器；已解析为 **轻配置编辑流程**，使用单页表单 + 预览卡片完成保存草稿、发布和发布后跳转作品详情。
 - “实施顺序”曾可能按 UI 或功能并行发散；已解析为契约/领域规则先行，再做后端存储/API，随后打通最小前端纵切，最后补投影体验与收口验证。
 - “回合进度事件”曾同时指 Direct turn update 与 Thread Manager 运行态事件；已解析为 AGC 项目开发对话只保留 **运行态事件**。
 - “哪些消息可显示”曾可能由后端历史分页判断；已解析为可见性判断属于 **聊天投影**，后端只按原始条目分页，前端负责跳过不可显示条目并推进分页锚点。
@@ -5,9 +5,12 @@ import {
  executeAdminRechargeRefund,
  getAdminFeatureGateConfig,
  getAdminUserDetail,
  listAdminGameDistributionReviews,
  listAdminRechargeOrders,
  reconcileAdminUserConsumption,
  resolveAdminRechargeRefundManualReview,
  reviewAdminGameDistributionVersion,
  suspendAdminGameDistributionGame,
  updateAdminAccount,
  uploadAdminEditorShowcaseCampaignImage,
  upsertAdminFeatureGateConfig,
@@ -364,3 +367,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);
 });
@@ -29,9 +29,14 @@ import type {
  AdminExternalApiKeyListQuery,
  AdminExternalApiKeyListResponse,
  AdminFeatureGateConfigResponse,
  AdminGameDistributionReviewListResponse,
  AdminGameDistributionReviewRequest,
  AdminGameDistributionReviewResponse,
  AdminLoginResponse,
  AdminMeResponse,
  AdminOverviewResponse,
  AdminProjectSnapshotListQuery,
  AdminProjectSnapshotListResponse,
  AdminRechargeOrderListQuery,
  AdminRechargeOrderListResponse,
  AdminRechargeRefundActionResponse,
@@ -198,6 +203,92 @@ export function listAdminAccounts(token: string) {
  return request<AdminAccountListResponse>('/admin/api/accounts', { token });
 }
 export function listAdminProjectSnapshots(
  token: string,
  query: AdminProjectSnapshotListQuery = {},
  signal?: AbortSignal,
 ) {
  const params = new URLSearchParams();
  if (query.cursor) params.set('cursor', query.cursor);
  params.set('limit', String(query.limit ?? 20));
  return request<AdminProjectSnapshotListResponse>(
    `/admin/api/project-snapshots?${params.toString()}`,
    { token, signal },
  );
 }
 export async function downloadAdminProjectSnapshot(
  token: string,
  userId: string,
  projectId: string,
  signal?: AbortSignal,
 ) {
  const path = `/admin/api/project-snapshots/${encodeURIComponent(userId)}/${encodeURIComponent(projectId)}/download`;
  const response = await fetch(buildRequestUrl(path), {
    headers: {
      Authorization: `Bearer ${token.trim()}`,
      Accept: 'application/zip',
      [API_RESPONSE_ENVELOPE_HEADER]: 'v1',
    },
    signal,
  });
  if (!response.ok) {
    const responseText = await response.text();
    throw buildAdminApiError(
      response,
      parseJsonResponse(responseText),
      responseText,
    );
  }
  const contentType = response.headers
    .get('content-type')
    ?.split(';')[0]
    ?.trim()
    .toLowerCase();
  if (contentType !== 'application/zip') {
    await response.body?.cancel();
    throw new AdminApiError({
      message: '下载失败：服务端未返回 ZIP 工程文件',
      status: response.status,
      code: 'INVALID_PROJECT_ARCHIVE_RESPONSE',
    });
  }
  return {
    blob: await response.blob(),
    filename: projectArchiveFilename(
      response.headers.get('content-disposition'),
    ),
  };
 }
 function projectArchiveFilename(contentDisposition: string | null): string {
  const extended = contentDisposition?.match(
    /(?:^|;)\s*filename\*=UTF-8'[^']*'([^;]+)/i,
  );
  const ordinary = contentDisposition?.match(
    /(?:^|;)\s*filename=(?:"((?:[^"\\]|\\.)*)"|([^;]+))/i,
  );
  let filename =
    ordinary?.[1]?.replace(/\\(.)/g, '$1') ?? ordinary?.[2]?.trim() ?? '';
  if (extended?.[1]) {
    try {
      filename = decodeURIComponent(extended[1].trim());
    } catch {
      // 非法扩展编码继续使用普通文件名。
    }
  }
  const safeName = Array.from(filename, (character) => {
    const code = character.charCodeAt(0);
    return code < 32 || code === 127 ? '_' : character;
  })
    .join('')
    .replace(/[<>:"/\\|?*]/g, '_')
    .trim()
    .replace(/[. ]+$/, '');
  if (!safeName || safeName.length > 240) return 'project.zip';
  return /\.zip$/i.test(safeName) ? safeName : `${safeName}.zip`;
 }
 export function createAdminAccount(
  token: string,
  payload: AdminCreateAccountRequest,
@@ -1088,3 +1179,72 @@ export function saveAgcModelCatalog(
    { token, method: 'PUT', body },
  );
 }
 export function listAdminGameDistributionReviews(token: string, limit = 48) {
  const normalizedLimit = Number.isFinite(limit)
    ? Math.min(Math.max(Math.trunc(limit), 1), 48)
    : 48;
  return request<AdminGameDistributionReviewListResponse>(
    `/admin/api/game-distribution/reviews?limit=${normalizedLimit}`,
    { token },
  );
 }
 /**
 * 审核游戏发行版本。幂等键由调用方生成并在同一次提交内复用，避免重复点击产生
 * 两条审核结论。
 */
 /**
 * 安全下架整个游戏。管理员下架同样要求 CAS 修订号与幂等键，避免并发审核互相覆盖。
 */
 export function suspendAdminGameDistributionGame(
  token: string,
  gameId: string,
  idempotencyKey: string,
  payload: import('./adminApiTypes').AdminGameDistributionSuspendRequest,
 ) {
  const normalizedGameId = gameId.trim();
  const normalizedKey = idempotencyKey.trim();
  if (!normalizedGameId) {
    throw new Error('缺少游戏 ID');
  }
  if (!normalizedKey || normalizedKey.length > 128) {
    throw new Error('下架幂等键必须是 1 到 128 个字符');
  }
  return request<
    import('./adminApiTypes').AdminGameDistributionSuspendResponse
  >(
    `/admin/api/game-distribution/games/${encodeURIComponent(normalizedGameId)}/suspend`,
    {
      method: 'POST',
      token,
      headers: { 'Idempotency-Key': normalizedKey },
      body: payload,
    },
  );
 }
 export function reviewAdminGameDistributionVersion(
  token: string,
  versionId: string,
  idempotencyKey: string,
  payload: AdminGameDistributionReviewRequest,
 ) {
  const normalizedVersionId = versionId.trim();
  const normalizedKey = idempotencyKey.trim();
  if (!normalizedVersionId) {
    throw new Error('缺少发行版本 ID');
  }
  if (!normalizedKey || normalizedKey.length > 128) {
    throw new Error('审核幂等键必须是 1 到 128 个字符');
  }
  return request<AdminGameDistributionReviewResponse>(
    `/admin/api/game-distribution/versions/${encodeURIComponent(normalizedVersionId)}/review`,
    {
      method: 'POST',
      token,
      headers: { 'Idempotency-Key': normalizedKey },
      body: payload,
    },
  );
 }
@@ -96,6 +96,27 @@ export interface AdminMeResponse {
  admin: AdminSessionPayload;
 }
 export interface AdminProjectSnapshotEntry {
  userId: string;
  projectId: string;
  projectName: string | null;
  syncRevision: number;
  syncedAtMs: number;
  fileCount: number;
  totalBytes: number;
  status: 'ready' | 'partial' | 'unverified';
 }
 export interface AdminProjectSnapshotListQuery {
  cursor?: string | null;
  limit?: number;
 }
 export interface AdminProjectSnapshotListResponse {
  items: AdminProjectSnapshotEntry[];
  nextCursor: string | null;
 }
 export interface AdminErrorReportEntry {
  batchId: string;
  eventCount: number;
@@ -1010,3 +1031,48 @@ export interface AdminAgcModelCatalog {
  defaultModelId: string;
  models: AdminAgcModel[];
 }
 export interface AdminGameDistributionReviewEntry {
  versionId: string;
  gameId: string;
  versionNumber: number;
  packageSha256: string;
  packageBytes: number;
  status: string;
  publicationRevision: number;
  reviewReason: string | null;
  createdAt: string;
  updatedAt: string;
 }
 export interface AdminGameDistributionReviewListResponse {
  entries: AdminGameDistributionReviewEntry[];
  nextCursor: string | null;
 }
 export interface AdminGameDistributionReviewRequest {
  decision: 'approve' | 'reject';
  expectedPublicationRevision: number;
  reviewReason?: string;
  entryUrl?: string;
 }
 export interface AdminGameDistributionReviewResponse {
  version: AdminGameDistributionReviewEntry;
  replayed: boolean;
 }
 export interface AdminGameDistributionSuspendRequest {
  expectedPublicationRevision: number;
  reason?: string;
 }
 export interface AdminGameDistributionSuspendResponse {
  game: {
    id: string;
    title: string;
    status: string;
    publicationRevision: number;
  };
  replayed: boolean;
 }
@@ -0,0 +1,128 @@
 import { afterEach, expect, test, vi } from 'vitest';
 import {
  downloadAdminProjectSnapshot,
  listAdminProjectSnapshots,
 } from './adminApiClient';
 afterEach(() => {
  vi.unstubAllGlobals();
 });
 test('项目列表携带分页与后台授权，解析标准响应', async () => {
  const payload = { items: [], nextCursor: 'next' };
  const fetchMock = vi
    .fn()
    .mockResolvedValue(
      new Response(JSON.stringify({ ok: true, data: payload })),
    );
  vi.stubGlobal('fetch', fetchMock);
  const controller = new AbortController();
  expect(
    await listAdminProjectSnapshots(
      'admin-token',
      { cursor: 'user/a+项目', limit: 20 },
      controller.signal,
    ),
  ).toEqual(payload);
  expect(fetchMock).toHaveBeenCalledWith(
    '/admin/api/project-snapshots?cursor=user%2Fa%2B%E9%A1%B9%E7%9B%AE&limit=20',
    expect.objectContaining({
      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
      signal: controller.signal,
    }),
  );
 });
 test('ZIP 下载以授权请求读取并优先保留中文附件名', async () => {
  const fetchMock = vi.fn().mockResolvedValue(
    new Response('PK\u0003\u0004', {
      headers: {
        'content-type': 'application/zip',
        'content-disposition':
          "attachment; filename=project.zip; filename*=UTF-8''%E4%B8%89%E6%B6%88-r2.zip",
      },
    }),
  );
  vi.stubGlobal('fetch', fetchMock);
  const controller = new AbortController();
  const archive = await downloadAdminProjectSnapshot(
    'admin-token',
    'user/a',
    'project/b',
    controller.signal,
  );
  expect(archive.filename).toBe('三消-r2.zip');
  expect(archive.blob.type).toBe('application/zip');
  expect(fetchMock).toHaveBeenCalledWith(
    '/admin/api/project-snapshots/user%2Fa/project%2Fb/download',
    expect.objectContaining({
      headers: expect.objectContaining({
        Authorization: 'Bearer admin-token',
        Accept: 'application/zip',
      }),
      signal: controller.signal,
    }),
  );
 });
 test.each([
  ['attachment; filename="工程.zip"; filename*=UTF-8\'\'%broken', '工程.zip'],
  ['attachment; filename="../secret.zip"', '.._secret.zip'],
  ["attachment; filename*=UTF-8''unsafe%00%1F%7F.zip", 'unsafe___.zip'],
  [null, 'project.zip'],
 ])('ZIP 附件名兼容安全回退 %s', async (header, expected) => {
  const headers: Record<string, string> = { 'content-type': 'application/zip' };
  // Response 的 Headers 只接受 Latin-1；真实 UTF-8 文件名使用 filename*。
  if (header)
    headers['content-disposition'] = header.replace('工程', 'project');
  vi.stubGlobal(
    'fetch',
    vi.fn().mockResolvedValue(new Response('PK', { headers })),
  );
  expect(
    (await downloadAdminProjectSnapshot('token', 'user', 'project')).filename,
  ).toBe(expected.replace('工程', 'project'));
 });
 test.each([401, 403, 409, 500])(
  '下载 HTTP %s 保留后台错误，不返回 ZIP',
  async (status) => {
    vi.stubGlobal(
      'fetch',
      vi.fn().mockResolvedValue(
        new Response(
          JSON.stringify({
            ok: false,
            error: { code: 'SNAPSHOT_FAILURE', message: '工程尚未同步完成' },
          }),
          {
            status,
            headers: { 'content-type': 'application/json' },
          },
        ),
      ),
    );
    await expect(
      downloadAdminProjectSnapshot('token', 'user', 'project'),
    ).rejects.toMatchObject({
      status,
      code: 'SNAPSHOT_FAILURE',
      message: '工程尚未同步完成',
    });
  },
 );
 test('200 JSON 或 HTML 不能被保存为成功 ZIP', async () => {
  vi.stubGlobal(
    'fetch',
    vi.fn().mockResolvedValue(
      new Response('{"ok":false}', {
        headers: { 'content-type': 'application/json' },
      }),
    ),
  );
  await expect(
    downloadAdminProjectSnapshot('token', 'user', 'project'),
  ).rejects.toMatchObject({ code: 'INVALID_PROJECT_ARCHIVE_RESPONSE' });
 });
@@ -26,11 +26,13 @@ import { AdminEditorAssetQueryPage } from '../pages/AdminEditorAssetQueryPage';
 import { AdminEditorGenerationPricingPage } from '../pages/AdminEditorGenerationPricingPage';
 import { AdminEditorShowcaseReviewPage } from '../pages/AdminEditorShowcaseReviewPage';
 import { AdminErrorReportsPage } from '../pages/AdminErrorReportsPage';
 import { AdminGameDistributionReviewPage } from '../pages/AdminGameDistributionReviewPage';
 import { AdminGrayReleaseConfigPage } from '../pages/AdminGrayReleaseConfigPage';
 import { AdminInviteCodePage } from '../pages/AdminInviteCodePage';
 import { AdminLoginPage } from '../pages/AdminLoginPage';
 import { AdminOverviewPage } from '../pages/AdminOverviewPage';
 import { AdminProfileWalletConfigPage } from '../pages/AdminProfileWalletConfigPage';
 import { AdminProjectSnapshotsPage } from '../pages/AdminProjectSnapshotsPage';
 import { AdminRechargeOrderPage } from '../pages/AdminRechargeOrderPage';
 import { AdminRechargeProductPage } from '../pages/AdminRechargeProductPage';
 import { AdminRedeemCodePage } from '../pages/AdminRedeemCodePage';
@@ -299,6 +301,12 @@ export function AdminApp() {
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
      {activeRouteId === 'game-distribution' ? (
        <AdminGameDistributionReviewPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
      {activeRouteId === 'editor-assets' ? (
        <AdminEditorAssetQueryPage
          token={token}
@@ -308,6 +316,12 @@ export function AdminApp() {
      {activeRouteId === 'accounts' ? (
        <AdminAccountsPage token={token} onUnauthorized={handleUnauthorized} />
      ) : null}
      {activeRouteId === 'project-snapshots' ? (
        <AdminProjectSnapshotsPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
    </AdminShell>
  );
 }
@@ -4,6 +4,8 @@ import {
  Bug,
  Coins,
  Database,
  FolderArchive,
  Gamepad2,
  GitBranch,
  Images,
  LayoutDashboard,
@@ -48,7 +50,9 @@ const routeIcons = {
  'recharge-orders': ReceiptText,
  'editor-generation-pricing': Coins,
  'editor-showcase': Star,
  'game-distribution': Gamepad2,
  'editor-assets': Images,
  'project-snapshots': FolderArchive,
  accounts: Users,
  'agc-models': ListChecks,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;
@@ -122,3 +122,49 @@ test('零权限 member 不回落到 Dashboard', () => {
  expect(routes).toEqual([]);
  expect(resolveAccessibleAdminRoute('#dashboard', routes)).toBeNull();
 });
 test('项目工程入口对 owner 与已授权 member 开放且可分配权限', () => {
  const route = {
    id: 'project-snapshots',
    label: '项目工程',
    hash: '#project-snapshots',
  };
  expect(adminRoutes.filter((item) => !item.ownerOnly)).toContainEqual(route);
  expect(resolveAdminRoute('#project-snapshots')).toBe('project-snapshots');
  expect(
    getAccessibleAdminRoutes({ accountRole: 'owner', tabPermissions: [] }),
  ).toContainEqual(route);
  expect(
    getAccessibleAdminRoutes({
      accountRole: 'member',
      tabPermissions: ['project-snapshots'],
    }),
  ).toEqual([route]);
  expect(
    getAccessibleAdminRoutes({
      accountRole: 'member',
      tabPermissions: ['tracking'],
    }),
  ).not.toContainEqual(route);
 });
 test('后台游戏审核路由可通过导航和 hash 访问', () => {
  expect(adminRoutes).toContainEqual({
    id: 'game-distribution',
    label: '游戏审核',
    hash: '#game-distribution',
  });
  expect(resolveAdminRoute('#game-distribution')).toBe('game-distribution');
  expect(routeHash('game-distribution')).toBe('#game-distribution');
 });
 test('member 可单独获得游戏审核 Tab 权限', () => {
  const routes = getAccessibleAdminRoutes({
    accountRole: 'member',
    tabPermissions: ['game-distribution'],
  });
  expect(routes.map((route) => route.id)).toEqual(['game-distribution']);
  expect(resolveAccessibleAdminRoute('#game-distribution', routes)).toBe(
    'game-distribution',
  );
 });
@@ -15,7 +15,9 @@ export type AdminRouteId =
  | 'recharge-orders'
  | 'editor-generation-pricing'
  | 'editor-showcase'
  | 'game-distribution'
  | 'editor-assets'
  | 'project-snapshots'
  | 'agc-models'
  | 'accounts';
@@ -53,7 +55,9 @@ export const adminRoutes: AdminRouteDefinition[] = [
  },
  { id: 'agc-models', label: 'AGC 模型', hash: '#agc-models', ownerOnly: true },
  { id: 'editor-showcase', label: '精选审核', hash: '#editor-showcase' },
  { id: 'game-distribution', label: '游戏审核', hash: '#game-distribution' },
  { id: 'editor-assets', label: '素材查询', hash: '#editor-assets' },
  { id: 'project-snapshots', label: '项目工程', hash: '#project-snapshots' },
  { id: 'accounts', label: '账号管理', hash: '#accounts', ownerOnly: true },
 ];
@@ -38,6 +38,7 @@ vi.mock('../api/adminApiClient', () => ({
 interface MockIntersectionObserverController {
  enter: (target: Element) => void;
  enterAll: (targets: Element[]) => void;
  isObserved: (target: Element) => boolean;
 }
@@ -106,6 +107,25 @@ function installIntersectionObserverMock(): MockIntersectionObserverController {
        );
      });
    },
    enterAll(targets) {
      act(() => {
        for (const target of targets) {
          const record = observed.get(target);
          if (!record) {
            throw new Error('目标缩略图尚未进入 IntersectionObserver');
          }
          record.callback(
            [
              {
                isIntersecting: true,
                target,
              } as IntersectionObserverEntry,
            ],
            record.observer,
          );
        }
      });
    },
    isObserved(target) {
      return observed.has(target);
    },
@@ -753,10 +773,10 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
  const thumbnails = entries.map((entry) =>
    thumbnailElementForLabel(entry.label),
  );
-  thumbnails.forEach((thumbnail) => {
+  for (const thumbnail of thumbnails) {
    expect(observer.isObserved(thumbnail)).toBe(true);
-    observer.enter(thumbnail);
+  }
-  });
+  observer.enterAll(thumbnails);
  await act(async () => {
    await Promise.resolve();
  });
@@ -776,7 +796,7 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
    await vi.advanceTimersByTimeAsync(200);
  });
  expect(getAdminAssetReadUrl).toHaveBeenCalledTimes(105);
-});
+}, 10_000);
 test('后台素材查询读取更多后为新进入可视区域的素材换签', async () => {
  const observer = installIntersectionObserverMock();
@@ -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();
 });
@@ -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>
  );
 }
@@ -154,6 +154,27 @@ test('灰度发布页可通过功能入口生成画布 Agent Gate Key', async ()
  );
 });
 test('灰度发布页可选择模板库并默认启用零比例灰度', async () => {
  const user = userEvent.setup();
  render(
    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
  );
  await screen.findByRole('button', { name: 'editor.new-toolbar' });
  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), ['agc']);
  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
    'agc:template-library',
  );
  expect(
    (screen.getByLabelText('Gate Key 目标') as HTMLSelectElement).value,
  ).toBe('template-library');
  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
    true,
  );
  expect((screen.getByLabelText('灰度比例') as HTMLInputElement).value).toBe(
    '0',
  );
 });
 test('灰度发布页保存时转换数组和百分比', async () => {
  const user = userEvent.setup();
  vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValueOnce({
@@ -27,9 +27,17 @@ interface GateTargetOption {
 const GATE_PREFIX_LABELS: Record<string, string> = {
  'image-editor': '画布',
  agc: '客户端',
 };
 const FIXED_GATE_TARGETS: GateTargetOption[] = [
  {
    prefix: 'agc',
    suffix: 'template-library',
    key: 'agc:template-library',
    label: '模板库',
    description: '客户端模板库灰度',
  },
  {
    prefix: 'image-editor',
    suffix: 'agent-sidebar',
@@ -180,7 +188,7 @@ export function AdminGrayReleaseConfigPage({
    setSelectedGateKey('');
    setGatePrefix(option.prefix);
    setGateKey(option.key);
-    setEnabled(false);
+    setEnabled(option.key === 'agc:template-library');
    setRolloutPercent('0');
    setAllowUserIds('');
    setAllowUserTags('');
--- a/Show More
+++ b/Show More