修复 bump-version 脚本导入排序以通过 lint:eslint

- bump-version.mjs 按 simple-import-sort 调整 node:child_process / node:path / node:url 导入顺序
细化 AGC 发布文档：区分 build 与 release:upload 的校验范围
2026-09-07 14:59:30 +08:00 · 2026-09-07 14:10:13 +08:00 · 2026-09-07 14:09:16 +08:00 · 2026-09-07 14:03:41 +08:00 · 2026-09-07 13:38:17 +08:00 · 2026-09-07 13:33:41 +08:00
1269 changed files with 81457 additions and 207416 deletions
@@ -5,7 +5,6 @@
 ## 目录约定

 - `.codex/skills/` 是项目专属 skill 根目录。每个 skill 以目录中的 `SKILL.md` 为入口，配套的参考资料和脚本放在同一目录下。
- `spec-driven-development` 负责跨模块、公开契约、SpacetimeDB、AGC/Runtime 和复杂 UI 任务的规范先行与逐里程碑验收；具体规则以 `docs/` 下的 SDD 工作流和模板为准。
 - `.codex/plugins/` 保存随仓库分发的项目插件资源及其参考资料。当前的 `game-studio` 插件提供浏览器游戏设计、原型、2D/3D 技术栈、素材管线和 playtest 工作流；是否启用遵循当前 Codex 的插件加载机制，不依赖旧工具的环境变量或个人配置脚本。
 - `.codex/hooks/`、`.codex/environments/` 等目录保存项目工具链所需的 hooks 和环境模板；它们不替代项目代码中的运行时配置。
 - 长期有效的产品、架构、接口、排障和协作知识统一放在 `docs/` 与 `docs/project-memory/`，不复制到本目录。
@@ -32,7 +32,6 @@ 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.

@@ -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`                                                                                                               | `sliceMode`, `gridX`, `gridY`, `sliceCount`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`       |
+| Icon spritesheet    | `/api/external/v1/editor/icon-spritesheets/generations`       | `referenceId`, `iconDescriptions`                                                                                                               | `sliceLayout`, `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.

-`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.
+`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.

 ## Common Values

@@ -102,7 +102,7 @@ Use OpenAPI as the final authority; these common values are a routing aid:

 - Image `kind`: `spec`, `character`, `quick-edit`, `ui-design`, `publication-material`; ordinary image generation may omit it.
 - External v1 currently has no structured game-scene generation operation. Do not send `kind: "scene"` or `assetKind: "scene"` through generic image generation; the server rejects both before queueing.
- Image `model`: `gpt-image-2.5`, `gemini-3.1-flash-image-preview`, `nanobanana2`, `nano-banana`. Persisted `gpt-image-2` / `gpt-image-2-c` are legacy values resolved only when submitting a new task.
+- Image `model`: `gpt-image-2`, `gemini-3.1-flash-image-preview`, `nanobanana2`, `nano-banana`.
 - Image `aspectRatio`: `1:1`, `2:3`, `3:2`, `9:16`, `16:9`.
 - Image `imageSize`: `0.5K`, `1K`, `2K`.
 - Video `model`: `seedance2.0`, `seedance2.0-fast`, `kling3.0`, `kling3.0-omni`, `veo3.1`, `veo3.1-fast`.
@@ -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`. `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`.
+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.

-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.
+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.

 Never use `assets/ui-prototype.png` as the spritesheet visual-spec reference. UI extraction is outside this canonical DAG.

@@ -617,7 +617,6 @@ class GenarrativeExternalClient:
        self,
        reference_id: str,
        icon_descriptions: list[str],
-        slice_mode: str,
        **fields: Any,
    ) -> Any:
        reference_id = normalize_optional_text(reference_id)
@@ -626,20 +625,6 @@ 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")
@@ -650,7 +635,6 @@ class GenarrativeExternalClient:
                **fields,
                "referenceId": reference_id,
                "iconDescriptions": descriptions,
-                "sliceMode": slice_mode,
            },
            idempotency_key=idempotency_key,
        )
