预览激活回接「运行」入口，聊天 @ 清单打开选择器时按需重读

- App.tsx 新增 activateRunningPreview，运行入口先问 Rust 要活体预览（activate_local_game_preview），命中就只切客户端运行视图
- App.tsx 的 executeRunLocal 命中活体预览时经 DirectProject 聊天的 announce 播报「已切换到客户端运行视图」，不再重复调用 start_local_game_preview；stopped / 非本项目 / 权限位要求确认一律回落到重新启动
- check-config.mjs 从 native-only 白名单移除 activate_local_game_preview 并同步注释（该门禁要求 App invoke 与白名单互斥）
- DirectProjectComposer 新增 onReferencePickerOpen，工具条按钮与附件菜单两处选择器入口打开前先刷新清单
- DirectProjectChatView 用 useDirectProjectManifest 的 refresh 重读聊天自己那份 @ 清单，不新增壳到聊天的清单推送通道
- 新增 tests/previewActivation.test.tsx，钉住切视图不重启 / stopped 回落重启 / 权限确认回落重启三条路径
- decision-log 记录本轮两处回归的背景、决策、取舍与验证方式

.codex/skills/genarrative-external-editor-api/SKILL.md

@@ -32,6 +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 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.
 

.codex/skills/genarrative-external-editor-api/references/api-operations.md

@@ -52,7 +52,7 @@ Every generation row requires a stable `Idempotency-Key` header and returns HTTP
 | Image generation    | `/api/external/v1/editor/images/generations`                  | `prompt`                                                                                                                                        | `kind`, `style`, `model`, `aspectRatio`, `imageSize`, `size`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
 | Image edit/redraw   | `/api/external/v1/editor/images/edits`                        | `prompt`, `sourceReferenceId`                                                                                                                   | `referenceImageSrcs`, `model`, `size`, `projectId`, `assetFolderId`, `assetLabel`, `targetLayerId`, `canvasCompletion`                                                 |
 | Background removal  | `/api/external/v1/editor/images/background-removals`          | `sourceImageSrc`                                                                                                                                | `projectId`, `sourceResourceId`, `targetLayerId`, static-image `assetKind`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs`                      |
-| Icon spritesheet    | `/api/external/v1/editor/icon-spritesheets/generations`       | `referenceId`, `iconDescriptions`                                                                                                               | `sliceLayout`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`       |
+| Icon spritesheet    | `/api/external/v1/editor/icon-spritesheets/generations`       | `referenceId`, `iconDescriptions`                                                                                                               | `sliceMode`, `gridX`, `gridY`, `sliceCount`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`       |
 | UI asset extraction | `/api/external/v1/editor/ui-designs/assets/extractions`       | `sourceImageSrc`, `aspectRatio`, `imageSize`                                                                                                    | `screenColor`, `model`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `spritesheetLabel`, `canvasCompletion`                                                     |
 | Character animation | `/api/external/v1/editor/character-animations/generations`    | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `assetFolderId`, `assetLabel`, `canvasCompletion`                                                                                     |
 | Video generation    | `/api/external/v1/editor/videos/generations`                  | `prompt`, `model`, `aspectRatio`, `durationSeconds`, `resolution`, `mode`, `sound`                                                              | `referenceImageSrcs`, `referenceVideoSrcs`, `referenceAudioSrcs`, `webSearchEnabled`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`                   |
@@ -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.
 
