修复图片交付尺寸与提示重触发

统一图片模型的业务交付像素并保留 GPT provider 合法请求尺寸禁止欠交付图片被放大并返回尺寸降级提示重置相同 warning 的三秒自动关闭计时补充前后端回归测试与编辑器契约文档
修复画布提示与图片尺寸一致性
2026-07-27 21:16:01 +08:00 · 2026-07-27 20:24:07 +08:00 · 2026-07-27 12:05:33 +08:00 · 2026-07-27 11:56:23 +08:00 · 2026-07-24 20:47:05 +08:00 · 2026-07-23 18:06:29 +08:00
1927 changed files with 275382 additions and 43263 deletions
@@ -1,15 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test:*)",
-      "Bash(netstat -ano)",
-      "Bash(npm run:*)",
-      "Bash(findstr :8081)",
-      "Bash(taskkill:*)",
-      "Bash(findstr LISTENING)",
-      "Bash(npx tsc:*)",
-      "Bash(lsof -ti:8081)",
-      "Bash(curl -s http://localhost:8081/health)"
-    ]
-  }
-}
@@ -14,20 +14,40 @@ if (hookInput && !isGitCommitCommand(extractShellCommand(hookInput))) {
 }

 const validationSteps = [
+  {
+    label: 'Rust format check',
+    command: npmCommand,
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run check:rustfmt']
+        : ['run', 'check:rustfmt'],
+  },
  {
    label: 'TypeScript typecheck',
    command: npmCommand,
-    args: process.platform === 'win32' ? ['/d', '/s', '/c', 'npm run typecheck'] : ['run', 'typecheck'],
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run typecheck']
+        : ['run', 'typecheck'],
  },
  {
    label: 'Admin web typecheck',
    command: npmCommand,
-    args: process.platform === 'win32' ? ['/d', '/s', '/c', 'npm run admin-web:typecheck'] : ['run', 'admin-web:typecheck'],
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run admin-web:typecheck']
+        : ['run', 'admin-web:typecheck'],
  },
  {
    label: 'Rust api-server compile check',
    command: 'cargo',
-    args: ['check', '-p', 'api-server', '--manifest-path', 'server-rs/Cargo.toml'],
+    args: [
+      'check',
+      '-p',
+      'api-server',
+      '--manifest-path',
+      'server-rs/Cargo.toml',
+    ],
  },
 ];

@@ -66,7 +86,9 @@ function runStep(step) {
  }

  if (result.error) {
-    console.error(`[codex-hook] ${step.label} 启动失败：${result.error.message}`);
+    console.error(
+      `[codex-hook] ${step.label} 启动失败：${result.error.message}`,
+    );
    return { ok: false, status: 1 };
  }

@@ -104,12 +126,15 @@ function extractShellCommand(input) {
    input?.command,
  ];

-  const command = candidates.find(value => typeof value === 'string' && value.trim().length > 0);
+  const command = candidates.find(
+    (value) => typeof value === 'string' && value.trim().length > 0,
+  );
  if (command) {
    return command;
  }

-  const shellCommand = input?.tool_input?.cmd ?? input?.toolInput?.cmd ?? input?.arguments?.cmd;
+  const shellCommand =
+    input?.tool_input?.cmd ?? input?.toolInput?.cmd ?? input?.arguments?.cmd;
  if (Array.isArray(shellCommand)) {
    return shellCommand.join(' ');
  }
@@ -318,6 +318,14 @@ For image edit/redraw that should replace an existing canvas layer, pass `projec

 For sound effects and BGM, `assetFolderId` and `assetLabel` can write the generated audio to the account asset library, same as image/video generation.

+## Successful Responses with Warnings
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction can return HTTP 2xx with an optional structured `warning`. A 2xx response means the task completed, but it does not guarantee that every requested post-processed derivative exists.
+
+- Apply the returned `project` and media snapshots before interpreting optional derivatives: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. When `warning.code` is `postprocess-failed-source-preserved`, the saved provider source image is the authoritative main result. Character output has no transparent derivative; icon spritesheet and UI extraction output have neither a transparent spritesheet nor slices. Display `warning.reason` directly, and do not synthesize missing derivatives or restart generation.
+- `sliceWarning` is a separate condition used only when transparent spritesheet post-processing succeeded but automatic slicing failed. Keep `sliceWarning.reason` as the original diagnostic and continue using the complete transparent spritesheet; a UI may add context when displaying it, but must not rewrite the stored reason.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. As defensive handling for a malformed response containing both, treat the general `warning` as authoritative and do not misclassify the source-preserved result as a slicing-only warning.
+
 ## Guardrails

 - Do not invent endpoints outside the OpenAPI, especially internal worker or runtime task-list routes.
@@ -78,6 +78,14 @@ Ask a follow-up only when two routes could both be correct and produce different

 All generation requests should be placed into both the current canvas and its same-name asset-library folder. For endpoints that support `assetLabel`, pass it. For UI extraction, use `spritesheetLabel`. For icon spritesheet, the folder is enough. For character animation, the endpoint does not return `asset`; after success call `POST /api/external/v1/editor/assets` using the first returned frame as `imageSrc`, the session `assetFolderId`, and `assetKind: "character-animation"`.

+## HTTP 2xx Warning Handling
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction may return HTTP 2xx while carrying a structured `warning`; completion does not imply that all post-processed derivatives exist.
+
+- Consume the returned `project` and media snapshots as authoritative: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. `warning.code: "postprocess-failed-source-preserved"` means the saved provider source is the main result. Character output has no transparent derivative, while icon spritesheet and UI extraction have no transparent spritesheet and no slices. Display `warning.reason` directly; do not construct missing assets or retry the provider generation from scratch.
+- `sliceWarning` is only for a transparent spritesheet that was created successfully but could not be split automatically. Use the complete transparent spritesheet and preserve `sliceWarning.reason` as the original diagnostic; it is not a post-processing/source-preserved warning.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. If a malformed response contains both, prioritize the general `warning` over `sliceWarning` defensively.
+
 ## Reference Image Upload

 If the user provides a local file as a reference image, run upload before the generation request:
@@ -1,11 +1,11 @@
 ---
 name: gpt-image-2-apimart
-description: Generate or inspect project image assets through this repository's VectorEngine gpt-image-2 workflow. Use when Codex needs to create puzzle template sample images, reproduce the server-rs gpt-image-2 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 VectorEngine

-Use this skill for project-local image asset generation that must match the repository's `server-rs` VectorEngine `gpt-image-2` path. 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

@@ -65,9 +65,9 @@ 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. 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 GPT-image-2 currently returns synchronously; do not poll APIMart task endpoints.
+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.

 ## Environment

@@ -9,6 +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';
+const fallbackImageModel = 'gpt-image-2-c';

 const prompts = [
  {
@@ -165,6 +167,25 @@ function extractBase64Images(payload) {
  return values;
 }

+function decodeStrictBase64Image(raw) {
+  const normalized = String(raw || '').trim();
+  if (
+    !normalized ||
+    normalized.length % 4 !== 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(
+      normalized,
+    )
+  ) {
+    return null;
+  }
+  const bytes = Buffer.from(normalized, 'base64');
+  return bytes.length > 0 &&
+    bytes.toString('base64') === normalized &&
+    inferExtensionFromBytes(bytes)
+    ? bytes
+    : null;
+}
+
 function inferExtensionFromContentType(contentType) {
  const normalized = contentType.split(';')[0]?.trim().toLowerCase();
  if (normalized === 'image/png') {
@@ -192,7 +213,13 @@ function inferExtensionFromBytes(bytes) {
  ) {
    return 'webp';
  }
-  return 'png';
+  if (
+    bytes.subarray(0, 6).toString('ascii') === 'GIF87a' ||
+    bytes.subarray(0, 6).toString('ascii') === 'GIF89a'
+  ) {
+    return 'gif';
+  }
+  return null;
 }

 async function fetchJson(url, options, timeoutMs) {
@@ -205,9 +232,20 @@ async function fetchJson(url, options, timeoutMs) {
    });
    const text = await response.text();
    if (!response.ok) {
-      throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`);
+      const error = new Error(
+        `VectorEngine ${response.status}: ${text.slice(0, 600)}`,
+      );
+      error.vectorEngineStatus = response.status;
+      error.vectorEngineBody = text;
+      throw error;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      error.vectorEngineResponseParse = true;
+      error.vectorEngineBody = text;
+      throw error;
    }
