Merge branch 'master' into feat/gptimage2to2.5

同步定价文档里的受控 backfill 口径
- 更新 2026-06-22 定价配置管理方案：缺模型条目改为继承编译内置默认值，并写明只自定义过 gpt-image-2 价格时的计价差异 - 在 2026-09-18 决策条目上标注该受控 backfill 已被 2026-09-22 决策取代
2026-09-22 15:58:22 +08:00 · 2026-09-22 14:49:02 +08:00 · 2026-09-22 14:42:34 +08:00 · 2026-09-22 14:17:44 +08:00 · 2026-09-22 14:08:09 +08:00 · 2026-09-22 14:03:19 +08:00
93 changed files with 2921 additions and 1981 deletions
@@ -102,7 +102,7 @@ Use OpenAPI as the final authority; these common values are a routing aid:

 - Image `kind`: `spec`, `character`, `quick-edit`, `ui-design`, `publication-material`; ordinary image generation may omit it.
 - External v1 currently has no structured game-scene generation operation. Do not send `kind: "scene"` or `assetKind: "scene"` through generic image generation; the server rejects both before queueing.
- Image `model`: `gpt-image-2`, `gemini-3.1-flash-image-preview`, `nanobanana2`, `nano-banana`.
+- Image `model`: `gpt-image-2.5`, `gemini-3.1-flash-image-preview`, `nanobanana2`, `nano-banana`. Persisted `gpt-image-2` is a legacy value resolved only when submitting a new task; the retired `gpt-image-2-c` is no longer accepted and is handled as an unsupported value.
 - Image `aspectRatio`: `1:1`, `2:3`, `3:2`, `9:16`, `16:9`.
 - Image `imageSize`: `0.5K`, `1K`, `2K`.
 - Video `model`: `seedance2.0`, `seedance2.0-fast`, `kling3.0`, `kling3.0-omni`, `veo3.1`, `veo3.1-fast`.
@@ -1,11 +1,17 @@
 ---
 name: gpt-image-2-apimart
-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.
+description: Generate or inspect project image assets through this repository's Tiantoken GPT Image 2.5 workflow. 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 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY image-generation configuration without exposing secrets. The directory name is historical.
 ---

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

-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.
+Use this skill for project-local image asset generation that must match the repository's image request contract. Provider routing is owned by `server-rs`; when this skill talks to the provider directly it must send the concrete provider model and the matching provider credentials, because the provider side only accepts concrete models:
+
+- generation (no reference images): `gpt-image-2.5-flare-c` through Tiantoken
+- edits (any reference image): `gpt-image-2.5-sunburst-c` through Tiantoken
+- nanobanana (`gemini-3.1-flash-image-preview`) stays on VectorEngine
+
+The business model name `gpt-image-2.5` is resolved to a concrete key by `server-rs` at the task boundary and is never sent to a provider directly. This client must not perform a cross-model fallback; the only retry the bundled scripts do is a same-model retry on transient upstream statuses (`408` / `429` / `5xx`, 1s/2s backoff, at most 3 attempts), which never changes the model. The folder still contains `apimart` in its name for compatibility with existing local plugin references.

 ## Workflow

@@ -24,15 +30,15 @@ Use this skill for project-local image asset generation that must match the repo
   ```

 5. Save final project assets under `public/` or another explicitly requested workspace path.
-6. Never print `VECTOR_ENGINE_API_KEY`. Report only whether configuration exists.
+6. Never print `TIANTOKEN_API_KEY`. Report only whether configuration exists.

 ## Request Contract

 The repository image path uses:

 ```text
-POST {VECTOR_ENGINE_BASE_URL}/v1/images/generations
-Authorization: Bearer {VECTOR_ENGINE_API_KEY}
+POST {TIANTOKEN_BASE_URL}/v1/images/generations
+Authorization: Bearer {TIANTOKEN_API_KEY}
 Content-Type: application/json
 ```

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

 ```json
 {
-  "model": "gpt-image-2",
+  "model": "gpt-image-2.5-flare-c",
  "prompt": "<prompt>",
  "n": 1,
  "size": "1024x1024"
@@ -50,22 +56,22 @@ Default body:
 For visual references, use the edit endpoint instead of the create endpoint:

 ```text
-POST {VECTOR_ENGINE_BASE_URL}/v1/images/edits
-Authorization: Bearer {VECTOR_ENGINE_API_KEY}
+POST {TIANTOKEN_BASE_URL}/v1/images/edits
+Authorization: Bearer {TIANTOKEN_API_KEY}
 Content-Type: multipart/form-data
 ```

 Multipart fields:

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

-In this repository, calls with no reference images use `POST /v1/images/generations`; calls with any reference image use `POST /v1/images/edits` and pass references as one or more `image` form parts. Both paths 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.
+In this repository, calls with no reference images use `POST /v1/images/generations` with `gpt-image-2.5-flare-c`; calls with any reference image use `POST /v1/images/edits` with `gpt-image-2.5-sunburst-c` and pass references as one or more `image` form parts. Server-side calls still submit the business model `gpt-image-2.5` and let `server-rs` resolve the concrete key; provider routing and retry policy remain server-owned, and pricing follows the same reference-image rule (generation with a reference image is charged at the edit tier). Match3D container UI generation embeds `public/match3d-background-references/pot-fused-reference.png` into the edit request as an `image` part.

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

@@ -75,12 +81,14 @@ Load environment values from process env first, then `.env.secrets.local`, `.env

 Required for live generation:

- `VECTOR_ENGINE_BASE_URL`
- `VECTOR_ENGINE_API_KEY`
+- `TIANTOKEN_BASE_URL`
+- `TIANTOKEN_API_KEY`

 Optional:

- `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`
+- `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS`
+
+`VECTOR_ENGINE_*` values no longer serve GPT Image 2.5: those credentials belong to VectorEngine, which only serves nanobanana. Do not fall back from `TIANTOKEN_*` to `VECTOR_ENGINE_*`.

 If the key or base URL is missing, stop after dry-run or explain the missing configuration. Do not ask the user to paste the key in chat.

@@ -9,8 +9,9 @@ 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';
+// GPT Image 2.5 生成任务只接受 concrete provider model；业务模型名 `gpt-image-2.5`
+// 由 server-rs 在任务边界解析，脚本直连 provider 时必须自己给出 concrete key。
+const imageModel = 'gpt-image-2.5-flare-c';

 const prompts = [
  {
@@ -101,18 +102,18 @@ function resolveEnv() {
    ...process.env,
  };
  return {
-    baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '')
+    baseUrl: String(loaded.TIANTOKEN_BASE_URL || '')
      .trim()
      .replace(/\/+$/u, ''),
-    apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(),
+    apiKey: String(loaded.TIANTOKEN_API_KEY || '').trim(),
    timeoutMs: Number.parseInt(
-      String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
+      String(loaded.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
      10,
    ),
  };
 }

-function buildVectorEngineImagesGenerationUrl(baseUrl) {
+function buildTiantokenImagesGenerationUrl(baseUrl) {
  return baseUrl.endsWith('/v1')
    ? `${baseUrl}/images/generations`
    : `${baseUrl}/v1/images/generations`;
@@ -222,6 +223,15 @@ function inferExtensionFromBytes(bytes) {
  return null;
 }

+// Tiantoken 偶发 408/429/5xx 时重试同一个 concrete model；跨模型回退仍由
+// server-rs 负责，脚本不做任何模型替换。
+const transientRetryMaxAttempts = 3;
+const transientRetryBaseDelayMs = 1000;
+
+function isTransientProviderStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+
 async function fetchJson(url, options, timeoutMs) {
  const abortController = new AbortController();
  const timer = setTimeout(() => abortController.abort(), timeoutMs);
@@ -233,22 +243,21 @@ async function fetchJson(url, options, timeoutMs) {
    const text = await response.text();
    if (!response.ok) {
      const error = new Error(
-        `VectorEngine ${response.status}: ${text.slice(0, 600)}`,
+        `Tiantoken ${response.status}: ${text.slice(0, 600)}`,
      );
-      error.vectorEngineStatus = response.status;
-      error.vectorEngineBody = text;
+      error.providerStatus = response.status;
      throw error;
    }
    try {
      return JSON.parse(text);
    } catch (error) {
-      error.vectorEngineResponseParse = true;
-      error.vectorEngineBody = text;
-      throw error;
+      throw new Error(
+        `Tiantoken 返回无法解析的响应体：${error.message}；响应片段：${text.slice(0, 600)}`,
+      );
    }
  } catch (error) {
    if (error?.name === 'AbortError') {
-      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
+      throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`);
    }
    throw error;
  } finally {
@@ -256,81 +265,55 @@ async function fetchJson(url, options, timeoutMs) {
  }
 }

-function shouldFallbackImageModel(error) {
-  const raw =
-    `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase();
-  if (error?.vectorEngineResponseParse) {
-    return !containsContentRejection(raw);
+async function fetchJsonWithRetry(url, options, timeoutMs, requestId) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fetchJson(url, options, timeoutMs);
+    } catch (error) {
+      if (
+        attempt >= transientRetryMaxAttempts ||
+        !isTransientProviderStatus(error?.providerStatus)
+      ) {
+        throw error;
+      }
+      const delayMs = transientRetryBaseDelayMs * 2 ** (attempt - 1);
+      console.warn(
+        `Tiantoken ${error.providerStatus} on ${requestId}, retrying the same model in ${delayMs}ms (attempt ${attempt + 1}/${transientRetryMaxAttempts})`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
  }
-  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}`,
-      );
-    }
+  const model = imageModel;
+  const requestBody = {
+    model,
+    prompt: buildPrompt(entry),
+    n: 1,
+    size: '1024x1024',
+  };
+  const payload = await fetchJsonWithRetry(
+    buildTiantokenImagesGenerationUrl(env.baseUrl),
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+    },
+    env.timeoutMs,
+    entry.id,
+  );
+  const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]);
+  if (extractImageUrls(payload)[0] || base64Image) {
+    return payload;
  }