-`sliceLayout: "grid-2x2"` is an opt-in contract for four fixed game-runtime assets. The provider prompt and server persistence both preserve the ordered slots left-top, right-top, left-bottom, right-bottom. Omit it to retain the default connected-component slicing behaviour for ordinary free-form icon sheets.
+`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
 

.codex/skills/genarrative-external-editor-api/references/capability-routing.md

@@ -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 the four-category game contract it must also send `sliceLayout: "grid-2x2"`; this is an explicit fixed-slot contract, not a client-side guessed crop.
+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. For the four-category game-chat contract, require response `sliceLayout: "grid-2x2"` 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.
 

.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py

@@ -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,6 +895,7 @@ def _self_test() -> None:
     client.generate_icon_spritesheet(
         "editor-resource-spec",
         ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"],
+        "connected-components",
         canvasSession=session,
         assetLabel="贪吃蛇透明图集",
         referenceId="must-not-override-explicit-reference",
@@ -887,6 +904,7 @@ def _self_test() -> None:
     assert calls[0]["path"] == "/api/external/v1/editor/icon-spritesheets/generations"
     assert calls[0]["body"]["referenceId"] == "editor-resource-spec"
     assert calls[0]["body"]["screenColor"] == "auto"
+    assert calls[0]["body"]["sliceMode"] == "connected-components"
     assert calls[0]["body"]["iconDescriptions"][0] == "蛇头向上"
     assert calls[1]["path"] == "/api/external/v1/generations/task-operation-demo"
     print("self-test ok")

.encoding-check-ignore

@@ -4,3 +4,5 @@
 src/components/AdventurePanel.tsx
 src/data/customWorldCharacterLoadout.ts
 dist_check_monster_position/**
+# 固定上游UTF-8测试刻意包含U+FFFD；upstream-integrity.test.mjs逐字节验证来源hash。
+apps/ai-game-creator-shell/src-tauri/vendor/codex-utils-path-uri/src/api_path_string_tests.rs

.env.example

@@ -1,8 +1,8 @@
 # Server-side OpenAI-compatible LLM endpoint base URL.
-LLM_BASE_URL="https://api.vectorengine.cn/v1"
+LLM_BASE_URL="https://api.tiantoken.com/v1"
 
 # Server-side API key used by the local Vite proxy.
-# Recommended: set `LLM_API_KEY` locally, or use `VECTOR_ENGINE_API_KEY`
+# Recommended: set `LLM_API_KEY` locally, or use `TIANTOKEN_API_KEY`
 # through the Rust api-server proxy.
 # Legacy compatibility: `VITE_LLM_API_KEY` is still supported by the proxy,
 # but it should not be relied on by browser code.
@@ -122,7 +122,7 @@ WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=""
 # Model name for chat completions.
 VITE_LLM_MODEL="gpt-5.4-mini"
 GENARRATIVE_LLM_PROVIDER="openai-compatible"
-GENARRATIVE_LLM_BASE_URL="https://api.vectorengine.cn/v1"
+GENARRATIVE_LLM_BASE_URL="https://api.tiantoken.com/v1"
 GENARRATIVE_LLM_API_KEY=""
 GENARRATIVE_LLM_MODEL="gpt-5.4-mini"
 
@@ -130,10 +130,15 @@ GENARRATIVE_LLM_MODEL="gpt-5.4-mini"
 DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/api/v1"
 DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
 
-# VectorEngine LLM and GPT-image-2 / Gemini image generation config.
+# Tiantoken LLM and GPT-image-2 / Gemini image generation config.
+TIANTOKEN_BASE_URL="https://api.tiantoken.com"
+TIANTOKEN_API_KEY=""
+TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS="1000000"
+
+# VectorEngine is retained for Suno audio generation only.
 VECTOR_ENGINE_BASE_URL="https://api.vectorengine.cn"
 VECTOR_ENGINE_API_KEY=""
-VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS="1000000"
+VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS="180000"
 
 # ElevenLabs editor sound-effect generation is server-side only.
 ELEVENLABS_BASE_URL="https://api.elevenlabs.io"
@@ -153,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，不要再开第二个终端重复启动。
@@ -221,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.

.eslintrc.cjs

@@ -164,6 +164,7 @@ module.exports = {
     'server-rs/target-*',
     'apps/desktop-shell/src-tauri/target',
     'apps/ai-game-creator-shell/src/features/ui-editor/types/**',
+    'apps/ai-game-creator-shell/src/features/project-workspace/generated/**',
     'target',
     'src/main.tsx',
     'src/App.tsx',

.gitattributes

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

.gitea/workflows/project-ci.yml

@@ -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
 
@@ -27,28 +31,26 @@ env:
   RUSTC_WRAPPER: ''
   CARGO_BUILD_RUSTC_WRAPPER: ''
 
-# job 声明顺序就是 runner 领取顺序，因此把最长尾的客户端 Rust 门禁排在前面，
+# job 声明顺序就是 runner 领取顺序，因此把两条最长尾的客户端 Rust lane 排在前面，
 # 让它在最少的等待下占用并发槽位；其余 job 按时长递减排列。
 #
 # 客户端（微信壳 / Expo 移动壳 / Tauri 桌面壳 / AI 游戏创作壳）门禁原先全部串在
 # `Native shell tests` 一个 job 里，实测 18 分 37 秒。现在按门禁组拆成一个分组一个 job：
 # `Native shell tests`（契约 + H5 / 微信 / 移动 / 桌面壳门禁 + 发布构建 smoke）、
 # `AI game creator shell web tests`（typecheck + 壳内测试）、`AI game creator shell