-    return JSON.parse(text);
  } catch (error) {
    if (error?.name === 'AbortError') {
      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
@@ -218,6 +256,83 @@ 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, fallbackImageModel]) {
+    const requestBody = {
+      model,
+      prompt: buildPrompt(entry),
+      n: 1,
+      size: '1024x1024',
+    };
+    try {
+      const payload = await fetchJson(
+        buildVectorEngineImagesGenerationUrl(env.baseUrl),
+        {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${env.apiKey}`,
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(requestBody),
+        },
+        env.timeoutMs,
+      );
+      const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]);
+      if (
+        extractImageUrls(payload)[0] ||
+        base64Image
+      ) {
+        return payload;
+      }
+      const error = new Error(`VectorEngine returned no image for ${entry.id}`);
+      error.vectorEngineResponseParse = true;
+      error.vectorEngineBody = JSON.stringify(payload).slice(0, 600);
+      throw error;
+    } catch (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}`);
+}
+
 async function downloadUrl(url, timeoutMs) {
  const abortController = new AbortController();
  const timer = setTimeout(() => abortController.abort(), timeoutMs);
@@ -244,25 +359,7 @@ async function downloadUrl(url, timeoutMs) {
 }

 async function generateOne(env, entry, outDir) {
-  const requestBody = {
-    model: 'gpt-image-2',
-    prompt: buildPrompt(entry),
-    n: 1,
-    size: '1024x1024',
-  };
-  const payload = await fetchJson(
-    buildVectorEngineImagesGenerationUrl(env.baseUrl),
-    {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${env.apiKey}`,
-        Accept: 'application/json',
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(requestBody),
-    },
-    env.timeoutMs,
-  );
+  const payload = await requestImagePayload(env, entry);

  const urls = extractImageUrls(payload);
  const b64Images = extractBase64Images(payload);
@@ -271,7 +368,10 @@ async function generateOne(env, entry, outDir) {
  if (urls[0]) {
    image = await downloadUrl(urls[0], env.timeoutMs);
  } else if (b64Images[0]) {
-    const bytes = Buffer.from(b64Images[0], 'base64');
+    const bytes = decodeStrictBase64Image(b64Images[0]);
+    if (!bytes) {
+      throw new Error(`VectorEngine returned invalid base64 image for ${entry.id}`);
+    }
    image = {
      bytes,
      extension: inferExtensionFromBytes(bytes),
@@ -304,8 +404,9 @@ if (dryRun) {
        requests: selectedPrompts.map((entry) => ({
          id: entry.id,
          title: entry.title,
+          fallbackModel: fallbackImageModel,
          body: {
-            model: 'gpt-image-2',
+            model: preferredImageModel,
            prompt: buildPrompt(entry),
            n: 1,
            size: '1024x1024',
@@ -14,6 +14,8 @@ const promptsPath = path.join(
 );
 const defaultOutDir = path.join(repoRoot, 'public', 'puzzle-creation-templates');
 const defaultTimeoutMs = 1000000;
+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) {
@@ -131,6 +133,25 @@ function extractBase64Images(payload) {
  return values;
 }

+function decodeStrictBase64Image(raw) {
+  const normalized = String(raw || '').trim();
+  if (
+    !normalized ||
+    normalized.length % 4 !== 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(
+      normalized,
+    )
+  ) {
+    return null;
+  }
+  const bytes = Buffer.from(normalized, 'base64');
+  return bytes.length > 0 &&
+    bytes.toString('base64') === normalized &&
+    inferExtensionFromBytes(bytes)
+    ? bytes
+    : null;
+}
+
 function inferExtensionFromContentType(contentType) {
  const normalized = contentType.split(';')[0]?.trim().toLowerCase();
  if (normalized === 'image/png') {
@@ -158,7 +179,13 @@ function inferExtensionFromBytes(bytes) {
  ) {
    return 'webp';
  }
-  return 'png';
+  if (
+    bytes.subarray(0, 6).toString('ascii') === 'GIF87a' ||
+    bytes.subarray(0, 6).toString('ascii') === 'GIF89a'
+  ) {
+    return 'gif';
+  }
+  return null;
 }

 async function fetchJson(url, options, timeoutMs) {
@@ -171,9 +198,20 @@ async function fetchJson(url, options, timeoutMs) {
    });
    const text = await response.text();
    if (!response.ok) {
-      throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`);
+      const error = new Error(
+        `VectorEngine ${response.status}: ${text.slice(0, 600)}`,
+      );
+      error.vectorEngineStatus = response.status;
+      error.vectorEngineBody = text;
+      throw error;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      error.vectorEngineResponseParse = true;
+      error.vectorEngineBody = text;
+      throw error;
    }
-    return JSON.parse(text);
  } catch (error) {
    if (error?.name === 'AbortError') {
      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
@@ -184,6 +222,83 @@ 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, fallbackImageModel]) {
+    const requestBody = {
+      model,
+      prompt: buildPrompt(template),
+      n: 1,
+      size: '1024x1024',
+    };
+    try {
+      const payload = await fetchJson(
+        buildVectorEngineImagesGenerationUrl(env.baseUrl),
+        {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${env.apiKey}`,
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(requestBody),
+        },
+        env.timeoutMs,
+      );
+      const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]);
+      if (
+        extractImageUrls(payload)[0] ||
+        base64Image
+      ) {
+        return payload;
+      }
+      const error = new Error(`VectorEngine returned no image for ${template.id}`);
+      error.vectorEngineResponseParse = true;
+      error.vectorEngineBody = JSON.stringify(payload).slice(0, 600);
+      throw error;
+    } catch (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}`);
+}
+
 async function downloadUrl(url, timeoutMs) {
  const abortController = new AbortController();
  const timer = setTimeout(() => abortController.abort(), timeoutMs);
@@ -210,25 +325,7 @@ async function downloadUrl(url, timeoutMs) {
 }

 async function generateOne(env, template, outDir) {
-  const requestBody = {
-    model: 'gpt-image-2',
-    prompt: buildPrompt(template),
-    n: 1,
-    size: '1024x1024',
-  };
-  const payload = await fetchJson(
-    buildVectorEngineImagesGenerationUrl(env.baseUrl),
-    {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${env.apiKey}`,
-        Accept: 'application/json',
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(requestBody),
-    },
-    env.timeoutMs,
-  );
+  const payload = await requestImagePayload(env, template);

  const urls = extractImageUrls(payload);
  const b64Images = extractBase64Images(payload);
@@ -237,7 +334,10 @@ async function generateOne(env, template, outDir) {
  if (urls[0]) {
    image = await downloadUrl(urls[0], env.timeoutMs);
  } else if (b64Images[0]) {
-    const bytes = Buffer.from(b64Images[0], 'base64');
+    const bytes = decodeStrictBase64Image(b64Images[0]);
+    if (!bytes) {
+      throw new Error(`VectorEngine returned invalid base64 image for ${template.id}`);
+    }
    image = {
      bytes,
      extension: inferExtensionFromBytes(bytes),
@@ -274,8 +374,9 @@ if (dryRun) {
        requests: selectedTemplates.map((template) => ({
          id: template.id,
          title: template.title,
+          fallbackModel: fallbackImageModel,
          body: {
-            model: 'gpt-image-2',
+            model: preferredImageModel,
            prompt: buildPrompt(template),
            n: 1,
            size: '1024x1024',
@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-cli
-description: SpacetimeDB 2.5 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification.
+description: SpacetimeDB 2.7 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification.
 ---

 # SpacetimeDB CLI
@@ -61,13 +61,38 @@ spacetime describe my-db table users --server http://127.0.0.1:3101 --json
 # Reducer/procedure calls. Arguments are positional JSON values.
 spacetime call --server http://127.0.0.1:3101 my-db my_reducer '"value"' '123'

-# 2.5 accepts hex strings for Identity arguments without full JSON tuple syntax.
+# 2.5+ accepts hex strings for Identity arguments without full JSON tuple syntax.
 spacetime call --server http://127.0.0.1:3101 my-db reducer_needing_identity 0xabc123...

 # Subscribe from CLI
 spacetime subscribe my-db "SELECT * FROM users" --num-updates 10 --server http://127.0.0.1:3101
 ```

+## Standalone MCP Endpoint (2.7)
+
+SpacetimeDB 2.7 standalone exposes an authenticated JSON-RPC MCP endpoint at
+`POST /v1/database/{name_or_identity}/mcp`. It advertises `ping`, `get_schema`,
+`sql`, and `call`. The SQL and reducer tools execute with the bearer token's
+identity, so keep routine smoke checks read-only.
+
+```bash
+curl -fsS \
+  -H "Authorization: Bearer ${SPACETIME_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"genarrative-smoke","version":"1.0.0"}}}' \
+  http://127.0.0.1:3101/v1/database/my-db/mcp
+
+curl -fsS \
+  -H "Authorization: Bearer ${SPACETIME_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{"message":"genarrative"}}}' \
+  http://127.0.0.1:3101/v1/database/my-db/mcp
+```
+
+For repository upgrade validation, also call `tools/list` and the read-only
+`get_schema` tool against an isolated local database. Do not use `sql` or `call`
+for writes unless that mutation is explicitly in scope.
+
 ## Server & Auth

 ```bash
@@ -102,7 +127,7 @@ curl -fsS http://127.0.0.1:3101/v1/ping
 | Flag | Description |
 |------|-------------|
 | `--server`, `-s` | Target server nickname, host, or URL |
-| `--yes`, `-y` | Non-interactive prompt skipping; in 2.5 prefer scoped values |
+| `--yes`, `-y` | Non-interactive prompt skipping; in 2.6+ use scoped values |
 | `--delete-data`, `-c` | Publish data policy: `always`, `on-conflict`, or `never` |
 | `--module-path`, `-p` | Module project path |
 | `--bin-path`, `-b` | Publish/generate from compiled wasm |
@@ -146,6 +171,8 @@ pid="$(systemctl show spacetimedb.service -p MainPID --value)"

 ## Notes

- Procedure calls are stable in 2.5; module HTTP handlers/webhooks, unstable view features, and RLS remain behind unstable gates per release notes.
- 2.5 fixes `publish --delete-data` config fallback so `spacetime.json` can provide the database name.
+- Procedure calls remain stable in 2.7; module HTTP handlers/webhooks and RLS capabilities still require their documented gates.
+- 2.5 fixed `publish --delete-data` config fallback; 2.6 kept that behavior and improved CLI binary distribution; 2.7 adds `spacetime sql --format json` and database `lock` / `unlock`.
+- The official 2.7.0 Linux release archives and container image currently use the `v2.7.0-hotfix3` asset tag while binaries report `2.7.0`; keep the asset tag distinct from the runtime version check.
+- Do not assume `spacetime version install 2.7.0` selected hotfix3: stale updater metadata can install bare-tag commit `a08663c7...`. For the current release, verify CLI commit `d220349a...` and use the official hotfix3 archive or repository provision flow when it differs.
 - Genarrative scripts should pass `--server` or `--server-url` explicitly instead of relying on CLI defaults.
@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-concepts
-description: Understand SpacetimeDB 2.5 architecture, reducer/procedure/table/view semantics, schema evolution, subscriptions, identity, and Genarrative-specific backend boundaries. Use when designing or reviewing SpacetimeDB-backed features.
+description: Understand SpacetimeDB 2.7 architecture, reducer/procedure/table/view semantics, schema evolution, subscriptions, identity, and Genarrative-specific backend boundaries. Use when designing or reviewing SpacetimeDB-backed features.
 ---

 # SpacetimeDB Core Concepts
@@ -20,7 +20,7 @@ SpacetimeDB is a relational database that also executes application logic in upl

 1. **Reducers are transactional**: they do not return data to callers. Read through subscriptions, read models, views, or BFF endpoints.
 2. **Reducers are deterministic**: no filesystem, network, wall-clock, or external RNG. Use `ctx.timestamp`, `ctx.rng()` / `ctx.random()`, and tables.
-3. **Procedures are stable in 2.5**: they can use explicit transactions and outgoing HTTP via `ctx.http`.
+3. **Procedures are stable in 2.7**: they can use explicit transactions and outgoing HTTP via `ctx.http`.
 4. **Identity comes from context**: use `ctx.sender()` or language equivalent for authorization. Never trust identity passed as an argument.
 5. **Auto-increment IDs are not ordering guarantees**: gaps are normal. Use timestamps or explicit sequence columns for ordering.
 6. **Schema changes need migration discipline**: existing Genarrative table fields must be appended with defaults; update migration code, table catalog, generated bindings, and run `npm run check:spacetime-schema`.
@@ -44,25 +44,25 @@ Reducers are deterministic transactional functions. They are the primary client-

 ## Procedures

-Procedures are stable in 2.5. They can be scheduled, can open explicit transactions with `with_tx` / `try_with_tx`, and can use outgoing HTTP (`ctx.http`).
+Procedures are stable in 2.7. They can be scheduled, can open explicit transactions with `with_tx` / `try_with_tx`, and can use outgoing HTTP (`ctx.http`).

 Genarrative default: keep external provider protocols in `platform-*` and orchestration in `api-server` unless a task explicitly moves a workflow into a module procedure.

-Module HTTP handlers/webhooks, unstable view features, and RLS `client_visibility_filter` remain gated behind unstable according to the 2.5 release notes.
+Module HTTP handlers/webhooks and RLS `client_visibility_filter` remain subject to their documented gates in 2.7.

 ## Views

-Views expose computed read-only data. In 2.4.1 Rust and TypeScript gained primary key support for procedural views; in 2.5 C# gained the same. Clients can receive `OnUpdate` events when subscribed to such views with primary keys. Ensure the view never returns duplicate primary keys, because that can fail view refresh and roll back the triggering transaction.
+Views expose computed read-only data. SpacetimeDB 2.7 supports primary keys on procedural views in Rust, TypeScript, C#, and C++. Clients can receive update events when subscribed to such views with primary keys. Ensure the view never returns duplicate primary keys, because that can fail view refresh and roll back the triggering transaction.

 ## Event Tables

 Event tables broadcast reducer/procedure-specific facts to subscribers and must be subscribed explicitly. They are excluded from `subscribe_to_all_tables()`.

-2.5 adds broader layout-altering automigrations for event tables, including column removal, reordering, and type changes that regular tables reject. This relaxed migration behavior is for event-only tables, not persistent tables.
+Since 2.6, event tables support broader layout-altering automigrations, including column removal, reordering, and type changes that regular tables reject. This relaxed migration behavior is for event-only tables, not persistent tables.

 Event-table primary keys and constraints are transaction-scoped. They can reject duplicate event rows within one transaction, but event rows are not retained in client cache, so clients observe event tables through insert callbacks only. Do not design Genarrative event tables around `OnUpdate` / `on_update` / `onUpdate`; use a persistent table or a primary-keyed procedural view when update callbacks are required.

-Official 2.4.1/2.5 release notes document primary-key-backed update callbacks for procedural views, not event tables.
+Official 2.4.1 through 2.7 release notes document primary-key-backed update callbacks for procedural views, not event tables.

 ## Subscriptions

@@ -78,7 +78,18 @@ Best practices:
 - Avoid overlapping queries that duplicate row delivery.
 - Use indexes for subscribed filters.

-## 2.2.0 to 2.5.0 Delta
+## Standalone MCP
+
+SpacetimeDB 2.7 standalone exposes `POST /v1/database/{name_or_identity}/mcp`
+using MCP JSON-RPC protocol `2025-06-18`. Its tools are `ping`, `get_schema`,
+`sql`, and `call`; SQL and reducer calls run with the authenticated caller's
+identity. In Genarrative this is an operator/developer integration surface, not
+a replacement for `api-server` BFF routes, `spacetime-client` facades, or public
+read models. Upgrade smoke should use an isolated local database and restrict
+itself to `initialize`, `tools/list`, `ping`, and `get_schema` unless writes are
+explicitly intended.
+
+## 2.2.0 to 2.7.0 Delta

 Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:

@@ -87,6 +98,9 @@ Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:
 - **2.4.0**: unstable module HTTP handlers/webhooks, faster synchronous WASM reducer runtime, commitlog resume truncation fix for silent data loss risk, better commitlog decode context, V8 heap metrics for procedure workers, JS execution-time billing regression reverted.
 - **2.4.1**: Rust and TypeScript procedural views can declare primary keys, enabling `OnUpdate` events for subscribed views; fixed index schema from ST tables.
 - **2.5.0**: procedures are stable, C# procedural views gain primary keys, event tables allow broader layout-altering automigrations, BTreeSet storage makes row insertion deterministic and avoids accidentally quadratic bulk insert behavior, `wasm_memory_bytes` billing metric semantics changed, template version constraints unified, `publish --delete-data` config fallback fixed, CLI `call` accepts hex Identity arguments.
+- **2.6.0**: procedural-view primary keys are available across Rust, TypeScript, and C#, commitlog gains `max_segment_size` / `write_buffer_size` / `preallocate_segments`, the default write buffer increases for throughput, event-table automigrations improve, and CLI binary distribution expands.
+- **2.6.1**: procedure contexts again receive the caller `Identity` and `ConnectionId`; generated TypeScript `Option<T>` fields use optional keys; `spacetime init --template` lists available templates when no template argument is supplied.
+- **2.7.0**: existing tables can add unique or primary-key constraints when current data satisfies them; standalone exposes an authenticated database MCP endpoint; Rust adds context-capability and table-accessor traits; `spacetime sql --format json` and database locking are available; view cleanup, backing-table migration, connection metrics, and memory metrics improve. Official current release assets use the `v2.7.0-hotfix3` tag while binaries report `2.7.0`.

 ## Debugging Checklist

@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-rust
-description: Develop SpacetimeDB 2.5 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.
+description: Develop SpacetimeDB 2.7 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.
 ---

 # SpacetimeDB Rust Module Development
@@ -28,7 +28,7 @@ ctx.db.player.find(id)          // Use ctx.db.player().id().find(&id)
 ctx.sender                      // Use ctx.sender()
 ctx.db.user().name().update(..) // Update by primary key only

-spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures in 2.5
+spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures since 2.5
 ```

 ## Required Patterns
@@ -181,11 +181,11 @@ fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) {

 Event tables must be subscribed explicitly and are excluded from `subscribe_to_all_tables()`.

-In 2.5, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.
+Since 2.6, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.

 Event-table primary keys and constraints are enforced only within the current transaction. They do not make event rows persistent, and client SDKs expose event tables as insert-only event streams. Do not rely on `OnUpdate` / `on_update` / `onUpdate` for event tables; use a persistent table or a primary-keyed procedural view when update callbacks are required.

-Official 2.4.1/2.5 release notes tie primary-key-backed update callbacks to procedural views, not event tables.
+Official 2.4.1 through 2.7 release notes tie primary-key-backed update callbacks to procedural views, not event tables.

 ## Views

@@ -228,7 +228,7 @@ For scheduled reducers, check `ctx.sender_auth().is_internal()` when the reducer

 ## Procedures

-Procedures are stable in 2.5 and no longer require the `unstable` feature.
+Procedures remain stable in 2.7 and no longer require the `unstable` feature.

 ```rust
 use spacetimedb::{procedure, ProcedureContext};
@@ -1,5 +1,7 @@
 # 微信小程序 web-view 登录配置。
 # 留空时不覆盖已有微信网页 OAuth 配置；正式联调时再填小程序 AppID / AppSecret。
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false
+
 WECHAT_MINI_PROGRAM_APP_ID=""
 WECHAT_MINI_PROGRAM_APP_SECRET=""
 WECHAT_JS_CODE_SESSION_ENDPOINT=""
@@ -1,11 +1,12 @@
 # Server-side OpenAI-compatible LLM endpoint base URL.
-LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
+LLM_BASE_URL="https://api.vectorengine.cn/v1"

 # Server-side API key used by the local Vite proxy.
-# Recommended: set `LLM_API_KEY` or `ARK_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.
-LLM_API_KEY="YOUR_API_KEY"
+LLM_API_KEY=""

 # Optional frontend override for the local proxy path.
 VITE_LLM_PROXY_BASE_URL="/api/llm"
@@ -103,6 +104,8 @@ WECHAT_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/sns/oauth2/access_token"
 WECHAT_USER_INFO_ENDPOINT="https://api.weixin.qq.com/sns/userinfo"
 WECHAT_JS_CODE_SESSION_ENDPOINT="https://api.weixin.qq.com/sns/jscode2session"
 WECHAT_STABLE_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/cgi-bin/stable_token"
+WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT="https://api.weixin.qq.com/xpay/query_order"
+WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_NOTIFY_PROVIDE_GOODS_ENDPOINT="https://api.weixin.qq.com/xpay/notify_provide_goods"
 WECHAT_PHONE_NUMBER_ENDPOINT="https://api.weixin.qq.com/wxa/business/getuserphonenumber"
 WECHAT_STATE_TTL_MINUTES="15"
 WECHAT_MOCK_USER_ID="wx-mock-user"
@@ -111,27 +114,19 @@ WECHAT_MOCK_DISPLAY_NAME="微信旅人"
 WECHAT_MOCK_AVATAR_URL=""
 WECHAT_MINIPROGRAM_MESSAGE_TOKEN=""
 WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=""
-WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED="true"
-WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID="m5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU"
-WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE="formal"
-
 # Model name for chat completions.
-VITE_LLM_MODEL="doubao-1-5-pro-32k-character-250715"
-
-# Optional: enable upstream web search for RPG story text generation.
-RPG_LLM_WEB_SEARCH_ENABLED="true"
+VITE_LLM_MODEL="gpt-5.4-mini"
+GENARRATIVE_LLM_PROVIDER="openai-compatible"
+GENARRATIVE_LLM_BASE_URL="https://api.vectorengine.cn/v1"
+GENARRATIVE_LLM_API_KEY=""
+GENARRATIVE_LLM_MODEL="gpt-5.4-mini"

 # Server-side DashScope endpoint and API key used by the local scene-image proxy.
 DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/api/v1"
 DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

-# APIMart Responses config for creative-agent text/multimodal understanding.
-APIMART_BASE_URL="https://api.apimart.ai/v1"
-APIMART_API_KEY="YOUR_APIMART_API_KEY"
-APIMART_IMAGE_REQUEST_TIMEOUT_MS="180000"
-
-# VectorEngine GPT-image-2 / Gemini image generation config.
-VECTOR_ENGINE_BASE_URL="https://api.vectorengine.ai"
+# VectorEngine LLM and GPT-image-2 / Gemini image generation config.
+VECTOR_ENGINE_BASE_URL="https://api.vectorengine.cn"
 VECTOR_ENGINE_API_KEY=""
 VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS="1000000"

@@ -148,6 +143,19 @@ ALIYUN_OSS_POST_EXPIRE_SECONDS="600"
 ALIYUN_OSS_POST_MAX_SIZE_BYTES="20971520"
 ALIYUN_OSS_SUCCESS_ACTION_STATUS="200"

+# BgFilter 受限资源 worker。父 api-server / external-generation-worker 与唯一的
+# `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 进程必须使用同一个内部 Token。
+# `npm run dev` 与 `npm run dev:api-server` 都会自动带起并验活唯一 worker，不要再开第二个终端重复启动。
+# 只有需要脱离父 API 单独验证 worker 时才运行 `npm run dev:bgfilter-worker`；不要让 `all` 角色兼任它。
+GENARRATIVE_BGFILTER_WORKER_HOST="127.0.0.1"
+GENARRATIVE_BGFILTER_WORKER_PORT="8083"
+GENARRATIVE_BGFILTER_WORKER_BASE_URL="http://127.0.0.1:8083"
+GENARRATIVE_BGFILTER_INTERNAL_TOKEN="CHANGE_ME_FOR_LOCAL"
+GENARRATIVE_BGFILTER_WORKER_CONCURRENCY="16"
+GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS="5000"
+GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS="2048"
+GENARRATIVE_BGFILTER_WORKER_CONNECT_TIMEOUT_MS="2000"
+
 # SpacetimeDB 数据目录备份到 OSS。备份 bucket 可与资源 bucket 分离；未设置时脚本回退使用 ALIYUN_OSS_BUCKET。
 GENARRATIVE_DATABASE_BACKUP_DATA_DIR=""
 GENARRATIVE_DATABASE_BACKUP_WORK_DIR=""
@@ -199,6 +207,10 @@ VITE_LLM_DEBUG_LOG="false"
 # Set to "true" to expose local diagnostic panels, or "false" to hide them.
 VITE_DEBUG_MODE=""

+# Optional: show the image editor right-side Agent entry at runtime.
+# This is read by api-server and exposed through /api/runtime/frontend-config.
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
+
 # 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.
@@ -29,6 +29,7 @@ GENARRATIVE_LLM_PROVIDER="ark"
 GENARRATIVE_LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
 GENARRATIVE_LLM_API_KEY="eb750614-e0b5-402a-bfea-4224862d251e"
 GENARRATIVE_LLM_MODEL="doubao-1-5-pro-32k-character-250715"
+GENARRATIVE_EDITOR_BGFILTER_BASE_URL="https://u1082648-b442-cd409e05.westx.seetacloud.com:8443"
 APIMART_BASE_URL="https://api.apimart.ai/v1"
 APIMART_API_KEY=""
 APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
@@ -36,12 +37,15 @@ DASHSCOPE_SCENE_IMAGE_MODEL="wan2.2-t2i-flash"
 DASHSCOPE_REFERENCE_IMAGE_MODEL="qwen-image-2.0"
 DASHSCOPE_COVER_IMAGE_MODEL="wan2.2-t2i-flash"
 ARK_CHARACTER_VIDEO_REQUEST_TIMEOUT_MS=420000
+
 # 启用服务端大模型调试日志（记录所有输入输出）
 LLM_DEBUG_LOG="true"

 # 注意：不要在客户端启用调试日志，避免敏感数据泄露
 # VITE_LLM_DEBUG_LOG="false"

+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=true
+
 ALIYUN_OSS_BUCKET="xushi-dev"
 ALIYUN_OSS_REGION="oss-cn-beijing"
 ALIYUN_OSS_ENDPOINT="oss-cn-beijing.aliyuncs.com"
@@ -24,6 +24,104 @@ module.exports = {
        'no-console': 'off',
      },
    },
+    {
+      files: ['**/scripts/**/*.{ts,js,mjs,cjs}'],
+      rules: {
+        'no-console': 'off',
+      },
+    },
+    {
+      files: ['**/*.test.{ts,tsx,js,mjs,cjs}'],
+      rules: {
+        'no-console': 'off',
+        'unused-imports/no-unused-vars': 'off',
+      },
+    },
+    {
+      files: ['miniprogram/**/*.js'],
+      globals: {
+        App: 'readonly',
+      },
+    },
+    {
+      files: [
+        'apps/admin-web/src/pages/*.tsx',
+        'src/components/platform-entry/PlatformMobileHomeWelcomeDialog.tsx',
+      ],
+      rules: {
+        'react-refresh/only-export-components': 'off',
+      },
+    },
+    {
+      files: ['src/components/platform-entry/PlatformEntryFlowShellImpl.tsx'],
+      rules: {
+        'react-hooks/exhaustive-deps': 'off',
+      },
+    },
+    {
+      files: [
+        'src/active-main.tsx',
+        'src/ActiveApp.tsx',
+        'src/AuthenticatedApp.tsx',
+        'src/hooks/useGameSettings.ts',
+        'src/routing/activeApp*.ts',
+        'src/routing/activeApp*.tsx',
+        'src/components/auth/**/*.{ts,tsx}',
+        'src/components/common/**/*.{ts,tsx}',
+        'src/components/creation-home/**/*.{ts,tsx}',
+        'src/components/image-editor/**/*.{ts,tsx}',
+        'src/components/project/**/*.{ts,tsx}',
+        'src/components/platform-entry/PlatformActiveProfileView*.tsx',
+        'src/components/platform-entry/PlatformEntryActiveFlowShell*.tsx',
+        'src/components/platform-entry/PlatformEntryFlowShell.tsx',
+        'src/components/platform-entry/PlatformProfileApiKeysModal.tsx',
+        'src/components/platform-entry/PlatformProfileModalShell.tsx',
+        'src/components/platform-entry/PlatformProfilePrimitives.tsx',
+        'src/components/platform-entry/PlatformProfileRechargeModal.tsx',
+        'src/components/platform-entry/PlatformProfileReferralModal.tsx',
+        'src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.tsx',
+        'src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx',
+        'src/components/platform-entry/PlatformRechargePaymentStatusDialogs.tsx',
+        'src/components/platform-entry/platformActiveProfileModel.ts',
+        'src/components/platform-entry/platformEntryActiveTypes.ts',
+        'src/components/platform-entry/platformProfileFundsModel.ts',
+        'src/components/platform-entry/platformProfileHostClipboard.ts',
+        'src/components/platform-entry/usePlatformProfileCenterController.ts',
+        'src/services/image-editor/**/*.{ts,tsx}',
+        'src/services/platform-entry/**/*.{ts,tsx}',
+      ],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              {
+                group: [
+                  '**/components/rpg-entry/**',
+                  '**/components/*-creation/**',
+                  '**/components/*-result/**',
+                  '**/components/*-runtime/**',
+                  '**/components/creation-agent/**',
+                  '**/components/creative-agent/**',
+                  '**/components/custom-world-*/**',
+                  '**/components/unified-creation/**',
+                  '**/services/rpg-entry/**',
+                  '**/services/rpg-runtime/**',
+                  '**/services/*-creation/**',
+                  '**/services/*-runtime/**',
+                  '**/services/*-works/**',
+                  '**/services/creation-agent/**',
+                  '**/services/creative-agent/**',
+                  '**/services/puzzle-*/**',
+                  '**/services/storyEngine/**',
+                ],
+                message: '现役前端不得重新导入已退役的创作模板模块。',
+              },
+            ],
+          },
+        ],
+      },
+    },
    {
      files: ['src/components/game-canvas/**/*.tsx'],
      rules: {
@@ -37,12 +135,6 @@ module.exports = {
        'simple-import-sort/exports': 'off',
      },
    },
-    {
-      files: ['src/components/match3d-runtime/Match3DPhysicsBoard.tsx'],
-      rules: {
-        'react-refresh/only-export-components': 'off',
-      },
-    },
  ],
  plugins: [
    '@typescript-eslint',
@@ -61,7 +153,242 @@ module.exports = {
    'dist',
    'dist_check',
    'dist_check_monster_position',
+    'coverage',
+    'build',
+    'output',
+    'retired/**',
    'node_modules',
+    'server-rs/target',
+    'server-rs/target-*',
+    'apps/desktop-shell/src-tauri/target',
+    'target',
+    'src/main.tsx',
+    'src/App.tsx',
+    'src/routing/appPageRoutes.ts',
+    'src/routing/appPageRoutes.test.ts',
+    'src/routing/appRoutes.tsx',
+    'src/routing/appRoutes.test.ts',
+    'src/services/appTitle.ts',
+    'src/services/appTitle.test.ts',
+    'src/components/CharacterAnimator.tsx',
+    'src/components/*.ts',
+    'src/components/*.tsx',
+    '!src/components/ResolvedAssetAudio.tsx',
+    '!src/components/ResolvedAssetImage.tsx',
+    '!src/components/ResolvedAssetVideo.tsx',
+    'src/hooks/*.ts',
+    'src/hooks/*.tsx',
+    '!src/hooks/useGameSettings.ts',
+    '!src/hooks/useHostNavigationCanGoBack.ts',
+    '!src/hooks/useHostNavigationCanGoBack.test.tsx',
+    '!src/hooks/useResolvedAssetReadUrl.ts',
+    '!src/hooks/useResolvedAssetReadUrl.test.tsx',
+    'src/persistence/*.ts',
+    'src/persistence/*.tsx',
+    '!src/persistence/gameSettingsStorage.ts',
+    '!src/persistence/gameSettingsStorage.test.ts',
+    '!src/persistence/storage.ts',
+    '!src/persistence/storage.test.ts',
+    'src/routing/*.ts',
+    'src/routing/*.tsx',
+    '!src/routing/activeAppPageRoutes.ts',
+    '!src/routing/activeAppPageRoutes.test.ts',
+    '!src/routing/activeAppRoutes.tsx',
+    '!src/routing/activeAppRoutes.test.ts',
+    'src/services/*.ts',
+    'src/services/*.tsx',
+    '!src/services/activeAppTitle.ts',
+    '!src/services/activeAppTitle.test.ts',
+    '!src/services/apiClient.ts',
+    '!src/services/apiClient.test.ts',
+    '!src/services/assetReadUrlService.ts',
+    '!src/services/assetReadUrlService.test.ts',
+    '!src/services/authService.ts',
+    '!src/services/authService.test.ts',
+    '!src/services/clipboard.ts',
+    '!src/services/clipboard.test.ts',
+    '!src/services/frontendRuntimeConfigService.ts',
+    '!src/services/frontendRuntimeConfigService.test.ts',
+    '!src/services/sseStream.ts',
+    '!src/services/sseStream.test.ts',
+    'src/AdventurePanel.tsx',
+    'src/AdventureEntityModal.tsx',
+    'src/App.tsx',
+    'src/App.test.tsx',
+    'src/CharacterCreation.tsx',
+    'src/RpgRuntimeApp.tsx',
+    'src/routing/appPageRoutes.ts',
+    'src/routing/appPageRoutes.test.ts',
+    'src/routing/appRoutes.tsx',
+    'src/routing/appRoutes.test.ts',
+    'src/*PlaygroundApp.tsx',
+    'src/ChildMotionDemoApp.tsx',
+    'src/Match3DPlaygroundApp.tsx',
+    'src/components/child-motion-demo/**',
+    'src/components/asset-studio/**',
+    'src/components/bark-battle-creation/**',
+    'src/components/big-fish-creation/**',
+    'src/components/big-fish-result/**',
+    'src/components/big-fish-runtime/**',
+    'src/components/creation-agent/**',
+    'src/components/creative-agent/**',
+    'src/components/custom-world-agent/**',
+    'src/components/custom-world-home/**',
+    'src/components/edutainment-creation/**',
+    'src/components/edutainment-result/**',
+    'src/components/edutainment-runtime/**',
+    'src/components/game-canvas/**',
+    'src/components/jump-hop-result/**',
+    'src/components/jump-hop-runtime/**',
+    'src/components/match3d-result/**',
+    'src/components/match3d-runtime/**',
+    'src/components/puzzle-clear-creation/**',
+    'src/components/puzzle-clear-result/**',
+    'src/components/puzzle-clear-runtime/**',
+    'src/components/puzzle-gallery/**',
+    'src/components/puzzle-result/**',
+    'src/components/puzzle-runtime/**',
+    'src/components/rpg-creation-asset-studio/**',
+    'src/components/rpg-creation-result/**',
+    'src/components/rpg-runtime-panels/**',
+    'src/components/square-hole-creation/**',
+    'src/components/square-hole-result/**',
+    'src/components/square-hole-runtime/**',
+    'src/components/unified-creation/**',
+    'src/components/visual-novel-creation/**',
+    'src/components/visual-novel-result/**',
+    'src/components/visual-novel-runtime/**',
+    'src/components/wooden-fish-result/**',
+    'src/components/wooden-fish-runtime/**',
+    'src/components/common/PublishShare*',
+    'src/components/common/publishShare*',
+    'src/components/platform-entry/PlatformEntryCreation*',
+    'src/components/platform-entry/PlatformEntryFlowShellImpl.tsx',
+    'src/components/platform-entry/platformEntryTypes.ts',
+    'src/components/platform-entry/PlatformEntryHome*',
+    'src/components/platform-entry/PlatformEntryWorld*',
+    'src/components/platform-entry/PlatformMobileHome*',
+    'src/components/platform-entry/PlatformWork*',
+    'src/components/platform-entry/PlatformDraft*',
+    'src/components/platform-entry/PlatformTask*',
+    'src/components/platform-entry/PlatformError*',
+    'src/components/platform-entry/barkBattle*',
+    'src/components/platform-entry/platformCreation*',
+    'src/components/platform-entry/platformDialog*',
+    'src/components/platform-entry/platformDraft*',
+    'src/components/platform-entry/platformEdutainment*',
+    'src/components/platform-entry/platformEntryCreation*',
+    'src/components/platform-entry/platformExternal*',
+    'src/components/platform-entry/platformGeneration*',
+    'src/components/platform-entry/platformHost*',
+    'src/components/platform-entry/platformMiniGame*',
+    'src/components/platform-entry/platformPlayed*',
+    'src/components/platform-entry/platformPublic*',
+    'src/components/platform-entry/platformPuzzle*',
+    'src/components/platform-entry/platformRecommend*',
+    'src/components/platform-entry/platformRpg*',
+    'src/components/platform-entry/platformSelection*',
+    'src/components/platform-entry/puzzleDraft*',
+    'src/components/platform-entry/usePlatformCreation*',
+    'src/components/platform-entry/usePlatformEntry*',
+    'src/components/platform-entry/PlatformEntryFlowShellImpl/**',
+    'src/components/platform-entry/platformMatch3DRuntimeProfile*',
+    'src/components/unified-creation/workspaces/JumpHopCreationWorkspace*',
+    'src/components/unified-creation/workspaces/Match3DCreationWorkspace*',
+    'src/components/rpg-creation-editor/**',
+    'src/components/rpg-entry/**',
+    'src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx',
+    'src/components/custom-world-home/CustomWorldCreationHub.test.tsx',
+    'src/components/custom-world-home/CustomWorldCreationHub.testAdapter.tsx',
+    'src/components/custom-world-home/creationWorkShelf.test.ts',
+    'src/components/rpg-runtime-shell/**',
+    'src/hooks/rpg-runtime-story/**',
+    'src/hooks/rpg-session/**',
+    'src/hooks/combat/**',
+    'src/hooks/useCombatFlow.ts',
+    'src/hooks/useStoryOptions.ts',
+    'src/prompts/customWorldPrompts.ts',
+    'src/services/ai.ts',
+    'src/services/appTitle.ts',
+    'src/services/appTitle.test.ts',
+    'src/services/miniGameDraftGenerationProgress.ts',
+    'src/services/creationEntryConfigService.ts',
+    'src/services/creationUrlState*',
+    'src/services/customWorld*',
+    'src/services/input-devices/**',
+    'src/services/publicWorkCode.ts',
+    'src/services/runtimeGuestAuth.ts',
+    'src/services/runtimeRequest*',
+    'src/services/runtimeAudioFeedback.ts',
+    'src/services/useMocapInput*',
+    'src/services/wechatMiniProgramSubscribe*',
+    'src/services/bark-battle-creation/**',
+    'src/services/bark-battle-runtime/**',
+    'src/services/big-fish-creation/**',
+    'src/services/big-fish-gallery/**',
+    'src/services/big-fish-runtime/**',
+    'src/services/big-fish-works/**',
+    'src/services/creation-agent/**',
+    'src/services/creation-audio/**',
+    'src/services/creative-agent/**',
+    'src/services/edutainment-baby-drawing/**',
+    'src/services/edutainment-baby-object/**',
+    'src/services/child-motion-demo/**',
+    'src/services/jump-hop/**',
+    'src/services/match3d-creation/**',
+    'src/services/match3d-runtime/**',
+    'src/services/match3d-works/**',
+    'src/services/match3dGeneratedModelCache*',
+    'src/services/match3dSpritesheetParser*',
+    'src/services/puzzle-agent/**',
+    'src/services/puzzle-gallery/**',
+    'src/services/puzzle-onboarding/**',
+    'src/services/puzzle-runtime/**',
+    'src/services/puzzle-works/**',
+    'src/services/rpg-creation/**',
+    'src/services/rpg-entry/**',
+    'src/services/rpg-runtime/**',
+    'src/services/square-hole-creation/**',
+    'src/services/square-hole-runtime/**',
+    'src/services/square-hole-works/**',
+    'src/services/storyEngine/**',
+    'src/services/visual-novel-creation/**',
+    'src/services/visual-novel-runtime/**',
+    'src/services/visual-novel-works/**',
+    'src/services/wooden-fish/**',
+    'src/types.ts',
+    'src/types/**',
+    'src/uiAssets.ts',
+    'scripts/loadtest/**',
+    'packages/shared/src/contracts/jumpHop.ts',
+    'packages/shared/src/contracts/match3dAgent.ts',
+    'packages/shared/src/contracts/match3dRuntime.ts',
+    'packages/shared/src/contracts/match3dWorks.ts',
+    'packages/shared/src/contracts/barkBattle*',
+    'packages/shared/src/contracts/bigFish*',
+    'packages/shared/src/contracts/creationAgent*',
+    'packages/shared/src/contracts/creationAudio*',
+    'packages/shared/src/contracts/creativeAgent*',
+    'packages/shared/src/contracts/customWorld*',
+    'packages/shared/src/contracts/edutainment*',
+    'packages/shared/src/contracts/playTypes*',
+    'packages/shared/src/contracts/publicWork*',
+    'packages/shared/src/contracts/puzzle*',
+    'packages/shared/src/contracts/rpg*',
+    'packages/shared/src/contracts/squareHole*',
+    'packages/shared/src/contracts/story*',
+    'packages/shared/src/contracts/visualNovel*',
+    'packages/shared/src/contracts/woodenFish*',
+    'scripts/export-match3d-resource-pipeline*',
+    'scripts/generate-child-motion-demo-assets.mjs',
+    'src/services/puzzle-clear/**',
+    'src/games/**',
+    'src/data/**',
+    'src/prompts/**',
+    'apps/admin-web/src/pages/AdminCreationEntrySwitchPage*',
+    'apps/admin-web/src/pages/AdminWorkVisibilityPage*',
+    'src/services/recommendedRuntimeGuestLaunch.test.ts',
+    'src/data/sceneEncounterPreviews.ts',
    'public/Icons',
    'media',
    '.codex-logs',
@@ -78,7 +405,10 @@ module.exports = {
  rules: {
    '@typescript-eslint/no-var-requires': 'off',
    'react-hooks/rules-of-hooks': 'error',
-    'react-refresh/only-export-components': ['error', {allowConstantExport: true}],
+    'react-refresh/only-export-components': [
+      'error',
+      { allowConstantExport: true },
+    ],
    'simple-import-sort/imports': 'error',
    'simple-import-sort/exports': 'error',
    '@typescript-eslint/no-unused-vars': 'off',
@@ -91,7 +421,7 @@ module.exports = {
      },
    ],
    'no-constant-condition': 'error',
-    'no-console': ['error', {allow: ['warn', 'error']}],
+    'no-console': ['error', { allow: ['warn', 'error'] }],
    'no-useless-escape': 'error',
    'prefer-const': 'error',
  },
@@ -0,0 +1,193 @@
+name: Project CI
+
+on:
+  push:
+    branches:
+      - master
+      - codex/ai-game-creator-app
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CI: 'true'
+  CARGO_INCREMENTAL: '0'
+  CARGO_HTTP_MULTIPLEXING: 'false'
+  CARGO_NET_RETRY: '10'
+  CARGO_TERM_COLOR: always
+  NPM_CONFIG_AUDIT: 'false'
+  NPM_CONFIG_FETCH_RETRIES: '10'
+  NPM_CONFIG_FETCH_RETRY_FACTOR: '2'
+  NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT: '60000'
+  NPM_CONFIG_FETCH_RETRY_MINTIMEOUT: '2000'
+  NPM_CONFIG_FUND: 'false'
+  NPM_CONFIG_PREFER_OFFLINE: 'true'
+  RUSTUP_AUTO_INSTALL: '0'
+  RUSTC_WRAPPER: ''
+  CARGO_BUILD_RUSTC_WRAPPER: ''
+
+jobs:
+  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
+          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: npm ci
+
+      - name: Run repository lint gates
+        run: npm run lint
+
+      - name: Build web applications
+        run: npm run build
+
+      - name: Validate content data
+        run: npm run check:content
+
+      - name: Check committed whitespace
+        shell: bash
+        run: |
+          set -euo pipefail
+          base_ref="${SPACETIME_SCHEMA_BASE_REF:-}"
+          test -n "${base_ref}"
+          git cat-file -e "${base_ref}^{commit}"
+          git diff --check "${base_ref}"...HEAD
+
+  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: npm ci
+
+      - 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
+
+  backend-tests:
+    name: Backend 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: 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
+          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: npm ci
+
+      - name: Check server-rs boundaries
+        run: npm run check:server-rs-ddd
+
+      - name: Run server-rs workspace tests
+        run: cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml
+
+      - name: Check api-server targets
+        run: cargo check --locked -p api-server --all-targets --manifest-path server-rs/Cargo.toml
+
+      - name: Check SpacetimeDB module
+        run: cargo check --locked -p spacetime-module --manifest-path server-rs/Cargo.toml
+
+  native-shell-tests:
+    name: Native shell 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: npm ci
+
+      - name: Run native shell gates
+        run: npm run check:native-shells
+
+      - name: Ensure native lockfile is unchanged
+        run: git diff --exit-code -- apps/desktop-shell/src-tauri/Cargo.lock
@@ -42,6 +42,7 @@ temp*build*/
 /.app/
 /target/
 /logs
+/.claude/settings.local.json
 /.codegraph/
 /.playwright-cli/
 **/.playwright-cli/
@@ -50,6 +51,7 @@ temp*build*/
 .worktrees/
 .rag/
 .env.secrets.local
+nohup.out
 spacetime.local.json
 deploy/container/api-server.env
 deploy/container/worker-smoke/
@@ -1,8 +1,8 @@
 ---
 name: genarrative-dev-stack-port-routing
 short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。
-description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
-version: 1.0.0
+description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:bgfilter-worker / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、Rust 进程环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -13,7 +13,7 @@ metadata:

 # Genarrative 本地 dev 启动端口与代理目标串联流程

-用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与四个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。
+用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与五个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。

 ## 适用场景

@@ -31,40 +31,44 @@ metadata:
 2. Rust `api-server`：`8082`，健康检查为 `http://127.0.0.1:<api-port>/healthz`。
 3. SpacetimeDB standalone：`3101`，健康检查为 `http://127.0.0.1:<spacetime-port>/v1/ping`。
 4. 后台 Vite：`3102`，后台地址为 `http://127.0.0.1:<admin-web-port>/admin/`。
+5. 独立 BgFilter worker：`8083`，就绪检查为 `http://127.0.0.1:<bgfilter-worker-port>/readyz`。

 端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。

-Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有端口探测、漂移和复用逻辑，不读系统级注册表。
+Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`、`bgfilterWorker = start + 4`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有统一端口探测和漂移逻辑，不读系统级注册表。

 ## 实现入口

 - `package.json`
-  - `dev`：执行 `node scripts/dev.mjs`，启动完整四模块。
-  - `dev:spacetime` / `dev:api-server` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs <module>`。
+  - `dev`：执行 `node scripts/dev.mjs`，启动完整五服务。
+  - `dev:spacetime` / `dev:api-server` / `dev:bgfilter-worker` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs <module>`；`dev:api-server` 会安全带起其依赖的 BgFilter worker。
 - `scripts/dev-stack-port-utils.mjs`
  - `isPortAvailable(...)`：探测端口是否可监听。
  - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。
-  - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。
+  - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite、BgFilter worker 端口，并避免本次解析结果互相冲突。
  - Linux 注册表分配：`reserveLinuxDevPortRange(...)` / `releaseLinuxDevPortRange(...)`，仅在 Linux 上启用系统级端口段登记与用户段复用，自动分配从 `10000-10099` 起。
-  - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。
+  - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102 bgfilterWorker:127.0.0.1:8083`。
 - `scripts/dev.mjs`
  - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。
-  - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。
-  - Linux 下会先申请系统级端口段并把它映射成四个 dev 端口；自动分配从 `10000-10099` 起，Windows 则直接沿用原有参数解析与端口漂移逻辑。
+  - 完整栈按 SpacetimeDB、publish、BgFilter worker readiness、api-server readiness、主站 Vite、后台 Vite 顺序启动。
+  - Linux 下会先申请系统级端口段并把它映射成五个 dev 端口；自动分配从 `10000-10099` 起，Windows 则把第五个服务纳入原有统一参数解析与端口漂移逻辑。
+  - 完整栈和 `dev:api-server` 把两个 Rust 进程作为同一重启单元，先全部停止，再先启动 BgFilter worker、后启动 api-server；不要为同一份 Rust 源码创建两个并发 `cargo` watcher。
  - 单模块命令复用同一套参数和 env 解析。

 ## 必须保持的传递链路

-`npm run dev` 和四个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置：
+`npm run dev` 和五个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置：

 1. SpacetimeDB 启动：`spacetime start --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"`。
 2. SpacetimeDB 发布：`spacetime publish ... --server "${SPACETIME_SERVER}"`。
 3. Rust api-server：`GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE`。
 4. api-server 健康检查：`wait_for_api_server "${RUST_SERVER_TARGET}/healthz" ...`。
-5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
-6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
-7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。
-8. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。
+5. BgFilter worker：`GENARRATIVE_PROCESS_ROLE=bgfilter-worker`、解析后的 `HOST / PORT`、与父 API 相同的 `GENARRATIVE_BGFILTER_WORKER_BASE_URL` / `GENARRATIVE_BGFILTER_INTERNAL_TOKEN`，以及显式有效的 `N / Q`。
+6. BgFilter worker readiness：父 API 启动前检查解析后地址的 `/readyz`。
+7. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
+8. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
+9. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/bgfilter-worker/spacetime` 必须显示最终实际地址。
+10. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。

 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。

@@ -74,7 +78,7 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range`
   - `scripts/dev-stack-port-utils.mjs`
   - `scripts/dev.mjs`
   - `scripts/dev-utils.mjs`
-   - `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`
+   - `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
   - `docs/project-memory/shared-memory/pitfalls.md`
 2. 优先改公共端口工具，不要把端口探测逻辑复制到多个脚本。
 3. 修改 `scripts/dev.mjs` 时确认变量顺序：先解析参数和端口，再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`，最后启动对应 service。
@@ -91,21 +95,21 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range`
 node --check scripts/dev.mjs
 npm run test -- scripts/dev-stack-port-utils.test.ts
 npm run check:encoding
-node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0
+node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0 bgfilterWorker:127.0.0.1:0
 ```

 端口冲突回归测试建议：

 1. 用测试或临时 Node server 占用某个优先端口。
 2. 调用 `findAvailablePort`，断言结果大于被占用端口。
-3. 调用 `resolveDevStackPorts`，断言四个结果互不相同。
+3. 调用 `resolveDevStackPorts`，断言五个结果互不相同。
 4. 如果实际启动完整栈，观察控制台：
   - `[dev:ports] ... 不可用，改用 ...`
   - `[dev] api-server: http://...:<actual-api-port>`
   - `[dev] spacetime: http://...:<actual-spacetime-port>`
   - 主站和后台 Vite 启动端口与日志一致。

-完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 `/healthz`、`/v1/ping` 和页面端口；不要等待 `npm run dev` 自然退出。
+完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 api-server `/healthz`、BgFilter worker `/readyz`、SpacetimeDB `/v1/ping` 和两个页面端口；不要等待 `npm run dev` 自然退出。检查地址必须取 `.app/dev-stack.json` 或启动日志中的实际端口，不能假定 worker 一定停在 `8083`。

 ## 常见坑

@@ -122,7 +126,8 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap
 - [ ] Linux 注册表分配、同用户复用固定段并继续漂移、自动分配从 `10000-10099` 起、Windows bypass 都有测试覆盖。
 - [ ] `scripts/dev.mjs` 通过 `node --check`。
 - [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
+- [ ] BgFilter worker 在 api-server 前 ready，父子共享实际 base URL / Token，Rust watch 只触发一次组合重启。
 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。
- [ ] 文档同步更新 `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
+- [ ] 文档同步更新 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 - [ ] 长期踩坑同步更新 `docs/project-memory/shared-memory/pitfalls.md`。
 - [ ] 修改中文文件后运行 `npm run check:encoding`。
@@ -16,6 +16,18 @@ _Avoid_: 在玩法页面内手写上传、参考图、重绘、预览、删除
 独立 `/editor` 中可保存、恢复和继续编辑的图片画布工作状态，包含画布视图、图层布局和资源引用；用于多图对比、生成结果衍生和画布级编辑，不替代玩法页面内的单图资产编辑。
 _Avoid_: 玩法结果页单图槽位、发布态作品、只存在前端内存里的临时画布

+**画布Agent对话**:
+图片画布工程右侧的对话式编辑器工具，用户通过自然语言调度画布已有的图片类生成与编辑能力（生成图片、生成角色形象、生成图标素材、生成 UI 设计图、基于附件的图片修改），并可附加画布素材或素材库图片作为参考；对话归属单个图片画布工程，可保存历史、新开会话和软删会话。属于画布域工具，不承接玩法创作、不产出玩法作品或模板，与「表单/图片输入创作工作台」的 Avoid 边界不冲突。
+_Avoid_: 对话式玩法创作工作台、绕过模型定价收口的生成入口、把对话消息当作画布布局真相、复用拼图专用 creative-agent 内存会话
+
+**画布Agent会话记录**:
+画布Agent对话的持久化形态：SpacetimeDB 表只存会话元数据（会话 ID、所属工程、属主、标题、软删标记、聊天记录 OSS 对象引用、时间戳），完整消息内容以会话粒度 JSON 对象存 OSS，追加消息即整体重写对象。
+_Avoid_: api-server 内存会话、消息全文入 SpacetimeDB 表、对话混入工程布局快照、每条消息一个 OSS 对象
+
+**画布Agent对话附件**:
+画布Agent对话消息携带的图片参考，统一为画布资源 / 素材库对象引用（resourceId / assetId + 可选 objectKey），单条消息上限 9 张；上传图片若从对话入口进入，必须复用素材库 / 画布资源登记链路，在上传格未落地前只从已有画布资源和账号素材库选择，不存在只属于对话的第三种图。
+_Avoid_: 对话私有图片副本、内嵌 base64 附件、音视频附件
+
 **画布资源**:
 图片画布工程中可被一个或多个图层引用的图片资源记录，保存 OSS 对象引用、上传 / 生成来源、提示词、模型、任务和尺寸等资源元数据；同一资源可以在工程布局中出现多次。
 _Avoid_: 图层位置、前端 hover / selected 状态、直接内嵌图片二进制
@@ -44,10 +44,10 @@ npm run dev

 补充说明：

- `npm run dev` 会启动 SpacetimeDB standalone、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调。
+- `npm run dev` 会启动 SpacetimeDB standalone、独立 `bgfilter-worker`、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调；内部 worker ready 后才启动 API。
 - 主站默认地址是 `http://127.0.0.1:3000`，后台可从 `http://127.0.0.1:3000/admin/` 进入，也可直连 `http://127.0.0.1:3102`。
- 四个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:web`、`npm run dev:admin-web`。
- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，`api-server` 改动后会重启 Rust 进程。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。
+- 五个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:web`、`npm run dev:admin-web`；其中 `dev:api-server` 会安全带起同 runner 的 BgFilter worker 依赖。
+- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，Rust 源码改动会把 `api-server` 与 `bgfilter-worker` 作为一个组合单元重启。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs bgfilter-worker`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。

 构建生产包：

@@ -98,21 +98,20 @@ npm run check:content
 主运行时：

 - [src/App.tsx](./src/App.tsx)
- [src/components/GameShell.tsx](./src/components/GameShell.tsx)
+- [src/AuthenticatedApp.tsx](./src/AuthenticatedApp.tsx)
+- [src/routing/appRoutes.tsx](./src/routing/appRoutes.tsx)
 - [src/hooks/useCombatFlow.ts](./src/hooks/useCombatFlow.ts)
- [src/hooks/useStoryGeneration.ts](./src/hooks/useStoryGeneration.ts)

 主流程内嵌编辑能力：

- [src/components/CustomWorldEntityEditorModal.tsx](./src/components/CustomWorldEntityEditorModal.tsx)
- [src/components/CustomWorldNpcVisualEditor.tsx](./src/components/CustomWorldNpcVisualEditor.tsx)
- [src/components/CustomWorldRoleAssetStudioModal.tsx](./src/components/CustomWorldRoleAssetStudioModal.tsx)
+- [src/components/image-editor/ImageCanvasEditorView.tsx](./src/components/image-editor/ImageCanvasEditorView.tsx)
+- [src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx](./src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx)
+- [src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.tsx](./src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.tsx)

 核心数据：

 - [src/data/scenePresets.ts](./src/data/scenePresets.ts)
 - [src/data/characterPresets.ts](./src/data/characterPresets.ts)
- [src/data/monsterPresets.ts](./src/data/monsterPresets.ts)
 - [src/data/npcInteractions.ts](./src/data/npcInteractions.ts)
 - [src/data/treasureInteractions.ts](./src/data/treasureInteractions.ts)

@@ -0,0 +1,299 @@
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  createAdminAccount,
+  executeAdminRechargeRefund,
+  getAdminFeatureGateConfig,
+  getAdminUserDetail,
+  listAdminRechargeOrders,
+  resolveAdminRechargeRefundManualReview,
+  updateAdminAccount,
+  uploadAdminEditorShowcaseCampaignImage,
+  upsertAdminFeatureGateConfig,
+} from './adminApiClient';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () => {
+  const fetchMock = vi.fn().mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ account: { accountId: 'member-1' } }), {
+        status: 200,
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await createAdminAccount('owner-token', {
+    username: 'operator',
+    displayName: '运营',
+    password: 'secret123',
+    tabPermissions: ['dashboard', 'tracking'],
+    enabled: true,
+  });
+  await updateAdminAccount('owner-token', 'member/1', {
+    displayName: '运营二组',
+    tabPermissions: ['tracking'],
+    enabled: false,
+  });
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe('/admin/api/accounts');
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({ Authorization: 'Bearer owner-token' }),
+    }),
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe('/admin/api/accounts/member%2F1');
+  expect(fetchMock.mock.calls[1]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'PUT',
+      body: JSON.stringify({
+        displayName: '运营二组',
+        tabPermissions: ['tracking'],
+        enabled: false,
+      }),
+    }),
+  );
+});
+
+test('灰度配置读写只使用通用 feature-gates 管理接口', async () => {
+  const fetchMock = vi.fn().mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ gates: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await getAdminFeatureGateConfig('gray-token');
+  await upsertAdminFeatureGateConfig('gray-token', {
+    gateKey: 'image-editor:agent-sidebar',
+    enabled: true,
+    rolloutPercent: 25,
+    allowUserIds: ['user-1'],
+    allowUserTags: ['beta'],
+    denyUserIds: ['blocked-1'],
+    description: '画布 Agent 入口灰度',
+  });
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe('/admin/api/feature-gates');
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer gray-token' }),
+    }),
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe('/admin/api/feature-gates');
+  expect(fetchMock.mock.calls[1]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'PUT',
+      headers: expect.objectContaining({ Authorization: 'Bearer gray-token' }),
+      body: JSON.stringify({
+        gateKey: 'image-editor:agent-sidebar',
+        enabled: true,
+        rolloutPercent: 25,
+        allowUserIds: ['user-1'],
+        allowUserTags: ['beta'],
+        denyUserIds: ['blocked-1'],
+        description: '画布 Agent 入口灰度',
+      }),
+    }),
+  );
+});
+
+test('活动卡图片上传成功后先确认正式私有对象再返回图片引用', async () => {
+  const closeBitmap = vi.fn();
+  vi.stubGlobal(
+    'createImageBitmap',
+    vi
+      .fn()
+      .mockResolvedValue({ width: 1024, height: 1536, close: closeBitmap }),
+  );
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          upload: {
+            bucket: 'genarrative-release',
+            host: 'https://genarrative-release.oss.example.com',
+            objectKey:
+              'generated-character-drafts/editor/showcase-campaign/current/card.png',
+            legacyPublicPath:
+              '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+            contentType: 'image/png',
+            formFields: { key: 'campaign-key', policy: 'signed-policy' },
+          },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      ),
+    )
+    .mockResolvedValueOnce(new Response('', { status: 200 }))
+    .mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ assetObject: { assetObjectId: 'assetobj-1' } }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        },
+      ),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+  const file = new File(['image-bytes'], 'card.png', { type: 'image/png' });
+
+  const uploaded = await uploadAdminEditorShowcaseCampaignImage(
+    'admin-token',
+    file,
+  );
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe(
+    '/admin/api/editor-showcase/campaign/image-upload-ticket',
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe(
+    'https://genarrative-release.oss.example.com',
+  );
+  expect(fetchMock.mock.calls[2]?.[0]).toBe(
+    '/admin/api/editor-showcase/campaign/image-upload-confirm',
+  );
+  expect(fetchMock.mock.calls[2]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+      body: JSON.stringify({
+        bucket: 'genarrative-release',
+        objectKey:
+          'generated-character-drafts/editor/showcase-campaign/current/card.png',
+        contentType: 'image/png',
+        contentLength: file.size,
+      }),
+    }),
+  );
+  expect(uploaded).toEqual({
+    imageSrc:
+      '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+    imageObjectKey:
+      'generated-character-drafts/editor/showcase-campaign/current/card.png',
+    imageWidth: 1024,
+    imageHeight: 1536,
+    legacyPublicPath:
+      '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+  });
+  expect(closeBitmap).toHaveBeenCalledOnce();
+});
+
+test('充值订单查询按后台契约序列化筛选参数', async () => {
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ entries: [] }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await listAdminRechargeOrders('token-1', {
+    orderId: 'order 1',
+    userId: 'user-1',
+    providerTransactionId: 'wx-1',
+    paymentChannel: 'wechat_native',
+    status: 'paid',
+    createdAfter: '2026-07-01T00:00:00.000Z',
+    createdBefore: '2026-07-13T23:59:00.000Z',
+    limit: 50,
+  });
+
+  const requestUrl = String(fetchMock.mock.calls[0]?.[0]);
+  const parsed = new URL(requestUrl, 'http://admin.local');
+  expect(parsed.pathname).toBe('/admin/api/profile/recharge-orders');
+  expect(Object.fromEntries(parsed.searchParams)).toEqual({
+    orderId: 'order 1',
+    providerTransactionId: 'wx-1',
+    userId: 'user-1',
+    paymentChannel: 'wechat_native',
+    status: 'paid',
+    createdAfter: '2026-07-01T00:00:00.000Z',
+    createdBefore: '2026-07-13T23:59:00.000Z',
+    limit: '50',
+  });
+});
+
+test('用户详情只发送实际提供的用户定位字段', async () => {
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue(
+      new Response(JSON.stringify({ userId: 'user-1' }), { status: 200 }),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await getAdminUserDetail('token-1', { publicUserCode: 'TN1001' });
+
+  const requestUrl = String(fetchMock.mock.calls[0]?.[0]);
+  const parsed = new URL(requestUrl, 'http://admin.local');
+  expect(parsed.pathname).toBe('/admin/api/profile/users/detail');
+  expect(Object.fromEntries(parsed.searchParams)).toEqual({
+    publicUserCode: 'TN1001',
+  });
+});
+
+test('退款执行使用独立 execute 管理员路由', async () => {
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
+      status: 200,
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await executeAdminRechargeRefund('token-1', {
+    orderId: 'order-1',
+    refundAmountCents: 300,
+    requestId: 'request-1',
+    reason: '用户申请',
+  });
+
+  expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+    '/admin/api/profile/recharge-refunds/execute',
+  );
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      body: JSON.stringify({
+        orderId: 'order-1',
+        refundAmountCents: 300,
+        requestId: 'request-1',
+        reason: '用户申请',
+      }),
+    }),
+  );
+});
+
+test('退款人工复核使用独立 resolve 管理员路由', async () => {
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
+      status: 200,
+    }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await resolveAdminRechargeRefundManualReview('token-1', {
+    outRefundNo: 'refund-1',
+    reason: '已核对微信商户平台原始账单',
+    expectedErrorCode: 'provider_transaction_id_mismatch',
+  });
+
+  expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+    '/admin/api/profile/recharge-refunds/manual-review/resolve',
+  );
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      body: JSON.stringify({
+        outRefundNo: 'refund-1',
+        reason: '已核对微信商户平台原始账单',
+        expectedErrorCode: 'provider_transaction_id_mismatch',
+      }),
+    }),
+  );
+});
@@ -1,4 +1,4 @@
-import {useCallback, useEffect, useState} from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';

 import {
  formatAdminApiError,
@@ -17,25 +17,31 @@ import {
  getStoredAdminToken,
  setStoredAdminToken,
 } from '../auth/adminAuthStore';
-import {AdminCreationEntrySwitchPage} from '../pages/AdminCreationEntrySwitchPage';
-import {AdminDashboardPage} from '../pages/AdminDashboardPage';
-import {AdminDebugHttpPage} from '../pages/AdminDebugHttpPage';
-import {AdminDatabaseTablesPage} from '../pages/AdminDatabaseTablesPage';
-import {AdminInviteCodePage} from '../pages/AdminInviteCodePage';
-import {AdminLoginPage} from '../pages/AdminLoginPage';
-import {AdminEditorGenerationPricingPage} from '../pages/AdminEditorGenerationPricingPage';
-import {AdminEditorAssetQueryPage} from '../pages/AdminEditorAssetQueryPage';
-import {AdminEditorShowcaseReviewPage} from '../pages/AdminEditorShowcaseReviewPage';
-import {AdminOverviewPage} from '../pages/AdminOverviewPage';
-import {AdminProfileWalletConfigPage} from '../pages/AdminProfileWalletConfigPage';
-import {AdminRechargeProductPage} from '../pages/AdminRechargeProductPage';
-import {AdminRedeemCodePage} from '../pages/AdminRedeemCodePage';
-import {AdminTaskConfigPage} from '../pages/AdminTaskConfigPage';
-import {AdminTrackingEventsPage} from '../pages/AdminTrackingEventsPage';
-import {AdminWorkVisibilityPage} from '../pages/AdminWorkVisibilityPage';
-import {AdminShell} from './AdminShell';
-import type {AdminRouteId} from './adminRoutes';
-import {resolveAdminRoute, routeHash} from './adminRoutes';
+import { AdminAccountsPage } from '../pages/AdminAccountsPage';
+import { AdminDashboardPage } from '../pages/AdminDashboardPage';
+import { AdminDatabaseTablesPage } from '../pages/AdminDatabaseTablesPage';
+import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
+import { AdminEditorAssetQueryPage } from '../pages/AdminEditorAssetQueryPage';
+import { AdminEditorGenerationPricingPage } from '../pages/AdminEditorGenerationPricingPage';
+import { AdminEditorShowcaseReviewPage } from '../pages/AdminEditorShowcaseReviewPage';
+import { AdminGrayReleaseConfigPage } from '../pages/AdminGrayReleaseConfigPage';
+import { AdminInviteCodePage } from '../pages/AdminInviteCodePage';
+import { AdminLoginPage } from '../pages/AdminLoginPage';
+import { AdminOverviewPage } from '../pages/AdminOverviewPage';
+import { AdminProfileWalletConfigPage } from '../pages/AdminProfileWalletConfigPage';
+import { AdminRechargeOrderPage } from '../pages/AdminRechargeOrderPage';
+import { AdminRechargeProductPage } from '../pages/AdminRechargeProductPage';
+import { AdminRedeemCodePage } from '../pages/AdminRedeemCodePage';
+import { AdminTaskConfigPage } from '../pages/AdminTaskConfigPage';
+import { AdminTrackingEventsPage } from '../pages/AdminTrackingEventsPage';
+import type { AdminRouteId } from './adminRoutes';
+import {
+  getAccessibleAdminRoutes,
+  resolveAccessibleAdminRoute,
+  resolveAdminRoute,
+  routeHash,
+} from './adminRoutes';
+import { AdminShell } from './AdminShell';

 type SessionStatus = 'checking' | 'guest' | 'authenticated';

@@ -53,6 +59,13 @@ export function AdminApp() {
    useState<ProfileWalletConfigAdminResponse | null>(null);
  const [rechargeProductResult, setRechargeProductResult] =
    useState<ProfileRechargeProductConfigAdminResponse | null>(null);
+  const accessibleRoutes = useMemo(
+    () => (admin ? getAccessibleAdminRoutes(admin) : []),
+    [admin],
+  );
+  const activeRouteId = accessibleRoutes.some((route) => route.id === routeId)
+    ? routeId
+    : null;

  const clearSession = useCallback((message = '') => {
    clearStoredAdminToken();
@@ -105,6 +118,26 @@ export function AdminApp() {
    };
  }, []);

+  useEffect(() => {
+    if (status !== 'authenticated' || !admin) {
+      return;
+    }
+
+    const nextRouteId = resolveAccessibleAdminRoute(
+      window.location.hash,
+      accessibleRoutes,
+    );
+    if (!nextRouteId) {
+      return;
+    }
+
+    setRouteId(nextRouteId);
+    const nextHash = routeHash(nextRouteId);
+    if (window.location.hash !== nextHash) {
+      window.history.replaceState(null, '', nextHash);
+    }
+  }, [accessibleRoutes, admin, routeId, status]);
+
  useEffect(() => {
    const handleHashChange = () => {
      setRouteId(resolveAdminRoute(window.location.hash));
@@ -122,17 +155,20 @@ export function AdminApp() {
    }
  }, []);

-  const handleLogin = useCallback(async (username: string, password: string) => {
-    const response = await loginAdmin(username, password);
-    setStoredAdminToken(response.token);
-    setToken(response.token);
-    setAdmin(response.admin);
-    setTaskConfigResult(null);
-    setProfileWalletConfigResult(null);
-    setRechargeProductResult(null);
-    setLoginNotice('');
-    setStatus('authenticated');
-  }, []);
+  const handleLogin = useCallback(
+    async (username: string, password: string) => {
+      const response = await loginAdmin(username, password);
+      setStoredAdminToken(response.token);
+      setToken(response.token);
+      setAdmin(response.admin);
+      setTaskConfigResult(null);
+      setProfileWalletConfigResult(null);
+      setRechargeProductResult(null);
+      setLoginNotice('');
+      setStatus('authenticated');
+    },
+    [],
+  );

  const handleUnauthorized = useCallback(
    (message = '登录状态已失效') => {
@@ -161,63 +197,56 @@ export function AdminApp() {
  return (
    <AdminShell
      admin={admin}
-      routeId={routeId}
+      routeId={activeRouteId}
+      routes={accessibleRoutes}
      onLogout={handleLogout}
      onRouteChange={handleRouteChange}
    >
-      {routeId === 'dashboard' ? (
+      {activeRouteId === null ? (
+        <section className="admin-panel admin-zero-permission-state">
+          <h2>暂无访问权限</h2>
+        </section>
+      ) : null}
+      {activeRouteId === 'dashboard' ? (
        <AdminDashboardPage token={token} onUnauthorized={handleUnauthorized} />
      ) : null}
-      {routeId === 'overview' ? (
+      {activeRouteId === 'overview' ? (
        <AdminOverviewPage token={token} onUnauthorized={handleUnauthorized} />
      ) : null}
-      {routeId === 'tables' ? (
+      {activeRouteId === 'tables' ? (
        <AdminDatabaseTablesPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'debug' ? (
+      {activeRouteId === 'debug' ? (
        <AdminDebugHttpPage token={token} onUnauthorized={handleUnauthorized} />
      ) : null}
-      {routeId === 'tracking' ? (
+      {activeRouteId === 'tracking' ? (
        <AdminTrackingEventsPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'redeem' ? (
+      {activeRouteId === 'gray-release' ? (
+        <AdminGrayReleaseConfigPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
+      {activeRouteId === 'redeem' ? (
        <AdminRedeemCodePage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'invite' ? (
+      {activeRouteId === 'invite' ? (
        <AdminInviteCodePage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'creation-announcement' ? (
-        <AdminCreationEntrySwitchPage
-          mode="announcements"
-          token={token}
-          onUnauthorized={handleUnauthorized}
-        />
-      ) : null}
-      {routeId === 'creation-entry' ? (
-        <AdminCreationEntrySwitchPage
-          token={token}
-          onUnauthorized={handleUnauthorized}
-        />
-      ) : null}
-      {routeId === 'work-visibility' ? (
-        <AdminWorkVisibilityPage
-          token={token}
-          onUnauthorized={handleUnauthorized}
-        />
-      ) : null}
-      {routeId === 'tasks' ? (
+      {activeRouteId === 'tasks' ? (
        <AdminTaskConfigPage
          result={taskConfigResult}
          token={token}
@@ -225,7 +254,7 @@ export function AdminApp() {
          onResultChange={setTaskConfigResult}
        />
      ) : null}
-      {routeId === 'profile-wallet' ? (
+      {activeRouteId === 'profile-wallet' ? (
        <AdminProfileWalletConfigPage
          result={profileWalletConfigResult}
          token={token}
@@ -233,7 +262,7 @@ export function AdminApp() {
          onResultChange={setProfileWalletConfigResult}
        />
      ) : null}
-      {routeId === 'recharge-products' ? (
+      {activeRouteId === 'recharge-products' ? (
        <AdminRechargeProductPage
          result={rechargeProductResult}
          token={token}
@@ -241,24 +270,33 @@ export function AdminApp() {
          onResultChange={setRechargeProductResult}
        />
      ) : null}
-      {routeId === 'editor-generation-pricing' ? (
+      {activeRouteId === 'recharge-orders' ? (
+        <AdminRechargeOrderPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
+      {activeRouteId === 'editor-generation-pricing' ? (
        <AdminEditorGenerationPricingPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'editor-showcase' ? (
+      {activeRouteId === 'editor-showcase' ? (
        <AdminEditorShowcaseReviewPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
-      {routeId === 'editor-assets' ? (
+      {activeRouteId === 'editor-assets' ? (
        <AdminEditorAssetQueryPage
          token={token}
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
+      {activeRouteId === 'accounts' ? (
+        <AdminAccountsPage token={token} onUnauthorized={handleUnauthorized} />
+      ) : null}
    </AdminShell>
  );
 }
@@ -1,32 +1,32 @@
 import {
  Activity,
-  Bug,
  BadgeDollarSign,
+  Bug,
  Coins,
-  LayoutDashboard,
-  LogOut,
-  Megaphone,
-  Eye,
-  Images,
-  Star,
-  WalletCards,
-  ShieldCheck,
-  ListChecks,
-  SlidersHorizontal,
  Database,
+  GitBranch,
+  Images,
+  LayoutDashboard,
+  ListChecks,
+  LogOut,
+  ReceiptText,
+  ShieldCheck,
+  Star,
  Table2,
  TicketCheck,
  TicketPercent,
+  Users,
+  WalletCards,
 } from 'lucide-react';
-import type {ReactNode} from 'react';
+import type { ReactNode } from 'react';

-import type {AdminSessionPayload} from '../api/adminApiTypes';
-import type {AdminRouteId} from './adminRoutes';
-import {adminRoutes} from './adminRoutes';
+import type { AdminSessionPayload } from '../api/adminApiTypes';
+import type { AdminRouteDefinition, AdminRouteId } from './adminRoutes';

 interface AdminShellProps {
  admin: AdminSessionPayload;
-  routeId: AdminRouteId;
+  routeId: AdminRouteId | null;
+  routes: AdminRouteDefinition[];
  children: ReactNode;
  onRouteChange: (routeId: AdminRouteId) => void;
  onLogout: () => void;
@@ -38,22 +38,23 @@ const routeIcons = {
  tables: Database,
  debug: Bug,
  tracking: Table2,
+  'gray-release': GitBranch,
  redeem: TicketPercent,
  invite: TicketCheck,
  'profile-wallet': WalletCards,
  tasks: ListChecks,
  'recharge-products': BadgeDollarSign,
+  'recharge-orders': ReceiptText,
  'editor-generation-pricing': Coins,
  'editor-showcase': Star,
  'editor-assets': Images,
-  'creation-announcement': Megaphone,
-  'creation-entry': SlidersHorizontal,
-  'work-visibility': Eye,
+  accounts: Users,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;

 export function AdminShell({
  admin,
  routeId,
+  routes,
  children,
  onRouteChange,
  onLogout,
@@ -72,7 +73,7 @@ export function AdminShell({
        </div>

        <nav className="admin-nav" aria-label="后台导航">
-          {adminRoutes.map((route) => {
+          {routes.map((route) => {
            const Icon = routeIcons[route.id];
            return (
              <button
@@ -95,7 +96,7 @@ export function AdminShell({
        <header className="admin-topbar">
          <div className="admin-user">
            <span>{admin.displayName || admin.username}</span>
-            <small>{admin.roles.join(' / ')}</small>
+            <small>{admin.accountRole === 'owner' ? 'owner' : 'member'}</small>
          </div>
          <button
            className="admin-icon-button"
@@ -112,7 +113,7 @@ export function AdminShell({
      </div>

      <nav className="admin-bottom-nav" aria-label="后台导航">
-        {adminRoutes.map((route) => {
+        {routes.map((route) => {
          const Icon = routeIcons[route.id];
          return (
            <button
@@ -1,6 +1,12 @@
-import {expect, test} from 'vitest';
+import { expect, test } from 'vitest';

-import {adminRoutes, resolveAdminRoute, routeHash} from './adminRoutes';
+import {
+  adminRoutes,
+  getAccessibleAdminRoutes,
+  resolveAccessibleAdminRoute,
+  resolveAdminRoute,
+  routeHash,
+} from './adminRoutes';

 test('后台默认进入 Dashboard', () => {
  expect(adminRoutes[0]).toEqual({
@@ -13,19 +19,6 @@ test('后台默认进入 Dashboard', () => {
  expect(routeHash('dashboard')).toBe('#dashboard');
 });

-// 中文注释：后台入口公告必须作为独立导航存在，避免公告表单被误藏在入口开关页。
-test('后台入口公告路由可通过导航和 hash 访问', () => {
-  expect(adminRoutes).toContainEqual({
-    id: 'creation-announcement',
-    label: '入口公告',
-    hash: '#creation-announcement',
-  });
-  expect(resolveAdminRoute('#creation-announcement')).toBe(
-    'creation-announcement',
-  );
-  expect(routeHash('creation-announcement')).toBe('#creation-announcement');
-});
-
 test('后台模型定价路由可通过导航和 hash 访问', () => {
  expect(adminRoutes).toContainEqual({
    id: 'editor-generation-pricing',
@@ -40,6 +33,22 @@ test('后台模型定价路由可通过导航和 hash 访问', () => {
  );
 });

+test('后台灰度发布路由可通过导航和 hash 访问', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'gray-release',
+    label: '灰度发布',
+    hash: '#gray-release',
+  });
+  expect(resolveAdminRoute('#gray-release')).toBe('gray-release');
+  expect(routeHash('gray-release')).toBe('#gray-release');
+});
+
+test('后台不再暴露旧创作模板管理路由', () => {
+  expect(resolveAdminRoute('#creation-entry')).toBe('dashboard');
+  expect(resolveAdminRoute('#creation-announcement')).toBe('dashboard');
+  expect(resolveAdminRoute('#work-visibility')).toBe('dashboard');
+});
+
 test('后台素材查询路由可通过导航和 hash 访问', () => {
  expect(adminRoutes).toContainEqual({
    id: 'editor-assets',
@@ -59,3 +68,57 @@ test('后台精选审核路由可通过导航和 hash 访问', () => {
  expect(resolveAdminRoute('#editor-showcase')).toBe('editor-showcase');
  expect(routeHash('editor-showcase')).toBe('#editor-showcase');
 });
+
+test('后台充值管理路由可通过导航和 hash 访问', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'recharge-orders',
+    label: '充值管理',
+    hash: '#recharge-orders',
+  });
+  expect(resolveAdminRoute('#recharge-orders')).toBe('recharge-orders');
+  expect(routeHash('recharge-orders')).toBe('#recharge-orders');
+});
+
+test('owner 可访问全部业务 Tab 和账号管理', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'owner',
+    tabPermissions: [],
+  });
+  expect(routes).toEqual(adminRoutes);
+  expect(routes.at(-1)).toMatchObject({ id: 'accounts', ownerOnly: true });
+});
+
+test('member 只访问已分配 Tab 且无权 hash 回落到第一项', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'member',
+    tabPermissions: ['tracking', 'recharge-orders'],
+  });
+  expect(routes.map((route) => route.id)).toEqual([
+    'tracking',
+    'recharge-orders',
+  ]);
+  expect(resolveAccessibleAdminRoute('#accounts', routes)).toBe('tracking');
+  expect(resolveAccessibleAdminRoute('#recharge-orders', routes)).toBe(
+    'recharge-orders',
+  );
+});
+
+test('member 可单独获得灰度发布 Tab 权限', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'member',
+    tabPermissions: ['gray-release'],
+  });
+  expect(routes.map((route) => route.id)).toEqual(['gray-release']);
+  expect(resolveAccessibleAdminRoute('#gray-release', routes)).toBe(
+    'gray-release',
+  );
+});
+
+test('零权限 member 不回落到 Dashboard', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'member',
+    tabPermissions: [],
+  });
+  expect(routes).toEqual([]);
+  expect(resolveAccessibleAdminRoute('#dashboard', routes)).toBeNull();
+});
--- a/Show More
+++ b/Show More