@@ -895,7 +879,6 @@ def _self_test() -> None:
    client.generate_icon_spritesheet(
        "editor-resource-spec",
        ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"],
-        "connected-components",
        canvasSession=session,
        assetLabel="贪吃蛇透明图集",
        referenceId="must-not-override-explicit-reference",
@@ -904,7 +887,6 @@ 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")
@@ -1,11 +1,11 @@
 ---
 name: gpt-image-2-apimart
-description: Generate or inspect project image assets through this repository's image workflow using the GPT Image 2.5 business model. Use when Codex needs to create puzzle template sample images, reproduce the server-rs image request body, dry-run image prompts, batch-generate local project thumbnails, or debug VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY image-generation configuration without exposing secrets. The directory name is historical.
+description: Generate or inspect project image assets through this repository's VectorEngine gpt-image-2 workflow with gpt-image-2-c fallback. Use when Codex needs to create puzzle template sample images, reproduce the server-rs image request body, dry-run image prompts, batch-generate local project thumbnails, or debug VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY image-generation configuration without exposing secrets. The directory name is historical.
 ---

-# GPT Image 2.5 project image workflow
+# gpt-image-2 VectorEngine

-Use this skill for project-local image asset generation that must match the repository's image request contract. Use the business model identifier `gpt-image-2.5`; provider concrete model routing is owned by `server-rs`, and this client must not perform a cross-model fallback. The folder still contains `apimart` in its name for compatibility with existing local plugin references.
+Use this skill for project-local image asset generation that must match the repository's `server-rs` VectorEngine image path. Keep the product/price model identifier and primary provider request as `gpt-image-2`, then fall back once to `gpt-image-2-c` for eligible provider failures. The folder still contains `apimart` in its name for compatibility with existing local plugin references.

 ## Workflow

@@ -40,7 +40,7 @@ Default body:

 ```json
 {
-  "model": "gpt-image-2.5",
+  "model": "gpt-image-2",
  "prompt": "<prompt>",
  "n": 1,
  "size": "1024x1024"
@@ -58,14 +58,14 @@ Content-Type: multipart/form-data
 Multipart fields:

 ```text
-model=gpt-image-2.5
+model=gpt-image-2
 prompt=<prompt>
 n=1
 size=1024x1024
 image=@reference.png
 ```

-In this repository, calls with no reference images use `POST /v1/images/generations`; calls with any reference image use `POST /v1/images/edits` and pass references as one or more `image` form parts. Both paths send the business model `gpt-image-2.5`; provider routing and retry policy remain server-owned. Match3D container UI generation embeds `public/match3d-background-references/pot-fused-reference.png` into the edit request as an `image` part.
+In this repository, calls with no reference images use `POST /v1/images/generations`; calls with any reference image use `POST /v1/images/edits` and pass references as one or more `image` form parts. Both paths prefer `gpt-image-2`; on an eligible upstream/model failure they retry with `gpt-image-2-c`. Do not fall back for authentication, local validation, request-budget exhaustion, uncertain send/connection failure, content-safety rejection, or a generated image URL download failure. Match3D container UI generation embeds `public/match3d-background-references/pot-fused-reference.png` into the edit request as an `image` part.

 Accept image output from `data[].url`, `data[].b64_json`, or direct nested `url` fields. VectorEngine image generation currently returns synchronously; do not poll APIMart task endpoints.

@@ -9,7 +9,8 @@ const skillRoot = path.resolve(__dirname, '..');
 const repoRoot = path.resolve(skillRoot, '..', '..', '..');
 const defaultOutDir = path.join(repoRoot, 'public', 'anthro-cat-illustrations');
 const defaultTimeoutMs = 1000000;
-const preferredImageModel = 'gpt-image-2.5';
+const preferredImageModel = 'gpt-image-2';
+const fallbackImageModel = 'gpt-image-2-c';

 const prompts = [
  {
@@ -255,8 +256,41 @@ async function fetchJson(url, options, timeoutMs) {
  }
 }

+function shouldFallbackImageModel(error) {
+  const raw =
+    `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase();
+  if (error?.vectorEngineResponseParse) {
+    return !containsContentRejection(raw);
+  }
+  const status = Number(error?.vectorEngineStatus || 0);
+  if (status === 408 || status >= 500) {
+    return true;
+  }
+  if (status === 429) {
+    return !containsContentRejection(raw);
+  }
+  const mentionsImageModel =
+    raw.includes('model') ||
+    raw.includes('模型') ||
+    raw.includes(preferredImageModel) ||
+    raw.includes(fallbackImageModel);
+  return (
+    [400, 404, 422].includes(status) &&
+    mentionsImageModel &&
+    /(not found|not supported|unsupported|unavailable|does not exist|invalid model|unknown model|不存在|不支持|不可用|未开通)/u.test(
+      raw,
+    )
+  );
+}
+
+function containsContentRejection(raw) {
+  return /(invalid_prompt|safety|content[_ ]policy|moderation|prompt rejected|content rejected|prompt refusal|content refusal|rejected by safety|rejected by moderation|敏感|违规|安全策略|内容审核|提示词拒绝|内容拒绝)/u.test(
+    raw,
+  );
+}
+
 async function requestImagePayload(env, entry) {
-  for (const model of [preferredImageModel]) {
+  for (const model of [preferredImageModel, fallbackImageModel]) {
    const requestBody = {
      model,
      prompt: buildPrompt(entry),
@@ -288,7 +322,12 @@ async function requestImagePayload(env, entry) {
      error.vectorEngineBody = JSON.stringify(payload).slice(0, 600);
      throw error;
    } catch (error) {
-      throw error;
+      if (model !== preferredImageModel || !shouldFallbackImageModel(error)) {
+        throw error;
+      }
+      console.warn(
+        `VectorEngine ${preferredImageModel} failed, retrying with ${fallbackImageModel}: ${error.message}`,
+      );
    }
  }
  throw new Error(`VectorEngine returned no image for ${entry.id}`);
@@ -369,7 +408,7 @@ if (dryRun) {
        requests: selectedPrompts.map((entry) => ({
          id: entry.id,
          title: entry.title,
-          fallbackModel: null,
+          fallbackModel: fallbackImageModel,
          body: {
            model: preferredImageModel,
            prompt: buildPrompt(entry),
@@ -18,7 +18,8 @@ const defaultOutDir = path.join(
  'puzzle-creation-templates',
 );
 const defaultTimeoutMs = 1000000;
-const preferredImageModel = 'gpt-image-2.5';
+const preferredImageModel = 'gpt-image-2';
+const fallbackImageModel = 'gpt-image-2-c';

 const args = new Map();
 for (let index = 2; index < process.argv.length; index += 1) {
@@ -225,8 +226,41 @@ async function fetchJson(url, options, timeoutMs) {
  }
 }

+function shouldFallbackImageModel(error) {
+  const raw =
+    `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase();
+  if (error?.vectorEngineResponseParse) {
+    return !containsContentRejection(raw);
+  }
+  const status = Number(error?.vectorEngineStatus || 0);
+  if (status === 408 || status >= 500) {
+    return true;
+  }
+  if (status === 429) {
+    return !containsContentRejection(raw);
+  }
+  const mentionsImageModel =
+    raw.includes('model') ||
+    raw.includes('模型') ||
+    raw.includes(preferredImageModel) ||
+    raw.includes(fallbackImageModel);
+  return (
+    [400, 404, 422].includes(status) &&
+    mentionsImageModel &&
+    /(not found|not supported|unsupported|unavailable|does not exist|invalid model|unknown model|不存在|不支持|不可用|未开通)/u.test(
+      raw,
+    )
+  );
+}
+
+function containsContentRejection(raw) {
+  return /(invalid_prompt|safety|content[_ ]policy|moderation|prompt rejected|content rejected|prompt refusal|content refusal|rejected by safety|rejected by moderation|敏感|违规|安全策略|内容审核|提示词拒绝|内容拒绝)/u.test(
+    raw,
+  );
+}
+
 async function requestImagePayload(env, template) {
-  for (const model of [preferredImageModel]) {
+  for (const model of [preferredImageModel, fallbackImageModel]) {
    const requestBody = {
      model,
      prompt: buildPrompt(template),
@@ -260,7 +294,12 @@ async function requestImagePayload(env, template) {
      error.vectorEngineBody = JSON.stringify(payload).slice(0, 600);
      throw error;
    } catch (error) {
-      throw error;
+      if (model !== preferredImageModel || !shouldFallbackImageModel(error)) {
+        throw error;
+      }
+      console.warn(
+        `VectorEngine ${preferredImageModel} failed, retrying with ${fallbackImageModel}: ${error.message}`,
+      );
    }
  }
  throw new Error(`VectorEngine returned no image for ${template.id}`);
@@ -345,7 +384,7 @@ if (dryRun) {
        requests: selectedTemplates.map((template) => ({
          id: template.id,
          title: template.title,
-          fallbackModel: null,
+          fallbackModel: fallbackImageModel,
          body: {
            model: preferredImageModel,
            prompt: buildPrompt(template),
@@ -1,43 +0,0 @@
---
-name: spec-driven-development
-description: 在 Genarrative 中处理跨模块功能、公开 API/DTO、SpacetimeDB schema、AGC/Runtime 或复杂 UI 状态链路时，按主规范、里程碑规范、单里程碑实现计划和验收证据推进；小型局部修复不触发。
-license: MIT
-metadata:
-  codex:
-    tags: [SDD, 规范驱动开发, 主规范, 里程碑, 验收]
---
-
-# SDD 规范驱动开发
-
-本 skill 把 Genarrative 的复杂任务路由到规范先行、单里程碑交付的工作流。权威规则和模板分别见：
-
- `docs/【协作规范】规范驱动开发工作流-2026-09-12.md`
- `docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md`
-
-## 触发条件
-
-使用本 skill 的任务包括：
-
- 跨前端、`api-server`、`platform-*`、`spacetime-client`、`spacetime-module` 或 `module-*` 的功能。
- `/api/external/v1`、共享 DTO、OpenAPI、SpacetimeDB schema、迁移或跨版本重放合同变化。
- AGC / DirectProject、Agent Runtime、工具白名单、审批、持久化恢复或资源工作流变化。
- 复杂 UI 状态链路、入口/页面生命周期变化，或需要多个独立验收面的功能。
-
-文案、单文件局部修复、无行为变化重构和一次性诊断继续使用轻量流程；执行中一旦触及公开行为或跨模块合同，切换到本 skill。
-
-## 执行要求
-
-1. 检查工作树，读取当前专题、源码、测试、契约和历史决策；写清交付结果、验收判据和不做项。
-2. 找到或更新唯一主规范。主规范描述行为合同、边界、非目标、兼容/迁移和证据，不绑定实现细节。
-3. 在 `docs/project-memory/plans/` 创建一个或多个 `【里程碑】中文标题-YYYY-MM-DD.md`，填写 `Version`、`Status`、`Date`、`Parent Spec`、范围、依赖和验收标准；评审通过前不写业务代码。
-4. 每次只选择一个已评审里程碑，创建对应的 `【实施计划】中文标题-YYYY-MM-DD.md`，明确修改边界、顺序、验证命令、风险和回滚点。
-5. 发现行为需要变化时，严格按 `主规范 → 尚未实现的里程碑规范 → 当前实现计划 → 代码与测试` 更新。
-6. 完成一个里程碑后，提供主规范/里程碑逐条对照、自动化验证、必要运行时 smoke、边界验证和未验证项；未验收不得推进下一个里程碑。
-7. 全部验收通过后，将持久结论合并回主规范，删除已完成的临时计划，并检查文档、契约、测试和提交边界一致。
-
-## 约束
-
- 里程碑和实现计划是开发期协调文件，完成或取消后删除；阶段编号和临时名称不得进入产品代码、用户文档、测试名称或提交标题。
- 活动计划可以提交以便团队同步，但不得把一次性实现步骤写进长期规范。
- 继续遵守现有 API、SpacetimeDB、AGC、编码和中文文档约束；本 skill 不替代专题门禁。
- 文档任务至少运行 `npm run check:doc-index`、`npm run check:encoding` 和 `git diff --check`；代码任务再运行范围匹配的测试、类型检查、schema/OpenAPI 或运行时 smoke。
@@ -1,8 +1,8 @@
 # Server-side OpenAI-compatible LLM endpoint base URL.
-LLM_BASE_URL="https://api.tiantoken.com/v1"
+LLM_BASE_URL="https://api.vectorengine.cn/v1"

 # Server-side API key used by the local Vite proxy.
-# Recommended: set `LLM_API_KEY` locally, or use `TIANTOKEN_API_KEY`
+# Recommended: set `LLM_API_KEY` locally, or use `VECTOR_ENGINE_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.tiantoken.com/v1"
+GENARRATIVE_LLM_BASE_URL="https://api.vectorengine.cn/v1"
 GENARRATIVE_LLM_API_KEY=""
 GENARRATIVE_LLM_MODEL="gpt-5.4-mini"

@@ -130,15 +130,10 @@ GENARRATIVE_LLM_MODEL="gpt-5.4-mini"
 DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/api/v1"
 DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

-# 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.
+# VectorEngine LLM and GPT-image-2 / Gemini image generation config.
 VECTOR_ENGINE_BASE_URL="https://api.vectorengine.cn"
 VECTOR_ENGINE_API_KEY=""
-VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS="180000"
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS="1000000"

 # ElevenLabs editor sound-effect generation is server-side only.
 ELEVENLABS_BASE_URL="https://api.elevenlabs.io"
@@ -158,15 +153,6 @@ 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，不要再开第二个终端重复启动。
@@ -164,7 +164,6 @@ 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',
@@ -23,6 +23,3 @@
 *.meta text
 *.anim text
 *.controller text
-
-# Rust ts-rs 生成的共享契约：保留在仓库中供 TS 消费，但不作为手写源文件统计。
-packages/shared/src/contracts/generated/** linguist-generated=true
@@ -7,10 +7,6 @@ on:
  pull_request:
  workflow_dispatch:

-concurrency:
-  group: project-ci-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
 permissions:
  contents: read

@@ -31,28 +27,9 @@ env:
  RUSTC_WRAPPER: ''
  CARGO_BUILD_RUSTC_WRAPPER: ''

-# job 声明顺序就是 runner 领取顺序，因此把最长尾的客户端 Rust 门禁排在前面，
-# 让它在最少的等待下占用并发槽位；其余 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 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`
-# （当年线程并行会互相干扰的是进程内后台锁与异步终态），片与片之间靠 job 级并发摊开。
-# 不要改回「一个 job 里多进程并行这几片」：同一容器内它们会争抢共享 HOME、target 与固定
-# 临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」。
 jobs:
-  # AGC 壳自身的 Rust bin 单测分片，4 片各自独立 job 并发执行、片内仍保持
-  # `--test-threads=1`。这里不装 npm 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，
-  # 也只需要 AGC 壳自己那份锁定依赖。
-  ai-game-creator-shell-rust-shard-1:
-    name: AI game creator shell Rust shard 1/4
+  repository-checks:
+    name: Repository checks
    runs-on: genarrative-ci
    steps:
      - name: Checkout full history from Gitea
@@ -64,246 +41,76 @@ jobs:
      - 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
+      - name: Resolve comparison base
        shell: bash
        run: |
          set -euo pipefail
-          # AGC 壳有独立 Cargo.lock，其 path 依赖已含 platform-llm、platform-agent、
-          # agent-runtime-core 与 shared-contracts，因此只锁这一份 manifest 就能覆盖壳测试
-          # 与 smoke 的全部第三方依赖；server-rs 那次预热归 crate 级 job，不在这里重复。
-          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
+          base_ref="$(node -e '
+            const fs = require("node:fs");
+            const event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
+            process.stdout.write(event.pull_request?.base?.sha ?? event.before ?? "");
+          ')"
+          if [[ -n "${base_ref}" && ! "${base_ref}" =~ ^0+$ ]]; then
+            git cat-file -e "${base_ref}^{commit}" 2>/dev/null || {
+              echo "comparison base commit is unavailable: ${base_ref}" >&2
              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
+            }
+          else
+            base_ref="$(git merge-base HEAD origin/master 2>/dev/null || git rev-parse HEAD)"
+          fi
+          resolved_base_ref="$(git rev-parse --verify "${base_ref}^{commit}" 2>/dev/null || true)"
+          head_ref="$(git rev-parse HEAD)"
+          if [[ "${resolved_base_ref}" == "${head_ref}" ]]; then
+            resolved_base_ref="$(git rev-parse --verify HEAD^ 2>/dev/null || true)"
+          fi
+          if [[ -z "${resolved_base_ref}" ]]; then
+            echo 'comparison base must resolve to a commit distinct from HEAD.' >&2
+            exit 1
+          fi
+          base_ref="${resolved_base_ref}"
+          if [[ "${GITHUB_EVENT_NAME:-}" == 'pull_request' ]] \
+            && ! git merge-base --is-ancestor "${base_ref}" HEAD; then
+            echo 'pull request head does not contain the latest base commit; update the branch and rerun CI.' >&2
+            exit 1
+          fi
+          echo "SPACETIME_SCHEMA_BASE_REF=${base_ref}" >> "${GITHUB_ENV}"

-      - name: Run AI game creator shell Rust shard 1/4
-        run: npm run check:native-shells:agc-rust-shard-1
+      - name: Install npm dependencies
+        run: bash scripts/ci-npm-ci-with-retry.sh

-  ai-game-creator-shell-rust-shard-2:
-    name: AI game creator shell Rust shard 2/4
+      - name: Run repository checks
+        run: npm run check:repository-ci
+
+  frontend-tests:
+    name: Frontend tests
    runs-on: genarrative-ci
    steps:
-      - name: Checkout full history from Gitea
+      - name: Checkout source from Gitea
        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '0'
+          GENARRATIVE_GITEA_FETCH_DEPTH: '1'
          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: Install npm dependencies
+        run: bash scripts/ci-npm-ci-with-retry.sh

-      - name: Run AI game creator shell Rust shard 2/4
-        run: npm run check:native-shells:agc-rust-shard-2
+      - name: Run frontend and script tests
+        run: npm run test

-  ai-game-creator-shell-rust-shard-3:
-    name: AI game creator shell Rust shard 3/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: Run BgFilter worker smoke harness tests
+        run: npm run bgfilter-worker:smoke-test

-      - name: Validate preinstalled CI job image and sandbox
-        run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh
+      - name: Validate production health patrol behavior
+        run: npm run check:production-health-patrol

-      - 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: Validate production API release behavior
+        run: npm run check:production-api-release

-      - 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
-
-  # agent-run smoke 会 spawn `cargo run`（走壳自己的 manifest），同样不装 npm 依赖，
-  # 单独一个 job，免得把已经压到 4 分钟级的片 job 拖长。
-  ai-game-creator-shell-rust-smoke:
-    name: AI game creator shell Rust smoke
-    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 agent-run smoke
-        run: npm run check:native-shells:agc-rust-smoke
-
-  # AGC 壳依赖的共享 / 平台和编辑器插件 crate 各自预热独立 manifest，再运行对应测试。
-  ai-game-creator-shell-rust-crates:
-    name: AI game creator shell Rust crates
-    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 server-rs 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 server-rs/Cargo.toml; then
-              break
-            fi
-            if [[ "${attempt}" -eq 5 ]]; then
-              echo 'server-rs Cargo dependency fetch failed after 5 attempts.' >&2
-              exit 1
-            fi
-            sleep $((attempt * 2))
-          done
-
-      - name: Prepare standalone Rust crate dependencies
-        shell: bash
-        run: |
-          set -euo pipefail
-          # agent-runtime-core / agent-runtime-orchestration 被 server-rs/Cargo.toml 的
-          # exclude 排除，不参与上面的 workspace 锁文件，因此上面那次锁定 fetch 覆盖不到它们；
-          # 而 `npm run ai-game-creator-shell:check:rust:crates` 会用
-          # `cargo test --manifest-path` 单独跑这两个 crate。不在这里预热的话，这两条测试
-          # 会在测试阶段自己 `Updating crates.io index`，crates.io 一抖动整条 job 就红
-          # （见 #327 / PR #316 run 1950）。
-          # 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 \
-            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 \
-                --manifest-path "${manifest_path}"; then
-                break
-              fi
-              if [[ "${attempt}" -eq 5 ]]; then
-                echo "standalone crate dependency fetch failed after 5 attempts: ${manifest_path}" >&2
-                exit 1
-              fi
-              sleep $((attempt * 2))
-            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: Run AI game creator shell shared crate gates
-        run: npm run check:native-shells:agc-rust-crates
+      - name: Validate production API deploy behavior
+        run: npm run check:production-api-deploy

  backend-tests:
    name: Backend tests
@@ -387,8 +194,6 @@ jobs:
      - name: Check SpacetimeDB module
        run: cargo check --locked -p spacetime-module --manifest-path server-rs/Cargo.toml

-  # 客户端的壳级与契约门禁：静态契约断言、H5 / 微信 / 移动 / 桌面壳运行时门禁，
-  # 以及依赖发布产物的构建 smoke。
  native-shell-tests:
    name: Native shell tests
    runs-on: genarrative-ci
@@ -410,6 +215,7 @@ jobs:
        run: |
          set -euo pipefail
          for manifest_path in \
+            server-rs/Cargo.toml \
            apps/desktop-shell/src-tauri/Cargo.toml \
            apps/ai-game-creator-shell/src-tauri/Cargo.toml; do
            for attempt in $(seq 1 5); do
@@ -426,118 +232,8 @@ jobs:
            done
          done

-      - name: Run native shell contract gates
-        run: npm run check:native-shells:contract
-
      - name: Run native shell gates
-        run: npm run check:native-shells:shells
-
-      - name: Run native shell release build smoke
-        run: npm run check:native-shells:release
+        run: npm run check:native-shells

      - name: Ensure native lockfiles are unchanged
        run: git diff --exit-code -- apps/desktop-shell/src-tauri/Cargo.lock apps/ai-game-creator-shell/src-tauri/Cargo.lock
-
-  frontend-tests:
-    name: Frontend tests
-    runs-on: genarrative-ci
-    steps:
-      - name: Checkout source from Gitea
-        env:
-          GENARRATIVE_GITEA_FETCH_DEPTH: '1'
-          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: Install npm dependencies
-        run: bash scripts/ci-npm-ci-with-retry.sh
-
-      - name: Run frontend and script tests
-        run: npm run test
-
-      - name: Run BgFilter worker smoke harness tests
-        run: npm run bgfilter-worker:smoke-test
-
-      - name: Validate production health patrol behavior
-        run: npm run check:production-health-patrol
-
-      - name: Validate production API release behavior
-        run: npm run check:production-api-release
-
-      - name: Validate production API deploy behavior
-        run: npm run check:production-api-deploy
-
-  repository-checks:
-    name: Repository checks
-    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: Resolve comparison base
-        shell: bash
-        run: |
-          set -euo pipefail
-          base_ref="$(node -e '
-            const fs = require("node:fs");
-            const event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
-            process.stdout.write(event.pull_request?.base?.sha ?? event.before ?? "");
-          ')"
-          if [[ -n "${base_ref}" && ! "${base_ref}" =~ ^0+$ ]]; then
-            git cat-file -e "${base_ref}^{commit}" 2>/dev/null || {
-              echo "comparison base commit is unavailable: ${base_ref}" >&2
-              exit 1
-            }
-          else
-            base_ref="$(git merge-base HEAD origin/master 2>/dev/null || git rev-parse HEAD)"
-          fi
-          resolved_base_ref="$(git rev-parse --verify "${base_ref}^{commit}" 2>/dev/null || true)"
-          head_ref="$(git rev-parse HEAD)"
-          if [[ "${resolved_base_ref}" == "${head_ref}" ]]; then
-            resolved_base_ref="$(git rev-parse --verify HEAD^ 2>/dev/null || true)"
-          fi
-          if [[ -z "${resolved_base_ref}" ]]; then
-            echo 'comparison base must resolve to a commit distinct from HEAD.' >&2
-            exit 1
-          fi
-          base_ref="${resolved_base_ref}"
-          if [[ "${GITHUB_EVENT_NAME:-}" == 'pull_request' ]] \
-            && ! git merge-base --is-ancestor "${base_ref}" HEAD; then
-            echo 'pull request head does not contain the latest base commit; update the branch and rerun CI.' >&2
-            exit 1
-          fi
-          echo "SPACETIME_SCHEMA_BASE_REF=${base_ref}" >> "${GITHUB_ENV}"
-
-      - name: Install npm dependencies
-        run: bash scripts/ci-npm-ci-with-retry.sh
-
-      - name: Run repository checks
-        run: npm run check:repository-ci
-
-  # 客户端的 AI 游戏创作壳前端门禁：typecheck 与壳内测试，不触碰 Cargo。
-  ai-game-creator-shell-web-tests:
-    name: AI game creator shell web tests
-    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: Install npm dependencies
-        run: bash scripts/ci-npm-ci-with-retry.sh
-
-      - name: Run AI game creator shell web gates
-        run: npm run check:native-shells:agc-web
@@ -40,18 +40,6 @@ temp*build*/
 /apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/codex-path/
 /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,4 +1 @@
-# 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
@@ -1,4 +1 @@
-# 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 -- "$@"
@@ -1,14 +1,5 @@
 {
  "singleQuote": true,
  "semi": true,
-  "trailingComma": "all",
-  "overrides": [
-    {
-      "files": "packages/shared/src/contracts/generated/**/*.ts",
-      "options": {
-        "printWidth": 1000,
-        "singleQuote": false
-      }
-    }
-  ]
+  "trailingComma": "all"
 }
@@ -16,7 +16,6 @@
  3. [`docs/project-memory/README.md`](docs/project-memory/README.md)、[`project-overview.md`](docs/project-memory/shared-memory/project-overview.md)、[`team-conventions.md`](docs/project-memory/shared-memory/team-conventions.md)、[`development-workflow.md`](docs/project-memory/shared-memory/development-workflow.md)。
  4. 与任务相关的 [`decision-log.md`](docs/project-memory/shared-memory/decision-log.md)、[`pitfalls.md`](docs/project-memory/shared-memory/pitfalls.md)、[`docs/README.md`](docs/README.md) 和当前专题文档。
 - 落地工程修改前，先确认是否已有足够具体的 PRD、技术方案或当前融合文档；文档仍存在编码级歧义时，先补文档再编码。
- 跨模块功能、公开 API/DTO、SpacetimeDB schema、AGC/Runtime 或复杂 UI 状态链路必须按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](docs/【协作规范】规范驱动开发工作流-2026-09-12.md) 先完成主规范、里程碑规范和单里程碑实现计划；评审与验收门禁未通过前不得进入下一里程碑。局部修复、文案和无行为变化重构继续走轻量流程。
 - 本仓库的本地 RAG 位于 [`scripts/rag/`](scripts/rag/)；RAG 只作为候选上下文，不替代打开源文件核对。默认不安装 RAG 运行时依赖，需要启用时必须先询问用户，并只安装到 gitignored 的 `.rag/runtime/`。

 ## 绝对约束
@@ -44,35 +44,6 @@ _Avoid_: 把同一资源的全局元数据和某一次摆放坐标混在同一
 由图片生成或图片修改流程产生的画布资源，必须记录来源资源、提示词、实际提示词、模型、provider、任务 ID 和生成时间；本期 `/editor` 的生成修改先允许 mock 生成资源，但仍按生成资源元数据形状保存。
 _Avoid_: 无来源的静态素材、只显示在 UI 但不落工程资源记录的生成结果

-**图片模型历史值与使用端解析**:
-图片资源中已持久化的 `gpt-image-2` 是历史业务事实，读回时保持原值；新任务使用业务模型值 `gpt-image-2.5`。当用户基于历史资源再次发起生成或编辑任务时，服务端只在新任务的使用端把历史值解析为当前业务模型，不改写历史资源。provider route 属于服务端执行与审计边界，前端不接收、不持久化、不展示，也不据此分支。
-_Avoid_: 读取数据库时改写历史模型值、把 provider route 暴露为前端模型选项或公开 DTO
-
-**图片 provider 显式路由**:
-api-server 在任务入口按业务语义显式选择具体 provider model name（生成或编辑），并把同一具体名传给图片平台适配器和后台定价解析；图片平台适配器不从参考图数量或前端字段猜测任务。具体 provider model name 只存在于服务端调用、定价配置和审计边界。
-后台管理 Web/API 是明确例外，可以查看和编辑两个具体定价 key；主站普通前端与公开定价 API 不接收这些 key。
-_Avoid_: 让图片适配器隐式猜路由、让主站前端携带 provider model name
-
-**业务模型**:
-面向任务与产品契约的稳定模型值；当前 GPT 图片新任务的业务模型是 `gpt-image-2.5`。业务模型不等同于 provider 的具体计费/请求 model，也不暴露 provider 凭证或 endpoint。
-_Avoid_: 把 provider concrete model 当作前端业务选项、用业务模型值直接推断 provider 凭证
-
-**具体模型**:
-服务端发送请求和定价使用的 concrete model name。GPT Image 2.5 生成与编辑分别是 `gpt-image-2.5-flare-c` 和 `gpt-image-2.5-sunburst-c`；nanobanana 仍使用 `gemini-3.1-flash-image-preview`。具体模型只在服务端执行、定价和审计边界出现。
-_Avoid_: 把具体模型写入普通前端 DTO、让未知字符串自动选择 provider
-
-**provider client**:
-按具体模型选出的外部图片 provider 连接配置，包含 provider identity、base URL 和 API key；VectorEngine 与 Tiantoken client 共享图片协议执行器，不复制请求/响应业务逻辑。两套 required client 在 api-server 启动时构造。
-_Avoid_: 在首次请求时才创建 client、在 provider client 中复制尺寸/重试/审计逻辑、跨 provider credential fallback
-
-**历史模型值**:
-已持久化的 `gpt-image-2` 或 `gpt-image-2-c` 字符串，只作为历史事实原样读取和审计；基于历史资源提交新任务时，在使用端解析为当前 GPT Image 2.5 业务任务，不回写历史记录，也不把旧值作为现役 provider route。
-_Avoid_: 数据库批量改写历史值、把历史值重新路由到 VectorEngine、把兼容解析扩散到普通前端
-
-**GPT Image 2.5 新生成展示名**:
-`GPT Image 2.5` 是新生成任务的产品展示名；历史资源与既有编辑上下文不因新模型上线而改写展示语义。
-_Avoid_: 把新生成展示名扩散到历史记录、历史生成器或旧编辑上下文
-
 **系列素材图集生成**:
 一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。
 _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO
@@ -201,20 +172,6 @@ _Avoid_: 多步骤向导、完整规则编辑器、拖拽编辑器
 Bark Battle 平台作品闭环按契约与领域规则、后端存储/API、最小前端纵切、投影体验、收口验证的顺序推进。
 _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI

-## 项目开发对话（DirectProject）
-
-**项目对话历史**:
-AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
-_Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
-
-**运行态事件**:
-Thread Manager 向订阅者推送的当前回合原始事件流，只服务运行期间与短期断线恢复，不替代项目对话历史。
-_Avoid_: 进度通知、快照轮询、第二套历史
-
-**聊天投影**:
-把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
-_Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
-
 ## Relationships

 - 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
@@ -249,5 +206,3 @@ _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
 - “入口闭环”曾可能只指内部 demo 或单个详情 CTA；已解析为 **正式作品入口闭环**，不新增独立专区或活动页。
 - “创作编辑”曾可能指多步骤向导或完整编辑器；已解析为 **轻配置编辑流程**，使用单页表单 + 预览卡片完成保存草稿、发布和发布后跳转作品详情。
 - “实施顺序”曾可能按 UI 或功能并行发散；已解析为契约/领域规则先行，再做后端存储/API，随后打通最小前端纵切，最后补投影体验与收口验证。
- “回合进度事件”曾同时指 Direct turn update 与 Thread Manager 运行态事件；已解析为 AGC 项目开发对话只保留 **运行态事件**。
- “哪些消息可显示”曾可能由后端历史分页判断；已解析为可见性判断属于 **聊天投影**，后端只按原始条目分页，前端负责跳过不可显示条目并推进分页锚点。
@@ -38,7 +38,6 @@ vi.mock('../api/adminApiClient', () => ({

 interface MockIntersectionObserverController {
  enter: (target: Element) => void;
-  enterAll: (targets: Element[]) => void;
  isObserved: (target: Element) => boolean;
 }

@@ -107,25 +106,6 @@ 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);
    },
@@ -773,10 +753,10 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
  const thumbnails = entries.map((entry) =>
    thumbnailElementForLabel(entry.label),
  );
-  for (const thumbnail of thumbnails) {
+  thumbnails.forEach((thumbnail) => {
    expect(observer.isObserved(thumbnail)).toBe(true);
-  }
-  observer.enterAll(thumbnails);
+    observer.enter(thumbnail);
+  });
  await act(async () => {
    await Promise.resolve();
  });
@@ -796,7 +776,7 @@ test('后台素材查询为大量同时可见的缩略图持续错峰换签', as
    await vi.advanceTimersByTimeAsync(200);
  });
  expect(getAdminAssetReadUrl).toHaveBeenCalledTimes(105);
-}, 10_000);
+});

 test('后台素材查询读取更多后为新进入可视区域的素材换签', async () => {
  const observer = installIntersectionObserverMock();
@@ -1,4 +0,0 @@
-# resources/plugins 由 build.rs 从 plugins/ 复制生成，属于构建产物。
-# 它在 dev 监听范围内，重新生成会让 Tauri dev 误判为源码改动而触发
-# “构建 -> 监听 -> 再构建”的自触发循环。
-resources/plugins/
@@ -2,8 +2,6 @@
  "schemaVersion": "game-creator-config.v2",
  "agentMode": "codex_app_server",
  "llm": {
-    "customEnabled": false,
-    "visibleModels": [],
    "apiKey": "",
    "baseUrl": "https://dev.genarrative.world/gpt/v1",
    "model": "gpt-6-astra",
@@ -15,8 +13,11 @@
    "autoCompactTokenLimit": 64000,
    "toolOutputTokenLimit": 12000,
    "requestTimeoutMs": 180000,
-    "maxRetries": 10,
+    "maxRetries": 2,
    "retryBackoffMs": 500
  },
-  "agentLlm": {}
+  "agentLlm": {},
+  "planning": {
+    "capabilityEnabled": true
+  }
 }
@@ -1,7 +1,7 @@
 {
  "name": "@genarrative/ai-game-creator-shell",
  "private": true,
-  "version": "0.1.67",
+  "version": "0.1.19",
  "type": "module",
  "scripts": {
    "dev": "node scripts/start-tauri-dev.mjs",
@@ -9,6 +9,7 @@
    "dev-stack": "node scripts/start-dev-stack.mjs",
    "build": "node scripts/build-release.mjs",
    "release:upload": "node scripts/release-upload.mjs",
+    "bump-version": "node scripts/bump-version.mjs",
    "skill-pack:check": "node scripts/check-skill-pack.mjs",
    "skill-pack:sync": "node scripts/check-skill-pack.mjs --write",
    "skill-pack:test": "node --test scripts/check-skill-pack.test.mjs",
@@ -19,6 +20,8 @@
    "config": "node scripts/game-creator-config-wizard.mjs",
    "test:chat": "node scripts/agent-swarm-test-chat.mjs --task \"制作一个可直接试玩的原创植物塔防小游戏：玩家选择并放置原创守卫阻挡敌人，完成波次后可以进入下一关并重新开始。主题、单位名称与视觉语言必须原创，不使用任何现有游戏角色、单位名、Logo 或受保护视觉语言。请自主完成正式产物、静态检查和双视口试玩验证。\" --no-open",
    "test:chat:manual": "node scripts/agent-swarm-test-chat.mjs",
+    "test:plan": "node scripts/agent-swarm-test-chat.mjs --plan --task \"我想做一款原创横版像素解谜小游戏，主角是一个能操控自己影子的小机器人，影子可以变成平台和开关。请完成立项策划并给出 Fast GDD。主题、角色名与视觉语言必须原创，不使用任何现有游戏角色、名称、Logo 或受保护视觉语言。\"",
+    "test:plan:manual": "node scripts/agent-swarm-test-chat.mjs --plan",
    "agent-run": "node scripts/run-cli-with-config.mjs --agent-run",
    "agent-run:smoke": "node scripts/smoke-agent-run-local-provider.mjs",
    "agent-runtime:real-e2e": "node scripts/agent-runtime-real-e2e.mjs",
@@ -47,21 +50,16 @@
    "@tauri-apps/plugin-dialog": "^2.7.2",
    "@tauri-apps/plugin-http": "^2.5.9",
    "@tauri-apps/plugin-opener": "~2",
-    "@tauri-apps/plugin-updater": "2.11.0",
    "@vitejs/plugin-react": "^5.0.4",
    "focus-trap-react": "^12.0.3",
    "lexical": "^0.47.0",
    "lucide-react": "^0.546.0",
-    "phaser": "^4.2.1",
    "react": "^19.0.0",
    "react-arborist": "^3.16.0",
    "react-colorful": "^5.8.0",
    "react-dom": "^19.0.0",
    "react-markdown": "^10.1.0",
-    "react-window": "^1.8.11",
-    "rehype-highlight": "^7.0.2",
    "remark-gfm": "^4.0.1",
-    "three": "^0.184.0",
    "vite": "^6.2.0",
    "zustand": "^5.0.14"
  },
@@ -73,8 +71,6 @@
    "@testing-library/user-event": "^14.6.1",
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
-    "@types/three": "^0.184.1",
-    "@types/react-window": "^1.8.8",
    "tailwindcss": "^4.1.14",
    "typescript": "~5.8.2",
    "vitest": "^0.34.6"
@@ -676,11 +676,11 @@ async function runSelfTest() {
      designFoundationAssetCall?.arguments?.input?.outputPath ===
        'assets/ui-prototype.png' &&
      designFoundationAssetCall.arguments.input.aspectRatio === '16:9' &&
-      designFoundationAssetCall.arguments.input.assetKind === 'ui-design' &&
+      designFoundationAssetCall.arguments.input.assetKind === 'ui-prototype' &&
      artAssetPlanAssetCall?.arguments?.input?.outputPath ===
        'assets/art-spritesheet.png' &&
      artAssetPlanAssetCall.arguments.input.aspectRatio === '1:1' &&
-      artAssetPlanAssetCall.arguments.input.assetKind === 'icon-spritesheet',
+      artAssetPlanAssetCall.arguments.input.assetKind === 'art-spritesheet',
    'self-test-visual-assets-invalid',
  );

@@ -36,6 +36,8 @@ export const ungeneratedGameEntryMarker =
  '还没有生成游戏。回到聊天输入创意并确认生成后';
 export const defaultRealSwarmTestTask =
  '制作一个可直接试玩的原创植物塔防小游戏：玩家选择并放置原创守卫阻挡敌人，完成波次后可以进入下一关并重新开始。主题、单位名称与视觉语言必须原创，不使用任何现有游戏角色、单位名、Logo 或受保护视觉语言。请自主完成正式产物、静态检查和双视口试玩验证。';
+export const defaultRealSwarmPlanTask =
+  '我想做一款原创横版像素解谜小游戏，主角是一个能操控自己影子的小机器人，影子可以变成平台和开关。请完成立项策划并给出 Fast GDD。主题、角色名与视觉语言必须原创，不使用任何现有游戏角色、名称、Logo 或受保护视觉语言。';
 export const swarmTurnReportPrefix = '[turn.report] ';
 export const swarmTurnReportSchema = 'game-creator-swarm-turn-report.v1';

@@ -70,7 +72,7 @@ const requiredFormalArtifactSpecs = [
  { path: 'game/balance.json', kind: 'json' },
  { path: 'assets/manifest.art.json', kind: 'json' },
  { path: 'assets/manifest.audio.json', kind: 'json' },
-  { path: 'game/index.html', kind: 'file' },
+  { path: 'game/index.html', kind: 'game-entry' },
  { path: 'exports/README.md', kind: 'file' },
 ];
 const editorImageArtifactSpecs = [
@@ -138,10 +140,15 @@ export const usage = `用法：
  --keep-project            保留自动创建的一次性项目
  --no-open                 手工模式启动预览但不自动打开浏览器
  --task <需求>             通过 manual 入口非交互提交自定义需求
-  --timeout-minutes <分钟>  设置本次执行期限；自动任务默认 50 分钟，手工模式默认不限时
+  --plan                    走「做方案」立项策划入口，不做游戏，不做产物验收和试玩
+  --timeout-minutes <分钟>  设置本次执行期限；自动任务默认 50 分钟，--plan 默认 6 分钟，手工模式默认不限时
  --dry-run                 只检查目录发现和项目准备，不启动 LLM
  -h, --help                显示帮助
-`;
+
+环境变量：
+  AGC_PLAN_GDD_DECISION     审批卡自动应答动作，默认 approve；revise/reject 必须
+                            同时用 AGC_PLAN_GDD_COMMENT 给出真实修改意见
+  AGC_PLAN_GDD_COMMENT      revise/reject 的意见原文`;

 function readOptionValue(args, index, option) {
  const value = args[index + 1]?.trim();
@@ -170,6 +177,7 @@ export function parseSwarmTestArguments(args) {
    keepProject: false,
    openBrowser: true,
    task: null,
+    plan: false,
    timeoutMinutes: null,
    dryRun: false,
    help: false,
@@ -194,6 +202,8 @@ export function parseSwarmTestArguments(args) {
      if (task.length > 4_000) throw new Error('--task 不能超过 4000 字符');
      options.task = task;
      index += 1;
+    } else if (argument === '--plan') {
+      options.plan = true;
    } else if (argument === '--timeout-minutes') {
      if (options.timeoutMinutes !== null) {
        throw new Error('--timeout-minutes 只能指定一次');
@@ -212,11 +222,16 @@ export function parseSwarmTestArguments(args) {
 }

 export function shouldStartPersistentPreview(options) {
-  return !options.task;
+  // 立项策划链路只出 GDD，没有可试玩产物，任何模式都不该起预览。
+  return !options.task && !options.plan;
 }

 export function resolveSwarmTestTimeoutMs(options) {
-  const minutes = options.timeoutMinutes ?? (options.task ? 50 : null);
+  // 立项策划的设计目标是五分钟出方案，给一分钟余量；再久就是卡住了，早失败
+  // 比让 harness 空等更有用。做游戏那条链路的 50 分钟不变。
+  const planMinutes = options.plan ? 6 : null;
+  const minutes =
+    options.timeoutMinutes ?? planMinutes ?? (options.task ? 50 : null);
  return minutes === null ? null : minutes * 60_000;
 }

@@ -371,15 +386,7 @@ async function runMissingConfigWizard(setActiveChild, explicitConfigDir) {
  }
 }

-async function secureWindowsPrivateRuntimePath(
-  targetPath,
-  options,
-  secureWindowsPath = null,
-) {
-  if (secureWindowsPath) {
-    await secureWindowsPath(targetPath, options);
-    return;
-  }
+async function secureWindowsPrivateRuntimePath(targetPath, options) {
  const { secureWindowsGameCreatorPathForCurrentUser } = await import(
    './game-creator-config-wizard.mjs'
  );
@@ -391,7 +398,6 @@ async function copyPrivateRuntimeConfigEntry(
  runtimeConfigDir,
  fileName,
  required,
-  secureWindowsPath = null,
 ) {
  const sourcePath = path.join(sourceConfigDir, fileName);
  const sourceMetadata = await lstat(sourcePath).catch((error) => {
@@ -411,11 +417,9 @@ async function copyPrivateRuntimeConfigEntry(
    const sourceBytes = await readFile(sourcePath);
    const destinationFile = await open(destinationPath, 'wx', 0o600);
    try {
-      await secureWindowsPrivateRuntimePath(
-        destinationPath,
-        { isDirectory: false },
-        secureWindowsPath,
-      );
+      await secureWindowsPrivateRuntimePath(destinationPath, {
+        isDirectory: false,
+      });
      await destinationFile.writeFile(sourceBytes);
      await destinationFile.sync();
    } finally {
@@ -448,11 +452,7 @@ async function copyPrivateRuntimeConfigEntry(
  return true;
 }

-export async function prepareSwarmTestRuntimeConfig(
-  sourceConfigDir,
-  tempRoot,
-  { secureWindowsPath = null } = {},
-) {
+export async function prepareSwarmTestRuntimeConfig(sourceConfigDir, tempRoot) {
  if (!path.isAbsolute(sourceConfigDir)) {
    throw new Error('配置来源目录必须是绝对路径');
  }
@@ -472,11 +472,9 @@ export async function prepareSwarmTestRuntimeConfig(
  );
  try {
    if (process.platform === 'win32') {
-      await secureWindowsPrivateRuntimePath(
-        runtimeConfigDir,
-        { isDirectory: true },
-        secureWindowsPath,
-      );
+      await secureWindowsPrivateRuntimePath(runtimeConfigDir, {
+        isDirectory: true,
+      });
    } else {
      await chmod(runtimeConfigDir, 0o700);
    }
@@ -494,14 +492,12 @@ export async function prepareSwarmTestRuntimeConfig(
      runtimeConfigDir,
      configFileName,
      true,
-      secureWindowsPath,
    );
    await copyPrivateRuntimeConfigEntry(
      canonicalSourceConfigDir,
      runtimeConfigDir,
      localConfigFileName,
      false,
-      secureWindowsPath,
    );
    return {
      path: await realpath(runtimeConfigDir),
@@ -983,12 +979,25 @@ export function swarmAutoPilotShouldCloseInput(output, promptsAfterSubmit) {
  return swarmAutoPilotSitsAtPrompt(output) && promptsAfterSubmit >= 1;
 }

+// GDD 审批位不能等 CLI 退出之后再处理：Run 停在这里时状态是 waiting-for-user-input，
+// 而 swarm CLI 恰好把这个状态算作「本轮还在跑」，turn 永远不 settle，CLI 也就永远
+// 不退出。所以审批必须在 CLI 还活着的时候并发做完，让 Run 自己继续跑到收束。
+// 这一句是 PlanGddCompletionBlockerKind::AwaitingApprovalDecision 专有的投影文案，
+// 另外三个 blocked 子状态都不会打出它；即便认错了，真正的判据也是随后那次
+// --plan-gdd-status，没有待决定审批时不会有任何写入。
+const planGddApprovalWaitPattern = /等待 Fast GDD 审批决定/u;
+
+export function swarmOutputAwaitsPlanGddApproval(line) {
+  return planGddApprovalWaitPattern.test(line);
+}
+
 async function runTaskCargo(
  cliArguments,
  task,
  setActiveChild,
  timeoutMs,
  autoPilot = false,
+  onPlanGddApprovalWait = null,
 ) {
  const child = spawnChild(cargoCommand, buildCargoCliArguments(cliArguments), {
    stdio: ['pipe', 'pipe', 'inherit'],
@@ -1000,6 +1009,25 @@ async function runTaskCargo(
  let taskSubmitted = false;
  let promptsSeen = 0;
  let sittingAtPrompt = false;
+  let planGddApproval = null;
+  let planGddApprovalError = null;
+  let planGddApprovalStarted = false;
+  let planGddApprovalPromise = null;
+  const startPlanGddApproval = () => {
+    planGddApprovalStarted = true;
+    console.log(
+      `[自动审批] 检测到 Fast GDD 审批位，正在提交 ${resolvePlanGddAutoDecision().action}`,
+    );
+    planGddApprovalPromise = onPlanGddApprovalWait()
+      .then((value) => {
+        planGddApproval = value;
+      })
+      .catch((error) => {
+        planGddApprovalError = error;
+        // 审批没成的话 Run 会一直停在等待位，干等到超时只会把真正的原因埋掉。
+        void terminateChildTree(child).catch(() => {});
+      });
+  };
  child.stdout.setEncoding('utf8');
  child.stdout.on('data', (chunk) => {
    process.stdout.write(chunk);
@@ -1012,6 +1040,13 @@ async function runTaskCargo(
        reportLines.push(normalizedLine);
        settled = true;
      }
+      if (
+        onPlanGddApprovalWait &&
+        !planGddApprovalStarted &&
+        swarmOutputAwaitsPlanGddApproval(normalizedLine)
+      ) {
+        startPlanGddApproval();
+      }
    }
    if (!autoPilot || child.stdin.writableEnded) return;
    const atPrompt = swarmAutoPilotSitsAtPrompt(pendingLine);
@@ -1050,9 +1085,12 @@ async function runTaskCargo(
    if (normalizedPendingLine.startsWith(swarmTurnReportPrefix)) {
      reportLines.push(normalizedPendingLine);
    }
+    await planGddApprovalPromise;
+    if (planGddApprovalError) throw planGddApprovalError;
    return {
      ...result,
      turnReportOutput: reportLines.join('\n'),
+      planGddApproval,
    };
  } finally {
    setActiveChild(null);
@@ -1742,6 +1780,196 @@ export async function validateSwarmProjectArtifacts(projectPath, options) {
  return inspection;
 }

+// 这四条路径的权威定义都在 Rust 侧 `planning_storage.rs`（`PLAN_SESSION_PATH`、
+// `PLAN_GDD_INDEX_PATH`、`PLAN_STORAGE_ROOT`、`PLAN_FAST_GDD_PATH`）。跨语言没有共享
+// 常量的通道，改路径时要连同 `GddApprovalCard.tsx` 一起动。
+export const planningOutputPaths = [
+  '.agent/planning/session.json',
+  '.agent/planning/index.json',
+  '.agent/planning/pending.json',
+  'game/fast_gdd.md',
+];
+
+export async function inspectPlanningOutputs(projectPath) {
+  const outputs = [];
+  for (const relativePath of planningOutputPaths) {
+    const absolutePath = path.join(projectPath, ...relativePath.split('/'));
+    const metadata = await lstat(absolutePath).catch((error) => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    });
+    outputs.push({
+      path: relativePath,
+      exists: Boolean(metadata?.isFile()),
+      bytes: metadata?.isFile() ? metadata.size : 0,
+    });
+  }
+  return outputs;
+}
+
+async function reportPlanningOutputs(projectPath) {
+  const outputs = await inspectPlanningOutputs(projectPath);
+  console.log('\n立项策划产物：');
+  for (const output of outputs) {
+    console.log(
+      output.exists
+        ? `  [有] ${output.path}（${output.bytes} 字节）`
+        : `  [无] ${output.path}`,
+    );
+  }
+}
+
+const planGddApprovalTimeoutMs = 60_000;
+export const planGddStatusOutputPrefix = 'planGddStateJson=';
+export const planGddDecisionOutputPrefix = 'planGddDecisionJson=';
+
+function parsePrefixedJsonLine(output, prefix, label) {
+  const line = output
+    .split('\n')
+    .map((value) => (value.endsWith('\r') ? value.slice(0, -1) : value))
+    .find((value) => value.startsWith(prefix));
+  if (!line) throw new Error(`${label}缺少 ${prefix} 输出`);
+  try {
+    return JSON.parse(line.slice(prefix.length));
+  } catch (error) {
+    throw new Error(`解析${label}失败：${error.message}`);
+  }
+}
+
+export function parsePlanGddStatusOutput(output) {
+  return parsePrefixedJsonLine(
+    output,
+    planGddStatusOutputPrefix,
+    'Fast GDD 审批状态',
+  );
+}
+
+export function parsePlanGddDecisionOutput(output) {
+  return parsePrefixedJsonLine(
+    output,
+    planGddDecisionOutputPrefix,
+    'Fast GDD 审批回执',
+  );
+}
+
+// 审批卡是这条链路唯一的人类判据，所以自动应答默认只投 approve，且只在投影确实有
+// 一张待决定审批时出手。revise/reject 需要一段真实的修改意见，让机器编一段等于把
+// 判据换成噪声——所以那两条分支只在跑的人自己用 AGC_PLAN_GDD_COMMENT 给出意见时
+// 才走。手工调 --plan-gdd-decide 也能达到同样效果，但那要求 plan 根 run 仍然活着，
+// 而它恰好是本进程持有的 CLI 子进程。
+export function planGddAutoApprovalIsPending(state) {
+  return Boolean(state?.pendingApproval);
+}
+
+export function resolvePlanGddAutoDecision(env = process.env) {
+  const action = (env.AGC_PLAN_GDD_DECISION ?? 'approve').trim();
+  if (!['approve', 'revise', 'reject'].includes(action)) {
+    throw new Error('AGC_PLAN_GDD_DECISION 只能是 approve / revise / reject');
+  }
+  const comment = (env.AGC_PLAN_GDD_COMMENT ?? '').trim();
+  if (action === 'approve') return { action, comment: null };
+  if (!comment) {
+    throw new Error(
+      `${action} 必须同时设 AGC_PLAN_GDD_COMMENT 提供真实修改意见`,
+    );
+  }
+  return { action, comment };
+}
+
+async function settlePlanGddApproval(
+  projectPath,
+  runtimeConfigPath,
+  setActiveChild,
+) {
+  const readStatus = async () => {
+    const result = await runCapturedCargo(
+      ['--config-dir', runtimeConfigPath, '--plan-gdd-status', projectPath],
+      setActiveChild,
+      {
+        timeoutMs: planGddApprovalTimeoutMs,
+        label: 'Fast GDD 审批状态查询',
+      },
+    );
+    if (result.code !== 0 || result.signal) {
+      throw new Error(
+        `读取 Fast GDD 审批状态失败：${result.stderr.trim() || result.stdout.trim()}`,
+      );
+    }
+    return parsePlanGddStatusOutput(result.stdout);
+  };
+
+  const before = await readStatus();
+  if (!planGddAutoApprovalIsPending(before)) {
+    return { decided: false, state: before };
+  }
+  const { action, comment } = resolvePlanGddAutoDecision();
+  const decision = await runCapturedCargo(
+    [
+      '--config-dir',
+      runtimeConfigPath,
+      '--plan-gdd-decide',
+      projectPath,
+      action,
+      ...(comment === null ? [] : ['--stdin']),
+    ],
+    setActiveChild,
+    {
+      timeoutMs: planGddApprovalTimeoutMs,
+      label: 'Fast GDD 审批决定',
+      stdin: comment,
+    },
+  );
+  if (decision.code !== 0 || decision.signal) {
+    throw new Error(
+      `提交 Fast GDD 审批决定失败：${decision.stderr.trim() || decision.stdout.trim()}`,
+    );
+  }
+  const receipt = parsePlanGddDecisionOutput(decision.stdout);
+  // 回执落盘和唤醒后台任务是两件事：decide 命令把唤醒失败降级成 recoveryPending，
+  // 于是审批已经生效、Run 却仍停在 waiting-for-user-input。实测就是这样——只有
+  // 补一次 --agent-resume 才会重新起 turn。这是仓库自己给这个状态定义的恢复动作。
+  let recovered = false;
+  if (receipt.recoveryPending) {
+    const resume = await runCapturedCargo(
+      ['--config-dir', runtimeConfigPath, '--agent-resume', projectPath],
+      setActiveChild,
+      {
+        timeoutMs: planGddApprovalTimeoutMs,
+        label: 'Fast GDD 审批后恢复后台任务',
+      },
+    );
+    if (resume.code !== 0 || resume.signal) {
+      throw new Error(
+        `审批已提交但恢复后台任务失败：${resume.stderr.trim() || resume.stdout.trim()}`,
+      );
+    }
+    recovered = true;
+  }
+  return { decided: true, receipt, recovered, state: await readStatus() };
+}
+
+async function reportPlanGddApproval(approval) {
+  const { state } = approval;
+  console.log('\nFast GDD 审批：');
+  if (!approval.decided) {
+    console.log(`  [无待决定审批] 当前投影状态=${state.state}`);
+    return;
+  }
+  console.log(
+    `  [已决定 ${approval.receipt.decisionRef.action}] outcome=${approval.receipt.outcome} v${approval.receipt.decisionRef.version} 投影状态=${state.state}`,
+  );
+  if (approval.recovered) {
+    console.log(
+      '  [已恢复] 审批回执的 recoveryPending 由一次 --agent-resume 收口',
+    );
+  }
+  if (state.session) {
+    console.log(
+      `  澄清轮次=${state.session.clarificationRound} 返工深度=${state.session.repairDepth} phase=${state.session.phase}`,
+    );
+  }
+}
+
 export async function hasConfiguredEditorApiKey(configDir) {
  let configured = false;
  for (const fileName of [configFileName, localConfigFileName]) {
@@ -1894,7 +2122,13 @@ export async function runSwarmTestChat(options) {
  const setActiveChild = (child) => {
    activeChild = child;
  };
+  // GDD 审批要和 swarm CLI 并发跑，两者不能共用 activeChild 这一个槽位：审批子进程
+  // 结束时的 setActiveChild(null) 会把 CLI 从槽里抹掉，Ctrl-C 就杀不到它了。
  const concurrentChildren = new Set();
+  const setConcurrentChild = (child) => {
+    if (child) concurrentChildren.add(child);
+    else concurrentChildren.clear();
+  };
  const stopRequested = () => receivedSignal !== null;
  const handleSignal = (signal) => {
    const repeatedSignal = receivedSignal !== null;
@@ -1972,10 +2206,11 @@ export async function runSwarmTestChat(options) {
        );
      }
      console.log('LLM 配置已就绪。');
+      const requirementNoun = options.plan ? '立项策划需求' : '游戏需求';
      console.log(
        options.task
-          ? '已提交一条非交互游戏需求，正在等待 Swarm 自主完成。\n'
-          : '输入一条游戏需求并回车；提交后按 Ctrl+D，让 Swarm 自主完成。\n',
+          ? `已提交一条非交互${requirementNoun}，正在等待 Swarm 自主完成。\n`
+          : `输入一条${requirementNoun}并回车；提交后按 Ctrl+D，让 Swarm 自主完成。\n`,
      );

      phase = 'chat';
@@ -1985,7 +2220,8 @@ export async function runSwarmTestChat(options) {
        runtimeConfig.path,
        '--swarm-chat',
        '--init',
-        '--autonomous-game-build',
+        // 做方案链路只能跑 standard 档，后端对 plan + autonomous 是硬否决。
+        options.plan ? '--plan' : '--autonomous-game-build',
        project.path,
      ];
      let chat;
@@ -1998,6 +2234,15 @@ export async function runSwarmTestChat(options) {
              timeoutDeadline === null
                ? null
                : Math.max(1, timeoutDeadline - Date.now()),
+              options.plan,
+              options.plan
+                ? () =>
+                    settlePlanGddApproval(
+                      project.path,
+                      runtimeConfig.path,
+                      setConcurrentChild,
+                    )
+                : null,
            )
          : await runInteractiveCargo(chatArguments, setActiveChild);
      } catch (error) {
@@ -2013,6 +2258,32 @@ export async function runSwarmTestChat(options) {
      if (options.task) {
        turnReport = parseSettledSwarmTurnReport(chat.turnReportOutput);
      }
+      if (options.plan) {
+        // 立项策划不出游戏产物，正式验收在 GDD 审批卡上；这里只报告落盘情况，
+        // 是否收束已经由 CLI 的退出码判过了。
+        // 自动任务档的审批已经在 CLI 运行期间并发做完了；手工档（人自己敲 Ctrl+D
+        // 退出）没有那次触发，退出后补一次，没有待决定审批时它是只读的。
+        phase = 'plan-approval';
+        const approval =
+          chat.planGddApproval ??
+          (await settlePlanGddApproval(
+            project.path,
+            runtimeConfig.path,
+            setConcurrentChild,
+          ));
+        if (receivedSignal) break session;
+        phase = 'plan-report';
+        await reportPlanGddApproval(approval);
+        await reportPlanningOutputs(project.path);
+        phase = 'complete';
+        console.log(
+          approval.decided
+            ? '\n立项策划链路已收束：Fast GDD 已批准，策划产物见上方清单。'
+            : '\n立项策划链路已收束：Run 正常结束但没有待决定审批，策划产物见上方清单。',
+        );
+        break session;
+      }
+      phase = 'artifact-validation';
      const requireEditorImages = await hasConfiguredEditorApiKey(
        runtimeConfig.path,
      );
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
suzmii	2043f8c966	修复 bump-version 脚本导入排序以通过 lint:eslint Project CI / Repository checks (pull_request) Successful in 2m54s Details Project CI / Frontend tests (pull_request) Successful in 3m14s Details Project CI / Backend tests (pull_request) Successful in 6m0s Details Project CI / Native shell tests (pull_request) Successful in 20m42s Details - bump-version.mjs 按 simple-import-sort 调整 node:child_process / node:path / node:url 导入顺序	2026-09-07 14:59:30 +08:00
suzmii	65012e89b6	细化 AGC 发布文档：区分 build 与 release:upload 的校验范围 Project CI / Repository checks (pull_request) Failing after 15m25s Details Project CI / Frontend tests (pull_request) Successful in 21m16s Details Project CI / Backend tests (pull_request) Failing after 1h45m38s Details Project CI / Native shell tests (pull_request) Failing after 1h50m38s Details - build 只校验五个版本来源一致；release:upload 在上传前额外校验版本已提交与防降级	2026-09-07 14:10:13 +08:00
suzmii	64b9ccfb9d	发布链路加固：要求版本已提交后再发布 - 新增 assertVersionCommitted：发布前确认 5 个版本来源相对 HEAD 已提交，避免仅 bump 未提交就 release 导致本地与 Jenkins 检出版本不一致 - release-upload 在取版本、OSS 防降级前调用该守卫 - 更新 AGC 更新技术方案文档，并补发布校验回归测试	2026-09-07 14:09:16 +08:00
suzmii	fcc3c39dad	bump-version 提交前校验，存在其他暂存改动时中止 - --commit 在改动任何版本文件前先检查已暂存文件，发现版本文件外的暂存改动则中止并提示，避免误提交无关内容 - 同步 AGC 更新技术方案文档说明	2026-09-07 14:03:41 +08:00
suzmii	f7a0adc616	bump-version 默认不提交，改为 --commit 显式提交 - bump-version.mjs 默认只写入版本文件、不创建提交；需要提交时加 --commit - 增加保护：若工作区已带着一次未提交的提升，再 --commit 不会重复递增，直接提交现有改动 - 同步 AGC 更新技术方案文档的用法示例与说明	2026-09-07 13:38:17 +08:00
suzmii	57cd81d551	修复 AGC 版本测试在 Windows 上的路径问题并澄清 bump-version 提示 - build-release.test.mjs 用 fileURLToPath 替代 URL.pathname，修复 Windows 下 /C:/... 路径导致的 3 个用例失败（既有的跨平台问题） - bump-version.mjs 的 --no-commit 输出改为“已写入版本文件，未创建提交”，避免被误认为不改文件的干跑	2026-09-07 13:33:41 +08:00
suzmii	78088e422a	AGC 版本号以仓库为准，新增 bump-version 提升版本命令 - 发布/构建不再自动递增版本、不再支持 AGC_RELEASE_VERSION 自由指定版本，改为读取仓库已提交的版本 - prepareReleaseVersion 只校验五个版本来源一致并返回仓库版本，不再改写版本文件 - 新增 apps/ai-game-creator-shell/scripts/bump-version.mjs，默认提升 patch，支持 minor/major/显式版本，写入五处并本地提交 - release:upload 发布前通过 assertVersionNotBelowOss 防降级：仓库版本低于 OSS 线上版本时中止，并提示先运行 bump-version - 新增根 npm run ai-game-creator-shell:bump-version 别名，并在 AGC 更新技术方案文档与 Jenkinsfile 中移除自由版本参数说明	2026-09-07 12:52:03 +08:00
suzmii	65551cd827	提升 AGC 版本至 0.1.19 并补充发布版本回写约定 - package.json 版本 0.1.12 -> 0.1.19，与 OSS latest.json 线上版本对齐，消除 dev 客户端每次启动误报发现新版本 - 同步更新根 package-lock.json、src-tauri/tauri.conf.json、src-tauri/Cargo.toml、Cargo.lock 中 AGC 包条目版本至 0.1.19，五处保持一致 - 在 AGC 更新技术方案文档的发布约定补充说明：发布新版本后必须手动将版本号变更提交回仓库，避免版本漂移	2026-09-07 12:34:09 +08:00