-# Rust shard 1/4` 到 `4/4`（AGC 壳 bin 单测按名单分 4 片）、`AI game creator shell
+# Rust lane 1/2`、`lane 2/2`（每条 lane 顺序运行两片 AGC 壳 bin 单测）、`AI game creator
-# Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的
+# shell Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的
 # 共享 / 平台 crate 测试）。各自的命令与拆分前逐一对应，本地
 # `npm run check:native-shells` 仍是同一条串行序列。
 #
-# AGC 壳的 bin 单测（2466 条）按名单分 4 片、一片一个 job：片内保持 `--test-threads=1`
+# AGC 壳的 bin 单测（2466 条）仍按名单分 4 片、片内保持 `--test-threads=1`；两条 lane
-# （当年线程并行会互相干扰的是进程内后台锁与异步终态），片与片之间靠 job 级并发摊开。
+# 各自顺序运行两片，让一次 job 只做一次依赖预热，同时避免同一容器内多进程并行争抢
-# 不要改回「一个 job 里多进程并行这几片」：同一容器内它们会争抢共享 HOME、target 与固定
+# 共享 HOME、target 与固定临时路径。每个分片调用仍会自校验「片并集等于全集且互斥」。
-# 临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」。
 jobs:
-  # AGC 壳自身的 Rust bin 单测分片，4 片各自独立 job 并发执行、片内仍保持
+  # AGC 壳自身的 Rust bin 单测由两条 lane 承载，每条 lane 顺序运行两片；这里不装 npm
-  # `--test-threads=1`。这里不装 npm 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，
+  # 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，也只需要 AGC 壳自己那份锁定依赖。
-  # 也只需要 AGC 壳自己那份锁定依赖。
+  ai-game-creator-shell-rust-lane-1:
-  ai-game-creator-shell-rust-shard-1:
+    name: AI game creator shell Rust lane 1/2
-    name: AI game creator shell Rust shard 1/4
     runs-on: genarrative-ci
     steps:
       - name: Checkout full history from Gitea
@@ -83,41 +85,11 @@ jobs:
       - name: Run AI game creator shell Rust shard 1/4
         run: npm run check:native-shells:agc-rust-shard-1
 
-  ai-game-creator-shell-rust-shard-2:
-    name: AI game creator shell Rust shard 2/4
-    runs-on: genarrative-ci
-    steps:
-      - name: Checkout full history from Gitea
-        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
-          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
-        run: genarrative-gitea-checkout
-
-      - name: Validate preinstalled CI job image and sandbox
-        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
-
-      - name: Prepare AI game creator shell 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 apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
-              break
-            fi
-            if [[ "${attempt}" -eq 5 ]]; then
-              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
-              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
-
       - name: Run AI game creator shell Rust shard 2/4
         run: npm run check:native-shells:agc-rust-shard-2
 
-  ai-game-creator-shell-rust-shard-3:
+  ai-game-creator-shell-rust-lane-2:
-    name: AI game creator shell Rust shard 3/4
+    name: AI game creator shell Rust lane 2/2
     runs-on: genarrative-ci
     steps:
       - name: Checkout full history from Gitea
@@ -149,36 +121,6 @@ jobs:
       - name: Run AI game creator shell Rust shard 3/4
         run: npm run check:native-shells:agc-rust-shard-3
 
-  ai-game-creator-shell-rust-shard-4:
-    name: AI game creator shell Rust shard 4/4
-    runs-on: genarrative-ci
-    steps:
-      - name: Checkout full history from Gitea
-        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
-          GENARRATIVE_GITEA_TOKEN: ${{ github.token }}
-        run: genarrative-gitea-checkout
-
-      - name: Validate preinstalled CI job image and sandbox
-        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
-
-      - name: Prepare AI game creator shell 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 apps/ai-game-creator-shell/src-tauri/Cargo.toml; then
-              break
-            fi
-            if [[ "${attempt}" -eq 5 ]]; then
-              echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2
-              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
-
       - name: Run AI game creator shell Rust shard 4/4
         run: npm run check:native-shells:agc-rust-shard-4
 
@@ -217,8 +159,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 +200,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 +223,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
 

.gitignore