-  throw new Error(`VectorEngine returned no image for ${entry.id}`);
+  throw new Error(
+    `Tiantoken returned no image for ${entry.id}：${JSON.stringify(payload).slice(0, 600)}`,
+  );
 }

 async function downloadUrl(url, timeoutMs) {
@@ -373,7 +356,7 @@ async function generateOne(env, entry, outDir) {
    const bytes = decodeStrictBase64Image(b64Images[0]);
    if (!bytes) {
      throw new Error(
-        `VectorEngine returned invalid base64 image for ${entry.id}`,
+        `Tiantoken returned invalid base64 image for ${entry.id}`,
      );
    }
    image = {
@@ -381,7 +364,7 @@ async function generateOne(env, entry, outDir) {
      extension: inferExtensionFromBytes(bytes),
    };
  } else {
-    throw new Error(`VectorEngine returned no image for ${entry.id}`);
+    throw new Error(`Tiantoken returned no image for ${entry.id}`);
  }

  mkdirSync(outDir, { recursive: true });
@@ -408,9 +391,8 @@ if (dryRun) {
        requests: selectedPrompts.map((entry) => ({
          id: entry.id,
          title: entry.title,
-          fallbackModel: fallbackImageModel,
          body: {
-            model: preferredImageModel,
+            model: imageModel,
            prompt: buildPrompt(entry),
            n: 1,
            size: '1024x1024',
@@ -429,7 +411,7 @@ if (!env.baseUrl || !env.apiKey) {
  console.error(
    JSON.stringify({
      ok: false,
-      error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY',
+      error: 'Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY',
      hasBaseUrl: Boolean(env.baseUrl),
      hasApiKey: Boolean(env.apiKey),
    }),
@@ -18,8 +18,9 @@ const defaultOutDir = path.join(
  'puzzle-creation-templates',
 );
 const defaultTimeoutMs = 1000000;
-const preferredImageModel = 'gpt-image-2';
-const fallbackImageModel = 'gpt-image-2-c';
+// GPT Image 2.5 生成任务只接受 concrete provider model；业务模型名 `gpt-image-2.5`
+// 由 server-rs 在任务边界解析，脚本直连 provider 时必须自己给出 concrete key。
+const imageModel = 'gpt-image-2.5-flare-c';

 const args = new Map();
 for (let index = 2; index < process.argv.length; index += 1) {
@@ -71,18 +72,18 @@ function resolveEnv() {
    ...process.env,
  };
  return {
-    baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '')
+    baseUrl: String(loaded.TIANTOKEN_BASE_URL || '')
      .trim()
      .replace(/\/+$/u, ''),
-    apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(),
+    apiKey: String(loaded.TIANTOKEN_API_KEY || '').trim(),
    timeoutMs: Number.parseInt(
-      String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
+      String(loaded.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
      10,
    ),
  };
 }

-function buildVectorEngineImagesGenerationUrl(baseUrl) {
+function buildTiantokenImagesGenerationUrl(baseUrl) {
  return baseUrl.endsWith('/v1')
    ? `${baseUrl}/images/generations`
    : `${baseUrl}/v1/images/generations`;
@@ -192,6 +193,15 @@ function inferExtensionFromBytes(bytes) {
  return null;
 }

+// Tiantoken 偶发 408/429/5xx 时重试同一个 concrete model；跨模型回退仍由
+// server-rs 负责，脚本不做任何模型替换。
+const transientRetryMaxAttempts = 3;
+const transientRetryBaseDelayMs = 1000;
+
+function isTransientProviderStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+
 async function fetchJson(url, options, timeoutMs) {
  const abortController = new AbortController();
  const timer = setTimeout(() => abortController.abort(), timeoutMs);
@@ -203,22 +213,21 @@ async function fetchJson(url, options, timeoutMs) {
    const text = await response.text();
    if (!response.ok) {
      const error = new Error(
-        `VectorEngine ${response.status}: ${text.slice(0, 600)}`,
+        `Tiantoken ${response.status}: ${text.slice(0, 600)}`,
      );
-      error.vectorEngineStatus = response.status;
-      error.vectorEngineBody = text;
+      error.providerStatus = response.status;
      throw error;
    }
    try {
      return JSON.parse(text);
    } catch (error) {
-      error.vectorEngineResponseParse = true;
-      error.vectorEngineBody = text;
-      throw error;
+      throw new Error(
+        `Tiantoken 返回无法解析的响应体：${error.message}；响应片段：${text.slice(0, 600)}`,
+      );
    }
  } catch (error) {
    if (error?.name === 'AbortError') {
-      throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`);
+      throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`);
    }
    throw error;
  } finally {
@@ -226,83 +235,55 @@ async function fetchJson(url, options, timeoutMs) {
  }
 }

-function shouldFallbackImageModel(error) {
-  const raw =
-    `${error?.message || ''}\n${error?.vectorEngineBody || ''}`.toLowerCase();
-  if (error?.vectorEngineResponseParse) {
-    return !containsContentRejection(raw);
+async function fetchJsonWithRetry(url, options, timeoutMs, requestId) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fetchJson(url, options, timeoutMs);
+    } catch (error) {
+      if (
+        attempt >= transientRetryMaxAttempts ||
+        !isTransientProviderStatus(error?.providerStatus)
+      ) {
+        throw error;
+      }
+      const delayMs = transientRetryBaseDelayMs * 2 ** (attempt - 1);
+      console.warn(
+        `Tiantoken ${error.providerStatus} on ${requestId}, retrying the same model in ${delayMs}ms (attempt ${attempt + 1}/${transientRetryMaxAttempts})`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
  }
-  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}`,
-      );
-    }
+  const model = imageModel;
+  const requestBody = {
+    model,
+    prompt: buildPrompt(template),
+    n: 1,
+    size: '1024x1024',
+  };
+  const payload = await fetchJsonWithRetry(
+    buildTiantokenImagesGenerationUrl(env.baseUrl),
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+    },
+    env.timeoutMs,
+    template.id,
+  );
+  const base64Image = decodeStrictBase64Image(extractBase64Images(payload)[0]);
+  if (extractImageUrls(payload)[0] || base64Image) {
+    return payload;
  }
-  throw new Error(`VectorEngine returned no image for ${template.id}`);
+  throw new Error(
+    `Tiantoken returned no image for ${template.id}：${JSON.stringify(payload).slice(0, 600)}`,
+  );
 }

 async function downloadUrl(url, timeoutMs) {
@@ -345,7 +326,7 @@ async function generateOne(env, template, outDir) {
    const bytes = decodeStrictBase64Image(b64Images[0]);
    if (!bytes) {
      throw new Error(
-        `VectorEngine returned invalid base64 image for ${template.id}`,
+        `Tiantoken returned invalid base64 image for ${template.id}`,
      );
    }
    image = {
@@ -353,7 +334,7 @@ async function generateOne(env, template, outDir) {
      extension: inferExtensionFromBytes(bytes),
    };
  } else {
-    throw new Error(`VectorEngine returned no image for ${template.id}`);
+    throw new Error(`Tiantoken returned no image for ${template.id}`);
  }

  mkdirSync(outDir, { recursive: true });
@@ -384,9 +365,8 @@ if (dryRun) {
        requests: selectedTemplates.map((template) => ({
          id: template.id,
          title: template.title,
-          fallbackModel: fallbackImageModel,
          body: {
-            model: preferredImageModel,
+            model: imageModel,
            prompt: buildPrompt(template),
            n: 1,
            size: '1024x1024',
@@ -405,7 +385,7 @@ if (!env.baseUrl || !env.apiKey) {
  console.error(
    JSON.stringify({
      ok: false,
-      error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY',
+      error: 'Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY',
      hasBaseUrl: Boolean(env.baseUrl),
      hasApiKey: Boolean(env.apiKey),
    }),
@@ -44,6 +44,35 @@ _Avoid_: 把同一资源的全局元数据和某一次摆放坐标混在同一
 由图片生成或图片修改流程产生的画布资源，必须记录来源资源、提示词、实际提示词、模型、provider、任务 ID 和生成时间；本期 `/editor` 的生成修改先允许 mock 生成资源，但仍按生成资源元数据形状保存。
 _Avoid_: 无来源的静态素材、只显示在 UI 但不落工程资源记录的生成结果

+**图片模型历史值与使用端解析**:
+图片资源中已持久化的 `gpt-image-2` 是历史业务事实，读回时保持原值；新任务使用业务模型值 `gpt-image-2.5`。当用户基于历史资源再次发起生成或编辑任务时，服务端只在新任务的使用端把历史值解析为当前业务模型，不改写历史资源。provider route 属于服务端执行与审计边界，前端不接收、不持久化、不展示，也不据此分支。
+_Avoid_: 读取数据库时改写历史模型值、把 provider route 暴露为前端模型选项或公开 DTO
+
+**图片 provider 显式路由**:
+api-server 在任务入口按业务语义显式选择具体 provider model name（生成或编辑），并把同一具体名传给图片平台适配器和后台定价解析；图片平台适配器不从参考图数量或前端字段猜测任务。具体 provider model name 只存在于服务端调用、定价配置和审计边界。
+后台管理 Web/API 是明确例外，可以查看和编辑两个具体定价 key；主站普通前端与公开定价 API 不接收这些 key。
+_Avoid_: 让图片适配器隐式猜路由、让主站前端携带 provider model name
+
+**业务模型**:
+面向任务与产品契约的稳定模型值；当前 GPT 图片新任务的业务模型是 `gpt-image-2.5`。业务模型不等同于 provider 的具体计费/请求 model，也不暴露 provider 凭证或 endpoint。
+_Avoid_: 把 provider concrete model 当作前端业务选项、用业务模型值直接推断 provider 凭证
+
+**具体模型**:
+服务端发送请求和定价使用的 concrete model name。GPT Image 2.5 生成与编辑分别是 `gpt-image-2.5-flare-c` 和 `gpt-image-2.5-sunburst-c`；nanobanana 仍使用 `gemini-3.1-flash-image-preview`。具体模型只在服务端执行、定价和审计边界出现。
+_Avoid_: 把具体模型写入普通前端 DTO、让未知字符串自动选择 provider
+
+**provider client**:
+按具体模型选出的外部图片 provider 连接配置，包含 provider identity、base URL 和 API key；VectorEngine 与 Tiantoken client 共享图片协议执行器，不复制请求/响应业务逻辑。两套 required client 在 api-server 启动时构造。
+_Avoid_: 在首次请求时才创建 client、在 provider client 中复制尺寸/重试/审计逻辑、跨 provider credential fallback
+
+**历史模型值**:
+已持久化的 `gpt-image-2` 字符串，只作为历史事实原样读取和审计；基于历史资源提交新任务时，在使用端解析为当前 GPT Image 2.5 业务任务，不回写历史记录，也不把旧值作为现役 provider route。已退役的 `gpt-image-2-c` 已从代码整体删除，只有数据库里的历史审计字符串原样保留，任何入口传入该值都按不支持的值处理。
+_Avoid_: 数据库批量改写历史值、把历史值重新路由到 VectorEngine、把兼容解析扩散到普通前端、为已删除的 `gpt-image-2-c` 重新加回常量或解析分支
+
+**GPT Image 2.5 新生成展示名**:
+`GPT Image 2.5` 是新生成任务的产品展示名；历史资源与既有编辑上下文不因新模型上线而改写展示语义。
+_Avoid_: 把新生成展示名扩散到历史记录、历史生成器或旧编辑上下文
+
 **系列素材图集生成**:
 一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。
 _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO
@@ -703,11 +703,11 @@ describe('快速编辑浮层的下拉弹层', () => {
    fireEvent.click(
      screen.getByRole('button', { name: '快速编辑模型 nanobanana2' }),
    );
-    expect(screen.getByRole('button', { name: 'gpt-image-2' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'GPT Image 2.5' })).toBeTruthy();

    // 点面板内、弹层外的提示词区域：只收弹层，不动面板本身。
    fireEvent.click(screen.getByLabelText('快速编辑提示词'));
-    expect(screen.queryByRole('button', { name: 'gpt-image-2' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'GPT Image 2.5' })).toBeNull();
    expect(
      screen.getByRole('button', { name: '快速编辑模型 nanobanana2' }),
    ).toBeTruthy();
@@ -739,10 +739,10 @@ describe('快速编辑浮层的下拉弹层', () => {
    fireEvent.click(
      screen.getByRole('button', { name: '快速编辑模型 nanobanana2' }),
    );
-    expect(screen.getByRole('button', { name: 'gpt-image-2' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'GPT Image 2.5' })).toBeTruthy();

    fireEvent.keyDown(document, { key: 'Escape' });

-    expect(screen.queryByRole('button', { name: 'gpt-image-2' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'GPT Image 2.5' })).toBeNull();
  });
 });
@@ -89,9 +89,11 @@ GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET_FILE=/etc/genarrative/secrets/l
 GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN_FILE=/etc/genarrative/secrets/llm-router-admin.token
 TIANTOKEN_BASE_URL=https://api.tiantoken.com
 TIANTOKEN_API_KEY=
+# 两个图片 provider 的超时互相独立：TIANTOKEN_* 只作用于 Tiantoken，VECTOR_ENGINE_* 只作用于 VectorEngine。
 TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS=1000000
 VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn
 VECTOR_ENGINE_API_KEY=
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000
 VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000
 ELEVENLABS_BASE_URL=https://api.elevenlabs.io
 ELEVENLABS_API_KEY=
@@ -80,6 +80,7 @@
 - [画板音乐生成入口](./【编辑器】画板音乐生成入口设计-2026-06-18.md)：BGM/SFX 共享视图、独立业务规则和当前发布门禁。
 - [画布 Agent 对话面板](./【编辑器】画布Agent对话面板-2026-07-03.md)
 - [画布 Agent 会话消息存 OSS](./adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md)
+- [GPT Image 2.5 模型路由与历史值兼容](./adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md)
 - [编辑器模型定价配置](./【编辑器】模型定价配置管理方案-2026-06-22.md)

 ## 后端、运维与测试
@@ -0,0 +1,25 @@
+# GPT Image 2.5 模型路由与历史值兼容
+
+状态：accepted
+
+新任务使用业务模型值 `gpt-image-2.5`，api-server 按任务显式选择具体 model：无参考图的生成使用 `gpt-image-2.5-flare-c`，编辑以及带参考图的生成使用 `gpt-image-2.5-sunburst-c`（参考图会让执行端必须走 edits multipart，因此执行与计价都按编辑 concrete model）。这两个 GPT Image 2.5 model 必须通过启动时构造的 Tiantoken client 发送；Tiantoken client 只读取显式配置的 `TIANTOKEN_BASE_URL`（部署值由环境设置为 `https://api.tiantoken.com`）和独立 `TIANTOKEN_API_KEY`，缺失即阻止 api-server 启动，不得回退到 VectorEngine 或其 API key。
+
+图片协议执行逻辑保持 provider-neutral：请求 body、multipart、尺寸约束、重试、响应解码和审计由共享 image executor 承担；VectorEngine 与 Tiantoken client 只提供相同协议所需的 base URL、API key 和 provider identity。platform-image 根据 concrete model 做严格白名单路由：`gpt-image-2.5-flare-c` 与 `gpt-image-2.5-sunburst-c` 走 Tiantoken，`gemini-3.1-flash-image-preview`（nanobanana）走 VectorEngine；未知 model 直接拒绝。已持久化的 `gpt-image-2` 只在新任务提交边界按兼容规则解析为当前 GPT Image 2.5 任务，不改写历史资源，也不进入旧 VectorEngine 图片路由。
+
+provider 白名单同时拒绝非 provider model：业务模型名 `gpt-image-2.5` 必须先由 api-server 在任务边界解析成 `gpt-image-2.5-flare-c` / `gpt-image-2.5-sunburst-c`；`gpt-image-2` 继续作为历史可读值接受。两者都不进入 provider 路由。
+
+`gpt-image-2-c` 已整体删除：它自兜底移除后只剩历史审计字符串，从未进入业务模型、持久化模型字段或前端契约，因此不再保留任何常量、解析分支、尺寸语义或 provider 路由。数据库里既有的审计字符串保持原样，不参与新任务。
+
+普通主站前端只接触业务模型和新生成展示名 `GPT Image 2.5`，admin Web/API 可以查看和编辑两个具体定价 key；生成类任务带参考图时后端必须走 edits multipart，因此 dispatch、审计与计价统一按编辑 concrete model `gpt-image-2.5-sunburst-c`（包含图标素材图集的固定参考图与 UI 素材提取的来源图），不存在「生成档计价 + 编辑档执行」的分裂。新代码不再跨模型或跨 provider fallback，已退役的 `gpt-image-2-c` 审计记录原样保留在数据库，代码不再引用该值。
+
+主站前端只把原本明确使用 GPT Image 2 的专用新任务改为业务模型值 `gpt-image-2.5`；普通图片、角色、场景、图标等原有 nanobanana 默认行为保持不变。画布参数或编辑布局读到 `gpt-image-2` 时，在使用端解析为 `gpt-image-2.5` 并触发参数迁移警告，原始资源、审计、metadata 和历史 fixture 不回写。AGC 现有资源生成界面与请求默认保持不变，不因本决策新增模型字段、选择器或尺寸行为。
+
+## Consequences
+
+- 定价配置的活动 key 是两个具体 provider model；持久化 override 与 SpacetimeDB record 只保存被显式设置过的模型，缺失条目一律继承编译内置默认（`server-rs/crates/api-server/config/editor-generation-pricing.default.json`），不再为每个新模型维护受控 backfill。旧单 key 配置因此把 GPT Image 2.5 档位落在默认值上，要改这两个具体 key 的价格必须显式写出。
+- 定价档位跟随任务最终 concrete model：带参考图的生成任务与编辑任务同价，admin 单独调整 `gpt-image-2.5-sunburst-c` 时生成带参考图的任务必须同步生效。
+- 新任务的同模型重试固定使用 api-server dispatch 的具体 model，不切换到另一个 model。
+- 两套 provider client 在 api-server 启动阶段同时构造；任一 required provider 配置缺失，启动失败而不是延迟到首次图片请求。
+- 两套 provider client 的缺失配置报错点名对应环境变量（`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`、`TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`），构造成功后用启动日志记录已启用的 provider。
+- provider routing 只依据 concrete model 的白名单，业务名与已退役的 `gpt-image-2-c` 一律拒绝（`gpt-image-2-c` 已从代码中整体删除，传入即按未知 model 处理）；provider client 不复制共享协议执行逻辑。
+- 公开资源、`generationInputs` 和普通前端契约不包含具体 provider key；admin 定价管理是明确例外。
@@ -3017,7 +3017,7 @@
          },
          "model": {
            "type": "string",
-            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时沿用编辑器默认。"
+            "description": "支持 gpt-image-2.5、gemini-3.1-flash-image-preview、nanobanana2、nano-banana；gpt-image-2 仅作为历史值在新任务提交边界兼容解析；已退役的 gpt-image-2-c 不再接受，命中按不支持的值处理。kind=ui-design 与 kind=publication-material 固定使用 gpt-image-2.5，传入的 model 会被忽略；其余 kind 未传时默认 gpt-image-2.5。"
          },
          "aspectRatio": {
            "type": "string",
@@ -3033,7 +3033,7 @@
            "type": "array",
            "items": {
              "type": "string",
-              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多 5 张；kind=quick-edit 时 gpt-image-2 最多 5 张、nanobanana2 最多 9 张。超限返回 400，不会静默截断。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多 5 张；kind=quick-edit 时 GPT Image 2.5 最多 5 张、nanobanana2 最多 9 张。超限返回 400，不会静默截断。"
            },
            "maxItems": 9
          },
@@ -3170,7 +3170,7 @@
          },
          "model": {
            "type": "string",
-            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。"
+            "description": "支持 gpt-image-2.5、gemini-3.1-flash-image-preview、nanobanana2、nano-banana；gpt-image-2 仅作为历史值兼容解析；已退役的 gpt-image-2-c 不再接受，命中按不支持的值处理。"
          },
          "aspectRatio": {
            "type": "string",
@@ -3184,7 +3184,7 @@
            "type": "array",
            "items": {
              "type": "string",
-              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceReferenceId 对应的主来源原图占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceReferenceId 对应的主来源原图占用 1 张 provider 容量，因此 GPT Image 2.5 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 8
          },
@@ -3373,7 +3373,7 @@
            "type": "array",
            "items": {
              "type": "string",
-              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 GPT Image 2.5 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 8
          },
@@ -3488,13 +3488,13 @@
          "model": {
            "type": "string",
            "default": "gemini-3.1-flash-image-preview",
-            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时默认使用 nanobanana。"
+            "description": "支持 gpt-image-2.5、gemini-3.1-flash-image-preview、nanobanana2、nano-banana；gpt-image-2 仅作为历史值兼容解析；已退役的 gpt-image-2-c 不再接受，命中按不支持的值处理。未传时默认使用 nanobanana（gemini-3.1-flash-image-preview）；传 gpt-image-2.5 时按 GPT Image 2.5 编辑任务执行。"
          },
          "referenceImageSrcs": {
            "type": "array",
            "items": {
              "type": "string",
-              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 5 张；超限返回 400，不会静默截断。"
+              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 GPT Image 2.5 最多再提交 4 张、nanobanana2 最多再提交 5 张；超限返回 400，不会静默截断。"
            },
            "maxItems": 5
          },
@@ -0,0 +1,50 @@
+# GPT Image 2.5 provider 边界重构实施计划
+
+- Version: 3
+- Status: active
+- Date: 2026-09-18
+- Parent Milestone: `docs/project-memory/plans/【里程碑】GPT Image 2.5 provider边界重构-2026-09-18.md`
+
+## 实施边界
+
+1. 先抽象 provider-neutral settings/client 与共享图片执行器接口；保留一套 body、multipart、尺寸、retry、响应和 audit 逻辑。
+2. 在 api-server 配置/state 初始化阶段分别构造 VectorEngine 与 Tiantoken client；删除 Tiantoken 对 VectorEngine URL/key 的任何 fallback。
+3. 在 platform-image 建立 concrete model 白名单路由：GPT Image 2.5 → Tiantoken，nanobanana → VectorEngine；legacy/unknown 按合同处理。
+4. 重命名 provider-specific client/build/transport 符号，避免共享逻辑继续伪装成 `vector_engine_*`；仅保留确有 VectorEngine 语义的名称。
+5. 迁移 api-server、Agent、raw edit、角色/图标/UI 入口和测试；核对 pricing/admin/public DTO 可见性。
+6. 删除跨模型/跨 provider fallback 分支，保留同 concrete model retry。
+
+## 前端同步边界（已确认）
+
+1. 主站 `src/components/image-editor/` 中，凡是原本明确写死 `gpt-image-2` 的 GPT 专用新任务（快速编辑、UI 设计、宣发、规范及对应提交/锁定模型）统一改为业务模型值 `gpt-image-2.5`；普通图片、角色、场景、图标等原有 nanobanana 默认行为不变。
+2. `normalizeEditorImageModel` 在编辑面板、画布生成参数和历史布局恢复的使用端把 `gpt-image-2` 与 `gpt-image-2-c` 解析为 `gpt-image-2.5`。该兼容命中必须触发既有参数回退警告；未知模型仍按原有无效参数处理。原始资源、审计、metadata 和历史 fixture 不回写。
+3. 主站新请求的 `model` 字段只发送业务模型值或 nanobanana 业务值，不发送 `gpt-image-2.5-flare-c` / `gpt-image-2.5-sunburst-c` 等 concrete provider model。
+4. AGC（`apps/ai-game-creator-shell/src` 及其 Tauri 本地资源生成链路）本里程碑不增加模型字段、选择器或尺寸行为；继续使用现有请求默认值。AGC 代码只在确属历史兼容读取/测试证明的位置保留旧值，不借本次同步引入新功能。
+5. OpenAPI、External editor skill reference、现役脚本和当前技术方案中的“新任务使用 GPT Image 2 / 2-c fallback”改为 GPT Image 2.5 口径；静态已生成 manifest、历史审计和兼容 fixture 保持旧值并补充历史语义断言。
+
+## 前端实现顺序
+
+1. 先在 `ImageCanvasGenerationModel` 集中定义历史别名解析与迁移警告结果，保持 nanobanana 默认值、尺寸矩阵和可选模型顺序不变。
+2. 迁移 `ImageCanvasGenerationDialogModel`、`ImageCanvasGenerationSubmissionModel`、生成工作流、快速编辑弹窗、规范/宣发面板的 GPT 专用默认、锁定值和提交 payload。
+3. 为 `generationInputs` / 画布布局 / 资源历史恢复补齐旧值迁移警告测试；确认新请求字段为 `gpt-image-2.5`，而历史原文仍未被改写。
+4. 更新 OpenAPI 与现役工具/专题文档，区分业务模型、concrete provider model、历史值和产品展示名；不得把 AGC 默认行为改成前端显式模型选择。
+
+## 验证命令
+
+- `cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check`
+- `cargo test -p platform-image`
+- `cargo test -p platform-editor-agent`
+- api-server 定向测试/`cargo check -p api-server`
+- `npm run typecheck`
+- `npm run check:doc-index`
+- `npm run check:encoding`
+- `git diff --check`
+- 主站图片编辑定向测试：模型选项/展示名、GPT 专用提交值、历史 `gpt-image-2` 与 `gpt-image-2-c` 恢复及警告、nanobanana 默认回归。
+- AGC 定向测试：确认未新增 `model` IPC 入参、未改变原有尺寸/UI 行为，现有资源生成请求继续依赖服务端默认。
+- OpenAPI/External editor 契约测试：模型说明、参考图容量说明和新业务模型值一致，provider concrete model 不进入普通前端契约。
+
+## 风险与回滚
+
+- 风险：启动阶段依赖变化、历史任务兼容解析遗漏、nanobanana 被误路由到 Tiantoken、provider key 泄露到公开 DTO。
+- 风险：主站把 nanobanana 的默认路径误改成 GPT Image 2.5，或把历史兼容值静默吞掉导致用户无法识别参数迁移。
+- 回滚：以 provider-neutral seam、启动配置、model route、主站前端同步四个局部提交边界回滚；不执行数据库历史迁移，也不回滚历史资源值。
@@ -0,0 +1,53 @@
+# GPT Image 2.5 provider 边界重构
+
+- Version: 2
+- Status: active
+- Date: 2026-09-18
+- Parent Spec: `docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`
+
+## 目标
+
+在保持图片协议执行逻辑共享的前提下，建立明确的 provider client 边界：GPT Image 2.5 通过 Tiantoken，nanobanana 通过 VectorEngine；路由依据 concrete model 严格白名单决定；两个 client 在 api-server 启动阶段构造。
+
+## 范围
+
+- `platform-image`：provider-neutral 图片执行器、provider client 注入 seam、concrete model 路由和错误/审计 provider 标识。
+- `api-server`：启动时构造 VectorEngine/Tiantoken 两个 client，分别读取各自环境变量；任务提交边界的历史模型兼容解析。
+- 共享请求、multipart、尺寸、retry、响应和 audit 逻辑保持单一实现。
+- Agent 与其它 server-side 图片调用方迁移到业务模型/concrete model 合同。
+- 定价、公开 DTO、admin DTO 与 provider model 可见性保持既定 ADR 约束。
+
+## 现役路由
+
+| Concrete model | Provider client | 业务用途 |
+| --- | --- | --- |
+| `gpt-image-2.5-flare-c` | Tiantoken | Generate，仅限不带参考图的生成任务 |
+| `gpt-image-2.5-sunburst-c` | Tiantoken | Edit，包括快速编辑、原位修改、raw edit，以及带参考图的生成任务（图标素材图集的固定参考图、UI 素材提取的来源图同在内） |
+| `gemini-3.1-flash-image-preview` | VectorEngine | nanobanana 生成/编辑能力 |
+
+`gpt-image-2` 与 `gpt-image-2-c` 只保留为历史持久化/审计字符串；新任务不得 dispatch 到旧 GPT Image 2 路由。未知 model 直接拒绝。
+
+## 必须成立的行为
+
+1. api-server 启动时同时构造两个 required provider client；任一对应环境变量缺失，启动失败。
+2. Tiantoken 只读取 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`；VectorEngine 只读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`，互不回退。
+3. platform-image 根据 concrete model 选择已注入 client；共享执行器不复制 provider 协议逻辑。
+4. 同 concrete model 可以 retry，但永不跨 concrete model 或跨 provider fallback。
+5. 历史值读取不改写；新任务提交边界将旧值兼容为 GPT Image 2.5 业务任务。
+6. 普通前端不接收 concrete provider model；admin 定价界面可查看和编辑两个具体 pricing key。
+7. 生成任务的 concrete model 由参考图决定：同一判据同时用于 dispatch、审计与计价，带参考图的生成任务按编辑档计价。
+
+## 非目标
+
+- 不复制两套完整图片 client。
+- 不新增 GPT Image 2 现役 VectorEngine 路由。
+- 不修改历史数据库记录或旧审计字符串。
+- 不把 provider client 选择下沉给普通前端。
+
+## 验收证据
+
+- provider routing 单元测试覆盖 flare/sunburst/nanobanana/legacy/unknown。
+- 启动配置测试证明两套 client 独立读取环境变量，缺失任一配置即失败且无 VectorEngine/Tiantoken 回退。
+- 请求审计测试证明 provider 与 concrete model 正确记录。
+- platform-image 与 Agent 定向测试通过。
+- api-server 类型/编译检查、前端类型检查、编码/文档/diff 门禁通过。
@@ -1,5 +1,53 @@
 # 决策记录

+## 2026-09-22 模型定价改为「编译内置默认 + 持久化覆盖」叠加，删除受控 backfill
+
+- 背景：`editor-generation-pricing.default.json`（`include_str!` 编译内置）是默认模型定价；磁盘 override 与 SpacetimeDB record 以前是「整份替换」，旧配置缺新模型 key 时 `validate()` 直接失败。为了让升级前只含单个 `gpt-image-2` key 的配置能启动，代码维护了 `backfill_legacy_gpt_image_2_5_pricing`、`backfill_legacy_sfx_pricing` 两个受控 backfill 加 record 路径上的内联 SFX 补齐，并且每新增一个模型都要再写一次同类兼容代码。
+- 决策：两条加载路径统一改为「以编译内置默认 JSON 为基线，叠加持久化配置里显式给出的模型条目」（`overlay_editor_generation_pricing`）：缺失模型继承默认值，写坏的条目仍由 `validate()` 拦截。删除两个 backfill 函数与 record 路径的内联补齐；磁盘 override 与 record 只保存被显式设置过的模型，admin 保存时仍写回完整模型集合。
+- 行为差异：旧配置里自定义过、但没有写出 `gpt-image-2.5-flare-c` / `gpt-image-2.5-sunburst-c` 的 `gpt-image-2` 价格不再自动传播到 GPT Image 2.5 档位，新任务按内置默认档（1K 3 / 2K 5 泥点）计价。仓库内置默认里三者本来就相同，因此只影响「自定义过 `gpt-image-2` 价格且此后从未再保存定价」的部署。
+- 迁移建议：只读检查 SpacetimeDB `editor_generation_pricing_config` 是否缺少两个 `gpt-image-2.5-*-c` 模型行（或与默认档位不一致）；确认后在后台保存一次定价即可把继承值落库，或显式写入期望档位。
+- 影响范围：`server-rs/crates/api-server/src/editor_generation_config.rs`、`server-rs/crates/api-server/src/state.rs` 及其单测；ADR `docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md` 同步更新。
+- 验证：`cargo test -p api-server editor_generation_pricing` 17 项通过（含新的 `editor_generation_pricing_legacy_override_inherits_missing_models_from_default`、`editor_generation_pricing_override_still_rejects_invalid_model_entries`，以及改名为 `..._inherits_legacy_*` 的两条 record 用例）。
+
+## 2026-09-22 删除失效的图片模型兜底审计链路
+
+- 背景：跨模型兜底 `gpt-image-2-c` 删除后，`platform-image` 已没有任何地方写入 `recovered_failure_audits`：executor 只创建空 Vec、成功路径空 append、失败路径原样返回，`PlatformImageError::FallbackFailed` 不可能被构造，`GeneratedImages.recovered_failure_audits` 和错误上的 `recovered_failure_audits()` 恒为空，api-server 成功运行摘要的 `recoveredFailureCount` 恒为 `0`。这条链路既是死代码，也会让排障误以为仍存在兜底审计。
+- 决策：整体删除——`PlatformImageError::FallbackFailed`、`recovered_failure_audits()`、`with_recovered_failure_audits`、`into_final_error`、`GeneratedImages.recovered_failure_audits`、executor 的 `finish_image_model_fallback_error` 包装与空 Vec 累积，以及 api-server 成功运行摘要里的 `recoveredFailureCount` 和两处 recovered audit 落库循环。终态错误 audit（`error.audit()` → `external_api_call_failure`）语义保持不变。
+- 边界：不改重试策略（同模型 408/429/5xx 重试仍只写 provider 日志）、不改 `external_api_call_failure` 的终态记录语义、不改扣费与 HTTP 错误映射。本文件 2026-07-21「VectorEngine 图片首选 gpt-image-2 并以 gpt-image-2-c 兜底」条目里的 `recoveredFailureCount` 观测字段自本次起不再存在；数据库历史审计字符串按原样保留。
+- 影响范围：`server-rs/crates/platform-image/src/image_provider/runtime/{error.rs,util.rs,types.rs,executor.rs,image_source.rs}`、`server-rs/crates/platform-image/tests/image_provider.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+- 验证：`cargo test -p platform-image`、`cargo check -p api-server`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+## 2026-09-22 图片 provider 单次 attempt 超时解耦
+
+- 背景：`config.rs` 把 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS`（回退 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`）统一写进 `vector_engine_image_request_timeout_ms`，`state.rs` 又用这一个字段同时构造 Tiantoken 与 VectorEngine 两个图片 client，`OpenAiImageSettings` 也取同一个值；结果是两个 provider 无法各自设置单次 attempt 超时，配置 Tiantoken 变量会顺带改写 VectorEngine 的 deadline（反之亦然）。
+- 决策：`AppConfig` 新增 `tiantoken_image_request_timeout_ms`（默认 `1000000`，env 只读 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS`）；`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只写 `vector_engine_image_request_timeout_ms`（默认同样 `1000000`）。Tiantoken 图片 client 与 `OpenAiImageSettings.request_timeout_ms` 改用新字段，VectorEngine client 保持原字段，两边都不再从对方的环境变量取值。
+- 边界：单次 attempt 语义不变（仍受 worker 绝对 job deadline 约束），默认值不变，因此现网只配置 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS=1000000` 的行为与之前一致；`deploy/env/api-server.env.example` 同步补上 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000`，让两个 provider 的取值都显式可见。不修改 nanobanana / Suno 链路、扣费、审计或重试策略。
+- 影响范围：`server-rs/crates/api-server/src/{config.rs,state.rs,openai_image_generation.rs}`、`deploy/env/api-server.env.example`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+- 验证：`cargo test -p api-server config::tests::from_env_reads_non_public_models_and_urls`（新增 Tiantoken / VectorEngine 双向不覆盖断言）、`cargo check -p api-server`。
+
+## 2026-09-21 生成带参考图统一按编辑 concrete model 执行与计价
+
+- 背景：GPT Image 2.5 迁移后，生成端在带参考图时会改走 `/v1/images/edits` 并提交 `gpt-image-2.5-sunburst-c`，但计价仍按 `gpt-image-2.5-flare-c` 生成档，dispatch 判断也分散在三个入口各自的 `if 带参考图` 表达式里；结果是「生成档扣费 + 编辑档执行/审计」分裂，admin 单独调价任一档位都会错价，ADR 里「普通生成即使因参考图使用 edits multipart，仍按生成 concrete model」与代码事实不符。
+- 决策：保留「按是否带参考图决定 concrete model」这一现有行为，把三处文档改到与代码一致；同时新增 `editor_image_generation_concrete_model(model, has_reference_images)` 作为生成类任务选择 concrete model 的唯一入口，dispatch 与计价共用同一判据。`image_generation_mud_points` 增加 `has_reference_images`，命中编辑 concrete model 时改走编辑档 `image_edit_model_mud_points`；图标素材图集（固定参考图）、UI 素材提取（来源图）、图标规范带 `referenceId`、Agent 生成类工具带 `referenceImageIds` 全部同规则。`EditImageTool` 计价从生成档改为编辑档，与直连快速编辑、raw edit 对齐。
+- 边界：nanobanana 生成与编辑共用一个 concrete model，参考图不改变档位；不引入跨模型 fallback；历史持久化值与审计字符串不改写。
+- 同批修复：`raw_image_edit` 发送前复用共享 `ensure_provider_matches_model` 白名单校验；`platform-image` 兜底 task id 前缀改为跟随实际 provider（`tiantoken-edit` / `tiantoken-nanobanana` 不再带 `vector-engine` 前缀）；`resolve_image_provider` 增加 `gpt-image-2 → Tiantoken` 断言把历史值意图钉死；删除 `openai_image_generation.rs` 中仅测试使用的 `create_openai_image_edit` / `create_openai_image_edit_with_references`（测试改用 `..._and_model` 变体，保留空参考图本地校验覆盖）；`normalize_editor_generation_options` 的具体 provider key 改用常量；External v1 OpenAPI 的 `model` 描述改为与实现一致（`kind=ui-design` / `publication-material` 固定 `gpt-image-2.5`，UI 素材提取未传默认 nanobanana）。
+- 影响范围：`api-server`（`editor_generation_config`、`editor_project`、`editor_project_icon`、`character_visual_assets`、`editor_agent/tool`、`openai_image_generation`）、`platform-image`（`raw_image_edit`、`runtime/executor`、集成测试）、ADR、里程碑文档、External v1 OpenAPI 描述、`.codex/skills/gpt-image-2-apimart` 脚本与 SKILL.md（改用 `TIANTOKEN_*` 凭据 + concrete model）。
+- 验证：`cargo test -p api-server editor_generation_config`、`cargo test -p api-server editor_agent::tool`、`cargo test -p api-server`（1123 passed / 1 failed，失败项为 mock LLM 连接超时，单测隔离重跑通过）；`cargo test -p platform-image`（22 + 64 + 14 passed）；`npx vitest run` 全量 382 files / 4619 passed（6 个测试文件的旧 `gpt-image-2` 断言与 mock 请求体读取竞态同步修正）；`npm run typecheck`、`npm run check:encoding`、`git diff --check` 通过。
+- 关联文档：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)、[`docs/project-memory/plans/【里程碑】GPT Image 2.5 provider边界重构-2026-09-18.md`](../plans/【里程碑】GPT%20Image%202.5%20provider边界重构-2026-09-18.md)。
+
+## 2026-09-21 图片 provider 白名单收紧，并整体删除 gpt-image-2-c
+
+- 背景：GPT Image 2.5 迁移后，`resolve_image_provider` 仍把业务模型名 `gpt-image-2.5` 与 `gpt-image-2-c` 一起判为 Tiantoken，等于把「非 provider model」留在 provider 边界白名单里。`gpt-image-2-c` 自 2026-07-21 起只是首选模型失败时的兜底 provider model（兜底移除后仅剩历史审计字符串），从未进入业务模型、持久化 `model` 字段或前端契约——api-server 持久化的模型一律取自 `generation_options.model`（业务值），前端在 2.5 迁移前只写 `gpt-image-2`。
+- 决策：`resolve_image_provider` 白名单只接受现役具体 provider model，业务名 `gpt-image-2.5` 命中即拒绝，必须先在任务边界解析成具体 key；`gpt-image-2` 继续作为历史可读值接受。`gpt-image-2-c` 不再只做「拒绝」，而是整体删除：常量、re-export、`is_gpt_image_2_family_model` 尺寸语义、`auditable_image_model` 审计标签、api-server 的三处提交边界解析、前端常量与历史恢复分支全部移除；数据库既有审计字符串原样保留，代码不再引用该值。
+- 影响范围：`platform-image`（constants / lib / image_provider mod / protocol request / runtime executor / 集成测试）、`api-server`（`openai_image_generation`、`editor_project`、`editor_generation_config`、`editor_agent/tool`）、主站前端 `ImageCanvasGenerationModel` 与其测试、External v1 OpenAPI 描述、ADR 与本文档。前端与 External v1 传入 `gpt-image-2-c` 现在按「不支持的值」处理（走既有未知值分支），不再解析为 GPT Image 2.5。
+- 验证：`cargo test -p platform-image` 全绿（含新增 `resolve_image_provider_rejects_business_model_and_accepts_concrete_models`）；`cargo test -p api-server` 1115 项；`npx vitest run src/components/image-editor/ImageCanvasGenerationModel.test.ts` 34 项通过；`check:encoding`、`check:doc-index` 通过。
+
+## 2026-09-21 图片 provider 启动期缺配置的报错点名环境变量
+
+- 背景：两个图片 provider client 都在 `AppState::new` 构造，缺 base URL / API key 即阻止 api-server 启动；旧报错只写「tiantoken 图片 provider 缺少 BASE_URL 配置」，没有点名变量名，而 `TIANTOKEN_*` 已不再从 `VECTOR_ENGINE_*` 回退，运维迁移时不易定位。
+- 决策：保持「不回退、缺失即启动失败」，但报错文案补上具体变量名（`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 或 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`）；client 构造成功后用 `info` 记录 provider、base_url、超时与对应 env 变量名，便于确认实际生效的 provider 配置。
+- 验证：`cargo check -p api-server` 通过；`cargo test -p api-server` 1115 项通过（0 失败）。
+
 ## 2026-09-21 合并 origin/master：Supervisor 永久退役，策划 V1V2 退役落到当前两条产品路径

 - 背景：`refactor/split-direct-project`（DirectProject 独立聊天容器）与 `origin/master`（#355 退役策划 Agent V1/V2）在 2026-09-18 之后各走一条线：本分支删掉 Supervisor 前端链路、把立项策划收敛到 `view/project-development/planning/`，master 删掉整套策划 V1/V2（前端会话 / 审批卡 / 适配器 / 类型与 Rust `planning_*_v2` 命令、`planning_gdd_model.rs`、`planning_policy_v2.rs`、`planning_session_v2.rs`）只保留 Design Agent。两边都在删 Supervisor，冲突集中在 `App.tsx`、聊天视图（`PlanningChatView`、`DirectProjectTurn`、`ToolCallGroup`）、Direct composer / 引用输入区、`styles.css`、Rust direct user item 与 appSurface 用例。
@@ -9201,6 +9249,31 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证：限速后 `Genarrative-Full-Build-And-Deploy` #289 / #290 SUCCESS；采样期 Jenkins 峰值 10.2~10.5 核、限流不足 2s（可忽略），runner 峰值 12.07 核且持续出现 throttling，整机回落到 2.6%~19.8%。
 - 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。

+## 2026-09-18 GPT Image 2.5 业务模型与具体 provider 定价路由
+
+- **决策**：新任务使用业务模型值 `gpt-image-2.5`；api-server 按任务显式 dispatch 具体模型 `gpt-image-2.5-flare-c`（无参考图的生成）或 `gpt-image-2.5-sunburst-c`（编辑，以及带参考图的生成），并把同一具体 key 交给 `platform-image` 与后台定价解析。带参考图的生成任务因为必须走 edits multipart，dispatch、审计与计价统一按编辑 concrete model；同模型重试不跨模型 fallback。
+- **历史兼容**：已持久化 `gpt-image-2` 读回原值不改写；基于旧资源发起新任务时，在提交边界解析为 `gpt-image-2.5`，新任务/新产物按新业务值和当前 task price 处理。旧 `gpt-image-2-c` 仅保留历史审计，不再作为 fallback 或业务模型。
+- **可见性**：普通主站前端和公开定价 API 不接收具体 provider key；新生成 UI label 为 `GPT Image 2.5`，历史资源/旧编辑上下文不扩散该 label。admin Web/API 是明确例外，可查看和编辑两个具体定价 key。旧单 key 定价配置允许受控 backfill，并加 compatibility TODO。【已被 2026-09-22「模型定价改为『编译内置默认 + 持久化覆盖』叠加，删除受控 backfill」取代：缺失模型条目改为继承编译内置默认值，两个 backfill 函数已删除，旧配置里只自定义过 `gpt-image-2` 的价格不再传播到 2.5 档位。】
+- **关联 ADR**：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)。
+
+- **补充**：GPT Image 2.5 的两个具体模型通过显式 `TIANTOKEN_BASE_URL` 与独立 `TIANTOKEN_API_KEY` 发送；环境变量缺失时必须失败，禁止使用 VectorEngine 配置或 API key 回退。
+
+## 2026-09-18 GPT Image 2.5 provider-neutral 执行器与双 client 启动边界
+
+- **决策**：图片协议执行逻辑保持单一共享实现；只抽出 provider client 的 identity、base URL、API key 和 client 构造，通过依赖注入复用请求 body、multipart、尺寸、retry、响应和 audit。
+- **路由**：`gpt-image-2.5-flare-c` / `gpt-image-2.5-sunburst-c` 走 Tiantoken；`gemini-3.1-flash-image-preview`（nanobanana）走 VectorEngine；`gpt-image-2` / `gpt-image-2-c` 仅是历史字符串，新任务不再进入旧 GPT Image 2 路由；未知 model 拒绝。
+- **启动**：api-server 启动时同时构造 VectorEngine 与 Tiantoken 两个 required client；各自只读取自己的环境变量，任一配置缺失即启动失败，不延迟到首次请求。
+- **重试**：只在同一个 concrete model 内 retry，禁止跨 model、跨 provider fallback。
+- **关联文档**：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)、[`docs/project-memory/plans/【里程碑】GPT Image 2.5 provider边界重构-2026-09-18.md`](../plans/【里程碑】GPT%20Image%202.5%20provider边界重构-2026-09-18.md)。
+
+## 2026-09-19 Tiantoken 凭据落到 AppConfig 字段并修复编辑器 LLM 测试夹具
+
+- **决策**：Tiantoken 凭据仍然只从 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 读取，不回退 VectorEngine；读取点从 `AppState::new` 前移到 `AppConfig::from_env()`，落到 `AppConfig.tiantoken_base_url` / `AppConfig.tiantoken_api_key` 两个字段，与其它 provider 的配置形态一致，`AppState` 构造与测试构造复用同一条路径；删除 `config::tiantoken_base_url()` / `config::tiantoken_api_key()` 两个现读环境变量的访问器。
+- **原因**：2026-09-18 的「双 provider 启动边界」改成现读环境变量后，`editor_background_music_prompt_assist`、`editor_sound_effect_prompt_assist`、`vector_engine_audio_generation/sound_effect_translation` 三处 mock LLM 夹具仍用 `AppConfig.vector_engine_*` 构造状态，28 条用例拿到 503 `editor_llm_unavailable`。改用进程环境变量做夹具会让并行用例互相踩 `TIANTOKEN_*`，因此把凭据落到 config 字段而不是在测试里 set_var。
+- **边界**：ADR 的「不得回退 VectorEngine 或其 API key」仍然成立，`from_env` 只读 `TIANTOKEN_*`，并有用例固定该行为。
+- **验证**：`cargo test -p api-server` 1060 passed / 0 failed / 6 ignored；`cargo fmt --all --check`、`npm run check:encoding`、`git diff --check` 通过。
+- **关联文档**：[`docs/adr/【ADR】GPT Image 2.5模型路由与历史值兼容-2026-09-18.md`](../../adr/【ADR】GPT%20Image%202.5模型路由与历史值兼容-2026-09-18.md)、[`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`](../../【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)。
+
 ## 2026-09-17 AGC 抠图接入本地资源编辑恢复闭环

 - 背景：`agc_remove_background` 原先只提交 `/api/editor/images/background-removals` 并返回 `queued`，没有轮询远端任务、下载完成媒体或写入本地 manifest；BgFilter 已成功处理但 Agent 因此永远只能看到受理回执。
@@ -7,6 +7,14 @@
 - 处理：客户端画布图标生成只 trim 描述并以单项 `iconDescriptions` 原样提交，保留内部换行；面板与原生入口按 `200` 个 Unicode 码点校验并拒绝空白或超限输入，不静默截断、不机械拆条。服务端共用的提示词流程负责规范图、背景与排布要求；其它图片生成的 `32000` 字符上限保持不变。
 - 验证：检查实际请求体与 trim 后的原文一致，并覆盖 `200/201` 码点、补充平面字符、换行和空白输入；不能只断言“请求长度未超限”。完整合同见 [画板图标素材生成入口设计](../../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。

+## 测试内 mock HTTP server 必须按 Content-Length 读满请求体再断言
+
+- 现象：`platform-image` 的 `nanobanana_generate_content_posts_native_body_and_reads_inline_data` 在本机（Windows）稳定红、在 CI 上存在偶发红，断言 `request_text.contains("\"imageSize\":\"512\"")` 失败，看起来像实现没有发送请求体。
+- 原因：该 mock 用例自带一版「读到第一个 `\r\n\r\n` 就 break」的读循环，而 `\r\n\r\n` 只代表请求头结束；reqwest 写完头再写 body，TCP 分片下 body 常常还没到。断言实际只看到头和半截 body，是测试脚手架的竞态，与平台 / 网络栈无关，被测代码本身没有问题。
+- 处理：mock server 一律复用同文件已有的 `read_http_request`，先解析 `Content-Length`，读满 `header_end + content_length` 再断言；同文件的 `image_edit_retries_send_timeout_once_and_succeeds` 与 `image_provider_deadline_clips_stalled_attempt_and_prevents_retry` 早已使用该 helper。
+- 验证：把断言期望值临时改成错误值，用例必须失败（证明读到了真实 body）；改回后期望连续重跑 8 次全绿，并跑 `cargo test -p platform-image` 全量（22 + 64 + 14 passed）。
+- 关联：`server-rs/crates/platform-image/tests/image_provider.rs`。
+
 ## 2026-09-21 不同渠道的包体在同一台设备安装会互相顶掉

 - **现象**：在一台已经装了某个渠道 AGC 客户端的设备上安装另一个渠道的安装包，装完后旧客户端直接消失（安装目录被覆盖、卸载项被接管），更新端点、平台服务器与本地登录态一起换成新渠道的；两个渠道的客户端无法共存。
@@ -2503,7 +2511,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`

 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
 - 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流；2026-07-05 后创意 Agent 文本链路也改为 VectorEngine Chat Completions `gpt-5.4-mini`，APIMart 不再作为当前创意 Agent 来源。
- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，业务 / 计费与 provider 首发模型均为 `gpt-image-2`，仅在符合条件的 provider 失败后切到兜底模型 `gpt-image-2-c`。
+- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，新任务业务模型为 `gpt-image-2.5`，provider 具体模型为 `gpt-image-2.5-flare-c`（不带参考图的生成）/ `gpt-image-2.5-sunburst-c`（编辑与带参考图的生成），带参考图的生成按编辑档计价，只在同一具体模型内重试。历史兜底模型 `gpt-image-2-c` 已从代码整体删除，不再存在任何 fallback 路径，请求体里出现该值即视为异常。
 - 验证：运行 `cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml` 和相关玩法图片生成测试；真实联调只在本地私密环境放置 VectorEngine key。
 - 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。

@@ -90,7 +90,7 @@ provider 响应只提取并透传 `data[].b64_json` 字符串，不在服务端
 ## 代码拆分

 - `server-rs/crates/api-server/src/raw_image.rs`：独立路由 handler、multipart 字段解析、请求/响应 DTO、PNG 输入校验、预检查和 raw billing 编排。
- `server-rs/crates/platform-image/src/vector_engine/raw_edit.rs`：raw 编辑选项、严格尺寸校验、独立 provider 请求映射和 `b64_json` 响应透传；由 api-server 按现有图片 API 传统构造并传入共享的 VectorEngine `reqwest::Client`，不在每个 raw 调用内部重复构造 client。每次请求仍用 `effective_request_timeout_ms` 通过 request builder 设置剩余 deadline；不修改统一 transport builder 的连接池策略。
+- `server-rs/crates/platform-image/src/raw_image_edit/mod.rs`：raw 编辑选项、严格尺寸校验、独立 provider 请求映射和 `b64_json` 响应透传；由 api-server 按现有图片 API 传统构造并传入启动时构造的 Tiantoken `reqwest::Client`，不在每个 raw 调用内部重复构造 client。每次请求仍用 `effective_request_timeout_ms` 通过 request builder 设置剩余 deadline；不修改统一 transport builder 的连接池策略。

 raw-edit 的图片输入使用独立的 `RawImageEditImage`（`bytes::Bytes`），由 reqwest `Part::stream(Body::from(Bytes))` 直接接管 multipart 请求体，避免整图和掩码在 `Part::bytes` 的 `Cow<[u8]>` 转换中再次复制。既有 `ReferenceImage`、`DownloadedImage` 及 curl/编辑器链路继续保持 `Vec<u8>` 契约，不因 raw-edit 引入全局字节类型迁移。

@@ -238,13 +238,13 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/

 本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.8.3`，CLI / standalone commit 固定核对为 `8e410d2842147bd8e5a32a9589cc00c19f7478e2`。若版本或 commit 错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为现役 settings、editor project 或 profile procedure 超时。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；其它版本可执行 `spacetime version install <version> && spacetime version use <version>`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会把 tool version 和 commit 一起写入 `dev-spacetime-tool-version`，启动新 standalone 与复用已有本地进程时都要求 `2.8.3 + 8e410d28...` 同时匹配；旧版本或旧单行版本记录会拒绝复用并要求重启。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。

-本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时，确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。VectorEngine 配置仅保留给 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 Tiantoken provider 首选请求都使用 `gpt-image-2`，符合条件时才回退到兜底模型 `gpt-image-2-c`；图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
+本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时，确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git；同时确认 VectorEngine 的 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 已配置，因为两个图片 client 都在 api-server 启动时构造，任一缺失都会阻止启动。VectorEngine 配置仍保留给 nanobanana 与 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 与 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是两条互相独立、默认都为 `1000000` 的单次 attempt 上限：前者只作用于 Tiantoken 图片 client（GPT Image 2.5 生成 / 编辑），后者只作用于 VectorEngine 图片 client（nanobanana 等），任一 provider 的超时设置都不会改写另一个；配置加载层允许显式值低于默认值，不再在读取环境变量时强制抬高。新生成任务使用业务模型 `gpt-image-2.5`，api-server 显式分派 `gpt-image-2.5-flare-c`（不带参考图的 generate）或 `gpt-image-2.5-sunburst-c`（edit 与带参考图的 generate，计价同步走编辑档）；已持久化的 `gpt-image-2` 只在提交边界按兼容规则解析，不改写历史值，也不回退到旧 GPT Image 2 路由；已退役的 `gpt-image-2-c` 已从代码整体删除，传入即按不支持的值处理。图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。

 编辑器 ElevenLabs 音效生成只从服务端读取 `ELEVENLABS_BASE_URL`、`ELEVENLABS_API_KEY` 和 `ELEVENLABS_REQUEST_TIMEOUT_MS`，timeout 默认 `180000ms`；base URL 或 Key 缺失时失败关闭，不回退 Vidu。生产 API 与 external-generation worker 通过共享 API env 取得同一配置，模板见 `deploy/env/api-server.env.example`；Key 不得进入 Web/Vite 环境、命令参数、日志、fixture 或仓库。普通测试只使用 loopback mock，禁止把真实付费请求作为 T3 自动验收。

 SFX V2 发布必须使用维护窗：先关闭 SFX 入队，再对显式目标执行只读 `spacetime sql <database> --server <server-url> --format json "SELECT job_id, status, request_payload_json FROM external_generation_job WHERE job_kind = 'editor_sound_effect_generation' AND (status = 'pending' OR status = 'running')"`；结果非零时保持旧 Worker drain，不得删除任务或让新 Worker 解析旧 Vidu payload。禁止依赖默认 server，禁止使用 `--root-dir`。清零后先部署共享 env 已对齐的 api-server / external-generation worker，检查 `/healthz` 和 Worker 启动，再部署 Web 并小流量开放 SFX。灰度对账 job 完成数、退款数、ElevenLabs POST 数、完成资源数和孤儿资源；翻译失败仍调用 provider、单 job provider POST 大于一次、成功退款或失败未退款均应立即停止放量。回滚先停止入队并收口 V2 pending / running job，不自动切回 Vidu，不执行 SpacetimeDB schema 或数据回滚。完整清单见 `docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md`。

-VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会在一次业务请求总上限 5 次内处理；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。首个 provider attempt 使用 `gpt-image-2`；明确模型不可用、408 / 非拒绝类 429 / 5xx、响应解析失败或非拒绝类缺图时，下一 attempt 直接切兜底模型 `gpt-image-2-c`，之后只在剩余次数内重试兜底模型。发送 / 连接错误无法确认上游是否已受理，只重试同一首选模型，不切模型；认证、普通参数、安全拒绝、图片下载和 budget 错误同样不切。worker 从 job 开始的同一时钟起点计算绝对 deadline，常规保留最后 `60` 秒给审计、OSS 和终态写回；job 预算小于 `120` 秒时保留一半。VectorEngine 单次 attempt timeout 取配置值和剩余 provider 预算的较小值；退避或模型切换后已没有下一次 attempt 的预算时立即停止。该 deadline 覆盖参考图、provider 请求 / 响应和响应图片下载的整次 provider future，但只在 worker 进程内通过 `RequestContext` 传递；普通 HTTP / `inline` 没有该 deadline，继续保持原有 timeout 和重试行为。日志中 `VectorEngine 首选图片模型失败，切换兼容模型` 会携带 `fallback_from_model` / `fallback_to_model`；即使回退成功，首选模型错误仍写入 `external_api_call_failure`，成功运行摘要的 `recoveredFailureCount` 同时递增。排查生产失败时应同时统计 fallback / retry 日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。这项收口不修改 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽与原子退款语义。
+VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会在一次业务请求总上限 5 次内处理；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。每次 provider attempt 都按任务确定的具体模型发送（`gpt-image-2.5-flare-c` 生成 / `gpt-image-2.5-sunburst-c` 编辑 / `gemini-3.1-flash-image-preview` nanobanana）；明确模型不可用、408 / 非拒绝类 429 / 5xx、响应解析失败或非拒绝类缺图时只在同一具体模型内重试，不切模型，历史兜底模型 `gpt-image-2-c` 已从代码整体删除。发送 / 连接错误无法确认上游是否已受理，同样只重试同一模型；认证、普通参数、安全拒绝、图片下载和 budget 错误不重试。worker 从 job 开始的同一时钟起点计算绝对 deadline，常规保留最后 `60` 秒给审计、OSS 和终态写回；job 预算小于 `120` 秒时保留一半。VectorEngine 单次 attempt timeout 取配置值和剩余 provider 预算的较小值；退避后已没有下一次 attempt 的预算时立即停止。该 deadline 覆盖参考图、provider 请求 / 响应和响应图片下载的整次 provider future，但只在 worker 进程内通过 `RequestContext` 传递；普通 HTTP / `inline` 没有该 deadline，继续保持原有 timeout 和重试行为。重试过程中的失败 attempt 只写 provider 日志；`external_api_call_failure` 只记录终态的 provider 错误 audit，成功运行摘要不再包含已删除的 `recoveredFailureCount`。排查生产失败时应同时统计 retry 日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。这项收口不修改 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽与原子退款语义。

 图片编辑器生成属于持久队列长任务：提交接口返回 job 后，前端通过 `/api/runtime/external-generation/jobs/{jobId}` 与编辑器项目资源状态收敛。生产排查小程序或 WebView `Failed to fetch` 时，若 Nginx access log 为 `499`、`upstream_status=-`，先按提交请求的 `request_id`、job id、worker 日志和 `external_api_call_failure` 对齐真实任务，不把客户端断开直接判定为 provider 失败。

@@ -63,7 +63,7 @@ SpacetimeDB 模块会在事务内重复执行同等强度的校验，并拒绝

 所有会调用外部生成 provider 的编辑器生成请求都必须由后端计算价格，前端请求不提交价格字段；同步执行按当前运行时配置进入 `execute_billable_asset_operation_with_cost` 预扣泥点，预扣失败不得继续调用上游。外部生成队列在入队时把价格写入 `external_generation_job.price_mud_points`，worker 必须用该冻结价格完成扣费、退款、响应和资产成本持久化，配置更新不得改变已入队任务金额。普通图片、规范、角色、UI 设计、宣发素材、快速编辑 / 图片修改、图标 spritesheet、UI 设计图提取素材、视频、角色动作、音效和背景音乐均遵循该规则。背景色决策（gpt-5-mini）本身也是一次上游调用，同样必须在预扣泥点之后发起：预扣前只做颜色无关的算价 / 校验（动画用默认色占位算价），决策放进 billable 闭包，余额不足则决策不跑、决策失败走失败退款。需要向前端展示实际扣费时，由后端在响应中返回 `priceMudPoints`。

-SFX V2 上线前已经存在的 SpacetimeDB 定价快照或旧本地 override 可能只有 `audio1.0`。读取这类历史快照时，`api-server` 只允许从当前受控默认配置补入缺失的 `eleven_text_to_sound_v2` 条目，再执行完整配置校验，使旧快照可继续读取；其它必需模型缺失仍失败。该兼容不修改 schema，也不在读取时写数据库或 override；下一次后台保存完整定价矩阵时自然持久化新键。发布前仍应确认运行时配置中的新键和价格已经批准。
+SFX V2 上线前已经存在的 SpacetimeDB 定价快照或旧本地 override 可能只有 `audio1.0`。读取这类历史快照时，`api-server` 以编译内置默认（`server-rs/crates/api-server/config/editor-generation-pricing.default.json`）为基线、叠加快照里显式给出的模型条目，缺失条目（含 `eleven_text_to_sound_v2` 与两个 `gpt-image-2.5-*-c` 具体 key）一律继承默认值，再执行完整配置校验；不再为单个模型维护受控 backfill，写坏的条目仍由校验拦截。该兼容不修改 schema，也不在读取时写数据库或 override；下一次后台保存完整定价矩阵时自然持久化新键。发布前仍应确认运行时配置中的新键和价格已经批准，注意旧快照里只自定义过历史 `gpt-image-2` 价格时，新任务按默认档位计价。

 ## 运行时身份首次授权

@@ -15,6 +15,20 @@
        "2K": 5
      }
    },
+    "gpt-image-2.5-flare-c": {
+      "unit": "perGeneration",
+      "prices": {
+        "1K": 3,
+        "2K": 5
+      }
+    },
+    "gpt-image-2.5-sunburst-c": {
+      "unit": "perGeneration",
+      "prices": {
+        "1K": 3,
+        "2K": 5
+      }
+    },
    "seedance2.0-fast": {
      "unit": "perSecond",
      "prices": {
@@ -5901,14 +5901,29 @@ mod tests {
            payload["models"]["gemini-3.1-flash-image-preview"]["prices"]["1K"],
            Value::Number(12.into())
        );
+        // 公开投影只暴露业务模型名 gpt-image-2.5（取生成档价格），
+        // 不外泄具体 provider key，也不再暴露历史 gpt-image-2。
        assert_eq!(
-            payload["models"]["gpt-image-2"]["prices"]["1K"],
+            payload["models"]["gpt-image-2.5"]["prices"]["1K"],
            Value::Number(3.into())
        );
        assert_eq!(
-            payload["models"]["gpt-image-2"]["prices"]["2K"],
+            payload["models"]["gpt-image-2.5"]["prices"]["2K"],
            Value::Number(5.into())
        );
+        let public_models = payload["models"]
+            .as_object()
+            .expect("公开定价必须暴露 models 对象");
+        for hidden_model in [
+            "gpt-image-2",
+            "gpt-image-2.5-flare-c",
+            "gpt-image-2.5-sunburst-c",
+        ] {
+            assert!(
+                !public_models.contains_key(hidden_model),
+                "公开定价不应暴露 {hidden_model}"
+            );
+        }
        assert_eq!(
            payload["models"]["audio1.0"]["price"],
            Value::Number(5.into())
@@ -5954,10 +5969,14 @@ mod tests {
                                    "unit": "perGeneration",
                                    "prices": { "0.5K": 9, "1K": 18, "2K": 36 }
                                },
-                                "gpt-image-2": {
+                                "gpt-image-2.5-flare-c": {
                                    "unit": "perGeneration",
                                    "prices": { "1K": 31, "2K": 62 }
                                },
+                                "gpt-image-2.5-sunburst-c": {
+                                    "unit": "perGeneration",
+                                    "prices": { "1K": 41, "2K": 82 }
+                                },
                                "seedance2.0-fast": {
                                    "unit": "perSecond",
                                    "prices": { "480p": 11, "720p": 22, "1080p": 44 }
@@ -5997,6 +6016,7 @@ mod tests {
        assert_eq!(response.status(), StatusCode::OK);

        let public_response = app
+            .clone()
            .oneshot(
                Request::builder()
                    .uri("/api/editor/generation-pricing")
@@ -6014,10 +6034,24 @@ mod tests {
        let payload: Value =
            serde_json::from_slice(&body).expect("public pricing payload should be json");

+        // 公开投影按业务模型名暴露生成档价格；具体 provider key 不下发普通前端。
        assert_eq!(
-            payload["models"]["gpt-image-2"]["prices"]["2K"],
+            payload["models"]["gpt-image-2.5"]["prices"]["2K"],
            Value::Number(62.into())
        );
+        let public_models = payload["models"]
+            .as_object()
+            .expect("公开定价必须暴露 models 对象");
+        for hidden_model in [
+            "gpt-image-2",
+            "gpt-image-2.5-flare-c",
+            "gpt-image-2.5-sunburst-c",
+        ] {
+            assert!(
+                !public_models.contains_key(hidden_model),
+                "公开定价不应暴露 {hidden_model}"
+            );
+        }
        assert_eq!(
            payload["models"]["audio1.0"]["unit"],
            Value::String("perGeneration".to_string())
@@ -6030,6 +6064,35 @@ mod tests {
            payload["models"]["seedance2.0"]["prices"]["720p"],
            Value::Number(26.into())
        );
+
+        // admin 定价接口是 concrete provider key 的明确例外，读回的是保存时的原始 key。
+        let admin_response = app
+            .oneshot(
+                Request::builder()
+                    .uri("/admin/api/editor-generation-pricing")
+                    .header("authorization", format!("Bearer {admin_token}"))
+                    .body(Body::empty())
+                    .expect("admin pricing request should build"),
+            )
+            .await
+            .expect("admin pricing request should succeed");
+        assert_eq!(admin_response.status(), StatusCode::OK);
+        let admin_body = admin_response
+            .into_body()
+            .collect()
+            .await
+            .expect("admin pricing body should collect")
+            .to_bytes();
+        let admin_payload: Value =
+            serde_json::from_slice(&admin_body).expect("admin pricing payload should be json");
+        assert_eq!(
+            admin_payload["models"]["gpt-image-2.5-flare-c"]["prices"]["2K"],
+            Value::Number(62.into())
+        );
+        assert_eq!(
+            admin_payload["models"]["gpt-image-2.5-sunburst-c"]["prices"]["2K"],
+            Value::Number(82.into())
+        );
    }

    /// 中文注释：验证入口公告拒绝可执行脚本，避免后台配置变成不受控注入。
@@ -34,10 +34,11 @@ use crate::{
        build_character_visual_negative_prompt, build_character_visual_prompt,
        build_fallback_moderation_safe_character_visual_prompt,
    },
+    editor_generation_config::editor_image_generation_concrete_model,
    http_error::AppError,
    openai_image_generation::{
-        DownloadedOpenAiImage, GPT_IMAGE_2_MODEL, OpenAiImageSettings,
-        build_openai_image_http_client, create_openai_image_generation,
+        DownloadedOpenAiImage, GPT_IMAGE_2_5_BUSINESS_NAME, OpenAiImageSettings,
+        build_openai_image_http_client, create_openai_image_generation_with_model,
        require_openai_image_settings,
    },
    platform_errors::map_oss_error,
@@ -45,7 +46,7 @@ use crate::{
    state::AppState,
 };

-const CHARACTER_VISUAL_MODEL: &str = GPT_IMAGE_2_MODEL;
+const CHARACTER_VISUAL_MODEL: &str = GPT_IMAGE_2_5_BUSINESS_NAME;
 const CHARACTER_VISUAL_ASSET_KIND: &str = "character_visual";
 const CHARACTER_VISUAL_ENTITY_KIND: &str = "character";
 const CHARACTER_VISUAL_SLOT: &str = "primary_visual";
@@ -777,13 +778,13 @@ fn build_character_visual_job_payload(task: AiTaskSnapshot) -> CharacterAssetJob
 }

 fn resolve_character_visual_model(value: &str) -> String {
-    // 中文注释：旧前端和历史草稿可能仍传 wan2.7-image-pro；RPG 主图当前统一归一到 gpt-image-2。
+    // 中文注释：旧前端和历史草稿可能仍传旧模型；只在新任务提交边界归一到当前业务模型。
    let trimmed = value.trim();
    if !trimmed.is_empty() && trimmed != CHARACTER_VISUAL_MODEL {
        tracing::warn!(
            requested_model = trimmed,
            effective_model = CHARACTER_VISUAL_MODEL,
-            "角色主形象图片模型已归一到 gpt-image-2"
+            "角色主形象图片模型已归一到当前业务模型"
        );
    }
    CHARACTER_VISUAL_MODEL.to_string()
@@ -940,15 +941,19 @@ async fn create_character_visual_generation(
 async fn create_character_visual_generation_once(
    http_client: &reqwest::Client,
    settings: &OpenAiImageSettings,
-    _model: &str,
+    model: &str,
    prompt: &str,
    size: &str,
    candidate_count: u32,
    reference_images: &[String],
 ) -> Result<GeneratedCharacterVisuals, AppError> {
-    let generated = create_openai_image_generation(
+    // 中文注释：参考图存在时后端会走编辑端点，因此必须提交编辑 concrete model 而不是生成模型。
+    let provider_model =
+        editor_image_generation_concrete_model(Some(model), !reference_images.is_empty());
+    let generated = create_openai_image_generation_with_model(
        http_client,
        settings,
+        provider_model,
        prompt,
        Some(build_character_visual_negative_prompt().as_str()),
        size,
@@ -1921,12 +1926,12 @@ mod tests {
    }

    #[test]
-    fn legacy_character_visual_model_normalizes_to_gpt_image_2() {
+    fn legacy_character_visual_model_normalizes_to_gpt_image_2_5() {
        assert_eq!(
            resolve_character_visual_model("wan2.7-image-pro"),
-            "gpt-image-2"
+            "gpt-image-2.5"
        );
-        assert_eq!(resolve_character_visual_model(""), "gpt-image-2");
+        assert_eq!(resolve_character_visual_model(""), "gpt-image-2.5");
    }

    #[test]
@@ -18,6 +18,7 @@ const DEFAULT_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS: u64 = 600;
 const DEFAULT_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS: u64 = 900;
 const DEFAULT_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS: u64 = 1_800;
 pub(crate) const DEFAULT_VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS: u64 = 1_000_000;
+pub(crate) const DEFAULT_TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS: u64 = 1_000_000;
 pub(crate) const DEFAULT_ELEVENLABS_REQUEST_TIMEOUT_MS: u64 = 180_000;
 const DEFAULT_EDITOR_BGFILTER_BASE_URL: &str = "http://58.87.105.82/bgfilter";
 const DEFAULT_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS: u64 = 5_000;
@@ -219,6 +220,18 @@ pub struct AppConfig {
    pub vector_engine_api_key: Option<String>,
    pub vector_engine_image_request_timeout_ms: u64,
    pub vector_engine_audio_request_timeout_ms: u64,
+    /// Tiantoken 是 GPT Image 2.5 图片链路和创意 Agent 文本链路的 provider。
+    ///
+    /// 只从 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 读取，刻意不回退 VectorEngine 凭据；
+    /// 启动时落到 `AppConfig` 字段，使 `AppState` 构造与测试构造复用同一条路径。
+    pub tiantoken_base_url: String,
+    pub tiantoken_api_key: Option<String>,
+    /// Tiantoken 图片链路（GPT Image 2.5 生成 / 编辑）的单次 attempt 超时。
+    ///
+    /// 与 `vector_engine_image_request_timeout_ms` 相互独立，只由
+    /// `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 配置，避免一个 provider 的超时设置
+    /// 顺带改写另一个 provider 的 deadline。
+    pub tiantoken_image_request_timeout_ms: u64,
    pub elevenlabs_base_url: String,
    pub elevenlabs_api_key: Option<String>,
    pub elevenlabs_request_timeout_ms: u64,
@@ -533,6 +546,9 @@ impl Default for AppConfig {
            vector_engine_api_key: None,
            vector_engine_image_request_timeout_ms: DEFAULT_VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS,
            vector_engine_audio_request_timeout_ms: 180_000,
+            tiantoken_base_url: String::new(),
+            tiantoken_api_key: None,
+            tiantoken_image_request_timeout_ms: DEFAULT_TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS,
            elevenlabs_base_url: String::new(),
            elevenlabs_api_key: None,
            elevenlabs_request_timeout_ms: DEFAULT_ELEVENLABS_REQUEST_TIMEOUT_MS,
@@ -1330,12 +1346,25 @@ impl AppConfig {

        config.vector_engine_api_key = read_first_non_empty_env(&["VECTOR_ENGINE_API_KEY"]);

-        if let Some(tiantoken_image_request_timeout_ms) = read_first_positive_u64_env(&[
-            "TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS",
-            "VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS",
-        ]) {
+        if let Some(vector_engine_image_request_timeout_ms) =
+            read_first_positive_u64_env(&["VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS"])
+        {
            // 单次 attempt 上限允许按环境收短；worker 调用还会受整次任务的绝对 deadline 约束。
-            config.vector_engine_image_request_timeout_ms = tiantoken_image_request_timeout_ms;
+            config.vector_engine_image_request_timeout_ms = vector_engine_image_request_timeout_ms;
+        }
+
+        // Tiantoken 只读取自己的环境变量，不从 VectorEngine 配置回退；启动时冻结进 AppConfig，
+        // 供 AppState 构造编辑器 LLM / 图片 client 时复用同一条配置路径。
+        config.tiantoken_base_url =
+            read_first_non_empty_env(&["TIANTOKEN_BASE_URL"]).unwrap_or_default();
+        config.tiantoken_api_key = read_first_non_empty_env(&["TIANTOKEN_API_KEY"]);
+
+        if let Some(tiantoken_image_request_timeout_ms) =
+            read_first_positive_u64_env(&["TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS"])
+        {
+            // Tiantoken 图片链路独立计时：`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 不再改写
+            // VectorEngine 的图片超时，两个 provider 各用自己的配置与默认值。
+            config.tiantoken_image_request_timeout_ms = tiantoken_image_request_timeout_ms;
        }

        if let Some(vector_engine_audio_request_timeout_ms) =
@@ -1481,20 +1510,6 @@ impl AppConfig {
    }
 }

-/// Tiantoken 是图片、文本和旧版非 Suno 音频生成的新 provider。
-///
-/// 这里保留对 `AppConfig.vector_engine_*` 的回退，方便测试构造的旧配置继续工作；
-/// 生产环境一旦设置了新的 `TIANTOKEN_*` 变量，就不会再把非 Suno 请求发往 VectorEngine。
-pub(crate) fn tiantoken_base_url(config: &AppConfig) -> String {
-    read_first_non_empty_env(&["TIANTOKEN_BASE_URL"])
-        .unwrap_or_else(|| config.vector_engine_base_url.clone())
-}
-
-pub(crate) fn tiantoken_api_key(config: &AppConfig) -> Option<String> {
-    read_first_non_empty_env(&["TIANTOKEN_API_KEY"])
-        .or_else(|| config.vector_engine_api_key.clone())
-}
-
 fn read_first_non_empty_env(keys: &[&str]) -> Option<String> {
    keys.iter().find_map(|key| {
        env::var(key).ok().and_then(|value| {
@@ -1800,7 +1815,6 @@ mod tests {
        DEFAULT_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS,
        DEFAULT_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS, ExternalGenerationMode,
        LlmProvider, ProcessRole, parse_bool, parse_external_generation_mode, parse_process_role,
-        tiantoken_api_key, tiantoken_base_url,
    };
    use std::{
        fs,
@@ -2008,37 +2022,52 @@ mod tests {
    }

    #[test]
-    fn tiantoken_provider_prefers_new_env_names_over_legacy_vector_engine_config() {
+    fn tiantoken_credentials_never_fall_back_to_vector_engine_env() {
        let _guard = ENV_LOCK
            .get_or_init(|| Mutex::new(()))
            .lock()
            .expect("env lock should not poison");
-        let mut config = AppConfig::default();
-        config.vector_engine_base_url = "https://vector.example.invalid".to_string();
-        config.vector_engine_api_key = Some("legacy-vector-key".to_string());
        unsafe {
            std::env::set_var("TIANTOKEN_BASE_URL", " https://api.tiantoken.example/ ");
            std::env::set_var("TIANTOKEN_API_KEY", " tiantoken-key ");
+            std::env::set_var("VECTOR_ENGINE_BASE_URL", "https://vector.example.invalid");
+            std::env::set_var("VECTOR_ENGINE_API_KEY", "legacy-vector-key");
        }

+        let config = AppConfig::from_env();
+
+        assert_eq!(config.tiantoken_base_url, "https://api.tiantoken.example/");
+        assert_eq!(config.tiantoken_api_key.as_deref(), Some("tiantoken-key"));
        assert_eq!(
-            tiantoken_base_url(&config),
-            "https://api.tiantoken.example/"
+            config.vector_engine_base_url,
+            "https://vector.example.invalid"
+        );
+        assert_eq!(
+            config.vector_engine_api_key.as_deref(),
+            Some("legacy-vector-key")
        );
-        assert_eq!(tiantoken_api_key(&config).as_deref(), Some("tiantoken-key"));

        unsafe {
            std::env::remove_var("TIANTOKEN_BASE_URL");
            std::env::remove_var("TIANTOKEN_API_KEY");
        }
+        let config = AppConfig::from_env();
+
+        assert_eq!(config.tiantoken_base_url, "");
+        assert_eq!(config.tiantoken_api_key, None);
        assert_eq!(
-            tiantoken_base_url(&config),
+            config.vector_engine_base_url,
            "https://vector.example.invalid"
        );
        assert_eq!(
-            tiantoken_api_key(&config).as_deref(),
+            config.vector_engine_api_key.as_deref(),
            Some("legacy-vector-key")
        );
+
+        unsafe {
+            std::env::remove_var("VECTOR_ENGINE_BASE_URL");
+            std::env::remove_var("VECTOR_ENGINE_API_KEY");
+        }
    }

    #[test]
@@ -2274,6 +2303,7 @@ mod tests {
            std::env::remove_var("VECTOR_ENGINE_BASE_URL");
            std::env::remove_var("VECTOR_ENGINE_API_KEY");
            std::env::remove_var("VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS");
            std::env::remove_var("HYPER3D_BASE_URL");
            std::env::remove_var("DASHSCOPE_SCENE_IMAGE_MODEL");
            std::env::remove_var("DASHSCOPE_REFERENCE_IMAGE_MODEL");
@@ -2292,6 +2322,7 @@ mod tests {
            std::env::set_var("VECTOR_ENGINE_BASE_URL", "https://vector.internal.example");
            std::env::set_var("VECTOR_ENGINE_API_KEY", "vector-engine-key");
            std::env::set_var("VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS", "210000");
+            std::env::set_var("TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS", "180000");
            std::env::set_var("HYPER3D_BASE_URL", "https://model.internal.example/api/v2");
            std::env::set_var("DASHSCOPE_SCENE_IMAGE_MODEL", "scene-model");
            std::env::set_var("DASHSCOPE_REFERENCE_IMAGE_MODEL", "reference-model");
@@ -2318,6 +2349,8 @@ mod tests {
            "https://vector.internal.example"
        );
        assert_eq!(config.vector_engine_image_request_timeout_ms, 210_000);
+        // 两个 provider 的图片超时互不覆盖：Tiantoken 用 TIANTOKEN_*，VectorEngine 用 VECTOR_ENGINE_*。
+        assert_eq!(config.tiantoken_image_request_timeout_ms, 180_000);
        assert_eq!(
            config.hyper3d_base_url,
            "https://model.internal.example/api/v2"
@@ -2343,6 +2376,7 @@ mod tests {
            std::env::remove_var("VECTOR_ENGINE_BASE_URL");
            std::env::remove_var("VECTOR_ENGINE_API_KEY");
            std::env::remove_var("VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS");
            std::env::remove_var("HYPER3D_BASE_URL");
            std::env::remove_var("DASHSCOPE_SCENE_IMAGE_MODEL");
            std::env::remove_var("DASHSCOPE_REFERENCE_IMAGE_MODEL");
@@ -1,3 +1,4 @@
+use std::borrow::Cow;
 use std::fmt::{Display, Formatter};

 use platform_editor_agent::agent::asset::ImageId;
@@ -28,7 +29,7 @@ use platform_editor_agent::agent::tools::generate_video::{
 };
 use platform_editor_agent::framework::error::PromptError;
 use platform_editor_agent::framework::tool::{Tool, ToolDyn, null_tool_args_as_missing};
-use platform_image::GPT_IMAGE_2_MODEL;
+use platform_image::{GPT_IMAGE_2_5_BUSINESS_NAME, GPT_IMAGE_2_MODEL};
 use serde::Serialize;
 use serde::de::DeserializeOwned;
 use serde_json::{Value, json};
@@ -224,6 +225,47 @@ fn parse_internal<T: DeserializeOwned>(
    })
 }

+/// 把持久化的历史 GPT Image 2 模型别名（`gpt-image-2`）改写为当前
+/// 业务模型 `gpt-image-2.5`。
+///
+/// 平台层图片工具只接受 `gemini-3.1-flash-image-preview` 与 `gpt-image-2.5`，但历史会话
+/// 里仍可能保存着 `gpt-image-2` 的工具调用参数。这里在进入强类型校验前做一次别名归一，
+/// 既让旧调用继续可用，也把计价统一到当前业务模型档位。
+fn normalize_legacy_image_model_args(value: &Value) -> Cow<'_, Value> {
+    let Some(model) = value.get("model").and_then(Value::as_str) else {
+        return Cow::Borrowed(value);
+    };
+    if model.trim() != GPT_IMAGE_2_MODEL {
+        return Cow::Borrowed(value);
+    }
+    let mut normalized = value.clone();
+    if let Some(fields) = normalized.as_object_mut() {
+        fields.insert(
+            "model".to_string(),
+            Value::String(GPT_IMAGE_2_5_BUSINESS_NAME.to_string()),
+        );
+    }
+    Cow::Owned(normalized)
+}
+
+/// 图片类工具的 `validate_args` 入口：先归一历史模型别名，再走强类型反序列化。
+fn parse_invalid_image_args<T: DeserializeOwned>(
+    tool_name: &str,
+    value: &Value,
+) -> Result<T, EditorAgentToolError> {
+    let normalized = normalize_legacy_image_model_args(value);
+    parse_invalid_args(tool_name, &normalized)
+}
+
+/// 图片类工具的 `pricing` 入口：即使调用方直接传入原始 args，也要先归一历史模型别名。
+fn parse_internal_image_args<T: DeserializeOwned>(
+    label: &str,
+    value: &Value,
+) -> Result<T, EditorAgentToolError> {
+    let normalized = normalize_legacy_image_model_args(value);
+    parse_internal(label, &normalized)
+}
+
 /// SFX V2 的显式 `duration: null` 表示自动时长，必须原样保留，不能被通用的
 /// “顶层 null 当缺省”兼容层恢复成手动 5 秒。但其余字段仍要走该兼容层：
 /// `model` 是无 Option 的 String，LLM 传 `model: null` 时若不剥离会直接反序列化失败。
@@ -305,13 +347,14 @@ fn editor_agent_image_mud_points(
    kind: Option<&str>,
    model: &str,
    image_size: Option<&str>,
+    has_reference_images: bool,
 ) -> u32 {
-    pricing.image_generation_mud_points(kind, Some(model), image_size)
+    pricing.image_generation_mud_points(kind, Some(model), image_size, has_reference_images)
 }

 impl EditorAgentTool for GenerateImageTool {
    fn validate_args(&self, args: &Value) -> Result<Value, EditorAgentToolError> {
-        let args: GenerateImageToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateImageToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        GenerateImageTool::validate_args(self, &args)
            .map_err(|error| EditorAgentToolError::invalid_args(error.to_string()))?;
        serialize_normalized_args(Self::NAME, &args)
@@ -322,12 +365,13 @@ impl EditorAgentTool for GenerateImageTool {
        pricing: &EditorGenerationPricingConfig,
        args: &Value,
    ) -> Result<u32, EditorAgentToolError> {
-        let args: GenerateImageToolArgs = parse_internal("generate image args", args)?;
+        let args: GenerateImageToolArgs = parse_internal_image_args("generate image args", args)?;
        Ok(editor_agent_image_mud_points(
            pricing,
            None,
            args.model.as_str(),
            Some(args.image_size.as_str()),
+            !args.reference_image_ids.is_empty(),
        ))
    }

@@ -337,7 +381,8 @@ impl EditorAgentTool for GenerateImageTool {
        pricing: &EditorGenerationPricingConfig,
    ) -> Result<EditorAgentToolCallDisplayArgs, EditorAgentToolError> {
        let price_mud_points = self.pricing(pricing, args)?;
-        let args: GenerateImageToolArgs = parse_internal("generate image display args", args)?;
+        let args: GenerateImageToolArgs =
+            parse_internal_image_args("generate image display args", args)?;
        let mut display_args = EditorAgentToolCallDisplayArgs::default();
        push_image_generation_display_args(
            &mut display_args,
@@ -358,7 +403,7 @@ impl EditorAgentTool for GenerateImageTool {
        context: &EditorAgentPrepareJobContext<'_>,
    ) -> Result<PreparedEditorAgentJob, EditorAgentToolError> {
        let price_mud_points = self.pricing(context.pricing, args)?;
-        let args: GenerateImageToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateImageToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let title = args.prompt.clone();
        let reference_image_srcs = resolve_image_ids(&args.reference_image_ids, &self.context)?;
        let payload = EditorImageGenerationRequest {
@@ -397,7 +442,7 @@ impl EditorAgentTool for GenerateImageTool {
        args: &Value,
        result: &Value,
    ) -> Result<String, EditorAgentToolError> {
-        let args: GenerateImageToolArgs = parse_internal("generate image args", args)?;
+        let args: GenerateImageToolArgs = parse_internal_image_args("generate image args", args)?;
        let result: EditorImageGenerationResult = parse_internal("generate image result", result)?;
        Ok(GenerateImageTool::format_execute_message(
            self, &args, &result,
@@ -418,7 +463,7 @@ impl EditorAgentTool for GenerateImageTool {

 impl EditorAgentTool for GenerateCharacterTool {
    fn validate_args(&self, args: &Value) -> Result<Value, EditorAgentToolError> {
-        let args: GenerateCharacterToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateCharacterToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        GenerateCharacterTool::validate_args(self, &args)
            .map_err(|error| EditorAgentToolError::invalid_args(error.to_string()))?;
        serialize_normalized_args(Self::NAME, &args)
@@ -429,12 +474,14 @@ impl EditorAgentTool for GenerateCharacterTool {
        pricing: &EditorGenerationPricingConfig,
        args: &Value,
    ) -> Result<u32, EditorAgentToolError> {
-        let args: GenerateCharacterToolArgs = parse_internal("generate character args", args)?;
+        let args: GenerateCharacterToolArgs =
+            parse_internal_image_args("generate character args", args)?;
        Ok(editor_agent_image_mud_points(
            pricing,
            Some("character"),
            args.model.as_str(),
            Some(args.image_size.as_str()),
+            !args.reference_image_ids.is_empty(),
        ))
    }

@@ -445,7 +492,7 @@ impl EditorAgentTool for GenerateCharacterTool {
    ) -> Result<EditorAgentToolCallDisplayArgs, EditorAgentToolError> {
        let price_mud_points = self.pricing(pricing, args)?;
        let args: GenerateCharacterToolArgs =
-            parse_internal("generate character display args", args)?;
+            parse_internal_image_args("generate character display args", args)?;
        let mut display_args = EditorAgentToolCallDisplayArgs::default();
        push_image_generation_display_args(
            &mut display_args,
@@ -466,7 +513,7 @@ impl EditorAgentTool for GenerateCharacterTool {
        context: &EditorAgentPrepareJobContext<'_>,
    ) -> Result<PreparedEditorAgentJob, EditorAgentToolError> {
        let price_mud_points = self.pricing(context.pricing, args)?;
-        let args: GenerateCharacterToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateCharacterToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let title = args.prompt.clone();
        let reference_image_srcs = resolve_image_ids(&args.reference_image_ids, &self.context)?;
        let payload = EditorImageGenerationRequest {
@@ -505,7 +552,8 @@ impl EditorAgentTool for GenerateCharacterTool {
        args: &Value,
        result: &Value,
    ) -> Result<String, EditorAgentToolError> {
-        let args: GenerateCharacterToolArgs = parse_internal("generate character args", args)?;
+        let args: GenerateCharacterToolArgs =
+            parse_internal_image_args("generate character args", args)?;
        let result: EditorImageGenerationResult =
            parse_internal("generate character result", result)?;
        Ok(GenerateCharacterTool::format_execute_message(
@@ -528,7 +576,7 @@ impl EditorAgentTool for GenerateCharacterTool {

 impl EditorAgentTool for GenerateUiDesignTool {
    fn validate_args(&self, args: &Value) -> Result<Value, EditorAgentToolError> {
-        let args: GenerateUiDesignToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateUiDesignToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        GenerateUiDesignTool::validate_args(self, &args)
            .map_err(|error| EditorAgentToolError::invalid_args(error.to_string()))?;
        serialize_normalized_args(Self::NAME, &args)
@@ -539,12 +587,14 @@ impl EditorAgentTool for GenerateUiDesignTool {
        pricing: &EditorGenerationPricingConfig,
        args: &Value,
    ) -> Result<u32, EditorAgentToolError> {
-        let args: GenerateUiDesignToolArgs = parse_internal("generate UI design args", args)?;
+        let args: GenerateUiDesignToolArgs =
+            parse_internal_image_args("generate UI design args", args)?;
        Ok(editor_agent_image_mud_points(
            pricing,
            Some("ui-design"),
            args.model.as_str(),
            Some(args.image_size.as_str()),
+            !args.reference_image_ids.is_empty(),
        ))
    }

@@ -555,7 +605,7 @@ impl EditorAgentTool for GenerateUiDesignTool {
    ) -> Result<EditorAgentToolCallDisplayArgs, EditorAgentToolError> {
        let price_mud_points = self.pricing(pricing, args)?;
        let args: GenerateUiDesignToolArgs =
-            parse_internal("generate UI design display args", args)?;
+            parse_internal_image_args("generate UI design display args", args)?;
        let mut display_args = EditorAgentToolCallDisplayArgs::default();
        push_image_generation_display_args(
            &mut display_args,
@@ -576,7 +626,7 @@ impl EditorAgentTool for GenerateUiDesignTool {
        context: &EditorAgentPrepareJobContext<'_>,
    ) -> Result<PreparedEditorAgentJob, EditorAgentToolError> {
        let price_mud_points = self.pricing(context.pricing, args)?;
-        let args: GenerateUiDesignToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateUiDesignToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let title = args.prompt.clone();
        let reference_image_srcs = resolve_image_ids(&args.reference_image_ids, &self.context)?;
        let payload = EditorImageGenerationRequest {
@@ -615,7 +665,8 @@ impl EditorAgentTool for GenerateUiDesignTool {
        args: &Value,
        result: &Value,
    ) -> Result<String, EditorAgentToolError> {
-        let args: GenerateUiDesignToolArgs = parse_internal("generate UI design args", args)?;
+        let args: GenerateUiDesignToolArgs =
+            parse_internal_image_args("generate UI design args", args)?;
        let result: EditorImageGenerationResult =
            parse_internal("generate UI design result", result)?;
        Ok(GenerateUiDesignTool::format_execute_message(
@@ -638,7 +689,7 @@ impl EditorAgentTool for GenerateUiDesignTool {

 impl EditorAgentTool for EditImageTool {
    fn validate_args(&self, args: &Value) -> Result<Value, EditorAgentToolError> {
-        let args: EditImageToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: EditImageToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        if let Some(error) = EditImageTool::validate_args(self, &args) {
            return Err(EditorAgentToolError::invalid_args(error.to_string()));
        }
@@ -650,13 +701,10 @@ impl EditorAgentTool for EditImageTool {
        pricing: &EditorGenerationPricingConfig,
        args: &Value,
    ) -> Result<u32, EditorAgentToolError> {
-        let _: EditImageToolArgs = parse_internal("edit image args", args)?;
-        Ok(editor_agent_image_mud_points(
-            pricing,
-            Some("quick-edit"),
-            GPT_IMAGE_2_MODEL,
-            Some("1K"),
-        ))
+        let args: EditImageToolArgs = parse_internal_image_args("edit image args", args)?;
+        // 中文注释：修改图片按编辑 concrete model 执行，计价必须走编辑档，
+        // 不能沿用生成档（admin 分开调价时生成档价格即错价）。
+        Ok(pricing.image_edit_model_mud_points(Some(args.model.as_str()), Some("1K")))
    }

    fn build_display_args(
@@ -665,7 +713,7 @@ impl EditorAgentTool for EditImageTool {
        pricing: &EditorGenerationPricingConfig,
    ) -> Result<EditorAgentToolCallDisplayArgs, EditorAgentToolError> {
        let price_mud_points = self.pricing(pricing, args)?;
-        let args: EditImageToolArgs = parse_internal("edit image display args", args)?;
+        let args: EditImageToolArgs = parse_internal_image_args("edit image display args", args)?;
        let mut display_args = EditorAgentToolCallDisplayArgs::default();
        push_string_display_arg(&mut display_args, "prompt", "修改要求", args.prompt);
        push_string_display_arg(&mut display_args, "model", "模型", args.model);
@@ -694,7 +742,7 @@ impl EditorAgentTool for EditImageTool {
        context: &EditorAgentPrepareJobContext<'_>,
    ) -> Result<PreparedEditorAgentJob, EditorAgentToolError> {
        let price_mud_points = self.pricing(context.pricing, args)?;
-        let args: EditImageToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: EditImageToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let source_reference_id = self
            .context
            .image_metadata(&args.object_image_id)
@@ -739,7 +787,7 @@ impl EditorAgentTool for EditImageTool {
        args: &Value,
        result: &Value,
    ) -> Result<String, EditorAgentToolError> {
-        let args: EditImageToolArgs = parse_internal("edit image args", args)?;
+        let args: EditImageToolArgs = parse_internal_image_args("edit image args", args)?;
        let result: EditorImageEditResult = parse_internal("edit image result", result)?;
        Ok(EditImageTool::format_execute_message(self, args, result))
    }
@@ -785,7 +833,7 @@ fn resolve_icon_spec_reference_id<'a>(

 impl EditorAgentTool for GenerateIconSpritesheetTool {
    fn validate_args(&self, args: &Value) -> Result<Value, EditorAgentToolError> {
-        let args: GenerateIconSpritesheetToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateIconSpritesheetToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let args = GenerateIconSpritesheetTool::normalize_args(self, args)
            .map_err(|error| EditorAgentToolError::invalid_args(error.to_string()))?;
        resolve_icon_spec_reference_id(&self.context, &args.reference_image_id)?;
@@ -798,12 +846,13 @@ impl EditorAgentTool for GenerateIconSpritesheetTool {
        args: &Value,
    ) -> Result<u32, EditorAgentToolError> {
        let args: GenerateIconSpritesheetToolArgs =
-            parse_internal("generate icon spritesheet args", args)?;
+            parse_internal_image_args("generate icon spritesheet args", args)?;
        Ok(editor_agent_image_mud_points(
            pricing,
            Some("icon"),
            args.model.as_str(),
            Some(args.image_size.as_str()),
+            !args.reference_image_ids.is_empty(),
        ))
    }

@@ -814,7 +863,7 @@ impl EditorAgentTool for GenerateIconSpritesheetTool {
    ) -> Result<EditorAgentToolCallDisplayArgs, EditorAgentToolError> {
        let price_mud_points = self.pricing(pricing, args)?;
        let args: GenerateIconSpritesheetToolArgs =
-            parse_internal("generate icon spritesheet display args", args)?;
+            parse_internal_image_args("generate icon spritesheet display args", args)?;
        let mut display_args = EditorAgentToolCallDisplayArgs::default();
        push_string_display_arg(
            &mut display_args,
@@ -855,7 +904,7 @@ impl EditorAgentTool for GenerateIconSpritesheetTool {
        context: &EditorAgentPrepareJobContext<'_>,
    ) -> Result<PreparedEditorAgentJob, EditorAgentToolError> {
        let price_mud_points = self.pricing(context.pricing, args)?;
-        let args: GenerateIconSpritesheetToolArgs = parse_invalid_args(Self::NAME, args)?;
+        let args: GenerateIconSpritesheetToolArgs = parse_invalid_image_args(Self::NAME, args)?;
        let reference_id =
            resolve_icon_spec_reference_id(&self.context, &args.reference_image_id)?.to_string();
        let reference_image_srcs = resolve_image_ids(&args.reference_image_ids, &self.context)?;
@@ -903,7 +952,7 @@ impl EditorAgentTool for GenerateIconSpritesheetTool {
        result: &Value,
    ) -> Result<String, EditorAgentToolError> {
        let args: GenerateIconSpritesheetToolArgs =
-            parse_internal("generate icon spritesheet args", args)?;
+            parse_internal_image_args("generate icon spritesheet args", args)?;
        let result: EditorIconSpritesheetResult =
            parse_internal("generate icon spritesheet result", result)?;
        Ok(GenerateIconSpritesheetTool::format_execute_message(
@@ -1250,7 +1299,10 @@ mod tests {
    use spacetime_client::{EditorCanvasRecord, EditorCanvasViewportRecord};

    use super::*;
-    use crate::editor_generation_config::load_editor_generation_pricing_from_paths;
+    use crate::editor_generation_config::{
+        EDITOR_IMAGE_MODEL_GPT_IMAGE_2_5_EDIT, EDITOR_IMAGE_MODEL_GPT_IMAGE_2_5_GENERATION,
+        load_editor_generation_pricing_from_paths,
+    };

    fn pricing() -> EditorGenerationPricingConfig {
        load_editor_generation_pricing_from_paths(None).expect("default editor pricing should load")
@@ -1350,7 +1402,7 @@ mod tests {
                "unknown": "drop-me"
            }))
            .expect("typed UI validation should pass");
-        assert_eq!(normalized["model"], GPT_IMAGE_2_MODEL);
+        assert_eq!(normalized["model"], GPT_IMAGE_2_5_BUSINESS_NAME);
        assert_eq!(normalized["aspect_ratio"], "1:1");
        assert_eq!(normalized["image_size"], "1K");
        assert!(normalized.get("unknown").is_none());
@@ -1495,6 +1547,31 @@ mod tests {
        );
    }

+    #[test]
+    fn dyn_validation_normalizes_legacy_gpt_image_2_alias() {
+        let edit = editor_agent_tool(EditImageTool::NAME, &context_with_image("image-1"))
+            .expect("edit tool should resolve");
+        let normalized = edit
+            .validate_args(&json!({
+                "object_image_id": "image-1",
+                "prompt": "把背景换成夜晚",
+                "model": GPT_IMAGE_2_MODEL
+            }))
+            .expect("legacy edit args should validate");
+        assert_eq!(normalized["model"], GPT_IMAGE_2_5_BUSINESS_NAME);
+
+        let image = editor_agent_tool(GenerateImageTool::NAME, &EditorToolContext::default())
+            .expect("image tool should resolve");
+        let normalized = image
+            .validate_args(&json!({
+                "prompt": "生成图片",
+                "model": GPT_IMAGE_2_MODEL,
+                "image_size": "2K"
+            }))
+            .expect("legacy generation alias should validate");
+        assert_eq!(normalized["model"], GPT_IMAGE_2_5_BUSINESS_NAME);
+    }
+
    #[test]
    fn dyn_pricing_keeps_all_existing_tool_formulas() {
        let pricing = pricing();
@@ -1512,6 +1589,7 @@ mod tests {
            ),
            (
                GenerateUiDesignTool::NAME,
+                // 历史持久化的 `gpt-image-2` 会先归一为 `gpt-image-2.5`，所以计价仍走当前档位。
                json!({ "prompt": "界面", "model": platform_image::GPT_IMAGE_2_MODEL, "image_size": "2K" }),
                5,
            ),
@@ -1552,11 +1630,67 @@ mod tests {
    }

    #[test]
-    fn dyn_pricing_uses_the_supplied_runtime_snapshot() {
+    fn dyn_pricing_routes_edit_tools_and_referenced_generation_to_the_edit_tier() {
        let mut pricing = pricing();
        pricing
            .models
-            .get_mut(GPT_IMAGE_2_MODEL)
+            .get_mut(EDITOR_IMAGE_MODEL_GPT_IMAGE_2_5_EDIT)
+            .expect("edit tier pricing should exist")
+            .prices
+            .insert("1K".to_string(), 41);
+        pricing
+            .models
+            .get_mut(EDITOR_IMAGE_MODEL_GPT_IMAGE_2_5_GENERATION)
+            .expect("generation tier pricing should exist")
+            .prices
+            .insert("1K".to_string(), 7);
+
+        let context = context_with_image("image-1");
+        let edit =
+            editor_agent_tool(EditImageTool::NAME, &context).expect("edit tool should resolve");
+        let edit_args = edit
+            .validate_args(&json!({ "object_image_id": "image-1", "prompt": "修改" }))
+            .expect("edit args should validate");
+        assert_eq!(edit.pricing(&pricing, &edit_args).expect("pricing"), 41);
+
+        let generate = editor_agent_tool(GenerateImageTool::NAME, &context)
+            .expect("image tool should resolve");
+        let without_reference = generate
+            .validate_args(&json!({
+                "prompt": "生成图片",
+                "model": GPT_IMAGE_2_5_BUSINESS_NAME,
+                "image_size": "1K"
+            }))
+            .expect("generation args should validate");
+        assert_eq!(
+            generate
+                .pricing(&pricing, &without_reference)
+                .expect("pricing"),
+            7
+        );
+        let with_reference = generate
+            .validate_args(&json!({
+                "prompt": "生成图片",
+                "model": GPT_IMAGE_2_5_BUSINESS_NAME,
+                "image_size": "1K",
+                "reference_image_ids": ["image-1"]
+            }))
+            .expect("referenced generation args should validate");
+        assert_eq!(
+            generate
+                .pricing(&pricing, &with_reference)
+                .expect("pricing"),
+            41
+        );
+    }
+
+    #[test]
+    fn dyn_pricing_uses_the_supplied_runtime_snapshot() {
+        let mut pricing = pricing();
+        // 历史 `gpt-image-2` 输入会归一为 `gpt-image-2.5-flare-c`，所以要改这个档位的价格。
+        pricing
+            .models
+            .get_mut(EDITOR_IMAGE_MODEL_GPT_IMAGE_2_5_GENERATION)
            .expect("gpt image pricing should exist")
            .prices
            .insert("2K".to_string(), 37);
@@ -1480,8 +1480,8 @@ mod tests {

    fn editor_llm_test_config(base_url: String) -> AppConfig {
        AppConfig {
-            vector_engine_base_url: base_url,
-            vector_engine_api_key: Some("test-vector-engine-key".to_string()),
+            tiantoken_base_url: base_url,
+            tiantoken_api_key: Some("test-tiantoken-key".to_string()),
            llm_max_retries: 0,
            ..AppConfig::default()
        }
--- a/Show More
+++ b/Show More