@@ -41,8 +41,22 @@ 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
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/darwin-arm64/
+/apps/ai-game-creator-shell/src-tauri/resources/codex/mac-native/darwin-x64/
 /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/src-tauri/resources/node-runtime/
+/apps/ai-game-creator-shell/src-tauri/resources/node-runtime-staging-*/
 /apps/ai-game-creator-shell/.llm-drafts/
 /apps/ai-game-creator-shell/game-creator.config.local.json
 /apps/mobile-shell/.expo/

.husky/pre-commit

@@ -1 +1,4 @@
+# Git 在链接工作树里执行 Hook 时会注入 GIT_DIR 等仓库定位变量，优先级高于 cwd；
+# 子进程（npm、lint-staged、测试夹具）会继承它们并写到真实仓库，故在入口统一清除。
+unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_PREFIX GIT_CONFIG_PARAMETERS GIT_CEILING_DIRECTORIES
 npm run format:staged

.husky/pre-push

@@ -1 +1,4 @@
+# Git 在链接工作树里执行 Hook 时会注入 GIT_DIR 等仓库定位变量，优先级高于 cwd；
+# 钩子链（npm → check:repository-ci → 测试夹具）会继承它们并写到真实仓库，故在入口统一清除。
+unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_PREFIX GIT_CONFIG_PARAMETERS GIT_CEILING_DIRECTORIES
 npm run check:pre-push-master -- "$@"

.prettierrc.json

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

AGENTS.md

@@ -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`。

CONTEXT.md

@@ -172,6 +172,28 @@ _Avoid_: 多步骤向导、完整规则编辑器、拖拽编辑器
 Bark Battle 平台作品闭环按契约与领域规则、后端存储/API、最小前端纵切、投影体验、收口验证的顺序推进。
 _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 
+## 项目开发对话（DirectProject）
+
+**DirectProject 专属聊天模块**:
+AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、发送队列、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。
+_Avoid_: 把 DirectProject 作为项目总控聊天的一个布尔分支、把四种 Agent 会话抽象成同一事实源
+
+**项目工作台布局**:
+承载本地项目的资源工作区、项目级工具和独立聊天产品路径的外层界面；布局拥有跨面板的账户/钱包入口，聊天模块只负责项目对话，不嵌套账户展示。
+_Avoid_: 把钱包入口塞进聊天设置、让聊天组件拥有工作台级账户状态
+
+**项目对话历史**:
+AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
+_Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
+
+**运行态事件**:
+Thread Manager 向订阅者推送的当前回合原始事件流，只服务运行期间与短期断线恢复，不替代项目对话历史。
+_Avoid_: 进度通知、快照轮询、第二套历史
+
+**聊天投影**:
+把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
+_Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
+
 ## Relationships
 
 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -206,3 +228,5 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
 - “入口闭环”曾可能只指内部 demo 或单个详情 CTA；已解析为 **正式作品入口闭环**，不新增独立专区或活动页。
 - “创作编辑”曾可能指多步骤向导或完整编辑器；已解析为 **轻配置编辑流程**，使用单页表单 + 预览卡片完成保存草稿、发布和发布后跳转作品详情。
 - “实施顺序”曾可能按 UI 或功能并行发散；已解析为契约/领域规则先行，再做后端存储/API，随后打通最小前端纵切，最后补投影体验与收口验证。
+- “回合进度事件”曾同时指 Direct turn update 与 Thread Manager 运行态事件；已解析为 AGC 项目开发对话只保留 **运行态事件**。
+- “哪些消息可显示”曾可能由后端历史分页判断；已解析为可见性判断属于 **聊天投影**，后端只按原始条目分页，前端负责跳过不可显示条目并推进分页锚点。

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

@@ -3,12 +3,15 @@ import { afterEach, expect, test, vi } from 'vitest';
 import {
   createAdminAccount,
   executeAdminRechargeRefund,
+  getAdminAgcTemplates,
   getAdminFeatureGateConfig,
   getAdminUserDetail,
+  importAdminAgcTemplates,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
   resolveAdminRechargeRefundManualReview,
   updateAdminAccount,
+  updateAdminAgcTemplate,
   uploadAdminEditorShowcaseCampaignImage,
   upsertAdminFeatureGateConfig,
   upsertProfileWalletConfig,
@@ -18,6 +21,93 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
+test('模板管理读取和更新复用认证封装，提交 revision 和封面但不提交 ZIP 或版本', async () => {
+  const library = { revision: 'revision-new', writable: true, templates: [] };
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: library }), {
+        status: 200,
+      }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  const controller = new AbortController();
+  expect(await getAdminAgcTemplates('admin-token', controller.signal)).toEqual(
+    library,
+  );
+  const update = {
+    expectedRevision: 'revision-old',
+    title: '空白模板',
+    summary: '简介',
+    tags: ['2D'],
+    enabled: true,
+    cover: { contentType: 'image/png', dataBase64: 'aW1hZ2U=' },
+  };
+  expect(
+    await updateAdminAgcTemplate('admin-token', 'template/1', update),
+  ).toEqual(library);
+  expect(fetchMock.mock.calls[0]).toEqual([
+    '/admin/api/agc-templates',
+    expect.objectContaining({
+      method: 'GET',
+      signal: controller.signal,
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+    }),
+  ]);
+  expect(fetchMock.mock.calls[1]).toEqual([
+    '/admin/api/agc-templates/template%2F1',
+    expect.objectContaining({
+      method: 'PUT',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        'Content-Type': 'application/json',
+      }),
+      body: JSON.stringify(update),
+    }),
+  ]);
+});
+
+test('模板批量导入走 multipart，不预设 JSON Content-Type', async () => {
+  const imported = {
+    revision: 'rev-2',
+    writable: true,
+    templates: [],
+    imported: [
+      {
+        id: 'alpha',
+        templateVersion: '0.1.0',
+        zipSizeBytes: 4,
+        zipSha256: 'a'.repeat(64),
+        reusedObjects: false,
+      },
+    ],
+  };
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: imported }), {
+        status: 200,
+      }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  const form = new FormData();
+  form.append(
+    'manifest',
+    JSON.stringify({ expectedRevision: 'rev-1', templates: [] }),
+  );
+  form.append(
+    'zip_0',
+    new File([new Uint8Array([1])], 'alpha.zip', { type: 'application/zip' }),
+  );
+
+  expect(await importAdminAgcTemplates('admin-token', form)).toEqual(imported);
+  const [url, init] = fetchMock.mock.calls[0]!;
+  expect(url).toBe('/admin/api/agc-templates/import');
+  expect(init.method).toBe('POST');
+  expect(init.body).toBe(form);
+  expect(init.headers).not.toHaveProperty('Content-Type');
+  expect(init.headers.Authorization).toBe('Bearer admin-token');
+});
+
 test('后台账号创建和更新同时携带 Tab 与独立操作权限', async () => {
   const fetchMock = vi.fn().mockImplementation(() =>
     Promise.resolve(

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

@@ -1,5 +1,6 @@
 import type {
   AdminAccountListResponse,
+  AdminAgcTemplateLibraryResponse,
   AdminConfirmEditorShowcaseCampaignImageUploadRequest,
   AdminCreateAccountRequest,
   AdminCreateAccountResponse,
@@ -29,9 +30,13 @@ import type {
   AdminExternalApiKeyListQuery,
   AdminExternalApiKeyListResponse,
   AdminFeatureGateConfigResponse,
+  AdminImportAgcTemplatesResponse,
   AdminLoginResponse,
   AdminMeResponse,
   AdminOverviewResponse,
+  AdminProjectSnapshotChannelsResponse,
+  AdminProjectSnapshotListQuery,
+  AdminProjectSnapshotListResponse,
   AdminRechargeOrderListQuery,
   AdminRechargeOrderListResponse,
   AdminRechargeRefundActionResponse,
@@ -45,6 +50,7 @@ import type {
   AdminTrackingEventListResponse,
   AdminUpdateAccountRequest,
   AdminUpdateAccountResponse,
+  AdminUpdateAgcTemplateRequest,
   AdminUploadedEditorShowcaseCampaignImage,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertFeatureGateConfigRequest,
@@ -83,6 +89,8 @@ interface AdminRequestOptions {
   method?: string;
   token?: string;
   body?: unknown;
+  /** multipart 表单：交给浏览器自己带 boundary，不能预设 Content-Type。 */
+  formData?: FormData;
   headers?: Record<string, string>;
   signal?: AbortSignal;
 }
@@ -170,6 +178,8 @@ export async function request<T>(
   if (typeof options.body !== 'undefined') {
     headers['Content-Type'] = 'application/json';
     init.body = JSON.stringify(options.body);
+  } else if (options.formData) {
+    init.body = options.formData;
   }
 
   const response = await fetch(buildRequestUrl(path), init);
@@ -198,6 +208,107 @@ 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);
+  if (query.channel) params.set('channel', query.channel);
+  params.set('limit', String(query.limit ?? 20));
+  return request<AdminProjectSnapshotListResponse>(
+    `/admin/api/project-snapshots?${params.toString()}`,
+    { token, signal },
+  );
+}
+
+export function getAdminProjectSnapshotChannels(
+  token: string,
+  signal?: AbortSignal,
+) {
+  return request<AdminProjectSnapshotChannelsResponse>(
+    '/admin/api/project-snapshots/channels',
+    { token, signal },
+  );
+}
+
+export async function downloadAdminProjectSnapshot(
+  token: string,
+  channel: string,
+  userId: string,
+  projectId: string,
+  signal?: AbortSignal,
+) {
+  const params = new URLSearchParams();
+  if (channel) params.set('channel', channel);
+  const query = params.toString();
+  const path = `/admin/api/project-snapshots/${encodeURIComponent(userId)}/${encodeURIComponent(projectId)}/download${query ? `?${query}` : ''}`;
+  const response = await fetch(buildRequestUrl(path), {
+    headers: {
+      Authorization: `Bearer ${token.trim()}`,
+      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 +1199,33 @@ export function saveAgcModelCatalog(
     { token, method: 'PUT', body },
   );
 }
+
+export function getAdminAgcTemplates(token: string, signal?: AbortSignal) {
+  return request<AdminAgcTemplateLibraryResponse>('/admin/api/agc-templates', {
+    token,
+    signal,
+  });
+}
+
+export function updateAdminAgcTemplate(
+  token: string,
+  id: string,
+  body: AdminUpdateAgcTemplateRequest,
+) {
+  return request<AdminAgcTemplateLibraryResponse>(
+    `/admin/api/agc-templates/${encodeURIComponent(id)}`,
+    { token, method: 'PUT', body },
+  );
+}
+
+/** 批量导入模板包：manifest 与 zip_N / cover_N 一起走 multipart，一批一次锁一次提交。 */
+export function importAdminAgcTemplates(token: string, formData: FormData) {
+  return request<AdminImportAgcTemplatesResponse>(
+    '/admin/api/agc-templates/import',
+    {
+      token,
+      method: 'POST',
+      formData,
+    },
+  );
+}

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

@@ -96,6 +96,36 @@ 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';
+  channel: string;
+  authorDisplayName?: string | null;
+  authorPublicUserCode?: string | null;
+}
+
+export interface AdminProjectSnapshotListQuery {
+  cursor?: string | null;
+  limit?: number;
+  channel?: string | null;
+}
+
+export interface AdminProjectSnapshotListResponse {
+  items: AdminProjectSnapshotEntry[];
+  nextCursor: string | null;
+}
+
+export interface AdminProjectSnapshotChannelsResponse {
+  defaultChannel: string;
+  channels: string[];
+}
+
 export interface AdminErrorReportEntry {
   batchId: string;
   eventCount: number;
@@ -123,6 +153,8 @@ export interface AdminErrorReportListResponse {
 }
 
 export interface AdminErrorReportDetail extends AdminErrorReportEntry {
+  firstFingerprint?: string;
+  firstSource?: string;
   note?: string;
   events: Array<Record<string, unknown>>;
   logNames: string[];
@@ -1010,3 +1042,67 @@ export interface AdminAgcModelCatalog {
   defaultModelId: string;
   models: AdminAgcModel[];
 }
+
+export interface AdminAgcTemplatePayload {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  enabled: boolean;
+  coverUrl: string;
+  zipSizeBytes: number;
+}
+
+export interface AdminAgcTemplateLibraryResponse {
+  revision: string;
+  writable: boolean;
+  templates: AdminAgcTemplatePayload[];
+}
+
+export interface AdminUpdateAgcTemplateRequest {
+  expectedRevision: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  enabled: boolean;
+  cover?: {
+    contentType: string;
+    dataBase64: string;
+  };
+}
+
+export interface AdminImportAgcTemplateItemPayload {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  entry: string;
+  zipField: string;
+  coverField: string;
+}
+
+export interface AdminImportAgcTemplatesManifest {
+  expectedRevision: string;
+  templates: AdminImportAgcTemplateItemPayload[];
+}
+
+export interface AdminImportAgcTemplateResult {
+  id: string;
+  templateVersion: string;
+  zipSizeBytes: number;
+  zipSha256: string;
+  reusedObjects: boolean;
+}
+
+export interface AdminImportAgcTemplatesResponse
+  extends AdminAgcTemplateLibraryResponse {
+  imported: AdminImportAgcTemplateResult[];
+}

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

@@ -0,0 +1,148 @@
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  downloadAdminProjectSnapshot,
+  getAdminProjectSnapshotChannels,
+  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, channel: 'release' },
+      controller.signal,
+    ),
+  ).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/project-snapshots?cursor=user%2Fa%2B%E9%A1%B9%E7%9B%AE&channel=release&limit=20',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+      signal: controller.signal,
+    }),
+  );
+});
+
+test('渠道列表按后台授权读取，解析本部署渠道', async () => {
+  const payload = { defaultChannel: 'release', channels: ['dev', 'release'] };
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue(
+      new Response(JSON.stringify({ ok: true, data: payload })),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+  expect(await getAdminProjectSnapshotChannels('admin-token')).toEqual(payload);
+  expect(fetchMock).toHaveBeenCalledWith(
+    '/admin/api/project-snapshots/channels',
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+    }),
+  );
+});
+
+test('ZIP 下载以授权请求读取并优先保留中文附件名', async () => {
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response('PK\u0003\u0004', {
+      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',
+    'release',
+    '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?channel=release',
+    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', 'release', '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', 'release', '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', 'release', 'user', 'project'),
+  ).rejects.toMatchObject({ code: 'INVALID_PROJECT_ARCHIVE_RESPONSE' });
+});

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

@@ -19,6 +19,7 @@ import {
 } from '../auth/adminAuthStore';
 import { AdminAccountsPage } from '../pages/AdminAccountsPage';
 import { AdminAgcModelsPage } from '../pages/AdminAgcModelsPage';
+import { AdminAgcTemplatesPage } from '../pages/AdminAgcTemplatesPage';
 import { AdminDashboardPage } from '../pages/AdminDashboardPage';
 import { AdminDatabaseTablesPage } from '../pages/AdminDatabaseTablesPage';
 import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
@@ -31,6 +32,7 @@ import { AdminInviteCodePage } from '../pages/AdminInviteCodePage';
 import { AdminLoginPage } from '../pages/AdminLoginPage';
 import { AdminOverviewPage } from '../pages/AdminOverviewPage';
 import { AdminProfileWalletConfigPage } from '../pages/AdminProfileWalletConfigPage';
+import { AdminProjectSnapshotsPage } from '../pages/AdminProjectSnapshotsPage';
 import { AdminRechargeOrderPage } from '../pages/AdminRechargeOrderPage';
 import { AdminRechargeProductPage } from '../pages/AdminRechargeProductPage';
 import { AdminRedeemCodePage } from '../pages/AdminRedeemCodePage';
@@ -293,6 +295,12 @@ export function AdminApp() {
       {activeRouteId === 'agc-models' ? (
         <AdminAgcModelsPage token={token} onUnauthorized={handleUnauthorized} />
       ) : null}
+      {activeRouteId === 'agc-templates' ? (
+        <AdminAgcTemplatesPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-showcase' ? (
         <AdminEditorShowcaseReviewPage
           token={token}
@@ -308,6 +316,12 @@ export function AdminApp() {
       {activeRouteId === 'accounts' ? (
         <AdminAccountsPage token={token} onUnauthorized={handleUnauthorized} />
       ) : null}
+      {activeRouteId === 'project-snapshots' ? (
+        <AdminProjectSnapshotsPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
     </AdminShell>
   );
 }

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

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

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

@@ -122,3 +122,55 @@ 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('模板管理只对 owner 或具有 agc-templates 权限的 member 可见', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'agc-templates',
+    label: '模板管理',
+    hash: '#agc-templates',
+  });
+  expect(resolveAdminRoute('#agc-templates')).toBe('agc-templates');
+  expect(routeHash('agc-templates')).toBe('#agc-templates');
+  expect(
+    getAccessibleAdminRoutes({ accountRole: 'owner', tabPermissions: [] }).some(
+      (route) => route.id === 'agc-templates',
+    ),
+  ).toBe(true);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['agc-templates'],
+    }).map((route) => route.id),
+  ).toEqual(['agc-templates']);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['editor-assets'],
+    }).some((route) => route.id === 'agc-templates'),
+  ).toBe(false);
+});

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

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

apps/admin-web/src/main.tsx

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