diff --git a/.claude/settings.local.json b/.claude/settings.local.json
deleted file mode 100644
index 031b36936..000000000
--- a/.claude/settings.local.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test:*)",
-      "Bash(netstat -ano)",
-      "Bash(npm run:*)",
-      "Bash(findstr :8081)",
-      "Bash(taskkill:*)",
-      "Bash(findstr LISTENING)",
-      "Bash(npx tsc:*)",
-      "Bash(lsof -ti:8081)",
-      "Bash(curl -s http://localhost:8081/health)",
-      "Bash(npm -v)",
-      "Bash(cargo --version)",
-      "Bash(rustc --version)",
-      "Skill(code-review)",
-      "Skill(code-review:*)"
-    ]
-  }
-}
diff --git a/.codex/skills/genarrative-external-editor-api/SKILL.md b/.codex/skills/genarrative-external-editor-api/SKILL.md
index abf8f6f3a..ac684ddf7 100644
--- a/.codex/skills/genarrative-external-editor-api/SKILL.md
+++ b/.codex/skills/genarrative-external-editor-api/SKILL.md
@@ -318,6 +318,14 @@ For image edit/redraw that should replace an existing canvas layer, pass `projec
 
 For sound effects and BGM, `assetFolderId` and `assetLabel` can write the generated audio to the account asset library, same as image/video generation.
 
+## Successful Responses with Warnings
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction can return HTTP 2xx with an optional structured `warning`. A 2xx response means the task completed, but it does not guarantee that every requested post-processed derivative exists.
+
+- Apply the returned `project` and media snapshots before interpreting optional derivatives: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. When `warning.code` is `postprocess-failed-source-preserved`, the saved provider source image is the authoritative main result. Character output has no transparent derivative; icon spritesheet and UI extraction output have neither a transparent spritesheet nor slices. Display `warning.reason` directly, and do not synthesize missing derivatives or restart generation.
+- `sliceWarning` is a separate condition used only when transparent spritesheet post-processing succeeded but automatic slicing failed. Keep `sliceWarning.reason` as the original diagnostic and continue using the complete transparent spritesheet; a UI may add context when displaying it, but must not rewrite the stored reason.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. As defensive handling for a malformed response containing both, treat the general `warning` as authoritative and do not misclassify the source-preserved result as a slicing-only warning.
+
 ## Guardrails
 
 - Do not invent endpoints outside the OpenAPI, especially internal worker or runtime task-list routes.
diff --git a/.codex/skills/genarrative-external-editor-api/references/api-selection.md b/.codex/skills/genarrative-external-editor-api/references/api-selection.md
index 747d7ea28..77f7269e9 100644
--- a/.codex/skills/genarrative-external-editor-api/references/api-selection.md
+++ b/.codex/skills/genarrative-external-editor-api/references/api-selection.md
@@ -78,6 +78,14 @@ Ask a follow-up only when two routes could both be correct and produce different
 
 All generation requests should be placed into both the current canvas and its same-name asset-library folder. For endpoints that support `assetLabel`, pass it. For UI extraction, use `spritesheetLabel`. For icon spritesheet, the folder is enough. For character animation, the endpoint does not return `asset`; after success call `POST /api/external/v1/editor/assets` using the first returned frame as `imageSrc`, the session `assetFolderId`, and `assetKind: "character-animation"`.
 
+## HTTP 2xx Warning Handling
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction may return HTTP 2xx while carrying a structured `warning`; completion does not imply that all post-processed derivatives exist.
+
+- Consume the returned `project` and media snapshots as authoritative: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. `warning.code: "postprocess-failed-source-preserved"` means the saved provider source is the main result. Character output has no transparent derivative, while icon spritesheet and UI extraction have no transparent spritesheet and no slices. Display `warning.reason` directly; do not construct missing assets or retry the provider generation from scratch.
+- `sliceWarning` is only for a transparent spritesheet that was created successfully but could not be split automatically. Use the complete transparent spritesheet and preserve `sliceWarning.reason` as the original diagnostic; it is not a post-processing/source-preserved warning.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. If a malformed response contains both, prioritize the general `warning` over `sliceWarning` defensively.
+
 ## Reference Image Upload
 
 If the user provides a local file as a reference image, run upload before the generation request:
diff --git a/.codex/skills/spacetimedb-concepts/SKILL.md b/.codex/skills/spacetimedb-concepts/SKILL.md
index f43b06519..c17575687 100644
--- a/.codex/skills/spacetimedb-concepts/SKILL.md
+++ b/.codex/skills/spacetimedb-concepts/SKILL.md
@@ -78,7 +78,7 @@ Best practices:
 - Avoid overlapping queries that duplicate row delivery.
 - Use indexes for subscribed filters.
 
-## 2.2.0 to 2.6.0 Delta
+## 2.2.0 to 2.6.1 Delta
 
 Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:
 
@@ -88,6 +88,7 @@ Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:
 - **2.4.1**: Rust and TypeScript procedural views can declare primary keys, enabling `OnUpdate` events for subscribed views; fixed index schema from ST tables.
 - **2.5.0**: procedures are stable, C# procedural views gain primary keys, event tables allow broader layout-altering automigrations, BTreeSet storage makes row insertion deterministic and avoids accidentally quadratic bulk insert behavior, `wasm_memory_bytes` billing metric semantics changed, template version constraints unified, `publish --delete-data` config fallback fixed, CLI `call` accepts hex Identity arguments.
 - **2.6.0**: procedural-view primary keys are available across Rust, TypeScript, and C#, commitlog gains `max_segment_size` / `write_buffer_size` / `preallocate_segments`, the default write buffer increases for throughput, event-table automigrations improve, and CLI binary distribution expands.
+- **2.6.1**: procedure contexts again receive the caller `Identity` and `ConnectionId`; generated TypeScript `Option<T>` fields use optional keys; `spacetime init --template` lists available templates when no template argument is supplied.
 
 ## Debugging Checklist
 
diff --git a/.env.local b/.env.local
index 66c7cb8e0..49f8cc1e8 100644
--- a/.env.local
+++ b/.env.local
@@ -29,6 +29,7 @@ GENARRATIVE_LLM_PROVIDER="ark"
 GENARRATIVE_LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
 GENARRATIVE_LLM_API_KEY="eb750614-e0b5-402a-bfea-4224862d251e"
 GENARRATIVE_LLM_MODEL="doubao-1-5-pro-32k-character-250715"
+GENARRATIVE_EDITOR_BGFILTER_BASE_URL="https://u1082648-b442-cd409e05.westx.seetacloud.com:8443"
 APIMART_BASE_URL="https://api.apimart.ai/v1"
 APIMART_API_KEY=""
 APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
@@ -36,6 +37,7 @@ DASHSCOPE_SCENE_IMAGE_MODEL="wan2.2-t2i-flash"
 DASHSCOPE_REFERENCE_IMAGE_MODEL="qwen-image-2.0"
 DASHSCOPE_COVER_IMAGE_MODEL="wan2.2-t2i-flash"
 ARK_CHARACTER_VIDEO_REQUEST_TIMEOUT_MS=420000
+
 # 启用服务端大模型调试日志（记录所有输入输出）
 LLM_DEBUG_LOG="true"
 
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index 8290da85c..c109a2d92 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -24,6 +24,40 @@ module.exports = {
         'no-console': 'off',
       },
     },
+    {
+      files: ['**/scripts/**/*.{ts,js,mjs,cjs}'],
+      rules: {
+        'no-console': 'off',
+      },
+    },
+    {
+      files: ['**/*.test.{ts,tsx,js,mjs,cjs}'],
+      rules: {
+        'no-console': 'off',
+        'unused-imports/no-unused-vars': 'off',
+      },
+    },
+    {
+      files: ['miniprogram/**/*.js'],
+      globals: {
+        App: 'readonly',
+      },
+    },
+    {
+      files: [
+        'apps/admin-web/src/pages/*.tsx',
+        'src/components/platform-entry/PlatformMobileHomeWelcomeDialog.tsx',
+      ],
+      rules: {
+        'react-refresh/only-export-components': 'off',
+      },
+    },
+    {
+      files: ['src/components/platform-entry/PlatformEntryFlowShellImpl.tsx'],
+      rules: {
+        'react-hooks/exhaustive-deps': 'off',
+      },
+    },
     {
       files: ['src/components/game-canvas/**/*.tsx'],
       rules: {
@@ -61,7 +95,25 @@ module.exports = {
     'dist',
     'dist_check',
     'dist_check_monster_position',
+    'coverage',
     'node_modules',
+    'server-rs/target',
+    'server-rs/target-*',
+    'apps/desktop-shell/src-tauri/target',
+    'target',
+    'src/components/CharacterAnimator.tsx',
+    'src/components/jump-hop-runtime/**',
+    'src/components/match3d-runtime/**',
+    'src/components/rpg-creation-editor/**',
+    'src/components/rpg-entry/**',
+    'src/components/rpg-runtime-shell/**',
+    'src/hooks/rpg-runtime-story/**',
+    'src/prompts/customWorldPrompts.ts',
+    'src/services/ai.ts',
+    'src/services/miniGameDraftGenerationProgress.ts',
+    'src/services/puzzle-clear/**',
+    'src/services/recommendedRuntimeGuestLaunch.test.ts',
+    'src/data/sceneEncounterPreviews.ts',
     'public/Icons',
     'media',
     '.codex-logs',
diff --git a/.gitignore b/.gitignore
index 7b4b5c235..b3dd2a2dc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,6 +48,7 @@ temp*build*/
 /.app/
 /target/
 /logs
+/.claude/settings.local.json
 /.codegraph/
 /.playwright-cli/
 **/.playwright-cli/
@@ -57,7 +58,7 @@ temp*build*/
 .worktrees/
 .rag/
 .env.secrets.local
-.claude/settings.local.json
+nohup.out
 spacetime.local.json
 deploy/container/api-server.env
 deploy/container/worker-smoke/
diff --git a/README.md b/README.md
index 214e3893b..71aa2ac89 100644
--- a/README.md
+++ b/README.md
@@ -98,21 +98,20 @@ npm run check:content
 主运行时：
 
 - [src/App.tsx](./src/App.tsx)
-- [src/components/GameShell.tsx](./src/components/GameShell.tsx)
+- [src/AuthenticatedApp.tsx](./src/AuthenticatedApp.tsx)
+- [src/routing/appRoutes.tsx](./src/routing/appRoutes.tsx)
 - [src/hooks/useCombatFlow.ts](./src/hooks/useCombatFlow.ts)
-- [src/hooks/useStoryGeneration.ts](./src/hooks/useStoryGeneration.ts)
 
 主流程内嵌编辑能力：
 
-- [src/components/CustomWorldEntityEditorModal.tsx](./src/components/CustomWorldEntityEditorModal.tsx)
-- [src/components/CustomWorldNpcVisualEditor.tsx](./src/components/CustomWorldNpcVisualEditor.tsx)
-- [src/components/CustomWorldRoleAssetStudioModal.tsx](./src/components/CustomWorldRoleAssetStudioModal.tsx)
+- [src/components/image-editor/ImageCanvasEditorView.tsx](./src/components/image-editor/ImageCanvasEditorView.tsx)
+- [src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx](./src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx)
+- [src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.tsx](./src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.tsx)
 
 核心数据：
 
 - [src/data/scenePresets.ts](./src/data/scenePresets.ts)
 - [src/data/characterPresets.ts](./src/data/characterPresets.ts)
-- [src/data/monsterPresets.ts](./src/data/monsterPresets.ts)
 - [src/data/npcInteractions.ts](./src/data/npcInteractions.ts)
 - [src/data/treasureInteractions.ts](./src/data/treasureInteractions.ts)
 
diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts
index 8b1f4eb25..979cd3c94 100644
--- a/apps/admin-web/src/api/adminApiClient.ts
+++ b/apps/admin-web/src/api/adminApiClient.ts
@@ -2,23 +2,21 @@ import type {
   AdminAccountListResponse,
   AdminCreateAccountRequest,
   AdminCreateAccountResponse,
-  AdminUpsertCreationEntryEventBannersRequest,
-  AdminUpsertCreationEntryTypeConfigRequest,
+  AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
+  AdminCreateEditorShowcaseCampaignImageUploadTicketResponse,
   AdminCreationEntryConfigResponse,
   AdminDashboardQuery,
   AdminDashboardResponse,
-  AdminDebugHttpRequest,
-  AdminDebugHttpResponse,
-  AdminDisableProfileRedeemCodeRequest,
-  AdminDisableProfileTaskConfigRequest,
   AdminDatabaseTableListResponse,
   AdminDatabaseTableRowsQuery,
   AdminDatabaseTableRowsResponse,
-  AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
-  AdminCreateEditorShowcaseCampaignImageUploadTicketResponse,
+  AdminDebugHttpRequest,
+  AdminDebugHttpResponse,
+  AdminDirectUploadTicketPayload,
+  AdminDisableProfileRedeemCodeRequest,
+  AdminDisableProfileTaskConfigRequest,
   AdminEditorAssetListQuery,
   AdminEditorAssetListResponse,
-  AdminDirectUploadTicketPayload,
   AdminEditorShowcaseAssetResponse,
   AdminEditorShowcaseCampaignResponse,
   AdminEditorShowcaseDisplayRequest,
@@ -37,14 +35,16 @@ import type {
   AdminRechargeRefundPreviewRequest,
   AdminRechargeRefundPreviewResponse,
   AdminRechargeRefundRegisterRequest,
-  AdminTrackingEventListQuery,
   AdminTrackingEventKeyListResponse,
+  AdminTrackingEventListQuery,
   AdminTrackingEventListResponse,
-  AdminUpdateWorkVisibilityRequest,
-  AdminUpdateWorkVisibilityResponse,
   AdminUpdateAccountRequest,
   AdminUpdateAccountResponse,
+  AdminUpdateWorkVisibilityRequest,
+  AdminUpdateWorkVisibilityResponse,
   AdminUploadedEditorShowcaseCampaignImage,
+  AdminUpsertCreationEntryEventBannersRequest,
+  AdminUpsertCreationEntryTypeConfigRequest,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertFeatureGateConfigRequest,
   AdminUpsertProfileInviteCodeRequest,
@@ -53,11 +53,11 @@ import type {
   AdminUpsertProfileTaskConfigRequest,
   AdminUpsertProfileWalletConfigRequest,
   AdminUpsertPublicWorkInteractionConfigRequest,
-  AdminWorkVisibilityListResponse,
   AdminUserDetailQuery,
   AdminUserDetailResponse,
   AdminWalletRestrictionRequest,
   AdminWalletRestrictionResponse,
+  AdminWorkVisibilityListResponse,
   ApiErrorEnvelope,
   ApiMeta,
   ApiSuccessEnvelope,
diff --git a/apps/admin-web/src/app/AdminApp.tsx b/apps/admin-web/src/app/AdminApp.tsx
index 2e58ac6f8..49834d3c8 100644
--- a/apps/admin-web/src/app/AdminApp.tsx
+++ b/apps/admin-web/src/app/AdminApp.tsx
@@ -17,26 +17,25 @@ import {
   getStoredAdminToken,
   setStoredAdminToken,
 } from '../auth/adminAuthStore';
-import {AdminCreationEntrySwitchPage} from '../pages/AdminCreationEntrySwitchPage';
 import {AdminAccountsPage} from '../pages/AdminAccountsPage';
+import {AdminCreationEntrySwitchPage} from '../pages/AdminCreationEntrySwitchPage';
 import {AdminDashboardPage} from '../pages/AdminDashboardPage';
-import {AdminDebugHttpPage} from '../pages/AdminDebugHttpPage';
 import {AdminDatabaseTablesPage} from '../pages/AdminDatabaseTablesPage';
-import {AdminInviteCodePage} from '../pages/AdminInviteCodePage';
-import {AdminLoginPage} from '../pages/AdminLoginPage';
-import {AdminEditorGenerationPricingPage} from '../pages/AdminEditorGenerationPricingPage';
+import {AdminDebugHttpPage} from '../pages/AdminDebugHttpPage';
 import {AdminEditorAssetQueryPage} from '../pages/AdminEditorAssetQueryPage';
+import {AdminEditorGenerationPricingPage} from '../pages/AdminEditorGenerationPricingPage';
 import {AdminEditorShowcaseReviewPage} from '../pages/AdminEditorShowcaseReviewPage';
 import {AdminGrayReleaseConfigPage} from '../pages/AdminGrayReleaseConfigPage';
+import {AdminInviteCodePage} from '../pages/AdminInviteCodePage';
+import {AdminLoginPage} from '../pages/AdminLoginPage';
 import {AdminOverviewPage} from '../pages/AdminOverviewPage';
 import {AdminProfileWalletConfigPage} from '../pages/AdminProfileWalletConfigPage';
-import {AdminRechargeProductPage} from '../pages/AdminRechargeProductPage';
 import {AdminRechargeOrderPage} from '../pages/AdminRechargeOrderPage';
+import {AdminRechargeProductPage} from '../pages/AdminRechargeProductPage';
 import {AdminRedeemCodePage} from '../pages/AdminRedeemCodePage';
 import {AdminTaskConfigPage} from '../pages/AdminTaskConfigPage';
 import {AdminTrackingEventsPage} from '../pages/AdminTrackingEventsPage';
 import {AdminWorkVisibilityPage} from '../pages/AdminWorkVisibilityPage';
-import {AdminShell} from './AdminShell';
 import type {AdminRouteId} from './adminRoutes';
 import {
   getAccessibleAdminRoutes,
@@ -44,6 +43,7 @@ import {
   resolveAdminRoute,
   routeHash,
 } from './adminRoutes';
+import {AdminShell} from './AdminShell';
 
 type SessionStatus = 'checking' | 'guest' | 'authenticated';
 
diff --git a/apps/admin-web/src/app/AdminShell.tsx b/apps/admin-web/src/app/AdminShell.tsx
index 12c050fab..e141357f2 100644
--- a/apps/admin-web/src/app/AdminShell.tsx
+++ b/apps/admin-web/src/app/AdminShell.tsx
@@ -1,25 +1,25 @@
 import {
   Activity,
-  Bug,
   BadgeDollarSign,
+  Bug,
   Coins,
-  LayoutDashboard,
-  LogOut,
-  Megaphone,
+  Database,
   Eye,
   GitBranch,
   Images,
-  Star,
-  WalletCards,
-  ShieldCheck,
+  LayoutDashboard,
   ListChecks,
+  LogOut,
+  Megaphone,
+  ReceiptText,
+  ShieldCheck,
   SlidersHorizontal,
-  Database,
+  Star,
   Table2,
   TicketCheck,
   TicketPercent,
-  ReceiptText,
   Users,
+  WalletCards,
 } from 'lucide-react';
 import type {ReactNode} from 'react';
 
diff --git a/apps/admin-web/src/config/trackingEventDefinitions.test.ts b/apps/admin-web/src/config/trackingEventDefinitions.test.ts
index 77523d548..ff3314447 100644
--- a/apps/admin-web/src/config/trackingEventDefinitions.test.ts
+++ b/apps/admin-web/src/config/trackingEventDefinitions.test.ts
@@ -5,8 +5,8 @@ import {
   adminTrackingEventDefinitions,
   buildAdminTrackingEventKeyOptions,
   filterAdminProfileTaskTrackingEventDefinitions,
-  filterAdminTrackingEventKeyOptions,
   filterAdminTrackingEventDefinitions,
+  filterAdminTrackingEventKeyOptions,
   findAdminTrackingEventDefinition,
 } from './trackingEventDefinitions';
 
diff --git a/apps/admin-web/src/pages/AdminDashboardPage.test.tsx b/apps/admin-web/src/pages/AdminDashboardPage.test.tsx
index e8aa77b61..a278a19dc 100644
--- a/apps/admin-web/src/pages/AdminDashboardPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminDashboardPage.test.tsx
@@ -1,6 +1,7 @@
 /* @vitest-environment jsdom */
 
 import {
+  act,
   fireEvent,
   render,
   screen,
@@ -308,6 +309,9 @@ test('Dashboard 四张趋势图共享横向日期窗口', async () => {
   if (!sourceChart || !targetChart) {
     throw new Error('趋势图未完整渲染');
   }
+  await act(async () => {
+    await Promise.resolve();
+  });
   setScrollableDimensions(sourceChart, {
     clientWidth: 100,
     scrollWidth: 500,
@@ -319,11 +323,11 @@ test('Dashboard 四张趋势图共享横向日期窗口', async () => {
     scrollLeft: 0,
   });
 
-  fireEvent.scroll(sourceChart);
-
-  await waitFor(() => {
-    expect(targetChart.scrollLeft).toBe(200);
+  await act(async () => {
+    fireEvent.scroll(sourceChart);
   });
+
+  expect(targetChart.scrollLeft).toBe(200);
 });
 
 test('Dashboard 访问人数趋势明确区分每日桶与时段去重总数', async () => {
diff --git a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
index ee2337e62..bd3a7e12d 100644
--- a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
@@ -2,12 +2,12 @@ import { ChevronDown, ChevronRight, Eye, FileText, RefreshCcw, X } from 'lucide-
 import { Fragment, type ReactNode } from 'react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import {
   getAdminAssetReadUrl,
   isAdminApiError,
   listAdminEditorAssets,
 } from '../api/adminApiClient';
-import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import type {
   AdminEditorAssetListQuery,
   AdminEditorAssetPayload,
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
index 8d02aa4d0..dbcc6375c 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
@@ -2,6 +2,7 @@ import { Eye, FileText, RefreshCcw, Upload, X } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
+import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import {
   getAdminAssetReadUrl,
   getAdminEditorShowcaseCampaign,
@@ -11,7 +12,6 @@ import {
   uploadAdminEditorShowcaseCampaignImage,
   upsertAdminEditorShowcaseCampaign,
 } from '../api/adminApiClient';
-import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import type {
   AdminEditorShowcaseAssetPayload,
   AdminEditorShowcaseCampaignPayload,
diff --git a/apps/admin-web/src/pages/AdminTrackingEventsPage.tsx b/apps/admin-web/src/pages/AdminTrackingEventsPage.tsx
index 010ce3708..b7fc04685 100644
--- a/apps/admin-web/src/pages/AdminTrackingEventsPage.tsx
+++ b/apps/admin-web/src/pages/AdminTrackingEventsPage.tsx
@@ -10,13 +10,13 @@ import type {
   AdminTrackingEventKeyPayload,
   TrackingScopeKind,
 } from '../api/adminApiTypes';
+import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
 import {
   buildAdminTrackingEventKeyOptions,
-  filterAdminTrackingEventKeyOptions,
   filterAdminTrackingEventDefinitions,
+  filterAdminTrackingEventKeyOptions,
   findAdminTrackingEventDefinition,
 } from '../config/trackingEventDefinitions';
-import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
 import { handlePageError } from './pageUtils';
 
 interface AdminTrackingEventsPageProps {
diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs
index 9cf16dea4..26ca9cc53 100644
--- a/apps/desktop-shell/scripts/check-config.mjs
+++ b/apps/desktop-shell/scripts/check-config.mjs
@@ -1,5 +1,5 @@
-import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 
 const configPath = new URL('../src-tauri/tauri.conf.json', import.meta.url);
 const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -1117,7 +1117,7 @@ function extractDesktopCapabilities(source) {
 }
 
 function extractDesktopHandledMethods(source) {
-  const matchBodies = [...source.matchAll(/match request\.method\.as_str\(\) \{([\s\S]*?)\n    \}/g)].map(
+  const matchBodies = [...source.matchAll(/match request\.method\.as_str\(\) \{([\s\S]*?)\n {4}\}/g)].map(
     (match) => match[1],
   );
   if (matchBodies.length === 0) {
@@ -1152,7 +1152,7 @@ function extractDesktopHostBridgeMethodBody(source, method) {
 
   const nextMethodMatch = source
     .slice(methodStart + method.length)
-    .match(/\n        (?:"[^"]+"|_)\s*=>/);
+    .match(/\n {8}(?:"[^"]+"|_)\s*=>/);
   const nextMethodStart = nextMethodMatch
     ? methodStart + method.length + nextMethodMatch.index
     : -1;
@@ -1410,10 +1410,6 @@ function extractTauriInvokeCommands(source) {
     .filter(Boolean);
 }
 
-function collectRustSourceBasenames(files) {
-  return files.map((file) => file.pathname.split('/').pop()).sort();
-}
-
 function collectRustSourceRelativePaths(files) {
   const rootPath = rustSourceDir.pathname.endsWith('/')
     ? rustSourceDir.pathname
diff --git a/apps/mobile-shell/scripts/check-build-artifacts.mjs b/apps/mobile-shell/scripts/check-build-artifacts.mjs
index fab3c8501..4e7ba1a23 100644
--- a/apps/mobile-shell/scripts/check-build-artifacts.mjs
+++ b/apps/mobile-shell/scripts/check-build-artifacts.mjs
@@ -1,6 +1,6 @@
+import {spawnSync} from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import {spawnSync} from 'node:child_process';
 
 const shellRoot = new URL('../', import.meta.url);
 const repoRoot = path.resolve(shellRoot.pathname, '../..');
diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs
index 19ce5f33e..38ba50b7d 100644
--- a/apps/mobile-shell/scripts/check-config.mjs
+++ b/apps/mobile-shell/scripts/check-config.mjs
@@ -1,5 +1,5 @@
-import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 
 import { PNG } from 'pngjs';
 
@@ -82,11 +82,6 @@ const filesPath = new URL('../src/host-bridge/files.ts', import.meta.url);
 const filesSource = fs.readFileSync(filesPath, 'utf8');
 const filesTestPath = new URL('../src/host-bridge/files.test.ts', import.meta.url);
 const filesTestSource = fs.readFileSync(filesTestPath, 'utf8');
-const filePayloadsPath = new URL(
-  '../src/host-bridge/filePayloads.ts',
-  import.meta.url,
-);
-const filePayloadsSource = fs.readFileSync(filePayloadsPath, 'utf8');
 const hapticsPath = new URL('../src/host-bridge/haptics.ts', import.meta.url);
 const hapticsSource = fs.readFileSync(hapticsPath, 'utf8');
 const hapticsTestPath = new URL(
@@ -495,7 +490,7 @@ function extractNumberConstExport(source, exportName) {
 
 function extractMobileBridgeHandledMethods(source) {
   const match = source.match(
-    /async function dispatchMobileHostBridgeRequest[\s\S]*?switch \(request\.method\) \{([\s\S]*?)\n  \}/,
+    /async function dispatchMobileHostBridgeRequest[\s\S]*?switch \(request\.method\) \{([\s\S]*?)\n {2}\}/,
   );
   if (!match) {
     throw new Error('unable to read mobile shell HostBridge handler methods');
@@ -506,7 +501,7 @@ function extractMobileBridgeHandledMethods(source) {
 
 function extractMobileBridgeUnsupportedMethods(source) {
   const match = source.match(
-    /async function dispatchMobileHostBridgeRequest[\s\S]*?switch \(request\.method\) \{([\s\S]*?)\n  \}/,
+    /async function dispatchMobileHostBridgeRequest[\s\S]*?switch \(request\.method\) \{([\s\S]*?)\n {2}\}/,
   );
   if (!match) {
     throw new Error('unable to read mobile shell HostBridge unsupported methods');
@@ -514,7 +509,7 @@ function extractMobileBridgeUnsupportedMethods(source) {
 
   const unsupportedMethods = new Set();
   const casePattern =
-    /case '([^']+)':([\s\S]*?)(?=\n    case '|\n    default:|\n  \})/g;
+    /case '([^']+)':([\s\S]*?)(?=\n {4}case '|\n {4}default:|\n {2}\})/g;
   for (const entry of match[1].matchAll(casePattern)) {
     if (entry[2].includes('unsupported(request.method)')) {
       unsupportedMethods.add(entry[1]);
@@ -990,10 +985,6 @@ const sharedEvents = extractStringArrayExport(
   sharedContractSource,
   'HOST_BRIDGE_EVENTS',
 );
-const sharedBlockedDownloadProtocols = extractStringArrayExport(
-  sharedContractSource,
-  'HOST_BRIDGE_MOBILE_WEBVIEW_BLOCKED_DOWNLOAD_PROTOCOLS',
-);
 const sharedMobileBaseCapabilities = extractStringArrayExport(
   sharedContractSource,
   'HOST_BRIDGE_EXPO_MOBILE_BASE_CAPABILITIES',
diff --git a/apps/mobile-shell/scripts/check-eas-build-config.mjs b/apps/mobile-shell/scripts/check-eas-build-config.mjs
index 596eeee94..f51e10792 100644
--- a/apps/mobile-shell/scripts/check-eas-build-config.mjs
+++ b/apps/mobile-shell/scripts/check-eas-build-config.mjs
@@ -1,5 +1,5 @@
-import fs from 'node:fs';
 import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
 
 const shellRoot = new URL('../', import.meta.url);
 const easConfigPath = new URL('eas.json', shellRoot);
diff --git a/apps/mobile-shell/scripts/check-expo-config.mjs b/apps/mobile-shell/scripts/check-expo-config.mjs
index 702d899e0..ec5514918 100644
--- a/apps/mobile-shell/scripts/check-expo-config.mjs
+++ b/apps/mobile-shell/scripts/check-expo-config.mjs
@@ -1,5 +1,4 @@
 import {spawnSync} from 'node:child_process';
-
 import fs from 'node:fs';
 
 const appConfigPath = new URL('../app.json', import.meta.url);
diff --git a/apps/mobile-shell/scripts/check-expo-export.mjs b/apps/mobile-shell/scripts/check-expo-export.mjs
index a4907e8b6..9643e66bc 100644
--- a/apps/mobile-shell/scripts/check-expo-export.mjs
+++ b/apps/mobile-shell/scripts/check-expo-export.mjs
@@ -1,5 +1,4 @@
 import {spawnSync} from 'node:child_process';
-
 import fs from 'node:fs';
 
 const shellRoot = new URL('../', import.meta.url);
diff --git a/apps/mobile-shell/src/host-bridge/bridge.test.ts b/apps/mobile-shell/src/host-bridge/bridge.test.ts
index 53726666f..d9a2736e1 100644
--- a/apps/mobile-shell/src/host-bridge/bridge.test.ts
+++ b/apps/mobile-shell/src/host-bridge/bridge.test.ts
@@ -625,24 +625,32 @@ describe('handleMobileHostBridgeMessage', () => {
   });
 
   test('app.openExternalUrl 原生异常返回稳定 host_error', async () => {
-    vi.mocked(Linking.canOpenURL).mockRejectedValueOnce({
-      code: 'native_linking_failure',
-      message: 'native linking failed',
-      nativeStackIOS: ['private native frame'],
-    });
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      vi.mocked(Linking.canOpenURL).mockRejectedValueOnce({
+        code: 'native_linking_failure',
+        message: 'native linking failed',
+        nativeStackIOS: ['private native frame'],
+      });
 
-    const response = await send(
-      request('app.openExternalUrl', {
-        url: 'https://example.com/path',
-      }),
-    );
+      const response = await send(
+        request('app.openExternalUrl', {
+          url: 'https://example.com/path',
+        }),
+      );
 
-    const failedResponse = expectFailed(response);
+      const failedResponse = expectFailed(response);
 
-    expect(failedResponse.error).toEqual({
-      code: 'host_error',
-      message: 'external URL cannot be opened',
-    });
+      expect(failedResponse.error).toEqual({
+        code: 'host_error',
+        message: 'external URL cannot be opened',
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        'mobile HostBridge navigation failed for external.open',
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
   });
 
   test('app.openExternalUrl 拒绝危险协议', async () => {
diff --git a/apps/mobile-shell/src/host-bridge/dispatch.ts b/apps/mobile-shell/src/host-bridge/dispatch.ts
index 9245caad2..df059be7e 100644
--- a/apps/mobile-shell/src/host-bridge/dispatch.ts
+++ b/apps/mobile-shell/src/host-bridge/dispatch.ts
@@ -1,4 +1,10 @@
 import { type HostBridgeRequest } from '../../../../packages/shared/src/contracts/hostBridge';
+import { getMobileHostBridgeAppearanceColorScheme } from './appearance';
+import { setMobileAppBadgeCount } from './badge';
+import {
+  readMobileHostBridgeClipboardText,
+  writeMobileHostBridgeClipboardText,
+} from './clipboard';
 import {
   captureMobileHostBridgeImageFile,
   exportMobileHostBridgeAudioFile,
@@ -9,32 +15,26 @@ import {
   importMobileHostBridgeImageFile,
   importMobileHostBridgeTextFile,
 } from './files';
-import {
-  failure,
-  type MobileHostBridgeNavigation,
-  unsupported,
-} from './protocol';
-import { resetQrScannerForTest, scanMobileHostBridgeQrCode } from './scanner';
-import {
-  openShare,
-  resetMobileHostBridgeShareTargetForTest,
-  setMobileHostBridgeShareTarget,
-} from './share';
-import { showMobileHostBridgeLocalNotification } from './notifications';
-import {
-  readMobileHostBridgeClipboardText,
-  writeMobileHostBridgeClipboardText,
-} from './clipboard';
 import { runMobileHostBridgeHapticsImpact } from './haptics';
-import { setMobileAppBadgeCount } from './badge';
-import { getMobileHostBridgeAppearanceColorScheme } from './appearance';
 import {
   openMobileHostBridgeExternalUrl,
   openMobileHostBridgeNativePage,
   reloadMobileHostBridgeWebView,
 } from './navigation';
 import { getMobileHostBridgeNetworkStatus } from './network';
+import { showMobileHostBridgeLocalNotification } from './notifications';
+import {
+  failure,
+  type MobileHostBridgeNavigation,
+  unsupported,
+} from './protocol';
 import { getMobileHostBridgeRuntimeResponse } from './runtime';
+import { resetQrScannerForTest, scanMobileHostBridgeQrCode } from './scanner';
+import {
+  openShare,
+  resetMobileHostBridgeShareTargetForTest,
+  setMobileHostBridgeShareTarget,
+} from './share';
 
 let navigation: MobileHostBridgeNavigation | null = null;
 
diff --git a/apps/mobile-shell/src/host-bridge/filePayloads.ts b/apps/mobile-shell/src/host-bridge/filePayloads.ts
index 8e076ec1b..6a76ce9d4 100644
--- a/apps/mobile-shell/src/host-bridge/filePayloads.ts
+++ b/apps/mobile-shell/src/host-bridge/filePayloads.ts
@@ -2,15 +2,15 @@ import type * as ImagePicker from 'expo-image-picker';
 
 import {
   type FileImportImageResult,
-  type HostBridgeAudioMimeType,
-  type HostBridgeDocumentMimeType,
-  type HostBridgeImageMimeType,
-  type HostBridgeTextMimeType,
   HOST_BRIDGE_AUDIO_MIME_TYPES,
   HOST_BRIDGE_DOCUMENT_MIME_TYPES,
   HOST_BRIDGE_IMAGE_MIME_TYPES,
   HOST_BRIDGE_IMPORT_IMAGE_MAX_BYTES,
   HOST_BRIDGE_TEXT_MIME_TYPES,
+  type HostBridgeAudioMimeType,
+  type HostBridgeDocumentMimeType,
+  type HostBridgeImageMimeType,
+  type HostBridgeTextMimeType,
   normalizeHostBridgeExportFileName,
   normalizeHostBridgeImportFileName,
 } from '../../../../packages/shared/src/contracts/hostBridge';
diff --git a/apps/mobile-shell/src/host-bridge/files.ts b/apps/mobile-shell/src/host-bridge/files.ts
index f1e85ab95..b97a2bfd0 100644
--- a/apps/mobile-shell/src/host-bridge/files.ts
+++ b/apps/mobile-shell/src/host-bridge/files.ts
@@ -14,11 +14,6 @@ import {
   type FileImportDocumentResult,
   type FileImportImageResult,
   type FileImportTextResult,
-  type HostBridgeAudioMimeType,
-  type HostBridgeError,
-  type HostBridgeImageMimeType,
-  type HostBridgeRequest,
-  type HostBridgeTextMimeType,
   HOST_BRIDGE_EXPORT_AUDIO_MAX_BYTES,
   HOST_BRIDGE_EXPORT_IMAGE_MAX_BYTES,
   HOST_BRIDGE_EXPORT_TEXT_MAX_BYTES,
@@ -26,6 +21,11 @@ import {
   HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES,
   HOST_BRIDGE_IMPORT_IMAGE_MAX_BYTES,
   HOST_BRIDGE_IMPORT_TEXT_MAX_BYTES,
+  type HostBridgeAudioMimeType,
+  type HostBridgeError,
+  type HostBridgeImageMimeType,
+  type HostBridgeRequest,
+  type HostBridgeTextMimeType,
   normalizeHostBridgeExportFileName,
   normalizeHostBridgeImportFileName,
 } from '../../../../packages/shared/src/contracts/hostBridge';
@@ -43,7 +43,6 @@ import {
   normalizedBase64Data,
   normalizeExportedAudioFileName,
   normalizeExportedImageFileName,
-  normalizeImportedAudioFileName,
   normalizeImportedAudioMimeType,
   normalizeImportedDocumentMimeType,
   normalizeImportedTextMimeType,
diff --git a/apps/mobile-shell/src/host-bridge/haptics.ts b/apps/mobile-shell/src/host-bridge/haptics.ts
index eb10ead4a..da54a12a9 100644
--- a/apps/mobile-shell/src/host-bridge/haptics.ts
+++ b/apps/mobile-shell/src/host-bridge/haptics.ts
@@ -3,9 +3,9 @@ import * as Haptics from 'expo-haptics';
 import {
   type HapticsImpactPayload,
   type HostBridgeError,
+  type HostBridgeHapticsImpactStyle,
   type HostBridgeRequest,
   normalizeHostBridgeHapticsImpactStyle,
-  type HostBridgeHapticsImpactStyle,
 } from '../../../../packages/shared/src/contracts/hostBridge';
 import { invalidRequest, ok } from './protocol';
 
diff --git a/apps/mobile-shell/src/host-bridge/navigation.test.ts b/apps/mobile-shell/src/host-bridge/navigation.test.ts
index a102c876b..cbf2adf45 100644
--- a/apps/mobile-shell/src/host-bridge/navigation.test.ts
+++ b/apps/mobile-shell/src/host-bridge/navigation.test.ts
@@ -6,12 +6,12 @@ import {
   HOST_BRIDGE_VERSION,
   type HostBridgeRequest,
 } from '../../../../packages/shared/src/contracts/hostBridge';
-import type { MobileHostBridgeNavigation } from './protocol';
 import {
   openMobileHostBridgeExternalUrl,
   openMobileHostBridgeNativePage,
   reloadMobileHostBridgeWebView,
 } from './navigation';
+import type { MobileHostBridgeNavigation } from './protocol';
 
 vi.mock('expo-linking', () => ({
   canOpenURL: vi.fn(),
diff --git a/apps/mobile-shell/src/host-bridge/navigation.ts b/apps/mobile-shell/src/host-bridge/navigation.ts
index 12ece029c..dc6867ffa 100644
--- a/apps/mobile-shell/src/host-bridge/navigation.ts
+++ b/apps/mobile-shell/src/host-bridge/navigation.ts
@@ -8,14 +8,13 @@ import {
   type OpenExternalUrlPayload,
 } from '../../../../packages/shared/src/contracts/hostBridge';
 import {
-  type MobileShellExternalNavigator,
   openMobileShellExternalNavigation,
   resolveMobileShellWebViewUrl,
 } from '../shell/navigation';
 import { buildMobileShellUrl } from '../shell/url';
 import {
-  type MobileHostBridgeNavigation,
   invalidRequest,
+  type MobileHostBridgeNavigation,
   ok,
   unsupported,
 } from './protocol';
diff --git a/apps/mobile-shell/src/host-bridge/network.ts b/apps/mobile-shell/src/host-bridge/network.ts
index c87f6f8f1..22dc3f0d5 100644
--- a/apps/mobile-shell/src/host-bridge/network.ts
+++ b/apps/mobile-shell/src/host-bridge/network.ts
@@ -1,5 +1,5 @@
-import { getMobileNetworkStatus } from '../shell/network';
 import { type HostBridgeRequest } from '../../../../packages/shared/src/contracts/hostBridge';
+import { getMobileNetworkStatus } from '../shell/network';
 import { failure, ok } from './protocol';
 
 function logMobileNetworkFailure(label: string, _error: unknown) {
diff --git a/apps/mobile-shell/src/host-bridge/scanner.test.ts b/apps/mobile-shell/src/host-bridge/scanner.test.ts
index ed5573aed..7514d4aca 100644
--- a/apps/mobile-shell/src/host-bridge/scanner.test.ts
+++ b/apps/mobile-shell/src/host-bridge/scanner.test.ts
@@ -1,8 +1,8 @@
 import { afterEach, describe, expect, test, vi } from 'vitest';
 
 import {
-  HOST_BRIDGE_SCANNER_TIMEOUT_MS,
   HOST_BRIDGE_PROTOCOL,
+  HOST_BRIDGE_SCANNER_TIMEOUT_MS,
   HOST_BRIDGE_VERSION,
   type HostBridgeRequest,
 } from '../../../../packages/shared/src/contracts/hostBridge';
diff --git a/apps/mobile-shell/src/host-bridge/scanner.ts b/apps/mobile-shell/src/host-bridge/scanner.ts
index b80cbdfa6..38e92bf57 100644
--- a/apps/mobile-shell/src/host-bridge/scanner.ts
+++ b/apps/mobile-shell/src/host-bridge/scanner.ts
@@ -2,8 +2,8 @@ import {
   HOST_BRIDGE_SCANNER_TIMEOUT_MS,
   type HostBridgeError,
   type HostBridgeRequest,
-  type ScannerScanQrCodeResult,
   normalizeHostBridgeQrCodeValue,
+  type ScannerScanQrCodeResult,
 } from '../../../../packages/shared/src/contracts/hostBridge';
 import { ok } from './protocol';
 
diff --git a/apps/mobile-shell/src/shell/QrScannerOverlay.tsx b/apps/mobile-shell/src/shell/QrScannerOverlay.tsx
index 0953ec255..c0e827222 100644
--- a/apps/mobile-shell/src/shell/QrScannerOverlay.tsx
+++ b/apps/mobile-shell/src/shell/QrScannerOverlay.tsx
@@ -1,7 +1,7 @@
 import {
+  type BarcodeScanningResult,
   Camera,
   CameraView,
-  type BarcodeScanningResult,
 } from 'expo-camera';
 import { useCallback, useEffect, useState } from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
diff --git a/apps/mobile-shell/src/shell/ShellApp.tsx b/apps/mobile-shell/src/shell/ShellApp.tsx
index 438c1a49c..390120cd8 100644
--- a/apps/mobile-shell/src/shell/ShellApp.tsx
+++ b/apps/mobile-shell/src/shell/ShellApp.tsx
@@ -28,9 +28,9 @@ import {
 } from 'react-native-webview';
 
 import {
-  type HostBridgeEventName,
   HOST_BRIDGE_PROTOCOL,
   HOST_BRIDGE_VERSION,
+  type HostBridgeEventName,
 } from '../../../../packages/shared/src/contracts/hostBridge';
 import {
   configureMobileHostBridgeNavigation,
@@ -52,18 +52,18 @@ import {
   getMobileNetworkStatus,
   subscribeMobileNetworkStatus,
 } from './network';
+import { QrScannerOverlay } from './QrScannerOverlay';
 import { MOBILE_SHELL_HOST_VERSION } from './runtime';
 import { MOBILE_SHELL_SAFE_AREA_EDGES } from './safeArea';
 import {
   buildMobileShellUrl,
   resolveMobileShellBaseWebUrl,
 } from './url';
+import { parseMobileWebViewHistoryStateMessage } from './webViewHistory';
 import {
   MOBILE_WEBVIEW_BEFORE_CONTENT_SCRIPT,
   shouldBlockMobileWebViewNavigationRequest,
 } from './webViewPolicy';
-import { parseMobileWebViewHistoryStateMessage } from './webViewHistory';
-import { QrScannerOverlay } from './QrScannerOverlay';
 
 const MobileShellWebView = WebView as unknown as ComponentType<
   WebViewProps & RefAttributes<WebView<unknown>>
@@ -304,6 +304,7 @@ export default function ShellApp() {
     };
   }, [
     baseWebUrl,
+    baseWebUrlOptions,
     resetNavigationCanGoBack,
     resetWebViewProcessFailureWindow,
     urlOptions,
diff --git a/apps/mobile-shell/src/shell/deepLink.ts b/apps/mobile-shell/src/shell/deepLink.ts
index a0e64b91d..ac2b6c9cb 100644
--- a/apps/mobile-shell/src/shell/deepLink.ts
+++ b/apps/mobile-shell/src/shell/deepLink.ts
@@ -1,8 +1,8 @@
 import {
   buildMobileShellUrl,
   type MobileShellBaseWebUrlOptions,
-  resolveMobileShellBaseWebUrl,
   type MobileShellUrlOptions,
+  resolveMobileShellBaseWebUrl,
 } from './url';
 
 const supportedHosts = new Set(['open', 'app']);
diff --git a/apps/mobile-shell/src/shell/url.test.ts b/apps/mobile-shell/src/shell/url.test.ts
index 8b5eb8077..62bc38dd1 100644
--- a/apps/mobile-shell/src/shell/url.test.ts
+++ b/apps/mobile-shell/src/shell/url.test.ts
@@ -7,8 +7,8 @@ import {
 } from '../../../../packages/shared/src/contracts/hostBridge';
 import {
   ALLOWED_PRODUCTION_WEB_ORIGIN,
-  DEFAULT_MOBILE_SHELL_WEB_URL,
   buildMobileShellUrl,
+  DEFAULT_MOBILE_SHELL_WEB_URL,
   resolveMobileShellBaseWebUrl,
 } from './url';
 
diff --git a/deploy/container/README.md b/deploy/container/README.md
index c6959b695..588749378 100644
--- a/deploy/container/README.md
+++ b/deploy/container/README.md
@@ -57,7 +57,7 @@ Linux Docker Engine 若要从宿主机 CLI 连到容器内服务，直接用 `ht
 
 ## 构建工具链
 
-`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.6.0` 依赖链要求 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。镜像构建阶段会同时复制 `public/`，用于满足 API 二进制里 `include_bytes!` 引用的内置素材；不要把 `public/generated-*` 放入镜像上下文。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。
+`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.6.1` 依赖链要求 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。镜像构建阶段会同时复制 `public/`，用于满足 API 二进制里 `include_bytes!` 引用的内置素材；不要把 `public/generated-*` 放入镜像上下文。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。
 
 ## 启动与验证
 
@@ -127,7 +127,7 @@ npm run container:worker-smoke -- status
 npm run container:worker-smoke -- smoke --force
 ```
 
-`container:worker-smoke` 默认会把本机 `spacetime` 2.6.0 CLI 打成轻量 SpacetimeDB 镜像，避免首次 smoke 必须拉取官方大镜像；普通 `npm run container:*` 压测默认使用 `clockworklabs/spacetime:v2.6.0`。如果 Docker build 阶段在容器内拉取 crates.io 依赖不稳定，可让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入临时 smoke 镜像。该模式默认使用 `rust:1.93-bookworm` 作为 builder、Debian bookworm smoke runtime 承载构建产物；需要换 builder 镜像时设置 `GENARRATIVE_WORKER_SMOKE_CARGO_IMAGE`，需要换运行时基础镜像时设置 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE`：
+`container:worker-smoke` 默认会把本机 `spacetime` 2.6.1 CLI 打成轻量 SpacetimeDB 镜像，避免首次 smoke 必须拉取官方大镜像；普通 `npm run container:*` 压测默认使用 `clockworklabs/spacetime:v2.6.1`。如果 Docker build 阶段在容器内拉取 crates.io 依赖不稳定，可让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入临时 smoke 镜像。该模式默认使用 `rust:1.93-bookworm` 作为 builder、Debian bookworm smoke runtime 承载构建产物；需要换 builder 镜像时设置 `GENARRATIVE_WORKER_SMOKE_CARGO_IMAGE`，需要换运行时基础镜像时设置 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE`：
 
 ```bash
 npm run container:worker-smoke -- smoke --local-binary
diff --git a/deploy/container/docker-compose.loadtest.yml b/deploy/container/docker-compose.loadtest.yml
index 10597b127..29431d854 100644
--- a/deploy/container/docker-compose.loadtest.yml
+++ b/deploy/container/docker-compose.loadtest.yml
@@ -2,7 +2,7 @@ name: genarrative-container-loadtest
 
 services:
   spacetimedb:
-    image: ${GENARRATIVE_CONTAINER_SPACETIME_IMAGE:-clockworklabs/spacetime:v2.6.0}
+    image: ${GENARRATIVE_CONTAINER_SPACETIME_IMAGE:-clockworklabs/spacetime:v2.6.1}
     user: root
     command:
       [
diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example
index 617553225..b4a392fa7 100644
--- a/deploy/env/api-server.env.example
+++ b/deploy/env/api-server.env.example
@@ -157,8 +157,18 @@ GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
 GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
 GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
 GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+# 可选：files 为逐文件 CAS + catalog，不生成 tar.gz；archive 保留旧全量压缩包兼容行为。
+GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT=archive
+# files 模式并行 PUT/HEAD 数量，必须为 1-64；默认 16。
+GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY=16
+# 可选：仅限制备份进程上传总带宽，单位 bytes/s；为空或 0 表示不限速。
+GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND=
 # 可选：显式要求备份工作目录所在文件系统至少保留的可用空间；为空时按数据目录大小 + 安全余量估算。
 GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES=
+# archive history 模式持久化已验真 full baseline 与追加批次；files 模式改用 work-dir 下的 files state。
+GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE=/var/lib/genarrative/database-backups/genarrative-prod-history-state.json
+# 仅 archive history 首次从 uploadStatus=uploaded 的 full manifest 初始化 state 时设置；初始化后可留空。
+GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST=
 # 可选：定时 / publish 前备份使用独立最小权限 AccessKey；为空时回退 ALIYUN_OSS_ACCESS_KEY_*。
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
diff --git a/deploy/systemd/genarrative-database-backup-files-history.conf b/deploy/systemd/genarrative-database-backup-files-history.conf
new file mode 100644
index 000000000..512898b80
--- /dev/null
+++ b/deploy/systemd/genarrative-database-backup-files-history.conf
@@ -0,0 +1,3 @@
+[Service]
+ExecStart=
+ExecStart=/usr/bin/node -- /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --storage-format files --mode history --work-dir /var/lib/genarrative/database-backups/files-history
diff --git a/docs/README.md b/docs/README.md
index c177be6ec..d8911947e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,156 +1,57 @@
 # 文档总览
 
-`docs/` 现在按主题维护项目当前口径；旧后端路线文档开始聚合和删除，后续实现以 Rust / SpacetimeDB 当前基线为准。
+`docs/` 只把当前融合文档和仍在维护的专题文档作为实现依据。旧创作模板、旧创作入口及其专属服务文档仅保留为历史材料，不再要求继续实现或兼容。
 
-## 快速入口
+## 必读入口
 
-- [Agent 工作入口与执行准则](./%E3%80%90%E5%8D%8F%E4%BD%9C%E8%A7%84%E8%8C%83%E3%80%91Agent%E5%B7%A5%E4%BD%9C%E5%85%A5%E5%8F%A3%E4%B8%8E%E6%89%A7%E8%A1%8C%E5%87%86%E5%88%99-2026-06-22.md)：复杂任务前的 Agent 阅读顺序、执行边界、技能路由、文档规则和验证口径。
-- [官网 SEO 地基实施约定](./technical/【SEO】官网SEO地基实施约定-2026-07-10.md)：首页基础 head、robots/sitemap、唯一 H1、精确 SPA 路由与未知路径 404 的长期技术边界。
-- [经验沉淀](./experience/README.md)：项目开发经验、UI 交接、历史实现经验。
-- [审计与复盘](./audits/README.md)：工程审查、文本/乱码审计、专项落地审计。
-- [系统设计](./design/README.md)：玩法、关系、物品与对话设计。
-- [技术方案](./technical/README.md)：动画、服务端、外部产品形态拆解。
-- [架构决策](./adr/)：记录已经接受的跨模块、长期有效架构取舍；对应长期摘要仍应同步到 `docs/project-memory/shared-memory/decision-log.md`。
-- [规划与优先级](./planning/README.md)：当前阶段的迭代排序与落地优先级；创作流程统一总计划见 [【玩法创作】创作流程统一总计划-2026-05-30.md](./planning/%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E5%88%9B%E4%BD%9C%E6%B5%81%E7%A8%8B%E7%BB%9F%E4%B8%80%E6%80%BB%E8%AE%A1%E5%88%92-2026-05-30.md)。
-- [参考目录](./reference/README.md)：脚本/Function 速查入口。
-  重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
-- [埋点查询](./tracking/README.md)：埋点原始事件与聚合投影的本地 SQL 查询。
-- [运营查询](./operations/README.md)：任务、领奖、钱包对账等后台核查查询。
-- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)，跳一跳俯视角玩法模板 PRD 见 [【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md](./prd/%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E8%B7%B3%E4%B8%80%E8%B7%B3%E4%BF%AF%E8%A7%86%E8%A7%92%E7%8E%A9%E6%B3%95%E6%A8%A1%E6%9D%BFPRD-2026-05-19.md)。
+1. [Agent 工作入口与执行准则](./【协作规范】Agent工作入口与执行准则-2026-06-22.md)
+2. [当前产品与工程约束](./【项目基线】当前产品与工程约束-2026-05-15.md)
+3. [server-rs 与 SpacetimeDB 数据契约](./【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
+4. [平台入口与玩法链路](./【玩法创作】平台入口与玩法链路-2026-05-15.md)
+5. [本地开发验证与生产运维](./【开发运维】本地开发验证与生产运维-2026-05-15.md)
 
-拼图生成页步骤真进度、步骤内假进度和精简展示口径见 [【玩法创作】拼图生成页进度口径-2026-05-23.md](./%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E6%8B%BC%E5%9B%BE%E7%94%9F%E6%88%90%E9%A1%B5%E8%BF%9B%E5%BA%A6%E5%8F%A3%E5%BE%84-2026-05-23.md)。
+团队长期约定、决策、流程和排障摘要统一从 [项目记忆入口](./project-memory/README.md) 读取。代码、当前融合文档与项目记忆冲突时，以代码和最新融合文档为准。
 
-从文字需求生成高一致性美术素材流程抽象出的发明专利交底稿见 [【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md](./%E3%80%90%E4%B8%93%E5%88%A9%E4%BA%A4%E5%BA%95%E3%80%91%E4%B8%80%E7%A7%8D%E6%9E%81%E4%BD%8E%E6%88%90%E6%9C%AC%E5%BF%AB%E9%80%9F%E7%94%9F%E6%88%90%E9%AB%98%E8%B4%A8%E9%87%8F2D%E5%B0%8F%E6%B8%B8%E6%88%8F%E9%AB%98%E4%B8%80%E8%87%B4%E6%80%A7%E7%BE%8E%E6%9C%AF%E7%B4%A0%E6%9D%90%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88-2026-05-25.md)。
+## 当前专题
 
-微信小程序虚拟支付接入、`wechat_mp_virtual` 渠道、`wx.requestVirtualPayment` 承接页和后端签名配置见 [【技术方案】微信虚拟支付接入-2026-05-26.md](./%E3%80%90%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88%E3%80%91%E5%BE%AE%E4%BF%A1%E8%99%9A%E6%8B%9F%E6%94%AF%E4%BB%98%E6%8E%A5%E5%85%A5-2026-05-26.md)。
+### 图片编辑器与 Agent
 
-微信小程序、Expo React Native 移动壳与 Tauri 桌面壳共用的宿主能力契约、method / capability 白名单、H5 facade 和三端边界见 [【前端架构】宿主壳能力统一协议-2026-06-17.md](./%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91%E5%AE%BF%E4%B8%BB%E5%A3%B3%E8%83%BD%E5%8A%9B%E7%BB%9F%E4%B8%80%E5%8D%8F%E8%AE%AE-2026-06-17.md)。
+- [图片画布编辑器 MVP 接入方案](./technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md)
+- [图片画布编辑器前端拆分计划](./technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md)
+- [画布 Agent 对话面板](./【编辑器】画布Agent对话面板-2026-07-03.md)
+- [画布 Agent 会话消息存 OSS](./adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md)
+- [图片画布撤销范围与操作提示方案](./【图片画布】撤销范围与操作提示方案-2026-07-17.md)
+- [浏览器内 AI Web 工程沙箱预览](./technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md)
+- [AI Web 工程 Runner 安全模型](./technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md)
 
-Expo React Native 移动壳和 Tauri 桌面壳的工程结构、同源 WebView 安全边界、原生能力实现、构建配置和门禁要求见 [【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md](./%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ExpoReactNative%E4%B8%8ETauri%E5%AE%BF%E4%B8%BB%E5%A3%B3%E6%96%B9%E6%A1%88-2026-06-17.md)。
+### 后端与公开数据
 
-原生壳本地开发与验证命令统一从根工程进入：移动壳使用 `npm run mobile-shell:dev`、`npm run mobile-shell:typecheck`、`npm run mobile-shell:test`，桌面壳使用 `npm run desktop-shell:dev`、`npm run desktop-shell:typecheck`、`npm run desktop-shell:test`，跨端结构和能力门禁使用 `npm run check:native-shells`。
+- [外部生成 Worker 化方案](./technical/【后端架构】外部生成Worker化方案-2026-06-03.md)
+- [统一公开作品 Read Model 设计](./technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md)
+- [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
+- [SpacetimeDB 连接池取消安全](./【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md)
 
-`/editor/agent` 浏览器内 AI Web 工程编辑器的静态 SPA 沙箱预览 MVP，采用“平台编辑器壳 + api-server 控制面 + 独立 runner worker + 独立预览域”四层结构；技术方案、威胁模型和验收清单见 [【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md](./technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md)、[【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md](./technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md) 和 [【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md](./technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md)。P1 先用确定性 mock Agent 生成结构化 patch、真实打通项目 / 快照 / 构建 / artifact / 预览闭环，落地拆分见 [【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md](./technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md)。
+### 后台、宿主壳与运维
 
-`/editor/canvas` 图片画布编辑器的画布素材 ZIP 导出能力，入口放在右上角标题栏下载图标内，采用前端 JSZip 打包画布中有效图层引用的上传图、生成图、修改结果和角色动作序列帧；动作图层右键“导出为”提供序列帧 ZIP（含前端生成的 `preview.gif`）与 Spine JSON ZIP 两个二级选项，方案见 [【前端架构】图片画布素材导出方案-2026-06-15.md](./technical/【前端架构】图片画布素材导出方案-2026-06-15.md)。
+- [Dashboard 运营看板方案](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)
+- [后台多账号与 Tab 访问权限](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)
+- [宿主壳能力统一协议](./【前端架构】宿主壳能力统一协议-2026-06-17.md)
+- [Expo React Native 与 Tauri 宿主壳方案](./【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md)
+- [Pingora 独立网关试点](./technical/【开发运维】Pingora独立网关试点-2026-06-11.md)
+- [本地 SSH 服务器管理面板](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)
 
-`/editor/canvas` 右侧画布 Agent 对话面板、会话持久化、SSE 事件、附件与生成落画板例外见 [【编辑器】画布Agent对话面板-2026-07-03.md](./【编辑器】画布Agent对话面板-2026-07-03.md)；消息正文存 OSS、元数据进 SpacetimeDB 的取舍见 [【ADR】画布Agent会话消息存OSS-2026-07-03.md](./adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md)。
+### 测试与协作
 
-图片画布生成类面板的模型泥点默认 JSON、SpacetimeDB 运行时事实源、后台“模型定价”页面和主站动态下发口径见 [【编辑器】模型定价配置管理方案-2026-06-22.md](./%E3%80%90%E7%BC%96%E8%BE%91%E5%99%A8%E3%80%91%E6%A8%A1%E5%9E%8B%E5%AE%9A%E4%BB%B7%E9%85%8D%E7%BD%AE%E7%AE%A1%E7%90%86%E6%96%B9%E6%A1%88-2026-06-22.md)。
+- [React 组件测试准则](./technical/【前端测试】React组件测试准则-2026-06-26.md)
+- [AI Web 工程静态预览验收清单](./technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md)
+- [当前阶段规划](./planning/README.md)
 
-React 组件测试的用户行为、稳定契约、hook / model 分层断言口径，以及避免内部 DOM 探针、图标 class 和完整对象快照式断言的规则见 [【前端测试】React组件测试准则-2026-06-26.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%B5%8B%E8%AF%95%E3%80%91React%E7%BB%84%E4%BB%B6%E6%B5%8B%E8%AF%95%E5%87%86%E5%88%99-2026-06-26.md)。
+## 历史文档边界
 
-桌面端全站客服悬浮入口的全局接入点、固定层级、拖拽边界和移动端隐藏口径见 [【前端架构】全站客服悬浮入口接入约定-2026-06-23.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91%E5%85%A8%E7%AB%99%E5%AE%A2%E6%9C%8D%E6%82%AC%E6%B5%AE%E5%85%A5%E5%8F%A3%E6%8E%A5%E5%85%A5%E7%BA%A6%E5%AE%9A-2026-06-23.md)。
+- 旧创作模板、旧创作入口、旧运行态和旧素材生成方案不再从本页索引，也不再作为修复目标。
+- `maincloud`、旧 Node/Express/PostgreSQL/Go 后端和人工 `spacetime --root-dir` 口径均已废弃。
+- 历史文档不得覆盖当前融合文档、代码契约或 `docs/project-memory/shared-memory/decision-log.md` 中更新的决策。
 
-桌面端 `/creation` 创作工具主页、顶级“草稿”入口替换为“项目”、最近项目、新建项目和陶泥儿精选素材瀑布流的落地计划见 [【玩法创作】创作主页与项目入口改版计划-2026-06-18.md](./%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E5%88%9B%E4%BD%9C%E4%B8%BB%E9%A1%B5%E4%B8%8E%E9%A1%B9%E7%9B%AE%E5%85%A5%E5%8F%A3%E6%94%B9%E7%89%88%E8%AE%A1%E5%88%92-2026-06-18.md)。
+## 命名规则
 
-本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
-
-生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。Pingora 只作为独立二进制影子网关试点时，边界、路由口径与替换前验收见 [【开发运维】Pingora独立网关试点-2026-06-11.md](./technical/【开发运维】Pingora独立网关试点-2026-06-11.md)。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)，Dashboard 默认入口、运营指标和统计口径见 [【后台管理】Dashboard运营看板方案-2026-06-23.md](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)，owner/member 多账号、18 个一级 Tab 权限和逐请求鉴权方案见 [【后台管理】多账号与Tab访问权限方案-2026-07-14.md](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)。
-
-SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。
-
-创作 Agent 问答流式失败时保留已显示回复、并透出更具体上游错误的契约见 [CREATION_AGENT_STREAM_FAILURE_RETENTION_FIX_2026-05-05.md](./technical/CREATION_AGENT_STREAM_FAILURE_RETENTION_FIX_2026-05-05.md)。
-
-`maincloud` 相关脚本、环境变量、测试名和文档要求已统一判定为历史残留，后续禁止新增、运行或引用；当前后端 smoke 使用 `npm run dev:api-server` 与 `/healthz`，详细规则见 [MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md](./technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md)。
-
-基于 LangChain-Rust，以“感知—思考—记忆—行动—反思—协作”闭环完成图文创意理解、拼图模板选择、积分范围确认、拼图草稿字段填充、立即试玩和自然语言修订草稿字段的 Agent 方案见 [CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md](./technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md)。
-
-创意互动内容 Agent Phase 1 的产品边界、实现细节、SpacetimeDB 落点、前端接入和可并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)。
-
-视觉小说模板接入以 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为最新口径：只吸收外部 TXT 玩法的模板创作与运行经验，禁止迁入外部平台功能，并删除回放。
-
-AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md) 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。
-
-前端 Server-Sent Events 客户端传输层收口到 `src/services/sseStream.ts`，事件边界、UTF-8 flush、JSON 解析跳过和提前取消约定见 [【前端架构】SSE客户端传输层收口约定-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91SSE%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%A0%E8%BE%93%E5%B1%82%E6%94%B6%E5%8F%A3%E7%BA%A6%E5%AE%9A-2026-06-03.md)。
-
-平台入口公开作品身份、跨玩法去重、公开作品流聚合、推荐运行态 kind 判定、推荐 runtime 启动意图、ready 判定和最新排序收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91%E5%B9%B3%E5%8F%B0%E5%85%A5%E5%8F%A3PublicGalleryFlowModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-统一作品详情页的玩法 kind、详情打开策略、自有作品动作模式、编辑 / 点赞 / 改造 / 启动意图和公开详情映射收口到 `src/components/platform-entry/platformPublicWorkDetailFlow.ts`；抓大鹅公开详情映射与启动 / 编辑 Adapter 的素材归一仍归 `platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md](./technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md)。
-
-创作中心作品架打开动作由 `CreationWorkShelfItem.actions.open` 统一承载，生产 Hub 只接收 `CreationWorkShelfItem[]` 与 UI 状态，不再接收各玩法 raw items 和回调列阵，规则见 [【前端架构】WorkShelfModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91WorkShelfModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-作品架删除确认的标题、删除说明、草稿 notice key 和拼图派生稳定 ID 收口到 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts`，平台壳只保留删除 API、刷新、错误和页面跳转副作用，规则见 [【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md](./technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md)。
-
-创作入口点击的占位、隐藏模板拦截、未知入口 no-op 与工作台启动目标收口到 `src/components/platform-entry/platformCreationLaunchModel.ts`，壳层只执行启动前准备、错误提示和受保护动作，规则见 [【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md)。
-
-平台入口公开码搜索的用户 ID、陶泥号、RPG 作品号、各玩法作品号前缀、per-play 公开码匹配、详情卡 DTO 映射和失败回退顺序收口到 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，壳层只按计划执行网络读取、详情打开和错误归航副作用，规则见 [【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md)。
-
-个人“玩过作品”面板的玩法别名、`worldKey` 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback 收口到 `src/components/platform-entry/platformPlayedWorkOpenModel.ts`，壳层只执行面板关闭、gallery 读取、详情打开和错误提示副作用，规则见 [【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md)。
-
-平台入口生成页进度 tick 的 stage 到生成状态映射、终态判定和视觉小说轻量生成特例收口到 `src/components/platform-entry/platformGenerationProgressTickModel.ts`，壳层只保留 `Date.now()`、`setInterval` 和 cleanup 副作用，规则见 [【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md)。
-
-平台壳的拼图 runtime 恢复 work、方洞 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 detail 恢复 session、敲木鱼生成中作品摘要和敲木鱼 pending session DTO 映射收口到 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts`，壳层只保留网络、状态、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md)。
-
-平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和 ready / generating 判定收口到 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts`，壳层只保留 API、后台任务、React state、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md)。
-
-平台小游戏草稿恢复和提交所需的拼图 / 抓大鹅表单 payload、拼图作品更新 payload、拼图编译 action、跳一跳 / 敲木鱼生成 action、pending metadata 与拼图 form-only 草稿判定收口到 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts`，壳层只保留 API、Action 执行、background task 与状态副作用，规则见 [【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md)。
-
-平台拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定收口到 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`，恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才抬为 ready，规则见 [【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md)。
-
-拼图排行榜提交回包后的服务端 run 快照合并收口到 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts`，只合并排行榜、run 身份、通关数上限和下一关 handoff，保留前端即时裁决的关卡状态与棋盘，规则见 [【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md)。
-
-后端拼图发布 / 待发布门槛收紧到首图、关卡画面、UI spritesheet 与关卡背景资产包完整，`module-puzzle` 的 preview blockers 与 `api-server` 的 session stage 判定保持同一规则，方案见 [【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md](./technical/【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md)。
-
-平台入口个人钱包本地 delta、dashboard 乐观更新与服务端快照对账规则收口到 `src/components/platform-entry/platformProfileWalletDeltaModel.ts`，平台壳只保留 API、ref 与 state 副作用，规则见 [【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md)。
-
-Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置、发布快照 / 发布回包资产兜底和草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 映射收口到 `src/components/platform-entry/barkBattleWorkCache.ts`，规则见 [【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md](./technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md)。
-
-平台首页推荐 runtime 的匿名 Runtime Guest Token、已登录 background auth、非 embedded no-op 和拼图 isolated/default auth mode 计划收口到 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md)。
-
-平台首页推荐 runtime 自动启动的桌面 / Tab / stage / loading gate、active entry 查找、ready 判定和 clear/start/noop 决策收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md)。
-
-RPG Agent 结果页发布门禁展示和预览来源 label 收口到 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts`，壳层只保留 session/profile 编排和结果页 props 传递，规则见 [【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md)。
-
-平台入口创作生成通知、pending 作品架占位、作品详情更新回填、失败覆盖、跨玩法草稿打开优先级、拼图稳定 ID 和草稿 Tab 未读点收口到 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，规则见 [【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91DraftGenerationShelfModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-平台入口创作恢复 URL 私有 query、初始恢复判定、创作直达恢复目标解析、恢复目标身份匹配、跳一跳 / 敲木鱼恢复阶段落点、拼图 runtime query 与拼图稳定身份互推收口到 `src/components/platform-entry/platformCreationUrlStateModel.ts` 和 `src/components/platform-entry/platformPuzzleIdentityModel.ts`，规则见 [【前端架构】CreationUrlStateModel收口计划-2026-06-03.md](./technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md)。
-
-平台入口错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key 与任务完成文案收口到 `src/components/platform-entry/platformDialogStateModel.ts`，规则见 [【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md](./technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md)。
-
-平台 UI Kit 的提示 / 确认弹窗收口到 `src/components/common/UnifiedConfirmDialog.tsx`，复制反馈收口到 `src/components/common/useCopyFeedback.ts`、`src/components/common/CopyFeedbackButton.tsx`、`src/components/common/CopyCodeButton.tsx` 与 `src/components/common/CopyFeedbackMessage.tsx`，基础状态提示收口到 `src/components/common/PlatformStatusMessage.tsx`，运行态短错误 / 成功 / 反馈 toast 收口到 `src/components/common/PlatformRuntimeStatusToast.tsx`，平台空态 / 轻量加载态收口到 `src/components/common/PlatformEmptyState.tsx`，平台动作按钮收口到 `src/components/common/PlatformActionButton.tsx`，平台白底子面板 / 小型列表卡片收口到 `src/components/common/PlatformSubpanel.tsx`，平台输入框 / 文本域收口到 `src/components/common/PlatformTextField.tsx`，平台字段标题收口到 `src/components/common/PlatformFieldLabel.tsx`，平台媒体预览框收口到 `src/components/common/PlatformMediaFrame.tsx`，平台胶囊状态标签收口到 `src/components/common/PlatformPillBadge.tsx`，平台图片全屏预览收口到 `src/components/common/PlatformImagePreviewModal.tsx`，平台 / 个人中心弹窗关闭按钮收口到 `src/components/common/PlatformModalCloseButton.tsx`，底层继续复用 `UnifiedModal`；普通提示、确认 / 取消、危险确认、复制状态机、短代码复制 chip、复制按钮表现、白底 / 个人中心 / 认证入口 token 状态条、运行态状态 toast、无操作空态、主动作按钮、白底子面板、白底交互列表卡片、普通输入字段、字段标题、图片源 / fallback / 固定比例媒体预览、全屏黑底图片查看、单个状态 / 标签 chip 和圆形关闭按钮优先使用公共 Module，规则见 [【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md](./technical/【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md)。
-
-平台入口受保护数据失效后的 stage 去留判定，以及缺失草稿 / 作品 / run 时的阶段回退，收口到 `src/components/platform-entry/platformSelectionStageModel.ts`，壳层只执行缓存清空、布尔事实汇总和必要跳转，规则见 [【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md)。
-
-小游戏 runtime client 的路径编码、JSON 请求、runtime guest auth 与 retry 选项收口到 `src/services/runtimeRequest.ts`，Match3D、SquareHole、Big Fish、Bark Battle、Puzzle 公开 / 推荐运行态请求、Jump Hop / Wooden Fish 正式 run 请求和 Visual Novel 局部 JSON runtime 请求已先迁移，规则见 [【前端架构】RuntimeClientFamily收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RuntimeClientFamily%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-抓大鹅 runtime profile 的公开详情转 work、session draft 转 profile、生成背景资产提升和 run/profile/public detail 素材优先级收口到 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91Match3DRuntimeProfile%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-公开作品分类选项、搜索、跨来源去重、今日筛选、排行排序和时间戳解析收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicGalleryViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-公开作品的玩法类型 label、公开作者 lookup 与游玩 / 改造 / 点赞等紧凑计数格式收口到 `src/components/rpg-entry/rpgEntryWorldPresentation.ts`，规则见 [【前端架构】PublicWorkPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicWorkPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-推荐 feed 的公开作品去重、普通内容过滤、active 窗口与上一条 / 下一条回环选择也收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RecommendFeedViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案收口到 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts`，规则见 [【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md](./technical/【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md)。
-
-排行频道的默认 tab、tab 文案、空态文案、排序字段与指标 label/value 收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RankingViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RankingViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-每日任务卡片与任务中心弹窗的任务选择、进度、状态标签和按钮文案收口到 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，规则见 [【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileTaskViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-个人数据卡、钱包 chip 与“玩过”弹窗的计数、时长、作品类型和作品号展示收口到 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts`，规则见 [【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileDashboardPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-个人资金展示的账单来源、金额正负号、余额兜底、充值价格、商品主值和会员摘要收口到 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts`，规则见 [【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileFundsViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
-
-## 推荐阅读顺序
-
-1. 先看 [经验沉淀](./experience/README.md)，快速建立这个项目的开发共识。
-2. 再看 [工程审查总览](./audits/engineering/README.md) 和 [文本审计总览](./audits/text/README.md)，了解当前风险。
-3. 需要排期时看 [规划与优先级](./planning/README.md)，创作链路相关任务优先看创作流程统一总计划。
-4. 需要补方案时进入 [系统设计](./design/README.md) / [技术方案](./technical/README.md)；涉及后端先看 [当前后端实现基线](./technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md)，涉及生产发布链路先看 [生产部署计划](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，涉及 SpacetimeDB 表结构变更时再看 [表结构变更约束](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。
-5. 需要对齐目标边界时再进入 [PRD](./prd)。
-
-## 分类规则
-
-- `experience/`：偏方法论、交接经验、长期有效的开发结论。
-- `audits/`：偏“现状扫描 / 问题定位 / 是否达标”的审查类文档。
-- `design/`：偏玩法机制、叙事关系、系统结构设计。
-- `technical/`：偏技术选型、实现路线、竞品/产品形态拆解。
-- `planning/`：偏阶段优先级与推进顺序。
-- `reference/`：偏目录、速查、检索辅助。
-- `tracking/`：偏埋点原始事实和聚合投影查询，不放任务进度或钱包对账。
-- `operations/`：偏后台运营核查、对账和排障查询。
-
-## 文档命名规则
-
-后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。标签用于跨目录检索，不替代上面的目录分类；历史文档不要求批量重命名，除非本次任务明确涉及该文档。
+后续新增 Markdown 文档文件名使用 `【标签名】中文标题-日期.md`。历史文件不做无关批量重命名；本次涉及的旧文档可直接删除或在当前入口中取消引用。
diff --git a/docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md b/docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md
index 194a23ea0..c1c881dbe 100644
--- a/docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md
+++ b/docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md
@@ -4,7 +4,7 @@
 
 ## 背景
 
-画布Agent对话需要保存历史记录并支持新开会话。消息正文是流式追加、体量随对话增长的 JSON 数据；SpacetimeDB 是后端唯一结构化真相存储，但表行不适合承载不断增长的长文本；画布工程快照已有独立保存链路，且对话流式更新频率远高于布局保存。
+画布Agent对话需要保存历史记录并支持新开会话。消息正文会随对话和工具结果持续增长；SpacetimeDB 是后端唯一结构化真相存储，但表行不适合承载不断增长的长文本；画布工程快照已有独立保存链路，对话消息也不应与布局保存互相竞争。
 
 ## 决策
 
@@ -14,7 +14,7 @@
 - 浏览器禁止直接上传、覆盖或签名写入 `editor-agent/` 对象；前端只通过 `api-server` 的会话接口创建会话、发送消息、读取历史，OSS 读写由服务端完成。
 - 消息文档序列化后的读写上限为 2 MiB；超过上限时后端拒绝继续读写该会话消息文档，并返回 payload too large 语义错误。
 - 同一会话内的消息追加采用 `conversationId` 级串行锁，避免同一会话的“读-改-写”整对象过程互相覆盖。
-- Agent 工具调用失败时，仍保留 assistant 消息和 `failed` generation record，包括 tool call、模型、错误信息等排障字段；失败记录是会话历史的一部分，不因 SSE 已返回错误而丢弃。
+- Agent 规划失败使用 `role=system`、正文以 `ERROR ` 开头的消息持久化；首次响应和同 `clientMessageId` 重放都通过 `deltaMessages` 返回该消息，`errorMessage` 不重复携带。前端隐藏前缀并显示红色错误气泡，后端构建后续 LLM memory 时仍保留该消息，让 Agent 获取上一轮失败上下文。工具调用失败继续保留 `status=failed` 工具记录、模型和错误信息；失败记录都是会话历史的一部分。
 - 不把消息明细写入 SpacetimeDB 表，不把对话混入画布工程快照，不在 api-server 内存中保存会话真相。
 
 ## 备选方案与取舍
@@ -31,5 +31,5 @@
 - 会话表仍只保存元数据和 `messagesObjectKey`；API 可以在读取时把 OSS 消息文档拼装为会话详情返回，但完整消息正文的持久化真相仍是 OSS JSON 文档。
 - 消息文档最大 2 MiB；该限制用于阻止单个会话无限增长。后续如果需要更长历史，应引入归档、分页对象或摘要压缩，不应把正文回填进 SpacetimeDB 表。
 - 会话软删只打表标记，OSS 对象保留，便于恢复与审计。
-- 工具生成失败也会写入消息文档：assistant 消息可标记为失败 / 错误类型，`generations` 中保留 `failed` record、模型和错误信息，便于用户回看失败原因和后续排障。
+- 规划或工具生成失败也必须写入消息文档：规划失败保存 `ERROR ` system 消息，工具失败保存失败状态、模型和错误信息，便于用户回看失败原因和后续排障。
 - 若未来出现跨会话消息检索需求，需另建投影或索引，不回退为消息入表。
diff --git a/docs/openapi/genarrative-external-v1.openapi.json b/docs/openapi/genarrative-external-v1.openapi.json
index acc09d755..5c3559d43 100644
--- a/docs/openapi/genarrative-external-v1.openapi.json
+++ b/docs/openapi/genarrative-external-v1.openapi.json
@@ -969,7 +969,7 @@
           "Editor Images"
         ],
         "operationId": "generateExternalEditorIconSpritesheet",
-        "summary": "按规范图生成并拆分图标素材",
+        "summary": "按规范图生成图标 spritesheet 并尝试拆分",
         "security": [
           {
             "ExternalApiKey": []
@@ -987,7 +987,7 @@
         },
         "responses": {
           "200": {
-            "description": "图标 spritesheet、切片结果与落库资源",
+            "description": "图标 spritesheet、实际切片结果、可选非阻断告警与落库资源",
             "content": {
               "application/json": {
                 "schema": {
@@ -1017,7 +1017,7 @@
           "Editor Images"
         ],
         "operationId": "extractExternalEditorUiDesignAssets",
-        "summary": "从 UI 设计图拆分素材",
+        "summary": "从 UI 设计图生成素材 spritesheet 并尝试拆分",
         "security": [
           {
             "ExternalApiKey": []
@@ -1035,7 +1035,7 @@
         },
         "responses": {
           "200": {
-            "description": "UI 设计图素材 spritesheet、切片结果与落库资源",
+            "description": "UI 设计图素材 spritesheet、实际切片结果、可选非阻断告警与落库资源",
             "content": {
               "application/json": {
                 "schema": {
@@ -2569,7 +2569,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "图片 Data URL。quick-edit 最多 9 张，其它模式最多使用前 5 张。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多使用前 5 张，数组上限为 9。"
             },
             "maxItems": 9
           },
@@ -2691,7 +2691,7 @@
           },
           "sourceImageSrc": {
             "type": "string",
-            "description": "待重绘/调整的图片 Data URL。"
+            "description": "待重绘/调整图片的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
           },
           "projectId": {
             "type": [
@@ -2737,13 +2737,33 @@
             "type": "string"
           },
           "model": {
-            "type": "string"
+            "type": "string",
+            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。"
+          },
+          "aspectRatio": {
+            "type": "string",
+            "enum": [
+              "1:1",
+              "4:3",
+              "3:2",
+              "2:3",
+              "9:16",
+              "16:9"
+            ]
+          },
+          "imageSize": {
+            "type": "string",
+            "enum": [
+              "0.5K",
+              "1K",
+              "2K"
+            ]
           },
           "referenceImageSrcs": {
             "type": "array",
             "items": {
               "type": "string",
-              "description": "图片 Data URL、asset://、OSS object key 或公网 URL。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
             },
             "maxItems": 8
           },
@@ -2849,6 +2869,17 @@
               }
             ],
             "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "生成成功但后处理降级时返回的非阻断告警。"
           }
         }
       },
@@ -2861,13 +2892,13 @@
         "properties": {
           "referenceImageSrc": {
             "type": "string",
-            "description": "规范图/参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+            "description": "图标规范的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
           },
           "referenceImageSrcs": {
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外图标素材参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。最多 8 张。"
             },
             "maxItems": 8
           },
@@ -2957,7 +2988,7 @@
         "properties": {
           "sourceImageSrc": {
             "type": "string",
-            "description": "UI 设计图 Data URL 或 objectKey。"
+            "description": "带红框标注的 UI 设计图稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；浏览器内合成后必须先上传 OSS 再提交。禁止 Data URL / Blob URL。"
           },
           "screenColor": {
             "type": [
@@ -2975,7 +3006,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外 UI 素材参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。最多 5 张。"
             },
             "maxItems": 5
           },
@@ -3090,6 +3121,25 @@
         },
         "additionalProperties": false
       },
+      "EditorGenerationWarning": {
+        "type": "object",
+        "required": [
+          "code",
+          "reason"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "const": "postprocess-failed-source-preserved",
+            "description": "透明背景处理最终失败并保留 provider 原图时的稳定原因码。"
+          },
+          "reason": {
+            "type": "string",
+            "description": "可直接展示给调用方的非阻断告警原因。"
+          }
+        },
+        "additionalProperties": false
+      },
       "EditorIconSpritesheetGenerationResponse": {
         "type": "object",
         "required": [
@@ -3130,7 +3180,7 @@
                 "type": "null"
               }
             ],
-            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。"
+            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。与通用 warning 互斥。"
           },
           "prompt": {
             "type": "string"
@@ -3184,7 +3234,24 @@
               }
             ],
             "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "透明背景处理最终失败、provider 原图作为主结果时返回的非阻断告警。与 sliceWarning 互斥。"
           }
+        },
+        "not": {
+          "required": [
+            "warning",
+            "sliceWarning"
+          ]
         }
       },
       "EditorCharacterAnimationGenerationRequest": {
@@ -3206,7 +3273,8 @@
             "type": "string"
           },
           "sourceImageSrc": {
-            "type": "string"
+            "type": "string",
+            "description": "角色源图的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
           },
           "sourceWidth": {
             "type": "integer",
@@ -3490,7 +3558,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "公网 URL、asset://、OSS object key 或图片 Data URL。仅 Seedance 2.0 系列支持。"
+              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
             },
             "maxItems": 9
           },
@@ -3498,7 +3566,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "公网 URL、asset:// 或 OSS object key。仅 Seedance 2.0 系列支持。"
+              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时视频必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
             },
             "maxItems": 3
           },
@@ -3506,7 +3574,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "公网 URL、asset://、OSS object key 或音频 Data URL。仅 Seedance 2.0 系列支持。"
+              "description": "公网 URL、asset://、当前账号的 objectKey、项目资源 ID 或素材 ID。本地临时音频必须先上传 OSS。禁止 Data URL / Blob URL。仅 Seedance 2.0 系列支持。"
             },
             "maxItems": 3
           },
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index fca36fd02..2d37e3794 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -103,6 +103,144 @@
 - 影响范围：`apps/ai-game-creator-shell/src-tauri/src/repository_context.rs`、Agent planning prompt、pending repository-context drift 门禁、真实 Runtime E2E harness 和 AI 游戏创作 Runtime 文档。
 - 验证方式：确定性测试覆盖发现根、优先级、YAML/路径/符号链接/预算、metadata 清洗、正文按需可见和 fingerprint 漂移；正式 `openai_chat / gpt-5.5` 的 `project-skill` suite 必须证明 hash-only fixture 先失败、匹配 Skill 在首个变更前读取、无关 Skill 不读取、唯一目标文件修改、Agent 与宿主验证通过，以及 Provider lifecycle、唯一回复、配置隔离和零泄漏全部闭合。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+## 2026-07-18 图片生成 K 档由 provider 直接生成
+
+- 背景：旧 gpt-image-2 尺寸表会把 2K 竖版回落到 `1024x1536`，图标入口又使用固定 `360x360 / 512x512` 占位；角色去背景结果变小时还会直接放大整张透明成品，导致 UI 显示的 2K 与模型实际生成清晰度不一致。
+- 决策：用户选择的模型、比例和 K 档先映射为 provider 可直接接受的真实像素，前端占位、api-server 请求和 VectorEngine request body 保持一致。带显式尺寸选项的用户生成不再用回图后缩放恢复 K 档；宣发素材固定交付尺寸与旧无尺寸请求保留原有兼容恢复。角色、图标和 UI 去背景降采样时只重采样 alpha 蒙版并应用回 provider 原始 RGB，不放大低分辨率后处理 RGB。
+- 影响范围：普通图片、角色形象、图标图集、UI 设计图的占位与生成请求，gpt-image-2 尺寸矩阵，以及角色透明后处理。
+- 验证方式：前端尺寸矩阵和入口占位测试、api-server 生成参数与 alpha 合成测试、platform-image 最终 request body 测试、类型检查、Rust check、编码和 diff 门禁。
+- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-18 阿里云 URL 抠图链路按外部调用阶段审计
+
+- 背景：阿里云 URL 抠图先从源 OSS GET，再解码、校验尺寸、归一化并上传临时 OSS；此前解码和尺寸失败仍使用普通 `InvalidRequest`，被错误标记为 `externalCallAttempted=false`，无法满足阿里云失败统一审计约定。
+- 决策：真正开始外部调用前的本地预检不写 `external_api_call_failure`；源 OSS GET 成功后发生的解码、尺寸、归一化、临时上传、阿里云请求和结果处理失败均进入审计。`platform-matting` 使用结构化 `LocalProcessing` 分类和 `failureStage`，由 api-server 映射为 `source_decode`、`source_validate`、`source_normalize`、`temp_upload`、`result_decode` 等阶段，不再把这些错误统称为“发请求前本地预检”。
+- 影响范围：`server-rs/crates/platform-matting/src/lib.rs`、`server-rs/crates/api-server/src/aliyun_matting.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/editor_project.rs`、后端架构文档。
+- 验证方式：运行 `cargo test -p platform-matting --manifest-path server-rs/Cargo.toml`、阿里云抠图与外部审计定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+
+## 2026-07-18 手动去背景稳定媒体引用校验收口
+
+- 背景：当前分支与 `master` 分别增加手动去背景专用 Data URL 校验和编辑器通用稳定媒体引用校验，直接叠加会让 API 与 worker 重复执行语义相同的 helper，并造成 `data:` / `blob:` 覆盖范围和错误文案漂移。
+- 决策：删除手动去背景专用校验。HTTP API 在入队前统一调用 `ensure_editor_reference_image_source_is_stable`，立即拒绝 `data:` / `blob:`；worker 不重复调用该入口校验，只通过 `resolve_editor_reference_object_key_for_owner` 完成稳定引用解析和 owner 归属校验。底层 `resolve_editor_reference_object_key` 在尝试 object key、项目资源 ID 或素材 ID 解析前统一拒绝内联媒体，作为历史任务和内部直接调用的最终边界。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、图片画布手动去背景测试和图片画布技术方案；不改变队列 DTO、BgFilter `image_url` 协议或 SpacetimeDB 的编辑器任务 payload 门禁。
+- 验证方式：覆盖 API 入队前拒绝 `data:` / `blob:`、解析器拒绝内联媒体、worker 只调用稳定引用解析与归属校验；运行 api-server 编辑器定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-17 画布 Agent 普通消息不提供客户端停止
+
+- 背景：普通消息进入 LLM 前，后端已经把用户消息写入 OSS；前端中断 fetch 只能停止本地等待，不能保证后端停止规划，且会保留无法与后端消息对齐的 optimistic message。
+- 决策：移除画布 Agent 普通消息的“停止”按钮和 `stopCurrentTurn`，发送期间保持按钮禁用并等待后端响应。待确认工具调用的“取消”仍保留，不受本决策影响。
+- 影响范围：画布 Agent 对话 hook、发送区交互、前端测试和专题文档。
+- 验证方式：运行画布 Agent hook / 面板定向测试、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
+
+## 2026-07-10 画布 Agent 工具确认分离执行参数与展示投影
+
+- 背景：画布 Agent 已在实际生成前进入 `pending_confirmation`，但 `EditorAgentToolCall.args` 只保存工具私有 JSON，其中图片参数是保护真实 data key 的 SHA-256 opaque ID。前端直接解析 raw args 只能显示内部哈希或图片数量，无法向用户准确展示即将使用的目标图、参考图和完整参数；若直接把图片 URL 或对象塞回 raw args，又会破坏确认执行反序列化和 LLM 不可见真实 data key 的安全边界。
+- 决策：`EditorAgentToolCall.args` 继续作为确认执行唯一真相，不允许前端改写或回传替代参数；新增必填 `displayArgs` 只读展示投影，内含 `stringArgs`、`imageArgs` 和 `extras.priceMudPoints`。`stringArgs` 承载提示词与规格等用户可见字段，`imageArgs.refs` 承载 `imageId` 及后端解析出的 `objectKey`、`imageSrc`、可选缩略图、标签和尺寸；`extras.priceMudPoints` 由 api-server 在创建待确认消息时使用后端运行时模型定价快照计算，前端只显示“预计消耗 N泥点”，不自行计算或回传价格。api-server 必须按已注册 tool 白名单，从已校验 args 与 OSS 会话文档的附件 / 历史生成结果构建该投影；前端只渲染投影，以 `ResolvedAssetImage` 换签显示图片，不解析 tool 私有 schema、不展示 SHA-256 ID。展示价格不参与确认执行或实际扣费，确认后仍由既有生成 BFF 按后端运行时定价预扣费。删除只重复 `args` 且没有稳定语义的 `EditorAgentToolCall.summary`。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
+- 影响范围：`shared-contracts` / `packages/shared` 的 `editorAgent` DTO、`api-server/src/editor_agent/api.rs` 的待确认消息构建、画布 Agent 待确认卡、OSS 会话消息文档与相关测试。
+- 验证方式：`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_agent`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`npm run test -- src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx src/services/image-editor/editorAgentClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`。
+
+## 2026-07-18 图片多产物任务的原图进入正常完成画布
+
+- 背景：角色形象、图标 spritesheet 和 UI 素材提取会同时持久化带纯色背景的 provider 原图与透明后处理结果；这些原图都需要在画布中可直接查看和复用。任务与扣费实际仍只有一次。
+- 决策：provider 原图继续写入 OSS、`asset_object`、项目资源和账号素材库。三类任务透明处理正常成功时，透明结果作为主图并保持生成器 `generatedLayerId` 锚点，provider 原图作为第二个图层放在透明主结果右侧；图标和 UI 的业务拆分素材从原图右侧继续排列。只有透明背景处理最终失败时，才把 provider 原图作为唯一主图完成占位并返回 warning。
+- 影响范围：角色形象、图标 spritesheet、UI 素材提取的画布完成快照，以及多产物持久化与画布展示边界。
+- 验证方式：后端定向测试断言三类任务正常成功都落透明主图与右侧 provider 原图、`generatedLayerId` 仍指向透明主图，图标 / UI 拆分素材继续排列在原图右侧，同时保留 source-only 失败降级测试；并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-17 生成后抠图原图以 OSS 作为内存生命周期边界
+
+- 背景：角色形象、图标图集、UI 素材图集和角色动作抽取帧的带背景原图虽然已先落私有 OSS，但 api-server 仍可能把原图字节保留到 BgFilter / 阿里云 / 本地 fallback 结束，造成并发任务下的内存峰值叠加。
+- 决策：目标链路的带背景原图上传 OSS 时消费 `DownloadedImage` 或动作帧字节所有权，不为上传克隆整张字节缓冲；上传完成后不再跨 BgFilter 调用常驻。手动去背景直接复用已有 OSS object key，不下载原图。BgFilter 只读取 600 秒签名 URL；进入阿里云 fallback 时由 `platform-matting` 新 URL 接口下载原图、上传 `AuthorizeFileUpload` 临时对象，并在开始阿里云推理前结束下载缓冲作用域；阿里云继续失败时，api-server 再从私有 OSS 独立下载原图供本地键色，产出后释放本次原图下载缓冲。
+- 边界：不改变接口 DTO、资源记录、画布原图展示、图集切分行为和降级顺序；“释放”指 Rust 所有权和 `Vec<u8>` 析构，RSS 不保证同步下降。
+- 验证方式：`platform-matting` 测试覆盖 URL 下载缓冲在临时上传后结束、降尺寸 Alpha 回贴；`api-server` 结构测试覆盖带背景原图 owned 上传、URL 阿里云 fallback、本地重新下载与原图释放；随后运行两个 crate 的测试与编译检查。
+
+## 2026-07-17 图片改造保持源图与所选清晰度
+
+- 背景：图片画布从已生成的 2K 角色图重新打开生成器时，面板恢复逻辑会优先采用新建面板的 1K 默认值；即使用户重新选择 2K，角色透明化链路也可能接受 BgFilter / 阿里云返回的 1K 后处理图，并因 `nanobanana2` 使用标量清晰度档位而跳过几何尺寸恢复，最终把 2K provider 原图降为 1K 透明图。
+- 决策：从既有图片重新打开普通图片、角色、UI 或宣发生成器时，在没有仍存活的生成对话框快照时按当前图层真实 `originalWidth / originalHeight` 恢复比例与清晰度，并按目标模型支持范围归一；恢复或切换比例 / 清晰度后，普通图片、角色、图标图集和 UI 设计图的待生成及生成中占位框必须同步使用目标像素尺寸，不能保留新建 draft 的默认 1K 框。UI 素材提取的占位按框选数量对应的 1K / 2K 计划生成，旧图片修改入口按源图真实尺寸占位。角色形象去背景完成后必须保持去背景前 provider 原图的像素尺寸；若去背景供应商返回较小结果，只把 alpha 蒙版重采样回原图并保留原始 RGB，不放大低分辨率透明成品。
+- 影响范围：图片画布生成对话框恢复、生成中占位尺寸、UI 素材提取与旧图片修改的 `canvasCompletion`、角色形象 BgFilter / 阿里云 / 本地去背后处理、项目资源与账号素材尺寸元数据。
+- 验证方式：覆盖“持久化 2K 角色图重开仍为 2K”“普通图片 / 角色 / 图标 / UI 改造的 2K 占位与目标一致”“普通生图、规范图和角色图生成中占位不回退 1K”“UI 提取和旧修改入口的完成占位使用业务目标尺寸”以及“较小去背结果只提供 alpha、最终 RGB 仍来自 2K provider 原图”的前后端定向测试，并运行前端类型检查、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## 2026-07-15 BgFilter 输入改用私有 OSS 短期签名 URL
+
+- 背景：角色形象、图标图集、UI 素材图集、角色动作抽取帧和手动去背景在调用 BgFilter 前都已有私有 OSS object key；继续由 api-server 下载或保留图片并作为 multipart `file` 再上传，会重复传输图片字节并占用 API 进程网络与内存。
+- 决策：上述抠图链路统一复用 object key，签发 600 秒 OSS GET URL，并通过 BgFilter multipart 的 `image_url` 字段提交；请求中不再携带 `file`。签名 URL 只交给 BgFilter，不写日志或持久化。2026-07-17 起，生成原图和动作帧上传后不再保留图片字节；进入“阿里云通用抠图 → 本地键色”兜底链时按阶段从私有 OSS 重新下载。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、相关测试与文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。
+- 验证方式：定向测试必须断言 BgFilter 请求函数包含 `image_url` 与 600 秒 OSS 换签，不包含 multipart `file` 或源图字节读取；随后运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+
+## 2026-07-15 阿里云通用抠图上传切换到 AuthorizeFileUpload 正式链路
+
+- 背景：`platform-matting` 原先通过 `viapiutils/GetOssStsToken` 获取临时 AK/SK，再向固定 `viapi-customer-temp` 共享桶执行 OSS V1 PUT。阿里云官方文档将该显式生成 URL 的共享临时桶通道标记为不保证 SLA、仅便于调试且不推荐生产使用；动作视频逐帧抠图会把这条风险放大到每任务 32 至 48 次。
+- 决策：非上海地域图片字节统一按新版官方 SDK `AdvanceRequest` 的实际协议处理：调用 `openplatform.aliyuncs.com` 的 `AuthorizeFileUpload` 获取单对象 `Bucket`、`Endpoint`、`AccessKeyId`、`EncodedPolicy`、`Signature` 与 `ObjectKey`；再以 multipart Policy POST 上传到动态返回的上海临时 OSS，表单字段为 `OSSAccessKeyId`（= AccessKeyId）、`policy`（= EncodedPolicy）、`Signature`、`key`（= ObjectKey）、`success_action_status=201` 与 `file`，最后把临时对象 URL 交给 `SegmentCommonImage`。移除 `GetOssStsToken`、固定 `viapi-customer-temp`、AccessKeySecret/SecurityToken 临时凭证组合和 OSS V1 SHA-1 签名；Policy POST 仍需要授权响应中的 `AccessKeyId`，不再下发可独立签名的完整临时密钥。图片归一化、结果下载、原尺寸 Alpha 回贴和上层降级顺序保持不变。该链路仍会让图片字节经过执行任务的 api-server / worker 并上传临时 OSS，不把它描述成阿里云服务端直接抓取任意公网 URL。
+- 影响范围：`server-rs/crates/platform-matting`、阿里云抠图冒烟示例、后端架构与开发运维文档；不改变 api-server DTO、动作拆帧、BgFilter 或业务降级契约。
+- 验证方式：`cargo test -p platform-matting --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并用真实图片运行 `segment_smoke`，确认授权上传 host 来自动态上海 OSS 且 `SegmentCommonImage` 成功返回。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、阿里云“通用图像分割”与“文件 URL 处理”官方文档。
+
+## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展
+
+- 背景：角色动作全部序列帧会并发进入 BgFilter，而服务端可能在自身进程内排队；固定 `180000ms` 会把排队时间和单帧推理共用同一预算，靠后的请求可能在服务仍正常处理时被 api-server 提前取消。
+- 决策：保留 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 作为统一基准值。只有角色动作逐帧 BgFilter 在共享 Client 的 RequestBuilder 上把每一次 HTTP attempt 覆盖为“基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧为 `244000 / 260000 / 276000ms`；角色形象单图、图标、UI 和手动去背景不增加帧预算。该 timeout 覆盖请求发起到响应体读取完成；首次失败后的重试重新获得同样的 request deadline，整批并发策略、失败排空语义和 worker long-job 总预算不变。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构、开发运维和图片画布专题文档。
+- 验证方式：运行角色动作超时公式、BgFilter request override 与逐帧流水线定向测试，执行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-15 手动复杂去背景复用 BgFilter 单次重试
+
+- 背景：图片画布手动去背景已经改用 BgFilter `background_mode=complex`，但 worker 仍只发送一次上游请求，短暂网络抖动会直接让任务失败。
+- 决策：手动去背景的 complex 请求复用现有 `EDITOR_BGFILTER_RETRY_COUNT=1`，首次请求失败后立即重试一次，两次都失败仍返回最终错误；本次不把手动 complex 接入标准纯色背景链路的阿里云 / 本地兜底，也不改变 flat 路径的熔断状态。
+- 影响范围：图片画布手动去背景 worker、BgFilter complex 请求日志和 api-server 定向测试。
+- 验证方式：运行 `cargo test -p api-server editor_manual_background_removal_retries_once --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/project-memory/shared-memory/decision-log.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-14 手动去背景迁移到 BgFilter complex 模式
+
+> 后续更正：本条关于 multipart 图片文件输入的描述已由 2026-07-15「BgFilter 输入改用私有 OSS 短期签名 URL」和 2026-07-17「生成后抠图原图以 OSS 作为内存生命周期边界」取代；当前手动路径不下载原图，只提交 `image_url`。下文保留作历史记录。
+
+- 背景：图片画布手动“去除背景”此前单独代理 BiRefNet 服务；BgFilter 已增加 `background_mode=complex`，可直接处理非纯色背景，继续保留独立服务会形成重复的上游、配置和错误处理链路。
+- 决策：`POST /api/editor/images/background-removals` 保持前端与 BFF 契约不变，worker 改用现有 BgFilter 地址、token、超时和共享 HTTP client。multipart 提交图片文件、`background_mode=complex`、`seg_model=birefnet` 与 `cross_check=off`，不提交 `screen_color`。标准纯色背景的角色形象、图标 spritesheet、UI 素材提取和角色动作逐帧抠图继续使用 `background_mode=flat`。删除独立 BiRefNet base URL / timeout 配置；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 仅作为 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 的兼容回退别名。
+- 影响范围：图片画布手动去背景 worker、BgFilter HTTP 协议、api-server 配置、资源元数据、前端 provider 展示和相关文档。
+- 验证方式：运行 api-server BGFilter / 手动去背景定向测试、前端 editorProjectClient / 画布 workflow 定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-07-13 外部生成任务持久化真实执行阶段
+
+- 背景：图片画布任务列表此前把所有 `running` 任务固定映射为“正在生成”，角色生图、图标/UI spritesheet、角色动作和手动去背景进入抠图后仍无法展示“正在处理”；前端按耗时推断阶段会产生新的非正式业务真相。
+- 决策：不新增 DB 表，在既有 `external_generation_job` 与 `external_generation_job_summary` 末尾追加带默认值的可选 `phase`。worker claim 时写 `generating`；角色生图、图标 spritesheet、UI 素材提取在调用 BgFilter 前，角色动作在视频生成返回并开始抽帧/逐帧抠图前，手动去背景在执行开始时，通过 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；api-server 对 `LeaseFencingRejected` 立即终止，对 `OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，仅对 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试 `1` 次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider，也不按错误文案猜测拒绝类型。BFF 将 `running + processing` 映射为“正在处理”，其它 `running`（含旧数据 `phase=None`）映射为“正在生成”；前端只展示后端投影。
+- 影响范围：`external_generation_job`、`external_generation_job_summary`、SpacetimeDB procedure / typed client / bindings、图片画布生成 worker、任务列表 BFF 与相关文档。
+- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、外部生成 module/client/api-server 定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作逐帧开启 BgFilter cross-check
+
+- 背景：角色动作逐帧抠图此前为减少额外推理开销固定传 `cross_check=off`，但动作帧同样需要保留发丝、镂空和运动边缘质量。
+- 决策：角色动作逐帧 BgFilter 请求固定显式传 `cross_check=on`，与角色形象保持一致；图标 spritesheet 和 UI 设计图素材提取继续固定传 `off`。该策略仍属于后端内部供应商参数，不进入前端或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作 BgFilter 全帧流水线与单次重试
+
+- 背景：角色动作抽帧后原先固定 `buffered(3)`，并在整批绿幕源帧串行落 OSS 后才开始抠图；每帧还单独创建 HTTP Client。公网 BgFilter 的网络等待会让服务端推理队列出现空档，且首个最终错误会通过 `try_collect` 提前取消 api-server 中其余已发 Future。
+- 决策：BgFilter HTTP Client 在 `AppState` 中统一创建并复用 keep-alive 连接池；每次 BgFilter 调用失败后立即重试 `1` 次，两次都失败才进入既有“阿里云通用抠图 → 本地键色”降级链，每次已发失败调用都保留审计。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的 `buffer_unordered` 连续发射并携带原始帧序，完成后排序；不在 api-server 新增供应商进程锁或全局 Semaphore。任一帧最终失败时先排空全部已启动 Future，再让整个动作任务失败退款，不发布缺帧动画。
+- 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_retries_once_before_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+## 2026-07-16 SpacetimeDB 备份采用逐文件基线、CAS 增量与安全历史清理
+
+- 背景：SpacetimeDB standalone 2.6.0 不自动删除已被 snapshot 覆盖的历史 commitlog 与旧 snapshot；反复压缩整个 `/stdb` 会重复占用磁盘、停机和 OSS 带宽。上游 issue #5542 的 contributor 明确说明，不触碰最新 snapshot 与重启所需 commitlog suffix 时，可在运行中移动或删除这些历史文件。
+- 决策：统一脚本新增 `--storage-format files`，完整基线递归保留目录、文件和 data-dir 内部相对符号链接，普通文件按 SHA-256 上传为不可变 CAS 对象，catalog 记录目录、路径、长度、SHA、对象 key 与相对链接目标；绝对或越界链接拒绝备份。相同内容不重复 PUT，后续 full 扫描只上传新增或变化内容，不再生成 tar.gz。旧 `archive` 路径保留兼容。full 必须从停库目录或已验证的冻结副本生成，不能把在线跨文件扫描称为一致时点备份。
+- history 继续按 replica 计算安全边界：只接受完整、未锁定且含同 offset `.snapshot_bsatn` 的 snapshot，保留跨越最新 snapshot 的边界 segment 及全部后缀。旧 segment 对和旧 snapshot 被递归映射为单文件 CAS 对象；对象、history catalog、full baseline catalog、候选 fingerprint 与当前边界全部验真后才删除源文件。同库执行用 work-dir PID lock 互斥。
+- OSS 固定恢复入口为 `<prefix>/<database>/latest.json`。CAS 文件和 full/history catalog 保持不可变；latest pointer 只保存最新 full catalog 与已发布 history catalog 的 object key、长度和 SHA，不包含主机绝对路径或文件内容。每次 state 变化先验真全部引用 catalog，再覆盖上传并 HEAD 验真 latest pointer，成功后才落本地 state；history 还必须在 pointer 成功后才允许删除源文件。全新机器可仅凭 bucket、database、prefix 与 OSS 凭据自动下载 pointer 和 full catalog。
+- dev 带宽不足时，允许把已冻结的 dev 基线经 `10.2.0.10 -> 10.2.4.16` 内网 rsync 到 release 独立 staging，再用 release 出口上传 dev bucket；staging 不得指向 release `/stdb`，不得停止或修改 release 服务，传输凭据必须临时创建并在演练后移除。catalog 不记录 staging 绝对路径，files state 可回传 dev 继续 history。
+- 恢复边界：恢复时默认从 OSS `latest.json` 自动定位 full catalog，创建目录并按相对路径下载每个对象、逐文件校验长度与 SHA；本地 state 只用于备份续跑，不再是异机恢复前置条件。远程 dev 已完成真实 OSS、清理、重启和异机隔离恢复演练；release timer 与 publish 前备份继续保持原行为。
+- systemd 接线：主 service 保持 `archive-full`。Server-Provision 新增默认值为 `archive-full` 的 `DATABASE_BACKUP_PROFILE`；dev 或 release 显式选择 `files-history` 时，必须为各自主机指定独立 work-dir，并先用 current release 脚本执行 history dry-run，确认已有 full state 后才安装仓库托管 drop-in，并删除现场手写旧 drop-in。切回默认 profile 必须删除所有 history 覆盖。
+- 影响范围：`scripts/database-backup-to-oss.mjs`、备份门禁、生产 env 示例、systemd 模板、Server-Provision、SpacetimeDB 运维与恢复流程；release timer 可在独立 baseline 验证后显式选择 profile，publish 前备份是否切换仍需单独决策。
+- 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；dev 现场必须完成逐文件 full catalog、重复 full 零 PUT、history dry-run、上传后清理、STDB 重启和按 catalog 隔离恢复 roundtrip。
+- 关联：<https://github.com/clockworklabs/SpacetimeDB/issues/5542#issuecomment-4981566448>。
 
 ## 2026-07-14 后台账号采用 owner 引导账号与一级 Tab 实时授权
 
@@ -123,8 +261,9 @@
 ## 2026-07-13 图片画布多产物生成任务必须保存全部可恢复产物
 
 - 背景：角色形象、图标 spritesheet 和 UI 素材提取会先得到带纯色背景的原图，再执行抠图或拆分；图片修改会先得到模型对齐尺寸的原始输出，角色动作会先得到绿幕预览视频，再抽帧和抠图。此前部分原始产物只登记到 OSS，或者要等后处理成功后才进入项目资源，用户无法在失败后找回已经生成成功的内容。
-- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取同时保留纯色背景原图与透明后处理结果。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
-- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，生成器 `generatedLayerId` 锚定主后处理结果。图标和 UI 图集自动拆分是 best-effort；识别或切片持久化失败仍完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取在透明背景处理正常成功时同时保留纯色背景原图与透明后处理结果；透明背景处理最终失败时只保留已经持久化的 provider 原图，并按下一条降级规则收口。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
+- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，正常成功时生成器 `generatedLayerId` 锚定主后处理结果，角色形象、图标 spritesheet 和 UI 素材提取都把 provider 原图作为第二个图层放在透明主结果右侧；图标和 UI 的业务拆分素材从原图右侧继续排列。三类任务已经保存 provider 原图、但透明背景处理最终失败时，任务以 `completed + warning` 收口，原图作为唯一主图完成画布占位；不写入不存在的透明处理图，图标和 UI 也不继续拆分。透明处理成功后的图标和 UI 图集自动拆分仍是 best-effort；识别或切片持久化失败继续完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 2026-07-16 告警契约补充：inline / external v1 继续返回结构化原始诊断；queue 有意把通用 `warning` 或 `sliceWarning` 归一为展示就绪字符串，通用 `warning.reason` 原样保留，`sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀，摘要与 BFF 原样投影，Web 直接展示。历史值保留写入时快照，不按新格式回填或推断；该内部字符串契约通过 API/worker 与 Web 同一维护窗口、同版本发布收口，不增加混部兼容层。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`character_animation_assets.rs`、外部生成任务摘要、图片画布完成快照、账号素材库和前端生成提示。
 - 验证方式：覆盖中间产物登记先于后处理、默认素材文件夹、图集拆分降级、inline / queue warning 和主结果锚定的定向测试，并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、前端定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -132,7 +271,7 @@
 ## 2026-07-12 泥点充值收敛为四档并统一资产入口
 
 - 背景：主站与图片画板的泥点余额入口、余额明细和充值弹窗存在不同实现，旧充值口径仍展示六档泥点、首充双倍和会员购买 / 升级入口，容易让展示、商品资格与后端余额真相发生漂移。
-- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
+- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。钱包明细每次展开都重新读取充值中心 BFF，打开期间实时总额变化时继续补读；图片画板的生成扣费或退款完成后同时刷新总额与充值中心拆分。充值中心读请求必须使用 revision 门禁，支付创建、到账确认等权威响应写入时使旧读失效，避免旧响应覆盖新的每日免费 / 不限时明细。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
 - 影响范围：`profile_recharge_product_config` 默认商品、充值中心 read model、共享前后端契约、主站与图片画板泥点资产入口、充值弹窗、后台充值商品默认值。
 - 验证方式：充值与统一入口定向前端测试、`npm run typecheck`、充值商品定向 Rust 测试、`cargo check -p spacetime-module -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -145,6 +284,14 @@
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、钱包定向 Rust 测试、个人中心定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
+## 2026-07-11 BgFilter 交叉模型否决用于角色形象与角色动作
+
+- 背景：新版 BgFilter 的 `cross_check` 默认开启，会额外运行 HR-matting 第二意见模型；角色形象与角色动作序列帧需要保留发丝、镂空和运动边缘质量；图标 spritesheet 和 UI 素材提取不需要承担这部分额外推理开销。
+- 决策：api-server 调用 BgFilter 时必须显式发送 multipart 字段 `cross_check`，不依赖服务端默认值。角色形象生成和角色动作逐帧去背固定传 `on`；图标 spritesheet 生成和 UI 设计图素材提取固定传 `off`。角色动作逐帧去背与三条静态生图路线复用同一条 `BgFilter → 阿里云通用抠图 → 本地键色` 降级链和同一 BgFilter 熔断器。该字段是后端内部供应商策略，不进入前端请求或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、图片画布 BgFilter 调用文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 2026-07-11 SpacetimeDB 工具链统一升级到 2.6.0
 
 - 背景：生产数据副本验证已使用 2.6.0 standalone，而仓库 Rust crate、本地 CLI、生成 bindings、容器与 server provision 仍锁定 2.5.0 或更早版本，继续混用会增加 BSATN / procedure 返回值与发布产物错配风险。
@@ -153,6 +300,14 @@
 - 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、`npm run test -- scripts/dev.test.ts`、server provision 工具测试、production ops / encoding / diff 门禁。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 2026-07-17 SpacetimeDB 工具链统一升级到 2.6.1
+
+- 背景：SpacetimeDB 2.6.1 修复 procedure context 中调用者 `Identity` / `ConnectionId` 丢失问题，并修正 TypeScript 生成代码中 `Option<T>` 字段的可选键语义；继续运行 2.6.0 会保留已知 procedure 身份回归。
+- 决策：`server-rs/Cargo.toml` 的 `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 精确锁定 2.6.1；本地 CLI / standalone、Rust bindings、worker smoke、容器压测镜像和生产 provision 下载根同步对齐 2.6.1。
+- 影响范围：Rust workspace lockfile、SpacetimeDB bindings、本地 dev 版本门禁、容器 smoke / loadtest、server provision Jenkins 与项目 SpacetimeDB skills / 文档。
+- 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、server provision 工具测试、encoding / diff 门禁。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-07-10 外部生成任务只持久化轻量媒体引用并独立维护摘要投影
 
 - 背景：编辑器 worker 化后直接把同步接口 payload 序列化进 `external_generation_job.request_payload_json`；前端又把已有 OSS `objectKey` 下载成 Data URL 再提交，导致单个任务 JSON 膨胀到数 MB，正式任务列表读取 20 条任务时同时搬运约 65 MB payload，并放大为 SpacetimeDB 与 api-server 的瞬时内存峰值。此前“禁止 Data URL 持久化”只覆盖工程、素材、图层和元数据，遗漏了正式生成任务表。
@@ -197,7 +352,7 @@
 ## 2026-07-09 角色动作视频生成背景色统一为多色自动决策 + 阿里云抠帧
 
 - 背景：角色动作视频抽帧过去固定 legacy `#00FF00` 绿幕 + 本地 `editor_green_screen`，与生图链路的多色自动决策不一致；实测出现背景色与前景 / 皮肤撞色（蓝撞蓝、桃 / 黄撞肤色）以及图生视频背景变白的问题。
-- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
+- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走 BgFilter（固定 `seg_model=birefnet`、`cross_check=on`），失败依次降级阿里云通用抠图和本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
 - 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs`、`editor_screen_background_decision.rs`、`editor_screen_background_filter.rs`（新增硬过滤模块）、`editor_green_screen.rs`（调色板）、`external_api_audit.rs`、`llm_model_routing.rs`、图片画布 MVP 与后端数据契约文档。
 - 验证方式：`cargo test -p api-server editor_screen_background character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、真机对源角色图跑视觉决策与候选危险度表、抽帧后采样序列帧背景色确认落在冷区安全集。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -312,6 +467,8 @@
 
 ## 2026-07-05 BgFilter 失败时本地纯色去背兜底
 
+> 后续更正：本条关于手动去背景仍使用独立 BiRefNet BFF 的描述已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：曾用一次性 BgFilter live probe 稳定复现 BgFilter 对 2K 输入返回 `HTTP 500 {"detail":"inference failed"}`，浏览器生成链路会因此收到“BgFilter 服务返回非成功状态”。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取仍优先调用独立 BgFilter；若 BgFilter 请求失败、返回非成功状态、返回空图片或非法图片，api-server 记录 warning 后使用本地 `editor_green_screen` 按解析后的纯色背景执行确定性去背兜底，不中断生成。手动任意图片去背景仍只走独立 BiRefNet BFF，不使用该兜底。
 - 更正（截至 2026-07-10 实现）：BgFilter 失败/熔断后不再直接本地兜底，而是先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 键色兜底；口径统一见 2026-07-09「角色动作视频…阿里云抠帧」决策，并已扩展到本条的角色形象/图标/UI 三条静态生图链路。
@@ -321,6 +478,8 @@
 
 ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
 
+> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
 - 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
@@ -362,10 +521,10 @@
 
 ## 2026-07-03 画布Agent会话元数据入 SpacetimeDB、消息正文存 OSS
 
-- 背景：图片画布工程需要对话式编辑历史，但消息正文随流式输出增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
-- 决策：新增 `module-editor-agent` 承载纯领域规则，`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、SSE、OSS 读写和既有生成工具调用。
+- 背景：图片画布工程需要对话式编辑历史，但消息正文随对话和工具结果增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
+- 决策：`module-editor-agent` 只承载可供 SpacetimeDB WASM 使用的纯领域规则；Agent runner、工具实现和资产 DTO 迁入原生 `platform-editor-agent`，仅由 `api-server` 依赖。`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、普通 JSON 消息、OSS 读写和既有生成工具调用。用户消息以独立 `clientMessageId` 在会话锁内幂等，数字 `message.id` 只作后端定位；旧 OSS 消息允许缺失幂等键，早期用户消息字符串 `id` 在读取时迁入 `clientMessageId`。画布 Agent 只与任务侧栏互斥，不与左侧素材 / 图层栏互斥。
 - 影响范围：图片画布右侧 Agent 面板、`shared-contracts` / `packages/shared` 的 `editorAgent` 契约、`spacetime-module` / `spacetime-client`、`platform-oss` 内部读签名边界、画布生成落板规则。
-- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 SSE client 定向测试、`npm run check:encoding`、`git diff --check`。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 JSON client 定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
 ## 2026-07-01 认证工作集只经 typed projection 同步正式表
@@ -378,6 +537,8 @@
 
 ## 2026-06-29 图片画布手动抠图走远端 BiRefNet BFF
 
+> 后续更正：本条独立 BiRefNet 服务、专用 base URL 以及 api-server 下载并解析原图的实现，已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：用户手动“去除背景”面对任意图片，前端 `chromaKey` 和标准绿幕后处理不适合复杂人物、自然背景或非纯色背景；远端 image host 已部署 BiRefNet 服务，需要让手动抠图走高质量模型，同时避免把服务令牌暴露到浏览器。
 - 决策：画布手动“去除背景”默认调用登录态同源 BFF `POST /api/editor/images/background-removals`。api-server 解析当前图片后代理到 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认指向 `http://58.87.105.82/remove-background`，可选 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只在服务端注入。api-server 对上游结果做字节和尺寸上限保护，并先落 OSS / asset object 再返回给前端。编辑器自己生成的标准绿幕资产不属于该决策，见 2026-06-30 绿幕契约收口。
 - 影响范围：api-server 编辑器图片接口、图片画布手动去背景、画布右上角任务侧栏、图片画布 MVP 技术文档。
@@ -551,13 +712,15 @@
 ## 2026-06-18 图片画布 UI 设计图提取素材保留图集
 
 - 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
-- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。UI 提取把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成先把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库并回填画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
+- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。透明背景处理正常成功时，UI 提取把透明 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放 provider 原图和拆分成功的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成在透明背景处理正常成功时把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库和画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分素材从 provider 原图右侧继续排列。拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。2026-07-16 起，透明背景处理最终失败时只把已经持久化的 provider 原图作为唯一主图放入画布，以 `completed + warning` 收口，不创建透明图集，也不继续拆分。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
 - 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
 - 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
 - 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
 
 ## 2026-06-30 图片画布标准绿幕契约收口
 
+> 后续更正：本条关于生成资产只使用本地透明化、手动路径继续使用独立 BiRefNet 的描述，已由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代；当前 flat 链路为 `BgFilter → 阿里云 → 本地键色`。下文保留作历史记录。
+
 - 背景：角色形象、图标 spritesheet、UI 提取 spritesheet 和角色动作帧都要求模型生成标准绿幕，但提示词片段和后处理入口分散在多个模块中，容易把标准绿幕资产误接到远端 BiRefNet。
 - 决策：编辑器标准绿幕提示词和本地确定性绿幕透明化统一收口到 `server-rs/crates/api-server/src/editor_green_screen.rs`。手动 `POST /api/editor/images/background-removals` 继续面向用户任意图片并走 BiRefNet；编辑器自己生成的标准绿幕资产统一复用 `platform-image::generated_asset_sheets` 的本地透明化能力，不再依赖 BiRefNet。角色图、图标 spritesheet、UI 提取 spritesheet 和角色动作抽帧源图必须在绿幕透明化前先保存一份带绿幕原图到 OSS，便于追溯和重处理。
 - 影响范围：`editor_project.rs` 的角色图 / 图标图集 / UI 提取图集、`character_animation_assets.rs` 的编辑器角色动作帧、编辑器绿幕相关文档。
@@ -1539,7 +1702,7 @@
 - 2026-06-07 追加：`GENARRATIVE_EXTERNAL_GENERATION_MODE` 使用 `queue|inline` 显式策略；生产和容器扩缩容验证保持 `queue`。本地开发若需要同步等待结果，应通过 `.env.local` 或本机环境显式配置为 `inline`，由 HTTP handler 复用同一 worker executor 直接返回 `completed`，不创建 `external_generation_job`，不支持 worker 动态扩缩容；脚本不得硬编码该策略。拼图写回 guard 字段改为可选，queue 路径仍必须完整校验 `job_id + worker_id + lease_token`；inline 路径只允许三项同时为空，半空 guard 仍拒绝。
 - 2026-06-11 追加：生产新增固定 `external-generation-controller` 进程角色和 `genarrative-external-generation-controller.service`。controller 只读取 `get_external_generation_queue_stats_and_return` 队列统计并管理 `genarrative-external-generation-worker@N.service`，不监听 HTTP、不执行外部生成任务；默认保留 `@1`，按 `claimable_pending + running_active + expired_running` 计算目标实例数，上限由 `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_MAX_WORKERS` 控制，缩容需要连续空闲轮数且每轮只停最高编号一个实例。
 - 2026-07-08 追加：生产 worker/controller 作为轻量 SpacetimeDB 客户端运行，专属 env 示例默认 `GENARRATIVE_SPACETIME_POOL_SIZE=1`；非 HTTP 角色只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure，且不再订阅 API 读模型连接池。worker/controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。
-- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 结束本次尝试、写失败 / 重试状态并释放 worker 槽位，若 SpacetimeDB 当时不可写则最多等到较短 lease 过期后重新领取，避免无进展续租无限延长。资产计费层对已扣费但 future 被取消的外部生成操作做异步补偿退款，避免超时取消绕过退款 outbox。
+- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 停止续租并释放 worker 槽位，但不取消已启动的业务 future，也不主动写失败 / 重试状态。在途写回由 lease fencing 仲裁：有效租约内照常完成，租约过期后任务可被重新认领，attempt 耗尽时由认领事务原子标记失败并结算退款，避免客户端取消与服务端写回发生竞态。
 - 影响范围：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、拼图 `compile_puzzle_draft`、拼图 `generate_puzzle_images`、拼图 `generate_puzzle_ui_background`、生产 env 模板和运维文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并在 queue 模式下用 `GENARRATIVE_PROCESS_ROLE=all npm run dev` smoke 至少一次 queued -> worker 完成链路；本地 inline 排查只确认不创建 `external_generation_job`。
 - 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -2518,7 +2681,7 @@
 ## 2026-05-07 server-rs Cargo 依赖集中到 workspace
 
 - 背景：`server-rs` 多 crate 已稳定成 DDD workspace，成员 `Cargo.toml` 中重复散写第三方版本和本地 path 依赖，升级 SpacetimeDB SDK、`serde`、`reqwest`、`tokio` 等依赖时容易漂移。
-- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。例外：`platform-matting` 向 VIAPI 官方临时 OSS 桶上传抠图输入时，因该临时桶接口要求 OSS V1 头签名，允许在该 crate 内部受限使用 `sha1` / `Hmac<sha1::Sha1>` 生成 V1 签名；该例外不得扩展到自有 OSS、通用阿里云 OpenAPI 或其它新链路。
+- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。2026-07-15 起，`platform-matting` 已移除 VIAPI 共享临时桶的 OSS V1 SHA-1 例外，改用 `AuthorizeFileUpload` 返回的 Policy POST 授权；后续不得恢复 crate 内 SHA-1 签名。
 - 影响范围：`server-rs/Cargo.toml`、所有 `server-rs/crates/*/Cargo.toml`、`platform-oss`、`platform-auth`、后续新增 Rust crate 或新增 Rust 依赖的开发流程。
 - 验证方式：修改 Cargo 配置后先执行 `cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps`，再按影响范围执行 `cargo check`、DDD 边界检查和编码检查。
 - 关联文档：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。
@@ -3347,8 +3510,9 @@
 ## 2026-06-19 编辑器角色形象回填改用通用抠图
 
 - 背景：画板编辑器里的 `生成角色形象` 属于编辑器图片生成链路，用户要求把“人物抠图”改成通用抠图方法，不再与 RPG / 资产工坊角色主图专用后处理绑定。
-- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；输出仍归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
+- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；透明背景处理正常成功时输出归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
 - 2026-06-22 补充：所有明确设置绿幕用于后续抠图的 prompt 都必须固定写明 `#00FF00 / RGB(0,255,0)`，不能只写“纯绿色绿幕”或“接近 #00FF00”；编辑器角色图通用抠图额外开启暗绿 / 灰绿绿幕背景识别，只作为生成模型偏离标准亮绿时的兜底。该宽松识别只参与从画布边缘连通扩散出的背景清理，不参与全图断开绿色区域删除，避免误伤角色衣物或纹理。
+- 2026-07-16 补充：透明背景处理最终失败、但 provider 原图已持久化时，角色任务以 `completed + warning` 收口，provider 原图作为唯一主图放入画布，不创建透明处理图。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 - 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_general_cutout`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet_muted_green_alpha_requires_explicit_option`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
 
@@ -3362,6 +3526,13 @@
 - 影响范围：`server-rs/crates/api-server/src/editor_generation_queue.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`。
 - 验证方式：`cargo test -p api-server external_generation_worker --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 
+## 2026-07-13 画布 Agent 工具执行状态复用外部生成任务
+
+- 决策：画布 Agent 的 OSS 工具消息使用 `status=not_completed|completed|failed|cancelled` 和可选 `externalJobId`；不使用 `cancelledAt`，不新增关联表。`external_generation_job` 是排队、执行、lease 与计费结算的唯一真相；OSS status 只表达该消息回填结果，不复制 queued / running。确认接口按 `conversationId + messageId + toolName` 稳定去重并复用既有编辑器 worker job kind。
+- 懒回填：`GET /conversation` 会在持有 conversation lock 后扫描 `status=not_completed` 且有 `externalJobId` 的工具消息，按 job id 定向读取主任务；完成时复用原工具 formatter 更新 system text、写入轻量媒体引用并标记 `completed`，任务本身失败时写入 `error` 并标记 `failed`。任务结果读取或 completed payload 解析 / formatter 首次失败后，在同一次 GET 内最多重试 3 次，每次等待 100ms 并重新读取主任务；读取失败或 completed 任务暂缺 `result_payload_json` 时，本次重试耗尽后保留 `not_completed + externalJobId` 供下次 GET 继续 reconcile，确定性的 payload 损坏、结构不兼容或 formatter 错误才在重试耗尽后写为 `failed`，避免致命错误永久循环。排队 / 执行保持 `not_completed`。worker 的 `result_payload_json` 只保留 formatter 与媒体引用所需的轻量生成回包，不向通用 summary 状态接口投影。
+- 影响范围：画布 Agent 共享契约、确认/取消接口、编辑器生成入队 helper、对话状态展示与恢复。
+- 验证方式：`cargo check -p api-server -p shared-contracts --manifest-path server-rs/Cargo.toml`、画布 Agent 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-06-18 原生壳 WebView 刷新能力只保留受控当前页刷新
 
 - 背景：Expo 移动壳和 Tauri 桌面壳都需要一个真实的宿主级刷新入口，供 H5 在检测到资源、登录态或运行态需要重新载入时请求宿主刷新当前容器；该能力不能演变成任意 URL 导航或原生 WebView ref 透传。
@@ -4348,7 +4519,7 @@
 
 - 背景：VectorEngine Apifox `api-349239079` 暴露 OpenAI-compatible `POST /v1/chat/completions`；创意 Agent 和通用 LLM 代理需要统一到 VectorEngine 文本服务，并将默认文本模型切换为 `gpt-5.4-mini`。
 - 决策：创意 Agent 的 `CREATIVE_AGENT_GPT5_MODEL` 固定为 `gpt-5.4-mini`，协议切到 Chat Completions，不再携带旧 APIMart `official_fallback` 字段；画布 Agent 侧边栏聊天规划请求也复用该模型和 Chat Completions 协议，不再显式使用 `gpt-4o` / Responses。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`。未单独配置 `GENARRATIVE_LLM_API_KEY` 时，api-server 可复用 `VECTOR_ENGINE_API_KEY`；前端 LLM 客户端必须兼容 OpenAI `choices`、api-server raw `{content}` 和项目 envelope `{ok,data:{content}}` 三种非流式响应，以及 OpenAI SSE delta 和 api-server `event: delta` 两种流式响应。
-- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` 等轻量摘要。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
+- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `toolName` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
 - 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate_image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate_image`，只有实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
 - 影响范围：`server-rs/crates/platform-agent`、`server-rs/crates/api-server/src/config.rs`、`src/services/llmClient.ts`、`.env.example`、`deploy/env/api-server.env.example`、`scripts/test-ve-llm.mjs`。
 - 验证方式：`npm run test -- src/services/llmClient.test.ts`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml from_env_reads_non_public_models_and_urls app_state_builds_creative_agent_gpt5_client_from_vector_engine_settings llm_chat_completions editor_agent_llm_request_uses_vector_engine_chat_model`、`cargo test -p platform-agent --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
@@ -4942,3 +5113,8 @@
 - 所有权与清理：账本保留同一 run 的已成功 planning entry，直到 run 完成、取消、失败、作废或明确 reconciliation 清理；这样单动作、多动作、confirmation、协作 batch 和直接回复都不会在下一 durable owner 建立前丢失。steer/cancel/终态/漂移清理前必须按整本账本补齐所有实际 requestId lifecycle，任一条失败时保留账本并进入 reconciliation。Runner 恢复会严格扫描 hash 路径、primary/`.previous` 和安全原子临时文件，清理合法终态遗留；Unix 全程使用固定目录句柄和根目录/Agent 目录 `flock`，安装用 `RENAME_EXCHANGE` 复核回滚，删除用 `RENAME_NOREPLACE` quarantine、inode 复核和原 fd 清空同步；Windows 使用相对父句柄及 `GetFileInformationByHandleEx` 句柄枚举，拒绝 reparse point/junction/硬链接并以禁止共享的独占句柄表示活跃 temp。两端都不依赖 PID 存活判断。未知、链接、目录身份替换或内容冲突项失败关闭。primary、`.previous` 或损坏账本阻止 `runner.shutdown_if_idle`。非协作同 UID 进程可主动忽略 Unix advisory lock，属于宿主 OS 信任边界，不纳入完整沙箱承诺。
 - 验收边界：确定性测试必须分别覆盖 base handoff 与 repair handoff 在 lifecycle completed 前停止，关闭 mock Provider 后恢复零网络、原 requestId 唯一闭合、repair/protocol audit 幂等、唯一 assistant/completed/committed stream和终局零 sidecar。独立非默认真实 suite `supervisor-swarm-tool-plan-handoff-runner-kill` 已实现并完成 Shell/Root 两级注册；它只使用 sentinel-owned sibling AppData 与 metadata-only zero-fault proxy，每轮随机 capability 严格绑定 project/Agent/run/实际 request slot。断点只能在 handoff 原子落盘并回读一致后、同一实际 requestId lifecycle `completed` 前 ACK，ACK 后才通过 pidfd `SIGKILL` 强杀 suite 自有 Runner。恢复必须在同一轮证明同一 requestId 唯一闭合、`networkReplayCount=0`、protocol/repair audit 幂等、handoff 与 durable batch plan fingerprint 对应、恢复消费前 action/pending/delivery/claim 等副作用为 `0`，并在终局得到零 sidecar、零重复、零临时资源残留和零正文/凭据/URL/绝对路径泄漏。2026-07-20 的真实单轮已经到达并通过上述 checkpoint，但随后因专业 Agent 连续连接失败而整轮 FAIL；另一独立轮因首批工具数不满足 fixture 也未通过，不能拼接为 PASS。Provider 成功到 handoff 原子落盘回读前的 unknown-result 及手动 context-compaction 仍不在本决策承诺内。
 - 当前证据：`tool_plan_`、`tool_plan_handoff_`、`provider_handoff_`、`provider_retry_`、`response_stream_`、`finalization_` 与 `finalization_resume_` 定向门禁均保持通过；本轮 `tool_plan_handoff_` 为 `44/44`，Supervisor collaboration 相关过滤为 `55/55`，权威返工合同用例为 `1/1`。Tauri/Rust 串行全量 1058 tests 为 `1054 passed / 4 ignored / 0 failed`，Linux `cargo check --tests` 与 `x86_64-pc-windows-gnu cargo check --tests` 均通过；E2E self-test、typecheck、变更脚本 ESLint、encoding 和 `git diff --check` 通过。默认并发全量只作竞态诊断，不替代 `--test-threads=1`。实现过程中发现并修复 thinking 归一化、源码路径误判、repair 漂移删账本、durable control 清理遗漏后继 repair lifecycle、复数敏感 key/Provider ID 泄漏、malformed JSON trivia 路径绕过、Agent DB 审计字段扩张、PID 复用 temp 误判、中间目录/文件名称换绑 TOCTOU、Windows 路径枚举 ABA 和审计尾部近似去重问题。真实 suite 的 checkpoint 已有单轮外部证据，但整轮仍无 PASS。
+## 2026-07-17 旧创作模板与入口停止维护
+
+- 决策：旧创作模板、旧创作入口及其专属运行服务进入下线范围，不再为跳一跳、抓大鹅 Match3D、儿童动作 Demo 等旧链路修复兼容问题、补生成脚本或维持专属门禁。
+- 边界：共享账号、钱包、资产、图片编辑器、公开作品、通用 HostBridge、API、SpacetimeDB、发布运维和安全能力不属于旧链路，仍需维持正式门禁。历史文档只作为背景材料，不再作为旧入口继续运行的依据。
+- 清理方式：允许直接删除已经失效的旧素材生成命令、入口路由、专属服务和对应测试；删除工程链路时仍需核对是否被当前共享能力引用，不能连带移除仍在使用的公共契约或持久化事实。
diff --git a/docs/project-memory/shared-memory/document-map.md b/docs/project-memory/shared-memory/document-map.md
index 18b38c8c6..cc98c88cb 100644
--- a/docs/project-memory/shared-memory/document-map.md
+++ b/docs/project-memory/shared-memory/document-map.md
@@ -1,6 +1,6 @@
 # 文档地图与阅读索引
 
-更新时间：`2026-07-03`
+更新时间：`2026-07-16`
 
 ## 当前文档入口
 
@@ -19,7 +19,7 @@
 | 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
 | UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
 | 图片画布生成面板与模型定价 | `docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】模型定价配置管理方案-2026-06-22.md` |
-| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、SSE 事件契约、与任务侧栏 / 左侧栏互斥规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
+| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、普通 JSON 消息、工具任务懒回填及侧栏并存规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
 
 ## 阅读顺序
 
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 0e79621e5..d7d4b121a 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -69,6 +69,29 @@
 - 处理：所有分钟级阶段等待都要在每轮先检查 owning task 的 failed/cancelled/budget-exhausted，以及 Runtime 的 needs-reconciliation；命中后立即抛出带阶段前缀的结构化错误。正常 pause 必须保留为可恢复状态，不能被 fail-fast 当失败；Runner 强杀后的 paused 稳定窗口继续按签名零推进单独验证。
 - 验证：用正式 `goal-runtime` 观察 Provider repair transport failure，确认部分报告立即保留成功/repair 协议计数、生命周期闭合和零泄漏证据；随后完整复跑仍能通过 Goal edit/pause/Runner kill/resume/finalization，证明 fail-fast 未破坏正常恢复路径。
 - 关联：`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e.mjs`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。
+## 图片生成的 K 档不能靠回图后缩放实现
+
+- 现象：用户选择 2K 时占位框看起来是 2K，最终资源元数据也显示为 2K，但模型请求实际仍是固定 1K 或竖版回落尺寸；画面只是后端放大后的低分辨率结果。
+- 原因：前端占位尺寸、api-server 的模型尺寸映射和 VectorEngine provider 合法尺寸各自维护；同时通用交付恢复与角色去背景恢复会直接缩放整张回图，掩盖了上游请求尺寸错误。
+- 处理：`model + imageSize + aspectRatio` 必须先解析为 provider 可直接生成的真实尺寸，前端占位和后端请求使用同一矩阵。带新尺寸字段的用户生成不执行回图后交付放大；角色、图标和 UI 的去背景服务若降采样，只缩放 alpha 蒙版并应用回模型原始 K 档 RGB。
+- 验证：覆盖 nanobanana2 / gpt-image-2 的比例与 K 档尺寸矩阵、VectorEngine 最终请求体、普通图片 / 角色 / 图标 / UI 占位，以及低分辨率去背景结果只贡献 alpha、不贡献被放大的 RGB。
+- 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/platform-image/src/vector_engine/request.rs`。
+
+## 多产物任务的中间原图不能只落资源库
+
+- 现象：角色形象、图标 spritesheet 或 UI 素材提取正常成功后，画布只有透明结果，用户无法直接对照和复用 provider 原图。
+- 原因：后端虽然为追溯和后处理失败恢复持久化了 provider 原图，但完成画布只写入透明主结果和拆分素材，把“资源已保存”错误等同为“用户已拿到原图”。
+- 处理：provider 原图始终写入 OSS、项目资源和账号素材库；三类任务正常成功时都同时落透明主结果与右侧 provider 原图，生成器 `generatedLayerId` 仍指向透明主结果，图标 / UI 拆分素材从原图右侧继续排列。仅当透明处理最终失败时，才用 provider 原图作为唯一主图完成占位。
+- 验证：覆盖三类任务正常成功都落透明结果与原图、原图位于透明图右侧、`generatedLayerId` 指向透明图、图标 / UI 拆分素材位于原图右侧，以及透明处理失败仍由原图单独完成占位。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
+
+## phase 上报的业务拒绝与传输失败不能共用字符串错误
+
+- 现象：provider 已经返回并保存原图，worker 上报 `processing` 时一次断连或超时就直接把任务判为失败；或者为了规避误杀而重试所有错误，导致 stale lease 的旧 worker 继续执行后处理。
+- 原因：phase procedure 的 lease / fencing 业务拒绝与 SDK 建连、断连、超时错误被压成同一种字符串错误，调用方无法可靠决定是否重试；按中文或 SDK 文案匹配会在错误文本变化后失效。
+- 处理：procedure 返回结构化 `LeaseFencingRejected` / `OtherRejected`，typed client 再把模块拒绝与 RPC 错误分开。`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试；只有 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试一次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider。不得让 phase 上报错误落入“后处理失败保留原图”的降级分支。
+- 验证：分别覆盖 lease / fencing 拒绝、其它拒绝、建连、断连、超时和第二次失败，确认最多调用两次；同时断言角色、图标和 UI 的原图降级只包住透明背景处理，不包住 phase 上报。
+- 关联：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
 
 ## 禁止 Data URL 持久化时不要漏掉异步任务 JSON
 
@@ -151,11 +174,19 @@
 - 验证：画板生成 workflow 测试覆盖 queueState 持续 `running` 到前端等待窗口结束时，不进入 failed、不显示该排队文案、不添加本地临时结果层。
 - 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`。
 
+## 图片画布历史不能回退当前权威状态或复活后端已删素材
+
+- 现象：生成占位框移动后开始生成，撤销移动会把仍在运行的生成对象恢复成待生成状态；切换到 2K 或改变比例后撤销位置，旧占位框还可能把当前尺寸回退。上传图层落库后，普通移动撤销可能被提示“可能会使图片消失”并永久卡在栈顶；即使安全检查已放行，直接恢复旧图层快照也会丢失刚回填的资源关联。素材库后端删除关联素材后，更早的移动快照还可能把已删图层重新加入并自动保存；修改素材类型虽然界面提示撤销成功，刷新后却可能从仍指向新类型的 resource 回弹。无稳定 ID 的“修改图片”草稿也可能被 target-null 快照直接关闭。
+- 原因：内容消失安全检查和历史快照合并是两道独立边界。图层内容签名若严格比较 `sourceAssetId`、`sourceResourceId` 等延迟回填的内部关联 ID，会把同一媒体误判为替换；放行后若仍用目标快照整体覆盖同 ID 图层或占位框，又会回退当前权威关联、内容或尺寸。相同 dialog ID 直接恢复整个旧对话框快照还会覆盖当前 `generating` / 完成态；没有 ID 的 edit 草稿则根本不会进入存在性检查。外部素材删除不写画布历史，若不主动剪除包含关联图层的旧目标快照，target-only 图层会被当作正常撤销删除完整恢复。`assetKind` 的正式事实保存在项目 resource，历史只改内存字段而保留当前 `resourceId` 时无法跨刷新成立。
+- 处理：图层内容身份按对象存储 key、对象标识和媒体地址的稳定优先级比较，内部关联 ID 的补齐不参与内容消失判断。同 ID 图层以 current 为权威，只从历史覆盖 `x`、`y`、`zIndex`、`groupId`、`assetKind`、`hidden`、`locked`、`flipX`、`flipY`；current 的资源关联、内容、媒体、生成元数据、尺寸和标题全部保留。同 ID generation dialog 从 target 恢复 placeholder 的 `x` / `y` 和 active / inactive 槽位对应的 `composerOpen`，current 的 `width` / `height` / `originalWidth` / `originalHeight`、当前参数、任务生命周期、提示词、参考图和结果保持一致；edit 草稿使用基于来源图层的稳定 ID。current 中不存在对应 ID 时属于撤销完整删除，可从 target 全量恢复对象。素材库删除必须用 `isLayerLinkedToAsset` matcher 同步过滤 undo / redo 中所有包含关联图层的 entry，即使图层只存在于历史中也要过滤；普通画布删除不调用该接口。assetKind undo / redo 每次重新创建匹配恢复类型的正式 resource，并按 layer 请求版本只接受最新响应。即时生成结果在追加图层前捕获生成历史，自动适合视图不再压入另一条历史。
+- 验证：覆盖 idle 生成框移动后进入 generating 再撤销、上传图层异步回填 `resourceId` / `sourceAssetId` / `sourceResourceId` 后撤销移动仍保留当前关联值、切换到 2K 或改变比例后撤销位置仍保留当前占位尺寸、非活动生成框被激活并拖动后撤销可恢复原 active / inactive 打开状态、撤销完整删除可以全量恢复对象、即时生成后第一次撤销直接命中生成保护、阈值内指针抖动既不移动也不产生历史、素材库删除后旧 undo / redo 无法复活关联 layer、edit 草稿不会被 target-null 快照吞掉，以及 assetKind 撤销与乱序 resource 响应后刷新仍保持最终类型。
+- 关联：`src/components/image-editor/ImageCanvasHistoryModel.ts`、`src/components/image-editor/useCanvasHistory.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasStageInteractions.ts`、`docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md`。
+
 ## 画板参考图 objectKey 必须先做归属校验
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
-- 原因：Data URL 参考图可以直接解析，但 objectKey 是服务端私有对象引用；只校验 generated 前缀、mime 和大小不能证明它属于当前账号。
-- 处理：所有编辑器参考图入口统一走 `parse_editor_reference_image(state, owner_user_id, source)`；objectKey 分支必须先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key，再读取 OSS。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 原因：Data URL/Blob URL 只允许停留在浏览器临时态，正式编辑器引用必须先上传并经统一 resolver 校验归属。
+- 处理：所有私有对象引用在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口（生成 / 重绘 / 图标 / UI 提取等交给 provider 的路径）再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
 - 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入图标生成请求；若快速编辑重开额外参考图，再补对应请求覆盖。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
 
@@ -288,21 +319,21 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx --reporter verbose`。
 - 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx`、`src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
 
-## 图片画布快速编辑不要直接提交普通图片 URL
+## 图片画布生成请求不要直接提交临时媒体源
 
-- 现象：图片画布快速编辑站内示例图、历史 generated 图或 OSS generated 图时，后端返回 `修改图片参考图必须是图片 Data URL。`。
-- 原因：快速编辑直接把图层 `src` 塞进 `/api/editor/images/generations` 的 `referenceImageSrcs`；默认示例图和部分持久化图层的 `src` 是 `/creation-type-references/*.webp`、`/generated-*` 或 OSS URL，而 `api-server` 的编辑参考图解析只接收 `data:image/*;base64,...`。
-- 处理：前端统一通过 `resolveEditorImageReferenceDataUrl(...)` 在提交前读取图片字节并转成图片 Data URL；Data URL 原样透传，`/generated-*` 和 generated OSS URL 先走 `/api/assets/read-url` 换签后由浏览器直读 OSS，直读失败时才 fallback 到 `/api/assets/read-bytes`，普通 public 路径直接 fetch。
-- 验证：`npm run test -- src/services/image-editor/editorImageReference.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx -t "editorImageReference|converts non-data-url quick edit source images before submitting references"`。
-- 关联：`src/services/image-editor/editorImageReference.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+- 现象：图片画布快速编辑、参考生成、去背景或角色动画提交 Data URL / Blob URL 时，前端或后端返回“必须先上传 OSS”。
+- 原因：Data URL / Blob URL 体积大且不能作为持久引用；如果写入外部生成队列，请求体会膨胀，worker 也无法稳定复用浏览器临时资源。
+- 处理：提交前优先复用图层已有 `objectKey`、项目资源 ID 或素材 ID；未登记的本地图片和普通 public 图片路径先通过 `resolveEditorGenerationMediaReference(...)` 读取并上传 OSS，再把稳定引用交给生成接口。Data URL 只允许用于浏览器内压缩、标注等临时处理，不能进入 API 请求、队列载荷或项目持久化。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server inline_data_url --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/editor_generation_queue.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
-## 图片编辑器角色动画不要默认提交大图 Data URL
+## 图片编辑器角色动画必须提交稳定图片引用
 
-- 现象：图片编辑器里对角色图点击 `生成动画` 后，后端返回 `Failed to buffer the request body: length limit exceeded`，请求还没进入角色动画 handler。
-- 原因：角色动画生成请求曾把角色图片 `src` 原样作为 `sourceImageSrc` 放进 JSON；角色图如果是较大的 Data URL，会超过 Axum 默认 `2MB` body limit，在 `Json` 提取器阶段被拦截。
-- 处理：前端在角色图已持久化时优先提交 `objectKey`，只把 Data URL 作为未持久化本地临时图兜底；后端 `/api/editor/character-animations/generations` 单独配置 `12MB` body limit 兼容旧请求，但新链路不应依赖传大图 JSON。
-- 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "only exposes character animation"`；`cargo test -p api-server editor_character_animation_accepts_character_image_body_above_default_limit --manifest-path server-rs/Cargo.toml`。
-- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`server-rs/crates/api-server/src/modules/play_flow.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+- 现象：图片编辑器里对尚未上传的角色图点击 `生成动画` 后，前端或后端返回 `sourceImageSrc 必须先上传 OSS`。
+- 原因：角色动画会进入外部生成队列，浏览器 Data URL / Blob URL 既不适合持久任务，也会放大 JSON 请求体。
+- 处理：前端统一通过 `resolveEditorGenerationMediaReference(...)` 取得 `objectKey` 或画板资源引用；本地临时角色图必须先上传 OSS。后端在入队前同步拒绝内联媒体，不再通过放宽 body limit 兼容 Data URL。
+- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 
 ## 图片编辑器角色动画抽帧不要采到视频尾点
 
@@ -376,11 +407,11 @@
 - 验证：`npm run test -- src/services/assetReadUrlService.test.ts --reporter verbose` 应覆盖大量不同 objectKey 同时换签时首批限量放行、后续按间隔派发；发布现场同类页面刷新时，Nginx `GET /api/assets/read-url` 429 应从 `upstream_status=-` / `genarrative_api_rps` 收敛。
 - 关联：`src/services/assetReadUrlService.ts`、`src/hooks/useResolvedAssetReadUrl.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
-## 图片编辑器 Seedance 2.0 参考媒体不要提交视频 Data URL
+## 图片编辑器 Seedance 2.0 参考媒体只提交稳定引用
 
 - 现象：画板生成视频选择 Seedance 2.0 并上传参考视频后，请求体暴涨、可能返回 `413` 或上游拒绝 `video_url.url`；文档示例或测试如果写 `data:video/mp4;base64,...`，后续实现很容易照抄。
-- 原因：火山 Seedance 2.0 参考视频只支持公网 URL 或 `asset://` 素材 ID，项目内画板资源应以 `objectKey` 由后端换签；视频不支持 Base64 / `data:video`，且 50MB 视频转 Base64 后会逼近或超过 64MB 请求体上限。参考音频虽然支持 Base64，但也不能单独输入，且大文件同样不应塞进 JSON。
-- 处理：参考视频 / 音频上传先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认；前端保留 signed URL 做预览，提交生成时优先使用 `objectKey`。后端归一化必须拒绝 `data:video/*`，非 Seedance 模型携带参考字段也必须拒绝；Ark body 显式带 `generate_audio:false`。
+- 原因：画板生成会进入持久队列，Base64 / Data URL / Blob URL 会放大请求和任务 JSON；直接签名客户端给出的 objectKey 又会绕过跨账号素材归属校验。项目资源 ID、素材 ID 和 objectKey 必须先解析到当前 owner 的正式对象，公网 URL 与 `asset://` 才能按供应商契约直接透传。
+- 处理：本地参考图片 / 视频 / 音频先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认；前端保留 signed URL 做预览，提交生成时使用 `objectKey`、项目资源 ID 或素材 ID。后端归一化拒绝全部 `data:*` / `blob:*`，签名 OSS URL 前统一校验 owner；稳定引用字段总长度限制为 `256KB`，非 Seedance 模型携带参考字段也必须拒绝；Ark body 显式带 `generate_audio:false`。
 - 验证：`npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`；`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`；`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`。
 - 关联：`src/services/image-editor/editorReferenceUploadClient.ts`、`src/components/image-editor/useImageCanvasUploadWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
 
@@ -428,9 +459,9 @@
 
 - 现象：用户点击图片素材的“快速编辑”后，画布上额外出现 `Quick Edit Generator` 占位，像是新建了一个生成器；但用户预期是在原图下方框选区域、填写一个提示词和模型，然后直接修改当前图。
 - 原因：快速编辑入口和提交链路误用了 `createQuickEditGenerationDialogDraft(...)` / `CanvasGenerationDialogState`，把“覆盖源图”的快速编辑伪装成会产出新图层的生成器占位。
-- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
-- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
-- 关联：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。
+- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。快速编辑任务进入 `generating` 后必须移除框选工具和覆盖层，禁止继续新增框选；失败恢复面板后可继续调整框选再重试。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
+- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。
 
 ## 图片画布快速编辑完成必须按目标图层回写
 
@@ -448,6 +479,22 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖来源参数继承、模型参数切换、目标尺寸提交和图层回填；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖图标类拒绝、provider 尺寸对齐和回图恢复。
 - 关联：`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`。
 
+## 图片画布生成中占位必须同步业务目标尺寸
+
+- 现象：用户选择 `2K` 生成或从 2K 普通图、角色图再次改造时，最终成品仍是 2K，但待生成 / 生成中的灰色框保持 1K 大小，完成后突然放大；UI 素材提取也可能始终显示 512 方框。
+- 原因：同来源改造先按默认 1K 创建 draft，再只恢复 `imageModel / aspectRatio / imageSize`，没有重新计算 placeholder；UI 提取和旧修改入口则分别写死图标展示尺寸与 `1024x1024`。
+- 处理：所有共享图片参数恢复和面板比例 / 清晰度切换都经过 `resizeGenerationPlaceholderToImageSelection(...)`，保持占位中心不变并同步 `width/height/originalWidth/originalHeight`；UI 提取按 `resolveUiAssetExtractionGenerationPlan(...)` 的 1K / 2K 计划计算占位，旧修改入口使用源图真实 Resolution。快速编辑覆盖源图，不另建生成占位，仍按目标尺寸更新原图层。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx --reporter=dot`。
+- 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`src/components/image-editor/ImageCanvasGenerationDialogModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片画布快速编辑模型必须在后端选择正确的 provider 协议
+
+- 现象：快速编辑继承或选择 `nanobanana2` 后，上游返回 `not supported model for image generation`；图集开放快速编辑后尤其容易触发。
+- 原因：前端把 `gemini-3.1-flash-image-preview` 正常提交到 `/api/editor/images/edits`，但后端无条件使用只支持 `gpt-image-2` 的 VectorEngine `/v1/images/edits` multipart 协议。
+- 处理：快速编辑请求同时提交 `model / aspectRatio / imageSize`。api-server 归一模型后分流：`nanobanana2` 使用 `/v1beta/models/{model}:generateContent`，把原图和参考图放入 `inline_data`，并传递 `generationConfig.imageConfig`；`gpt-image-2` 继续使用 `/v1/images/edits` multipart 和 16 像素 provider 边界对齐。nanobanana2 保留 provider 输出几何尺寸，不套用 GPT edits 的像素恢复。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖前端参数提交；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖模型分流、尺寸档位计费与 GPT 对齐恢复。
+- 关联：`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`。
+
 ## 图片画布纯尺寸变换必须先在内存决策再单次上传
 
 - 现象：`nanobanana2` 已返回并成功解码图片，任务随后报“尺寸无效”；普通生图若把尺寸恢复作为硬失败，provider 已成功回图后仍可能没有素材进入素材库和画布。
@@ -1666,6 +1713,14 @@
 - 验证：`npm run dev -- --watch` 下修改 `apps/admin-web/src/**` 应由 Vite HMR 处理，不应出现连续 `[dev] 重启 admin-web`；`scripts/dev.test.ts` 覆盖 web/admin-web 不注册外层 watch。
 - 关联：`scripts/dev.mjs`、`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
 
+## 根目录 `nohup.out` 持续写入会触发主站 Vite 刷新循环
+
+- 现象：在仓库根目录用 `nohup npm run dev ... &` 启动完整 dev 栈后，即使没有修改前端源码，主站页面也会反复整页刷新；`nohup.out` 同时持续增长。
+- 原因：未显式重定向 stdout / stderr 时，`nohup.out` 会收集 SpacetimeDB、api-server 和两套 Vite 的整套 dev 栈输出。主站 Vite 的 root 是仓库根目录，若 watcher 未忽略这个持续写入的文件，每次追加日志都会被当成文件变化；后台 Vite root 是 `apps/admin-web`，仓库根日志不在其监听根内。
+- 处理：主站 `vite.config.ts` 的 `server.watch.ignored` 保持忽略 `**/nohup.out`，Git 同时忽略 `nohup.out`。修改配置后重启主站 Vite。若显式重定向到其它仓库内日志文件，该文件不会自动受保护，应写到 Vite root 之外或补充精确忽略规则。
+- 验证：在仓库根目录追加 `nohup.out` 时主站不再刷新，真实源码修改仍正常触发 HMR；`git check-ignore nohup.out` 能命中忽略规则，`git status` 不出现该日志。
+- 关联：`vite.config.ts`、`.gitignore`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 本地 SpacetimeDB publish 401 可清本地库重发
 
 - 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
@@ -3389,3 +3444,26 @@
 - 验证：新命令为 `npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-final-reply-transient-retry-real-e2e -- --config-dir <发布AppData绝对路径>`；旧 `supervisor-swarm-transient-retry` 只保留首次 tool-plan 证明。fault proxy `14/14`、E2E self-test **PASS**、前端 `308/308` 及 shell typecheck、`platform-llm 41/41`、`platform-agent 17/17`、`shared-contracts 7/7` 等确定性门禁已完成。真实外部 Provider suite 共执行六轮，前五轮均为 **FAIL** 且不得拼接：第一、二轮沿用既有失败记录，第三轮为终态后过早观察到 `1` 个 finalization journal，第四轮为 quality-review 普通 tool-plan 连续 transport/connectivity 失败耗尽重试且未进入目标故障，第五轮为上述写锁竞争与绝对锁路径问题；修复后第六轮在同一轮内完整 **PASS**。
 - 第六轮证据：`gpt-5.5 / openai_chat`，`2` 条初始加 `1` 条 repair delivery、`3` 条专业 Agent assistant，Project Supervisor base final-reply 目标与可信宿主 verify marker 门禁均成立；受控 Provider `failed=1 / retry=1`、incidental `failure=0 / retry=0`，`30s` backoff，pidfd `claim=2 / signal=2`，Runner `resumed=true / identityStable=true`。父 tool-plan 故障前后均为 `13`，parent final-reply 与最终 assistant 唯一，response stream `sequence=2 / committed`；pending、retry、handoff、finalization、confirmation sidecar、全部重复计数及 API Key、私有正文、项目路径、正式配置路径和公共报告泄漏扫描命中均为 `0`。V1.41 handoff 原子提交前的 unknown-result 和 tool-plan handoff 未覆盖边界继续保留。
 - 关联：`apps/ai-game-creator-shell/scripts/llm-transient-fault-proxy.mjs`、`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e.mjs`、`apps/ai-game-creator-shell/tests/llmTransientFaultProxy.test.ts`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。
+## SpacetimeDB 历史归档不能按文件名小于 snapshot 就全部删除
+
+- 现象：看到最新 `N.snapshot_dir` 后，把所有起始 offset 小于 `N` 的 `.stdb.log` 删除，或者只把旧日志上传 OSS 就宣称已有完整增量灾备。
+- 原因：segment 文件名只表示该段最早事务；起始 offset 小于等于最新 snapshot 的最后一个 segment 可能跨越 snapshot 边界，重启仍需要它。历史归档也不会及时覆盖 control-db、program bytes、最新 snapshot 和 active segment。
+- 处理：latest snapshot 必须是未锁定且存在同 offset `.snapshot_bsatn` 的完整目录，空目录或同名 `.lock` 存在时忽略。每个 replica 独立保留 `max(segment_start <= latest_snapshot)` 及全部后缀，只处理更早 segment 对；旧 snapshot 只保留最新一个。`--storage-format files` 必须先发布完整 full catalog；history 对每个候选文件 CAS 对象、history catalog 和 full catalog 执行 HEAD 长度/SHA 验真，再复算边界与 stat fingerprint，最后发布并验真固定 `latest.json`；pointer 失败时不得推进 state 或删除源文件。不要把在线逐文件 full 扫描当成跨文件一致备份，基线必须来自停库目录或已验证冻结副本。SSH 或工具超时后先检查 work-dir PID lock 与原进程，不要直接并发重跑；不要在 history 模式传 `--stop-service`。定时任务通过 Server-Provision 的显式 profile 和仓库 drop-in 管理，启用前 dry-run 验证 baseline，切回 archive 时同时移除托管与现场遗留 drop-in；不要在 `/etc/systemd/system` 长期保留手写覆盖，release 必须建立和验证自己的 full baseline 与 work-dir，不能直接复用 dev 的本地 state。
+- 验证：dry-run 输出 replica 的 `latestSnapshot`、`boundarySegment` 和候选清单；从另一台机器仅凭 OSS `latest.json` 自动定位 full catalog，创建目录、下载文件并逐项校验长度/SHA，启动隔离 data-dir 验证 `/v1/ping`、snapshot restore、commitlog replay、module launch、代表性 SQL 与 reducer。
+- 关联：`scripts/database-backup-to-oss.mjs`、`scripts/check-database-backup-to-oss.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## Procedure 事务鉴权要兼容 SpacetimeDB 2.6.0 的匿名 TxContext
+
+- 现象：api-server 的 SpacetimeDB token identity 与 `editor_generation_pricing_config.writer_identity` 完全一致，服务启动门禁也通过，但手动拆分图集调用 `find_editor_asset_group_source_and_return` 仍返回“当前 identity 无权调用模型生成运行时服务”。
+- 原因：SpacetimeDB 2.6.0 的 `ProcedureContext::try_with_tx` 使用内部匿名事务上下文，闭包参数 `TxContext` 解引用得到的 `ReducerContext::sender()` 固定为 `Identity::ZERO`，不是 procedure 外层调用者。把 runtime writer 鉴权写成 `require_*(tx, tx.sender())` 会稳定误拒绝合法服务 identity。SpacetimeDB 2.6.1 已修复为向事务透传 procedure caller，但尚未升级的 dev / release 模块仍受 2.6.0 行为影响。
+- 处理：在调用 `try_with_tx` 前通过 `let caller = ctx.sender()` 捕获真实调用者，再把 `caller` 显式传入事务函数；迁移、后台账号、runtime profile、外部生成等现有 procedure 已采用这一模式。`npm run check:spacetime-runtime-access` 禁止编辑器 runtime writer 鉴权重新直接读取事务 `ctx.sender()`。运行环境升级到 2.6.1 后继续保留显式 caller，避免鉴权依赖 SDK 版本细节。
+- 验证：运行 `npm run check:spacetime-runtime-access`、`cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`；发布使用 SpacetimeDB 2.6.1 构建的新模块后，以 runtime writer identity 重试 `POST /api/editor/icon-spritesheets/slices`，确认来源查询、分片素材写入与 cohort 完成不再返回 identity 403。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`scripts/check-spacetime-runtime-access.mjs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## Portal 弹窗必须在遮罩根节点携带平台主题
+
+- 现象：项目库点击“重命名”后，标题、输入框和按钮仍显示，但弹窗面板及遮罩背景变透明，看起来像“改名界面的背景没了”。
+- 原因：`UnifiedModal` 默认 portal 到 `document.body`；若业务入口只在页面内层继承 `platform-theme`，portal 根节点不会继承该容器的 CSS 变量。此时 `.platform-modal-shell` 的 `background: var(--platform-modal-fill)` 和 `.platform-overlay` 的背景声明都会失效。
+- 处理：平台白底工具弹窗优先复用 `PlatformToolModalShell`，由共享壳读取当前 `AuthUiContext.platformTheme`，并把 `platform-theme platform-theme--<light|dark>` 挂到 portal overlay；不要用硬编码白底掩盖主题变量缺失。必须直接使用 `UnifiedModal` 的特殊场景，也要在 `overlayClassName` 显式传递当前平台主题。
+- 验证：在 light / dark 主题下打开 portal 弹窗，断言 dialog 的 overlay 携带对应主题类，并在真实浏览器核对 panel 与遮罩的 computed background 均非透明。
+- 关联：`src/components/project/ProjectGalleryView.tsx`、`src/components/common/PlatformToolModalShell.tsx`、`src/components/common/UnifiedModal.tsx`。
diff --git a/docs/project-memory/shared-memory/project-overview.md b/docs/project-memory/shared-memory/project-overview.md
index c38f161ff..bd97b320f 100644
--- a/docs/project-memory/shared-memory/project-overview.md
+++ b/docs/project-memory/shared-memory/project-overview.md
@@ -1,6 +1,6 @@
 # Genarrative 项目共享概览
 
-更新时间：`2026-06-23`
+更新时间：`2026-07-17`
 
 ## 一句话定位
 
@@ -36,7 +36,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 server-rs + Axum + SpacetimeDB
 ```
 
-当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.0` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
+当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.1` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
 
 职责边界：
 
diff --git a/docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md b/docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md
index 567120384..e6198b20e 100644
--- a/docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md
+++ b/docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md
@@ -1,6 +1,6 @@
 # SSE 客户端传输层收口约定
 
-更新时间：`2026-06-03`
+更新时间：`2026-07-16`
 
 ## 背景
 
@@ -13,7 +13,6 @@
 - `readSseStream` 负责读取 `Response.body`、识别 `\n\n` 与 `\r\n\r\n` 事件边界、合并多行 `data:`、flush `TextDecoder` 尾部缓冲，并支持事件处理函数返回 `false` 后取消 reader。
 - `readSseJsonStream` 只在传输事件基础上解析 JSON object，空 data 与异常 JSON 继续按旧口径静默跳过。
 - 各业务 client 只保留领域事件归一化、最终结果聚合和中文错误文案，不再重复实现 SSE 边界扫描、reader 循环或 UTF-8 flush。
-- `src/services/image-editor/editorAgentSse.ts` 消费画布 Agent 的 JSON SSE，只校验并归一 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done` 事件，不持有 reader 循环或事件边界解析。
 - OpenAI 兼容流、`[DONE]` 哨兵或其它非 JSON SSE 可直接使用 `readSseStream`；业务 JSON 事件优先使用 `readSseJsonStream`。
 
 ## 落地范围
@@ -26,27 +25,15 @@
 - `src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`
 - `src/services/rpg-entry/rpgProfileClient.ts`
 - `src/services/llmClient.ts`
-- `src/services/image-editor/editorAgentSse.ts`
 
 后续新增 SSE client 时不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环；若确实需要特殊 framing，应先扩展 `sseStream.ts` 的传输能力，再在业务 client 中处理领域语义。
 
-## 画布 Agent SSE client 口径
-
-`src/services/image-editor/editorAgentSse.ts` 是画布 Agent 的业务事件归一层，只允许做以下事情：
-
-- 调用 `readSseJsonStream(response, handler)` 读取 JSON SSE。
-- 白名单识别 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`。
-- 支持两种兼容输入形态：优先使用 SSE `event:` 字段作为事件名；若 `data` 内含 `{ "event": "...", "data": {...} }`，则归一为同一 `EditorAgentSseEvent`。
-- 对未知事件名、缺失 `data` 或非对象 JSON 静默跳过，保持业务 client 的容错口径。
-
-`editorAgentSse.ts` 不得实现 `Response.body.getReader()`、`TextDecoder`、SSE 边界扫描、JSON 字符串拼接、fetch、鉴权、错误文案、会话状态聚合或画布聚焦逻辑；这些职责分别留在 `sseStream.ts`、`editorAgentClient.ts`、`useEditorAgentConversation.ts` 和画布视图层。
+画布 Agent 已改为 `POST /api/editor/agent-conversations/{conversationId}/messages` 普通 JSON 请求，不属于本 SSE 传输层的落地范围；其客户端只通过 `requestJson` 读取 `EditorAgentMessageResponse`，不得为了恢复旧文档口径重新增加私有 SSE parser。
 
 ## 验收
 
 - `src/services/sseStream.test.ts` 覆盖 CRLF / LF 边界、UTF-8 尾部 flush、异常 JSON 跳过和提前停止取消 reader。
 - `src/services/llmClient.test.ts` 覆盖 OpenAI 兼容文本流、异常 JSON 跳过和 `[DONE]` 后提前停止。
-- `src/services/image-editor/editorAgentSse.test.ts` 覆盖画布 Agent 的 `stage`、`generation_result`、`done` 事件解析，以及 `{ event, data }` fallback 形态归一。
-- `src/services/image-editor/editorAgentClient.test.ts` 覆盖会话 CRUD 路由和 `/messages/stream` 发起后能收到类型化 SSE 事件。
-- 后续修改 `editorAgentSse.ts` 时，若出现手写 reader、`TextDecoder`、SSE 边界扫描或 fetch 逻辑，应视为违反本收口约定。
+- `src/services/image-editor/editorAgentClient.test.ts` 覆盖会话 CRUD 和 `/messages` 普通 JSON 路由；画布 Agent 不纳入 SSE parser 验收。
 - 已有 OpenAI 兼容文本流、NPC 聊天流、创作 Agent、创意互动 Agent、视觉小说运行态和充值订单状态测试继续通过。
 - `npm run typecheck` 不产生新的类型错误。
diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
index 01c745e50..478583ba6 100644
--- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
+++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
@@ -20,13 +20,15 @@
 - 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层、生成占位框或画板的边缘与中心线；当移动元素接近两个同轴元素形成的等距位置时，支持横向或纵向等距吸附。
 - 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词、重绘提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片，并提供“复制信息”复制当前可见字段。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。
 - 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。重绘 / 改造输入框只允许从 `generationInputs.fields` 中恢复用户可见输入快照，例如普通生成提示词、视频描述、音效 `prompt`、背景音乐 `gpt_description_prompt`、角色设定、UI 用户输入、图标素材描述、规范表单和宣发素材字段；禁止回退展示资源 `prompt` / `actualPrompt` 中的后端拼接 Prompt、固定生成模板或模型默认提示词。没有用户输入快照的旧图层打开改造时保持空输入，等待用户重新填写。
-- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端读入当前图层图片 Data URL 后走同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片源读取为图片 Data URL；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
-- 图片画布抠图分两类：手动去除背景面向用户任意图片，走登录态同源 BFF `POST /api/editor/images/background-removals` 并转发远端 BiRefNet；编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用独立 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `180000ms`（BgFilter CPU 推理）。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt 和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。三条 BgFilter 路径还必须固定把默认 `segModel=birefnet` 传为 `seg_model`；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交该值。这里的 `birefnet` 只是 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。后端在调用 BgFilter 前必须先把带纯色背景 / 绿幕源图写入 OSS；BgFilter 请求失败、返回非成功状态、空图片或非法图片时，以及连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒熔断期，api-server 都先调用阿里云通用抠图，只有阿里云失败才用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作生成的序列帧背景色已与生图统一：前端固定提交 `screenColor=auto`，后端视觉决策出具体 hex 并把源角色图合成到该背景色后再图生视频；抽帧后逐帧优先阿里云通用抠图，失败降级本地 `editor_green_screen`（按选定背景色，而非固定 `#00FF00`）。BiRefNet 手动去背景服务地址为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认 `http://58.87.105.82/remove-background`；BgFilter 可选访问令牌来自 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`，所有令牌都只在服务端注入，前端不持有令牌。api-server 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object，再返回 `imageSrc/objectKey/assetObjectId/taskId`；queue 模式下手动去背景进入 SpacetimeDB 外部生成队列，画布任务侧栏只展示服务器任务阶段，生成中才显示耗时，不显示百分比；有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。
-- 多产物生成以后端项目快照为唯一画布真相：同一任务的原始产物、抠图 / 透明化结果和拆分结果都要先登记为 `editor_project_resource`，再通过一次 `canvasCompletion` 原子写入画布。角色形象、图标 spritesheet 和 UI 素材提取的纯色背景原图不能只留在 OSS；透明后处理结果保持主图层和 `generatedLayerId` 锚点，原图及其它附属产物从主结果右侧开始错开放置。无项目上下文时不创建项目资源或画布图层。
+- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端优先复用当前图层 objectKey；尚未登记的本地图片先上传 OSS，再把 objectKey 交给同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；普通图片、角色、图标图集、UI 设计图及其重绘 / 改造入口必须在比例或清晰度恢复、切换时同步把占位框 `width/height/originalWidth/originalHeight` 更新为目标像素尺寸，生成中不得继续显示默认 1K 框；UI 素材提取的 1K / 2K 图集占位和旧图片修改入口也分别使用本次目标尺寸与源图真实尺寸。待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片解析为已上传的 objectKey 或资源 ID；浏览器临时图片需先上传 OSS；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
+- 图片画布抠图统一使用 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `180000ms`（BgFilter CPU 推理）。手动去除背景面向用户任意图片，仍走登录态同源 BFF `POST /api/editor/images/background-removals` 和外部生成队列；API 在入队前拒绝 `data:` / `blob:` 内联媒体，worker 将稳定引用解析为当前账号已登记的 OSS object key 并校验归属后签发 600 秒 URL，固定提交 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不下载原图，也不提交 `file` 或 `screen_color`。首次请求失败后立即重试 `1` 次，两次都失败则返回最终错误；manual complex 不接入依赖纯色键值的阿里云 / 本地键色降级链，也不改变 flat 链路的熔断状态。手动与标准纯色背景两类模式共用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 和共享 HTTP client；BgFilter token 未配置时只兼容回退读取旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。所有令牌都只在服务端注入，前端不持有令牌。worker 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object；接口只返回 `queueState`，有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。
+- 编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用 BgFilter `background_mode=flat`。角色形象生成、图标 spritesheet 生成、UI 设计图素材提取和角色动作的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt、动作视频实色背景和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。四条 flat 路径同时把默认 `segModel=birefnet` 传为 `seg_model`，并显式传 `cross_check`：角色形象生成和角色动作逐帧去背传 `on`，图标 spritesheet 和 UI 设计图素材提取传 `off`，不依赖 BgFilter 服务端默认值；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交 `seg_model`、`background_mode` 或 `cross_check`。flat 请求首次失败后立即重试 `1` 次；第二次仍失败、返回非成功状态、空图片或非法图片时，以及连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒熔断期，api-server 都先调用阿里云通用抠图，只有阿里云失败才用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作生成的序列帧背景色已与生图统一：后端把源角色图合成到视觉决策出的具体 hex 后再图生视频；抽帧后逐帧进入同一条 `BgFilter（background_mode=flat，cross_check=on）→ 阿里云 → 本地键色` 链路。
+- 角色动作逐帧抠图在 api-server 内复用共享 BgFilter HTTP Client；每一次 HTTP attempt 使用“`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景仍使用基准值。该值是单个请求从发起到响应体读取完成的 timeout，不是整批帧或整项角色动作任务超时；单帧首次失败立即重试 `1` 次并重新签发 OSS URL、重新计时，第二次仍失败才按 object key 进入阿里云/本地降级链，整项任务另受 worker long-job 预算约束。全部 `32 / 40 / 48` 帧按“对应绿幕源图上传 OSS 并释放原帧字节 → 以签名 URL 调 BgFilter/按 object key 降级 → 透明帧落 OSS”连续加入无序在途流水线，允许响应乱序完成并在最终返回前按 `frameIndex` 恢复顺序；任一帧最终失败时仍排空全部已启动请求，整个动作任务失败退款，不发布缺帧动画。
+- 多产物生成以后端项目快照为唯一画布真相：同一任务实际产生的原始产物、抠图 / 透明化结果和拆分结果都要先登记为 `editor_project_resource`，再通过一次 `canvasCompletion` 原子写入画布。角色形象、图标 spritesheet 和 UI 素材提取的纯色背景原图不能只留在 OSS。透明后处理成功时，处理结果保持主图层和 `generatedLayerId` 锚点，三类任务同时把 provider 原图作为第二个图层放在透明主结果右侧，图标和 UI 的实际拆分素材从 provider 原图右侧开始放置。透明背景处理最终失败时，只把已保存的原图作为唯一主图完成占位，不放透明处理图，图标和 UI 不继续拆分。source-only fallback 的前端只消费后端返回的 `project` / `resource` 快照，不按缺失字段自行构造透明图、切片或图层；任务以 `completed + warning` 收口。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。通用 `warning.reason` 是可直接展示的完整原因，并优先于 `sliceWarning`；既有 `sliceWarning.reason` 只表示透明图成功后的自动拆分失败，保留后端原始诊断，inline 前端仅在展示时补充“图集已生成，但自动拆分未完成：”提示，queue worker 则把它归一为 BFF `warning` 字符串后由前端直接展示。无项目上下文时不创建项目资源或画布图层。
 - 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。完整图标图集 `icon-spritesheet` 支持快速编辑，拆分后的单个 `icon` 不提供该入口，前后端必须使用同一素材类型规则。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并在错误红框中显示具体错误文案。
 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。
-- 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。
-- 画布底部工具栏 / 面板 Dock 提供“画布 Agent”入口。点击后打开右侧独立 Agent 对话面板；桌面端为右侧窄面板，移动端占满可用宽度。该面板与素材侧栏、图层侧栏、右上角任务侧栏互斥，打开 Agent 时必须收起其它侧栏，打开其它侧栏或任务侧栏时也必须收起 Agent。Agent 面板不得在当前画布内容下方追加内联内容，也不默认展示大段功能说明文案。
+- 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。进行中阶段只使用外部生成 BFF 返回的 `phaseDetail`：调用或等待图片 / 视频生成服务时显示“正在生成”，进入 BgFilter、逐帧抠图或手动去背景时显示“正在处理”；前端不得按耗时或任务类型猜测阶段。
+- 画布底部工具栏 / 面板 Dock 提供“画布 Agent”入口。点击后打开右侧独立 Agent 对话面板；桌面端为右侧窄面板，移动端占满可用宽度。该面板只与右上角任务侧栏互斥；素材 / 图层侧栏允许与 Agent 同时展开，切换左侧栏不得关闭 Agent。Agent 面板不得在当前画布内容下方追加内联内容，也不默认展示大段功能说明文案。
 - 所有会新建画布生成占位的入口必须先创建 draft，再统一经过 `ImageCanvasGenerationPlacementModel` 计算落点，禁止各入口自行使用当前视口中心裸坐标或原图右侧固定偏移。当前覆盖入口包括 `生成图片`、`生成规范`、`生成角色形象`、`生成图标素材`、`生成视频`、`生成UI设计图` 和 `生成角色动作`。placement 模型的避让对象为所有未隐藏画布图层，以及当前 active / inactive generation dialogs 中仍存在的 placeholder；每个避让矩形按 32px 画布世界坐标间距外扩。候选落点以当前视口世界中心为距离目标，优先选择离视口中心最近且不重叠的占位位置；若中心被占用，会按上下左右和环形候选继续寻找。打开生成面板时必须把避让后的 placeholder 写入 `openCanvasGenerationDialog(...)`，并立即调用 `centerViewportOnPlacement(...)` 居中到新占位中心，保持原 viewport scale 不变；图片快速编辑不属于新建占位入口，提交后覆盖源图。
 
 ## 交互规则
@@ -34,7 +36,7 @@
 - `适合视图` 的正式语义为“显示画布所有可见元素”，不再回到固定 `x/y/scale`。
 - 右上角缩放控件只展示当前缩放百分比；点击后弹出菜单：放大、缩小、显示画布所有元素、缩放至 50%、缩放至 100%、缩放至 200%。缩放百分比以实际画布 `viewport.scale = 0.5` 作为显示 `100%` 的基准，菜单中的 `50% / 100% / 200%` 分别对应实际 `0.25 / 0.5 / 1`，工程持久化保存和读取仍使用用户可见缩放语义。
 - 缩放菜单支持 `Ctrl/Cmd +`、`Ctrl/Cmd -` 和 `Shift + 1`；快捷键只改变 viewport，不修改工程资源。
-- 右上角提供快捷键入口，点击后打开独立快捷键弹窗；画布不常驻展示说明文案。Windows 快捷键覆盖 `Ctrl+Z` / `Ctrl+Shift+Z` 撤销重做、`Ctrl+A/C/V/X/D` 全选 / 复制 / 粘贴 / 剪切 / 复制一份、`Ctrl+0/1/+/-` 视图控制、`V/H/U/G/Shift+V/M` 工具切换、`Alt+1/Alt+2/Alt+M` 面板切换、`Ctrl+]` / `Ctrl+[` / `Ctrl+Shift+]` / `Ctrl+Shift+[` 层级调整、方向键微移 / `Shift+方向键` 大步移动、`Ctrl+Shift+S` 下载画布素材和 `F2` 重命名项目；快捷键只触发对应画布交互，不绕过既有保存 / 生成 / 上传工作流。
+- 右上角提供快捷键入口，点击后打开独立快捷键弹窗；画布不常驻展示说明文案。Windows 快捷键覆盖 `Ctrl+Z` / `Ctrl+Shift+Z` 撤销与恢复、`Ctrl+A/C/V/X/D` 全选 / 复制 / 粘贴 / 剪切 / 复制一份、`Ctrl+0/1/+/-` 视图控制、`V/H/U/G/Shift+V/M` 工具切换、`Alt+1/Alt+2/Alt+M` 面板切换、`Ctrl+]` / `Ctrl+[` / `Ctrl+Shift+]` / `Ctrl+Shift+[` 层级调整、方向键微移 / `Shift+方向键` 大步移动、`Ctrl+Shift+S` 下载画布素材和 `F2` 重命名项目；快捷键只触发对应画布交互，不绕过既有保存 / 生成 / 上传工作流。撤销与恢复的内容保护、提示和验收边界统一以 [`图片画布撤销、恢复范围与操作提示方案`](../【图片画布】撤销范围与操作提示方案-2026-07-17.md) 为准。
 - 背景色控件只修改编辑器工作区底色，不恢复网格线或棋盘格底纹，也不影响图片本体。
 - 吸附阈值以屏幕像素为准，换算到世界坐标后参与拖拽计算；边缘 / 中心线和等距吸附共用同一阈值。拖拽结束后只保存最终图层或生成占位布局，不保存临时参考线。
 - 项目页封面和画布图片图层必须先渲染项目卡、图层外框、标题、尺寸和操作 chrome；图片换签或解码未完成时，只在图片区域显示轻量加载态，不阻塞外框和文字等低成本信息先出现。
@@ -53,11 +55,11 @@
 - `editor_project_resource` 表保存工程画布引用过的资源快照：`resourceId`、`projectId`、`ownerUserId`、OSS / asset object 引用、图片尺寸、来源类型、prompt、actualPrompt、model、provider、taskId、sourceResourceId、`assetKind`、`generationInputs`、创建时间和更新时间。上传素材被拖入画布时会复制为 project resource，图层只引用 resourceId；图片、图标和 UI 素材生成 BFF 在请求携带 `projectId` 时由后端直接创建新 resource，并把 `resourceId` 随生成响应返回给前端。图片生成请求如果同时携带 `canvasCompletion`（生成器 `dialogId`、标题和占位框，或无 dialog 的右侧完成占位），BFF / worker 在生成成功后必须直接读取当前项目布局，优先使用最新 `generation-dialog` 占位框位置；只有当前布局仍存在对应 `generation-dialog` 时才插入轻量结果图层、把生成器标记为 `idle` 并写入 `generatedLayerId`，沿用后端当前 viewport 保存布局，再返回或刷新最新项目快照；前端只应用该快照刷新显示，不把生成完成态作为本地业务真相，也不在项目加载时根据资源行推断完成态。有项目上下文但后端没有返回项目快照时，前端不得本地补结果图层，只保留当前生成器交互状态等待下一次项目刷新。
 - 项目封面图是画布当前视口栅格化后的静态快照资源，不在项目列表页临时重放 `layers + viewport`。前端在项目加载后和防抖保存 layout 时生成 320x240 PNG，走私有 OSS / asset object 上传，再创建 `editor_project_resource`，其中 `assetKind="project-cover-snapshot"`、`sourceType="uploaded"`。`/project` 与 `/creation` 最近项目卡只读取最新封面快照资源渲染；没有封面快照时显示普通项目占位，不回退为实时画布组合。
 - 图片、音频、视频和角色动画帧文件本体继续走 OSS / asset object；浏览器读取私有 generated 对象统一经 `/api/assets/read-url` 换签，签名 URL 可在 session 内复用，但不得作为持久化真相。`/api/assets/read-url` 属于页面展示层高频后台请求，前端统一在 `assetReadUrlService` 内做同 key pending 去重、session 缓存和跨组件节流；UI 设计切片、角色动画帧或大量素材恢复时不得绕过该服务并发换签，否则单页可在同一秒内打满发布入口 `genarrative_api_rps` burst。
-- 登录态上传和生成结果必须先落 OSS / asset object，再向 `editor_project_resource` / `editor_asset` 写入轻量 `imageSrc: "/<objectKey>"`、`objectKey` 和 `assetObjectId`；未登录演示态可以在内存里使用 Data URL 预览，但项目、素材库、项目资源和 `editor_canvas.layers_json` 不得写入 `data:image/*`、`data:video/*`、`data:audio/*` 或 `blob:`。旧数据读取时如果已有 `objectKey`，`imageSrc` 归一成 `/<objectKey>`；没有 `objectKey` 的旧 Data URL 需要走修复上传并回写轻量引用。裁扩在项目上下文中虽然由前端 canvas 本地渲染 PNG，也必须先上传 OSS / asset object 并创建 `editor_project_resource`，再把带正式 `resourceId/objectKey/assetObjectId` 的裁扩图层加入画布；不能先把 `local-resource-*` + Data URL 图层交给项目保存或后续去背景。上传到生成面板参考图槽位的图片必须先创建 `editor_project_resource` 行；没有当前工程 ID 时才创建账号级 `editor_asset` 行，随后把对应 `resourceId` 或 `assetId` 写入参考图临时状态，生成请求仍使用临时状态中的图片源或 `objectKey`。
-- 资源表保存资源和素材级元数据；图层位置、层级、分组选中所需 ID 和 groupId 保存在 `editor_canvas` 的布局 JSON。布局 JSON 是混合数组：普通图层按 `layerId/resourceId` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存，不新增单独表。普通图层的新保存不再把 `assetKind/generationInputs` 写入布局 JSON；刷新时优先从 `editor_project_resource` 恢复，旧布局中的同名字段只作为兼容兜底。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；角色、图标等纯色抠图生成器的前端用户路径不保存或恢复 `screenColor` / `segModel`，同源重绘也不再从 `generationInputs.fields` 恢复 `抠图背景色` 或 `抠图模型`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成器快照中的参考图同样只保存 `resourceId/sourceAssetId` 行引用和展示所需 label，不保存图片 Data URL、signed URL 或 `objectKey`；刷新时用 `editor_project_resource` / `editor_asset` 行恢复临时生成请求所需图片源。生成成功后仍保存该快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。`generationInputs.references` 是用户可见输入快照中的行级索引，只允许保存 `{ title, label, refType, refId }`；生成接口所需的图片 Data URL、signed URL 或 `objectKey` 只存在于提交前的临时参考图状态和请求体字段，不进入资源 / 素材元数据。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。
-- 图片类、生成视频和音频结果除作为 `editor_project_resource` 和画布图层保存外，还要写入账号级 `editor_asset` 素材库；该写入由生成 BFF 在请求携带 `assetFolderId` 时完成。角色、图标图集、UI 提取和角色动作等多产物任务把 provider 原始输出及后处理结果分别入库：所有条目沿用 `character`、`icon-spritesheet`、`character-animation` 等真实类型，provider 原始输出承载任务模型成本，后处理派生产物阶段成本为 0。后台素材查询以最终产物为父行、每个中间产物为可展开的独立子行，分页只计算父任务；手动重拆图集保留独立 `taskId` 用于存储隔离和日志排障，通过私有 provenance 从服务端生成账号素材的 source resource、asset object 或 Object Key 取得可信来源任务，并把它写入 `groupTaskId`，不信任客户端可提交的 resource `taskId/assetKind`；跨项目复用后仍可通过稳定媒体引用找回来源。没有可信来源的新拆分显式归到自身任务，不走历史资源链回溯。每个手动切片同时写入 `groupTaskExpectedAssetCount`，全部切片落库后写独立 cohort 完成事实；后台 read model 只让同一根任务的一个已完成拆分批次并入原图集父项，用户后来删除单片不会让批次脱组，部分失败批次和后续重复拆分批次按各自真实任务分页，避免残缺批次抢占根任务、单组无限增长或素材丢失。历史行在项目资源仍存在时兼容回溯，删除项目资源前只固化直接受影响行的真实来源字段，有界展示 ID 不反写数据库。`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画布图片、改图、图标素材、UI 素材提取、角色动作、视频、音效和背景音乐生成都先返回 `queueState`，前端轮询 `/api/runtime/external-generation/jobs/{jobId}` 到完成后重新读取项目快照；`inline` 或无项目上下文时才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。生成请求失败、inline 完成或 queue 任务终态完成 / 失败后，右上角泥点 chip 必须通过 `/profile/dashboard` 回读余额，不做本地乐观扣减。生成视频会单独抽取首帧封面写入 `thumbnailSrc`，素材栏和拖回画布时沿用该封面作为 poster。
+- 登录态上传和生成结果必须先落 OSS / asset object，再向 `editor_project_resource` / `editor_asset` 写入轻量 `imageSrc: "/<objectKey>"`、`objectKey` 和 `assetObjectId`；未登录演示态可以在内存里使用 Data URL 预览，但项目、素材库、项目资源和 `editor_canvas.layers_json` 不得写入 `data:image/*`、`data:video/*`、`data:audio/*` 或 `blob:`。旧数据读取时如果已有 `objectKey`，`imageSrc` 归一成 `/<objectKey>`；没有 `objectKey` 的旧 Data URL 需要走修复上传并回写轻量引用。裁扩在项目上下文中虽然由前端 canvas 本地渲染 PNG，也必须先上传 OSS / asset object 并创建 `editor_project_resource`，再把带正式 `resourceId/objectKey/assetObjectId` 的裁扩图层加入画布；不能先把 `local-resource-*` + Data URL 图层交给项目保存或后续去背景。上传到生成面板参考图槽位的图片必须先创建 `editor_project_resource` 行；没有当前工程 ID 时才创建账号级 `editor_asset` 行，随后把对应 `resourceId` 或 `assetId` 写入参考图临时状态；生成请求提交前必须把临时状态解析成 `objectKey`、项目资源 ID 或素材 ID，未登记的本地图片和普通图片路径先上传 OSS，不能直接提交 Data URL、Blob URL 或临时图片源。
+- 资源表保存资源和素材级元数据；图层位置、层级、分组选中所需 ID 和 groupId 保存在 `editor_canvas` 的布局 JSON。布局 JSON 是混合数组：普通图层按 `layerId/resourceId` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存，不新增单独表。普通图层的新保存不再把 `assetKind/generationInputs` 写入布局 JSON；刷新时优先从 `editor_project_resource` 恢复，旧布局中的同名字段只作为兼容兜底。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；角色、图标等纯色抠图生成器的前端用户路径不保存或恢复 `screenColor` / `segModel`，同源重绘也不再从 `generationInputs.fields` 恢复 `抠图背景色` 或 `抠图模型`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成器快照中的参考图同样只保存 `resourceId/sourceAssetId` 行引用和展示所需 label，不保存图片 Data URL、signed URL 或 `objectKey`；刷新时用 `editor_project_resource` / `editor_asset` 行恢复临时生成请求所需图片源。生成成功后仍保存该快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。`generationInputs.references` 是用户可见输入快照中的行级索引，只允许保存 `{ title, label, refType, refId }`；生成接口只接收提交前临时状态解析出的 `objectKey` 或资源 ID；Data URL、Blob URL 和 signed URL 不进入请求体，不进入资源 / 素材元数据。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。
+- 图片类、生成视频和音频结果除作为 `editor_project_resource` 和画布图层保存外，还要写入账号级 `editor_asset` 素材库；该写入由生成 BFF 在请求携带 `assetFolderId` 时完成。角色、图标图集、UI 提取和角色动作等多产物任务把实际产生的 provider 原始输出及后处理结果分别入库：所有条目沿用 `character`、`icon-spritesheet`、`character-animation` 等真实类型，provider 原始输出承载任务模型成本，后处理派生产物阶段成本为 0。后台素材查询以最终产物为父行、每个中间产物为可展开的独立子行，分页只计算父任务；手动重拆图集保留独立 `taskId` 用于存储隔离和日志排障，通过私有 provenance 从服务端生成账号素材的 source resource、asset object 或 Object Key 取得可信来源任务，并把它写入 `groupTaskId`，不信任客户端可提交的 resource `taskId/assetKind`；跨项目复用后仍可通过稳定媒体引用找回来源。没有可信来源的新拆分显式归到自身任务，不走历史资源链回溯。每个手动切片同时写入 `groupTaskExpectedAssetCount`，全部切片落库后写独立 cohort 完成事实；后台 read model 只让同一根任务的一个已完成拆分批次并入原图集父项，用户后来删除单片不会让批次脱组，部分失败批次和后续重复拆分批次按各自真实任务分页，避免残缺批次抢占根任务、单组无限增长或素材丢失。历史行在项目资源仍存在时兼容回溯，删除项目资源前只固化直接受影响行的真实来源字段，有界展示 ID 不反写数据库。`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画布图片、改图、图标素材、UI 素材提取、角色动作、视频、音效和背景音乐生成都先返回 `queueState`，前端轮询 `/api/runtime/external-generation/jobs/{jobId}` 到完成后重新读取项目快照；`inline` 或无项目上下文时才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。生成请求失败、inline 完成或 queue 任务终态完成 / 失败后，右上角泥点 chip 必须通过 `/profile/dashboard` 回读余额，不做本地乐观扣减。生成视频会单独抽取首帧封面写入 `thumbnailSrc`，素材栏和拖回画布时沿用该封面作为 poster。
 - 生成面板不展示资源名称输入，默认使用原有自动编号；提示词输入保持统一可见边框。内部命名契约仍使用可选 `assetLabel`，最大 80 字符并在提交时 trim；历史状态或内部调用携带非空名称时，同一个名称必须贯穿 `assetLabel`、`canvasCompletion.title`、项目资源、账号素材和本地兜底图层，刷新后不得退回模板名。图标图集与角色动作请求同样兼容该字段，中间原图使用主名称加固定后缀，拆分素材继续按素材描述命名。
-- 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和 SSE 最终写回由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。
+- 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和工具结果回填由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。
 - Agent 消息附件只允许引用当前工程画布资源或账号素材库图片，来源类型为 `canvas_resource` / `library_asset`，最多 9 张。附件请求可携带展示用 `imageSrc/thumbnailSrc/objectKey/width/height/label`，但持久化真相仍以后端校验后的 resource / asset 行和 OSS 对象为准；不得把 Data URL、signed URL 或 blob URL 当作会话长期事实。
 - 前端不直接订阅 SpacetimeDB，统一通过 api-server 的 `/api/editor/projects*` BFF 读写。
 - 工程刷新恢复可先应用 session 级轻量项目快照缓存，让画布和素材 chrome 尽快显示；缓存快照必须排除 `data:*` / `blob:` 内联媒体，且在后端项目快照返回前不得触发自动保存。后端快照回来后覆盖本地缓存显示并恢复正常保存队列。
@@ -77,7 +79,7 @@
 - `POST /api/editor/projects/{projectId}/agent-conversations`：在当前工程下创建画布 Agent 会话；可选传入标题，默认标题为“新对话”。
 - `GET /api/editor/agent-conversations/{conversationId}`：读取指定画布 Agent 会话详情，返回会话摘要和 OSS 消息正文中的消息列表。
 - `DELETE /api/editor/agent-conversations/{conversationId}`：软删除指定画布 Agent 会话，并返回删除后的会话摘要。
-- `POST /api/editor/agent-conversations/{conversationId}/messages/stream`：发送画布 Agent 消息并返回 JSON SSE。请求体包含 `clientMessageId`、`text` 和可选 `attachments`；文本与附件不可同时为空。SSE 事件名固定为 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`。生成结果中的图片通过后端写入 project resource / 账号素材后返回轻量快照，前端只消费返回的资源引用并刷新 / 聚焦画布。工具失败时也必须保留失败 generation record，不得只返回一次性错误。
+- `POST /api/editor/agent-conversations/{conversationId}/messages`：发送画布 Agent 消息并返回普通 JSON `EditorAgentMessageResponse`。请求体包含 `clientMessageId`、`text` 和可选 `attachments`；文本与附件不可同时为空，同一会话重复 `clientMessageId` 必须幂等返回或拒绝重复追加。响应包含权威会话摘要、`deltaMessages` 和可选 `errorMessage`。LLM / 规划失败写入 `role=system`、正文以 `ERROR ` 开头的 OSS 消息并放入 `deltaMessages`，不再重复设置 `errorMessage`；前端隐藏前缀后显示红色错误气泡。工具失败继续保存工具状态和错误信息。
 - `GET /api/editor/assets/library`：读取当前账号的素材文件夹和素材。首次读取时自动创建“项目素材”默认文件夹。
 - `POST /api/editor/assets/folders`：新建素材文件夹。
 - `PATCH /api/editor/assets/folders/{folderId}`：重命名、折叠 / 展开素材文件夹。
@@ -85,11 +87,11 @@
 - `POST /api/editor/assets`：批量或单个创建账号级素材，登录态上传必须写入 OSS / asset object 引用和 `/<objectKey>` 轻量路径，不允许把 Data URL / signed URL 写入素材库。
 - `PATCH /api/editor/assets/{assetId}`：重命名素材或移动素材到文件夹。
 - `DELETE /api/editor/assets/{assetId}`：删除素材。已放入画布的 project resource 不被级联删除，避免旧画布丢图。
-- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片；普通图片的 provider 回图先留在内存，尺寸变换成功后只上传变换结果，变换失败则只上传 provider 原图，主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`，生成成功后 api-server 先保存带纯色背景源图，再调用 BgFilter 并传入 `screen_color=<screenColor>`、`seg_model=<segModel>` 生成透明 PNG。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits；`nanobanana2` 的 `512 / 1024 / 2K` 是标量清晰度档位，后端保留 provider 输出几何尺寸，不按 `宽x高` 解析。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成成功后创建 project resource / 账号素材并在响应中返回 resource / asset 快照。
-- `POST /api/editor/images/background-removals`：接收当前图片源，校验登录态后由 api-server 解析为图片文件并转发到 BiRefNet 去背景服务；请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`，有 `canvasCompletion` 时完成后按生成占位写入结果图层，否则沿用旧的目标图层替换路径；响应返回 `imageSrc`、`objectKey`、`assetObjectId`、`width`、`height`、`taskId`、`elapsedMs`、`provider` 和可选 `project` 快照。服务地址由 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL` 配置，令牌只在服务端通过 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 注入。
-- `POST /api/editor/icon-spritesheets/generations`：按图标规范图和素材描述数组生成 spritesheet，生成成功后 api-server 先保存带纯色背景 spritesheet 源图，再调用 BgFilter 生成透明 spritesheet。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置中对应生图模型的尺寸档位（如 `nanobanana2` 的 `0.5K / 1K / 2K` 或 `gpt-image-2` 的 `1K / 2K`），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。后端保存透明 spritesheet project resource / 账号素材，并随响应返回对应快照。
-- `POST /api/editor/ui-designs/assets/extractions`：前端把红色框选轮廓绘入本地临时图后，先将该图上传 OSS 并确认 asset object，再以返回的 `objectKey` 作为参考图入队；Data URL / Blob URL 只允许停留在上传前的浏览器临时态。接口固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet，生成成功后 api-server 先保存带纯色背景 spritesheet 源图，再调用 BgFilter 生成透明 spritesheet，并按连通域自动拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，后端保存 spritesheet / 拆分素材并返回对应 resource / asset 快照；前端必须把 spritesheet 原图与拆分素材都加入画布。
-- `POST /api/editor/images/edits`：按提示词和当前图片的已登记 `objectKey` / `resourceId` 调用 VectorEngine edits，返回新的生成图片元数据；图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。画布快速编辑必须把源图精确 `originalWidth x originalHeight` 作为业务目标 `size` 提交，不能重新映射为近似比例或 1K / 2K 预设；api-server 在 VectorEngine provider 边界把目标尺寸和所有 multipart 参考图临时补齐到 16 的倍数，回图后在内存恢复业务目标尺寸，成功时只上传恢复结果，失败时只上传 provider 原图。无论是否发生尺寸恢复都只创建一个 project resource / 账号素材，不显示重复“原始输出”。16 对齐尺寸不得泄漏到正常完成的最终响应、资源或图层 Resolution；变换失败降级时以实际 provider 原图尺寸为准。本地红框标记图必须先上传再提交 objectKey；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。
+- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片。带 `model / aspectRatio / imageSize` 的用户生成必须把当前 K 档对应的真实像素直接传给 provider，前端占位与该请求尺寸使用同一映射；不得先请求固定 1K 再放大为 2K。普通图片的 provider 回图先留在内存，尺寸变换成功后只上传变换结果，变换失败则只上传 provider 原图，主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`；api-server 先保存带纯色背景源图，再调用 BgFilter 并传入 `screen_color=<screenColor>`、`seg_model=<segModel>`，透明处理成功时生成透明 PNG，最终失败时按前述多产物降级规则以原图主结果和通用 `warning` 收口。角色、图标图集和 UI 图集的透明处理正常成功但返回尺寸与 provider 原图不同时，只重采样透明图的 alpha 蒙版并应用回 provider 原图的原始分辨率 RGB，不放大低分辨率后处理成品。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`，并继续按固定交付像素处理。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits；`nanobanana2` 的 `512 / 1024 / 2K` 是标量清晰度档位，后端保留 provider 输出几何尺寸，不按 `宽x高` 解析。从既有图层重新打开生成器且没有仍存活的对话框快照时，前端按该图层真实 `originalWidth / originalHeight` 恢复比例和清晰度，不得回落到新建面板的 1K 默认值。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成完成后在响应中返回实际产物的 project / resource / asset 快照。
+- `POST /api/editor/images/background-removals`：接收当前图片的 `objectKey`、`resourceId` 或 `assetId` 候选引用，登录态和稳定引用入口校验通过后创建外部生成任务，响应只返回 `queueState`。worker 才负责引用解析和归属校验，不下载原图；调用共享 BgFilter HTTP client 前签发 600 秒 OSS URL，multipart 固定为 `image_url + background_mode=complex + seg_model=birefnet + cross_check=off`，不包含 `file` 或 `screen_color`，首次失败立即重试 `1` 次，两次都失败返回最终错误。请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`，有 `canvasCompletion` 时完成后按生成占位写入结果图层，否则沿用旧的目标图层替换路径。令牌只在服务端通过 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 注入，未配置时兼容回退旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。
+- `POST /api/editor/icon-spritesheets/generations`：按图标规范图和素材描述数组生成 spritesheet；api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet 并尝试拆分。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置中对应生图模型的尺寸档位（如 `nanobanana2` 的 `0.5K / 1K / 2K` 或 `gpt-image-2` 的 `1K / 2K`），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但拆分失败时保留整张透明图并返回 `sliceWarning`。响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`。
+- `POST /api/editor/ui-designs/assets/extractions`：前端把红色框选轮廓绘入本地临时图后，先将该图上传 OSS 并确认 asset object，再以返回的 `objectKey` 作为参考图入队；Data URL / Blob URL 只允许停留在上传前的浏览器临时态。接口固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet；api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet 并按连通域尝试拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但拆分失败时保留整张透明图并返回 `sliceWarning`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`；前端按后端快照落画布，不补造缺失产物。
+- `POST /api/editor/images/edits`：按提示词和当前图片的已登记 `objectKey` / `resourceId` 修改图片，返回新的生成图片元数据；图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`，并随用户当前选择提交 `model / aspectRatio / imageSize / size`。api-server 必须先归一模型再选择 VectorEngine 协议：`nanobanana2` 调用 `/v1beta/models/{model}:generateContent` 并把原图作为 `inline_data`、比例和清晰度写入 `generationConfig.imageConfig`；`gpt-image-2` 调用 `/v1/images/edits` multipart。gpt-image-2 路径在 provider 边界把目标尺寸和所有 multipart 参考图临时补齐到 16 的倍数，回图后在内存恢复业务目标尺寸；nanobanana2 路径保留 provider 按比例和清晰度返回的几何尺寸。成功时只上传最终结果，尺寸恢复失败时只上传 provider 原图；无论是否发生尺寸恢复都只创建一个 project resource / 账号素材，不显示重复“原始输出”。16 对齐尺寸不得泄漏到正常完成的最终响应、资源或图层 Resolution；变换失败降级时以实际 provider 原图尺寸为准。本地红框标记图必须先上传再提交 objectKey；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。
 - `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音、默认联网搜索标记和泥点价格生成视频。前端可选模型为 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，默认 `seedance2.0-fast`；后端必须将 `seedance2.0-fast` 映射到 `doubao-seedance-2-0-fast-260128`，将 `seedance2.0` 映射到 `doubao-seedance-2-0-260128`，两者不得混用。后端允许 6 类比例、4 到 15 秒整数、`480p / 720p / 1080p`，并拒绝 `seedance2.0-fast + 1080p`；`sound=on/off` 映射 Ark `generate_audio=true/false`。后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `asset` 快照，基础响应返回 `videoSrc`、尺寸、prompt、model、provider、taskId、durationSeconds、resolution 和 `priceMudPoints`。
 - `POST /api/editor/audios/sound-effects/generations` 与 `POST /api/editor/audios/background-music/generations`：按音效 / 背景音乐参数生成音频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `resource` / `asset` 快照，基础响应返回 `audioSrc`、prompt、model、provider、taskId、duration、歌词和 `priceMudPoints`。
 
@@ -101,8 +103,7 @@
 - 示例素材可继续复用 `public/creation-type-references/` 下的站内图片；用户上传和后续生成资源必须通过资源记录表达。
 - 不把 hover、dragging、临时吸附线、Space 临时抓手等瞬时 UI 状态写入后端。
 - 不在 UI 中加入大段功能说明，编辑器界面只展示必要的工具、素材和状态信息。
-- 画布 Agent 前端分层固定为：`editorAgentClient.ts` 负责 BFF 请求、鉴权错误和 stream 发起；`editorAgentSse.ts` 只负责 SSE JSON 事件归一；`useEditorAgentConversation.ts` 负责会话列表、当前会话、消息流、阶段和停止状态；`EditorAgentConversationPanelView.tsx` 只负责右侧面板展示与交互。
-- `editorAgentSse.ts` 必须复用 `src/services/sseStream.ts` 的 `readSseJsonStream`，不得复制 SSE reader、`TextDecoder`、事件边界扫描或 UTF-8 flush 逻辑；该文件不得承接 fetch、鉴权、会话聚合、画布聚焦或 UI 错误文案。
+- 画布 Agent 前端分层固定为：`editorAgentClient.ts` 负责普通 JSON BFF 请求、鉴权和错误映射；`useEditorAgentConversation.ts` 负责会话列表、当前会话、消息请求等待态、工具任务状态和客户端取消等待；`EditorAgentConversationPanelView.tsx` 只负责右侧面板展示与交互。画布 Agent 不新增私有 SSE parser。
 - 不复用或改写 `CreativeImageInputPanel` 的单图资产编辑语义；`/editor/canvas` 是独立图片画布工程的画布入口。
 
 ## 验收用例
@@ -113,8 +114,10 @@
 - 默认选择模式；底部工具栏能切换工具；中键拖拽和 Space 临时抓手都能平移画布。
 - 拖拽图片或生成占位框接近其它图片 / 生成占位框边缘、中心或等距分布位置时显示吸附线，并保存吸附后的最终布局。
 - 生成图片点击后显示画布内 `Image Generator` 占位框和跟随占位框的生成输入框，生成失败保留占位和输入状态，生成成功后在占位位置创建真实图层，并让输入框继续跟随该生成图。
+- 选择 `1K / 2K` 或切换比例后，占位框在待生成和生成中阶段都必须立即显示对应目标像素尺寸；从普通图片、角色、图标图集或 UI 设计图再次改造时同样适用，完成落图前后不得从默认 1K 框跳变为 2K 成品。
 - 生成中的占位图聚焦后支持键盘 `Delete` / `Backspace` 删除，不新增可见删除按钮；删除后对应异步回写必须按生成器 ID 判空并丢弃，不能把已删除素材重新落回画布。音乐 / 音频生成占位和已生成音频图层同样必须支持键盘删除。
 - 画布常用快捷键必须与右上角快捷键弹窗一致；新增快捷键时应同步更新 `ImageCanvasShortcutModel`、快捷键 hook 单测和本方案。输入框、文本域和 contenteditable 聚焦时不得触发画布编辑快捷键。
+- 撤销或恢复画布布局时不得覆盖同 ID 生成对象当前的任务生命周期、提示词、参考图和结果；上传持久化延迟回填内部资源 ID 不得把安全移动误判为素材替换。生成结果必须在加入画布前写入生成历史，自动适合视图不得覆盖这条栈顶记录。
 - 生成器快照刷新后必须恢复；待生成、生成中、失败和已生成后跟随成品图层的生成器都不能因为刷新丢失输入、参数、参考图或占位框位置。宣发素材生成器刷新后必须继续显示正确的卡片类型、游戏名、分类、描述和已绑定参考图。
 - 画布多选语义必须同时覆盖普通图层和仍显示占位框的生成器对象：Shift 点选或框选可把生成器加入当前选择；拖动任一已选图层或生成器时，所有已选普通图层和生成器占位框同步移动；删除 / Backspace / Delete 作用于完整选择集合，移除所有已选图层和生成器对象。生成器对象在选择集合中使用稳定 `generation-dialog:<id>` 目标 ID，不把生成器伪装成普通图层，也不新增后端表。
 - 生成类入口打开画布内面板时，底部 AI 工具栏必须保持可见；`生成规范`、角色 / 图标规范来源、角色常规参考图来源这类轻量菜单通过页面级 fixed portal 渲染，不能留在底部工具栏或参考图横向滚动容器内部，避免被局部 `overflow` 裁切。角色规范和常规参考图来源菜单必须向上弹出；常规参考图点击后先选择“从画布中选择”或“上传图片”，从画布取图时只绑定参考图，不触发普通画布图层选中、聚焦、面板隐藏或拖拽逻辑，绑定后退出画布选择状态。所有生成面板参考图槽位统一为方形图标组件；角色规范槽位只显示规范 logo 和 `角色规范` 四字，绑定来源标题只保留给可访问名称、悬浮 title 和图片信息。已有参考图槽位只有在 hover / focus 时显示右上角 `×`，点击后只解绑对应参考图。角色形象生成面板每次成功绑定角色规范后，在当前编辑器生命周期内缓存为上一张角色规范；再次新建角色形象时自动带入该缓存。图标素材和 UI 设计图面板每次成功绑定图标规范后，同样缓存为上一张图标规范；再次新建需要图标规范的素材时自动带入该缓存。生成规范菜单里的图标规范对象自身只把首行参考图作为可选参考，不要求必须先绑定图标规范。
@@ -122,21 +125,21 @@
 - 快速编辑面板底部只显示模型选择和 `修改` 按钮；打开时视口聚焦必须预留底部面板空间，面板位于素材下方，不得遮挡原素材，且素材在当前屏幕内完整可见。快速编辑请求只把原图或红框序号标注图作为 `sourceImageSrc` 直接提交，信息面板输入快照只展示用户填写的快速编辑提示词。
 - 点击生成、生成规范、生成角色形象或生成图标素材后创建的占位图可继续保留；点击画布空白区域让当前图片或占位图失焦时，关闭当前生成面板并移除图片选中样式，但不删除占位图本身。
 - 生成资源显示元数据按钮，元数据窗口展示来源、生成输入快照、model、task、Resolution 和 OSS 引用；生成输入快照只包含用户面板输入和参考图行引用，不包含后端拼接 Prompt，不再展示独立 Size 字段，也不渲染参考图 Data URL 缩略图。
-- 点击底部 Dock 的“画布 Agent”后，右侧独立 Agent 面板打开；素材 / 图层侧栏和任务侧栏被收起。再次点击或点击面板关闭按钮后收起 Agent。打开素材 / 图层侧栏或任务侧栏时，Agent 面板同步关闭。
+- 点击底部 Dock 的“画布 Agent”后，右侧独立 Agent 面板打开，任务侧栏被收起；素材 / 图层侧栏保持当前状态并可继续切换。再次点击或点击面板关闭按钮后收起 Agent；打开任务侧栏时 Agent 面板同步关闭。
 - Agent 面板能读取当前工程会话列表；无历史会话时发送第一条消息会先创建“新对话”。支持新建会话、切换会话和删除当前会话；删除必须通过独立确认弹窗完成，不能在面板下方追加确认内容。
 - Agent 输入支持文本消息、附件消息和纯附件消息；附件选择弹窗可在“画布 / 素材库”之间切换，只展示图片类资源，最多选择 9 张。
-- 发送消息后，面板展示用户消息、Agent 阶段状态和 SSE 增量回复；`stage/message_delta/tool_started/tool_completed/generation_result/error/done` 都能被正确渲染。流式响应中点击“停止”会中断当前请求，并把仍在 streaming / generating 的消息标记为停止态。
-- Agent 返回生成结果缩略图后，点击缩略图应优先聚焦当前画布中已有 `resourceId` 对应图层；如果当前内存布局尚未包含该资源，则重新读取工程快照，应用后再聚焦新图层。对话入口触发生成时不创建“即将生成”画布占位；生成中状态只显示在消息流，生成完成后通过后端 `canvasCompletion` 落新图层。工具失败时消息内必须保留失败 generation record 和错误气泡，不能只弹一次性 toast。
+- 发送消息后，面板先展示本地用户消息和请求等待态，再应用普通 JSON 响应中的 `deltaMessages`；客户端取消等待只终止本次 transport 等待，不把已经确认入队的外部生成任务改成停止态。
+- Agent 工具任务完成并懒回填后，消息内缩略图只作纯预览，不显示名称也不点击聚焦图层；前端同时重新读取工程快照和素材库。对话入口触发生成时不创建“即将生成”画布占位，生成完成后由后端 `canvasCompletion` 落新图层。规划或工具失败时消息内必须保留可回读的失败状态和错误气泡，不能只弹一次性 toast 或返回瞬时 `errorMessage`。
 - 画布 Agent 会话刷新后能从后端恢复会话标题、消息、附件和生成记录；前端不得根据本地临时状态伪造会话持久化结果。
-- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`，由 api-server 代理远端 BiRefNet 服务并持久化结果；有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词；生成的透明 spritesheet 原图和拆分后的独立素材都作为画布图层保留。
+- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`，由 api-server 通过共享 BgFilter `background_mode=complex` 链路去背景并持久化结果；有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。
 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。
-- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；只有尚未登记的浏览器本地图片才先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。
+- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；尚未登记且没有稳定引用的浏览器本地图片或普通 public 图片路径都必须先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。
 - 快速编辑不保留额外参考图入口；点击修改时只把原图或红框序号标注图作为 `/api/editor/images/edits` 的 `sourceImageSrc` 提交给后端。
 - 素材文件夹可以新建、折叠、重命名和删除；删除普通文件夹后，其素材移动到“项目素材”。普通上传默认落入“上传素材”文件夹；素材库缺少该文件夹时，前端在首次普通上传前创建一次并复用，拖到指定文件夹或点击指定文件夹上传时仍进入目标文件夹。
 - 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入“上传素材”并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入“上传素材”并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；上传视频同样在创建素材和图层前读取视频 metadata 宽高，保证单层下载或 ZIP 导出的真实视频文件重新导入后仍按文件自身尺寸入画布；仅在无法解析尺寸时才使用对应媒体兜底尺寸。
 - 音频 / 视频素材卡和画布媒体图层必须提供稳定的非文字视觉预览：优先使用 `thumbnailSrc` / 视频 `poster`，没有真实首帧或音频封面时使用由媒体类型、素材名和地址派生的确定性视觉底图。视频图层使用原生 `<video controls preload="metadata" playsInline>` 播放，外层图层仍承接选择和拖拽语义；音频图层播放前继续通过 `/api/assets/read-url` 换签。画布素材导出按 `mediaType` 保留真实媒体格式：图片进入 `images/`，音频 / 视频进入 `media/`，文件扩展名从响应 MIME、`objectKey` 或源 URL 推断，不得把音频 / 视频导出成 PNG。
 - 画布素材 ZIP 的 `metadata.json` 只保存前端信息弹窗和导出文件列表可见的展示快照：项目标题、导出时间、图层标题、文件路径、类型、生成输入、模型显示名、Task 短 ID、Object 显示值、Resolution / 时长和导出错误。导出的生成输入只保留用户实际填写或选择的内容；系统默认兜底提示词、固定工作流提示词、内置图标描述、UI 提取素材固定提示词等内置提示词即使存在于历史 `generationInputs`，也不得写入导出元数据。不得把 `projectId`、`layerId`、`resourceId`、`sourceAssetId`、`sourceResourceId`、原始 `prompt` / `actualPrompt` / `provider` 或画布坐标、锁定、隐藏等布局状态写入导出元数据；Object 字段仅沿用信息弹窗当前可见值。
-- `生成角色动作` 的完成结果按序列帧素材处理：图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。下载和 ZIP 导出必须因此得到序列帧 ZIP / frames 目录，不能回退为预览视频或首帧 PNG；后端抽帧后先保存带绿幕帧源图，再走绿幕透明化后处理并落盘透明帧素材。
+- `生成角色动作` 的完成结果按序列帧素材处理：图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。下载和 ZIP 导出必须因此得到序列帧 ZIP / frames 目录，不能回退为预览视频或首帧 PNG；后端抽帧后逐帧保存带绿幕源图，上传时消费并释放原帧字节，再用该对象的 600 秒 OSS URL 完成透明化并落盘透明帧素材。
 - 素材面板支持按素材名、文件夹名、生成信息、模型、任务和媒体类型搜索，并支持选择模式框选，一次选中多个素材，并可批量移动或删除上传素材。
 - 图层面板支持按图层名、生成信息、模型、任务和媒体类型搜索；支持选择多个图层后创建图层组，组名和 groupId 随画布布局保存。
 - 小地图支持拖拽视口框，拖动时画布 viewport 跟随移动；`pointermove` 更新必须通过 `requestAnimationFrame` 合帧，结束拖拽时 flush 最后一帧，避免高频 pointermove 直接压垮 React 渲染和项目持久化链路。
diff --git a/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md
index fd05d28d6..4a633479f 100644
--- a/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md
+++ b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md
@@ -75,9 +75,9 @@
 ## 第七阶段模块
 
 - `useCanvasHistory.ts`
-  - 承载画布历史栈：快照创建、快照恢复、撤销、重做、历史栈长度限制和 `canUndo` / `canRedo` 派生状态。
+  - 承载画布历史栈：快照创建、安全快照恢复、撤销、恢复、历史栈长度限制和 `canUndo` / `canRedo` 派生状态。
   - 主视图继续负责在具体用户动作前调用 `captureCanvasHistory`，并通过 hook 注入恢复快照后需要清理的 hover、元数据、框选、吸附、右键菜单和平移拖拽状态。
-  - 该 hook 有独立测试覆盖图层、视口、active / archived 生成对话框和选中态的撤销 / 重做恢复，避免后续把 history 逻辑继续埋回主视图。
+  - 该 hook 有独立测试覆盖图层、视口、active / archived 生成对话框和选中态的撤销 / 恢复，并保证布局历史不会把同 ID 生成对象的当前任务状态恢复成旧快照，避免后续把 history 逻辑继续埋回主视图。
 
 ## 第八阶段模块
 
@@ -118,7 +118,7 @@
 - `ImageCanvasGenerationLayerModel.ts`
   - 承载生成结果落画布的纯数据规则：普通生图、修改图片、快速编辑和图标素材批量结果如何生成图层 id、临时 resourceId、标题、位置、原始分辨率尺寸、zIndex、source metadata、`assetKind`、源图关联和 `generationInputs`。
   - 主视图继续负责生成提交 API、生成对象 active / archived 状态、资源持久化、图层选择、侧栏切换、对话框收起和适合视图等副作用，避免把多个画布生成对象的生命周期拆成浅 wrapper。
-  - 该模块用独立单测锁定“图片显示尺寸跟随原始 Resolution”“生成占位框只作为定位参考”“图标素材沿用当前行宽换行规则”和“快速编辑保留源图分组 / 类型”的规则。
+  - 该模块用独立单测锁定“图片显示尺寸跟随原始 Resolution”“生成占位框的位置和目标像素尺寸共同作为完成落图契约”“图标素材沿用当前行宽换行规则”和“快速编辑保留源图分组 / 类型”的规则。
 
 ## 第十三阶段模块
 
@@ -181,9 +181,9 @@
 ## 第二十一阶段模块
 
 - `useImageCanvasKeyboardShortcuts.ts`
-  - 承载图片画布全局键盘快捷键：Windows 下支持 Ctrl+Z / Ctrl+Shift+Z 撤销重做、Ctrl+A/C/V/X/D 全选 / 复制 / 粘贴 / 剪切 / 复制一份、Ctrl+0/1/+/- 视图控制、V/H/U/G/Shift+V/M 工具切换、Alt+1/Alt+2/Alt+M 面板切换、Ctrl+] / Ctrl+[ / Ctrl+Shift+] / Ctrl+Shift+[ 层级调整、方向键微移、Backspace / Delete 删除选中元素、Escape 关闭临时面板并取消选择，以及 Space 临时抓手。
+  - 承载图片画布全局键盘快捷键：Windows 下支持 Ctrl+Z / Ctrl+Shift+Z 撤销与恢复、Ctrl+A/C/V/X/D 全选 / 复制 / 粘贴 / 剪切 / 复制一份、Ctrl+0/1/+/- 视图控制、V/H/U/G/Shift+V/M 工具切换、Alt+1/Alt+2/Alt+M 面板切换、Ctrl+] / Ctrl+[ / Ctrl+Shift+] / Ctrl+Shift+[ 层级调整、方向键微移、Backspace / Delete 删除选中元素、Escape 关闭临时面板并取消选择，以及 Space 临时抓手。
   - 主视图继续保留各工作流状态和具体副作用，例如图层删除、生成对话框、规格菜单、快速编辑面板和 chrome 面板状态；快捷键 hook 只接收 ref、setter 与回调，不直接读写素材库、路由或 API。
-  - 该 hook 用独立单测覆盖输入框忽略快捷键、撤销重做、编辑命令、视图 / 层级命令、工具 / 面板命令、方向键移动、选中元素删除、生成占位删除、Escape 保留生成中面板、Space 临时抓手和 Shift 状态；主视图 DOM 测试继续覆盖真实编辑器里的 Backspace、Escape、Space 和 undo / redo 集成路径。
+  - 该 hook 用独立单测覆盖输入框忽略快捷键、撤销与恢复、编辑命令、视图 / 层级命令、工具 / 面板命令、方向键移动、选中元素删除、生成占位删除、Escape 保留生成中面板、Space 临时抓手和 Shift 状态；主视图 DOM 测试继续覆盖真实编辑器里的 Backspace、Escape、Space 和 undo / redo 集成路径。
 - `ImageCanvasShortcutDialogView.tsx` / `ImageCanvasShortcutModel.ts`
   - 承载右上角快捷键入口打开后的独立弹窗和 Windows 快捷键表；快捷键文案、键帽和“新增”状态集中在模型中维护，避免 UI 表格和 hook 行为漂移。
 
@@ -250,4 +250,4 @@
 - `npm run typecheck`
 - `npm run check:encoding`
 - `git diff --check`
-- 浏览器回归 `/editor/canvas`：确认登录弹窗、素材上传、背景设置面板、底部工具栏、Space 临时抓手、撤销 / 重做和画布基础渲染仍正常。
+- 浏览器回归 `/editor/canvas`：确认登录弹窗、素材上传、背景设置面板、底部工具栏、Space 临时抓手、撤销 / 恢复、安全阻止提示和画布基础渲染仍正常。
diff --git a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md
index 6908adc2c..d0cf8c26f 100644
--- a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md
+++ b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md
@@ -1,6 +1,6 @@
 # 外部生成 Worker 化方案
 
-更新时间：`2026-06-24`
+更新时间：`2026-07-15`
 
 ## 背景
 
@@ -13,8 +13,8 @@
 - 多个 worker 进程通过 SpacetimeDB 任务表抢占任务，依赖 lease 超时恢复，支持按进程数和单进程并发动态缩扩容。
 - 本地或小流量同步排查可显式启用 `inline` 模式，由 HTTP handler 复用同一 worker executor 同步执行并返回 `completed`；该模式不创建队列任务，也不具备 worker 横向扩容能力。
 - SpacetimeDB reducer / procedure 只做任务状态流转，不做网络、文件系统或外部 provider I/O。
-- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
-- 第一版外部生成队列粒度固定为“单个用户动作对应单个 job”。例如草稿编译、结果页单槽重生、图集重生都各自入一个 job；job 内部可以串行或并行调用 provider、OSS、SpacetimeDB 写回，但不再拆成“提示词 / 生图 / 切图 / 去背景 / 持久化 / 回写”等阶段 job。阶段进度只作为 `request_payload_json` / 业务 session 的展示状态，不作为队列调度单位。
+- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、手动去背景、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
+- 第一版外部生成队列粒度固定为“单个用户动作对应单个 job”。例如草稿编译、结果页单槽重生、图集重生都各自入一个 job；job 内部可以串行或并行调用 provider、OSS、SpacetimeDB 写回，但不再拆成“提示词 / 生图 / 切图 / 去背景 / 持久化 / 回写”等阶段 job。用户可见执行阶段通过现有任务行及摘要投影的轻量 `phase` 保存，不作为队列调度单位，也不写回大 payload。
 - 不调用外部图片 / 音频 / LLM provider 的动作继续 inline 执行，不为了统一排队而进入 `external_generation_job`。
 
 ## Module 与 Interface
@@ -24,12 +24,16 @@
 - `enqueue_external_generation_job_and_return`：按 `dedupe_key` 幂等创建或返回现有任务。
 - `claim_external_generation_jobs_and_return`：worker 按 `worker_id`、`limit` 和 lease 时长抢占 `pending` 或 lease 过期的 `running` 任务，返回本次 claim 的 `lease_token`。
 - `renew_external_generation_job_lease_and_return`：worker 长任务执行期间按 `worker_id + lease_token` 续租，防止外部生成超过单次 lease 后被重复领取。
+- `update_external_generation_job_phase_and_return`：worker 按 `job_id + worker_id + lease_token` 把当前执行阶段更新为 `generating` 或 `processing`，并同步现有摘要投影；不新增阶段任务或阶段表。procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`，调用方不解析错误文案；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试 `1` 次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。
 - `complete_external_generation_job_and_return`：worker 成功后按 `worker_id + lease_token` 写入 `result_payload_json`，任务进入 `completed`。
 - `fail_external_generation_job_and_return`：worker 失败后按 `worker_id + lease_token` 回写错误，并按 `max_attempts` 决定回到 `pending` 重试或进入 `failed`。
-- `list_external_generation_jobs_and_return`：按当前账号读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格和完成提示确认状态。
-- `acknowledge_external_generation_jobs_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入 `notification_acknowledged_at` 并追加审计事件。
+- `list_external_generation_job_summaries_and_return`：按当前账号从轻量摘要投影读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格、执行阶段和完成提示确认状态。
+- `acknowledge_external_generation_job_summaries_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入摘要投影的 `notification_acknowledged_at` 并追加审计事件。
 - `get_external_generation_queue_stats_and_return`：controller 读取队列积压、运行中任务和过期 lease 数量，用于计算 worker 目标实例数；该 procedure 只读 `external_generation_job`，不直接操作 systemd。
-- `get_external_generation_job_and_return`：按 `job_id` 读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
+- `get_external_generation_job_summary_and_return`：按 `job_id` 从轻量摘要投影读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
+- `get_external_generation_job_result_and_return`：仅供后端内部回填异步编辑器 Agent 工具调用；按 `job_id + owner_user_id` 返回 `status`、`last_error_message` 和已持久化的 `result_payload_json`，不返回请求 payload、lease 或其它 worker 字段。该 procedure 不替代摘要状态读取接口，也不经 BFF 暴露给前端。
+
+不带 `summary / summaries` 的旧 `get / list / acknowledge_external_generation_job*` procedure 只保留给受控内部兼容，不是 BFF 正式读取入口。
 
 这个 Module 的 **Seam** 在 SpacetimeDB procedure + `spacetime-client` facade；`api-server` HTTP role 和 worker role 都只依赖这个 Interface。外部 provider、OSS、计费补偿、玩法草稿回写仍留在 `api-server` worker implementation 内，不进入 SpacetimeDB reducer。
 
@@ -38,11 +42,12 @@
 队列状态对前端只通过 `api-server` BFF 暴露，不允许前端直接查询 SpacetimeDB private table：
 
 - `GET /api/runtime/external-generation/queue-overview`：当前账号队列概览，用于兼容旧展示和轻量状态读取。返回 pending、running、未确认终态数量和更新时间。
-- `GET /api/runtime/external-generation/jobs?limit=20&includeAcknowledgedTerminal=false`：当前账号正式生成任务列表，用于 `我的` 页签任务列表和完成 / 失败提示。返回每个任务的 job id、kind、source、可展示 label、状态、进度、错误、`priceMudPoints`、`refundLedgerId`、`notificationAcknowledgedAt` 和时间戳。默认不返回已确认的终态任务；需要拆分活跃和完成列表时可追加 `statuses=running,queued` 或 `statuses=completed,failed`，BFF 仍只返回当前账号任务。
+- `GET /api/runtime/external-generation/jobs?limit=20&includeAcknowledgedTerminal=false`：当前账号正式生成任务列表，用于 `我的` 页签任务列表和完成 / 失败提示。返回每个任务的 job id、kind、source、可展示 label、状态、进度、错误、可选 `warning`、`priceMudPoints`、`refundLedgerId`、`notificationAcknowledgedAt` 和时间戳。默认不返回已确认的终态任务；需要拆分活跃和完成列表时可追加 `statuses=running,queued` 或 `statuses=completed,failed`，BFF 仍只返回当前账号任务。
+- 任务被 claim 后默认处于 `generating`，BFF 显示“正在生成”；真实进入 BgFilter、逐帧抠图或手动去背景时切换为 `processing`，BFF 显示“正在处理”。旧任务 `phase=None` 按 `generating` 兼容，前端不得按耗时或 job kind 推断阶段。
 - `POST /api/runtime/external-generation/jobs/acknowledge`：生成完成 / 失败提示展示后由前端后台调用，BFF 只传当前账号 job ids，后端只确认属于当前账号且已终态的任务。
-- `GET /api/runtime/external-generation/jobs/{jobId}`：单 job 状态，用于生成页轮询某次动作。返回 `jobId`、`jobKind`、`sourceModule`、`sourceEntityId`、`status`、`attempt`、`maxAttempts`、`createdAt`、`startedAt`、`completedAt`、`updatedAt`、可展示的 `requestLabel`、可展示的 `lastErrorMessage`、以及业务侧下一次轮询所需的 source 标识。
+- `GET /api/runtime/external-generation/jobs/{jobId}`：单 job 状态，用于生成页轮询某次动作。返回 `operationId`（即任务 ID）、`status`、`phaseLabel`、`phaseDetail`、`progress`、`error`、`updatedAtMicros`，以及可选、可直接展示的 `warning` 完整文案。生成页轮询只依赖状态、阶段、进度、错误和警告；`jobKind`、source 和完整时间信息继续由任务列表接口或业务快照提供。`attempt` / `maxAttempts` 属于 worker 调度事实，不向该前端契约暴露；若未来需要面向用户展示，必须单独完成产品、契约和摘要投影设计。
 
-BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍以 `external_generation_job` 为准，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。
+BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；worker 调度、lease、执行和计费事实仍以 `external_generation_job` 为准，用户可见任务列表、单任务状态、执行阶段和通知确认的正式读取事实源为 `external_generation_job_summary`，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。
 
 ## 任务表
 
@@ -52,7 +57,7 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
 | --- | --- |
 | `job_id` | 主键，`extgen-` 前缀 UUID |
 | `dedupe_key` | 唯一键，建议为 `play/action/session/scope` |
-| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation`、`editor_background_music_generation` |
+| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation`、`editor_background_music_generation` |
 | `owner_user_id` | 触发用户 |
 | `source_module` | 玩法或能力名，例如 `puzzle` |
 | `source_entity_id` | session/profile/work 等作用域 |
@@ -70,6 +75,9 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
 | `price_mud_points` | 后端计算的本任务价格，用于任务列表展示和排障 |
 | `refund_ledger_id` | 失败退款产生的钱包退款流水 ID，便于从任务追到退款记录 |
 | `notification_acknowledged_at` | 用户已确认完成 / 失败提示的时间，未确认终态任务下次登录继续集中弹出 |
+| `phase` | 尾部可选字段；`null / generating / processing`，claim 时写 `generating`，进入正式后处理时写 `processing` |
+
+用户正式读取使用私有轻量投影 `external_generation_job_summary`。该表同步保存 owner、来源、状态、`phase`、价格、有限错误/告警摘要、通知确认和时间字段，不复制 request/result payload、worker lease 或 dedupe 内部字段；enqueue、claim、renew、phase update、complete、fail 与 acknowledge 都必须维护对应投影语义。
 
 新增私有审计表 `external_generation_job_event`，记录 `enqueued/claimed/lease_renewed/completed/failed/acknowledged` 等事件。事件表只追加状态转换事实，不作为当前状态源；排障时先看 `external_generation_job` 当前状态，再按 `job_id` 追 `external_generation_job_event` 时间线。
 
@@ -113,7 +121,7 @@ worker 配置：
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_CONCURRENCY`：单进程并发领取/执行数量。
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS`：空队列轮询间隔。
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS`：任务 lease 时长，默认 `600`；worker 会按约三分之一 lease、最长 30 秒的间隔续租。该值应覆盖一次心跳网络抖动窗口，不需要大于完整外部生成链路耗时。
-- `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS`：普通外部生成 job 的执行预算，默认 `900`。超过预算后当前 worker 停止当前尝试、写入失败 / 重试状态并释放 worker 槽位，避免任务长期保持 `running_active`；若业务 future 已在计费操作内被取消，计费层会按外部生成 job id 异步补偿退款。
+- `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS`：普通外部生成 job 的执行预算，默认 `900`。超过预算后当前 worker 停止续租并释放 worker 槽位，但不取消已启动的业务 future，也不主动写入失败 / 重试状态；在途执行交由 lease fencing 仲裁：写回在租约有效期内到达则照常完成，否则被拒绝，租约过期后任务可被重新认领，attempt 耗尽时由认领事务原子标记失败并结算退款。
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS`：视频、角色动作等长耗时 job 的执行预算，默认 `1800`。
 
 controller 配置：
@@ -126,7 +134,7 @@ controller 配置：
 - `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_SERVICE_TEMPLATE`：systemd worker 模板，默认 `genarrative-external-generation-worker@{}.service`。
 - `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_DRY_RUN`：只记录决策不执行 systemctl，默认 `false`。
 
-动态缩扩容方式：生产默认由 `deploy/systemd/genarrative-external-generation-controller.service` 启动 `GENARRATIVE_PROCESS_ROLE=external-generation-controller`，controller 读取 `get_external_generation_queue_stats_and_return` 后对 `genarrative-external-generation-worker@N.service` 执行精确 `systemctl start/stop`；无需改变 HTTP 进程数。controller 只操作 `@1..@MAX` 中的缺口或最高编号多余实例，保留 `@1` 作为保底 worker。缩容或发布重启 worker 时，进程收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务会在 lease 过期后被其它 worker 重新领取。若 worker 内业务 future 长时间无返回，执行预算到期后会结束当前尝试并释放槽位；如果当时 SpacetimeDB 写回失败，任务也会按较短 lease 进入可重领窗口，避免无进展续租无限延长。容器链路已有独立 `external-generation-worker` compose service；扩 worker 必须扩这个 worker service，不能只扩 `api-server` HTTP service。
+动态缩扩容方式：生产默认由 `deploy/systemd/genarrative-external-generation-controller.service` 启动 `GENARRATIVE_PROCESS_ROLE=external-generation-controller`，controller 读取 `get_external_generation_queue_stats_and_return` 后对 `genarrative-external-generation-worker@N.service` 执行精确 `systemctl start/stop`；无需改变 HTTP 进程数。controller 只操作 `@1..@MAX` 中的缺口或最高编号多余实例，保留 `@1` 作为保底 worker。缩容或发布重启 worker 时，进程收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务会在 lease 过期后被其它 worker 重新领取。若 worker 内业务 future 长时间无返回，执行预算到期后 worker 会停止续租并释放槽位，在途 future 继续运行至租约仲裁窗口；有效租约内的写回仍可完成，租约过期后才会由其它 worker 重新认领，避免客户端取消与服务端写回竞态。容器链路已有独立 `external-generation-worker` compose service；扩 worker 必须扩这个 worker service，不能只扩 `api-server` HTTP service。
 
 ## 已接入的拼图纵切
 
@@ -178,6 +186,7 @@ controller 配置：
 
 - `editor_image_generation`：普通图片、生成规范、角色形象、UI 设计图、宣发素材和图片快速编辑。
 - `editor_image_edit`：图片编辑 / 修改结果。
+- `editor_background_removal`：手动去除任意图片背景，worker 使用 BgFilter complex 模式、首次失败后重试 `1` 次，并把执行阶段标记为 `processing`。
 - `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。
 - `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。
 - `editor_character_animation_generation`：角色动作视频和帧素材生成。
@@ -186,6 +195,12 @@ controller 配置：
 
 画板结果的业务真相仍是 `editor_project_resource`、账号级 `editor_asset` 和 `editor_canvas.layers_json`。请求携带 `projectId + canvasCompletion` 时，worker 成功后读取当前项目 layout，用最新 generation dialog placeholder 或无 dialog 完成占位写入结果图层，并保存项目快照；前端轮询单 job 到 completed 后重新读取项目快照，不从队列 payload 或本地临时响应重建正式图层。生成器已被删除时，worker 只保留生成出的资源 / 素材记录，不把结果重新塞回画布。
 
+角色形象、图标 spritesheet 和 UI 素材提取在 provider 原图已经持久化后，如果透明背景处理最终失败，只用原图完成 `canvasCompletion`，不创建或回填透明处理图，图标和 UI 也不继续拆分，任务保持 `completed`。这个 source-only 降级只包住透明背景处理的最终失败；phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。
+
+透明背景处理正常成功时，角色形象、图标 spritesheet 和 UI 素材提取的画布都同时放透明主结果与 provider 原图：透明主结果保持生成器 `generatedLayerId` 主锚点，provider 原图作为第二个图层放在其右侧；图标和 UI 实际拆分出的业务素材从 provider 原图右侧继续排列。
+
+inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：通用 `warning` 优先并原样保留完整 `reason`；只有不存在通用 `warning` 时，才给 `sliceWarning.reason` 添加“图集已生成，但自动拆分未完成：”前缀。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。
+
 ## 验收
 
 基础检查：
diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
index 417a7b583..c29d747f5 100644
--- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
@@ -74,6 +74,8 @@ src/
 
 根级原生壳检查还会反查两端单端配置检查的依赖版本门禁：移动壳必须继续锁定 Expo SDK、React Native、WebView、EAS CLI 和 `package-lock.json` 实际解析版本；桌面壳必须继续锁定 Tauri CLI、Cargo manifest、`Cargo.lock` 解析版本和直接依赖关系。升级 Expo / React Native / Tauri 不能只改 `package.json` 或 `Cargo.toml`，必须同时更新单端配置检查、锁文件和本文档里的宿主能力假设。
 
+桌面壳的 `permissions/autogenerated/` 由 Tauri `build.rs` 生成且保持 gitignored。`npm run check:native-shells` 必须先运行桌面 Rust 测试生成权限清单，再执行桌面配置检查，最后执行 release build smoke；不能让干净检出因为静态检查早于生成步骤而失败，也不能把生成权限文件提交进仓库。
+
 结构门禁按完整相对路径反查文档和目录：微信桥接层为 `miniprogram/host-bridge/dispatch.js`、`miniprogram/host-bridge/payment.js`、`miniprogram/host-bridge/protocol.js`、`miniprogram/host-bridge/shareGrid.js`、`miniprogram/host-bridge/subscribeMessage.js`、`miniprogram/host-bridge/webView.js`；微信 shell 层为 `miniprogram/shell/payment.js`、`miniprogram/shell/shareGrid.js`、`miniprogram/shell/subscribeMessage.js`、`miniprogram/shell/webView.js`；微信页面包装层为 `miniprogram/pages/share-grid/index.js`、`miniprogram/pages/share-grid/index.json`、`miniprogram/pages/share-grid/index.wxml`、`miniprogram/pages/share-grid/index.wxss`、`miniprogram/pages/subscribe-message/index.js`、`miniprogram/pages/subscribe-message/index.json`、`miniprogram/pages/subscribe-message/index.wxml`、`miniprogram/pages/subscribe-message/index.wxss`、`miniprogram/pages/web-view/index.js`、`miniprogram/pages/web-view/index.json`、`miniprogram/pages/web-view/index.wxml`、`miniprogram/pages/web-view/index.wxss`、`miniprogram/pages/wechat-pay/index.js`、`miniprogram/pages/wechat-pay/index.json`、`miniprogram/pages/wechat-pay/index.wxml`、`miniprogram/pages/wechat-pay/index.wxss`；移动源码根为 `apps/mobile-shell/src/env.d.ts`；移动桥接层为 `apps/mobile-shell/src/host-bridge/appearance.test.ts`、`apps/mobile-shell/src/host-bridge/appearance.ts`、`apps/mobile-shell/src/host-bridge/badge.test.ts`、`apps/mobile-shell/src/host-bridge/badge.ts`、`apps/mobile-shell/src/host-bridge/bridge.ts`、`apps/mobile-shell/src/host-bridge/capabilities.test.ts`、`apps/mobile-shell/src/host-bridge/capabilities.ts`、`apps/mobile-shell/src/host-bridge/clipboard.test.ts`、`apps/mobile-shell/src/host-bridge/clipboard.ts`、`apps/mobile-shell/src/host-bridge/dispatch.ts`、`apps/mobile-shell/src/host-bridge/filePayloads.test.ts`、`apps/mobile-shell/src/host-bridge/filePayloads.ts`、`apps/mobile-shell/src/host-bridge/files.test.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/src/host-bridge/haptics.test.ts`、`apps/mobile-shell/src/host-bridge/haptics.ts`、`apps/mobile-shell/src/host-bridge/navigation.test.ts`、`apps/mobile-shell/src/host-bridge/navigation.ts`、`apps/mobile-shell/src/host-bridge/network.test.ts`、`apps/mobile-shell/src/host-bridge/network.ts`、`apps/mobile-shell/src/host-bridge/notifications.test.ts`、`apps/mobile-shell/src/host-bridge/notifications.ts`、`apps/mobile-shell/src/host-bridge/protocol.test.ts`、`apps/mobile-shell/src/host-bridge/protocol.ts`、`apps/mobile-shell/src/host-bridge/runtime.test.ts`、`apps/mobile-shell/src/host-bridge/runtime.ts`、`apps/mobile-shell/src/host-bridge/scanner.test.ts`、`apps/mobile-shell/src/host-bridge/scanner.ts`、`apps/mobile-shell/src/host-bridge/share.test.ts`、`apps/mobile-shell/src/host-bridge/share.ts`；移动 shell 层为 `apps/mobile-shell/src/shell/QrScannerOverlay.test.tsx`、`apps/mobile-shell/src/shell/QrScannerOverlay.tsx`、`apps/mobile-shell/src/shell/ShellApp.tsx`、`apps/mobile-shell/src/shell/deepLink.ts`、`apps/mobile-shell/src/shell/lifecycle.ts`、`apps/mobile-shell/src/shell/loadFailure.ts`、`apps/mobile-shell/src/shell/navigation.ts`、`apps/mobile-shell/src/shell/network.ts`、`apps/mobile-shell/src/shell/runtime.ts`、`apps/mobile-shell/src/shell/safeArea.ts`、`apps/mobile-shell/src/shell/url.ts`、`apps/mobile-shell/src/shell/webViewGlobals.d.ts`、`apps/mobile-shell/src/shell/webViewHistory.ts`、`apps/mobile-shell/src/shell/webViewPolicy.ts`；桌面入口为 `apps/desktop-shell/src-tauri/src/app.rs`、`apps/desktop-shell/src-tauri/src/main.rs`；桌面桥接层为 `apps/desktop-shell/src-tauri/src/host_bridge/appearance.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/badge.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/capabilities.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/clipboard.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/file_payloads.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/files.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/mod.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/navigation.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/network.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/runtime.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/share.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/title.rs`；桌面 shell 层为 `apps/desktop-shell/src-tauri/src/shell/deep_link.rs`、`apps/desktop-shell/src-tauri/src/shell/events.rs`、`apps/desktop-shell/src-tauri/src/shell/file_drop.rs`、`apps/desktop-shell/src-tauri/src/shell/lifecycle.rs`、`apps/desktop-shell/src-tauri/src/shell/mod.rs`、`apps/desktop-shell/src-tauri/src/shell/navigation.rs`、`apps/desktop-shell/src-tauri/src/shell/network.rs`、`apps/desktop-shell/src-tauri/src/shell/runtime.rs`、`apps/desktop-shell/src-tauri/src/shell/tray.rs`、`apps/desktop-shell/src-tauri/src/shell/url.rs`、`apps/desktop-shell/src-tauri/src/shell/webview.rs`、`apps/desktop-shell/src-tauri/src/shell/window_state.rs`。这些目录不得新增未登记子目录或生产入口；移动端和桌面端单端配置检查同样会拒绝未登记生产模块。
 
 ## HostBridge 消息协议
diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
index 8c95934f9..fd08f0a67 100644
--- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
@@ -83,7 +83,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗
 - `setHostAppBadgeCount()`：原生 App 宿主的受控应用角标入口。H5 只传 `0` 到共享契约 `HOST_BRIDGE_BADGE_COUNT_MAX` 之间的整数，`0` 表示清除角标；Expo 移动壳只在 iOS 声明 `app.setBadgeCount`，并通过 Expo Notifications 查询 / 请求 `allowBadge` 权限，再以 `Notifications.setBadgeCountAsync(count)` 的返回值作为成功依据；权限拒绝、权限状态不可读、系统返回 `false` 或原生 API 异常都必须返回明确失败，Android 不声明该能力，且请求实际到达 Android 壳时必须返回 `unsupported_capability`，不得返回成功；Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回明确错误，由 H5 视作失败并继续主流程。当前 H5 只把“可见作品架里未读的草稿生成完成更新”同步为角标数，同一个草稿有多个恢复 ID 时只计 1，已读、失败、生成中和不可见草稿不计入；宿主不支持或设置失败不改变 H5 红点、作品架或后端状态。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `app.setBadgeCount` 请求，保证未读计数模型和原生壳消费链路同时被门禁覆盖。
 - `reloadHostWebView()`：原生 App 宿主的受控 WebView 刷新入口。H5 只能请求刷新当前承载主站的宿主 WebView；Expo 移动壳调用当前 `react-native-webview` 的 `reload()`，Tauri 桌面壳调用主 `WebviewWindow.reload()`。该能力不接受 payload，不开放任意 URL 导航、脚本执行、Tauri guest API 或 RN WebView ref；成功只表示宿主已发起刷新，刷新后当前 H5 上下文会卸载。`AuthGate` 在登录态从未登录变为已登录、或从已登录变为未登录时优先调用该能力刷新当前容器；宿主未声明、返回失败或不可用时再回退浏览器 `window.location.reload()`。
 - `openHostExternalUrl()`：原生 App 宿主的受控外链入口。H5 中需要离开主站的外链在 `native_app` 下先通过 `app.openExternalUrl` 请求宿主系统浏览器打开；只允许 `http:`、`https:`、`mailto:`、`tel:`，相对路径会先归一化到当前站点绝对 URL，再通过共享契约 `normalizeHostBridgeExternalUrlPayload()` 清洗为 `{ url }` 载荷。Expo 移动壳消费该共享 payload normalizer，Tauri 桌面壳在 Rust 侧用 URL parser 镜像同一协议清单。宿主不可用或拒绝时回退浏览器外链行为，普通浏览器和小程序保持原有 `<a>` 语义。H5 支付链接和微信 OAuth 登录授权 URL 也走该入口：原生壳未声明真实 `payment.request` / `auth.requestLogin` 前，微信 H5 支付 URL 和后端返回的微信登录授权 URL 优先交给宿主系统浏览器，宿主未处理时才回退当前 WebView 跳转；不得把 H5 支付或网页登录伪装成已完成的原生支付 / 原生登录。
-- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录和内置独立 H5 体验入口等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://www.genarrative.world` 同源 H5 route 并在主窗口内跳转。H5 facade 在 `native_app` 下发送 `navigation.openNativePage` 前先拒绝空值、控制字符、协议相对 URL、外域绝对 URL 和非 `http:` / `https:` 协议目标，避免把明显不安全的跳转请求交给原生壳；同源绝对 URL、`/path` 和保留给桌面壳兼容的相对 route 继续由宿主二次归一并补写宿主上下文。微信小程序分支仍按小程序页面 URL 语义走 `wx.miniProgram.navigateTo`，不套原生 App 同源 H5 预校验。平台首页的儿童动作热身 Demo 入口在 `native_app` 且宿主声明 `navigation.openNativePage` 时必须优先走该 facade 跳转 `/child-motion-demo`，普通浏览器、小程序和未声明能力的裁剪壳才回退浏览器跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。
+- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录和仍在维护的同源 H5 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://www.genarrative.world` 同源 H5 route 并在主窗口内跳转。H5 facade 在 `native_app` 下发送 `navigation.openNativePage` 前先拒绝空值、控制字符、协议相对 URL、外域绝对 URL 和非 `http:` / `https:` 协议目标，避免把明显不安全的跳转请求交给原生壳；同源绝对 URL、`/path` 和保留给桌面壳兼容的相对 route 继续由宿主二次归一并补写宿主上下文。微信小程序分支仍按小程序页面 URL 语义走 `wx.miniProgram.navigateTo`，不套原生 App 同源 H5 预校验。旧创作入口和儿童动作 Demo 已退出宿主壳强制验收，不再作为 `check:native-shells` 的专属路由契约；真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。
 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。H5 facade 发起请求前先通过共享契约 `normalizeHostBridgeExportTextPayload()` 预校验文件名、文本内容、可选 MIME 和 5 MiB 上限；Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，可选 MIME 只能来自共享契约 `HOST_BRIDGE_TEXT_MIME_TYPES`，未传时默认为 `text/plain`，非文本 MIME 必须拒绝，不能借文本导出通道伪装成图片、音频或二进制文件；Expo 与 Tauri 壳仍必须二次校验真实文本字节数和 MIME。成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。创作 Agent 工作台在 `native_app` 且声明该能力时提供会话 Markdown 导出入口，导出内容只来自当前 H5 已持有的会话标题、摘要、进度、锚点、消息、流式回复和输入草稿，并在 H5 侧先按同一 5 MiB 上限做 UTF-8 byte 校验；普通浏览器、小程序和未声明能力的裁剪壳不展示该入口。
 - `importHostTextFile()`：原生 App 宿主的受控文本导入入口。Expo 移动壳通过 Expo DocumentPicker 打开系统文档选择器，Tauri 桌面壳通过系统文件选择框读取用户选择的文本文件；两端都只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 或对应扩展名，单次不超过 5 MiB，成功只返回通过共享 `normalizeHostBridgeImportFileName()` 清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力；宿主必须在读取文本内容前拿到可信 byte count 并完成上限校验，移动壳在 picker 缺少 `size` 时改用 Expo `File.size`，仍拿不到可信大小时直接拒绝导入；H5 facade 收到结果后继续通过共享契约 `normalizeHostBridgeImportTextResult()` 复核文件名、MIME、文本内容和字节数，非法或超界结果归为 `false`；用户取消时由 H5 facade 归为 `false`。创作 Agent 工作台在 `native_app` 且声明该能力时优先调用宿主文本导入，并把结果转换成现有浏览器 `File` 后继续复用后端 `/api/runtime/creation-agent/document-inputs/parse` 解析链路；普通浏览器、小程序和未声明能力的裁剪壳继续使用原文件输入。
 - `importHostDocumentFile()`：原生 App 宿主的受控文档导入入口。Expo 移动壳通过 Expo DocumentPicker，Tauri 桌面壳通过系统文件选择框读取用户选择的文档副本；两端都只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document` 或对应 `.txt` / `.md` / `.markdown` / `.csv` / `.json` / `.docx` 扩展名，单次不超过 5 MiB。成功只返回通过共享 `normalizeHostBridgeImportFileName()` 清洗后的文件名、MIME、base64 内容和字节数，不暴露设备本地 URI、本机绝对路径或通用文件系统能力；宿主必须在读取 base64 前拿到可信 byte count 并完成上限校验，移动壳在 picker 缺少 `size` 时改用 Expo `File.size`，仍拿不到可信大小时直接拒绝导入；H5 facade 收到结果后继续通过共享契约 `normalizeHostBridgeImportDocumentResult()` 复核文件名、MIME、base64 和字节数。创作 Agent 工作台在 `native_app` 且声明该能力时优先调用宿主文档导入，把返回 base64 转换成现有浏览器 `File` 后继续调用 `/api/runtime/creation-agent/document-inputs/parse`；旧壳只声明 `file.importText` 时才回退到文本导入，普通浏览器、小程序和未声明能力的裁剪壳继续使用原文件输入。该能力不在前端解析 DOCX，也不绕过后端文档解析、大小校验或错误口径；移动壳配置检查必须强制文档 MIME 清单、5 MiB 上限和导入文件名清洗函数来自共享 HostBridge 契约。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index 696e8ac0a..e1e614870 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -1,6 +1,6 @@
 # server-rs 与 SpacetimeDB 数据契约
 
-更新时间：`2026-07-03`
+更新时间：`2026-07-17`
 
 ## 后端主线
 
@@ -16,7 +16,7 @@ server-rs + Axum + SpacetimeDB
 
 `server-rs/Cargo.toml` 是 workspace 事实源。默认构建成员为 `crates/api-server`；第三方依赖版本和 workspace 内 crate path 统一放在 `[workspace.dependencies]`。
 
-SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.6.0`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `server-rs/Cargo.toml` 锁定版本对齐，避免 BSATN / procedure result 反序列化错配。遇到版本不匹配时，不继续沿着业务超时排查，先把 CLI / standalone 直接升级到锁定版本并重启后再重试。
+SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.6.1`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `server-rs/Cargo.toml` 锁定版本对齐，避免 BSATN / procedure result 反序列化错配。遇到版本不匹配时，不继续沿着业务超时排查，先把 CLI / standalone 直接升级到锁定版本并重启后再重试。2.6.1 还修复了 procedure context 中调用者 `Identity` / `ConnectionId` 丢失问题，因此依赖调用者身份的 procedure 不得继续运行在 2.6.0 standalone 上。
 
 当前主要 crate：
 
@@ -78,12 +78,15 @@ npm run check:server-rs-ddd
 
 ### 图片画布 Agent 对话
 
-- `/api/editor/projects/{projectId}/agent-conversations` 负责当前工程会话列表和新建；`/api/editor/agent-conversations/{conversationId}` 负责详情读取和软删；`/api/editor/agent-conversations/{conversationId}/messages/stream` 负责发送消息并返回 SSE。
+- `/api/editor/projects/{projectId}/agent-conversations` 负责当前工程会话列表和新建；`/api/editor/agent-conversations/{conversationId}` 负责详情读取、终态工具消息懒回填和软删；`POST /api/editor/agent-conversations/{conversationId}/messages` 负责发送消息并返回普通 JSON `EditorAgentMessageResponse`，画布 Agent 不提供 `/messages/stream` SSE 路由。消息请求必须携带最长 128 字符的 `clientMessageId`；前端对该 POST 显式启用 1 次瞬时 transport 重试，并复用同一个序列化 body、`clientMessageId` 和 `x-request-id`。同一会话在锁内按该键幂等，重复键同内容返回已有回合或从已保存用户消息继续，异内容返回 `409`。数字 `EditorAgentMessage.id` 仍只作为工具确认 / 取消的后端消息定位符，不能复用为客户端幂等键。
 - `module-editor-agent` 只承载纯领域校验：标题派生、附件上限、消息输入规则和会话软删访问规则；不直接依赖 Axum、SpacetimeDB、OSS、LLM 或 Tokio。
 - `spacetime-module` 的 `editor_agent_conversation` 只保存元数据；创建、列表、读取、更新时间和软删通过 `create_editor_agent_conversation_and_return`、`list_editor_agent_conversations_and_return`、`get_editor_agent_conversation_and_return`、`touch_editor_agent_conversation_and_return`、`delete_editor_agent_conversation_and_return` procedure 完成，`api-server` 只能经 `spacetime-client` facade 访问。
-- 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、SSE 事件持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。
+- 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、消息与工具结果持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。LLM / 规划失败必须写入 `role=system`、正文以 `ERROR ` 开头的消息，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏前缀并显示红色错误气泡，后端仍把该 system 消息注入后续 LLM memory，使 Agent 能读取失败上下文。工具失败同样必须形成可回读记录，不能只返回瞬时错误。
 - 对话附件只允许引用当前工程 `editor_project_resource` 或当前账号 `editor_asset` 的图片；前端可提交展示用 `imageSrc` / `thumbnailSrc`，后端必须按 `resourceId` / `assetId` 重新归一、校验 owner / project 和 `objectKey`，再给 LLM 或生成工具使用。
 - 画布 Agent 工具复用既有编辑器图片生成 / 修改 / 图标 spritesheet BFF，并继续使用后端模型定价和 `execute_billable_asset_operation_with_cost`；前端不提交 `priceMudPoints`。
+- `/messages/{messageId}/confirm` 与 `/messages/{messageId}/cancel` 只返回成功确认；前端成功后立即重新读取整个会话，以会话详情中的权威消息状态和 `externalJobId` 驱动气泡展示与任务轮询。
+- 会话详情的终态懒回填必须在单次 GET 和同一 conversation lock 内完成有界重试：任务结果读取、completed payload 解析或工具 formatter 首次失败后最多重试 3 次，每次等待 100ms 并重新读取主任务。任务读取失败或 completed 任务暂缺 `result_payload_json` 时，本次重试耗尽后仍保留 OSS 工具消息的 `not_completed + externalJobId`，由下次会话读取继续 reconcile；JSON 损坏、结果结构不兼容或 formatter 失败等确定性致命错误在重试耗尽后原子写为 `failed`，保存“重试 3 次后仍失败”的最后错误，避免永久循环。
+- 画布 Agent 是“正式任务 payload 不进入通用用户 read model”规则的窄例外消费者：`GET /api/editor/agent-conversations/{conversationId}` 只按会话中已有的 `externalJobId` 定向读取主任务，完成后由对应工具 formatter 从 `result_payload_json` 提取并归一有界的图片 / 视频 / 音频引用，写入 OSS 工具消息后返回。前端仍不得通过通用任务列表 / 状态接口读取或解析 `request_payload_json` / `result_payload_json`；OSS 轻量媒体引用只是会话展示与后续 Agent 上下文，不替代 `editor_project_resource`、`editor_asset`、`editor_canvas.layers_json` 或 `external_generation_job` 的业务真相。
 
 ### 创作 / 游玩统一流程主干
 
@@ -175,7 +178,8 @@ npm run check:server-rs-ddd
 7. 面向公开列表的只读投影优先做成 public view / public 读模型表，并由 `api-server` 的 `spacetime-client` 长期订阅后读本地 cache。跨玩法公开作品统一主读模型是 `public_work_gallery_entry` 和 `public_work_detail_entry`；公开作品资产读取授权投影是 `public_work_asset_read_grant`；各玩法既有 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 保留为 source view 和兼容路径。短期不把作品列表整体交给浏览器前端直接订阅；不要让 HTTP 列表接口每次请求都调用 procedure 重新组装全量列表。需要请求时间窗口的轻量统计可订阅 `public_work_play_daily_stat` 后在 `api-server` 本地聚合，需要写入副作用的详情、点赞、游玩记录仍走玩法 procedure / reducer。前端不得直接订阅 `puzzle_work_profile`、`custom_world_profile` 等领域源表，也不得自己做 join、聚合或权限逻辑。首屏、排序、字段归一、权限降级和 HTTP fallback 由 `api-server` BFF 维持。
 8. 多列索引按 SpacetimeDB 绑定生成的元组参数直接传入，例如 `.filter((source_type, profile_id, played_day))`；前缀查询只传前缀元组，例如 `.filter((scope_kind, scope_id.as_str()))`。不要为了绕过类型问题退回整表遍历。
 9. procedure result 必须返回 typed snapshot / typed value。`spacetime-client` mapper 不得再通过 `row_json/session_json/work_json/items_json/run_json/event_json/feedback_json: Option<String>` 做跨层 JSON 字符串传输，也不得在 mapper 里反序列化旧 `*JsonRecord` 兼容结构。业务内部持久化字段如 `profile_payload_json`、`levels_json` 等不属于 procedure result 载荷例外，仍按各自表契约处理。
-10. 修改后运行：
+10. procedure 需要按调用者 identity 鉴权时，必须先从外层 `ProcedureContext::sender()` 捕获 caller，再把 caller 显式传入 `try_with_tx` 闭包内的事务函数。SpacetimeDB 2.6.0 的 `TxContext` 使用内部匿名事务身份，`tx.sender()` 固定为 `Identity::ZERO`；2.6.1 已向事务透传 procedure caller，但项目仍保持显式 caller 参数，兼容尚未升级的运行环境并让鉴权边界不依赖 SDK 隐式语义。
+11. 修改后运行：
 
 ```bash
 npm run spacetime:generate
@@ -234,14 +238,17 @@ npm run check:server-rs-ddd
 6. 编辑器图片生成 / 图片修改 / 图标 spritesheet / UI 设计图提取素材 / 视频 / 角色动作 / 音效 / 背景音乐必须在后端计算模型价格后使用 `execute_billable_asset_operation_with_cost` 预扣泥点；预扣失败必须 fail-closed，不得继续提交 VectorEngine、Ark、Suno 或 Vidu 上游任务。
 7. 队列任务按 `job_id + claim_attempt` 使用独立 consume/refund ledger。新 attempt 结算旧 attempt 时必须先写 `asset_operation_wallet_settlement`：旧 consume 已存在则原子退款，尚不存在则写取消 intent；迟到 consume 在同一 SpacetimeDB 事务内看到 intent 后必须失败关闭。重复 consume/refund 只有用户、金额、来源和配对 ledger 全部一致时才可视为幂等成功。lease 过期时只有 `attempt < max_attempts` 才能递增并重领；最终 attempt 已耗尽时，claim transaction 必须直接把 job 收口为 `failed`、清理 lease、写失败事件并结算当前 attempt，不能再把任务返回 worker 或调用 provider。
 8. 音频生成的编辑器链路虽然任务提交和结果发布分离，仍必须把提交时后端计算出的模型价格写入 `AudioAssetBindingTarget.billing_points_cost`，最终发布落资产时按该价格扣费；创作音频目标未提供该字段时才使用旧的创作音频固定成本。
-9. 编辑器进入外部生成持久队列的图片生成、图片修改、去背景、图标 spritesheet、UI 设计图提取、角色动作和视频参考图，只允许提交已登记的 generated `objectKey`、`resourceId` 或 `assetId`；任务 `request_payload_json` / `result_payload_json` 任意层级都禁止 `data:` / `blob:`，并受统一字节上限保护。objectKey 必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，后端通过归属校验后才签名读取 OSS。本地红框序号标注图必须先上传并确认对象，再把 objectKey 入队；不得把既有 objectKey 下载成 Data URL 后写入任务。图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；图片快速编辑当前不开放额外参考图。UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，图标素材上限 8 张额外参考图。同步且不持久化的历史兼容入口即使仍能解析 Data URL，也不能把该值转存到工程、素材、元数据、审计或任务表。
+9. 编辑器进入外部生成持久队列的图片生成、图片修改、去背景、图标 spritesheet、UI 设计图提取、角色动作和视频参考图，调用方必须提交 `objectKey` / `resourceId` / `assetId` 候选引用；BFF 只做内联媒体与 payload 门禁，登记状态和归属由 worker 统一解析。任务 `request_payload_json` / `result_payload_json` 任意层级都禁止 `data:` / `blob:`，并受统一字节上限保护。无效普通字符串可以入队，但必须在签名和 provider 调用前失败；本次不增加 API 侧数据库查询或同步 owner 校验。若以后要求无效引用同步返回 400，应作为独立改造。objectKey 最终必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，由 worker 在解析后、签名读取 OSS 前完成归属校验。本地红框序号标注图必须先上传并确认对象，再把 objectKey 入队；不得把既有 objectKey 下载成 Data URL 后写入任务。图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；图片快速编辑当前不开放额外参考图。UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，图标素材上限 8 张额外参考图。同步且不持久化的历史兼容入口即使仍能解析 Data URL，也不能把该值转存到工程、素材、元数据、审计或任务表。
 
 ## 外部服务与资产
 
 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；`platform-llm` 文本请求默认走 Responses，旧 `/api/llm/chat/completions` 代理和少数旧运行态聊天显式保留 Chat Completions 兼容协议；创意 Agent `gpt-5` Responses / Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/responses`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`；未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
 - 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
-- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 继续代理独立 BiRefNet 服务，配置为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`、`GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 和 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS`。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的生成后纯色背景透明化改走独立 BgFilter 服务，配置为 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时为 `180000ms`（BgFilter 当前为 CPU 推理，单次抠图较慢，必须留足超时），token 未配置时复用 BiRefNet token。BgFilter 请求必须显式传 `screen_color=<screenColor>` 和 `seg_model=<segModel>`；前端用户路径不展示抠图模型选择并固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，其中 `birefnet` 只表示 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。BgFilter 调用失败，或连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）并在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内打开熔断时，均跳过或结束 BgFilter 调用后复用同一兜底链：先调用阿里云通用抠图，阿里云失败才使用本地 `editor_green_screen` 键色扣除；熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败时降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。BgFilter 与阿里云抠图失败都写入 `external_api_call_failure` 审计。
+- 抠图输入以私有 OSS 作为内存生命周期边界：生成原图和角色动作抽取帧上传时消费图片字节所有权，上传完成后不保留原图缓冲；手动去背景直接解析并校验已有 OSS object key，不下载原图。BgFilter 必须为 object key 签发 600 秒 GET URL 并通过 multipart `image_url` 提交，不用 `file` 重传；flat 链路进入阿里云 fallback 时由 `platform-matting` URL 接口单独下载并上传 `AuthorizeFileUpload` 临时对象，在推理前释放下载缓冲，继续 fallback 到本地键色时再单独下载一次原图，本地产出后释放本次原图下载缓冲。签名 URL 不得写入日志、审计或持久化。
+- 阿里云通用抠图的非上海地域输入不得使用 `viapiutils/GetOssStsToken`、固定 `viapi-customer-temp` 或 OSS V1 PUT。`platform-matting` 必须按官方新版 SDK Advance 协议调用 `AuthorizeFileUpload`，使用动态返回的单对象 Policy 执行 multipart POST，再把临时上海 OSS URL 交给 `SegmentCommonImage`；输入归一化、结果下载与原尺寸 Alpha 回贴继续留在同一适配器内。该协议仍上传图片字节，不等同于阿里云服务端直接抓取任意公网 URL，也不改变上层 BgFilter → 阿里云 → 本地降级顺序。
+- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 与角色形象生成、图标 spritesheet 生成、UI 设计图素材提取、角色动作抽帧后的透明化统一走 BgFilter，配置为 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN` 和 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时为 `180000ms`（BgFilter 当前为 CPU 推理，单次抠图较慢，必须留足超时）；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 BgFilter token 的兼容回退别名，原手动去背景专用 base URL / timeout 配置已经删除。手动去背景固定传 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或 `screen_color`；该 API 接收 `objectKey`、`resourceId` 或 `assetId` 候选引用；BFF 入队前统一拒绝 `data:` / `blob:`；worker 不重复入口校验，只调用 `resolve_editor_reference_object_key_for_owner`，底层 resolver 在解析引用前拒绝内联媒体，并在签名前完成登记状态和 owner 校验；直接签发 OSS URL，不下载原图。标准纯色背景四条链路固定传 `background_mode=flat`，并显式传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>` 和 `cross_check=<on|off>`，其中角色形象生成和角色动作逐帧去背传 `cross_check=on`，图标 spritesheet 生成和 UI 设计图素材提取传 `cross_check=off`。前端用户路径不展示抠图模型、模式或 cross-check，固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`；这些参数只属于后端内部供应商策略，不进入前端或外部 OpenAPI。标准纯色背景 BgFilter 调用失败，或连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）并在 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内打开熔断时，继续复用“阿里云通用抠图 → 本地 `editor_green_screen` 键色扣除”兜底链，熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后每帧先上传私有 OSS 并释放原帧缓冲，再以该 object key 的签名 URL 固定使用 `seg_model=birefnet`、`cross_check=on` 进入上述三段式链路。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。标准纯色背景链路中，BgFilter 调用失败和阿里云抠图链路已开始后的失败（包括源 OSS GET 成功后的解码、尺寸校验和归一化失败）都写入 `external_api_call_failure` 审计；真正开始外部调用前的本地预检不写该审计，并在 `failureStage` 中保留 `source_decode`、`source_validate` 等阶段。
+- BgFilter 连接复用、重试与动作帧流水线：api-server 必须在 `AppState` 复用同一个 BgFilter HTTP Client 及 keep-alive 连接池。`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 是所有路径的基准请求超时；角色动作逐帧 BgFilter 的每一次 HTTP attempt 使用“基准超时 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景仍使用基准值。api-server 只在共享 Client 的单次 RequestBuilder 上覆盖该值；它覆盖从请求发起到响应体读取完成，是单次 attempt 的总 deadline，不是整批帧或 worker job 超时，重试会重新签发 600 秒 OSS URL 并获得同样的 request deadline，整项任务仍受 worker long-job 预算约束。flat 与 complex 请求首次失败后都立即重试 `1` 次；标准纯色背景 flat 请求第二次仍失败才进入“阿里云通用抠图 → 本地键色”降级链，手动 complex 请求第二次仍失败则返回最终错误，不接入依赖纯色键值的降级链，也不改变 flat 路径的熔断状态。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图 owned 上传 OSS 并释放原帧 → 以签名 URL 调 BgFilter/按 object key 降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的无序在途集合连续发射，不在 api-server 增加供应商进程锁或固定小并发窗口；返回结果携带原始帧序并在收口时排序。任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。
 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
@@ -280,14 +287,16 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`ExternalGenerationJob`
 - 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
-- 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，但用户可见任务列表、价格、状态、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
-- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用；图标图集生成和 UI 素材提取成功但自动拆分降级时，worker 的 `result_payload_json` 只额外保存有界的 `warning.code/reason`，不保存 spritesheet、切片列表或媒体 URL。其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行和受控维护读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得再返回或解析这两个 payload。
+- 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写阶段、完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，末尾可选 `phase` 只取 `generating / processing`；claim 写 `generating`，真实进入抠图处理时由受 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 以结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试一次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。用户可见任务列表、价格、状态、阶段、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
+- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用。画布 Agent 来源的任务可在 `result_payload_json.editor-agent-tool-call-result` 中保存有界的轻量结果和已登记媒体引用，供后端按已有 `externalJobId + owner_user_id` 定向懒回填；其它编辑器任务保持元数据结果，并可保存有界的 `warning.code/reason`。其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行、受控维护以及画布 Agent 的定向结果回填读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得返回或解析这两个 payload。画布 Agent 懒回填必须经对应工具 formatter 归一为有界轻量媒体引用后写入 OSS 会话，不能把原始 payload 直接透传前端。
+- 非阻断告警：角色形象、图标图集和 UI 素材提取已保存 provider 原图、但透明背景处理最终失败时，以原图唯一主图完成任务；透明图和切片不写入画布。这个 source-only 降级只包住透明背景处理的最终失败，phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。图标 / UI 透明图集成功但自动拆分降级时仍保留透明图集；通用 `warning` 与 `sliceWarning` 互斥。两类成功降级都以既有 `completed` 状态收口，不新增状态值：source-only 的 inline / external v1 响应使用结构化 `warning.code/reason`，仅拆分失败的 inline / external v1 响应继续使用既有 `sliceWarning.code/reason`，其 `reason` 保留原始诊断；queue worker 才把两者归一为有界的 `result_payload_json.warning`，且通用 `warning` 优先并原样保留完整 `reason`，只有 `sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀。除上述画布 Agent 定向回填的轻量结果外，队列结果不保存图片、切片列表或媒体 URL。
 
 ### `external_generation_job_summary`
 
 - Rust 结构体：`ExternalGenerationJobSummary`
 - 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
-- 用途：外部生成正式任务列表的轻量投影，按 `job_id` 保存 owner、来源、状态、价格、有界错误摘要、有界非阻断告警 `warning_message`、通知确认时间、各阶段时间和入队时提取的 `request_prompt`，不包含 request/result payload、worker lease 或 dedupe 内部字段。错误与告警摘要都不复制内联媒体并限制为 2048 字符；`warning_message` 由完成任务的轻量 `result_payload_json.warning.reason` 提取，complete 和历史 backfill 共用同一构建路径。列表在单次 owner 扫描中同时计数并只保留请求 limit 的固定大小 top-N，不得先收集全量历史再截断。enqueue、claim、renew、complete、fail 事务同步投影；acknowledge 只更新该轻量表并写审计事件，后续主任务同步必须保留已有确认时间，禁止为了写确认时间加载 / 重写大 payload 行。BFF 的列表、状态和确认只调用 summary procedure。历史终态任务由迁移操作员的游标分批 maintenance procedure 在压缩 payload 时同步回填摘要，正式列表不得为兼容旧数据回扫完整主表。
+- 用途：外部生成正式任务列表的轻量投影，按 `job_id` 保存 owner、来源、状态、可选 `phase`、价格、有界错误摘要、通知确认时间、各阶段时间和入队时提取的 `request_prompt`，不包含 request/result payload、worker lease 或 dedupe 内部字段。错误摘要统一拒绝内联媒体并限制为 2048 字符；列表在单次 owner 扫描中同时计数并只保留请求 limit 的固定大小 top-N，不得先收集全量历史再截断。enqueue、claim、renew、phase update、complete、fail 事务同步投影；acknowledge 只更新该轻量表并写审计事件，后续主任务同步必须保留已有确认时间，禁止为了写确认时间加载 / 重写大 payload 行。BFF 的列表、状态和确认只调用 summary procedure；`running + processing` 映射为“正在处理”，其它 running（含旧行 `phase=None`）映射为“正在生成”。历史终态任务由迁移操作员的游标分批 maintenance procedure 在压缩 payload 时同步回填摘要，正式列表不得为兼容旧数据回扫完整主表。
+- 非阻断告警：摘要字段 `warning_message` 是展示投影，由完成任务的轻量 `result_payload_json.warning.reason` 原样提取，不等同于公开 inline / external v1 的原始结构化诊断字段。complete 和历史 backfill 共用同一构建路径；历史任务按其结果载荷中已写入的 `reason` 快照投影，不为格式升级重写或补前缀。单 job 状态和任务列表 BFF 以 `warning: string` 返回该可直接展示的完整文案，不再返回结构化 code，Web 不得再次补前缀或按字符串推断告警类型。错误与告警摘要都不复制内联媒体并限制为 2048 字符。`phase` 与 `warning_message` 分别表示当前执行阶段和成功降级提示，不得混用；worker / BFF / Web 必须同版本协调发布，不保证滚动混部或旧 Web 缓存下的字符串语义兼容。
 - 正式读取 procedure 为 `get_external_generation_job_summary_and_return`、`list_external_generation_job_summaries_and_return` 和 `acknowledge_external_generation_job_summaries_and_return`。历史维护 procedure 为 `compact_external_generation_job_payloads_and_return` 与 `backfill_external_generation_job_summaries_and_return`，仅 migration operator 可调用；运维入口统一使用 `npm run spacetime:external-generation:maintain -- ...`，默认 dry-run、单批最多 25 条。B-tree cursor 选择阶段最多反序列化 `limit + 1` 行，apply 再按主键逐条读取选中行；怀疑存在单行异常巨型 JSON 时必须先使用 `--limit 1`。payload 压缩额外固定使用 `source_module = editor-canvas` 的复合 cursor 索引，不得静默改写其它玩法历史任务。
 
 ### `external_generation_job_event`
@@ -558,14 +567,14 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorAssetGroupSourceProvenance`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：手动图集拆分的私有可信来源索引。仅当账号素材由后端生成链路写入且具有正式 `source_resource_id` 时，按 owner + source resource、asset object 和 Object Key 记录真实来源 `task_id`；普通素材 / 资源创建请求不能直接写该表。跨项目复用素材后可通过稳定媒体引用找回原任务，历史行首次扫描命中后补写索引。
+- 说明：手动图集拆分的私有可信来源索引。仅当账号素材由后端生成链路写入且具有正式 `source_resource_id` 时，按 owner + source resource、asset object 和 Object Key 记录真实来源 `task_id`；普通素材 / 资源创建请求不能直接写该表。跨项目复用素材后可通过稳定媒体引用找回原任务，历史行首次扫描命中后补写索引。该持久表纳入 `migration_tables!` 导入导出清单，数据库迁移与恢复不得遗漏来源归组事实。
 - 主键：`lookup_key`。
 
 ### `editor_asset_group_cohort`
 
 - Rust 结构体：`EditorAssetGroupCohort`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：手动拆分批次的私有完成事实。api-server 只有在预期的全部 asset ID 已成功落库并由 runtime service identity 逐行校验 owner、真实 task、归组 task 和预期数量一致后才能插入；事实写入后不随用户删除单片素材而撤销。没有完成事实的现代批次不能并入来源根任务。
+- 说明：手动拆分批次的私有完成事实。api-server 只有在预期的全部 asset ID 已成功落库并由 runtime service identity 逐行校验 owner、真实 task、归组 task 和预期数量一致后才能插入；事实写入后不随用户删除单片素材而撤销。没有完成事实的现代批次不能并入来源根任务。该持久表纳入 `migration_tables!` 导入导出清单，数据库迁移与恢复必须保留不可逆批次完成事实。
 - 主键：`cohort_id`。
 
 ### `editor_showcase_asset`
diff --git a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
index b7159d938..038dc8ad6 100644
--- a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
+++ b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
@@ -42,6 +42,8 @@ v1 只开放以下能力：
 - `POST /api/external/v1/editor/audios/background-music/generations`：生成编辑器背景音乐素材。
 - `GET /api/external/v1/openapi.json`：导出本版本 OpenAPI 3.1 JSON。
 
+角色图生成、图标 spritesheet 和 UI 素材提取的 2xx 成功响应可携带可选结构化 `warning { code, reason }`，当前稳定 `code` 为 `postprocess-failed-source-preserved`。provider 原图已保存但透明背景处理最终失败时，接口返回原图，不返回不存在的透明处理图，图标和 UI 也不继续拆分；有 `projectId + canvasCompletion` 时由原图完成画布写回，无画布上下文时只返回原图及实际存在的资源 / 素材快照。调用方应展示 warning，但不得把任务改判为失败。该降级只覆盖透明背景处理的最终失败，phase 上报、原图或透明处理图持久化、画布写回失败仍返回错误。图标 / UI 已成功生成透明图、只有自动拆分失败时继续使用既有 `sliceWarning`；服务端保证通用 `warning` 与 `sliceWarning` 互斥，防御性客户端若收到异常双字段响应仍以通用 `warning` 为准。
+
 管理 API Key 的登录态接口保留在站内个人中心链路，但不写入外部 OpenAPI JSON：
 
 ```text
@@ -137,6 +139,7 @@ docs/openapi/genarrative-external-v1.openapi.json
 - API Key 创建只返回一次明文，列表不返回明文。
 - 撤销后的 API Key 调用外部接口返回 `401`。
 - 外部图片生成、重绘、图标拆分、UI 素材拆分、视频、音效和音乐生成成功后，生成结果按请求同时出现在画布资源和账号级素材库。
+- 角色图、图标 spritesheet 和 UI 素材提取的 2xx 成功响应允许携带 `EditorGenerationWarning`；provider 原图保留降级与自动拆分降级必须保持成功状态，并分别使用通用 `warning` 与兼容 `sliceWarning` 表达。
 - 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
 - OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
 - OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。
diff --git a/docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md b/docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md
new file mode 100644
index 000000000..1385fc039
--- /dev/null
+++ b/docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md
@@ -0,0 +1,57 @@
+# 图片画布撤销、恢复范围与操作提示方案
+
+更新时间：`2026-07-20`
+
+## 产品规则
+
+- 用户通过画布“撤销”按钮或 `Ctrl+Z` 触发撤销，通过“恢复”按钮或 `Ctrl+Shift+Z` 恢复最近一次成功撤销的操作。
+- 撤销成功显示 `已撤销：XX操作`，恢复成功显示 `已恢复：XX操作`；提示位于画布工作区顶部居中，3 秒后自动消失。
+- 如果目标快照会删除当前图层或生成结果、把当前可见图层重新隐藏，或者用其它素材替换当前素材，则不得恢复快照。
+- 撤销被阻止时显示 `无法撤销：XX操作，可能会使图片消失`；恢复被阻止时显示 `无法恢复：XX操作，可能会使图片消失`。
+- 被阻止的记录不得出栈，也不得跳过到更早记录；画布状态不变，因此不会触发项目自动保存。
+- 成功撤销会生成一条恢复记录；成功恢复后仍可再次撤销。撤销后发生新的画布编辑时，清空恢复历史。
+
+## 操作边界
+
+允许撤销的典型操作包括移动图片、移动生成结果、调整层级、组合与取消组合、删除或剪切图片、隐藏图片、锁定与解锁、翻转、修改素材类型和调整画布视图。删除、剪切和隐藏允许撤销，是因为目标只会让内容重新出现。
+
+添加素材、上传到画布、粘贴、创建副本、生成图片、扩图新增结果、显示隐藏图片、替换图片以及其它会让当前结果消失的撤销必须被安全检查阻止。`Ctrl+C`、选择变化、滚轮或抓手视口移动、导出下载、项目重命名、素材库后端删除和生成任务副作用不进入画布历史；素材库后端删除发生后，同时剪除撤销栈和恢复栈中所有包含关联图层的目标快照，不能让更早的画布历史复活已删除素材。
+
+恢复同样执行动态安全检查。移动、层级、分组、锁定、翻转和视图等不会减少内容的操作可以恢复；重新执行删除、剪切、隐藏、删除生成结果或替换当前素材时必须被阻止。
+
+## 技术实现
+
+- 撤销栈和恢复栈均保存操作类型、目标 `CanvasHistorySnapshot` 和创建时间，分别最多保留 60 条。
+- 新画布操作把操作前快照写入撤销栈并清空恢复栈；成功撤销把当前快照写入恢复栈，成功恢复把当前快照写回撤销栈。
+- 操作类型用于生成用户提示，并对添加、上传、生成和替换等明确会移除当前结果的撤销做保护；其它操作能否应用由当前快照与目标快照的差异检查决定。
+- 安全检查以稳定的 `layer.id` 判断当前图层是否仍存在；内容身份优先比较对象存储 key、对象标识和媒体地址，序列帧结果比较完整帧列表。`resourceId`、`sourceResourceId`、`sourceAssetId` 等内部关联 ID 的延迟回填不视为图片替换。
+- 恢复历史快照时，相同 ID 的图层以当前对象为权威，只从目标快照覆盖 `x`、`y`、`zIndex`、`groupId`、`assetKind`、`hidden`、`locked`、`flipX`、`flipY`。当前图层的资源关联、内容、媒体、生成元数据、`width` / `height` / `originalWidth` / `originalHeight` 和标题必须保留，不能被异步回填前的旧快照覆盖。
+- 当前生成对话框和非活动生成结果按稳定 ID 纳入内容存在性检查，避免恢复操作删除当前生成结果。相同 ID 的生成对话框只从目标快照恢复占位框 `x` / `y` 以及 active / inactive 槽位对应的 `composerOpen`，当前占位框的 `width` / `height` / `originalWidth` / `originalHeight`、当前比例与清晰度等参数、`generating` / `failed` / 完成态、提示词、参考图和任务结果继续以当前状态为准，不能被旧历史快照降级。
+- “修改图片”草稿使用基于来源图层的稳定 ID；撤销目标没有该草稿时必须阻止恢复，目标包含同 ID 旧草稿时保留当前未提交提示词和参数。
+- 当前快照中已经没有对应 ID 的完整删除对象不执行上述字段级合并；撤销删除或剪切时仍可从目标快照全量恢复图层或生成对话框。
+- 位置、尺寸、层级、分组、锁定、翻转、标题和素材类型不进入内容签名，避免误拦截普通编辑。
+- 素材库删除通过本次删除素材与历史图层的关联 matcher，同时过滤撤销栈和恢复栈；只删除目标快照中包含关联图层的记录，保留不可能复活该素材的其它画布历史。即使关联图层当前已经不在画布、只存在于历史快照中，也必须执行过滤。
+- 修改素材类型的撤销与恢复仍以当前图层内容为权威，但每次成功恢复类型后都要创建与恢复类型一致的正式项目 resource，再回填新 `resourceId`。同一图层的 resource 创建请求使用单调版本号，迟到的旧类型响应不得覆盖更晚的 undo / redo 结果。
+- 鼠标拖动在按下时暂存操作前快照；屏幕位移达到点击阈值后才开始改变画布坐标并只提交一条历史，阈值内的指针抖动和单击都不产生位移或历史记录。
+- 本地即时结果与后端项目快照结果都必须在生成图层加入画布前写入一条生成历史；生成完成后的自动适合视图不再额外压入视口历史，保证用户第一次撤销就命中生成保护。
+- 顶部消息复用 `PlatformRuntimeStatusToast`，成功使用中性色，被阻止使用警告色；连续触发会替换消息并重新开始 3 秒计时。
+
+## 验收重点
+
+1. 添加、上传、粘贴、复制、生成和替换图片后撤销，当前图片不消失且出现准确警告。
+2. 删除、剪切、隐藏、移动、分组和层级调整可以正常撤销，并出现成功提示。
+3. 移动、层级、分组、锁定、翻转和视图等安全操作可以恢复，并可再次撤销。
+4. 删除、剪切、隐藏、删除生成结果和替换素材的恢复会被阻止，当前内容保持不变。
+5. 被阻止的记录仍位于栈顶，连续撤销或恢复不会越过保护边界。
+6. 撤销后发生新编辑会清空恢复栈；恢复按钮随栈状态正确启用或禁用。
+7. 一次鼠标拖动只产生一条历史，单击不产生历史。
+8. `Ctrl+Z` 与 `Ctrl+Shift+Z` 分别触发撤销和恢复，在可编辑输入区域内不拦截原生行为。
+9. 提示在 3 秒后消失，连续提示按最后一次触发重新计时。
+10. 生成占位框移动后开始生成，再撤销移动时，只恢复位置，不得把正在运行的同 ID 生成对象回退为待生成状态。
+11. 上传素材落库异步补齐 `resourceId`、`sourceResourceId`、`sourceAssetId` 后撤销移动，位置恢复且三个当前关联值保持不变。
+12. 生成参数切换到 2K 或改变比例并同步占位尺寸后撤销位置，只恢复占位框 `x` / `y`，不得回退当前宽高、原始宽高或生成参数。
+13. 拖动非活动生成框触发 active / inactive 互换后撤销，原 active 生成框恢复打开，原非活动生成框恢复关闭，任务状态与尺寸不回退。
+14. 即时生成、本地结果和后端项目快照结果都只生成一条准确的生成历史，自动适合视图不会遮挡该历史。
+15. 图层移动后从素材库删除关联素材，随后撤销或恢复都不得把已删除图层重新加入画布；普通画布删除未伴随素材库删除时仍可撤销。
+16. 打开“修改图片”并输入未提交提示词后，从按钮等非输入控件触发撤销不得关闭弹窗或回退当前草稿。
+17. 修改素材类型后立即撤销或快速撤销再恢复，最终只允许最新类型的 resource 响应回填；刷新项目后类型与最后一次成功历史操作一致。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index b64ab30f7..7e58c5d1c 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -1,6 +1,6 @@
 # 本地开发验证与生产运维
 
-更新时间：`2026-06-12`
+更新时间：`2026-07-17`
 
 ## 标准开发流程
 
@@ -33,6 +33,8 @@ npm run dev
 
 `npm run dev` 和单模块 `npm run dev:web`、`npm run dev:api-server`、`npm run dev:spacetime`、`npm run dev:admin-web` 启动后都会更新根目录 `.app/dev-stack.json`。该文件记录本次命令、数据库、更新时间，以及 `spacetime`、`api-server`、`web`、`admin-web` 的 `pid`、监听 host / port、可访问 URL、启动状态和当前命令。`.app/` 是本地运行态目录，不提交 Git；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。
 
+通过 `nohup` 在仓库根目录启动 dev 栈且未显式重定向 stdout / stderr 时，默认 `nohup.out` 会持续收集 SpacetimeDB、api-server、主站 Vite 和后台 Vite 的整套 dev 栈输出；该文件已被主站 Vite watcher 和 Git 忽略，避免日志追加触发页面刷新循环，重启主站 Vite 后生效。若把输出显式重定向到其它仓库内文件（例如 `> dev.out`），该自定义文件不会自动获得同样的 watcher 保护，应改为写到 Vite root 之外，或同步配置精确的忽略规则。
+
 单独启动主站前端：
 
 ```bash
@@ -61,11 +63,16 @@ HTTP 角色的 `GENARRATIVE_SPACETIME_POOL_SIZE` 只表示 procedure / reducer 
 
 生产拆分角色时，`external-generation-worker` 和 `external-generation-controller` 的专属 env 示例会把 `GENARRATIVE_SPACETIME_POOL_SIZE` 覆盖为 `1`；非 HTTP 角色不创建 API 缓存读连接，只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure。worker / controller 不执行模型定价 seed，启动时先调用受 runtime writer 鉴权的 queue-stats procedure 做只读预检，身份不匹配时 fail-fast；当前正式 systemd unit 通过共同加载 `/etc/genarrative/api-server.env` 继承同一 `GENARRATIVE_SPACETIME_TOKEN`，专属角色 env 示例不重复配置该 token。`GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS` 与 controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。
 
-生产 worker 默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS=600`，只覆盖 worker 心跳抖动和短暂断连窗口，不再把 lease 当成完整任务时长；默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS=900`，角色动画 / 视频类长任务使用 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800`。worker 在单次尝试超过执行预算后会停止当前尝试、写入失败 / 重试状态并释放 worker 槽位；如果 SpacetimeDB 当时不可写，当前租约最多再保留到 lease 过期，之后任务重新变为可领取。生产部署和 provision 脚本会给 `/etc/genarrative/api-server.env` 与 `/etc/genarrative/external-generation-worker.env` 补齐这些变量；已有自定义值不覆盖，只会把历史旧默认 `3600` 迁移为 `600`。
+生产 worker 默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS=600`，只覆盖 worker 心跳抖动和短暂断连窗口，不再把 lease 当成完整任务时长；默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS=900`，角色动画 / 视频类长任务使用 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800`。worker 在单次尝试超过执行预算后会停止续租并释放 worker 槽位，但不会取消已启动的业务 future 或主动写入失败 / 重试状态；在途执行由 lease fencing 仲裁，有效租约内写回仍可完成，租约过期后任务才可重新领取，attempt 耗尽时由认领事务标记失败并结算退款。生产部署和 provision 脚本会给 `/etc/genarrative/api-server.env` 与 `/etc/genarrative/external-generation-worker.env` 补齐这些变量；已有自定义值不覆盖，只会把历史旧默认 `3600` 迁移为 `600`。
 
 lease 过期后不代表任务一定再次执行：claim transaction 只有在 `attempt < max_attempts` 时才会递增 attempt 并返回 worker；如果过期的是最终 attempt，则直接把 job 收口为 `failed`、清理 lease，并按入队冻结价格为当前 attempt 原子退款或写 cancellation intent。该终态任务不会再次进入 provider executor，迟到 consume 会被 settlement intent 拒绝。
 
-图片画布角色图、图标素材和 UI 素材提取在绿色 / 蓝色幕布去背景时优先调用 BgFilter；默认 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000`，连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后熔断 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒。BgFilter 调用失败和熔断期均先走阿里云通用抠图，只有阿里云失败才走本地幕布色去背景兜底。阿里云这层默认 `GENARRATIVE_ALIYUN_MATTING_ENABLED=true`，但必须在 `api-server.env` 填入 `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID` / `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET`（或标准 SDK 命名 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`）才会真正启用；AccessKey 缺失时启动日志会打印「阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化」，抠图直接塌成 BgFilter→本地两级，`npm run check:api-server-env` 也会给出对应告警。修改这些变量后需要重启对应 `api-server` / worker 进程；排查时先从 worker 启动日志确认 lease 和 job timeout，再看 `editor_bgfilter_request_start`、`editor_bgfilter_fallback_to_aliyun_matting`、`editor_bgfilter_circuit_open_fallback_to_aliyun_matting`，以及阿里云失败后的 `editor_aliyun_matting_fallback_to_local_screen_background_removal` 日志。
+图片画布角色图、图标素材、UI 素材提取和角色动作逐帧去背景时优先调用 BgFilter；当前全部调用都显式传 `background_mode=flat`，保持单一纯色背景抠图语义。默认 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000`，该值是所有路径的基准请求超时；角色动作逐帧请求的每一次 HTTP attempt 额外增加 `2000ms × 本次实际帧数`，默认 `32 / 40 / 48` 帧对应 `244000 / 260000 / 276000ms`，角色形象单图、图标、UI 和手动去背景继续使用基准值。该 request timeout 不是整批帧或整项任务超时，首次失败后的重试会重新计时；角色动作整项任务仍受默认 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS=1800` 预算约束，排查时以 `editor_bgfilter_request_start.timeout_ms` 确认实际值。连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后熔断 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒。BgFilter 调用失败和熔断期均先走阿里云通用抠图，只有阿里云失败才走本地幕布色去背景兜底。阿里云这层默认 `GENARRATIVE_ALIYUN_MATTING_ENABLED=true`，但必须在 `api-server.env` 填入 `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID` / `GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET`（或标准 SDK 命名 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`）才会真正启用；AccessKey 缺失时启动日志会打印「阿里云抠图 AccessKey 未配置，跳过抠图客户端初始化」，抠图直接塌成 BgFilter→本地两级，`npm run check:api-server-env` 也会给出对应告警。修改这些变量后需要重启对应 `api-server` / worker 进程；排查时先从 worker 启动日志确认 lease 和 job timeout，再看带 `background_mode=flat` 的 `editor_bgfilter_request_start`、`editor_bgfilter_fallback_to_aliyun_matting`、`editor_bgfilter_circuit_open_fallback_to_aliyun_matting`，以及阿里云失败后的 `editor_aliyun_matting_fallback_to_local_screen_background_removal` 日志。
+手动 `POST /api/editor/images/background-removals` 同样调用 BgFilter，但 worker 只解析并校验已有 OSS object key，直接签发 600 秒 URL，不下载原图；multipart 固定传 `image_url`、`background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或背景色。首次失败后立即重试 `1` 次，两次都失败则返回最终错误。它不进入只适用于已知纯色背景的阿里云 / 本地键色兜底链，也不改变 flat 路径的熔断状态。标准纯色背景四条链路仍固定传 `background_mode=flat`。两种模式统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 和共享 HTTP client；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只保留为 token 兼容别名。
+
+阿里云通用抠图的非上海地域输入使用 `AuthorizeFileUpload → Policy POST → SegmentCommonImage` 正式链路，上传 Bucket / Endpoint / ObjectKey 由阿里云动态返回；不得恢复 `GetOssStsToken`、固定 `viapi-customer-temp`、临时 AK/SK 或 OSS V1 PUT。该切换不新增环境变量；真实链路冒烟可运行 `cargo run -p platform-matting --example segment_smoke --manifest-path server-rs/Cargo.toml -- <图片路径>`，预期日志中的输入 host 为授权响应返回的上海 OSS host，并完成结果下载。图片字节仍经过执行任务的 api-server / worker，排障时不要把 Advance 路径误判为阿里云直接抓取任意公网 URL。
+
+BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去背景源图直接使用 600 秒签名 URL：`api-server` 的 multipart 提交 `image_url` 及对应模式参数，不再提交 `file`，也不会在 BgFilter 调用前重新下载 OSS 对象。生成原图和动作帧上传完成后应已消费并释放字节所有权；手动路径从始至终不读取原图字节。flat 路径的 BgFilter 失败或熔断打开后，阿里云 fallback 才单独下载源对象并上传动态临时桶，临时上传完成即释放本次下载缓冲；阿里云继续失败时本地 fallback 再独立下载，并在本地处理产出后释放本次原图缓冲。排障日志只应出现 object key 与签名有效期，不得记录带 `x-oss-*` 查询参数的完整 URL。这里的释放是 Rust 缓冲析构，不以操作系统 RSS 立即下降作为判据。
 
 `我的` 页签或排障面板展示队列等待时，只读取 BFF 队列接口：`GET /api/runtime/external-generation/queue-overview` 查看当前用户可见队列概览，`GET /api/runtime/external-generation/jobs/{jobId}` 查看单 job 状态。生成页 / 进度页不承接队列概览，只展示当前玩法业务进度；队列接口只提供等待 / 运行 / 失败 / 完成状态补充，最终草稿、作品和结果页仍要轮询对应玩法 session/detail 接口收敛到 ready 或 failed；不要直接查询 `external_generation_job` private table，也不要把 worker 内部 payload 暴露到前端。
 
@@ -73,7 +80,7 @@ lease 过期后不代表任务一定再次执行：claim transaction 只有在 `
 
 自 2026-07-11 起，`Genarrative-Full-Build-And-Deploy` 的每日 04:00 timer 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，不得依赖下游 Job 默认值或提前各自发布；统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。上文“定时构建缺少审批人时失败”的旧口径不再作为当前 dev 定时发布行为。
 
-Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。
+Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。
 
 需要验证“更新 API 不停 worker”和“worker 是否持续消费队列”时，优先使用隔离容器 smoke：`npm run container:worker-smoke -- smoke`。该脚本生成 gitignored 的 `deploy/container/worker-smoke/api-server.env`，启动独立 compose project 与独立 SpacetimeDB，发布当前 `spacetime-module` 后写入 `worker_smoke_unsupported` 测试 job；预期 worker claim 后执行 unsupported 失败分支，再执行 API-only recreate 并确认 worker 容器 ID 不变，最后再次入队验证 API 更新后队列仍可消费。`external_generation_job` 是 private table，脚本通过 worker 日志确认 job_id 被消费，不用 CLI SQL 查询私表。该 smoke 不读取 `.env.local`，也不依赖真实 VectorEngine / OSS 密钥；真实生图链路联调再在本地私有 env 中补齐 provider 配置。worker-smoke 默认把本机 `spacetime` CLI 打成轻量 SpacetimeDB 镜像，避免本机首次 smoke 依赖官方大镜像下载。若容器内 Cargo 拉取 crates.io 依赖不稳定，可用 `npm run container:worker-smoke -- smoke --local-binary` 让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入 Debian bookworm smoke runtime 临时镜像；可用 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE` 覆盖运行时基础镜像；若隔离端口或库数据需要重建，追加 `--force`。完成 queue 链路验证时，还要用队列概览 BFF 和单 job 状态接口确认 job 从 queued/running 收敛，并用对应玩法 session/detail 接口确认业务状态同步完成。
 
@@ -144,7 +151,7 @@ spacetime sql <database> "SELECT * FROM puzzle_gallery_card_view LIMIT 1" --serv
 
 本地 `npm run dev:spacetime` 发布模块时必须显式忽略仓库根目录的 `spacetime.json`，由脚本固定追加 `--no-config` 并使用命令参数里传入的数据库名和 `--server http://127.0.0.1:3101`。否则 CLI 可能把发布目标改写到配置文件里的其他数据库，导致 `dev:spacetime` 启动后又因发布失败自动退出，浏览器随后会在 `ws://127.0.0.1:3101/v1/database/.../subscribe` 看到连接拒绝。
 
-本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.6.0`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；遇到版本不匹配时不要继续深挖业务超时，直接执行 `spacetime version install <version> && spacetime version use <version>`，或在目标就是最新版本时执行 `spacetime version upgrade`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。
+本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.6.1`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；遇到版本不匹配时不要继续深挖业务超时，直接执行 `spacetime version install <version> && spacetime version use <version>`，或在目标就是最新版本时执行 `spacetime version upgrade`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。
 
 本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查 RPG / 拼图 / 抓大鹅等 VectorEngine 生图链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。VectorEngine `gpt-image-2` 图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`；`api-server` 只做配置、玩法编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前，按原比例尽量收敛 `gpt-image-2` 的显式像素尺寸：最大边长不超过 `3840`、宽高均为 `16` 的倍数、长短边比不超过 `3:1`，总像素范围为 `655360` 至 `8294400`。无法满足全部条件时回退为 `1024x1024`；其他模型保留其传入尺寸。开局 CG 故事板、首图、背景和图集都属于长耗时图片请求；后端默认会把 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 下限收口到 `1000000`，旧进程仍可能沿用重启前的短超时。若 VectorEngine 在 `send()` 阶段失败且日志显示 `SendRequest`，先看同一 `request_id` 的 provider 日志字段 `source`、`source_chain`、`source_chain_depth`，再查 `external_api_call_failure.metadata_json.errorSource`；当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。拼图关卡资产按 `level_scene -> ui_spritesheet -> level_background` 顺序生成，日志会带 `slot`、`asset_kind` 和 `elapsed_ms`。
 
@@ -155,13 +162,13 @@ VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`c
 查看本地 Rust / SpacetimeDB 日志：
 
 ```bash
-npm run dev:rust:logs
+npm run dev:spacetime:logs
 ```
 
 后台前端：
 
 ```bash
-npm run admin-web:dev
+npm run dev:admin-web
 npm run admin-web:build
 npm run admin-web:typecheck
 ```
@@ -270,7 +277,7 @@ npm run check:spacetime-schema
 `rustfmt.toml` 固定 Edition 2024 的格式化口径。Rust 源码统一使用
 `cargo fmt --all --manifest-path server-rs/Cargo.toml` 格式化，并用
 `npm run check:rustfmt` 做只读校验；Codex 提交前门禁、API 生产构建和
-SpacetimeDB module 生产构建都会执行同一检查，避免不同开发机或构建节点反复产生格式差异。
+SpacetimeDB module 生产构建都会执行同一检查，避免不同开发机或构建节点反复产生格式差异。Web 生产构建还会执行 production-ops、ESLint、主站与后台类型检查，以及排除已下线旧玩法后的当前 Vitest；API 生产构建追加 production-ops、DDD/schema/runtime-access 和 api-server 全 target 编译检查；SpacetimeDB module 生产构建追加 production-ops、DDD/schema/runtime-access 和管理员 procedure smoke。上述门禁由 `npm run check:production-ops` 反查，不能只保留在本地说明中。
 
 ## 前端改动验收
 
@@ -303,7 +310,7 @@ UI 相关修改要重点验证：
 
 ### SpacetimeDB 数据目录 OSS 备份
 
-数据库备份不放进 `spacetime-module` reducer / procedure：备份属于文件系统与 OSS 外部副作用，必须由运维脚本在 SpacetimeDB 宿主外执行。当前统一脚本为 `scripts/database-backup-to-oss.mjs`（npm 命令 `npm run database:backup:oss`）；生产 provision 还会安装 `genarrative-database-backup.timer`，每天 `03:20` 左右自动执行一次 OSS 冷备份：
+数据库备份不放进 `spacetime-module` reducer / procedure：备份属于文件系统与 OSS 外部副作用，必须由运维脚本在 SpacetimeDB 宿主外执行。当前统一脚本为 `scripts/database-backup-to-oss.mjs`（npm 命令 `npm run database:backup:oss`）。默认 `--storage-format archive --mode full` 保持原有全量压缩包冷备行为；`--storage-format files` 不生成 tar.gz，而是把目录树映射成逐文件 CAS 对象与 catalog，full 重跑只上传新增或内容变化的文件，history 只处理已被最新 snapshot 完全覆盖的历史 commitlog 与旧 snapshot。`Genarrative-Server-Provision` 的 `DATABASE_BACKUP_PROFILE` 默认是 `archive-full`，继续安装每天 `03:20` 左右执行的全量冷备主 service；development 和 release 都可以显式选择 `files-history`，但指定 work-dir 必须已经有与本机 database/bucket 匹配且已发布的 full baseline state：
 
 ```bash
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service --restart-service-after genarrative-external-generation-worker@1.service --restart-service-after genarrative-external-generation-controller.service
@@ -326,13 +333,69 @@ GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
 GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
 GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
 GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT=archive
+GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY=16
+GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND=
 GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES=
+GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE=/var/lib/genarrative/database-backups/genarrative-prod-history-state.json
+# 仅 archive history 首次从一份 uploadStatus=uploaded 的全量 manifest 初始化 state 时设置或传 --baseline-manifest。
+GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST=
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
 ```
 
 `GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET` 为空时会回退 `ALIYUN_OSS_BUCKET`；AccessKey 默认复用 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，也可用 `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID` / `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET` 为备份 bucket 单独配置最小权限账号。冷备脚本会在停止 SpacetimeDB 前检查 `GENARRATIVE_DATABASE_BACKUP_WORK_DIR` 所在文件系统剩余空间；未设置 `GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES` 时，按数据目录大小加安全余量估算，空间不足会在停库前失败，避免写满根分区。即使打包或上传前步骤失败，只要脚本已经停过 SpacetimeDB，也会先恢复 SpacetimeDB 并执行 `--restart-service-after` 指定的 API / worker / controller，再带着原始备份错误退出。`Genarrative-Server-Provision` 会创建 `/var/lib/genarrative/database-backups` 并归属 `genarrative:genarrative`，同时安装并启用 `genarrative-database-backup.timer`。手动检查定时器：`systemctl list-timers genarrative-database-backup.timer`；手动触发一次：`systemctl start genarrative-database-backup.service`。如果 timer 显示 `enabled` 但 `inactive/dead` 且 `NEXT` / `Trigger` 为空，先写入当前 stamp 避免 `Persistent=true` 在白天立刻补跑冷备份：`touch /var/lib/systemd/timers/stamp-genarrative-database-backup.timer && systemctl daemon-reload && systemctl start genarrative-database-backup.timer`，随后确认下一次触发时间约为次日 `03:20`。
 
+`files-history` 使用仓库模板 `deploy/systemd/genarrative-database-backup-files-history.conf` 覆盖主 service 的 `ExecStart`，从 `/etc/genarrative/api-server.env` 读取 data-dir、database、bucket、prefix 与 OSS 凭据，不在 unit 写死环境目标，也不传 `--stop-service`。Server-Provision 在改动 drop-in 前，先用 current release 的同一脚本、同一 env 和 `DATABASE_BACKUP_FILES_HISTORY_WORK_DIR` 执行一次 history `--dry-run`；缺少已发布 full catalog 的 files state、current 脚本过旧或配置不匹配都会在安装 drop-in 和 `daemon-reload` 前失败。选择 `archive-full` 会主动删除仓库托管的 `10-files-history.conf` 与 dev 试点遗留的 `10-dev-files.conf`，防止 systemd 继续合并旧覆盖。dev 可继续指定已有 `/var/lib/genarrative/database-backups/dev-files`，release 建议先在 `/var/lib/genarrative/database-backups/release-files` 建立自己的 full baseline；两台机器不得复用或互传本地 state 目录冒充本机基线。启用时通过 Server-Provision Job 选择目标、`DATABASE_BACKUP_PROFILE=files-history` 和对应 work-dir，先保持 `DRY_RUN=true` 核对，再以同参数正式 provision。不要直接在 `/etc/systemd/system` 手写第二份 drop-in。
+
+files full 会递归扫描 data-dir，保留空目录、每个普通文件的相对路径，以及目标仍位于 data-dir 内部的相对符号链接；绝对链接或解析后越界的链接直接拒绝。文件按 SHA-256 上传到不可变对象 key，catalog 记录目录、路径、长度、SHA、对象 key 和相对链接目标，不写 staging 主机的绝对路径。相同 catalog 重跑不重复 PUT；新增或变化文件先 HEAD CAS 对象，存在且长度/SHA 元数据一致就复用，否则上传。16 MiB 及以下对象使用单次 PUT 后 HEAD 验真，大对象继续使用 multipart；对象操作默认以 16 路并行执行，可用 `GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY=1..64` 调整。需要给线上入口留带宽时设置 `GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND=<bytes/s>`，该共享限速器只包裹备份上传流，空值或 `0` 表示不限速，不修改主机全局 qdisc。并发、限速和单次 PUT 都不改变“全部对象、catalog 与 latest pointer 成功后才推进 state/清理”的顺序。full 基线必须来自停库后的 data-dir 或已通过恢复验证的冻结副本；源文件上传前后 stat 虽会复核，但在线扫描不能保证大量文件属于同一跨文件一致时点。catalog 验真后，脚本把最新 full/history 引用发布到固定 `<prefix>/<database>/latest.json`，全新机器不需要本地 state 即可自动发现恢复入口。
+
+history 的安全边界按每个 replica 独立计算。设最新完整且未锁定的 snapshot offset 为 `S`；数字更大但缺少同 offset `.snapshot_bsatn`、仍存在同名 `.lock` 的目录不能参与边界计算。脚本必须保留起始 offset 小于等于 `S` 的最后一个 commitlog segment，以及它之后的全部 segment；只处理更早的 `.stdb.log` / `.stdb.ofs`，snapshot 只处理最新目录之前的旧目录。files history 会递归展开候选目录，逐对象复用或上传，随后依次验真候选对象、history catalog 与 full baseline catalog，再重新扫描边界和 stat fingerprint，最后覆盖发布并验真 `latest.json`；任何一步失败都不推进 state 或删除源文件。脚本在 work-dir 使用 PID lock 拒绝同库并发上传，SSH 超时后必须先检查原进程，不能直接重跑。
+
+```bash
+# 从停库目录或已验证冻结副本建立逐文件完整基线；相同 work-dir 重跑只传变化内容。
+node -- scripts/database-backup-to-oss.mjs \
+  --storage-format files \
+  --mode full \
+  --data-dir /path/to/frozen/stdb \
+  --work-dir /var/lib/genarrative/database-backups/dev-files \
+  --database genarrative-prod \
+  --env-file /etc/genarrative/api-server.env
+
+# 把完整 work-dir/state 放回 dev 后，先只读查看可清理历史候选。
+node -- scripts/database-backup-to-oss.mjs \
+  --storage-format files \
+  --mode history \
+  --data-dir /stdb \
+  --work-dir /var/lib/genarrative/database-backups/dev-files \
+  --database genarrative-prod \
+  --env-file /etc/genarrative/api-server.env \
+  --dry-run \
+  --result-file /var/lib/genarrative/database-backups/history-dry-run.json
+
+# 核对 dry-run 后执行真实归档与清理；history 在线处理不可变历史文件，不传 --stop-service。
+node -- scripts/database-backup-to-oss.mjs \
+  --storage-format files \
+  --mode history \
+  --data-dir /stdb \
+  --work-dir /var/lib/genarrative/database-backups/dev-files \
+  --database genarrative-prod \
+  --env-file /etc/genarrative/api-server.env
+```
+
+dev 出口过慢时，可以把冻结基线经内网 rsync 到 release 独立 staging，再由 release 上传 dev bucket。staging 必须位于 `/var/lib/genarrative/dev-database-backup-staging/` 一类隔离目录，命令显式传 staging `--data-dir`、独立 `--work-dir`、dev `--bucket`，且不得传 `--stop-service`；禁止指向或修改 release `/stdb`。中转 key 只为本次传输临时授权，结束后从 dev 私钥和 release `authorized_keys` 同时移除。上传完成后把整个 files work-dir/state 回传 dev，history 才能延续同一 baseline catalog。
+
+完整恢复默认从 OSS 固定 `latest.json` 读取最新 full catalog：先创建 `directories`，再把每个 `files[].objectKey` 下载到 `<restore-root>/<files[].path>` 并逐项核对 `sizeBytes` / `sha256`；history catalog 用于证明已清理历史仍有 OSS 对象，不需要把已被 full baseline 覆盖的旧文件叠回当前恢复目录。本地 state 仍可作为兼容入口，但不再是异机恢复的前置条件。随后用隔离 data-dir 启动同版本 standalone，验证 `/v1/ping`、日志中的 snapshot restore / commitlog replay / module launch、代表性 SQL 和 reducer。dev 已完成这轮 OSS-only 异机恢复与重启演练；当前 live release 仍保持 `archive-full`，需要切换时先为 release 建立并恢复验证独立 full baseline，再通过 Server-Provision 显式选择 `files-history`，无需修改代码或解除额外硬门禁。
+
+```bash
+node -- scripts/database-backup-to-oss.mjs \
+  --env-file /etc/genarrative/api-server.env \
+  --database genarrative-prod \
+  --restore-files-latest \
+  --restore-dir /var/lib/genarrative/database-backup-restore/stdb \
+  --result-file /var/lib/genarrative/database-backup-restore/restore-result.json
+```
+
 冷备份后必须做一次只读验收，不要只看 `genarrative-database-backup.service` 是否成功退出：
 
 ```bash
@@ -504,7 +567,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt
 - `api-server` 正常运行时 `/healthz` 只返回进程存活状态，`/readyz` 会同时检查进程是否仍接收新流量和 SpacetimeDB 连接租约是否健康；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
 - SpacetimeDB 健康检查默认使用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS=2` 的短等待窗口，和业务 procedure 的 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 分开。`/readyz` 失败时 `details.spacetime.stage` 会标出当前卡住阶段：`pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result` 或 `read_cache`；`elapsedMs` / `timeoutMs` 用于确认是否命中健康检查窗口。业务请求日志也会写入 `operation_kind`、`operation_name`、`spacetime_stage` 和 `elapsed_ms`，后续 45 秒超时不再只靠 Nginx `request_time=45s` 推断。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax -p TimeoutStopUSec` 和 `cat /proc/$(pidof api-server)/limits` 核对。
-- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.6.0` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
+- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.6.1` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
 - 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源，目标部署 agent 也不再需要访问源码 Git remote。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。该服务必须存在系统用户 / 组 `otelcol`，并且 `/etc/otelcol/genarrative-debug.yaml` 已安装到目标机；若看到 `status=217/USER` 或 `Failed to determine user credentials`，优先检查 `getent passwd otelcol`，再补齐 `/etc/otelcol` 配置目录并重启服务。
 - Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 是反代兜底，防止拼图入口页 / 新增关卡本地参考图 Data URL 或旧兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；拼图本地参考图前后端统一限制 6MB，历史图片仍提交 `referenceImageAssetObjectId(s)`。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否超出 6MB 或错误提交了未压缩大图。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
diff --git a/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md b/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md
index 6a29a90b2..6aeb9e5aa 100644
--- a/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md
+++ b/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md
@@ -55,7 +55,7 @@ Prompt 输入摘要与 Prompt 约束只作为内部生成契约维护，不在 U
 - 宣发素材请求携带 `kind: publication-material`，前端提交和后端 handler 都固定归一为 `gpt-image-2`；即使旧前端或外部请求传入 `nanobanana2`，后端也按 `gpt-image-2` 生成和计费，但价格仍来自运行时模型定价配置，不写死数值。
 - `publication-detail-gallery` 不再携带 `candidateCount: 5`；后端仍兼容多候选请求，但当前宣发素材入口不主动批量生成。
 - 尺寸请求和成品交付规格必须使用明确像素值：游戏首图 `720x540`、详情图 `720x1280`、运营海报 `1280x720`。这些值是画布图层与成品的业务规格；由于三种规格并非都满足 `gpt-image-2` 的上游尺寸约束，VectorEngine 适配层会在发送前等比归一到合法请求尺寸（最大边 `3840`、两边为 `16` 的倍数、长短边比不超过 `3:1`、总像素 `655360..8294400`），不能将上游归一后的尺寸当作宣发成品规格。只有 `16:9`、`9:16`、`2k` 等比例 / 档位别名才走 provider 预设映射。
-- 参考图在提交 `/api/editor/images/generations` 前由前端压缩成适合生成理解的图片 Data URL，避免原图 Data URL 撑爆 JSON 请求体；后端该路由保留 `12MB` body limit 作为兼容兜底。
+- 参考图在提交 `/api/editor/images/generations` 前必须先落稳定引用：本地图先上传 OSS 并确认 asset object，提交时使用 `objectKey`、项目资源 ID 或素材 ID；禁止把 Data URL / Blob URL 写入生成请求或外部生成队列载荷。浏览器内可对临时图做压缩等处理，但压缩结果也必须上传后再提交。
 - 扣费通过现有钱包资产操作封装执行；上游生成失败或未返回图片时按现有补偿逻辑退款。
 - 生成成功后，成品作为图片画布生成图层加入画布，并保留游戏输入和参考图摘要供图层信息使用。
 
diff --git a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
index e8d8a3677..6fd784f9f 100644
--- a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
+++ b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
@@ -68,7 +68,7 @@
 - 生成图片和生成视频文本输入框紧贴参考图下方，取消旧网格预留导致的空白高度。
 - 生成规范类图片固定使用 `16:9·2K · gpt-image-2`。这三个参数在面板底部沿用可编辑参数按钮的胶囊样式展示，但控件保持禁用不可点击，不提供比例、尺寸或模型修改入口。
 - 宣发素材的 `游戏首图`、`详情五图`、`运营海报` 固定使用 `gpt-image-2`。面板底部只显示禁用态 `gpt-image-2` 模型胶囊和生成按钮，不出现 `nanobanana2` 选项；后端收到 `publication-material` 旧请求时也必须强制归一为 `gpt-image-2`。
-- 图片快速编辑保留一个提示词输入框，并展示与常规图片生成一致的比例 / 尺寸和模型选择；提示词 placeholder 为 `你希望素材如何修改？`，提交按钮显示 `修改`，不展示额外参考图控件。打开面板时优先继承原图关联生成器记录的模型、比例和尺寸；没有关联生成器时使用图层模型，并按原图真实分辨率推导比例和尺寸；模型缺失或已不受支持时回落到当前默认图片模型。切换模型后只展示该模型支持的参数，不兼容的当前值回落到该模型默认值，按钮泥点按选定模型和尺寸同步刷新。
+- 图片快速编辑保留一个提示词输入框，并展示与常规图片生成一致的比例 / 尺寸和模型选择；提示词 placeholder 为 `你希望素材如何修改？`，提交按钮显示 `修改`，不展示额外参考图控件。打开面板时优先继承原图关联生成器记录的模型、比例和尺寸；没有关联生成器时使用图层模型，并按原图真实分辨率推导比例和尺寸；模型缺失或已不受支持时回落到当前默认图片模型。切换模型后只展示该模型支持的参数，不兼容的当前值回落到该模型默认值，按钮泥点按选定模型和尺寸同步刷新。提交时必须同时传递 `model / aspectRatio / imageSize`；后端按模型选择 provider 协议：`nanobanana2` 使用 `generateContent + inline_data`，`gpt-image-2` 使用 `/v1/images/edits` multipart，不能把 nanobanana 模型 ID 发往 GPT edits 端点。
 - 不再在底部常驻展开全部可选项。
 
 ## 泥点显示
@@ -110,15 +110,19 @@
 - 查看信息按钮固定使用圆形 `i` 图标，不使用中括号、花括号或文本符号样式。
 - 视频 / 角色 / 角色动作 / 音效 / 背景音乐待生成占位的角标同样按 viewport 反向缩放，不随画布缩放变小。
 - 已生成角色图、角色动作图或其它生成结果图被点击时只选中图层并收起已有生成输入框；重绘、快速编辑和生成动画面板必须由对应工具栏按钮或右键菜单显式打开。
+- 角色图层打开“生成动作”后再点击“改造”，必须重新打开角色形象生成器；动作生成对话框只把角色图层作为输入来源，不得被识别为该角色图层自身的来源生成器。
+- 角色动作结果图层点击“改造”时，必须通过 `sourceResourceId` 找回原角色图层并重新打开角色动作生成器；关联原角色已不存在时应显示明确提示，不得无响应或降级成图片生成器。
+- 恢复已生成图层的来源生成器时，角色、动作、规范、图标、UI、宣发、视频、音效和背景音乐必须按 `assetKind / mediaType` 恢复对应面板；去背景或快速编辑产生的派生 `quick-edit` 对话框不得遮住图层原有来源生成器。
+- 任何会移除画布图层的入口，包括删除、右键剪切和素材库删除关联素材，都必须同步清理该图层关联的生成面板和派生状态，不得在保存或刷新后恢复成孤立占位。
 
 ## 画布保存
 
 - 生成占位图和生成器对话框不是临时浮层，必须作为画布布局数据保存。
 - 保存时在现有画布布局数组中追加 `itemType: "generation-dialog"` 项，记录生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和 `generatedLayerId`。
 - 生成成功后仍保留生成器快照；画布渲染优先用 `generatedLayerId` 锚定到成品图层，不再重复显示灰色占位框。
-- 一次生成任务产生多个可复用产物时，全部产物都必须由后端登记为项目资源并随同一次完成快照加入画布，不能只保留最终产物或由前端临时追加。角色形象、图标 spritesheet 和 UI 素材提取至少同时回填纯色背景原图与透明后处理结果；UI 素材提取继续一并回填拆分素材。`generatedLayerId` 仍锚定透明后处理主结果，附属产物从主结果右侧开始错开放置。
+- 一次生成任务产生多个可复用产物时，已实际生成的产物都必须由后端登记为项目资源并随同一次完成快照加入画布，不能由前端临时追加。角色形象、图标 spritesheet 和 UI 素材提取在透明背景处理正常成功时同时回填纯色背景原图与透明后处理结果，UI 素材提取继续一并回填拆分成功的素材；`generatedLayerId` 锚定透明后处理主结果，附属产物从主结果右侧开始错开放置。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建不存在的透明处理图，图标和 UI 也不继续拆分；角色重绘遵循同一规则。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。
 - 多产物任务的可恢复中间产物还必须进入账号素材库，未传 `assetFolderId` 时落默认“项目”文件夹，并在抠图、尺寸恢复、抽帧或拆分前完成登记。图片修改保存模型对齐尺寸的原始输出；角色动作把绿幕预览视频保存为一个素材，逐帧绿幕源图只保留在同一任务 OSS 路径，避免素材库一次新增 32 至 48 张帧图。普通图片、去背景和音频等没有独立上游中间产物的任务不重复复制最终结果。
-- 图标和 UI 图集自动拆分属于非阻断附加动作；识别或切片持久化失败时整张透明图集仍完成并回填，前端通过 warning toast 提示用户可手动重试。inline 响应、worker 队列终态和刷新后的任务列表必须使用同一 warning 语义，不能把已完成图集标记为失败。
+- 图标和 UI 图集自动拆分只在透明图集成功后执行，属于非阻断附加动作；识别或切片持久化失败时整张透明图集仍完成并回填，前端通过 `sliceWarning` toast 提示用户可手动重试。透明背景最终失败使用通用 `warning.code/reason`，与 `sliceWarning` 互斥；`sliceWarning` 只表示透明图集成功但自动拆分失败，其 `reason` 原始契约保持不变。inline 响应、worker 队列终态和刷新后的任务列表必须使用同一 warning 语义，不能把已完成或降级完成的任务标记为失败。
 - 普通图片、图片修改、规范、角色、图标、UI 设计、宣发素材、视频、音效、背景音乐和角色动作生成面板不展示“资源名称”输入，默认继续使用现有“类型 + 编号”名称；提示词输入保持统一可见边框。状态与请求契约仍兼容可选 `assetLabel`，内部调用或历史状态携带名称时最多 80 个字符并在提交时 trim，最终解析出的同一个名称必须同时写入画布图层、`editor_project_resource`、`editor_asset` 和 `canvasCompletion.title`。中间原图在主名称后追加“（原图）/（原始输出）”，拆分图标仍使用各自素材描述。
 - 图片、视频和音频生成结果都要写入账号级素材库；视频 / 音频结果由后端持久化到 OSS 并回传 `objectKey` / `assetObjectId`，前端保存素材库时一并记录，后续预览和再次加入画布走统一换签链路。
 - 刷新项目后，画布需要同时恢复图层、生成器快照和生成输入框跟随关系。
@@ -160,11 +164,11 @@
 
 - 参考媒体只对 `seedance2.0-fast` / `seedance2.0` 开放；切换到 Kling 等非 Seedance 模型时，前端不提交 `referenceImageSrcs` / `referenceVideoSrcs` / `referenceAudioSrcs`，后端收到非 Seedance 参考字段必须拒绝。
 - 多模态参考按火山 Seedance 2.0 文档限制：参考图片 0~9 张，参考视频 0~3 个，参考音频 0~3 段；音频不可单独输入，必须至少搭配 1 张参考图片或 1 个参考视频。
-- 参考图片支持 URL / Base64 / `asset://` / 画板资源路径；格式为 jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30MB，请求体总大小不超过 64MB。
-- 参考视频只支持 URL / `asset://` / 画板资源路径，不支持 Base64 / `data:video/*`；格式为 mp4、mov，单个文件不超过 50MB，单个时长 [2, 15] 秒，最多 3 个且总时长不超过 15 秒。
-- 参考音频支持 URL / Base64 / `asset://` / 画板资源路径；格式为 wav、mp3，单个文件不超过 15MB，单个时长 [2, 15] 秒，最多 3 段且总时长不超过 15 秒。
-- 前端上传参考视频 / 参考音频必须走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 入库；前端状态保存 signed URL 供预览，同时保存 `objectKey` / `assetObjectId`，提交生成时优先使用 `objectKey`。
-- 后端接收画板资源 `objectKey` 后统一重新签名为 Ark 可读 URL，再按文档构造 `content`：`image_url` + `role=reference_image`、`video_url` + `role=reference_video`、`audio_url` + `role=reference_audio`。
+- 参考图片支持公网 URL、`asset://`、当前账号的 `objectKey`、项目资源 ID 或素材 ID；格式为 jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30MB，不接受 Base64 / Data URL / Blob URL。
+- 参考视频支持公网 URL、`asset://`、当前账号的 `objectKey`、项目资源 ID 或素材 ID；格式为 mp4、mov，单个文件不超过 50MB，单个时长 [2, 15] 秒，最多 3 个且总时长不超过 15 秒，不接受 Base64 / Data URL / Blob URL。
+- 参考音频支持公网 URL、`asset://`、当前账号的 `objectKey`、项目资源 ID 或素材 ID；格式为 wav、mp3，单个文件不超过 15MB，单个时长 [2, 15] 秒，最多 3 段且总时长不超过 15 秒，不接受 Base64 / Data URL / Blob URL。三类参考媒体最终提交的稳定引用字段总长度不得超过 `256KB`。
+- 前端本地参考媒体必须走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 入库；前端状态保存 signed URL 供预览，同时保存 `objectKey` / `assetObjectId`，提交生成时使用稳定引用。
+- 后端接收 `objectKey`、项目资源 ID 或素材 ID 后，先解析并校验对象属于当前 owner，再重新签名为 Ark 可读 URL，并按文档构造 `content`：`image_url` + `role=reference_image`、`video_url` + `role=reference_video`、`audio_url` + `role=reference_audio`。
 - 画板生成视频按静音 toggle 映射 Ark `generate_audio`：`sound=on` 时传 `true`，`sound=off` 时传 `false`，不能只依赖上游默认值。
 - Seedance 2.0 文档提示不支持直接上传含真人人脸的参考图 / 视频；当前画板尚未做真人脸授权证明、来源声明或服务端人脸拦截，后续开放真人素材前必须补授权/来源确认链路。
 
@@ -190,7 +194,7 @@
 - 生成视频 / 角色形象 / 角色动作 / 音效 / 背景音乐新建后，画布占位空白样式和右上角标签均与对应生成类型一致，不再统一使用图片占位 icon。
 - 新建空白待生成占位的尺寸必须和面板参数一致；图片类修改比例 / 尺寸、视频修改清晰度后，画布空白占位同步变更且保持中心点。
 - 点击角色图只选中图层并显示工具栏，不自动弹出重绘、快速编辑或角色动画面板；点击工具栏或右键菜单中的 `生成动画` 才创建角色动作占位和面板。
-- 点击 UI 设计图只选中图层并显示工具栏；工具栏在 `去除背景按钮` 后显示 `提取素材`，点击后画布自动缩放平移到素材完整展示，并在素材下方显示 UI 素材提取面板。UI 素材提取默认启用矩形框选，右侧工具栏与快速编辑统一，当前启用工具按钮保持高亮，点击同一工具可取消启用态；面板提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选截图预览、固定模型 `gpt-image-2`、计划规格和提取按钮泥点，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。用户至少框选一个区域后才能点击 `提取`，前端把红色轮廓绘入原图作为参考图，再固定用自动决策纯色背景素材提取提示词生成 spritesheet。框选数量不超过阈值时提交 `1:1·1K` 参数，超过阈值时提交 `1:1·2K` 参数；后端按 gpt-image-2 对应尺寸计算扣费，保存纯色背景源图后调用 BgFilter 按默认抠图模型 `birefnet` 透明化，并复用图标素材拆分流程，把透明 spritesheet 图集和拆分素材都放到画布。
+- 点击 UI 设计图只选中图层并显示工具栏；工具栏在 `去除背景按钮` 后显示 `提取素材`，点击后画布自动缩放平移到素材完整展示，并在素材下方显示 UI 素材提取面板。UI 素材提取默认启用矩形框选，右侧工具栏与快速编辑统一，当前启用工具按钮保持高亮，点击同一工具可取消启用态；面板提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选截图预览、固定模型 `gpt-image-2`、计划规格和提取按钮泥点，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。用户至少框选一个区域后才能点击 `提取`，前端把红色轮廓绘入原图作为参考图，再固定用自动决策纯色背景素材提取提示词生成 spritesheet。框选数量不超过阈值时提交 `1:1·1K` 参数，超过阈值时提交 `1:1·2K` 参数；后端按 gpt-image-2 对应尺寸计算扣费，保存纯色背景源图后调用 BgFilter 按默认抠图模型 `birefnet` 透明化。正常透明化成功时复用图标素材拆分流程，把透明 spritesheet 图集和拆分成功的素材放到画布；透明背景处理最终失败时只把 provider 原图放到画布，不继续拆分，并显示通用 warning。
 - 生成游戏音效面板底部不显示字段标题，左下角只有一个时长参数按钮，选项为 Vidu duration `2-10` 秒；右下角固定模型胶囊显示 `Vidu` 并紧贴生成按钮。
 - 生成游戏背景音乐面板右下角固定模型胶囊显示 `Suno` 并紧贴生成按钮；`make_instrumental` 不在 UI 中展示。
 - 生成视频结果以视频图层加入画布，画布媒体元素标记为 `画布视频：生成视频 N`。
diff --git a/docs/【编辑器】画布Agent对话面板-2026-07-03.md b/docs/【编辑器】画布Agent对话面板-2026-07-03.md
index 632598beb..bbb9f3286 100644
--- a/docs/【编辑器】画布Agent对话面板-2026-07-03.md
+++ b/docs/【编辑器】画布Agent对话面板-2026-07-03.md
@@ -1,6 +1,6 @@
 # 画布Agent对话面板
 
-日期：`2026-07-03`
+日期：`2026-07-16`
 
 ## 定位与边界
 
@@ -8,9 +8,9 @@
 - 它是画布域工具，**不承接玩法创作**、不产出玩法作品或模板，与 `CONTEXT.md` 中「表单/图片输入创作工作台」的 Avoid 边界不冲突。
 - 独立于拼图专用的 `/api/runtime/creative-agent/sessions`（该会话为 api-server 内存态、拼图领域专用，不复用）。
 
-## 能力范围（第一期）
+## 能力范围
 
-对话 Agent 可通过 function-calling 触发以下五类工具，全部复用既有计费收口接口：
+对话 Agent 可通过 function-calling 触发以下八类工具，全部复用既有计费收口接口：
 
 | 工具 | 后端接口 |
 | --- | --- |
@@ -19,19 +19,22 @@
 | 生成角色形象 | 既有角色形象生成入口对应接口 |
 | 生成图标素材 | `POST /api/editor/icon-spritesheets/generations` |
 | 生成 UI 设计图 | 既有 UI 设计图生成入口对应接口 |
+| 生成视频 | `POST /api/editor/videos/generations` |
+| 生成游戏音效 | `POST /api/editor/audios/sound-effects/generations` |
+| 生成背景音乐 | `POST /api/editor/audios/background-music/generations` |
 
 - 意图解析与工具编排在后端 api-server，前端只渲染状态，不承接业务规则。
 - 下面的工具选择口径属于 Agent 规划 prompt / function-calling 约束，不是侧边栏 UI 说明文案；侧边栏面板不展示这些规则解释。
 - 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
 - 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
 - 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
-- 视频 / 音频 / 图层操作等其余画板功能第一期不进入对话工具面，仍走现有面板。
+- 图层操作及其他未注册的画板功能第一期不进入对话工具面，仍走现有面板。
 
 ## 当前分支落地状态
 
-- 已落地：会话元数据、OSS 消息文档、会话 CRUD、SSE 消息流、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、停止当前 SSE 回合、附件从画布资源 / 账号素材库选择，以及五类图片工具对既有生成入口的复用。
-- 已落地：`tool_started` / `tool_completed` 事件携带 `status`；工具失败时也会写入失败 generation record，并随后发送 `stage=failed` 与 `error`，前端应保留消息内失败条目。
-- 未落地：附件弹窗末尾上传格、跨刷新异步生成恢复、external generation task 轮询回填。未落地前，对话消息状态只表示本次 SSE 回合记录，不作为后台任务队列真相。
+- 已落地：会话元数据、OSS 消息文档、会话 CRUD、带 `clientMessageId` 幂等键的普通 JSON 消息请求、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、附件从画布资源 / 账号素材库选择，以及八类图片 / 音视频工具对既有生成入口的复用。
+- 已落地：工具确认 / 取消、external generation task 轮询与会话懒回填。LLM 未配置、请求失败或规划结果解析失败时，后端把 `role=system`、正文以 `ERROR ` 开头的消息写入 OSS，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏 wire 前缀并以红色错误气泡展示。工具执行失败继续保存 `status=failed`、模型和错误信息，不能只返回瞬时错误。
+- 未落地：附件弹窗末尾上传格。`external_generation_job` 继续作为后台任务队列真相，对话消息只保存确认、回填状态和轻量媒体结果引用。
 
 ## 会话与持久化
 
@@ -39,24 +42,27 @@
 - SpacetimeDB 新表 `editor_agent_conversation` 只存会话元数据：会话 ID、projectId、ownerUserId、标题、软删标记、聊天记录 OSS 对象引用、创建/更新时间。
 - 完整消息内容存 OSS：`editor-agent/{conversationId}.json`，**会话粒度整体读写**（追加消息=重写对象），不按消息拆对象。
 - 不把对话塞进画布工程快照 payload，不在 api-server 内存中保存会话真相。
-- 会话标题：新会话默认「新对话」，首条用户消息发出后自动截取前 N 字作为标题；第一期不做手动重命名。
+- 会话标题：新会话默认「新对话」，首条含文本的用户消息发出后自动截取前 N 字作为标题；列表摘要、详情和消息回包均携带同一必填标题，前端只展示该标题，不以会话 ID 或本地推导兜底。标题写入失败会使该消息请求失败，不能静默继续。
 - 会话删除：列表项 hover 出删除按钮 + 确认；软删（表打 deleted 标记，OSS 对象保留）。
+- 每次用户主动发送生成一个最长 128 字符的 `clientMessageId`；`editorAgentClient` 对网络错误和通用瞬时状态码显式启用 1 次 POST transport 重试，重试复用同一个已序列化 body、`clientMessageId` 和 `x-request-id`。该字段独立于数字 `message.id` 并随用户消息写入 OSS。旧消息缺失时按 `None` 兼容；早期 SSE 文档若把客户端键存成用户消息字符串 `id`，读取时将其迁入 `clientMessageId`，同时重建数字定位符。后端在会话锁内检查重复键：内容一致时返回已持久化的同一回合结果，尚无结果时复用原用户消息继续规划；文本或附件身份不同则返回 `409`，不得再次追加用户消息或调用 LLM。
 
 ## 生成结果落画板（对现有占位规则的例外）
 
-- 对话入口触发的生成**不创建"即将生成"画布占位**（区别于其余生成面板）；生成中状态由对话消息流承载。
-- 生成完成后：结果图按统一 placement 避让模型（视口中心就近、避开现有图层、32px 间距）落画板为新图层，同时登记到默认项目素材库，并在对话消息内显示纯缩略图；前端收到 `generation_result` 后立即刷新工程快照与素材库，缩略图本身不显示名称也不承担图层跳转。
+- 对话入口触发的生成**不创建"即将生成"画布占位**（区别于其余生成面板）；生成中状态由工具消息和外部任务状态承载。
+- 生成完成后：结果图按统一 placement 避让模型（视口中心就近、避开现有图层、32px 间距）落画板为新图层，同时登记到默认项目素材库；前端轮询到任务终态并重新读取会话后，以回填的轻量媒体引用显示纯缩略图并刷新工程快照与素材库，缩略图本身不显示名称也不承担图层跳转。
 - 消息内生成结果缩略图必须携带并优先使用 `objectKey` / `assetObjectId`，前端通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签后渲染，不能把裸 `/generated-*` 私有路径直接交给 `<img>`。
-- 当前第一阶段通过既有编辑器生成 BFF 的 `canvasCompletion` 写回工程快照；刷新后异步任务恢复和轮询回填属于后续能力，不在本阶段声明为已完成。
+- 既有编辑器 worker 通过 `canvasCompletion` 写回工程快照；刷新后由 external generation task 状态和会话懒回填恢复结果。
 - 该例外已同步登记在《生成类面板Lovart统一改造方案-2026-06-17》「画布占位落点」节。
 
 ## 右侧布局
 
 - 对话框与既有任务侧栏（`ImageCanvasTaskSidebarView`）**互斥展开**：展开一个自动收起另一个；各自收起后保留入口按钮。
-- 对话框与左侧素材 / 图层侧栏也互斥：打开画布 Agent 时收起左侧栏；再次打开素材、图层或任务侧栏时收起 Agent 面板。
+- 对话框与左侧素材 / 图层侧栏**不互斥**，允许同时展开，便于在对话中选取和核对画布素材；左侧栏切换不改变 Agent 面板开关状态。
 - 桌面端对话框固定宽约 360–400px；移动端抽屉式全宽覆盖；收起态为胶囊/圆形入口按钮。
 - 会话管理入口在对话框头部：当前会话标题 + 历史会话下拉（按更新时间倒序）+ 新建对话按钮，全部包在对话框内。
-- 收起对话框只是隐藏面板，不卸载当前会话 hook；流式回复、`生成中` 阶段和停止按钮状态必须在收起 / 重新打开之间保持一致。
+- 快速切换会话或会话轮询刷新产生并发详情请求时，前端只允许最后发起的请求更新当前会话、消息、错误和加载态；旧响应不得覆盖用户最新选择。
+- 普通 JSON 消息请求的回包必须绑定发送时的会话：用户在等待期间切换到其他会话后，只更新原会话的列表摘要，不得把原会话的 `deltaMessages` 、错误或画布刷新副作用应用到当前面板。
+- 收起对话框只是隐藏面板，不卸载当前会话 hook；普通 JSON 消息请求的等待态和外部生成任务状态必须在收起 / 重新打开之间保持一致。
 
 ## 附件
 
@@ -68,11 +74,29 @@
 - 应用后附件以胶囊 chip 挂在输入框上方；发出的消息内附件渲染为纯文本胶囊 chip（名称 + 小图标），**默认无缩略图，鼠标悬浮才浮出缩略图预览**。
 - 附件领域形状：统一为画布资源 / 素材库对象引用（`resourceId` / `assetId` + 可选 `objectKey`），不存在只属于对话的第三种图；单条消息上限 9 张（前后端共同校验）。前端可携带展示用 `imageSrc` / `thumbnailSrc`，后端必须按当前工程和当前账号重新归一、校验归属与 `objectKey`。
 
+## 工具调用确认展示契约
+
+- Agent 规划出生成或编辑工具后，先把 `status=not_completed` 且没有 `externalJobId` 的工具消息持久化为待确认记录；确认卡必须在真正调用生成 provider 前展示本次提示词、规格参数、目标图和参考图缩略图，用户确认后才执行，取消后保留同一条 `status=cancelled` 记录。内部 system 文本和图片哈希 ID 不直接展示给用户。
+- 工具消息只保存 `status`（`not_completed` / `completed` / `failed` / `cancelled`）和可选 `externalJobId`。`external_generation_job` 仍是队列、执行、lease 与计费结算真相；OSS status 仅表示该条对话消息是否已经回填完成结果或失败，不复制 queued / running。
+- 确认接口必须先把工具参数转换为既有编辑器 worker payload，再使用 `editor-agent:{conversationId}:{messageId}:{toolName}` 稳定 dedupe key 入队；同一确认的请求重试只能得到同一个 external job。入队成功后把返回的 job id 写回同一条 OSS 工具消息，不新增 Agent 工具执行关联表。
+- 前端根据 `externalJobId` 查询通用 external-generation job 状态；worker 继续通过 `canvasCompletion` 把生成结果写回工程与素材库。浏览器断线、刷新或 api-server 重启不得导致确认接口重新扣费或重新提交 provider。
+- `GET /conversation` 会在同一个 conversation lock 内扫描 `status=not_completed` 且已有 `externalJobId` 的工具消息：只对这些消息按 job id 定向读取主任务；任务完成后复用对应工具的 `format_execute_message` 替换 system text、回填轻量图片 / 视频 / 音频引用并写为 `completed`，任务失败则回填 `error` 并写为 `failed`。任务结果读取或 completed payload 解析 / formatter 回填失败时，必须在同一次 GET 内完成首次尝试及最多 3 次重试，三次重试各间隔 100ms 并重新读取任务结果；仍失败才把该工具消息写为 `failed` 并保存最后错误。该重试不依赖前端再次刷新。排队和执行中都保持 `not_completed`，整轮扫描结果一次性写回 OSS。
+- `EditorAgentToolCall.args` 保留为工具返回的原始 JSON，是确认接口重新反序列化并执行工具的唯一参数真相。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId`；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey`、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
+- `EditorAgentToolCall.displayArgs` 是必填、只读的用户确认展示投影，与 `args` 分离：
+  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；
+  - `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与原始参数对应的 `imageId`，以及后端从已校验会话上下文解析出的 `objectKey`、`imageSrc`、可选 `thumbnailSrc` / `label` / `width` / `height`。
+  - `extras.priceMudPoints` 保存创建待确认消息时按后端运行时模型定价快照计算的预计泥点消耗；前端统一展示为“预计消耗 N泥点”，不自行计算价格。
+- `displayArgs` 只能由 api-server 按已注册 tool 白名单，基于已经通过 ToolArgs 校验的 `args` 和当前 OSS 会话文档中的附件 / 历史生成结果构建；不能信任 LLM 自报的展示地址、标题或素材元数据。展示投影不参与确认执行，确认接口仍只读取同一条持久化 tool call 的 `args`，避免“看到的素材”和“实际执行的素材”分叉。
+- `extras.priceMudPoints` 同样只属于展示投影，不作为扣费输入；确认后仍由既有生成 BFF 按后端运行时定价执行预扣费，因此该字段表达用户确认时看到的价格快照，而不是前端可提交或覆盖的计费真相。
+- `EditorAgentToolCall.summary` 只是 `args` 的重复字符串且没有稳定语义，当前契约删除该字段，不再作为展示或执行输入。
+- 前端待确认卡只消费必填 `displayArgs`，不解析各 tool 私有的 snake_case / camelCase schema，也不把 `sha256:*` ID 当标题或图片地址。图片统一通过 `ResolvedAssetImage` 使用 `objectKey` 换签后显示，签名 URL 不进入消息文档。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
+
 ## LLM 与计费
 
-- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册五类工具。
-- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、请求失败或返回格式不可解析时，后端写入明确错误消息，不使用本地关键词或“收到：...”回显兜底。
-- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册八类工具。
+- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、请求失败或返回格式不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。
+- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 工具参数中的图片 ID 是由真实 object key 或图片地址计算的稳定 SHA-256 标识；真实 data key 仅存于 api-server 的工具上下文映射，所有图片工具在执行时查表恢复，不能把 object key 或图片地址作为 LLM 可见的工具 ID。
 - 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，LLM 默认选择 `edit_image` 并引用 `latestGeneratedImage` 作为源图；除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `generate_image`。
 - 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate_image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
 - 画布 Agent 规划请求使用 Chat Completions、1024 `max_tokens` 和 60 秒 Agent 专用请求超时；生成图片/编辑图片仍走对应生成工具和模型计费。
@@ -83,13 +107,13 @@
 
 做（第一期）：
 
-1. 助手文本 SSE 流式输出；
-2. 阶段提示行（思考中 → 思考完成 → 生成中 → 完成/失败）；
+1. 助手文本随普通 JSON 消息响应一次性返回；
+2. 消息请求等待态，以及工具任务的待确认、生成中、完成 / 失败状态；
 3. 工具/模型标注行（生成时显示模型名 + 图标）；
 4. 消息内生成结果缩略图（纯预览，不显示名称，不点击聚焦图层）；
 5. 生成中的进行中动画；
 6. 错误气泡（失败/余额不足，带原因）；
-7. 发送中断：进行中时发送按钮变「停止」，可中断当前回合（已提交的生成任务不追回，照常落画板）。
+7. 普通消息请求等待期间禁用发送按钮，不提供客户端停止操作；前端持续等待后端响应，避免后端已持久化消息但前端中断请求后产生会话状态错位。
 
 不做（明确排除，防止后人补齐）：
 
@@ -113,22 +137,22 @@
 - `api-server`：
   - `GET/POST /api/editor/projects/{projectId}/agent-conversations`（列表/新建）；
   - `GET/DELETE /api/editor/agent-conversations/{conversationId}`（详情/软删）；
-  - `POST /api/editor/agent-conversations/{conversationId}/messages/stream`（SSE）；
+  - `POST /api/editor/agent-conversations/{conversationId}/messages`（JSON）；
   - Agent 编排（function-calling 循环、工具内部调既有生成执行链路）放 api-server 编排层，独立文件，不复用 `creative_agent.rs` 内存会话。
-- `shared-contracts` + `packages/shared`：新 `editorAgent` DTO 与 SSE 事件契约（`stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`）。
+- `shared-contracts` + `packages/shared`：`editorAgent` 会话、消息、工具确认展示与轻量媒体结果 DTO；消息响应返回 `conversation`、`deltaMessages` 和可选 `errorMessage`。
 
 ## 实施顺序
 
 1. 契约与领域规则（shared-contracts / packages/shared + module-editor-agent）；
 2. 存储层（spacetime-module 表 + procedure + migration + spacetime-client + schema check）；
-3. api-server 会话 CRUD + 消息 OSS 读写 + SSE 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
+3. api-server 会话 CRUD + 消息 OSS 读写 + JSON 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
 4. 前端最小纵切（对话框、会话管理、消息流、附件弹窗、侧边栏/小地图默认值）——可与 3 并行：3 只碰 `server-rs/`，4 只碰 `src/` 且先以契约 mock 客户端联调，汇合点在 4 末接真实 API；
-5. LLM 编排 + 五类工具接入 + 生成落画板 + 停止/错误态（替换回显桩这一个点）；
+5. LLM 编排 + 八类工具接入 + 生成落画板 + 请求等待 / 错误态（替换回显桩这一个点）；
 6. 验证与文档：定向测试、类型检查、`npm run check:encoding`、`git diff --check`、`npm run check:spacetime-schema`、api-server smoke `/healthz`；同步 `CONTEXT.md` 与相关文档。
 
 ## 第一阶段验收补充
 
-- 打开画布 Agent 后，任务侧栏和左侧素材 / 图层面板应关闭；再次打开任务侧栏或素材 / 图层面板时，Agent 面板应关闭。
-- 发送消息时先本地追加用户消息，再消费 SSE 增量；停止按钮只中断当前 SSE 回合，不追回已经提交的生成工具调用。
-- Agent 消息内生成结果缩略图只用于预览，不显示名称，也不点击跳转图层；收到 `generation_result` 时统一刷新工程快照和素材库。
+- 打开画布 Agent 后任务侧栏应关闭，再次打开任务侧栏时 Agent 面板应关闭；素材 / 图层面板与 Agent 可同时展开，互不改写开关状态。
+- 发送消息时先本地追加用户消息，再应用 JSON 响应中的 `deltaMessages`；请求等待期间发送按钮保持禁用，前端不主动中断当前回合。
+- Agent 消息内生成结果缩略图只用于预览，不显示名称，也不点击跳转图层；轮询到任务终态并完成会话懒回填后统一刷新工程快照和素材库。
 - 对话内容可被用户选中复制；用户从输入框或对话内容点击回画布图层 / 生成器时，焦点应回到画布对象，Backspace / Delete 等画布快捷键继续生效。
diff --git a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
index 829bf6f72..31a91bead 100644
--- a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
+++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
@@ -54,16 +54,16 @@
 - 框选状态参考微信截图工具栏布局，默认矩形框选，并支持矩形框选、椭圆框选和画笔自由框选三种工具。
 - 用户可在同一张 UI 设计图上多次框选；未至少框选一个区域时，工具栏 `提取` 按钮不可点击。
 - 可上传普通参考图辅助 UI 素材提取，用于约束被框选素材的风格、配色或材质；普通参考图会以 `objectKey` 随合成后的红框 UI 设计图一起提交。
-- 点击 `提取` 后，前端把所有框选的红色轮廓绘入原 UI 设计图，生成合成图片 Data URL，再提交到 `POST /api/editor/ui-designs/assets/extractions`。
+- 点击 `提取` 后，前端把所有框选的红色轮廓绘入原 UI 设计图生成合成图；Data URL / Blob URL 只允许停留在浏览器临时态，必须先上传 OSS 并确认 asset object，再以返回的 `objectKey`（或项目资源 / 素材 ID）作为 `sourceImageSrc` 提交到 `POST /api/editor/ui-designs/assets/extractions`。
 - 后端固定使用 `gpt-image-2` 图片编辑链路，并固定提示词：
 
 ```text
 仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用后端自动决策出的抠图背景色。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。
 ```
 
-- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS、项目资源和账号素材库，再调用 BgFilter 按默认 `segModel=birefnet` 透明化；透明 spritesheet 同样先进入 OSS、项目资源和账号素材库，再复用图标素材的连通域拆分能力。调用方未指定素材文件夹时落默认“项目”文件夹。
-- UI 素材自动拆分与图标图集一致，属于 best-effort 附加动作。未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`；识别或切片持久化失败仍返回整张透明图集和 `sliceWarning`，前端显示非阻断 warning toast，用户可手动重试。
-- 前端先把 spritesheet 原图作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分出的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布。图集图层同样提供 `拆分图集` 工具栏按钮，可使用相同连通域规则重新拆分。
+- 后端收到 spritesheet 后先把带解析后纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲，不克隆保留），写入项目资源和账号素材库；随后只持 object key。每次 BgFilter attempt 重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，默认 `segModel=birefnet`。BgFilter 主路径不重新下载原图；首次失败后立即重试 `1` 次（重试同样重新换签），第二次仍失败进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。透明背景处理正常成功时，透明 spritesheet 同样先进入 OSS、项目资源和账号素材库，再复用图标素材的连通域拆分能力；调用方未指定素材文件夹时落默认“项目”文件夹。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。
+- UI 素材自动拆分只在透明图集成功后执行，与图标图集一致，属于 best-effort 附加动作。未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`；识别或切片持久化失败仍返回整张透明图集和 `sliceWarning`，前端显示非阻断 warning toast，用户可手动重试。`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。
+- 正常透明化成功时，前端先把透明 spritesheet 作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分成功的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布；透明背景处理最终失败时只消费后端快照中的 provider 原图。透明图集图层提供 `拆分图集` 工具栏按钮，可使用相同连通域规则重新拆分。
 
 ## 验收点
 
@@ -72,5 +72,5 @@
 - 从画布选择时只能绑定图标规范图片。
 - 请求参数包含 `kind: "ui-design"`、`model: "gpt-image-2"`、比例、大小与可选参考图。
 - 上传普通参考图后，请求参考图数组同时包含图标规范和普通参考图，生成图层信息面板展示 `用户输入`、`图标规范` 与普通参考图。
-- 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后进入红框素材框选状态，至少框选一个区域后才能调用固定 `gpt-image-2` 提取接口，请求包含 `screenColor`，画布同时出现透明 spritesheet 图集和拆分后的独立素材。
+- 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后进入红框素材框选状态，至少框选一个区域后才能调用固定 `gpt-image-2` 提取接口，请求包含 `screenColor`。正常透明化和拆分成功时画布同时出现透明 spritesheet 图集和拆分后的独立素材；透明图集成功但拆分失败时只出现透明图集，透明背景处理最终失败时只出现 provider 原图并显示通用 warning。
 - UI 素材提取面板上传普通参考图后，提取请求参考图数组同时包含红框 UI 设计图和普通参考图，生成图层信息面板展示 `UI设计图` 与普通参考图。
diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
index 35fc3a1c8..9e1fc8946 100644
--- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
@@ -4,15 +4,15 @@
 
 ## 背景
 
-图片画布编辑器已有普通图片生成、生成规范、生成角色形象和角色动画入口。本次新增 `生成图标素材`，用于一次输入多条图标素材描述，生成一张纯色背景 spritesheet，在后端去背景后自动拆分为可独立编辑的素材。
+图片画布编辑器已有普通图片生成、生成规范、生成角色形象和角色动画入口。本次新增 `生成图标素材`，用于一次输入多条图标素材描述，生成一张纯色背景 spritesheet；后端去背景正常成功后，再尝试自动拆分为可独立编辑的素材。
 
 ## 入口与画布表现
 
 - 底部 AI 画布工具栏新增 `生成图标素材` 按钮。
 - 点击后立即在画布中心创建图标素材占位图，不复用普通“单张空白图片”图标；占位图表现为一叠空白素材图标卡片。
-- 图标素材占位图使用 `360x360` 的画布展示尺寸和 `512x512` 的原始图集尺寸；面板中的模型、比例和尺寸仍按生成契约独立提交，不用通用图片生成的 `1K` 画布外框。
+- 图标素材占位图必须按当前模型、比例和 K 档对应的真实 provider 请求像素初始化；切换参数后继续保持占位尺寸与请求尺寸一致，不得用固定 `360x360 / 512x512` 框代替生成目标。
 - 图标素材面板锚定在占位图下方，和现有生成输入框同一层级展示。
-- 生成完成后删除占位态，把后端返回的透明 spritesheet 作为 `assetKind: "icon-spritesheet"` 的图集图层放到画布，并把按 alpha 连通域拆出的 `assetKind: "icon"` 素材铺到图集右侧。
+- 透明背景处理正常成功后删除占位态：透明 spritesheet 作为主图（`assetKind: "icon-spritesheet"`，`generatedLayerId` 锚点）放入画布，provider 带背景原图作为第二个同类型图层放在透明主图右侧，按 alpha 连通域成功拆出的 `assetKind: "icon"` 素材从原图右侧继续铺放；透明背景处理最终失败时，后端完成快照只用 provider 原图替换占位态。
 - 选中 `assetKind: "icon-spritesheet"` 图层时，图片浮动工具栏显示 `拆分图集`；手动拆分只追加独立素材，不复制原图集。
 - 图标规范图写入 `assetKind: "icon-spec"`，用于刷新后保留标签和限制点选来源。
 
@@ -38,15 +38,15 @@
 
 - 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
 - 请求字段：
-  - `referenceImageSrc`：图标规范 Data URL。
+  - `referenceImageSrc`：图标规范的稳定引用（当前账号的 `objectKey`、项目资源 ID 或素材 ID）；本地临时图必须先上传 OSS，禁止 Data URL / Blob URL。
   - `iconDescriptions`：过滤空文本后的图标描述数组，`1..100`。
   - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
   - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
   - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
   - `priceMudPoints`：按当前模型和尺寸从编辑器生成计费配置计算；`nanobanana2 1K` 为 `12`，`gpt-image-2 1K` 为 `3`、`gpt-image-2 2K` 为 `5`。前端只提交配置函数计算值，后端用 `editor_generation_config` 校验，不允许素材生成面板自行写死价格。
 - 模型与尺寸选项：
-  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
-  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/edits`，把图标规范图作为 multipart `image`，按 `size` 映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+  - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/edits`，把图标规范图作为 multipart `image`。K 档按最长边计算，并转换为 provider 可直接生成的合法像素：`1K` 的 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9` 分别为 `1024x1024 / 1024x768 / 1024x688 / 688x1024 / 608x1088 / 1088x608`；`2K` 分别为 `2048x2048 / 2048x1536 / 2048x1376 / 1376x2048 / 1152x2048 / 2048x1152`。其中 9:16 的 1K 尺寸按 provider 最小总像素和 16 对齐约束修正。禁止把 2K 竖图回落为 1K 请求，也禁止在回图后放大伪造所选 K 档。
 - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
 - 不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端在组装 prompt 前把 `auto` 自动决策为具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`，最终 prompt 和 BgFilter 不透传 `auto`。
 - Prompt 固定为：
@@ -59,17 +59,17 @@
 
 ## 去背与保存
 
-- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 透明化；请求字段包含 `screenColor` 和 `segModel`，前端用户路径固定提交 `screenColor=auto` 与默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
-- 带背景原图和去背后的透明 spritesheet 都先同时写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。
-- 自动拆分是生成后的 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；前端在 inline、worker 队列完成和刷新恢复三条路径统一显示 warning toast，用户可在图集工具栏手动重试。
+- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲，再签发 600 秒 GET URL 调用 BgFilter 透明化；BgFilter multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。
+- 透明背景处理正常成功时，带背景原图和去背后的透明 spritesheet 都先写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；若 BgFilter 返回较小图集，只把 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不放大低分辨率后处理成品。画布完成快照同时写入透明主图与右侧 provider 原图（二者均已登记为 project resource / 账号素材），`generatedLayerId` 仍锚定透明主图；成功拆出的切片从 provider 原图右侧继续排列。调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。
+- 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
 - 响应通过 `iconImageSrcs` 返回成功切片素材；自动生成使用用户输入的素材描述命名，UI 设计提取和手动拆分按从上到下、从左到右自动命名为 `素材 N`。
 - 手动拆分调用 `POST /api/editor/icon-spritesheets/slices`，只允许读取当前用户项目中的 `icon-spritesheet` 资源，不调用图片生成 provider，不扣除泥点。输入限制为单边最多 `4096` 像素、总像素最多 `2048×2048`，单次最多持久化 `64` 个切片；超限在任何切片写入前拒绝。
 
 ## 前端铺放规则
 
-- spritesheet 图集放在原占位图位置附近。
-- 自动拆分素材从图集右侧开始换行铺放；手动拆分使用相同布局，但保留原图集不变。
-- 生成成功后关闭图标素材面板，选中 spritesheet 图集，并打开图层面板。
+- 透明 spritesheet 主图放在原占位图位置附近；provider 带背景原图放在透明主图右侧。
+- 自动拆分素材从 provider 原图右侧开始换行铺放；手动拆分使用相同布局，但保留原图集不变。
+- 生成成功后关闭图标素材面板，选中透明 spritesheet 主图，并打开图层面板。
 
 ## 验收
 
@@ -78,7 +78,7 @@
 - 默认 6 个素材描述会进入 prompt；用户在单个文本框中继续输入时最多解析 100 个素材描述。
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
-- 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，上传参考图优先提交 `objectKey`，并写入 `generationInputs.references`。
-- 生成成功后画布同时出现透明 spritesheet 图集和按描述命名的独立图标图层。
-- 选中图集图层时显示 `拆分图集`，点击后不新增第二张图集，只在原图集右侧追加自动识别的独立素材，并同步写入素材库。
+- 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，二者都必须是稳定引用（`objectKey` / 项目资源 ID / 素材 ID），禁止 Data URL / Blob URL，并写入 `generationInputs.references`。
+- 透明背景处理和自动拆分都成功后，画布同时出现透明 spritesheet 主图、其右侧的 provider 原图，以及从原图右侧铺开的按描述命名的独立图标图层；透明图集成功但拆分失败时仍出现透明主图与右侧原图，透明背景处理最终失败时只出现 provider 原图。
+- 选中透明图集图层时显示 `拆分图集`；点击后源图集显示扫描蒙层与 `拆图中` 状态，工具栏按钮同步切换为旋转图标和 `拆图中` 并禁用重复提交。完成后恢复工具栏，不新增第二张图集，只在 provider 原图右侧追加自动识别的独立素材，并同步写入素材库。
 - 生成图标素材提交体包含按模型和尺寸计算的 `priceMudPoints`；`nanobanana2 1K` 应为 `12`，`gpt-image-2 1K` 应为 `3`，`gpt-image-2 2K` 应为 `5`。若前端传入与后端计费配置不一致的值，后端返回 `priceMudPoints` 校验错误，不继续调用上游生成。
diff --git a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
index 374c65796..057f22910 100644
--- a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
@@ -55,8 +55,8 @@
   - 前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，不从生成器快照或输入快照恢复旧手动背景色 / 抠图模型。后端在组装 prompt 前把 `auto` 自动决策为具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`；调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
   - 比例按 `x:y` 展示；大小按 `0.5K / 1K / 2K` 展示。
 - 尺寸选项来源以 VectorEngine 接入文档为准：
-  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。
-  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/generations` 或 `/v1/images/edits`，按文档尺寸映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+  - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/generations` 或 `/v1/images/edits`。K 档按最长边计算，并转换为 provider 可直接生成的合法像素：`1K` 的 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9` 分别为 `1024x1024 / 1024x768 / 1024x688 / 688x1024 / 608x1088 / 1088x608`；`2K` 分别为 `2048x2048 / 2048x1536 / 2048x1376 / 1376x2048 / 1152x2048 / 2048x1152`。其中 9:16 的 1K 尺寸按 provider 最小总像素和 16 对齐约束修正。禁止把 2K 竖图回落为 1K 请求，也禁止在回图后放大伪造所选 K 档。
 - 后端如果收到参考图，`nanobanana2` 把参考图作为 `inline_data` 传入原生 `generateContent`；`gpt-image-2` 走带多参考图的图片编辑链路。没有参考图时按所选模型走纯文本生成链路。
 - `kind = "character"` 时，后端不直接把前端文本当完整生图提示词，而是把文本作为 `角色设定` 填入固定提示词骨架：
 
@@ -65,8 +65,8 @@
 角色设定：<用户输入的角色设定>
 ```
 
-- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图写入 OSS，再调用独立 BgFilter 服务透明化：multipart 字段包含 `file`、`screen_color=<screenColor>` 和 `seg_model=<segModel>`，用户路径默认并只提交 `seg_model=birefnet`。这里的 `seg_model=birefnet` 是 BgFilter 管线内部后端，不等同于手动去背景使用的独立 BiRefNet 服务。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不调用手动去背景的独立 BiRefNet；输出仍统一为透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`。接口回包仍返回透明 PNG Data URL 供画板立即显示，同时返回 `objectKey` / `assetObjectId`，前端创建图层和画板资源记录时必须保存这些字段。
-- 对 `assetKind: "character"` 的角色图层执行 `重绘` 时，前端仍使用原图作为参考图，但请求 `kind` 必须传 `character`，让后端继续套用上述角色提示词限定、角色图后处理和角色资产持久化；普通图片图层重绘仍保持 `kind: "quick-edit"`。
+- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图 owned 上传私有 OSS（消费图片字节所有权，上传完成后释放原图缓冲），再对 object key 签发 600 秒 GET URL 调用共享 BgFilter 服务透明化。BgFilter 主路径不重新下载原图；每次 HTTP attempt 重新换签，multipart 字段包含 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=on`，不包含 `file`，用户路径默认并只提交 `seg_model=birefnet`；`flat` 明确表示单一纯色背景抠图模式，`birefnet` 是 BgFilter 管线内部后端。首次请求失败后立即重试 `1` 次，第二次仍失败进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。角色图 prompt 按 `screenColor` 写入颜色名称、hex 和 RGB。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不复用手动去背景的 `background_mode=complex` 路径。透明背景处理正常成功时，输出透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`；接口回包返回 `imageSrc: "/<objectKey>"`、`objectKey`、`assetObjectId` 及资源快照，画布同时写入透明主结果和 provider 原图，生成器 `generatedLayerId` 锚定透明主结果，provider 原图作为第二个图层放在其右侧。三段透明背景处理最终仍失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建不存在的透明处理图；通用 `warning.code/reason` 携带完整降级原因。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。前端创建图层和画板资源记录时必须保存最终回包对应的媒体引用。
+- 对 `assetKind: "character"` 的角色图层执行 `重绘` 时，前端仍使用原图作为参考图，但请求 `kind` 必须传 `character`，让后端继续套用上述角色提示词限定、角色图后处理和角色资产持久化；透明背景正常成功与最终失败保留 provider 原图的收口规则和角色新生成一致。普通图片图层重绘仍保持 `kind: "quick-edit"`。
 
 ## 生成规范参考图
 
@@ -114,7 +114,7 @@
 - 角色生成提交统一走 `/api/editor/images/generations`，按 `角色规范 -> 常规参考图` 顺序传 `referenceImageSrcs`，并写入 `assetKind: "character"`。
 - 角色图层重绘同样走 `/api/editor/images/generations` 的 `kind: "character"` 分支，原图作为参考图提交，生成结果继续保留 `assetKind: "character"`。
 - 角色和图标素材生成已接入 `nanobanana2` / `gpt-image-2` 模型切换、上次模型记忆，以及按模型归一的比例 / 大小尺寸；`nanobanana2` 使用原生 `generateContent` 的 `imageConfig.aspectRatio/imageSize`，`gpt-image-2` 使用文档列出的 `size` 字符串。
-- 角色生成后端已按固定 prompt 骨架补入 `角色设定` 和自动决策纯色抠图背景，并在生成成功后先保存纯色背景源图，再通过 BgFilter 按用户路径默认 `segModel=birefnet` 执行透明化、写入 `generated-character-drafts/editor/character-images/<taskId>/image.png` 路径下的 OSS 私有对象，返回的 `objectKey` / `assetObjectId` 会随画板资源记录保存。
+- 角色生成后端已按固定 prompt 骨架补入 `角色设定` 和自动决策纯色抠图背景，并在生成成功后先保存纯色背景源图，再通过 BgFilter 按用户路径默认 `segModel=birefnet` 执行透明化；透明化成功时把处理图写入 `generated-character-drafts/editor/character-images/<taskId>/image.png` 路径下的 OSS 私有对象，并把透明主结果与其右侧 provider 原图一起写入画布，`generatedLayerId` 仍锚定透明主结果；最终失败时则只保留并返回已经持久化的 provider 原图和通用 warning。若 BgFilter 返回较小图片，只允许把其 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不得放大低分辨率透明成品。最终回包的 `objectKey` / `assetObjectId` 会随画板资源记录保存。
 - `Esc` 只退出角色规范画布点选状态，不关闭角色生成面板。
 - 已补充回归测试覆盖角色形象生成、点选退出、角色动画入口隔离和快速编辑入口。
 - 本次验证命令：
@@ -147,9 +147,9 @@
 ### Prompt 与生成契约
 
 - 前端提交到 `POST /api/editor/character-animations/generations`。
-- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长，并可通过 `assetFolderId` 指定中间视频素材落点。角色图片已经持久化到 OSS 时，`sourceImageSrc` 必须优先传 `objectKey`；只有未持久化的本地临时图片才允许传 Data URL。
+- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长，并可通过 `assetFolderId` 指定中间视频素材落点。`sourceImageSrc` 只允许传当前账号的 `objectKey`、项目资源 ID 或素材 ID；未持久化的本地临时图片必须先上传 OSS，不能提交 Data URL 或 Blob URL。后端解析稳定引用后必须校验对象属于当前 owner，再读取 OSS 内容。
 - 后端使用角色图片作为首帧和尾帧参考，模型固定映射到 `doubao-seedance-2-0-fast-260128`。
-- 后端路由兼容旧 Data URL 请求并单独放宽 JSON body limit 到 `12MB`，但该限额只作为兼容兜底，不作为新链路默认传大图的方式。
+- 后端在内联执行和队列入队前都会拒绝 Data URL / Blob URL；路由使用默认 JSON body limit，不再为内联图片请求单独放宽。
 - 后端 prompt 使用以下固定骨架，并把面板输入追加到 `动作描述：` 后：
 
 ```text
@@ -162,7 +162,8 @@
 
 - 视频生成完成后，后端先把带纯色背景的预览视频登记为 OSS 私有对象、`asset_object`、项目资源和账号素材，再按面板选择抽取对应帧数：`32`、`40` 或 `48`。未传 `assetFolderId` 时进入默认“项目”素材文件夹；后续抽帧或抠图失败不能抹掉这份已经生成成功的可恢复视频。
 - 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。
-- 每帧必须先把带自动决策纯色背景的源图写入 OSS，再优先调用阿里云通用抠图输出透明背景 PNG；阿里云失败时降级执行本地 `editor_green_screen`，并按同一次生成已选定的 `screenColor` 去背。
+- 每帧绿幕源图字节由上传 owned 消费（`frame.bytes` 移入 put，上传完成后释放原帧缓冲，不克隆保留）；后续只持 object key。每次 BgFilter attempt 重新签发 600 秒 GET URL，multipart 仅传 `image_url`（加 `background_mode=flat`、`seg_model=birefnet`、`cross_check=on` 与同一次生成已选定的 `screenColor`），不传 `file`。BgFilter 主路径不重新下载原帧；失败后走 `阿里云通用抠图（按签名 URL 单独下载）→ 本地 editor_green_screen（再按 object key 独立下载一次并在产出后释放）`。BgFilter 每一次 HTTP attempt 的 timeout 使用“`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧分别为 `244000 / 260000 / 276000ms`；首次失败后重试 `1` 次。
+- 全部 `32 / 40 / 48` 帧以覆盖本次所有帧的无序在途集合连续发射，允许乱序完成并最终按 `frameIndex` 排序；任一帧最终失败时先排空全部已启动 Future，再让整项任务失败退款，不发布缺帧动画。
 - 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
 - 画板前端回填角色动作结果时，必须以 `frames[0].imageSrc` 创建 `mediaType: "image-sequence"`、`assetKind: "character-animation"` 图层，并把完整 `frames` 保存为图层 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。
 - 角色动作图层在画布中使用序列帧播放器循环展示透明 PNG 帧；刷新恢复时必须继续读取 `imageSequenceFrames`，不能回退到 `<video>` 预览。
diff --git a/jenkins/Jenkinsfile.production-api-build b/jenkins/Jenkinsfile.production-api-build
index a2de704af..c3e8d7608 100644
--- a/jenkins/Jenkinsfile.production-api-build
+++ b/jenkins/Jenkinsfile.production-api-build
@@ -125,7 +125,11 @@ pipeline {
               echo "[api-build] 未找到 sccache，改用 rustc 直接构建。"
               unset RUSTC_WRAPPER
             fi
+            npm run check:encoding
             npm run check:rustfmt
+            npm run check:production-ops
+            npm run check:server-rs-ddd
+            cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml
             pingora_args=()
             if [[ "${INCLUDE_PINGORA_GATEWAY:-false}" == "true" ]]; then
               pingora_args+=(--include-pingora-gateway)
diff --git a/jenkins/Jenkinsfile.production-server-provision b/jenkins/Jenkinsfile.production-server-provision
index e59a82fa9..4163a132b 100644
--- a/jenkins/Jenkinsfile.production-server-provision
+++ b/jenkins/Jenkinsfile.production-server-provision
@@ -25,7 +25,7 @@ pipeline {
     string(name: 'PROVISION_DOWNLOADS_DIR', defaultValue: 'provision-tool-downloads', description: '目标服务器工作区内暂存 SpacetimeDB/otelcol 安装包的相对目录')
     string(name: 'PROVISION_TOOLS_DIR', defaultValue: 'provision-tools', description: '目标机工作区内由已下载安装包生成的工具包目录')
     string(name: 'PROVISION_DOWNLOAD_PROXY', defaultValue: '', description: '可选，目标服务器下载 SpacetimeDB 和 otelcol-contrib 时使用的代理地址，例如 http://127.0.0.1:7890；留空不设置代理')
-    string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.0', description: '目标服务器使用的 SpacetimeDB Linux release tarball 根地址；默认固定到项目锁定版本')
+    string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.1', description: '目标服务器使用的 SpacetimeDB Linux release tarball 根地址；默认固定到项目锁定版本')
     string(name: 'SPACETIME_TARGET_HOST', defaultValue: 'x86_64-unknown-linux-gnu', description: 'SpacetimeDB 预编译包 host triple，development/release Linux amd64 使用默认值')
     string(name: 'SPACETIME_ROOT', defaultValue: '/stdb', description: 'SpacetimeDB root-dir')
     string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: 'release 根目录')
@@ -33,6 +33,8 @@ pipeline {
     string(name: 'WEB_LINK', defaultValue: '/srv/genarrative/web', description: 'Nginx 静态站点目录或软链接')
     string(name: 'API_ENV_FILE', defaultValue: '/etc/genarrative/api-server.env', description: 'api-server 环境文件')
     string(name: 'API_PORT', defaultValue: '8082', description: 'api-server 本机监听端口')
+    choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-history'], description: '数据库定时备份 profile；默认 archive-full，files-history 仅在指定 work-dir 已有完整 full baseline 后启用')
+    string(name: 'DATABASE_BACKUP_FILES_HISTORY_WORK_DIR', defaultValue: '/var/lib/genarrative/database-backups/files-history', description: 'files-history 的本地 state/catalog 目录；dev/release 必须使用各自已建立 full baseline 的独立目录')
     choice(name: 'NGINX_CONFIG_MODE', choices: ['none', 'production-https', 'development-http'], description: 'Nginx 配置模式；开发服无域名时选 development-http，release 正式入口选 production-https')
     booleanParam(name: 'ENABLE_SERVICES', defaultValue: true, description: '启用并启动 spacetimedb 与 api-server systemd 服务')
     booleanParam(name: 'ENABLE_OTELCOL', defaultValue: true, description: '安装并启用本机 OpenTelemetry Collector；api-server 模板默认开启 OTLP，如需关闭请在 API_ENV_FILE 中将 GENARRATIVE_OTEL_ENABLED 改为 false')
@@ -103,6 +105,14 @@ pipeline {
           if (params.DEPLOY_TARGET == 'release' && nginxMode == 'development-http') {
             error('release 目标禁止安装 development-http Nginx 配置；无证书初始化请使用 NGINX_CONFIG_MODE=none。')
           }
+          def databaseBackupProfile = params.DATABASE_BACKUP_PROFILE?.trim()
+          if (!(databaseBackupProfile in ['archive-full', 'files-history'])) {
+            error("DATABASE_BACKUP_PROFILE 只能是 archive-full 或 files-history，当前值: ${params.DATABASE_BACKUP_PROFILE}")
+          }
+          def databaseBackupFilesHistoryWorkDir = params.DATABASE_BACKUP_FILES_HISTORY_WORK_DIR?.trim()
+          if (!(databaseBackupFilesHistoryWorkDir ==~ /^\/var\/lib\/genarrative\/database-backups\/[A-Za-z0-9._\/-]+$/) || databaseBackupFilesHistoryWorkDir.contains('..')) {
+            error("DATABASE_BACKUP_FILES_HISTORY_WORK_DIR 必须是 /var/lib/genarrative/database-backups/ 下不含连续点号的绝对路径，当前值: ${params.DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}")
+          }
           if (!params.DRY_RUN && nginxMode == 'production-https' && params.SERVER_NAME?.trim() == 'genarrative.example.com') {
             error('真实初始化安装 Nginx 配置时必须把 SERVER_NAME 改成真实域名，不能使用 genarrative.example.com 占位值。证书未准备好时请先保持 NGINX_CONFIG_MODE=none。')
           }
@@ -199,7 +209,7 @@ BASH
                 OTELCOL_VERSION="${OTELCOL_VERSION:-0.151.0}" \
                 PREPARE_OTELCOL="${ENABLE_OTELCOL:-true}" \
                 PROVISION_DOWNLOAD_PROXY="${PROVISION_DOWNLOAD_PROXY:-}" \
-                SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.0}" \
+                SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.1}" \
                 SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}" \
                 SPACETIME_ROOT="${SPACETIME_ROOT:-/stdb}" \
                 scripts/prepare-server-provision-tools.sh
diff --git a/jenkins/Jenkinsfile.production-stdb-module-build b/jenkins/Jenkinsfile.production-stdb-module-build
index 2383e2420..3f3894c68 100644
--- a/jenkins/Jenkinsfile.production-stdb-module-build
+++ b/jenkins/Jenkinsfile.production-stdb-module-build
@@ -129,7 +129,11 @@ pipeline {
                   echo "[stdb-build] 未找到可用 sccache，改用 rustc 直接构建。"
                   unset RUSTC_WRAPPER
                 fi
+                npm run check:encoding
                 npm run check:rustfmt
+                npm run check:production-ops
+                npm run check:server-rs-ddd
+                npm run check:admin-account-procedures
                 SOURCE_BRANCH="${SOURCE_BRANCH}" SOURCE_COMMIT="${SOURCE_COMMIT}" \
                 npm run build:production-release -- --component spacetime-module --name "${EFFECTIVE_BUILD_VERSION}"
               '
diff --git a/jenkins/Jenkinsfile.production-web-build b/jenkins/Jenkinsfile.production-web-build
index b53b13b9f..9a543a9a6 100644
--- a/jenkins/Jenkinsfile.production-web-build
+++ b/jenkins/Jenkinsfile.production-web-build
@@ -95,6 +95,12 @@ pipeline {
         sh '''
           bash -lc '
             set -euo pipefail
+            npm run check:encoding
+            npm run check:production-ops
+            npm run lint:eslint
+            npm run typecheck
+            npm run admin-web:typecheck
+            npm run test
             SOURCE_BRANCH="${SOURCE_BRANCH}" SOURCE_COMMIT="${SOURCE_COMMIT}" \
             npm run build:production-release -- --component web --name "${EFFECTIVE_BUILD_VERSION}"
           '
diff --git a/logs/codex-mobile-dock-fix.png b/logs/codex-mobile-dock-fix.png
deleted file mode 100644
index 3d22149f5..000000000
Binary files a/logs/codex-mobile-dock-fix.png and /dev/null differ
diff --git a/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.input.json b/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.input.json
deleted file mode 100644
index 1d5b16b8f..000000000
--- a/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.input.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-  "provider": "ark",
-  "model": "doubao-1-5-pro-32k-character-250715",
-  "stream": true,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是一个负责和创作者共创拼图画面的中文创意策划。\n\n你要帮助用户把一句灵感逐步收束成可以发布成拼图关卡的视觉方案。\n\n你必须同时输出：\n1. 一段直接发给用户的中文回复 replyText\n2. 当前进度 progressPercent\n3. 下一轮完整可用的 nextAnchorPack\n\n硬约束：\n1. 只能输出 JSON，不能输出代码块或解释\n2. nextAnchorPack 必须是完整对象，不能只输出 patch\n3. replyText 必须是自然中文，不能提“字段”“锚点”“结构”“JSON”等内部词\n4. replyText 一次最多推进一个最关键问题\n5. 如果用户已经给出明确方向，就优先吸收和收束，不要机械反问\n6. progressPercent 范围只能是 0 到 100\n7. status 只能使用 missing / inferred / confirmed / locked\n\n\n模板目标：收束成可以发布为拼图关卡的视觉方案。\n\n本模板只通过以下锚点问题体现差异：\n1. 题材承诺（themePromise / 拼图共创）：这张拼图给玩家的题材和完成期待是什么？；达成效果：明确拼图主题、辨识度和完成后的满足感。\n2. 画面主体（visualSubject / 拼图共创）：画面中最需要被玩家一眼看懂的主体是什么？；达成效果：明确主体、层级和可被切片识别的形状。\n3. 视觉气质（visualMood / 拼图共创）：整体色彩、光线、情绪和美术风格是什么？；达成效果：收束画面风格，避免结果图风格漂移。\n4. 拼图记忆点（compositionHooks / 拼图共创）：哪些构图、纹理或局部细节会成为玩家拼接线索？；达成效果：提供适合拼图玩法的边缘、块面和局部记忆点。\n5. 标签与禁忌（tagsAndForbidden / 拼图共创）：需要保留哪些关键词，又必须避开什么内容？；达成效果：锁定生成标签和负向约束。\n\n用户刚刚主动要求你自动补充剩余关键字。\n\n这表示用户接受你基于当前方向自行补完仍缺失的关键设定：当前题材方向里的拼图关键词\n\n本轮要求：\n1. 不要再继续提问\n2. 不要要求用户再提供素材、风格或禁忌\n3. 必须保留已有已确认内容，并直接补齐缺失或仍为空的关键项\n4. 对你自行推断补齐的项，应标记或表达为系统推断；已有明确内容继续保持确认或锁定状态\n5. progressPercent 直接输出为 100\n6. 输出完整 nextAnchorPack，直接补齐 value 为空或 status 为 missing 的项\n7. replyText 只做简短完成说明，引导用户可以生成结果页，不能出现问号\n\n当前是第 3 轮，当前进度 10% 。\n\n是否要求自动补充剩余关键字：是\n\n当前 anchor pack：\n{\n  \"theme_promise\": {\n    \"key\": \"themePromise\",\n    \"label\": \"题材承诺\",\n    \"value\": \"可爱小狗的温馨瞬间\",\n    \"status\": \"Missing\"\n  },\n  \"visual_subject\": {\n    \"key\": \"visualSubject\",\n    \"label\": \"画面主体\",\n    \"value\": \"\",\n    \"status\": \"Missing\"\n  },\n  \"visual_mood\": {\n    \"key\": \"visualMood\",\n    \"label\": \"视觉气质\",\n    \"value\": \"\",\n    \"status\": \"Missing\"\n  },\n  \"composition_hooks\": {\n    \"key\": \"compositionHooks\",\n    \"label\": \"拼图记忆点\",\n    \"value\": \"\",\n    \"status\": \"Missing\"\n  },\n  \"tags_and_forbidden\": {\n    \"key\": \"tagsAndForbidden\",\n    \"label\": \"标签与禁忌\",\n    \"value\": \"\",\n    \"status\": \"Missing\"\n  }\n}\n\n最近聊天记录：\n[\n  {\n    \"content\": \"先告诉我你想做一张什么样的拼图图像，我会帮你收束成可发布的题材锚点。\",\n    \"kind\": \"chat\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"可爱小狗\",\n    \"kind\": \"chat\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"可爱小狗确实是很受欢迎的拼图主题，那你希望这张拼图里的小狗在做什么呢？是玩耍、睡觉，还是其他的状态？\",\n    \"kind\": \"chat\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"请补充剩余设定。\",\n    \"kind\": \"chat\",\n    \"role\": \"user\"\n  }\n]\n\n请严格按以下 JSON 输出，不要输出其他文字：\n{\n  \"replyText\": \"\",\n  \"progressPercent\": 0,\n  \"nextAnchorPack\": {\n    \"themePromise\": {\n      \"key\": \"themePromise\",\n      \"label\": \"题材承诺\",\n      \"value\": \"\",\n      \"status\": \"missing\"\n    },\n    \"visualSubject\": {\n      \"key\": \"visualSubject\",\n      \"label\": \"画面主体\",\n      \"value\": \"\",\n      \"status\": \"missing\"\n    },\n    \"visualMood\": {\n      \"key\": \"visualMood\",\n      \"label\": \"视觉气质\",\n      \"value\": \"\",\n      \"status\": \"missing\"\n    },\n    \"compositionHooks\": {\n      \"key\": \"compositionHooks\",\n      \"label\": \"拼图记忆点\",\n      \"value\": \"\",\n      \"status\": \"missing\"\n    },\n    \"tagsAndForbidden\": {\n      \"key\": \"tagsAndForbidden\",\n      \"label\": \"标签与禁忌\",\n      \"value\": \"\",\n      \"status\": \"missing\"\n    }\n  }\n}"
-    },
-    {
-      "role": "user",
-      "content": "请按约定输出这一轮的 JSON。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.output.txt b/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.output.txt
deleted file mode 100644
index 160344688..000000000
--- a/logs/llm-raw/1777207823146-31804-000001-read_stream_failed.output.txt
+++ /dev/null
@@ -1,536 +0,0 @@
-data: {"choices":[{"delta":{"content":"{","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"reply","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Text","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"好","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"根据","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"你的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"要求","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"我","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"为","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"你","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"补齐","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"了","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"拼图","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"设定","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"主题","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"是","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"‘","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"可爱","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"小狗","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"温馨","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"瞬间","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"’","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"画面","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"主体","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"是","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"一只","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"正在","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"打","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"盹","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"金毛","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"犬","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"躺在","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"柔软","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"地毯","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"上","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"旁边","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"有","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"一个","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"毛绒","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"玩具","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"视觉","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"气质","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"是","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"温暖","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"柔和","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"色调","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"整体","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"给","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"人","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"一种","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"温馨","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"舒适","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"感觉","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"拼图","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"记忆","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"点","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"可以","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"是","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"小狗","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"轮廓","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"毛发","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"纹理","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"玩具","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"形状","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"和","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"颜色","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"等","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"标签","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"为","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"‘","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"小狗","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"’","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"‘","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"温馨","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"’","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"‘","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"可爱","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"’","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"禁忌","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"是","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"避免","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"出现","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"血腥","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"暴力","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"、","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"恐怖","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"等","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"内容","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"你","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"可以","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"根据","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"这些","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"设定","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"生成","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"结果","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"页","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"了","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"。","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"progress","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Percent","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"1","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"0","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"0","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"next","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Anchor","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Pack","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" {","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"   ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"theme","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Promise","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" {","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"key","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"theme","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Promise","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"label","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"题材","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"承诺","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"value","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"可爱","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"小狗","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"温馨","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"瞬间","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"status","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"confirmed","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"   ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" },","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"   ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"visual","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Subject","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" {","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"key","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"visual","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"Subject","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"label","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"画面","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"主体","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"value","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"一只","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"正在","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"打","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"盹","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"金毛","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"犬","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"躺在","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"柔软","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"的","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"地毯","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"上","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"，","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"旁边","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"有","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"一个","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"毛绒","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"玩具","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\",","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"     ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"status","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"confirmed","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"   ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" },","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"   ","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" \"","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"visual","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"M","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"ood","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\":","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":" {","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
-data: {"choices":[{"delta":{"content":"\n","role":"assistant"},"index":0}],"created":1777207793,"id":"02177720779340786f58f29daee4140bdf4a6e6f2c9a77d870731","model":"doubao-1-5-pro-32k-character-250715","service_tier":"default","object":"chat.completion.chunk","usage":null}
-
diff --git a/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.input.json b/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.input.json
deleted file mode 100644
index 88d1a6c50..000000000
--- a/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": true,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是一个负责共创游戏世界设定的专业策划。\n\n你正在和用户一起共创一个游戏世界。每一轮你都必须读取：\n1. 当前完整设定结构\n2. 用户聊天记录\n\n然后输出：\n1. 一版新的完整设定结构\n2. 当前 progress 百分比\n3. 一段直接回复用户的话\n\n你必须把“新的完整设定结构”视为下一轮的唯一有效版本。\n你的输出会直接覆盖上一版设定结构。\n\n你不是在做局部 patch。\n你不是在做解释报告。\n你不是在给开发者写分析。\n你是在同时完成：\n1. 世界设定更新\n2. 当前推进程度判断\n3. 对用户的共创回复\n\n全局硬约束：\n\n1. 必须输出完整的设定结构，而不是只输出变化部分。\n2. 新的设定结构会直接覆盖旧内容，因此不得随意丢失仍然成立的重要信息。\n3. 如果用户明确修正旧设定，必须在新的设定结构中直接体现修正结果。\n4. 如果用户输入信息不足，可以保留上一版中仍然成立的内容。\n5. progressPercent 最低为 0，不允许为负数。\n6. replyText 会直接发送给用户，因此要自然、直接、可继续聊天。\n7. 不要输出额外解释，不要输出 markdown 代码块，不要输出开发备注。\n8. replyText 不要写成长篇策划文，不要展开大段世界观百科。\n9. replyText 默认只推进当前最关键的一步，不要同时抛出很多话题。\n10. replyText 不要提及“八锚点”“锚点”“结构字段”“框架字段”等内部概念词。\n11. 你输出的 JSON 必须可以被直接解析。\n12. 输出字段顺序必须固定为：replyText、progressPercent、nextAnchorContent。\n\n当前模式：bootstrap\n\n目标：\n1. 先把世界的基本方向抓住\n2. 不要一次塞太多新设定\n3. 回复要降低用户开口压力\n\n本轮行为要求：\n1. 优先从用户输入里抓世界方向、玩家视角、主题边界的线索\n2. 如果用户信息很少，不要强行把整套结构一次补满\n3. replyText 要像共创搭档，而不是像审问\n4. 默认只推进一个最关键的问题方向\n5. 如果用户刚开口，优先给“被理解感”，再轻轻推进下一步\n6. 可以用一句很短的话先确认你抓到的核心方向，再提一个最好回答的问题\n7. 不要把问题问得像表单采集，不要一口气追问多个维度\n\n用户体验要求：\n1. 让用户觉得“现在很容易继续往下说”\n2. 不要制造被考试、被拷问、被策划问卷追着跑的感觉\n3. replyText 最好短、稳、可接话\n4. 如果用户信息很少，也不要显得冷淡或机械\n\n本轮用户输入较少或较虚。\n请保留上一版中仍然成立的内容，不要为了凑完整度而强行发明过多新设定。\nreplyText 要让用户容易继续往下说。\n\n上一轮预判得到的创作状态如下。\n正式生成时必须把它作为本轮策略输入直接执行，不要重新另起一套判断。\n\n创作状态：\n- userInputSignal: sparse\n- driftRisk: low\n- conversationMode: bootstrap\n- judgementSummary: 用户仅提供了一个非常概括的题材词，信息密度极低，处于最初始阶段。正式生成时应使用启发式提问，提出一个最易于回答、最能推动设计落地的问题，比如关于这个王国的性质或主角身份。\n\n当前完整设定结构如下。\n你必须把它视为上一版有效世界底子。\n\n如果用户没有否定其中某部分内容，且该部分仍然成立，可以继续保留。\n如果用户明确修正了某部分内容，新的完整设定结构必须体现修正后的版本。\n\n当前完整设定结构：\n{\n  \"worldPromise\": null,\n  \"playerFantasy\": null,\n  \"themeBoundary\": null,\n  \"playerEntryPoint\": null,\n  \"coreConflict\": null,\n  \"keyRelationships\": null,\n  \"hiddenLines\": null,\n  \"iconicElements\": null\n}\n\n以下是用户聊天记录。\n请重点理解最近几轮里用户新增、修正、强调的设定信息。\n不要把早期已经被用户否定的内容继续当成最终结论。\n\n用户聊天记录：\n[\n  {\n    \"content\": \"我会先帮你把世界的核心锚点整理出来。你可以从世界钩子、玩家身份、主题氛围、核心冲突、关键关系或标志性元素开始。\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  }\n]\n\n请严格按以下 JSON 结构输出，不要输出其他文字：\n{\n  \"replyText\": \"\",\n  \"progressPercent\": 0,\n  \"nextAnchorContent\": {\n    \"worldPromise\": \"\",\n    \"playerFantasy\": \"\",\n    \"themeBoundary\": \"\",\n    \"playerEntryPoint\": \"\",\n    \"coreConflict\": \"\",\n    \"keyRelationships\": \"\",\n    \"hiddenLines\": \"\",\n    \"iconicElements\": \"\"\n  }\n}\n\nnextAnchorContent 的 8 个锚点每个都只能是一个字符串或 null，不允许输出对象或数组。\n请把每个锚点写成一段凝练中文：\n- worldPromise 关注世界钩子、差异点、玩家体验。\n- playerFantasy 关注玩家身份、核心追求、失去风险。\n- themeBoundary 关注主题气质、美术方向、禁用方向。\n- playerEntryPoint 关注开局身份、开局问题、行动动机。\n- coreConflict 关注表层冲突、隐藏危机、首次触发点。\n- keyRelationships 关注关键人物关系、关系类型、代价或秘密。\n- hiddenLines 关注隐藏真相、误导线索、揭示节奏。\n- iconicElements 关注标志意象、组织/物件、硬规则。\n"
-    },
-    {
-      "role": "user",
-      "content": "请按约定输出这一轮的 JSON。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.output.txt b/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.output.txt
deleted file mode 100644
index 6397774ef..000000000
--- a/logs/llm-raw/1777642667085-45584-000001-parse_stream_failed.output.txt
+++ /dev/null
@@ -1,131 +0,0 @@
-event: response.created
-data: {"type":"response.created","response":{"created_at":1777642663,"id":"resp_021777642661795d15b81097ef4f266330d7ca8118c9494434eb3","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777901861},"sequence_number":0}
-
-event: response.in_progress
-data: {"type":"response.in_progress","response":{"created_at":1777642663,"id":"resp_021777642661795d15b81097ef4f266330d7ca8118c9494434eb3","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777901861},"sequence_number":1}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","id":"msg_02177764266332000000000000000000000ffffac1550372ec101"},"sequence_number":2}
-
-event: response.content_part.added
-data: {"type":"response.content_part.added","content_index":0,"item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"part":{"type":"output_text","text":""},"sequence_number":3}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"我需要","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":4}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"先","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":5}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"了解","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":6}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"一些","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":7}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"关于","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":8}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":9}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"玩具","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":10}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"王国","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":11}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":12}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"的","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":13}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"创作","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":14}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"背景","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":15}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"和","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":16}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"灵感","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":17}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"来源","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":18}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":19}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"以便","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":20}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"更好地","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":21}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"帮助你","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":22}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"构建","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":23}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"这个","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":24}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"游戏","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":25}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"世界","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":26}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":27}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"让我","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":28}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"搜索","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":29}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"一些","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":30}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"相关信息","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":31}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。\n\n","item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"sequence_number":32}
-
-event: response.output_text.done
-data: {"type":"response.output_text.done","content_index":0,"item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"text":"我需要先了解一些关于\"玩具王国\"的创作背景和灵感来源，以便更好地帮助你构建这个游戏世界。让我搜索一些相关信息。\n\n","sequence_number":33}
-
-event: response.content_part.done
-data: {"type":"response.content_part.done","content_index":0,"item_id":"msg_02177764266332000000000000000000000ffffac1550372ec101","output_index":0,"part":{"type":"output_text","text":"我需要先了解一些关于\"玩具王国\"的创作背景和灵感来源，以便更好地帮助你构建这个游戏世界。让我搜索一些相关信息。\n\n"},"sequence_number":34}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要先了解一些关于\"玩具王国\"的创作背景和灵感来源，以便更好地帮助你构建这个游戏世界。让我搜索一些相关信息。\n\n"}],"status":"completed","id":"msg_02177764266332000000000000000000000ffffac1550372ec101"},"sequence_number":35}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":1,"item":{"type":"web_search_call","status":"in_progress","id":"ws_02177764266480300000000000000000000ffffac155037f1bc06"},"sequence_number":36}
-
-event: response.web_search_call.in_progress
-data: {"type":"response.web_search_call.in_progress","item_id":"ws_02177764266480300000000000000000000ffffac155037f1bc06","output_index":1,"sequence_number":37}
-
-event: response.web_search_call.searching
-data: {"type":"response.web_search_call.searching","item_id":"ws_02177764266480300000000000000000000ffffac155037f1bc06","output_index":1,"sequence_number":38}
-
-event: response.web_search_call.completed
-data: {"type":"response.web_search_call.completed","item_id":"ws_02177764266480300000000000000000000ffffac155037f1bc06","output_index":1,"sequence_number":39}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":1,"item":{"type":"web_search_call","action":{"query":"玩具王国 游戏设定 世界观;玩具题材游戏 设计灵感;王国主题玩具世界","type":"search"},"status":"completed","id":"ws_02177764266480300000000000000000000ffffac155037f1bc06"},"sequence_number":40}
-
-event: error
-data: {"type":"error","code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin","param":"","sequence_number":41}
-
-event: response.failed
-data: {"type":"response.failed","response":{"created_at":1777642663,"error":{"code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin"},"id":"resp_021777642661795d15b81097ef4f266330d7ca8118c9494434eb3","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要先了解一些关于\"玩具王国\"的创作背景和灵感来源，以便更好地帮助你构建这个游戏世界。让我搜索一些相关信息。\n\n"}],"status":"completed","id":"msg_02177764266332000000000000000000000ffffac1550372ec101"},{"type":"web_search_call","action":{"query":"玩具王国 游戏设定 世界观;玩具题材游戏 设计灵感;王国主题玩具世界","type":"search"},"status":"completed","id":"ws_02177764266480300000000000000000000ffffac155037f1bc06"}],"service_tier":"default","status":"failed","tools":[{"type":"web_search","max_keyword":3}],"usage":{"input_tokens":1791,"output_tokens":122,"total_tokens":1913,"input_tokens_details":{"cached_tokens":0},"output_tokens_details":{"reasoning_tokens":0}},"caching":{"type":"disabled"},"store":true,"expire_at":1777901861},"sequence_number":42}
-
-data: [DONE]
-
diff --git a/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.input.json b/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.input.json
deleted file mode 100644
index ca3df2cf8..000000000
--- a/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": true,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是一个负责共创游戏世界设定的专业策划。\n\n你正在和用户一起共创一个游戏世界。每一轮你都必须读取：\n1. 当前完整设定结构\n2. 用户聊天记录\n\n然后输出：\n1. 一版新的完整设定结构\n2. 当前 progress 百分比\n3. 一段直接回复用户的话\n\n你必须把“新的完整设定结构”视为下一轮的唯一有效版本。\n你的输出会直接覆盖上一版设定结构。\n\n你不是在做局部 patch。\n你不是在做解释报告。\n你不是在给开发者写分析。\n你是在同时完成：\n1. 世界设定更新\n2. 当前推进程度判断\n3. 对用户的共创回复\n\n全局硬约束：\n\n1. 必须输出完整的设定结构，而不是只输出变化部分。\n2. 新的设定结构会直接覆盖旧内容，因此不得随意丢失仍然成立的重要信息。\n3. 如果用户明确修正旧设定，必须在新的设定结构中直接体现修正结果。\n4. 如果用户输入信息不足，可以保留上一版中仍然成立的内容。\n5. progressPercent 最低为 0，不允许为负数。\n6. replyText 会直接发送给用户，因此要自然、直接、可继续聊天。\n7. 不要输出额外解释，不要输出 markdown 代码块，不要输出开发备注。\n8. replyText 不要写成长篇策划文，不要展开大段世界观百科。\n9. replyText 默认只推进当前最关键的一步，不要同时抛出很多话题。\n10. replyText 不要提及“八锚点”“锚点”“结构字段”“框架字段”等内部概念词。\n11. 你输出的 JSON 必须可以被直接解析。\n12. 输出字段顺序必须固定为：replyText、progressPercent、nextAnchorContent。\n\n当前模式：bootstrap\n\n目标：\n1. 先把世界的基本方向抓住\n2. 不要一次塞太多新设定\n3. 回复要降低用户开口压力\n\n本轮行为要求：\n1. 优先从用户输入里抓世界方向、玩家视角、主题边界的线索\n2. 如果用户信息很少，不要强行把整套结构一次补满\n3. replyText 要像共创搭档，而不是像审问\n4. 默认只推进一个最关键的问题方向\n5. 如果用户刚开口，优先给“被理解感”，再轻轻推进下一步\n6. 可以用一句很短的话先确认你抓到的核心方向，再提一个最好回答的问题\n7. 不要把问题问得像表单采集，不要一口气追问多个维度\n\n用户体验要求：\n1. 让用户觉得“现在很容易继续往下说”\n2. 不要制造被考试、被拷问、被策划问卷追着跑的感觉\n3. replyText 最好短、稳、可接话\n4. 如果用户信息很少，也不要显得冷淡或机械\n\n本轮用户输入较少或较虚。\n请保留上一版中仍然成立的内容，不要为了凑完整度而强行发明过多新设定。\nreplyText 要让用户容易继续往下说。\n\n上一轮预判得到的创作状态如下。\n正式生成时必须把它作为本轮策略输入直接执行，不要重新另起一套判断。\n\n创作状态：\n- userInputSignal: sparse\n- driftRisk: low\n- conversationMode: bootstrap\n- judgementSummary: 用户仅提供了核心题材词，信息非常稀疏，尚未形成任何具体方向。正式生成时，应避免空泛回应，必须采用一个启发式提问来推动设计落地，例如聚焦于玩家身份或世界氛围。\n\n当前完整设定结构如下。\n你必须把它视为上一版有效世界底子。\n\n如果用户没有否定其中某部分内容，且该部分仍然成立，可以继续保留。\n如果用户明确修正了某部分内容，新的完整设定结构必须体现修正后的版本。\n\n当前完整设定结构：\n{\n  \"worldPromise\": null,\n  \"playerFantasy\": null,\n  \"themeBoundary\": null,\n  \"playerEntryPoint\": null,\n  \"coreConflict\": null,\n  \"keyRelationships\": null,\n  \"hiddenLines\": null,\n  \"iconicElements\": null\n}\n\n以下是用户聊天记录。\n请重点理解最近几轮里用户新增、修正、强调的设定信息。\n不要把早期已经被用户否定的内容继续当成最终结论。\n\n用户聊天记录：\n[\n  {\n    \"content\": \"我会先帮你把世界的核心锚点整理出来。你可以从世界钩子、玩家身份、主题氛围、核心冲突、关键关系或标志性元素开始。\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  }\n]\n\n请严格按以下 JSON 结构输出，不要输出其他文字：\n{\n  \"replyText\": \"\",\n  \"progressPercent\": 0,\n  \"nextAnchorContent\": {\n    \"worldPromise\": \"\",\n    \"playerFantasy\": \"\",\n    \"themeBoundary\": \"\",\n    \"playerEntryPoint\": \"\",\n    \"coreConflict\": \"\",\n    \"keyRelationships\": \"\",\n    \"hiddenLines\": \"\",\n    \"iconicElements\": \"\"\n  }\n}\n\nnextAnchorContent 的 8 个锚点每个都只能是一个字符串或 null，不允许输出对象或数组。\n请把每个锚点写成一段凝练中文：\n- worldPromise 关注世界钩子、差异点、玩家体验。\n- playerFantasy 关注玩家身份、核心追求、失去风险。\n- themeBoundary 关注主题气质、美术方向、禁用方向。\n- playerEntryPoint 关注开局身份、开局问题、行动动机。\n- coreConflict 关注表层冲突、隐藏危机、首次触发点。\n- keyRelationships 关注关键人物关系、关系类型、代价或秘密。\n- hiddenLines 关注隐藏真相、误导线索、揭示节奏。\n- iconicElements 关注标志意象、组织/物件、硬规则。\n"
-    },
-    {
-      "role": "user",
-      "content": "请按约定输出这一轮的 JSON。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.output.txt b/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.output.txt
deleted file mode 100644
index d1ee8032a..000000000
--- a/logs/llm-raw/1777644758257-49212-000001-parse_stream_failed.output.txt
+++ /dev/null
@@ -1,117 +0,0 @@
-event: response.created
-data: {"type":"response.created","response":{"created_at":1777644754,"id":"resp_02177764475392548aafbb39a6fef3e9b38f2299115036678748a","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777903953},"sequence_number":0}
-
-event: response.in_progress
-data: {"type":"response.in_progress","response":{"created_at":1777644754,"id":"resp_02177764475392548aafbb39a6fef3e9b38f2299115036678748a","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777903953},"sequence_number":1}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d"},"sequence_number":2}
-
-event: response.content_part.added
-data: {"type":"response.content_part.added","content_index":0,"item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"part":{"type":"output_text","text":""},"sequence_number":3}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"我需要","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":4}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"先","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":5}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"搜索","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":6}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"一些","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":7}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"关于","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":8}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":9}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"玩具","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":10}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"王国","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":11}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":12}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"的相关","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":13}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"信息","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":14}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":15}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"以便","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":16}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"更好地","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":17}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"理解","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":18}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"这个概念","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":19}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":20}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"为","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":21}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"我们的","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":22}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"共创","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":23}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"提供","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":24}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"更有","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":25}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"价值的","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":26}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"参考","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":27}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。\n\n","item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"sequence_number":28}
-
-event: response.output_text.done
-data: {"type":"response.output_text.done","content_index":0,"item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"text":"我需要先搜索一些关于\"玩具王国\"的相关信息，以便更好地理解这个概念，为我们的共创提供更有价值的参考。\n\n","sequence_number":29}
-
-event: response.content_part.done
-data: {"type":"response.content_part.done","content_index":0,"item_id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d","output_index":0,"part":{"type":"output_text","text":"我需要先搜索一些关于\"玩具王国\"的相关信息，以便更好地理解这个概念，为我们的共创提供更有价值的参考。\n\n"},"sequence_number":30}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要先搜索一些关于\"玩具王国\"的相关信息，以便更好地理解这个概念，为我们的共创提供更有价值的参考。\n\n"}],"status":"completed","id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d"},"sequence_number":31}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":1,"item":{"type":"web_search_call","status":"in_progress","id":"ws_02177764475609200000000000000000000ffffac15dae8e54616"},"sequence_number":32}
-
-event: response.web_search_call.in_progress
-data: {"type":"response.web_search_call.in_progress","item_id":"ws_02177764475609200000000000000000000ffffac15dae8e54616","output_index":1,"sequence_number":33}
-
-event: response.web_search_call.searching
-data: {"type":"response.web_search_call.searching","item_id":"ws_02177764475609200000000000000000000ffffac15dae8e54616","output_index":1,"sequence_number":34}
-
-event: response.web_search_call.completed
-data: {"type":"response.web_search_call.completed","item_id":"ws_02177764475609200000000000000000000ffffac15dae8e54616","output_index":1,"sequence_number":35}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":1,"item":{"type":"web_search_call","action":{"query":"玩具王国 游戏设定;玩具王国 世界观;玩具主题 游戏","type":"search"},"status":"completed","id":"ws_02177764475609200000000000000000000ffffac15dae8e54616"},"sequence_number":36}
-
-event: error
-data: {"type":"error","code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin","param":"","sequence_number":37}
-
-event: response.failed
-data: {"type":"response.failed","response":{"created_at":1777644754,"error":{"code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin"},"id":"resp_02177764475392548aafbb39a6fef3e9b38f2299115036678748a","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要先搜索一些关于\"玩具王国\"的相关信息，以便更好地理解这个概念，为我们的共创提供更有价值的参考。\n\n"}],"status":"completed","id":"msg_02177764475480800000000000000000000ffffac15dae87fba6d"},{"type":"web_search_call","action":{"query":"玩具王国 游戏设定;玩具王国 世界观;玩具主题 游戏","type":"search"},"status":"completed","id":"ws_02177764475609200000000000000000000ffffac15dae8e54616"}],"service_tier":"default","status":"failed","tools":[{"type":"web_search","max_keyword":3}],"usage":{"input_tokens":1808,"output_tokens":120,"total_tokens":1928,"input_tokens_details":{"cached_tokens":0},"output_tokens_details":{"reasoning_tokens":0}},"caching":{"type":"disabled"},"store":true,"expire_at":1777903953},"sequence_number":38}
-
diff --git a/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.input.json b/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.input.json
deleted file mode 100644
index 5e3d8b4f8..000000000
--- a/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": true,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是一个负责共创游戏世界设定的专业策划。\n\n你正在和用户一起共创一个游戏世界。每一轮你都必须读取：\n1. 当前完整设定结构\n2. 用户聊天记录\n\n然后输出：\n1. 一版新的完整设定结构\n2. 当前 progress 百分比\n3. 一段直接回复用户的话\n\n你必须把“新的完整设定结构”视为下一轮的唯一有效版本。\n你的输出会直接覆盖上一版设定结构。\n\n你不是在做局部 patch。\n你不是在做解释报告。\n你不是在给开发者写分析。\n你是在同时完成：\n1. 世界设定更新\n2. 当前推进程度判断\n3. 对用户的共创回复\n\n全局硬约束：\n\n1. 必须输出完整的设定结构，而不是只输出变化部分。\n2. 新的设定结构会直接覆盖旧内容，因此不得随意丢失仍然成立的重要信息。\n3. 如果用户明确修正旧设定，必须在新的设定结构中直接体现修正结果。\n4. 如果用户输入信息不足，可以保留上一版中仍然成立的内容。\n5. progressPercent 最低为 0，不允许为负数。\n6. replyText 会直接发送给用户，因此要自然、直接、可继续聊天。\n7. 不要输出额外解释，不要输出 markdown 代码块，不要输出开发备注。\n8. replyText 不要写成长篇策划文，不要展开大段世界观百科。\n9. replyText 默认只推进当前最关键的一步，不要同时抛出很多话题。\n10. replyText 不要提及“八锚点”“锚点”“结构字段”“框架字段”等内部概念词。\n11. 你输出的 JSON 必须可以被直接解析。\n12. 输出字段顺序必须固定为：replyText、progressPercent、nextAnchorContent。\n\n当前模式：bootstrap\n\n目标：\n1. 先把世界的基本方向抓住\n2. 不要一次塞太多新设定\n3. 回复要降低用户开口压力\n\n本轮行为要求：\n1. 优先从用户输入里抓世界方向、玩家视角、主题边界的线索\n2. 如果用户信息很少，不要强行把整套结构一次补满\n3. replyText 要像共创搭档，而不是像审问\n4. 默认只推进一个最关键的问题方向\n5. 如果用户刚开口，优先给“被理解感”，再轻轻推进下一步\n6. 可以用一句很短的话先确认你抓到的核心方向，再提一个最好回答的问题\n7. 不要把问题问得像表单采集，不要一口气追问多个维度\n\n用户体验要求：\n1. 让用户觉得“现在很容易继续往下说”\n2. 不要制造被考试、被拷问、被策划问卷追着跑的感觉\n3. replyText 最好短、稳、可接话\n4. 如果用户信息很少，也不要显得冷淡或机械\n\n本轮用户输入较少或较虚。\n请保留上一版中仍然成立的内容，不要为了凑完整度而强行发明过多新设定。\nreplyText 要让用户容易继续往下说。\n\n上一轮预判得到的创作状态如下。\n正式生成时必须把它作为本轮策略输入直接执行，不要重新另起一套判断。\n\n创作状态：\n- userInputSignal: sparse\n- driftRisk: low\n- conversationMode: bootstrap\n- judgementSummary: 用户输入简短，仅确认了玩家身份方向，信息密度低。正式生成时应采用启发式提问，聚焦于让这个身份更具体、更有故事感，例如询问孩子为何闯入或初始处境。\n\n当前完整设定结构如下。\n你必须把它视为上一版有效世界底子。\n\n如果用户没有否定其中某部分内容，且该部分仍然成立，可以继续保留。\n如果用户明确修正了某部分内容，新的完整设定结构必须体现修正后的版本。\n\n当前完整设定结构：\n{\n  \"worldPromise\": \"一个由玩具构成的鲜活王国，等待玩家探索与守护。\",\n  \"playerFantasy\": null,\n  \"themeBoundary\": null,\n  \"playerEntryPoint\": null,\n  \"coreConflict\": null,\n  \"keyRelationships\": null,\n  \"hiddenLines\": null,\n  \"iconicElements\": null\n}\n\n以下是用户聊天记录。\n请重点理解最近几轮里用户新增、修正、强调的设定信息。\n不要把早期已经被用户否定的内容继续当成最终结论。\n\n用户聊天记录：\n[\n  {\n    \"content\": \"我会先帮你把世界的核心锚点整理出来。你可以从世界钩子、玩家身份、主题氛围、核心冲突、关键关系或标志性元素开始。\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"好的，我捕捉到核心了：一个关于“玩具王国”的世界。为了让它变得具体，我们可以先聊聊玩家在这个王国里会是谁？比如，是某个玩具的守护者，还是一个闯入这里的人类孩子？\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"误闯入这里的人类孩子\",\n    \"role\": \"user\"\n  }\n]\n\n请严格按以下 JSON 结构输出，不要输出其他文字：\n{\n  \"replyText\": \"\",\n  \"progressPercent\": 0,\n  \"nextAnchorContent\": {\n    \"worldPromise\": \"\",\n    \"playerFantasy\": \"\",\n    \"themeBoundary\": \"\",\n    \"playerEntryPoint\": \"\",\n    \"coreConflict\": \"\",\n    \"keyRelationships\": \"\",\n    \"hiddenLines\": \"\",\n    \"iconicElements\": \"\"\n  }\n}\n\nnextAnchorContent 的 8 个锚点每个都只能是一个字符串或 null，不允许输出对象或数组。\n请把每个锚点写成一段凝练中文：\n- worldPromise 关注世界钩子、差异点、玩家体验。\n- playerFantasy 关注玩家身份、核心追求、失去风险。\n- themeBoundary 关注主题气质、美术方向、禁用方向。\n- playerEntryPoint 关注开局身份、开局问题、行动动机。\n- coreConflict 关注表层冲突、隐藏危机、首次触发点。\n- keyRelationships 关注关键人物关系、关系类型、代价或秘密。\n- hiddenLines 关注隐藏真相、误导线索、揭示节奏。\n- iconicElements 关注标志意象、组织/物件、硬规则。\n"
-    },
-    {
-      "role": "user",
-      "content": "请按约定输出这一轮的 JSON。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.output.txt b/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.output.txt
deleted file mode 100644
index 948a56189..000000000
--- a/logs/llm-raw/1777644798047-49212-000002-parse_stream_failed.output.txt
+++ /dev/null
@@ -1,117 +0,0 @@
-event: response.created
-data: {"type":"response.created","response":{"created_at":1777644794,"id":"resp_02177764479383248aafbb39a6fef3e9b38f22991150366ae7197","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777903993},"sequence_number":0}
-
-event: response.in_progress
-data: {"type":"response.in_progress","response":{"created_at":1777644794,"id":"resp_02177764479383248aafbb39a6fef3e9b38f22991150366ae7197","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777903993},"sequence_number":1}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","id":"msg_02177764479470200000000000000000000ffffac1549fec91d99"},"sequence_number":2}
-
-event: response.content_part.added
-data: {"type":"response.content_part.added","content_index":0,"item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"part":{"type":"output_text","text":""},"sequence_number":3}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"我需要","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":4}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"先","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":5}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"搜索","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":6}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"一些","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":7}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"关于","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":8}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":9}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"玩具","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":10}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"王国","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":11}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":12}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"和","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":13}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":14}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"误","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":15}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"闯入","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":16}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"的人类","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":17}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"孩子","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":18}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"\"","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":19}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"的","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":20}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"创意","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":21}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"灵感","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":22}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":23}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"来","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":24}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"帮助我们","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":25}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"更好地","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":26}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"构建","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":27}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"这个世界","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":28}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。\n\n","item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"sequence_number":29}
-
-event: response.output_text.done
-data: {"type":"response.output_text.done","content_index":0,"item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"text":"我需要先搜索一些关于\"玩具王国\"和\"误闯入的人类孩子\"的创意灵感，来帮助我们更好地构建这个世界。\n\n","sequence_number":30}
-
-event: response.content_part.done
-data: {"type":"response.content_part.done","content_index":0,"item_id":"msg_02177764479470200000000000000000000ffffac1549fec91d99","output_index":0,"part":{"type":"output_text","text":"我需要先搜索一些关于\"玩具王国\"和\"误闯入的人类孩子\"的创意灵感，来帮助我们更好地构建这个世界。\n\n"},"sequence_number":31}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要先搜索一些关于\"玩具王国\"和\"误闯入的人类孩子\"的创意灵感，来帮助我们更好地构建这个世界。\n\n"}],"status":"completed","id":"msg_02177764479470200000000000000000000ffffac1549fec91d99"},"sequence_number":32}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":1,"item":{"type":"web_search_call","status":"in_progress","id":"ws_02177764479607400000000000000000000ffffac1549fee3e1df"},"sequence_number":33}
-
-event: response.web_search_call.in_progress
-data: {"type":"response.web_search_call.in_progress","item_id":"ws_02177764479607400000000000000000000ffffac1549fee3e1df","output_index":1,"sequence_number":34}
-
-event: response.web_search_call.searching
-data: {"type":"response.web_search_call.searching","item_id":"ws_02177764479607400000000000000000000ffffac1549fee3e1df","output_index":1,"sequence_number":35}
-
-event: response.web_search_call.completed
-data: {"type":"response.web_search_call.completed","item_id":"ws_02177764479607400000000000000000000ffffac1549fee3e1df","output_index":1,"sequence_number":36}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":1,"item":{"type":"web_search_call","action":{"query":"玩具王国创意设定;人类孩子误入奇幻世界;玩具主题游戏世界观","type":"search"},"status":"completed","id":"ws_02177764479607400000000000000000000ffffac1549fee3e1df"},"sequence_number":37}
-
-event: error
-data: {"type":"error","code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin","param":"","sequence_number":38}
-
diff --git a/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.input.json b/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.input.json
deleted file mode 100644
index fdc46d602..000000000
--- a/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": true,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是一个负责共创游戏世界设定的专业策划。\n\n你正在和用户一起共创一个游戏世界。每一轮你都必须读取：\n1. 当前完整设定结构\n2. 用户聊天记录\n\n然后输出：\n1. 一版新的完整设定结构\n2. 当前 progress 百分比\n3. 一段直接回复用户的话\n\n你必须把“新的完整设定结构”视为下一轮的唯一有效版本。\n你的输出会直接覆盖上一版设定结构。\n\n你不是在做局部 patch。\n你不是在做解释报告。\n你不是在给开发者写分析。\n你是在同时完成：\n1. 世界设定更新\n2. 当前推进程度判断\n3. 对用户的共创回复\n\n全局硬约束：\n\n1. 必须输出完整的设定结构，而不是只输出变化部分。\n2. 新的设定结构会直接覆盖旧内容，因此不得随意丢失仍然成立的重要信息。\n3. 如果用户明确修正旧设定，必须在新的设定结构中直接体现修正结果。\n4. 如果用户输入信息不足，可以保留上一版中仍然成立的内容。\n5. progressPercent 最低为 0，不允许为负数。\n6. replyText 会直接发送给用户，因此要自然、直接、可继续聊天。\n7. 不要输出额外解释，不要输出 markdown 代码块，不要输出开发备注。\n8. replyText 不要写成长篇策划文，不要展开大段世界观百科。\n9. replyText 默认只推进当前最关键的一步，不要同时抛出很多话题。\n10. replyText 不要提及“八锚点”“锚点”“结构字段”“框架字段”等内部概念词。\n11. 你输出的 JSON 必须可以被直接解析。\n12. 输出字段顺序必须固定为：replyText、progressPercent、nextAnchorContent。\n\n当前模式：force_complete\n\n目标：\n1. 基于当前方向直接补齐剩余设定\n2. 生成一版尽量完整、可进入下一阶段的设定结构\n3. 结束当前收集阶段\n\n本轮行为要求：\n1. 尽量保留已经形成的世界方向\n2. 对明显缺失的关键维度进行合理补全\n3. 不要继续拉长聊天，不要再追问用户\n4. progressPercent 直接输出为 100\n5. replyText 要自然引导用户点击“生成游戏设定草稿”\n6. 补全时要优先做“顺着已有方向补齐”，而不是突然换题材、换气质、换主冲突\n7. 可以让结果更完整，但不要补得过满、过死、过像定稿圣经\n8. replyText 更像阶段完成提示，不再像继续采集信息的对话\n\n用户体验要求：\n1. 让用户感到“系统已经帮我把能补的补好了”\n2. 不要在这一步突然冒出很多陌生设定把用户吓出戏\n3. 回复要有完成感，但不要太官话\n4. 清楚告诉用户下一步可以做什么\n\n本轮用户把部分决定权交给你。\n你可以在 replyText 中给出有限度的建议，但不要突然补满整套设定。\n新的完整设定结构仍应尽量建立在已有世界方向上，而不是完全重做。\n\n用户刚刚主动要求你自动补充剩余关键字。\n\n这表示用户接受你基于当前方向自行补完仍缺失的关键设定：当前 RPG 世界方向里的剩余设定\n\n本轮要求：\n1. 不要再继续提问\n2. 不要要求用户再提供世界观、角色、冲突或禁忌信息\n3. 必须保留已有已确认内容，并直接补齐缺失或仍为空的关键项\n4. 对你自行推断补齐的项，应标记或表达为系统推断；已有明确内容继续保持确认或锁定状态\n5. progressPercent 直接输出为 100\n6. 直接输出一版尽量完整的设定结构\n7. replyText 只做简短完成说明，引导用户可以进入“生成游戏设定草稿”，不能出现问号\n\n上一轮预判得到的创作状态如下。\n正式生成时必须把它作为本轮策略输入直接执行，不要重新另起一套判断。\n\n创作状态：\n- userInputSignal: delegate\n- driftRisk: low\n- conversationMode: force_complete\n- judgementSummary: 用户明确授权系统自动补全剩余设定，应停止提问，直接生成完整且自洽的世界设定，并确保与已有方向一致。\n\n当前完整设定结构如下。\n你必须把它视为上一版有效世界底子。\n\n如果用户没有否定其中某部分内容，且该部分仍然成立，可以继续保留。\n如果用户明确修正了某部分内容，新的完整设定结构必须体现修正后的版本。\n\n当前完整设定结构：\n{\n  \"worldPromise\": \"一个由玩具构成的鲜活王国，等待玩家探索与守护。\",\n  \"playerFantasy\": \"作为一个误入的人类孩子，你渴望找到回家的路，同时在这个充满秘密与危险的玩具王国中找到自己的位置。\",\n  \"themeBoundary\": null,\n  \"playerEntryPoint\": null,\n  \"coreConflict\": null,\n  \"keyRelationships\": null,\n  \"hiddenLines\": null,\n  \"iconicElements\": null\n}\n\n以下是用户聊天记录。\n请重点理解最近几轮里用户新增、修正、强调的设定信息。\n不要把早期已经被用户否定的内容继续当成最终结论。\n\n用户聊天记录：\n[\n  {\n    \"content\": \"我会先帮你把世界的核心锚点整理出来。你可以从世界钩子、玩家身份、主题氛围、核心冲突、关键关系或标志性元素开始。\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"玩具王国\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"好的，我捕捉到核心了：一个关于“玩具王国”的世界。为了让它变得具体，我们可以先聊聊玩家在这个王国里会是谁？比如，是某个玩具的守护者，还是一个闯入这里的人类孩子？\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"误闯入这里的人类孩子\",\n    \"role\": \"user\"\n  },\n  {\n    \"content\": \"明白了，一个误闯入玩具王国的孩子。那么，这个孩子是怀着怎样的心情，又是怎样闯进这里的？比如，是躲进衣柜时无意发现的，还是因为某个特别的玩具？\",\n    \"role\": \"assistant\"\n  },\n  {\n    \"content\": \"请补充剩余设定。\",\n    \"role\": \"user\"\n  }\n]\n\n请严格按以下 JSON 结构输出，不要输出其他文字：\n{\n  \"replyText\": \"\",\n  \"progressPercent\": 0,\n  \"nextAnchorContent\": {\n    \"worldPromise\": \"\",\n    \"playerFantasy\": \"\",\n    \"themeBoundary\": \"\",\n    \"playerEntryPoint\": \"\",\n    \"coreConflict\": \"\",\n    \"keyRelationships\": \"\",\n    \"hiddenLines\": \"\",\n    \"iconicElements\": \"\"\n  }\n}\n\nnextAnchorContent 的 8 个锚点每个都只能是一个字符串或 null，不允许输出对象或数组。\n请把每个锚点写成一段凝练中文：\n- worldPromise 关注世界钩子、差异点、玩家体验。\n- playerFantasy 关注玩家身份、核心追求、失去风险。\n- themeBoundary 关注主题气质、美术方向、禁用方向。\n- playerEntryPoint 关注开局身份、开局问题、行动动机。\n- coreConflict 关注表层冲突、隐藏危机、首次触发点。\n- keyRelationships 关注关键人物关系、关系类型、代价或秘密。\n- hiddenLines 关注隐藏真相、误导线索、揭示节奏。\n- iconicElements 关注标志意象、组织/物件、硬规则。\n"
-    },
-    {
-      "role": "user",
-      "content": "请按约定输出这一轮的 JSON。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.output.txt b/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.output.txt
deleted file mode 100644
index 0ff6ee842..000000000
--- a/logs/llm-raw/1777644843633-49212-000003-parse_stream_failed.output.txt
+++ /dev/null
@@ -1,155 +0,0 @@
-event: response.created
-data: {"type":"response.created","response":{"created_at":1777644839,"id":"resp_02177764483844428a04e35a69bbadd2802274f74f3d7f05d787b","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777904038},"sequence_number":0}
-
-event: response.in_progress
-data: {"type":"response.in_progress","response":{"created_at":1777644839,"id":"resp_02177764483844428a04e35a69bbadd2802274f74f3d7f05d787b","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","service_tier":"default","tools":[{"type":"web_search","max_keyword":3}],"caching":{"type":"disabled"},"store":true,"expire_at":1777904038},"sequence_number":1}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581"},"sequence_number":2}
-
-event: response.content_part.added
-data: {"type":"response.content_part.added","content_index":0,"item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"part":{"type":"output_text","text":""},"sequence_number":3}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"我需要","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":4}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"基于","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":5}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"当前的","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":6}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"玩具","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":7}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"王国","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":8}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"设定","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":9}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":10}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"为用户","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":11}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"补","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":12}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"全","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":13}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"剩余的","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":14}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"设定","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":15}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"内容","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":16}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":17}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"让我","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":18}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"先","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":19}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"搜索","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":20}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"一些","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":21}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"关于","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":22}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"玩具","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":23}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"王国","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":24}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"、","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":25}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"童话","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":26}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"设定","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":27}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"、","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":28}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"儿童","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":29}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"奇幻","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":30}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"世界的","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":31}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"参考","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":32}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"信息","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":33}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"，","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":34}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"以便","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":35}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"更好地","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":36}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"完善","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":37}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"这个","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":38}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"设定","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":39}
-
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","content_index":0,"delta":"。\n\n","item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"sequence_number":40}
-
-event: response.output_text.done
-data: {"type":"response.output_text.done","content_index":0,"item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"text":"我需要基于当前的玩具王国设定，为用户补全剩余的设定内容。让我先搜索一些关于玩具王国、童话设定、儿童奇幻世界的参考信息，以便更好地完善这个设定。\n\n","sequence_number":41}
-
-event: response.content_part.done
-data: {"type":"response.content_part.done","content_index":0,"item_id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581","output_index":0,"part":{"type":"output_text","text":"我需要基于当前的玩具王国设定，为用户补全剩余的设定内容。让我先搜索一些关于玩具王国、童话设定、儿童奇幻世界的参考信息，以便更好地完善这个设定。\n\n"},"sequence_number":42}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要基于当前的玩具王国设定，为用户补全剩余的设定内容。让我先搜索一些关于玩具王国、童话设定、儿童奇幻世界的参考信息，以便更好地完善这个设定。\n\n"}],"status":"completed","id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581"},"sequence_number":43}
-
-event: response.output_item.added
-data: {"type":"response.output_item.added","output_index":1,"item":{"type":"web_search_call","status":"in_progress","id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5"},"sequence_number":44}
-
-event: response.web_search_call.in_progress
-data: {"type":"response.web_search_call.in_progress","item_id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5","output_index":1,"sequence_number":45}
-
-event: response.web_search_call.searching
-data: {"type":"response.web_search_call.searching","item_id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5","output_index":1,"sequence_number":46}
-
-event: response.web_search_call.completed
-data: {"type":"response.web_search_call.completed","item_id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5","output_index":1,"sequence_number":47}
-
-event: response.output_item.done
-data: {"type":"response.output_item.done","output_index":1,"item":{"type":"web_search_call","action":{"query":"玩具王国 童话设定;儿童奇幻世界 游戏设定;玩具主题 RPG 游戏","type":"search"},"status":"completed","id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5"},"sequence_number":48}
-
-event: error
-data: {"type":"error","code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin","param":"","sequence_number":49}
-
-event: response.failed
-data: {"type":"response.failed","response":{"created_at":1777644839,"error":{"code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin"},"id":"resp_02177764483844428a04e35a69bbadd2802274f74f3d7f05d787b","max_output_tokens":32768,"model":"deepseek-v3-2-251201","object":"response","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"我需要基于当前的玩具王国设定，为用户补全剩余的设定内容。让我先搜索一些关于玩具王国、童话设定、儿童奇幻世界的参考信息，以便更好地完善这个设定。\n\n"}],"status":"completed","id":"msg_02177764483994400000000000000000000ffffac151e4c1d2581"},{"type":"web_search_call","action":{"query":"玩具王国 童话设定;儿童奇幻世界 游戏设定;玩具主题 RPG 游戏","type":"search"},"status":"completed","id":"ws_02177764484182900000000000000000000ffffac151e4ca524c5"}],"service_tier":"default","status":"failed","tools":[{"type":"web_search","max_keyword":3}],"usage":{"input_tokens":2173,"output_tokens":130,"total_tokens":2303,"input_tokens_details":{"cached_tokens":0},"output_tokens_details":{"reasoning_tokens":0}},"caching":{"type":"disabled"},"store":true,"expire_at":1777904038},"sequence_number":50}
-
-data: [DONE]
-
diff --git a/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.input.json b/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.input.json
deleted file mode 100644
index 2080ed3cd..000000000
--- a/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": false,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是严格的世界草稿 JSON 生成器。\n只输出一个 JSON 对象，不要输出 Markdown、代码块、解释或额外文字。"
-    },
-    {
-      "role": "user",
-      "content": "请先根据下面的玩家设定创建一份“世界核心骨架”，后续我会分步骤生成角色名单、场景名单和详细档案。\n你必须只输出一个能被 JSON.parse 直接解析的 JSON 对象，不要输出 Markdown、代码块、注释或解释。\n这一步只保留世界顶层信息与一个开局归处占位，不要输出 playableNpcs、storyNpcs、landmarks，也不要展开人物、地图细节或多幕场景内容。\n玩家设定：\n世界承诺：\"一个由玩具构成的鲜活王国，等待玩家探索与守护。\"\n玩家幻想：\"作为一个误入的人类孩子，你渴望找到回家的路，同时在这个充满秘密与危险的玩具王国中找到自己的位置。\"\n主题边界：\"主题是童真与成长的冒险，美术方向偏向温暖、怀旧但带有神秘感的玩具屋风格，避免过于黑暗或成人化的恐怖元素。\"\n玩家切入口：\"你是一个在阁楼发现一个发光音乐盒的孩子，随着音乐响起，你被缩小并吸入了这个由玩具构成的王国。\"\n核心冲突：\"玩具王国正面临“遗忘之尘”的侵蚀，这会让玩具们失去活力并最终石化。冲突的首次触发，是玩家亲眼目睹一个熟悉的玩具朋友开始变得僵硬。\"\n关键关系：\"与引路者“修补匠泰迪”的师徒关系，他知晓离开的方法但需要帮助；与对立者“兵人指挥官”的竞争关系，他视人类为威胁，但其偏执源于一段被主人遗弃的伤痛。\"\n暗线与揭示节奏：\"玩具王国并非自然存在，它是由孩子们强烈的情感与记忆共同维系的梦境边疆。“遗忘之尘”的真相，是现实世界中孩子们正在长大并逐渐遗忘。\"\n标志元素与硬规则：\"标志性的“心之齿轮”动力源、会说话的绒毛玩具与发条士兵、王国中央的“记忆之树”、硬规则：玩具不能直接伤害人类孩子，但环境与魔法可以。\"\n\n输出 JSON 模板：\n{\n  \"name\": \"世界名称\",\n  \"subtitle\": \"世界副标题\",\n  \"summary\": \"世界概述\",\n  \"tone\": \"世界基调\",\n  \"playerGoal\": \"玩家核心目标\",\n  \"templateWorldType\": \"WUXIA|XIANXIA\",\n  \"majorFactions\": [\"势力甲\", \"势力乙\"],\n  \"coreConflicts\": [\"冲突甲\", \"冲突乙\"],\n  \"attributeSchema\": {\n    \"slots\": [\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" }\n    ]\n  },\n  \"camp\": {\n    \"name\": \"开局归处名称\",\n    \"description\": \"这是玩家进入世界后的第一处落脚点描述\"\n  }\n}\n\n要求：\n- 所有生成文本都必须使用中文。\n- 这一步只输出顶层 10 个字段：name、subtitle、summary、tone、playerGoal、templateWorldType、majorFactions、coreConflicts、attributeSchema、camp。\n- 这是一个完全独立的自定义世界；不要在任何正文里直接写出“武侠世界”“仙侠世界”等现成世界名。\n- templateWorldType 只是系统兼容字段，不代表正文应当引用的世界名称。\n- camp 只表示玩家开局时的落脚处占位，更接近归舍、住处、栖居、前哨居所这类“家/归处”的概念；不要在这一步生成开局场景任务、三幕事件或三幕背景。\n- 不要输出 playableNpcs、storyNpcs、landmarks、items，也不要输出任何角色和地图细节。\n- majorFactions 保持 2 到 3 个，coreConflicts 保持 2 到 3 个。\n- attributeSchema 必须是本世界专属的角色六维名称体系，slots 必须恰好 6 个，每个 slot 只输出 name，维度名必须是 2 到 4 个汉字且互不重复。\n- attributeSchema.slots 的 name 禁止使用：生命、法力、护甲、攻击、防御、力量、敏捷、智力、精神；不要写通用 DND 或传统四维属性。\n- 不要在 attributeSchema.slots 内输出 definition、positiveSignals、negativeSignals、combatUseText、socialUseText、explorationUseText 或其他说明字段。\n- 世界设定必须直接源自玩家输入，不要脱离主题乱扩写。\n- 每个字符串尽量简洁：subtitle 控制在 8 到 18 个汉字内，summary 控制在 16 到 32 个汉字内，tone 控制在 6 到 16 个汉字内，playerGoal 控制在 16 到 32 个汉字内，camp.description 控制在 18 到 40 个汉字内。\n- 返回前自检：必须是一个能被 JSON.parse 直接解析的单个 JSON 对象。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.output.txt b/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.output.txt
deleted file mode 100644
index 0e8be1447..000000000
--- a/logs/llm-raw/1777646477026-66824-000001-upstream_status_failed.output.txt
+++ /dev/null
@@ -1 +0,0 @@
-{"error":{"code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin Request id: 0217776464712214e907dae862d8462a9d84f058f87472e323c64","param":"","type":"NotFound"}}
\ No newline at end of file
diff --git a/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.input.json b/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.input.json
deleted file mode 100644
index 2080ed3cd..000000000
--- a/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": false,
-  "attempt": 1,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是严格的世界草稿 JSON 生成器。\n只输出一个 JSON 对象，不要输出 Markdown、代码块、解释或额外文字。"
-    },
-    {
-      "role": "user",
-      "content": "请先根据下面的玩家设定创建一份“世界核心骨架”，后续我会分步骤生成角色名单、场景名单和详细档案。\n你必须只输出一个能被 JSON.parse 直接解析的 JSON 对象，不要输出 Markdown、代码块、注释或解释。\n这一步只保留世界顶层信息与一个开局归处占位，不要输出 playableNpcs、storyNpcs、landmarks，也不要展开人物、地图细节或多幕场景内容。\n玩家设定：\n世界承诺：\"一个由玩具构成的鲜活王国，等待玩家探索与守护。\"\n玩家幻想：\"作为一个误入的人类孩子，你渴望找到回家的路，同时在这个充满秘密与危险的玩具王国中找到自己的位置。\"\n主题边界：\"主题是童真与成长的冒险，美术方向偏向温暖、怀旧但带有神秘感的玩具屋风格，避免过于黑暗或成人化的恐怖元素。\"\n玩家切入口：\"你是一个在阁楼发现一个发光音乐盒的孩子，随着音乐响起，你被缩小并吸入了这个由玩具构成的王国。\"\n核心冲突：\"玩具王国正面临“遗忘之尘”的侵蚀，这会让玩具们失去活力并最终石化。冲突的首次触发，是玩家亲眼目睹一个熟悉的玩具朋友开始变得僵硬。\"\n关键关系：\"与引路者“修补匠泰迪”的师徒关系，他知晓离开的方法但需要帮助；与对立者“兵人指挥官”的竞争关系，他视人类为威胁，但其偏执源于一段被主人遗弃的伤痛。\"\n暗线与揭示节奏：\"玩具王国并非自然存在，它是由孩子们强烈的情感与记忆共同维系的梦境边疆。“遗忘之尘”的真相，是现实世界中孩子们正在长大并逐渐遗忘。\"\n标志元素与硬规则：\"标志性的“心之齿轮”动力源、会说话的绒毛玩具与发条士兵、王国中央的“记忆之树”、硬规则：玩具不能直接伤害人类孩子，但环境与魔法可以。\"\n\n输出 JSON 模板：\n{\n  \"name\": \"世界名称\",\n  \"subtitle\": \"世界副标题\",\n  \"summary\": \"世界概述\",\n  \"tone\": \"世界基调\",\n  \"playerGoal\": \"玩家核心目标\",\n  \"templateWorldType\": \"WUXIA|XIANXIA\",\n  \"majorFactions\": [\"势力甲\", \"势力乙\"],\n  \"coreConflicts\": [\"冲突甲\", \"冲突乙\"],\n  \"attributeSchema\": {\n    \"slots\": [\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" },\n      { \"name\": \"维度名\" }\n    ]\n  },\n  \"camp\": {\n    \"name\": \"开局归处名称\",\n    \"description\": \"这是玩家进入世界后的第一处落脚点描述\"\n  }\n}\n\n要求：\n- 所有生成文本都必须使用中文。\n- 这一步只输出顶层 10 个字段：name、subtitle、summary、tone、playerGoal、templateWorldType、majorFactions、coreConflicts、attributeSchema、camp。\n- 这是一个完全独立的自定义世界；不要在任何正文里直接写出“武侠世界”“仙侠世界”等现成世界名。\n- templateWorldType 只是系统兼容字段，不代表正文应当引用的世界名称。\n- camp 只表示玩家开局时的落脚处占位，更接近归舍、住处、栖居、前哨居所这类“家/归处”的概念；不要在这一步生成开局场景任务、三幕事件或三幕背景。\n- 不要输出 playableNpcs、storyNpcs、landmarks、items，也不要输出任何角色和地图细节。\n- majorFactions 保持 2 到 3 个，coreConflicts 保持 2 到 3 个。\n- attributeSchema 必须是本世界专属的角色六维名称体系，slots 必须恰好 6 个，每个 slot 只输出 name，维度名必须是 2 到 4 个汉字且互不重复。\n- attributeSchema.slots 的 name 禁止使用：生命、法力、护甲、攻击、防御、力量、敏捷、智力、精神；不要写通用 DND 或传统四维属性。\n- 不要在 attributeSchema.slots 内输出 definition、positiveSignals、negativeSignals、combatUseText、socialUseText、explorationUseText 或其他说明字段。\n- 世界设定必须直接源自玩家输入，不要脱离主题乱扩写。\n- 每个字符串尽量简洁：subtitle 控制在 8 到 18 个汉字内，summary 控制在 16 到 32 个汉字内，tone 控制在 6 到 16 个汉字内，playerGoal 控制在 16 到 32 个汉字内，camp.description 控制在 18 到 40 个汉字内。\n- 返回前自检：必须是一个能被 JSON.parse 直接解析的单个 JSON 对象。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.output.txt b/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.output.txt
deleted file mode 100644
index a55e22eb0..000000000
--- a/logs/llm-raw/1777646793980-66824-000002-upstream_status_failed.output.txt
+++ /dev/null
@@ -1 +0,0 @@
-{"error":{"code":"ToolNotOpen","message":"Your account has not activated web search. You may activate it at https://console.volcengine.com/common-buy/CC_content_plugin Request id: 021777646789563cb7552bf2b2738992c27085ac90ab905f9fd41","param":"","type":"NotFound"}}
\ No newline at end of file
diff --git a/logs/llm-raw/1777646955503-66824-000003-request_timeout.input.json b/logs/llm-raw/1777646955503-66824-000003-request_timeout.input.json
deleted file mode 100644
index 23b514602..000000000
--- a/logs/llm-raw/1777646955503-66824-000003-request_timeout.input.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "provider": "ark",
-  "protocol": "responses",
-  "model": "deepseek-v3-2-251201",
-  "stream": false,
-  "attempt": 2,
-  "maxTokens": null,
-  "messages": [
-    {
-      "role": "system",
-      "content": "你是严格的世界草稿 JSON 生成器。\n只输出一个 JSON 对象，不要输出 Markdown、代码块、解释或额外文字。"
-    },
-    {
-      "role": "user",
-      "content": "请根据下面的世界核心信息，生成一批场景角色框架名单。\n后续我会继续补全人物档案，所以这一步每个角色只保留身份骨架与资产默认描述字段。\n你必须只输出一个能被 JSON.parse 直接解析的 JSON 对象，不要输出 Markdown、代码块、注释或解释。\n世界核心信息：\n世界：心忆王国\n副标题：记忆织就的玩具边疆\n世界概述：一个由孩子们强烈情感与记忆维系的玩具梦境世界，正面临遗忘之尘的侵蚀危机。\n世界基调：温暖怀旧中透着神秘感的童真冒险\n玩家核心目标：在寻找回家之路的同时，帮助玩具王国抵抗遗忘之尘的侵蚀，揭开王国存亡的真相。\n主要势力：修补匠工坊、钢铁军团、绒毛议会\n核心冲突：遗忘之尘侵蚀与玩具石化危机、人类孩子身份引发的信任与偏见、守护记忆与面对成长的永恒抉择\n开局归处：修补匠小屋（泰迪的工作室兼临时居所，堆满各种工具与半成品玩具，散发着松木与机油混合的安心气味。）\n输出 JSON 模板：\n{\n  \"storyNpcs\": [\n    {\n      \"name\": \"角色名称\",\n      \"title\": \"称号\",\n      \"role\": \"身份\",\n      \"description\": \"极简定位描述\",\n      \"visualDescription\": \"默认角色形象描述\",\n      \"actionDescription\": \"默认角色动作描述\",\n      \"sceneVisualDescription\": \"默认出现场景描述\",\n      \"initialAffinity\": 18,\n      \"relationshipHooks\": [\"一个关系切入口\"],\n      \"tags\": [\"标签1\", \"标签2\"]\n    }\n  ]\n}\n要求：\n- 必须生成恰好 2 个场景角色。\n- 这是一个完全独立的自定义世界；不要把角色写成来自“武侠世界”“仙侠世界”等现成世界。\n- 名称必须具体且互不重复，不要使用 角色1、NPC1、场景角色1 之类的占位名。\n- 只保留：name、title、role、description、visualDescription、actionDescription、sceneVisualDescription、initialAffinity、relationshipHooks、tags。\n- visualDescription 是打开角色形象图像生成面板时默认填入的角色形象描述，必须具体到体型、服装、轮廓与识别点，控制在 24 到 60 个汉字内。\n- actionDescription 是打开每个角色动作视频生成面板时默认填入的动作描述，必须体现该角色默认动作节奏、武器或施法方式，控制在 18 到 48 个汉字内。\n- sceneVisualDescription 是该角色常出现或关联的场景画面描述，会作为场景生图描述框的默认候选，控制在 24 到 60 个汉字内。\n- relationshipHooks 最多 1 条；tags 保持 1 到 2 个。\n- description 控制在 8 到 18 个汉字内，title 和 role 也尽量短。\n- initialAffinity 必须是 -40 到 90 的整数。\n- 场景角色要覆盖势力成员、居民、异类或怪物，不要全是同一种身份；敌对或怪物型角色可以使用负好感。\n- 所有生成文本都必须使用中文。\n- 返回前自检：必须是一个能被 JSON.parse 直接解析的单个 JSON 对象。"
-    }
-  ]
-}
\ No newline at end of file
diff --git a/logs/llm-raw/1777646955503-66824-000003-request_timeout.output.txt b/logs/llm-raw/1777646955503-66824-000003-request_timeout.output.txt
deleted file mode 100644
index 2947b9223..000000000
--- a/logs/llm-raw/1777646955503-66824-000003-request_timeout.output.txt
+++ /dev/null
@@ -1 +0,0 @@
-LLM 请求超时，累计尝试 2 次
\ No newline at end of file
diff --git a/package.json b/package.json
index 394558f53..6503a77b7 100644
--- a/package.json
+++ b/package.json
@@ -72,8 +72,6 @@
     "deploy:pingora-realpath-canary-disable": "bash scripts/deploy/pingora-realpath-canary-disable.sh",
     "deploy:pingora-direct-enable": "bash scripts/deploy/pingora-direct-enable.sh",
     "deploy:pingora-direct-rollback": "bash scripts/deploy/pingora-direct-rollback.sh",
-    "assets:child-motion-demo": "node scripts/generate-child-motion-demo-assets.mjs",
-    "assets:match3d-style-references": "node scripts/generate-match3d-style-references.mjs",
     "spine-export-validator:dev": "npm --prefix tools/spine-json-export-validator run dev --",
     "spine-export-validator:typecheck": "npm --prefix tools/spine-json-export-validator run typecheck",
     "spine-export-validator:build": "npm --prefix tools/spine-json-export-validator run build",
diff --git a/packages/shared/src/components/PlatformMudPointWalletEntry.test.tsx b/packages/shared/src/components/PlatformMudPointWalletEntry.test.tsx
index dbace6b73..de0c34f56 100644
--- a/packages/shared/src/components/PlatformMudPointWalletEntry.test.tsx
+++ b/packages/shared/src/components/PlatformMudPointWalletEntry.test.tsx
@@ -57,7 +57,7 @@ test('shows only permanent and daily free points in the shared wallet panel', as
   expect(within(details).getByText('每日免费泥点')).toBeTruthy();
   expect(within(details).getByText('27')).toBeTruthy();
   expect(within(details).getByText('每天重置为 20 泥点')).toBeTruthy();
-  expect(onRequestDetails).not.toHaveBeenCalled();
+  expect(onRequestDetails).toHaveBeenCalledTimes(1);
 
   await user.click(within(details).getByRole('button', { name: '使用详情' }));
   expect(onOpenLedger).toHaveBeenCalledTimes(1);
@@ -85,6 +85,61 @@ test('keeps the chip on the live balance when cached details are stale', () => {
   expect(screen.queryByRole('button', { name: '泥点 207' })).toBeNull();
 });
 
+test('refreshes cached balance details while open and after reopening', () => {
+  const onRequestDetails = vi.fn();
+  const { rerender } = render(
+    <PlatformMudPointWalletEntry
+      balance={207}
+      breakdown={breakdown}
+      onRequestDetails={onRequestDetails}
+      onRecharge={vi.fn()}
+      onOpenLedger={vi.fn()}
+    />,
+  );
+
+  const balanceButton = screen.getByRole('button', { name: '泥点 207' });
+  fireEvent.mouseEnter(balanceButton);
+  expect(onRequestDetails).toHaveBeenCalledTimes(1);
+
+  rerender(
+    <PlatformMudPointWalletEntry
+      balance={195}
+      breakdown={breakdown}
+      onRequestDetails={onRequestDetails}
+      onRecharge={vi.fn()}
+      onOpenLedger={vi.fn()}
+    />,
+  );
+
+  expect(screen.getByRole('dialog', { name: '泥点账户详情' })).toBeTruthy();
+  expect(onRequestDetails).toHaveBeenCalledTimes(2);
+
+  fireEvent.pointerDown(document.body);
+  fireEvent.mouseEnter(screen.getByRole('button', { name: '泥点 195' }));
+  expect(onRequestDetails).toHaveBeenCalledTimes(3);
+});
+
+test('requests missing details after the opening balance load completes', () => {
+  const onRequestDetails = vi.fn();
+  const props = {
+    balance: 20,
+    breakdown: null,
+    variant: 'mobile' as const,
+    onRequestDetails,
+    onRecharge: vi.fn(),
+    onOpenLedger: vi.fn(),
+  };
+  const { rerender } = render(
+    <PlatformMudPointWalletEntry {...props} isLoading />,
+  );
+
+  fireEvent.click(screen.getByRole('button', { name: '泥点 20' }));
+  expect(onRequestDetails).not.toHaveBeenCalled();
+
+  rerender(<PlatformMudPointWalletEntry {...props} isLoading={false} />);
+  expect(onRequestDetails).toHaveBeenCalledTimes(1);
+});
+
 test('keeps the desktop panel open while moving across the gap without click pinning', () => {
   vi.useFakeTimers();
 
diff --git a/packages/shared/src/components/PlatformMudPointWalletEntry.tsx b/packages/shared/src/components/PlatformMudPointWalletEntry.tsx
index 57190b210..dd814d33a 100644
--- a/packages/shared/src/components/PlatformMudPointWalletEntry.tsx
+++ b/packages/shared/src/components/PlatformMudPointWalletEntry.tsx
@@ -64,6 +64,7 @@ export function PlatformMudPointWalletEntry({
 }: PlatformMudPointWalletEntryProps) {
   const rootRef = useRef<HTMLDivElement | null>(null);
   const isOpenRef = useRef(false);
+  const requestedDetailsKeyForOpenRef = useRef<string | null>(null);
   const closeTimerRef = useRef<number | null>(null);
   const [isOpen, setIsOpen] = useState(false);
   const isCompact = variant === 'mobile';
@@ -74,6 +75,7 @@ export function PlatformMudPointWalletEntry({
       : formatMudPointCount(displayedBalance, true);
   const exactBalanceLabel =
     displayedBalance === null ? '--' : formatMudPointCount(displayedBalance);
+  const detailsRequestKey = `balance:${balance ?? breakdown?.totalPoints ?? 'unknown'}`;
 
   const cancelPendingClose = useCallback(() => {
     if (closeTimerRef.current !== null) {
@@ -85,9 +87,21 @@ export function PlatformMudPointWalletEntry({
   const closeDetails = useCallback(() => {
     cancelPendingClose();
     isOpenRef.current = false;
+    requestedDetailsKeyForOpenRef.current = null;
     setIsOpen(false);
   }, [cancelPendingClose]);
 
+  const requestDetailsIfNeeded = useCallback(() => {
+    if (
+      isLoading ||
+      requestedDetailsKeyForOpenRef.current === detailsRequestKey
+    ) {
+      return;
+    }
+    requestedDetailsKeyForOpenRef.current = detailsRequestKey;
+    onRequestDetails();
+  }, [detailsRequestKey, isLoading, onRequestDetails]);
+
   const requestAndOpen = useCallback(() => {
     cancelPendingClose();
     if (isOpenRef.current) {
@@ -95,13 +109,17 @@ export function PlatformMudPointWalletEntry({
     }
     isOpenRef.current = true;
     setIsOpen(true);
-    if (!breakdown && !isLoading) {
-      onRequestDetails();
-    }
-  }, [breakdown, cancelPendingClose, isLoading, onRequestDetails]);
+    requestDetailsIfNeeded();
+  }, [cancelPendingClose, requestDetailsIfNeeded]);
 
   useEffect(() => cancelPendingClose, [cancelPendingClose]);
 
+  useEffect(() => {
+    if (isOpen) {
+      requestDetailsIfNeeded();
+    }
+  }, [isOpen, requestDetailsIfNeeded]);
+
   useEffect(() => {
     if (!isOpen) {
       return;
@@ -151,9 +169,7 @@ export function PlatformMudPointWalletEntry({
     <div
       ref={rootRef}
       className={`platform-mud-point-wallet-entry relative shrink-0 ${className ?? ''}`}
-      onMouseEnter={isCompact ? undefined : requestAndOpen}
       onMouseLeave={isCompact ? undefined : closeAfterPointerLeaves}
-      onFocusCapture={isCompact ? undefined : requestAndOpen}
       onBlurCapture={closeAfterFocusLeaves}
     >
       <div
@@ -168,6 +184,8 @@ export function PlatformMudPointWalletEntry({
           aria-expanded={isOpen}
           aria-haspopup="dialog"
           aria-busy={isLoading}
+          onMouseEnter={isCompact ? undefined : requestAndOpen}
+          onFocus={isCompact ? undefined : requestAndOpen}
           onClick={
             isCompact
               ? () => {
diff --git a/packages/shared/src/contracts/customWorldAgent.ts b/packages/shared/src/contracts/customWorldAgent.ts
index e5d115e0f..cff4c959d 100644
--- a/packages/shared/src/contracts/customWorldAgent.ts
+++ b/packages/shared/src/contracts/customWorldAgent.ts
@@ -4,9 +4,9 @@
  * 工作包 H 完成后，真实类型定义已经迁移到 rpg* 契约文件中；这里仅聚合旧命名分文件。
  */
 
+export type * from './customWorldAgentActions';
 export type * from './customWorldAgentAnchors';
 export type * from './customWorldAgentDraft';
-export type * from './customWorldAgentActions';
 export type * from './customWorldAgentSession';
 export type * from './customWorldResultPreview';
 export type * from './customWorldWorkSummary';
diff --git a/packages/shared/src/contracts/customWorldAgentActions.ts b/packages/shared/src/contracts/customWorldAgentActions.ts
index a959bd0a2..ca370a261 100644
--- a/packages/shared/src/contracts/customWorldAgentActions.ts
+++ b/packages/shared/src/contracts/customWorldAgentActions.ts
@@ -9,6 +9,6 @@ export type {
   RpgAgentOperationRecord as CustomWorldAgentOperationRecord,
   RpgAgentOperationStatus as CustomWorldAgentOperationStatus,
   RpgAgentOperationType as CustomWorldAgentOperationType,
-  RpgAgentSupportedAction as CustomWorldSupportedAction,
   RpgAgentSuggestedAction as CustomWorldSuggestedAction,
+  RpgAgentSupportedAction as CustomWorldSupportedAction,
 } from './rpgAgentActions';
diff --git a/packages/shared/src/contracts/customWorldAgentSession.ts b/packages/shared/src/contracts/customWorldAgentSession.ts
index 8a320a404..383281c31 100644
--- a/packages/shared/src/contracts/customWorldAgentSession.ts
+++ b/packages/shared/src/contracts/customWorldAgentSession.ts
@@ -6,15 +6,15 @@
 export type {
   CreateRpgAgentSessionRequest as CreateCustomWorldAgentSessionRequest,
   CreateRpgAgentSessionResponse as CreateCustomWorldAgentSessionResponse,
-  GetRpgAgentCardDetailResponse as GetCustomWorldAgentCardDetailResponse,
+  RpgCreationIntentReadiness as CreatorIntentReadiness,
   RpgAgentMessage as CustomWorldAgentMessage,
   RpgAgentMessageKind as CustomWorldAgentMessageKind,
   RpgAgentMessageRole as CustomWorldAgentMessageRole,
-  RpgAgentPendingClarification as CustomWorldPendingClarification,
   RpgAgentQualityFinding as CustomWorldAgentQualityFinding,
   RpgAgentSessionSnapshot as CustomWorldAgentSessionSnapshot,
   RpgAgentStage as CustomWorldAgentStage,
-  RpgCreationIntentReadiness as CreatorIntentReadiness,
+  RpgAgentPendingClarification as CustomWorldPendingClarification,
+  GetRpgAgentCardDetailResponse as GetCustomWorldAgentCardDetailResponse,
   SendRpgAgentMessageRequest as SendCustomWorldAgentMessageRequest,
   SendRpgAgentMessageResponse as SendCustomWorldAgentMessageResponse,
 } from './rpgAgentSession';
diff --git a/packages/shared/src/contracts/customWorldWorkSummary.ts b/packages/shared/src/contracts/customWorldWorkSummary.ts
index 62a952f9d..53061335a 100644
--- a/packages/shared/src/contracts/customWorldWorkSummary.ts
+++ b/packages/shared/src/contracts/customWorldWorkSummary.ts
@@ -4,8 +4,8 @@
  */
 
 export type {
-  ListRpgCreationWorksResponse as ListCustomWorldWorksResponse,
   RpgCreationWorkSource as CustomWorldWorkSource,
   RpgCreationWorkStatus as CustomWorldWorkStatus,
   RpgCreationWorkSummary as CustomWorldWorkSummary,
+  ListRpgCreationWorksResponse as ListCustomWorldWorksResponse,
 } from './rpgCreationWorkSummary';
diff --git a/packages/shared/src/contracts/editorAgent.ts b/packages/shared/src/contracts/editorAgent.ts
index a7daaeb33..b85143eae 100644
--- a/packages/shared/src/contracts/editorAgent.ts
+++ b/packages/shared/src/contracts/editorAgent.ts
@@ -1,38 +1,18 @@
 // 画布Agent对话契约：会话元数据存 SpacetimeDB，消息正文整体存 OSS（editor-agent/{conversationId}.json）。
 
 export const EDITOR_AGENT_MAX_ATTACHMENTS = 9;
-export const EDITOR_AGENT_TITLE_MAX_CHARS = 20;
-export const EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE = '新对话';
-export const EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION = 1;
+export const EDITOR_AGENT_ERROR_MESSAGE_PREFIX = 'ERROR ';
 
-export type EditorAgentStage =
-  | 'idle'
-  | 'thinking'
-  | 'responding'
-  | 'generating'
-  | 'completed'
-  | 'failed';
+export type EditorAgentMessageRole = 'user' | 'assistant' | 'system';
 
-export type EditorAgentMessageRole = 'user' | 'assistant';
-
-export type EditorAgentMessageKind = 'chat' | 'stage' | 'error';
-
-export type EditorAgentMessageStatus =
-  | 'streaming'
-  | 'generating'
+export type EditorAgentToolCallStatus =
+  | 'not_completed'
   | 'completed'
   | 'failed'
-  | 'stopped';
+  | 'cancelled';
 
 export type EditorAgentAttachmentSource = 'canvas_resource' | 'library_asset';
 
-export type EditorAgentToolName =
-  | 'generate_image'
-  | 'edit_image'
-  | 'generate_character'
-  | 'generate_icon_spritesheet'
-  | 'generate_ui_design';
-
 export interface EditorAgentAttachmentRef {
   source: EditorAgentAttachmentSource;
   referenceId: string;
@@ -45,36 +25,87 @@ export interface EditorAgentAttachmentRef {
 }
 
 export interface EditorAgentGeneratedImage {
-  resourceId: string | null;
+  resourceId?: string | null;
   objectKey?: string | null;
   assetObjectId?: string | null;
   imageSrc: string;
-  thumbnailSrc: string | null;
-  width: number | null;
-  height: number | null;
+  thumbnailSrc?: string | null;
+  width?: number | null;
+  height?: number | null;
 }
 
-export type EditorAgentGenerationStatus = 'generating' | 'completed' | 'failed';
+export interface EditorAgentGeneratedVideo {
+  resourceId?: string | null;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  videoSrc: string;
+  thumbnailSrc?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
 
-export interface EditorAgentGenerationRecord {
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  summary?: string | null;
-  taskId: string | null;
-  status: EditorAgentGenerationStatus;
-  model: string | null;
+export interface EditorAgentGeneratedAudio {
+  resourceId?: string | null;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  audioSrc: string;
+}
+
+export interface EditorAgentToolCallStringArg {
+  name: string;
+  label: string;
+  value: string;
+}
+
+export interface EditorAgentToolCallImageRef {
+  imageId: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  thumbnailSrc?: string | null;
+  label?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface EditorAgentToolCallImageArg {
+  name: string;
+  label: string;
+  refs: EditorAgentToolCallImageRef[];
+}
+
+export interface EditorAgentToolCallDisplayExtras {
+  priceMudPoints: number;
+}
+
+export interface EditorAgentToolCallDisplayArgs {
+  stringArgs: EditorAgentToolCallStringArg[];
+  imageArgs: EditorAgentToolCallImageArg[];
+  extras: EditorAgentToolCallDisplayExtras;
+}
+
+export interface EditorAgentToolCall {
+  toolName: string;
+  status: EditorAgentToolCallStatus;
+  args: unknown;
+  displayArgs: EditorAgentToolCallDisplayArgs;
+  externalJobId?: string | null;
   images: EditorAgentGeneratedImage[];
+  // Older persisted conversation documents do not contain these media fields.
+  videos?: EditorAgentGeneratedVideo[];
+  audios?: EditorAgentGeneratedAudio[];
   error?: string | null;
 }
 
 export interface EditorAgentMessage {
-  id: string;
+  // Frontend must not use this to organize messages.
+  // It is an opaque backend locator for pending tool-call operations.
+  id: number;
+  // Present only on user messages created from a client send request.
+  clientMessageId?: string | null;
   role: EditorAgentMessageRole;
-  kind: EditorAgentMessageKind;
   text: string;
   attachments: EditorAgentAttachmentRef[];
-  generations: EditorAgentGenerationRecord[];
-  status: EditorAgentMessageStatus;
+  toolCall: EditorAgentToolCall | null;
   createdAt: string;
 }
 
@@ -82,12 +113,15 @@ export interface EditorAgentConversationSummary {
   conversationId: string;
   projectId: string;
   title: string;
-  createdAt: string;
   updatedAt: string;
 }
 
-export interface EditorAgentConversationDetail
-  extends EditorAgentConversationSummary {
+export interface EditorAgentConversationDetail {
+  conversationId: string;
+  projectId: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
   messages: EditorAgentMessage[];
 }
 
@@ -109,63 +143,14 @@ export interface EditorAgentConversationResponse {
   conversation: EditorAgentConversationDetail;
 }
 
-export interface StreamEditorAgentMessageRequest {
+export interface EditorAgentMessageRequest {
   clientMessageId: string;
   text: string;
   attachments?: EditorAgentAttachmentRef[];
 }
 
-export interface EditorAgentStageEvent {
-  conversationId: string;
-  stage: EditorAgentStage;
+export interface EditorAgentMessageResponse {
+  conversation: EditorAgentConversationSummary;
+  deltaMessages: EditorAgentMessage[];
+  errorMessage: string | null;
 }
-
-export interface EditorAgentMessageDeltaEvent {
-  conversationId: string;
-  messageId: string;
-  role: EditorAgentMessageRole;
-  kind: EditorAgentMessageKind;
-  textDelta: string;
-}
-
-export interface EditorAgentToolEvent {
-  conversationId: string;
-  messageId: string;
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  summary?: string | null;
-  taskId?: string | null;
-  model?: string | null;
-  status?: EditorAgentGenerationStatus | null;
-  error?: string | null;
-}
-
-export interface EditorAgentGenerationResultEvent {
-  conversationId: string;
-  messageId: string;
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  model: string | null;
-  images: EditorAgentGeneratedImage[];
-}
-
-export interface EditorAgentErrorEvent {
-  conversationId: string | null;
-  code: string;
-  message: string;
-  recoverable: boolean;
-}
-
-export interface EditorAgentDoneEvent {
-  conversationId: string;
-  title: string | null;
-}
-
-export type EditorAgentSseEvent =
-  | { event: 'stage'; data: EditorAgentStageEvent }
-  | { event: 'message_delta'; data: EditorAgentMessageDeltaEvent }
-  | { event: 'tool_started'; data: EditorAgentToolEvent }
-  | { event: 'tool_completed'; data: EditorAgentToolEvent }
-  | { event: 'generation_result'; data: EditorAgentGenerationResultEvent }
-  | { event: 'error'; data: EditorAgentErrorEvent }
-  | { event: 'done'; data: EditorAgentDoneEvent };
diff --git a/packages/shared/src/contracts/hostBridge.test.ts b/packages/shared/src/contracts/hostBridge.test.ts
index 1b79fb6dc..b5999566f 100644
--- a/packages/shared/src/contracts/hostBridge.test.ts
+++ b/packages/shared/src/contracts/hostBridge.test.ts
@@ -1,38 +1,38 @@
 import { describe, expect, test } from 'vitest';
 
 import {
+  HOST_BRIDGE_CAPABILITIES,
+  HOST_BRIDGE_DEFAULT_REQUEST_TIMEOUT_MS,
+  HOST_BRIDGE_DESKTOP_NETWORK_CHECK_TIMEOUT_MS,
+  HOST_BRIDGE_DOCUMENT_MIME_TYPES,
+  HOST_BRIDGE_EVENTS,
   HOST_BRIDGE_EXPO_MOBILE_BASE_CAPABILITIES,
   HOST_BRIDGE_EXPO_MOBILE_IOS_CAPABILITIES,
   HOST_BRIDGE_EXPO_MOBILE_IOS_EXTRA_CAPABILITIES,
-  HOST_BRIDGE_NATIVE_APP_QUERY,
-  HOST_BRIDGE_NATIVE_APP_QUERY_KEY,
-  HOST_BRIDGE_NATIVE_APP_QUERY_KEYS,
-  HOST_BRIDGE_PRESERVED_RUNTIME_CONTEXT_QUERY_KEYS,
-  HOST_BRIDGE_RUNTIME_CONTEXT_QUERY_KEY,
-  HOST_BRIDGE_TAURI_DESKTOP_CAPABILITIES,
-  HOST_BRIDGE_WECHAT_MINI_PROGRAM_CAPABILITIES,
-  HOST_BRIDGE_WECHAT_MINI_PROGRAM_SOURCE_QUERY,
-  HOST_BRIDGE_PUBLIC_WEB_ORIGIN,
-  HOST_BRIDGE_PUBLIC_WEB_URL,
-  HOST_BRIDGE_TAURI_COMMAND,
-  HOST_BRIDGE_CAPABILITIES,
-  HOST_BRIDGE_DOCUMENT_MIME_TYPES,
-  HOST_BRIDGE_DEFAULT_REQUEST_TIMEOUT_MS,
-  HOST_BRIDGE_DESKTOP_NETWORK_CHECK_TIMEOUT_MS,
-  HOST_BRIDGE_EVENTS,
   HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES,
   HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT,
   HOST_BRIDGE_MAX_REQUEST_TIMEOUT_MS,
   HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID,
   HOST_BRIDGE_MOBILE_WEBVIEW_BLOCKED_DOWNLOAD_PROTOCOLS,
+  HOST_BRIDGE_NATIVE_APP_QUERY,
+  HOST_BRIDGE_NATIVE_APP_QUERY_KEY,
+  HOST_BRIDGE_NATIVE_APP_QUERY_KEYS,
+  HOST_BRIDGE_PRESERVED_RUNTIME_CONTEXT_QUERY_KEYS,
+  HOST_BRIDGE_PUBLIC_WEB_ORIGIN,
+  HOST_BRIDGE_PUBLIC_WEB_URL,
   HOST_BRIDGE_RESPONSE_CACHE_MAX,
+  HOST_BRIDGE_RUNTIME_CONTEXT_QUERY_KEY,
   HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS,
   HOST_BRIDGE_SCANNER_TIMEOUT_MS,
+  HOST_BRIDGE_TAURI_COMMAND,
+  HOST_BRIDGE_TAURI_DESKTOP_CAPABILITIES,
   HOST_BRIDGE_TEXT_MIME_TYPES,
   HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS,
-  isHostBridgeMethod,
+  HOST_BRIDGE_WECHAT_MINI_PROGRAM_CAPABILITIES,
+  HOST_BRIDGE_WECHAT_MINI_PROGRAM_SOURCE_QUERY,
   isHostBridgeCapability,
   isHostBridgeEventName,
+  isHostBridgeMethod,
   normalizeHostBridgeAppTitle,
   normalizeHostBridgeBadgeCount,
   normalizeHostBridgeClipboardText,
diff --git a/packages/shared/src/contracts/puzzleAgentActions.ts b/packages/shared/src/contracts/puzzleAgentActions.ts
index bf0f92eec..ae38849b3 100644
--- a/packages/shared/src/contracts/puzzleAgentActions.ts
+++ b/packages/shared/src/contracts/puzzleAgentActions.ts
@@ -1,5 +1,5 @@
-import type { PuzzleAgentSessionSnapshot } from './puzzleAgentSession';
 import type { ExternalGenerationJobStatusRecord } from './externalGeneration';
+import type { PuzzleAgentSessionSnapshot } from './puzzleAgentSession';
 
 export type PuzzleAgentSuggestedActionType =
   | 'request_summary'
diff --git a/packages/shared/src/contracts/rpgAgentSession.ts b/packages/shared/src/contracts/rpgAgentSession.ts
index 0bdb8ef12..bd933b672 100644
--- a/packages/shared/src/contracts/rpgAgentSession.ts
+++ b/packages/shared/src/contracts/rpgAgentSession.ts
@@ -1,4 +1,4 @@
-import type { RpgAgentActionResponse, RpgAgentOperationRecord, RpgAgentSupportedAction, RpgAgentSuggestedAction } from './rpgAgentActions';
+import type { RpgAgentActionResponse, RpgAgentOperationRecord, RpgAgentSuggestedAction,RpgAgentSupportedAction } from './rpgAgentActions';
 import type { RpgCreationAnchorContent } from './rpgAgentAnchors';
 import type { RpgAgentAssetCoverageSummary, RpgAgentDraftCardDetail, RpgAgentDraftCardSummary } from './rpgAgentDraft';
 import type { RpgCreationPreviewEnvelope } from './rpgCreationPreview';
diff --git a/packages/shared/src/contracts/rpgContracts.test.ts b/packages/shared/src/contracts/rpgContracts.test.ts
index 8278d2a0b..f0f9c2f57 100644
--- a/packages/shared/src/contracts/rpgContracts.test.ts
+++ b/packages/shared/src/contracts/rpgContracts.test.ts
@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'vitest';
+
 import type { CustomWorldAgentSessionSnapshot } from './customWorldAgentSession';
 import type { CustomWorldResultPreviewEnvelope } from './customWorldResultPreview';
 import type { CustomWorldWorkSummary } from './customWorldWorkSummary';
-
 import {
   createRpgAgentFoundationDraftProfileFixture,
-  createRpgAgentSupportedActionsFixture,
   createRpgAgentSessionFixture,
+  createRpgAgentSupportedActionsFixture,
   createRpgCreationAnchorContentFixture,
   createRpgCreationPreviewEnvelopeFixture,
   createRpgCreationPublishedProfileFixture,
diff --git a/packages/shared/src/contracts/rpgCreationResultView.ts b/packages/shared/src/contracts/rpgCreationResultView.ts
index 853a3eeb0..1917274cc 100644
--- a/packages/shared/src/contracts/rpgCreationResultView.ts
+++ b/packages/shared/src/contracts/rpgCreationResultView.ts
@@ -1,5 +1,5 @@
-import type { CustomWorldProfileRecord } from './runtime';
 import type { RpgAgentSessionSnapshot } from './rpgAgentSession';
+import type { CustomWorldProfileRecord } from './runtime';
 
 export type RpgCreationResultProfileSource =
   | 'result_preview'
diff --git a/packages/shared/src/http.ts b/packages/shared/src/http.ts
index cfa89536b..bda8f6c94 100644
--- a/packages/shared/src/http.ts
+++ b/packages/shared/src/http.ts
@@ -20,7 +20,7 @@ export type ApiErrorCode =
   | 'conflict'
   | 'upstream_error'
   | 'internal_error'
-  | (string & {});
+  | (string & Record<never, never>);
 
 export type ApiErrorPayload = {
   code: ApiErrorCode;
diff --git a/scripts/check-admin-account-procedures.mjs b/scripts/check-admin-account-procedures.mjs
index 9c8440615..ea49c7f26 100644
--- a/scripts/check-admin-account-procedures.mjs
+++ b/scripts/check-admin-account-procedures.mjs
@@ -20,7 +20,7 @@ const repoRoot = path.resolve(
   '..',
 );
 const database = 'admin-account-smoke';
-const expectedSpacetimeVersion = '2.6.0';
+const expectedSpacetimeVersion = '2.6.1';
 const commandTimeoutMs = 5 * 60 * 1000;
 
 function assert(condition, message) {
diff --git a/scripts/check-database-backup-to-oss.mjs b/scripts/check-database-backup-to-oss.mjs
index bbc8b0fb2..809d54266 100644
--- a/scripts/check-database-backup-to-oss.mjs
+++ b/scripts/check-database-backup-to-oss.mjs
@@ -1,11 +1,28 @@
 #!/usr/bin/env node
 
 import {spawnSync} from 'node:child_process';
-import {existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync} from 'node:fs';
 import {tmpdir} from 'node:os';
 import path from 'node:path';
+import {Readable} from 'node:stream';
 
-import {buildAuthorization, buildCanonicalQuery, uploadArchive} from './database-backup-to-oss.mjs';
+import {
+  buildAuthorization,
+  buildCanonicalQuery,
+  cleanupHistoryCandidates,
+  collectDirectFileEntries,
+  createUploadBandwidthLimiter,
+  discoverHistoryPlan,
+  restoreDirectFilesBackup,
+  restoreDirectFilesLatest,
+  resumeUploadedHistoryBatch,
+  runDirectFilesBackup,
+  uploadArchive,
+  uploadDirectFile,
+  uploadHistoryArchiveWithCleanup,
+  uploadManifestFile,
+} from './database-backup-to-oss.mjs';
 
 const BACKUP_SCRIPT = path.resolve('scripts/database-backup-to-oss.mjs');
 const tmpRoot = mkdtempSync(path.join(tmpdir(), 'genarrative-database-backup-check-'));
@@ -32,9 +49,431 @@ async function main() {
   assertInsufficientSpaceStopsBeforeServiceChanges();
   assertArchiveFailureStillRestoresDependentServices();
   await assertMultipartUploadRetriesAndVerifiesRemoteLength();
+  await assertUploadBandwidthLimiterSharesBudgetAndPropagatesErrors();
+  await assertDirectSmallFileUsesSinglePut();
   await assertMissingPartEtagAbortsMultipartUpload();
   await assertCompleteResponseAmbiguityUsesHeadVerification();
   await assertHeadLengthMismatchAbortsMultipartUpload();
+  await assertHeadShaMismatchAbortsMultipartUpload();
+  await assertManifestUploadUsesShaAndHeadVerification();
+  assertHistoryDiscoversDevAndProductionLayoutsWithMultipleReplicas();
+  assertHistoryRequiresBaselineAndProducesDeterministicDeferredBatch();
+  assertHistoryBackupLockRejectsLiveAndStaleOwners();
+  assertHistorySkipsReplicaWithoutSnapshotAndRejectsMalformedNames();
+  assertHistoryStatDriftPreventsAnyCleanup();
+  await assertHistoryUploadFailureDoesNotDeleteSources();
+  await assertHistorySuccessfulUploadCleansAndIsIdempotent();
+  await assertHistoryResumeReverifiesArchiveAndManifest();
+  await assertDirectFilesPreservePathsAndIncrementWithoutDuplicateUpload();
+  await assertDirectFilesConcurrencyIsBounded();
+  await assertDirectHistoryPublishesCatalogBeforeCleanup();
+  await assertDirectHistoryWithoutCandidatesPublishesLatest();
+  await assertDirectFilesRestoreDownloadsCatalogAndObjects();
+}
+
+function createDirectOssHarness() {
+  const objects = new Map();
+  const uploadedKeys = [];
+  const verifiedKeys = [];
+  const uploadFn = async ({archivePath, objectKey, archiveSha256}) => {
+    const body = readFileSync(archivePath);
+    const sha256 = createHash('sha256').update(body).digest('hex');
+    assertEqual(sha256, archiveSha256, `direct file ${objectKey} 的上传 SHA 必须来自实际内容。`);
+    objects.set(objectKey, {body, contentLength: body.length, sha256});
+    uploadedKeys.push(objectKey);
+    return {objectKey, contentLength: body.length, archiveSha256: sha256, verifiedAt: '2026-07-16T01:00:00.000Z'};
+  };
+  const uploadManifestFn = async ({manifestPath, objectKey}) => {
+    const body = readFileSync(manifestPath);
+    const sha256 = createHash('sha256').update(body).digest('hex');
+    objects.set(objectKey, {body, contentLength: body.length, sha256});
+    uploadedKeys.push(objectKey);
+    return {objectKey, contentLength: body.length, archiveSha256: sha256, verifiedAt: '2026-07-16T01:00:01.000Z'};
+  };
+  const verifyFn = async ({objectKey, contentLength, archiveSha256}) => {
+    verifiedKeys.push(objectKey);
+    const object = objects.get(objectKey);
+    if (!object) {
+      const error = new Error(`missing ${objectKey}`);
+      error.status = 404;
+      throw error;
+    }
+    if (object.contentLength !== contentLength || object.sha256 !== archiveSha256) {
+      throw new Error(`mismatch ${objectKey}`);
+    }
+    return {verifiedAt: '2026-07-16T01:00:02.000Z'};
+  };
+  return {objects, uploadedKeys, verifiedKeys, uploadFn, uploadManifestFn, verifyFn};
+}
+
+async function assertDirectSmallFileUsesSinglePut() {
+  const filePath = path.join(tmpRoot, 'direct-small-file.bin');
+  const body = Buffer.from('small direct object');
+  const sha256 = createHash('sha256').update(body).digest('hex');
+  writeFileSync(filePath, body);
+  const methods = [];
+  let uploadedBytes = 0;
+  const fetchImpl = async (_url, options) => {
+    methods.push(options.method);
+    if (options.method === 'PUT') {
+      for await (const chunk of options.body) {
+        uploadedBytes += chunk.length;
+      }
+      return new Response('', {status: 200, headers: {etag: '"single-etag"'}});
+    }
+    if (options.method === 'HEAD') {
+      return new Response(null, {status: 200, headers: {
+        'content-length': String(body.length),
+        'x-oss-meta-file-sha256': sha256,
+      }});
+    }
+    throw new Error(`unexpected method ${options.method}`);
+  };
+  const result = await uploadDirectFile({
+    archivePath: filePath,
+    bucket: 'backup-bucket',
+    endpoint: 'oss-cn-shanghai.aliyuncs.com',
+    objectKey: 'database-backups/test-db/files/small',
+    accessKeyId: 'test-id',
+    accessKeySecret: 'test-secret',
+    archiveSha256: sha256,
+    fetchImpl,
+    bandwidthLimiter: createUploadBandwidthLimiter(64 * 1024),
+  });
+  assertEqual(result.uploadMode, 'single', '小型逐文件对象必须使用单次 PUT。');
+  assertEqual(methods.join(','), 'PUT,HEAD', '小型逐文件对象只能执行 PUT 后 HEAD 验真，不得进入 multipart。');
+  assertEqual(uploadedBytes, body.length, '逐文件带宽限制流不得丢失上传内容。');
+}
+
+async function assertUploadBandwidthLimiterSharesBudgetAndPropagatesErrors() {
+  assertEqual(createUploadBandwidthLimiter('0'), null, '上传带宽限制为 0 时必须关闭。');
+  assertThrows(
+    () => createUploadBandwidthLimiter('1023'),
+    '必须为空、0 或 >= 1024 的整数',
+    '上传带宽限制必须拒绝过小值。',
+  );
+  const delays = [];
+  const limiter = createUploadBandwidthLimiter(1024, {
+    nowFn: () => 0,
+    sleepImpl: async (delayMs) => {
+      delays.push(delayMs);
+    },
+  });
+  const consume = async (stream) => {
+    let totalBytes = 0;
+    for await (const chunk of stream) {
+      totalBytes += chunk.length;
+    }
+    return totalBytes;
+  };
+  const [firstBytes, secondBytes] = await Promise.all([
+    consume(limiter.wrap(Readable.from([Buffer.alloc(1024), Buffer.alloc(1024)], {objectMode: false}))),
+    consume(limiter.wrap(Readable.from([Buffer.alloc(1024), Buffer.alloc(1024)], {objectMode: false}))),
+  ]);
+  assertEqual(firstBytes + secondBytes, 4096, '共享上传限速器不得丢失并发流内容。');
+  assertEqual(delays.join(','), '1000,2000,3000,4000', '两个并发上传流必须共享同一个累计带宽预算。');
+
+  let sourceError = null;
+  try {
+    await consume(limiter.wrap(Readable.from((async function* failingSource() {
+      yield Buffer.alloc(1);
+      throw new Error('source-read-failed');
+    })(), {objectMode: false})));
+  } catch (error) {
+    sourceError = error;
+  }
+  assertIncludes(sourceError?.message, 'source-read-failed', '限速流必须向上传请求透传源读取错误。');
+}
+
+async function assertDirectFilesPreservePathsAndIncrementWithoutDuplicateUpload() {
+  const root = path.join(tmpRoot, 'direct-files-incremental');
+  const dataDir = path.join(root, 'stdb');
+  const workDir = path.join(root, 'work');
+  mkdirSync(path.join(dataDir, 'replicas', '1', 'snapshots', '00000000000000000010.snapshot_dir', 'objects'), {recursive: true});
+  mkdirSync(path.join(dataDir, 'empty-directory'), {recursive: true});
+  mkdirSync(path.join(dataDir, 'bin', '2.6.0'), {recursive: true});
+  symlinkSync('2.6.0', path.join(dataDir, 'bin', 'current'));
+  writeFileSync(path.join(dataDir, 'control-db'), 'control');
+  writeFileSync(
+    path.join(dataDir, 'replicas', '1', 'snapshots', '00000000000000000010.snapshot_dir', 'objects', 'object.bin'),
+    'snapshot object',
+  );
+  const harness = createDirectOssHarness();
+  const options = {
+    mode: 'full', dataDir, workDir, database: 'test-db', bucket: 'backup-bucket', objectPrefix: 'database-backups',
+    uploadOptions: {}, uploadFn: harness.uploadFn, uploadManifestFn: harness.uploadManifestFn, verifyFn: harness.verifyFn,
+  };
+  const collected = await collectDirectFileEntries({dataDir, database: 'test-db', objectPrefix: 'database-backups'});
+  assertTrue(
+    collected.files.some(({path: filePath}) => filePath === 'replicas/1/snapshots/00000000000000000010.snapshot_dir/objects/object.bin'),
+    'files catalog 必须原样保留 snapshot 内文件的相对路径。',
+  );
+  assertTrue(collected.directories.includes('empty-directory'), 'files catalog 必须保留空目录。');
+  assertTrue(
+    collected.symlinks.some(({path: symlinkPath, target}) => symlinkPath === 'bin/current' && target === '2.6.0'),
+    'files catalog 必须保留指向 data-dir 内部的相对符号链接。',
+  );
+
+  const first = await runDirectFilesBackup(options);
+  assertEqual(first.uploadedCount, 2, '首次 files full 应上传全部普通文件。');
+  assertTrue(!Object.hasOwn(first.catalog, 'dataDir'), '远端 files catalog 不得绑定 staging 主机的绝对 data-dir。');
+  const latestObjectKey = 'database-backups/test-db/latest.json';
+  const latest = JSON.parse(harness.objects.get(latestObjectKey).body.toString('utf8'));
+  assertEqual(latest.latestFullCatalog.catalogId, first.catalogId, 'latest pointer 必须指向已验真的最新 full catalog。');
+  assertTrue(!Object.hasOwn(latest.latestFullCatalog, 'files'), 'latest full ref 不得嵌入 files 数组。');
+  assertTrue(latest.historyCatalogs.every((catalog) => !Object.hasOwn(catalog, 'files')), 'latest history ref 不得嵌入 files 数组。');
+  const immutableUploadsAfterFirst = harness.uploadedKeys.filter((objectKey) => objectKey !== latestObjectKey).length;
+  const repeated = await runDirectFilesBackup(options);
+  assertEqual(repeated.uploadedCount, 0, '相同目录重复运行不得重复上传文件。');
+  assertEqual(
+    harness.uploadedKeys.filter((objectKey) => objectKey !== latestObjectKey).length,
+    immutableUploadsAfterFirst,
+    '相同 catalog 重跑不得重复 PUT 文件或 catalog，但应覆盖验真 latest pointer。',
+  );
+
+  writeFileSync(path.join(dataDir, 'control-db'), 'control changed');
+  writeFileSync(path.join(dataDir, 'new-program.bin'), 'new program');
+  const incremental = await runDirectFilesBackup(options);
+  assertEqual(incremental.uploadedCount, 2, '增量 files full 只应上传新增和变化文件。');
+  assertEqual(incremental.reusedCount, 1, '增量 files full 应复用未变化 snapshot 文件。');
+}
+
+async function assertDirectFilesConcurrencyIsBounded() {
+  const root = path.join(tmpRoot, 'direct-files-concurrency');
+  const dataDir = path.join(root, 'stdb');
+  const workDir = path.join(root, 'work');
+  mkdirSync(dataDir, {recursive: true});
+  for (let index = 0; index < 12; index += 1) {
+    writeFileSync(path.join(dataDir, `file-${index}.bin`), `content-${index}`);
+  }
+  const harness = createDirectOssHarness();
+  let activeUploads = 0;
+  let maxActiveUploads = 0;
+  const uploadFn = async (options) => {
+    activeUploads += 1;
+    maxActiveUploads = Math.max(maxActiveUploads, activeUploads);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    try {
+      return await harness.uploadFn(options);
+    } finally {
+      activeUploads -= 1;
+    }
+  };
+  await runDirectFilesBackup({
+    mode: 'full',
+    dataDir,
+    workDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    objectPrefix: 'database-backups',
+    uploadOptions: {},
+    uploadFn,
+    uploadManifestFn: harness.uploadManifestFn,
+    verifyFn: harness.verifyFn,
+    concurrency: 3,
+  });
+  assertTrue(maxActiveUploads > 1, 'files 备份应按配置并发处理多个对象。');
+  assertTrue(maxActiveUploads <= 3, 'files 备份对象并发数不得超过配置上限。');
+}
+
+async function assertDirectHistoryPublishesCatalogBeforeCleanup() {
+  const fixture = createHistoryFixture('direct-files-history-cleanup', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const harness = createDirectOssHarness();
+  const common = {
+    dataDir: fixture.dataDir,
+    workDir: fixture.workDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    objectPrefix: 'database-backups',
+    uploadOptions: {},
+    uploadFn: harness.uploadFn,
+    verifyFn: harness.verifyFn,
+  };
+  await runDirectFilesBackup({...common, mode: 'full', uploadManifestFn: harness.uploadManifestFn});
+  const plan = discoverHistoryPlan({dataDir: fixture.dataDir});
+  let failure = null;
+  try {
+    await runDirectFilesBackup({
+      ...common,
+      mode: 'history',
+      uploadManifestFn: async () => {
+        throw new Error('synthetic direct catalog failure');
+      },
+    });
+  } catch (error) {
+    failure = error;
+  }
+  assertIncludes(failure?.message ?? '', 'synthetic direct catalog failure', 'direct history catalog 发布失败必须向上返回。');
+  for (const candidate of plan.candidates) {
+    assertTrue(existsSync(path.join(fixture.dataDir, candidate.path)), `direct history catalog 发布失败不得删除: ${candidate.path}`);
+  }
+
+  let pointerFailure = null;
+  try {
+    await runDirectFilesBackup({
+      ...common,
+      mode: 'history',
+      uploadManifestFn: harness.uploadManifestFn,
+      verifyFn: async (options) => {
+        if (options.objectKey.endsWith('/latest.json')) {
+          throw new Error('synthetic latest pointer HEAD failure');
+        }
+        return harness.verifyFn(options);
+      },
+    });
+  } catch (error) {
+    pointerFailure = error;
+  }
+  assertIncludes(pointerFailure?.message ?? '', 'synthetic latest pointer HEAD failure', 'latest pointer HEAD 验真失败必须向上返回。');
+  for (const candidate of plan.candidates) {
+    assertTrue(existsSync(path.join(fixture.dataDir, candidate.path)), `latest pointer 发布失败不得删除: ${candidate.path}`);
+  }
+
+  const success = await runDirectFilesBackup({...common, mode: 'history', uploadManifestFn: harness.uploadManifestFn});
+  assertEqual(success.uploadedCount, 0, 'history 文件已在 full CAS baseline 时不应重复上传内容。');
+  for (const file of success.catalog.files) {
+    assertTrue(
+      harness.verifiedKeys.includes(file.objectKey),
+      `history 清理前必须逐个验真 baseline 复用对象: ${file.path}`,
+    );
+  }
+  assertEqual(success.cleanup?.deletedCount, plan.candidates.length, 'catalog 和 baseline 验真后才应清理全部安全候选。');
+
+  const state = JSON.parse(readFileSync(success.statePath, 'utf8'));
+  const historyCatalogObjectKey = state.historyCatalogs[0].objectKey;
+  harness.objects.delete(historyCatalogObjectKey);
+  let brokenHistoryFailure = null;
+  try {
+    await runDirectFilesBackup({...common, mode: 'history', uploadManifestFn: harness.uploadManifestFn});
+  } catch (error) {
+    brokenHistoryFailure = error;
+  }
+  assertIncludes(
+    brokenHistoryFailure?.message ?? '',
+    `missing ${historyCatalogObjectKey}`,
+    'latest pointer 发布前必须重新验真所有 history catalog 引用。',
+  );
+}
+
+async function assertDirectHistoryWithoutCandidatesPublishesLatest() {
+  const fixture = createHistoryFixture('direct-files-history-empty', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [10], segments: [0]});
+  const harness = createDirectOssHarness();
+  const common = {
+    dataDir: fixture.dataDir,
+    workDir: fixture.workDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    objectPrefix: 'database-backups',
+    uploadOptions: {},
+    uploadFn: harness.uploadFn,
+    uploadManifestFn: harness.uploadManifestFn,
+    verifyFn: harness.verifyFn,
+  };
+  await runDirectFilesBackup({...common, mode: 'full'});
+  const latestObjectKey = 'database-backups/test-db/latest.json';
+  harness.objects.delete(latestObjectKey);
+  const result = await runDirectFilesBackup({...common, mode: 'history'});
+  assertEqual(result.candidateCount, 0, 'fixture 应没有可归档 history 候选。');
+  assertTrue(harness.objects.has(latestObjectKey), 'history 无候选时仍必须从现有 state 发布 latest pointer。');
+  assertTrue(harness.verifiedKeys.includes(latestObjectKey), 'history 无候选时 latest pointer 仍必须 HEAD 验真。');
+}
+
+async function assertDirectFilesRestoreDownloadsCatalogAndObjects() {
+  const root = path.join(tmpRoot, 'direct-files-restore');
+  const dataDir = path.join(root, 'stdb');
+  const workDir = path.join(root, 'work');
+  const restoreDir = path.join(root, 'restore');
+  mkdirSync(path.join(dataDir, 'empty-directory'), {recursive: true});
+  mkdirSync(path.join(dataDir, 'config'), {recursive: true});
+  mkdirSync(path.join(dataDir, 'bin', '2.6.0'), {recursive: true});
+  symlinkSync('2.6.0', path.join(dataDir, 'bin', 'current'));
+  const keyPath = path.join(dataDir, 'config', 'id_ecdsa');
+  writeFileSync(keyPath, 'private key fixture');
+  chmodSync(keyPath, 0o640);
+  const harness = createDirectOssHarness();
+  await runDirectFilesBackup({
+    mode: 'full', dataDir, workDir, database: 'test-db', bucket: 'backup-bucket', objectPrefix: 'database-backups',
+    uploadOptions: {}, uploadFn: harness.uploadFn, uploadManifestFn: harness.uploadManifestFn, verifyFn: harness.verifyFn,
+  });
+  writeFileSync(keyPath, 'updated private key fixture');
+  chmodSync(keyPath, 0o640);
+  const latestFull = await runDirectFilesBackup({
+    mode: 'full', dataDir, workDir, database: 'test-db', bucket: 'backup-bucket', objectPrefix: 'database-backups',
+    uploadOptions: {}, uploadFn: harness.uploadFn, uploadManifestFn: harness.uploadManifestFn, verifyFn: harness.verifyFn,
+  });
+  const restored = await restoreDirectFilesBackup({
+    statePath: latestFull.statePath,
+    restoreDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    uploadOptions: {},
+    downloadBufferFn: async ({objectKey}) => Buffer.from(harness.objects.get(objectKey)?.body ?? ''),
+    downloadFileFn: async ({objectKey, destinationPath}) => {
+      const object = harness.objects.get(objectKey);
+      if (!object) {
+        throw new Error(`missing ${objectKey}`);
+      }
+      writeFileSync(destinationPath, object.body);
+    },
+  });
+  assertEqual(restored.downloadedCount, 1, 'files restore 必须从对象存储下载 catalog 中的普通文件。');
+  assertEqual(readFileSync(path.join(restoreDir, 'config', 'id_ecdsa'), 'utf8'), 'updated private key fixture', 'files restore 必须按最新 full catalog 的原相对路径恢复内容。');
+  assertTrue(existsSync(path.join(restoreDir, 'empty-directory')), 'files restore 必须重建空目录。');
+  assertEqual(statSync(path.join(restoreDir, 'config', 'id_ecdsa')).mode & 0o7777, 0o640, 'files restore 必须恢复文件权限。');
+  assertTrue(lstatSync(path.join(restoreDir, 'bin', 'current')).isSymbolicLink(), 'files restore 必须重建符号链接。');
+  assertEqual(readlinkSync(path.join(restoreDir, 'bin', 'current'), 'utf8'), '2.6.0', 'files restore 必须保留符号链接目标。');
+
+  rmSync(restoreDir, {recursive: true, force: true});
+  const downloadBufferFn = async ({objectKey}) => {
+    const object = harness.objects.get(objectKey);
+    if (!object) {
+      throw new Error(`missing ${objectKey}`);
+    }
+    return Buffer.from(object.body);
+  };
+  let objectDownloadCount = 0;
+  const downloadFileFn = async ({objectKey, destinationPath}) => {
+    objectDownloadCount += 1;
+    const object = harness.objects.get(objectKey);
+    if (!object) {
+      throw new Error(`missing ${objectKey}`);
+    }
+    writeFileSync(destinationPath, object.body);
+  };
+  const dryRun = await restoreDirectFilesLatest({
+    restoreDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    objectPrefix: 'database-backups',
+    uploadOptions: {},
+    dryRun: true,
+    downloadBufferFn,
+    downloadFileFn,
+    verifyFn: harness.verifyFn,
+  });
+  assertEqual(dryRun.catalogId, latestFull.catalogId, 'OSS-only dry-run 必须选择 latestFullCatalog。');
+  assertEqual(dryRun.fileCount, 1, 'OSS-only dry-run 应返回 full catalog 文件数。');
+  assertEqual(dryRun.symlinkCount, 1, 'OSS-only dry-run 应返回 full catalog 符号链接数。');
+  assertEqual(dryRun.totalSizeBytes, String(Buffer.byteLength('updated private key fixture')), 'OSS-only dry-run 应返回总字节数。');
+  assertEqual(objectDownloadCount, 0, 'OSS-only dry-run 不得下载数据对象。');
+  assertTrue(!existsSync(restoreDir), 'OSS-only dry-run 不得创建恢复目录。');
+
+  const latestRestored = await restoreDirectFilesLatest({
+    restoreDir,
+    database: 'test-db',
+    bucket: 'backup-bucket',
+    objectPrefix: 'database-backups',
+    uploadOptions: {},
+    downloadBufferFn,
+    downloadFileFn,
+    verifyFn: harness.verifyFn,
+  });
+  assertEqual(latestRestored.catalogId, latestFull.catalogId, 'OSS-only restore 必须选择 latestFullCatalog。');
+  assertEqual(latestRestored.downloadedCount, 1, 'OSS-only restore 应下载 latest full catalog 的数据对象。');
+  assertEqual(readFileSync(path.join(restoreDir, 'config', 'id_ecdsa'), 'utf8'), 'updated private key fixture', 'OSS-only restore 应还原最新 full 内容。');
+  assertEqual(readlinkSync(path.join(restoreDir, 'bin', 'current'), 'utf8'), '2.6.0', 'OSS-only restore 应还原符号链接。');
 }
 
 function assertCanonicalQueryAndAuthorizationIncludeMultipartParameters() {
@@ -138,6 +577,7 @@ async function assertMultipartUploadRetriesAndVerifiesRemoteLength() {
     Buffer.alloc(partSizeBytes, 'b'),
     Buffer.alloc(17, 'c'),
   ]);
+  const payloadSha256 = createHash('sha256').update(payload).digest('hex');
   mkdirSync(root, {recursive: true});
   writeFileSync(archivePath, payload);
 
@@ -167,7 +607,10 @@ async function assertMultipartUploadRetriesAndVerifiesRemoteLength() {
       return new Response('<CompleteMultipartUploadResult/>', {status: 200, headers: {etag: '"complete-etag"'}});
     }
     if (options.method === 'HEAD') {
-      return new Response(null, {status: 200, headers: {'content-length': String(payload.length)}});
+      return new Response(null, {status: 200, headers: {
+        'content-length': String(payload.length),
+        'x-oss-meta-archive-sha256': payloadSha256,
+      }});
     }
     throw new Error(`unexpected request: ${options.method} ${url}`);
   };
@@ -199,6 +642,7 @@ async function assertMultipartUploadRetriesAndVerifiesRemoteLength() {
   const initiateRequest = requests[0];
   assertTrue(initiateRequest.url.endsWith('?uploads'), 'InitiateMultipartUpload URL 必须使用裸 uploads 参数。');
   assertTrue(!initiateRequest.url.endsWith('?uploads='), 'InitiateMultipartUpload URL 不能把裸参数写成 uploads=。');
+  assertEqual(initiateRequest.headers['x-oss-meta-archive-sha256'], payloadSha256, 'multipart 对象必须保存本地归档 SHA-256 元数据。');
   const firstPartRequests = requests.filter(({method, url}) => method === 'PUT' && new URL(url).searchParams.get('partNumber') === '1');
   assertEqual(firstPartRequests.length, 2, '第一段应产生原请求和一次重试。');
   assertBufferEqual(firstPartRequests[0].body, payload.subarray(0, partSizeBytes), '第一段原请求内容必须完整。');
@@ -222,6 +666,7 @@ async function assertHeadLengthMismatchAbortsMultipartUpload() {
   const archivePath = path.join(root, 'backup.tar.gz');
   const partSizeBytes = 100 * 1024;
   const payload = Buffer.alloc(partSizeBytes + 1, 'x');
+  const payloadSha256 = createHash('sha256').update(payload).digest('hex');
   mkdirSync(root, {recursive: true});
   writeFileSync(archivePath, payload);
 
@@ -240,7 +685,10 @@ async function assertHeadLengthMismatchAbortsMultipartUpload() {
       return new Response('<CompleteMultipartUploadResult/>', {status: 200, headers: {etag: '"complete-etag"'}});
     }
     if (options.method === 'HEAD') {
-      return new Response(null, {status: 200, headers: {'content-length': String(payload.length - 1)}});
+      return new Response(null, {status: 200, headers: {
+        'content-length': String(payload.length - 1),
+        'x-oss-meta-archive-sha256': payloadSha256,
+      }});
     }
     if (options.method === 'DELETE') {
       return new Response(null, {status: 204});
@@ -277,6 +725,122 @@ async function assertHeadLengthMismatchAbortsMultipartUpload() {
   assertTrue(abortRequest?.url.endsWith('?uploadId=mismatch-upload'), 'AbortMultipartUpload 必须携带同一 uploadId。');
 }
 
+async function assertHeadShaMismatchAbortsMultipartUpload() {
+  const root = path.join(tmpRoot, 'multipart-head-sha-mismatch');
+  const archivePath = path.join(root, 'backup.tar.gz');
+  const payload = Buffer.alloc(100 * 1024, 's');
+  mkdirSync(root, {recursive: true});
+  writeFileSync(archivePath, payload);
+  const requests = [];
+  const fetchImpl = async (url, options) => {
+    await readRequestBody(options.body);
+    requests.push({url, method: options.method});
+    const parsedUrl = new URL(url);
+    if (options.method === 'POST' && parsedUrl.search === '?uploads') {
+      return new Response('<InitiateMultipartUploadResult><UploadId>sha-mismatch-upload</UploadId></InitiateMultipartUploadResult>', {status: 200});
+    }
+    if (options.method === 'PUT') {
+      return new Response('', {status: 200, headers: {etag: '"part-etag"'}});
+    }
+    if (options.method === 'POST') {
+      return new Response('<CompleteMultipartUploadResult/>', {status: 200});
+    }
+    if (options.method === 'HEAD') {
+      return new Response(null, {status: 200, headers: {
+        'content-length': String(payload.length),
+        'x-oss-meta-archive-sha256': '0'.repeat(64),
+      }});
+    }
+    if (options.method === 'DELETE') {
+      return new Response(null, {status: 204});
+    }
+    throw new Error(`unexpected request: ${options.method} ${url}`);
+  };
+  let uploadError = null;
+  try {
+    await uploadArchive({
+      archivePath,
+      bucket: 'genarrative-test',
+      endpoint: 'oss-cn-shanghai.aliyuncs.com',
+      objectKey: 'database-backups/test/sha-mismatch.tar.gz',
+      accessKeyId: 'test-access-key',
+      accessKeySecret: 'test-access-secret',
+      partSizeBytes: 100 * 1024,
+      maxAttempts: 1,
+      fetchImpl,
+      nowFn: () => new Date('2026-07-13T10:20:30.000Z'),
+      sleepImpl: async () => {},
+      randomFn: () => 0,
+    });
+  } catch (error) {
+    uploadError = error;
+  }
+  assertIncludes(uploadError?.message ?? '', 'SHA-256 不一致', 'HEAD SHA-256 不一致时上传必须失败。');
+  assertTrue(
+    requests.some(({method, url}) => method === 'DELETE' && url.endsWith('?uploadId=sha-mismatch-upload')),
+    'HEAD SHA-256 不一致后必须 best-effort AbortMultipartUpload。',
+  );
+}
+
+async function assertManifestUploadUsesShaAndHeadVerification() {
+  const root = path.join(tmpRoot, 'manifest-upload');
+  const manifestPath = path.join(root, 'backup.manifest.json');
+  const body = Buffer.from(JSON.stringify({uploadStatus: 'uploaded', catalog: 'x'.repeat(150 * 1024)}));
+  const bodySha256 = createHash('sha256').update(body).digest('hex');
+  mkdirSync(root, {recursive: true});
+  writeFileSync(manifestPath, body);
+  const requests = [];
+  let limitedChunkCount = 0;
+  let limitedBytes = 0;
+  const result = await uploadManifestFile({
+    manifestPath,
+    bucket: 'genarrative-test',
+    endpoint: 'oss-cn-shanghai.aliyuncs.com',
+    objectKey: 'database-backups/test/backup.tar.gz.manifest.json',
+    accessKeyId: 'test-access-key',
+    accessKeySecret: 'test-access-secret',
+    maxAttempts: 1,
+    nowFn: () => new Date('2026-07-13T10:20:30.000Z'),
+    sleepImpl: async () => {},
+    randomFn: () => 0,
+    bandwidthLimiter: {
+      wrap(readable) {
+        return Readable.from((async function* observeLimitedManifest() {
+          for await (const chunk of readable) {
+            limitedChunkCount += 1;
+            limitedBytes += chunk.length;
+            yield chunk;
+          }
+        })(), {objectMode: false});
+      },
+    },
+    fetchImpl: async (url, options) => {
+      const requestBody = await readRequestBody(options.body);
+      requests.push({url, method: options.method, headers: options.headers, body: requestBody});
+      if (options.method === 'PUT') {
+        return new Response(null, {status: 200});
+      }
+      if (options.method === 'HEAD') {
+        return new Response(null, {status: 200, headers: {
+          'x-oss-meta-file-size': String(body.length),
+          'x-oss-meta-archive-sha256': bodySha256,
+        }});
+      }
+      throw new Error(`unexpected request: ${options.method} ${url}`);
+    },
+  });
+  assertEqual(result.archiveSha256, bodySha256, 'manifest 上传结果必须记录本地 SHA-256。');
+  assertBufferEqual(requests.find(({method}) => method === 'PUT')?.body, body, 'manifest PUT 必须上传完整 JSON。');
+  assertEqual(limitedBytes, body.length, 'manifest 必须完整经过上传带宽限制流。');
+  assertTrue(limitedChunkCount > 1, '大型 manifest 必须分块经过限速器，不能整块突发上传。');
+  assertTrue(requests.some(({method}) => method === 'HEAD'), 'manifest PUT 后必须执行 HEAD 验真。');
+  assertEqual(
+    requests.find(({method}) => method === 'PUT')?.headers['x-oss-meta-file-size'],
+    String(body.length),
+    'manifest PUT 必须记录原始字节数，供动态压缩 HEAD 缺少 content-length 时验真。',
+  );
+}
+
 async function assertMissingPartEtagAbortsMultipartUpload() {
   const root = path.join(tmpRoot, 'multipart-missing-etag');
   const archivePath = path.join(root, 'backup.tar.gz');
@@ -331,6 +895,7 @@ async function assertCompleteResponseAmbiguityUsesHeadVerification() {
   const root = path.join(tmpRoot, 'multipart-complete-ambiguity');
   const archivePath = path.join(root, 'backup.tar.gz');
   const payload = Buffer.alloc(100 * 1024, 'c');
+  const payloadSha256 = createHash('sha256').update(payload).digest('hex');
   mkdirSync(root, {recursive: true});
   writeFileSync(archivePath, payload);
 
@@ -354,7 +919,10 @@ async function assertCompleteResponseAmbiguityUsesHeadVerification() {
       return new Response('<Error><Code>NoSuchUpload</Code></Error>', {status: 404});
     }
     if (options.method === 'HEAD') {
-      return new Response(null, {status: 200, headers: {'content-length': String(payload.length)}});
+      return new Response(null, {status: 200, headers: {
+        'content-length': String(payload.length),
+        'x-oss-meta-archive-sha256': payloadSha256,
+      }});
     }
     if (options.method === 'DELETE') {
       return new Response(null, {status: 204});
@@ -385,6 +953,459 @@ async function assertCompleteResponseAmbiguityUsesHeadVerification() {
   assertTrue(!requests.some(({method}) => method === 'DELETE'), 'HEAD 已证实对象完整时不得 Abort 已完成上传。');
 }
 
+function assertHistoryDiscoversDevAndProductionLayoutsWithMultipleReplicas() {
+  const dev = createHistoryFixture('history-dev-layout', {nestedData: false});
+  createReplicaHistory(dev.replicasDir, '1', {
+    snapshots: [0, 187, 279],
+    segments: [0, 188, 280],
+  });
+  createReplicaHistory(dev.replicasDir, '2', {
+    snapshots: [50, 99],
+    segments: [0, 51, 100],
+  });
+  const devPlan = discoverHistoryPlan({dataDir: dev.dataDir});
+  assertEqual(devPlan.replicas.length, 2, 'history 应逐 replica 计算安全边界。');
+  assertEqual(devPlan.candidates.length, 7, '多 replica history 候选数量必须符合 snapshot/segment 边界。');
+  assertTrue(
+    devPlan.candidates.some(({path}) => path === 'replicas/1/clog/00000000000000000000.stdb.log'),
+    'dev 布局应识别边界 segment 之前的 commitlog。',
+  );
+  assertTrue(
+    !devPlan.candidates.some(({path}) => path.includes('00000000000000000188.stdb.log')),
+    '跨越 latest snapshot 的边界 segment 必须保留。',
+  );
+  assertTrue(
+    !devPlan.candidates.some(({path}) => path.includes('00000000000000000279.snapshot_dir')),
+    '每个 replica 的 latest snapshot 必须保留。',
+  );
+
+  const production = createHistoryFixture('history-production-layout', {nestedData: true});
+  createReplicaHistory(production.replicasDir, '7', {
+    snapshots: [10, 20],
+    segments: [0, 11, 21],
+  });
+  const productionPlan = discoverHistoryPlan({dataDir: production.dataDir});
+  assertEqual(productionPlan.replicasDir, 'data/replicas', 'history 必须兼容 /stdb/data/replicas 布局。');
+  assertEqual(productionPlan.candidates.length, 3, 'production 布局应识别一个旧 snapshot 与一对旧 commitlog 文件。');
+
+  const importResult = runHistoryDryRun(dev);
+  assertStatus(importResult, 0, 'history dry-run 应能从已有 uploaded baseline manifest 导入 state。');
+  assertTrue(existsSync(dev.statePath), 'history dry-run 应持久化导入后的 baseline state。');
+  assertIncludes(importResult.stdout, 'history dry-run', 'history dry-run 应明确说明不会上传或删除。');
+  for (const candidate of devPlan.candidates) {
+    assertTrue(existsSync(path.join(dev.dataDir, candidate.path)), `history dry-run 不得删除候选: ${candidate.path}`);
+  }
+}
+
+function assertHistorySkipsReplicaWithoutSnapshotAndRejectsMalformedNames() {
+  const noSnapshot = createHistoryFixture('history-no-snapshot', {nestedData: false});
+  createReplicaHistory(noSnapshot.replicasDir, '1', {snapshots: [], segments: [0]});
+  const plan = discoverHistoryPlan({dataDir: noSnapshot.dataDir});
+  assertEqual(plan.candidates.length, 0, '没有 snapshot 的 replica 不得产生可删除候选。');
+  assertEqual(plan.replicas[0]?.reason, 'no-snapshot', '没有 snapshot 时应记录明确跳过原因。');
+
+  const incompleteSnapshot = createHistoryFixture('history-incomplete-snapshot', {nestedData: false});
+  const incompleteReplica = createReplicaHistory(incompleteSnapshot.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  mkdirSync(path.join(incompleteReplica.snapshotsDir, '00000000000000000020.snapshot_dir'));
+  mkdirSync(path.join(incompleteReplica.snapshotsDir, '00000000000000000030.snapshot_dir'));
+  writeFileSync(path.join(incompleteReplica.snapshotsDir, '00000000000000000030.snapshot_dir', '00000000000000000030.snapshot_bsatn'), 'locked');
+  writeFileSync(path.join(incompleteReplica.snapshotsDir, '00000000000000000030.lock'), `${process.pid}\n`);
+  const incompletePlan = discoverHistoryPlan({dataDir: incompleteSnapshot.dataDir});
+  assertEqual(incompletePlan.replicas[0]?.latestSnapshot, '10', '缺少 snapshot_bsatn 或仍有 lockfile 的目录不得成为 latest snapshot。');
+  assertTrue(
+    !incompletePlan.candidates.some(({path}) => path.includes('00000000000000000010.snapshot_dir')),
+    '最后一个完整且未锁定的 snapshot 必须保留。',
+  );
+
+  const malformedLog = createHistoryFixture('history-malformed-log', {nestedData: false});
+  const malformedLogReplica = createReplicaHistory(malformedLog.replicasDir, '1', {snapshots: [10], segments: [0, 11]});
+  writeFileSync(path.join(malformedLogReplica.clogDir, 'broken.stdb.log'), 'broken');
+  assertThrows(
+    () => discoverHistoryPlan({dataDir: malformedLog.dataDir}),
+    'commitlog 文件名不符合预期',
+    '异常 commitlog 名称必须阻断整个清理计划。',
+  );
+}
+
+function assertHistoryRequiresBaselineAndProducesDeterministicDeferredBatch() {
+  const missingBaseline = createHistoryFixture('history-missing-baseline', {nestedData: false});
+  createReplicaHistory(missingBaseline.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  rmSync(missingBaseline.baselineManifestPath, {force: true});
+  const missingResult = runHistoryCommand(missingBaseline, ['--dry-run'], {includeBaselineManifest: false});
+  assertStatus(missingResult, 1, 'history 没有 baseline state 或 imported manifest 时必须失败。');
+  assertIncludes(missingResult.stderr, '缺少已验真 baseline state', 'baseline 门禁失败应给出明确错误。');
+
+  const wrongKind = createHistoryFixture('history-wrong-baseline-kind', {nestedData: false});
+  createReplicaHistory(wrongKind.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const wrongKindManifest = JSON.parse(readFileSync(wrongKind.baselineManifestPath, 'utf8'));
+  wrongKindManifest.backupKind = 'spacetimedb-history';
+  writeFileSync(wrongKind.baselineManifestPath, `${JSON.stringify(wrongKindManifest)}\n`);
+  const wrongKindResult = runHistoryDryRun(wrongKind);
+  assertStatus(wrongKindResult, 1, 'history archive manifest 不得被导入为 full baseline。');
+  assertIncludes(wrongKindResult.stderr, 'backupKind 必须是 spacetimedb-data-dir', 'baseline 类型不匹配应失败关闭。');
+
+  const deterministic = createHistoryFixture('history-deterministic-batch', {nestedData: false});
+  createReplicaHistory(deterministic.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  importHistoryState(deterministic);
+  const firstResultFile = path.join(deterministic.workDir, 'defer-first.json');
+  const secondResultFile = path.join(deterministic.workDir, 'defer-second.json');
+  const first = runHistoryCommand(deterministic, ['--defer-upload', '--result-file', firstResultFile]);
+  const second = runHistoryCommand(deterministic, ['--defer-upload', '--result-file', secondResultFile]);
+  assertStatus(first, 0, '第一次 history defer 应成功生成归档。');
+  assertStatus(second, 0, '相同候选重复 history defer 应幂等复用 batch identity。');
+  const firstPayload = JSON.parse(readFileSync(firstResultFile, 'utf8'));
+  const secondPayload = JSON.parse(readFileSync(secondResultFile, 'utf8'));
+  assertEqual(firstPayload.batchId, secondPayload.batchId, '相同 baseline 与候选必须生成确定性 batchId。');
+  assertEqual(firstPayload.objectKey, secondPayload.objectKey, '相同 batch 重跑不得制造新的 OSS object key。');
+  const archiveListing = spawnSync('tar', ['-tzf', firstPayload.archivePath], {encoding: 'utf8'});
+  assertStatus(archiveListing, 0, 'history 归档应可被 tar 正常读取。');
+  assertIncludes(archiveListing.stdout, path.basename(firstPayload.manifestPath), 'history 归档内部必须携带安全候选 manifest。');
+
+  const dryRunPending = createHistoryFixture('history-dry-run-pending-cleanup', {nestedData: false});
+  createReplicaHistory(dryRunPending.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const dryRunState = importHistoryState(dryRunPending);
+  const dryRunPlan = discoverHistoryPlan({dataDir: dryRunPending.dataDir});
+  dryRunState.batches.push({
+    batchId: 'pending-cleanup',
+    objectKey: 'database-backups/test-db/history/pending-cleanup.tar.gz',
+    contentLength: 10,
+    verifiedAt: '2026-07-16T00:20:00.000Z',
+    uploadedAt: '2026-07-16T00:20:00.000Z',
+    status: 'uploaded',
+    candidates: dryRunPlan.candidates,
+  });
+  writeFileSync(dryRunPending.statePath, `${JSON.stringify(dryRunState)}\n`);
+  const pendingDryRunResult = runHistoryDryRun(dryRunPending);
+  assertStatus(pendingDryRunResult, 0, '存在待清理 uploaded batch 时 history dry-run 仍应只读成功。');
+  for (const candidate of dryRunPlan.candidates) {
+    assertTrue(existsSync(path.join(dryRunPending.dataDir, candidate.path)), `history dry-run 不得恢复执行待清理 batch: ${candidate.path}`);
+  }
+}
+
+function assertHistoryBackupLockRejectsLiveAndStaleOwners() {
+  const liveOwner = createHistoryFixture('history-live-lock', {nestedData: false});
+  createReplicaHistory(liveOwner.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  importHistoryState(liveOwner);
+  const liveLockPath = path.join(liveOwner.workDir, 'test-db.backup.lock');
+  writeFileSync(liveLockPath, `${process.pid}\n`);
+  const liveResult = runHistoryCommand(liveOwner, ['--defer-upload']);
+  assertStatus(liveResult, 1, '仍存活进程持有 backup lock 时必须拒绝并发备份。');
+  assertIncludes(liveResult.stderr, '已有数据库备份进程持有锁', '并发备份失败应报告 lock owner pid。');
+
+  const staleOwner = createHistoryFixture('history-stale-lock', {nestedData: false});
+  createReplicaHistory(staleOwner.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  importHistoryState(staleOwner);
+  const staleLockPath = path.join(staleOwner.workDir, 'test-db.backup.lock');
+  writeFileSync(staleLockPath, '2147483647\n');
+  const staleResult = runHistoryCommand(staleOwner, ['--defer-upload']);
+  assertStatus(staleResult, 1, '失效 owner pid 的 backup lock 也必须失败关闭，避免并发抢锁。');
+  assertIncludes(staleResult.stderr, '拒绝自动抢锁', '失效 backup lock 应要求人工核对 multipart 与进程。');
+  assertTrue(existsSync(staleLockPath), '失效 backup lock 未经人工核对不得自动删除。');
+}
+
+function assertHistoryStatDriftPreventsAnyCleanup() {
+  const fixture = createHistoryFixture('history-stat-drift', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const plan = discoverHistoryPlan({dataDir: fixture.dataDir});
+  const driftCandidate = plan.candidates.find(({kind}) => kind === 'commitlog');
+  const untouchedCandidate = plan.candidates.find(({kind}) => kind === 'snapshot');
+  writeFileSync(path.join(fixture.dataDir, driftCandidate.path), 'changed-after-plan');
+  assertThrows(
+    () => cleanupHistoryCandidates({dataDir: fixture.dataDir, candidates: plan.candidates}),
+    'stat 漂移',
+    '任一候选 stat 漂移时必须在删除任何文件前失败。',
+  );
+  assertTrue(existsSync(path.join(fixture.dataDir, untouchedCandidate.path)), 'stat 漂移失败时不得删除其他候选。');
+}
+
+async function assertHistoryUploadFailureDoesNotDeleteSources() {
+  const fixture = createHistoryFixture('history-upload-failure', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const state = importHistoryState(fixture);
+  const plan = discoverHistoryPlan({dataDir: fixture.dataDir});
+  const archivePath = path.join(fixture.workDir, 'history.tar.gz');
+  const manifestPath = `${archivePath}.manifest.json`;
+  writeFileSync(archivePath, 'history archive');
+  const manifest = createHistoryManifest({fixture, state, plan, archivePath});
+  writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`);
+
+  let uploadError = null;
+  try {
+    await uploadHistoryArchiveWithCleanup({
+      archivePath,
+      manifestPath,
+      manifest,
+      statePath: fixture.statePath,
+      uploadOptions: {},
+      uploadFn: async () => {
+        throw new Error('synthetic upload failure');
+      },
+      manifestUploadFn: async () => {
+        throw new Error('manifest upload must not run after archive failure');
+      },
+    });
+  } catch (error) {
+    uploadError = error;
+  }
+  assertIncludes(uploadError?.message ?? '', 'synthetic upload failure', 'history 应保留上传失败原因。');
+  for (const candidate of plan.candidates) {
+    assertTrue(existsSync(path.join(fixture.dataDir, candidate.path)), `上传失败不得删除 history 源文件: ${candidate.path}`);
+  }
+  const stateAfterFailure = JSON.parse(readFileSync(fixture.statePath, 'utf8'));
+  assertEqual(stateAfterFailure.batches.length, 0, '上传失败不得把 batch 标记为 uploaded。');
+
+  const manifestFailure = createHistoryFixture('history-manifest-upload-failure', {nestedData: false});
+  createReplicaHistory(manifestFailure.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const manifestFailureState = importHistoryState(manifestFailure);
+  const manifestFailurePlan = discoverHistoryPlan({dataDir: manifestFailure.dataDir});
+  const manifestFailureArchive = path.join(manifestFailure.workDir, 'history.tar.gz');
+  const manifestFailurePath = `${manifestFailureArchive}.manifest.json`;
+  writeFileSync(manifestFailureArchive, 'history archive');
+  const manifestFailurePayload = createHistoryManifest({
+    fixture: manifestFailure,
+    state: manifestFailureState,
+    plan: manifestFailurePlan,
+    archivePath: manifestFailureArchive,
+  });
+  writeFileSync(manifestFailurePath, `${JSON.stringify(manifestFailurePayload)}\n`);
+  let manifestUploadError = null;
+  try {
+    await uploadHistoryArchiveWithCleanup({
+      archivePath: manifestFailureArchive,
+      manifestPath: manifestFailurePath,
+      manifest: manifestFailurePayload,
+      statePath: manifestFailure.statePath,
+      uploadOptions: {},
+      uploadFn: async () => ({
+        bucket: 'backup-bucket',
+        objectKey: manifestFailurePayload.objectKey,
+        contentLength: 15,
+        archiveSha256: 'c'.repeat(64),
+        verifiedAt: '2026-07-16T00:05:00.000Z',
+      }),
+      manifestUploadFn: async () => {
+        throw new Error('synthetic manifest upload failure');
+      },
+    });
+  } catch (error) {
+    manifestUploadError = error;
+  }
+  assertIncludes(manifestUploadError?.message ?? '', 'synthetic manifest upload failure', 'sidecar manifest 上传失败应阻断清理。');
+  for (const candidate of manifestFailurePlan.candidates) {
+    assertTrue(existsSync(path.join(manifestFailure.dataDir, candidate.path)), `manifest 上传失败不得删除源文件: ${candidate.path}`);
+  }
+}
+
+async function assertHistorySuccessfulUploadCleansAndIsIdempotent() {
+  const fixture = createHistoryFixture('history-upload-success', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const state = importHistoryState(fixture);
+  const plan = discoverHistoryPlan({dataDir: fixture.dataDir});
+  const archivePath = path.join(fixture.workDir, 'history.tar.gz');
+  const manifestPath = `${archivePath}.manifest.json`;
+  writeFileSync(archivePath, 'history archive');
+  const manifest = createHistoryManifest({fixture, state, plan, archivePath});
+  writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`);
+  let baselineVerifyCount = 0;
+  const result = await uploadHistoryArchiveWithCleanup({
+    archivePath,
+    manifestPath,
+    manifest,
+    statePath: fixture.statePath,
+    uploadOptions: {},
+    uploadFn: async () => ({
+      bucket: 'backup-bucket',
+      objectKey: manifest.objectKey,
+      contentLength: 15,
+      archiveSha256: 'b'.repeat(64),
+      etag: 'test-etag',
+      uploadMode: 'multipart',
+      partCount: 1,
+      partSizeBytes: 102400,
+      verifiedAt: '2026-07-16T00:10:00.000Z',
+    }),
+    manifestUploadFn: async ({objectKey}) => ({
+      objectKey,
+      contentLength: 512,
+      archiveSha256: 'd'.repeat(64),
+      verifiedAt: '2026-07-16T00:10:01.000Z',
+    }),
+    verifyFn: async () => {
+      baselineVerifyCount += 1;
+      return {verifiedAt: '2026-07-16T00:10:02.000Z'};
+    },
+  });
+  assertEqual(baselineVerifyCount, 2, 'history 删除源文件前必须重新验真 full baseline 与 sidecar。');
+  assertEqual(result.cleanup.deletedCount, plan.candidates.length, '验真上传成功后应删除全部安全候选。');
+  for (const candidate of plan.candidates) {
+    assertTrue(!existsSync(path.join(fixture.dataDir, candidate.path)), `验真成功后应删除 history 源文件: ${candidate.path}`);
+  }
+  const repeatedCleanup = cleanupHistoryCandidates({dataDir: fixture.dataDir, candidates: plan.candidates});
+  assertEqual(repeatedCleanup.alreadyMissingCount, plan.candidates.length, '重复清理同一 uploaded batch 应幂等。');
+}
+
+async function assertHistoryResumeReverifiesArchiveAndManifest() {
+  const fixture = createHistoryFixture('history-resume-verification', {nestedData: false});
+  createReplicaHistory(fixture.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const state = importHistoryState(fixture);
+  const plan = discoverHistoryPlan({dataDir: fixture.dataDir});
+  state.batches.push({
+    batchId: 'resume-batch',
+    objectKey: 'database-backups/test-db/history/resume.tar.gz',
+    contentLength: 100,
+    archiveSha256: 'e'.repeat(64),
+    verifiedAt: '2026-07-16T00:30:00.000Z',
+    manifestObjectKey: 'database-backups/test-db/history/resume.tar.gz.manifest.json',
+    manifestContentLength: 200,
+    manifestArchiveSha256: 'f'.repeat(64),
+    manifestVerifiedAt: '2026-07-16T00:30:01.000Z',
+    uploadedAt: '2026-07-16T00:30:00.000Z',
+    status: 'uploaded',
+    candidates: plan.candidates,
+  });
+  writeFileSync(fixture.statePath, `${JSON.stringify(state)}\n`);
+  const verifiedKeys = [];
+  await resumeUploadedHistoryBatch({
+    statePath: fixture.statePath,
+    state,
+    dataDir: fixture.dataDir,
+    verificationOptions: {},
+    verifyFn: async ({objectKey}) => {
+      verifiedKeys.push(objectKey);
+      return {verifiedAt: '2026-07-16T00:31:00.000Z'};
+    },
+  });
+  assertEqual(verifiedKeys.length, 2, '续清理前必须重新验真 history archive 与 sidecar manifest。');
+  for (const candidate of plan.candidates) {
+    assertTrue(!existsSync(path.join(fixture.dataDir, candidate.path)), `续清理验真后应删除候选: ${candidate.path}`);
+  }
+
+  const failure = createHistoryFixture('history-resume-verification-failure', {nestedData: false});
+  createReplicaHistory(failure.replicasDir, '1', {snapshots: [0, 10], segments: [0, 1, 11]});
+  const failureState = importHistoryState(failure);
+  const failurePlan = discoverHistoryPlan({dataDir: failure.dataDir});
+  failureState.batches.push({...state.batches[0], candidates: failurePlan.candidates});
+  writeFileSync(failure.statePath, `${JSON.stringify(failureState)}\n`);
+  let resumeError = null;
+  try {
+    await resumeUploadedHistoryBatch({
+      statePath: failure.statePath,
+      state: failureState,
+      dataDir: failure.dataDir,
+      verificationOptions: {},
+      verifyFn: async () => {
+        throw new Error('synthetic resume HEAD failure');
+      },
+    });
+  } catch (error) {
+    resumeError = error;
+  }
+  assertIncludes(resumeError?.message ?? '', 'synthetic resume HEAD failure', '续清理 OSS 复核失败应保留错误。');
+  for (const candidate of failurePlan.candidates) {
+    assertTrue(existsSync(path.join(failure.dataDir, candidate.path)), `续清理验真失败不得删除候选: ${candidate.path}`);
+  }
+}
+
+function createHistoryFixture(name, {nestedData}) {
+  const root = path.join(tmpRoot, name);
+  const dataDir = path.join(root, 'stdb');
+  const replicasDir = nestedData ? path.join(dataDir, 'data', 'replicas') : path.join(dataDir, 'replicas');
+  const workDir = path.join(root, 'work');
+  const statePath = path.join(workDir, 'history-state.json');
+  const baselineManifestPath = path.join(workDir, 'baseline.manifest.json');
+  mkdirSync(replicasDir, {recursive: true});
+  mkdirSync(workDir, {recursive: true});
+  writeFileSync(baselineManifestPath, `${JSON.stringify({
+    backupKind: 'spacetimedb-data-dir',
+    uploadStatus: 'uploaded',
+    database: 'test-db',
+    dataDir,
+    bucket: 'backup-bucket',
+    objectKey: 'database-backups/test-db/baseline.tar.gz',
+    manifestObjectKey: 'database-backups/test-db/baseline.tar.gz.manifest.json',
+    contentLength: 1234,
+    archiveSha256: 'a'.repeat(64),
+    manifestContentLength: 512,
+    manifestArchiveSha256: '9'.repeat(64),
+    manifestVerifiedAt: '2026-07-16T00:00:00.500Z',
+    verifiedAt: '2026-07-16T00:00:00.000Z',
+    uploadedAt: '2026-07-16T00:00:01.000Z',
+  }, null, 2)}\n`);
+  return {root, dataDir, replicasDir, workDir, statePath, baselineManifestPath};
+}
+
+function createReplicaHistory(replicasDir, replicaId, {snapshots, segments}) {
+  const replicaDir = path.join(replicasDir, replicaId);
+  const snapshotsDir = path.join(replicaDir, 'snapshots');
+  const clogDir = path.join(replicaDir, 'clog');
+  mkdirSync(snapshotsDir, {recursive: true});
+  mkdirSync(clogDir, {recursive: true});
+  for (const transaction of snapshots) {
+    const name = `${String(transaction).padStart(20, '0')}.snapshot_dir`;
+    const snapshotDir = path.join(snapshotsDir, name);
+    mkdirSync(path.join(snapshotDir, 'objects'), {recursive: true});
+    writeFileSync(path.join(snapshotDir, `${String(transaction).padStart(20, '0')}.snapshot_bsatn`), `snapshot-${transaction}`);
+    writeFileSync(path.join(snapshotDir, 'objects', 'object.bin'), `object-${transaction}`);
+  }
+  for (const transaction of segments) {
+    const prefix = String(transaction).padStart(20, '0');
+    writeFileSync(path.join(clogDir, `${prefix}.stdb.log`), `log-${transaction}`);
+    writeFileSync(path.join(clogDir, `${prefix}.stdb.ofs`), `ofs-${transaction}`);
+  }
+  return {replicaDir, snapshotsDir, clogDir};
+}
+
+function runHistoryDryRun(fixture) {
+  const resultFile = path.join(fixture.workDir, 'dry-run-result.json');
+  return runHistoryCommand(fixture, [
+    '--result-file', resultFile,
+    '--dry-run',
+  ]);
+}
+
+function runHistoryCommand(fixture, extraArgs = [], {includeBaselineManifest = true} = {}) {
+  const baselineManifestArgs = includeBaselineManifest
+    ? ['--baseline-manifest', fixture.baselineManifestPath]
+    : [];
+  return spawnSync(process.execPath, [
+    BACKUP_SCRIPT,
+    '--mode', 'history',
+    '--data-dir', fixture.dataDir,
+    '--work-dir', fixture.workDir,
+    '--database', 'test-db',
+    '--bucket', 'backup-bucket',
+    '--endpoint', 'oss-cn-shanghai.aliyuncs.com',
+    '--access-key-id', 'test-access-key',
+    '--access-key-secret', 'test-access-secret',
+    '--baseline-state', fixture.statePath,
+    ...baselineManifestArgs,
+    ...extraArgs,
+  ], {encoding: 'utf8'});
+}
+
+function importHistoryState(fixture) {
+  const result = runHistoryDryRun(fixture);
+  assertStatus(result, 0, '测试 fixture 应能导入 baseline state。');
+  return JSON.parse(readFileSync(fixture.statePath, 'utf8'));
+}
+
+function createHistoryManifest({fixture, state, plan, archivePath}) {
+  return {
+    schemaVersion: 1,
+    backupKind: 'spacetimedb-history',
+    database: 'test-db',
+    dataDir: fixture.dataDir,
+    bucket: 'backup-bucket',
+    objectKey: `database-backups/test-db/history/${state.baseline.id}/test-batch.tar.gz`,
+    archivePath,
+    baselineId: state.baseline.id,
+    baselineStatePath: fixture.statePath,
+    batchId: 'test-batch',
+    candidates: plan.candidates,
+    uploadStatus: 'pending',
+  };
+}
+
 async function readRequestBody(body) {
   if (body === undefined || body === null) {
     return Buffer.alloc(0);
@@ -502,6 +1523,20 @@ function assertTrue(condition, reason) {
   }
 }
 
+function assertThrows(callback, expectedMessage, reason) {
+  let thrown = null;
+  try {
+    callback();
+  } catch (error) {
+    thrown = error;
+  }
+  if (!(thrown instanceof Error)) {
+    failures.push(`${reason} 预期抛出错误。`);
+    return;
+  }
+  assertIncludes(thrown.message, expectedMessage, reason);
+}
+
 function assertBufferEqual(actual, expected, reason) {
   if (!Buffer.isBuffer(actual) || !actual.equals(expected)) {
     failures.push(`${reason} 预期 ${expected.length} bytes，实际 ${actual?.length ?? '<missing>'} bytes。`);
diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs
index 9de7d220e..3d661baf5 100644
--- a/scripts/check-native-shells.mjs
+++ b/scripts/check-native-shells.mjs
@@ -1411,47 +1411,7 @@ const desktopCapabilityFlowContracts = [
     ],
   },
 ];
-const h5NativeAppRouteFlowContracts = [
-  {
-    route: '/child-motion-demo',
-    label: 'child motion demo',
-    files: [
-      'src/components/platform-entry/PlatformEntryFlowShellImpl.tsx',
-      'src/routing/appRoutes.tsx',
-      'src/routing/appRoutes.test.ts',
-      'src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx',
-    ],
-    snippets: [
-      [
-        'src/components/platform-entry/PlatformEntryFlowShellImpl.tsx',
-        "navigateHostNativePage('/child-motion-demo')",
-      ],
-      [
-        'src/components/platform-entry/PlatformEntryFlowShellImpl.tsx',
-        "window.location.assign('/child-motion-demo')",
-      ],
-      ['src/routing/appRoutes.tsx', "normalizedPath === '/child-motion-demo'"],
-      ['src/routing/appRoutes.test.ts', "matchAppRoute('/child-motion-demo')"],
-      [
-        'src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx',
-        "request.method === 'navigation.openNativePage'",
-      ],
-      [
-        'src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx',
-        "url === '/child-motion-demo'",
-      ],
-    ],
-    tests: [
-      'src/routing/appRoutes.test.ts',
-    ],
-    targetedTests: [
-      {
-        filePath: 'src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx',
-        name: 'native app opens child motion demo through host navigation bridge',
-      },
-    ],
-  },
-];
+const h5NativeAppRouteFlowContracts = [];
 const expectedWechatHostBridgeFiles = [
   'dispatch.js',
   'payment.js',
@@ -1758,8 +1718,6 @@ const h5HostBridgeTests = [
   'src/services/clipboard.test.ts',
   'src/services/appTitle.test.ts',
 ];
-const h5PlatformHostBridgeIntegrationTest =
-  'native app jump hop draft completion sends host notification and badge from platform shell';
 const h5NativeAppRouteFlowTestSteps = h5NativeAppRouteFlowContracts.flatMap(
   (contract) =>
     (contract.targetedTests ?? []).map((test) => ({
@@ -1790,18 +1748,6 @@ const steps = [
     command: npmCommand,
     args: ['run', 'test', '--', ...h5HostBridgeTests],
   },
-  {
-    label: 'h5-platform-host-bridge-integration',
-    command: npmCommand,
-    args: [
-      'run',
-      'test',
-      '--',
-      'src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx',
-      '-t',
-      h5PlatformHostBridgeIntegrationTest,
-    ],
-  },
   ...h5NativeAppRouteFlowTestSteps,
   {
     label: 'wechat-shell-tests',
@@ -1833,6 +1779,11 @@ const steps = [
     command: npmCommand,
     args: ['run', 'mobile-shell:export'],
   },
+  {
+    label: 'desktop-shell-test',
+    command: npmCommand,
+    args: ['run', 'desktop-shell:test'],
+  },
   {
     label: 'desktop-shell-typecheck',
     command: npmCommand,
@@ -1848,11 +1799,6 @@ const steps = [
     command: npmCommand,
     args: ['run', 'ai-game-creator-shell:build', '--', '--no-bundle'],
   },
-  {
-    label: 'desktop-shell-test',
-    command: npmCommand,
-    args: ['run', 'desktop-shell:test'],
-  },
   {
     label: 'desktop-shell-release-build-smoke',
     command: npmCommand,
@@ -2586,7 +2532,6 @@ function assertH5HostBridgePayloadBoundaries() {
     'HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS',
     'HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS',
     'HOST_BRIDGE_SCANNER_TIMEOUT_MS',
-    'HOST_BRIDGE_APP_TITLE_MAX_LENGTH',
   ]) {
     if (!h5HostBridgeSource.includes(`${sharedBoundary},`)) {
       throw new Error(
diff --git a/scripts/check-pingora-current-release-audit.mjs b/scripts/check-pingora-current-release-audit.mjs
index dd87e6220..f03ee6cd6 100644
--- a/scripts/check-pingora-current-release-audit.mjs
+++ b/scripts/check-pingora-current-release-audit.mjs
@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import {
   chmodSync,
   copyFileSync,
   existsSync,
-  symlinkSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
   rmSync,
+  symlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
diff --git a/scripts/check-pingora-cutover-evidence-verify.mjs b/scripts/check-pingora-cutover-evidence-verify.mjs
index 83cc9c7b6..186809bc0 100644
--- a/scripts/check-pingora-cutover-evidence-verify.mjs
+++ b/scripts/check-pingora-cutover-evidence-verify.mjs
@@ -3,7 +3,6 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
-  existsSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
diff --git a/scripts/check-pingora-direct-enable.mjs b/scripts/check-pingora-direct-enable.mjs
index dcfe02110..7216283c4 100644
--- a/scripts/check-pingora-direct-enable.mjs
+++ b/scripts/check-pingora-direct-enable.mjs
@@ -3,8 +3,8 @@
 import { spawnSync } from 'node:child_process';
 import {
   existsSync,
-  mkdtempSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   rmSync,
   symlinkSync,
diff --git a/scripts/check-pingora-direct-live.mjs b/scripts/check-pingora-direct-live.mjs
index 1fb3c48fe..fdd392bc2 100644
--- a/scripts/check-pingora-direct-live.mjs
+++ b/scripts/check-pingora-direct-live.mjs
@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
+import { createHash, randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import http from 'node:http';
 import https from 'node:https';
 import net from 'node:net';
-import tls from 'node:tls';
-import { createHash, randomBytes } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
 import nodePath from 'node:path';
+import tls from 'node:tls';
 
 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_SPACETIME_DATABASE = 'genarrative-prod';
diff --git a/scripts/check-pingora-direct-preflight.mjs b/scripts/check-pingora-direct-preflight.mjs
index 67ddf2747..e06d75644 100644
--- a/scripts/check-pingora-direct-preflight.mjs
+++ b/scripts/check-pingora-direct-preflight.mjs
@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
+import { spawnSync } from 'node:child_process';
 import { accessSync, constants, readFileSync } from 'node:fs';
 import net from 'node:net';
-import { spawnSync } from 'node:child_process';
 import { userInfo } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
diff --git a/scripts/check-pingora-gateway-env-shadow-switch.mjs b/scripts/check-pingora-gateway-env-shadow-switch.mjs
index 57a28ee43..fe28ba89e 100644
--- a/scripts/check-pingora-gateway-env-shadow-switch.mjs
+++ b/scripts/check-pingora-gateway-env-shadow-switch.mjs
@@ -3,7 +3,6 @@
 import { spawnSync } from 'node:child_process';
 import {
   chmodSync,
-  existsSync,
   mkdtempSync,
   readFileSync,
   rmSync,
diff --git a/scripts/check-pingora-health-patrol-env-switch.mjs b/scripts/check-pingora-health-patrol-env-switch.mjs
index 922664aeb..dc6fc0999 100644
--- a/scripts/check-pingora-health-patrol-env-switch.mjs
+++ b/scripts/check-pingora-health-patrol-env-switch.mjs
@@ -7,8 +7,8 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
-  realpathSync,
   readFileSync,
+  realpathSync,
   rmSync,
   statSync,
   symlinkSync,
diff --git a/scripts/check-pingora-realpath-canary-toggle.mjs b/scripts/check-pingora-realpath-canary-toggle.mjs
index 22f0e0c95..59fae8ecf 100644
--- a/scripts/check-pingora-realpath-canary-toggle.mjs
+++ b/scripts/check-pingora-realpath-canary-toggle.mjs
@@ -4,8 +4,8 @@ import { spawnSync } from 'node:child_process';
 import {
   chmodSync,
   existsSync,
-  mkdtempSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   rmSync,
   writeFileSync,
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index d46621969..bf3331dc6 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -13,11 +13,56 @@ const checks = [
     includes: 'npm run check:rustfmt',
     reason: 'API 生产构建必须在编译前执行 Rust 格式检查。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'npm run check:server-rs-ddd',
+    reason: 'API 生产构建必须执行 server-rs DDD/schema/runtime-access 门禁。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml',
+    reason: 'API 生产构建必须执行 api-server 全 target 编译检查。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-stdb-module-build',
     includes: 'npm run check:rustfmt',
     reason: 'Stdb module 生产构建必须在编译前执行 Rust 格式检查。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-stdb-module-build',
+    includes: 'npm run check:server-rs-ddd',
+    reason: 'Stdb module 生产构建必须执行 DDD/schema/runtime-access 门禁。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-stdb-module-build',
+    includes: 'npm run check:admin-account-procedures',
+    reason: 'Stdb module 生产构建必须执行管理员 procedure smoke。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-web-build',
+    includes: 'npm run check:production-ops',
+    reason: 'Web 生产构建必须执行生产运维静态门禁。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-web-build',
+    includes: 'npm run lint:eslint',
+    reason: 'Web 生产构建必须执行 ESLint 门禁。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-web-build',
+    includes: 'npm run typecheck',
+    reason: 'Web 生产构建必须执行主站类型检查。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-web-build',
+    includes: 'npm run admin-web:typecheck',
+    reason: 'Web 生产构建必须执行后台类型检查。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-web-build',
+    includes: 'npm run test',
+    reason: 'Web 生产构建必须执行当前维护范围内的 Vitest。',
+  },
   {
     file: 'server-rs/crates/spacetime-module/src/migration.rs',
     includes:
@@ -514,6 +559,76 @@ const checks = [
     reason:
       '生产冷备份 service 必须用 node -- 分隔脚本参数，避免 Node 22 抢占业务 --env-file。',
   },
+  {
+    file: 'deploy/systemd/genarrative-database-backup.service',
+    excludes: '--storage-format files',
+    reason: '生产数据库备份主 service 必须继续保持 archive full 默认行为。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-history.conf',
+    includes: 'ExecStart=\nExecStart=/usr/bin/node -- /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file',
+    reason: 'files-history drop-in 必须先清空主 service 的 ExecStart，并使用 current release 脚本。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-history.conf',
+    includes: '--storage-format files --mode history --work-dir /var/lib/genarrative/database-backups/files-history',
+    reason: 'files-history drop-in 必须只执行逐文件历史归档，并复用已建立基线的独立 work-dir。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-history.conf',
+    excludes: '--stop-service',
+    reason: 'files-history 在线归档不可停止 SpacetimeDB。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-history.conf',
+    excludes: '--database',
+    reason: 'files-history drop-in 不得写死数据库名，必须从环境文件读取。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-history.conf',
+    excludes: '--bucket',
+    reason: 'files-history drop-in 不得写死 OSS bucket，必须从环境文件读取。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'DATABASE_BACKUP_PROFILE="${DATABASE_BACKUP_PROFILE:-archive-full}"',
+    reason: 'Server-Provision 的数据库备份 profile 必须默认保持 archive-full。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'archive-full|files-history)',
+    reason: 'Server-Provision 必须拒绝未知数据库备份 profile。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: '--storage-format files --mode history --work-dir',
+    reason: 'Server-Provision 启用 files-history 前必须用真实 current release 脚本执行只读 baseline 预检。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'run_cmd rm -f "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"',
+    reason: 'Server-Provision 切回 archive-full 时必须移除托管及现场遗留的 history drop-in。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'install_file "${rendered_drop_in}" "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" 0644',
+    reason: 'Server-Provision 必须从仓库模板安装托管的 files-history drop-in。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-server-provision',
+    includes: "choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-history']",
+    reason: 'Server-Provision Job 必须显式暴露 archive-first 的数据库备份 profile。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-server-provision',
+    includes: "string(name: 'DATABASE_BACKUP_FILES_HISTORY_WORK_DIR', defaultValue: '/var/lib/genarrative/database-backups/files-history'",
+    reason: 'Server-Provision Job 必须允许 dev/release 为 files-history 选择各自的 baseline state 目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-server-provision',
+    excludes: "params.DEPLOY_TARGET == 'release' && databaseBackupProfile == 'files-history'",
+    reason: 'release 必须能在显式选择 profile 且 baseline 预检通过后启用 files-history。',
+  },
   {
     file: 'scripts/database-backup-to-oss.mjs',
     includes: 'assertSufficientWorkDirSpace({dataDir, workDir, args, env})',
@@ -6837,6 +6952,7 @@ const checks = [
 const nodeEnvFileCommandFiles = [
   'package.json',
   'deploy/systemd/genarrative-database-backup.service',
+  'deploy/systemd/genarrative-database-backup-files-history.conf',
   'scripts/deploy/production-stdb-publish.sh',
   'scripts/deploy/pingora-direct-enable.sh',
   'scripts/deploy/pingora-direct-rollback.sh',
diff --git a/scripts/check-server-provision-tools.sh b/scripts/check-server-provision-tools.sh
index 7d4b9caa8..f8805debb 100755
--- a/scripts/check-server-provision-tools.sh
+++ b/scripts/check-server-provision-tools.sh
@@ -37,11 +37,11 @@ chmod +x "${TARGET_BIN_DIR}/otelcol-contrib"
 
 cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" <<'EOF'
 #!/usr/bin/env bash
-echo "spacetimedb-cli 2.6.0"
+echo "spacetimedb-cli 2.6.1"
 EOF
 cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone" <<'EOF'
 #!/usr/bin/env bash
-echo "spacetimedb-standalone 2.6.0"
+echo "spacetimedb-standalone 2.6.1"
 EOF
 chmod +x \
   "${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" \
@@ -58,7 +58,7 @@ if ! (
     OTELCOL_TARGET_BIN="${TARGET_BIN_DIR}/otelcol-contrib" \
     OTELCOL_VERSION="0.151.0" \
     SPACETIME_ROOT="${SPACETIME_ROOT_DIR}" \
-    SPACETIME_EXPECTED_VERSION="2.6.0" \
+    SPACETIME_EXPECTED_VERSION="2.6.1" \
     "${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
     >"${OUTPUT_LOG}" 2>&1
 ); then
diff --git a/scripts/check-server-rs-ddd-boundaries.mjs b/scripts/check-server-rs-ddd-boundaries.mjs
index 54bf0536f..607ccd0e7 100644
--- a/scripts/check-server-rs-ddd-boundaries.mjs
+++ b/scripts/check-server-rs-ddd-boundaries.mjs
@@ -146,8 +146,11 @@ function collectMigrationTables() {
     return new Set();
   }
 
+  const migrationTableBody = macroMatch[1]
+    .replace(/\/\*[\s\S]*?\*\//gu, ' ')
+    .replace(/\/\/[^\r\n]*/gu, ' ');
   return new Set(
-    [...macroMatch[1].matchAll(/\b([a-z][a-z0-9_]*)\b/gu)]
+    [...migrationTableBody.matchAll(/\b([a-z][a-z0-9_]*)\b/gu)]
       .map((match) => match[1])
       .filter((name) => !['arg'].includes(name)),
   );
diff --git a/scripts/check-spacetime-runtime-access.mjs b/scripts/check-spacetime-runtime-access.mjs
index 0931ef21a..271a68337 100644
--- a/scripts/check-spacetime-runtime-access.mjs
+++ b/scripts/check-spacetime-runtime-access.mjs
@@ -108,6 +108,12 @@ const forbiddenSnippets = [
     snippet: '.custom_world_profile()\n        .iter()\n        .filter(|profile| {',
     reason: 'custom_world_profile Published 同步已有 by_custom_world_profile_publication_status 索引',
   },
+  {
+    file: 'server-rs/crates/spacetime-module/src/editor_project_storage.rs',
+    snippet: 'require_editor_generation_runtime_service_identity(ctx, ctx.sender())',
+    reason:
+      'procedure runtime writer 鉴权必须显式传 caller，兼容 TxContext sender 为 Identity::ZERO 的 SpacetimeDB 2.6.0',
+  },
 ];
 
 const procedureResultFiles = [
diff --git a/scripts/check-spacetime-schema-guard.mjs b/scripts/check-spacetime-schema-guard.mjs
index e3042ca2a..c34fbbf38 100644
--- a/scripts/check-spacetime-schema-guard.mjs
+++ b/scripts/check-spacetime-schema-guard.mjs
@@ -481,9 +481,9 @@ function getChangedFiles(baseRef) {
     tryGit(['ls-files', '--others', '--exclude-standard', '-z', bindingsRoot]) ?? '';
   return new Set(
     [
-      ...diffOutput.split(/\u0000/u),
-      ...untrackedModuleOutput.split(/\u0000/u),
-      ...untrackedBindingsOutput.split(/\u0000/u),
+      ...diffOutput.split(String.fromCharCode(0)),
+      ...untrackedModuleOutput.split(String.fromCharCode(0)),
+      ...untrackedBindingsOutput.split(String.fromCharCode(0)),
     ]
       .map(normalizePath)
       .filter(Boolean),
@@ -575,7 +575,7 @@ function compareTables(baseTables, currentTables) {
     }
   }
 
-  for (const [accessor, table] of currentTables) {
+  for (const accessor of currentTables.keys()) {
     if (!baseTables.has(accessor)) {
       schemaChanged = true;
     }
diff --git a/scripts/check-visual-novel-vn11-negative-scan.mjs b/scripts/check-visual-novel-vn11-negative-scan.mjs
index d26f3265a..f482d6af2 100644
--- a/scripts/check-visual-novel-vn11-negative-scan.mjs
+++ b/scripts/check-visual-novel-vn11-negative-scan.mjs
@@ -180,10 +180,6 @@ function hasExternalPlatformMarker(line) {
   return externalPlatformPatterns.some((pattern) => pattern.test(line));
 }
 
-function formatHits(hits) {
-  return hits.map((hit) => `  - ${hit.file}:${hit.lineNumber} ${hit.text}`);
-}
-
 const documentFiles = collectFiles(documentTargets);
 const visualNovelFiles = collectFiles(visualNovelImplementationTargets);
 
diff --git a/scripts/container-worker-smoke.mjs b/scripts/container-worker-smoke.mjs
index c7c2c9e5c..689e928fa 100644
--- a/scripts/container-worker-smoke.mjs
+++ b/scripts/container-worker-smoke.mjs
@@ -761,7 +761,7 @@ function composeEnv() {
 }
 
 function localSpacetimeImageName() {
-  return `${projectName}-spacetimedb:2.6.0`;
+  return `${projectName}-spacetimedb:2.6.1`;
 }
 
 function spacetimeServerUrl(state) {
diff --git a/scripts/database-backup-to-oss.mjs b/scripts/database-backup-to-oss.mjs
index d38a28598..80fb5392c 100644
--- a/scripts/database-backup-to-oss.mjs
+++ b/scripts/database-backup-to-oss.mjs
@@ -1,8 +1,29 @@
 #!/usr/bin/env node
 import {spawnSync} from 'node:child_process';
 import {createHash, createHmac} from 'node:crypto';
-import {createReadStream, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, statfsSync, writeFileSync} from 'node:fs';
-import {basename, dirname, isAbsolute, resolve} from 'node:path';
+import {
+  chmodSync,
+  closeSync,
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statfsSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import {basename, dirname, isAbsolute, join, relative, resolve, sep} from 'node:path';
+import {Readable} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
 import {setTimeout as sleep} from 'node:timers/promises';
 import {fileURLToPath} from 'node:url';
 
@@ -26,16 +47,30 @@ const OSS_MAX_MULTIPART_PARTS = 10_000;
 const DEFAULT_OSS_REQUEST_MAX_ATTEMPTS = 5;
 const DEFAULT_OSS_RETRY_BASE_DELAY_MS = 1_000;
 const DEFAULT_OSS_RETRY_MAX_DELAY_MS = 30_000;
+const DEFAULT_DIRECT_FILES_CONCURRENCY = 16;
+const MAX_DIRECT_FILES_CONCURRENCY = 64;
+const DIRECT_FILES_SINGLE_PUT_MAX_BYTES = 16 * 1024 * 1024;
 const RETRYABLE_OSS_HTTP_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const HISTORY_STATE_SCHEMA_VERSION = 1;
+const HISTORY_MANIFEST_SCHEMA_VERSION = 1;
+const DIRECT_FILES_STATE_SCHEMA_VERSION = 1;
+const DIRECT_FILES_CATALOG_SCHEMA_VERSION = 1;
+const DIRECT_FILES_LATEST_SCHEMA_VERSION = 1;
 
 function usage() {
   console.log(`用法:
-  npm run database:backup:oss -- [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
+  npm run database:backup:oss -- [--mode full|history] [--storage-format archive|files] [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
   node -- scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
   node -- scripts/database-backup-to-oss.mjs --upload-archive <path>
+  node -- scripts/database-backup-to-oss.mjs --publish-manifest <path>
+  node -- scripts/database-backup-to-oss.mjs --restore-files-state <path> --restore-dir <path>
+  node -- scripts/database-backup-to-oss.mjs --restore-files-latest --restore-dir <path> [--dry-run]
 
 说明:
-  将 SpacetimeDB 数据目录打包成 .tar.gz，并上传到阿里云 OSS 指定 bucket。
+  将 SpacetimeDB 数据目录以 .tar.gz 或逐文件 catalog 形式上传到阿里云 OSS 指定 bucket。
+  默认 full 模式保持原有全量冷备行为；history 模式只归档已被最新 snapshot 覆盖的历史 commitlog 与旧 snapshot。
+  --storage-format files 不打包：按原相对路径建立 catalog，文件内容以 SHA-256 不可变对象上传；重复运行只上传新增或变化内容。
+  archive history 必须有已验真的 full baseline state；files history 必须复用同一 work-dir 中已发布的 full catalog state。
   --defer-upload 只生成本地冷备份和 manifest，不上传；后续用 --upload-archive 异步上传。
   默认读取 .env / .env.local / .env.secrets.local；生产服务可传 --env-file /etc/genarrative/api-server.env。
   shell 环境变量优先级最高，不会被 env 文件覆盖。
@@ -46,8 +81,11 @@ function usage() {
   GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET      备份 bucket；未设置时回退 ALIYUN_OSS_BUCKET
   GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX      对象前缀，默认 database-backups
   GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT    OSS endpoint；未设置时回退 ALIYUN_OSS_ENDPOINT
+  GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT  archive（默认）或 files
   GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL      true 时保留本地 tar.gz
   GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES  备份前要求 work dir 所在文件系统至少有这些可用字节；未设置时按数据目录大小估算
+  GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE  history 使用的 full baseline 与追加批次状态文件
+  GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST 首次初始化 history state 的 uploaded full manifest
   ALIYUN_OSS_ACCESS_KEY_ID / ALIYUN_OSS_ACCESS_KEY_SECRET
 `);
 }
@@ -121,6 +159,14 @@ function parseArgs(argv) {
     objectKey: '',
     resultFile: '',
     minFreeBytes: '',
+    mode: 'full',
+    baselineState: '',
+    baselineManifest: '',
+    publishManifest: '',
+    storageFormat: '',
+    restoreFilesState: '',
+    restoreFilesLatest: false,
+    restoreDir: '',
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -198,6 +244,30 @@ function parseArgs(argv) {
       case '--min-free-bytes':
         options.minFreeBytes = readValue();
         break;
+      case '--mode':
+        options.mode = readValue();
+        break;
+      case '--baseline-state':
+        options.baselineState = readValue();
+        break;
+      case '--baseline-manifest':
+        options.baselineManifest = readValue();
+        break;
+      case '--publish-manifest':
+        options.publishManifest = readValue();
+        break;
+      case '--storage-format':
+        options.storageFormat = readValue();
+        break;
+      case '--restore-files-state':
+        options.restoreFilesState = readValue();
+        break;
+      case '--restore-files-latest':
+        options.restoreFilesLatest = true;
+        break;
+      case '--restore-dir':
+        options.restoreDir = readValue();
+        break;
       default:
         throw new Error(`未知参数: ${arg}`);
     }
@@ -210,6 +280,55 @@ function firstNonEmpty(...values) {
   return values.map((value) => String(value ?? '').trim()).find(Boolean) ?? '';
 }
 
+function parseDirectFilesConcurrency(rawValue) {
+  const value = Number(String(rawValue ?? DEFAULT_DIRECT_FILES_CONCURRENCY).trim());
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_DIRECT_FILES_CONCURRENCY) {
+    throw new Error(`GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY 必须是 1-${MAX_DIRECT_FILES_CONCURRENCY} 的整数，实际: ${rawValue}`);
+  }
+  return value;
+}
+
+export function createUploadBandwidthLimiter(rawValue, {nowFn = Date.now, sleepImpl = sleep} = {}) {
+  const normalized = String(rawValue ?? '').trim();
+  if (!normalized || normalized === '0') {
+    return null;
+  }
+  const maxBytesPerSecond = Number(normalized);
+  if (!Number.isSafeInteger(maxBytesPerSecond) || maxBytesPerSecond < 1024) {
+    throw new Error(`GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND 必须为空、0 或 >= 1024 的整数，实际: ${rawValue}`);
+  }
+  let nextAvailableAtMs = 0;
+  const waitForChunk = async (sizeBytes) => {
+    const now = nowFn();
+    const startAt = Math.max(now, nextAvailableAtMs);
+    const finishAt = startAt + (sizeBytes / maxBytesPerSecond) * 1000;
+    nextAvailableAtMs = finishAt;
+    const delayMs = Math.max(0, finishAt - now);
+    if (delayMs > 0) {
+      await sleepImpl(delayMs);
+    }
+  };
+  return {
+    maxBytesPerSecond,
+    wrap(readable) {
+      return Readable.from((async function* throttleUpload() {
+        for await (const chunk of readable) {
+          await waitForChunk(chunk.length);
+          yield chunk;
+        }
+      })(), {objectMode: false});
+    },
+  };
+}
+
+function createBufferReadStream(buffer, chunkSizeBytes = 64 * 1024) {
+  return Readable.from((function* readChunks() {
+    for (let offset = 0; offset < buffer.length; offset += chunkSizeBytes) {
+      yield buffer.subarray(offset, Math.min(offset + chunkSizeBytes, buffer.length));
+    }
+  })(), {objectMode: false});
+}
+
 function resolvePath(value) {
   return isAbsolute(value) ? value : resolve(REPO_ROOT, value);
 }
@@ -251,6 +370,356 @@ function buildBackupNames({database, dataDir, objectPrefix}) {
   return {fileName, objectKey};
 }
 
+function atomicWriteJson(filePath, payload) {
+  mkdirSync(dirname(filePath), {recursive: true});
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {encoding: 'utf8', mode: 0o600});
+  chmodSync(tempPath, 0o600);
+  renameSync(tempPath, filePath);
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function acquireBackupLock({workDir, database}) {
+  mkdirSync(workDir, {recursive: true});
+  const lockPath = join(workDir, `${sanitizeObjectPart(database, 'spacetimedb')}.backup.lock`);
+  try {
+    const fd = openSync(lockPath, 'wx', 0o600);
+    writeFileSync(fd, `${process.pid}\n`, 'utf8');
+    closeSync(fd);
+    const release = () => {
+      try {
+        const ownerPid = Number(String(readFileSync(lockPath, 'utf8')).trim());
+        if (ownerPid === process.pid) {
+          rmSync(lockPath, {force: true});
+        }
+      } catch {
+        // The lock may already have been removed by the normal exit path.
+      }
+    };
+    process.once('exit', release);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.once(signal, () => {
+        release();
+        process.exit(signal === 'SIGINT' ? 130 : 143);
+      });
+    }
+    return lockPath;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+  const ownerPid = Number(String(readFileSync(lockPath, 'utf8')).trim());
+  if (Number.isSafeInteger(ownerPid) && ownerPid > 0 && processIsAlive(ownerPid)) {
+    throw new Error(`已有数据库备份进程持有锁: ${lockPath} pid=${ownerPid}`);
+  }
+  throw new Error(`发现失效数据库备份锁，拒绝自动抢锁；请核对 OSS multipart 与进程后手工删除: ${lockPath} pid=${ownerPid || '<invalid>'}`);
+}
+
+function historyStatePath({args, env, workDir, database}) {
+  return resolvePath(firstNonEmpty(
+    args.baselineState,
+    env.GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE,
+    join(workDir, `${sanitizeObjectPart(database, 'spacetimedb')}-history-state.json`),
+  ));
+}
+
+function baselineIdFor(baseline) {
+  return sha256Hex([
+    baseline.bucket,
+    baseline.objectKey,
+    baseline.verifiedAt,
+    baseline.contentLength,
+    baseline.archiveSha256,
+  ].join('\0')).slice(0, 24);
+}
+
+function normalizeUploadedBaselineManifest(manifest, {database, dataDir}) {
+  if (manifest.uploadStatus !== 'uploaded') {
+    throw new Error(`baseline manifest 必须是 uploaded，实际: ${manifest.uploadStatus ?? '<missing>'}`);
+  }
+  if (manifest.backupKind !== 'spacetimedb-data-dir') {
+    throw new Error(`baseline manifest backupKind 必须是 spacetimedb-data-dir，实际: ${manifest.backupKind ?? '<missing>'}`);
+  }
+  const baseline = {
+    backupKind: 'spacetimedb-data-dir',
+    database: firstNonEmpty(manifest.database, database),
+    dataDir: resolvePath(firstNonEmpty(manifest.dataDir, dataDir)),
+    bucket: String(manifest.bucket ?? '').trim(),
+    objectKey: String(manifest.objectKey ?? '').trim(),
+    verifiedAt: String(manifest.verifiedAt ?? '').trim(),
+    uploadedAt: String(manifest.uploadedAt ?? '').trim(),
+    contentLength: Number(manifest.contentLength),
+    archiveSha256: String(manifest.archiveSha256 ?? '').trim().toLowerCase(),
+    manifestObjectKey: String(manifest.manifestObjectKey ?? '').trim(),
+    manifestContentLength: Number(manifest.manifestContentLength),
+    manifestArchiveSha256: String(manifest.manifestArchiveSha256 ?? '').trim().toLowerCase(),
+    manifestVerifiedAt: String(manifest.manifestVerifiedAt ?? '').trim(),
+  };
+  if (
+    !baseline.bucket
+    || !baseline.objectKey
+    || !baseline.verifiedAt
+    || !Number.isSafeInteger(baseline.contentLength)
+    || baseline.contentLength <= 0
+    || !/^[a-f0-9]{64}$/u.test(baseline.archiveSha256)
+    || !baseline.manifestObjectKey
+    || !Number.isSafeInteger(baseline.manifestContentLength)
+    || baseline.manifestContentLength <= 0
+    || !/^[a-f0-9]{64}$/u.test(baseline.manifestArchiveSha256)
+    || !baseline.manifestVerifiedAt
+  ) {
+    throw new Error('baseline manifest 缺少已验真 OSS 归档或 sidecar 信息。');
+  }
+  baseline.id = baselineIdFor(baseline);
+  return baseline;
+}
+
+function validateHistoryState(state, {database, dataDir}) {
+  if (state.schemaVersion !== HISTORY_STATE_SCHEMA_VERSION || !state.baseline) {
+    throw new Error('history state schemaVersion 或 baseline 无效。');
+  }
+  const baseline = normalizeUploadedBaselineManifest(
+    {...state.baseline, uploadStatus: 'uploaded'},
+    {database, dataDir},
+  );
+  if (baseline.database !== database) {
+    throw new Error(`history state database 不匹配: expected=${database}, actual=${baseline.database}`);
+  }
+  if (resolvePath(baseline.dataDir) !== resolvePath(dataDir)) {
+    throw new Error(`history state dataDir 不匹配: expected=${resolvePath(dataDir)}, actual=${resolvePath(baseline.dataDir)}`);
+  }
+  return {
+    ...state,
+    baseline,
+    batches: Array.isArray(state.batches) ? state.batches : [],
+  };
+}
+
+function writeBaselineState({statePath, baseline, previousState = null}) {
+  const state = {
+    schemaVersion: HISTORY_STATE_SCHEMA_VERSION,
+    updatedAt: new Date().toISOString(),
+    baseline,
+    batches: previousState?.baseline?.id === baseline.id && Array.isArray(previousState.batches)
+      ? previousState.batches
+      : [],
+  };
+  atomicWriteJson(statePath, state);
+  return state;
+}
+
+function loadOrImportHistoryState({args, env, statePath, database, dataDir}) {
+  if (existsSync(statePath)) {
+    return validateHistoryState(readManifest(statePath), {database, dataDir});
+  }
+  const importPath = firstNonEmpty(args.baselineManifest, env.GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST);
+  if (!importPath) {
+    throw new Error(`history 模式缺少已验真 baseline state: ${statePath}；可用 --baseline-manifest 导入已有 uploaded baseline manifest。`);
+  }
+  const baseline = normalizeUploadedBaselineManifest(readManifest(resolvePath(importPath)), {database, dataDir});
+  return writeBaselineState({statePath, baseline});
+}
+
+function assertSafeRelativePath(dataDir, absolutePath) {
+  const relativePath = relative(resolvePath(dataDir), resolvePath(absolutePath));
+  if (!relativePath || relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+    throw new Error(`history 候选路径越界或等于数据目录: ${absolutePath}`);
+  }
+  return relativePath.split(sep).join('/');
+}
+
+function statFingerprint(absolutePath, rootPath = absolutePath) {
+  const entries = [];
+  let totalSize = 0n;
+  const visit = (currentPath) => {
+    const stat = lstatSync(currentPath, {bigint: true});
+    if (stat.isSymbolicLink()) {
+      throw new Error(`history 候选不得包含符号链接: ${currentPath}`);
+    }
+    const entryPath = currentPath === rootPath ? '.' : relative(rootPath, currentPath).split(sep).join('/');
+    const kind = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
+    if (kind === 'other') {
+      throw new Error(`history 候选只允许普通文件或目录: ${currentPath}`);
+    }
+    entries.push([
+      entryPath,
+      kind,
+      stat.dev.toString(),
+      stat.ino.toString(),
+      stat.mode.toString(),
+      stat.size.toString(),
+      stat.mtimeNs.toString(),
+    ].join('\0'));
+    if (stat.isFile()) {
+      totalSize += stat.size;
+    } else {
+      for (const name of readdirSync(currentPath).sort()) {
+        visit(join(currentPath, name));
+      }
+    }
+  };
+  visit(rootPath);
+  return {
+    fingerprint: sha256Hex(entries.join('\n')),
+    sizeBytes: totalSize.toString(),
+    entryCount: entries.length,
+  };
+}
+
+function findReplicasDir(dataDir) {
+  const candidates = [resolve(dataDir, 'replicas'), resolve(dataDir, 'data', 'replicas')]
+    .filter((candidate) => existsSync(candidate) && lstatSync(candidate).isDirectory());
+  if (candidates.length !== 1) {
+    throw new Error(`无法唯一确定 replicas 目录: ${candidates.length === 0 ? '<none>' : candidates.join(', ')}`);
+  }
+  return candidates[0];
+}
+
+function historyCandidate({dataDir, absolutePath, kind, replicaId, transaction}) {
+  const stat = statFingerprint(absolutePath);
+  return {
+    path: assertSafeRelativePath(dataDir, absolutePath),
+    kind,
+    replicaId,
+    transaction: transaction.toString(),
+    ...stat,
+  };
+}
+
+export function discoverHistoryPlan({dataDir}) {
+  const resolvedDataDir = resolvePath(dataDir);
+  const replicasDir = findReplicasDir(resolvedDataDir);
+  const replicaEntries = readdirSync(replicasDir, {withFileTypes: true});
+  const replicas = [];
+  const candidates = [];
+
+  for (const replicaEntry of replicaEntries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!replicaEntry.isDirectory()) {
+      continue;
+    }
+    if (!/^\d+$/u.test(replicaEntry.name)) {
+      throw new Error(`replica 目录名不符合预期: ${replicaEntry.name}`);
+    }
+    const replicaId = replicaEntry.name;
+    const replicaDir = join(replicasDir, replicaId);
+    const snapshotsDir = join(replicaDir, 'snapshots');
+    const clogDir = join(replicaDir, 'clog');
+    if (!existsSync(snapshotsDir) || !lstatSync(snapshotsDir).isDirectory()) {
+      replicas.push({replicaId, status: 'skipped', reason: 'no-snapshots-directory'});
+      continue;
+    }
+    const snapshotEntries = readdirSync(snapshotsDir, {withFileTypes: true});
+    const snapshots = snapshotEntries.flatMap((entry) => {
+      const match = /^(\d{20})\.snapshot_dir$/u.exec(entry.name);
+      if (!match) {
+        return [];
+      }
+      const transaction = BigInt(match[1]);
+      if (transaction > 0xffff_ffff_ffff_ffffn) {
+        throw new Error(`snapshot transaction 超出 u64: ${entry.name}`);
+      }
+      if (!entry.isDirectory()) {
+        throw new Error(`snapshot 候选必须是目录: ${join(snapshotsDir, entry.name)}`);
+      }
+      const snapshotDir = join(snapshotsDir, entry.name);
+      const lockPath = join(snapshotsDir, `${match[1]}.lock`);
+      const snapshotFile = join(snapshotDir, `${match[1]}.snapshot_bsatn`);
+      if (existsSync(lockPath) || !existsSync(snapshotFile) || !lstatSync(snapshotFile).isFile()) {
+        return [];
+      }
+      return [{name: entry.name, transaction}];
+    }).sort((left, right) => left.transaction < right.transaction ? -1 : left.transaction > right.transaction ? 1 : 0);
+    if (snapshots.length === 0) {
+      replicas.push({replicaId, status: 'skipped', reason: 'no-snapshot'});
+      continue;
+    }
+    if (!existsSync(clogDir) || !lstatSync(clogDir).isDirectory()) {
+      throw new Error(`replica ${replicaId} 缺少 clog 目录。`);
+    }
+    const segmentFiles = new Map();
+    for (const entry of readdirSync(clogDir, {withFileTypes: true})) {
+      const match = /^(\d{20})\.stdb\.(log|ofs)$/u.exec(entry.name);
+      if (!match) {
+        throw new Error(`commitlog 文件名不符合预期: ${entry.name}`);
+      }
+      if (!entry.isFile()) {
+        throw new Error(`commitlog 候选必须是普通文件: ${join(clogDir, entry.name)}`);
+      }
+      const transaction = BigInt(match[1]);
+      if (transaction > 0xffff_ffff_ffff_ffffn) {
+        throw new Error(`commitlog transaction 超出 u64: ${entry.name}`);
+      }
+      const key = transaction.toString();
+      const group = segmentFiles.get(key) ?? {transaction};
+      group[match[2]] = entry.name;
+      segmentFiles.set(key, group);
+    }
+    for (const group of segmentFiles.values()) {
+      if (group.ofs && !group.log) {
+        throw new Error(`commitlog offset 缺少对应 log: replica=${replicaId}, transaction=${group.transaction}`);
+      }
+    }
+    const segments = [...segmentFiles.values()]
+      .filter((group) => group.log)
+      .sort((left, right) => left.transaction < right.transaction ? -1 : left.transaction > right.transaction ? 1 : 0);
+    const latestSnapshot = snapshots.at(-1).transaction;
+    const boundarySegment = segments.filter((segment) => segment.transaction <= latestSnapshot).at(-1);
+    if (!boundarySegment) {
+      throw new Error(`replica ${replicaId} 无法找到覆盖 latest snapshot ${latestSnapshot} 的 commitlog 边界。`);
+    }
+    for (const snapshot of snapshots.slice(0, -1)) {
+      candidates.push(historyCandidate({
+        dataDir: resolvedDataDir,
+        absolutePath: join(snapshotsDir, snapshot.name),
+        kind: 'snapshot',
+        replicaId,
+        transaction: snapshot.transaction,
+      }));
+    }
+    for (const segment of segments.filter((item) => item.transaction < boundarySegment.transaction)) {
+      candidates.push(historyCandidate({
+        dataDir: resolvedDataDir,
+        absolutePath: join(clogDir, segment.log),
+        kind: 'commitlog',
+        replicaId,
+        transaction: segment.transaction,
+      }));
+      if (segment.ofs) {
+        candidates.push(historyCandidate({
+          dataDir: resolvedDataDir,
+          absolutePath: join(clogDir, segment.ofs),
+          kind: 'commitlog-offset',
+          replicaId,
+          transaction: segment.transaction,
+        }));
+      }
+    }
+    replicas.push({
+      replicaId,
+      status: 'ready',
+      latestSnapshot: latestSnapshot.toString(),
+      boundarySegment: boundarySegment.transaction.toString(),
+    });
+  }
+  candidates.sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    dataDir: resolvedDataDir,
+    replicasDir: assertSafeRelativePath(resolvedDataDir, replicasDir),
+    replicas,
+    candidates,
+    totalSizeBytes: candidates.reduce((sum, item) => sum + BigInt(item.sizeBytes), 0n).toString(),
+  };
+}
+
 function runCommand(command, args, options = {}) {
   const result = spawnSync(command, args, {
     cwd: options.cwd ?? REPO_ROOT,
@@ -371,6 +840,18 @@ function assertSufficientWorkDirSpace({dataDir, workDir, args, env}) {
   }
 }
 
+function assertSufficientHistoryWorkDirSpace({historySizeBytes, workDir, args, env}) {
+  mkdirSync(workDir, {recursive: true});
+  const availableBytes = getAvailableBytes(workDir);
+  const requiredFreeBytes = calculateRequiredFreeBytes({dataSizeBytes: BigInt(historySizeBytes), args, env});
+  console.log(
+    `[database-backup] history 空间预检: candidates=${formatBytes(historySizeBytes)}, available=${formatBytes(availableBytes)}, required=${formatBytes(requiredFreeBytes)}`,
+  );
+  if (availableBytes < requiredFreeBytes) {
+    throw new Error(`history 工作目录剩余空间不足: available=${formatBytes(availableBytes)}；required=${formatBytes(requiredFreeBytes)}`);
+  }
+}
+
 function collectRestartServicesAfterBackup({args, env}) {
   const serviceNames = [
     ...String(env.GENARRATIVE_DATABASE_BACKUP_RESTART_SERVICE_AFTER ?? '')
@@ -448,9 +929,119 @@ function createArchive({dataDir, workDir, fileName}) {
   const entryName = basename(dataDir);
   console.log(`[database-backup] 打包: ${dataDir} -> ${archivePath}`);
   runCommand('tar', ['-czf', archivePath, '-C', parentDir, entryName], {stdio: 'inherit'});
+  verifyArchive(archivePath);
   return archivePath;
 }
 
+function verifyArchive(archivePath) {
+  console.log(`[database-backup] 校验归档: ${archivePath}`);
+  runCommand('tar', ['-tzf', archivePath], {stdio: 'ignore'});
+}
+
+function historyBatchId({baselineId, plan}) {
+  const identity = plan.candidates.map((candidate) => [
+    candidate.path,
+    candidate.kind,
+    candidate.transaction,
+    candidate.fingerprint,
+  ].join('\0')).join('\n');
+  return sha256Hex(`${baselineId}\0${identity}`).slice(0, 32);
+}
+
+function buildHistoryNames({database, objectPrefix, baselineId, batchId}) {
+  const databasePart = sanitizeObjectPart(database, 'spacetimedb');
+  const prefix = String(objectPrefix || 'database-backups')
+    .trim()
+    .replace(/^\/+|\/+$/gu, '')
+    .split('/')
+    .filter(Boolean)
+    .map((part) => sanitizeObjectPart(part, 'backup'))
+    .join('/');
+  const fileName = `${databasePart}-history-${batchId}.tar.gz`;
+  return {
+    fileName,
+    objectKey: [prefix, databasePart, 'history', baselineId, fileName].filter(Boolean).join('/'),
+  };
+}
+
+function createHistoryArchive({dataDir, workDir, fileName, manifestPath, candidates}) {
+  mkdirSync(workDir, {recursive: true});
+  const archivePath = resolve(workDir, fileName);
+  const candidatePaths = candidates.map((candidate) => candidate.path);
+  console.log(`[database-backup] 打包 history: ${candidatePaths.length} 个候选 -> ${archivePath}`);
+  runCommand('tar', [
+    '-czf',
+    archivePath,
+    '-C',
+    dataDir,
+    ...candidatePaths,
+    '-C',
+    dirname(manifestPath),
+    basename(manifestPath),
+  ], {stdio: 'inherit'});
+  verifyArchive(archivePath);
+  return archivePath;
+}
+
+function recordHistoryBatch({statePath, state, manifest, uploadResult, manifestUpload, status, cleanedAt = ''}) {
+  const batch = {
+    batchId: manifest.batchId,
+    objectKey: uploadResult.objectKey,
+    contentLength: uploadResult.contentLength,
+    archiveSha256: uploadResult.archiveSha256,
+    verifiedAt: uploadResult.verifiedAt,
+    manifestObjectKey: manifestUpload.objectKey,
+    manifestContentLength: manifestUpload.contentLength,
+    manifestArchiveSha256: manifestUpload.archiveSha256,
+    manifestVerifiedAt: manifestUpload.verifiedAt,
+    uploadedAt: manifest.uploadedAt,
+    status,
+    cleanedAt,
+    candidates: manifest.candidates,
+  };
+  const batches = state.batches.filter((item) => item.batchId !== batch.batchId);
+  batches.push(batch);
+  const nextState = {...state, updatedAt: new Date().toISOString(), batches};
+  atomicWriteJson(statePath, nextState);
+  return nextState;
+}
+
+function candidateKey(candidate) {
+  return `${candidate.kind}\0${candidate.path}`;
+}
+
+export function cleanupHistoryCandidates({dataDir, candidates}) {
+  const currentPlan = discoverHistoryPlan({dataDir});
+  const eligible = new Map(currentPlan.candidates.map((candidate) => [candidateKey(candidate), candidate]));
+  const existing = [];
+  for (const candidate of candidates) {
+    const absolutePath = resolve(dataDir, candidate.path);
+    assertSafeRelativePath(dataDir, absolutePath);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    const current = eligible.get(candidateKey(candidate));
+    if (!current) {
+      throw new Error(`history 候选已不在当前安全边界内，拒绝删除: ${candidate.path}`);
+    }
+    const currentStat = statFingerprint(absolutePath);
+    if (currentStat.fingerprint !== candidate.fingerprint || currentStat.sizeBytes !== candidate.sizeBytes) {
+      throw new Error(`history 候选 stat 漂移，拒绝删除: ${candidate.path}`);
+    }
+    existing.push({candidate, absolutePath});
+  }
+  existing.sort((left, right) => {
+    const priority = {'commitlog-offset': 0, commitlog: 1, snapshot: 2};
+    return (priority[left.candidate.kind] ?? 3) - (priority[right.candidate.kind] ?? 3)
+      || left.candidate.path.localeCompare(right.candidate.path);
+  });
+  for (const {candidate, absolutePath} of existing) {
+    rmSync(absolutePath, {recursive: candidate.kind === 'snapshot', force: false});
+    console.log(`[database-backup] 已清理 history 源文件: ${candidate.path}`);
+  }
+  return {deletedCount: existing.length, alreadyMissingCount: candidates.length - existing.length};
+}
+
 function writeManifest({manifestPath, payload}) {
   writeFileSync(manifestPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
 }
@@ -470,6 +1061,776 @@ function sha256Hex(content) {
   return createHash('sha256').update(content).digest('hex');
 }
 
+async function sha256FileHex(filePath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(filePath)) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+function directFilesStatePath({workDir, database}) {
+  return join(workDir, `${sanitizeObjectPart(database, 'spacetimedb')}-files-state.json`);
+}
+
+function normalizeObjectPrefix(objectPrefix, database) {
+  const prefix = String(objectPrefix || 'database-backups')
+    .trim()
+    .replace(/^\/+|\/+$/gu, '')
+    .split('/')
+    .filter(Boolean)
+    .map((part) => sanitizeObjectPart(part, 'backup'))
+    .join('/');
+  return [prefix, sanitizeObjectPart(database, 'spacetimedb')].filter(Boolean).join('/');
+}
+
+function directFileIdentity(filePath) {
+  const stat = lstatSync(filePath, {bigint: true});
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(`files 模式只允许普通文件: ${filePath}`);
+  }
+  return {
+    dev: stat.dev.toString(),
+    ino: stat.ino.toString(),
+    size: stat.size.toString(),
+    mtimeNs: stat.mtimeNs.toString(),
+    mode: Number(stat.mode & 0o7777n),
+  };
+}
+
+function sameDirectFileIdentity(left, right) {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.mode === right.mode;
+}
+
+export async function collectDirectFileEntries({dataDir, candidates = null, objectPrefix, database}) {
+  const resolvedDataDir = resolvePath(dataDir);
+  if (!existsSync(resolvedDataDir) || !lstatSync(resolvedDataDir).isDirectory()) {
+    throw new Error(`files 数据目录不存在或不是目录: ${resolvedDataDir}`);
+  }
+  const files = new Map();
+  const symlinks = new Map();
+  const directories = new Set(['.']);
+  const roots = candidates === null
+    ? [{absolutePath: resolvedDataDir, relativePath: '.'}]
+    : candidates.map((candidate) => ({
+      absolutePath: resolve(resolvedDataDir, candidate.path),
+      relativePath: assertSafeRelativePath(resolvedDataDir, resolve(resolvedDataDir, candidate.path)),
+    }));
+
+  const visit = async (absolutePath, relativePath) => {
+    const stat = lstatSync(absolutePath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(absolutePath, 'utf8');
+      if (!target || isAbsolute(target)) {
+        throw new Error(`files 模式只允许 data-dir 内部的相对符号链接: ${absolutePath} -> ${target}`);
+      }
+      assertSafeRelativePath(resolvedDataDir, resolve(dirname(absolutePath), target));
+      symlinks.set(relativePath, {path: relativePath, target});
+      return;
+    }
+    if (stat.isDirectory()) {
+      directories.add(relativePath);
+      for (const name of readdirSync(absolutePath).sort()) {
+        const childRelative = relativePath === '.' ? name : `${relativePath}/${name}`;
+        await visit(join(absolutePath, name), childRelative);
+      }
+      return;
+    }
+    if (!stat.isFile()) {
+      throw new Error(`files 模式只允许普通文件或目录: ${absolutePath}`);
+    }
+    const before = directFileIdentity(absolutePath);
+    const sha256 = await sha256FileHex(absolutePath);
+    const after = directFileIdentity(absolutePath);
+    if (!sameDirectFileIdentity(before, after)) {
+      throw new Error(`files 扫描期间源文件发生变化: ${relativePath}`);
+    }
+    const basePrefix = normalizeObjectPrefix(objectPrefix, database);
+    files.set(relativePath, {
+      path: relativePath,
+      sizeBytes: Number(after.size),
+      sha256,
+      mode: after.mode,
+      objectKey: `${basePrefix}/files/sha256/${sha256.slice(0, 2)}/${sha256}`,
+      sourceStat: after,
+    });
+  };
+
+  for (const root of roots.sort((left, right) => left.relativePath.localeCompare(right.relativePath))) {
+    if (!existsSync(root.absolutePath)) {
+      throw new Error(`files 候选在扫描前消失: ${root.relativePath}`);
+    }
+    await visit(root.absolutePath, root.relativePath);
+  }
+  return {
+    directories: [...directories].sort(),
+    files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
+    symlinks: [...symlinks.values()].sort((left, right) => left.path.localeCompare(right.path)),
+  };
+}
+
+function directCatalogIdentity({mode, baselineCatalogId, rootName, directories, files, symlinks}) {
+  return sha256Hex(JSON.stringify({
+    mode,
+    baselineCatalogId: baselineCatalogId || '',
+    rootName,
+    directories,
+    files: files.map(({path, sizeBytes, sha256, mode, objectKey}) => ({path, sizeBytes, sha256, mode, objectKey})),
+    symlinks,
+  }));
+}
+
+function readDirectFilesState(statePath, {database, bucket}) {
+  if (!existsSync(statePath)) {
+    return null;
+  }
+  const state = readManifest(statePath);
+  if (
+    state.schemaVersion !== DIRECT_FILES_STATE_SCHEMA_VERSION
+    || state.backupKind !== 'spacetimedb-direct-files-state'
+    || state.database !== database
+    || state.bucket !== bucket
+  ) {
+    throw new Error(`files state 与本次数据源或 bucket 不匹配: ${statePath}`);
+  }
+  return state;
+}
+
+async function ensureDirectObject({
+  file,
+  dataDir,
+  uploadOptions,
+  previousFile,
+  verifyCatalogReuse = false,
+  uploadFn,
+  verifyFn,
+}) {
+  const absolutePath = resolve(dataDir, file.path);
+  assertSafeRelativePath(dataDir, absolutePath);
+  if (previousFile?.sha256 === file.sha256
+    && previousFile?.sizeBytes === file.sizeBytes
+    && previousFile?.objectKey === file.objectKey) {
+    if (verifyCatalogReuse) {
+      await verifyFn({
+        ...uploadOptions,
+        objectKey: file.objectKey,
+        contentLength: file.sizeBytes,
+        archiveSha256: file.sha256,
+      });
+    }
+    return {
+      status: verifyCatalogReuse ? 'catalog-reused-verified' : 'catalog-reused',
+      objectKey: file.objectKey,
+    };
+  }
+  try {
+    await verifyFn({
+      ...uploadOptions,
+      objectKey: file.objectKey,
+      contentLength: file.sizeBytes,
+      archiveSha256: file.sha256,
+    });
+    return {status: 'oss-reused', objectKey: file.objectKey};
+  } catch (error) {
+    if (error?.status !== 404) {
+      throw error;
+    }
+  }
+  const beforeUpload = directFileIdentity(absolutePath);
+  if (!sameDirectFileIdentity(beforeUpload, file.sourceStat)) {
+    throw new Error(`files 上传前源文件 stat 漂移: ${file.path}`);
+  }
+  await uploadFn({
+    archivePath: absolutePath,
+    ...uploadOptions,
+    objectKey: file.objectKey,
+    archiveSha256: file.sha256,
+    backupKind: 'spacetimedb-direct-file',
+    contentType: 'application/octet-stream',
+    allowEmpty: true,
+  });
+  const afterUpload = directFileIdentity(absolutePath);
+  if (!sameDirectFileIdentity(afterUpload, file.sourceStat)) {
+    throw new Error(`files 上传期间源文件 stat 漂移: ${file.path}`);
+  }
+  return {status: 'uploaded', objectKey: file.objectKey};
+}
+
+async function ensureDirectManifest({manifestPath, objectKey, uploadOptions, uploadManifestFn, verifyFn}) {
+  const body = readFileSync(manifestPath);
+  const archiveSha256 = sha256Hex(body);
+  try {
+    const verification = await verifyFn({
+      ...uploadOptions,
+      objectKey,
+      contentLength: body.length,
+      archiveSha256,
+    });
+    return {objectKey, contentLength: body.length, archiveSha256, verifiedAt: verification.verifiedAt, reused: true};
+  } catch (error) {
+    if (error?.status !== 404) {
+      throw error;
+    }
+  }
+  return uploadManifestFn({manifestPath, ...uploadOptions, objectKey});
+}
+
+function directCatalogRef(catalog) {
+  return {
+    mode: catalog.mode,
+    catalogId: catalog.catalogId,
+    objectKey: catalog.objectKey,
+    contentLength: catalog.contentLength,
+    sha256: catalog.sha256,
+    verifiedAt: catalog.verifiedAt,
+  };
+}
+
+function assertDirectCatalogRef(catalog, expectedMode, label) {
+  if (
+    !catalog
+    || catalog.mode !== expectedMode
+    || !/^[a-f0-9]{64}$/u.test(catalog.catalogId)
+    || typeof catalog.objectKey !== 'string'
+    || !catalog.objectKey
+    || !Number.isSafeInteger(catalog.contentLength)
+    || catalog.contentLength <= 0
+    || !/^[a-f0-9]{64}$/u.test(catalog.sha256)
+    || typeof catalog.verifiedAt !== 'string'
+    || !catalog.verifiedAt
+  ) {
+    throw new Error(`files ${label} catalog ref 无效。`);
+  }
+  return directCatalogRef(catalog);
+}
+
+function buildDirectFilesLatest({database, bucket, state}) {
+  const latestFullCatalog = assertDirectCatalogRef(state?.latestCatalog, 'full', 'latest full');
+  const historyCatalogs = (state?.historyCatalogs ?? []).map((catalog) => (
+    assertDirectCatalogRef(catalog, 'history', 'history')
+  ));
+  return {
+    schemaVersion: DIRECT_FILES_LATEST_SCHEMA_VERSION,
+    backupKind: 'spacetimedb-direct-files-latest',
+    database,
+    bucket,
+    updatedAt: new Date().toISOString(),
+    latestFullCatalog,
+    historyCatalogs,
+  };
+}
+
+function validateDirectFilesLatest(latest, {database, bucket}) {
+  if (
+    latest?.schemaVersion !== DIRECT_FILES_LATEST_SCHEMA_VERSION
+    || latest.backupKind !== 'spacetimedb-direct-files-latest'
+    || latest.database !== database
+    || latest.bucket !== bucket
+    || !Array.isArray(latest.historyCatalogs)
+  ) {
+    throw new Error('files latest pointer 契约无效。');
+  }
+  return {
+    ...latest,
+    latestFullCatalog: assertDirectCatalogRef(latest.latestFullCatalog, 'full', 'latest full'),
+    historyCatalogs: latest.historyCatalogs.map((catalog) => assertDirectCatalogRef(catalog, 'history', 'history')),
+  };
+}
+
+async function publishDirectFilesLatest({
+  workDir,
+  database,
+  bucket,
+  objectPrefix,
+  state,
+  uploadOptions,
+  uploadManifestFn,
+  verifyFn,
+}) {
+  const latest = buildDirectFilesLatest({database, bucket, state});
+  for (const catalogRef of [latest.latestFullCatalog, ...latest.historyCatalogs]) {
+    await verifyFn({
+      ...uploadOptions,
+      objectKey: catalogRef.objectKey,
+      contentLength: catalogRef.contentLength,
+      archiveSha256: catalogRef.sha256,
+    });
+  }
+  const latestPath = join(workDir, `${sanitizeObjectPart(database, 'spacetimedb')}-latest.json`);
+  const latestObjectKey = `${normalizeObjectPrefix(objectPrefix, database)}/latest.json`;
+  writeManifest({manifestPath: latestPath, payload: latest});
+  const uploaded = await uploadManifestFn({manifestPath: latestPath, ...uploadOptions, objectKey: latestObjectKey});
+  const verification = await verifyFn({
+    ...uploadOptions,
+    objectKey: latestObjectKey,
+    contentLength: uploaded.contentLength,
+    archiveSha256: uploaded.archiveSha256,
+  });
+  return {
+    latest,
+    latestPath,
+    latestObjectKey,
+    contentLength: uploaded.contentLength,
+    sha256: uploaded.archiveSha256,
+    verifiedAt: verification.verifiedAt,
+  };
+}
+
+export async function runDirectFilesBackup({
+  mode,
+  dataDir,
+  workDir,
+  database,
+  bucket,
+  objectPrefix,
+  dryRun = false,
+  resultFile = '',
+  uploadOptions,
+  uploadFn = uploadDirectFile,
+  uploadManifestFn = uploadManifestFile,
+  verifyFn = verifyOssObject,
+  concurrency = 1,
+}) {
+  mkdirSync(workDir, {recursive: true});
+  const statePath = directFilesStatePath({workDir, database});
+  const state = readDirectFilesState(statePath, {database, bucket});
+  if (mode === 'history' && (!state?.baselineCatalog || state?.latestCatalog?.mode !== 'full')) {
+    throw new Error(`files history 模式缺少已发布 full baseline catalog: ${statePath}`);
+  }
+  const plan = mode === 'history' ? discoverHistoryPlan({dataDir}) : null;
+  const collected = await collectDirectFileEntries({
+    dataDir,
+    candidates: plan?.candidates ?? null,
+    objectPrefix,
+    database,
+  });
+  const baselineCatalogId = mode === 'history' ? (state?.baselineCatalog?.catalogId ?? '') : '';
+  const rootName = basename(dataDir);
+  const catalogId = directCatalogIdentity({mode, baselineCatalogId, rootName, ...collected});
+  const basePrefix = normalizeObjectPrefix(objectPrefix, database);
+  const catalogObjectKey = `${basePrefix}/catalogs/${mode}/${catalogId}.json`;
+  const catalogPath = join(workDir, `${sanitizeObjectPart(database, 'spacetimedb')}-${mode}-${catalogId}.catalog.json`);
+  const catalog = {
+    schemaVersion: DIRECT_FILES_CATALOG_SCHEMA_VERSION,
+    backupKind: mode === 'full' ? 'spacetimedb-data-dir-files' : 'spacetimedb-history-files',
+    database,
+    bucket,
+    mode,
+    catalogId,
+    catalogObjectKey,
+    baselineCatalogId,
+    rootName,
+    directories: collected.directories,
+    files: collected.files.map(({sourceStat: _sourceStat, ...file}) => file),
+    symlinks: collected.symlinks,
+  };
+  writeManifest({manifestPath: catalogPath, payload: catalog});
+  const summary = {
+    statePath,
+    catalogPath,
+    catalogObjectKey,
+    catalogId,
+    fileCount: collected.files.length,
+    symlinkCount: collected.symlinks.length,
+    totalSizeBytes: collected.files.reduce((sum, file) => sum + BigInt(file.sizeBytes), 0n).toString(),
+    candidateCount: plan?.candidates.length ?? 0,
+  };
+  if (resultFile) {
+    atomicWriteJson(resolvePath(resultFile), {...summary, dryRun});
+  }
+  console.log(`[database-backup] files ${mode}: files=${summary.fileCount}, symlinks=${summary.symlinkCount}, size=${formatBytes(summary.totalSizeBytes)}, catalog=${catalogId}`);
+  if (dryRun) {
+    console.log('[database-backup] files dry-run，仅扫描并生成本地 catalog，不上传或删除。');
+    return {...summary, catalog, uploadedCount: 0, reusedCount: 0};
+  }
+  if (mode === 'history' && plan.candidates.length === 0) {
+    await verifyFn({
+      ...uploadOptions,
+      objectKey: state.latestCatalog.objectKey,
+      contentLength: state.latestCatalog.contentLength,
+      archiveSha256: state.latestCatalog.sha256,
+    });
+    const latestPointer = await publishDirectFilesLatest({
+      workDir,
+      database,
+      bucket,
+      objectPrefix,
+      state,
+      uploadOptions,
+      uploadManifestFn,
+      verifyFn,
+    });
+    console.log('[database-backup] files history 没有可归档候选。');
+    const emptyResult = {...summary, catalog, latestPointer, uploadedCount: 0, reusedCount: 0, cleanup: null};
+    if (resultFile) {
+      atomicWriteJson(resolvePath(resultFile), emptyResult);
+    }
+    return emptyResult;
+  }
+
+  if (state?.latestCatalog?.catalogId === catalogId && state.latestCatalog.mode === mode) {
+    await verifyFn({...uploadOptions, objectKey: state.latestCatalog.objectKey, contentLength: state.latestCatalog.contentLength, archiveSha256: state.latestCatalog.sha256});
+    if (mode === 'full') {
+      const latestPointer = await publishDirectFilesLatest({
+        workDir,
+        database,
+        bucket,
+        objectPrefix,
+        state,
+        uploadOptions,
+        uploadManifestFn,
+        verifyFn,
+      });
+      console.log('[database-backup] files catalog 未变化，无文件需要上传。');
+      return {...summary, catalog, latestPointer, uploadedCount: 0, reusedCount: collected.files.length, unchanged: true};
+    }
+  }
+
+  if (state?.latestCatalog) {
+    await verifyFn({
+      ...uploadOptions,
+      objectKey: state.latestCatalog.objectKey,
+      contentLength: state.latestCatalog.contentLength,
+      archiveSha256: state.latestCatalog.sha256,
+    });
+  }
+
+  const previousFiles = new Map((state?.latestCatalog?.files ?? []).map((file) => [file.path, file]));
+  let uploadedCount = 0;
+  let reusedCount = 0;
+  let nextIndex = 0;
+  let completedCount = 0;
+  const workerCount = Math.min(concurrency, collected.files.length);
+  const workers = Array.from({length: workerCount}, async () => {
+    while (nextIndex < collected.files.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const file = collected.files[index];
+      const result = await ensureDirectObject({
+        file,
+        dataDir,
+        uploadOptions,
+        previousFile: previousFiles.get(file.path),
+        verifyCatalogReuse: mode === 'history',
+        uploadFn,
+        verifyFn,
+      });
+      if (result.status === 'uploaded') {
+        uploadedCount += 1;
+      } else {
+        reusedCount += 1;
+      }
+      completedCount += 1;
+      if (collected.files.length <= 100 || completedCount % 1000 === 0 || completedCount === collected.files.length) {
+        console.log(`[database-backup] files 进度: ${completedCount}/${collected.files.length} (${result.status}) ${file.path}`);
+      }
+    }
+  });
+  await Promise.all(workers);
+  const catalogUpload = await ensureDirectManifest({
+    manifestPath: catalogPath,
+    objectKey: catalogObjectKey,
+    uploadOptions,
+    uploadManifestFn,
+    verifyFn,
+  });
+  await verifyFn({...uploadOptions, objectKey: catalogObjectKey, contentLength: catalogUpload.contentLength, archiveSha256: catalogUpload.archiveSha256});
+
+  if (mode === 'history') {
+    await verifyFn({
+      ...uploadOptions,
+      objectKey: state.baselineCatalog.objectKey,
+      contentLength: state.baselineCatalog.contentLength,
+      archiveSha256: state.baselineCatalog.sha256,
+    });
+  }
+  const catalogRef = {
+    mode,
+    catalogId,
+    objectKey: catalogObjectKey,
+    contentLength: catalogUpload.contentLength,
+    sha256: catalogUpload.archiveSha256,
+    verifiedAt: catalogUpload.verifiedAt,
+    files: catalog.files,
+    symlinks: catalog.symlinks,
+  };
+  const nextState = {
+    schemaVersion: DIRECT_FILES_STATE_SCHEMA_VERSION,
+    backupKind: 'spacetimedb-direct-files-state',
+    database,
+    dataDir,
+    bucket,
+    updatedAt: new Date().toISOString(),
+    baselineCatalog: state?.baselineCatalog ?? catalogRef,
+    latestCatalog: mode === 'full' ? catalogRef : state.latestCatalog,
+    historyCatalogs: mode === 'history'
+      ? [...(state.historyCatalogs ?? []).filter((item) => item.catalogId !== catalogId), catalogRef]
+      : (state?.historyCatalogs ?? []),
+  };
+  const latestPointer = await publishDirectFilesLatest({
+    workDir,
+    database,
+    bucket,
+    objectPrefix,
+    state: nextState,
+    uploadOptions,
+    uploadManifestFn,
+    verifyFn,
+  });
+  atomicWriteJson(statePath, nextState);
+  let cleanup = null;
+  if (mode === 'history') {
+    cleanup = cleanupHistoryCandidates({dataDir, candidates: plan.candidates});
+  }
+  const finalResult = {...summary, catalog, latestPointer, uploadedCount, reusedCount, cleanup};
+  if (resultFile) {
+    atomicWriteJson(resolvePath(resultFile), finalResult);
+  }
+  return finalResult;
+}
+
+async function downloadOssBuffer({objectKey, uploadOptions}) {
+  const response = await signedOssRequest({
+    ...ossRequestDefaults(uploadOptions),
+    method: 'GET',
+    objectKey,
+    operation: '下载对象',
+  });
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function downloadOssFile({objectKey, destinationPath, uploadOptions}) {
+  const response = await signedOssRequest({
+    ...ossRequestDefaults(uploadOptions),
+    method: 'GET',
+    objectKey,
+    operation: '下载对象',
+  });
+  const tempPath = `${destinationPath}.partial-${process.pid}`;
+  rmSync(tempPath, {force: true});
+  try {
+    if (response.body) {
+      await pipeline(Readable.fromWeb(response.body), createWriteStream(tempPath, {mode: 0o600}));
+    } else {
+      writeFileSync(tempPath, Buffer.alloc(0), {mode: 0o600});
+    }
+    renameSync(tempPath, destinationPath);
+  } catch (error) {
+    rmSync(tempPath, {force: true});
+    throw error;
+  }
+}
+
+async function loadDirectFilesCatalog({catalogRef, database, bucket, uploadOptions, downloadBufferFn}) {
+  const catalogBody = await downloadBufferFn({objectKey: catalogRef.objectKey, uploadOptions});
+  if (catalogBody.length !== catalogRef.contentLength || sha256Hex(catalogBody) !== catalogRef.sha256) {
+    throw new Error(`files restore catalog 长度或 SHA-256 不一致: ${catalogRef.objectKey}`);
+  }
+  const catalog = JSON.parse(catalogBody.toString('utf8'));
+  if (
+    catalog.schemaVersion !== DIRECT_FILES_CATALOG_SCHEMA_VERSION
+    || catalog.backupKind !== 'spacetimedb-data-dir-files'
+    || catalog.database !== database
+    || catalog.bucket !== bucket
+    || catalog.catalogId !== catalogRef.catalogId
+    || !Array.isArray(catalog.directories)
+    || !Array.isArray(catalog.files)
+  ) {
+    throw new Error(`files restore catalog 契约无效: ${catalogRef.objectKey}`);
+  }
+  return {...catalog, symlinks: catalog.symlinks ?? []};
+}
+
+function assertDirectCatalogFile(file, index) {
+  if (
+    !file
+    || typeof file.path !== 'string'
+    || !Number.isSafeInteger(file.sizeBytes)
+    || file.sizeBytes < 0
+    || !/^[a-f0-9]{64}$/u.test(file.sha256)
+    || typeof file.objectKey !== 'string'
+    || !file.objectKey
+    || !Number.isSafeInteger(file.mode)
+  ) {
+    throw new Error(`files restore catalog 文件项无效: index=${index}`);
+  }
+}
+
+function assertDirectCatalogSymlink(symlink, index, restoreDir) {
+  if (
+    !symlink
+    || typeof symlink.path !== 'string'
+    || !symlink.path
+    || typeof symlink.target !== 'string'
+    || !symlink.target
+    || isAbsolute(symlink.target)
+  ) {
+    throw new Error(`files restore catalog 符号链接项无效: index=${index}`);
+  }
+  const destinationPath = resolve(restoreDir, symlink.path);
+  assertSafeRelativePath(restoreDir, destinationPath);
+  assertSafeRelativePath(restoreDir, resolve(dirname(destinationPath), symlink.target));
+}
+
+async function restoreDirectFilesCatalog({
+  catalog,
+  restoreDir,
+  uploadOptions,
+  resultFile = '',
+  dryRun = false,
+  downloadFileFn = downloadOssFile,
+}) {
+  const resolvedRestoreDir = resolvePath(restoreDir);
+  catalog.files.forEach(assertDirectCatalogFile);
+  catalog.symlinks.forEach((symlink, index) => assertDirectCatalogSymlink(symlink, index, resolvedRestoreDir));
+  const totalSizeBytes = catalog.files.reduce((sum, file) => sum + BigInt(file.sizeBytes), 0n).toString();
+  if (dryRun) {
+    const result = {
+      restoreDir: resolvedRestoreDir,
+      catalogId: catalog.catalogId,
+      fileCount: catalog.files.length,
+      symlinkCount: catalog.symlinks.length,
+      totalSizeBytes,
+      downloadedCount: 0,
+      reusedCount: 0,
+      dryRun: true,
+    };
+    if (resultFile) {
+      atomicWriteJson(resolvePath(resultFile), result);
+    }
+    return result;
+  }
+  mkdirSync(resolvedRestoreDir, {recursive: true, mode: 0o700});
+  for (const directoryPath of catalog.directories) {
+    if (directoryPath === '.') {
+      continue;
+    }
+    const absolutePath = resolve(resolvedRestoreDir, directoryPath);
+    assertSafeRelativePath(resolvedRestoreDir, absolutePath);
+    mkdirSync(absolutePath, {recursive: true});
+  }
+
+  let downloadedCount = 0;
+  let reusedCount = 0;
+  for (const [index, file] of catalog.files.entries()) {
+    const destinationPath = resolve(resolvedRestoreDir, file.path);
+    assertSafeRelativePath(resolvedRestoreDir, destinationPath);
+    mkdirSync(dirname(destinationPath), {recursive: true});
+    let reusable = false;
+    if (existsSync(destinationPath) && lstatSync(destinationPath).isFile()) {
+      const stat = statSync(destinationPath);
+      reusable = stat.size === file.sizeBytes && await sha256FileHex(destinationPath) === file.sha256;
+    }
+    if (reusable) {
+      reusedCount += 1;
+    } else {
+      rmSync(destinationPath, {force: true});
+      await downloadFileFn({objectKey: file.objectKey, destinationPath, uploadOptions});
+      const stat = statSync(destinationPath);
+      const sha256 = await sha256FileHex(destinationPath);
+      if (stat.size !== file.sizeBytes || sha256 !== file.sha256) {
+        rmSync(destinationPath, {force: true});
+        throw new Error(`files restore 对象长度或 SHA-256 不一致: ${file.path}`);
+      }
+      downloadedCount += 1;
+    }
+    chmodSync(destinationPath, file.mode & 0o7777);
+    console.log(`[database-backup] files restore: ${index + 1}/${catalog.files.length} (${reusable ? 'reused' : 'downloaded'}) ${file.path}`);
+  }
+  for (const symlink of catalog.symlinks) {
+    const destinationPath = resolve(resolvedRestoreDir, symlink.path);
+    assertSafeRelativePath(resolvedRestoreDir, destinationPath);
+    mkdirSync(dirname(destinationPath), {recursive: true});
+    rmSync(destinationPath, {recursive: true, force: true});
+    symlinkSync(symlink.target, destinationPath);
+    console.log(`[database-backup] files restore: symlink ${symlink.path} -> ${symlink.target}`);
+  }
+  const result = {
+    restoreDir: resolvedRestoreDir,
+    catalogId: catalog.catalogId,
+    fileCount: catalog.files.length,
+    symlinkCount: catalog.symlinks.length,
+    totalSizeBytes,
+    downloadedCount,
+    reusedCount,
+  };
+  if (resultFile) {
+    atomicWriteJson(resolvePath(resultFile), result);
+  }
+  return result;
+}
+
+export async function restoreDirectFilesBackup({
+  statePath,
+  restoreDir,
+  database,
+  bucket,
+  uploadOptions,
+  resultFile = '',
+  dryRun = false,
+  downloadBufferFn = downloadOssBuffer,
+  downloadFileFn = downloadOssFile,
+}) {
+  const state = readDirectFilesState(resolvePath(statePath), {database, bucket});
+  if (!state?.latestCatalog || state.latestCatalog.mode !== 'full') {
+    throw new Error(`files restore 缺少 full baseline catalog: ${statePath}`);
+  }
+  const catalogRef = assertDirectCatalogRef(state.latestCatalog, 'full', 'latest full');
+  const catalog = await loadDirectFilesCatalog({catalogRef, database, bucket, uploadOptions, downloadBufferFn});
+  return restoreDirectFilesCatalog({
+    catalog,
+    restoreDir,
+    uploadOptions,
+    resultFile,
+    dryRun,
+    downloadFileFn,
+  });
+}
+
+export async function restoreDirectFilesLatest({
+  restoreDir,
+  database,
+  bucket,
+  objectPrefix,
+  uploadOptions,
+  resultFile = '',
+  dryRun = false,
+  downloadBufferFn = downloadOssBuffer,
+  downloadFileFn = downloadOssFile,
+  verifyFn = verifyOssObject,
+}) {
+  const latestObjectKey = `${normalizeObjectPrefix(objectPrefix, database)}/latest.json`;
+  const latestBody = await downloadBufferFn({objectKey: latestObjectKey, uploadOptions});
+  const latestSha256 = sha256Hex(latestBody);
+  await verifyFn({
+    ...uploadOptions,
+    objectKey: latestObjectKey,
+    contentLength: latestBody.length,
+    archiveSha256: latestSha256,
+  });
+  const latest = validateDirectFilesLatest(JSON.parse(latestBody.toString('utf8')), {database, bucket});
+  const catalogRef = latest.latestFullCatalog;
+  await verifyFn({
+    ...uploadOptions,
+    objectKey: catalogRef.objectKey,
+    contentLength: catalogRef.contentLength,
+    archiveSha256: catalogRef.sha256,
+  });
+  const catalog = await loadDirectFilesCatalog({catalogRef, database, bucket, uploadOptions, downloadBufferFn});
+  return restoreDirectFilesCatalog({
+    catalog,
+    restoreDir,
+    uploadOptions,
+    resultFile,
+    dryRun,
+    downloadFileFn,
+  });
+}
+
 function regionFromEndpoint(endpoint) {
   const match = /^oss-([a-z0-9-]+)\./u.exec(endpoint);
   if (!match) {
@@ -563,6 +1924,34 @@ function retryDelayMs({attempt, baseDelayMs, maxDelayMs, randomFn}) {
   return Math.floor(randomFn() * ceiling);
 }
 
+function ossRequestDefaults({
+  bucket,
+  endpoint,
+  accessKeyId,
+  accessKeySecret,
+  fetchImpl = globalThis.fetch,
+  nowFn = () => new Date(),
+  sleepImpl = sleep,
+  randomFn = Math.random,
+  maxAttempts = DEFAULT_OSS_REQUEST_MAX_ATTEMPTS,
+  retryBaseDelayMs = DEFAULT_OSS_RETRY_BASE_DELAY_MS,
+  retryMaxDelayMs = DEFAULT_OSS_RETRY_MAX_DELAY_MS,
+}) {
+  return {
+    bucket,
+    endpoint,
+    accessKeyId,
+    accessKeySecret,
+    fetchImpl,
+    nowFn,
+    sleepImpl,
+    randomFn,
+    maxAttempts,
+    retryBaseDelayMs,
+    retryMaxDelayMs,
+  };
+}
+
 async function signedOssRequest({
   method,
   bucket,
@@ -694,21 +2083,70 @@ function resolveMultipartPartSize(fileSize, configuredPartSize) {
   return partSize;
 }
 
-async function verifyUploadedObject({requestOptions, expectedContentLength}) {
+async function verifyUploadedObject({requestOptions, expectedContentLength, expectedArchiveSha256}) {
   const response = await signedOssRequest({
     ...requestOptions,
     method: 'HEAD',
     operation: 'HEAD 验证',
   });
   const contentLengthHeader = response.headers.get('content-length');
-  if (!contentLengthHeader || !/^\d+$/u.test(contentLengthHeader)) {
-    throw new Error(`OSS HEAD 验证缺少有效 content-length: ${contentLengthHeader ?? '<missing>'}`);
+  const metadataLengthHeader = response.headers.get('x-oss-meta-file-size');
+  const effectiveLengthHeader = /^\d+$/u.test(contentLengthHeader ?? '')
+    ? contentLengthHeader
+    : metadataLengthHeader;
+  if (!effectiveLengthHeader || !/^\d+$/u.test(effectiveLengthHeader)) {
+    throw new Error(
+      `OSS HEAD 验证缺少有效 content-length/file-size: content-length=${contentLengthHeader ?? '<missing>'}, file-size=${metadataLengthHeader ?? '<missing>'}`,
+    );
   }
-  const remoteContentLength = Number(contentLengthHeader);
+  const remoteContentLength = Number(effectiveLengthHeader);
   if (remoteContentLength !== expectedContentLength) {
     throw new Error(`OSS HEAD 验证长度不一致: local=${expectedContentLength}, remote=${remoteContentLength}`);
   }
-  return {verifiedAt: new Date().toISOString(), remoteContentLength};
+  const remoteArchiveSha256 = String(
+    response.headers.get('x-oss-meta-file-sha256')
+    ?? response.headers.get('x-oss-meta-archive-sha256')
+    ?? '',
+  ).trim().toLowerCase();
+  if (remoteArchiveSha256 !== expectedArchiveSha256) {
+    throw new Error(`OSS HEAD 验证 SHA-256 不一致: local=${expectedArchiveSha256}, remote=${remoteArchiveSha256 || '<missing>'}`);
+  }
+  return {verifiedAt: new Date().toISOString(), remoteContentLength, remoteArchiveSha256};
+}
+
+export async function verifyOssObject({
+  bucket,
+  endpoint,
+  objectKey,
+  accessKeyId,
+  accessKeySecret,
+  contentLength,
+  archiveSha256,
+  fetchImpl = globalThis.fetch,
+  nowFn = () => new Date(),
+  sleepImpl = sleep,
+  randomFn = Math.random,
+  maxAttempts = DEFAULT_OSS_REQUEST_MAX_ATTEMPTS,
+}) {
+  const requestOptions = {
+    bucket,
+    endpoint,
+    objectKey,
+    accessKeyId,
+    accessKeySecret,
+    fetchImpl,
+    nowFn,
+    sleepImpl,
+    randomFn,
+    maxAttempts,
+    retryBaseDelayMs: DEFAULT_OSS_RETRY_BASE_DELAY_MS,
+    retryMaxDelayMs: DEFAULT_OSS_RETRY_MAX_DELAY_MS,
+  };
+  return verifyUploadedObject({
+    requestOptions,
+    expectedContentLength: Number(contentLength),
+    expectedArchiveSha256: String(archiveSha256 ?? '').trim().toLowerCase(),
+  });
 }
 
 async function abortMultipartUpload({requestOptions, uploadId}) {
@@ -741,13 +2179,20 @@ export async function uploadArchive({
   nowFn = () => new Date(),
   sleepImpl = sleep,
   randomFn = Math.random,
+  backupKind = 'spacetimedb-data-dir',
+  archiveSha256 = '',
+  contentType = 'application/gzip',
+  allowEmpty = false,
+  bandwidthLimiter = null,
 }) {
   const fileStat = statSync(archivePath);
-  if (!fileStat.isFile() || fileStat.size <= 0) {
-    throw new Error(`待上传备份必须是非空文件: ${archivePath}`);
+  if (!fileStat.isFile() || (!allowEmpty && fileStat.size <= 0)) {
+    throw new Error(`待上传备份必须是${allowEmpty ? '' : '非空'}普通文件: ${archivePath}`);
+  }
+  const verifiedArchiveSha256 = archiveSha256 || await sha256FileHex(archivePath);
+  if (!/^[a-f0-9]{64}$/u.test(verifiedArchiveSha256)) {
+    throw new Error(`归档 SHA-256 无效: ${verifiedArchiveSha256}`);
   }
-  const partSize = resolveMultipartPartSize(fileStat.size, partSizeBytes);
-  const partCount = Math.ceil(fileStat.size / partSize);
   const requestOptions = {
     bucket,
     endpoint,
@@ -762,6 +2207,26 @@ export async function uploadArchive({
     retryBaseDelayMs,
     retryMaxDelayMs,
   };
+  if (fileStat.size === 0) {
+    await signedOssRequest({
+      ...requestOptions,
+      method: 'PUT',
+      headers: {
+        'content-type': contentType,
+        'x-oss-meta-archive-sha256': verifiedArchiveSha256,
+        'x-oss-meta-file-sha256': verifiedArchiveSha256,
+        'x-oss-meta-file-size': '0',
+        'x-oss-meta-backup-kind': backupKind,
+      },
+      contentLength: 0,
+      bodyFactory: () => Buffer.alloc(0),
+      operation: '上传空文件',
+    });
+    const verification = await verifyUploadedObject({requestOptions, expectedContentLength: 0, expectedArchiveSha256: verifiedArchiveSha256});
+    return {bucket, objectKey, contentLength: 0, archiveSha256: verifiedArchiveSha256, etag: '', uploadMode: 'single', partCount: 1, partSizeBytes: 0, verifiedAt: verification.verifiedAt};
+  }
+  const partSize = resolveMultipartPartSize(fileStat.size, partSizeBytes);
+  const partCount = Math.ceil(fileStat.size / partSize);
   let uploadId = '';
   let uploadCompleted = false;
 
@@ -772,8 +2237,11 @@ export async function uploadArchive({
       method: 'POST',
       queries: {uploads: null},
       headers: {
-        'content-type': 'application/gzip',
-        'x-oss-meta-backup-kind': 'spacetimedb-data-dir',
+        'content-type': contentType,
+        'x-oss-meta-archive-sha256': verifiedArchiveSha256,
+        'x-oss-meta-file-sha256': verifiedArchiveSha256,
+        'x-oss-meta-file-size': String(fileStat.size),
+        'x-oss-meta-backup-kind': backupKind,
       },
       operation: 'InitiateMultipartUpload',
     });
@@ -793,7 +2261,10 @@ export async function uploadArchive({
         queries: {partNumber, uploadId},
         headers: {'content-type': 'application/octet-stream'},
         contentLength,
-        bodyFactory: () => createReadStream(archivePath, {start, end}),
+        bodyFactory: () => {
+          const stream = createReadStream(archivePath, {start, end});
+          return bandwidthLimiter ? bandwidthLimiter.wrap(stream) : stream;
+        },
         operation: `UploadPart ${partNumber}/${partCount}`,
       });
       const etag = response.headers.get('etag');
@@ -822,19 +2293,24 @@ export async function uploadArchive({
       }
     } catch (completeError) {
       try {
-        await verifyUploadedObject({requestOptions, expectedContentLength: fileStat.size});
+        await verifyUploadedObject({requestOptions, expectedContentLength: fileStat.size, expectedArchiveSha256: verifiedArchiveSha256});
         completeResponse = null;
       } catch {
         throw completeError;
       }
     }
 
-    const verification = await verifyUploadedObject({requestOptions, expectedContentLength: fileStat.size});
+    const verification = await verifyUploadedObject({
+      requestOptions,
+      expectedContentLength: fileStat.size,
+      expectedArchiveSha256: verifiedArchiveSha256,
+    });
     uploadCompleted = true;
     return {
       bucket,
       objectKey,
       contentLength: fileStat.size,
+      archiveSha256: verifiedArchiveSha256,
       etag: completeResponse?.headers.get('etag')?.replace(/^"|"$/gu, '') ?? '',
       uploadMode: 'multipart',
       partCount,
@@ -849,7 +2325,256 @@ export async function uploadArchive({
   }
 }
 
-async function uploadExistingArchive({args, env, bucket, endpoint, accessKeyId, accessKeySecret, objectPrefix}) {
+export async function uploadDirectFile({
+  archivePath,
+  bucket,
+  endpoint,
+  objectKey,
+  accessKeyId,
+  accessKeySecret,
+  fetchImpl = globalThis.fetch,
+  nowFn = () => new Date(),
+  sleepImpl = sleep,
+  randomFn = Math.random,
+  maxAttempts = DEFAULT_OSS_REQUEST_MAX_ATTEMPTS,
+  retryBaseDelayMs = DEFAULT_OSS_RETRY_BASE_DELAY_MS,
+  retryMaxDelayMs = DEFAULT_OSS_RETRY_MAX_DELAY_MS,
+  backupKind = 'spacetimedb-direct-file',
+  archiveSha256 = '',
+  contentType = 'application/octet-stream',
+  allowEmpty = true,
+  bandwidthLimiter = null,
+}) {
+  const fileStat = statSync(archivePath);
+  if (!fileStat.isFile() || (!allowEmpty && fileStat.size <= 0)) {
+    throw new Error(`待上传备份必须是${allowEmpty ? '' : '非空'}普通文件: ${archivePath}`);
+  }
+  if (fileStat.size > DIRECT_FILES_SINGLE_PUT_MAX_BYTES) {
+    return uploadArchive({
+      archivePath,
+      bucket,
+      endpoint,
+      objectKey,
+      accessKeyId,
+      accessKeySecret,
+      fetchImpl,
+      nowFn,
+      sleepImpl,
+      randomFn,
+      maxAttempts,
+      retryBaseDelayMs,
+      retryMaxDelayMs,
+      backupKind,
+      archiveSha256,
+      contentType,
+      allowEmpty,
+      bandwidthLimiter,
+    });
+  }
+  const verifiedArchiveSha256 = archiveSha256 || await sha256FileHex(archivePath);
+  if (!/^[a-f0-9]{64}$/u.test(verifiedArchiveSha256)) {
+    throw new Error(`归档 SHA-256 无效: ${verifiedArchiveSha256}`);
+  }
+  const requestOptions = {
+    bucket,
+    endpoint,
+    objectKey,
+    accessKeyId,
+    accessKeySecret,
+    fetchImpl,
+    nowFn,
+    sleepImpl,
+    randomFn,
+    maxAttempts,
+    retryBaseDelayMs,
+    retryMaxDelayMs,
+  };
+  await signedOssRequest({
+    ...requestOptions,
+    method: 'PUT',
+    headers: {
+      'content-type': contentType,
+      'x-oss-meta-archive-sha256': verifiedArchiveSha256,
+      'x-oss-meta-file-sha256': verifiedArchiveSha256,
+      'x-oss-meta-file-size': String(fileStat.size),
+      'x-oss-meta-backup-kind': backupKind,
+    },
+    contentLength: fileStat.size,
+    bodyFactory: () => {
+      if (fileStat.size === 0) {
+        return Buffer.alloc(0);
+      }
+      const stream = createReadStream(archivePath);
+      return bandwidthLimiter ? bandwidthLimiter.wrap(stream) : stream;
+    },
+    operation: '上传逐文件对象',
+  });
+  const verification = await verifyUploadedObject({
+    requestOptions,
+    expectedContentLength: fileStat.size,
+    expectedArchiveSha256: verifiedArchiveSha256,
+  });
+  return {
+    bucket,
+    objectKey,
+    contentLength: fileStat.size,
+    archiveSha256: verifiedArchiveSha256,
+    etag: '',
+    uploadMode: 'single',
+    partCount: 1,
+    partSizeBytes: fileStat.size,
+    verifiedAt: verification.verifiedAt,
+  };
+}
+
+export async function uploadManifestFile({
+  manifestPath,
+  bucket,
+  endpoint,
+  objectKey,
+  accessKeyId,
+  accessKeySecret,
+  fetchImpl = globalThis.fetch,
+  nowFn = () => new Date(),
+  sleepImpl = sleep,
+  randomFn = Math.random,
+  maxAttempts = DEFAULT_OSS_REQUEST_MAX_ATTEMPTS,
+  bandwidthLimiter = null,
+}) {
+  const body = readFileSync(manifestPath);
+  if (body.length === 0) {
+    throw new Error(`待上传 manifest 不能为空: ${manifestPath}`);
+  }
+  const archiveSha256 = sha256Hex(body);
+  const requestOptions = {
+    bucket,
+    endpoint,
+    objectKey,
+    accessKeyId,
+    accessKeySecret,
+    fetchImpl,
+    nowFn,
+    sleepImpl,
+    randomFn,
+    maxAttempts,
+    retryBaseDelayMs: DEFAULT_OSS_RETRY_BASE_DELAY_MS,
+    retryMaxDelayMs: DEFAULT_OSS_RETRY_MAX_DELAY_MS,
+  };
+  await signedOssRequest({
+    ...requestOptions,
+    method: 'PUT',
+    headers: {
+      'content-type': 'application/json',
+      'x-oss-meta-archive-sha256': archiveSha256,
+      'x-oss-meta-file-size': String(body.length),
+      'x-oss-meta-backup-kind': 'spacetimedb-backup-manifest',
+    },
+    contentLength: body.length,
+    bodyFactory: () => {
+      const stream = createBufferReadStream(body);
+      return bandwidthLimiter ? bandwidthLimiter.wrap(stream) : stream;
+    },
+    operation: '上传 manifest',
+  });
+  const verification = await verifyUploadedObject({
+    requestOptions,
+    expectedContentLength: body.length,
+    expectedArchiveSha256: archiveSha256,
+  });
+  return {objectKey, contentLength: body.length, archiveSha256, verifiedAt: verification.verifiedAt};
+}
+
+function uploadedManifestPayload({manifest, database, result}) {
+  return {
+    ...manifest,
+    database,
+    bucket: result.bucket,
+    objectKey: result.objectKey,
+    manifestObjectKey: `${result.objectKey}.manifest.json`,
+    contentLength: result.contentLength,
+    archiveSha256: result.archiveSha256,
+    etag: result.etag,
+    uploadMode: result.uploadMode,
+    partCount: result.partCount,
+    partSizeBytes: result.partSizeBytes,
+    verifiedAt: result.verifiedAt,
+    uploadedAt: new Date().toISOString(),
+    uploadStatus: 'uploaded',
+  };
+}
+
+export async function uploadHistoryArchiveWithCleanup({
+  archivePath,
+  manifestPath,
+  manifest,
+  statePath,
+  uploadOptions,
+  uploadFn = uploadArchive,
+  manifestUploadFn = uploadManifestFile,
+  verifyFn = verifyOssObject,
+}) {
+  const result = await uploadFn({
+    archivePath,
+    ...uploadOptions,
+    backupKind: 'spacetimedb-history',
+  });
+  const uploadedManifest = uploadedManifestPayload({manifest, database: manifest.database, result});
+  writeManifest({manifestPath, payload: uploadedManifest});
+  const manifestUpload = await manifestUploadFn({
+    manifestPath,
+    ...uploadOptions,
+    objectKey: uploadedManifest.manifestObjectKey,
+  });
+  uploadedManifest.manifestVerifiedAt = manifestUpload.verifiedAt;
+  uploadedManifest.manifestContentLength = manifestUpload.contentLength;
+  uploadedManifest.manifestArchiveSha256 = manifestUpload.archiveSha256;
+  writeManifest({manifestPath, payload: uploadedManifest});
+  let state = validateHistoryState(readManifest(statePath), {
+    database: uploadedManifest.database,
+    dataDir: uploadedManifest.dataDir,
+  });
+  if (state.baseline.id !== uploadedManifest.baselineId) {
+    throw new Error(`history manifest baselineId 与 state 不匹配: manifest=${uploadedManifest.baselineId}, state=${state.baseline.id}`);
+  }
+  await verifyFn({
+    ...uploadOptions,
+    bucket: state.baseline.bucket,
+    objectKey: state.baseline.objectKey,
+    contentLength: state.baseline.contentLength,
+    archiveSha256: state.baseline.archiveSha256,
+  });
+  await verifyFn({
+    ...uploadOptions,
+    bucket: state.baseline.bucket,
+    objectKey: state.baseline.manifestObjectKey,
+    contentLength: state.baseline.manifestContentLength,
+    archiveSha256: state.baseline.manifestArchiveSha256,
+  });
+  state = recordHistoryBatch({
+    statePath,
+    state,
+    manifest: uploadedManifest,
+    uploadResult: result,
+    manifestUpload,
+    status: 'uploaded',
+  });
+  const cleanup = cleanupHistoryCandidates({
+    dataDir: uploadedManifest.dataDir,
+    candidates: uploadedManifest.candidates,
+  });
+  state = recordHistoryBatch({
+    statePath,
+    state,
+    manifest: uploadedManifest,
+    uploadResult: result,
+    manifestUpload,
+    status: 'cleaned',
+    cleanedAt: new Date().toISOString(),
+  });
+  return {result, uploadedManifest, cleanup, state};
+}
+
+async function uploadExistingArchive({args, env, bucket, endpoint, accessKeyId, accessKeySecret, objectPrefix, bandwidthLimiter}) {
   const archivePath = resolvePath(args.uploadArchive);
   if (!existsSync(archivePath)) {
     throw new Error(`待上传备份文件不存在: ${archivePath}`);
@@ -860,6 +2585,13 @@ async function uploadExistingArchive({args, env, bucket, endpoint, accessKeyId,
   const dataDir = firstNonEmpty(manifest.dataDir, env.GENARRATIVE_DATABASE_BACKUP_DATA_DIR, DEFAULT_PRODUCTION_DATA_DIR);
   const database = firstNonEmpty(args.database, manifest.database, env.GENARRATIVE_SPACETIME_DATABASE, basename(dataDir));
   const objectKey = firstNonEmpty(args.objectKey, manifest.objectKey, buildBackupNames({database, dataDir, objectPrefix}).objectKey);
+  if (manifest.backupKind !== 'spacetimedb-history') {
+    manifest.backupKind = 'spacetimedb-data-dir';
+    manifest.baselineStatePath = firstNonEmpty(
+      manifest.baselineStatePath,
+      historyStatePath({args, env, workDir: dirname(archivePath), database}),
+    );
+  }
 
   console.log(`[database-backup] 上传已有备份: ${archivePath}`);
   console.log(`[database-backup] 目标对象: oss://${bucket}/${objectKey}`);
@@ -869,30 +2601,52 @@ async function uploadExistingArchive({args, env, bucket, endpoint, accessKeyId,
     return;
   }
 
-  const result = await uploadArchive({archivePath, bucket, endpoint, objectKey, accessKeyId, accessKeySecret});
+  const statePath = resolvePath(firstNonEmpty(
+    manifest.baselineStatePath,
+    historyStatePath({args, env, workDir: dirname(archivePath), database}),
+  ));
+  let result;
+  let uploadedAt;
+  if (manifest.backupKind === 'spacetimedb-history') {
+    const historyResult = await uploadHistoryArchiveWithCleanup({
+      archivePath,
+      manifestPath,
+      manifest,
+      statePath,
+      uploadOptions: {bucket, endpoint, objectKey, accessKeyId, accessKeySecret, bandwidthLimiter},
+    });
+    result = historyResult.result;
+    uploadedAt = historyResult.uploadedManifest.uploadedAt;
+    console.log(`[database-backup] history 上传并清理完成: ${JSON.stringify(historyResult.cleanup)}`);
+  } else {
+    result = await uploadArchive({archivePath, bucket, endpoint, objectKey, accessKeyId, accessKeySecret, bandwidthLimiter});
+    const uploadedManifest = uploadedManifestPayload({manifest, database, result});
+    uploadedAt = uploadedManifest.uploadedAt;
+    writeManifest({manifestPath, payload: uploadedManifest});
+    const manifestUpload = await uploadManifestFile({
+      manifestPath,
+      bucket,
+      endpoint,
+      objectKey: uploadedManifest.manifestObjectKey,
+      accessKeyId,
+      accessKeySecret,
+      bandwidthLimiter,
+    });
+    uploadedManifest.manifestVerifiedAt = manifestUpload.verifiedAt;
+    uploadedManifest.manifestContentLength = manifestUpload.contentLength;
+    uploadedManifest.manifestArchiveSha256 = manifestUpload.archiveSha256;
+    writeManifest({manifestPath, payload: uploadedManifest});
+    const previousState = existsSync(statePath)
+      ? validateHistoryState(readManifest(statePath), {database, dataDir})
+      : null;
+    const baseline = normalizeUploadedBaselineManifest(uploadedManifest, {database, dataDir});
+    writeBaselineState({statePath, baseline, previousState});
+    console.log(`[database-backup] 已写入 baseline state: ${statePath}`);
+  }
   console.log(`[database-backup] 上传完成: ${JSON.stringify(result)}`);
 
-  const uploadedAt = new Date().toISOString();
-  writeManifest({
-    manifestPath,
-    payload: {
-      ...manifest,
-      database,
-      bucket: result.bucket,
-      objectKey: result.objectKey,
-      contentLength: result.contentLength,
-      etag: result.etag,
-      uploadMode: result.uploadMode,
-      partCount: result.partCount,
-      partSizeBytes: result.partSizeBytes,
-      verifiedAt: result.verifiedAt,
-      uploadedAt,
-      uploadStatus: 'uploaded',
-    },
-  });
-
   if (args.resultFile) {
-    writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({archivePath, manifestPath, ...result, uploadedAt}, null, 2)}\n`, 'utf8');
+    writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({archivePath, manifestPath, statePath, ...result, uploadedAt}, null, 2)}\n`, 'utf8');
   }
 
   const keepLocal = args.keepLocal || String(env.GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL ?? '').trim().toLowerCase() === 'true';
@@ -906,6 +2660,206 @@ async function uploadExistingArchive({args, env, bucket, endpoint, accessKeyId,
   }
 }
 
+async function publishExistingManifest({args, bucket, endpoint, accessKeyId, accessKeySecret, bandwidthLimiter}) {
+  const manifestPath = resolvePath(args.publishManifest);
+  const manifest = readManifest(manifestPath);
+  if (manifest.uploadStatus !== 'uploaded' || !manifest.objectKey) {
+    throw new Error('只允许发布 uploadStatus=uploaded 且包含 objectKey 的备份 manifest。');
+  }
+  manifest.manifestObjectKey = manifest.manifestObjectKey || `${manifest.objectKey}.manifest.json`;
+  writeManifest({manifestPath, payload: manifest});
+  const result = await uploadManifestFile({
+    manifestPath,
+    bucket,
+    endpoint,
+    objectKey: manifest.manifestObjectKey,
+    accessKeyId,
+    accessKeySecret,
+    bandwidthLimiter,
+  });
+  manifest.manifestVerifiedAt = result.verifiedAt;
+  manifest.manifestContentLength = result.contentLength;
+  manifest.manifestArchiveSha256 = result.archiveSha256;
+  writeManifest({manifestPath, payload: manifest});
+  console.log(`[database-backup] manifest 上传并验真完成: ${JSON.stringify(result)}`);
+}
+
+export async function resumeUploadedHistoryBatch({statePath, state, dataDir, verificationOptions, verifyFn = verifyOssObject}) {
+  const pendingBatch = state.batches.find((batch) => batch.status === 'uploaded');
+  if (!pendingBatch) {
+    return state;
+  }
+  console.log(`[database-backup] 重试已上传 history 批次的本地清理: ${pendingBatch.batchId}`);
+  await verifyFn({
+    ...verificationOptions,
+    objectKey: pendingBatch.objectKey,
+    contentLength: pendingBatch.contentLength,
+    archiveSha256: pendingBatch.archiveSha256,
+  });
+  await verifyFn({
+    ...verificationOptions,
+    objectKey: pendingBatch.manifestObjectKey,
+    contentLength: pendingBatch.manifestContentLength,
+    archiveSha256: pendingBatch.manifestArchiveSha256,
+  });
+  const cleanup = cleanupHistoryCandidates({dataDir, candidates: pendingBatch.candidates});
+  const manifest = {
+    batchId: pendingBatch.batchId,
+    uploadedAt: pendingBatch.uploadedAt,
+    candidates: pendingBatch.candidates,
+  };
+  const uploadResult = {
+    objectKey: pendingBatch.objectKey,
+    contentLength: pendingBatch.contentLength,
+    archiveSha256: pendingBatch.archiveSha256,
+    verifiedAt: pendingBatch.verifiedAt,
+  };
+  const manifestUpload = {
+    objectKey: pendingBatch.manifestObjectKey,
+    contentLength: pendingBatch.manifestContentLength,
+    archiveSha256: pendingBatch.manifestArchiveSha256,
+    verifiedAt: pendingBatch.manifestVerifiedAt,
+  };
+  const nextState = recordHistoryBatch({
+    statePath,
+    state,
+    manifest,
+    uploadResult,
+    manifestUpload,
+    status: 'cleaned',
+    cleanedAt: new Date().toISOString(),
+  });
+  console.log(`[database-backup] 已完成 history 清理重试: ${JSON.stringify(cleanup)}`);
+  return nextState;
+}
+
+async function runHistoryBackup({
+  args,
+  env,
+  dataDir,
+  workDir,
+  database,
+  bucket,
+  endpoint,
+  accessKeyId,
+  accessKeySecret,
+  objectPrefix,
+  keepLocal,
+  bandwidthLimiter,
+}) {
+  const statePath = historyStatePath({args, env, workDir, database});
+  let state = loadOrImportHistoryState({args, env, statePath, database, dataDir});
+  if (!args.dryRun && !args.deferUpload) {
+    console.log(`[database-backup] 重新验真 full baseline: oss://${state.baseline.bucket}/${state.baseline.objectKey}`);
+    await verifyOssObject({
+      bucket: state.baseline.bucket,
+      endpoint,
+      objectKey: state.baseline.objectKey,
+      accessKeyId,
+      accessKeySecret,
+      contentLength: state.baseline.contentLength,
+      archiveSha256: state.baseline.archiveSha256,
+    });
+    await verifyOssObject({
+      bucket: state.baseline.bucket,
+      endpoint,
+      objectKey: state.baseline.manifestObjectKey,
+      accessKeyId,
+      accessKeySecret,
+      contentLength: state.baseline.manifestContentLength,
+      archiveSha256: state.baseline.manifestArchiveSha256,
+    });
+    state = await resumeUploadedHistoryBatch({
+      statePath,
+      state,
+      dataDir,
+      verificationOptions: {bucket, endpoint, accessKeyId, accessKeySecret},
+    });
+  }
+  const plan = discoverHistoryPlan({dataDir});
+  console.log(`[database-backup] history replicas: ${JSON.stringify(plan.replicas)}`);
+  console.log(`[database-backup] history 候选: count=${plan.candidates.length}, size=${formatBytes(plan.totalSizeBytes)}`);
+  if (args.resultFile) {
+    writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({statePath, baseline: state.baseline, ...plan}, null, 2)}\n`, 'utf8');
+  }
+  if (args.dryRun) {
+    console.log('[database-backup] history dry-run，仅输出安全候选，不打包、上传或删除。');
+    return;
+  }
+  if (plan.candidates.length === 0) {
+    console.log('[database-backup] 没有可归档的 history 候选。');
+    return;
+  }
+
+  assertSufficientHistoryWorkDirSpace({historySizeBytes: plan.totalSizeBytes, workDir, args, env});
+  const batchId = historyBatchId({baselineId: state.baseline.id, plan});
+  const {fileName, objectKey} = buildHistoryNames({
+    database,
+    objectPrefix,
+    baselineId: state.baseline.id,
+    batchId,
+  });
+  const archivePath = resolve(workDir, fileName);
+  const manifestPath = `${archivePath}.manifest.json`;
+  const manifest = {
+    schemaVersion: HISTORY_MANIFEST_SCHEMA_VERSION,
+    backupKind: 'spacetimedb-history',
+    createdAt: new Date().toISOString(),
+    database,
+    dataDir,
+    bucket,
+    objectKey,
+    archivePath,
+    baselineId: state.baseline.id,
+    baselineStatePath: statePath,
+    batchId,
+    replicas: plan.replicas,
+    candidates: plan.candidates,
+    totalSizeBytes: plan.totalSizeBytes,
+    uploadStatus: args.deferUpload ? 'deferred' : 'pending',
+  };
+  writeManifest({manifestPath, payload: manifest});
+  createHistoryArchive({
+    dataDir,
+    workDir,
+    fileName,
+    manifestPath,
+    candidates: plan.candidates,
+  });
+
+  if (args.deferUpload) {
+    console.log(`[database-backup] 已生成 history 归档，延后上传且未清理源文件: ${archivePath}`);
+    if (args.resultFile) {
+      writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({archivePath, manifestPath, statePath, bucket, objectKey, batchId}, null, 2)}\n`, 'utf8');
+    }
+    return;
+  }
+
+  const historyResult = await uploadHistoryArchiveWithCleanup({
+    archivePath,
+    manifestPath,
+    manifest,
+    statePath,
+    uploadOptions: {bucket, endpoint, objectKey, accessKeyId, accessKeySecret, bandwidthLimiter},
+  });
+  console.log(`[database-backup] history 上传并清理完成: ${JSON.stringify(historyResult.cleanup)}`);
+  if (args.resultFile) {
+    writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({
+      archivePath,
+      manifestPath,
+      statePath,
+      batchId,
+      ...historyResult.result,
+      uploadedAt: historyResult.uploadedManifest.uploadedAt,
+    }, null, 2)}\n`, 'utf8');
+  }
+  if (!keepLocal) {
+    rmSync(archivePath, {force: true});
+    rmSync(manifestPath, {force: true});
+    console.log('[database-backup] 已删除本地 history 临时归档和清单。');
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const env = loadEffectiveEnv(args.envFiles);
@@ -927,6 +2881,16 @@ async function main() {
   const objectPrefix = firstNonEmpty(args.objectPrefix, env.GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX, 'database-backups');
   const database = firstNonEmpty(args.database, env.GENARRATIVE_SPACETIME_DATABASE, basename(dataDir));
   const keepLocal = args.keepLocal || String(env.GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL ?? '').trim().toLowerCase() === 'true';
+  const storageFormat = firstNonEmpty(args.storageFormat, env.GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT, 'archive');
+  const directFilesConcurrency = parseDirectFilesConcurrency(env.GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY);
+  const uploadBandwidthLimiter = createUploadBandwidthLimiter(env.GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND);
+
+  if (!['full', 'history'].includes(args.mode)) {
+    throw new Error(`--mode 只能是 full 或 history，实际: ${args.mode}`);
+  }
+  if (!['archive', 'files'].includes(storageFormat)) {
+    throw new Error(`--storage-format 只能是 archive 或 files，实际: ${storageFormat}`);
+  }
 
   for (const [label, value] of Object.entries({bucket, endpoint, accessKeyId, accessKeySecret})) {
     if (!value) {
@@ -934,8 +2898,132 @@ async function main() {
     }
   }
 
+  if (args.restoreFilesState && args.restoreFilesLatest) {
+    throw new Error('--restore-files-state 与 --restore-files-latest 不能同时使用。');
+  }
+  if (args.restoreFilesState) {
+    if (!args.restoreDir) {
+      throw new Error('--restore-files-state 必须同时传 --restore-dir。');
+    }
+    await restoreDirectFilesBackup({
+      statePath: args.restoreFilesState,
+      restoreDir: args.restoreDir,
+      database,
+      bucket,
+      uploadOptions: {bucket, endpoint, accessKeyId, accessKeySecret},
+      resultFile: args.resultFile,
+      dryRun: args.dryRun,
+    });
+    return;
+  }
+  if (args.restoreFilesLatest) {
+    if (!args.restoreDir) {
+      throw new Error('--restore-files-latest 必须同时传 --restore-dir。');
+    }
+    await restoreDirectFilesLatest({
+      restoreDir: args.restoreDir,
+      database,
+      bucket,
+      objectPrefix,
+      uploadOptions: {bucket, endpoint, accessKeyId, accessKeySecret},
+      resultFile: args.resultFile,
+      dryRun: args.dryRun,
+    });
+    return;
+  }
+  if (args.restoreDir) {
+    throw new Error('--restore-dir 只能与 --restore-files-state 或 --restore-files-latest 一起使用。');
+  }
+
+  if (!args.dryRun) {
+    const lockPath = acquireBackupLock({workDir, database});
+    console.log(`[database-backup] 已获取进程锁: ${lockPath}`);
+  }
+
+  if (args.publishManifest) {
+    await publishExistingManifest({args, bucket, endpoint, accessKeyId, accessKeySecret, bandwidthLimiter: uploadBandwidthLimiter});
+    return;
+  }
+
   if (args.uploadArchive) {
-    await uploadExistingArchive({args, env, bucket, endpoint, accessKeyId, accessKeySecret, objectPrefix});
+    await uploadExistingArchive({
+      args,
+      env,
+      bucket,
+      endpoint,
+      accessKeyId,
+      accessKeySecret,
+      objectPrefix,
+      bandwidthLimiter: uploadBandwidthLimiter,
+    });
+    return;
+  }
+
+  if (storageFormat === 'files') {
+    if (args.deferUpload) {
+      throw new Error('files 模式无需本地归档且不支持 --defer-upload；失败后使用同一 work-dir 重跑即可续传。');
+    }
+    const stopService = args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE);
+    const restartServicesAfter = collectRestartServicesAfterBackup({args, env});
+    let serviceStopped = false;
+    let backupError = null;
+    let restoreError = null;
+    try {
+      if (args.mode === 'full' && !args.dryRun) {
+        serviceStopped = stopServiceIfNeeded(stopService);
+      }
+      await runDirectFilesBackup({
+        mode: args.mode,
+        dataDir,
+        workDir,
+        database,
+        bucket,
+        objectPrefix,
+        dryRun: args.dryRun,
+        resultFile: args.resultFile,
+        uploadOptions: {bucket, endpoint, accessKeyId, accessKeySecret, bandwidthLimiter: uploadBandwidthLimiter},
+        concurrency: directFilesConcurrency,
+      });
+    } catch (error) {
+      backupError = error;
+    } finally {
+      try {
+        if (serviceStopped) {
+          restoreServicesAfterBackup({stopService, serviceStopped, restartServicesAfter});
+        } else if (!backupError && args.mode === 'full' && !args.dryRun) {
+          restartServicesAfterBackup(restartServicesAfter);
+        }
+      } catch (error) {
+        restoreError = error;
+      }
+    }
+    if (backupError && restoreError) {
+      throw new AggregateError([backupError, restoreError], `files 备份失败，且恢复依赖服务时也失败: ${backupError.message}; ${restoreError.message}`);
+    }
+    if (backupError) {
+      throw backupError;
+    }
+    if (restoreError) {
+      throw restoreError;
+    }
+    return;
+  }
+
+  if (args.mode === 'history') {
+    await runHistoryBackup({
+      args,
+      env,
+      dataDir,
+      workDir,
+      database,
+      bucket,
+      endpoint,
+      accessKeyId,
+      accessKeySecret,
+      objectPrefix,
+      keepLocal,
+      bandwidthLimiter: uploadBandwidthLimiter,
+    });
     return;
   }
 
@@ -983,50 +3071,63 @@ async function main() {
   }
 
   const manifestPath = `${archivePath}.manifest.json`;
+  const baselineStatePath = historyStatePath({args, env, workDir, database});
+  const fullManifest = {
+    backupKind: 'spacetimedb-data-dir',
+    createdAt: new Date().toISOString(),
+    database,
+    dataDir,
+    bucket,
+    objectKey,
+    archivePath,
+    baselineStatePath,
+    uploadStatus: args.deferUpload ? 'deferred' : 'pending',
+  };
   writeManifest({
     manifestPath,
-    payload: {
-      createdAt: new Date().toISOString(),
-      database,
-      dataDir,
-      bucket,
-      objectKey,
-      archivePath,
-      uploadStatus: args.deferUpload ? 'deferred' : 'pending',
-    },
+    payload: fullManifest,
   });
 
   if (args.deferUpload) {
     console.log(`[database-backup] 已生成本地冷备份，延后上传: ${archivePath}`);
     console.log(`[database-backup] 已写入备份清单: ${manifestPath}`);
     if (args.resultFile) {
-      writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({archivePath, manifestPath, bucket, objectKey}, null, 2)}\n`, 'utf8');
+      writeFileSync(resolvePath(args.resultFile), `${JSON.stringify({archivePath, manifestPath, baselineStatePath, bucket, objectKey}, null, 2)}\n`, 'utf8');
     }
     return;
   }
 
-  const result = await uploadArchive({archivePath, bucket, endpoint, objectKey, accessKeyId, accessKeySecret});
-  console.log(`[database-backup] 上传完成: ${JSON.stringify(result)}`);
-
-  writeManifest({
-    manifestPath,
-    payload: {
-      createdAt: new Date().toISOString(),
-      database,
-      dataDir,
-      bucket: result.bucket,
-      objectKey: result.objectKey,
-      archivePath,
-      contentLength: result.contentLength,
-      etag: result.etag,
-      uploadMode: result.uploadMode,
-      partCount: result.partCount,
-      partSizeBytes: result.partSizeBytes,
-      verifiedAt: result.verifiedAt,
-      uploadedAt: new Date().toISOString(),
-      uploadStatus: 'uploaded',
-    },
+  const result = await uploadArchive({
+    archivePath,
+    bucket,
+    endpoint,
+    objectKey,
+    accessKeyId,
+    accessKeySecret,
+    bandwidthLimiter: uploadBandwidthLimiter,
   });
+  console.log(`[database-backup] 上传完成: ${JSON.stringify(result)}`);
+  const uploadedManifest = uploadedManifestPayload({manifest: fullManifest, database, result});
+  writeManifest({manifestPath, payload: uploadedManifest});
+  const manifestUpload = await uploadManifestFile({
+    manifestPath,
+    bucket,
+    endpoint,
+    objectKey: uploadedManifest.manifestObjectKey,
+    accessKeyId,
+    accessKeySecret,
+    bandwidthLimiter: uploadBandwidthLimiter,
+  });
+  uploadedManifest.manifestVerifiedAt = manifestUpload.verifiedAt;
+  uploadedManifest.manifestContentLength = manifestUpload.contentLength;
+  uploadedManifest.manifestArchiveSha256 = manifestUpload.archiveSha256;
+  writeManifest({manifestPath, payload: uploadedManifest});
+  const previousState = existsSync(baselineStatePath)
+    ? validateHistoryState(readManifest(baselineStatePath), {database, dataDir})
+    : null;
+  const baseline = normalizeUploadedBaselineManifest(uploadedManifest, {database, dataDir});
+  writeBaselineState({statePath: baselineStatePath, baseline, previousState});
+  console.log(`[database-backup] 已写入 baseline state: ${baselineStatePath}`);
 
   if (!keepLocal) {
     rmSync(archivePath, {force: true});
diff --git a/scripts/deploy/pingora-gateway-env-shadow-switch.mjs b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
index ab7ba188e..aede1700b 100644
--- a/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
+++ b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import {
-  chownSync,
   chmodSync,
+  chownSync,
   lstatSync,
   mkdtempSync,
   readFileSync,
diff --git a/scripts/deploy/pingora-health-patrol-env-switch.mjs b/scripts/deploy/pingora-health-patrol-env-switch.mjs
index 60f5df19a..dd09c41d8 100644
--- a/scripts/deploy/pingora-health-patrol-env-switch.mjs
+++ b/scripts/deploy/pingora-health-patrol-env-switch.mjs
@@ -2,8 +2,8 @@
 
 import { spawnSync } from 'node:child_process';
 import {
-  chownSync,
   chmodSync,
+  chownSync,
   lstatSync,
   mkdtempSync,
   readFileSync,
diff --git a/scripts/deploy/pingora-tls-cert-sync.mjs b/scripts/deploy/pingora-tls-cert-sync.mjs
index 63533eea7..569de5c00 100644
--- a/scripts/deploy/pingora-tls-cert-sync.mjs
+++ b/scripts/deploy/pingora-tls-cert-sync.mjs
@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { execFileSync, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import {
   accessSync,
@@ -15,9 +16,8 @@ import {
   rmSync,
   statSync,
 } from 'node:fs';
-import { execFileSync, spawnSync } from 'node:child_process';
-import path from 'node:path';
 import { userInfo } from 'node:os';
+import path from 'node:path';
 
 const DEFAULT_SERVICE_USER = 'genarrative';
 const DEFAULT_SERVICE_GROUP = 'genarrative';
diff --git a/scripts/deploy/production-runtime-writer-identity-rotate.mjs b/scripts/deploy/production-runtime-writer-identity-rotate.mjs
index 29ffc2f6d..44489533b 100644
--- a/scripts/deploy/production-runtime-writer-identity-rotate.mjs
+++ b/scripts/deploy/production-runtime-writer-identity-rotate.mjs
@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
+import { spawn } from 'node:child_process';
+
 import {
   callSpacetimeProcedureViaCli,
   ensureProcedureOk,
   validateSpacetimeDatabaseName,
 } from '../spacetime-migration-common.mjs';
-import { spawn } from 'node:child_process';
 
 const PROCEDURE = 'rotate_editor_generation_runtime_service_identity_and_return';
 
diff --git a/scripts/dev-stack-port-utils.mjs b/scripts/dev-stack-port-utils.mjs
index c119ea46e..d4f5cdd0f 100644
--- a/scripts/dev-stack-port-utils.mjs
+++ b/scripts/dev-stack-port-utils.mjs
@@ -8,9 +8,9 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs';
+import {createServer} from 'node:net';
 import {hostname, userInfo} from 'node:os';
 import {dirname, resolve} from 'node:path';
-import {createServer} from 'node:net';
 
 const LINUX_DEV_PORT_RANGE_REGISTRY_ROOT = '/var/tmp/genarrative-dev-port-ranges';
 const LINUX_DEV_PORT_RANGE_POOL_START = 10000;
@@ -308,7 +308,7 @@ function nextLinuxPortRangeCandidate(registry) {
 async function withLinuxPortRangeRegistryLock(lockPath, action) {
   ensureWorldWritableDirectory(dirname(lockPath));
 
-  while (true) {
+  for (;;) {
     try {
       writeFileSync(
         lockPath,
diff --git a/scripts/dev-stack-port-utils.test.ts b/scripts/dev-stack-port-utils.test.ts
index 353b7a100..8f56402f7 100644
--- a/scripts/dev-stack-port-utils.test.ts
+++ b/scripts/dev-stack-port-utils.test.ts
@@ -1,8 +1,10 @@
-import {createServer} from 'node:net';
 import {mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {createServer} from 'node:net';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
+
 import {describe, expect, it} from 'vitest';
+
 import {
   findAvailablePort,
   mapDevPortsToPortRange,
@@ -23,6 +25,27 @@ function reservePort(port) {
   });
 }
 
+async function reserveConsecutivePorts() {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const firstServer = await reservePort(0);
+    const firstPort = firstServer.address().port;
+
+    if (firstPort === 65535) {
+      await new Promise((resolve) => firstServer.close(resolve));
+      continue;
+    }
+
+    try {
+      const secondServer = await reservePort(firstPort + 1);
+      return {firstServer, secondServer, firstPort};
+    } catch {
+      await new Promise((resolve) => firstServer.close(resolve));
+    }
+  }
+
+  throw new Error('无法为测试保留两个连续端口');
+}
+
 describe('dev stack port utils', () => {
   it('解析端口段并映射到四个 dev 端口', () => {
     expect(parsePortRangeSpec('10000-10099')).toEqual({
@@ -39,9 +62,7 @@ describe('dev stack port utils', () => {
   });
 
   it('使用端口可用性检查为被占用端口寻找后续可用端口', async () => {
-    const firstServer = await reservePort(0);
-    const firstPort = firstServer.address().port;
-    const secondServer = await reservePort(firstPort + 1);
+    const {firstServer, secondServer, firstPort} = await reserveConsecutivePorts();
 
     try {
       const availablePort = await findAvailablePort({
diff --git a/scripts/dev.mjs b/scripts/dev.mjs
index e48dec3de..c1004be94 100644
--- a/scripts/dev.mjs
+++ b/scripts/dev.mjs
@@ -924,7 +924,8 @@ function readLinuxApiServerProcessSnapshot(pid) {
     if (
       error?.code === 'ENOENT' ||
       error?.code === 'EACCES' ||
-      error?.code === 'EPERM'
+      error?.code === 'EPERM'  ||
+      error?.code === 'ESRCH'
     ) {
       return null;
     }
diff --git a/scripts/dev.test.ts b/scripts/dev.test.ts
index 988d21bf9..b6ebbac90 100644
--- a/scripts/dev.test.ts
+++ b/scripts/dev.test.ts
@@ -945,6 +945,7 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
   });
 
   test('本地 API identity 不跟随符号链接记录', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const tempDir = mkdtempSync(join(tmpdir(), 'genarrative-api-identity-'));
     try {
       const { explicitOptions, options } = parseArgs(
@@ -988,6 +989,9 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
         identity: 'linked-identity',
         token: 'linked-token',
       });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('本地 API identity 记录不可用，将重新创建'),
+      );
     } finally {
       rmSync(tempDir, { recursive: true, force: true });
     }
@@ -1165,6 +1169,7 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
   });
 
   test('不复用权限宽松、格式非法或空的本地运行服务 bootstrap secret 记录', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const tempDir = mkdtempSync(
       join(tmpdir(), 'genarrative-runtime-bootstrap-secret-'),
     );
@@ -1234,6 +1239,11 @@ spacetimedb tool version 2.6.0; spacetimedb-lib version 2.6.0;
       if (process.platform !== 'win32') {
         expect(statSync(secretPath).mode & 0o777).toBe(0o600);
       }
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          '本地运行服务 bootstrap secret 记录不可用，将重新生成',
+        ),
+      );
     } finally {
       rmSync(tempDir, { recursive: true, force: true });
     }
diff --git a/scripts/export-match3d-resource-pipeline.mjs b/scripts/export-match3d-resource-pipeline.mjs
index 93f7839cb..48b597e52 100644
--- a/scripts/export-match3d-resource-pipeline.mjs
+++ b/scripts/export-match3d-resource-pipeline.mjs
@@ -1,7 +1,7 @@
 import {Buffer} from 'node:buffer';
-import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
-import path from 'node:path';
 import {spawnSync} from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import path from 'node:path';
 
 import {mergeApiServerEnv} from './dev-utils.mjs';
 
diff --git a/scripts/jenkins-server-provision.sh b/scripts/jenkins-server-provision.sh
index 3a49739be..89d1b6cdc 100755
--- a/scripts/jenkins-server-provision.sh
+++ b/scripts/jenkins-server-provision.sh
@@ -10,6 +10,11 @@ GENARRATIVE_OPENSSL_VERSION="${GENARRATIVE_OPENSSL_VERSION:-3.2.0}"
 GENARRATIVE_OPENSSL_PREFIX="${GENARRATIVE_OPENSSL_PREFIX:-/opt/genarrative/openssl-3.2.0}"
 GENARRATIVE_OPENSSL_SOURCE_URL="${GENARRATIVE_OPENSSL_SOURCE_URL:-https://github.com/openssl/openssl/releases/download/openssl-${GENARRATIVE_OPENSSL_VERSION}/openssl-${GENARRATIVE_OPENSSL_VERSION}.tar.gz}"
 GENARRATIVE_OPENSSL_SOURCE_SHA256="${GENARRATIVE_OPENSSL_SOURCE_SHA256:-14c826f07c7e433706fb5c69fa9e25dab95684844b4c962a2cf1bf183eb4690e}"
+DATABASE_BACKUP_PROFILE="${DATABASE_BACKUP_PROFILE:-archive-full}"
+DATABASE_BACKUP_FILES_HISTORY_WORK_DIR="${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR:-/var/lib/genarrative/database-backups/files-history}"
+DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR="/etc/systemd/system/genarrative-database-backup.service.d"
+DATABASE_BACKUP_FILES_HISTORY_DROP_IN="${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}/10-files-history.conf"
+DATABASE_BACKUP_LEGACY_DEV_DROP_IN="${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}/10-dev-files.conf"
 
 require_non_root_relative_path() {
   local label="$1"
@@ -63,6 +68,21 @@ validate_server_names() {
   done
 }
 
+validate_database_backup_profile() {
+  case "${DATABASE_BACKUP_PROFILE}" in
+    archive-full|files-history)
+      ;;
+    *)
+      echo "[server-provision] DATABASE_BACKUP_PROFILE 只能是 archive-full 或 files-history，当前值: ${DATABASE_BACKUP_PROFILE}" >&2
+      exit 1
+      ;;
+  esac
+  if [[ ! "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}" =~ ^/var/lib/genarrative/database-backups/[A-Za-z0-9._/-]+$ || "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}" == *..* ]]; then
+    echo "[server-provision] DATABASE_BACKUP_FILES_HISTORY_WORK_DIR 必须是 /var/lib/genarrative/database-backups/ 下不含连续点号的绝对路径，当前值: ${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}" >&2
+    exit 1
+  fi
+}
+
 run_cmd() {
   echo "+ $*"
   if [[ "${DRY_RUN}" != "true" ]]; then
@@ -917,6 +937,52 @@ render_database_backup_service() {
     deploy/systemd/genarrative-database-backup.service
 }
 
+render_database_backup_files_history_drop_in() {
+  local current_escaped env_escaped work_dir_escaped
+  current_escaped="$(escape_sed_replacement "${CURRENT_LINK}")"
+  env_escaped="$(escape_sed_replacement "${API_ENV_FILE}")"
+  work_dir_escaped="$(escape_sed_replacement "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}")"
+  sed \
+    -e "s|/opt/genarrative/current|${current_escaped}|g" \
+    -e "s|/etc/genarrative/api-server.env|${env_escaped}|g" \
+    -e "s|/var/lib/genarrative/database-backups/files-history|${work_dir_escaped}|g" \
+    deploy/systemd/genarrative-database-backup-files-history.conf
+}
+
+configure_database_backup_profile() {
+  local rendered_drop_in
+
+  if [[ "${DATABASE_BACKUP_PROFILE}" == "archive-full" ]]; then
+    echo "[server-provision] 数据库备份 profile=archive-full，保留主 service 的全量冷备行为。"
+    run_cmd rm -f "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+    return
+  fi
+
+  echo "[server-provision] 数据库备份 profile=files-history，先只读验证 full baseline state。"
+  if [[ "${DRY_RUN}" == "true" ]]; then
+    echo "+ /usr/bin/node -- ${CURRENT_LINK}/scripts/database-backup-to-oss.mjs --env-file ${API_ENV_FILE} --storage-format files --mode history --work-dir ${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR} --dry-run"
+  else
+    if [[ ! -f "${CURRENT_LINK}/scripts/database-backup-to-oss.mjs" ]]; then
+      echo "[server-provision] current release 缺少数据库备份脚本: ${CURRENT_LINK}/scripts/database-backup-to-oss.mjs" >&2
+      exit 1
+    fi
+    /usr/bin/node -- "${CURRENT_LINK}/scripts/database-backup-to-oss.mjs" \
+      --env-file "${API_ENV_FILE}" \
+      --storage-format files \
+      --mode history \
+      --work-dir "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}" \
+      --dry-run
+  fi
+
+  run_cmd install -d -o genarrative -g genarrative -m 0750 "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}"
+  run_cmd install -d -o root -g root -m 0755 "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}"
+  run_cmd rm -f "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+  rendered_drop_in="$(mktemp)"
+  render_database_backup_files_history_drop_in >"${rendered_drop_in}"
+  install_file "${rendered_drop_in}" "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" 0644
+  rm -f "${rendered_drop_in}"
+}
+
 render_health_patrol_service() {
   local current_escaped
   current_escaped="$(escape_sed_replacement "${CURRENT_LINK}")"
@@ -930,6 +996,7 @@ require_path deploy/systemd/genarrative-api.service
 require_path deploy/systemd/genarrative-external-generation-worker@.service
 require_path deploy/systemd/genarrative-external-generation-controller.service
 require_path deploy/systemd/genarrative-database-backup.service
+require_path deploy/systemd/genarrative-database-backup-files-history.conf
 require_path deploy/systemd/genarrative-database-backup.timer
 require_path deploy/systemd/genarrative-health-patrol.service
 require_path deploy/systemd/genarrative-health-patrol.timer
@@ -951,9 +1018,10 @@ require_path scripts/deploy/maintenance-off.sh
 require_path scripts/deploy/maintenance-status.sh
 
 validate_server_names
+validate_database_backup_profile
 require_non_root_relative_path "PROVISION_TOOLS_DIR" "${PROVISION_TOOLS_DIR}"
 
-echo "[server-provision] target=${DEPLOY_TARGET}, dry_run=${DRY_RUN}, nginx_config_mode=${NGINX_CONFIG_MODE}, source_commit=$(cat .jenkins-source-commit)"
+echo "[server-provision] target=${DEPLOY_TARGET}, dry_run=${DRY_RUN}, nginx_config_mode=${NGINX_CONFIG_MODE}, database_backup_profile=${DATABASE_BACKUP_PROFILE}, source_commit=$(cat .jenkins-source-commit)"
 
 run_cmd id
 require_root_for_real_provision
@@ -1033,6 +1101,7 @@ else
   echo "[server-provision] 已存在环境文件，保留不覆盖: ${API_ENV_FILE}"
 fi
 ensure_api_runtime_env_defaults
+configure_database_backup_profile
 
 if [[ ! -f "${WORKER_ENV_FILE}" ]]; then
   echo "+ create ${WORKER_ENV_FILE} from example"
diff --git a/scripts/ops/production-health-patrol.mjs b/scripts/ops/production-health-patrol.mjs
index 60eab89f9..14b2dd2b3 100644
--- a/scripts/ops/production-health-patrol.mjs
+++ b/scripts/ops/production-health-patrol.mjs
@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
 import http from 'node:http';
 import https from 'node:https';
-import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
 const STATUS_RANK = {
diff --git a/scripts/prepare-server-provision-tools.sh b/scripts/prepare-server-provision-tools.sh
index a1bc2ee70..8a8ff3a9b 100755
--- a/scripts/prepare-server-provision-tools.sh
+++ b/scripts/prepare-server-provision-tools.sh
@@ -9,7 +9,7 @@ OTELCOL_DOWNLOAD_ROOT="${OTELCOL_DOWNLOAD_ROOT:-https://github.com/open-telemetr
 OTELCOL_ARCHIVE_PATH="${OTELCOL_ARCHIVE_PATH:-}"
 OTELCOL_TARGET_BIN="${OTELCOL_TARGET_BIN:-/usr/local/bin/otelcol-contrib}"
 SPACETIME_INSTALLER_URL="${SPACETIME_INSTALLER_URL:-https://install.spacetimedb.com}"
-SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.0}"
+SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.6.1}"
 SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}"
 SPACETIME_ROOT="${SPACETIME_ROOT:-/stdb}"
 SPACETIME_EXPECTED_VERSION="${SPACETIME_EXPECTED_VERSION:-}"
diff --git a/scripts/rebind-orphan-work-owners.test.ts b/scripts/rebind-orphan-work-owners.test.ts
index b57335860..736279d3c 100644
--- a/scripts/rebind-orphan-work-owners.test.ts
+++ b/scripts/rebind-orphan-work-owners.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+
 import { rebindOrphanWorkOwnersInMigration } from './rebind-orphan-work-owners.mjs';
 
 const placeholderUserId = 'wx-openid-placeholder';
diff --git a/scripts/repair-auth-public-user-codes.test.ts b/scripts/repair-auth-public-user-codes.test.ts
index 6273e77d6..b9414ee8d 100644
--- a/scripts/repair-auth-public-user-codes.test.ts
+++ b/scripts/repair-auth-public-user-codes.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+
 import { repairAuthPublicUserCodesInMigration } from './repair-auth-public-user-codes.mjs';
 
 function table(name: string, rows: unknown[]) {
diff --git a/scripts/run-bash-script.mjs b/scripts/run-bash-script.mjs
index a18812145..6aec0ea5b 100644
--- a/scripts/run-bash-script.mjs
+++ b/scripts/run-bash-script.mjs
@@ -1,5 +1,5 @@
-import {existsSync} from 'node:fs';
 import {spawn} from 'node:child_process';
+import {existsSync} from 'node:fs';
 
 const [, , scriptPath, ...scriptArgs] = process.argv;
 
diff --git a/scripts/smoke-content.ts b/scripts/smoke-content.ts
index 0929a65da..ae1dd814d 100644
--- a/scripts/smoke-content.ts
+++ b/scripts/smoke-content.ts
@@ -1,4 +1,4 @@
-import { buildCompanionState, ROLE_TEMPLATE_CHARACTERS, resolveEncounterRecruitCharacter } from '../src/data/characterPresets.ts';
+import { buildCompanionState, resolveEncounterRecruitCharacter,ROLE_TEMPLATE_CHARACTERS } from '../src/data/characterPresets.ts';
 import { activateRosterCompanion, benchActiveCompanion, recruitCompanionToParty } from '../src/data/companionRoster.ts';
 import { getInventoryItemValue, getNpcPurchasePrice } from '../src/data/economy.ts';
 import {
diff --git a/scripts/spacetime-export-migration-json.mjs b/scripts/spacetime-export-migration-json.mjs
index 4837e115b..94a5912c5 100644
--- a/scripts/spacetime-export-migration-json.mjs
+++ b/scripts/spacetime-export-migration-json.mjs
@@ -2,6 +2,7 @@
 
 import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
+
 import {
   callSpacetimeProcedure,
   callSpacetimeProcedureViaCli,
diff --git a/scripts/spacetime-import-migration-json.mjs b/scripts/spacetime-import-migration-json.mjs
index 8b46fa16e..aa9d14653 100644
--- a/scripts/spacetime-import-migration-json.mjs
+++ b/scripts/spacetime-import-migration-json.mjs
@@ -3,6 +3,7 @@
 import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+
 import {
   assertReadableFile,
   callSpacetimeProcedure,
diff --git a/scripts/spacetime-logs-local.sh b/scripts/spacetime-logs-local.sh
index 9502ba0a4..0ca7f8592 100644
--- a/scripts/spacetime-logs-local.sh
+++ b/scripts/spacetime-logs-local.sh
@@ -13,7 +13,7 @@ usage() {
   1. 从本地 SpacetimeDB 通过 spacetime logs 提取模块日志到本地文件。
   2. 默认读取 spacetime.local.json 的 database 字段，默认 server 为 http://127.0.0.1:3101。
   3. 默认输出到 logs/spacetime/<database>-<timestamp>.log；--follow 会持续追加并同步写到终端。
-  4. 默认使用 server-rs/.spacetimedb/local 作为 spacetime CLI root，保持本地身份与 standalone 一致。
+  4. 始终显式传入 server URL，不读取或改写 spacetime CLI 的个人 root 配置。
 EOF
 }
 
@@ -52,7 +52,6 @@ REPO_ROOT="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
 
 DATABASE=""
 SPACETIME_SERVER="http://127.0.0.1:3101"
-SPACETIME_ROOT_DIR="${REPO_ROOT}/server-rs/.spacetimedb/local"
 LINES="200"
 OUTPUT=""
 FOLLOW=0
@@ -71,10 +70,6 @@ while [[ $# -gt 0 ]]; do
       SPACETIME_SERVER="${2:?缺少 --server 的值}"
       shift 2
       ;;
-    --spacetime-root-dir)
-      SPACETIME_ROOT_DIR="${2:?缺少 --spacetime-root-dir 的值}"
-      shift 2
-      ;;
     --lines|-n)
       LINES="${2:?缺少 --lines 的值}"
       shift 2
@@ -123,7 +118,6 @@ fi
 
 echo "[stdb:logs] database: ${DATABASE}"
 echo "[stdb:logs] server: ${SPACETIME_SERVER}"
-echo "[stdb:logs] spacetime root: ${SPACETIME_ROOT_DIR}"
 echo "[stdb:logs] output: ${OUTPUT}"
 
-spacetime --root-dir="${SPACETIME_ROOT_DIR}" "${ARGS[@]}" | tee -a "${OUTPUT}"
+spacetime "${ARGS[@]}" | tee -a "${OUTPUT}"
diff --git a/scripts/spacetime-migration-common.test.ts b/scripts/spacetime-migration-common.test.ts
index 02219e50b..1e14f7c6f 100644
--- a/scripts/spacetime-migration-common.test.ts
+++ b/scripts/spacetime-migration-common.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+
 import {
   buildSpacetimeCallArgs,
   encodeSpacetimeCliOption,
diff --git a/scripts/test-ve-llm.mjs b/scripts/test-ve-llm.mjs
index d2e65f06a..a9f2b848e 100644
--- a/scripts/test-ve-llm.mjs
+++ b/scripts/test-ve-llm.mjs
@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { dirname,resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -52,7 +52,9 @@ async function test(name, method, path, body = null) {
     const elapsed = Date.now() - start;
     const text = await resp.text();
     let json = null;
-    try { json = JSON.parse(text); } catch {}
+    try { json = JSON.parse(text); } catch {
+      // 非 JSON 上游错误由下方原始文本分支处理。
+    }
 
     if (resp.ok) {
       const model = json?.model || json?.data?.[0]?.id || '?';
diff --git a/server-rs/Cargo.lock b/server-rs/Cargo.lock
index 275dee293..8b586614c 100644
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -238,6 +238,7 @@ dependencies = [
  "platform-agent",
  "platform-audio",
  "platform-auth",
+ "platform-editor-agent",
  "platform-hyper3d",
  "platform-image",
  "platform-llm",
@@ -4457,6 +4458,19 @@ dependencies = [
  "urlencoding",
 ]
 
+[[package]]
+name = "platform-editor-agent"
+version = "0.1.0"
+dependencies = [
+ "hmac",
+ "platform-agent",
+ "platform-llm",
+ "serde",
+ "serde_json",
+ "sha2",
+ "shared-contracts",
+]
+
 [[package]]
 name = "platform-hyper3d"
 version = "0.1.0"
@@ -4497,18 +4511,15 @@ dependencies = [
 name = "platform-matting"
 version = "0.1.0"
 dependencies = [
- "base64 0.22.1",
  "dotenvy",
  "hex",
  "hmac",
- "httpdate",
  "image",
  "platform-oss",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
  "serde_urlencoded",
- "sha1",
  "sha2",
  "time",
  "tokio",
@@ -5893,9 +5904,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8037ee5a6fa7348bf0392c728e4de4a0ba6f89c967eff80b666ac3e1e8f2b612"
+checksum = "b6eff5017248ff2e35e03564df947fdf3e963f7198be6ae1d9e894c2efb2ea15"
 dependencies = [
  "anyhow",
  "bytemuck",
@@ -5916,9 +5927,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-bindings-macro"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "202fb591c7d18fbbd4aec24a34ad6f03e3accc41580aee0fd2f9ad0514681917"
+checksum = "fce86c7657dcb42a33ce55f0100f98964dc15b64e79f06803a478676b74d6c82"
 dependencies = [
  "heck 0.4.1",
  "humantime",
@@ -5930,18 +5941,18 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-bindings-sys"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "60869317019bbc8fa571e5c8ff21fe72abf9e5bcb579531efdded4e93a76e827"
+checksum = "dbe5f9d71d59bdb93d81a7a61eee75ac2f1f88f91e139a7e263261f9dbf316de"
 dependencies = [
  "spacetimedb-primitives",
 ]
 
 [[package]]
 name = "spacetimedb-client-api-messages"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ad481e05f959aa646e36e3e2e8b7581da58ca8f8a1b5e643122fc2bd4a4ff0df"
+checksum = "1642404553853b56e521a12aa9849807d8e003433934c73eeebbc8671f1254f8"
 dependencies = [
  "bytes",
  "bytestring",
@@ -5961,9 +5972,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-data-structures"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ec3aa387bfa45691c11b57e9072522dde3bbb554f7e017b57025b591556dbfb"
+checksum = "3407c90a3da48b1c421bbad6a2ee6de3855a77d73fae98773bcc058426f1318f"
 dependencies = [
  "ahash",
  "crossbeam-queue",
@@ -5976,9 +5987,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-lib"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7d05a4bef4619afe949f7eac9c3a31f06f21c5139c89920a8f4c7dd7b09c24a8"
+checksum = "bceaf72bdbf1a624d55d17ebaa38f8cf78a4972e43641c6cbf94f82318b5581d"
 dependencies = [
  "anyhow",
  "bitflags 2.13.0",
@@ -6001,9 +6012,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-memory-usage"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "064ae4130ddc47e1b87b59252d041cf929ffbdc53686af80dff290f819e523ef"
+checksum = "6cc1e19f664b47f4b3b82fb69b2fc096c3d82dc659ea705d62bbbec2fa9c2e83"
 dependencies = [
  "decorum",
  "ethnum",
@@ -6011,9 +6022,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-metrics"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "65b36210b2cdde2784e22e7182717bf1ab06a431f54bf9662e38bd1bcb8681c5"
+checksum = "0c794455ed96245d52d837c8bbc3493d1c17d9f6382e6c5fee1c88926c9aa04a"
 dependencies = [
  "arrayvec",
  "itertools 0.12.1",
@@ -6023,9 +6034,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-primitives"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9c1e4745d32aacb71d29050f1ff6fa24fa149d939b8787f90ec28d2cac3c107b"
+checksum = "b7525fda46b21fffdc62805099dee853a79000e0673ff6df4b8355cb0b8dabe8"
 dependencies = [
  "bitflags 2.13.0",
  "either",
@@ -6037,18 +6048,18 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-query-builder"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "79849bd28750b3351d54f3df4b37c5454cae3c62d0184bc9855650048a80c032"
+checksum = "1f283c4797961d9a94f623ee4c66e6a94d30861b6380a49a27ac2d9568e17125"
 dependencies = [
  "spacetimedb-lib",
 ]
 
 [[package]]
 name = "spacetimedb-sats"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ca3327e8cd735f347ef5ff08a61b9806418acdcc0394ddd35a212c0849e4295"
+checksum = "6cefb87b7d5e760d43cb65855591e25af772bdcca19562e5796ae797240d1998"
 dependencies = [
  "anyhow",
  "arrayvec",
@@ -6079,9 +6090,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-schema"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cb81b65cfa1da17f5f032f9566086670fb68a27f14f194a4dad76a21cc79f490"
+checksum = "775cfdeb406e5628bf78b2221b0e0fd2fcba583f691bb89ba1c9338790ecaf7d"
 dependencies = [
  "anyhow",
  "convert_case 0.6.0",
@@ -6110,9 +6121,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-sdk"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ceb50bcefcb70ae517c672a7ac21cbaf7affd44f0d9991968869eff566d83ba5"
+checksum = "074a6d8828638176eb8e9bba7a3e6fb75dc659b260717306eb966c7e10575cd7"
 dependencies = [
  "anymap3",
  "base64 0.21.7",
@@ -6142,9 +6153,9 @@ dependencies = [
 
 [[package]]
 name = "spacetimedb-sql-parser"
-version = "2.6.0"
+version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86cbda18ee77e497b698b22377750228b1e88ead4dcb79fc3fddb78cccab0a77"
+checksum = "3b978b6d76cfbe5782a7f0dae7e25f6be4e7e13cfad26c9211d4eb4cdf8c22da"
 dependencies = [
  "derive_more",
  "spacetimedb-lib",
diff --git a/server-rs/Cargo.toml b/server-rs/Cargo.toml
index 3d3bc1151..61d585844 100644
--- a/server-rs/Cargo.toml
+++ b/server-rs/Cargo.toml
@@ -42,6 +42,7 @@ members = [
     "crates/platform-wechat",
     "crates/platform-speech",
     "crates/platform-agent",
+    "crates/platform-editor-agent",
     "crates/pingora-gateway",
     "crates/server-manager-panel",
     "crates/shared-contracts",
@@ -84,6 +85,7 @@ module-square-hole = { path = "crates/module-square-hole", default-features = fa
 module-story = { path = "crates/module-story", default-features = false }
 module-visual-novel = { path = "crates/module-visual-novel", default-features = false }
 platform-agent = { path = "crates/platform-agent", default-features = false }
+platform-editor-agent = { path = "crates/platform-editor-agent", default-features = false }
 platform-auth = { path = "crates/platform-auth", default-features = false }
 platform-audio = { path = "crates/platform-audio", default-features = false }
 platform-hyper3d = { path = "crates/platform-hyper3d", default-features = false }
@@ -133,9 +135,9 @@ serde_urlencoded = "0.7"
 sha1 = "0.10"
 sha2 = "0.10"
 socket2 = "0.6"
-spacetimedb = "=2.6.0"
-spacetimedb-sdk = "=2.6.0"
-spacetimedb-lib = { version = "=2.6.0", default-features = false }
+spacetimedb = "=2.6.1"
+spacetimedb-sdk = "=2.6.1"
+spacetimedb-lib = { version = "=2.6.1", default-features = false }
 time = "0.3"
 tokio = "1"
 tokio-stream = "0.1"
diff --git a/server-rs/README.md b/server-rs/README.md
index 661f13bb4..02f8a1cb1 100644
--- a/server-rs/README.md
+++ b/server-rs/README.md
@@ -30,10 +30,10 @@ cargo test -p api-server --manifest-path server-rs/Cargo.toml
 npm run check:server-rs-ddd
 npm run check:spacetime-schema
 npm run spacetime:generate
-npm run api-server
+npm run dev:api-server
 ```
 
-涉及 API smoke 时用 `npm run api-server` 启动后端并检查 `/healthz`，不要使用旧 `api-server:maincloud`。
+涉及 API smoke 时用 `npm run dev:api-server` 启动后端并检查 `/healthz`，不要使用旧 `api-server:maincloud`。
 
 ## 当前文档
 
diff --git a/server-rs/crates/api-server/Cargo.toml b/server-rs/crates/api-server/Cargo.toml
index 8949fdca5..29a238b70 100644
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -38,6 +38,7 @@ module-square-hole = { workspace = true }
 module-story = { workspace = true }
 module-visual-novel = { workspace = true }
 platform-agent = { workspace = true }
+platform-editor-agent = { workspace = true }
 platform-audio = { workspace = true }
 platform-auth = { workspace = true }
 platform-hyper3d = { workspace = true }
diff --git a/server-rs/crates/api-server/README.md b/server-rs/crates/api-server/README.md
index 2a1bba8c9..42f3336e4 100644
--- a/server-rs/crates/api-server/README.md
+++ b/server-rs/crates/api-server/README.md
@@ -99,7 +99,7 @@
 1. 进程启动时通过 `shared-logging` 统一初始化 `tracing subscriber`。
 2. 默认日志过滤器来自 `GENARRATIVE_API_LOG`，未提供时回落到 `info,tower_http=info`。
 3. HTTP 访问日志统一通过 Axum 路由层的 `TraceLayer` 输出，后续 `request_id`、响应头与错误中间件继续在同一层扩展。
-4. 本地启动器 `npm run api-server` 和完整联调入口 `npm run dev` / `npm run dev:rust` 会在保留终端实时输出的同时，把同一份 `cargo` / `api-server` 输出持久化到 `logs/api-server/`。如需固定文件或目录，可设置 `GENARRATIVE_API_SERVER_LOG_FILE` 或 `GENARRATIVE_API_SERVER_LOG_DIR`。
+4. 本地启动器 `npm run dev:api-server` 和完整联调入口 `npm run dev` 会在保留终端实时输出的同时，把同一份 `cargo` / `api-server` 输出持久化到 `logs/api-server/`。如需固定文件或目录，可设置 `GENARRATIVE_API_SERVER_LOG_FILE` 或 `GENARRATIVE_API_SERVER_LOG_DIR`。
 
 当前 request context 约定：
 
diff --git a/server-rs/crates/api-server/src/aliyun_matting.rs b/server-rs/crates/api-server/src/aliyun_matting.rs
index 60f5a9921..e961513e6 100644
--- a/server-rs/crates/api-server/src/aliyun_matting.rs
+++ b/server-rs/crates/api-server/src/aliyun_matting.rs
@@ -1,21 +1,20 @@
 //! 阿里云通用抠图在 api-server 侧的适配层。
 //!
-//! 输入 URL 策略：抠图服务只认上海地域 OSS URL，而我们没有上海地域自有 OSS，
-//! 统一由 platform-matting 上传 VIAPI 官方临时桶（1 天自动过期，无需清理）。
+//! 输入统一由 platform-matting 通过 AuthorizeFileUpload 单对象 Policy 上传动态临时 OSS。
 
 use axum::http::StatusCode;
 use platform_matting::MattingError;
-use serde_json::json;
+use serde_json::{Value, json};
 
 use crate::{
     http_error::AppError, openai_image_generation::DownloadedOpenAiImage, state::AppState,
 };
 
-/// 图片字节 → 阿里云通用抠图 → 原尺寸透明 PNG。
-/// 未配置抠图客户端时返回错误，由调用方决定是否降级本地算法。
-pub(crate) async fn segment_image_with_aliyun_matting(
+/// 私有 OSS 签名 URL → 延迟下载 → 阿里云临时桶 → 原尺寸透明 PNG。
+/// 下载和临时上传由 platform-matting 收口，源图缓冲不会跨越整次阿里云推理常驻。
+pub(crate) async fn segment_image_url_with_aliyun_matting(
     state: &AppState,
-    image: &DownloadedOpenAiImage,
+    image_url: &str,
     log_label: &str,
 ) -> Result<DownloadedOpenAiImage, AppError> {
     let matting_client = state
@@ -25,7 +24,7 @@ pub(crate) async fn segment_image_with_aliyun_matting(
     let file_name = format!("{log_label}.png");
     let started_at = std::time::Instant::now();
     let output_bytes = matting_client
-        .segment_image_to_transparent_png(image.bytes.as_slice(), &file_name)
+        .segment_image_url_to_transparent_png(image_url, &file_name)
         .await
         .map_err(|error| {
             aliyun_matting_failure_to_app_error(&error, started_at.elapsed().as_millis() as u64)
@@ -34,7 +33,7 @@ pub(crate) async fn segment_image_with_aliyun_matting(
         provider = "aliyun-matting",
         log_label,
         elapsed_ms = started_at.elapsed().as_millis() as u64,
-        "阿里云通用抠图完成"
+        "阿里云通用抠图 URL 输入完成"
     );
 
     Ok(DownloadedOpenAiImage {
@@ -48,18 +47,36 @@ pub(crate) async fn segment_image_with_aliyun_matting(
 ///
 /// 分类（是否外部调用、超时、传输层故障、上游 HTTP 状态）由 platform-matting 在错误发生处
 /// 结构化捕获，这里只做协议中立的读取，不再从中文 message 反推——外部供应商协议归属留在
-/// platform-* 层。`InvalidConfig` / `InvalidRequest` / `Sign` 是发请求前的本地预检失败，
-/// `external_call_attempted()` 为 false，据此跳过外部失败审计。
+/// platform-* 层。`InvalidConfig` / `InvalidRequest` / `Sign` 是尚未开始外部调用的本地预检失败；
+/// URL 链路在 OSS GET 成功后发生的解码、尺寸或其它本地处理失败由 `LocalProcessing` 表示，
+/// 仍然需要进入外部失败审计，但不得包装成可重试的上游 5xx。
 fn aliyun_matting_failure_to_app_error(error: &MattingError, latency_ms: u64) -> AppError {
     let message = error.message();
     if !error.external_call_attempted() {
-        // 本地预检失败（未配置 / 图片解码失败 / 尺寸过小 / 签名构造失败），未触达阿里云。
+        // 本地预检失败（未配置 / 尚未下载源图前的参数或签名错误），未触达外部调用链路。
         return AppError::from_status(StatusCode::UNPROCESSABLE_ENTITY).with_details(json!({
             "provider": "aliyun-matting",
             "message": message,
             "timeout": false,
             "transport": false,
+            "localProcessing": false,
             "externalCallAttempted": false,
+            "failureStage": error.failure_stage(),
+            "latencyMs": latency_ms,
+            "rawExcerpt": message.chars().take(500).collect::<String>(),
+        }));
+    }
+    // 外部调用已开始，但失败在本地解码 / 校验 / 归一等阶段：要审计，不能标成上游 5xx / 可重试。
+    if matches!(error, MattingError::LocalProcessing(_)) {
+        return AppError::from_status(StatusCode::UNPROCESSABLE_ENTITY).with_details(json!({
+            "provider": "aliyun-matting",
+            "message": message,
+            "timeout": false,
+            "transport": false,
+            "localProcessing": true,
+            "upstreamStatus": Value::Null,
+            "externalCallAttempted": true,
+            "failureStage": error.failure_stage(),
             "latencyMs": latency_ms,
             "rawExcerpt": message.chars().take(500).collect::<String>(),
         }));
@@ -75,7 +92,10 @@ fn aliyun_matting_failure_to_app_error(error: &MattingError, latency_ms: u64) ->
         "message": message,
         "timeout": timeout,
         "transport": error.is_transport(),
+        "localProcessing": false,
         "upstreamStatus": error.upstream_status(),
+        "externalCallAttempted": true,
+        "failureStage": error.failure_stage(),
         "latencyMs": latency_ms,
         "rawExcerpt": message.chars().take(500).collect::<String>(),
     }))
@@ -86,6 +106,7 @@ fn aliyun_matting_unconfigured_error() -> AppError {
         "provider": "aliyun-matting",
         "message": "阿里云抠图客户端未配置或未启用。",
         "externalCallAttempted": false,
+        "failureStage": "preflight",
     }))
 }
 
@@ -100,6 +121,21 @@ mod tests {
         assert!(!crate::external_api_audit::matting_failure_external_call_attempted(&error));
     }
 
+    #[test]
+    fn url_input_path_delegates_download_and_temp_upload_to_platform_matting() {
+        let source = include_str!("aliyun_matting.rs");
+        let start = source
+            .find("pub(crate) async fn segment_image_url_with_aliyun_matting")
+            .expect("URL input adapter should exist");
+        let tail = &source[start..];
+        let end = tail
+            .find("/// 把 platform-matting 的错误映射")
+            .expect("URL input adapter should end before error mapper");
+        let body = &tail[..end];
+
+        assert!(body.contains("segment_image_url_to_transparent_png"));
+    }
+
     #[test]
     fn local_preflight_failures_do_not_count_as_external_call() {
         for error in [
@@ -108,7 +144,7 @@ mod tests {
             ),
             MattingError::InvalidRequest("解析待抠图图片失败：invalid png".to_string()),
             MattingError::InvalidConfig("endpoint 为空".to_string()),
-            MattingError::Sign("初始化 OSS V1 签名器失败".to_string()),
+            MattingError::Sign("构造 AuthorizeFileUpload 签名失败".to_string()),
         ] {
             let mapped = aliyun_matting_failure_to_app_error(&error, 3);
 
@@ -129,6 +165,79 @@ mod tests {
         }
     }
 
+    #[test]
+    fn local_processing_after_source_download_is_audited_with_failure_stage() {
+        for (error, expected_stage) in [
+            (
+                MattingError::InvalidRequest("解析待抠图图片失败：invalid png".to_string())
+                    .with_failure_stage("source_decode"),
+                "source_decode",
+            ),
+            (
+                MattingError::InvalidRequest("待抠图图片尺寸 16x16 过小".to_string())
+                    .with_failure_stage("source_validate"),
+                "source_validate",
+            ),
+        ] {
+            let mapped = aliyun_matting_failure_to_app_error(&error, 3);
+
+            assert!(crate::external_api_audit::matting_failure_external_call_attempted(&mapped));
+            // 本地处理失败要审计，但 HTTP 包装不得落成可重试 5xx。
+            assert_eq!(mapped.status_code(), StatusCode::UNPROCESSABLE_ENTITY);
+            let details = mapped.details().expect("details present");
+            assert_eq!(
+                details
+                    .get("externalCallAttempted")
+                    .and_then(|v| v.as_bool()),
+                Some(true)
+            );
+            assert_eq!(
+                details.get("localProcessing").and_then(|v| v.as_bool()),
+                Some(true)
+            );
+            assert_eq!(
+                details.get("transport").and_then(|v| v.as_bool()),
+                Some(false)
+            );
+            assert!(
+                details
+                    .get("upstreamStatus")
+                    .is_none_or(|value| value.is_null())
+            );
+            assert_eq!(
+                details.get("failureStage").and_then(|v| v.as_str()),
+                Some(expected_stage)
+            );
+            assert_eq!(
+                crate::external_api_audit::matting_failure_audit_failure_stage(
+                    &mapped,
+                    "aliyun_segment",
+                ),
+                expected_stage
+            );
+            assert_eq!(
+                crate::external_api_audit::matting_failure_audit_status_code(&mapped),
+                None,
+                "本地处理失败没有上游 HTTP 状态，不能回退包装码"
+            );
+            let draft = crate::external_api_audit::build_matting_external_api_failure_draft(
+                "aliyun-matting",
+                "imageseg.example".to_string(),
+                "editor-screen-background-removal",
+                expected_stage,
+                crate::external_api_audit::matting_failure_audit_status_code(&mapped),
+                crate::external_api_audit::matting_failure_audit_timeout(&mapped),
+                crate::external_api_audit::matting_failure_audit_is_transport(&mapped),
+                crate::external_api_audit::matting_failure_audit_latency_ms(&mapped),
+                mapped.message().to_string(),
+                crate::external_api_audit::matting_failure_audit_raw_excerpt(&mapped),
+                &crate::external_api_audit::ExternalApiAuditContext::default(),
+            );
+            assert_eq!(draft.status_class, Some("local"));
+            assert!(!draft.retryable);
+        }
+    }
+
     #[test]
     fn upstream_transport_failure_maps_to_retryable_transport() {
         let error = MattingError::upstream_transport_error(
diff --git a/server-rs/crates/api-server/src/app.rs b/server-rs/crates/api-server/src/app.rs
index 976c67481..a148df426 100644
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -1725,19 +1725,18 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn editor_character_animation_accepts_character_image_body_above_default_limit() {
+    async fn editor_character_animation_rejects_inline_data_url_before_queueing() {
         let state = AppState::new(AppConfig {
-            external_generation_mode: ExternalGenerationMode::Inline,
+            external_generation_mode: ExternalGenerationMode::Queue,
             ..AppConfig::default()
         })
         .expect("state should build");
         let seed_user = seed_phone_user_with_password(&state, "13800138190", TEST_PASSWORD).await;
         let token = sign_test_user_token(&state, &seed_user, "sess_editor_character_body");
         let app = build_router(state);
-        let source_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
         let request_body = serde_json::json!({
             "sourceLayerId": "layer-character-large",
-            "sourceImageSrc": source_image_src,
+            "sourceImageSrc": "data:image/png;base64,AAAA",
             "sourceWidth": 1024,
             "sourceHeight": 1024,
             "promptText": "待机呼吸循环。",
@@ -1748,7 +1747,6 @@ mod tests {
             "model": "seedance2.0-fast"
         })
         .to_string();
-        assert!(request_body.len() > 2 * 1024 * 1024);
 
         let response = app
             .oneshot(
@@ -1763,7 +1761,7 @@ mod tests {
             .await
             .expect("request should succeed");
 
-        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
         let body = response
             .into_body()
             .collect()
@@ -1772,10 +1770,9 @@ mod tests {
             .to_bytes();
         let body_text = String::from_utf8_lossy(&body);
         assert!(
-            body_text.contains("ARK_CHARACTER_VIDEO_BASE_URL"),
-            "handler should parse the oversized character source image before checking Ark config: {body_text}"
+            body_text.contains("先上传 OSS"),
+            "handler should reject inline character sources: {body_text}"
         );
-        assert!(!body_text.contains("length limit exceeded"));
     }
 
     #[tokio::test]
@@ -1811,23 +1808,21 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn editor_ui_design_asset_extraction_accepts_image_body_above_default_limit() {
+    async fn editor_ui_design_asset_extraction_rejects_inline_data_url_before_queueing() {
         let state = AppState::new(AppConfig {
-            external_generation_mode: ExternalGenerationMode::Inline,
+            external_generation_mode: ExternalGenerationMode::Queue,
             ..AppConfig::default()
         })
         .expect("state should build");
         let seed_user = seed_phone_user_with_password(&state, "13800138188", TEST_PASSWORD).await;
         let token = sign_test_user_token(&state, &seed_user, "sess_editor_ui_extract_body");
         let app = build_router(state);
-        let source_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
         let request_body = serde_json::json!({
-            "sourceImageSrc": source_image_src,
+            "sourceImageSrc": "data:image/png;base64,AAAA",
             "aspectRatio": "1:1",
             "imageSize": "1K",
         })
         .to_string();
-        assert!(request_body.len() > 2 * 1024 * 1024);
 
         let response = app
             .oneshot(
@@ -1842,7 +1837,7 @@ mod tests {
             .await
             .expect("request should succeed");
 
-        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
         let body = response
             .into_body()
             .collect()
@@ -1851,33 +1846,28 @@ mod tests {
             .to_bytes();
         let body_text = String::from_utf8_lossy(&body);
         assert!(
-            body_text.contains("VECTOR_ENGINE")
-                || body_text.contains("OPENAI")
-                || body_text.contains("配置"),
-            "handler should parse the oversized UI design image before checking image config: {body_text}"
+            body_text.contains("先上传 OSS"),
+            "handler should reject inline UI design sources: {body_text}"
         );
-        assert!(!body_text.contains("length limit exceeded"));
     }
 
     #[tokio::test]
-    async fn editor_image_generation_accepts_reference_body_above_default_limit() {
+    async fn editor_image_generation_rejects_inline_data_url_before_queueing() {
         let state = AppState::new(AppConfig {
-            external_generation_mode: ExternalGenerationMode::Inline,
+            external_generation_mode: ExternalGenerationMode::Queue,
             ..AppConfig::default()
         })
         .expect("state should build");
         let seed_user = seed_phone_user_with_password(&state, "13800138028", TEST_PASSWORD).await;
         let token = sign_test_user_token(&state, &seed_user, "sess_editor_image_reference_body");
         let app = build_router(state);
-        let reference_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
         let request_body = serde_json::json!({
             "prompt": "生成宣发素材",
             "kind": "publication-material",
             "size": "720x540",
-            "referenceImageSrcs": [reference_image_src],
+            "referenceImageSrcs": ["data:image/png;base64,AAAA"],
         })
         .to_string();
-        assert!(request_body.len() > 2 * 1024 * 1024);
 
         let response = app
             .oneshot(
@@ -1892,7 +1882,7 @@ mod tests {
             .await
             .expect("request should succeed");
 
-        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
         let body = response
             .into_body()
             .collect()
@@ -1901,31 +1891,28 @@ mod tests {
             .to_bytes();
         let body_text = String::from_utf8_lossy(&body);
         assert!(
-            body_text.contains("VECTOR_ENGINE_BASE_URL"),
-            "handler should parse the oversized editor reference before checking VectorEngine config: {body_text}"
+            body_text.contains("先上传 OSS"),
+            "handler should reject inline editor references: {body_text}"
         );
-        assert!(!body_text.contains("length limit exceeded"));
     }
 
     #[tokio::test]
-    async fn editor_image_edit_accepts_reference_body_above_default_limit() {
+    async fn editor_image_edit_rejects_inline_data_url_before_queueing() {
         let state = AppState::new(AppConfig {
-            external_generation_mode: ExternalGenerationMode::Inline,
+            external_generation_mode: ExternalGenerationMode::Queue,
             ..AppConfig::default()
         })
         .expect("state should build");
         let seed_user = seed_phone_user_with_password(&state, "13800138029", TEST_PASSWORD).await;
         let token = sign_test_user_token(&state, &seed_user, "sess_editor_image_edit_body");
         let app = build_router(state);
-        let source_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
         let request_body = serde_json::json!({
             "prompt": "快速编辑图片",
-            "sourceImageSrc": source_image_src,
+            "sourceImageSrc": "data:image/png;base64,AAAA",
             "size": "1024x1024",
             "model": "gpt-image-2"
         })
         .to_string();
-        assert!(request_body.len() > 2 * 1024 * 1024);
 
         let response = app
             .oneshot(
@@ -1940,7 +1927,7 @@ mod tests {
             .await
             .expect("request should succeed");
 
-        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
         let body = response
             .into_body()
             .collect()
@@ -1949,10 +1936,9 @@ mod tests {
             .to_bytes();
         let body_text = String::from_utf8_lossy(&body);
         assert!(
-            body_text.contains("VECTOR_ENGINE_BASE_URL"),
-            "handler should parse the oversized editor edit image before checking VectorEngine config: {body_text}"
+            body_text.contains("先上传 OSS"),
+            "handler should reject inline editor edit sources: {body_text}"
         );
-        assert!(!body_text.contains("length limit exceeded"));
     }
 
     #[tokio::test]
@@ -2025,10 +2011,7 @@ mod tests {
             payload["user"]["loginMethod"],
             Value::String("password".to_string())
         );
-        assert_eq!(
-            payload["user"]["createdAt"],
-            Value::String(seed_user.created_at)
-        );
+        assert!(payload["user"].get("createdAt").is_none());
         assert!(payload["token"].as_str().is_some());
     }
 
@@ -2308,7 +2291,7 @@ mod tests {
             payload["user"]["phoneNumberMasked"],
             Value::String("138****8000".to_string())
         );
-        assert!(payload["user"]["createdAt"].as_str().is_some());
+        assert!(payload["user"].get("createdAt").is_none());
         assert_eq!(payload["created"], Value::Bool(true));
         assert!(payload["referral"].is_null());
     }
diff --git a/server-rs/crates/api-server/src/assets.rs b/server-rs/crates/api-server/src/assets.rs
index dfc6d90f0..16113daaf 100644
--- a/server-rs/crates/api-server/src/assets.rs
+++ b/server-rs/crates/api-server/src/assets.rs
@@ -1217,13 +1217,17 @@ mod tests {
 
     #[tokio::test]
     async fn direct_upload_ticket_returns_service_unavailable_when_oss_missing() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let token =
+            seed_authenticated_token(&state, "13800138121", "sess_assets_missing_oss").await;
+        let app = build_router(state);
 
         let response = app
             .oneshot(
                 Request::builder()
                     .method("POST")
                     .uri("/api/assets/direct-upload-tickets")
+                    .header("authorization", format!("Bearer {token}"))
                     .header("content-type", "application/json")
                     .body(Body::from(
                         json!({
@@ -1490,13 +1494,17 @@ mod tests {
 
     #[tokio::test]
     async fn sts_upload_credentials_are_disabled_for_browser_writes() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let token =
+            seed_authenticated_token(&state, "13800138122", "sess_assets_sts_disabled").await;
+        let app = build_router(state);
 
         let response = app
             .oneshot(
                 Request::builder()
                     .method("POST")
                     .uri("/api/assets/sts-upload-credentials")
+                    .header("authorization", format!("Bearer {token}"))
                     .header("x-genarrative-response-envelope", "1")
                     .body(Body::empty())
                     .expect("request should build"),
@@ -1525,13 +1533,18 @@ mod tests {
 
     #[tokio::test]
     async fn confirm_asset_object_returns_service_unavailable_when_oss_missing() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let token =
+            seed_authenticated_token(&state, "13800138123", "sess_assets_confirm_missing_oss")
+                .await;
+        let app = build_router(state);
 
         let response = app
             .oneshot(
                 Request::builder()
                     .method("POST")
                     .uri("/api/assets/objects/confirm")
+                    .header("authorization", format!("Bearer {token}"))
                     .header("content-type", "application/json")
                     .body(Body::from(
                         json!({
@@ -1558,13 +1571,17 @@ mod tests {
             ..AppConfig::default()
         };
 
-        let app = build_router(AppState::new(config).expect("state should build"));
+        let state = AppState::new(config).expect("state should build");
+        let token =
+            seed_authenticated_token(&state, "13800138124", "sess_assets_bucket_mismatch").await;
+        let app = build_router(state);
 
         let response = app
             .oneshot(
                 Request::builder()
                     .method("POST")
                     .uri("/api/assets/objects/confirm")
+                    .header("authorization", format!("Bearer {token}"))
                     .header("content-type", "application/json")
                     .body(Body::from(
                         json!({
@@ -1588,13 +1605,17 @@ mod tests {
 
     #[tokio::test]
     async fn bind_asset_object_rejects_missing_slot_before_calling_spacetime() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let token =
+            seed_authenticated_token(&state, "13800138125", "sess_assets_missing_slot").await;
+        let app = build_router(state);
 
         let response = app
             .oneshot(
                 Request::builder()
                     .method("POST")
                     .uri("/api/assets/objects/bind")
+                    .header("authorization", format!("Bearer {token}"))
                     .header("content-type", "application/json")
                     .body(Body::from(
                         json!({
diff --git a/server-rs/crates/api-server/src/character_animation_assets.rs b/server-rs/crates/api-server/src/character_animation_assets.rs
index 4c0ac0140..b925e07d3 100644
--- a/server-rs/crates/api-server/src/character_animation_assets.rs
+++ b/server-rs/crates/api-server/src/character_animation_assets.rs
@@ -62,20 +62,23 @@ use crate::{
     },
     editor_green_screen::{
         EditorScreenBackgroundColor, editor_green_screen_character_prompt_clause,
-        remove_editor_generated_green_screen_background,
     },
     editor_project::{
-        EditorCanvasGeneratedLayerInput, PersistEditorGeneratedAssetRequest,
+        EDITOR_ASSET_ID_PREFIX, EDITOR_BGFILTER_CROSS_CHECK_ENABLED,
+        EDITOR_BGFILTER_DEFAULT_SEG_MODEL, EDITOR_RESOURCE_ID_PREFIX,
+        EditorCanvasGeneratedLayerInput, EditorGenerationPhaseReporter,
+        PersistEditorGeneratedAssetRequest,
         apply_editor_screen_background_decision_to_generation_inputs,
         build_editor_canvas_generated_layer_item, complete_editor_canvas_generation_with_items,
         persist_editor_generated_media_asset,
+        remove_editor_generated_screen_background_with_bgfilter_with_request_timeout,
+        resolve_editor_reference_object_key_for_owner,
     },
     editor_screen_background_decision::{
         EditorScreenBackgroundDecisionInput, EditorScreenBackgroundDecisionKind,
         resolve_editor_screen_background_color,
     },
     http_error::AppError,
-    openai_image_generation::DownloadedOpenAiImage,
     platform_errors::map_oss_error,
     prompt::role_asset_studio::{
         build_role_asset_workflow, normalize_animation_prompt_text_by_key,
@@ -114,6 +117,7 @@ const EDITOR_CHARACTER_ANIMATION_MODEL: &str = "seedance2.0-fast";
 const EDITOR_CHARACTER_ANIMATION_ASSET_KIND: &str = "editor_character_animation";
 const EDITOR_CHARACTER_ANIMATION_RESOURCE_ASSET_KIND: &str = "character-animation";
 const EDITOR_CHARACTER_ANIMATION_PROVIDER_SOURCE_SLOT: &str = "provider_source";
+const EDITOR_CHARACTER_ANIMATION_BGFILTER_TIMEOUT_PER_FRAME_MS: u64 = 2_000;
 const EDITOR_VIDEO_ASSET_KIND: &str = "editor_video";
 const EDITOR_VIDEO_ENTITY_KIND: &str = "editor_canvas";
 const EDITOR_VIDEO_SLOT: &str = "video_preview";
@@ -127,7 +131,7 @@ const EDITOR_VIDEO_MODEL_VEO_3_1_FAST: &str = "veo3.1-fast";
 const EDITOR_VIDEO_REFERENCE_IMAGE_LIMIT: usize = 9;
 const EDITOR_VIDEO_REFERENCE_VIDEO_LIMIT: usize = 3;
 const EDITOR_VIDEO_REFERENCE_AUDIO_LIMIT: usize = 3;
-const EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES: usize = 64 * 1024 * 1024;
+const EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES: usize = 256 * 1024;
 const EDITOR_VIDEO_REFERENCE_READ_EXPIRE_SECONDS: u64 = 60 * 60;
 
 const BUILT_IN_MOTION_TEMPLATES: [MotionTemplate; 4] = [
@@ -565,6 +569,14 @@ pub async fn generate_editor_character_animation(
         )
     })?;
     let owner_user_id = authenticated.claims().user_id().to_string();
+    if matches_inline_media_source(payload.source_image_src.as_str()) {
+        return Err(character_animation_error_response(
+            &request_context,
+            editor_character_animation_bad_request(
+                "sourceImageSrc 必须先上传 OSS，并使用 objectKey 或画板资源引用。",
+            ),
+        ));
+    }
     if !state.config.external_generation_mode.is_inline() {
         let pricing = state.editor_generation_pricing().await.map_err(|error| {
             character_animation_error_response(
@@ -610,6 +622,7 @@ pub async fn generate_editor_character_animation(
         request_context,
         owner_user_id,
         Ok(Json(payload)),
+        None,
     )
     .await
 }
@@ -619,6 +632,7 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
     request_context: RequestContext,
     owner_user_id: String,
     payload: Result<Json<EditorCharacterAnimationGenerateRequest>, JsonRejection>,
+    phase_reporter: Option<EditorGenerationPhaseReporter>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = payload.map_err(|error| {
         character_animation_error_response(
@@ -636,6 +650,14 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
     let asset_folder_id = payload.asset_folder_id.clone();
     let asset_label =
         resolve_editor_character_animation_asset_label(payload.asset_label.as_deref());
+    if matches_inline_media_source(payload.source_image_src.as_str()) {
+        return Err(character_animation_error_response(
+            &request_context,
+            editor_character_animation_bad_request(
+                "sourceImageSrc 必须先上传 OSS，并使用 objectKey 或画板资源引用。",
+            ),
+        ));
+    }
 
     let pricing = state.editor_generation_pricing().await.map_err(|error| {
         character_animation_error_response(
@@ -649,10 +671,17 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
     // 先解析源角色图：图生视频的主体颜色完全由源图决定，背景色决策必须看到这张图。
     let source_resolve_client = build_upstream_http_client(SOURCE_IMAGE_RESOLVE_TIMEOUT_MS)
         .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let source_object_key = resolve_editor_reference_object_key_for_owner(
+        &state,
+        owner_user_id.as_str(),
+        payload.source_image_src.trim(),
+    )
+    .await
+    .map_err(|error| character_animation_error_response(&request_context, error))?;
     let source_data_url = resolve_media_source_as_data_url(
         &state,
         &source_resolve_client,
-        payload.source_image_src.trim(),
+        source_object_key.as_str(),
         "sourceImageSrc",
     )
     .await
@@ -736,6 +765,10 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
                 source_data_url.as_str(),
             )
             .await?;
+            // 扣费契约（【编辑器】画板角色形象生成入口设计-2026-06-15）：角色动作的交付物是
+            // 画布可用的透明序列帧，预览视频本身不是可用结果；因此预览落库、phase 上报、抽帧、
+            // 逐帧抠图、首帧落库全部留在计费闭包内，任一步失败都走 execute_billable 的失败退款。
+            // 有别于角色生图 / 编辑器视频（provider 产物即交付物，provider 成功即收口扣费）。
             let source_record = persist_editor_generated_media_asset(
                 &state,
                 PersistEditorGeneratedAssetRequest {
@@ -765,6 +798,9 @@ pub(crate) async fn generate_editor_character_animation_for_owner(
                 },
             )
             .await?;
+            if let Some(reporter) = phase_reporter.as_ref() {
+                reporter.report_processing(&state).await?;
+            }
             let provider_source_resource_id = source_record
                 .0
                 .as_ref()
@@ -2002,7 +2038,8 @@ async fn request_editor_video_preview(
     request: &NormalizedEditorVideoRequest,
 ) -> Result<GeneratedAnimationPreview, AppError> {
     let upstream_task_id =
-        create_editor_text_to_video_task(state, http_client, settings, request).await?;
+        create_editor_text_to_video_task(state, http_client, settings, owner_user_id, request)
+            .await?;
     let video_url =
         wait_for_ark_content_generation_task(http_client, &settings.ark, upstream_task_id.as_str())
             .await?;
@@ -2026,9 +2063,10 @@ async fn create_editor_text_to_video_task(
     state: &AppState,
     http_client: &reqwest::Client,
     settings: &EditorVideoSettings,
+    owner_user_id: &str,
     request: &NormalizedEditorVideoRequest,
 ) -> Result<String, AppError> {
-    let request_body = build_editor_video_ark_request_body(state, request)?;
+    let request_body = build_editor_video_ark_request_body(state, owner_user_id, request).await?;
     let response = http_client
         .post(format!(
             "{}/contents/generations/tasks",
@@ -2254,6 +2292,18 @@ async fn create_editor_ark_image_to_video_task(
     })
 }
 
+fn editor_character_animation_bgfilter_request_timeout_ms(
+    base_timeout_ms: u64,
+    frame_count: usize,
+) -> u64 {
+    let frame_timeout_increment_ms = u64::try_from(frame_count)
+        .unwrap_or(u64::MAX)
+        .saturating_mul(EDITOR_CHARACTER_ANIMATION_BGFILTER_TIMEOUT_PER_FRAME_MS);
+    base_timeout_ms
+        .saturating_add(frame_timeout_increment_ms)
+        .max(1)
+}
+
 async fn extract_and_persist_editor_character_animation_frames(
     state: &AppState,
     owner_user_id: &str,
@@ -2280,189 +2330,183 @@ async fn extract_and_persist_editor_character_animation_frames(
         Some(request.duration_seconds as f64),
     )
     .await?;
-    persist_editor_character_animation_provider_source_frames(
-        state,
-        owner_user_id,
-        source_layer_id,
-        task_id,
-        &finalized_frames,
-    )
-    .await?;
-    let finalized_frames = remove_editor_character_animation_frame_backgrounds(
-        state,
-        finalized_frames,
-        request.frame_width,
-        request.frame_height,
-        request.screen_color,
-        audit,
-    )
-    .await?;
+    use futures_util::StreamExt as _;
 
-    let mut frame_payloads = Vec::with_capacity(finalized_frames.len());
-    let mut first_frame_object = None;
-    for (index, frame) in finalized_frames.into_iter().enumerate() {
-        let content_type = frame.mime_type.clone();
-        let put_result = put_character_animation_object(
-            state,
-            LegacyAssetPrefix::Animations,
-            vec![
-                "editor".to_string(),
-                sanitize_storage_segment(source_layer_id, "layer"),
-                task_id.to_string(),
-            ],
-            format!("frame{:02}.{}", index + 1, frame.extension),
-            frame.mime_type,
-            frame.bytes,
-            build_asset_metadata(
-                EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
+    let frame_count = finalized_frames.len();
+    let bgfilter_request_timeout_ms = editor_character_animation_bgfilter_request_timeout_ms(
+        state.config.editor_bgfilter_request_timeout_ms,
+        frame_count,
+    );
+    let frame_results = futures_util::stream::iter(finalized_frames.into_iter().enumerate().map(
+        |(frame_index, frame)| async move {
+            process_and_persist_editor_character_animation_frame(
+                state,
                 owner_user_id,
-                "editor_layer",
                 source_layer_id,
-                "animation_frame",
-                "editor-character-animation",
-            ),
-        )
-        .await?;
-        let confirmed = confirm_editor_character_animation_frame_asset_object(
-            state,
-            owner_user_id,
-            source_layer_id,
-            task_id,
-            put_result.object_key.clone(),
-            content_type,
-        )
-        .await?;
-        if index == 0 {
-            first_frame_object = Some((
-                put_result.object_key.clone(),
-                confirmed.record.asset_object_id,
-            ));
+                task_id,
+                frame_index,
+                frame,
+                request.frame_width,
+                request.frame_height,
+                request.screen_color,
+                bgfilter_request_timeout_ms,
+                audit,
+            )
+            .await
+            .map_err(|error| (frame_index, error))
+        },
+    ))
+    // 中文注释：动作帧上限固定为 48。全部帧连续进入在途集合，由 BgFilter 服务端既有进程锁自行排队；
+    // api-server 不再等待前一帧返回，也不因返回乱序产生队头阻塞。
+    .buffer_unordered(frame_count.max(1))
+    // 中文注释：不能 try_collect 提前取消。已经发出的请求必须全部排空，避免服务端完成计算后无人接收。
+    .collect::<Vec<_>>()
+    .await;
+
+    let mut frame_payloads = Vec::with_capacity(frame_count);
+    let mut frame_errors = Vec::new();
+    for frame_result in frame_results {
+        match frame_result {
+            Ok(frame_payload) => frame_payloads.push(frame_payload),
+            Err(frame_error) => frame_errors.push(frame_error),
         }
-        frame_payloads.push(EditorCharacterAnimationFramePayload {
-            frame_index: index as u32 + 1,
-            image_src: put_result.legacy_public_path,
-            width: request.frame_width,
-            height: request.frame_height,
-        });
+    }
+    frame_payloads.sort_by_key(|frame| frame.payload.frame_index);
+    frame_errors.sort_by_key(|(frame_index, _)| *frame_index);
+    if let Some((frame_index, error)) = frame_errors.into_iter().next() {
+        tracing::warn!(
+            frame_index = frame_index + 1,
+            completed_frames = frame_payloads.len(),
+            expected_frames = frame_count,
+            error = %error,
+            "editor_animation_frame_pipeline_failed_after_drain"
+        );
+        return Err(error);
     }
 
-    let (first_frame_object_key, first_frame_asset_object_id) =
-        first_frame_object.ok_or_else(|| {
+    let (first_frame_object_key, first_frame_asset_object_id) = frame_payloads
+        .first()
+        .map(|frame| (frame.object_key.clone(), frame.asset_object_id.clone()))
+        .ok_or_else(|| {
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                 "provider": "editor-character-animation",
                 "message": "角色动作抽帧完成但没有生成首帧对象。",
             }))
         })?;
     Ok(PersistedEditorCharacterAnimationFrameSet {
-        frames: frame_payloads,
         first_frame_object_key,
         first_frame_asset_object_id,
+        frames: frame_payloads
+            .into_iter()
+            .map(|frame| frame.payload)
+            .collect(),
     })
 }
 
-async fn persist_editor_character_animation_provider_source_frames(
+async fn process_and_persist_editor_character_animation_frame(
     state: &AppState,
     owner_user_id: &str,
     source_layer_id: &str,
     task_id: &str,
-    frames: &[FinalizedAnimationFrame],
-) -> Result<(), AppError> {
-    for (index, frame) in frames.iter().enumerate() {
-        put_character_animation_object(
-            state,
-            LegacyAssetPrefix::Animations,
-            vec![
-                "editor".to_string(),
-                sanitize_storage_segment(source_layer_id, "layer"),
-                task_id.to_string(),
-            ],
-            format!("green-screen-frame{:02}.{}", index + 1, frame.extension),
-            frame.mime_type.clone(),
-            frame.bytes.clone(),
-            build_asset_metadata(
-                EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
-                owner_user_id,
-                "editor_layer",
-                source_layer_id,
-                EDITOR_CHARACTER_ANIMATION_PROVIDER_SOURCE_SLOT,
-                "editor-character-animation",
-            ),
-        )
-        .await?;
-    }
-    Ok(())
-}
-
-/// 逐帧抠图：优先阿里云通用抠图，失败降级本地键色（使用生成时的纯色背景色）。
-/// 小并发保序处理，单帧降级不影响其他帧。
-async fn remove_editor_character_animation_frame_backgrounds(
-    state: &AppState,
-    frames: Vec<FinalizedAnimationFrame>,
+    frame_index: usize,
+    frame: FinalizedAnimationFrame,
     frame_width: u32,
     frame_height: u32,
     screen_color: EditorScreenBackgroundColor,
+    bgfilter_request_timeout_ms: u64,
     audit: &crate::external_api_audit::ExternalApiAuditContext,
-) -> Result<Vec<FinalizedAnimationFrame>, AppError> {
-    use futures_util::{StreamExt as _, TryStreamExt as _};
+) -> Result<ProcessedEditorCharacterAnimationFrame, AppError> {
+    // 中文注释：每一帧只要求自己的绿幕源图先落 OSS，不再等待整批源图全部上传完成。
+    let source_put = put_character_animation_object(
+        state,
+        LegacyAssetPrefix::Animations,
+        vec![
+            "editor".to_string(),
+            sanitize_storage_segment(source_layer_id, "layer"),
+            task_id.to_string(),
+        ],
+        format!(
+            "green-screen-frame{:02}.{}",
+            frame_index + 1,
+            frame.extension
+        ),
+        frame.mime_type.clone(),
+        frame.bytes,
+        build_asset_metadata(
+            EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
+            owner_user_id,
+            "editor_layer",
+            source_layer_id,
+            EDITOR_CHARACTER_ANIMATION_PROVIDER_SOURCE_SLOT,
+            "editor-character-animation",
+        ),
+    )
+    .await?;
 
-    const FRAME_MATTING_CONCURRENCY: usize = 3;
+    let removed = remove_editor_generated_screen_background_with_bgfilter_with_request_timeout(
+        state,
+        source_put.object_key.as_str(),
+        screen_color,
+        EDITOR_BGFILTER_DEFAULT_SEG_MODEL,
+        EDITOR_BGFILTER_CROSS_CHECK_ENABLED,
+        bgfilter_request_timeout_ms,
+        audit,
+    )
+    .await?;
+    tracing::debug!(
+        frame_index,
+        screen_color = screen_color.hex,
+        "editor_animation_frame_background_removed"
+    );
+    let finalized = finalize_animation_frame_payload(
+        removed.image.bytes.as_slice(),
+        removed.image.mime_type.as_str(),
+        frame_width,
+        frame_height,
+        false,
+    )?;
+    let content_type = finalized.mime_type.clone();
+    let put_result = put_character_animation_object(
+        state,
+        LegacyAssetPrefix::Animations,
+        vec![
+            "editor".to_string(),
+            sanitize_storage_segment(source_layer_id, "layer"),
+            task_id.to_string(),
+        ],
+        format!("frame{:02}.{}", frame_index + 1, finalized.extension),
+        finalized.mime_type,
+        finalized.bytes,
+        build_asset_metadata(
+            EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
+            owner_user_id,
+            "editor_layer",
+            source_layer_id,
+            "animation_frame",
+            "editor-character-animation",
+        ),
+    )
+    .await?;
+    let confirmed = confirm_editor_character_animation_frame_asset_object(
+        state,
+        owner_user_id,
+        source_layer_id,
+        task_id,
+        put_result.object_key.clone(),
+        content_type,
+    )
+    .await?;
 
-    futures_util::stream::iter(frames.into_iter().enumerate().map(
-        |(frame_index, frame)| async move {
-            let image = DownloadedOpenAiImage {
-                bytes: frame.bytes,
-                mime_type: frame.mime_type,
-                extension: frame.extension,
-            };
-            let removed = match crate::aliyun_matting::segment_image_with_aliyun_matting(
-                state,
-                &image,
-                "editor-animation-frame",
-            )
-            .await
-            {
-                Ok(removed) => removed,
-                Err(error) => {
-                    tracing::warn!(
-                        provider = "aliyun-matting",
-                        frame_index,
-                        screen_color = screen_color.hex,
-                        error = %error,
-                        error_details = ?error.details(),
-                        "editor_animation_frame_aliyun_matting_fallback_to_local"
-                    );
-                    if crate::external_api_audit::matting_failure_external_call_attempted(&error) {
-                        crate::external_api_audit::record_matting_external_api_failure(
-                            state,
-                            audit,
-                            "aliyun-matting",
-                            state.config.aliyun_matting_endpoint.clone(),
-                            "editor-character-animation-frame-matting",
-                            "aliyun_segment",
-                            crate::external_api_audit::matting_failure_audit_status_code(&error),
-                            crate::external_api_audit::matting_failure_audit_timeout(&error),
-                            crate::external_api_audit::matting_failure_audit_latency_ms(&error),
-                            error.message().to_string(),
-                            crate::external_api_audit::matting_failure_audit_raw_excerpt(&error)
-                                .or_else(|| Some(format!("frame_index={frame_index}"))),
-                        )
-                        .await;
-                    }
-                    remove_editor_generated_green_screen_background(&image, screen_color)?
-                }
-            };
-            finalize_animation_frame_payload(
-                removed.bytes.as_slice(),
-                removed.mime_type.as_str(),
-                frame_width,
-                frame_height,
-                false,
-            )
+    Ok(ProcessedEditorCharacterAnimationFrame {
+        payload: EditorCharacterAnimationFramePayload {
+            frame_index: frame_index as u32 + 1,
+            image_src: put_result.legacy_public_path,
+            width: frame_width,
+            height: frame_height,
         },
-    ))
-    .buffered(FRAME_MATTING_CONCURRENCY)
-    .try_collect::<Vec<_>>()
-    .await
+        object_key: put_result.object_key,
+        asset_object_id: confirmed.record.asset_object_id,
+    })
 }
 
 async fn publish_animation_set(
@@ -3379,11 +3423,12 @@ fn normalize_editor_video_request_with_pricing(
     })
 }
 
-fn build_editor_video_ark_request_body(
+async fn build_editor_video_ark_request_body(
     state: &AppState,
+    owner_user_id: &str,
     request: &NormalizedEditorVideoRequest,
 ) -> Result<Value, AppError> {
-    let content = build_editor_video_ark_content(state, request)?;
+    let content = build_editor_video_ark_content(state, owner_user_id, request).await?;
     Ok(json!({
         "model": request.provider_model,
         "content": content,
@@ -3395,8 +3440,9 @@ fn build_editor_video_ark_request_body(
     }))
 }
 
-fn build_editor_video_ark_content(
+async fn build_editor_video_ark_content(
     state: &AppState,
+    owner_user_id: &str,
     request: &NormalizedEditorVideoRequest,
 ) -> Result<Vec<Value>, AppError> {
     let mut content = Vec::new();
@@ -3408,22 +3454,25 @@ fn build_editor_video_ark_content(
     }
     let reference_image_urls = resolve_editor_video_reference_urls(
         state,
+        owner_user_id,
         request.reference_image_srcs.as_slice(),
         "参考图片",
-        true,
-    )?;
+    )
+    .await?;
     let reference_video_urls = resolve_editor_video_reference_urls(
         state,
+        owner_user_id,
         request.reference_video_srcs.as_slice(),
         "参考视频",
-        false,
-    )?;
+    )
+    .await?;
     let reference_audio_urls = resolve_editor_video_reference_urls(
         state,
+        owner_user_id,
         request.reference_audio_srcs.as_slice(),
         "参考音频",
-        true,
-    )?;
+    )
+    .await?;
     content.extend(reference_image_urls.iter().map(|url| {
         json!({
             "type": "image_url",
@@ -3448,31 +3497,30 @@ fn build_editor_video_ark_content(
     Ok(content)
 }
 
-fn resolve_editor_video_reference_urls(
+async fn resolve_editor_video_reference_urls(
     state: &AppState,
+    owner_user_id: &str,
     sources: &[String],
     label: &str,
-    allow_data_url: bool,
 ) -> Result<Vec<String>, AppError> {
-    sources
-        .iter()
-        .map(|source| {
-            resolve_editor_video_reference_url(state, source.as_str(), label, allow_data_url)
-        })
-        .collect()
+    let mut resolved = Vec::with_capacity(sources.len());
+    for source in sources {
+        resolved.push(
+            resolve_editor_video_reference_url(state, owner_user_id, source.as_str(), label)
+                .await?,
+        );
+    }
+    Ok(resolved)
 }
 
-fn resolve_editor_video_reference_url(
+async fn resolve_editor_video_reference_url(
     state: &AppState,
+    owner_user_id: &str,
     source: &str,
     label: &str,
-    allow_data_url: bool,
 ) -> Result<String, AppError> {
     let value = source.trim();
     if value.starts_with("data:") {
-        if allow_data_url {
-            return Ok(value.to_string());
-        }
         return Err(editor_video_bad_request(format!(
             "{label}格式不支持，请使用官方支持的 URL、素材 ID 或画板资源路径。"
         )));
@@ -3484,17 +3532,24 @@ fn resolve_editor_video_reference_url(
         return Ok(value.to_string());
     }
 
-    let object_key = value.trim_start_matches('/');
-    if LegacyAssetPrefix::from_object_key(object_key).is_none() {
-        let format_hint = if allow_data_url {
-            "公网 URL、素材 ID、data URL 或画板资源路径"
-        } else {
-            "公网 URL、素材 ID 或画板资源路径"
-        };
-        return Err(editor_video_bad_request(format!(
-            "{label}必须是官方支持的{format_hint}。"
-        )));
-    }
+    let object_key = resolve_editor_reference_object_key_for_owner(state, owner_user_id, value)
+        .await
+        .map_err(|error| {
+            error.with_details(json!({
+                "provider": "editor-video",
+                "field": label,
+                "message": format!(
+                    "{label}必须是当前账号的 objectKey、项目资源 ID、素材 ID，或官方支持的公网 URL。"
+                ),
+            }))
+        })?;
+    sign_editor_video_object_key_url(state, object_key.as_str())
+}
+
+fn sign_editor_video_object_key_url(
+    state: &AppState,
+    object_key: &str,
+) -> Result<String, AppError> {
     let oss_client = state.oss_client().ok_or_else(|| {
         AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
             "provider": "aliyun-oss",
@@ -3559,9 +3614,9 @@ fn normalize_editor_video_references(
         validate_editor_video_reference_src(
             src,
             "参考图片",
-            &["data:image/", "http://", "https://", "asset://"],
+            &["http://", "https://", "asset://"],
             true,
-            "对应媒体 data URL",
+            "URL、素材 ID 或画板资源路径",
         )?;
     }
     for src in &video_srcs {
@@ -3577,9 +3632,9 @@ fn normalize_editor_video_references(
         validate_editor_video_reference_src(
             src,
             "参考音频",
-            &["data:audio/", "http://", "https://", "asset://"],
+            &["http://", "https://", "asset://"],
             true,
-            "对应媒体 data URL",
+            "URL、素材 ID 或画板资源路径",
         )?;
     }
 
@@ -3590,7 +3645,9 @@ fn normalize_editor_video_references(
         .map(String::len)
         .sum::<usize>();
     if request_bytes > EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES {
-        return Err(editor_video_bad_request("参考文件总请求体不能超过 64MB。"));
+        return Err(editor_video_bad_request(
+            "参考素材引用字段总长度不能超过 256KB。",
+        ));
     }
 
     Ok(NormalizedEditorVideoReferences {
@@ -3608,6 +3665,11 @@ fn normalize_reference_srcs(values: Vec<String>) -> Vec<String> {
         .collect()
 }
 
+fn matches_inline_media_source(value: &str) -> bool {
+    let value = value.trim_start().to_ascii_lowercase();
+    value.starts_with("data:") || value.starts_with("blob:")
+}
+
 fn validate_editor_video_reference_src(
     value: &str,
     label: &str,
@@ -3626,6 +3688,9 @@ fn validate_editor_video_reference_src(
     {
         return Ok(());
     }
+    if value.starts_with(EDITOR_RESOURCE_ID_PREFIX) || value.starts_with(EDITOR_ASSET_ID_PREFIX) {
+        return Ok(());
+    }
     Err(editor_video_bad_request(format!(
         "{label}格式不支持，请使用官方支持的{format_hint}。"
     )))
@@ -5633,6 +5698,12 @@ struct PersistedEditorCharacterAnimationFrameSet {
     first_frame_asset_object_id: String,
 }
 
+struct ProcessedEditorCharacterAnimationFrame {
+    payload: EditorCharacterAnimationFramePayload,
+    object_key: String,
+    asset_object_id: String,
+}
+
 // 统一收口动作生成阶段返回的草稿载荷，避免图片序列和视频预览分支在 handler 层分叉太散。
 struct CharacterAnimationGeneratedDraft {
     image_sources: Vec<String>,
@@ -6044,7 +6115,83 @@ mod tests {
     }
 
     #[test]
-    fn editor_character_animation_frames_use_local_green_screen_postprocess() {
+    fn editor_character_animation_rejects_inline_media_before_queueing() {
+        let source = include_str!("character_animation_assets.rs");
+        assert_function_contains_in_order(
+            source,
+            "pub async fn generate_editor_character_animation",
+            "pub(crate) async fn generate_editor_character_animation_for_owner",
+            &[
+                "matches_inline_media_source",
+                "enqueue_editor_generation_job",
+            ],
+        );
+        assert_function_contains_in_order(
+            source,
+            "pub(crate) async fn generate_editor_character_animation_for_owner",
+            "pub async fn generate_editor_video",
+            &[
+                "resolve_editor_reference_object_key_for_owner",
+                "resolve_media_source_as_data_url",
+            ],
+        );
+        assert!(matches_inline_media_source("data:image/png;base64,AAAA"));
+        assert!(matches_inline_media_source("  BLOB:local-preview"));
+        assert!(!matches_inline_media_source(
+            "/generated-images/editor/character.png"
+        ));
+    }
+
+    #[test]
+    fn editor_character_animation_reports_processing_after_video_generation() {
+        let source = include_str!("character_animation_assets.rs");
+        // 扣费契约：角色动作的交付物是透明序列帧，预览落库、phase 上报、抽帧、首帧落库
+        // 全部在计费闭包内收口之前完成，任一步失败必须触发退款。
+        assert_function_contains_in_order(
+            source,
+            "pub(crate) async fn generate_editor_character_animation_for_owner",
+            "pub async fn generate_editor_video",
+            &[
+                "execute_billable_asset_operation_with_cost",
+                "request_editor_character_animation_preview",
+                "persist_editor_generated_media_asset",
+                "reporter.report_processing(&state).await?",
+                "extract_and_persist_editor_character_animation_frames",
+                "Ok::<_, AppError>((generated, frames, normalized, generation_inputs))",
+            ],
+        );
+    }
+
+    #[test]
+    fn editor_character_animation_bgfilter_timeout_scales_with_frame_count() {
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(180_000, 32),
+            244_000
+        );
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(180_000, 40),
+            260_000
+        );
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(180_000, 48),
+            276_000
+        );
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(0, 32),
+            64_000
+        );
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(0, 0),
+            1
+        );
+        assert_eq!(
+            editor_character_animation_bgfilter_request_timeout_ms(u64::MAX - 1, 48),
+            u64::MAX
+        );
+    }
+
+    #[test]
+    fn editor_character_animation_frames_use_three_stage_matting_fallback() {
         let source = include_str!("character_animation_assets.rs");
         assert_function_contains(
             source,
@@ -6052,39 +6199,53 @@ mod tests {
             "async fn publish_animation_set",
             &[
                 "apply_chroma_key: false",
-                "persist_editor_character_animation_provider_source_frames",
-                "remove_editor_character_animation_frame_backgrounds",
+                "editor_character_animation_bgfilter_request_timeout_ms",
+                "state.config.editor_bgfilter_request_timeout_ms",
+                "process_and_persist_editor_character_animation_frame",
+                "bgfilter_request_timeout_ms",
+                ".buffer_unordered(frame_count.max(1))",
+                ".collect::<Vec<_>>()",
+                "frame_payloads.sort_by_key",
+                "frame_errors.sort_by_key",
             ],
         );
         assert_function_contains_in_order(
             source,
-            "async fn extract_and_persist_editor_character_animation_frames",
+            "async fn process_and_persist_editor_character_animation_frame",
             "async fn publish_animation_set",
             &[
-                "persist_editor_character_animation_provider_source_frames",
-                "remove_editor_character_animation_frame_backgrounds",
+                "put_character_animation_object",
+                "green-screen-frame",
+                "remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
+                "source_put.object_key.as_str()",
+                "bgfilter_request_timeout_ms",
+                "finalize_animation_frame_payload",
+                "put_character_animation_object",
+                "animation_frame",
             ],
         );
         assert_function_contains(
             source,
-            "async fn persist_editor_character_animation_provider_source_frames",
-            "fn remove_editor_character_animation_frame_backgrounds",
+            "async fn process_and_persist_editor_character_animation_frame",
+            "async fn publish_animation_set",
             &[
                 "EDITOR_CHARACTER_ANIMATION_ASSET_KIND",
                 "EDITOR_CHARACTER_ANIMATION_PROVIDER_SOURCE_SLOT",
                 "green-screen-frame",
-                "put_character_animation_object",
-            ],
-        );
-        assert_function_contains(
-            source,
-            "fn remove_editor_character_animation_frame_backgrounds",
-            "async fn publish_animation_set",
-            &[
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
+                "EDITOR_BGFILTER_DEFAULT_SEG_MODEL",
+                "EDITOR_BGFILTER_CROSS_CHECK_ENABLED",
+                "bgfilter_request_timeout_ms",
                 "finalize_animation_frame_payload",
             ],
         );
+        let frame_pipeline = source
+            .split_once("async fn process_and_persist_editor_character_animation_frame")
+            .and_then(|(_, tail)| tail.split_once("async fn publish_animation_set"))
+            .map(|(body, _)| body)
+            .expect("frame pipeline function should exist");
+        assert!(!frame_pipeline.contains("frame.bytes.clone()"));
+        assert!(!frame_pipeline.contains("DownloadedOpenAiImage"));
     }
 
     #[test]
@@ -6149,12 +6310,14 @@ mod tests {
         assert_function_contains(
             source,
             "async fn extract_and_persist_editor_character_animation_frames",
-            "async fn persist_editor_character_animation_provider_source_frames",
-            &[
-                "confirm_editor_character_animation_frame_asset_object",
-                "first_frame_object_key",
-                "first_frame_asset_object_id",
-            ],
+            "async fn process_and_persist_editor_character_animation_frame",
+            &["first_frame_object_key", "first_frame_asset_object_id"],
+        );
+        assert_function_contains(
+            source,
+            "async fn process_and_persist_editor_character_animation_frame",
+            "async fn confirm_editor_character_animation_frame_asset_object",
+            &["confirm_editor_character_animation_frame_asset_object"],
         );
         assert_function_contains(
             source,
@@ -6447,11 +6610,15 @@ mod tests {
             mode: "std".to_string(),
             sound: "off".to_string(),
             web_search_enabled: true,
-            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_image_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/image/demo.png".to_string(),
+            ],
             reference_video_srcs: vec![
                 "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
             ],
-            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+            reference_audio_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/audio/demo.mp3".to_string(),
+            ],
             project_id: None,
             canvas_completion: None,
             generation_inputs: None,
@@ -6464,7 +6631,7 @@ mod tests {
 
         assert_eq!(
             normalized.reference_image_srcs,
-            vec!["data:image/png;base64,image"]
+            vec!["generated-character-drafts/editor/seedance-references/image/demo.png"]
         );
         assert_eq!(
             normalized.reference_video_srcs,
@@ -6472,7 +6639,7 @@ mod tests {
         );
         assert_eq!(
             normalized.reference_audio_srcs,
-            vec!["data:audio/mpeg;base64,audio"]
+            vec!["generated-character-drafts/editor/seedance-references/audio/demo.mp3"]
         );
     }
 
@@ -6504,7 +6671,46 @@ mod tests {
     }
 
     #[test]
-    fn editor_video_ark_body_sets_generate_audio_false_without_mode() {
+    fn editor_video_rejects_seedance_image_and_audio_data_urls() {
+        for (image_srcs, audio_srcs, expected_message) in [
+            (
+                vec!["data:image/png;base64,image".to_string()],
+                Vec::new(),
+                "参考图片格式不支持",
+            ),
+            (
+                vec!["generated-character-drafts/editor/reference.png".to_string()],
+                vec!["data:audio/mpeg;base64,audio".to_string()],
+                "参考音频格式不支持",
+            ),
+        ] {
+            let error = normalize_editor_video_request(EditorVideoGenerateRequest {
+                prompt: "参考素材生成视频".to_string(),
+                model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+                aspect_ratio: "16:9".to_string(),
+                duration_seconds: 4,
+                resolution: "480p".to_string(),
+                mode: "std".to_string(),
+                sound: "off".to_string(),
+                web_search_enabled: true,
+                reference_image_srcs: image_srcs,
+                reference_video_srcs: Vec::new(),
+                reference_audio_srcs: audio_srcs,
+                project_id: None,
+                canvas_completion: None,
+                generation_inputs: None,
+                source_resource_id: None,
+                asset_kind: None,
+                asset_folder_id: None,
+                asset_label: None,
+            })
+            .expect_err("Seedance references must not accept data URLs");
+            assert!(error.body_text().contains(expected_message));
+        }
+    }
+
+    #[tokio::test]
+    async fn editor_video_ark_body_sets_generate_audio_false_without_mode() {
         let state = AppState::new(AppConfig::default()).expect("state should build");
         let request = normalize_editor_video_request(EditorVideoGenerateRequest {
             prompt: "参考素材生成视频".to_string(),
@@ -6515,9 +6721,9 @@ mod tests {
             mode: "std".to_string(),
             sound: "off".to_string(),
             web_search_enabled: true,
-            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_image_srcs: vec!["https://assets.example.com/reference.png".to_string()],
             reference_video_srcs: vec!["https://assets.example.com/reference.mp4".to_string()],
-            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+            reference_audio_srcs: vec!["https://assets.example.com/reference.mp3".to_string()],
             project_id: None,
             canvas_completion: None,
             generation_inputs: None,
@@ -6528,8 +6734,9 @@ mod tests {
         })
         .expect("seedance multimodal request should normalize");
 
-        let body =
-            build_editor_video_ark_request_body(&state, &request).expect("ark body should build");
+        let body = build_editor_video_ark_request_body(&state, "video-owner", &request)
+            .await
+            .expect("ark body should build");
 
         assert_eq!(body["generate_audio"], json!(false));
         assert!(body.get("mode").is_none());
@@ -6543,7 +6750,7 @@ mod tests {
     }
 
     #[test]
-    fn editor_video_ark_content_signs_generated_object_keys() {
+    fn editor_video_reference_resolution_checks_owner_before_signing() {
         let state = AppState::new(AppConfig {
             oss_bucket: Some("genarrative-assets".to_string()),
             oss_endpoint: Some("oss-cn-shanghai.aliyuncs.com".to_string()),
@@ -6552,7 +6759,14 @@ mod tests {
             ..AppConfig::default()
         })
         .expect("state should build with OSS");
-        let request = normalize_editor_video_request(EditorVideoGenerateRequest {
+        let object_key = "generated-character-drafts/editor/seedance-references/video/demo.mp4";
+        let signed_url = sign_editor_video_object_key_url(&state, object_key)
+            .expect("validated object keys should be signable");
+        assert!(signed_url.starts_with("https://genarrative-assets.oss-cn-shanghai.aliyuncs.com/"));
+        assert!(signed_url.contains(object_key));
+        assert!(signed_url.contains("x-oss-signature="));
+
+        let registered_reference = normalize_editor_video_request(EditorVideoGenerateRequest {
             prompt: "参考视频生成视频".to_string(),
             model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
             aspect_ratio: "16:9".to_string(),
@@ -6562,9 +6776,7 @@ mod tests {
             sound: "off".to_string(),
             web_search_enabled: true,
             reference_image_srcs: Vec::new(),
-            reference_video_srcs: vec![
-                "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
-            ],
+            reference_video_srcs: vec!["editor-resource-video-reference".to_string()],
             reference_audio_srcs: Vec::new(),
             project_id: None,
             canvas_completion: None,
@@ -6574,23 +6786,21 @@ mod tests {
             asset_folder_id: None,
             asset_label: None,
         })
-        .expect("seedance objectKey request should normalize");
-
-        let content = build_editor_video_ark_content(&state, &request)
-            .expect("ark content should sign object keys");
-        let signed_url = content[1]["video_url"]["url"]
-            .as_str()
-            .expect("video url should be string");
-
-        assert!(signed_url.starts_with("https://genarrative-assets.oss-cn-shanghai.aliyuncs.com/"));
-        assert!(
-            signed_url
-                .contains("generated-character-drafts/editor/seedance-references/video/demo.mp4")
+        .expect("registered editor resource IDs should normalize");
+        assert_eq!(
+            registered_reference.reference_video_srcs,
+            vec!["editor-resource-video-reference"]
         );
-        assert!(signed_url.contains("x-oss-signature="));
-        assert_ne!(
-            signed_url,
-            "generated-character-drafts/editor/seedance-references/video/demo.mp4"
+
+        let source = include_str!("character_animation_assets.rs");
+        assert_function_contains_in_order(
+            source,
+            "async fn resolve_editor_video_reference_url",
+            "fn sign_editor_video_object_key_url",
+            &[
+                "resolve_editor_reference_object_key_for_owner",
+                "sign_editor_video_object_key_url",
+            ],
         );
     }
 
diff --git a/server-rs/crates/api-server/src/config.rs b/server-rs/crates/api-server/src/config.rs
index 0631b8e5f..3ebcc16b8 100644
--- a/server-rs/crates/api-server/src/config.rs
+++ b/server-rs/crates/api-server/src/config.rs
@@ -17,8 +17,6 @@ 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;
-const DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL: &str = "http://58.87.105.82";
-const DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS: u64 = 120_000;
 const DEFAULT_EDITOR_BGFILTER_BASE_URL: &str = "http://58.87.105.82/bgfilter";
 const DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS: u64 = 180_000;
 const DEFAULT_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD: u32 = 3;
@@ -64,9 +62,6 @@ pub struct AppConfig {
     pub wallet_refund_outbox_flush_interval: Duration,
     pub wallet_refund_outbox_max_bytes: u64,
     pub editor_generation_pricing_override_path: PathBuf,
-    pub editor_background_removal_base_url: String,
-    pub editor_background_removal_token: Option<String>,
-    pub editor_background_removal_request_timeout_ms: u64,
     pub editor_bgfilter_base_url: String,
     pub editor_bgfilter_token: Option<String>,
     pub editor_bgfilter_request_timeout_ms: u64,
@@ -312,11 +307,6 @@ impl Default for AppConfig {
             wallet_refund_outbox_max_bytes: 64 * 1024 * 1024,
             editor_generation_pricing_override_path:
                 crate::editor_generation_config::default_editor_generation_pricing_override_path(),
-            editor_background_removal_base_url: DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL
-                .to_string(),
-            editor_background_removal_token: None,
-            editor_background_removal_request_timeout_ms:
-                DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS,
             editor_bgfilter_base_url: DEFAULT_EDITOR_BGFILTER_BASE_URL.to_string(),
             editor_bgfilter_token: None,
             editor_bgfilter_request_timeout_ms: DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS,
@@ -515,18 +505,6 @@ impl AppConfig {
         {
             config.editor_generation_pricing_override_path = PathBuf::from(pricing_override_path);
         }
-        if let Some(base_url) =
-            read_first_non_empty_env(&["GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL"])
-        {
-            config.editor_background_removal_base_url = base_url;
-        }
-        config.editor_background_removal_token =
-            read_first_non_empty_env(&["GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN"]);
-        if let Some(timeout_ms) = read_first_positive_u64_env(&[
-            "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS",
-        ]) {
-            config.editor_background_removal_request_timeout_ms = timeout_ms;
-        }
         if let Some(base_url) = read_first_non_empty_env(&["GENARRATIVE_EDITOR_BGFILTER_BASE_URL"])
         {
             config.editor_bgfilter_base_url = base_url;
@@ -1612,8 +1590,7 @@ fn parse_positive_u16(raw: &str) -> Option<u16> {
 #[cfg(test)]
 mod tests {
     use super::{
-        AppConfig, DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL,
-        DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS, DEFAULT_EDITOR_BGFILTER_BASE_URL,
+        AppConfig, DEFAULT_EDITOR_BGFILTER_BASE_URL,
         DEFAULT_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS,
         DEFAULT_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD,
         DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS,
@@ -1638,15 +1615,6 @@ mod tests {
         assert!(config.llm_base_url.is_empty());
         // assert!(config.apimart_base_url.is_empty());
         assert!(config.vector_engine_base_url.is_empty());
-        assert_eq!(
-            config.editor_background_removal_base_url,
-            DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL
-        );
-        assert_eq!(
-            config.editor_background_removal_request_timeout_ms,
-            DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS
-        );
-        assert!(config.editor_background_removal_token.is_none());
         assert_eq!(
             config.editor_bgfilter_base_url,
             DEFAULT_EDITOR_BGFILTER_BASE_URL
@@ -2387,46 +2355,6 @@ mod tests {
         }
     }
 
-    #[test]
-    fn from_env_reads_editor_background_removal_settings() {
-        let _guard = ENV_LOCK
-            .get_or_init(|| Mutex::new(()))
-            .lock()
-            .expect("env lock should not poison");
-
-        unsafe {
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL");
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN");
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS");
-            std::env::set_var(
-                "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL",
-                "http://10.0.0.12:8090",
-            );
-            std::env::set_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN", "token-1");
-            std::env::set_var(
-                "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS",
-                "90000",
-            );
-        }
-
-        let config = AppConfig::from_env();
-        assert_eq!(
-            config.editor_background_removal_base_url,
-            "http://10.0.0.12:8090"
-        );
-        assert_eq!(
-            config.editor_background_removal_token.as_deref(),
-            Some("token-1")
-        );
-        assert_eq!(config.editor_background_removal_request_timeout_ms, 90_000);
-
-        unsafe {
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL");
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN");
-            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS");
-        }
-    }
-
     #[test]
     fn from_env_reads_editor_bgfilter_settings_and_reuses_background_token() {
         let _guard = ENV_LOCK
diff --git a/server-rs/crates/api-server/src/editor_agent.rs b/server-rs/crates/api-server/src/editor_agent.rs
deleted file mode 100644
index 2eab230e6..000000000
--- a/server-rs/crates/api-server/src/editor_agent.rs
+++ /dev/null
@@ -1,2814 +0,0 @@
-use std::{
-    collections::BTreeMap,
-    convert::Infallible,
-    sync::{Arc, Mutex, OnceLock},
-};
-
-use axum::{
-    Json,
-    extract::{Extension, Path, State},
-    http::StatusCode,
-    response::{
-        IntoResponse, Response,
-        sse::{Event, Sse},
-    },
-};
-use module_editor_agent::{
-    EDITOR_AGENT_CONVERSATION_ID_PREFIX, EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE,
-    EDITOR_AGENT_MESSAGE_ID_PREFIX, derive_conversation_title, editor_agent_messages_object_key,
-    validate_user_message,
-};
-use platform_llm::{LlmError, LlmErrorKind, LlmMessage, LlmMessageContentPart, LlmRunRequest};
-use platform_oss::{
-    LegacyAssetPrefix, OssObjectAccess, OssPutObjectRequest, OssSignedGetObjectUrlRequest,
-};
-use serde::{Deserialize, Serialize};
-use serde_json::{Value, json};
-use shared_contracts::assets::{
-    EditorCanvasGenerationCompletionPayload, EditorCanvasGenerationPlaceholderPayload,
-};
-use shared_contracts::editor_agent::{
-    CreateEditorAgentConversationRequest, EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION,
-    EditorAgentAttachmentRef, EditorAgentAttachmentSource, EditorAgentConversationDetail,
-    EditorAgentConversationListResponse, EditorAgentConversationMessagesDocument,
-    EditorAgentConversationResponse, EditorAgentConversationSummary, EditorAgentDoneEvent,
-    EditorAgentErrorEvent, EditorAgentGeneratedImage, EditorAgentGenerationRecord,
-    EditorAgentGenerationResultEvent, EditorAgentGenerationStatus, EditorAgentMessage,
-    EditorAgentMessageDeltaEvent, EditorAgentMessageKind, EditorAgentMessageRole,
-    EditorAgentMessageStatus, EditorAgentStage, EditorAgentStageEvent, EditorAgentToolEvent,
-    EditorAgentToolName, StreamEditorAgentMessageRequest,
-};
-use shared_kernel::{build_prefixed_uuid_id, normalize_optional_string, normalize_required_string};
-use spacetime_client::{
-    EditorAgentConversationCreateRecordInput, EditorAgentConversationDeleteRecordInput,
-    EditorAgentConversationRecord, EditorAgentConversationTouchRecordInput,
-    EditorAssetLibraryRecord, EditorAssetRecord, EditorProjectGetRecordInput, EditorProjectRecord,
-    EditorProjectResourceRecord,
-};
-
-use crate::{
-    api_response::json_success_body,
-    auth::AuthenticatedAccessToken,
-    editor_project::{
-        EditorGenerationCaller, EditorIconSpritesheetGenerationRequest, EditorImageEditRequest,
-        EditorImageGenerationRequest, current_utc_micros, edit_editor_image_for_owner,
-        generate_editor_icon_spritesheet_for_owner, generate_editor_image_for_owner,
-        map_editor_project_error,
-    },
-    http_error::AppError,
-    platform_errors::map_oss_error,
-    request_context::RequestContext,
-    state::AppState,
-};
-
-const EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES: usize = 2 * 1024 * 1024;
-const EDITOR_AGENT_MESSAGES_READ_EXPIRE_SECONDS: u64 = 60;
-const EDITOR_AGENT_LLM_ATTACHMENT_URL_EXPIRE_SECONDS: u64 = 300;
-const EDITOR_AGENT_LLM_MAX_HISTORY_MESSAGES: usize = 12;
-const EDITOR_AGENT_LLM_PLANNING_MODEL: &str = platform_agent::CREATIVE_AGENT_GPT5_MODEL;
-const EDITOR_AGENT_LLM_MAX_OUTPUT_TOKENS: u32 = 1024;
-const EDITOR_AGENT_LLM_REQUEST_TIMEOUT_MS: u64 = 60_000;
-const EDITOR_AGENT_TOOL_CALL_ID_PREFIX: &str = "editor-agent-tool";
-const EDITOR_AGENT_CANVAS_RESULT_GAP: f64 = 32.0;
-type EditorAgentConversationLockMap = Mutex<BTreeMap<String, Arc<tokio::sync::Mutex<()>>>>;
-static EDITOR_AGENT_CONVERSATION_LOCKS: OnceLock<EditorAgentConversationLockMap> = OnceLock::new();
-
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "camelCase")]
-struct EditorAgentConversationDeleteResponse {
-    deleted_conversation_id: String,
-    conversation: EditorAgentConversationSummary,
-}
-
-pub async fn list_editor_agent_conversations(
-    State(state): State<AppState>,
-    Path(project_id): Path<String>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-) -> Result<Json<Value>, AppError> {
-    let owner_user_id = authenticated.claims().user_id().to_string();
-    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
-    ensure_editor_project_access(&state, project_id.as_str(), owner_user_id.as_str()).await?;
-    let conversations = state
-        .spacetime_client()
-        .list_editor_agent_conversations(project_id, owner_user_id)
-        .await
-        .map_err(map_editor_project_error)?
-        .into_iter()
-        .map(conversation_summary_from_record)
-        .collect();
-
-    Ok(json_success_body(
-        Some(&request_context),
-        EditorAgentConversationListResponse { conversations },
-    ))
-}
-
-pub async fn create_editor_agent_conversation(
-    State(state): State<AppState>,
-    Path(project_id): Path<String>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-    Json(payload): Json<CreateEditorAgentConversationRequest>,
-) -> Result<Json<Value>, AppError> {
-    let owner_user_id = authenticated.claims().user_id().to_string();
-    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
-    ensure_editor_project_access(&state, project_id.as_str(), owner_user_id.as_str()).await?;
-
-    let conversation_id = build_prefixed_uuid_id(EDITOR_AGENT_CONVERSATION_ID_PREFIX);
-    let messages_object_key = editor_agent_messages_object_key(conversation_id.as_str());
-    let title = normalize_optional_string(payload.title)
-        .unwrap_or_else(|| EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE.to_string());
-    let now_micros = current_utc_micros();
-    let seed_record = EditorAgentConversationRecord {
-        conversation_id: conversation_id.clone(),
-        project_id: project_id.clone(),
-        owner_user_id: owner_user_id.clone(),
-        title: title.clone(),
-        messages_object_key: messages_object_key.clone(),
-        deleted: false,
-        created_at: now_rfc3339(),
-        updated_at: now_rfc3339(),
-        updated_at_micros: now_micros,
-    };
-    write_messages_document(
-        &state,
-        &seed_record,
-        &empty_messages_document(conversation_id.as_str()),
-    )
-    .await?;
-
-    let conversation = state
-        .spacetime_client()
-        .create_editor_agent_conversation(EditorAgentConversationCreateRecordInput {
-            conversation_id,
-            project_id,
-            owner_user_id,
-            title,
-            messages_object_key,
-            created_at_micros: now_micros,
-        })
-        .await
-        .map_err(map_editor_project_error)?;
-    let document = read_messages_document(&state, &conversation).await?;
-
-    Ok(json_success_body(
-        Some(&request_context),
-        EditorAgentConversationResponse {
-            conversation: conversation_detail_from_record(conversation, document.messages),
-        },
-    ))
-}
-
-pub async fn get_editor_agent_conversation(
-    State(state): State<AppState>,
-    Path(conversation_id): Path<String>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-) -> Result<Json<Value>, AppError> {
-    let owner_user_id = authenticated.claims().user_id().to_string();
-    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
-    let conversation = state
-        .spacetime_client()
-        .get_editor_agent_conversation(conversation_id, owner_user_id)
-        .await
-        .map_err(map_editor_project_error)?;
-    let document = read_messages_document(&state, &conversation).await?;
-
-    Ok(json_success_body(
-        Some(&request_context),
-        EditorAgentConversationResponse {
-            conversation: conversation_detail_from_record(conversation, document.messages),
-        },
-    ))
-}
-
-pub async fn delete_editor_agent_conversation(
-    State(state): State<AppState>,
-    Path(conversation_id): Path<String>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-) -> Result<Json<Value>, AppError> {
-    let owner_user_id = authenticated.claims().user_id().to_string();
-    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
-    let conversation = state
-        .spacetime_client()
-        .delete_editor_agent_conversation(EditorAgentConversationDeleteRecordInput {
-            conversation_id,
-            owner_user_id,
-            updated_at_micros: current_utc_micros(),
-        })
-        .await
-        .map_err(map_editor_project_error)?;
-
-    Ok(json_success_body(
-        Some(&request_context),
-        EditorAgentConversationDeleteResponse {
-            deleted_conversation_id: conversation.conversation_id.clone(),
-            conversation: conversation_summary_from_record(conversation),
-        },
-    ))
-}
-
-pub async fn stream_editor_agent_message(
-    State(state): State<AppState>,
-    Path(conversation_id): Path<String>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
-    Json(payload): Json<StreamEditorAgentMessageRequest>,
-) -> Result<Response, AppError> {
-    let owner_user_id = authenticated.claims().user_id().to_string();
-    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
-    let client_message_id = normalize_required_string(payload.client_message_id.as_str())
-        .ok_or_else(|| editor_agent_bad_request("clientMessageId is required"))?;
-    let attachment_reference_ids = payload
-        .attachments
-        .iter()
-        .map(|attachment| attachment.reference_id.clone())
-        .collect::<Vec<_>>();
-    validate_user_message(payload.text.as_str(), &attachment_reference_ids)
-        .map_err(|error| editor_agent_bad_request(error.to_string()))?;
-
-    let conversation = state
-        .spacetime_client()
-        .get_editor_agent_conversation(conversation_id, owner_user_id.clone())
-        .await
-        .map_err(map_editor_project_error)?;
-    let attachments =
-        normalize_editor_agent_attachments(&state, &conversation, payload.attachments.as_slice())
-            .await?;
-    let conversation_lock = editor_agent_conversation_lock(conversation.conversation_id.as_str());
-    let conversation_lock_guard = conversation_lock.lock_owned().await;
-    let mut document = read_messages_document(&state, &conversation).await?;
-    if document
-        .messages
-        .iter()
-        .any(|message| message.id == client_message_id)
-    {
-        return Err(
-            AppError::from_status(StatusCode::CONFLICT).with_details(json!({
-                "provider": "editor-agent",
-                "field": "clientMessageId",
-                "message": "clientMessageId already exists in this conversation",
-            })),
-        );
-    }
-
-    let was_empty = document.messages.is_empty();
-    let user_message = EditorAgentMessage {
-        id: client_message_id,
-        role: EditorAgentMessageRole::User,
-        kind: EditorAgentMessageKind::Chat,
-        text: payload.text.trim().to_string(),
-        attachments,
-        generations: Vec::new(),
-        status: EditorAgentMessageStatus::Completed,
-        created_at: now_rfc3339(),
-    };
-    document.messages.push(user_message.clone());
-    write_messages_document(&state, &conversation, &document).await?;
-    let latest_generation_reference = latest_editor_agent_generated_image_reference(&document);
-
-    let assistant_message_id = build_prefixed_uuid_id(EDITOR_AGENT_MESSAGE_ID_PREFIX);
-    let stream_state = state.clone();
-    let stream_conversation = conversation.clone();
-    let stream_title = was_empty.then(|| derive_conversation_title(user_message.text.as_str()));
-    let stream_assistant_message_id = assistant_message_id.clone();
-    let stream_user_message = user_message.clone();
-    let stream_latest_generation_reference = latest_generation_reference.clone();
-    let stream_request_context = request_context.clone();
-    let stream_conversation_lock_guard = conversation_lock_guard;
-
-    let stream = async_stream::stream! {
-        let _conversation_lock_guard = stream_conversation_lock_guard;
-        yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-            "stage",
-            EditorAgentStageEvent {
-                conversation_id: stream_conversation.conversation_id.clone(),
-                stage: EditorAgentStage::Thinking,
-            },
-        ));
-
-        let mut assistant_status = EditorAgentMessageStatus::Completed;
-        let mut generation_records = Vec::new();
-        let mut planning_failed = false;
-
-        let turn_plan = match plan_editor_agent_turn(
-            &stream_state,
-            &stream_conversation,
-            &document,
-            &stream_user_message,
-            stream_latest_generation_reference.as_ref(),
-        )
-        .await {
-            Ok(turn_plan) => turn_plan,
-            Err(error) => {
-                let app_error = error.into_app_error();
-                let error_message = app_error.body_text();
-                assistant_status = EditorAgentMessageStatus::Failed;
-                planning_failed = true;
-                EditorAgentTurnPlan {
-                    reply_text: error_message,
-                    tool_call: None,
-                }
-            }
-        };
-        let assistant_text = turn_plan.reply_text;
-        let assistant_kind = if assistant_status == EditorAgentMessageStatus::Failed {
-            EditorAgentMessageKind::Error
-        } else {
-            EditorAgentMessageKind::Chat
-        };
-
-        yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-            "stage",
-            EditorAgentStageEvent {
-                conversation_id: stream_conversation.conversation_id.clone(),
-                stage: EditorAgentStage::Responding,
-            },
-        ));
-        yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-            "message_delta",
-            EditorAgentMessageDeltaEvent {
-                conversation_id: stream_conversation.conversation_id.clone(),
-                message_id: stream_assistant_message_id.clone(),
-                role: EditorAgentMessageRole::Assistant,
-                kind: assistant_kind,
-                text_delta: assistant_text.clone(),
-            },
-        ));
-        if planning_failed {
-            yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                "stage",
-                EditorAgentStageEvent {
-                    conversation_id: stream_conversation.conversation_id.clone(),
-                    stage: EditorAgentStage::Failed,
-                },
-            ));
-        }
-
-        if let Some(tool_call) = turn_plan.tool_call {
-            let tool_call_id = build_prefixed_uuid_id(EDITOR_AGENT_TOOL_CALL_ID_PREFIX);
-            let tool_summary = tool_call
-                .summary
-                .clone()
-                .or_else(|| Some(editor_agent_tool_default_summary(tool_call.tool_name)));
-            yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                "tool_started",
-                EditorAgentToolEvent {
-                    conversation_id: stream_conversation.conversation_id.clone(),
-                    message_id: stream_assistant_message_id.clone(),
-                    tool_call_id: tool_call_id.clone(),
-                    tool_name: tool_call.tool_name,
-                    summary: tool_summary.clone(),
-                    task_id: None,
-                    model: tool_call.model.clone(),
-                    status: Some(EditorAgentGenerationStatus::Generating),
-                    error: None,
-                },
-            ));
-            yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                "stage",
-                EditorAgentStageEvent {
-                    conversation_id: stream_conversation.conversation_id.clone(),
-                    stage: EditorAgentStage::Generating,
-                },
-            ));
-
-            match execute_editor_agent_tool_call(
-                &stream_state,
-                &stream_request_context,
-                &stream_conversation,
-                &stream_user_message,
-                &tool_call_id,
-                stream_latest_generation_reference.as_ref(),
-                tool_call,
-            )
-            .await
-            {
-                Ok(execution) => {
-                    generation_records.push(execution.record.clone());
-                    yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                        "generation_result",
-                        EditorAgentGenerationResultEvent {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            message_id: stream_assistant_message_id.clone(),
-                            tool_call_id: tool_call_id.clone(),
-                            tool_name: execution.record.tool_name,
-                            model: execution.record.model.clone(),
-                            images: execution.record.images.clone(),
-                        },
-                    ));
-                    yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                        "tool_completed",
-                        EditorAgentToolEvent {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            message_id: stream_assistant_message_id.clone(),
-                            tool_call_id,
-                            tool_name: execution.record.tool_name,
-                            summary: Some(execution.summary),
-                            task_id: execution.record.task_id.clone(),
-                            model: execution.record.model.clone(),
-                            status: Some(EditorAgentGenerationStatus::Completed),
-                            error: None,
-                        },
-                    ));
-                }
-                Err(error) => {
-                    let error_code = error.error.code().to_string();
-                    let error_message = error.error.body_text();
-                    let error_model = error.model.clone();
-                    assistant_status = EditorAgentMessageStatus::Failed;
-                    generation_records.push(EditorAgentGenerationRecord {
-                        tool_call_id: tool_call_id.clone(),
-                        tool_name: error.tool_name,
-                        summary: tool_summary.clone(),
-                        task_id: None,
-                        status: EditorAgentGenerationStatus::Failed,
-                        model: error_model.clone(),
-                        images: Vec::new(),
-                        error: Some(error_message.clone()),
-                    });
-                    yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                        "tool_completed",
-                        EditorAgentToolEvent {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            message_id: stream_assistant_message_id.clone(),
-                            tool_call_id,
-                            tool_name: error.tool_name,
-                            summary: tool_summary,
-                            task_id: None,
-                            model: error_model,
-                            status: Some(EditorAgentGenerationStatus::Failed),
-                            error: Some(error_message.clone()),
-                        },
-                    ));
-                    yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                        "stage",
-                        EditorAgentStageEvent {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            stage: EditorAgentStage::Failed,
-                        },
-                    ));
-                    yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                        "error",
-                        EditorAgentErrorEvent {
-                            conversation_id: Some(stream_conversation.conversation_id.clone()),
-                            code: error_code,
-                            message: error_message,
-                            recoverable: true,
-                        },
-                    ));
-                }
-            }
-        }
-
-        let write_result = async {
-            let mut next_document = read_messages_document(&stream_state, &stream_conversation).await?;
-            if !next_document
-                .messages
-                .iter()
-                .any(|message| message.id == stream_assistant_message_id)
-            {
-                next_document.messages.push(EditorAgentMessage {
-                    id: stream_assistant_message_id.clone(),
-                    role: EditorAgentMessageRole::Assistant,
-                    kind: if assistant_status == EditorAgentMessageStatus::Failed {
-                        EditorAgentMessageKind::Error
-                    } else {
-                        EditorAgentMessageKind::Chat
-                    },
-                    text: assistant_text,
-                    attachments: Vec::new(),
-                    generations: generation_records,
-                    status: assistant_status,
-                    created_at: now_rfc3339(),
-                });
-            }
-            write_messages_document(&stream_state, &stream_conversation, &next_document).await
-        }
-        .await;
-        match write_result {
-            Ok(()) => {
-                let mut done_title = None;
-                if let Some(title) = stream_title {
-                    match stream_state.spacetime_client().touch_editor_agent_conversation(
-                        EditorAgentConversationTouchRecordInput {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            owner_user_id: stream_conversation.owner_user_id.clone(),
-                            title: Some(title.clone()),
-                            updated_at_micros: current_utc_micros(),
-                        },
-                    ).await {
-                        Ok(updated) => done_title = Some(updated.title),
-                        Err(error) => {
-                            yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                                "error",
-                                EditorAgentErrorEvent {
-                                    conversation_id: Some(stream_conversation.conversation_id.clone()),
-                                    code: "SPACETIME_UPDATE_FAILED".to_string(),
-                                    message: error.to_string(),
-                                    recoverable: true,
-                                },
-                            ));
-                        }
-                    }
-                } else {
-                    match stream_state.spacetime_client().touch_editor_agent_conversation(
-                        EditorAgentConversationTouchRecordInput {
-                            conversation_id: stream_conversation.conversation_id.clone(),
-                            owner_user_id: stream_conversation.owner_user_id.clone(),
-                            title: None,
-                            updated_at_micros: current_utc_micros(),
-                        },
-                    ).await {
-                        Ok(_) => {}
-                        Err(error) => {
-                            yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                                "error",
-                                EditorAgentErrorEvent {
-                                    conversation_id: Some(stream_conversation.conversation_id.clone()),
-                                    code: "SPACETIME_UPDATE_FAILED".to_string(),
-                                    message: error.to_string(),
-                                    recoverable: true,
-                                },
-                            ));
-                        }
-                    }
-                }
-                yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                    "stage",
-                    EditorAgentStageEvent {
-                        conversation_id: stream_conversation.conversation_id.clone(),
-                        stage: EditorAgentStage::Completed,
-                    },
-                ));
-                yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                    "done",
-                    EditorAgentDoneEvent {
-                        conversation_id: stream_conversation.conversation_id.clone(),
-                        title: done_title,
-                    },
-                ));
-            }
-            Err(error) => {
-                yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                    "stage",
-                    EditorAgentStageEvent {
-                        conversation_id: stream_conversation.conversation_id.clone(),
-                        stage: EditorAgentStage::Failed,
-                    },
-                ));
-                yield Ok::<Event, Infallible>(editor_agent_sse_json_event_or_error(
-                    "error",
-                    EditorAgentErrorEvent {
-                        conversation_id: Some(stream_conversation.conversation_id.clone()),
-                        code: error.code().to_string(),
-                        message: error.body_text(),
-                        recoverable: true,
-                    },
-                ));
-            }
-        }
-    };
-
-    Ok(Sse::new(stream).into_response())
-}
-
-fn editor_agent_conversation_lock(conversation_id: &str) -> Arc<tokio::sync::Mutex<()>> {
-    let locks = EDITOR_AGENT_CONVERSATION_LOCKS.get_or_init(|| Mutex::new(BTreeMap::new()));
-    let mut locks = locks
-        .lock()
-        .unwrap_or_else(|poisoned| poisoned.into_inner());
-    locks
-        .entry(conversation_id.to_string())
-        .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
-        .clone()
-}
-
-async fn ensure_editor_project_access(
-    state: &AppState,
-    project_id: &str,
-    owner_user_id: &str,
-) -> Result<(), AppError> {
-    state
-        .spacetime_client()
-        .get_editor_project(EditorProjectGetRecordInput {
-            project_id: project_id.to_string(),
-            owner_user_id: owner_user_id.to_string(),
-        })
-        .await
-        .map(|_| ())
-        .map_err(map_editor_project_error)
-}
-
-async fn normalize_editor_agent_attachments(
-    state: &AppState,
-    conversation: &EditorAgentConversationRecord,
-    attachments: &[EditorAgentAttachmentRef],
-) -> Result<Vec<EditorAgentAttachmentRef>, AppError> {
-    if attachments.is_empty() {
-        return Ok(Vec::new());
-    }
-
-    let needs_canvas_resources = attachments
-        .iter()
-        .any(|attachment| attachment.source == EditorAgentAttachmentSource::CanvasResource);
-    let needs_library_assets = attachments
-        .iter()
-        .any(|attachment| attachment.source == EditorAgentAttachmentSource::LibraryAsset);
-
-    let project = if needs_canvas_resources {
-        Some(
-            state
-                .spacetime_client()
-                .get_editor_project(EditorProjectGetRecordInput {
-                    project_id: conversation.project_id.clone(),
-                    owner_user_id: conversation.owner_user_id.clone(),
-                })
-                .await
-                .map_err(map_editor_project_error)?,
-        )
-    } else {
-        None
-    };
-    let library = if needs_library_assets {
-        Some(
-            state
-                .spacetime_client()
-                .get_editor_asset_library(conversation.owner_user_id.clone(), current_utc_micros())
-                .await
-                .map_err(map_editor_project_error)?,
-        )
-    } else {
-        None
-    };
-
-    attachments
-        .iter()
-        .map(|attachment| {
-            normalize_editor_agent_attachment(
-                conversation,
-                project.as_ref(),
-                library.as_ref(),
-                attachment,
-            )
-        })
-        .collect()
-}
-
-fn normalize_editor_agent_attachment(
-    conversation: &EditorAgentConversationRecord,
-    project: Option<&EditorProjectRecord>,
-    library: Option<&EditorAssetLibraryRecord>,
-    attachment: &EditorAgentAttachmentRef,
-) -> Result<EditorAgentAttachmentRef, AppError> {
-    let reference_id = normalize_required_string(attachment.reference_id.as_str())
-        .ok_or_else(|| editor_agent_bad_request("attachment.referenceId is required"))?;
-    match attachment.source {
-        EditorAgentAttachmentSource::CanvasResource => {
-            let project = project.ok_or_else(|| {
-                editor_agent_bad_request("canvas resource attachment project context missing")
-            })?;
-            let resource = project
-                .resources
-                .iter()
-                .find(|resource| resource.resource_id == reference_id)
-                .ok_or_else(|| {
-                    editor_agent_bad_request(format!(
-                        "canvas resource attachment not found in current project: {reference_id}"
-                    ))
-                })?;
-            normalize_canvas_resource_attachment(conversation, attachment, resource)
-        }
-        EditorAgentAttachmentSource::LibraryAsset => {
-            let library = library.ok_or_else(|| {
-                editor_agent_bad_request("library asset attachment context missing")
-            })?;
-            let asset = library
-                .assets
-                .iter()
-                .find(|asset| asset.asset_id == reference_id)
-                .ok_or_else(|| {
-                    editor_agent_bad_request(format!(
-                        "library asset attachment not found for current user: {reference_id}"
-                    ))
-                })?;
-            normalize_library_asset_attachment(attachment, asset)
-        }
-    }
-}
-
-fn normalize_canvas_resource_attachment(
-    conversation: &EditorAgentConversationRecord,
-    attachment: &EditorAgentAttachmentRef,
-    resource: &EditorProjectResourceRecord,
-) -> Result<EditorAgentAttachmentRef, AppError> {
-    if resource.project_id != conversation.project_id
-        || resource.owner_user_id != conversation.owner_user_id
-    {
-        return Err(editor_agent_bad_request(
-            "canvas resource attachment does not belong to this conversation project",
-        ));
-    }
-    validate_attachment_object_key(
-        attachment.object_key.as_deref(),
-        resource.object_key.as_deref(),
-        resource.resource_id.as_str(),
-    )?;
-
-    Ok(EditorAgentAttachmentRef {
-        source: EditorAgentAttachmentSource::CanvasResource,
-        reference_id: resource.resource_id.clone(),
-        object_key: resource.object_key.clone(),
-        image_src: resource.image_src.clone(),
-        thumbnail_src: None,
-        label: normalize_optional_string(attachment.label.clone()),
-        width: Some(resource.width),
-        height: Some(resource.height),
-    })
-}
-
-fn normalize_library_asset_attachment(
-    attachment: &EditorAgentAttachmentRef,
-    asset: &EditorAssetRecord,
-) -> Result<EditorAgentAttachmentRef, AppError> {
-    validate_attachment_object_key(
-        attachment.object_key.as_deref(),
-        asset.object_key.as_deref(),
-        asset.asset_id.as_str(),
-    )?;
-
-    Ok(EditorAgentAttachmentRef {
-        source: EditorAgentAttachmentSource::LibraryAsset,
-        reference_id: asset.asset_id.clone(),
-        object_key: asset.object_key.clone(),
-        image_src: asset.image_src.clone(),
-        thumbnail_src: asset.thumbnail_src.clone(),
-        label: normalize_optional_string(attachment.label.clone())
-            .or_else(|| Some(asset.label.clone())),
-        width: Some(asset.width),
-        height: Some(asset.height),
-    })
-}
-
-fn validate_attachment_object_key(
-    submitted_object_key: Option<&str>,
-    stored_object_key: Option<&str>,
-    reference_id: &str,
-) -> Result<(), AppError> {
-    let Some(submitted_object_key) = submitted_object_key.and_then(normalize_required_string)
-    else {
-        return Ok(());
-    };
-    let Some(stored_object_key) = stored_object_key.and_then(normalize_required_string) else {
-        return Err(editor_agent_bad_request(format!(
-            "attachment objectKey is not available for reference: {reference_id}"
-        )));
-    };
-    if submitted_object_key != stored_object_key {
-        return Err(editor_agent_bad_request(format!(
-            "attachment objectKey does not match reference: {reference_id}"
-        )));
-    }
-    Ok(())
-}
-
-fn conversation_summary_from_record(
-    conversation: EditorAgentConversationRecord,
-) -> EditorAgentConversationSummary {
-    EditorAgentConversationSummary {
-        conversation_id: conversation.conversation_id,
-        project_id: conversation.project_id,
-        title: conversation.title,
-        created_at: conversation.created_at,
-        updated_at: conversation.updated_at,
-    }
-}
-
-fn conversation_detail_from_record(
-    conversation: EditorAgentConversationRecord,
-    messages: Vec<EditorAgentMessage>,
-) -> EditorAgentConversationDetail {
-    EditorAgentConversationDetail {
-        conversation_id: conversation.conversation_id,
-        project_id: conversation.project_id,
-        title: conversation.title,
-        created_at: conversation.created_at,
-        updated_at: conversation.updated_at,
-        messages,
-    }
-}
-
-fn empty_messages_document(conversation_id: &str) -> EditorAgentConversationMessagesDocument {
-    EditorAgentConversationMessagesDocument {
-        version: EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION,
-        conversation_id: conversation_id.to_string(),
-        messages: Vec::new(),
-    }
-}
-
-async fn read_messages_document(
-    state: &AppState,
-    conversation: &EditorAgentConversationRecord,
-) -> Result<EditorAgentConversationMessagesDocument, AppError> {
-    let oss_client = state
-        .oss_client()
-        .ok_or_else(editor_agent_oss_unavailable)?;
-    let signed = oss_client
-        .sign_internal_get_object_url(OssSignedGetObjectUrlRequest {
-            object_key: conversation.messages_object_key.clone(),
-            expire_seconds: Some(EDITOR_AGENT_MESSAGES_READ_EXPIRE_SECONDS),
-        })
-        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
-    let response = reqwest::Client::new()
-        .get(signed.signed_url.as_str())
-        .send()
-        .await
-        .map_err(|error| editor_agent_oss_read_error(error.to_string()))?;
-    if response.status() == reqwest::StatusCode::NOT_FOUND {
-        return Ok(empty_messages_document(
-            conversation.conversation_id.as_str(),
-        ));
-    }
-    if !response.status().is_success() {
-        return Err(editor_agent_oss_read_error(format!(
-            "OSS returned non-success status {}",
-            response.status().as_u16()
-        )));
-    }
-    if response
-        .content_length()
-        .is_some_and(|size| size > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES as u64)
-    {
-        return Err(editor_agent_messages_document_too_large());
-    }
-    let bytes = response
-        .bytes()
-        .await
-        .map_err(|error| editor_agent_oss_read_error(error.to_string()))?;
-    if bytes.is_empty() {
-        return Ok(empty_messages_document(
-            conversation.conversation_id.as_str(),
-        ));
-    }
-    if bytes.len() > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES {
-        return Err(editor_agent_messages_document_too_large());
-    }
-    let document: EditorAgentConversationMessagesDocument = serde_json::from_slice(&bytes)
-        .map_err(|error| {
-            editor_agent_oss_read_error(format!("message document JSON invalid: {error}"))
-        })?;
-    if document.conversation_id != conversation.conversation_id {
-        return Err(
-            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": "editor-agent",
-                "message": "message document conversationId does not match metadata",
-                "conversationId": conversation.conversation_id,
-                "documentConversationId": document.conversation_id,
-            })),
-        );
-    }
-    Ok(document)
-}
-
-async fn write_messages_document(
-    state: &AppState,
-    conversation: &EditorAgentConversationRecord,
-    document: &EditorAgentConversationMessagesDocument,
-) -> Result<(), AppError> {
-    if document.conversation_id != conversation.conversation_id {
-        return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "editor-agent",
-                "message": "message document conversationId does not match metadata",
-            })),
-        );
-    }
-    let body = serde_json::to_vec(document).map_err(|error| {
-        AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
-            "provider": "editor-agent",
-            "message": format!("failed to serialize message document: {error}"),
-        }))
-    })?;
-    if body.len() > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES {
-        return Err(editor_agent_messages_document_too_large());
-    }
-
-    let oss_client = state
-        .oss_client()
-        .ok_or_else(editor_agent_oss_unavailable)?;
-    let put_result = oss_client
-        .put_object(
-            &reqwest::Client::new(),
-            OssPutObjectRequest {
-                prefix: LegacyAssetPrefix::EditorAgent,
-                path_segments: Vec::new(),
-                file_name: format!("{}.json", conversation.conversation_id),
-                content_type: Some("application/json; charset=utf-8".to_string()),
-                access: OssObjectAccess::Private,
-                metadata: BTreeMap::from([
-                    (
-                        "conversation-id".to_string(),
-                        conversation.conversation_id.clone(),
-                    ),
-                    ("project-id".to_string(), conversation.project_id.clone()),
-                    (
-                        "owner-user-id".to_string(),
-                        conversation.owner_user_id.clone(),
-                    ),
-                ]),
-                body,
-            },
-        )
-        .await
-        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
-    if put_result.object_key != conversation.messages_object_key {
-        return Err(
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
-                "provider": "editor-agent",
-                "message": "OSS object key mismatch while writing message document",
-                "expectedObjectKey": conversation.messages_object_key,
-                "actualObjectKey": put_result.object_key,
-            })),
-        );
-    }
-    Ok(())
-}
-
-#[derive(Clone, Debug, PartialEq)]
-struct EditorAgentTurnPlan {
-    reply_text: String,
-    tool_call: Option<EditorAgentToolCallPlan>,
-}
-
-#[derive(Clone, Debug, PartialEq)]
-struct EditorAgentToolCallPlan {
-    tool_name: EditorAgentToolName,
-    prompt: String,
-    summary: Option<String>,
-    model: Option<String>,
-    aspect_ratio: Option<String>,
-    image_size: Option<String>,
-    icon_descriptions: Vec<String>,
-}
-
-#[derive(Debug, Deserialize)]
-#[serde(rename_all = "camelCase")]
-struct EditorAgentRawTurnPlan {
-    reply_text: Option<String>,
-    tool_call: Option<EditorAgentRawToolCallPlan>,
-}
-
-#[derive(Debug, Deserialize)]
-#[serde(rename_all = "camelCase")]
-struct EditorAgentRawToolCallPlan {
-    tool_name: EditorAgentToolName,
-    prompt: Option<String>,
-    summary: Option<String>,
-    model: Option<String>,
-    aspect_ratio: Option<String>,
-    image_size: Option<String>,
-    icon_descriptions: Option<Vec<String>>,
-}
-
-#[derive(Debug)]
-struct EditorAgentToolExecution {
-    record: EditorAgentGenerationRecord,
-    summary: String,
-}
-
-#[derive(Clone, Debug)]
-struct EditorAgentGeneratedImageReference {
-    source_message_id: String,
-    tool_call_id: String,
-    tool_name: EditorAgentToolName,
-    summary: Option<String>,
-    model: Option<String>,
-    resource_id: Option<String>,
-    object_key: Option<String>,
-    asset_object_id: Option<String>,
-    image_src: String,
-    thumbnail_src: Option<String>,
-    width: Option<u32>,
-    height: Option<u32>,
-}
-
-#[derive(Debug)]
-struct EditorAgentToolExecutionError {
-    tool_name: EditorAgentToolName,
-    model: Option<String>,
-    error: AppError,
-}
-
-#[derive(Debug)]
-enum EditorAgentPlanningError {
-    LlmUnavailable,
-    LlmRequestFailed(LlmError),
-    InvalidLlmResponse,
-}
-
-impl EditorAgentPlanningError {
-    fn into_app_error(self) -> AppError {
-        match self {
-            Self::LlmUnavailable => AppError::from_status(StatusCode::SERVICE_UNAVAILABLE)
-                .with_details(json!({
-                    "provider": "editor-agent-llm",
-                    "message": "画布 Agent 的 LLM 未配置，无法处理这句话。",
-                })),
-            Self::LlmRequestFailed(error) => {
-                let status = match error.kind() {
-                    LlmErrorKind::Timeout => StatusCode::GATEWAY_TIMEOUT,
-                    LlmErrorKind::InvalidConfig | LlmErrorKind::InvalidRequest => {
-                        StatusCode::SERVICE_UNAVAILABLE
-                    }
-                    LlmErrorKind::Connectivity
-                    | LlmErrorKind::Upstream
-                    | LlmErrorKind::StreamUnavailable
-                    | LlmErrorKind::EmptyResponse
-                    | LlmErrorKind::Transport
-                    | LlmErrorKind::Deserialize => StatusCode::BAD_GATEWAY,
-                };
-                AppError::from_status(status).with_details(json!({
-                    "provider": "editor-agent-llm",
-                    "message": format!("画布 Agent 调用 LLM 失败：{error}"),
-                }))
-            }
-            Self::InvalidLlmResponse => AppError::from_status(StatusCode::BAD_GATEWAY)
-                .with_details(json!({
-                    "provider": "editor-agent-llm",
-                    "message": "画布 Agent 的 LLM 返回格式错误，未能解析回复。",
-                })),
-        }
-    }
-}
-
-async fn plan_editor_agent_turn(
-    state: &AppState,
-    conversation: &EditorAgentConversationRecord,
-    document: &EditorAgentConversationMessagesDocument,
-    user_message: &EditorAgentMessage,
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-) -> Result<EditorAgentTurnPlan, EditorAgentPlanningError> {
-    let Some(llm_client) = state.creative_agent_gpt5_client() else {
-        return Err(EditorAgentPlanningError::LlmUnavailable);
-    };
-
-    let request = build_editor_agent_llm_request(
-        state,
-        conversation,
-        document,
-        user_message,
-        latest_generation_reference,
-    )
-    .await;
-    let response = llm_client
-        .run(request)
-        .await
-        .map_err(EditorAgentPlanningError::LlmRequestFailed)?;
-    parse_editor_agent_turn_plan(response.text.as_str())
-        .map(|plan| {
-            apply_previous_generation_edit_default(plan, user_message, latest_generation_reference)
-        })
-        .ok_or(EditorAgentPlanningError::InvalidLlmResponse)
-}
-
-async fn build_editor_agent_llm_request(
-    state: &AppState,
-    conversation: &EditorAgentConversationRecord,
-    document: &EditorAgentConversationMessagesDocument,
-    user_message: &EditorAgentMessage,
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-) -> LlmRunRequest {
-    let mut user_parts = vec![LlmMessageContentPart::InputText {
-        text: build_editor_agent_llm_user_prompt(
-            conversation,
-            document,
-            user_message,
-            latest_generation_reference,
-        ),
-    }];
-    for attachment in &user_message.attachments {
-        if let Some(image_url) = sign_editor_agent_attachment_image_url(state, attachment) {
-            user_parts.push(LlmMessageContentPart::InputImage { image_url });
-        }
-    }
-    if user_message.attachments.is_empty()
-        && editor_agent_text_mentions_previous_generation(user_message.text.as_str())
-    {
-        if let Some(reference) = latest_generation_reference {
-            if let Some(image_url) = sign_editor_agent_generated_image_url(state, reference) {
-                user_parts.push(LlmMessageContentPart::InputImage { image_url });
-            }
-        }
-    }
-
-    LlmRunRequest::new(vec![
-        LlmMessage::system(editor_agent_llm_system_prompt()),
-        LlmMessage::user_multimodal(user_parts),
-    ])
-    .with_model(EDITOR_AGENT_LLM_PLANNING_MODEL)
-    .with_openai_chat()
-    .with_max_output_tokens(EDITOR_AGENT_LLM_MAX_OUTPUT_TOKENS)
-    .with_request_timeout_ms(EDITOR_AGENT_LLM_REQUEST_TIMEOUT_MS)
-}
-
-fn editor_agent_llm_system_prompt() -> String {
-    [
-        "你是 Genarrative 图片画布 Agent，只负责帮助用户理解、规划和触发画布生成工具。",
-        "必须只输出一个 JSON 对象，不要输出 Markdown、解释或额外文本。",
-        "JSON 结构：{\"replyText\":\"给用户看的中文回复\",\"toolCall\":null 或 {\"toolName\":\"generate_image|edit_image|generate_character|generate_icon_spritesheet|generate_ui_design\",\"prompt\":\"生成或修改提示词\",\"summary\":\"短动作摘要\",\"model\":null,\"aspectRatio\":null,\"imageSize\":\"1K\",\"iconDescriptions\":[\"图标描述\"]}}。",
-        "只有用户明确要求生成、重绘、修改、画 UI、出角色或图标时才给 toolCall；普通咨询、评价、解释时 toolCall 为 null。",
-        "工具说明：",
-        "generate_image：从文字生成一张全新图片，适合新场景、新物体、新插画、新背景、规范图/视觉规范图/风格规范图/素材规范展板；不要用于修改上一张图或附件图。prompt 必须写完整画面、主体、风格、构图和背景。",
-        "edit_image：修改已有图片，适合换衣服、改颜色、替换背景、局部重绘、保持主体/构图/姿势不变的编辑请求；必须使用 latestAttachments 或 latestGeneratedImage 作为源图。",
-        "generate_character：生成新的角色形象、人物立绘或角色设定图；如果用户是在改上一张角色图的服装、颜色、表情、姿势或背景，应改用 edit_image。",
-        "generate_icon_spritesheet：生成一组图标素材或图标图集，适合用户明确要多个 icon / 图标 / spritesheet；必须有 latestAttachments 作为图标规范或风格参考，并填写 iconDescriptions。",
-        "generate_ui_design：生成一张完整 UI 设计图或界面稿，适合 HUD、弹窗、面板、按钮组合和整页界面；不要用于提取图标、拆素材或修改上一张图。",
-        "规范图要求：用户要求生成规范图/视觉规范图/风格规范图/素材规范展板时，当前使用 generate_image；prompt 必须明确这是规范展板，并写入统一视角、线条粗细、描边、填充风格、材质、阴影、圆角、状态层级、色卡/色号、尺寸标注和排版层级。",
-        "角色规范图/角色美术视觉规范设定图属于规范展板时使用 generate_image，prompt 要包含头身比例、标准立绘、动作帧样例、服饰配饰分层和专属角色色卡；只有用户要生成单个全新角色形象/立绘/普通角色设定图时才使用 generate_character。",
-        "图标规范图/图标视觉规范展板属于规范展板时使用 generate_image；只有用户明确要生成多个图标成品、图标素材图集或 spritesheet，并提供图标规范/风格参考附件时才使用 generate_icon_spritesheet。",
-        "UI 规范图/组件规范展板如果是规范展板而非完整可用界面稿，也使用 generate_image；完整界面稿/HUD/弹窗/面板才使用 generate_ui_design。",
-        "工具选择优先级：明确修改/指代已有图 => edit_image；规范图/视觉规范图/风格规范图/素材规范展板 => generate_image；明确新角色且不是规范展板或修改已有图 => generate_character；多个图标成品/图标图集 => generate_icon_spritesheet；完整界面稿 => generate_ui_design；其他全新图片 => generate_image。",
-        "edit_image 必须依赖 latestAttachments 或 latestGeneratedImage；generate_icon_spritesheet 必须依赖 latestAttachments。",
-        "当 latestGeneratedImage 存在，且用户说“这张/刚才那个/上一张/把衣服换成/改成/换成/修改上一张图”等指代或修改上一轮结果的话，必须选择 edit_image，prompt 保留用户修改要求，不要要求用户重新选择参考图，也不要降级成 generate_image。",
-        "没有 latestAttachments 且没有 latestGeneratedImage 时，不要调用 edit_image 或 generate_icon_spritesheet，应在 replyText 中提示先选择参考图。",
-        "generate_ui_design 表示生成一张 UI 设计图，不是提取 UI 素材。",
-        "对话回复要简短，不能承诺免费生成；生成工具由后端按模型定价扣泥点。",
-    ]
-    .join("\n")
-}
-
-fn build_editor_agent_llm_user_prompt(
-    conversation: &EditorAgentConversationRecord,
-    document: &EditorAgentConversationMessagesDocument,
-    user_message: &EditorAgentMessage,
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-) -> String {
-    let history = document
-        .messages
-        .iter()
-        .rev()
-        .take(EDITOR_AGENT_LLM_MAX_HISTORY_MESSAGES)
-        .collect::<Vec<_>>()
-        .into_iter()
-        .rev()
-        .map(|message| {
-            json!({
-                "role": message.role,
-                "kind": message.kind,
-                "text": message.text,
-                "attachmentCount": message.attachments.len(),
-                "generationCount": message.generations.len(),
-                "generations": message
-                    .generations
-                    .iter()
-                    .map(editor_agent_generation_context_json)
-                    .collect::<Vec<_>>(),
-            })
-        })
-        .collect::<Vec<_>>();
-    let attachments = user_message
-        .attachments
-        .iter()
-        .map(|attachment| {
-            json!({
-                "source": attachment.source,
-                "referenceId": attachment.reference_id,
-                "label": attachment.label,
-                "width": attachment.width,
-                "height": attachment.height,
-                "hasObjectKey": attachment.object_key.as_ref().is_some_and(|value| !value.trim().is_empty()),
-            })
-        })
-        .collect::<Vec<_>>();
-
-    json!({
-        "conversationId": conversation.conversation_id,
-        "projectId": conversation.project_id,
-        "latestUserText": user_message.text,
-        "latestAttachments": attachments,
-        "latestGeneratedImage": latest_generation_reference
-            .map(editor_agent_generated_image_reference_context_json),
-        "recentMessages": history,
-    })
-    .to_string()
-}
-
-fn editor_agent_generation_context_json(generation: &EditorAgentGenerationRecord) -> Value {
-    json!({
-        "toolCallId": generation.tool_call_id,
-        "toolName": generation.tool_name,
-        "summary": generation.summary,
-        "status": generation.status,
-        "model": generation.model,
-        "images": generation.images.iter().take(4).map(|image| json!({
-            "resourceId": image.resource_id,
-            "objectKey": image.object_key,
-            "assetObjectId": image.asset_object_id,
-            "imageSrc": image.image_src,
-            "thumbnailSrc": image.thumbnail_src,
-            "width": image.width,
-            "height": image.height,
-            "hasObjectKey": image.object_key.as_ref().is_some_and(|value| !value.trim().is_empty()),
-        })).collect::<Vec<_>>(),
-    })
-}
-
-fn editor_agent_generated_image_reference_context_json(
-    reference: &EditorAgentGeneratedImageReference,
-) -> Value {
-    json!({
-        "sourceMessageId": reference.source_message_id,
-        "toolCallId": reference.tool_call_id,
-        "toolName": reference.tool_name,
-        "summary": reference.summary,
-        "model": reference.model,
-        "resourceId": reference.resource_id,
-        "objectKey": reference.object_key,
-        "assetObjectId": reference.asset_object_id,
-        "imageSrc": reference.image_src,
-        "thumbnailSrc": reference.thumbnail_src,
-        "width": reference.width,
-        "height": reference.height,
-        "hasObjectKey": reference.object_key.as_ref().is_some_and(|value| !value.trim().is_empty()),
-    })
-}
-
-fn sign_editor_agent_attachment_image_url(
-    state: &AppState,
-    attachment: &EditorAgentAttachmentRef,
-) -> Option<String> {
-    let object_key = attachment
-        .object_key
-        .as_deref()
-        .map(str::trim)
-        .filter(|value| !value.is_empty())?;
-    state
-        .oss_client()?
-        .sign_get_object_url(OssSignedGetObjectUrlRequest {
-            object_key: object_key.trim_start_matches('/').to_string(),
-            expire_seconds: Some(EDITOR_AGENT_LLM_ATTACHMENT_URL_EXPIRE_SECONDS),
-        })
-        .ok()
-        .map(|signed| signed.signed_url)
-}
-
-fn sign_editor_agent_generated_image_url(
-    state: &AppState,
-    reference: &EditorAgentGeneratedImageReference,
-) -> Option<String> {
-    let object_key = reference
-        .object_key
-        .as_deref()
-        .map(str::trim)
-        .filter(|value| !value.is_empty())?;
-    state
-        .oss_client()?
-        .sign_get_object_url(OssSignedGetObjectUrlRequest {
-            object_key: object_key.trim_start_matches('/').to_string(),
-            expire_seconds: Some(EDITOR_AGENT_LLM_ATTACHMENT_URL_EXPIRE_SECONDS),
-        })
-        .ok()
-        .map(|signed| signed.signed_url)
-}
-
-fn latest_editor_agent_generated_image_reference(
-    document: &EditorAgentConversationMessagesDocument,
-) -> Option<EditorAgentGeneratedImageReference> {
-    document.messages.iter().rev().find_map(|message| {
-        message
-            .generations
-            .iter()
-            .rev()
-            .filter(|generation| generation.status == EditorAgentGenerationStatus::Completed)
-            .find_map(|generation| {
-                generation.images.iter().rev().find_map(|image| {
-                    let has_reference_source = image
-                        .object_key
-                        .as_deref()
-                        .is_some_and(|value| !value.trim().is_empty())
-                        || image
-                            .resource_id
-                            .as_deref()
-                            .is_some_and(|value| !value.trim().is_empty())
-                        || !image.image_src.trim().is_empty();
-                    has_reference_source.then(|| EditorAgentGeneratedImageReference {
-                        source_message_id: message.id.clone(),
-                        tool_call_id: generation.tool_call_id.clone(),
-                        tool_name: generation.tool_name,
-                        summary: generation.summary.clone(),
-                        model: generation.model.clone(),
-                        resource_id: image.resource_id.clone(),
-                        object_key: image.object_key.clone(),
-                        asset_object_id: image.asset_object_id.clone(),
-                        image_src: image.image_src.clone(),
-                        thumbnail_src: image.thumbnail_src.clone(),
-                        width: image.width,
-                        height: image.height,
-                    })
-                })
-            })
-    })
-}
-
-fn editor_agent_generated_reference_source(
-    reference: &EditorAgentGeneratedImageReference,
-) -> Option<String> {
-    reference
-        .object_key
-        .as_deref()
-        .map(str::trim)
-        .filter(|value| !value.is_empty())
-        .map(|value| value.trim_start_matches('/').to_string())
-        .or_else(|| {
-            reference
-                .resource_id
-                .as_deref()
-                .map(str::trim)
-                .filter(|value| !value.is_empty())
-                .map(ToOwned::to_owned)
-        })
-        .or_else(|| {
-            reference
-                .image_src
-                .trim()
-                .strip_prefix('/')
-                .map(str::to_string)
-                .filter(|value| !value.is_empty())
-        })
-}
-
-fn editor_agent_text_mentions_previous_generation(text: &str) -> bool {
-    let normalized = text.trim().to_lowercase();
-    contains_any(
-        normalized.as_str(),
-        &[
-            "这张",
-            "这个图",
-            "这幅",
-            "这张图",
-            "刚才",
-            "刚刚",
-            "刚才那个",
-            "刚才那张",
-            "上一张",
-            "上张",
-            "上一幅",
-            "上一个",
-            "前一张",
-            "上次生成",
-            "刚生成",
-            "latest image",
-            "previous image",
-            "last image",
-        ],
-    )
-}
-
-fn editor_agent_text_requests_previous_generation_edit(text: &str) -> bool {
-    let normalized = text.trim().to_lowercase();
-    if editor_agent_text_mentions_previous_generation(normalized.as_str())
-        && contains_any(
-            normalized.as_str(),
-            &[
-                "修改", "改成", "换成", "替换", "重绘", "编辑", "优化", "去掉", "加上", "增加",
-                "变成", "调整", "换一", "换掉", "remove", "change", "edit", "redraw",
-            ],
-        )
-    {
-        return true;
-    }
-
-    let has_visual_target = contains_any(
-        normalized.as_str(),
-        &[
-            "衣服", "服装", "发型", "头发", "背景", "颜色", "色调", "表情", "姿势", "主体", "风格",
-            "脸", "眼睛", "帽子", "鞋", "裙子", "外套",
-        ],
-    );
-    let has_edit_verb = contains_any(
-        normalized.as_str(),
-        &[
-            "换", "改", "变", "加", "去", "删", "替换", "调整", "change", "edit", "remove",
-        ],
-    );
-    has_visual_target && has_edit_verb
-}
-
-fn apply_previous_generation_edit_default(
-    mut plan: EditorAgentTurnPlan,
-    user_message: &EditorAgentMessage,
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-) -> EditorAgentTurnPlan {
-    if latest_generation_reference.is_none()
-        || !user_message.attachments.is_empty()
-        || !editor_agent_text_requests_previous_generation_edit(user_message.text.as_str())
-    {
-        return plan;
-    }
-
-    let should_force_edit = plan
-        .tool_call
-        .as_ref()
-        .is_none_or(|tool_call| tool_call.tool_name != EditorAgentToolName::EditImage);
-    if !should_force_edit {
-        return plan;
-    }
-
-    let original_tool = plan.tool_call.take();
-    let prompt = original_tool
-        .as_ref()
-        .map(|tool_call| tool_call.prompt.clone())
-        .unwrap_or_else(|| user_message.text.trim().to_string());
-    let summary = original_tool
-        .as_ref()
-        .and_then(|tool_call| tool_call.summary.clone())
-        .or_else(|| Some("修改上一张图".to_string()));
-    let model = original_tool
-        .as_ref()
-        .and_then(|tool_call| tool_call.model.clone());
-    let image_size = original_tool
-        .as_ref()
-        .and_then(|tool_call| tool_call.image_size.clone())
-        .or_else(|| Some("1K".to_string()));
-
-    plan.reply_text = "我会基于上一张生成图按你的要求修改。".to_string();
-    plan.tool_call = Some(EditorAgentToolCallPlan {
-        tool_name: EditorAgentToolName::EditImage,
-        prompt,
-        summary,
-        model,
-        aspect_ratio: None,
-        image_size,
-        icon_descriptions: Vec::new(),
-    });
-    plan
-}
-
-fn parse_editor_agent_turn_plan(raw_text: &str) -> Option<EditorAgentTurnPlan> {
-    let json_text = extract_editor_agent_json_object(raw_text)?;
-    let raw: EditorAgentRawTurnPlan = serde_json::from_str(json_text).ok()?;
-    let tool_call = match raw.tool_call {
-        Some(tool) => {
-            let prompt = normalize_optional_string(tool.prompt)?;
-            Some(EditorAgentToolCallPlan {
-                tool_name: tool.tool_name,
-                prompt,
-                summary: normalize_optional_string(tool.summary),
-                model: normalize_optional_string(tool.model),
-                aspect_ratio: normalize_optional_string(tool.aspect_ratio),
-                image_size: normalize_optional_string(tool.image_size),
-                icon_descriptions: tool
-                    .icon_descriptions
-                    .unwrap_or_default()
-                    .into_iter()
-                    .filter_map(|description| normalize_optional_string(Some(description)))
-                    .collect(),
-            })
-        }
-        None => None,
-    };
-    let reply_text = normalize_editor_agent_reply_text(raw.reply_text, tool_call.as_ref())?;
-
-    Some(EditorAgentTurnPlan {
-        reply_text,
-        tool_call,
-    })
-}
-
-fn extract_editor_agent_json_object(raw_text: &str) -> Option<&str> {
-    let trimmed = raw_text.trim();
-    let without_fence = if let Some(rest) = trimmed.strip_prefix("```json") {
-        rest.strip_suffix("```").unwrap_or(rest).trim()
-    } else if let Some(rest) = trimmed.strip_prefix("```") {
-        rest.strip_suffix("```").unwrap_or(rest).trim()
-    } else {
-        trimmed
-    };
-    let start = without_fence.find('{')?;
-    let end = without_fence.rfind('}')?;
-    (start <= end).then_some(&without_fence[start..=end])
-}
-
-fn normalize_editor_agent_reply_text(
-    reply_text: Option<String>,
-    tool_call: Option<&EditorAgentToolCallPlan>,
-) -> Option<String> {
-    let reply_text = normalize_optional_string(reply_text)?;
-    if !editor_agent_reply_text_looks_structural(reply_text.as_str()) {
-        return Some(reply_text);
-    }
-    tool_call.map(editor_agent_tool_call_reply_text)
-}
-
-fn editor_agent_reply_text_looks_structural(text: &str) -> bool {
-    let trimmed = text.trim();
-    if trimmed.is_empty() {
-        return true;
-    }
-    let lower = trimmed.to_ascii_lowercase();
-    if matches!(lower.as_str(), "null" | "undefined") {
-        return true;
-    }
-    trimmed.len() <= 2
-        && trimmed
-            .chars()
-            .all(|character| matches!(character, '{' | '}' | '[' | ']' | '"' | ':' | ','))
-}
-
-fn editor_agent_tool_call_reply_text(tool_call: &EditorAgentToolCallPlan) -> String {
-    match tool_call.tool_name {
-        EditorAgentToolName::GenerateImage => "我来生成图片。".to_string(),
-        EditorAgentToolName::EditImage => "我来修改图片。".to_string(),
-        EditorAgentToolName::GenerateCharacter => "我来生成角色形象。".to_string(),
-        EditorAgentToolName::GenerateIconSpritesheet => "我来生成图标素材。".to_string(),
-        EditorAgentToolName::GenerateUiDesign => "我来生成 UI 设计图。".to_string(),
-    }
-}
-
-#[cfg(test)]
-fn heuristic_editor_agent_turn_plan(
-    text: &str,
-    attachments: &[EditorAgentAttachmentRef],
-) -> EditorAgentTurnPlan {
-    let trimmed = text.trim();
-    let normalized = trimmed.to_lowercase();
-    let wants_generation = contains_any(
-        normalized.as_str(),
-        &[
-            "生成", "出图", "绘制", "设计", "画一", "画个", "画张", "generate", "create",
-        ],
-    );
-    let wants_edit = contains_any(
-        normalized.as_str(),
-        &[
-            "修改", "改成", "重绘", "换成", "编辑", "优化", "edit", "redraw",
-        ],
-    );
-    let wants_character = contains_any(
-        normalized.as_str(),
-        &["角色", "人物", "立绘", "形象", "character"],
-    );
-    let wants_icons = contains_any(
-        normalized.as_str(),
-        &["图标", "icon", "spritesheet", "素材图集"],
-    );
-    let wants_ui = contains_any(
-        normalized.as_str(),
-        &["ui", "界面", "hud", "按钮", "面板", "弹窗"],
-    );
-
-    let tool_name = if wants_icons && !attachments.is_empty() {
-        Some(EditorAgentToolName::GenerateIconSpritesheet)
-    } else if wants_edit && !attachments.is_empty() {
-        Some(EditorAgentToolName::EditImage)
-    } else if wants_character && wants_generation {
-        Some(EditorAgentToolName::GenerateCharacter)
-    } else if wants_ui && wants_generation {
-        Some(EditorAgentToolName::GenerateUiDesign)
-    } else if wants_generation {
-        Some(EditorAgentToolName::GenerateImage)
-    } else {
-        None
-    };
-
-    let reply_text = match tool_name {
-        Some(EditorAgentToolName::EditImage) => "我来按你的要求修改这张图。".to_string(),
-        Some(EditorAgentToolName::GenerateCharacter) => "我来生成角色形象。".to_string(),
-        Some(EditorAgentToolName::GenerateIconSpritesheet) => "我来生成图标素材图集。".to_string(),
-        Some(EditorAgentToolName::GenerateUiDesign) => "我来生成 UI 设计图。".to_string(),
-        Some(EditorAgentToolName::GenerateImage) => "我来生成图片。".to_string(),
-        None => build_echo_assistant_text(trimmed, attachments.len()),
-    };
-    let tool_call = tool_name.map(|tool_name| EditorAgentToolCallPlan {
-        tool_name,
-        prompt: if trimmed.is_empty() {
-            "根据附件生成适合当前画布的图片".to_string()
-        } else {
-            trimmed.to_string()
-        },
-        summary: Some(editor_agent_tool_default_summary(tool_name)),
-        model: None,
-        aspect_ratio: None,
-        image_size: Some("1K".to_string()),
-        icon_descriptions: derive_icon_descriptions(trimmed),
-    });
-
-    EditorAgentTurnPlan {
-        reply_text,
-        tool_call,
-    }
-}
-
-fn contains_any(text: &str, needles: &[&str]) -> bool {
-    needles.iter().any(|needle| text.contains(needle))
-}
-
-fn derive_icon_descriptions(prompt: &str) -> Vec<String> {
-    let normalized = prompt.trim();
-    if normalized.is_empty() {
-        return vec![
-            "主按钮图标".to_string(),
-            "奖励图标".to_string(),
-            "关闭图标".to_string(),
-        ];
-    }
-    normalized
-        .split(['、', ',', '，', '\n', ';', '；'])
-        .map(str::trim)
-        .filter(|item| !item.is_empty())
-        .take(8)
-        .map(ToOwned::to_owned)
-        .collect::<Vec<_>>()
-        .into_iter()
-        .filter(|item| item.chars().count() <= 80)
-        .collect::<Vec<_>>()
-        .pipe_non_empty_or_else(|| vec![normalized.to_string()])
-}
-
-trait VecPipeNonEmpty<T> {
-    fn pipe_non_empty_or_else<F>(self, fallback: F) -> Self
-    where
-        F: FnOnce() -> Self;
-}
-
-impl<T> VecPipeNonEmpty<T> for Vec<T> {
-    fn pipe_non_empty_or_else<F>(self, fallback: F) -> Self
-    where
-        F: FnOnce() -> Self,
-    {
-        if self.is_empty() { fallback() } else { self }
-    }
-}
-
-async fn execute_editor_agent_tool_call(
-    state: &AppState,
-    request_context: &RequestContext,
-    conversation: &EditorAgentConversationRecord,
-    user_message: &EditorAgentMessage,
-    tool_call_id: &str,
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-    tool_call: EditorAgentToolCallPlan,
-) -> Result<EditorAgentToolExecution, EditorAgentToolExecutionError> {
-    let project = state
-        .spacetime_client()
-        .get_editor_project(EditorProjectGetRecordInput {
-            project_id: conversation.project_id.clone(),
-            owner_user_id: conversation.owner_user_id.clone(),
-        })
-        .await
-        .map_err(map_editor_project_error)
-        .map_err(|error| EditorAgentToolExecutionError {
-            tool_name: tool_call.tool_name,
-            model: tool_call.model.clone(),
-            error,
-        })?;
-    let completion =
-        build_editor_agent_canvas_completion(&project, tool_call.tool_name, &tool_call.prompt);
-    let caller = EditorGenerationCaller {
-        owner_user_id: conversation.owner_user_id.clone(),
-        audit_subject_user_id: Some(conversation.owner_user_id.clone()),
-        audit_project_id: Some(conversation.project_id.clone()),
-    };
-    let tool_request_context = editor_agent_tool_request_context(request_context, tool_call_id);
-    let attachment_sources = editor_agent_attachment_sources(user_message.attachments.as_slice());
-    let previous_generation_source = (tool_call.tool_name == EditorAgentToolName::EditImage
-        && user_message.attachments.is_empty())
-    .then(|| latest_generation_reference.and_then(editor_agent_generated_reference_source))
-    .flatten();
-    let tool_reference_sources = previous_generation_source
-        .clone()
-        .map(|source| vec![source])
-        .unwrap_or_else(|| attachment_sources.clone());
-    let generation_reference_context = editor_agent_tool_generation_reference_context(
-        user_message.attachments.as_slice(),
-        latest_generation_reference,
-        previous_generation_source.as_deref(),
-    );
-    let generation_inputs = Some(json!({
-        "source": "editor-agent",
-        "conversationId": conversation.conversation_id,
-        "messageId": user_message.id,
-        "toolCallId": tool_call_id,
-        "fields": [{ "title": "用户指令", "value": tool_call.prompt }],
-        "references": generation_reference_context,
-    }));
-
-    let tool_name = tool_call.tool_name;
-    let tool_model = tool_call.model.clone();
-    let response = match tool_name {
-        EditorAgentToolName::GenerateImage
-        | EditorAgentToolName::GenerateCharacter
-        | EditorAgentToolName::GenerateUiDesign => {
-            let kind = match tool_name {
-                EditorAgentToolName::GenerateCharacter => Some("character".to_string()),
-                EditorAgentToolName::GenerateUiDesign => Some("ui-design".to_string()),
-                _ => None,
-            };
-            generate_editor_image_for_owner(
-                state,
-                &tool_request_context,
-                caller,
-                EditorImageGenerationRequest {
-                    prompt: tool_call.prompt.clone(),
-                    size: None,
-                    kind,
-                    model: tool_call.model.clone(),
-                    screen_color: Some("auto".to_string()),
-                    seg_model: Some("birefnet".to_string()),
-                    aspect_ratio: tool_call.aspect_ratio.clone(),
-                    image_size: tool_call.image_size.clone(),
-                    reference_image_srcs: Some(tool_reference_sources.clone()),
-                    project_id: Some(conversation.project_id.clone()),
-                    asset_kind: Some(editor_agent_tool_asset_kind(tool_name).to_string()),
-                    generation_inputs,
-                    asset_folder_id: Some(editor_agent_default_asset_folder_id()),
-                    asset_label: tool_call.summary.clone(),
-                    source_resource_id: editor_agent_tool_source_resource_id(
-                        user_message.attachments.as_slice(),
-                        latest_generation_reference,
-                        previous_generation_source.as_deref(),
-                    ),
-                    canvas_completion: Some(completion),
-                },
-            )
-            .await
-        }
-        EditorAgentToolName::EditImage => {
-            let (source_image_src, reference_image_srcs) = split_editor_agent_edit_sources(
-                tool_reference_sources.clone(),
-            )
-            .ok_or_else(|| EditorAgentToolExecutionError {
-                tool_name,
-                model: tool_model.clone(),
-                error: editor_agent_bad_request("修改图片需要先选择一张画布或素材库图片附件"),
-            })?;
-            edit_editor_image_for_owner(
-                state,
-                &tool_request_context,
-                caller,
-                EditorImageEditRequest {
-                    prompt: tool_call.prompt.clone(),
-                    source_image_src,
-                    size: None,
-                    model: tool_call.model.clone(),
-                    reference_image_srcs: Some(reference_image_srcs),
-                    project_id: Some(conversation.project_id.clone()),
-                    asset_kind: Some(editor_agent_tool_asset_kind(tool_name).to_string()),
-                    generation_inputs,
-                    asset_folder_id: Some(editor_agent_default_asset_folder_id()),
-                    asset_label: tool_call.summary.clone(),
-                    source_resource_id: editor_agent_tool_source_resource_id(
-                        user_message.attachments.as_slice(),
-                        latest_generation_reference,
-                        previous_generation_source.as_deref(),
-                    ),
-                    target_layer_id: None,
-                    canvas_completion: Some(completion),
-                },
-            )
-            .await
-        }
-        EditorAgentToolName::GenerateIconSpritesheet => {
-            let (reference_image_src, extra_references) =
-                split_editor_agent_edit_sources(attachment_sources).ok_or_else(|| {
-                    EditorAgentToolExecutionError {
-                        tool_name,
-                        model: tool_model.clone(),
-                        error: editor_agent_bad_request("生成图标素材需要先选择一张图标规范参考图"),
-                    }
-                })?;
-            let icon_descriptions = if tool_call.icon_descriptions.is_empty() {
-                derive_icon_descriptions(tool_call.prompt.as_str())
-            } else {
-                tool_call.icon_descriptions.clone()
-            };
-            generate_editor_icon_spritesheet_for_owner(
-                state,
-                &tool_request_context,
-                caller,
-                EditorIconSpritesheetGenerationRequest {
-                    reference_image_src,
-                    reference_image_srcs: Some(extra_references),
-                    icon_descriptions,
-                    model: tool_call.model.clone(),
-                    screen_color: Some("auto".to_string()),
-                    seg_model: Some("birefnet".to_string()),
-                    aspect_ratio: tool_call.aspect_ratio.clone(),
-                    image_size: tool_call.image_size.clone(),
-                    project_id: Some(conversation.project_id.clone()),
-                    generation_inputs,
-                    asset_folder_id: Some(editor_agent_default_asset_folder_id()),
-                    asset_label: None,
-                    canvas_completion: Some(completion),
-                },
-            )
-            .await
-        }
-    }
-    .map_err(|error| EditorAgentToolExecutionError {
-        tool_name,
-        model: tool_model.clone(),
-        error,
-    })?;
-
-    Ok(build_editor_agent_tool_execution(
-        tool_call_id,
-        tool_name,
-        tool_call.summary,
-        response.0,
-    ))
-}
-
-fn editor_agent_tool_request_context(base: &RequestContext, tool_call_id: &str) -> RequestContext {
-    RequestContext::new(
-        format!("{}:{tool_call_id}", base.request_id()),
-        format!("{} editor-agent-tool", base.operation()),
-        std::time::Duration::ZERO,
-        false,
-    )
-}
-
-fn build_editor_agent_tool_execution(
-    tool_call_id: &str,
-    tool_name: EditorAgentToolName,
-    summary: Option<String>,
-    response_body: Value,
-) -> EditorAgentToolExecution {
-    let data = response_body
-        .get("data")
-        .filter(|_| response_body.get("ok").and_then(Value::as_bool) == Some(true))
-        .unwrap_or(&response_body);
-    let images = editor_agent_generated_images_from_response(tool_name, data);
-    let task_id = data
-        .get("taskId")
-        .and_then(Value::as_str)
-        .map(str::to_string)
-        .or_else(|| {
-            images
-                .iter()
-                .find_map(|image| image.resource_id.as_ref().map(|_| ()))
-                .and_then(|_| {
-                    data.get("taskId")
-                        .and_then(Value::as_str)
-                        .map(str::to_string)
-                })
-        });
-    let model = data
-        .get("model")
-        .and_then(Value::as_str)
-        .map(str::to_string);
-    let resolved_summary = summary.unwrap_or_else(|| editor_agent_tool_default_summary(tool_name));
-
-    EditorAgentToolExecution {
-        record: EditorAgentGenerationRecord {
-            tool_call_id: tool_call_id.to_string(),
-            tool_name,
-            summary: Some(resolved_summary.clone()),
-            task_id,
-            status: EditorAgentGenerationStatus::Completed,
-            model,
-            images,
-            error: None,
-        },
-        summary: resolved_summary,
-    }
-}
-
-fn editor_agent_generated_images_from_response(
-    tool_name: EditorAgentToolName,
-    data: &Value,
-) -> Vec<EditorAgentGeneratedImage> {
-    if tool_name == EditorAgentToolName::GenerateIconSpritesheet {
-        let mut images = Vec::new();
-        if let Some(resource) = data.get("spritesheetResource") {
-            images.push(editor_agent_generated_image_from_resource(
-                resource,
-                data.get("spritesheetImageSrc").and_then(Value::as_str),
-                data.get("spritesheetWidth").and_then(Value::as_u64),
-                data.get("spritesheetHeight").and_then(Value::as_u64),
-            ));
-        }
-        if let Some(icon_images) = data.get("iconImageSrcs").and_then(Value::as_array) {
-            for icon in icon_images {
-                if let Some(resource) = icon.get("resource") {
-                    images.push(editor_agent_generated_image_from_resource(
-                        resource,
-                        icon.get("imageSrc").and_then(Value::as_str),
-                        icon.get("width").and_then(Value::as_u64),
-                        icon.get("height").and_then(Value::as_u64),
-                    ));
-                }
-            }
-        }
-        return images;
-    }
-
-    data.get("resource")
-        .map(|resource| {
-            vec![editor_agent_generated_image_from_resource(
-                resource,
-                data.get("imageSrc").and_then(Value::as_str),
-                data.get("width").and_then(Value::as_u64),
-                data.get("height").and_then(Value::as_u64),
-            )]
-        })
-        .unwrap_or_else(|| {
-            data.get("imageSrc")
-                .and_then(Value::as_str)
-                .map(|image_src| {
-                    vec![EditorAgentGeneratedImage {
-                        resource_id: None,
-                        object_key: None,
-                        asset_object_id: None,
-                        image_src: image_src.to_string(),
-                        thumbnail_src: None,
-                        width: data
-                            .get("width")
-                            .and_then(Value::as_u64)
-                            .and_then(|value| u32::try_from(value).ok()),
-                        height: data
-                            .get("height")
-                            .and_then(Value::as_u64)
-                            .and_then(|value| u32::try_from(value).ok()),
-                    }]
-                })
-                .unwrap_or_default()
-        })
-}
-
-fn editor_agent_generated_image_from_resource(
-    resource: &Value,
-    fallback_image_src: Option<&str>,
-    fallback_width: Option<u64>,
-    fallback_height: Option<u64>,
-) -> EditorAgentGeneratedImage {
-    EditorAgentGeneratedImage {
-        resource_id: resource
-            .get("resourceId")
-            .and_then(Value::as_str)
-            .map(str::to_string),
-        object_key: resource
-            .get("objectKey")
-            .and_then(Value::as_str)
-            .map(str::to_string),
-        asset_object_id: resource
-            .get("assetObjectId")
-            .and_then(Value::as_str)
-            .map(str::to_string),
-        image_src: resource
-            .get("imageSrc")
-            .and_then(Value::as_str)
-            .or(fallback_image_src)
-            .unwrap_or("")
-            .to_string(),
-        thumbnail_src: resource
-            .get("thumbnailSrc")
-            .and_then(Value::as_str)
-            .map(str::to_string),
-        width: resource
-            .get("width")
-            .and_then(Value::as_u64)
-            .or(fallback_width)
-            .and_then(|value| u32::try_from(value).ok()),
-        height: resource
-            .get("height")
-            .and_then(Value::as_u64)
-            .or(fallback_height)
-            .and_then(|value| u32::try_from(value).ok()),
-    }
-}
-
-fn editor_agent_attachment_sources(attachments: &[EditorAgentAttachmentRef]) -> Vec<String> {
-    attachments
-        .iter()
-        .filter_map(|attachment| {
-            attachment
-                .object_key
-                .as_deref()
-                .map(str::trim)
-                .filter(|value| !value.is_empty())
-                .map(|value| value.trim_start_matches('/').to_string())
-                .or_else(|| normalize_required_string(attachment.reference_id.as_str()))
-        })
-        .collect()
-}
-
-fn editor_agent_tool_generation_reference_context(
-    attachments: &[EditorAgentAttachmentRef],
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-    previous_generation_source: Option<&str>,
-) -> Vec<Value> {
-    if previous_generation_source.is_some() {
-        return latest_generation_reference
-            .map(|reference| {
-                vec![json!({
-                    "title": reference
-                        .summary
-                        .clone()
-                        .unwrap_or_else(|| "上一张生成图".to_string()),
-                    "label": reference.summary,
-                    "refType": "previous-generation",
-                    "refId": reference.resource_id,
-                    "resourceId": reference.resource_id,
-                    "objectKey": reference.object_key,
-                    "assetObjectId": reference.asset_object_id,
-                    "toolCallId": reference.tool_call_id,
-                    "toolName": reference.tool_name,
-                    "sourceMessageId": reference.source_message_id,
-                    "source": previous_generation_source,
-                    "implicit": true,
-                })]
-            })
-            .unwrap_or_default();
-    }
-
-    attachments
-        .iter()
-        .map(|attachment| {
-            json!({
-                "title": attachment.label.clone().unwrap_or_else(|| "对话附件".to_string()),
-                "label": attachment.label,
-                "refType": match attachment.source {
-                    EditorAgentAttachmentSource::CanvasResource => "project-resource",
-                    EditorAgentAttachmentSource::LibraryAsset => "asset",
-                },
-                "refId": attachment.reference_id,
-                "resourceId": (attachment.source == EditorAgentAttachmentSource::CanvasResource)
-                    .then(|| attachment.reference_id.clone()),
-                "objectKey": attachment.object_key,
-            })
-        })
-        .collect()
-}
-
-fn editor_agent_tool_source_resource_id(
-    attachments: &[EditorAgentAttachmentRef],
-    latest_generation_reference: Option<&EditorAgentGeneratedImageReference>,
-    previous_generation_source: Option<&str>,
-) -> Option<String> {
-    if previous_generation_source.is_some() {
-        return latest_generation_reference.and_then(|reference| reference.resource_id.clone());
-    }
-    attachments
-        .first()
-        .map(|attachment| attachment.reference_id.clone())
-}
-
-fn split_editor_agent_edit_sources(sources: Vec<String>) -> Option<(String, Vec<String>)> {
-    let mut iter = sources.into_iter();
-    let first = iter.next()?;
-    Some((first, iter.collect()))
-}
-
-fn editor_agent_tool_asset_kind(tool_name: EditorAgentToolName) -> &'static str {
-    match tool_name {
-        EditorAgentToolName::GenerateCharacter => "character",
-        EditorAgentToolName::GenerateUiDesign => "ui-design",
-        EditorAgentToolName::EditImage => "editor_agent_edit_image",
-        EditorAgentToolName::GenerateIconSpritesheet => "icon-spritesheet",
-        EditorAgentToolName::GenerateImage => "editor_agent_generated_image",
-    }
-}
-
-fn editor_agent_default_asset_folder_id() -> String {
-    "project".to_string()
-}
-
-fn editor_agent_tool_default_summary(tool_name: EditorAgentToolName) -> String {
-    match tool_name {
-        EditorAgentToolName::GenerateImage => "生成图片",
-        EditorAgentToolName::EditImage => "修改图片",
-        EditorAgentToolName::GenerateCharacter => "生成角色形象",
-        EditorAgentToolName::GenerateIconSpritesheet => "生成图标素材",
-        EditorAgentToolName::GenerateUiDesign => "生成 UI 设计图",
-    }
-    .to_string()
-}
-
-fn build_editor_agent_canvas_completion(
-    project: &EditorProjectRecord,
-    tool_name: EditorAgentToolName,
-    title: &str,
-) -> EditorCanvasGenerationCompletionPayload {
-    let (width, height) = editor_agent_tool_display_size(tool_name);
-    let (x, y) = next_editor_agent_canvas_position(project.layers.clone(), width, height);
-    EditorCanvasGenerationCompletionPayload {
-        dialog_id: None,
-        title: normalize_optional_string(Some(title.to_string()))
-            .unwrap_or_else(|| editor_agent_tool_default_summary(tool_name)),
-        placeholder: EditorCanvasGenerationPlaceholderPayload {
-            x,
-            y,
-            width,
-            height,
-            original_width: width,
-            original_height: height,
-        },
-    }
-}
-
-fn editor_agent_tool_display_size(tool_name: EditorAgentToolName) -> (f64, f64) {
-    match tool_name {
-        EditorAgentToolName::GenerateUiDesign => (640.0, 360.0),
-        EditorAgentToolName::GenerateCharacter => (512.0, 768.0),
-        _ => (512.0, 512.0),
-    }
-}
-
-fn next_editor_agent_canvas_position(layers: Value, _width: f64, _height: f64) -> (f64, f64) {
-    let mut max_right: Option<f64> = None;
-    let mut min_y: Option<f64> = None;
-    if let Value::Array(items) = layers {
-        for item in items {
-            if item.get("itemType").and_then(Value::as_str) == Some("generation-dialog") {
-                continue;
-            }
-            let Some(x) = item.get("x").and_then(Value::as_f64) else {
-                continue;
-            };
-            let Some(y) = item.get("y").and_then(Value::as_f64) else {
-                continue;
-            };
-            let width = item.get("width").and_then(Value::as_f64).unwrap_or(0.0);
-            if !x.is_finite() || !y.is_finite() || !width.is_finite() {
-                continue;
-            }
-            max_right = Some(max_right.map_or(x + width, |value| value.max(x + width)));
-            min_y = Some(min_y.map_or(y, |value| value.min(y)));
-        }
-    }
-    (
-        max_right.map_or(0.0, |right| right + EDITOR_AGENT_CANVAS_RESULT_GAP),
-        min_y.unwrap_or(0.0),
-    )
-}
-
-#[cfg(test)]
-fn build_echo_assistant_text(text: &str, attachment_count: usize) -> String {
-    let trimmed = text.trim();
-    if trimmed.is_empty() {
-        return format!("已收到 {attachment_count} 个附件。");
-    }
-    format!("收到：{trimmed}")
-}
-
-fn now_rfc3339() -> String {
-    shared_kernel::format_rfc3339(time::OffsetDateTime::now_utc())
-        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
-}
-
-async fn require_editor_agent_sidebar_enabled(
-    state: &AppState,
-    owner_user_id: &str,
-) -> Result<(), AppError> {
-    match state
-        .is_image_editor_agent_sidebar_enabled_for_user(Some(owner_user_id))
-        .await
-    {
-        Ok(true) => Ok(()),
-        Ok(false) => Err(editor_agent_sidebar_unavailable()),
-        Err(error) => Err(AppError::from_status(StatusCode::BAD_GATEWAY)
-            .with_message("读取画布 Agent 灰度配置失败")
-            .with_details(json!({
-                "provider": "spacetimedb",
-                "message": error.to_string(),
-            }))),
-    }
-}
-
-fn editor_agent_sidebar_unavailable() -> AppError {
-    AppError::from_status(StatusCode::SERVICE_UNAVAILABLE)
-        .with_message("画布 Agent 暂不可用")
-        .with_details(json!({
-            "provider": "editor-agent",
-            "reason": "image_editor_agent_sidebar_disabled",
-            "gateKey": module_runtime::IMAGE_EDITOR_AGENT_SIDEBAR_GATE_KEY,
-        }))
-}
-
-fn editor_agent_bad_request(message: impl Into<String>) -> AppError {
-    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-        "provider": "editor-agent",
-        "message": message.into(),
-    }))
-}
-
-fn editor_agent_oss_unavailable() -> AppError {
-    AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
-        "provider": "aliyun-oss",
-        "reason": "OSS is not configured for editor agent conversations",
-    }))
-}
-
-fn editor_agent_oss_read_error(message: impl Into<String>) -> AppError {
-    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-        "provider": "aliyun-oss",
-        "message": message.into(),
-    }))
-}
-
-fn editor_agent_messages_document_too_large() -> AppError {
-    AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE).with_details(json!({
-        "provider": "editor-agent",
-        "message": "message document is too large",
-        "maxBytes": EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES,
-    }))
-}
-
-fn editor_agent_sse_json_event_or_error<T>(event_name: &str, payload: T) -> Event
-where
-    T: Serialize,
-{
-    match serde_json::to_string(&payload) {
-        Ok(data) => Event::default().event(event_name).data(data),
-        Err(error) => Event::default().event("error").data(
-            serde_json::to_string(&EditorAgentErrorEvent {
-                conversation_id: None,
-                code: "SERIALIZE_EVENT_FAILED".to_string(),
-                message: error.to_string(),
-                recoverable: false,
-            })
-            .unwrap_or_else(|_| "{}".to_string()),
-        ),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::AppConfig;
-    use platform_llm::LlmApiKind;
-
-    #[test]
-    fn echo_assistant_text_uses_attachment_fallback() {
-        assert_eq!(
-            build_echo_assistant_text("  画一棵树  ", 0),
-            "收到：画一棵树"
-        );
-        assert_eq!(build_echo_assistant_text("   ", 2), "已收到 2 个附件。");
-    }
-
-    #[test]
-    fn empty_document_uses_contract_version() {
-        let document = empty_messages_document("editor-agent-conv-1");
-        assert_eq!(document.version, EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION);
-        assert_eq!(document.conversation_id, "editor-agent-conv-1");
-        assert!(document.messages.is_empty());
-    }
-
-    #[test]
-    fn canvas_attachment_normalization_uses_project_resource_truth() {
-        let conversation = test_conversation_record();
-        let attachment = EditorAgentAttachmentRef {
-            source: EditorAgentAttachmentSource::CanvasResource,
-            reference_id: " resource-1 ".to_string(),
-            object_key: Some("generated-editor-assets/resource-1.png".to_string()),
-            image_src: "https://client.example/stale.png".to_string(),
-            thumbnail_src: Some("https://client.example/thumb.png".to_string()),
-            label: Some("  参考图  ".to_string()),
-            width: Some(1),
-            height: Some(1),
-        };
-        let resource = test_project_resource_record();
-
-        let normalized =
-            normalize_canvas_resource_attachment(&conversation, &attachment, &resource)
-                .expect("attachment should normalize");
-
-        assert_eq!(normalized.reference_id, "resource-1");
-        assert_eq!(
-            normalized.object_key.as_deref(),
-            Some("generated-editor-assets/resource-1.png")
-        );
-        assert_eq!(normalized.image_src, "/api/assets/read/resource-1.png");
-        assert_eq!(normalized.thumbnail_src, None);
-        assert_eq!(normalized.label.as_deref(), Some("参考图"));
-        assert_eq!(normalized.width, Some(512));
-        assert_eq!(normalized.height, Some(256));
-    }
-
-    #[test]
-    fn attachment_normalization_rejects_mismatched_object_key() {
-        let conversation = test_conversation_record();
-        let attachment = EditorAgentAttachmentRef {
-            source: EditorAgentAttachmentSource::CanvasResource,
-            reference_id: "resource-1".to_string(),
-            object_key: Some("generated-editor-assets/other.png".to_string()),
-            image_src: "/api/assets/read/resource-1.png".to_string(),
-            thumbnail_src: None,
-            label: None,
-            width: None,
-            height: None,
-        };
-        let resource = test_project_resource_record();
-
-        assert!(
-            normalize_canvas_resource_attachment(&conversation, &attachment, &resource).is_err()
-        );
-    }
-
-    #[test]
-    fn library_attachment_normalization_uses_asset_label_fallback() {
-        let attachment = EditorAgentAttachmentRef {
-            source: EditorAgentAttachmentSource::LibraryAsset,
-            reference_id: "asset-1".to_string(),
-            object_key: None,
-            image_src: "https://client.example/stale.png".to_string(),
-            thumbnail_src: None,
-            label: None,
-            width: None,
-            height: None,
-        };
-        let asset = EditorAssetRecord {
-            asset_id: "asset-1".to_string(),
-            folder_id: "project".to_string(),
-            label: "素材库图".to_string(),
-            asset_object_id: Some("asset-object-1".to_string()),
-            image_src: "/api/assets/read/asset-1.png".to_string(),
-            object_key: Some("generated-editor-assets/asset-1.png".to_string()),
-            width: 128,
-            height: 128,
-            source_type: "uploaded".to_string(),
-            prompt: None,
-            actual_prompt: None,
-            model: None,
-            provider: None,
-            task_id: None,
-            asset_kind: None,
-            generation_inputs: None,
-            source_resource_id: None,
-            public_showcase_enabled: None,
-            thumbnail_src: Some("/api/assets/read/asset-1-thumb.png".to_string()),
-            generation_cost_mud_points: 0,
-            showcase_id: None,
-            showcase_review_status: None,
-            showcase_display_enabled: None,
-            showcase_like_count: None,
-            created_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at: "2026-07-03T00:00:00Z".to_string(),
-        };
-
-        let normalized = normalize_library_asset_attachment(&attachment, &asset)
-            .expect("library attachment should normalize");
-
-        assert_eq!(normalized.label.as_deref(), Some("素材库图"));
-        assert_eq!(
-            normalized.thumbnail_src.as_deref(),
-            Some("/api/assets/read/asset-1-thumb.png")
-        );
-        assert_eq!(normalized.width, Some(128));
-        assert_eq!(normalized.height, Some(128));
-    }
-
-    #[test]
-    fn generated_image_from_resource_keeps_private_asset_keys() {
-        let image = editor_agent_generated_image_from_resource(
-            &json!({
-                "resourceId": "resource-1",
-                "imageSrc": "/generated-editor-assets/result.png",
-                "thumbnailSrc": "/generated-editor-assets/result-thumb.png",
-                "objectKey": "generated-editor-assets/result.png",
-                "assetObjectId": "asset-object-result",
-                "width": 1024,
-                "height": 768
-            }),
-            None,
-            None,
-            None,
-        );
-
-        assert_eq!(image.resource_id.as_deref(), Some("resource-1"));
-        assert_eq!(
-            image.object_key.as_deref(),
-            Some("generated-editor-assets/result.png")
-        );
-        assert_eq!(
-            image.asset_object_id.as_deref(),
-            Some("asset-object-result")
-        );
-        assert_eq!(image.width, Some(1024));
-        assert_eq!(image.height, Some(768));
-    }
-
-    #[test]
-    fn editor_agent_generations_target_default_asset_library_folder() {
-        assert_eq!(editor_agent_default_asset_folder_id(), "project");
-    }
-
-    #[test]
-    fn editor_agent_turn_plan_parses_fenced_json_tool_call() {
-        let plan = parse_editor_agent_turn_plan(
-            r#"```json
-{
-  "replyText": "我来生成一张像素风角色图。",
-  "toolCall": {
-    "toolName": "generate_character",
-    "prompt": "像素风银发游侠",
-    "summary": "生成像素角色",
-    "imageSize": "1K"
-  }
-}
-```"#,
-        )
-        .expect("fenced JSON should parse");
-
-        assert_eq!(plan.reply_text, "我来生成一张像素风角色图。");
-        let tool_call = plan.tool_call.expect("tool call should exist");
-        assert_eq!(tool_call.tool_name, EditorAgentToolName::GenerateCharacter);
-        assert_eq!(tool_call.prompt, "像素风银发游侠");
-        assert_eq!(tool_call.summary.as_deref(), Some("生成像素角色"));
-        assert_eq!(tool_call.image_size.as_deref(), Some("1K"));
-    }
-
-    #[test]
-    fn editor_agent_turn_plan_rejects_invalid_llm_response() {
-        assert!(parse_editor_agent_turn_plan("收到：画一棵树").is_none());
-        assert!(
-            parse_editor_agent_turn_plan(
-                r#"{"toolCall":{"toolName":"generate_image","prompt":"画一棵树"}}"#,
-            )
-            .is_none()
-        );
-        assert!(
-            parse_editor_agent_turn_plan(
-                r#"{"replyText":"我来生成图片。","toolCall":{"toolName":"generate_image"}}"#,
-            )
-            .is_none()
-        );
-    }
-
-    #[test]
-    fn editor_agent_turn_plan_replaces_structural_reply_fragment() {
-        let plan = parse_editor_agent_turn_plan(
-            r#"{"replyText":"{","toolCall":{"toolName":"generate_image","prompt":"生成一张角色规范图","summary":"生成角色规范图"}}"#,
-        )
-        .expect("valid tool call should parse");
-
-        assert_eq!(plan.reply_text, "我来生成图片。");
-        assert_eq!(
-            plan.tool_call.as_ref().map(|tool_call| tool_call.tool_name),
-            Some(EditorAgentToolName::GenerateImage)
-        );
-    }
-
-    #[test]
-    fn editor_agent_llm_system_prompt_describes_each_tool() {
-        let prompt = editor_agent_llm_system_prompt();
-
-        for expected in [
-            "generate_image：从文字生成一张全新图片",
-            "edit_image：修改已有图片",
-            "generate_character：生成新的角色形象",
-            "generate_icon_spritesheet：生成一组图标素材或图标图集",
-            "generate_ui_design：生成一张完整 UI 设计图或界面稿",
-            "规范图/视觉规范图/风格规范图/素材规范展板",
-            "当前使用 generate_image",
-            "角色规范图/角色美术视觉规范设定图",
-            "图标规范图/图标视觉规范展板",
-            "统一视角、线条粗细",
-            "色卡/色号",
-            "工具选择优先级",
-            "明确修改/指代已有图 => edit_image",
-            "规范图/视觉规范图/风格规范图/素材规范展板 => generate_image",
-        ] {
-            assert!(
-                prompt.contains(expected),
-                "system prompt should contain {expected}"
-            );
-        }
-    }
-
-    #[test]
-    fn latest_generation_reference_enters_llm_prompt() {
-        let conversation = test_conversation_record();
-        let user_message = test_user_message("把刚才那个衣服换成蓝色");
-        let mut document = empty_messages_document(conversation.conversation_id.as_str());
-        document.messages.push(EditorAgentMessage {
-            id: "editor-agent-message-assistant-1".to_string(),
-            role: EditorAgentMessageRole::Assistant,
-            kind: EditorAgentMessageKind::Chat,
-            text: "已生成角色图。".to_string(),
-            attachments: Vec::new(),
-            generations: vec![test_completed_generation_record()],
-            status: EditorAgentMessageStatus::Completed,
-            created_at: "2026-07-05T00:00:00Z".to_string(),
-        });
-        document.messages.push(user_message.clone());
-
-        let reference = latest_editor_agent_generated_image_reference(&document)
-            .expect("latest generated image should be available");
-        let prompt = build_editor_agent_llm_user_prompt(
-            &conversation,
-            &document,
-            &user_message,
-            Some(&reference),
-        );
-        let prompt_json: Value = serde_json::from_str(prompt.as_str()).expect("prompt is JSON");
-
-        assert_eq!(
-            prompt_json["latestGeneratedImage"]["toolName"],
-            json!("generate_image")
-        );
-        assert_eq!(
-            prompt_json["latestGeneratedImage"]["summary"],
-            json!("生成红衣角色")
-        );
-        assert_eq!(
-            prompt_json["latestGeneratedImage"]["resourceId"],
-            json!("resource-generated-1")
-        );
-        assert_eq!(
-            prompt_json["latestGeneratedImage"]["objectKey"],
-            json!("generated-editor-assets/result.png")
-        );
-        assert_eq!(
-            prompt_json["recentMessages"][0]["generations"][0]["images"][0]["objectKey"],
-            json!("generated-editor-assets/result.png")
-        );
-    }
-
-    #[test]
-    fn previous_generation_edit_default_coerces_generate_image_to_edit_image() {
-        let user_message = test_user_message("把衣服换成蓝色");
-        let reference = test_generated_image_reference();
-        let plan = EditorAgentTurnPlan {
-            reply_text: "我来生成图片。".to_string(),
-            tool_call: Some(EditorAgentToolCallPlan {
-                tool_name: EditorAgentToolName::GenerateImage,
-                prompt: "把衣服换成蓝色".to_string(),
-                summary: Some("生成蓝色衣服".to_string()),
-                model: None,
-                aspect_ratio: Some("1:1".to_string()),
-                image_size: Some("1K".to_string()),
-                icon_descriptions: Vec::new(),
-            }),
-        };
-
-        let adjusted =
-            apply_previous_generation_edit_default(plan, &user_message, Some(&reference));
-        let tool_call = adjusted.tool_call.expect("tool should be forced");
-
-        assert_eq!(tool_call.tool_name, EditorAgentToolName::EditImage);
-        assert_eq!(tool_call.prompt, "把衣服换成蓝色");
-        assert_eq!(adjusted.reply_text, "我会基于上一张生成图按你的要求修改。");
-    }
-
-    #[test]
-    fn previous_generation_reference_becomes_implicit_edit_source() {
-        let reference = test_generated_image_reference();
-
-        let sources = editor_agent_generated_reference_source(&reference);
-        let context = editor_agent_tool_generation_reference_context(
-            &[],
-            Some(&reference),
-            sources.as_deref(),
-        );
-
-        assert_eq!(
-            sources.as_deref(),
-            Some("generated-editor-assets/result.png")
-        );
-        assert_eq!(context[0]["refType"], json!("previous-generation"));
-        assert_eq!(context[0]["resourceId"], json!("resource-generated-1"));
-        assert_eq!(
-            context[0]["objectKey"],
-            json!("generated-editor-assets/result.png")
-        );
-        assert_eq!(context[0]["implicit"], json!(true));
-    }
-
-    #[test]
-    fn editor_agent_tool_execution_persists_summary() {
-        let execution = build_editor_agent_tool_execution(
-            "editor-agent-tool-1",
-            EditorAgentToolName::EditImage,
-            Some("换蓝色衣服".to_string()),
-            json!({
-                "ok": true,
-                "data": {
-                    "model": "gpt-image-2",
-                    "resource": {
-                        "resourceId": "resource-generated-2",
-                        "imageSrc": "/generated-editor-assets/blue.png",
-                        "objectKey": "generated-editor-assets/blue.png",
-                        "assetObjectId": "asset-object-blue",
-                        "width": 1024,
-                        "height": 1024
-                    }
-                }
-            }),
-        );
-
-        assert_eq!(execution.summary, "换蓝色衣服");
-        assert_eq!(execution.record.summary.as_deref(), Some("换蓝色衣服"));
-    }
-
-    #[tokio::test]
-    async fn editor_agent_llm_request_uses_vector_engine_chat_model() {
-        let conversation = test_conversation_record();
-        let document = empty_messages_document(conversation.conversation_id.as_str());
-        let user_message = test_user_message("帮我看看这张图还能怎么改");
-        let state = AppState::new(AppConfig::default()).expect("state should build");
-
-        let request =
-            build_editor_agent_llm_request(&state, &conversation, &document, &user_message, None)
-                .await;
-
-        assert_eq!(request.api_kind, LlmApiKind::OpenAiChat);
-        assert_eq!(
-            request.model.as_deref(),
-            Some(platform_agent::CREATIVE_AGENT_GPT5_MODEL)
-        );
-        assert_eq!(
-            request.max_output_tokens,
-            Some(EDITOR_AGENT_LLM_MAX_OUTPUT_TOKENS)
-        );
-        assert_eq!(
-            request.request_timeout_ms,
-            Some(EDITOR_AGENT_LLM_REQUEST_TIMEOUT_MS)
-        );
-    }
-
-    #[test]
-    fn editor_agent_heuristic_routes_tools_from_user_text() {
-        let character_plan =
-            heuristic_editor_agent_turn_plan("帮我生成一个角色形象：猫耳骑士", &[]);
-        assert_eq!(
-            character_plan
-                .tool_call
-                .as_ref()
-                .expect("character tool expected")
-                .tool_name,
-            EditorAgentToolName::GenerateCharacter
-        );
-
-        let edit_plan = heuristic_editor_agent_turn_plan(
-            "把附件这张图改成赛博朋克风格",
-            &[EditorAgentAttachmentRef {
-                source: EditorAgentAttachmentSource::CanvasResource,
-                reference_id: "resource-1".to_string(),
-                object_key: Some("generated-editor-assets/resource-1.png".to_string()),
-                image_src: "/generated-editor-assets/resource-1.png".to_string(),
-                thumbnail_src: None,
-                label: None,
-                width: Some(512),
-                height: Some(512),
-            }],
-        );
-        assert_eq!(
-            edit_plan
-                .tool_call
-                .as_ref()
-                .expect("edit tool expected")
-                .tool_name,
-            EditorAgentToolName::EditImage
-        );
-
-        let chat_plan = heuristic_editor_agent_turn_plan("这张图适合做头像吗？", &[]);
-        assert!(chat_plan.tool_call.is_none());
-    }
-
-    #[test]
-    fn editor_agent_canvas_completion_places_result_after_existing_layers() {
-        let project = EditorProjectRecord {
-            project_id: "project-1".to_string(),
-            owner_user_id: "user-1".to_string(),
-            title: "画布".to_string(),
-            canvas: spacetime_client::EditorCanvasRecord {
-                canvas_id: "canvas-1".to_string(),
-                project_id: "project-1".to_string(),
-                title: "画布".to_string(),
-                viewport: spacetime_client::EditorCanvasViewportRecord {
-                    x: 0.0,
-                    y: 0.0,
-                    scale: 1.0,
-                },
-                layers: json!([]),
-                created_at: "2026-07-03T00:00:00Z".to_string(),
-                updated_at: "2026-07-03T00:00:00Z".to_string(),
-            },
-            viewport: spacetime_client::EditorCanvasViewportRecord {
-                x: 0.0,
-                y: 0.0,
-                scale: 1.0,
-            },
-            layers: json!([
-                {
-                    "layerId": "layer-1",
-                    "resourceId": "resource-1",
-                    "x": 10.0,
-                    "y": 20.0,
-                    "width": 180.0,
-                    "height": 120.0
-                }
-            ]),
-            resources: Vec::new(),
-            created_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at: "2026-07-03T00:00:00Z".to_string(),
-        };
-
-        let completion = build_editor_agent_canvas_completion(
-            &project,
-            EditorAgentToolName::GenerateUiDesign,
-            "UI 设计图",
-        );
-
-        assert_eq!(completion.dialog_id, None);
-        assert_eq!(completion.title, "UI 设计图");
-        assert_eq!(completion.placeholder.x, 222.0);
-        assert_eq!(completion.placeholder.y, 20.0);
-        assert_eq!(completion.placeholder.width, 640.0);
-        assert_eq!(completion.placeholder.height, 360.0);
-    }
-
-    fn test_conversation_record() -> EditorAgentConversationRecord {
-        EditorAgentConversationRecord {
-            conversation_id: "editor-agent-conv-1".to_string(),
-            project_id: "project-1".to_string(),
-            owner_user_id: "user-1".to_string(),
-            title: "新对话".to_string(),
-            messages_object_key: "editor-agent/editor-agent-conv-1.json".to_string(),
-            deleted: false,
-            created_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at_micros: 1,
-        }
-    }
-
-    fn test_project_resource_record() -> EditorProjectResourceRecord {
-        EditorProjectResourceRecord {
-            resource_id: "resource-1".to_string(),
-            project_id: "project-1".to_string(),
-            owner_user_id: "user-1".to_string(),
-            asset_object_id: Some("asset-object-1".to_string()),
-            image_src: "/api/assets/read/resource-1.png".to_string(),
-            object_key: Some("generated-editor-assets/resource-1.png".to_string()),
-            width: 512,
-            height: 256,
-            source_type: "generated".to_string(),
-            prompt: Some("森林".to_string()),
-            actual_prompt: None,
-            model: Some("gpt-image-2".to_string()),
-            provider: Some("VectorEngine".to_string()),
-            task_id: Some("task-1".to_string()),
-            source_resource_id: None,
-            asset_kind: Some("editor_generated_image".to_string()),
-            generation_inputs: None,
-            public_showcase_enabled: false,
-            created_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at: "2026-07-03T00:00:00Z".to_string(),
-        }
-    }
-
-    fn test_user_message(text: &str) -> EditorAgentMessage {
-        EditorAgentMessage {
-            id: "editor-agent-message-user-1".to_string(),
-            role: EditorAgentMessageRole::User,
-            kind: EditorAgentMessageKind::Chat,
-            text: text.to_string(),
-            attachments: Vec::new(),
-            generations: Vec::new(),
-            status: EditorAgentMessageStatus::Completed,
-            created_at: "2026-07-05T00:00:00Z".to_string(),
-        }
-    }
-
-    fn test_completed_generation_record() -> EditorAgentGenerationRecord {
-        EditorAgentGenerationRecord {
-            tool_call_id: "editor-agent-tool-generated-1".to_string(),
-            tool_name: EditorAgentToolName::GenerateImage,
-            summary: Some("生成红衣角色".to_string()),
-            task_id: Some("task-generated-1".to_string()),
-            status: EditorAgentGenerationStatus::Completed,
-            model: Some("gpt-image-2".to_string()),
-            images: vec![EditorAgentGeneratedImage {
-                resource_id: Some("resource-generated-1".to_string()),
-                object_key: Some("generated-editor-assets/result.png".to_string()),
-                asset_object_id: Some("asset-object-result".to_string()),
-                image_src: "/generated-editor-assets/result.png".to_string(),
-                thumbnail_src: Some("/generated-editor-assets/result-thumb.png".to_string()),
-                width: Some(1024),
-                height: Some(1024),
-            }],
-            error: None,
-        }
-    }
-
-    fn test_generated_image_reference() -> EditorAgentGeneratedImageReference {
-        let mut document = empty_messages_document("editor-agent-conv-1");
-        document.messages.push(EditorAgentMessage {
-            id: "editor-agent-message-assistant-1".to_string(),
-            role: EditorAgentMessageRole::Assistant,
-            kind: EditorAgentMessageKind::Chat,
-            text: "已生成角色图。".to_string(),
-            attachments: Vec::new(),
-            generations: vec![test_completed_generation_record()],
-            status: EditorAgentMessageStatus::Completed,
-            created_at: "2026-07-05T00:00:00Z".to_string(),
-        });
-        latest_editor_agent_generated_image_reference(&document)
-            .expect("latest generated image should be available")
-    }
-}
diff --git a/server-rs/crates/api-server/src/editor_agent/api.rs b/server-rs/crates/api-server/src/editor_agent/api.rs
new file mode 100644
index 000000000..04a7e33a2
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/api.rs
@@ -0,0 +1,1196 @@
+use axum::extract::{Path, State};
+use axum::{Extension, Json};
+use module_editor_agent::{
+    EDITOR_AGENT_CONVERSATION_ID_PREFIX, EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE,
+    derive_conversation_title, editor_agent_messages_object_key, validate_user_message,
+};
+use platform_editor_agent::framework::agent_builder::AgentBuilder;
+use platform_editor_agent::framework::error::PromptError;
+use platform_editor_agent::framework::memory::VecMemory;
+use platform_editor_agent::framework::run::PromptOutput;
+use platform_editor_agent::framework::tool::Tool;
+use platform_llm::LlmMessage;
+use serde::Serialize;
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+use shared_contracts::assets::{
+    EditorBackgroundMusicGenerateRequest, EditorSoundEffectGenerateRequest,
+    EditorVideoGenerateRequest,
+};
+use shared_contracts::editor_agent::{
+    CreateEditorAgentConversationRequest, EDITOR_AGENT_ERROR_MESSAGE_PREFIX,
+    EditorAgentConversationListResponse, EditorAgentConversationMessagesDocument,
+    EditorAgentConversationResponse, EditorAgentConversationSummary, EditorAgentMessage,
+    EditorAgentMessageRequest, EditorAgentMessageResponse, EditorAgentMessageRole,
+    EditorAgentToolCall, EditorAgentToolCallStatus,
+};
+use spacetime_client::{
+    EditorAgentConversationCreateRecordInput, EditorAgentConversationDeleteRecordInput,
+    EditorAgentConversationRecord, EditorAgentConversationTouchRecordInput,
+    EditorProjectGetRecordInput,
+};
+
+use crate::api_response::json_success_body;
+use crate::auth::AuthenticatedAccessToken;
+use crate::editor_agent::pricing::EditorAgentPricedTool;
+use crate::editor_agent::utils::{
+    IntoImageId, build_editor_agent_canvas_completion, conversation_detail_from_record,
+    conversation_summary_from_record, editor_agent_bad_request, empty_messages_document,
+    ensure_editor_project_access, normalize_editor_agent_attachments, now_rfc3339,
+    read_messages_document, require_editor_agent_sidebar_enabled, write_messages_document,
+};
+use crate::editor_agent::{context, display_args, reconcile};
+use crate::editor_generation_config::EditorGenerationPricingConfig;
+use crate::editor_generation_queue::{
+    EDITOR_BACKGROUND_MUSIC_GENERATION_JOB_KIND, EDITOR_ICON_SPRITESHEET_GENERATION_JOB_KIND,
+    EDITOR_IMAGE_EDIT_JOB_KIND, EDITOR_IMAGE_GENERATION_JOB_KIND,
+    EDITOR_SOUND_EFFECT_GENERATION_JOB_KIND, EDITOR_VIDEO_GENERATION_JOB_KIND,
+    enqueue_editor_generation_job_with_identity,
+};
+use crate::editor_project::{
+    EditorIconSpritesheetGenerationRequest, EditorImageEditRequest, EditorImageGenerationRequest,
+};
+use crate::editor_project::{current_utc_micros, map_editor_project_error};
+use crate::http_error::AppError;
+use crate::request_context::RequestContext;
+use crate::state::AppState;
+use platform_editor_agent::agent::agent::LlmChatAgentBuilder;
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{EditImageTool, EditImageToolArgs};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use shared_kernel::{build_prefixed_uuid_id, normalize_optional_string, normalize_required_string};
+
+const EDITOR_AGENT_CLIENT_MESSAGE_ID_MAX_CHARS: usize = 128;
+
+pub async fn editor_agent_message(
+    State(state): State<AppState>,
+    Path(conversation_id): Path<String>,
+    Extension(_request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorAgentMessageRequest>,
+) -> Result<Json<EditorAgentMessageResponse>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    let client_message_id = validate_editor_agent_message_request(&payload)?;
+    let normalized_text = payload.text.trim().to_string();
+    // Load conversation & attachments
+    let conversation = state
+        .spacetime_client()
+        .get_editor_agent_conversation(conversation_id.clone(), owner_user_id.clone())
+        .await
+        .map_err(|e| {
+            AppError::from_status(axum::http::StatusCode::NOT_FOUND)
+                .with_details(json!({ "message": format!("conversation not found: {e}") }))
+        })?;
+
+    let attachments =
+        normalize_editor_agent_attachments(&state, &conversation, payload.attachments.as_slice())
+            .await?;
+
+    let conversation_lock = crate::editor_agent::utils::editor_agent_conversation_lock(
+        conversation.conversation_id.as_str(),
+    );
+    let _conversation_lock_guard = conversation_lock.lock_owned().await;
+
+    let mut document: EditorAgentConversationMessagesDocument =
+        read_messages_document(&state, &conversation).await?;
+
+    let existing_user_index = find_idempotent_editor_agent_user_message(
+        &document,
+        client_message_id.as_str(),
+        normalized_text.as_str(),
+        attachments.as_slice(),
+    )?;
+
+    let (user_message, history_end, conversation_summary) =
+        if let Some(user_index) = existing_user_index {
+            let delta_messages = document.messages[user_index + 1..]
+                .iter()
+                .take_while(|message| message.role != EditorAgentMessageRole::User)
+                .cloned()
+                .collect::<Vec<_>>();
+            if !delta_messages.is_empty() {
+                return Ok(Json(EditorAgentMessageResponse {
+                    conversation: conversation_summary_from_record(conversation),
+                    delta_messages,
+                    error_message: None,
+                }));
+            }
+
+            (
+                document.messages[user_index].clone(),
+                user_index,
+                conversation_summary_from_record(conversation.clone()),
+            )
+        } else {
+            // Determine initialization before attachment bookkeeping adds a system message.
+            let was_empty = document.messages.is_empty();
+            let now = now_rfc3339();
+            if !attachments.is_empty() {
+                let mut attachment_info = String::new();
+                attachment_info.push_str("user has just uploaded attachments of the order: ");
+                for attachment in &attachments {
+                    attachment_info.push_str(&format!("{} ,", attachment.clone().into_image_id()));
+                }
+                document.messages.push(EditorAgentMessage {
+                    id: document.messages.len(),
+                    client_message_id: None,
+                    role: EditorAgentMessageRole::System,
+                    text: attachment_info,
+                    attachments: Vec::new(),
+                    tool_call: None,
+                    created_at: now.clone(),
+                });
+            }
+
+            let history_end = document.messages.len();
+            let user_message = EditorAgentMessage {
+                id: document.messages.len(),
+                client_message_id: Some(client_message_id),
+                role: EditorAgentMessageRole::User,
+                text: normalized_text,
+                attachments,
+                tool_call: None,
+                created_at: now,
+            };
+            document.messages.push(user_message.clone());
+            write_messages_document(&state, &conversation, &document).await?;
+
+            // Persist and return the authoritative summary for every turn. Initialization sets the
+            // title from the first user prompt; a metadata write failure must fail the request.
+            let updated_conversation = state
+                .spacetime_client()
+                .touch_editor_agent_conversation(EditorAgentConversationTouchRecordInput {
+                    conversation_id: conversation.conversation_id.clone(),
+                    owner_user_id: conversation.owner_user_id.clone(),
+                    title: was_empty.then(|| derive_conversation_title(user_message.text.as_str())),
+                    updated_at_micros: current_utc_micros(),
+                })
+                .await
+                .map_err(map_editor_project_error)?;
+
+            (
+                user_message,
+                history_end,
+                conversation_summary_from_record(updated_conversation),
+            )
+        };
+
+    // The current user message is passed separately to prompt(), so memory stops before it.
+    let previous_messages: Vec<LlmMessage> = document.messages[..history_end]
+        .iter()
+        .map(|message| match message.role {
+            EditorAgentMessageRole::User => LlmMessage::user(&message.text),
+            EditorAgentMessageRole::Assistant => LlmMessage::assistant(&message.text),
+            EditorAgentMessageRole::System => LlmMessage::system(&message.text),
+        })
+        // Tool calls and attachment bookkeeping are separate system messages.
+        .rev()
+        .take(18)
+        .rev()
+        .collect();
+
+    // Build tool context from document
+    let tool_context = context::build_tool_context(&document);
+
+    // Build and run agent
+    let Some(llm_client) = state.creative_agent_gpt5_client() else {
+        return persist_editor_agent_planning_error(
+            &state,
+            &conversation,
+            &mut document,
+            conversation_summary,
+            "Creative Agent GPT-5 client not configured",
+        )
+        .await;
+    };
+    let llm_client = llm_client.clone();
+    let pricing = match state.editor_generation_pricing().await {
+        Ok(pricing) => pricing,
+        Err(error) => {
+            return persist_editor_agent_planning_error(
+                &state,
+                &conversation,
+                &mut document,
+                conversation_summary,
+                format!("failed to load editor generation pricing: {error}"),
+            )
+            .await;
+        }
+    };
+
+    let memory = VecMemory::new(previous_messages);
+
+    let mut agent = LlmChatAgentBuilder::new()
+        .with_client(llm_client)
+        .system_prompt(editor_agent_system_prompt())
+        .tool(EditImageTool {
+            context: tool_context.clone(),
+        })
+        .tool(GenerateImageTool {
+            context: tool_context.clone(),
+        })
+        .tool(GenerateCharacterTool {
+            context: tool_context.clone(),
+        })
+        .tool(GenerateIconSpritesheetTool {
+            context: tool_context.clone(),
+        })
+        .tool(GenerateSoundEffectTool)
+        .tool(GenerateBackgroundMusicTool)
+        .tool(GenerateVideoTool {
+            context: tool_context.clone(),
+        })
+        .tool(GenerateUiDesignTool {
+            context: tool_context.clone(),
+        })
+        .max_turns(3)
+        .memory(memory)
+        .build();
+
+    let agent_result = agent
+        .prompt(LlmMessage::user(user_message.text.clone()))
+        .await;
+
+    let assistant_now = now_rfc3339();
+
+    match build_delta_messages(
+        agent_result,
+        &assistant_now,
+        document.messages.len(),
+        &document,
+        &tool_context,
+        &pricing,
+    ) {
+        Err(error) => {
+            persist_editor_agent_planning_error(
+                &state,
+                &conversation,
+                &mut document,
+                conversation_summary,
+                error.to_string(),
+            )
+            .await
+        }
+        Ok(delta_messages) => {
+            for msg in &delta_messages {
+                document.messages.push(msg.clone());
+            }
+            write_messages_document(&state, &conversation, &document).await?;
+
+            Ok(Json(EditorAgentMessageResponse {
+                conversation: conversation_summary,
+                delta_messages,
+                error_message: None,
+            }))
+        }
+    }
+}
+
+fn build_editor_agent_error_message(
+    message_id: usize,
+    error: impl std::fmt::Display,
+) -> EditorAgentMessage {
+    EditorAgentMessage {
+        id: message_id,
+        client_message_id: None,
+        role: EditorAgentMessageRole::System,
+        text: format!("{EDITOR_AGENT_ERROR_MESSAGE_PREFIX}{error}"),
+        attachments: Vec::new(),
+        tool_call: None,
+        created_at: now_rfc3339(),
+    }
+}
+
+async fn persist_editor_agent_planning_error(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+    document: &mut EditorAgentConversationMessagesDocument,
+    conversation_summary: EditorAgentConversationSummary,
+    error: impl std::fmt::Display,
+) -> Result<Json<EditorAgentMessageResponse>, AppError> {
+    let error_message = build_editor_agent_error_message(document.messages.len(), error);
+    document.messages.push(error_message.clone());
+    write_messages_document(state, conversation, document).await?;
+
+    Ok(Json(EditorAgentMessageResponse {
+        conversation: conversation_summary,
+        delta_messages: vec![error_message],
+        error_message: None,
+    }))
+}
+
+fn validate_editor_agent_message_request(
+    payload: &EditorAgentMessageRequest,
+) -> Result<String, AppError> {
+    let client_message_id = normalize_required_string(payload.client_message_id.as_str())
+        .ok_or_else(|| editor_agent_bad_request("clientMessageId is required"))?;
+    if client_message_id.chars().count() > EDITOR_AGENT_CLIENT_MESSAGE_ID_MAX_CHARS {
+        return Err(editor_agent_bad_request(format!(
+            "clientMessageId must not exceed {EDITOR_AGENT_CLIENT_MESSAGE_ID_MAX_CHARS} characters"
+        )));
+    }
+    let attachment_reference_ids = payload
+        .attachments
+        .iter()
+        .map(|attachment| attachment.reference_id.clone())
+        .collect::<Vec<_>>();
+    validate_user_message(payload.text.as_str(), attachment_reference_ids.as_slice())
+        .map_err(|error| editor_agent_bad_request(error.to_string()))?;
+    Ok(client_message_id)
+}
+
+fn find_idempotent_editor_agent_user_message(
+    document: &EditorAgentConversationMessagesDocument,
+    client_message_id: &str,
+    text: &str,
+    attachments: &[shared_contracts::editor_agent::EditorAgentAttachmentRef],
+) -> Result<Option<usize>, AppError> {
+    let Some((index, message)) = document
+        .messages
+        .iter()
+        .enumerate()
+        .find(|(_, message)| message.client_message_id.as_deref() == Some(client_message_id))
+    else {
+        return Ok(None);
+    };
+
+    if message.role != EditorAgentMessageRole::User
+        || message.text != text
+        || !editor_agent_attachment_requests_match(&message.attachments, attachments)
+    {
+        return Err(
+            AppError::from_status(axum::http::StatusCode::CONFLICT).with_details(json!({
+                "provider": "editor-agent",
+                "field": "clientMessageId",
+                "message": "clientMessageId already exists with different message content",
+            })),
+        );
+    }
+
+    Ok(Some(index))
+}
+
+fn editor_agent_attachment_requests_match(
+    stored: &[shared_contracts::editor_agent::EditorAgentAttachmentRef],
+    submitted: &[shared_contracts::editor_agent::EditorAgentAttachmentRef],
+) -> bool {
+    stored.len() == submitted.len()
+        && stored.iter().zip(submitted).all(|(left, right)| {
+            left.source == right.source && left.reference_id == right.reference_id
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use shared_contracts::editor_agent::{EditorAgentAttachmentRef, EditorAgentAttachmentSource};
+
+    fn attachment(reference_id: impl Into<String>) -> EditorAgentAttachmentRef {
+        EditorAgentAttachmentRef {
+            source: EditorAgentAttachmentSource::CanvasResource,
+            reference_id: reference_id.into(),
+            object_key: None,
+            image_src: "/generated/test.png".to_string(),
+            thumbnail_src: None,
+            label: None,
+            width: None,
+            height: None,
+        }
+    }
+
+    #[test]
+    fn validates_editor_agent_message_before_normalizing_attachments() {
+        let empty_payload = EditorAgentMessageRequest {
+            client_message_id: "client-message-empty".to_string(),
+            text: "   ".to_string(),
+            attachments: Vec::new(),
+        };
+        assert!(validate_editor_agent_message_request(&empty_payload).is_err());
+
+        let too_many_payload = EditorAgentMessageRequest {
+            client_message_id: "client-message-many".to_string(),
+            text: "生成一张图".to_string(),
+            attachments: (0..10)
+                .map(|index| attachment(format!("res-{index}")))
+                .collect(),
+        };
+        assert!(validate_editor_agent_message_request(&too_many_payload).is_err());
+
+        let attachment_only_payload = EditorAgentMessageRequest {
+            client_message_id: "client-message-attachment".to_string(),
+            text: String::new(),
+            attachments: vec![attachment("res-1")],
+        };
+        assert!(validate_editor_agent_message_request(&attachment_only_payload).is_ok());
+
+        let missing_client_message_id = EditorAgentMessageRequest {
+            client_message_id: "   ".to_string(),
+            text: "生成一张图".to_string(),
+            attachments: Vec::new(),
+        };
+        assert!(validate_editor_agent_message_request(&missing_client_message_id).is_err());
+
+        let oversized_client_message_id = EditorAgentMessageRequest {
+            client_message_id: "x".repeat(EDITOR_AGENT_CLIENT_MESSAGE_ID_MAX_CHARS + 1),
+            text: "生成一张图".to_string(),
+            attachments: Vec::new(),
+        };
+        assert!(validate_editor_agent_message_request(&oversized_client_message_id).is_err());
+    }
+
+    #[test]
+    fn detects_idempotent_message_replays_and_content_conflicts() {
+        let stored_attachment = attachment("res-1");
+        let document = EditorAgentConversationMessagesDocument {
+            version: 2,
+            conversation_id: "conversation-1".to_string(),
+            messages: vec![EditorAgentMessage {
+                id: 0,
+                client_message_id: Some("client-message-1".to_string()),
+                role: EditorAgentMessageRole::User,
+                text: "生成一张图".to_string(),
+                attachments: vec![stored_attachment.clone()],
+                tool_call: None,
+                created_at: "2026-07-16T00:00:00Z".to_string(),
+            }],
+        };
+
+        assert_eq!(
+            find_idempotent_editor_agent_user_message(
+                &document,
+                "client-message-1",
+                "生成一张图",
+                &[stored_attachment.clone()],
+            )
+            .expect("same request should be an idempotent replay"),
+            Some(0),
+        );
+        assert!(
+            find_idempotent_editor_agent_user_message(
+                &document,
+                "client-message-1",
+                "生成另一张图",
+                &[stored_attachment],
+            )
+            .is_err()
+        );
+        assert_eq!(
+            find_idempotent_editor_agent_user_message(
+                &document,
+                "client-message-2",
+                "生成一张图",
+                &[],
+            )
+            .expect("new request should not match"),
+            None,
+        );
+    }
+
+    #[test]
+    fn builds_system_error_message_with_wire_prefix() {
+        let message = build_editor_agent_error_message(3, "planning failed");
+
+        assert_eq!(message.id, 3);
+        assert_eq!(message.role, EditorAgentMessageRole::System);
+        assert_eq!(message.text, "ERROR planning failed");
+        assert!(message.tool_call.is_none());
+    }
+}
+fn editor_agent_system_prompt() -> &'static str {
+    r#"
+你是 Genarrative 图片画布 Agent，只负责帮助用户理解、规划和触发画布生成工具。
+对话回复要简短，不能承诺免费生成；实际生成工具由后端按模型定价扣泥点。
+"#
+}
+
+fn build_delta_messages(
+    result: Result<Vec<PromptOutput>, PromptError>,
+    created_at: &str,
+    messages_offset: usize,
+    document: &EditorAgentConversationMessagesDocument,
+    tool_context: &EditorToolContext,
+    pricing: &EditorGenerationPricingConfig,
+) -> Result<Vec<EditorAgentMessage>, PromptError> {
+    let outputs = result?;
+    let mut messages = Vec::with_capacity(outputs.len());
+
+    for (i, out) in outputs.into_iter().enumerate() {
+        let absolute_idx = messages_offset + i;
+        match out {
+            PromptOutput::Text(text) => {
+                messages.push(EditorAgentMessage {
+                    id: absolute_idx,
+                    client_message_id: None,
+                    role: EditorAgentMessageRole::Assistant,
+                    text,
+                    attachments: Vec::new(),
+                    tool_call: None,
+                    created_at: created_at.to_string(),
+                });
+            }
+            PromptOutput::Tool(tco) => {
+                let display_args = display_args::build_tool_call_display_args(
+                    tco.tool_call.name.as_str(),
+                    &tco.tool_call.args,
+                    document,
+                    tool_context,
+                    pricing,
+                )?;
+                messages.push(EditorAgentMessage {
+                    id: absolute_idx,
+                    client_message_id: None,
+                    role: EditorAgentMessageRole::System,
+                    text: tco.message,
+                    attachments: Vec::new(),
+                    tool_call: Some(EditorAgentToolCall {
+                        tool_name: tco.tool_call.name,
+                        status: EditorAgentToolCallStatus::NotCompleted,
+                        args: tco.tool_call.args,
+                        display_args,
+                        external_job_id: None,
+                        images: Vec::new(),
+                        videos: Vec::new(),
+                        audios: Vec::new(),
+                        error: None,
+                    }),
+                    created_at: created_at.to_string(),
+                });
+            }
+        }
+    }
+
+    Ok(messages)
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct EditorAgentConversationDeleteResponse {
+    deleted_conversation_id: String,
+    conversation: EditorAgentConversationSummary,
+}
+
+pub async fn list_editor_agent_conversations(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    ensure_editor_project_access(&state, project_id.as_str(), owner_user_id.as_str()).await?;
+    let conversations = state
+        .spacetime_client()
+        .list_editor_agent_conversations(project_id, owner_user_id)
+        .await
+        .map_err(map_editor_project_error)?
+        .into_iter()
+        .map(conversation_summary_from_record)
+        .collect();
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAgentConversationListResponse { conversations },
+    ))
+}
+
+pub async fn create_editor_agent_conversation(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<CreateEditorAgentConversationRequest>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    ensure_editor_project_access(&state, project_id.as_str(), owner_user_id.as_str()).await?;
+
+    let conversation_id = build_prefixed_uuid_id(EDITOR_AGENT_CONVERSATION_ID_PREFIX);
+    let messages_object_key = editor_agent_messages_object_key(conversation_id.as_str());
+    let title = normalize_optional_string(payload.title)
+        .unwrap_or_else(|| EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE.to_string());
+    let now_micros = current_utc_micros();
+    let seed_record = EditorAgentConversationRecord {
+        conversation_id: conversation_id.clone(),
+        project_id: project_id.clone(),
+        owner_user_id: owner_user_id.clone(),
+        title: title.clone(),
+        messages_object_key: messages_object_key.clone(),
+        deleted: false,
+        created_at: now_rfc3339(),
+        updated_at: now_rfc3339(),
+        updated_at_micros: now_micros,
+    };
+    write_messages_document(
+        &state,
+        &seed_record,
+        &empty_messages_document(conversation_id.as_str()),
+    )
+    .await?;
+
+    let conversation = state
+        .spacetime_client()
+        .create_editor_agent_conversation(EditorAgentConversationCreateRecordInput {
+            conversation_id,
+            project_id,
+            owner_user_id,
+            title,
+            messages_object_key,
+            created_at_micros: now_micros,
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+    let document = read_messages_document(&state, &conversation).await?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAgentConversationResponse {
+            conversation: conversation_detail_from_record(conversation, document.messages),
+        },
+    ))
+}
+
+pub async fn get_editor_agent_conversation(
+    State(state): State<AppState>,
+    Path(conversation_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    let conversation = state
+        .spacetime_client()
+        .get_editor_agent_conversation(conversation_id, owner_user_id)
+        .await
+        .map_err(map_editor_project_error)?;
+    let conversation_lock = crate::editor_agent::utils::editor_agent_conversation_lock(
+        conversation.conversation_id.as_str(),
+    );
+    let _conversation_lock_guard = conversation_lock.lock_owned().await;
+    let mut document = read_messages_document(&state, &conversation).await?;
+    let reconciled_messages =
+        reconcile::reconcile_editor_agent_tool_calls(&state, &conversation, &mut document).await?;
+    if !reconciled_messages.is_empty() {
+        write_messages_document(&state, &conversation, &document).await?;
+    }
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAgentConversationResponse {
+            conversation: conversation_detail_from_record(conversation, document.messages),
+        },
+    ))
+}
+
+pub async fn delete_editor_agent_conversation(
+    State(state): State<AppState>,
+    Path(conversation_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    let conversation = state
+        .spacetime_client()
+        .delete_editor_agent_conversation(EditorAgentConversationDeleteRecordInput {
+            conversation_id,
+            owner_user_id,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAgentConversationDeleteResponse {
+            deleted_conversation_id: conversation.conversation_id.clone(),
+            conversation: conversation_summary_from_record(conversation),
+        },
+    ))
+}
+
+pub async fn cancel_editor_agent_tool_call(
+    State(state): State<AppState>,
+    Path((conversation_id, message_id)): Path<(String, usize)>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+
+    let conversation = state
+        .spacetime_client()
+        .get_editor_agent_conversation(conversation_id, owner_user_id)
+        .await
+        .map_err(|e| {
+            AppError::from_status(axum::http::StatusCode::NOT_FOUND)
+                .with_details(json!({ "message": format!("conversation not found: {e}") }))
+        })?;
+
+    let conversation_lock = crate::editor_agent::utils::editor_agent_conversation_lock(
+        conversation.conversation_id.as_str(),
+    );
+    let _conversation_lock_guard = conversation_lock.lock_owned().await;
+
+    let mut document: EditorAgentConversationMessagesDocument =
+        read_messages_document(&state, &conversation).await?;
+
+    // Validate message index
+    if message_id >= document.messages.len() {
+        return Err(AppError::from_status(axum::http::StatusCode::NOT_FOUND)
+            .with_details(json!({ "message": "message not found" })));
+    }
+
+    let msg = &mut document.messages[message_id];
+
+    // Validate role and tool_call
+    if msg.role != EditorAgentMessageRole::System {
+        return Err(editor_agent_bad_request("message is not a system message"));
+    }
+    let tc = msg
+        .tool_call
+        .as_mut()
+        .ok_or_else(|| editor_agent_bad_request("message has no tool call"))?;
+    if tc.status != EditorAgentToolCallStatus::NotCompleted || tc.external_job_id.is_some() {
+        return Err(editor_agent_bad_request(
+            "tool call is no longer pending confirmation",
+        ));
+    }
+
+    tc.status = EditorAgentToolCallStatus::Cancelled;
+    let arg_json = tc.args.to_string();
+    msg.text = format!(
+        "[tool_call:{tool_name}] args: {arg_json} output: 用户已取消该操作",
+        tool_name = tc.tool_name,
+        arg_json = arg_json,
+    );
+
+    write_messages_document(&state, &conversation, &document).await?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        json!({ "ok": true }),
+    ))
+}
+
+pub async fn confirm_editor_agent_tool_call(
+    State(state): State<AppState>,
+    Path((conversation_id, message_id)): Path<(String, usize)>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    require_editor_agent_sidebar_enabled(&state, owner_user_id.as_str()).await?;
+    let conversation = state
+        .spacetime_client()
+        .get_editor_agent_conversation(conversation_id, owner_user_id)
+        .await
+        .map_err(|error| {
+            AppError::from_status(axum::http::StatusCode::NOT_FOUND).with_details(json!({
+                "message": format!("conversation not found: {error}"),
+            }))
+        })?;
+    let conversation_lock = crate::editor_agent::utils::editor_agent_conversation_lock(
+        conversation.conversation_id.as_str(),
+    );
+    let _conversation_lock_guard = conversation_lock.lock_owned().await;
+    let mut document = read_messages_document(&state, &conversation).await?;
+    let message = document
+        .messages
+        .get(message_id)
+        .ok_or_else(|| AppError::from_status(axum::http::StatusCode::NOT_FOUND))?;
+    if message.role != EditorAgentMessageRole::System {
+        return Err(editor_agent_bad_request("message is not a system message"));
+    }
+    let tool_call = message
+        .tool_call
+        .as_ref()
+        .ok_or_else(|| editor_agent_bad_request("message has no tool call"))?;
+    if tool_call.status == EditorAgentToolCallStatus::Cancelled {
+        return Err(editor_agent_bad_request("tool call was cancelled"));
+    }
+    if tool_call.status != EditorAgentToolCallStatus::NotCompleted
+        || tool_call.external_job_id.is_some()
+    {
+        return Ok(json_success_body(
+            Some(&request_context),
+            json!({ "ok": true }),
+        ));
+    }
+
+    let tool_name = tool_call.tool_name.clone();
+    let tool_args = tool_call.args.clone();
+    let pricing = state.editor_generation_pricing().await.map_err(|error| {
+        AppError::from_status(axum::http::StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+            "provider": "editor-generation-pricing",
+            "message": error.to_string(),
+        }))
+    })?;
+    let project = load_editor_agent_project(&state, &conversation).await?;
+    let context = context::build_tool_context(&document);
+    let generation_inputs = |title: &str, value: &str| {
+        Some(json!({
+          // TODO extract const
+            "source": "editor-agent",
+            "conversationId": conversation.conversation_id,
+            "toolCallMessageId": message_id,
+            "fields": [{ "title": title, "value": value }],
+        }))
+    };
+
+    let (job_kind, request_label, price_mud_points, payload) = match tool_name.as_str() {
+        GenerateImageTool::NAME | GenerateCharacterTool::NAME | GenerateUiDesignTool::NAME => {
+            let args: GenerateImageToolArgs = parse_confirm_tool_args(&tool_args)?;
+            let tool = GenerateImageTool {
+                context: context.clone(),
+            };
+            tool.validate_args(&args).map_err(|error| {
+                editor_agent_bad_request(format!("invalid tool call args: {error}"))
+            })?;
+            let kind = match tool_name.as_str() {
+                GenerateCharacterTool::NAME => Some("character"),
+                GenerateUiDesignTool::NAME => Some("ui-design"),
+                _ => None,
+            };
+            let price = match kind {
+                Some("character") => GenerateCharacterTool {
+                    context: context.clone(),
+                }
+                .pricing(&pricing, &args),
+                Some("ui-design") => GenerateUiDesignTool {
+                    context: context.clone(),
+                }
+                .pricing(&pricing, &args),
+                _ => tool.pricing(&pricing, &args),
+            };
+            let title = args.prompt.clone();
+            let reference_image_srcs = args
+                .reference_image_ids
+                .iter()
+                .map(|image_id| {
+                    context
+                        .image_data_key(image_id)
+                        .map(ToOwned::to_owned)
+                        .ok_or_else(|| {
+                            editor_agent_bad_request(format!("image {image_id} not found"))
+                        })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let payload = EditorImageGenerationRequest {
+                prompt: args.prompt,
+                size: None,
+                kind: kind.map(ToOwned::to_owned),
+                model: None,
+                screen_color: (kind == Some("character")).then(|| "auto".to_string()),
+                seg_model: (kind == Some("character")).then(|| "birefnet".to_string()),
+                aspect_ratio: args.aspect_ratio,
+                image_size: args.image_size,
+                reference_image_srcs: Some(reference_image_srcs),
+                project_id: Some(conversation.project_id.clone()),
+                asset_kind: Some(kind.unwrap_or("editor_agent_generated_image").to_string()),
+                generation_inputs: generation_inputs("用户指令", &title),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some(title.clone()),
+                source_resource_id: None,
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project, &tool_name, &title,
+                )),
+            };
+            (
+                EDITOR_IMAGE_GENERATION_JOB_KIND,
+                "画布 Agent 生成图片",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        EditImageTool::NAME => {
+            let args: EditImageToolArgs = parse_confirm_tool_args(&tool_args)?;
+            if args.prompt.trim().is_empty() {
+                return Err(editor_agent_bad_request("prompt not provided"));
+            }
+            let source_image_src = context
+                .image_data_key(&args.object_image_id)
+                .ok_or_else(|| editor_agent_bad_request("object image not found"))?
+                .to_string();
+            let reference_image_srcs = args
+                .reference_image_ids
+                .iter()
+                .map(|image_id| {
+                    context
+                        .image_data_key(image_id)
+                        .map(ToOwned::to_owned)
+                        .ok_or_else(|| {
+                            editor_agent_bad_request(format!("image {image_id} not found"))
+                        })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let title = args.prompt.clone();
+            let price = EditImageTool {
+                context: context.clone(),
+            }
+            .pricing(&pricing, &args);
+            let payload = EditorImageEditRequest {
+                prompt: args.prompt,
+                source_image_src,
+                size: None,
+                model: None,
+                aspect_ratio: None,
+                image_size: None,
+                reference_image_srcs: Some(reference_image_srcs),
+                project_id: Some(conversation.project_id.clone()),
+                asset_kind: Some("editor_agent_edit_image".to_string()),
+                generation_inputs: generation_inputs("用户指令", &title),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some(title.clone()),
+                source_resource_id: None,
+                target_layer_id: None,
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project,
+                    EditImageTool::NAME,
+                    &title,
+                )),
+            };
+            (
+                EDITOR_IMAGE_EDIT_JOB_KIND,
+                "画布 Agent 修改图片",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        GenerateIconSpritesheetTool::NAME => {
+            let args: GenerateIconSpritesheetToolArgs = parse_confirm_tool_args(&tool_args)?;
+            let tool = GenerateIconSpritesheetTool {
+                context: context.clone(),
+            };
+            let price = tool.pricing(&pricing, &args);
+            let reference_image_src = context
+                .image_data_key(&args.reference_image_id)
+                .ok_or_else(|| editor_agent_bad_request("reference image not found"))?
+                .to_string();
+            let reference_image_srcs = args
+                .reference_image_ids
+                .iter()
+                .map(|image_id| {
+                    context
+                        .image_data_key(image_id)
+                        .map(ToOwned::to_owned)
+                        .ok_or_else(|| {
+                            editor_agent_bad_request(format!("image {image_id} not found"))
+                        })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let payload = EditorIconSpritesheetGenerationRequest {
+                reference_image_src,
+                reference_image_srcs: Some(reference_image_srcs),
+                icon_descriptions: args.icon_descriptions.clone(),
+                model: None,
+                screen_color: Some("auto".to_string()),
+                seg_model: Some("birefnet".to_string()),
+                aspect_ratio: args.aspect_ratio,
+                image_size: args.image_size,
+                project_id: Some(conversation.project_id.clone()),
+                generation_inputs: Some(
+                    json!({"source":"editor-agent","conversationId":conversation.conversation_id,"toolCallMessageId":message_id}),
+                ),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some("图标素材图集".to_string()),
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project,
+                    GenerateIconSpritesheetTool::NAME,
+                    "图标素材图集",
+                )),
+            };
+            (
+                EDITOR_ICON_SPRITESHEET_GENERATION_JOB_KIND,
+                "画布 Agent 生成图标素材",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        GenerateVideoTool::NAME => {
+            let args: GenerateVideoToolArgs = parse_confirm_tool_args(&tool_args)?;
+            let reference_image_srcs = args
+                .reference_image_ids
+                .iter()
+                .map(|image_id| {
+                    context
+                        .image_data_key(image_id)
+                        .map(ToOwned::to_owned)
+                        .ok_or_else(|| {
+                            editor_agent_bad_request(format!("image {image_id} not found"))
+                        })
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let title = args.prompt.clone();
+            let price = GenerateVideoTool {
+                context: context.clone(),
+            }
+            .pricing(&pricing, &args);
+            let payload = EditorVideoGenerateRequest {
+                prompt: args.prompt,
+                model: args.model.unwrap_or_else(|| "seedance2.0-fast".to_string()),
+                aspect_ratio: args.aspect_ratio.unwrap_or_else(|| "16:9".to_string()),
+                duration_seconds: args.duration_seconds.unwrap_or(4),
+                resolution: args.resolution.unwrap_or_else(|| "720p".to_string()),
+                mode: "std".to_string(),
+                sound: args.sound.unwrap_or_else(|| "off".to_string()),
+                web_search_enabled: false,
+                reference_image_srcs,
+                reference_video_srcs: Vec::new(),
+                reference_audio_srcs: Vec::new(),
+                project_id: Some(conversation.project_id.clone()),
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project,
+                    GenerateVideoTool::NAME,
+                    &title,
+                )),
+                generation_inputs: generation_inputs("用户指令", &title),
+                source_resource_id: None,
+                asset_kind: Some("video".to_string()),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some(title),
+            };
+            (
+                EDITOR_VIDEO_GENERATION_JOB_KIND,
+                "画布 Agent 生成视频",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        GenerateSoundEffectTool::NAME => {
+            let args: GenerateSoundEffectToolArgs = parse_confirm_tool_args(&tool_args)?;
+            let price = GenerateSoundEffectTool.pricing(&pricing, &args);
+            let title = args.prompt.clone();
+            let payload = EditorSoundEffectGenerateRequest {
+                prompt: args.prompt,
+                model: None,
+                duration: args.duration.unwrap_or(3),
+                project_id: Some(conversation.project_id.clone()),
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project,
+                    GenerateSoundEffectTool::NAME,
+                    &title,
+                )),
+                generation_inputs: generation_inputs("用户指令", &title),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some(title),
+            };
+            (
+                EDITOR_SOUND_EFFECT_GENERATION_JOB_KIND,
+                "画布 Agent 生成音效",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        GenerateBackgroundMusicTool::NAME => {
+            let args: GenerateBackgroundMusicToolArgs = parse_confirm_tool_args(&tool_args)?;
+            let price = GenerateBackgroundMusicTool.pricing(&pricing, &args);
+            let title = args.prompt.clone();
+            let payload = EditorBackgroundMusicGenerateRequest {
+                gpt_description_prompt: args.prompt,
+                make_instrumental: args.make_instrumental,
+                project_id: Some(conversation.project_id.clone()),
+                canvas_completion: Some(build_editor_agent_canvas_completion(
+                    &project,
+                    GenerateBackgroundMusicTool::NAME,
+                    "生成背景音乐",
+                )),
+                generation_inputs: generation_inputs("用户指令", &title),
+                asset_folder_id: Some("project".to_string()),
+                asset_label: Some("生成背景音乐".to_string()),
+            };
+            (
+                EDITOR_BACKGROUND_MUSIC_GENERATION_JOB_KIND,
+                "画布 Agent 生成背景音乐",
+                price,
+                serde_json::to_value(payload),
+            )
+        }
+        _ => {
+            return Err(editor_agent_bad_request(format!(
+                "unsupported tool: {tool_name}"
+            )));
+        }
+    };
+    let payload = payload.map_err(|error| {
+        AppError::from_status(axum::http::StatusCode::INTERNAL_SERVER_ERROR)
+            .with_details(json!({"message": format!("failed to serialize tool payload: {error}")}))
+    })?;
+    let (job_id, dedupe_key) = editor_agent_tool_job_identity(
+        conversation.conversation_id.as_str(),
+        message_id,
+        tool_name.as_str(),
+    );
+    let job = enqueue_editor_generation_job_with_identity(
+        &state,
+        conversation.owner_user_id.as_str(),
+        job_kind,
+        conversation.project_id.clone(),
+        request_label,
+        u64::from(price_mud_points),
+        &payload,
+        job_id,
+        dedupe_key,
+    )
+    .await?;
+    let message = &mut document.messages[message_id];
+    let tool_call = message
+        .tool_call
+        .as_mut()
+        .ok_or_else(|| editor_agent_bad_request("message has no tool call"))?;
+    tool_call.external_job_id = Some(job.job_id);
+    tool_call.status = EditorAgentToolCallStatus::NotCompleted;
+    write_messages_document(&state, &conversation, &document).await?;
+    Ok(json_success_body(
+        Some(&request_context),
+        json!({ "ok": true }),
+    ))
+}
+
+fn parse_confirm_tool_args<T: serde::de::DeserializeOwned>(value: &Value) -> Result<T, AppError> {
+    serde_json::from_value(value.clone())
+        .map_err(|error| editor_agent_bad_request(format!("invalid tool call args: {error}")))
+}
+
+fn editor_agent_tool_job_identity(
+    conversation_id: &str,
+    message_id: usize,
+    tool_name: &str,
+) -> (String, String) {
+    let dedupe_key = format!("editor-agent:{conversation_id}:{message_id}:{tool_name}");
+    let digest = Sha256::digest(dedupe_key.as_bytes());
+    (format!("task-editor-agent-{digest:x}"), dedupe_key)
+}
+
+async fn load_editor_agent_project(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+) -> Result<spacetime_client::EditorProjectRecord, AppError> {
+    state
+        .spacetime_client()
+        .get_editor_project(EditorProjectGetRecordInput {
+            project_id: conversation.project_id.clone(),
+            owner_user_id: conversation.owner_user_id.clone(),
+        })
+        .await
+        .map_err(|error| {
+            AppError::from_status(axum::http::StatusCode::NOT_FOUND)
+                .with_details(json!({ "message": format!("project not found: {error}") }))
+        })
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/context.rs b/server-rs/crates/api-server/src/editor_agent/context.rs
new file mode 100644
index 000000000..d5a1f1e6b
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/context.rs
@@ -0,0 +1,37 @@
+use crate::editor_agent::utils::IntoDataKey;
+use platform_editor_agent::agent::asset::{ImageId, ImageMetadata};
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use shared_contracts::editor_agent::EditorAgentConversationMessagesDocument;
+use std::collections::HashMap;
+
+pub fn build_tool_context(document: &EditorAgentConversationMessagesDocument) -> EditorToolContext {
+    let mut images: HashMap<ImageId, ImageMetadata> = HashMap::new();
+
+    for msg in document.messages.iter().rev() {
+        // tool gen
+        if let Some(tc) = &msg.tool_call {
+            for img in &tc.images {
+                let data_key = img.clone().into_data_key();
+                let image_id = ImageId::from_data_key(&data_key);
+                let metadata = ImageMetadata {
+                    tag: String::new(),
+                    data_key,
+                };
+                images.insert(image_id, metadata);
+            }
+        }
+
+        // user pointed
+        for a in &msg.attachments {
+            let data_key = a.clone().into_data_key();
+            let image_id = ImageId::from_data_key(&data_key);
+            let metadata = ImageMetadata {
+                tag: String::new(),
+                data_key,
+            };
+            images.insert(image_id, metadata);
+        }
+    }
+
+    EditorToolContext { images }
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/display_args.rs b/server-rs/crates/api-server/src/editor_agent/display_args.rs
new file mode 100644
index 000000000..df0ca205d
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/display_args.rs
@@ -0,0 +1,329 @@
+use crate::editor_agent::pricing::EditorAgentPricedTool;
+use crate::editor_agent::utils::{IntoDataKey, IntoImageId};
+use crate::editor_generation_config::EditorGenerationPricingConfig;
+use platform_editor_agent::agent::asset::ImageId;
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{EditImageTool, EditImageToolArgs};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use platform_editor_agent::framework::error::PromptError;
+use platform_editor_agent::framework::tool::Tool;
+use serde_json::Value;
+use shared_contracts::editor_agent::{
+    EditorAgentConversationMessagesDocument, EditorAgentToolCallDisplayArgs,
+    EditorAgentToolCallDisplayExtras, EditorAgentToolCallImageArg, EditorAgentToolCallImageRef,
+    EditorAgentToolCallStringArg,
+};
+
+pub fn build_tool_call_display_args(
+    tool_name: &str,
+    args: &Value,
+    document: &EditorAgentConversationMessagesDocument,
+    tool_context: &EditorToolContext,
+    pricing: &EditorGenerationPricingConfig,
+) -> Result<EditorAgentToolCallDisplayArgs, PromptError> {
+    let mut display_args = EditorAgentToolCallDisplayArgs::default();
+
+    let price_mud_points = match tool_name {
+        EditImageTool::NAME => {
+            let args: EditImageToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = EditImageTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "修改要求", args.prompt);
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "object_image_id",
+                "目标图片",
+                std::slice::from_ref(&args.object_image_id),
+            )?;
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateImageTool::NAME | GenerateCharacterTool::NAME | GenerateUiDesignTool::NAME => {
+            let args: GenerateImageToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = match tool_name {
+                GenerateImageTool::NAME => GenerateImageTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                GenerateCharacterTool::NAME => GenerateCharacterTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                GenerateUiDesignTool::NAME => GenerateUiDesignTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                _ => unreachable!("tool name was matched above"),
+            };
+            push_string_display_arg(&mut display_args, "prompt", "提示词", args.prompt);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "画面比例",
+                args.aspect_ratio,
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "image_size",
+                "图片尺寸",
+                args.image_size,
+            );
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateIconSpritesheetTool::NAME => {
+            let args: GenerateIconSpritesheetToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateIconSpritesheetTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(
+                &mut display_args,
+                "icon_descriptions",
+                "图标描述",
+                args.icon_descriptions.join("\n"),
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "图集比例",
+                args.aspect_ratio,
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "image_size",
+                "图片尺寸",
+                args.image_size,
+            );
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_id",
+                "规范参考图",
+                std::slice::from_ref(&args.reference_image_id),
+            )?;
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "额外参考图",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateVideoTool::NAME => {
+            let args: GenerateVideoToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateVideoTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "视频描述", args.prompt);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "画面比例",
+                args.aspect_ratio,
+            );
+            if let Some(duration_seconds) = args.duration_seconds {
+                push_string_display_arg(
+                    &mut display_args,
+                    "duration_seconds",
+                    "时长（秒）",
+                    duration_seconds.to_string(),
+                );
+            }
+            push_optional_string_display_arg(&mut display_args, "model", "模型", args.model);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "resolution",
+                "分辨率",
+                args.resolution,
+            );
+            push_optional_string_display_arg(&mut display_args, "sound", "声音", args.sound);
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateSoundEffectTool::NAME => {
+            let args: GenerateSoundEffectToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateSoundEffectTool.pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "音效描述", args.prompt);
+            if let Some(duration) = args.duration {
+                push_string_display_arg(
+                    &mut display_args,
+                    "duration",
+                    "时长（秒）",
+                    duration.to_string(),
+                );
+            }
+            price_mud_points
+        }
+        GenerateBackgroundMusicTool::NAME => {
+            let args: GenerateBackgroundMusicToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateBackgroundMusicTool.pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "音乐描述", args.prompt);
+            push_string_display_arg(
+                &mut display_args,
+                "make_instrumental",
+                "纯音乐",
+                if args.make_instrumental { "是" } else { "否" },
+            );
+            price_mud_points
+        }
+        _ => {
+            return Err(PromptError::InternalError(format!(
+                "missing display argument mapping for tool {tool_name}"
+            )));
+        }
+    };
+
+    display_args.extras = EditorAgentToolCallDisplayExtras { price_mud_points };
+
+    Ok(display_args)
+}
+
+fn parse_display_tool_args<T>(tool_name: &str, args: &Value) -> Result<T, PromptError>
+where
+    T: serde::de::DeserializeOwned,
+{
+    serde_json::from_value(args.clone()).map_err(|error| {
+        PromptError::InternalError(format!(
+            "failed to build display arguments for {tool_name}: {error}"
+        ))
+    })
+}
+
+fn push_string_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    name: &str,
+    label: &str,
+    value: impl Into<String>,
+) {
+    let value = value.into();
+    if value.trim().is_empty() {
+        return;
+    }
+    display_args.string_args.push(EditorAgentToolCallStringArg {
+        name: name.to_string(),
+        label: label.to_string(),
+        value,
+    });
+}
+
+fn push_optional_string_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    name: &str,
+    label: &str,
+    value: Option<String>,
+) {
+    if let Some(value) = value {
+        push_string_display_arg(display_args, name, label, value);
+    }
+}
+
+fn push_image_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    document: &EditorAgentConversationMessagesDocument,
+    name: &str,
+    label: &str,
+    image_ids: &[ImageId],
+) -> Result<(), PromptError> {
+    if image_ids.is_empty() {
+        return Ok(());
+    }
+
+    let refs = image_ids
+        .iter()
+        .map(|image_id| {
+            resolve_tool_call_image_ref(document, image_id).ok_or_else(|| {
+                PromptError::InternalError(format!(
+                    "display image reference {} is missing from conversation context",
+                    image_id.id
+                ))
+            })
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+
+    display_args.image_args.push(EditorAgentToolCallImageArg {
+        name: name.to_string(),
+        label: label.to_string(),
+        refs,
+    });
+    Ok(())
+}
+
+pub fn resolve_tool_call_image_ref(
+    document: &EditorAgentConversationMessagesDocument,
+    image_id: &ImageId,
+) -> Option<EditorAgentToolCallImageRef> {
+    for message in document.messages.iter().rev() {
+        for attachment in message.attachments.iter().rev() {
+            if attachment.clone().into_image_id() == *image_id {
+                return Some(EditorAgentToolCallImageRef {
+                    image_id: image_id.id.clone(),
+                    image_src: attachment.image_src.clone(),
+                    object_key: attachment.object_key.clone(),
+                    thumbnail_src: attachment.thumbnail_src.clone(),
+                    label: attachment.label.clone(),
+                    width: attachment.width,
+                    height: attachment.height,
+                });
+            }
+        }
+
+        if let Some(tool_call) = &message.tool_call {
+            for image in tool_call.images.iter().rev() {
+                let data_key = image.clone().into_data_key();
+                if ImageId::from_data_key(data_key) == *image_id {
+                    return Some(EditorAgentToolCallImageRef {
+                        image_id: image_id.id.clone(),
+                        image_src: image.image_src.clone(),
+                        object_key: image.object_key.clone(),
+                        thumbnail_src: image.thumbnail_src.clone(),
+                        label: None,
+                        width: image.width,
+                        height: image.height,
+                    });
+                }
+            }
+        }
+    }
+
+    None
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/mod.rs b/server-rs/crates/api-server/src/editor_agent/mod.rs
new file mode 100644
index 000000000..eaa31b0fe
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/mod.rs
@@ -0,0 +1,13 @@
+pub mod api;
+mod context;
+mod display_args;
+pub mod pricing;
+mod reconcile;
+mod resp_to_asset;
+mod utils;
+
+pub use api::{
+    cancel_editor_agent_tool_call, confirm_editor_agent_tool_call,
+    create_editor_agent_conversation, delete_editor_agent_conversation,
+    get_editor_agent_conversation, list_editor_agent_conversations,
+};
diff --git a/server-rs/crates/api-server/src/editor_agent/pricing.rs b/server-rs/crates/api-server/src/editor_agent/pricing.rs
new file mode 100644
index 000000000..42bd43e47
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/pricing.rs
@@ -0,0 +1,313 @@
+use crate::editor_generation_config::EditorGenerationPricingConfig;
+#[cfg(test)]
+use crate::editor_generation_config::load_editor_generation_pricing_from_paths;
+#[cfg(test)]
+use platform_editor_agent::agent::asset::ImageId;
+#[cfg(test)]
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{EditImageTool, EditImageToolArgs};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use platform_editor_agent::framework::tool::Tool;
+use platform_image::GPT_IMAGE_2_MODEL;
+#[cfg(test)]
+use std::collections::HashMap;
+
+#[cfg(test)]
+fn context() -> EditorToolContext {
+    EditorToolContext {
+        images: HashMap::new(),
+    }
+}
+
+#[cfg(test)]
+fn image_args(image_size: Option<&str>) -> GenerateImageToolArgs {
+    GenerateImageToolArgs {
+        prompt: "生成图片".to_string(),
+        reference_image_ids: Vec::new(),
+        aspect_ratio: Some("1:1".to_string()),
+        image_size: image_size.map(ToOwned::to_owned),
+    }
+}
+
+#[test]
+fn every_editor_agent_tool_exposes_argument_based_pricing() {
+    let pricing = load_editor_generation_pricing_from_paths(None)
+        .expect("default editor pricing should load");
+    let context = context();
+
+    assert_eq!(
+        EditImageTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &EditImageToolArgs {
+                object_image_id: ImageId {
+                    id: "image-1".to_string(),
+                },
+                reference_image_ids: Vec::new(),
+                prompt: "改成蓝色".to_string(),
+            },
+        ),
+        3
+    );
+    assert_eq!(
+        GenerateImageTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(Some("2K"))),
+        5
+    );
+    assert_eq!(
+        GenerateCharacterTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(None)),
+        3
+    );
+    assert_eq!(
+        GenerateUiDesignTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(Some("2K"))),
+        5
+    );
+    assert_eq!(
+        GenerateIconSpritesheetTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &GenerateIconSpritesheetToolArgs {
+                reference_image_id: ImageId {
+                    id: "image-1".to_string(),
+                },
+                reference_image_ids: Vec::new(),
+                icon_descriptions: vec!["背包".to_string(), "地图".to_string()],
+                aspect_ratio: Some("1:1".to_string()),
+                image_size: Some("2K".to_string()),
+            },
+        ),
+        5
+    );
+    assert_eq!(
+        GenerateVideoTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &GenerateVideoToolArgs {
+                prompt: "镜头缓慢推进".to_string(),
+                reference_image_ids: Vec::new(),
+                aspect_ratio: None,
+                duration_seconds: Some(6),
+                model: Some("seedance2.0".to_string()),
+                resolution: Some("720p".to_string()),
+                sound: None,
+            },
+        ),
+        144
+    );
+    assert_eq!(
+        GenerateSoundEffectTool.pricing(
+            &pricing,
+            &GenerateSoundEffectToolArgs {
+                prompt: "按钮点击声".to_string(),
+                duration: None,
+            },
+        ),
+        5
+    );
+    assert_eq!(
+        GenerateBackgroundMusicTool.pricing(
+            &pricing,
+            &GenerateBackgroundMusicToolArgs {
+                prompt: "轻松背景音乐".to_string(),
+                make_instrumental: true,
+            },
+        ),
+        12
+    );
+}
+
+#[test]
+fn pricing_uses_the_supplied_runtime_snapshot() {
+    let mut pricing = load_editor_generation_pricing_from_paths(None)
+        .expect("default editor pricing should load");
+    pricing
+        .models
+        .get_mut("gpt-image-2")
+        .expect("gpt image pricing should exist")
+        .prices
+        .insert("2K".to_string(), 37);
+    pricing
+        .models
+        .get_mut("seedance2.0-fast")
+        .expect("video pricing should exist")
+        .prices
+        .insert("720p".to_string(), 7);
+    pricing
+        .models
+        .get_mut("audio1.0")
+        .expect("sound pricing should exist")
+        .price = Some(19);
+
+    assert_eq!(
+        GenerateImageTool { context: context() }.pricing(&pricing, &image_args(Some("2K"))),
+        37
+    );
+    assert_eq!(
+        GenerateVideoTool { context: context() }.pricing(
+            &pricing,
+            &GenerateVideoToolArgs {
+                prompt: "four seconds".to_string(),
+                reference_image_ids: Vec::new(),
+                aspect_ratio: None,
+                duration_seconds: None,
+                model: None,
+                resolution: None,
+                sound: None,
+            },
+        ),
+        28
+    );
+    assert_eq!(
+        GenerateSoundEffectTool.pricing(
+            &pricing,
+            &GenerateSoundEffectToolArgs {
+                prompt: "sound".to_string(),
+                duration: None,
+            },
+        ),
+        19
+    );
+}
+
+impl EditorAgentPricedTool for GenerateVideoTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateVideoToolArgs,
+    ) -> u32 {
+        let model = args
+            .model
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .unwrap_or(Self::DEFAULT_VIDEO_MODEL);
+        let resolution = args
+            .resolution
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .unwrap_or(Self::DEFAULT_VIDEO_RESOLUTION);
+        let duration_seconds = args
+            .duration_seconds
+            .unwrap_or(Self::DEFAULT_VIDEO_DURATION_SECONDS);
+        pricing.video_model_mud_points(Some(model), resolution, duration_seconds)
+    }
+}
+
+impl EditorAgentPricedTool for GenerateUiDesignTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("ui-design"), args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateSoundEffectTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        _args: &GenerateSoundEffectToolArgs,
+    ) -> u32 {
+        pricing.sound_effect_model_mud_points(None)
+    }
+}
+
+impl EditorAgentPricedTool for GenerateImageTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, None, args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateIconSpritesheetTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateIconSpritesheetToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("icon"), args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateCharacterTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("character"), args.image_size.as_deref())
+    }
+}
+
+/// api-server 侧的画布 Agent 工具计价扩展。
+///
+/// 通用 `Tool` 仍只负责参数校验；价格依赖 api-server 的运行时配置，不能下沉到
+/// `module-editor-agent`。实际执行和扣费仍由既有生成 BFF 负责。
+pub(crate) trait EditorAgentPricedTool: Tool {
+    fn pricing(&self, pricing: &EditorGenerationPricingConfig, args: &<Self as Tool>::Args) -> u32;
+}
+
+pub(crate) fn editor_agent_image_mud_points(
+    pricing: &EditorGenerationPricingConfig,
+    kind: Option<&str>,
+    image_size: Option<&str>,
+) -> u32 {
+    // 这些 Agent 工具当前向既有 BFF 传 model=None；BFF 会先归一为 gpt-image-2。
+    // 尺寸同样只把精确的 2K 识别为 2K，其余值回落到 1K。
+    let normalized_image_size = match image_size.map(str::trim) {
+        Some("2K") => "2K",
+        _ => "1K",
+    };
+    pricing.image_generation_mud_points(kind, Some(GPT_IMAGE_2_MODEL), Some(normalized_image_size))
+}
+
+impl EditorAgentPricedTool for GenerateBackgroundMusicTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        _args: &GenerateBackgroundMusicToolArgs,
+    ) -> u32 {
+        pricing.background_music_model_mud_points(None)
+    }
+}
+
+impl EditorAgentPricedTool for EditImageTool {
+    fn pricing(&self, pricing: &EditorGenerationPricingConfig, _args: &EditImageToolArgs) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("quick-edit"), Some("1K"))
+    }
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/reconcile.rs b/server-rs/crates/api-server/src/editor_agent/reconcile.rs
new file mode 100644
index 000000000..20d21a02f
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/reconcile.rs
@@ -0,0 +1,369 @@
+use crate::editor_agent::resp_to_asset;
+use crate::http_error::AppError;
+use crate::state::AppState;
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{
+    EditImageTool, EditImageToolArgs, EditorImageEditResult,
+};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    EditorIconSpritesheetResult, GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    EditorImageGenerationResult, GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use platform_editor_agent::framework::tool::Tool;
+use serde_json::Value;
+use shared_contracts::assets::{EditorAudioGenerateResponse, EditorVideoGenerateResponse};
+use shared_contracts::editor_agent::{
+    EditorAgentConversationMessagesDocument, EditorAgentMessage, EditorAgentToolCallStatus,
+};
+use spacetime_client::{EditorAgentConversationRecord, ExternalGenerationJobGetRecordInput};
+use tokio::time::{Duration, sleep};
+
+pub(crate) const EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES: u8 = 3;
+const EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY: Duration = Duration::from_millis(100);
+
+#[derive(Debug, PartialEq)]
+enum ResultReconcileFailure {
+    RetryLater(String),
+    Fatal(String),
+}
+
+impl From<String> for ResultReconcileFailure {
+    fn from(error: String) -> Self {
+        Self::Fatal(error)
+    }
+}
+
+pub async fn reconcile_editor_agent_tool_calls(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+    document: &mut EditorAgentConversationMessagesDocument,
+) -> Result<Vec<EditorAgentMessage>, AppError> {
+    let candidates = document
+        .messages
+        .iter()
+        .enumerate()
+        .filter_map(|(message_index, message)| {
+            let tool_call = message.tool_call.as_ref()?;
+            if tool_call.status != EditorAgentToolCallStatus::NotCompleted {
+                return None;
+            }
+            Some((message_index, tool_call.external_job_id.clone()?))
+        })
+        .collect::<Vec<_>>();
+    let mut reconciled = Vec::new();
+
+    for (message_index, job_id) in candidates {
+        let mut last_reconcile_error = None;
+
+        for retry_count in 0..=EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES {
+            let job = match state
+                .spacetime_client()
+                .get_external_generation_job_generated_artifacts(
+                    ExternalGenerationJobGetRecordInput {
+                        job_id: job_id.clone(),
+                        owner_user_id: conversation.owner_user_id.clone(),
+                    },
+                )
+                .await
+            {
+                Ok(job) => job,
+                Err(error) => {
+                    last_reconcile_error = Some(ResultReconcileFailure::RetryLater(format!(
+                        "读取生成任务结果失败：{error}"
+                    )));
+                    if should_retry_result_reconcile(retry_count) {
+                        sleep(EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY).await;
+                    }
+                    continue;
+                }
+            };
+
+            match job.status.as_str() {
+                "completed" => {
+                    let original_message = document.messages[message_index].clone();
+                    match reconcile_completed_editor_agent_tool_call(
+                        &mut document.messages[message_index],
+                        job.result_payload_json.as_deref(),
+                    ) {
+                        Ok(()) => {
+                            last_reconcile_error = None;
+                            reconciled.push(document.messages[message_index].clone());
+                            break;
+                        }
+                        Err(error) => {
+                            document.messages[message_index] = original_message;
+                            last_reconcile_error = Some(error);
+                        }
+                    }
+                }
+                "failed" => {
+                    mark_job_failed(
+                        &mut document.messages[message_index],
+                        job.last_error_message
+                            .unwrap_or_else(|| "生成失败".to_string()),
+                    );
+                    last_reconcile_error = None;
+                    reconciled.push(document.messages[message_index].clone());
+                    break;
+                }
+                _ => {
+                    last_reconcile_error = None;
+                    break;
+                }
+            }
+
+            if should_retry_result_reconcile(retry_count) {
+                sleep(EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY).await;
+            }
+        }
+
+        if let Some(error) = last_reconcile_error
+            && apply_exhausted_result_reconcile_failure(
+                &mut document.messages[message_index],
+                error,
+            )
+        {
+            reconciled.push(document.messages[message_index].clone());
+        }
+    }
+
+    Ok(reconciled)
+}
+
+fn should_retry_result_reconcile(retry_count: u8) -> bool {
+    retry_count < EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES
+}
+
+fn mark_job_failed(message: &mut EditorAgentMessage, error: String) {
+    let tool_call = message
+        .tool_call
+        .as_mut()
+        .expect("reconcile candidate contains a tool call");
+    tool_call.error = Some(error.clone());
+    tool_call.status = EditorAgentToolCallStatus::Failed;
+    message.text = format!("[tool_call:{}] output: {error}", tool_call.tool_name);
+}
+
+fn mark_fatal_result_reconcile_failed(message: &mut EditorAgentMessage, error: String) {
+    mark_job_failed(
+        message,
+        format!(
+            "任务终态结果回填重试 {EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES} 次后仍失败：{error}"
+        ),
+    );
+}
+
+fn apply_exhausted_result_reconcile_failure(
+    message: &mut EditorAgentMessage,
+    failure: ResultReconcileFailure,
+) -> bool {
+    match failure {
+        ResultReconcileFailure::RetryLater(_) => false,
+        ResultReconcileFailure::Fatal(error) => {
+            mark_fatal_result_reconcile_failed(message, error);
+            true
+        }
+    }
+}
+
+fn reconcile_completed_editor_agent_tool_call(
+    message: &mut EditorAgentMessage,
+    result_payload_json: Option<&str>,
+) -> Result<(), ResultReconcileFailure> {
+    let response = result_payload_json
+        .ok_or_else(|| ResultReconcileFailure::RetryLater("生成任务缺少结果数据".to_string()))
+        .and_then(|payload| {
+            serde_json::from_str::<Value>(payload)
+                .map_err(|error| ResultReconcileFailure::Fatal(error.to_string()))
+        })?
+        // TODO extract const
+        .get("editor-agent-tool-call-result")
+        .cloned()
+        .ok_or_else(|| {
+            ResultReconcileFailure::Fatal("生成任务缺少 Agent 工具调用结果".to_string())
+        })?;
+    let tool_call = message
+        .tool_call
+        .as_mut()
+        .ok_or_else(|| ResultReconcileFailure::Fatal("消息缺少工具调用".to_string()))?;
+    let tool_name = tool_call.tool_name.clone();
+
+    match tool_name.as_str() {
+        GenerateImageTool::NAME | GenerateCharacterTool::NAME | GenerateUiDesignTool::NAME => {
+            let args: GenerateImageToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorImageGenerationResult = parse_reconciled_value(&response)?;
+            message.text = match tool_name.as_str() {
+                GenerateCharacterTool::NAME => GenerateCharacterTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+                GenerateUiDesignTool::NAME => GenerateUiDesignTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+                _ => GenerateImageTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+            };
+            tool_call.images = vec![resp_to_asset::editor_agent_generated_image(&result)];
+        }
+        EditImageTool::NAME => {
+            let args: EditImageToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorImageEditResult = parse_reconciled_value(&response)?;
+            tool_call.images = vec![resp_to_asset::editor_agent_generated_edited_image(&result)];
+            message.text = EditImageTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(args, result);
+        }
+        GenerateIconSpritesheetTool::NAME => {
+            let args: GenerateIconSpritesheetToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorIconSpritesheetResult = parse_reconciled_value(&response)?;
+            message.text = GenerateIconSpritesheetTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(&args, &result);
+            tool_call.images = resp_to_asset::editor_agent_generated_spritesheet_images(&result);
+        }
+        GenerateVideoTool::NAME => {
+            let args: GenerateVideoToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorVideoGenerateResponse = parse_reconciled_value(&response)?;
+            message.text = GenerateVideoTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(&args, &result);
+            tool_call.videos = vec![resp_to_asset::editor_agent_generated_video(&result)];
+        }
+        GenerateSoundEffectTool::NAME | GenerateBackgroundMusicTool::NAME => {
+            let result: EditorAudioGenerateResponse = parse_reconciled_value(&response)?;
+            message.text = if tool_name == GenerateSoundEffectTool::NAME {
+                let args: GenerateSoundEffectToolArgs = parse_reconciled_value(&tool_call.args)?;
+                GenerateSoundEffectTool.format_execute_message(&args, &result)
+            } else {
+                let args: GenerateBackgroundMusicToolArgs =
+                    parse_reconciled_value(&tool_call.args)?;
+                GenerateBackgroundMusicTool.format_execute_message(&args, &result)
+            };
+            tool_call.audios = vec![resp_to_asset::editor_agent_generated_audio(&result)];
+        }
+        _ => {
+            return Err(ResultReconcileFailure::Fatal(format!(
+                "不支持回填工具 {tool_name}"
+            )));
+        }
+    }
+    tool_call.error = None;
+    tool_call.status = EditorAgentToolCallStatus::Completed;
+    Ok(())
+}
+
+fn parse_reconciled_value<T: serde::de::DeserializeOwned>(value: &Value) -> Result<T, String> {
+    serde_json::from_value(value.clone()).map_err(|error| error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn pending_tool_message() -> EditorAgentMessage {
+        serde_json::from_value(json!({
+            "id": 1,
+            "role": "system",
+            "text": "waiting",
+            "attachments": [],
+            "toolCall": {
+                "toolName": "generate_image",
+                "status": "not_completed",
+                "args": {},
+                "displayArgs": {
+                    "stringArgs": [],
+                    "imageArgs": [],
+                    "extras": { "priceMudPoints": 0 }
+                },
+                "externalJobId": "job-1",
+                "images": []
+            },
+            "createdAt": "2026-07-16T00:00:00Z"
+        }))
+        .expect("pending tool message should deserialize")
+    }
+
+    #[test]
+    fn terminal_result_reconcile_retries_three_times_after_the_initial_attempt() {
+        assert!(should_retry_result_reconcile(0));
+        assert!(should_retry_result_reconcile(1));
+        assert!(should_retry_result_reconcile(2));
+        assert!(!should_retry_result_reconcile(3));
+    }
+
+    #[test]
+    fn exhausted_fatal_result_reconcile_marks_the_tool_call_failed() {
+        let mut message = pending_tool_message();
+
+        let changed = apply_exhausted_result_reconcile_failure(
+            &mut message,
+            ResultReconcileFailure::Fatal("invalid result payload".to_string()),
+        );
+
+        assert!(changed);
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::Failed);
+        assert_eq!(
+            tool_call.error.as_deref(),
+            Some("任务终态结果回填重试 3 次后仍失败：invalid result payload")
+        );
+        assert!(message.text.contains("重试 3 次后仍失败"));
+    }
+
+    #[test]
+    fn missing_result_payload_is_retryable_and_preserves_pending_job_reference() {
+        let mut message = pending_tool_message();
+
+        let error = reconcile_completed_editor_agent_tool_call(&mut message, None)
+            .expect_err("missing result payload should be retried later");
+
+        assert_eq!(
+            error,
+            ResultReconcileFailure::RetryLater("生成任务缺少结果数据".to_string())
+        );
+        assert!(!apply_exhausted_result_reconcile_failure(
+            &mut message,
+            error,
+        ));
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::NotCompleted);
+        assert_eq!(tool_call.external_job_id.as_deref(), Some("job-1"));
+        assert_eq!(tool_call.error, None);
+    }
+
+    #[test]
+    fn read_failure_is_retryable_without_terminal_message_mutation() {
+        let mut message = pending_tool_message();
+        let error = ResultReconcileFailure::RetryLater(
+            "读取生成任务结果失败：temporarily unavailable".to_string(),
+        );
+
+        assert!(!apply_exhausted_result_reconcile_failure(
+            &mut message,
+            error,
+        ));
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::NotCompleted);
+        assert_eq!(tool_call.external_job_id.as_deref(), Some("job-1"));
+    }
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/resp_to_asset.rs b/server-rs/crates/api-server/src/editor_agent/resp_to_asset.rs
new file mode 100644
index 000000000..014a7d159
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/resp_to_asset.rs
@@ -0,0 +1,105 @@
+use platform_editor_agent::agent::tools::edit_image::EditorImageEditResult;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::EditorIconSpritesheetResult;
+use platform_editor_agent::agent::tools::generate_image::EditorImageGenerationResult;
+use serde_json::Value;
+use shared_contracts::assets::{EditorAudioGenerateResponse, EditorVideoGenerateResponse};
+use shared_contracts::editor_agent::{
+    EditorAgentGeneratedAudio, EditorAgentGeneratedImage, EditorAgentGeneratedVideo,
+};
+
+fn value_string(value: Option<&Value>, field: &str) -> Option<String> {
+    value
+        .and_then(|resource| resource.get(field))
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned)
+}
+
+pub fn editor_agent_generated_image(
+    result: &EditorImageGenerationResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        image_src: result.image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_edited_image(
+    result: &EditorImageEditResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        image_src: result.image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_spritesheet(
+    result: &EditorIconSpritesheetResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.spritesheet_resource.as_ref(), "resourceId"),
+        object_key: value_string(result.spritesheet_resource.as_ref(), "objectKey"),
+        asset_object_id: value_string(result.spritesheet_resource.as_ref(), "assetObjectId"),
+        image_src: result.spritesheet_image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.spritesheet_width),
+        height: Some(result.spritesheet_height),
+    }
+}
+
+pub fn editor_agent_generated_spritesheet_images(
+    result: &EditorIconSpritesheetResult,
+) -> Vec<EditorAgentGeneratedImage> {
+    let images = result
+        .icon_image_srcs
+        .iter()
+        .map(|image| EditorAgentGeneratedImage {
+            resource_id: value_string(image.resource.as_ref(), "resourceId"),
+            object_key: value_string(image.resource.as_ref(), "objectKey"),
+            asset_object_id: value_string(image.resource.as_ref(), "assetObjectId"),
+            image_src: image.image_src.clone(),
+            thumbnail_src: None,
+            width: Some(image.width),
+            height: Some(image.height),
+        })
+        .collect::<Vec<_>>();
+    if images.is_empty() {
+        vec![editor_agent_generated_spritesheet(result)]
+    } else {
+        images
+    }
+}
+
+pub fn editor_agent_generated_video(
+    result: &EditorVideoGenerateResponse,
+) -> EditorAgentGeneratedVideo {
+    EditorAgentGeneratedVideo {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        video_src: result.video_src.clone(),
+        thumbnail_src: result.thumbnail_src.clone(),
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_audio(
+    result: &EditorAudioGenerateResponse,
+) -> EditorAgentGeneratedAudio {
+    EditorAgentGeneratedAudio {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        audio_src: result.audio_src.clone(),
+    }
+}
diff --git a/server-rs/crates/api-server/src/editor_agent/utils.rs b/server-rs/crates/api-server/src/editor_agent/utils.rs
new file mode 100644
index 000000000..27ce6e423
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_agent/utils.rs
@@ -0,0 +1,613 @@
+use crate::editor_project::{current_utc_micros, map_editor_project_error};
+use crate::http_error::AppError;
+use crate::platform_errors::map_oss_error;
+use crate::state::AppState;
+use axum::http::StatusCode;
+use platform_editor_agent::agent::asset::ImageId;
+use platform_oss::{
+    LegacyAssetPrefix, OssObjectAccess, OssPutObjectRequest, OssSignedGetObjectUrlRequest,
+};
+use serde_json::{Value, json};
+use shared_contracts::assets::{
+    EditorCanvasGenerationCompletionPayload, EditorCanvasGenerationPlaceholderPayload,
+};
+use shared_contracts::editor_agent::{
+    EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION, EditorAgentAttachmentRef, EditorAgentAttachmentSource,
+    EditorAgentConversationDetail, EditorAgentConversationMessagesDocument,
+    EditorAgentConversationSummary, EditorAgentGeneratedImage, EditorAgentMessage,
+};
+use shared_kernel::{normalize_optional_string, normalize_required_string};
+use spacetime_client::{
+    EditorAgentConversationRecord, EditorAssetLibraryRecord, EditorAssetRecord,
+    EditorProjectGetRecordInput, EditorProjectRecord, EditorProjectResourceRecord,
+};
+use std::collections::BTreeMap;
+use std::sync::{Arc, Mutex, OnceLock};
+
+pub trait IntoDataKey {
+    fn into_data_key(self) -> String;
+}
+impl IntoDataKey for EditorAgentAttachmentRef {
+    fn into_data_key(self) -> String {
+        self.object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            // .or_else(|| normalize_required_string(self.reference_id.as_str()))
+            .unwrap_or_else(|| self.image_src.clone())
+    }
+}
+impl IntoDataKey for EditorAgentGeneratedImage {
+    fn into_data_key(self) -> String {
+        self.object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or(self.image_src)
+    }
+}
+impl IntoDataKey for EditorProjectResourceRecord {
+    fn into_data_key(self) -> String {
+        self.object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| self.image_src.clone())
+    }
+}
+
+impl IntoDataKey for EditorAssetRecord {
+    fn into_data_key(self) -> String {
+        self.object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| self.image_src.clone())
+    }
+}
+
+pub trait IntoImageId {
+    fn into_image_id(self) -> ImageId;
+}
+impl IntoImageId for EditorAgentAttachmentRef {
+    fn into_image_id(self) -> ImageId {
+        ImageId::from_data_key(self.into_data_key())
+    }
+}
+impl IntoImageId for EditorProjectResourceRecord {
+    fn into_image_id(self) -> ImageId {
+        ImageId::from_data_key(self.into_data_key())
+    }
+}
+impl IntoImageId for EditorAssetRecord {
+    fn into_image_id(self) -> ImageId {
+        ImageId::from_data_key(self.into_data_key())
+    }
+}
+
+// TODO resource id is not traced by now
+// pub trait IntoResourceId {
+//     fn into_resource_id(self) -> String;
+// }
+//
+// impl IntoResourceId for EditorProjectResourceRecord {
+//     fn into_resource_id(self) -> String {
+//         self.resource_id
+//     }
+// }
+//
+// impl IntoResourceId for EditorAssetRecord {
+//     fn into_resource_id(self) -> String {
+//         self.asset_id
+//     }
+// }
+
+#[cfg(test)]
+mod image_id_tests {
+    use platform_editor_agent::agent::asset::ImageId;
+
+    #[test]
+    fn image_id_is_a_stable_hash_of_the_data_key() {
+        let data_key = "editor-projects/proj-1/image.png";
+        let image_id = ImageId::from_data_key(data_key);
+
+        assert_eq!(image_id, ImageId::from_data_key(data_key));
+        assert_ne!(image_id, ImageId::from_data_key("another-image.png"));
+        assert!(image_id.id.starts_with("sha256:"));
+        assert!(!image_id.id.contains(data_key));
+    }
+}
+
+type EditorAgentConversationLockMap = Mutex<BTreeMap<String, Arc<tokio::sync::Mutex<()>>>>;
+static EDITOR_AGENT_CONVERSATION_LOCKS: OnceLock<EditorAgentConversationLockMap> = OnceLock::new();
+
+pub fn editor_agent_conversation_lock(conversation_id: &str) -> Arc<tokio::sync::Mutex<()>> {
+    let locks = EDITOR_AGENT_CONVERSATION_LOCKS.get_or_init(|| Mutex::new(BTreeMap::new()));
+    let mut locks = locks
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    locks
+        .entry(conversation_id.to_string())
+        .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
+        .clone()
+}
+pub fn now_rfc3339() -> String {
+    shared_kernel::format_rfc3339(time::OffsetDateTime::now_utc())
+        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
+}
+
+const EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES: usize = 2 * 1024 * 1024;
+pub async fn require_editor_agent_sidebar_enabled(
+    state: &AppState,
+    owner_user_id: &str,
+) -> Result<(), AppError> {
+    match state
+        .is_image_editor_agent_sidebar_enabled_for_user(Some(owner_user_id))
+        .await
+    {
+        Ok(true) => Ok(()),
+        Ok(false) => Err(editor_agent_sidebar_unavailable()),
+        Err(error) => Err(AppError::from_status(StatusCode::BAD_GATEWAY)
+            .with_message("读取画布 Agent 灰度配置失败")
+            .with_details(json!({
+                "provider": "spacetimedb",
+                "message": error.to_string(),
+            }))),
+    }
+}
+
+fn editor_agent_sidebar_unavailable() -> AppError {
+    AppError::from_status(StatusCode::SERVICE_UNAVAILABLE)
+        .with_message("画布 Agent 暂不可用")
+        .with_details(json!({
+            "provider": "editor-agent",
+            "reason": "image_editor_agent_sidebar_disabled",
+            "gateKey": module_runtime::IMAGE_EDITOR_AGENT_SIDEBAR_GATE_KEY,
+        }))
+}
+// const EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES: usize = 2 * 1024 * 1024;
+pub fn editor_agent_bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "editor-agent",
+        "message": message.into(),
+    }))
+}
+
+fn editor_agent_oss_unavailable() -> AppError {
+    AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+        "provider": "aliyun-oss",
+        "reason": "OSS is not configured for editor agent conversations",
+    }))
+}
+
+fn editor_agent_oss_read_error(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+        "provider": "aliyun-oss",
+        "message": message.into(),
+    }))
+}
+
+fn editor_agent_messages_document_too_large() -> AppError {
+    AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE).with_details(json!({
+        "provider": "editor-agent",
+        "message": "message document is too large",
+        "maxBytes": EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES,
+    }))
+}
+pub async fn write_messages_document(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+    document: &EditorAgentConversationMessagesDocument,
+) -> Result<(), AppError> {
+    if document.conversation_id != conversation.conversation_id {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-agent",
+                "message": "message document conversationId does not match metadata",
+            })),
+        );
+    }
+    let body = serde_json::to_vec(document).map_err(|error| {
+        AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+            "provider": "editor-agent",
+            "message": format!("failed to serialize message document: {error}"),
+        }))
+    })?;
+    if body.len() > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES {
+        return Err(editor_agent_messages_document_too_large());
+    }
+
+    let oss_client = state
+        .oss_client()
+        .ok_or_else(editor_agent_oss_unavailable)?;
+    let put_result = oss_client
+        .put_object(
+            &reqwest::Client::new(),
+            OssPutObjectRequest {
+                prefix: LegacyAssetPrefix::EditorAgent,
+                path_segments: Vec::new(),
+                file_name: format!("{}.json", conversation.conversation_id),
+                content_type: Some("application/json; charset=utf-8".to_string()),
+                access: OssObjectAccess::Private,
+                metadata: BTreeMap::from([
+                    (
+                        "conversation-id".to_string(),
+                        conversation.conversation_id.clone(),
+                    ),
+                    ("project-id".to_string(), conversation.project_id.clone()),
+                    (
+                        "owner-user-id".to_string(),
+                        conversation.owner_user_id.clone(),
+                    ),
+                ]),
+                body,
+            },
+        )
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    if put_result.object_key != conversation.messages_object_key {
+        return Err(
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                "provider": "editor-agent",
+                "message": "OSS object key mismatch while writing message document",
+                "expectedObjectKey": conversation.messages_object_key,
+                "actualObjectKey": put_result.object_key,
+            })),
+        );
+    }
+    Ok(())
+}
+
+const EDITOR_AGENT_MESSAGES_READ_EXPIRE_SECONDS: u64 = 60;
+
+pub async fn read_messages_document(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+) -> Result<EditorAgentConversationMessagesDocument, AppError> {
+    let oss_client = state
+        .oss_client()
+        .ok_or_else(editor_agent_oss_unavailable)?;
+    let signed = oss_client
+        .sign_internal_get_object_url(OssSignedGetObjectUrlRequest {
+            object_key: conversation.messages_object_key.clone(),
+            expire_seconds: Some(EDITOR_AGENT_MESSAGES_READ_EXPIRE_SECONDS),
+        })
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    let response = reqwest::Client::new()
+        .get(signed.signed_url.as_str())
+        .send()
+        .await
+        .map_err(|error| editor_agent_oss_read_error(error.to_string()))?;
+    if response.status() == StatusCode::NOT_FOUND {
+        return Ok(empty_messages_document(
+            conversation.conversation_id.as_str(),
+        ));
+    }
+    if !response.status().is_success() {
+        return Err(editor_agent_oss_read_error(format!(
+            "OSS returned non-success status {}",
+            response.status().as_u16()
+        )));
+    }
+    if response
+        .content_length()
+        .is_some_and(|size| size > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES as u64)
+    {
+        return Err(editor_agent_messages_document_too_large());
+    }
+    let bytes = response
+        .bytes()
+        .await
+        .map_err(|error| editor_agent_oss_read_error(error.to_string()))?;
+    if bytes.is_empty() {
+        return Ok(empty_messages_document(
+            conversation.conversation_id.as_str(),
+        ));
+    }
+    if bytes.len() > EDITOR_AGENT_MESSAGES_DOCUMENT_MAX_BYTES {
+        return Err(editor_agent_messages_document_too_large());
+    }
+    let document: EditorAgentConversationMessagesDocument = serde_json::from_slice(&bytes)
+        .map_err(|error| {
+            editor_agent_oss_read_error(format!("message document JSON invalid: {error}"))
+        })?;
+    if document.conversation_id != conversation.conversation_id {
+        return Err(
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "editor-agent",
+                "message": "message document conversationId does not match metadata",
+                "conversationId": conversation.conversation_id,
+                "documentConversationId": document.conversation_id,
+            })),
+        );
+    }
+    Ok(document)
+}
+
+pub async fn ensure_editor_project_access(
+    state: &AppState,
+    project_id: &str,
+    owner_user_id: &str,
+) -> Result<(), AppError> {
+    state
+        .spacetime_client()
+        .get_editor_project(EditorProjectGetRecordInput {
+            project_id: project_id.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+        })
+        .await
+        .map(|_| ())
+        .map_err(map_editor_project_error)
+}
+
+pub async fn normalize_editor_agent_attachments(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+    attachments: &[EditorAgentAttachmentRef],
+) -> Result<Vec<EditorAgentAttachmentRef>, AppError> {
+    if attachments.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let needs_canvas_resources = attachments
+        .iter()
+        .any(|attachment| attachment.source == EditorAgentAttachmentSource::CanvasResource);
+    let needs_library_assets = attachments
+        .iter()
+        .any(|attachment| attachment.source == EditorAgentAttachmentSource::LibraryAsset);
+
+    let project = if needs_canvas_resources {
+        Some(
+            state
+                .spacetime_client()
+                .get_editor_project(EditorProjectGetRecordInput {
+                    project_id: conversation.project_id.clone(),
+                    owner_user_id: conversation.owner_user_id.clone(),
+                })
+                .await
+                .map_err(map_editor_project_error)?,
+        )
+    } else {
+        None
+    };
+    let library = if needs_library_assets {
+        Some(
+            state
+                .spacetime_client()
+                .get_editor_asset_library(conversation.owner_user_id.clone(), current_utc_micros())
+                .await
+                .map_err(map_editor_project_error)?,
+        )
+    } else {
+        None
+    };
+
+    attachments
+        .iter()
+        .map(|attachment| {
+            normalize_editor_agent_attachment(
+                conversation,
+                project.as_ref(),
+                library.as_ref(),
+                attachment,
+            )
+        })
+        .collect()
+}
+
+fn normalize_editor_agent_attachment(
+    conversation: &EditorAgentConversationRecord,
+    project: Option<&EditorProjectRecord>,
+    library: Option<&EditorAssetLibraryRecord>,
+    attachment: &EditorAgentAttachmentRef,
+) -> Result<EditorAgentAttachmentRef, AppError> {
+    let reference_id = normalize_required_string(attachment.reference_id.as_str())
+        .ok_or_else(|| editor_agent_bad_request("attachment.referenceId is required"))?;
+    match attachment.source {
+        EditorAgentAttachmentSource::CanvasResource => {
+            let project = project.ok_or_else(|| {
+                editor_agent_bad_request("canvas resource attachment project context missing")
+            })?;
+            let resource = project
+                .resources
+                .iter()
+                .find(|resource| resource.resource_id == reference_id)
+                .ok_or_else(|| {
+                    editor_agent_bad_request(format!(
+                        "canvas resource attachment not found in current project: {reference_id}"
+                    ))
+                })?;
+            normalize_canvas_resource_attachment(conversation, attachment, resource)
+        }
+        EditorAgentAttachmentSource::LibraryAsset => {
+            let library = library.ok_or_else(|| {
+                editor_agent_bad_request("library asset attachment context missing")
+            })?;
+            let asset = library
+                .assets
+                .iter()
+                .find(|asset| asset.asset_id == reference_id)
+                .ok_or_else(|| {
+                    editor_agent_bad_request(format!(
+                        "library asset attachment not found for current user: {reference_id}"
+                    ))
+                })?;
+            normalize_library_asset_attachment(attachment, asset)
+        }
+    }
+}
+
+pub fn normalize_canvas_resource_attachment(
+    conversation: &EditorAgentConversationRecord,
+    attachment: &EditorAgentAttachmentRef,
+    resource: &EditorProjectResourceRecord,
+) -> Result<EditorAgentAttachmentRef, AppError> {
+    if resource.project_id != conversation.project_id
+        || resource.owner_user_id != conversation.owner_user_id
+    {
+        return Err(editor_agent_bad_request(
+            "canvas resource attachment does not belong to this conversation project",
+        ));
+    }
+    validate_attachment_object_key(
+        attachment.object_key.as_deref(),
+        resource.object_key.as_deref(),
+        resource.resource_id.as_str(),
+    )?;
+
+    Ok(EditorAgentAttachmentRef {
+        source: EditorAgentAttachmentSource::CanvasResource,
+        reference_id: resource.resource_id.clone(),
+        object_key: resource.object_key.clone(),
+        image_src: resource.image_src.clone(),
+        thumbnail_src: None,
+        label: normalize_optional_string(attachment.label.clone()),
+        width: Some(resource.width),
+        height: Some(resource.height),
+    })
+}
+
+pub fn normalize_library_asset_attachment(
+    attachment: &EditorAgentAttachmentRef,
+    asset: &EditorAssetRecord,
+) -> Result<EditorAgentAttachmentRef, AppError> {
+    validate_attachment_object_key(
+        attachment.object_key.as_deref(),
+        asset.object_key.as_deref(),
+        asset.asset_id.as_str(),
+    )?;
+
+    Ok(EditorAgentAttachmentRef {
+        source: EditorAgentAttachmentSource::LibraryAsset,
+        reference_id: asset.asset_id.clone(),
+        object_key: asset.object_key.clone(),
+        image_src: asset.image_src.clone(),
+        thumbnail_src: asset.thumbnail_src.clone(),
+        label: normalize_optional_string(attachment.label.clone())
+            .or_else(|| Some(asset.label.clone())),
+        width: Some(asset.width),
+        height: Some(asset.height),
+    })
+}
+
+fn validate_attachment_object_key(
+    submitted_object_key: Option<&str>,
+    stored_object_key: Option<&str>,
+    reference_id: &str,
+) -> Result<(), AppError> {
+    let Some(submitted_object_key) = submitted_object_key.and_then(normalize_required_string)
+    else {
+        return Ok(());
+    };
+    let Some(stored_object_key) = stored_object_key.and_then(normalize_required_string) else {
+        return Err(editor_agent_bad_request(format!(
+            "attachment objectKey is not available for reference: {reference_id}"
+        )));
+    };
+    if submitted_object_key != stored_object_key {
+        return Err(editor_agent_bad_request(format!(
+            "attachment objectKey does not match reference: {reference_id}"
+        )));
+    }
+    Ok(())
+}
+
+pub fn conversation_summary_from_record(
+    conversation: EditorAgentConversationRecord,
+) -> EditorAgentConversationSummary {
+    EditorAgentConversationSummary {
+        conversation_id: conversation.conversation_id,
+        project_id: conversation.project_id,
+        title: conversation.title,
+        updated_at: conversation.updated_at,
+    }
+}
+
+pub fn conversation_detail_from_record(
+    conversation: EditorAgentConversationRecord,
+    messages: Vec<EditorAgentMessage>,
+) -> EditorAgentConversationDetail {
+    EditorAgentConversationDetail {
+        conversation_id: conversation.conversation_id,
+        project_id: conversation.project_id,
+        title: conversation.title,
+        created_at: conversation.created_at,
+        updated_at: conversation.updated_at,
+        messages,
+    }
+}
+
+pub fn build_editor_agent_canvas_completion(
+    project: &EditorProjectRecord,
+    tool_name: &str,
+    title: &str,
+) -> EditorCanvasGenerationCompletionPayload {
+    let (width, height) = editor_agent_tool_display_size(tool_name);
+    let (x, y) = next_editor_agent_canvas_position(project.layers.clone(), width, height);
+    EditorCanvasGenerationCompletionPayload {
+        dialog_id: None,
+        title: title.to_string(),
+        placeholder: EditorCanvasGenerationPlaceholderPayload {
+            x,
+            y,
+            width,
+            height,
+            original_width: width,
+            original_height: height,
+        },
+    }
+}
+
+fn editor_agent_tool_display_size(tool_name: &str) -> (f64, f64) {
+    match tool_name {
+        "ui-design" | "generate-ui-design" => (640.0, 360.0),
+        "generate-character" => (512.0, 768.0),
+        _ => (512.0, 512.0),
+    }
+}
+
+const EDITOR_AGENT_CANVAS_RESULT_GAP: f64 = 32.0;
+
+fn next_editor_agent_canvas_position(
+    layers: serde_json::Value,
+    _width: f64,
+    _height: f64,
+) -> (f64, f64) {
+    let mut max_right: Option<f64> = None;
+    let mut min_y: Option<f64> = None;
+    if let Value::Array(items) = layers {
+        for item in items {
+            if item.get("itemType").and_then(Value::as_str) == Some("generation-dialog") {
+                continue;
+            }
+            let Some(x) = item.get("x").and_then(Value::as_f64) else {
+                continue;
+            };
+            let Some(y) = item.get("y").and_then(Value::as_f64) else {
+                continue;
+            };
+            let width = item.get("width").and_then(Value::as_f64).unwrap_or(0.0);
+            if !x.is_finite() || !y.is_finite() || !width.is_finite() {
+                continue;
+            }
+            max_right = Some(max_right.map_or(x + width, |value| value.max(x + width)));
+            min_y = Some(min_y.map_or(y, |value| value.min(y)));
+        }
+    }
+    (
+        max_right.map_or(0.0, |right| right + EDITOR_AGENT_CANVAS_RESULT_GAP),
+        min_y.unwrap_or(0.0),
+    )
+}
+
+pub fn empty_messages_document(conversation_id: &str) -> EditorAgentConversationMessagesDocument {
+    EditorAgentConversationMessagesDocument {
+        version: EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION,
+        conversation_id: conversation_id.to_string(),
+        messages: Vec::new(),
+    }
+}
diff --git a/server-rs/crates/api-server/src/editor_generation_queue.rs b/server-rs/crates/api-server/src/editor_generation_queue.rs
index e58ea8dc9..640aa6dc9 100644
--- a/server-rs/crates/api-server/src/editor_generation_queue.rs
+++ b/server-rs/crates/api-server/src/editor_generation_queue.rs
@@ -47,12 +47,41 @@ where
     T: Serialize,
 {
     let job_id = build_prefixed_uuid_id("task-");
+    enqueue_editor_generation_job_with_identity(
+        state,
+        owner_user_id,
+        job_kind,
+        source_entity_id,
+        request_label,
+        price_mud_points,
+        payload,
+        job_id.clone(),
+        format!("editor-canvas:{job_kind}:{job_id}"),
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn enqueue_editor_generation_job_with_identity<T>(
+    state: &AppState,
+    owner_user_id: &str,
+    job_kind: &str,
+    source_entity_id: impl Into<String>,
+    request_label: impl Into<String>,
+    price_mud_points: u64,
+    payload: &T,
+    job_id: String,
+    dedupe_key: String,
+) -> Result<ExternalGenerationJobRecord, AppError>
+where
+    T: Serialize,
+{
     let request_payload_json = serialize_editor_generation_job_payload(payload)?;
     let now_micros = current_utc_micros();
     state
         .spacetime_client()
         .enqueue_external_generation_job(ExternalGenerationJobEnqueueRecordInput {
-            dedupe_key: format!("editor-canvas:{job_kind}:{job_id}"),
+            dedupe_key,
             job_id,
             job_kind: job_kind.to_string(),
             owner_user_id: owner_user_id.to_string(),
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index b07b63629..a87179325 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -11,7 +11,6 @@ use axum::{
     extract::{Extension, Path, Query, State},
     http::StatusCode,
 };
-use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
 use module_assets::{
     AssetObjectAccessPolicy, AssetObjectFieldError, build_asset_object_upsert_input,
     generate_asset_object_id,
@@ -49,6 +48,7 @@ use spacetime_client::{
     EditorShowcaseAssetLikeToggleRecordInput, EditorShowcaseAssetPublicListRecordInput,
     EditorShowcaseAssetRecord, EditorShowcaseAssetSubmitRecordInput,
     EditorShowcaseCampaignConfigGetRecordInput, EditorShowcaseCampaignConfigRecord,
+    ExternalGenerationJobPhaseUpdateError, ExternalGenerationJobPhaseUpdateRecordInput,
     SpacetimeClientError,
 };
 
@@ -121,12 +121,20 @@ const EDITOR_ICON_SPRITESHEET_ASSET_KIND: &str = "editor_icon_spritesheet";
 const EDITOR_ICON_SPRITESHEET_SLICE_ASSET_KIND: &str = "editor_icon_spritesheet_slice";
 const EDITOR_ICON_SPRITESHEET_SLICE_WARNING_COMPONENTS: &str = "insufficient-connected-components";
 const EDITOR_ICON_SPRITESHEET_SLICE_WARNING_PERSISTENCE: &str = "slice-persistence-failed";
+const EDITOR_GENERATION_POSTPROCESS_WARNING_CODE: &str = "postprocess-failed-source-preserved";
+const EDITOR_GENERATION_PHASE_REPORT_RETRY_COUNT: usize = 1;
 const EDITOR_UI_DESIGN_SPRITESHEET_ASSET_KIND: &str = "editor_ui_design_spritesheet";
 const EDITOR_UI_DESIGN_ASSET_IMAGE_KIND: &str = "editor_ui_design_asset";
 const EDITOR_LEGACY_GREEN_SCREEN_SOURCE_ASSET_KIND: &str = "editor_green_screen_source";
 const EDITOR_PROVIDER_SOURCE_SLOT: &str = "provider_source";
-const EDITOR_BGFILTER_DEFAULT_SEG_MODEL: &str = "birefnet";
+pub(crate) const EDITOR_BGFILTER_DEFAULT_SEG_MODEL: &str = "birefnet";
 const EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG: &str = "anime-seg";
+const EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS: u64 = 600;
+const EDITOR_BGFILTER_BACKGROUND_MODE_FLAT: &str = "flat";
+const EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX: &str = "complex";
+pub(crate) const EDITOR_BGFILTER_CROSS_CHECK_ENABLED: bool = true;
+pub(crate) const EDITOR_BGFILTER_CROSS_CHECK_DISABLED: bool = false;
+const EDITOR_BGFILTER_RETRY_COUNT: usize = 1;
 const EDITOR_PUBLICATION_MATERIAL_ASSET_KIND: &str = "editor_publication_material";
 const EDITOR_LEGACY_INLINE_IMAGE_ASSET_KIND: &str = "editor_legacy_inline_image";
 
@@ -259,6 +267,8 @@ pub struct EditorImageEditRequest {
     pub(crate) source_image_src: String,
     pub(crate) size: Option<String>,
     pub(crate) model: Option<String>,
+    pub(crate) aspect_ratio: Option<String>,
+    pub(crate) image_size: Option<String>,
     pub(crate) reference_image_srcs: Option<Vec<String>>,
     pub(crate) project_id: Option<String>,
     pub(crate) asset_kind: Option<String>,
@@ -333,6 +343,7 @@ pub(crate) struct EditorGenerationCaller {
     pub(crate) owner_user_id: String,
     pub(crate) audit_subject_user_id: Option<String>,
     pub(crate) audit_project_id: Option<String>,
+    pub(crate) phase_reporter: Option<EditorGenerationPhaseReporter>,
 }
 
 impl EditorGenerationCaller {
@@ -342,8 +353,93 @@ impl EditorGenerationCaller {
             audit_subject_user_id: Some(owner_user_id.clone()),
             owner_user_id,
             audit_project_id: None,
+            phase_reporter: None,
         }
     }
+
+    async fn report_processing_phase(&self, state: &AppState) -> Result<(), AppError> {
+        if let Some(reporter) = self.phase_reporter.as_ref() {
+            reporter.report_processing(state).await?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct EditorGenerationPhaseReporter {
+    job_id: String,
+    worker_id: String,
+    lease_token: String,
+}
+
+impl EditorGenerationPhaseReporter {
+    pub(crate) fn new(job_id: String, worker_id: String, lease_token: String) -> Self {
+        Self {
+            job_id,
+            worker_id,
+            lease_token,
+        }
+    }
+
+    pub(crate) async fn report_processing(&self, state: &AppState) -> Result<(), AppError> {
+        let input = ExternalGenerationJobPhaseUpdateRecordInput {
+            job_id: self.job_id.clone(),
+            worker_id: self.worker_id.clone(),
+            lease_token: self.lease_token.clone(),
+            phase: "processing".to_string(),
+        };
+        let max_attempts = EDITOR_GENERATION_PHASE_REPORT_RETRY_COUNT + 1;
+        for attempt in 1..=max_attempts {
+            match state
+                .spacetime_client()
+                .update_external_generation_job_phase(input.clone())
+                .await
+            {
+                Ok(_) => return Ok(()),
+                Err(error) => {
+                    let will_retry =
+                        should_retry_editor_generation_phase_update(&error, attempt, max_attempts);
+                    tracing::warn!(
+                        provider = "external-generation-phase",
+                        job_id = %self.job_id,
+                        attempt,
+                        max_attempts,
+                        will_retry,
+                        lease_fencing_rejected = error.is_lease_fencing_rejected(),
+                        error = %error,
+                        "external_generation_processing_phase_report_failed"
+                    );
+                    if will_retry {
+                        continue;
+                    }
+                    return Err(map_editor_generation_phase_update_error(error));
+                }
+            }
+        }
+        unreachable!("phase report retry loop should return on success or final error")
+    }
+}
+
+fn should_retry_editor_generation_phase_update(
+    error: &ExternalGenerationJobPhaseUpdateError,
+    attempt: usize,
+    max_attempts: usize,
+) -> bool {
+    error.is_retryable_transport() && attempt < max_attempts
+}
+
+fn map_editor_generation_phase_update_error(
+    error: ExternalGenerationJobPhaseUpdateError,
+) -> AppError {
+    let status = if error.is_lease_fencing_rejected() {
+        StatusCode::CONFLICT
+    } else {
+        StatusCode::BAD_GATEWAY
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": "external-generation-phase",
+        "message": format!("更新外部生成任务处理阶段失败：{error}"),
+    }))
 }
 
 #[derive(Debug, Serialize)]
@@ -527,6 +623,20 @@ pub(crate) struct EditorCanvasGeneratedLayerInput {
     pub(crate) preview_video_path: Option<String>,
 }
 
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorGenerationWarningResponse {
+    code: &'static str,
+    reason: String,
+}
+
+fn editor_postprocess_fallback_warning(reason: &'static str) -> EditorGenerationWarningResponse {
+    EditorGenerationWarningResponse {
+        code: EDITOR_GENERATION_POSTPROCESS_WARNING_CODE,
+        reason: reason.to_string(),
+    }
+}
+
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct EditorImageGenerationResponse {
@@ -544,6 +654,8 @@ pub struct EditorImageGenerationResponse {
     resource: Option<EditorProjectResourcePayload>,
     asset: Option<EditorAssetPayload>,
     project: Option<EditorProjectPayload>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    warning: Option<EditorGenerationWarningResponse>,
 }
 
 #[derive(Debug, Serialize)]
@@ -599,6 +711,8 @@ pub struct EditorIconSpritesheetGenerationResponse {
     spritesheet_resource: Option<EditorProjectResourcePayload>,
     spritesheet_asset: Option<EditorAssetPayload>,
     project: Option<EditorProjectPayload>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    warning: Option<EditorGenerationWarningResponse>,
 }
 
 #[derive(Debug, Serialize)]
@@ -1328,6 +1442,12 @@ pub async fn generate_editor_image(
 ) -> Result<Json<Value>, AppError> {
     let caller = EditorGenerationCaller::from_authenticated(&authenticated);
     if !state.config.external_generation_mode.is_inline() {
+        ensure_editor_reference_image_sources_are_stable(
+            payload.reference_image_srcs.as_deref(),
+            "editor-image-generation",
+            "referenceImageSrcs",
+            "生成参考图",
+        )?;
         let normalized_kind = payload.kind.as_deref().map(str::trim);
         let is_ui_design_generation = matches!(normalized_kind, Some("ui-design"));
         let is_publication_material_generation =
@@ -1388,6 +1508,12 @@ pub(crate) async fn generate_editor_image_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorImageGenerationRequest,
 ) -> Result<Json<Value>, AppError> {
+    ensure_editor_reference_image_sources_are_stable(
+        payload.reference_image_srcs.as_deref(),
+        "editor-image-generation",
+        "referenceImageSrcs",
+        "生成参考图",
+    )?;
     let role_setting = payload.prompt.trim().to_string();
     if role_setting.is_empty() {
         return Err(
@@ -1454,15 +1580,6 @@ pub(crate) async fn generate_editor_image_for_owner(
     // 决策移入闭包后 payload.reference_image_srcs 已被 reference_sources 消费，
     // 这里从过滤后的 reference_sources 预先固化 ui-design 的「是否带参考图」布尔。
     let ui_has_references = !reference_sources.is_empty();
-    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
-        request_context,
-        caller.audit_subject_user_id.clone(),
-        caller
-            .audit_project_id
-            .clone()
-            .or_else(|| payload.project_id.clone()),
-    );
-    let http_client = build_openai_image_http_client(&settings)?;
     let negative_prompt = Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体");
     let reference_images = if reference_sources.is_empty() {
         Vec::new()
@@ -1476,6 +1593,15 @@ pub(crate) async fn generate_editor_image_for_owner(
         }
         parsed_reference_images
     };
+    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
+        request_context,
+        caller.audit_subject_user_id.clone(),
+        caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+    );
+    let http_client = build_openai_image_http_client(&settings)?;
     let image_size = if is_ui_design_generation {
         Cow::Owned(generation_options.size.clone())
     } else {
@@ -1627,7 +1753,7 @@ pub(crate) async fn generate_editor_image_for_owner(
             state,
             caller.owner_user_id.as_str(),
             generated.task_id.as_str(),
-            &image,
+            image,
             submitted_prompt.as_str(),
             generated.actual_prompt.as_deref(),
             storage_profile.asset_kind,
@@ -1635,6 +1761,10 @@ pub(crate) async fn generate_editor_image_for_owner(
             "character-image",
         )
         .await?;
+        let source_image_src =
+            editor_media_src_from_object_key(source_persisted.object_key.as_str());
+        let source_object_key = source_persisted.object_key.clone();
+        let source_asset_object_id = source_persisted.asset_object_id.clone();
         let source_record = persist_editor_provider_source_resource(
             state,
             source_persisted,
@@ -1662,6 +1792,7 @@ pub(crate) async fn generate_editor_image_for_owner(
             },
         )
         .await?;
+        caller.report_processing_phase(state).await?;
         let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
             user_id: caller.audit_subject_user_id.clone(),
             profile_id: caller
@@ -1672,17 +1803,81 @@ pub(crate) async fn generate_editor_image_for_owner(
         };
         let removal = remove_editor_generated_screen_background_with_bgfilter(
             state,
-            &image,
+            source_object_key.as_str(),
             screen_color.expect("character generation should have screen color"),
             seg_model.expect("character generation should have BgFilter seg model"),
+            EDITOR_BGFILTER_CROSS_CHECK_ENABLED,
             &matting_audit,
         )
-        .await?;
-        image = removal.image;
+        .await;
+        let removal = match removal {
+            Ok(removal) => removal,
+            Err(error) => {
+                let failure_message = error.body_text();
+                tracing::warn!(
+                    provider = "editor-character-image",
+                    operation = "background_postprocess",
+                    task_id = %generated.task_id,
+                    error = %failure_message,
+                    "角色原图已保存，但透明背景处理失败，使用原图完成画布"
+                );
+                let completed_project = complete_editor_canvas_generation(
+                    state,
+                    caller.owner_user_id.as_str(),
+                    payload.project_id.as_deref(),
+                    payload.canvas_completion.as_ref(),
+                    source_record.resource.as_ref(),
+                )
+                .await?;
+                return Ok(json_success_body(
+                    Some(&request_context),
+                    EditorImageGenerationResponse {
+                        image_src: source_image_src,
+                        object_key: Some(source_object_key),
+                        asset_object_id: Some(source_asset_object_id),
+                        width: provider_width,
+                        height: provider_height,
+                        source_type: "generated",
+                        prompt: role_setting,
+                        actual_prompt: generated.actual_prompt,
+                        model: generation_options.model.to_string(),
+                        provider: "VectorEngine",
+                        task_id: generated.task_id,
+                        resource: source_record.resource,
+                        asset: source_record.asset,
+                        project: completed_project,
+                        warning: Some(editor_postprocess_fallback_warning(
+                            "生成任务成功，后处理失败。",
+                        )),
+                    },
+                ));
+            }
+        };
+        let removal_provider = removal.provider;
+        let (restored_removal_image, postprocess_dimension_error) =
+            apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original(
+                state,
+                source_object_key.as_str(),
+                provider_width,
+                provider_height,
+                removal.image,
+            )
+            .await;
+        if let Some(error) = postprocess_dimension_error {
+            tracing::warn!(
+                task_id = %generated.task_id,
+                provider = removal_provider,
+                provider_width,
+                provider_height,
+                error = ?error,
+                "角色透明图尺寸恢复失败，保留去背景服务原始输出"
+            );
+        }
+        image = restored_removal_image;
         output_prompt = "去除纯色背景".to_string();
         output_actual_prompt = None;
         output_model = removal.model;
-        output_provider = removal.provider.to_string();
+        output_provider = removal_provider.to_string();
         output_generation_inputs =
             build_editor_derived_asset_generation_inputs("角色抠图", &output_model, &source_record);
         Some(source_record)
@@ -1690,14 +1885,18 @@ pub(crate) async fn generate_editor_image_for_owner(
         None
     };
 
-    // TODO the image size passed to api is already normalized, should remove those normalize
-    // and let resize here to get the proper size
+    // 中文注释：带模型尺寸选项的用户生成已经把目标像素直接传给 provider，不能在回图后靠缩放伪造 K 档。
+    // 只有宣发素材的固定交付尺寸和没有新尺寸字段的历史请求继续执行交付尺寸恢复。
     let (restored_image, dimension_restore_error) =
-        restore_editor_generated_image_output_dimensions_or_original(
-            image,
-            generation_options.model,
-            image_size.as_ref(),
-        );
+        if is_publication_material_generation || !has_dimension_options {
+            restore_editor_generated_image_output_dimensions_or_original(
+                image,
+                generation_options.model,
+                image_size.as_ref(),
+            )
+        } else {
+            (image, None)
+        };
     if let Some(error) = dimension_restore_error {
         tracing::warn!(
             task_id = %generated.task_id,
@@ -1798,6 +1997,7 @@ pub(crate) async fn generate_editor_image_for_owner(
             resource: generated_asset.resource,
             asset: generated_asset.asset,
             project: completed_project,
+            warning: None,
         },
     ))
 }
@@ -1911,7 +2111,15 @@ async fn resolve_editor_image_edit_price(
     state: &AppState,
     model: &str,
     size: &str,
+    image_size: Option<&str>,
 ) -> Result<u32, AppError> {
+    let price_size = if model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+        image_size
+            .map(|value| normalize_editor_generation_image_size(model, Some(value)))
+            .unwrap_or_else(|| editor_image_price_size_from_pixels(size))
+    } else {
+        editor_image_price_size_from_pixels(size)
+    };
     let expected_price_mud_points = state
         .editor_generation_pricing()
         .await
@@ -1921,11 +2129,7 @@ async fn resolve_editor_image_edit_price(
                 "message": error.to_string(),
             }))
         })?
-        .image_generation_mud_points(
-            Some("quick-edit"),
-            Some(model),
-            Some(editor_image_price_size_from_pixels(size)),
-        );
+        .image_generation_mud_points(Some("quick-edit"), Some(model), Some(price_size));
     Ok(expected_price_mud_points)
 }
 
@@ -1942,6 +2146,63 @@ fn editor_image_price_size_from_pixels(size: &str) -> &'static str {
     if width.max(height) > 1536 { "2K" } else { "1K" }
 }
 
+fn editor_image_edit_uses_nanobanana_generate_content(model: &str) -> bool {
+    model == EDITOR_IMAGE_MODEL_NANOBANANA2
+}
+
+fn normalize_editor_image_edit_generation_options(
+    model: Option<&str>,
+    aspect_ratio: Option<&str>,
+    image_size: Option<&str>,
+    legacy_size: Option<&str>,
+) -> EditorGenerationOptions {
+    let model_options = normalize_editor_generation_options(model, None, None);
+    let inferred_aspect_ratio = aspect_ratio
+        .filter(|value| !value.trim().is_empty())
+        .or_else(|| infer_editor_image_edit_aspect_ratio(legacy_size));
+    let inferred_image_size = image_size
+        .filter(|value| !value.trim().is_empty())
+        .or_else(|| infer_editor_image_edit_size_tier(model_options.model, legacy_size));
+    normalize_editor_generation_options(model, inferred_aspect_ratio, inferred_image_size)
+}
+
+fn infer_editor_image_edit_aspect_ratio(size: Option<&str>) -> Option<&'static str> {
+    let (width, height) = parse_editor_image_edit_pixel_size(size?)?;
+    let source_ratio = f64::from(width) / f64::from(height);
+    [
+        ("1:1", 1.0),
+        ("4:3", 4.0 / 3.0),
+        ("3:2", 3.0 / 2.0),
+        ("2:3", 2.0 / 3.0),
+        ("9:16", 9.0 / 16.0),
+        ("16:9", 16.0 / 9.0),
+    ]
+    .into_iter()
+    .min_by(|(_, left), (_, right)| {
+        (left - source_ratio)
+            .abs()
+            .total_cmp(&(right - source_ratio).abs())
+    })
+    .map(|(label, _)| label)
+}
+
+fn infer_editor_image_edit_size_tier(model: &str, size: Option<&str>) -> Option<&'static str> {
+    let (width, height) = parse_editor_image_edit_pixel_size(size?)?;
+    let long_edge = width.max(height);
+    if model == EDITOR_IMAGE_MODEL_NANOBANANA2 && long_edge <= 768 {
+        return Some("0.5K");
+    }
+    Some(if long_edge > 1536 { "2K" } else { "1K" })
+}
+
+fn parse_editor_image_edit_pixel_size(size: &str) -> Option<(u32, u32)> {
+    let normalized = size.trim().replace('*', "x");
+    let (width, height) = normalized.split_once('x')?;
+    let width = width.parse::<u32>().ok()?;
+    let height = height.parse::<u32>().ok()?;
+    (width > 0 && height > 0).then_some((width, height))
+}
+
 fn normalize_editor_image_generation_size(size: Option<&str>) -> Cow<'static, str> {
     match size.map(str::trim).filter(|value| !value.is_empty()) {
         Some("1024x1024") | Some("1024*1024") | Some("1:1") => Cow::Borrowed("1024x1024"),
@@ -2056,13 +2317,17 @@ fn editor_generation_size_for_model(model: &str, aspect_ratio: &str, image_size:
 
     match (image_size, aspect_ratio) {
         ("2K", "1:1") => "2048x2048",
-        // 中文注释：gpt-image-2 文档未列出 2K 竖版，竖版选择回落到文档明确支持的 1K 竖版。
-        ("2K", "2:3") | ("2K", "9:16") => "1024x1536",
+        ("2K", "2:3") => "1376x2048",
+        ("2K", "9:16") => "1152x2048",
         ("2K", "4:3") => "2048x1536",
-        ("2K", "16:9") | ("2K", "3:2") => "2048x1152",
-        ("1K", "2:3") | ("1K", "9:16") => "1024x1536",
-        ("1K", "4:3") => "1536x1024",
-        ("1K", "3:2") | ("1K", "16:9") => "1536x1024",
+        ("2K", "3:2") => "2048x1376",
+        ("2K", "16:9") => "2048x1152",
+        ("1K", "2:3") => "688x1024",
+        // 中文注释：9:16 的 1024 长边会低于 provider 最小总像素，按原比例放大并做 16 对齐后直接请求。
+        ("1K", "9:16") => "608x1088",
+        ("1K", "4:3") => "1024x768",
+        ("1K", "3:2") => "1024x688",
+        ("1K", "16:9") => "1088x608",
         _ => "1024x1024",
     }
     .to_string()
@@ -2182,9 +2447,10 @@ async fn ensure_editor_image_edit_source_allowed(
     ensure_editor_image_edit_asset_kind_allowed(asset_kind)
 }
 
-fn encode_editor_image_edit_png(
+fn encode_editor_image_png(
     image: image::DynamicImage,
     failure_status: StatusCode,
+    provider: &str,
     failure_message: &str,
 ) -> Result<Vec<u8>, AppError> {
     let mut bytes = Cursor::new(Vec::new());
@@ -2192,13 +2458,21 @@ fn encode_editor_image_edit_png(
         .write_to(&mut bytes, image::ImageFormat::Png)
         .map_err(|error| {
             AppError::from_status(failure_status).with_details(json!({
-                "provider": "editor-image-edit",
+                "provider": provider,
                 "message": format!("{failure_message}：{error}"),
             }))
         })?;
     Ok(bytes.into_inner())
 }
 
+fn encode_editor_image_edit_png(
+    image: image::DynamicImage,
+    failure_status: StatusCode,
+    failure_message: &str,
+) -> Result<Vec<u8>, AppError> {
+    encode_editor_image_png(image, failure_status, "editor-image-edit", failure_message)
+}
+
 fn prepare_editor_image_edit_references(
     reference_images: &mut [OpenAiReferenceImage],
     target_size: &str,
@@ -2335,6 +2609,105 @@ fn restore_editor_generated_image_output_dimensions_or_original(
     }
 }
 
+fn apply_editor_postprocessed_alpha_to_provider_source(
+    provider_source: &DownloadedOpenAiImage,
+    postprocessed: &DownloadedOpenAiImage,
+) -> Result<Option<DownloadedOpenAiImage>, AppError> {
+    let provider_source =
+        image::load_from_memory(provider_source.bytes.as_slice()).map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "editor-image-postprocess",
+                "message": format!("provider 原图不是有效图片：{error}"),
+            }))
+        })?;
+    let postprocessed =
+        image::load_from_memory(postprocessed.bytes.as_slice()).map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "editor-image-postprocess",
+                "message": format!("透明后处理图不是有效图片：{error}"),
+            }))
+        })?;
+    if postprocessed.width() == provider_source.width()
+        && postprocessed.height() == provider_source.height()
+    {
+        return Ok(None);
+    }
+
+    // 中文注释：图片模型已经按用户所选 K 档直接生成 provider 原图。
+    // 去背景服务若缩小图片，只重采样其 alpha 蒙版并应用回原始分辨率 RGB，禁止把低分辨率成品整图放大。
+    let postprocessed = postprocessed.to_rgba8();
+    let alpha = image::GrayImage::from_fn(postprocessed.width(), postprocessed.height(), |x, y| {
+        image::Luma([postprocessed.get_pixel(x, y).0[3]])
+    });
+    let alpha = image::imageops::resize(
+        &alpha,
+        provider_source.width(),
+        provider_source.height(),
+        image::imageops::FilterType::Lanczos3,
+    );
+    let mut restored = provider_source.to_rgba8();
+    for (x, y, pixel) in restored.enumerate_pixels_mut() {
+        pixel.0[3] = alpha.get_pixel(x, y).0[0];
+    }
+    Ok(Some(DownloadedOpenAiImage {
+        bytes: encode_editor_image_png(
+            image::DynamicImage::ImageRgba8(restored),
+            StatusCode::BAD_GATEWAY,
+            "editor-image-postprocess",
+            "恢复透明蒙版尺寸失败",
+        )?,
+        mime_type: "image/png".to_string(),
+        extension: "png".to_string(),
+    }))
+}
+
+async fn apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original(
+    state: &AppState,
+    provider_source_object_key: &str,
+    provider_width: u32,
+    provider_height: u32,
+    postprocessed: DownloadedOpenAiImage,
+) -> (DownloadedOpenAiImage, Option<AppError>) {
+    let postprocessed_dimensions =
+        image::ImageReader::new(Cursor::new(postprocessed.bytes.as_slice()))
+            .with_guessed_format()
+            .map_err(|error| {
+                AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                    "provider": "editor-image-postprocess",
+                    "message": format!("无法识别透明后处理图格式：{error}"),
+                }))
+            })
+            .and_then(|reader| {
+                reader.into_dimensions().map_err(|error| {
+                    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                        "provider": "editor-image-postprocess",
+                        "message": format!("无法读取透明后处理图尺寸：{error}"),
+                    }))
+                })
+            });
+    match postprocessed_dimensions {
+        Ok((postprocessed_width, postprocessed_height))
+            if postprocessed_width == provider_width && postprocessed_height == provider_height =>
+        {
+            return (postprocessed, None);
+        }
+        Ok(_) => {}
+        Err(error) => return (postprocessed, Some(error)),
+    }
+
+    // 中文注释：provider 原图已在 BgFilter 调用前交给 OSS 并释放；只有输出尺寸漂移时才短时回读原图回贴 alpha。
+    let provider_source =
+        match download_editor_persisted_image_object(state, provider_source_object_key).await {
+            Ok(provider_source) => provider_source,
+            Err(error) => return (postprocessed, Some(error)),
+        };
+    match apply_editor_postprocessed_alpha_to_provider_source(&provider_source, &postprocessed) {
+        Ok(Some(restored)) => (restored, None),
+        Ok(None) => (postprocessed, None),
+        Err(error) => (postprocessed, Some(error)),
+    }
+}
+
 fn restore_editor_generated_image_output_dimensions(
     output: &DownloadedOpenAiImage,
     model: &str,
@@ -2397,14 +2770,35 @@ pub async fn edit_editor_image(
 ) -> Result<Json<Value>, AppError> {
     let caller = EditorGenerationCaller::from_authenticated(&authenticated);
     if !state.config.external_generation_mode.is_inline() {
+        ensure_editor_reference_image_source_is_stable(
+            payload.source_image_src.as_str(),
+            "editor-image-edit",
+            "sourceImageSrc",
+            "待修改图片",
+        )?;
+        ensure_editor_reference_image_sources_are_stable(
+            payload.reference_image_srcs.as_deref(),
+            "editor-image-edit",
+            "referenceImageSrcs",
+            "修改参考图",
+        )?;
         ensure_editor_image_edit_source_allowed(&state, caller.owner_user_id.as_str(), &payload)
             .await?;
-        let generation_options =
-            normalize_editor_generation_options(payload.model.as_deref(), None, None);
+        let generation_options = normalize_editor_image_edit_generation_options(
+            payload.model.as_deref(),
+            payload.aspect_ratio.as_deref(),
+            payload.image_size.as_deref(),
+            payload.size.as_deref(),
+        );
         let image_size = normalize_editor_image_generation_size(payload.size.as_deref());
         let price_mud_points = u64::from(
-            resolve_editor_image_edit_price(&state, generation_options.model, image_size.as_ref())
-                .await?,
+            resolve_editor_image_edit_price(
+                &state,
+                generation_options.model,
+                image_size.as_ref(),
+                Some(generation_options.image_size),
+            )
+            .await?,
         );
         let source_entity_id =
             editor_generation_source_entity_id(payload.project_id.as_deref(), "editor-image-edit");
@@ -2435,6 +2829,18 @@ pub(crate) async fn edit_editor_image_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorImageEditRequest,
 ) -> Result<Json<Value>, AppError> {
+    ensure_editor_reference_image_source_is_stable(
+        payload.source_image_src.as_str(),
+        "editor-image-edit",
+        "sourceImageSrc",
+        "待修改图片",
+    )?;
+    ensure_editor_reference_image_sources_are_stable(
+        payload.reference_image_srcs.as_deref(),
+        "editor-image-edit",
+        "referenceImageSrcs",
+        "修改参考图",
+    )?;
     ensure_editor_image_edit_source_allowed(state, caller.owner_user_id.as_str(), &payload).await?;
     let prompt = payload.prompt.trim().to_string();
     if prompt.is_empty() {
@@ -2445,8 +2851,12 @@ pub(crate) async fn edit_editor_image_for_owner(
             })),
         );
     }
-    let generation_options =
-        normalize_editor_generation_options(payload.model.as_deref(), None, None);
+    let generation_options = normalize_editor_image_edit_generation_options(
+        payload.model.as_deref(),
+        payload.aspect_ratio.as_deref(),
+        payload.image_size.as_deref(),
+        payload.size.as_deref(),
+    );
     let requested_image_size = normalize_editor_image_generation_size(payload.size.as_deref());
     let mut reference_images =
         Vec::with_capacity(1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len));
@@ -2475,33 +2885,71 @@ pub(crate) async fn edit_editor_image_for_owner(
     );
     let http_client = build_openai_image_http_client(&settings)?;
     let edit_dimensions =
-        prepare_editor_image_edit_references(&mut reference_images, requested_image_size.as_ref())?;
-    let image_size = format!(
-        "{}x{}",
-        edit_dimensions.provider_width, edit_dimensions.provider_height
-    );
-    let expected_price_mud_points =
-        resolve_editor_image_edit_price(state, generation_options.model, image_size.as_ref())
-            .await?;
-    let generated = execute_billable_asset_operation_with_cost(
+        if editor_image_edit_uses_nanobanana_generate_content(generation_options.model) {
+            None
+        } else {
+            Some(prepare_editor_image_edit_references(
+                &mut reference_images,
+                requested_image_size.as_ref(),
+            )?)
+        };
+    let provider_size = edit_dimensions
+        .map(|dimensions| {
+            format!(
+                "{}x{}",
+                dimensions.provider_width, dimensions.provider_height
+            )
+        })
+        .unwrap_or_else(|| generation_options.provider_image_size.to_string());
+    let expected_price_mud_points = resolve_editor_image_edit_price(
         state,
-        caller.owner_user_id.as_str(),
-        "editor_image_edit",
-        request_context.request_id(),
-        u64::from(expected_price_mud_points),
-        create_openai_image_edit_with_references_and_model(
-            &http_client,
-            &settings,
-            generation_options.model,
-            prompt.as_str(),
-            Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体"),
-            image_size.as_ref(),
-            1,
-            reference_images.as_slice(),
-            "图片画布修改图片",
-        ),
+        generation_options.model,
+        requested_image_size.as_ref(),
+        Some(generation_options.image_size),
     )
     .await?;
+    let generated = if editor_image_edit_uses_nanobanana_generate_content(generation_options.model)
+    {
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            "editor_image_edit",
+            request_context.request_id(),
+            u64::from(expected_price_mud_points),
+            create_openai_nanobanana_generate_content(
+                &http_client,
+                &settings,
+                generation_options.model,
+                prompt.as_str(),
+                Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体"),
+                generation_options.aspect_ratio,
+                provider_size.as_str(),
+                reference_images.as_slice(),
+                "图片画布修改图片",
+            ),
+        )
+        .await?
+    } else {
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            "editor_image_edit",
+            request_context.request_id(),
+            u64::from(expected_price_mud_points),
+            create_openai_image_edit_with_references_and_model(
+                &http_client,
+                &settings,
+                generation_options.model,
+                prompt.as_str(),
+                Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体"),
+                provider_size.as_str(),
+                1,
+                reference_images.as_slice(),
+                "图片画布修改图片",
+            ),
+        )
+        .await?
+    };
     let provider_image = generated.images.into_iter().next().ok_or_else(|| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
             "provider": "vector-engine",
@@ -2519,15 +2967,18 @@ pub(crate) async fn edit_editor_image_for_owner(
             })?;
     let asset_label =
         resolve_editor_generated_asset_label(payload.asset_label.clone(), "图片修改结果");
-    let (image, dimension_restore_error) =
-        restore_editor_image_edit_output_dimensions_or_original(provider_image, &edit_dimensions);
+    let (image, dimension_restore_error) = if let Some(edit_dimensions) = edit_dimensions.as_ref() {
+        restore_editor_image_edit_output_dimensions_or_original(provider_image, edit_dimensions)
+    } else {
+        (provider_image, None)
+    };
     if let Some(error) = dimension_restore_error {
         tracing::warn!(
             task_id = %generated.task_id,
             provider_width,
             provider_height,
-            target_width = edit_dimensions.target_width,
-            target_height = edit_dimensions.target_height,
+            target_width = edit_dimensions.map(|dimensions| dimensions.target_width),
+            target_height = edit_dimensions.map(|dimensions| dimensions.target_height),
             error = ?error,
             "画板快速编辑尺寸恢复失败，保留并上传 provider 原图"
         );
@@ -2617,6 +3068,7 @@ pub(crate) async fn edit_editor_image_for_owner(
             resource: generated_asset.resource,
             asset: generated_asset.asset,
             project: completed_project,
+            warning: None,
         },
     ))
 }
@@ -2628,6 +3080,12 @@ pub async fn remove_editor_image_background(
     Json(payload): Json<EditorBackgroundRemovalRequest>,
 ) -> Result<Json<Value>, AppError> {
     let caller = EditorGenerationCaller::from_authenticated(&authenticated);
+    ensure_editor_reference_image_source_is_stable(
+        payload.source_image_src.as_str(),
+        "editor-background-removal",
+        "sourceImageSrc",
+        "待去除背景图片",
+    )?;
     let source_entity_id = editor_generation_source_entity_id(
         payload.project_id.as_deref(),
         "editor-background-removal",
@@ -2658,13 +3116,17 @@ pub(crate) async fn remove_editor_image_background_for_owner(
     payload: EditorBackgroundRemovalRequest,
 ) -> Result<Json<Value>, AppError> {
     let started_at = Instant::now();
-    let source_image = parse_editor_reference_image(
+    caller.report_processing_phase(state).await?;
+    let source_object_key = resolve_editor_reference_object_key_for_owner(
         state,
         caller.owner_user_id.as_str(),
         payload.source_image_src.as_str(),
     )
     .await?;
-    let removed = request_editor_background_removal_image(state, source_image).await?;
+    validate_editor_background_removal_source(state, source_object_key.as_str()).await?;
+    let removed =
+        request_editor_background_removal_image_with_retry(state, source_object_key.as_str())
+            .await?;
     let task_id = normalize_optional_string(payload.task_id.clone())
         .unwrap_or_else(|| format!("background-removal-{}", current_utc_micros()));
     let persisted = persist_editor_generated_image(
@@ -2678,7 +3140,7 @@ pub(crate) async fn remove_editor_image_background_for_owner(
         "background-removal",
         "removed-background",
         "result",
-        "birefnet",
+        "bgfilter-complex",
     )
     .await?;
     let image_src = editor_media_src_from_object_key(persisted.object_key.as_str());
@@ -2698,8 +3160,8 @@ pub(crate) async fn remove_editor_image_background_for_owner(
             height: removed.height,
             prompt: "remove background".to_string(),
             actual_prompt: None,
-            model: "BiRefNet".to_string(),
-            provider: "BiRefNet".to_string(),
+            model: "BgFilter complex".to_string(),
+            provider: "BgFilter".to_string(),
             task_id: task_id.clone(),
             group_task_id: None,
             group_task_expected_asset_count: None,
@@ -2744,7 +3206,7 @@ pub(crate) async fn remove_editor_image_background_for_owner(
             source_type: "generated",
             task_id,
             elapsed_ms: u64::try_from(started_at.elapsed().as_millis()).unwrap_or(u64::MAX),
-            provider: "BiRefNet",
+            provider: "BgFilter",
             resource: generated_asset.resource,
             asset: generated_asset.asset,
             project: completed_project,
@@ -2758,17 +3220,186 @@ struct EditorBackgroundRemovalImage {
     height: u32,
 }
 
-struct EditorScreenBackgroundRemovalOutput {
-    image: DownloadedOpenAiImage,
-    provider: &'static str,
-    model: String,
+async fn validate_editor_background_removal_source(
+    state: &AppState,
+    source_object_key: &str,
+) -> Result<(), AppError> {
+    let oss_client = state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置",
+        }))
+    })?;
+    let http_client = reqwest::Client::new();
+    let head = oss_client
+        .head_object(
+            &http_client,
+            OssHeadObjectRequest {
+                object_key: source_object_key.to_string(),
+            },
+        )
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    if head.content_length > EDITOR_REFERENCE_IMAGE_MAX_SIZE_BYTES {
+        return Err(editor_reference_image_too_large());
+    }
+
+    let content_type =
+        normalize_editor_background_removal_source_mime_type(head.content_type.as_deref())
+            .ok_or_else(|| {
+                editor_background_removal_source_unsupported(
+                    "图片参考图的 Content-Type 不是支持的图片类型。",
+                )
+            })?;
+    let signed_url = sign_editor_private_object_read_url(
+        state,
+        source_object_key,
+        EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
+    )?;
+    let probe_end = EDITOR_BACKGROUND_REMOVAL_SOURCE_PROBE_BYTES.saturating_sub(1);
+    let response = http_client
+        .get(signed_url)
+        .header(reqwest::header::RANGE, format!("bytes=0-{probe_end}"))
+        .send()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取图片参考图文件头失败：{error}"),
+            }))
+        })?;
+    if response.status() != StatusCode::PARTIAL_CONTENT {
+        return Err(
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": "OSS 未按 Range 返回图片文件头。",
+                "status": response.status().as_u16(),
+            })),
+        );
+    }
+    if response
+        .content_length()
+        .is_none_or(|size| size > EDITOR_BACKGROUND_REMOVAL_SOURCE_PROBE_BYTES)
+    {
+        return Err(
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": "OSS 返回的图片文件头大小异常。",
+            })),
+        );
+    }
+    let probe = response.bytes().await.map_err(|error| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "aliyun-oss",
+            "message": format!("读取图片参考图文件头失败：{error}"),
+        }))
+    })?;
+    validate_editor_background_removal_source_content(content_type, probe.as_ref())
 }
 
-async fn remove_editor_generated_screen_background_with_bgfilter(
+fn validate_editor_background_removal_source_content(
+    content_type: &str,
+    bytes: &[u8],
+) -> Result<(), AppError> {
+    let detected_type = infer_editor_reference_image_mime_type(bytes).ok_or_else(|| {
+        editor_background_removal_source_unsupported("图片参考图文件魔数不是支持的图片类型。")
+    })?;
+    if detected_type != content_type {
+        return Err(editor_background_removal_source_unsupported(
+            "图片参考图的 Content-Type 与文件魔数不一致。",
+        ));
+    }
+    Ok(())
+}
+
+fn normalize_editor_background_removal_source_mime_type(
+    content_type: Option<&str>,
+) -> Option<&'static str> {
+    let mime_type = content_type?.split(';').next()?.trim();
+    if mime_type.eq_ignore_ascii_case("image/png") {
+        Some("image/png")
+    } else if mime_type.eq_ignore_ascii_case("image/jpeg") {
+        Some("image/jpeg")
+    } else if mime_type.eq_ignore_ascii_case("image/webp") {
+        Some("image/webp")
+    } else {
+        None
+    }
+}
+
+fn editor_background_removal_source_unsupported(message: &str) -> AppError {
+    AppError::from_status(StatusCode::UNSUPPORTED_MEDIA_TYPE).with_details(json!({
+        "provider": "editor-reference-image",
+        "field": "sourceImageSrc",
+        "message": message,
+    }))
+}
+
+async fn request_editor_background_removal_image_with_retry(
     state: &AppState,
-    image: &DownloadedOpenAiImage,
+    source_object_key: &str,
+) -> Result<EditorBackgroundRemovalImage, AppError> {
+    let max_attempts = EDITOR_BGFILTER_RETRY_COUNT + 1;
+    let mut final_error = None;
+    for attempt in 1..=max_attempts {
+        match request_editor_background_removal_image(state, source_object_key).await {
+            Ok(removed) => return Ok(removed),
+            Err(error) => {
+                let will_retry = attempt < max_attempts;
+                tracing::warn!(
+                    provider = "bgfilter",
+                    background_mode = EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX,
+                    attempt,
+                    max_attempts,
+                    will_retry,
+                    error = %error,
+                    error_details = ?error.details(),
+                    "editor_background_removal_request_attempt_failed"
+                );
+                if will_retry {
+                    continue;
+                }
+                final_error = Some(error);
+            }
+        }
+    }
+
+    Err(final_error.expect("BgFilter complex retry loop should retain its final error"))
+}
+
+pub(crate) struct EditorScreenBackgroundRemovalOutput {
+    pub(crate) image: DownloadedOpenAiImage,
+    pub(crate) provider: &'static str,
+    pub(crate) model: String,
+}
+
+pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter(
+    state: &AppState,
+    source_object_key: &str,
     screen_color: EditorScreenBackgroundColor,
     seg_model: &str,
+    cross_check: bool,
+    audit: &crate::external_api_audit::ExternalApiAuditContext,
+) -> Result<EditorScreenBackgroundRemovalOutput, AppError> {
+    remove_editor_generated_screen_background_with_bgfilter_with_request_timeout(
+        state,
+        source_object_key,
+        screen_color,
+        seg_model,
+        cross_check,
+        state.config.editor_bgfilter_request_timeout_ms,
+        audit,
+    )
+    .await
+}
+
+pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter_with_request_timeout(
+    state: &AppState,
+    source_object_key: &str,
+    screen_color: EditorScreenBackgroundColor,
+    seg_model: &str,
+    cross_check: bool,
+    request_timeout_ms: u64,
     audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<EditorScreenBackgroundRemovalOutput, AppError> {
     if let Some(remaining) = editor_bgfilter_circuit_open_remaining(state) {
@@ -2778,72 +3409,124 @@ async fn remove_editor_generated_screen_background_with_bgfilter(
             provider = "bgfilter",
             screen_color = screen_color.hex,
             seg_model,
+            cross_check,
             cooldown_ms = remaining.as_millis() as u64,
             "editor_bgfilter_circuit_open_fallback_to_aliyun_matting"
         );
-        return fallback_editor_screen_background_removal(state, image, screen_color, audit).await;
+        return fallback_editor_screen_background_removal(
+            state,
+            source_object_key,
+            screen_color,
+            audit,
+        )
+        .await;
     }
 
-    match request_editor_generated_screen_background_with_bgfilter(
-        state,
-        image,
-        screen_color,
-        seg_model,
-    )
-    .await
-    {
-        Ok(image) => {
-            record_editor_bgfilter_success();
-            Ok(EditorScreenBackgroundRemovalOutput {
-                image,
-                provider: "BgFilter",
-                model: seg_model.to_string(),
-            })
-        }
-        Err(error) => {
-            record_editor_bgfilter_failure(state);
-            tracing::warn!(
-                provider = "bgfilter",
-                screen_color = screen_color.hex,
-                seg_model,
-                error = %error,
-                error_details = ?error.details(),
-                "editor_bgfilter_fallback_to_aliyun_matting"
-            );
-            crate::external_api_audit::record_matting_external_api_failure(
-                state,
-                audit,
-                "bgfilter",
-                state.config.editor_bgfilter_base_url.clone(),
-                "editor-screen-background-removal",
-                "bgfilter_segment",
-                crate::external_api_audit::matting_failure_audit_status_code(&error),
-                crate::external_api_audit::matting_failure_audit_timeout(&error),
-                crate::external_api_audit::matting_failure_audit_latency_ms(&error),
-                error.message().to_string(),
-                crate::external_api_audit::matting_failure_audit_raw_excerpt(&error),
-            )
-            .await;
-            fallback_editor_screen_background_removal(state, image, screen_color, audit).await
+    let max_attempts = EDITOR_BGFILTER_RETRY_COUNT + 1;
+    let mut final_error = None;
+    for attempt in 1..=max_attempts {
+        match request_editor_generated_screen_background_with_bgfilter(
+            state,
+            source_object_key,
+            screen_color,
+            seg_model,
+            cross_check,
+            request_timeout_ms,
+        )
+        .await
+        {
+            Ok(image) => {
+                record_editor_bgfilter_success();
+                return Ok(EditorScreenBackgroundRemovalOutput {
+                    image,
+                    provider: "BgFilter",
+                    model: seg_model.to_string(),
+                });
+            }
+            Err(error) => {
+                record_editor_bgfilter_failure(state);
+                let will_retry = attempt < max_attempts;
+                tracing::warn!(
+                    provider = "bgfilter",
+                    screen_color = screen_color.hex,
+                    seg_model,
+                    cross_check,
+                    attempt,
+                    max_attempts,
+                    will_retry,
+                    error = %error,
+                    error_details = ?error.details(),
+                    "editor_bgfilter_request_attempt_failed"
+                );
+                crate::external_api_audit::record_matting_external_api_failure(
+                    state,
+                    audit,
+                    "bgfilter",
+                    state.config.editor_bgfilter_base_url.clone(),
+                    "editor-screen-background-removal",
+                    "bgfilter_segment",
+                    crate::external_api_audit::matting_failure_audit_status_code(&error),
+                    crate::external_api_audit::matting_failure_audit_timeout(&error),
+                    crate::external_api_audit::matting_failure_audit_is_transport(&error),
+                    crate::external_api_audit::matting_failure_audit_latency_ms(&error),
+                    error.message().to_string(),
+                    crate::external_api_audit::matting_failure_audit_raw_excerpt(&error),
+                )
+                .await;
+                if will_retry {
+                    continue;
+                }
+                final_error = Some(error);
+            }
         }
     }
+
+    if let Some(error) = final_error {
+        tracing::warn!(
+            provider = "bgfilter",
+            screen_color = screen_color.hex,
+            seg_model,
+            cross_check,
+            error = %error,
+            error_details = ?error.details(),
+            "editor_bgfilter_fallback_to_aliyun_matting"
+        );
+        return fallback_editor_screen_background_removal(
+            state,
+            source_object_key,
+            screen_color,
+            audit,
+        )
+        .await;
+    }
+
+    fallback_editor_screen_background_removal(state, source_object_key, screen_color, audit).await
 }
 
 /// BgFilter 不可用（熔断打开或调用失败）时的统一兜底链：先阿里云通用抠图，失败再退本地键色扣除。
 /// 熔断打开路径与 BgFilter 调用失败路径共用此链，确保 cooldown 内仍是「阿里云 → 本地」而非直接本地。
 async fn fallback_editor_screen_background_removal(
     state: &AppState,
-    image: &DownloadedOpenAiImage,
+    source_object_key: &str,
     screen_color: EditorScreenBackgroundColor,
     audit: &crate::external_api_audit::ExternalApiAuditContext,
 ) -> Result<EditorScreenBackgroundRemovalOutput, AppError> {
-    match crate::aliyun_matting::segment_image_with_aliyun_matting(
+    let aliyun_result = match sign_editor_private_object_read_url(
         state,
-        image,
-        "editor-screen-background",
-    )
-    .await
-    {
+        source_object_key,
+        EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
+    ) {
+        Ok(source_url) => {
+            crate::aliyun_matting::segment_image_url_with_aliyun_matting(
+                state,
+                source_url.as_str(),
+                "editor-screen-background",
+            )
+            .await
+        }
+        Err(error) => Err(error),
+    };
+    match aliyun_result {
         Ok(image) => Ok(EditorScreenBackgroundRemovalOutput {
             image,
             provider: "Aliyun Matting",
@@ -2864,21 +3547,28 @@ async fn fallback_editor_screen_background_removal(
                     "aliyun-matting",
                     state.config.aliyun_matting_endpoint.clone(),
                     "editor-screen-background-removal",
-                    "aliyun_segment",
+                    crate::external_api_audit::matting_failure_audit_failure_stage(
+                        &error,
+                        "aliyun_segment",
+                    ),
                     crate::external_api_audit::matting_failure_audit_status_code(&error),
                     crate::external_api_audit::matting_failure_audit_timeout(&error),
+                    crate::external_api_audit::matting_failure_audit_is_transport(&error),
                     crate::external_api_audit::matting_failure_audit_latency_ms(&error),
                     error.message().to_string(),
                     crate::external_api_audit::matting_failure_audit_raw_excerpt(&error),
                 )
                 .await;
             }
-            remove_editor_generated_green_screen_background(image, screen_color).map(|image| {
-                EditorScreenBackgroundRemovalOutput {
-                    image,
-                    provider: "Genarrative Local",
-                    model: "screen-color-keying".to_string(),
-                }
+            let source_image =
+                download_editor_persisted_image_object(state, source_object_key).await?;
+            let output =
+                remove_editor_generated_green_screen_background(&source_image, screen_color);
+            drop(source_image);
+            output.map(|image| EditorScreenBackgroundRemovalOutput {
+                image,
+                provider: "Genarrative Local",
+                model: "screen-color-keying".to_string(),
             })
         }
     }
@@ -2937,54 +3627,47 @@ fn reset_editor_bgfilter_circuit_for_tests() {
 
 async fn request_editor_generated_screen_background_with_bgfilter(
     state: &AppState,
-    image: &DownloadedOpenAiImage,
+    source_object_key: &str,
     screen_color: EditorScreenBackgroundColor,
     seg_model: &str,
+    cross_check: bool,
+    request_timeout_ms: u64,
 ) -> Result<DownloadedOpenAiImage, AppError> {
     let url = editor_bgfilter_endpoint(state)?;
+    let signed_image_url = sign_editor_private_object_read_url(
+        state,
+        source_object_key,
+        EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
+    )?;
     let call_id = format!("bgfilter-call-{}", current_utc_micros());
     let request_started_at = Instant::now();
-    let timeout_ms = state.config.editor_bgfilter_request_timeout_ms.max(1);
-    let input_bytes = image.bytes.len();
-    let source_mime_type = image.mime_type.clone();
-    let source_file_name = format!(
-        "editor-generated-source.{}",
-        image.extension.trim_start_matches('.')
-    );
+    let timeout_ms = request_timeout_ms.max(1);
     tracing::info!(
         %call_id,
         upstream_url = %url,
-        file_name = %source_file_name,
-        mime_type = %source_mime_type,
+        source_object_key,
+        image_url_expire_seconds = EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
         screen_color = screen_color.hex,
         seg_model,
-        input_bytes,
+        background_mode = EDITOR_BGFILTER_BACKGROUND_MODE_FLAT,
+        cross_check,
         timeout_ms,
         "editor_bgfilter_request_start"
     );
-    let http_client = reqwest::Client::builder()
-        .timeout(std::time::Duration::from_millis(timeout_ms))
-        .build()
-        .map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
-                "provider": "bgfilter",
-                "message": format!("创建 BgFilter HTTP 客户端失败：{error}"),
-            }))
-        })?;
-    let file_part = reqwest::multipart::Part::bytes(image.bytes.clone())
-        .file_name(source_file_name)
-        .mime_str(source_mime_type.as_str())
-        .map_err(|error| {
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "bgfilter",
-                "message": format!("图片 MIME 类型无效：{error}"),
-            }))
-        })?;
+    let http_client = state.editor_bgfilter_http_client();
     let form = reqwest::multipart::Form::new()
-        .part("file", file_part)
+        .text("image_url", signed_image_url.clone())
         .text("screen_color", screen_color.hex.to_string())
-        .text("seg_model", seg_model.to_string());
-    let mut request = http_client.post(url.as_str()).multipart(form);
+        .text("seg_model", seg_model.to_string())
+        .text("background_mode", EDITOR_BGFILTER_BACKGROUND_MODE_FLAT)
+        .text(
+            "cross_check",
+            editor_bgfilter_cross_check_form_value(cross_check),
+        );
+    let mut request = http_client
+        .post(url.as_str())
+        .timeout(Duration::from_millis(timeout_ms))
+        .multipart(form);
     if let Some(token) = state
         .config
         .editor_bgfilter_token
@@ -3011,6 +3694,7 @@ async fn request_editor_generated_screen_background_with_bgfilter(
             .text()
             .await
             .unwrap_or_else(|error| format!("读取上游错误失败：{error}"));
+        let message = sanitize_editor_bgfilter_upstream_message(&message, &signed_image_url);
         tracing::warn!(
             %call_id,
             upstream_status = status.as_u16(),
@@ -3050,6 +3734,11 @@ async fn request_editor_generated_screen_background_with_bgfilter(
         .get("x-bgfilter-screen-color")
         .and_then(|value| value.to_str().ok())
         .map(ToOwned::to_owned);
+    let upstream_cross_check = response
+        .headers()
+        .get("x-bgfilter-cross-check")
+        .and_then(|value| value.to_str().ok())
+        .map(ToOwned::to_owned);
     let bytes = read_editor_image_removal_response_bytes(
         response,
         "bgfilter",
@@ -3080,9 +3769,10 @@ async fn request_editor_generated_screen_background_with_bgfilter(
         height = decoded.height(),
         screen_color = screen_color.hex,
         seg_model,
+        cross_check,
         upstream_screen_color = upstream_screen_color.as_deref().unwrap_or(""),
         upstream_seg_model = upstream_seg_model.as_deref().unwrap_or(""),
-        input_bytes,
+        upstream_cross_check = upstream_cross_check.as_deref().unwrap_or(""),
         output_bytes = image.bytes.len(),
         elapsed_ms = request_started_at.elapsed().as_millis() as u64,
         upstream_elapsed_ms,
@@ -3094,51 +3784,40 @@ async fn request_editor_generated_screen_background_with_bgfilter(
 
 async fn request_editor_background_removal_image(
     state: &AppState,
-    source_image: OpenAiReferenceImage,
+    source_object_key: &str,
 ) -> Result<EditorBackgroundRemovalImage, AppError> {
-    let url = editor_background_removal_endpoint(state)?;
+    let url = editor_bgfilter_endpoint(state)?;
+    let signed_image_url = sign_editor_private_object_read_url(
+        state,
+        source_object_key,
+        EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
+    )?;
     let call_id = format!("background-removal-call-{}", current_utc_micros());
     let request_started_at = Instant::now();
-    let timeout_ms = state
-        .config
-        .editor_background_removal_request_timeout_ms
-        .max(1);
-    let input_bytes = source_image.bytes.len();
-    let source_file_name = source_image.file_name.clone();
-    let source_mime_type = source_image.mime_type.clone();
+    let timeout_ms = state.config.editor_bgfilter_request_timeout_ms.max(1);
     tracing::info!(
         %call_id,
         upstream_url = %url,
-        file_name = %source_file_name,
-        mime_type = %source_mime_type,
-        input_bytes,
+        source_object_key,
+        image_url_expire_seconds = EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS,
+        background_mode = EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX,
+        cross_check = EDITOR_BGFILTER_CROSS_CHECK_DISABLED,
         timeout_ms,
         "editor_background_removal_request_start"
     );
-    let http_client = reqwest::Client::builder()
-        .timeout(std::time::Duration::from_millis(timeout_ms))
-        .build()
-        .map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
-                "provider": "birefnet",
-                "message": format!("创建抠图 HTTP 客户端失败：{error}"),
-            }))
-        })?;
-    let file_part = reqwest::multipart::Part::bytes(source_image.bytes)
-        .file_name(source_image.file_name)
-        .mime_str(source_image.mime_type.as_str())
-        .map_err(|error| {
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "birefnet",
-                "message": format!("图片 MIME 类型无效：{error}"),
-            }))
-        })?;
-    let mut request = http_client
-        .post(url.as_str())
-        .multipart(reqwest::multipart::Form::new().part("file", file_part));
+    let http_client = state.editor_bgfilter_http_client();
+    let form = reqwest::multipart::Form::new()
+        .text("image_url", signed_image_url.clone())
+        .text("background_mode", EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX)
+        .text("seg_model", EDITOR_BGFILTER_DEFAULT_SEG_MODEL)
+        .text(
+            "cross_check",
+            editor_bgfilter_cross_check_form_value(EDITOR_BGFILTER_CROSS_CHECK_DISABLED),
+        );
+    let mut request = http_client.post(url.as_str()).multipart(form);
     if let Some(token) = state
         .config
-        .editor_background_removal_token
+        .editor_bgfilter_token
         .as_deref()
         .map(str::trim)
         .filter(|token| !token.is_empty())
@@ -3153,7 +3832,7 @@ async fn request_editor_background_removal_image(
             error = %error,
             "editor_background_removal_request_failed"
         );
-        map_editor_background_removal_error(error)
+        map_editor_bgfilter_error(error, request_started_at.elapsed().as_millis() as u64)
     })?;
     let status = response.status();
     if !status.is_success() {
@@ -3161,6 +3840,7 @@ async fn request_editor_background_removal_image(
             .text()
             .await
             .unwrap_or_else(|error| format!("读取上游错误失败：{error}"));
+        let message = sanitize_editor_bgfilter_upstream_message(&message, &signed_image_url);
         tracing::warn!(
             %call_id,
             upstream_status = status.as_u16(),
@@ -3170,8 +3850,8 @@ async fn request_editor_background_removal_image(
         );
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": "birefnet",
-                "message": "抠图服务返回非成功状态",
+                "provider": "bgfilter",
+                "message": "BgFilter 服务返回非成功状态",
                 "upstreamStatus": status.as_u16(),
                 "upstreamMessage": message.chars().take(500).collect::<String>(),
             })),
@@ -3186,15 +3866,15 @@ async fn request_editor_background_removal_image(
         .to_string();
     let upstream_elapsed_ms = response
         .headers()
-        .get("x-birefnet-elapsed-ms")
+        .get("x-bgfilter-elapsed-ms")
         .and_then(|value| value.to_str().ok())
         .and_then(|value| value.parse::<u64>().ok());
     let bytes = read_editor_background_removal_bytes(response, request_started_at).await?;
     if bytes.is_empty() {
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": "birefnet",
-                "message": "抠图服务未返回图片",
+                "provider": "bgfilter",
+                "message": "BgFilter 服务未返回图片",
             })),
         );
     }
@@ -3209,7 +3889,6 @@ async fn request_editor_background_removal_image(
         status = status.as_u16(),
         width = decoded.width(),
         height = decoded.height(),
-        input_bytes,
         output_bytes = image.bytes.len(),
         elapsed_ms = request_started_at.elapsed().as_millis() as u64,
         upstream_elapsed_ms,
@@ -3223,22 +3902,6 @@ async fn request_editor_background_removal_image(
     })
 }
 
-fn editor_background_removal_endpoint(state: &AppState) -> Result<String, AppError> {
-    let base_url = state.config.editor_background_removal_base_url.trim();
-    if base_url.is_empty() {
-        return Err(
-            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
-                "provider": "birefnet",
-                "message": "抠图服务地址未配置",
-            })),
-        );
-    }
-    Ok(format!(
-        "{}/remove-background",
-        base_url.trim_end_matches('/')
-    ))
-}
-
 fn editor_bgfilter_endpoint(state: &AppState) -> Result<String, AppError> {
     let base_url = state.config.editor_bgfilter_base_url.trim();
     if base_url.is_empty() {
@@ -3255,6 +3918,34 @@ fn editor_bgfilter_endpoint(state: &AppState) -> Result<String, AppError> {
     ))
 }
 
+fn sign_editor_private_object_read_url(
+    state: &AppState,
+    object_key: &str,
+    expire_seconds: u64,
+) -> Result<String, AppError> {
+    let oss_client = state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置",
+        }))
+    })?;
+    oss_client
+        .sign_get_object_url(OssSignedGetObjectUrlRequest {
+            object_key: object_key.to_string(),
+            expire_seconds: Some(expire_seconds),
+        })
+        .map(|signed| signed.signed_url)
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))
+}
+
+fn sanitize_editor_bgfilter_upstream_message(message: &str, signed_image_url: &str) -> String {
+    let sanitized = message.replace(signed_image_url, "[signed OSS URL redacted]");
+    if sanitized.to_ascii_lowercase().contains("x-oss-") {
+        return "BgFilter 服务返回错误（OSS 签名 URL 已脱敏）".to_string();
+    }
+    sanitized.chars().take(500).collect()
+}
+
 fn parse_editor_bgfilter_seg_model(value: Option<&str>) -> Result<&'static str, AppError> {
     let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
         return Ok(EDITOR_BGFILTER_DEFAULT_SEG_MODEL);
@@ -3275,17 +3966,8 @@ fn parse_editor_bgfilter_seg_model(value: Option<&str>) -> Result<&'static str,
     }
 }
 
-fn map_editor_background_removal_error(error: reqwest::Error) -> AppError {
-    let status = if error.is_timeout() {
-        StatusCode::GATEWAY_TIMEOUT
-    } else {
-        StatusCode::BAD_GATEWAY
-    };
-    AppError::from_status(status).with_details(json!({
-        "provider": "birefnet",
-        "message": format!("请求抠图服务失败：{error}"),
-        "timeout": error.is_timeout(),
-    }))
+fn editor_bgfilter_cross_check_form_value(enabled: bool) -> &'static str {
+    if enabled { "on" } else { "off" }
 }
 
 fn map_editor_bgfilter_error(error: reqwest::Error, latency_ms: u64) -> AppError {
@@ -3307,7 +3989,7 @@ async fn read_editor_background_removal_bytes(
     response: reqwest::Response,
     request_started_at: Instant,
 ) -> Result<Vec<u8>, AppError> {
-    read_editor_image_removal_response_bytes(response, "birefnet", "抠图服务", request_started_at)
+    read_editor_image_removal_response_bytes(response, "bgfilter", "BgFilter", request_started_at)
         .await
 }
 
@@ -3380,7 +4062,7 @@ fn editor_image_removal_body_read_error(
 }
 
 fn decode_editor_background_removal_image(bytes: &[u8]) -> Result<image::DynamicImage, AppError> {
-    decode_editor_removed_background_image(bytes, "birefnet")
+    decode_editor_removed_background_image(bytes, "bgfilter")
 }
 
 fn decode_editor_removed_background_image(
@@ -3537,6 +4219,18 @@ pub async fn generate_editor_icon_spritesheet(
 ) -> Result<Json<Value>, AppError> {
     let caller = EditorGenerationCaller::from_authenticated(&authenticated);
     if !state.config.external_generation_mode.is_inline() {
+        ensure_editor_reference_image_source_is_stable(
+            payload.reference_image_src.as_str(),
+            "editor-icon-spritesheet",
+            "referenceImageSrc",
+            "图标素材规范",
+        )?;
+        ensure_editor_reference_image_sources_are_stable(
+            payload.reference_image_srcs.as_deref(),
+            "editor-icon-spritesheet",
+            "referenceImageSrcs",
+            "图标素材参考图",
+        )?;
         let generation_options = normalize_editor_generation_options(
             payload.model.as_deref(),
             payload.aspect_ratio.as_deref(),
@@ -3581,6 +4275,18 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorIconSpritesheetGenerationRequest,
 ) -> Result<Json<Value>, AppError> {
+    ensure_editor_reference_image_source_is_stable(
+        payload.reference_image_src.as_str(),
+        "editor-icon-spritesheet",
+        "referenceImageSrc",
+        "图标素材规范",
+    )?;
+    ensure_editor_reference_image_sources_are_stable(
+        payload.reference_image_srcs.as_deref(),
+        "editor-icon-spritesheet",
+        "referenceImageSrcs",
+        "图标素材参考图",
+    )?;
     let icon_descriptions = normalize_icon_descriptions(payload.icon_descriptions)?;
     // 背景色决策挪到预扣泥点之后（见下方 execute_billable 闭包），避免余额不足 / 生成注定失败时
     // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要的输入。
@@ -3600,7 +4306,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
             error.with_details(json!({
                 "provider": "editor-icon-spritesheet",
                 "field": "referenceImageSrc",
-                "message": "图标素材规范必须是图片 Data URL、objectKey、资源或素材引用。",
+                "message": "图标素材规范必须是 objectKey、资源或素材引用。",
             }))
         })?,
     );
@@ -3614,7 +4320,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
                     error.with_details(json!({
                         "provider": "editor-icon-spritesheet",
                         "field": "referenceImageSrcs",
-                        "message": "图标素材参考图必须是图片 Data URL、objectKey、资源或素材引用。",
+                        "message": "图标素材参考图必须是 objectKey、资源或素材引用。",
                     }))
                 })?,
         );
@@ -3731,7 +4437,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         state,
         caller.owner_user_id.as_str(),
         generated.task_id.as_str(),
-        &image,
+        image,
         prompt.as_str(),
         generated.actual_prompt.as_deref(),
         EDITOR_ICON_SPRITESHEET_ASSET_KIND,
@@ -3739,6 +4445,8 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         "spritesheet",
     )
     .await?;
+    let source_image_src = editor_media_src_from_object_key(source_persisted.object_key.as_str());
+    let source_object_key = source_persisted.object_key.clone();
     let source_record = persist_editor_provider_source_resource(
         state,
         source_persisted,
@@ -3760,6 +4468,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         },
     )
     .await?;
+    caller.report_processing_phase(state).await?;
     let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
         user_id: caller.audit_subject_user_id.clone(),
         profile_id: caller
@@ -3770,13 +4479,76 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
     };
     let removal = remove_editor_generated_screen_background_with_bgfilter(
         state,
-        &image,
+        source_object_key.as_str(),
         screen_color,
         seg_model,
+        EDITOR_BGFILTER_CROSS_CHECK_DISABLED,
         &matting_audit,
     )
-    .await?;
-    let image = removal.image;
+    .await;
+    let removal = match removal {
+        Ok(removal) => removal,
+        Err(error) => {
+            let failure_message = error.body_text();
+            tracing::warn!(
+                provider = "editor-icon-spritesheet",
+                operation = "background_postprocess",
+                task_id = %generated.task_id,
+                error = %failure_message,
+                "图标图集原图已保存，但透明背景处理失败，使用原图完成画布"
+            );
+            let completed_project = complete_editor_canvas_generation(
+                state,
+                caller.owner_user_id.as_str(),
+                payload.project_id.as_deref(),
+                payload.canvas_completion.as_ref(),
+                source_record.resource.as_ref(),
+            )
+            .await?;
+            return Ok(json_success_body(
+                Some(&request_context),
+                EditorIconSpritesheetGenerationResponse {
+                    spritesheet_image_src: source_image_src,
+                    spritesheet_width: source_width,
+                    spritesheet_height: source_height,
+                    icon_image_srcs: Vec::new(),
+                    slice_warning: None,
+                    prompt,
+                    actual_prompt: generated.actual_prompt,
+                    model: generation_options.model.to_string(),
+                    provider: "VectorEngine",
+                    task_id: generated.task_id,
+                    price_mud_points: expected_price_mud_points,
+                    spritesheet_resource: source_record.resource,
+                    spritesheet_asset: source_record.asset,
+                    project: completed_project,
+                    warning: Some(editor_postprocess_fallback_warning(
+                        "生成任务成功，后处理失败。",
+                    )),
+                },
+            ));
+        }
+    };
+    let removal_provider = removal.provider;
+    let (image, postprocess_dimension_error) =
+        apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original(
+            state,
+            source_object_key.as_str(),
+            source_width,
+            source_height,
+            removal.image,
+        )
+        .await;
+    if let Some(error) = postprocess_dimension_error {
+        tracing::warn!(
+            task_id = %generated.task_id,
+            provider = removal_provider,
+            source_width,
+            source_height,
+            error = ?error,
+            "图标透明图蒙版尺寸恢复失败，保留去背景服务原始输出"
+        );
+    }
     let matting_generation_inputs = build_editor_derived_asset_generation_inputs(
         "图标图集抠图",
         &removal.model,
@@ -3948,6 +4720,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
             spritesheet_resource: spritesheet_record.resource,
             spritesheet_asset: spritesheet_record.asset,
             project: completed_project,
+            warning: None,
         },
     ))
 }
@@ -4200,6 +4973,18 @@ pub async fn extract_editor_ui_design_assets(
 ) -> Result<Json<Value>, AppError> {
     let caller = EditorGenerationCaller::from_authenticated(&authenticated);
     if !state.config.external_generation_mode.is_inline() {
+        ensure_editor_reference_image_source_is_stable(
+            payload.source_image_src.as_str(),
+            "editor-ui-design-asset-extraction",
+            "sourceImageSrc",
+            "UI设计图",
+        )?;
+        ensure_editor_reference_image_sources_are_stable(
+            payload.reference_image_srcs.as_deref(),
+            "editor-ui-design-asset-extraction",
+            "referenceImageSrcs",
+            "UI素材参考图",
+        )?;
         let generation_options = normalize_editor_ui_design_asset_extraction_options(
             payload.model.as_deref(),
             payload.aspect_ratio.as_str(),
@@ -4244,6 +5029,18 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorUiDesignAssetExtractionRequest,
 ) -> Result<Json<Value>, AppError> {
+    ensure_editor_reference_image_source_is_stable(
+        payload.source_image_src.as_str(),
+        "editor-ui-design-asset-extraction",
+        "sourceImageSrc",
+        "UI设计图",
+    )?;
+    ensure_editor_reference_image_sources_are_stable(
+        payload.reference_image_srcs.as_deref(),
+        "editor-ui-design-asset-extraction",
+        "referenceImageSrcs",
+        "UI素材参考图",
+    )?;
     // 背景色决策挪到预扣泥点之后（见下方 execute_billable 闭包），避免余额不足 / 生成注定失败时
     // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要的输入。
     let requested_screen_color = payload.screen_color.clone();
@@ -4263,7 +5060,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         error.with_details(json!({
             "provider": "editor-ui-design-asset-extraction",
             "field": "sourceImageSrc",
-            "message": "UI设计图必须是图片 Data URL、objectKey、资源或素材引用。",
+            "message": "UI设计图必须是 objectKey、资源或素材引用。",
         }))
     })?;
     let mut reference_images = vec![reference_image];
@@ -4278,7 +5075,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
                     error.with_details(json!({
                         "provider": "editor-ui-design-asset-extraction",
                         "field": "referenceImageSrcs",
-                        "message": "UI素材参考图必须是图片 Data URL、objectKey、资源或素材引用。",
+                        "message": "UI素材参考图必须是 objectKey、资源或素材引用。",
                     }))
                 })?,
         );
@@ -4393,7 +5190,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         state,
         caller.owner_user_id.as_str(),
         generated.task_id.as_str(),
-        &image,
+        image,
         prompt.as_str(),
         generated.actual_prompt.as_deref(),
         EDITOR_UI_DESIGN_SPRITESHEET_ASSET_KIND,
@@ -4401,6 +5198,8 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         "spritesheet",
     )
     .await?;
+    let source_image_src = editor_media_src_from_object_key(source_persisted.object_key.as_str());
+    let source_object_key = source_persisted.object_key.clone();
     let source_record = persist_editor_provider_source_resource(
         state,
         source_persisted,
@@ -4422,6 +5221,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         },
     )
     .await?;
+    caller.report_processing_phase(state).await?;
     let matting_audit = crate::external_api_audit::ExternalApiAuditContext {
         user_id: caller.audit_subject_user_id.clone(),
         profile_id: caller
@@ -4432,13 +5232,76 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
     };
     let removal = remove_editor_generated_screen_background_with_bgfilter(
         state,
-        &image,
+        source_object_key.as_str(),
         screen_color,
         seg_model,
+        EDITOR_BGFILTER_CROSS_CHECK_DISABLED,
         &matting_audit,
     )
-    .await?;
-    let image = removal.image;
+    .await;
+    let removal = match removal {
+        Ok(removal) => removal,
+        Err(error) => {
+            let failure_message = error.body_text();
+            tracing::warn!(
+                provider = "editor-ui-design-asset-extraction",
+                operation = "background_postprocess",
+                task_id = %generated.task_id,
+                error = %failure_message,
+                "UI 素材图集原图已保存，但透明背景处理失败，使用原图完成画布"
+            );
+            let completed_project = complete_editor_canvas_generation(
+                state,
+                caller.owner_user_id.as_str(),
+                payload.project_id.as_deref(),
+                payload.canvas_completion.as_ref(),
+                source_record.resource.as_ref(),
+            )
+            .await?;
+            return Ok(json_success_body(
+                Some(&request_context),
+                EditorIconSpritesheetGenerationResponse {
+                    spritesheet_image_src: source_image_src,
+                    spritesheet_width: source_width,
+                    spritesheet_height: source_height,
+                    icon_image_srcs: Vec::new(),
+                    slice_warning: None,
+                    prompt,
+                    actual_prompt: generated.actual_prompt,
+                    model: generation_options.model.to_string(),
+                    provider: "VectorEngine",
+                    task_id: generated.task_id,
+                    price_mud_points: expected_price_mud_points,
+                    spritesheet_resource: source_record.resource,
+                    spritesheet_asset: source_record.asset,
+                    project: completed_project,
+                    warning: Some(editor_postprocess_fallback_warning(
+                        "生成任务成功，后处理失败。",
+                    )),
+                },
+            ));
+        }
+    };
+    let removal_provider = removal.provider;
+    let (image, postprocess_dimension_error) =
+        apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original(
+            state,
+            source_object_key.as_str(),
+            source_width,
+            source_height,
+            removal.image,
+        )
+        .await;
+    if let Some(error) = postprocess_dimension_error {
+        tracing::warn!(
+            task_id = %generated.task_id,
+            provider = removal_provider,
+            source_width,
+            source_height,
+            error = ?error,
+            "UI 素材透明图蒙版尺寸恢复失败，保留去背景服务原始输出"
+        );
+    }
     let matting_generation_inputs =
         build_editor_derived_asset_generation_inputs("UI图集抠图", &removal.model, &source_record);
     let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
@@ -4604,6 +5467,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
             spritesheet_resource: spritesheet_record.resource,
             spritesheet_asset: spritesheet_record.asset,
             project: completed_project,
+            warning: None,
         },
     ))
 }
@@ -5883,10 +6747,9 @@ fn generated_canvas_media_type(asset_kind: Option<&str>) -> &'static str {
     }
 }
 
-fn build_multi_asset_canvas_layer_items(
+fn build_primary_canvas_layer_items(
     completion: &EditorCanvasGenerationCompletionRequest,
     primary_resource: Option<&EditorProjectResourcePayload>,
-    source_resource: Option<&EditorProjectResourcePayload>,
 ) -> (Vec<Value>, Option<String>) {
     let Some(primary_resource) = primary_resource else {
         return (Vec::new(), None);
@@ -5900,25 +6763,37 @@ fn build_multi_asset_canvas_layer_items(
         primary_layer_id.as_str(),
         0,
     );
+    (vec![primary_item], Some(primary_layer_id))
+}
+
+fn build_multi_asset_canvas_layer_items(
+    completion: &EditorCanvasGenerationCompletionRequest,
+    primary_resource: Option<&EditorProjectResourcePayload>,
+    source_resource: Option<&EditorProjectResourcePayload>,
+) -> (Vec<Value>, Option<String>) {
+    let (mut items, primary_layer_id) =
+        build_primary_canvas_layer_items(completion, primary_resource);
+    let Some(primary_item) = items.first() else {
+        return (items, primary_layer_id);
+    };
     let primary_right = primary_item
         .get("x")
         .and_then(Value::as_f64)
-        .unwrap_or(placeholder.x)
+        .unwrap_or(completion.placeholder.x)
         + primary_item
             .get("width")
             .and_then(Value::as_f64)
-            .unwrap_or(placeholder.width.max(1.0));
+            .unwrap_or(completion.placeholder.width.max(1.0));
     let primary_y = primary_item
         .get("y")
         .and_then(Value::as_f64)
-        .unwrap_or(placeholder.y);
-    let mut items = vec![primary_item];
+        .unwrap_or(completion.placeholder.y);
 
     if let Some(source_resource) = source_resource {
         let source_layer_id = generated_canvas_layer_id(source_resource.resource_id.as_str());
         let mut source_item = build_generated_canvas_layer_item(
             completion,
-            &placeholder,
+            &completion.placeholder,
             source_resource,
             source_layer_id.as_str(),
             0,
@@ -5934,7 +6809,7 @@ fn build_multi_asset_canvas_layer_items(
         items.push(source_item);
     }
 
-    (items, Some(primary_layer_id))
+    (items, primary_layer_id)
 }
 
 fn build_icon_spritesheet_canvas_layer_items(
@@ -6432,6 +7307,71 @@ pub(crate) async fn persist_editor_generated_image(
     file_stem: &str,
     slot: &str,
     provider: &str,
+) -> Result<PersistedEditorGeneratedImage, AppError> {
+    persist_editor_generated_image_data(
+        state,
+        owner_user_id,
+        task_id,
+        GeneratedImageAssetDataUrl {
+            format: normalize_generated_image_asset_mime(image.mime_type.as_str()),
+            bytes: image.bytes.clone(),
+        },
+        prompt,
+        actual_prompt,
+        asset_kind,
+        path_kind,
+        file_stem,
+        slot,
+        provider,
+    )
+    .await
+}
+
+async fn persist_editor_generated_image_owned(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: &str,
+    image: DownloadedOpenAiImage,
+    prompt: &str,
+    actual_prompt: Option<&str>,
+    asset_kind: &str,
+    path_kind: &str,
+    file_stem: &str,
+    slot: &str,
+    provider: &str,
+) -> Result<PersistedEditorGeneratedImage, AppError> {
+    let image_data = GeneratedImageAssetDataUrl {
+        format: normalize_generated_image_asset_mime(image.mime_type.as_str()),
+        bytes: image.bytes,
+    };
+    persist_editor_generated_image_data(
+        state,
+        owner_user_id,
+        task_id,
+        image_data,
+        prompt,
+        actual_prompt,
+        asset_kind,
+        path_kind,
+        file_stem,
+        slot,
+        provider,
+    )
+    .await
+}
+
+async fn persist_editor_generated_image_data(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: &str,
+    image: GeneratedImageAssetDataUrl,
+    prompt: &str,
+    actual_prompt: Option<&str>,
+    asset_kind: &str,
+    path_kind: &str,
+    file_stem: &str,
+    slot: &str,
+    provider: &str,
 ) -> Result<PersistedEditorGeneratedImage, AppError> {
     let oss_client = state.oss_client().ok_or_else(|| {
         AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
@@ -6448,10 +7388,7 @@ pub(crate) async fn persist_editor_generated_image(
                 sanitize_editor_storage_segment(task_id, "task"),
             ],
             file_stem: sanitize_editor_storage_segment(file_stem, "image"),
-            image: GeneratedImageAssetDataUrl {
-                format: normalize_generated_image_asset_mime(image.mime_type.as_str()),
-                bytes: image.bytes.clone(),
-            },
+            image,
             access: OssObjectAccess::Private,
             metadata: GeneratedImageAssetAdapterMetadata {
                 asset_kind: Some(asset_kind.to_string()),
@@ -6527,14 +7464,14 @@ async fn persist_editor_provider_source_image(
     state: &AppState,
     owner_user_id: &str,
     task_id: &str,
-    image: &DownloadedOpenAiImage,
+    image: DownloadedOpenAiImage,
     prompt: &str,
     actual_prompt: Option<&str>,
     asset_kind: &str,
     path_kind: &str,
     file_stem: &str,
 ) -> Result<PersistedEditorGeneratedImage, AppError> {
-    persist_editor_generated_image(
+    persist_editor_generated_image_owned(
         state,
         owner_user_id,
         task_id,
@@ -6586,23 +7523,70 @@ async fn persist_editor_provider_source_resource(
 
 const EDITOR_REFERENCE_IMAGE_READ_EXPIRE_SECONDS: u64 = 300;
 const EDITOR_REFERENCE_IMAGE_MAX_SIZE_BYTES: u64 = 32 * 1024 * 1024;
+const EDITOR_BACKGROUND_REMOVAL_SOURCE_PROBE_BYTES: u64 = 16;
 const EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES: usize = 32 * 1024 * 1024;
 const EDITOR_BACKGROUND_REMOVAL_MAX_IMAGE_DIMENSION: u32 = 8192;
 
+fn is_editor_inline_media_source(source: &str) -> bool {
+    source
+        .trim_start()
+        .as_bytes()
+        .get(..5)
+        .is_some_and(|prefix| {
+            prefix.eq_ignore_ascii_case(b"data:") || prefix.eq_ignore_ascii_case(b"blob:")
+        })
+}
+
+fn ensure_editor_reference_image_source_is_stable(
+    source: &str,
+    provider: &str,
+    field: &str,
+    label: &str,
+) -> Result<(), AppError> {
+    if !is_editor_inline_media_source(source) {
+        return Ok(());
+    }
+    Err(
+        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": provider,
+            "field": field,
+            "message": format!("{label}必须先上传 OSS，并使用 objectKey、项目资源 ID 或素材 ID 引用。"),
+        })),
+    )
+}
+
+fn ensure_editor_reference_image_sources_are_stable(
+    sources: Option<&[String]>,
+    provider: &str,
+    field: &str,
+    label: &str,
+) -> Result<(), AppError> {
+    for source in sources.unwrap_or(&[]) {
+        ensure_editor_reference_image_source_is_stable(source, provider, field, label)?;
+    }
+    Ok(())
+}
+
 pub(crate) async fn parse_editor_reference_image(
     state: &AppState,
     owner_user_id: &str,
     source: &str,
 ) -> Result<OpenAiReferenceImage, AppError> {
-    let trimmed = source.trim();
-    if trimmed.starts_with("data:") {
-        return parse_editor_reference_image_data_url(trimmed);
-    }
-    let object_key = resolve_editor_reference_object_key(state, owner_user_id, trimmed).await?;
-    ensure_editor_reference_object_key_owned(state, owner_user_id, object_key.as_str()).await?;
+    let object_key =
+        resolve_editor_reference_object_key_for_owner(state, owner_user_id, source).await?;
     read_editor_reference_image_object(state, object_key.as_str()).await
 }
 
+pub(crate) async fn resolve_editor_reference_object_key_for_owner(
+    state: &AppState,
+    owner_user_id: &str,
+    source: &str,
+) -> Result<String, AppError> {
+    let object_key = resolve_editor_reference_object_key(state, owner_user_id, source).await?;
+    ensure_editor_reference_object_key_owned(state, owner_user_id, object_key.as_str()).await?;
+    Ok(object_key)
+}
+
 fn normalize_editor_reference_image_sources(sources: Option<&[String]>, limit: usize) -> Vec<&str> {
     sources
         .unwrap_or(&[])
@@ -6621,7 +7605,7 @@ fn normalize_editor_reference_object_key(source: &str) -> Result<String, AppErro
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                 "provider": "editor-reference-image",
                 "field": "sourceImageSrc",
-                "message": "图片参考图必须是图片 Data URL、已登记的 generated objectKey、项目资源或素材引用。",
+                "message": "图片参考图必须是已登记的 generated objectKey、项目资源或素材引用。",
             })),
         );
     }
@@ -6633,6 +7617,12 @@ async fn resolve_editor_reference_object_key(
     owner_user_id: &str,
     source: &str,
 ) -> Result<String, AppError> {
+    ensure_editor_reference_image_source_is_stable(
+        source,
+        "editor-reference-image",
+        "sourceImageSrc",
+        "图片参考图",
+    )?;
     match normalize_editor_reference_object_key(source) {
         Ok(object_key) => Ok(object_key),
         Err(error) => {
@@ -6806,58 +7796,6 @@ fn editor_reference_image_forbidden(object_key: &str) -> AppError {
     }))
 }
 
-fn parse_editor_reference_image_data_url(source: &str) -> Result<OpenAiReferenceImage, AppError> {
-    let Some((header, data)) = source.trim().split_once(',') else {
-        return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "editor-image-edit",
-                "field": "sourceImageSrc",
-                "message": "修改图片参考图必须是图片 Data URL。",
-            })),
-        );
-    };
-    let Some(mime_type) = header
-        .strip_prefix("data:")
-        .and_then(|value| value.strip_suffix(";base64"))
-        .filter(|value| value.starts_with("image/"))
-    else {
-        return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "editor-image-edit",
-                "field": "sourceImageSrc",
-                "message": "修改图片参考图必须是 base64 图片 Data URL。",
-            })),
-        );
-    };
-    let bytes = BASE64_STANDARD.decode(data.trim()).map_err(|error| {
-        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-            "provider": "editor-image-edit",
-            "field": "sourceImageSrc",
-            "message": format!("修改图片参考图解码失败：{error}"),
-        }))
-    })?;
-    if bytes.is_empty() {
-        return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "editor-image-edit",
-                "field": "sourceImageSrc",
-                "message": "修改图片参考图为空。",
-            })),
-        );
-    }
-    let extension = match mime_type {
-        "image/jpeg" => "jpg",
-        "image/png" => "png",
-        "image/webp" => "webp",
-        _ => "png",
-    };
-    Ok(OpenAiReferenceImage {
-        bytes,
-        mime_type: mime_type.to_string(),
-        file_name: format!("editor-reference.{extension}"),
-    })
-}
-
 async fn read_editor_reference_image_object(
     state: &AppState,
     source: &str,
@@ -6883,7 +7821,7 @@ async fn read_editor_reference_image_object(
             expire_seconds: Some(EDITOR_REFERENCE_IMAGE_READ_EXPIRE_SECONDS),
         })
         .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
-    let response = reqwest::Client::new()
+    let mut response = reqwest::Client::new()
         .get(signed.signed_url.as_str())
         .send()
         .await
@@ -6915,12 +7853,18 @@ async fn read_editor_reference_image_object(
         .and_then(|value| value.to_str().ok())
         .and_then(normalize_editor_reference_image_mime_type)
         .map(ToOwned::to_owned);
-    let bytes = response.bytes().await.map_err(|error| {
+    let mut bytes = Vec::new();
+    while let Some(chunk) = response.chunk().await.map_err(|error| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
             "provider": "aliyun-oss",
             "message": format!("读取图片参考图内容失败：{error}"),
         }))
-    })?;
+    })? {
+        if bytes.len().saturating_add(chunk.len()) as u64 > EDITOR_REFERENCE_IMAGE_MAX_SIZE_BYTES {
+            return Err(editor_reference_image_too_large());
+        }
+        bytes.extend_from_slice(chunk.as_ref());
+    }
     if bytes.is_empty() {
         return Err(
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
@@ -6930,11 +7874,8 @@ async fn read_editor_reference_image_object(
             })),
         );
     }
-    if bytes.len() as u64 > EDITOR_REFERENCE_IMAGE_MAX_SIZE_BYTES {
-        return Err(editor_reference_image_too_large());
-    }
     let mime_type = content_type_mime
-        .or_else(|| infer_editor_reference_image_mime_type(bytes.as_ref()).map(ToOwned::to_owned))
+        .or_else(|| infer_editor_reference_image_mime_type(bytes.as_slice()).map(ToOwned::to_owned))
         .ok_or_else(|| {
             AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                 "provider": "editor-reference-image",
@@ -6946,12 +7887,24 @@ async fn read_editor_reference_image_object(
         .to_string();
     let extension = editor_reference_image_extension(mime_type.as_str());
     Ok(OpenAiReferenceImage {
-        bytes: bytes.to_vec(),
+        bytes,
         mime_type,
         file_name: format!("editor-reference.{extension}"),
     })
 }
 
+async fn download_editor_persisted_image_object(
+    state: &AppState,
+    object_key: &str,
+) -> Result<DownloadedOpenAiImage, AppError> {
+    let image = read_editor_reference_image_object(state, object_key).await?;
+    Ok(DownloadedOpenAiImage {
+        extension: editor_reference_image_extension(image.mime_type.as_str()).to_string(),
+        mime_type: image.mime_type,
+        bytes: image.bytes,
+    })
+}
+
 fn normalize_editor_reference_image_mime_type(content_type: &str) -> Option<&str> {
     let mime_type = content_type.split(';').next()?.trim();
     mime_type.starts_with("image/").then_some(mime_type)
@@ -7037,6 +7990,107 @@ pub(crate) fn current_utc_micros() -> i64 {
 mod tests {
     use super::*;
     use crate::{config::AppConfig, editor_green_screen::parse_editor_screen_background_color};
+    use std::{
+        io::{Read as _, Write as _},
+        net::{TcpListener, TcpStream},
+        sync::mpsc,
+        thread,
+    };
+
+    fn encode_test_png(width: u32, height: u32) -> Vec<u8> {
+        let image = image::DynamicImage::new_rgba8(width, height);
+        let mut bytes = Cursor::new(Vec::new());
+        image
+            .write_to(&mut bytes, image::ImageFormat::Png)
+            .expect("test PNG should encode");
+        bytes.into_inner()
+    }
+
+    fn read_mock_http_request(stream: &mut TcpStream) -> Vec<u8> {
+        stream
+            .set_read_timeout(Some(Duration::from_secs(1)))
+            .expect("mock request read timeout should be set");
+        let mut request = Vec::new();
+        let mut chunk = [0_u8; 1024];
+        let mut expected_total = None;
+
+        loop {
+            match stream.read(&mut chunk) {
+                Ok(0) => break,
+                Ok(bytes_read) => {
+                    request.extend_from_slice(&chunk[..bytes_read]);
+                    if expected_total.is_none()
+                        && let Some(header_end) = request
+                            .windows(4)
+                            .position(|window| window == b"\r\n\r\n")
+                            .map(|index| index + 4)
+                    {
+                        let headers = String::from_utf8_lossy(&request[..header_end]);
+                        let content_length = headers
+                            .lines()
+                            .find_map(|line| {
+                                let (name, value) = line.split_once(':')?;
+                                name.eq_ignore_ascii_case("content-length")
+                                    .then(|| value.trim().parse::<usize>().ok())
+                                    .flatten()
+                            })
+                            .unwrap_or(0);
+                        expected_total = Some(header_end + content_length);
+                    }
+                    if expected_total.is_some_and(|total| request.len() >= total) {
+                        break;
+                    }
+                }
+                Err(error)
+                    if error.kind() == std::io::ErrorKind::WouldBlock
+                        || error.kind() == std::io::ErrorKind::TimedOut =>
+                {
+                    break;
+                }
+                Err(error) => panic!("mock server failed to read request: {error}"),
+            }
+        }
+
+        request
+    }
+
+    fn spawn_bgfilter_png_mock(
+        response_png: Vec<u8>,
+    ) -> (String, mpsc::Receiver<Vec<u8>>, thread::JoinHandle<()>) {
+        spawn_bgfilter_png_mock_with_delay(response_png, Duration::ZERO)
+    }
+
+    fn spawn_bgfilter_png_mock_with_delay(
+        response_png: Vec<u8>,
+        response_delay: Duration,
+    ) -> (String, mpsc::Receiver<Vec<u8>>, thread::JoinHandle<()>) {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("mock listener should bind");
+        let address = listener
+            .local_addr()
+            .expect("mock listener should expose address");
+        let (request_sender, request_receiver) = mpsc::channel();
+        let server = thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("BgFilter request should connect");
+            let request = read_mock_http_request(&mut stream);
+            request_sender
+                .send(request)
+                .expect("captured request should be delivered");
+            thread::sleep(response_delay);
+            let headers = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: image/png\r\nX-BgFilter-Elapsed-Ms: 9\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+                response_png.len()
+            );
+            stream
+                .write_all(headers.as_bytes())
+                .expect("mock response headers should be written");
+            stream
+                .write_all(response_png.as_slice())
+                .expect("mock response PNG should be written");
+            stream.flush().expect("mock response should flush");
+        });
+
+        (format!("http://{address}"), request_receiver, server)
+    }
 
     fn editor_project_resource_for_canvas_test(
         resource_id: &str,
@@ -7125,6 +8179,25 @@ mod tests {
         );
     }
 
+    #[test]
+    fn bgfilter_upstream_message_redacts_signed_oss_url() {
+        let signed_url = "https://dev-bucket.oss-cn-beijing.aliyuncs.com/generated/input.png?x-oss-signature=secret&x-oss-expires=600";
+        let message = format!("invalid image_url: {signed_url}; code=fetch_failed");
+
+        let sanitized = sanitize_editor_bgfilter_upstream_message(&message, signed_url);
+
+        assert!(!sanitized.contains("x-oss-signature"));
+        assert!(!sanitized.contains("secret"));
+        assert!(sanitized.contains("[signed OSS URL redacted]"));
+        assert!(sanitized.contains("fetch_failed"));
+
+        let escaped_message = format!("invalid image_url: {}", signed_url.replace('&', "\\u0026"));
+        let escaped_sanitized =
+            sanitize_editor_bgfilter_upstream_message(&escaped_message, signed_url);
+        assert!(!escaped_sanitized.contains("x-oss-"));
+        assert!(!escaped_sanitized.contains("secret"));
+    }
+
     #[test]
     fn bgfilter_body_read_timeout_maps_to_gateway_timeout_and_transport() {
         let error = editor_image_removal_body_read_error(
@@ -7733,23 +8806,51 @@ mod tests {
         let state = AppState::new(AppConfig::default()).expect("state should build");
 
         assert_eq!(
-            resolve_editor_image_edit_price(&state, GPT_IMAGE_2_MODEL, "1024x1024")
+            resolve_editor_image_edit_price(&state, GPT_IMAGE_2_MODEL, "1024x1024", None)
                 .await
                 .unwrap(),
             3
         );
         assert_eq!(
-            resolve_editor_image_edit_price(&state, GPT_IMAGE_2_MODEL, "2048x1152")
+            resolve_editor_image_edit_price(&state, GPT_IMAGE_2_MODEL, "2048x1152", None)
                 .await
                 .unwrap(),
             5
         );
         assert_eq!(
-            resolve_editor_image_edit_price(&state, EDITOR_IMAGE_MODEL_NANOBANANA2, "2048x2048")
+            resolve_editor_image_edit_price(&state, GPT_IMAGE_2_MODEL, "2048x1152", Some("1K"),)
                 .await
                 .unwrap(),
+            5
+        );
+        assert_eq!(
+            resolve_editor_image_edit_price(
+                &state,
+                EDITOR_IMAGE_MODEL_NANOBANANA2,
+                "2048x2048",
+                Some("2K"),
+            )
+            .await
+            .unwrap(),
             24
         );
+        assert_eq!(
+            resolve_editor_image_edit_price(
+                &state,
+                EDITOR_IMAGE_MODEL_NANOBANANA2,
+                "512x512",
+                Some("0.5K"),
+            )
+            .await
+            .unwrap(),
+            8
+        );
+        assert!(editor_image_edit_uses_nanobanana_generate_content(
+            EDITOR_IMAGE_MODEL_NANOBANANA2
+        ));
+        assert!(!editor_image_edit_uses_nanobanana_generate_content(
+            GPT_IMAGE_2_MODEL
+        ));
     }
 
     #[test]
@@ -7804,6 +8905,44 @@ mod tests {
         assert_eq!(restored.extension, "png");
     }
 
+    #[test]
+    fn static_image_postprocess_restores_only_alpha_at_provider_dimensions() {
+        let provider_source = image::RgbaImage::from_pixel(4, 4, image::Rgba([200, 10, 20, 255]));
+        let mut provider_source_bytes = Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(provider_source)
+            .write_to(&mut provider_source_bytes, image::ImageFormat::Png)
+            .expect("test image should encode");
+        let provider_source = DownloadedOpenAiImage {
+            bytes: provider_source_bytes.into_inner(),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        };
+
+        let postprocessed = image::RgbaImage::from_pixel(2, 2, image::Rgba([1, 2, 240, 77]));
+        let mut postprocessed_bytes = Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(postprocessed)
+            .write_to(&mut postprocessed_bytes, image::ImageFormat::Png)
+            .expect("test image should encode");
+        let postprocessed = DownloadedOpenAiImage {
+            bytes: postprocessed_bytes.into_inner(),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        };
+
+        let restored =
+            apply_editor_postprocessed_alpha_to_provider_source(&provider_source, &postprocessed)
+                .expect("postprocessed alpha should restore provider dimensions")
+                .expect("smaller alpha mask should be applied to provider source");
+        let restored_image = image::load_from_memory(restored.bytes.as_slice())
+            .unwrap()
+            .to_rgba8();
+
+        assert_eq!((restored_image.width(), restored_image.height()), (4, 4));
+        assert_eq!(restored_image.get_pixel(1, 1).0, [200, 10, 20, 77]);
+        assert_eq!(restored.mime_type, "image/png");
+        assert_eq!(restored.extension, "png");
+    }
+
     #[test]
     fn publication_material_generation_restores_provider_output_to_workflow_dimensions() {
         let image = image::DynamicImage::new_rgba8(944, 704);
@@ -7923,7 +9062,7 @@ mod tests {
 
         let gpt = normalize_editor_generation_options(Some("gpt-image-2"), Some("2:3"), Some("1K"));
         assert_eq!(gpt.model, GPT_IMAGE_2_MODEL);
-        assert_eq!(gpt.size, "1024x1536");
+        assert_eq!(gpt.size, "688x1024");
         assert_eq!(gpt.aspect_ratio, "2:3");
         assert_eq!(gpt.image_size, "1K");
         assert_eq!(gpt.provider_image_size, "1K");
@@ -7937,7 +9076,7 @@ mod tests {
         let gpt_cover =
             normalize_editor_generation_options(Some("gpt-image-2"), Some("4:3"), Some("1K"));
         assert_eq!(gpt_cover.model, GPT_IMAGE_2_MODEL);
-        assert_eq!(gpt_cover.size, "1536x1024");
+        assert_eq!(gpt_cover.size, "1024x768");
         assert_eq!(gpt_cover.aspect_ratio, "4:3");
 
         let gpt_landscape_2k =
@@ -7947,12 +9086,34 @@ mod tests {
         assert_eq!(gpt_landscape_2k.aspect_ratio, "16:9");
         assert_eq!(gpt_landscape_2k.image_size, "2K");
 
-        let gpt_portrait_2k_fallback =
+        let gpt_portrait_2k =
             normalize_editor_generation_options(Some("gpt-image-2"), Some("9:16"), Some("2K"));
-        assert_eq!(gpt_portrait_2k_fallback.model, GPT_IMAGE_2_MODEL);
-        assert_eq!(gpt_portrait_2k_fallback.size, "1024x1536");
-        assert_eq!(gpt_portrait_2k_fallback.aspect_ratio, "9:16");
-        assert_eq!(gpt_portrait_2k_fallback.image_size, "2K");
+        assert_eq!(gpt_portrait_2k.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(gpt_portrait_2k.size, "1152x2048");
+        assert_eq!(gpt_portrait_2k.aspect_ratio, "9:16");
+        assert_eq!(gpt_portrait_2k.image_size, "2K");
+
+        for (image_size, aspect_ratio, expected_size) in [
+            ("1K", "1:1", "1024x1024"),
+            ("1K", "4:3", "1024x768"),
+            ("1K", "3:2", "1024x688"),
+            ("1K", "2:3", "688x1024"),
+            ("1K", "9:16", "608x1088"),
+            ("1K", "16:9", "1088x608"),
+            ("2K", "1:1", "2048x2048"),
+            ("2K", "4:3", "2048x1536"),
+            ("2K", "3:2", "2048x1376"),
+            ("2K", "2:3", "1376x2048"),
+            ("2K", "9:16", "1152x2048"),
+            ("2K", "16:9", "2048x1152"),
+        ] {
+            let options = normalize_editor_generation_options(
+                Some(GPT_IMAGE_2_MODEL),
+                Some(aspect_ratio),
+                Some(image_size),
+            );
+            assert_eq!(options.size, expected_size);
+        }
 
         let fallback = normalize_editor_generation_options(
             Some("unknown-model"),
@@ -7982,7 +9143,7 @@ mod tests {
         );
         assert_eq!(
             resolve_editor_image_request_size(Some("generate"), Some("720x540"), true, &options),
-            "1536x1024"
+            "1024x768"
         );
     }
 
@@ -8196,8 +9357,8 @@ mod tests {
             source_type: "generated".to_string(),
             prompt: Some("remove background".to_string()),
             actual_prompt: None,
-            model: Some("BiRefNet".to_string()),
-            provider: Some("BiRefNet".to_string()),
+            model: Some("BgFilter complex".to_string()),
+            provider: Some("BgFilter".to_string()),
             task_id: Some("extgen-cutout".to_string()),
             source_resource_id: Some("resource-source".to_string()),
             asset_kind: Some("character".to_string()),
@@ -8508,7 +9669,7 @@ mod tests {
     }
 
     #[test]
-    fn editor_canvas_multi_asset_items_keep_source_and_anchor_processed_result() {
+    fn editor_canvas_character_generation_places_processed_result_and_provider_source() {
         let completion = EditorCanvasGenerationCompletionRequest {
             dialog_id: Some("dialog-character".to_string()),
             title: "角色形象 1".to_string(),
@@ -8533,7 +9694,6 @@ mod tests {
             400,
             600,
         );
-
         let (items, primary_layer_id) =
             build_multi_asset_canvas_layer_items(&completion, Some(&processed), Some(&source));
 
@@ -8594,7 +9754,78 @@ mod tests {
     }
 
     #[test]
-    fn editor_canvas_spritesheet_items_include_source_sheet_and_slices() {
+    fn editor_canvas_postprocess_fallback_only_anchors_provider_source() {
+        let completion = EditorCanvasGenerationCompletionRequest {
+            dialog_id: Some("dialog-character-fallback".to_string()),
+            title: "角色形象 1".to_string(),
+            placeholder: EditorCanvasGenerationPlaceholderPayload {
+                x: 100.0,
+                y: 80.0,
+                width: 200.0,
+                height: 300.0,
+                original_width: 400.0,
+                original_height: 600.0,
+            },
+        };
+        let source = editor_project_resource_for_canvas_test(
+            "resource-character-source",
+            "character",
+            400,
+            600,
+        );
+        let source_layer_id = generated_canvas_layer_id(source.resource_id.as_str());
+        let source_item = build_generated_canvas_layer_item(
+            &completion,
+            &completion.placeholder,
+            &source,
+            source_layer_id.as_str(),
+            0,
+        );
+        let layers = json!([{
+            "itemType": "generation-dialog",
+            "layerId": "generation-dialog:dialog-character-fallback",
+            "resourceId": "generation-dialog:dialog-character-fallback",
+            "dialog": {
+                "id": "dialog-character-fallback",
+                "status": "generating",
+                "placeholder": completion.placeholder.clone()
+            }
+        }]);
+
+        let completed = apply_editor_canvas_generation_multi_items(
+            layers,
+            &completion,
+            vec![source_item],
+            Some(source_layer_id.clone()),
+        )
+        .expect("source-only fallback should complete the generation dialog");
+        let completed_items = completed
+            .layers
+            .as_array()
+            .expect("layers should stay array");
+        let generated_resources = completed_items
+            .iter()
+            .filter(|item| {
+                item.get("resourceId")
+                    .and_then(Value::as_str)
+                    .is_some_and(|resource_id| resource_id.starts_with("resource-character-"))
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(generated_resources.len(), 1);
+        assert_eq!(
+            generated_resources[0]["resourceId"],
+            json!("resource-character-source")
+        );
+        let dialog = completed_items
+            .iter()
+            .find(|item| item["itemType"] == "generation-dialog")
+            .and_then(|item| item.get("dialog"))
+            .expect("generation dialog should remain");
+        assert_eq!(dialog["generatedLayerId"], json!(source_layer_id));
+    }
+
+    #[test]
+    fn editor_canvas_spritesheet_items_include_processed_sheet_provider_source_and_slices() {
         let completion = EditorCanvasGenerationCompletionRequest {
             dialog_id: Some("dialog-ui-assets".to_string()),
             title: "UI素材图集".to_string(),
@@ -8614,7 +9845,7 @@ mod tests {
             512,
         );
         let source = editor_project_resource_for_canvas_test(
-            "resource-ui-source",
+            "resource-ui-sheet-source",
             "icon-spritesheet",
             512,
             512,
@@ -8642,15 +9873,15 @@ mod tests {
             Some("layer-editor-resource-resource-ui-sheet")
         );
         assert_eq!(items[0]["resourceId"], json!("resource-ui-sheet"));
-        assert_eq!(items[1]["resourceId"], json!("resource-ui-source"));
-        assert_eq!(items[1]["assetKind"], json!("icon-spritesheet"));
+        assert_eq!(items[1]["resourceId"], json!("resource-ui-sheet-source"));
+        assert_eq!(items[1]["title"], json!("UI素材图集（原图）"));
         assert_eq!(items[2]["resourceId"], json!("resource-ui-slice"));
         let source_right = items[1]["x"].as_f64().unwrap() + items[1]["width"].as_f64().unwrap();
         assert!(items[2]["x"].as_f64().unwrap() > source_right);
     }
 
     #[test]
-    fn editor_canvas_spritesheet_items_keep_sheet_and_source_when_slices_are_empty() {
+    fn editor_canvas_spritesheet_items_keep_processed_sheet_and_provider_source_without_slices() {
         let completion = EditorCanvasGenerationCompletionRequest {
             dialog_id: Some("dialog-icon-sheet".to_string()),
             title: "图标素材图集".to_string(),
@@ -8670,12 +9901,11 @@ mod tests {
             512,
         );
         let source = editor_project_resource_for_canvas_test(
-            "resource-icon-source",
+            "resource-icon-sheet-source",
             "icon-spritesheet",
             512,
             512,
         );
-
         let (items, primary_layer_id) = build_icon_spritesheet_canvas_layer_items(
             &completion,
             Some(&processed),
@@ -8685,8 +9915,8 @@ mod tests {
 
         assert_eq!(items.len(), 2);
         assert_eq!(items[0]["resourceId"], json!("resource-icon-sheet"));
-        assert_eq!(items[1]["resourceId"], json!("resource-icon-source"));
-        assert_eq!(items[1]["assetKind"], json!("icon-spritesheet"));
+        assert_eq!(items[1]["resourceId"], json!("resource-icon-sheet-source"));
+        assert_eq!(items[1]["title"], json!("图标素材图集（原图）"));
         assert_eq!(
             primary_layer_id.as_deref(),
             Some("layer-editor-resource-resource-icon-sheet")
@@ -8835,13 +10065,23 @@ mod tests {
     }
 
     #[test]
-    fn editor_reference_image_data_url_stays_compatible() {
-        let parsed = parse_editor_reference_image_data_url("data:image/png;base64,AAAA")
-            .expect("legacy data URL reference should still parse");
+    fn editor_reference_inline_media_is_not_an_object_reference() {
+        for inline_source in ["data:image/png;base64,AAAA", "blob:browser-only"] {
+            let error = normalize_editor_reference_object_key(inline_source)
+                .expect_err("inline image should require upload before generation");
+            assert!(error.body_text().contains("objectKey"));
+        }
 
-        assert_eq!(parsed.mime_type, "image/png");
-        assert_eq!(parsed.file_name, "editor-reference.png");
-        assert_eq!(parsed.bytes, vec![0, 0, 0]);
+        let source = include_str!("editor_project.rs");
+        assert_function_contains_in_order(
+            source,
+            "async fn resolve_editor_reference_object_key(",
+            "async fn find_editor_reference_object_key_by_registered_id",
+            &[
+                "ensure_editor_reference_image_source_is_stable",
+                "normalize_editor_reference_object_key",
+            ],
+        );
     }
 
     #[test]
@@ -9024,6 +10264,91 @@ mod tests {
         assert_eq!(infer_editor_reference_image_mime_type(b"not image"), None);
     }
 
+    #[test]
+    fn editor_background_removal_source_requires_supported_content_type_and_matching_magic() {
+        assert_eq!(
+            normalize_editor_background_removal_source_mime_type(Some("IMAGE/PNG; charset=utf-8")),
+            Some("image/png")
+        );
+        assert_eq!(
+            normalize_editor_background_removal_source_mime_type(Some("image/gif")),
+            None
+        );
+        assert_eq!(
+            normalize_editor_background_removal_source_mime_type(Some("application/pdf")),
+            None
+        );
+        assert_eq!(
+            normalize_editor_background_removal_source_mime_type(None),
+            None
+        );
+
+        assert!(
+            validate_editor_background_removal_source_content(
+                "image/png",
+                b"\x89PNG\r\n\x1a\nrest"
+            )
+            .is_ok()
+        );
+        assert_eq!(
+            validate_editor_background_removal_source_content(
+                "image/png",
+                &[0xff, 0xd8, 0xff, 0xe0]
+            )
+            .expect_err("mismatched image content should be rejected")
+            .status_code(),
+            StatusCode::UNSUPPORTED_MEDIA_TYPE
+        );
+        assert_eq!(
+            validate_editor_background_removal_source_content("image/png", b"not image")
+                .expect_err("non-image content should be rejected")
+                .status_code(),
+            StatusCode::UNSUPPORTED_MEDIA_TYPE
+        );
+    }
+
+    #[test]
+    fn editor_character_postprocess_fallback_response_keeps_source_and_warning() {
+        let response = EditorImageGenerationResponse {
+            image_src: "/api/assets/source-character.png".to_string(),
+            object_key: Some("generated/editor/character-source.png".to_string()),
+            asset_object_id: Some("asset-object-character-source".to_string()),
+            width: 1024,
+            height: 1536,
+            source_type: "generated",
+            prompt: "角色形象".to_string(),
+            actual_prompt: Some("角色形象 actual".to_string()),
+            model: GPT_IMAGE_2_MODEL.to_string(),
+            provider: "VectorEngine",
+            task_id: "task-character-source".to_string(),
+            resource: None,
+            asset: None,
+            project: None,
+            warning: Some(editor_postprocess_fallback_warning(
+                "生成任务成功，后处理失败。",
+            )),
+        };
+
+        let payload = serde_json::to_value(response).expect("response should serialize");
+
+        assert_eq!(
+            payload["imageSrc"],
+            json!("/api/assets/source-character.png")
+        );
+        assert_eq!(
+            payload["objectKey"],
+            json!("generated/editor/character-source.png")
+        );
+        assert_eq!(
+            payload["warning"]["code"],
+            json!(EDITOR_GENERATION_POSTPROCESS_WARNING_CODE)
+        );
+        assert_eq!(
+            payload["warning"]["reason"],
+            json!("生成任务成功，后处理失败。")
+        );
+    }
+
     #[tokio::test]
     async fn editor_icon_spritesheet_price_is_resolved_from_generation_config() {
         let state = AppState::new(AppConfig::default()).expect("state should build");
@@ -9065,6 +10390,7 @@ mod tests {
             spritesheet_resource: None,
             spritesheet_asset: None,
             project: None,
+            warning: None,
         };
         let payload = serde_json::to_value(response).expect("response should serialize");
 
@@ -9074,10 +10400,9 @@ mod tests {
             payload["sliceWarning"]["code"],
             json!("insufficient-connected-components")
         );
-        assert!(
-            payload["sliceWarning"]["reason"]
-                .as_str()
-                .is_some_and(|reason| reason.contains("连通域数量不足"))
+        assert_eq!(
+            payload["sliceWarning"]["reason"],
+            json!("图标 spritesheet 连通域数量不足：需要 2 个，实际 1 个。")
         );
     }
 
@@ -9085,7 +10410,7 @@ mod tests {
     async fn editor_ui_design_asset_extraction_price_uses_selected_model_and_size() {
         let state = AppState::new(AppConfig::default()).expect("state should build");
         let request: EditorUiDesignAssetExtractionRequest = serde_json::from_value(json!({
-            "sourceImageSrc": "data:image/png;base64,AAAA",
+            "sourceImageSrc": "/generated-images/editor/ui-design.png",
             "model": "gpt-image-2",
             "screenColor": "#E6D8FF",
             "segModel": "anime-seg",
@@ -9167,20 +10492,35 @@ mod tests {
     fn editor_image_edit_request_omits_price_mud_points() {
         let request: EditorImageEditRequest = serde_json::from_value(json!({
             "prompt": "修改图片",
-            "sourceImageSrc": "data:image/png;base64,AAAA",
+            "sourceImageSrc": "/generated-images/editor/source.png",
             "size": "2048x1152",
-            "model": "gpt-image-2",
-            "referenceImageSrcs": ["data:image/png;base64,BBBB"],
+            "model": "gemini-3.1-flash-image-preview",
+            "aspectRatio": "16:9",
+            "imageSize": "2K",
+            "referenceImageSrcs": ["/generated-images/editor/style.png"],
             "targetLayerId": "layer-source"
         }))
         .expect("image edit request should deserialize without price");
 
         assert_eq!(request.prompt, "修改图片");
         assert_eq!(request.size.as_deref(), Some("2048x1152"));
-        assert_eq!(request.model.as_deref(), Some("gpt-image-2"));
+        assert_eq!(
+            request.model.as_deref(),
+            Some("gemini-3.1-flash-image-preview")
+        );
+        assert_eq!(request.aspect_ratio.as_deref(), Some("16:9"));
+        assert_eq!(request.image_size.as_deref(), Some("2K"));
+        let legacy_options = normalize_editor_image_edit_generation_options(
+            request.model.as_deref(),
+            None,
+            None,
+            Some("2048x1365"),
+        );
+        assert_eq!(legacy_options.aspect_ratio, "3:2");
+        assert_eq!(legacy_options.image_size, "2K");
         assert_eq!(
             request.reference_image_srcs,
-            Some(vec!["data:image/png;base64,BBBB".to_string()])
+            Some(vec!["/generated-images/editor/style.png".to_string()])
         );
         assert_eq!(request.target_layer_id.as_deref(), Some("layer-source"));
     }
@@ -9244,6 +10584,68 @@ mod tests {
         );
     }
 
+    #[test]
+    fn editor_inline_media_sources_are_rejected_before_queueing() {
+        let source = include_str!("editor_project.rs");
+        for (start, end) in [
+            (
+                "pub async fn generate_editor_image(",
+                "pub(crate) async fn generate_editor_image_for_owner",
+            ),
+            (
+                "pub async fn edit_editor_image(",
+                "pub(crate) async fn edit_editor_image_for_owner",
+            ),
+            (
+                "pub async fn remove_editor_image_background(",
+                "pub(crate) async fn remove_editor_image_background_for_owner",
+            ),
+            (
+                "pub async fn generate_editor_icon_spritesheet(",
+                "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
+            ),
+            (
+                "pub async fn extract_editor_ui_design_assets(",
+                "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
+            ),
+        ] {
+            assert_function_contains_in_order(
+                source,
+                start,
+                end,
+                &[
+                    "ensure_editor_reference_image_source",
+                    "enqueue_editor_generation_job",
+                ],
+            );
+        }
+
+        for inline_source in [
+            "data:image/png;base64,AAAA",
+            "  DATA:image/png;base64,AAAA",
+            "blob:browser-only",
+        ] {
+            let error = ensure_editor_reference_image_source_is_stable(
+                inline_source,
+                "editor-test",
+                "sourceImageSrc",
+                "测试图片",
+            )
+            .expect_err("inline media must require upload before generation");
+            assert_eq!(error.status_code(), StatusCode::BAD_REQUEST);
+            assert!(error.body_text().contains("先上传 OSS"));
+        }
+        assert!(
+            ensure_editor_reference_image_source_is_stable(
+                "/generated-images/editor/reference.png",
+                "editor-test",
+                "sourceImageSrc",
+                "测试图片",
+            )
+            .is_ok()
+        );
+    }
+
     #[test]
     fn editor_image_edit_can_complete_by_replacing_target_layer() {
         let source = include_str!("editor_project.rs");
@@ -9260,10 +10662,10 @@ mod tests {
     }
 
     #[test]
-    fn editor_icon_spritesheet_request_accepts_extra_references() {
+    fn editor_icon_spritesheet_request_accepts_stable_extra_references() {
         let request: EditorIconSpritesheetGenerationRequest = serde_json::from_value(json!({
-            "referenceImageSrc": "data:image/png;base64,spec",
-            "referenceImageSrcs": ["data:image/png;base64,style"],
+            "referenceImageSrc": "/generated-images/editor/spec.png",
+            "referenceImageSrcs": ["/generated-images/editor/style.png"],
             "iconDescriptions": ["返回按钮"],
             "screenColor": "#7FB3FF",
             "segModel": "anime-seg",
@@ -9273,7 +10675,7 @@ mod tests {
 
         assert_eq!(
             request.reference_image_srcs,
-            Some(vec!["data:image/png;base64,style".to_string()])
+            Some(vec!["/generated-images/editor/style.png".to_string()])
         );
         assert_eq!(request.screen_color.as_deref(), Some("#7FB3FF"));
         assert_eq!(request.seg_model.as_deref(), Some("anime-seg"));
@@ -9383,6 +10785,112 @@ mod tests {
         assert!(parse_editor_bgfilter_seg_model(Some("u2net")).is_err());
     }
 
+    #[test]
+    fn editor_bgfilter_cross_check_form_value_matches_service_contract() {
+        assert_eq!(editor_bgfilter_cross_check_form_value(true), "on");
+        assert_eq!(editor_bgfilter_cross_check_form_value(false), "off");
+    }
+
+    #[test]
+    fn editor_bgfilter_background_mode_matches_service_contract() {
+        assert_eq!(EDITOR_BGFILTER_BACKGROUND_MODE_FLAT, "flat");
+        assert_eq!(EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX, "complex");
+    }
+
+    #[tokio::test]
+    async fn editor_generated_bgfilter_request_timeout_overrides_shared_client_default() {
+        let response_png = encode_test_png(3, 2);
+        let (base_url, request_receiver, server) =
+            spawn_bgfilter_png_mock_with_delay(response_png.clone(), Duration::from_millis(100));
+        let state = AppState::new(AppConfig {
+            editor_bgfilter_base_url: base_url,
+            editor_bgfilter_request_timeout_ms: 20,
+            oss_bucket: Some("genarrative-assets".to_string()),
+            oss_endpoint: Some("oss-cn-beijing.aliyuncs.com".to_string()),
+            oss_access_key_id: Some("test-ak".to_string()),
+            oss_access_key_secret: Some("test-sk".to_string()),
+            ..AppConfig::default()
+        })
+        .expect("state should build");
+
+        let removed = request_editor_generated_screen_background_with_bgfilter(
+            &state,
+            "generated-character-drafts/editor/source.png",
+            parse_editor_screen_background_color(Some("#CFEFFF"))
+                .expect("screen color should parse"),
+            EDITOR_BGFILTER_DEFAULT_SEG_MODEL,
+            EDITOR_BGFILTER_CROSS_CHECK_ENABLED,
+            2_000,
+        )
+        .await
+        .expect("request timeout override should outlive the shared client default");
+        request_receiver
+            .recv_timeout(Duration::from_secs(1))
+            .expect("mock server should capture request");
+        server.join().expect("mock server should stop cleanly");
+
+        assert_eq!(removed.bytes, response_png);
+        assert_eq!(removed.mime_type, "image/png");
+        assert_eq!(removed.extension, "png");
+    }
+
+    #[tokio::test]
+    async fn editor_manual_background_removal_sends_complex_bgfilter_http_contract() {
+        let response_png = encode_test_png(3, 2);
+        let (base_url, request_receiver, server) = spawn_bgfilter_png_mock(response_png.clone());
+        let state = AppState::new(AppConfig {
+            editor_bgfilter_base_url: base_url,
+            editor_bgfilter_token: Some("manual-complex-token".to_string()),
+            editor_bgfilter_request_timeout_ms: 5_000,
+            oss_bucket: Some("genarrative-assets".to_string()),
+            oss_endpoint: Some("oss-cn-beijing.aliyuncs.com".to_string()),
+            oss_access_key_id: Some("test-ak".to_string()),
+            oss_access_key_secret: Some("test-sk".to_string()),
+            ..AppConfig::default()
+        })
+        .expect("state should build");
+
+        let removed = request_editor_background_removal_image_with_retry(
+            &state,
+            "generated-character-drafts/editor/manual-source.png",
+        )
+        .await
+        .expect("BgFilter PNG response should decode");
+        let request = request_receiver
+            .recv_timeout(Duration::from_secs(1))
+            .expect("mock server should capture request");
+        server.join().expect("mock server should stop cleanly");
+        let request_text = String::from_utf8_lossy(request.as_slice());
+        let lowercase_request = request_text.to_ascii_lowercase();
+
+        assert!(request_text.starts_with("POST /remove-background HTTP/1.1\r\n"));
+        assert!(
+            lowercase_request.contains("\r\nx-genarrative-image-token: manual-complex-token\r\n")
+        );
+        assert!(request_text.contains("name=\"image_url\""));
+        assert!(request_text.contains("genarrative-assets.oss-cn-beijing.aliyuncs.com"));
+        assert!(lowercase_request.contains("x-oss-signature-version"));
+        assert!(!request_text.contains("name=\"file\""));
+        assert!(request_text.contains("name=\"background_mode\"\r\n\r\ncomplex\r\n"));
+        assert!(request_text.contains("name=\"seg_model\"\r\n\r\nbirefnet\r\n"));
+        assert!(request_text.contains("name=\"cross_check\"\r\n\r\noff\r\n"));
+        assert!(!request_text.contains("name=\"screen_color\""));
+
+        assert_eq!((removed.width, removed.height), (3, 2));
+        assert_eq!(removed.image.mime_type, "image/png");
+        assert_eq!(removed.image.extension, "png");
+        assert_eq!(removed.image.bytes, response_png);
+
+        let provider_error = decode_editor_background_removal_image(b"not an image")
+            .expect_err("invalid BgFilter response should fail decoding");
+        assert_eq!(
+            provider_error
+                .details()
+                .and_then(|details| details.get("provider")),
+            Some(&json!("bgfilter"))
+        );
+    }
+
     #[test]
     fn editor_bgfilter_circuit_opens_after_consecutive_failures_and_resets_on_success() {
         reset_editor_bgfilter_circuit_for_tests();
@@ -9456,8 +10964,11 @@ mod tests {
             "fn normalize_editor_image_generation_size",
             &[
                 "persist_editor_provider_source_image",
+                "caller.report_processing_phase(state).await?",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_ENABLED",
                 "persist_editor_provider_source_resource",
+                "build_multi_asset_canvas_layer_items",
                 "if is_character_generation",
             ],
         );
@@ -9469,6 +10980,7 @@ mod tests {
                 "persist_editor_provider_source_image",
                 "persist_editor_provider_source_resource",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_ENABLED",
             ],
         );
         assert_function_contains(
@@ -9477,7 +10989,9 @@ mod tests {
             "pub async fn extract_editor_ui_design_assets",
             &[
                 "persist_editor_provider_source_image",
+                "caller.report_processing_phase(state).await?",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
                 "persist_editor_provider_source_resource",
                 "slice_generated_icon_spritesheet_by_connected_components",
                 "persist_editor_spritesheet_slices",
@@ -9490,7 +11004,20 @@ mod tests {
             &[
                 "persist_editor_provider_source_image",
                 "persist_editor_provider_source_resource",
+                "caller.report_processing_phase(state).await?",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
+            ],
+        );
+        assert_function_contains_in_order(
+            source,
+            "pub(crate) async fn remove_editor_image_background_for_owner",
+            "struct EditorBackgroundRemovalImage",
+            &[
+                "caller.report_processing_phase(state).await?",
+                "resolve_editor_reference_object_key_for_owner",
+                "validate_editor_background_removal_source",
+                "request_editor_background_removal_image_with_retry",
             ],
         );
         assert_function_contains(
@@ -9500,6 +11027,7 @@ mod tests {
             &[
                 "persist_editor_provider_source_image",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
                 "persist_editor_provider_source_resource",
                 "slice_generated_icon_spritesheet_all_by_connected_components",
             ],
@@ -9512,18 +11040,31 @@ mod tests {
                 "persist_editor_provider_source_image",
                 "persist_editor_provider_source_resource",
                 "remove_editor_generated_screen_background_with_bgfilter",
+                "EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
+            ],
+        );
+        assert_function_contains(
+            source,
+            "pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter(",
+            "pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
+            &[
+                "state.config.editor_bgfilter_request_timeout_ms",
+                "remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
             ],
         );
         assert_function_contains_in_order(
             source,
-            "async fn remove_editor_generated_screen_background_with_bgfilter",
+            "async fn remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
             "async fn fallback_editor_screen_background_removal",
             &[
                 // 熔断打开分支必须先委派统一兜底链（阿里云→本地），不能直接退化本地扣色；
                 // BgFilter 调用失败分支同样走该兜底链。
                 "editor_bgfilter_circuit_open_remaining",
                 "fallback_editor_screen_background_removal",
+                "EDITOR_BGFILTER_RETRY_COUNT + 1",
                 "request_editor_generated_screen_background_with_bgfilter",
+                "will_retry",
+                "record_matting_external_api_failure",
                 "fallback_editor_screen_background_removal",
             ],
         );
@@ -9532,29 +11073,73 @@ mod tests {
             "async fn fallback_editor_screen_background_removal",
             "async fn request_editor_generated_screen_background_with_bgfilter",
             &[
-                "segment_image_with_aliyun_matting",
+                "segment_image_url_with_aliyun_matting",
+                "download_editor_persisted_image_object",
                 "remove_editor_generated_green_screen_background",
+                "drop(source_image)",
             ],
         );
         assert_function_contains(
             source,
             "async fn request_editor_generated_screen_background_with_bgfilter",
-            "async fn request_editor_background_removal_image",
+            "async fn request_editor_background_removal_image(",
             &[
                 "editor_bgfilter_endpoint",
-                "editor_bgfilter_request_timeout_ms.max(1)",
+                "sign_editor_private_object_read_url",
+                "EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS",
+                "\"image_url\"",
+                "request_timeout_ms.max(1)",
+                "state.editor_bgfilter_http_client()",
+                ".timeout(Duration::from_millis(timeout_ms))",
                 "\"screen_color\"",
                 "\"seg_model\"",
                 "seg_model.to_string()",
+                "\"background_mode\"",
+                "EDITOR_BGFILTER_BACKGROUND_MODE_FLAT",
+                "\"cross_check\"",
+                "editor_bgfilter_cross_check_form_value(cross_check)",
+            ],
+        );
+        assert_function_not_contains(
+            source,
+            "async fn request_editor_generated_screen_background_with_bgfilter",
+            "async fn request_editor_background_removal_image(",
+            &[
+                ".part(\"file\"",
+                "reqwest::multipart::Part::bytes",
+                "reqwest::Client::builder",
             ],
         );
         assert_function_contains(
             source,
-            "async fn request_editor_background_removal_image",
-            "fn editor_background_removal_endpoint",
+            "async fn request_editor_background_removal_image(",
+            "fn editor_bgfilter_endpoint",
             &[
-                "editor_background_removal_endpoint",
-                "\"provider\": \"birefnet\"",
+                "editor_bgfilter_endpoint",
+                "sign_editor_private_object_read_url",
+                "EDITOR_MATTING_SOURCE_URL_EXPIRE_SECONDS",
+                "\"image_url\"",
+                "editor_bgfilter_request_timeout_ms.max(1)",
+                "state.editor_bgfilter_http_client()",
+                "editor_bgfilter_token",
+                "\"background_mode\"",
+                "EDITOR_BGFILTER_BACKGROUND_MODE_COMPLEX",
+                "\"seg_model\"",
+                "EDITOR_BGFILTER_DEFAULT_SEG_MODEL",
+                "\"cross_check\"",
+                "EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
+                "\"provider\": \"bgfilter\"",
+            ],
+        );
+        assert_function_not_contains(
+            source,
+            "async fn request_editor_background_removal_image(",
+            "fn editor_bgfilter_endpoint",
+            &[
+                "\"screen_color\"",
+                ".part(\"file\"",
+                "reqwest::multipart::Part::bytes",
+                "reqwest::Client::builder",
             ],
         );
         assert_function_not_contains(
@@ -9619,6 +11204,370 @@ mod tests {
         );
     }
 
+    #[test]
+    fn editor_bgfilter_retries_once_before_fallback() {
+        let source = include_str!("editor_project.rs");
+        assert!(source.contains("const EDITOR_BGFILTER_RETRY_COUNT: usize = 1;"));
+        assert_function_contains_in_order(
+            source,
+            "async fn remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
+            "async fn fallback_editor_screen_background_removal",
+            &[
+                "let max_attempts = EDITOR_BGFILTER_RETRY_COUNT + 1",
+                "for attempt in 1..=max_attempts",
+                "request_editor_generated_screen_background_with_bgfilter",
+                "let will_retry = attempt < max_attempts",
+                "if will_retry",
+                "continue",
+                "final_error = Some(error)",
+                "fallback_editor_screen_background_removal",
+            ],
+        );
+    }
+
+    #[test]
+    fn editor_processing_phase_retries_transport_once_but_not_fencing() {
+        let source = include_str!("editor_project.rs");
+        assert!(source.contains("const EDITOR_GENERATION_PHASE_REPORT_RETRY_COUNT: usize = 1;"));
+        assert_function_contains_in_order(
+            source,
+            "pub(crate) async fn report_processing(&self, state: &AppState)",
+            "fn map_editor_generation_phase_update_error",
+            &[
+                "let max_attempts = EDITOR_GENERATION_PHASE_REPORT_RETRY_COUNT + 1",
+                "for attempt in 1..=max_attempts",
+                ".update_external_generation_job_phase(input.clone())",
+                "should_retry_editor_generation_phase_update",
+                "if will_retry",
+                "continue",
+                "map_editor_generation_phase_update_error(error)",
+            ],
+        );
+        assert_function_contains(
+            source,
+            "fn map_editor_generation_phase_update_error",
+            "#[derive(Debug, Serialize)]",
+            &["error.is_lease_fencing_rejected()", "StatusCode::CONFLICT"],
+        );
+    }
+
+    #[test]
+    fn editor_processing_phase_retry_policy_stops_after_one_transport_retry() {
+        let max_attempts = EDITOR_GENERATION_PHASE_REPORT_RETRY_COUNT + 1;
+        let transport_errors = [
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Build(
+                "initial websocket connect failed".to_string(),
+            )),
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::ConnectDropped),
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Timeout(
+                spacetime_client::SpacetimeClientStage::ProcedureResult,
+            )),
+        ];
+        for error in &transport_errors {
+            assert!(should_retry_editor_generation_phase_update(
+                error,
+                1,
+                max_attempts
+            ));
+            assert!(!should_retry_editor_generation_phase_update(
+                error,
+                max_attempts,
+                max_attempts
+            ));
+        }
+
+        let lease = ExternalGenerationJobPhaseUpdateError::LeaseFencingRejected(
+            "lease token 不匹配".to_string(),
+        );
+        assert!(!should_retry_editor_generation_phase_update(
+            &lease,
+            1,
+            max_attempts
+        ));
+
+        let rejected = ExternalGenerationJobPhaseUpdateError::Rejected("phase 非法".to_string());
+        assert!(!should_retry_editor_generation_phase_update(
+            &rejected,
+            1,
+            max_attempts
+        ));
+
+        for error in [
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Procedure(
+                "procedure rejected".to_string(),
+            )),
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Runtime(
+                "runtime invariant failed".to_string(),
+            )),
+        ] {
+            assert!(!should_retry_editor_generation_phase_update(
+                &error,
+                1,
+                max_attempts
+            ));
+        }
+    }
+
+    #[test]
+    fn editor_static_postprocess_failure_completes_canvas_with_source_only() {
+        let source = include_str!("editor_project.rs");
+        for (start, end) in [
+            (
+                "pub(crate) async fn generate_editor_image_for_owner",
+                "fn normalize_editor_image_generation_size",
+            ),
+            (
+                "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
+                "pub async fn extract_editor_ui_design_assets",
+            ),
+            (
+                "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
+                "pub(crate) fn editor_project_payload_from_record",
+            ),
+        ] {
+            assert_function_contains_in_order(
+                source,
+                start,
+                end,
+                &[
+                    "persist_editor_provider_source_resource",
+                    "caller.report_processing_phase(state).await?",
+                    "remove_editor_generated_screen_background_with_bgfilter",
+                    "Err(error)",
+                    "complete_editor_canvas_generation",
+                    "source_record.resource.as_ref()",
+                    "warning: Some(editor_postprocess_fallback_warning",
+                ],
+            );
+
+            let start_index = source
+                .find(start)
+                .unwrap_or_else(|| panic!("missing function start marker: {start}"));
+            let function_tail = &source[start_index..];
+            let end_index = function_tail
+                .find(end)
+                .unwrap_or_else(|| panic!("missing function end marker: {end}"));
+            let body = &function_tail[..end_index];
+            let fallback_start = body
+                .find("let removal = match removal {")
+                .unwrap_or_else(|| panic!("{start} should match only the postprocess result"));
+            let success_marker = if start.contains("generate_editor_image_for_owner") {
+                "image = restored_removal_image;"
+            } else {
+                "let removal_provider = removal.provider;"
+            };
+            let fallback_end = body[fallback_start..]
+                .find(success_marker)
+                .map(|offset| fallback_start + offset)
+                .unwrap_or_else(|| {
+                    panic!("{start} should resume its processed-image success path")
+                });
+            let fallback = &body[fallback_start..fallback_end];
+            assert!(fallback.contains("return Ok(json_success_body"));
+            for forbidden in [
+                "persist_editor_generated_image(",
+                "persist_editor_generated_asset(",
+                "slice_generated_icon_spritesheet",
+                "persist_editor_spritesheet_slices",
+            ] {
+                assert!(
+                    !fallback.contains(forbidden),
+                    "{start} fallback must not absorb later failure scope: {forbidden}"
+                );
+            }
+            if start.contains("spritesheet") || start.contains("ui_design") {
+                let success_tail = &body[fallback_end..];
+                assert!(success_tail.contains("persist_editor_generated_image("));
+                assert!(success_tail.contains("persist_editor_generated_asset("));
+                assert!(success_tail.contains("persist_editor_spritesheet_slices"));
+            }
+        }
+    }
+
+    #[test]
+    fn editor_character_postprocess_fallback_is_inline_and_does_not_swallow_other_failures() {
+        let source = include_str!("editor_project.rs");
+        let start = source
+            .find("pub(crate) async fn generate_editor_image_for_owner")
+            .expect("character generation function should exist");
+        let function_tail = &source[start..];
+        let end = function_tail
+            .find("fn normalize_editor_image_generation_size")
+            .expect("character generation function end marker should exist");
+        let body = &function_tail[..end];
+
+        let phase = body
+            .find("caller.report_processing_phase(state).await?")
+            .expect("phase report should remain fallible");
+        let removal = body
+            .find("let removal = remove_editor_generated_screen_background_with_bgfilter")
+            .expect("transparent background postprocess should exist");
+        let fallback_start = body
+            .find("let removal = match removal {")
+            .expect("only the postprocess result should be matched");
+        let fallback_end = body[fallback_start..]
+            .find("image = restored_removal_image;")
+            .map(|offset| fallback_start + offset)
+            .expect("processed-image success path should follow the fallback match");
+        let fallback = &body[fallback_start..fallback_end];
+
+        assert!(
+            phase < removal,
+            "phase errors must fail before fallback is considered"
+        );
+        for snippet in [
+            "Err(error)",
+            "complete_editor_canvas_generation",
+            "source_record.resource.as_ref()",
+            "return Ok(json_success_body",
+            "warning: Some(editor_postprocess_fallback_warning",
+        ] {
+            assert!(
+                fallback.contains(snippet),
+                "character postprocess fallback should contain {snippet}"
+            );
+        }
+        for forbidden in [
+            "persist_editor_generated_image(",
+            "persist_editor_generated_asset(",
+            "slice_generated_icon_spritesheet",
+            "build_multi_asset_canvas_layer_items",
+        ] {
+            assert!(
+                !fallback.contains(forbidden),
+                "character postprocess fallback must not absorb later failure scope: {forbidden}"
+            );
+        }
+
+        let success_tail = &body[fallback_end..];
+        assert!(success_tail.contains("persist_editor_generated_image("));
+        assert!(success_tail.contains("persist_editor_generated_asset("));
+        assert!(success_tail.contains(".await?;"));
+    }
+
+    #[test]
+    fn editor_manual_background_removal_retries_once() {
+        let source = include_str!("editor_project.rs");
+        assert_function_contains_in_order(
+            source,
+            "async fn request_editor_background_removal_image_with_retry",
+            "async fn request_editor_background_removal_image(",
+            &[
+                "let max_attempts = EDITOR_BGFILTER_RETRY_COUNT + 1",
+                "for attempt in 1..=max_attempts",
+                "request_editor_background_removal_image(state, source_object_key)",
+                "let will_retry = attempt < max_attempts",
+                "if will_retry",
+                "continue",
+                "final_error = Some(error)",
+            ],
+        );
+    }
+
+    #[test]
+    fn editor_matting_releases_source_buffers_at_oss_boundaries() {
+        let source = include_str!("editor_project.rs");
+        for (start, end) in [
+            (
+                "pub(crate) async fn generate_editor_image_for_owner",
+                "fn normalize_editor_image_generation_size",
+            ),
+            (
+                "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
+                "pub async fn extract_editor_ui_design_assets",
+            ),
+            (
+                "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
+                "pub(crate) fn editor_project_payload_from_record",
+            ),
+        ] {
+            assert_function_contains_in_order(
+                source,
+                start,
+                end,
+                &[
+                    "persist_editor_provider_source_image",
+                    "remove_editor_generated_screen_background_with_bgfilter",
+                    "apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original",
+                    "persist_editor_generated_image",
+                ],
+            );
+        }
+        assert_function_contains(
+            source,
+            "async fn persist_editor_provider_source_image",
+            "async fn persist_editor_provider_source_resource",
+            &["persist_editor_generated_image_owned"],
+        );
+        assert_function_contains_in_order(
+            source,
+            "async fn apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original",
+            "fn restore_editor_generated_image_output_dimensions",
+            &[
+                "into_dimensions",
+                "return (postprocessed, None)",
+                "download_editor_persisted_image_object",
+                "apply_editor_postprocessed_alpha_to_provider_source",
+            ],
+        );
+        for (start, end) in [
+            (
+                "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
+                "pub async fn extract_editor_ui_design_assets",
+            ),
+            (
+                "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
+                "pub(crate) fn editor_project_payload_from_record",
+            ),
+        ] {
+            assert_function_contains(
+                source,
+                start,
+                end,
+                &["bytes: image.bytes.clone()", "slice_source"],
+            );
+            assert_function_not_contains(
+                source,
+                start,
+                end,
+                &[
+                    "download_editor_persisted_image_object",
+                    "drop(slice_source)",
+                ],
+            );
+        }
+        assert_function_not_contains(
+            source,
+            "pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter(",
+            "pub(crate) async fn remove_editor_generated_screen_background_with_bgfilter_with_request_timeout",
+            &["fallback_image", "DownloadedOpenAiImage"],
+        );
+        assert_function_contains(
+            source,
+            "async fn persist_editor_generated_image_owned",
+            "async fn persist_editor_generated_image_data",
+            &["bytes: image.bytes"],
+        );
+        assert_function_not_contains(
+            source,
+            "async fn persist_editor_generated_image_owned",
+            "async fn persist_editor_generated_image_data",
+            &["image.bytes.clone()"],
+        );
+        assert_function_contains(
+            source,
+            "async fn read_editor_reference_image_object",
+            "async fn download_editor_persisted_image_object",
+            &["response.chunk().await", "bytes.extend_from_slice"],
+        );
+        assert_function_not_contains(
+            source,
+            "async fn read_editor_reference_image_object",
+            "async fn download_editor_persisted_image_object",
+            &["response.bytes().await", "bytes.to_vec()"],
+        );
+    }
+
     #[test]
     fn editor_paid_image_postprocess_keeps_provider_outputs_recoverable() {
         let source = include_str!("editor_project.rs");
diff --git a/server-rs/crates/api-server/src/external_api_audit.rs b/server-rs/crates/api-server/src/external_api_audit.rs
index e62d3a0fb..0039f7b0a 100644
--- a/server-rs/crates/api-server/src/external_api_audit.rs
+++ b/server-rs/crates/api-server/src/external_api_audit.rs
@@ -159,6 +159,7 @@ pub(crate) async fn record_matting_external_api_failure(
     failure_stage: &'static str,
     status_code: Option<u16>,
     timeout: bool,
+    transport: bool,
     latency_ms: Option<u64>,
     error_message: String,
     raw_excerpt: Option<String>,
@@ -170,6 +171,7 @@ pub(crate) async fn record_matting_external_api_failure(
         failure_stage,
         status_code,
         timeout,
+        transport,
         latency_ms,
         error_message,
         raw_excerpt,
@@ -178,31 +180,41 @@ pub(crate) async fn record_matting_external_api_failure(
     record_external_api_failure(state, draft).await;
 }
 
+/// 构建抠图失败审计 draft。`transport` 必须由调用方从错误结构化字段读取，
+/// 不能用 `status_code.is_none()` 反推——本地处理失败同样没有上游 HTTP 状态。
 #[allow(clippy::too_many_arguments)]
-fn build_matting_external_api_failure_draft(
+pub(crate) fn build_matting_external_api_failure_draft(
     provider: &'static str,
     endpoint: String,
     operation: &'static str,
     failure_stage: &'static str,
     status_code: Option<u16>,
     timeout: bool,
+    transport: bool,
     latency_ms: Option<u64>,
     error_message: String,
     raw_excerpt: Option<String>,
     context: &ExternalApiAuditContext,
 ) -> ExternalApiFailureDraft {
-    // status_code=None ⟺ statusClass=transport（见 status_class）：DNS / 连接重置 / 读体中断 / 超时
-    // 这类传输层失败没有上游 HTTP 状态。它们必须与 "transport failures actionable" 语义一致，
-    // 记为 retryable=true，否则 statusClass=transport 却 retryable=false 会误导告警 / 重试分析。
-    let has_transport_error = status_code.is_none();
+    // 传输层：无上游 HTTP 状态 + timeout/transport 标记 → statusClass=transport、retryable=true。
+    // 本地处理：无上游 HTTP 状态且非 transport → statusClass=local、retryable=false。
+    // 不得把「status_code=None」一律当成 transport，否则 LocalProcessing 会污染可重试 5xx 分析。
+    let is_transport_failure = timeout || transport;
+    let resolved_status_class = if is_transport_failure && status_code.is_none() {
+        "transport"
+    } else if status_code.is_none() {
+        "local"
+    } else {
+        status_class(status_code)
+    };
     ExternalApiFailureDraft::new(provider, endpoint, operation, failure_stage, error_message)
         .with_status_code(status_code)
-        .with_optional_status_class(Some(status_class(status_code)))
+        .with_optional_status_class(Some(resolved_status_class))
         .with_timeout(timeout)
         .with_retryable(is_retryable_external_api_failure(
             status_code,
             timeout,
-            has_transport_error,
+            is_transport_failure,
         ))
         .with_latency_ms(latency_ms)
         .with_raw_excerpt(raw_excerpt)
@@ -210,21 +222,31 @@ fn build_matting_external_api_failure_draft(
 }
 
 pub(crate) fn matting_failure_audit_status_code(error: &AppError) -> Option<u16> {
-    error
+    // 真实上游 HTTP 状态优先；本地处理 / 传输层都没有可写的上游 status。
+    if let Some(status) = error
         .details()
         .and_then(|details| details.get("upstreamStatus"))
         .and_then(Value::as_u64)
         .and_then(|value| u16::try_from(value).ok())
-        .or_else(|| {
-            if matting_failure_audit_is_transport(error) {
-                None
-            } else {
-                Some(error.status_code().as_u16())
-            }
-        })
+    {
+        return Some(status);
+    }
+    if matting_failure_audit_is_local_processing(error) || matting_failure_audit_is_transport(error)
+    {
+        return None;
+    }
+    Some(error.status_code().as_u16())
 }
 
-fn matting_failure_audit_is_transport(error: &AppError) -> bool {
+pub(crate) fn matting_failure_audit_is_local_processing(error: &AppError) -> bool {
+    error
+        .details()
+        .and_then(|details| details.get("localProcessing"))
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+}
+
+pub(crate) fn matting_failure_audit_is_transport(error: &AppError) -> bool {
     matting_failure_audit_timeout(error)
         || error
             .details()
@@ -256,6 +278,30 @@ pub(crate) fn matting_failure_external_call_attempted(error: &AppError) -> bool
         .unwrap_or(true)
 }
 
+pub(crate) fn matting_failure_audit_failure_stage(
+    error: &AppError,
+    fallback: &'static str,
+) -> &'static str {
+    let stage = error
+        .details()
+        .and_then(|details| details.get("failureStage"))
+        .and_then(Value::as_str);
+    match stage {
+        Some("preflight") => "preflight",
+        Some("source_download") => "source_download",
+        Some("source_decode") => "source_decode",
+        Some("source_validate") => "source_validate",
+        Some("source_normalize") => "source_normalize",
+        Some("temp_upload") => "temp_upload",
+        Some("aliyun_segment") => "aliyun_segment",
+        Some("result_download") => "result_download",
+        Some("result_decode") => "result_decode",
+        Some("result_validate") => "result_validate",
+        Some("result_encode") => "result_encode",
+        _ => fallback,
+    }
+}
+
 pub(crate) fn matting_failure_audit_raw_excerpt(error: &AppError) -> Option<String> {
     error
         .details()
@@ -575,7 +621,7 @@ mod tests {
 
     #[test]
     fn matting_failure_draft_marks_non_timeout_transport_retryable() {
-        // status_code=None、timeout=false 的非超时 transport 失败（DNS / 连接重置 / 读体中断）：
+        // status_code=None、timeout=false、transport=true 的非超时传输故障：
         // statusClass 必须是 transport 且 retryable=true，否则与 "transport failures actionable" 冲突。
         let draft = build_matting_external_api_failure_draft(
             "bgfilter",
@@ -584,6 +630,7 @@ mod tests {
             "bgfilter_segment",
             None,
             false,
+            true,
             Some(67),
             "请求 BgFilter 服务失败：dns error".to_string(),
             Some("dns error".to_string()),
@@ -599,6 +646,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn matting_failure_draft_marks_local_processing_non_retryable() {
+        // 本地处理失败没有上游 HTTP 状态，也不是 transport；不得记成可重试 5xx/transport。
+        let draft = build_matting_external_api_failure_draft(
+            "aliyun-matting",
+            "imageseg.example".to_string(),
+            "editor-screen-background-removal",
+            "source_decode",
+            None,
+            false,
+            false,
+            Some(3),
+            "解析待抠图图片失败：invalid png".to_string(),
+            Some("invalid png".to_string()),
+            &ExternalApiAuditContext::default(),
+        );
+
+        assert_eq!(draft.status_code, None);
+        assert_eq!(draft.status_class, Some("local"));
+        assert!(!draft.timeout);
+        assert!(!draft.retryable);
+    }
+
     #[test]
     fn matting_failure_draft_keeps_client_error_non_retryable() {
         // 真实上游 4xx（非 429 / 408）不是传输故障，仍应 retryable=false，不能被误判为可重试。
@@ -609,6 +679,7 @@ mod tests {
             "aliyun_segment",
             Some(400),
             false,
+            false,
             Some(12),
             "通用抠图接口返回失败（HTTP 400，Code=InvalidImage）：bad image".to_string(),
             None,
diff --git a/server-rs/crates/api-server/src/external_editor_api.rs b/server-rs/crates/api-server/src/external_editor_api.rs
index b8789b1dc..dc9935d49 100644
--- a/server-rs/crates/api-server/src/external_editor_api.rs
+++ b/server-rs/crates/api-server/src/external_editor_api.rs
@@ -684,6 +684,7 @@ pub async fn generate_external_editor_character_animation(
         request_context,
         principal.owner_user_id().to_string(),
         payload,
+        None,
     )
     .await
 }
@@ -750,6 +751,7 @@ fn editor_generation_caller(
         owner_user_id: principal.owner_user_id().to_string(),
         audit_subject_user_id: Some(principal.owner_user_id().to_string()),
         audit_project_id: normalize_optional_string(project_id),
+        phase_reporter: None,
     }
 }
 
@@ -882,6 +884,20 @@ mod tests {
                 ["sliceWarning"]["anyOf"][0]["$ref"],
             "#/components/schemas/EditorIconSpritesheetSliceWarning"
         );
+        assert_eq!(
+            parsed["components"]["schemas"]["EditorImageGenerationResponse"]["properties"]["warning"]
+                ["anyOf"][0]["$ref"],
+            "#/components/schemas/EditorGenerationWarning"
+        );
+        assert_eq!(
+            parsed["components"]["schemas"]["EditorIconSpritesheetGenerationResponse"]["properties"]
+                ["warning"]["anyOf"][0]["$ref"],
+            "#/components/schemas/EditorGenerationWarning"
+        );
+        assert_eq!(
+            parsed["components"]["schemas"]["EditorGenerationWarning"]["required"],
+            json!(["code", "reason"])
+        );
         assert!(
             parsed["paths"]
                 .get("/api/external/v1/editor/ui-designs/assets/extractions")
diff --git a/server-rs/crates/api-server/src/external_generation.rs b/server-rs/crates/api-server/src/external_generation.rs
index e766bb669..2b83d7296 100644
--- a/server-rs/crates/api-server/src/external_generation.rs
+++ b/server-rs/crates/api-server/src/external_generation.rs
@@ -172,6 +172,9 @@ fn map_external_generation_job_status(
             100,
             None,
         ),
+        "running" if job.phase.as_deref() == Some("processing") => {
+            (ExternalGenerationJobStatus::Running, "正在处理。", 70, None)
+        }
         "running" => (ExternalGenerationJobStatus::Running, "正在生成。", 35, None),
         "failed" => (
             ExternalGenerationJobStatus::Failed,
@@ -314,6 +317,7 @@ mod tests {
             refund_ledger_id: None,
             notification_acknowledged_at: None,
             notification_acknowledged_at_micros: None,
+            phase: None,
             warning_message: Some("连通域数量不足".to_string()),
         };
         let status = map_external_generation_job_status_detail(summary.clone());
@@ -326,4 +330,66 @@ mod tests {
         assert_eq!(task.warning.as_deref(), Some("连通域数量不足"));
         assert!(task.error.is_none());
     }
+
+    #[test]
+    fn maps_running_processing_phase_from_backend_projection() {
+        let status = map_external_generation_job_status(ExternalGenerationJobSummaryRecord {
+            job_id: "task-processing".to_string(),
+            job_kind: "editor_character_animation_generation".to_string(),
+            owner_user_id: "user-1".to_string(),
+            source_module: "editor-canvas".to_string(),
+            source_entity_id: "project-1".to_string(),
+            request_label: "角色动作生成".to_string(),
+            request_prompt: None,
+            status: "running".to_string(),
+            last_error_message: None,
+            created_at: "2026-07-13T08:00:00Z".to_string(),
+            started_at: Some("2026-07-13T08:00:01Z".to_string()),
+            completed_at: None,
+            updated_at: "2026-07-13T08:00:10Z".to_string(),
+            updated_at_micros: 1_000,
+            price_mud_points: 4,
+            refund_ledger_id: None,
+            notification_acknowledged_at: None,
+            notification_acknowledged_at_micros: None,
+            phase: Some("processing".to_string()),
+            warning_message: None,
+        });
+
+        assert_eq!(status.status, ExternalGenerationJobStatus::Running);
+        assert_eq!(status.phase_detail, "正在处理。");
+        assert_eq!(status.progress, 70);
+    }
+
+    #[test]
+    fn maps_legacy_running_job_without_phase_as_generating() {
+        let mut job = ExternalGenerationJobSummaryRecord {
+            job_id: "task-legacy".to_string(),
+            job_kind: "editor_image_generation".to_string(),
+            owner_user_id: "user-1".to_string(),
+            source_module: "editor-canvas".to_string(),
+            source_entity_id: "project-1".to_string(),
+            request_label: "图片生成".to_string(),
+            request_prompt: None,
+            status: "running".to_string(),
+            last_error_message: None,
+            created_at: "2026-07-13T08:00:00Z".to_string(),
+            started_at: Some("2026-07-13T08:00:01Z".to_string()),
+            completed_at: None,
+            updated_at: "2026-07-13T08:00:10Z".to_string(),
+            updated_at_micros: 1_000,
+            price_mud_points: 4,
+            refund_ledger_id: None,
+            notification_acknowledged_at: None,
+            notification_acknowledged_at_micros: None,
+            phase: None,
+            warning_message: None,
+        };
+
+        let legacy = map_external_generation_job_status(job.clone());
+        assert_eq!(legacy.phase_detail, "正在生成。");
+        job.phase = Some("generating".to_string());
+        let generating = map_external_generation_job_status(job);
+        assert_eq!(generating.phase_detail, "正在生成。");
+    }
 }
diff --git a/server-rs/crates/api-server/src/external_generation_worker.rs b/server-rs/crates/api-server/src/external_generation_worker.rs
index 48327dfa7..5567c9c5a 100644
--- a/server-rs/crates/api-server/src/external_generation_worker.rs
+++ b/server-rs/crates/api-server/src/external_generation_worker.rs
@@ -9,12 +9,13 @@ use spacetime_client::{
     ExternalGenerationJobRenewLeaseRecordInput, ExternalGenerationQueueWakeSubscription,
 };
 use tokio::{
-    task::JoinSet,
-    time::{Instant, sleep},
+    task::{JoinHandle, JoinSet},
+    time::sleep,
 };
 use tracing::{error, info, warn};
 
 const MAX_EDITOR_GENERATION_WARNING_CHARS: usize = 2_048;
+const EDITOR_GENERATION_SLICE_WARNING_PREFIX: &str = "图集已生成，但自动拆分未完成：";
 const EDITOR_GENERATION_WARNING_REDACTED_MESSAGE: &str =
     "自动拆分未完成（告警详情含内联媒体引用，已省略）";
 
@@ -32,7 +33,7 @@ use crate::{
         EDITOR_UI_DESIGN_ASSET_EXTRACTION_JOB_KIND, EDITOR_VIDEO_GENERATION_JOB_KIND,
     },
     editor_project::{
-        EditorBackgroundRemovalRequest, EditorGenerationCaller,
+        EditorBackgroundRemovalRequest, EditorGenerationCaller, EditorGenerationPhaseReporter,
         EditorIconSpritesheetGenerationRequest, EditorImageEditRequest,
         EditorImageGenerationRequest, EditorUiDesignAssetExtractionRequest,
         edit_editor_image_for_owner, extract_editor_ui_design_assets_for_owner,
@@ -324,38 +325,155 @@ async fn process_external_generation_job(
             return Err(message);
         }
     };
-    let work = with_external_generation_billing_attempt_context(
+    // work 单独 spawn：已发出的 SpacetimeDB procedure 无法通过 drop 客户端 future 撤销，
+    // 若超时时 drop 在途写回再抢先写失败态，可能出现“业务写回已提交、任务却被标记失败
+    // 并退款”的不一致。因此超时/续租失败时不取消 work，也不在客户端写失败态，交由服务端
+    // lease fencing 仲裁：写回在租约有效期内到达则任务照常完成，否则被拒绝；租约到期后
+    // 任务被重新认领，attempt 耗尽时由认领事务原子地标记失败并结算退款。
+    let mut work_handle = tokio::spawn(with_external_generation_billing_attempt_context(
         job.job_id.clone(),
         billing_claim_attempt,
         billing_price_mud_points,
         process_external_generation_job_once(state.clone(), worker_id.clone(), job.clone()),
-    );
+    ));
+    let heartbeat =
+        maintain_external_generation_job_lease(&state, &worker_id, &job, lease, heartbeat_interval);
+    match await_external_generation_job_execution(
+        join_external_generation_work(&mut work_handle),
+        heartbeat,
+        job_timeout,
+    )
+    .await
+    {
+        ExternalGenerationJobExecutionOutcome::Finished(result) => result,
+        ExternalGenerationJobExecutionOutcome::TimedOut => {
+            let message = external_generation_worker_timeout_message(&job, job_timeout);
+            warn!(
+                job_id = %job.job_id,
+                job_kind = %job.job_kind,
+                timeout_seconds = job_timeout.as_secs(),
+                "external generation worker 任务超过执行预算，停止续租并释放 worker 槽位，在途执行交由租约仲裁"
+            );
+            detach_external_generation_work_until_lease_expiry(
+                work_handle,
+                &job,
+                lease,
+                "任务超过执行预算",
+            );
+            Err(message)
+        }
+        ExternalGenerationJobExecutionOutcome::LeaseRenewalFailed(error) => {
+            detach_external_generation_work_until_lease_expiry(
+                work_handle,
+                &job,
+                lease,
+                "任务租约续期失败",
+            );
+            Err(error)
+        }
+    }
+}
+
+async fn join_external_generation_work(
+    work_handle: &mut JoinHandle<Result<(), String>>,
+) -> Result<(), String> {
+    match work_handle.await {
+        Ok(result) => result,
+        Err(join_error) => Err(format!("external generation work 任务 panic：{join_error}")),
+    }
+}
+
+/// 停止等待 work 后不能直接取消它：在途 procedure 可能已在服务端提交。让它继续跑完当前
+/// 尝试，写回由 lease fencing 裁决是否生效。等到租约必然过期（2 倍租约时长，此后一切
+/// 围栏写回都会被拒绝）仍未结束的任务才安全取消，取消触发的计费补偿退款按 attempt
+/// 账本幂等，与队列侧耗尽结算不会重复。
+fn detach_external_generation_work_until_lease_expiry(
+    mut work_handle: JoinHandle<Result<(), String>>,
+    job: &ExternalGenerationJobRecord,
+    lease: Duration,
+    reason: &'static str,
+) {
+    let job_id = job.job_id.clone();
+    let job_kind = job.job_kind.clone();
+    let grace = lease.saturating_mul(2);
+    tokio::spawn(async move {
+        match tokio::time::timeout(grace, &mut work_handle).await {
+            Ok(Ok(Ok(()))) => info!(
+                job_id = %job_id,
+                job_kind = %job_kind,
+                reason,
+                "external generation worker 脱管任务已在租约仲裁窗口内完成写回"
+            ),
+            Ok(Ok(Err(error))) => info!(
+                job_id = %job_id,
+                job_kind = %job_kind,
+                reason,
+                error = %error,
+                "external generation worker 脱管任务在租约仲裁窗口内以失败结束"
+            ),
+            Ok(Err(join_error)) => error!(
+                job_id = %job_id,
+                job_kind = %job_kind,
+                reason,
+                error = %join_error,
+                "external generation worker 脱管任务 panic"
+            ),
+            Err(_) => {
+                work_handle.abort();
+                warn!(
+                    job_id = %job_id,
+                    job_kind = %job_kind,
+                    reason,
+                    grace_ms = grace.as_millis() as u64,
+                    "external generation worker 脱管任务超过租约仲裁窗口仍未结束，已取消；其后续写回将被 lease fencing 拒绝"
+                );
+            }
+        }
+    });
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum ExternalGenerationJobExecutionOutcome {
+    Finished(Result<(), String>),
+    TimedOut,
+    LeaseRenewalFailed(String),
+}
+
+async fn await_external_generation_job_execution<W, H>(
+    work: W,
+    heartbeat: H,
+    job_timeout: Duration,
+) -> ExternalGenerationJobExecutionOutcome
+where
+    W: Future<Output = Result<(), String>>,
+    H: Future<Output = Result<(), String>>,
+{
     tokio::pin!(work);
-    let heartbeat = sleep(heartbeat_interval);
     tokio::pin!(heartbeat);
     let job_deadline = sleep(job_timeout);
     tokio::pin!(job_deadline);
 
+    tokio::select! {
+        biased;
+        result = &mut work => ExternalGenerationJobExecutionOutcome::Finished(result),
+        _ = &mut job_deadline => ExternalGenerationJobExecutionOutcome::TimedOut,
+        result = &mut heartbeat => match result {
+            Ok(()) => unreachable!("external generation heartbeat monitor should not finish"),
+            Err(error) => ExternalGenerationJobExecutionOutcome::LeaseRenewalFailed(error),
+        },
+    }
+}
+
+async fn maintain_external_generation_job_lease(
+    state: &AppState,
+    worker_id: &str,
+    job: &ExternalGenerationJobRecord,
+    lease: Duration,
+    heartbeat_interval: Duration,
+) -> Result<(), String> {
     loop {
-        tokio::select! {
-            biased;
-            result = &mut work => return result,
-            _ = &mut job_deadline => {
-                let message = external_generation_worker_timeout_message(&job, job_timeout);
-                warn!(
-                    job_id = %job.job_id,
-                    job_kind = %job.job_kind,
-                    timeout_seconds = job_timeout.as_secs(),
-                    "external generation worker 任务超过执行预算，停止当前尝试并释放 worker 槽位"
-                );
-                fail_job(&state, &worker_id, &job, message.clone()).await?;
-                return Err(message);
-            }
-            _ = &mut heartbeat => {
-                renew_job_lease(&state, &worker_id, &job, lease).await?;
-                heartbeat.as_mut().reset(Instant::now() + heartbeat_interval);
-            }
-        }
+        sleep(heartbeat_interval).await;
+        renew_job_lease(state, worker_id, job, lease).await?;
     }
 }
 
@@ -670,12 +788,20 @@ async fn process_external_generation_job_once(
             match generate_editor_image_for_owner(
                 &state,
                 &request_context,
-                editor_generation_worker_caller(&job),
+                editor_generation_worker_caller(&worker_id, &job)?,
                 payload,
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(response) => {
+                    complete_editor_generation_job_with_response(
+                        &state,
+                        &worker_id,
+                        &job,
+                        &response.0,
+                    )
+                    .await
+                }
                 Err(error) => {
                     let message = error.body_text();
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -698,12 +824,14 @@ async fn process_external_generation_job_once(
             match edit_editor_image_for_owner(
                 &state,
                 &request_context,
-                editor_generation_worker_caller(&job),
+                editor_generation_worker_caller(&worker_id, &job)?,
                 payload,
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(error) => {
                     let message = error.body_text();
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -727,12 +855,14 @@ async fn process_external_generation_job_once(
             match remove_editor_image_background_for_owner(
                 &state,
                 &request_context,
-                editor_generation_worker_caller(&job),
+                editor_generation_worker_caller(&worker_id, &job)?,
                 payload,
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(error) => {
                     let message = error.body_text();
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -755,7 +885,7 @@ async fn process_external_generation_job_once(
             match generate_editor_icon_spritesheet_for_owner(
                 &state,
                 &request_context,
-                editor_generation_worker_caller(&job),
+                editor_generation_worker_caller(&worker_id, &job)?,
                 payload,
             )
             .await
@@ -791,7 +921,7 @@ async fn process_external_generation_job_once(
             match extract_editor_ui_design_assets_for_owner(
                 &state,
                 &request_context,
-                editor_generation_worker_caller(&job),
+                editor_generation_worker_caller(&worker_id, &job)?,
                 payload,
             )
             .await
@@ -830,10 +960,13 @@ async fn process_external_generation_job_once(
                 request_context,
                 job.owner_user_id.clone(),
                 Ok(Json(payload)),
+                Some(editor_generation_phase_reporter(&worker_id, &job)?),
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -862,7 +995,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -891,7 +1026,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -920,7 +1057,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -1013,30 +1152,40 @@ fn worker_request_context(job: &ExternalGenerationJobRecord) -> RequestContext {
     )
 }
 
-fn editor_generation_worker_caller(job: &ExternalGenerationJobRecord) -> EditorGenerationCaller {
-    EditorGenerationCaller {
+fn editor_generation_worker_caller(
+    worker_id: &str,
+    job: &ExternalGenerationJobRecord,
+) -> Result<EditorGenerationCaller, String> {
+    Ok(EditorGenerationCaller {
         owner_user_id: job.owner_user_id.clone(),
         audit_subject_user_id: Some(job.owner_user_id.clone()),
         audit_project_id: Some(job.source_entity_id.clone()),
-    }
+        phase_reporter: Some(editor_generation_phase_reporter(worker_id, job)?),
+    })
+}
+
+fn editor_generation_phase_reporter(
+    worker_id: &str,
+    job: &ExternalGenerationJobRecord,
+) -> Result<EditorGenerationPhaseReporter, String> {
+    Ok(EditorGenerationPhaseReporter::new(
+        job.job_id.clone(),
+        worker_id.to_string(),
+        require_job_lease_token(job)?,
+    ))
 }
 
 async fn complete_editor_generation_job(
     state: &AppState,
     worker_id: &str,
     job: &ExternalGenerationJobRecord,
+    response: Value,
 ) -> Result<(), String> {
     complete_job(
         state,
         worker_id,
         job,
-        Some(
-            json!({
-                "sourceModule": job.source_module.clone(),
-                "sourceEntityId": job.source_entity_id.clone(),
-            })
-            .to_string(),
-        ),
+        Some(editor_generation_result_payload_json(job, &response)),
     )
     .await
 }
@@ -1064,7 +1213,18 @@ fn editor_generation_result_payload_json(
         "sourceModule": job.source_module.clone(),
         "sourceEntityId": job.source_entity_id.clone(),
     });
-    if let Some(warning) = extract_editor_generation_slice_warning(response)
+    if is_editor_agent_generation_job(job)
+        && let Some(object) = payload.as_object_mut()
+    {
+        // The Agent needs this compact result to restore its tool-call card. Other jobs keep
+        // master's metadata-only completion payload to avoid turning the queue into an asset API.
+        object.insert(
+            // TODO extract const
+            "editor-agent-tool-call-result".to_string(),
+            compact_editor_generation_result(response.clone()),
+        );
+    }
+    if let Some(warning) = extract_editor_generation_warning(response)
         && let Some(object) = payload.as_object_mut()
     {
         object.insert("warning".to_string(), warning);
@@ -1072,15 +1232,73 @@ fn editor_generation_result_payload_json(
     payload.to_string()
 }
 
-fn extract_editor_generation_slice_warning(response: &Value) -> Option<Value> {
+fn is_editor_agent_generation_job(job: &ExternalGenerationJobRecord) -> bool {
+    serde_json::from_str::<Value>(job.request_payload_json.as_str())
+        .ok()
+        .is_some_and(|payload| {
+            payload
+                .pointer("/generationInputs/source")
+                .and_then(Value::as_str)
+                // TODO extract const
+                .is_some_and(|source| source.trim() == "editor-agent")
+        })
+}
+
+fn compact_editor_generation_result(mut result: Value) -> Value {
+    let Some(object) = result.as_object_mut() else {
+        return result;
+    };
+    object.remove("project");
+    object.remove("asset");
+    object.remove("spritesheetAsset");
+    for field in ["resource", "spritesheetResource"] {
+        let Some(resource) = object.get_mut(field).and_then(Value::as_object_mut) else {
+            continue;
+        };
+        resource
+            .retain(|key, _| matches!(key.as_str(), "resourceId" | "objectKey" | "assetObjectId"));
+    }
+    if let Some(icon_image_srcs) = object
+        .get_mut("iconImageSrcs")
+        .and_then(Value::as_array_mut)
+    {
+        for icon in icon_image_srcs {
+            let Some(icon) = icon.as_object_mut() else {
+                continue;
+            };
+            if let Some(resource) = icon.get_mut("resource").and_then(Value::as_object_mut) {
+                resource.retain(|key, _| {
+                    matches!(key.as_str(), "resourceId" | "objectKey" | "assetObjectId")
+                });
+            }
+            icon.retain(|key, _| {
+                matches!(
+                    key.as_str(),
+                    "name" | "imageSrc" | "width" | "height" | "resource"
+                )
+            });
+        }
+    }
+    result
+}
+
+fn extract_editor_generation_warning(response: &Value) -> Option<Value> {
     let data = response.get("data").unwrap_or(response);
-    let warning = data.get("sliceWarning")?;
+    let (warning, is_slice_warning) = match data.get("warning") {
+        Some(warning) => (warning, false),
+        None => (data.get("sliceWarning")?, true),
+    };
     let code = warning.get("code")?.as_str()?.trim();
     let reason = warning.get("reason")?.as_str()?.trim();
     if code.is_empty() || reason.is_empty() {
         return None;
     }
-    let reason = normalize_editor_generation_warning_reason(reason);
+    let reason = if is_slice_warning {
+        format!("{EDITOR_GENERATION_SLICE_WARNING_PREFIX}{reason}")
+    } else {
+        reason.to_string()
+    };
+    let reason = normalize_editor_generation_warning_reason(reason.as_str());
     Some(json!({
         "code": code,
         "reason": reason,
@@ -1262,6 +1480,16 @@ mod tests {
         assert_eq!(guard.lease_token.as_deref(), Some("lease-1"));
     }
 
+    #[test]
+    fn editor_worker_caller_carries_phase_reporter() {
+        let job = external_generation_job_record_fixture(Some("lease-1"));
+
+        let caller = editor_generation_worker_caller("worker-a", &job)
+            .expect("worker caller should include claimed job phase reporter");
+
+        assert!(caller.phase_reporter.is_some());
+    }
+
     #[test]
     fn worker_write_guard_requires_claimed_job_lease_token() {
         let job = external_generation_job_record_fixture(None);
@@ -1330,6 +1558,118 @@ mod tests {
         assert_eq!(message, "VECTOR_ENGINE_API_KEY 未配置");
     }
 
+    #[tokio::test]
+    async fn worker_heartbeat_wait_does_not_stop_work_progress() {
+        let connection = std::sync::Arc::new(tokio::sync::Semaphore::new(1));
+        let work_started = std::sync::Arc::new(tokio::sync::Notify::new());
+        let work_connection = connection.clone();
+        let work_started_signal = work_started.clone();
+        let work = async move {
+            let permit = work_connection
+                .acquire_owned()
+                .await
+                .expect("work should acquire the only connection");
+            work_started_signal.notify_one();
+            tokio::time::sleep(Duration::from_millis(25)).await;
+            drop(permit);
+            Ok(())
+        };
+        let heartbeat_connection = connection.clone();
+        let heartbeat = async move {
+            work_started.notified().await;
+            let _permit = heartbeat_connection
+                .acquire_owned()
+                .await
+                .expect("heartbeat should acquire after work releases the connection");
+            std::future::pending::<Result<(), String>>().await
+        };
+
+        let outcome =
+            await_external_generation_job_execution(work, heartbeat, Duration::from_secs(1)).await;
+
+        assert_eq!(
+            outcome,
+            ExternalGenerationJobExecutionOutcome::Finished(Ok(()))
+        );
+    }
+
+    #[tokio::test]
+    async fn worker_deadline_drops_local_work_future_before_returning() {
+        let connection = std::sync::Arc::new(tokio::sync::Semaphore::new(1));
+        let work_connection = connection.clone();
+        let work = async move {
+            let _permit = work_connection
+                .acquire_owned()
+                .await
+                .expect("work should acquire the only connection");
+            std::future::pending::<Result<(), String>>().await
+        };
+        let heartbeat = std::future::pending::<Result<(), String>>();
+
+        let outcome =
+            await_external_generation_job_execution(work, heartbeat, Duration::from_millis(25))
+                .await;
+
+        assert_eq!(outcome, ExternalGenerationJobExecutionOutcome::TimedOut);
+        assert!(
+            connection.try_acquire().is_ok(),
+            "deadline 返回前应先 drop 传入的 work future 并释放其持有的资源"
+        );
+    }
+
+    #[tokio::test]
+    async fn worker_detached_work_keeps_running_after_deadline() {
+        let finished = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let finished_flag = finished.clone();
+        let work_handle = tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+            finished_flag.store(true, std::sync::atomic::Ordering::SeqCst);
+            Ok(())
+        });
+        let job = external_generation_job_record_fixture(Some("lease-1"));
+
+        detach_external_generation_work_until_lease_expiry(
+            work_handle,
+            &job,
+            Duration::from_millis(200),
+            "任务超过执行预算",
+        );
+
+        tokio::time::sleep(Duration::from_millis(100)).await;
+        assert!(
+            finished.load(std::sync::atomic::Ordering::SeqCst),
+            "超时后在途 work 应继续执行完成，而不是被取消"
+        );
+    }
+
+    #[tokio::test]
+    async fn worker_detached_work_is_aborted_after_lease_arbitration_window() {
+        let connection = std::sync::Arc::new(tokio::sync::Semaphore::new(1));
+        let work_connection = connection.clone();
+        let work_handle = tokio::spawn(async move {
+            let _permit = work_connection
+                .acquire_owned()
+                .await
+                .expect("work should acquire the only connection");
+            std::future::pending::<Result<(), String>>().await
+        });
+        let job = external_generation_job_record_fixture(Some("lease-1"));
+
+        detach_external_generation_work_until_lease_expiry(
+            work_handle,
+            &job,
+            Duration::from_millis(10),
+            "任务超过执行预算",
+        );
+
+        let reacquired =
+            tokio::time::timeout(Duration::from_secs(2), connection.acquire_owned()).await;
+        assert!(
+            reacquired.is_ok(),
+            "超过租约仲裁窗口后应取消仍未结束的 work 并释放其持有的资源"
+        );
+    }
+
     #[test]
     fn editor_generation_result_payload_keeps_only_lightweight_slice_warning() {
         let job = external_generation_job_record_fixture(Some("lease-1"));
@@ -1352,11 +1692,200 @@ mod tests {
             payload["warning"],
             json!({
                 "code": "insufficient-connected-components",
-                "reason": "连通域数量不足"
+                "reason": "图集已生成，但自动拆分未完成：连通域数量不足"
             })
         );
         assert!(payload.get("spritesheetImageSrc").is_none());
         assert!(payload.get("iconImageSrcs").is_none());
+        assert!(payload.get("editor-agent-tool-call-result").is_none());
+    }
+
+    #[test]
+    fn editor_agent_result_payload_keeps_compact_response() {
+        let mut job = external_generation_job_record_fixture(Some("lease-1"));
+        job.request_payload_json = json!({
+            "generationInputs": { "source": "editor-agent" },
+        })
+        .to_string();
+        let response = json!({
+            "imageSrc": "/api/assets/object/generated.png",
+            "objectKey": "users/user-1/generated.png",
+            "assetObjectId": "asset-object-1",
+            "width": 1024,
+            "height": 1024,
+            "sourceType": "generated",
+            "prompt": "castle",
+            "actualPrompt": null,
+            "model": "gpt-image-2",
+            "provider": "VectorEngine",
+            "taskId": "provider-task-1",
+            "resource": {
+                "resourceId": "resource-1",
+                "objectKey": "users/user-1/generated.png",
+                "assetObjectId": "asset-object-1",
+                "imageSrc": "data:image/png;base64,SHOULD_NOT_PERSIST",
+            },
+            "asset": { "assetId": "asset-1" },
+            "project": { "projectId": "project-1" },
+        });
+
+        let payload: Value =
+            serde_json::from_str(&editor_generation_result_payload_json(&job, &response))
+                .expect("worker result should be valid JSON");
+
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["imageSrc"],
+            json!("/api/assets/object/generated.png")
+        );
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["resource"],
+            json!({
+                "resourceId": "resource-1",
+                "objectKey": "users/user-1/generated.png",
+                "assetObjectId": "asset-object-1",
+            })
+        );
+        assert!(
+            payload["editor-agent-tool-call-result"]
+                .get("asset")
+                .is_none()
+        );
+        assert!(
+            payload["editor-agent-tool-call-result"]
+                .get("project")
+                .is_none()
+        );
+        assert!(!payload.to_string().contains("data:image"));
+    }
+
+    #[test]
+    fn editor_agent_spritesheet_result_keeps_all_persisted_slices() {
+        let mut job = external_generation_job_record_fixture(Some("lease-1"));
+        job.request_payload_json = json!({
+            "generationInputs": { "source": "editor-agent" },
+        })
+        .to_string();
+        let response = json!({
+            "spritesheetImageSrc": "/api/assets/object/sheet.png",
+            "spritesheetWidth": 512,
+            "spritesheetHeight": 512,
+            "taskId": "provider-task-1",
+            "spritesheetResource": {
+                "resourceId": "sheet-resource",
+                "objectKey": "users/user-1/sheet.png",
+                "assetObjectId": "sheet-object",
+            },
+            "iconImageSrcs": [
+                {
+                    "name": "backpack",
+                    "imageSrc": "/api/assets/object/backpack.png",
+                    "width": 64,
+                    "height": 64,
+                    "resource": {
+                        "resourceId": "icon-resource-1",
+                        "objectKey": "users/user-1/backpack.png",
+                        "assetObjectId": "icon-object-1",
+                        "imageSrc": "data:image/png;base64,SHOULD_NOT_PERSIST",
+                    },
+                    "asset": { "assetId": "icon-asset-1" },
+                },
+                {
+                    "name": "map",
+                    "imageSrc": "/api/assets/object/map.png",
+                    "width": 64,
+                    "height": 64,
+                    "resource": {
+                        "resourceId": "icon-resource-2",
+                        "objectKey": "users/user-1/map.png",
+                        "assetObjectId": "icon-object-2",
+                    },
+                },
+            ],
+        });
+
+        let payload: Value =
+            serde_json::from_str(&editor_generation_result_payload_json(&job, &response))
+                .expect("worker result should be valid JSON");
+
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"]
+                .as_array()
+                .map(Vec::len),
+            Some(2)
+        );
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"][0]["resource"],
+            json!({
+                "resourceId": "icon-resource-1",
+                "objectKey": "users/user-1/backpack.png",
+                "assetObjectId": "icon-object-1",
+            })
+        );
+        assert!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"][0]
+                .get("asset")
+                .is_none()
+        );
+        assert!(!payload.to_string().contains("data:image"));
+    }
+
+    #[test]
+    fn editor_generation_result_payload_prefers_common_postprocess_warning() {
+        let job = external_generation_job_record_fixture(Some("lease-1"));
+        let response = json!({
+            "data": {
+                "imageSrc": "data:image/png;base64,SHOULD_NOT_PERSIST",
+                "warning": {
+                    "code": "postprocess-failed-source-preserved",
+                    "reason": "生成任务成功，后处理失败。"
+                },
+                "sliceWarning": {
+                    "code": "insufficient-connected-components",
+                    "reason": "不应覆盖通用后处理告警"
+                }
+            }
+        });
+
+        let payload: Value =
+            serde_json::from_str(&editor_generation_result_payload_json(&job, &response))
+                .expect("worker 结果应是合法 JSON");
+
+        assert_eq!(
+            payload["warning"],
+            json!({
+                "code": "postprocess-failed-source-preserved",
+                "reason": "生成任务成功，后处理失败。"
+            })
+        );
+        assert!(payload.get("imageSrc").is_none());
+    }
+
+    #[test]
+    fn editor_image_job_completion_keeps_inline_response_warning() {
+        let source = include_str!("external_generation_worker.rs");
+        let start = source
+            .find("EDITOR_IMAGE_GENERATION_JOB_KIND => {")
+            .expect("editor image worker branch should exist");
+        let branch_tail = &source[start..];
+        let end = branch_tail
+            .find("EDITOR_IMAGE_EDIT_JOB_KIND => {")
+            .expect("editor image worker branch end marker should exist");
+        let branch = &branch_tail[..end];
+
+        for snippet in [
+            "Ok(response)",
+            "complete_editor_generation_job_with_response",
+            "&response.0",
+        ] {
+            assert!(
+                branch.contains(snippet),
+                "editor image completion should preserve response warning via {snippet}"
+            );
+        }
+        assert!(
+            !branch.contains("Ok(_) => complete_editor_generation_job"),
+            "editor image completion must not discard the inline fallback warning"
+        );
     }
 
     #[test]
@@ -1448,6 +1977,7 @@ mod tests {
             refund_ledger_id: None,
             notification_acknowledged_at: None,
             notification_acknowledged_at_micros: None,
+            phase: Some("generating".to_string()),
         }
     }
 }
diff --git a/server-rs/crates/api-server/src/modules/editor_project.rs b/server-rs/crates/api-server/src/modules/editor_project.rs
index 3842c5c53..547443534 100644
--- a/server-rs/crates/api-server/src/modules/editor_project.rs
+++ b/server-rs/crates/api-server/src/modules/editor_project.rs
@@ -7,10 +7,11 @@ use axum::{
 
 use crate::{
     auth::require_bearer_auth,
+    editor_agent::api::editor_agent_message,
     editor_agent::{
+        cancel_editor_agent_tool_call, confirm_editor_agent_tool_call,
         create_editor_agent_conversation, delete_editor_agent_conversation,
         get_editor_agent_conversation, list_editor_agent_conversations,
-        stream_editor_agent_message,
     },
     editor_project::{
         create_editor_asset, create_editor_asset_folder, create_editor_project,
@@ -27,7 +28,6 @@ use crate::{
     state::AppState,
 };
 
-const EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
 const EDITOR_AGENT_MESSAGE_BODY_LIMIT_BYTES: usize = 2 * 1024 * 1024;
 
 pub fn router(state: AppState) -> Router<AppState> {
@@ -99,14 +99,28 @@ pub fn router(state: AppState) -> Router<AppState> {
                 )),
         )
         .route(
-            "/api/editor/agent-conversations/{conversation_id}/messages/stream",
-            post(stream_editor_agent_message)
+            "/api/editor/agent-conversations/{conversation_id}/messages",
+            post(editor_agent_message)
                 .layer(DefaultBodyLimit::max(EDITOR_AGENT_MESSAGE_BODY_LIMIT_BYTES))
                 .route_layer(middleware::from_fn_with_state(
                     state.clone(),
                     require_bearer_auth,
                 )),
         )
+        .route(
+            "/api/editor/agent-conversations/{conversation_id}/messages/{message_id}/confirm",
+            post(confirm_editor_agent_tool_call).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/agent-conversations/{conversation_id}/messages/{message_id}/cancel",
+            post(cancel_editor_agent_tool_call).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/editor/project-resources/{resource_id}/showcase",
             patch(update_editor_project_resource_showcase).route_layer(
@@ -168,49 +182,31 @@ pub fn router(state: AppState) -> Router<AppState> {
         )
         .route(
             "/api/editor/images/generations",
-            post(generate_editor_image)
-                .layer(DefaultBodyLimit::max(
-                    // 中文注释：图片画布生图仍兼容参考图 Data URL 入参，宣发素材提交前会压缩，后端保留有限兜底。
-                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(generate_editor_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/images/edits",
-            post(edit_editor_image)
-                .layer(DefaultBodyLimit::max(
-                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(edit_editor_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/images/background-removals",
-            post(remove_editor_image_background)
-                .layer(DefaultBodyLimit::max(
-                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(remove_editor_image_background).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/icon-spritesheets/generations",
-            post(generate_editor_icon_spritesheet)
-                // 中文注释：图标规范参考图会以 Data URL 提交，需避免默认 2MB body limit 在 handler 前拦截。
-                .layer(DefaultBodyLimit::max(
-                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(generate_editor_icon_spritesheet).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/icon-spritesheets/slices",
@@ -221,14 +217,9 @@ pub fn router(state: AppState) -> Router<AppState> {
         )
         .route(
             "/api/editor/ui-designs/assets/extractions",
-            post(extract_editor_ui_design_assets)
-                // 中文注释：UI 设计图提取素材复用图片 Data URL 入参，需兼容较大的画板生成图。
-                .layer(DefaultBodyLimit::max(
-                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(extract_editor_ui_design_assets).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
 }
diff --git a/server-rs/crates/api-server/src/modules/external_api.rs b/server-rs/crates/api-server/src/modules/external_api.rs
index 3841ffb25..497ade677 100644
--- a/server-rs/crates/api-server/src/modules/external_api.rs
+++ b/server-rs/crates/api-server/src/modules/external_api.rs
@@ -1,7 +1,5 @@
 use axum::{
-    Router,
-    extract::DefaultBodyLimit,
-    middleware,
+    Router, middleware,
     routing::{get, patch, post},
 };
 
@@ -28,9 +26,6 @@ use crate::{
     state::AppState,
 };
 
-const EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
-const EXTERNAL_EDITOR_VIDEO_BODY_LIMIT_BYTES: usize = 64 * 1024 * 1024;
-
 pub fn router(state: AppState) -> Router<AppState> {
     Router::new()
         .route("/api/external/v1/openapi.json", get(openapi_json))
@@ -141,69 +136,42 @@ pub fn router(state: AppState) -> Router<AppState> {
         )
         .route(
             "/api/external/v1/editor/images/generations",
-            post(generate_external_editor_image)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(generate_external_editor_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
         )
         .route(
             "/api/external/v1/editor/images/edits",
-            post(edit_external_editor_image)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(edit_external_editor_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
         )
         .route(
             "/api/external/v1/editor/icon-spritesheets/generations",
-            post(generate_external_editor_icon_spritesheet)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(generate_external_editor_icon_spritesheet).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_external_api_key),
+            ),
         )
         .route(
             "/api/external/v1/editor/ui-designs/assets/extractions",
-            post(extract_external_editor_ui_design_assets)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(extract_external_editor_ui_design_assets).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_external_api_key),
+            ),
         )
         .route(
             "/api/external/v1/editor/character-animations/generations",
-            post(generate_external_editor_character_animation)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(generate_external_editor_character_animation).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_external_api_key),
+            ),
         )
         .route(
             "/api/external/v1/editor/videos/generations",
-            post(generate_external_editor_video)
-                .layer(DefaultBodyLimit::max(
-                    EXTERNAL_EDITOR_VIDEO_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_external_api_key,
-                )),
+            post(generate_external_editor_video).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
         )
         .route(
             "/api/external/v1/editor/audios/sound-effects/generations",
diff --git a/server-rs/crates/api-server/src/modules/play_flow.rs b/server-rs/crates/api-server/src/modules/play_flow.rs
index cb05b06a3..371bb24c2 100644
--- a/server-rs/crates/api-server/src/modules/play_flow.rs
+++ b/server-rs/crates/api-server/src/modules/play_flow.rs
@@ -52,8 +52,6 @@ use crate::{
 };
 
 const HYPER3D_IMAGE_TO_MODEL_BODY_LIMIT_BYTES: usize = 56 * 1024 * 1024;
-const EDITOR_CHARACTER_ANIMATION_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
-const EDITOR_VIDEO_BODY_LIMIT_BYTES: usize = 64 * 1024 * 1024;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct PlayFlowDomainAdapter {
@@ -460,24 +458,17 @@ fn play_flow_support_router(state: AppState) -> Router<AppState> {
         )
         .route(
             "/api/editor/character-animations/generations",
-            post(generate_editor_character_animation)
-                .layer(DefaultBodyLimit::max(
-                    // 中文注释：画板角色动画首版仍兼容角色图 Data URL 入参，避免大于 Axum 默认 2MB 的角色图在 handler 前被拦截。
-                    EDITOR_CHARACTER_ANIMATION_BODY_LIMIT_BYTES,
-                ))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(generate_editor_character_animation).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/videos/generations",
-            post(generate_editor_video)
-                .layer(DefaultBodyLimit::max(EDITOR_VIDEO_BODY_LIMIT_BYTES))
-                .route_layer(middleware::from_fn_with_state(
-                    state.clone(),
-                    require_bearer_auth,
-                )),
+            post(generate_editor_video).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/editor/audios/sound-effects/generations",
diff --git a/server-rs/crates/api-server/src/runtime_inventory.rs b/server-rs/crates/api-server/src/runtime_inventory.rs
index 53c0e29d2..9aa2c5d4d 100644
--- a/server-rs/crates/api-server/src/runtime_inventory.rs
+++ b/server-rs/crates/api-server/src/runtime_inventory.rs
@@ -126,8 +126,7 @@ mod tests {
 
     #[tokio::test]
     async fn runtime_inventory_returns_bad_gateway_when_spacetime_not_published() {
-        let state = seed_authenticated_state().await;
-        let token = issue_access_token(&state);
+        let (state, token) = seed_authenticated_state().await;
         let app = build_router(state);
 
         let response = app
@@ -161,35 +160,29 @@ mod tests {
         );
     }
 
-    async fn seed_authenticated_state() -> AppState {
+    async fn seed_authenticated_state() -> (AppState, String) {
         let state = AppState::new(AppConfig::default()).expect("state should build");
-        state
+        let user = state
             .seed_test_phone_user_with_password("13800138103", "secret123")
-            .await
-            .id;
-        state
-    }
-
-    fn issue_access_token(state: &AppState) -> String {
+            .await;
         let claims = AccessTokenClaims::from_input(
             AccessTokenClaimsInput {
-                user_id: "user_00000001".to_string(),
-                session_id: state.seed_test_refresh_session_for_user_id(
-                    "user_00000001",
-                    "sess_runtime_inventory",
-                ),
+                user_id: user.id.clone(),
+                session_id: state
+                    .seed_test_refresh_session_for_user(&user, "sess_runtime_inventory"),
                 provider: AuthProvider::Password,
                 roles: vec!["user".to_string()],
-                token_version: 2,
+                token_version: user.token_version,
                 phone_verified: true,
                 binding_status: BindingStatus::Active,
-                display_name: Some("背包查询用户".to_string()),
+                display_name: Some(user.display_name.clone()),
             },
             state.auth_jwt_config(),
             OffsetDateTime::now_utc(),
         )
         .expect("claims should build");
 
-        sign_access_token(&claims, state.auth_jwt_config()).expect("token should sign")
+        let token = sign_access_token(&claims, state.auth_jwt_config()).expect("token should sign");
+        (state, token)
     }
 }
diff --git a/server-rs/crates/api-server/src/state.rs b/server-rs/crates/api-server/src/state.rs
index 62d067b4a..72ae24659 100644
--- a/server-rs/crates/api-server/src/state.rs
+++ b/server-rs/crates/api-server/src/state.rs
@@ -276,6 +276,7 @@ pub struct AppStateInner {
     llm_client: Option<LlmClient>,
     creative_agent_gpt5_client: Option<LlmClient>,
     matting_client: Option<MattingClient>,
+    editor_bgfilter_http_client: reqwest::Client,
     creative_agent_executor: Arc<MockLangChainRustAgentExecutor>,
     // Phase 1 任务 E 的 creative session facade 暂存在 api-server。
     // creative_agent_* 表由任务 D 收口后，这里只保留读写 facade。
@@ -515,6 +516,7 @@ impl AppState {
         let llm_client = build_llm_client(&config)?;
         let creative_agent_gpt5_client = build_creative_agent_gpt5_client(&config)?;
         let matting_client = build_matting_client(&config)?;
+        let editor_bgfilter_http_client = build_editor_bgfilter_http_client(&config)?;
         let http_request_permit_pools = HttpRequestPermitPools::from_config(&config);
         let (profile_recharge_order_updates, _) = broadcast::channel(128);
 
@@ -555,6 +557,7 @@ impl AppState {
             llm_client,
             creative_agent_gpt5_client,
             matting_client,
+            editor_bgfilter_http_client,
             creative_agent_executor: Arc::new(MockLangChainRustAgentExecutor),
             creative_agent_sessions: Arc::new(Mutex::new(HashMap::new())),
             profile_recharge_order_updates,
@@ -1255,6 +1258,10 @@ impl AppState {
         self.matting_client.as_ref()
     }
 
+    pub fn editor_bgfilter_http_client(&self) -> &reqwest::Client {
+        &self.editor_bgfilter_http_client
+    }
+
     pub fn creative_agent_executor(&self) -> Arc<MockLangChainRustAgentExecutor> {
         self.creative_agent_executor.clone()
     }
@@ -1954,6 +1961,25 @@ fn build_matting_client(config: &AppConfig) -> Result<Option<MattingClient>, App
         .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))
 }
 
+fn build_editor_bgfilter_http_client(
+    config: &AppConfig,
+) -> Result<reqwest::Client, AppStateInitError> {
+    reqwest::Client::builder()
+        .timeout(std::time::Duration::from_millis(
+            config.editor_bgfilter_request_timeout_ms.max(1),
+        ))
+        .connect_timeout(std::time::Duration::from_secs(30))
+        .pool_idle_timeout(std::time::Duration::from_secs(300))
+        .pool_max_idle_per_host(64)
+        .tcp_keepalive(std::time::Duration::from_secs(60))
+        .build()
+        .map_err(|error| {
+            AppStateInitError::DependencyUnavailable(format!(
+                "构建共享 BgFilter HTTP 客户端失败：{error}"
+            ))
+        })
+}
+
 fn build_wechat_client(config: &AppConfig) -> WechatClient {
     WechatClient::new(WechatConfig {
         app_id: config.wechat_mini_program_app_id.clone(),
diff --git a/server-rs/crates/api-server/src/tracking_outbox.rs b/server-rs/crates/api-server/src/tracking_outbox.rs
index 5c1e29b7b..0f85a68c9 100644
--- a/server-rs/crates/api-server/src/tracking_outbox.rs
+++ b/server-rs/crates/api-server/src/tracking_outbox.rs
@@ -123,6 +123,7 @@ impl TrackingOutbox {
             .as_mut()
             .expect("active file should be open before append");
         file.write_all(&line).await?;
+        file.flush().await?;
         inner.active_count = inner.active_count.saturating_add(1);
         inner.active_bytes = inner.active_bytes.saturating_add(line_bytes);
         inner.total_bytes = inner.total_bytes.saturating_add(line_bytes);
@@ -571,6 +572,19 @@ mod tests {
         let _ = std::fs::remove_dir_all(dir);
     }
 
+    #[tokio::test]
+    async fn enqueue_flushes_active_file_before_success() {
+        let dir = test_dir("flush-before-success");
+        let outbox = test_outbox(dir.clone(), 500, 1024 * 1024);
+
+        outbox.enqueue(sample_event("event-1")).await.unwrap();
+
+        let active_contents = std::fs::read_to_string(dir.join(ACTIVE_FILE_NAME)).unwrap();
+        assert!(active_contents.contains("event-1"));
+
+        let _ = std::fs::remove_dir_all(dir);
+    }
+
     #[tokio::test]
     async fn enqueue_drops_when_outbox_exceeds_max_bytes() {
         let dir = test_dir("max-bytes");
diff --git a/server-rs/crates/module-assets/src/asset_object_core.rs b/server-rs/crates/module-assets/src/asset_object_core.rs
index 56f66f705..6e7d567c3 100644
--- a/server-rs/crates/module-assets/src/asset_object_core.rs
+++ b/server-rs/crates/module-assets/src/asset_object_core.rs
@@ -1,5 +1,5 @@
 use shared_kernel::{
-    build_prefixed_seed_id, format_timestamp_micros, normalize_optional_string,
+    build_prefixed_seed_entropy_id, format_timestamp_micros, normalize_optional_string,
     normalize_required_string,
 };
 
@@ -203,12 +203,14 @@ pub fn build_asset_entity_binding_record(
     }
 }
 
+// 资产确认可能在同一微秒内并发发生（例如角色动作帧 48 路并发确认），
+// 主键必须带随机熵；时间前缀仅保留调试可读性，不参与唯一性保证。
 pub fn generate_asset_object_id(seed_micros: i64) -> String {
-    build_prefixed_seed_id(ASSET_OBJECT_ID_PREFIX, seed_micros)
+    build_prefixed_seed_entropy_id(ASSET_OBJECT_ID_PREFIX, seed_micros)
 }
 
 pub fn generate_asset_binding_id(seed_micros: i64) -> String {
-    build_prefixed_seed_id(ASSET_BINDING_ID_PREFIX, seed_micros)
+    build_prefixed_seed_entropy_id(ASSET_BINDING_ID_PREFIX, seed_micros)
 }
 
 pub fn normalize_optional_value(value: Option<String>) -> Option<String> {
@@ -219,6 +221,21 @@ pub fn normalize_optional_value(value: Option<String>) -> Option<String> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn generated_ids_with_same_seed_micros_never_collide() {
+        let seed_micros = 1_713_686_400_000_000;
+
+        let first_object_id = generate_asset_object_id(seed_micros);
+        let second_object_id = generate_asset_object_id(seed_micros);
+        assert!(first_object_id.starts_with(ASSET_OBJECT_ID_PREFIX));
+        assert_ne!(first_object_id, second_object_id);
+
+        let first_binding_id = generate_asset_binding_id(seed_micros);
+        let second_binding_id = generate_asset_binding_id(seed_micros);
+        assert!(first_binding_id.starts_with(ASSET_BINDING_ID_PREFIX));
+        assert_ne!(first_binding_id, second_binding_id);
+    }
+
     #[test]
     fn validate_asset_object_fields_accepts_minimal_private_object_contract() {
         let result = validate_asset_object_fields(
diff --git a/server-rs/crates/module-editor-agent/Cargo.toml b/server-rs/crates/module-editor-agent/Cargo.toml
index e54246781..188b483f0 100644
--- a/server-rs/crates/module-editor-agent/Cargo.toml
+++ b/server-rs/crates/module-editor-agent/Cargo.toml
@@ -12,4 +12,4 @@ spacetime-types = ["dep:spacetimedb"]
 serde = { workspace = true }
 serde_json = { workspace = true }
 shared-kernel = { workspace = true }
-spacetimedb = { workspace = true, optional = true }
\ No newline at end of file
+spacetimedb = { workspace = true, optional = true }
diff --git a/server-rs/crates/module-editor-agent/src/events.rs b/server-rs/crates/module-editor-agent/src/events.rs
new file mode 100644
index 000000000..d434b0985
--- /dev/null
+++ b/server-rs/crates/module-editor-agent/src/events.rs
@@ -0,0 +1 @@
+//! 编辑器 Agent 领域事件预留落位，当前不导出独立事件类型。
diff --git a/server-rs/crates/module-editor-agent/src/lib.rs b/server-rs/crates/module-editor-agent/src/lib.rs
index b68fa5247..b700e48b0 100644
--- a/server-rs/crates/module-editor-agent/src/lib.rs
+++ b/server-rs/crates/module-editor-agent/src/lib.rs
@@ -2,6 +2,7 @@ mod application;
 mod commands;
 mod domain;
 mod errors;
+mod events;
 
 pub use application::*;
 pub use commands::*;
diff --git a/server-rs/crates/platform-editor-agent/Cargo.toml b/server-rs/crates/platform-editor-agent/Cargo.toml
new file mode 100644
index 000000000..a38849a97
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "platform-editor-agent"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[dependencies]
+hmac = { workspace = true }
+platform-agent = { workspace = true }
+platform-llm = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+shared-contracts = { workspace = true, features = ["oss-contracts"] }
diff --git a/server-rs/crates/platform-editor-agent/src/agent/agent.rs b/server-rs/crates/platform-editor-agent/src/agent/agent.rs
new file mode 100644
index 000000000..31dcb461d
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/agent.rs
@@ -0,0 +1,201 @@
+use crate::framework::agent::{Agent, LlmApiAdaptor};
+use crate::framework::agent_builder::AgentBuilder;
+use crate::framework::error::PromptError;
+use crate::framework::hook::Hook;
+use crate::framework::memory::AgentMemory;
+use crate::framework::tool::{Tool, ToolDyn};
+use platform_agent::CREATIVE_AGENT_GPT5_MODEL;
+use platform_llm::{LlmClient, LlmMessage, LlmRunRequest};
+use serde_json::Value;
+
+const EDITOR_AGENT_LLM_MAX_OUTPUT_TOKENS: u32 = 1024;
+const EDITOR_AGENT_LLM_REQUEST_TIMEOUT_MS: u64 = 60_000;
+
+pub struct LlmCompletionModel {
+    client: LlmClient,
+}
+
+impl LlmApiAdaptor<LlmMessage> for LlmCompletionModel {
+    async fn complete<'a>(
+        &self,
+        messages: impl Iterator<Item = &'a LlmMessage> + Send,
+    ) -> Result<String, PromptError> {
+        let request = build_editor_agent_llm_request(messages.cloned().collect());
+        let response = self
+            .client
+            .run(request)
+            .await
+            .map_err(|e| PromptError::CompletionError(e.to_string()))?;
+        Ok(response.text)
+    }
+
+    fn tool_result_message(&self, tool_name: &str, output: &str) -> LlmMessage {
+        LlmMessage::system(format!("Tool '{tool_name}' returned: {output}"))
+    }
+
+    fn build_assistant_message(&self, text: &str) -> LlmMessage {
+        LlmMessage::assistant(text)
+    }
+}
+
+fn build_editor_agent_llm_request(messages: Vec<LlmMessage>) -> LlmRunRequest {
+    LlmRunRequest::new(messages)
+        .with_model(CREATIVE_AGENT_GPT5_MODEL)
+        .with_openai_chat()
+        .with_max_output_tokens(EDITOR_AGENT_LLM_MAX_OUTPUT_TOKENS)
+        .with_request_timeout_ms(EDITOR_AGENT_LLM_REQUEST_TIMEOUT_MS)
+}
+
+pub struct LlmChatAgentBuilder {
+    client: Option<LlmClient>,
+    system_prompt_parts: Vec<String>,
+    tools: Vec<Box<dyn ToolDyn>>,
+    hooks: Vec<Box<dyn Hook>>,
+    max_turns: usize,
+    memory_data: Option<Box<dyn AgentMemory<LlmMessage>>>,
+}
+
+impl AgentBuilder<LlmMessage, LlmCompletionModel> for LlmChatAgentBuilder {
+    type Client = LlmClient;
+
+    fn new() -> Self {
+        Self {
+            client: None,
+            system_prompt_parts: Vec::new(),
+            tools: Vec::new(),
+            hooks: Vec::new(),
+            max_turns: 10,
+            memory_data: None,
+        }
+    }
+
+    fn with_client(mut self, client: LlmClient) -> Self {
+        self.client = Some(client);
+        self
+    }
+
+    fn system_prompt(mut self, system_prompt: impl Into<String>) -> Self {
+        self.system_prompt_parts.push(system_prompt.into());
+        self
+    }
+
+    fn tool(mut self, tool: impl Tool + Send + Sync + 'static) -> Self {
+        self.tools.push(Box::new(tool));
+        self
+    }
+
+    fn add_hook(mut self, hook: impl Hook + 'static) -> Self {
+        self.hooks.push(Box::new(hook));
+        self
+    }
+
+    fn max_turns(mut self, n: usize) -> Self {
+        self.max_turns = n;
+        self
+    }
+
+    fn memory(mut self, memory: impl AgentMemory<LlmMessage> + 'static) -> Self {
+        self.memory_data = Some(Box::new(memory));
+        self
+    }
+
+    fn build(self) -> Agent<LlmCompletionModel, LlmMessage> {
+        let model = LlmCompletionModel {
+            client: self.client.expect("call .with_client() first"),
+        };
+        let mut agent = Agent::new(model);
+        let tool_specs = self
+            .tools
+            .iter()
+            .map(|tool| ToolPromptSpec {
+                name: tool.tool_name().to_string(),
+                description: tool.description(),
+                parameters: tool.parameters(),
+            })
+            .collect::<Vec<_>>();
+        let base_prompt = self.system_prompt_parts.join("\n\n");
+        let system_prompt = build_tools_system_prompt(&base_prompt, &tool_specs);
+        agent.tools = self.tools;
+        agent.hooks = self.hooks;
+        agent.default_max_turns = self.max_turns;
+        agent.memory = self.memory_data;
+        agent.system_prompt = Some(LlmMessage::system(&system_prompt));
+        agent
+    }
+}
+
+struct ToolPromptSpec {
+    name: String,
+    description: String,
+    parameters: Value,
+}
+
+fn build_tools_system_prompt(base_prompt: &str, tool_specs: &[ToolPromptSpec]) -> String {
+    let mut prompt = String::new();
+    prompt.push_str(base_prompt);
+    prompt.push_str("\n\nYou have access to the following tools.\n\n");
+
+    if tool_specs.is_empty() {
+        prompt.push_str("(No tools available.)\n");
+    } else {
+        prompt.push_str("## JSON Response Format\n");
+        prompt.push_str("respond with valid JSON only (no markdown fences):\n");
+        prompt.push_str("{\n");
+        prompt.push_str("  \"reply_text\": \"your message to the user\",\n");
+        prompt.push_str("  \"tool_calls\": [\n    {\n");
+        prompt.push_str("      \"tool_name\": \"tool_name_here\",\n");
+        prompt.push_str("      \"args\": { \"argument_name\": \"argument_value\" }\n");
+        prompt.push_str("    }\n  ]\n");
+        prompt.push_str("}\n\n");
+        prompt.push_str("If you don't need to use a tool, respond with:\n");
+        prompt.push_str("{\n");
+        prompt.push_str("  \"reply_text\": \"your message\",\n");
+        prompt.push_str("  \"tool_calls\": []\n");
+        prompt.push_str("}\n\n");
+        prompt.push_str("## Available Tools\n\n");
+
+        for tool in tool_specs {
+            prompt.push_str(&format!("- {}\n", tool.name));
+            prompt.push_str(&format!("  Description: {}\n", tool.description));
+            prompt.push_str("  Arguments JSON Schema:\n");
+            let parameters = serde_json::to_string_pretty(&tool.parameters)
+                .unwrap_or_else(|_| tool.parameters.to_string());
+            prompt.push_str(&parameters);
+            prompt.push_str("\n");
+        }
+
+        prompt.push_str(
+      "as you see, tool_calls is an array, several tools calls can be executed in one turn concurrently. ",
+    );
+        prompt.push_str("your valid tool call will be recorded as system message");
+        prompt.push_str(
+          "some tools calls needs user's confirmation, you should not retry the same tool call in this case.\
+           And if all tool calls are pending confirmation, you should just end the turn, as you cant do more before user's action"
+        );
+    }
+
+    prompt
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use platform_llm::LlmApiKind;
+
+    #[test]
+    fn editor_agent_llm_request_keeps_gpt5_contract() {
+        let request = build_editor_agent_llm_request(vec![
+            LlmMessage::system("系统提示"),
+            LlmMessage::user("用户请求"),
+        ]);
+
+        assert_eq!(
+            request.model.as_deref(),
+            Some(platform_agent::CREATIVE_AGENT_GPT5_MODEL)
+        );
+        assert_eq!(request.api_kind, LlmApiKind::OpenAiChat);
+        assert_eq!(request.max_output_tokens, Some(1024));
+        assert_eq!(request.request_timeout_ms, Some(60_000));
+        assert_eq!(request.messages.len(), 2);
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/asset.rs b/server-rs/crates/platform-editor-agent/src/agent/asset.rs
new file mode 100644
index 000000000..0f9bced59
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/asset.rs
@@ -0,0 +1,43 @@
+use hmac::digest::Digest;
+use serde::{Deserialize, Serialize};
+use sha2::Sha256;
+use std::fmt::Display;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct ImageId {
+    pub id: String,
+}
+
+impl ImageId {
+    /// Keep data keys server-side while giving the model a stable image reference.
+    pub fn from_data_key(data_key: impl AsRef<str>) -> Self {
+        let digest = Sha256::digest(data_key.as_ref().as_bytes());
+        Self {
+            id: format!("sha256:{digest:x}"),
+        }
+    }
+}
+
+impl Serialize for ImageId {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        self.id.serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ImageId {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        String::deserialize(deserializer).map(|id| ImageId { id })
+    }
+}
+
+impl Display for ImageId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.id)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ImageMetadata {
+    pub tag: String,
+    pub data_key: String,
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/mod.rs b/server-rs/crates/platform-editor-agent/src/agent/mod.rs
new file mode 100644
index 000000000..ab3846cdf
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/mod.rs
@@ -0,0 +1,3 @@
+pub mod agent;
+pub mod asset;
+pub mod tools;
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/context.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/context.rs
new file mode 100644
index 000000000..2cd2aebfd
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/context.rs
@@ -0,0 +1,22 @@
+use crate::agent::asset::ImageId;
+use crate::agent::asset::ImageMetadata;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+impl EditorToolContext {
+    /// Check if an image with the given ID exists in the context.
+    pub fn contains_image(&self, image_id: &ImageId) -> bool {
+        self.images.contains_key(image_id)
+    }
+
+    pub fn image_data_key(&self, image_id: &ImageId) -> Option<&str> {
+        self.images
+            .get(image_id)
+            .map(|metadata| metadata.data_key.as_str())
+    }
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct EditorToolContext {
+    pub images: HashMap<ImageId, ImageMetadata>,
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/edit_image.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/edit_image.rs
new file mode 100644
index 000000000..865b78eb8
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/edit_image.rs
@@ -0,0 +1,175 @@
+use crate::agent::asset::ImageId;
+use crate::agent::tools::context::EditorToolContext;
+use crate::framework::tool::{Tool, ToolFailure, ToolFailureKind};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::error::Error;
+use std::fmt::Display;
+pub struct EditImageTool {
+    pub context: EditorToolContext,
+}
+
+#[derive(Debug, Clone)]
+pub enum EditImageError {
+    ObjectImageNotProvided,
+    PromptNotProvided,
+    AssetNotFound(ImageId),
+}
+
+impl Display for EditImageError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            EditImageError::ObjectImageNotProvided => {
+                write!(f, "object image not provided")
+            }
+            EditImageError::PromptNotProvided => write!(f, "prompt not provided"),
+            EditImageError::AssetNotFound(image_id) => {
+                write!(f, "asset {image_id} not found in context")
+            }
+        }
+    }
+}
+
+impl Error for EditImageError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EditImageToolArgs {
+    pub object_image_id: ImageId,
+    #[serde(default)]
+    pub reference_image_ids: Vec<ImageId>,
+    pub prompt: String,
+    // #[serde(default)]
+    // pub tag: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EditImageToolOutput {
+    pub message: String,
+}
+
+impl Tool for EditImageTool {
+    const NAME: &'static str = "edit-image";
+    type Error = EditImageError;
+    type Args = EditImageToolArgs;
+    type Output = EditImageToolOutput;
+
+    fn description(&self) -> String {
+        "仅用于修改已有图片：换衣服、改颜色、替换背景、局部重绘，或保持主体、构图、姿势不变的编辑。用户指代“这张”“刚才那个”“上一张”“改成”“换成”时优先使用本工具。必须使用已有图片上下文；没有参考图时不要调用，应提示用户先选择参考图。"
+            .to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "object_image_id": {
+                    "type": "string",
+                    "description": "要修改的目标图片。"
+                },
+                "reference_image_ids": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "修改参考图 ID 列表（可选的，用于提供风格或元素参考）。"
+                },
+                "prompt": {
+                    "type": "string",
+                    "description": "编辑提示词，描述希望如何修改图片。例如「把背景换成红色」、「把人物改成坐着」。"
+                },
+                // "tag": {
+                //     "type": "string",
+                //     "description": "为新生成的图片添加标签，用于后续在上下文中引用。"
+                // }
+            },
+            "required": ["object_image_id", "prompt"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            if let Some(error) = self.validate_args(&args) {
+                return Err(error);
+            }
+            Ok(EditImageToolOutput {
+                message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string(),
+            })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        match error {
+            EditImageError::AssetNotFound(_) => {
+                ToolFailure::new(ToolFailureKind::NotFound, error.to_string())
+            }
+            EditImageError::ObjectImageNotProvided | EditImageError::PromptNotProvided => {
+                ToolFailure::invalid_args(error.to_string())
+            }
+        }
+    }
+}
+
+/// Typed result deserialized from `edit_editor_image_for_owner` response.
+///
+/// Mirrors `EditorImageGenerationResponse` but uses `String` instead of `&'static str`
+/// and `Value` for nested payload types so that `#[derive(Deserialize)]` works.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorImageEditResult {
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub asset_object_id: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: String,
+    pub actual_prompt: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub task_id: String,
+    pub resource: Option<Value>,
+    pub asset: Option<Value>,
+    pub project: Option<Value>,
+}
+
+impl EditImageTool {
+    /// Validate the semantic correctness of the arguments.
+    fn validate_args(&self, args: &EditImageToolArgs) -> Option<EditImageError> {
+        if args.prompt.trim().is_empty() {
+            return Some(EditImageError::PromptNotProvided);
+        }
+        if !self.context.contains_image(&args.object_image_id) {
+            return Some(EditImageError::AssetNotFound(args.object_image_id.clone()));
+        }
+
+        for ref_id in &args.reference_image_ids {
+            if !self.context.contains_image(ref_id) {
+                return Some(EditImageError::AssetNotFound(ref_id.clone()));
+            }
+        }
+        None
+    }
+
+    pub fn format_execute_message(
+        &self,
+        args: <Self as Tool>::Args,
+        result: EditorImageEditResult,
+    ) -> String {
+        let name = Self::NAME.to_string();
+        let arg_json = serde_json::to_string(&args).unwrap_or_default();
+
+        let data_key = result
+            .object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| result.image_src.clone());
+        let image_id = ImageId::from_data_key(data_key);
+        format!(
+            "[tool_call:{name}] args: {arg_json} output: edited result saved as image: {image_id}"
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_background_music.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_background_music.rs
new file mode 100644
index 000000000..1b262a431
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_background_music.rs
@@ -0,0 +1,83 @@
+use crate::framework::tool::{Tool, ToolFailure};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_contracts::assets::EditorAudioGenerateResponse;
+use std::error::Error;
+use std::fmt::Display;
+
+pub struct GenerateBackgroundMusicTool;
+
+#[derive(Debug, Clone)]
+pub enum GenerateBackgroundMusicError {
+    PromptNotProvided,
+}
+impl Display for GenerateBackgroundMusicError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "background music prompt not provided")
+    }
+}
+impl Error for GenerateBackgroundMusicError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateBackgroundMusicToolArgs {
+    pub prompt: String,
+    #[serde(default = "default_instrumental")]
+    pub make_instrumental: bool,
+}
+fn default_instrumental() -> bool {
+    true
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateBackgroundMusicToolOutput {
+    pub message: String,
+}
+
+impl Tool for GenerateBackgroundMusicTool {
+    const NAME: &'static str = "generate-background-music";
+    type Error = GenerateBackgroundMusicError;
+    type Args = GenerateBackgroundMusicToolArgs;
+    type Output = GenerateBackgroundMusicToolOutput;
+    fn description(&self) -> String {
+        "根据文字描述生成背景音乐。默认生成纯音乐，除非明确要求歌词或人声。".to_string()
+    }
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object", "properties": {
+                "prompt": { "type": "string", "description": "音乐风格、情绪、乐器和节奏描述。" },
+                "make_instrumental": { "type": "boolean", "description": "是否生成纯音乐，默认 true。" }
+            }, "required": ["prompt"], "additionalProperties": false
+        })
+    }
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            if args.prompt.trim().is_empty() {
+                return Err(GenerateBackgroundMusicError::PromptNotProvided);
+            }
+            Ok(GenerateBackgroundMusicToolOutput {
+                message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string(),
+            })
+        }
+    }
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        ToolFailure::invalid_args(error.to_string())
+    }
+}
+
+impl GenerateBackgroundMusicTool {
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateBackgroundMusicToolArgs,
+        result: &EditorAudioGenerateResponse,
+    ) -> String {
+        format!(
+            "[tool_call:{}] args: {} output: generated audio saved as: {}",
+            Self::NAME,
+            serde_json::to_string(args).unwrap_or_default(),
+            result.audio_src
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_character.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_character.rs
new file mode 100644
index 000000000..6cd34f41f
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_character.rs
@@ -0,0 +1,79 @@
+use crate::agent::tools::context::EditorToolContext;
+use crate::agent::tools::generate_image::{
+    EditorImageGenerationResult, GenerateImageError, GenerateImageTool, GenerateImageToolArgs,
+    GenerateImageToolOutput,
+};
+use crate::framework::tool::{Tool, ToolFailure};
+use serde_json::{Value, json};
+
+pub struct GenerateCharacterTool {
+    pub context: EditorToolContext,
+}
+
+impl Tool for GenerateCharacterTool {
+    const NAME: &'static str = "generate-character";
+    type Error = GenerateImageError;
+    type Args = GenerateImageToolArgs;
+    type Output = GenerateImageToolOutput;
+
+    fn description(&self) -> String {
+        "仅用于生成新的角色形象、人物立绘或普通角色设定图。已有角色图的服装、颜色、表情、姿势或背景修改必须选择 edit-image。角色规范图、角色美术视觉规范设定图或规范展板必须选择 generate-image。"
+            .to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "prompt": { "type": "string", "description": "角色外貌、服装、姿势、画风和构图的完整描述。" },
+                "reference_image_ids": { "type": "array", "items": { "type": "string" }, "description": "可选角色或画风参考图 ID。" },
+                "aspect_ratio": { "type": "string", "description": "可选比例，例如 2:3 或 9:16。" },
+                "image_size": { "type": "string", "description": "可选清晰度，例如 1K 或 2K。" }
+            },
+            "required": ["prompt"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            GenerateImageTool {
+                context: self.context.clone(),
+            }
+            .validate_args(&args)?;
+            Ok(GenerateImageToolOutput { message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string() })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        GenerateImageTool {
+            context: self.context.clone(),
+        }
+        .classify_error(error)
+    }
+}
+
+impl GenerateCharacterTool {
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateImageToolArgs,
+        result: &EditorImageGenerationResult,
+    ) -> String {
+        let tool_name = Self::NAME;
+        let args = serde_json::to_string(args).unwrap_or_default();
+        let data_key = result
+            .object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| result.image_src.clone());
+        let image_id = crate::agent::asset::ImageId::from_data_key(data_key);
+        format!(
+            "[tool_call:{tool_name}] args: {args} output: generated result saved as image: {image_id}"
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_icon_spritesheet.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_icon_spritesheet.rs
new file mode 100644
index 000000000..d1892b901
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_icon_spritesheet.rs
@@ -0,0 +1,172 @@
+use crate::agent::asset::ImageId;
+use crate::agent::tools::context::EditorToolContext;
+use crate::framework::tool::{Tool, ToolFailure, ToolFailureKind};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::error::Error;
+use std::fmt::Display;
+
+pub struct GenerateIconSpritesheetTool {
+    pub context: EditorToolContext,
+}
+
+#[derive(Debug, Clone)]
+pub enum GenerateIconSpritesheetError {
+    ReferenceNotProvided,
+    DescriptionsNotProvided,
+    AssetNotFound(ImageId),
+}
+
+impl Display for GenerateIconSpritesheetError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::ReferenceNotProvided => write!(f, "reference image not provided"),
+            Self::DescriptionsNotProvided => write!(f, "icon descriptions not provided"),
+            Self::AssetNotFound(image_id) => write!(f, "asset {image_id} not found in context"),
+        }
+    }
+}
+
+impl Error for GenerateIconSpritesheetError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateIconSpritesheetToolArgs {
+    pub reference_image_id: ImageId,
+    #[serde(default)]
+    pub reference_image_ids: Vec<ImageId>,
+    pub icon_descriptions: Vec<String>,
+    #[serde(default)]
+    pub aspect_ratio: Option<String>,
+    #[serde(default)]
+    pub image_size: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateIconSpritesheetToolOutput {
+    pub message: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetResult {
+    pub spritesheet_image_src: String,
+    pub spritesheet_width: u32,
+    pub spritesheet_height: u32,
+    pub task_id: String,
+    pub spritesheet_resource: Option<Value>,
+    pub spritesheet_asset: Option<Value>,
+    pub project: Option<Value>,
+    #[serde(default)]
+    pub icon_image_srcs: Vec<EditorIconSpritesheetImage>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetImage {
+    pub image_src: String,
+    pub width: u32,
+    pub height: u32,
+    pub resource: Option<Value>,
+}
+
+impl Tool for GenerateIconSpritesheetTool {
+    const NAME: &'static str = "generate-icon-spritesheet";
+    type Error = GenerateIconSpritesheetError;
+    type Args = GenerateIconSpritesheetToolArgs;
+    type Output = GenerateIconSpritesheetToolOutput;
+
+    fn description(&self) -> String {
+        "仅用于生成多个图标成品、图标素材图集或 spritesheet。必须提供图标规范或风格参考图，并填写多个 icon_descriptions；没有参考图时不要调用，应提示用户先选择参考图。图标规范图或图标视觉规范展板不是本工具，应使用 generate-image。".to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "reference_image_id": { "type": "string", "description": "必填的图标规范或风格参考图 ID。" },
+                "reference_image_ids": { "type": "array", "items": { "type": "string" }, "description": "可选的额外参考图 ID。" },
+                "icon_descriptions": { "type": "array", "items": { "type": "string" }, "description": "要生成的多个图标描述。" },
+                "aspect_ratio": { "type": "string", "description": "可选图集比例。" },
+                "image_size": { "type": "string", "description": "可选清晰度，例如 1K 或 2K。" }
+            },
+            "required": ["reference_image_id", "icon_descriptions"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            self.validate_args(&args)?;
+            Ok(GenerateIconSpritesheetToolOutput {
+                message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string(),
+            })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        match error {
+            GenerateIconSpritesheetError::AssetNotFound(_) => {
+                ToolFailure::new(ToolFailureKind::NotFound, error.to_string())
+            }
+            GenerateIconSpritesheetError::ReferenceNotProvided
+            | GenerateIconSpritesheetError::DescriptionsNotProvided => {
+                ToolFailure::invalid_args(error.to_string())
+            }
+        }
+    }
+}
+
+impl GenerateIconSpritesheetTool {
+    fn validate_args(
+        &self,
+        args: &GenerateIconSpritesheetToolArgs,
+    ) -> Result<(), GenerateIconSpritesheetError> {
+        if args.reference_image_id.id.trim().is_empty() {
+            return Err(GenerateIconSpritesheetError::ReferenceNotProvided);
+        }
+        if !self.context.contains_image(&args.reference_image_id) {
+            return Err(GenerateIconSpritesheetError::AssetNotFound(
+                args.reference_image_id.clone(),
+            ));
+        }
+        if args
+            .icon_descriptions
+            .iter()
+            .all(|description| description.trim().is_empty())
+        {
+            return Err(GenerateIconSpritesheetError::DescriptionsNotProvided);
+        }
+        for image_id in &args.reference_image_ids {
+            if !self.context.contains_image(image_id) {
+                return Err(GenerateIconSpritesheetError::AssetNotFound(
+                    image_id.clone(),
+                ));
+            }
+        }
+        Ok(())
+    }
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateIconSpritesheetToolArgs,
+        result: &EditorIconSpritesheetResult,
+    ) -> String {
+        let tool_name = Self::NAME;
+        let args = serde_json::to_string(args).unwrap_or_default();
+        let data_key = result
+            .spritesheet_resource
+            .as_ref()
+            .and_then(|resource| resource.get("objectKey"))
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| result.spritesheet_image_src.clone());
+        let image_id = ImageId::from_data_key(data_key);
+        format!(
+            "[tool_call:{tool_name}] args: {args} output: generated spritesheet saved as image: {image_id}",
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_image.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_image.rs
new file mode 100644
index 000000000..959c1c31f
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_image.rs
@@ -0,0 +1,158 @@
+use crate::agent::asset::ImageId;
+use crate::agent::tools::context::EditorToolContext;
+use crate::framework::tool::{Tool, ToolFailure, ToolFailureKind};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::error::Error;
+use std::fmt::Display;
+
+pub struct GenerateImageTool {
+    pub context: EditorToolContext,
+}
+
+#[derive(Debug, Clone)]
+pub enum GenerateImageError {
+    PromptNotProvided,
+    AssetNotFound(ImageId),
+}
+
+impl Display for GenerateImageError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::PromptNotProvided => write!(f, "prompt not provided"),
+            Self::AssetNotFound(image_id) => write!(f, "asset {image_id} not found in context"),
+        }
+    }
+}
+
+impl Error for GenerateImageError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateImageToolArgs {
+    pub prompt: String,
+    #[serde(default)]
+    pub reference_image_ids: Vec<ImageId>,
+    #[serde(default)]
+    // TODO restrict to a set of possible values
+    pub aspect_ratio: Option<String>,
+    #[serde(default)]
+    pub image_size: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateImageToolOutput {
+    pub message: String,
+}
+
+impl Tool for GenerateImageTool {
+    const NAME: &'static str = "generate-image";
+    type Error = GenerateImageError;
+    type Args = GenerateImageToolArgs;
+    type Output = GenerateImageToolOutput;
+
+    fn description(&self) -> String {
+        "用于从文字生成全新图片：新场景、新物体、新插画或新背景；也专用于规范图、视觉规范图、风格规范图、素材规范展板。不要用来修改已有图，已有图修改应选 edit-image。规范展板 prompt 必须写明统一视角、线条粗细、描边、填充风格、材质、阴影、圆角、状态层级、色卡或色号、尺寸标注和排版层级；角色规范展板还要含头身比例、标准立绘、动作帧样例、服饰配饰分层和专属色卡。完整 prompt 必须包含画面、主体、风格、构图和背景。"
+            .to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": "完整的生图提示词，包含主体、场景、风格、构图和背景。"
+                },
+                "reference_image_ids": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "可选参考图 ID 列表，用于提供画风或元素参考。"
+                },
+                "aspect_ratio": {
+                    "type": "string",
+                    "description": "可选画面比例，例如 1:1、16:9、9:16。"
+                },
+                "image_size": {
+                    "type": "string",
+                    "description": "可选图片清晰度，例如 1K、2K、4K。"
+                }
+            },
+            "required": ["prompt"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            self.validate_args(&args)?;
+            Ok(GenerateImageToolOutput {
+                message: "this tool call is pending user confirmation.".to_string(),
+            })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        match error {
+            GenerateImageError::AssetNotFound(_) => {
+                ToolFailure::new(ToolFailureKind::NotFound, error.to_string())
+            }
+            GenerateImageError::PromptNotProvided => ToolFailure::invalid_args(error.to_string()),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorImageGenerationResult {
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub asset_object_id: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: String,
+    pub actual_prompt: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub task_id: String,
+    pub resource: Option<Value>,
+    pub asset: Option<Value>,
+    pub project: Option<Value>,
+}
+
+impl GenerateImageTool {
+    pub fn validate_args(&self, args: &GenerateImageToolArgs) -> Result<(), GenerateImageError> {
+        if args.prompt.trim().is_empty() {
+            return Err(GenerateImageError::PromptNotProvided);
+        }
+        for image_id in &args.reference_image_ids {
+            if !self.context.contains_image(image_id) {
+                return Err(GenerateImageError::AssetNotFound(image_id.clone()));
+            }
+        }
+        Ok(())
+    }
+
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateImageToolArgs,
+        result: &EditorImageGenerationResult,
+    ) -> String {
+        let args = serde_json::to_string(args).unwrap_or_default();
+        let data_key = result
+            .object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| result.image_src.clone());
+        let image_id = ImageId::from_data_key(data_key);
+        format!(
+            "[tool_call:{}] args: {args} output: generated result saved as image: {image_id}",
+            Self::NAME,
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_sound_effect.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_sound_effect.rs
new file mode 100644
index 000000000..15fff27ec
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_sound_effect.rs
@@ -0,0 +1,92 @@
+use crate::framework::tool::{Tool, ToolFailure};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_contracts::assets::EditorAudioGenerateResponse;
+use std::error::Error;
+use std::fmt::Display;
+
+pub struct GenerateSoundEffectTool;
+
+#[derive(Debug, Clone)]
+pub enum GenerateSoundEffectError {
+    PromptNotProvided,
+}
+
+impl Display for GenerateSoundEffectError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "sound effect prompt not provided")
+    }
+}
+
+impl Error for GenerateSoundEffectError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateSoundEffectToolArgs {
+    pub prompt: String,
+    #[serde(default)]
+    pub duration: Option<u8>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateSoundEffectToolOutput {
+    pub message: String,
+}
+
+impl Tool for GenerateSoundEffectTool {
+    const NAME: &'static str = "generate-sound-effect";
+    type Error = GenerateSoundEffectError;
+    type Args = GenerateSoundEffectToolArgs;
+    type Output = GenerateSoundEffectToolOutput;
+
+    fn description(&self) -> String {
+        "根据文字描述生成一段音效，例如脚步声、按钮点击声或环境音。".to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "prompt": { "type": "string", "description": "音效内容、材质、节奏和情绪描述。" },
+                "duration": { "type": "integer", "description": "可选时长（秒）。" },
+                // "model": { "type": "string", "description": "可选音效模型。" }
+            },
+            "required": ["prompt"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            if args.prompt.trim().is_empty() {
+                return Err(GenerateSoundEffectError::PromptNotProvided);
+            }
+            Ok(GenerateSoundEffectToolOutput {
+                message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string(),
+            })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        ToolFailure::invalid_args(error.to_string())
+    }
+}
+
+impl GenerateSoundEffectTool {
+    // pub const DEFAULT_MODEL: &'static str = "audio1.0";
+
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateSoundEffectToolArgs,
+        result: &EditorAudioGenerateResponse,
+    ) -> String {
+        format!(
+            "[tool_call:{}] args: {} output: generated audio saved as: {}",
+            Self::NAME,
+            serde_json::to_string(args).unwrap_or_default(),
+            result.audio_src
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_ui_design.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_ui_design.rs
new file mode 100644
index 000000000..2a7ee56b3
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_ui_design.rs
@@ -0,0 +1,78 @@
+use crate::agent::tools::context::EditorToolContext;
+use crate::agent::tools::generate_image::{
+    EditorImageGenerationResult, GenerateImageError, GenerateImageTool, GenerateImageToolArgs,
+    GenerateImageToolOutput,
+};
+use crate::framework::tool::{Tool, ToolFailure};
+use serde_json::{Value, json};
+
+pub struct GenerateUiDesignTool {
+    pub context: EditorToolContext,
+}
+
+impl Tool for GenerateUiDesignTool {
+    const NAME: &'static str = "generate-ui-design";
+    type Error = GenerateImageError;
+    type Args = GenerateImageToolArgs;
+    type Output = GenerateImageToolOutput;
+
+    fn description(&self) -> String {
+        "仅用于生成完整可用的 UI 设计图或界面稿，包括 HUD、弹窗、面板、按钮组合和整页界面。不要用于提取图标、拆素材或修改已有图；UI 规范图、组件规范展板或视觉规范展板应使用 generate-image。".to_string()
+    }
+
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "prompt": { "type": "string", "description": "完整 UI 画面、信息层级、视觉风格和构图描述。" },
+                "reference_image_ids": { "type": "array", "items": { "type": "string" }, "description": "可选 UI 风格或布局参考图 ID。" },
+                "aspect_ratio": { "type": "string", "description": "可选画面比例。" },
+                "image_size": { "type": "string", "description": "可选清晰度，例如 1K 或 2K。" }
+            },
+            "required": ["prompt"],
+            "additionalProperties": false
+        })
+    }
+
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            GenerateImageTool {
+                context: self.context.clone(),
+            }
+            .validate_args(&args)?;
+            Ok(GenerateImageToolOutput { message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string() })
+        }
+    }
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        GenerateImageTool {
+            context: self.context.clone(),
+        }
+        .classify_error(error)
+    }
+}
+
+impl GenerateUiDesignTool {
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateImageToolArgs,
+        result: &EditorImageGenerationResult,
+    ) -> String {
+        let tool_name = Self::NAME;
+        let args = serde_json::to_string(args).unwrap_or_default();
+        let data_key = result
+            .object_key
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(|value| value.trim_start_matches('/').to_string())
+            .unwrap_or_else(|| result.image_src.clone());
+        let image_id = crate::agent::asset::ImageId::from_data_key(data_key);
+        format!(
+            "[tool_call:{tool_name}] args: {args} output: generated result saved as image: {image_id}"
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/generate_video.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_video.rs
new file mode 100644
index 000000000..81cf19361
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/generate_video.rs
@@ -0,0 +1,117 @@
+use crate::agent::asset::ImageId;
+use crate::agent::tools::context::EditorToolContext;
+use crate::framework::tool::{Tool, ToolFailure, ToolFailureKind};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_contracts::assets::EditorVideoGenerateResponse;
+use std::error::Error;
+use std::fmt::Display;
+
+pub struct GenerateVideoTool {
+    pub context: EditorToolContext,
+}
+
+#[derive(Debug, Clone)]
+pub enum GenerateVideoError {
+    PromptNotProvided,
+    AssetNotFound(ImageId),
+}
+impl Display for GenerateVideoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::PromptNotProvided => write!(f, "video prompt not provided"),
+            Self::AssetNotFound(image_id) => write!(f, "asset {image_id} not found in context"),
+        }
+    }
+}
+impl Error for GenerateVideoError {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateVideoToolArgs {
+    pub prompt: String,
+    #[serde(default)]
+    pub reference_image_ids: Vec<ImageId>,
+    #[serde(default)]
+    pub aspect_ratio: Option<String>,
+    #[serde(default)]
+    pub duration_seconds: Option<u32>,
+    #[serde(default)]
+    pub model: Option<String>,
+    #[serde(default)]
+    pub resolution: Option<String>,
+    #[serde(default)]
+    pub sound: Option<String>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GenerateVideoToolOutput {
+    pub message: String,
+}
+
+impl Tool for GenerateVideoTool {
+    const NAME: &'static str = "generate-video";
+    type Error = GenerateVideoError;
+    type Args = GenerateVideoToolArgs;
+    type Output = GenerateVideoToolOutput;
+    fn description(&self) -> String {
+        "根据文字描述生成一段短视频；可选图片参考图用于镜头风格或主体参考。".to_string()
+    }
+    fn parameters(&self) -> Value {
+        json!({
+            "type": "object", "properties": {
+                "prompt": { "type": "string", "description": "镜头、主体动作、场景和风格描述。" },
+                "reference_image_ids": { "type": "array", "items": { "type": "string" }, "description": "可选图片参考图 ID。" },
+                "aspect_ratio": { "type": "string", "description": "可选比例，默认 16:9。" },
+                "duration_seconds": { "type": "integer", "description": "可选时长，默认 4 秒。" },
+                "model": { "type": "string", "description": "可选视频模型。" },
+                "resolution": { "type": "string", "description": "可选清晰度，默认 720p。" },
+                "sound": { "type": "string", "description": "是否生成声音，默认 off。" }
+            }, "required": ["prompt"], "additionalProperties": false
+        })
+    }
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send {
+        async move {
+            if args.prompt.trim().is_empty() {
+                return Err(GenerateVideoError::PromptNotProvided);
+            }
+            for id in &args.reference_image_ids {
+                if !self.context.contains_image(id) {
+                    return Err(GenerateVideoError::AssetNotFound(id.clone()));
+                }
+            }
+            Ok(GenerateVideoToolOutput {
+                message: "this tool call is pending user confirmation. if all is pending, just end this turn".to_string(),
+            })
+        }
+    }
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        match error {
+            GenerateVideoError::AssetNotFound(_) => {
+                ToolFailure::new(ToolFailureKind::NotFound, error.to_string())
+            }
+            GenerateVideoError::PromptNotProvided => ToolFailure::invalid_args(error.to_string()),
+        }
+    }
+}
+
+impl GenerateVideoTool {
+    pub const DEFAULT_VIDEO_MODEL: &'static str = "seedance2.0-fast";
+    pub const DEFAULT_VIDEO_RESOLUTION: &'static str = "720p";
+    pub const DEFAULT_VIDEO_DURATION_SECONDS: u32 = 4;
+
+    pub fn format_execute_message(
+        &self,
+        args: &GenerateVideoToolArgs,
+        result: &EditorVideoGenerateResponse,
+    ) -> String {
+        let video_id = ImageId::from_data_key(result.video_src.as_str());
+        format!(
+            "[tool_call:{}] args: {} output: generated video saved as: {}",
+            Self::NAME,
+            serde_json::to_string(args).unwrap_or_default(),
+            video_id
+        )
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/agent/tools/mod.rs b/server-rs/crates/platform-editor-agent/src/agent/tools/mod.rs
new file mode 100644
index 000000000..f3ea99cc1
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/agent/tools/mod.rs
@@ -0,0 +1,9 @@
+pub mod context;
+pub mod edit_image;
+pub mod generate_background_music;
+pub mod generate_character;
+pub mod generate_icon_spritesheet;
+pub mod generate_image;
+pub mod generate_sound_effect;
+pub mod generate_ui_design;
+pub mod generate_video;
diff --git a/server-rs/crates/platform-editor-agent/src/framework/agent.rs b/server-rs/crates/platform-editor-agent/src/framework/agent.rs
new file mode 100644
index 000000000..824123030
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/agent.rs
@@ -0,0 +1,79 @@
+use crate::framework::error::PromptError;
+use crate::framework::hook::Hook;
+use crate::framework::memory::AgentMemory;
+use crate::framework::run::PromptRequest;
+use crate::framework::tool::{Tool, ToolDyn};
+
+pub struct Agent<M: LlmApiAdaptor<Message>, Message> {
+    pub model: M,
+    pub tools: Vec<Box<dyn ToolDyn>>,
+    pub hooks: Vec<Box<dyn Hook>>,
+    pub default_max_turns: usize,
+    pub system_prompt: Option<Message>,
+    pub memory: Option<Box<dyn AgentMemory<Message>>>,
+}
+
+impl<M, Message> Agent<M, Message>
+where
+    M: LlmApiAdaptor<Message> + 'static,
+    Message: Send + 'static,
+{
+    pub fn new(model: M) -> Self {
+        Self {
+            model,
+            tools: Vec::new(),
+            hooks: Vec::new(),
+            default_max_turns: 10,
+            system_prompt: None,
+            memory: None,
+        }
+    }
+
+    pub fn tool(mut self, tool: impl Tool + Send + Sync + 'static) -> Self {
+        self.tools.push(Box::new(tool));
+        self
+    }
+
+    pub fn system_prompt(mut self, msg: Message) -> Self {
+        self.system_prompt = Some(msg);
+        self
+    }
+
+    pub fn memory(mut self, mem: impl AgentMemory<Message> + 'static) -> Self {
+        self.memory = Some(Box::new(mem));
+        self
+    }
+
+    pub fn hook(mut self, hook: impl Hook + 'static) -> Self {
+        self.hooks.push(Box::new(hook));
+        self
+    }
+
+    pub fn max_turns(mut self, n: usize) -> Self {
+        self.default_max_turns = n;
+        self
+    }
+
+    pub fn tools(&self) -> &[Box<dyn ToolDyn>] {
+        &self.tools
+    }
+
+    pub fn prompt(&mut self, message: impl Into<Message> + Send) -> PromptRequest<'_, M, Message>
+    where
+        Message: 'static,
+    {
+        PromptRequest::new(self, message.into())
+    }
+}
+
+pub trait LlmApiAdaptor<Message>: Send + Sync {
+    fn complete<'a>(
+        &self,
+        messages: impl Iterator<Item = &'a Message> + Send,
+    ) -> impl Future<Output = Result<String, PromptError>> + Send
+    where
+        Message: 'a;
+    fn tool_result_message(&self, tool_name: &str, output: &str) -> Message;
+
+    fn build_assistant_message(&self, text: &str) -> Message;
+}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/agent_builder.rs b/server-rs/crates/platform-editor-agent/src/framework/agent_builder.rs
new file mode 100644
index 000000000..f2f90d8cc
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/agent_builder.rs
@@ -0,0 +1,18 @@
+use crate::framework::agent::{Agent, LlmApiAdaptor};
+use crate::framework::hook::Hook;
+use crate::framework::memory::AgentMemory;
+use crate::framework::tool::Tool;
+
+pub trait AgentBuilder<Message, M: LlmApiAdaptor<Message>> {
+    type Client;
+
+    fn new() -> Self;
+    fn with_client(self, client: Self::Client) -> Self;
+    fn system_prompt(self, system_prompt: impl Into<String>) -> Self;
+    fn tool(self, tool: impl Tool + Send + Sync + 'static) -> Self;
+    fn add_hook(self, hook: impl Hook + 'static) -> Self;
+    fn max_turns(self, n: usize) -> Self;
+    fn memory(self, memory: impl AgentMemory<Message> + 'static) -> Self;
+
+    fn build(self) -> Agent<M, Message>;
+}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/error.rs b/server-rs/crates/platform-editor-agent/src/framework/error.rs
new file mode 100644
index 000000000..bc830dbac
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/error.rs
@@ -0,0 +1,22 @@
+#[derive(Debug, Clone)]
+pub enum PromptError {
+    CompletionError(String),
+    ToolError(String),
+    InternalError(String),
+    MaxTurnsReached { max_turns: usize },
+}
+
+impl std::fmt::Display for PromptError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::CompletionError(msg) => write!(f, "completion error: {msg}"),
+            Self::ToolError(msg) => write!(f, "tool error: {msg}"),
+            Self::InternalError(msg) => write!(f, "internal error: {msg}"),
+            Self::MaxTurnsReached { max_turns } => {
+                write!(f, "max turns reached: {max_turns}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for PromptError {}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/hook.rs b/server-rs/crates/platform-editor-agent/src/framework/hook.rs
new file mode 100644
index 000000000..c5fd255a3
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/hook.rs
@@ -0,0 +1,14 @@
+use crate::framework::run::{TextFlow, ToolCallFlow};
+use crate::framework::tool::ToolCall;
+
+pub trait Hook: Send + Sync {
+    fn on_text_reply(&self, _text: &str) -> TextFlow {
+        TextFlow::Continue
+    }
+    fn before_tool_call(&self, _tool_call: &ToolCall) -> ToolCallFlow {
+        ToolCallFlow::Continue
+    }
+    fn after_tool_call(&self, _tool_name: &str, _output: &mut serde_json::Value) -> ToolCallFlow {
+        ToolCallFlow::Continue
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/memory.rs b/server-rs/crates/platform-editor-agent/src/framework/memory.rs
new file mode 100644
index 000000000..3157d7387
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/memory.rs
@@ -0,0 +1,31 @@
+use serde::{Deserialize, Serialize};
+
+pub trait AgentMemory<Message>: Send + Sync {
+    fn get_memory(&self) -> &[Message];
+    fn append_message(&mut self, message: Message);
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VecMemory<Message> {
+    messages: Vec<Message>,
+}
+
+impl<Message> VecMemory<Message> {
+    pub fn new(messages: Vec<Message>) -> Self {
+        Self { messages }
+    }
+
+    pub fn into_inner(self) -> Vec<Message> {
+        self.messages
+    }
+}
+
+impl<Message: Send + Sync> AgentMemory<Message> for VecMemory<Message> {
+    fn get_memory(&self) -> &[Message] {
+        &self.messages
+    }
+
+    fn append_message(&mut self, message: Message) {
+        self.messages.push(message);
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/mod.rs b/server-rs/crates/platform-editor-agent/src/framework/mod.rs
new file mode 100644
index 000000000..0f84bfb15
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/mod.rs
@@ -0,0 +1,7 @@
+pub mod agent;
+pub mod agent_builder;
+pub mod error;
+pub mod hook;
+pub mod memory;
+pub mod run;
+pub mod tool;
diff --git a/server-rs/crates/platform-editor-agent/src/framework/run.rs b/server-rs/crates/platform-editor-agent/src/framework/run.rs
new file mode 100644
index 000000000..2b4a90a1c
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/run.rs
@@ -0,0 +1,278 @@
+use crate::framework::agent::Agent;
+use crate::framework::agent::LlmApiAdaptor;
+use crate::framework::error::PromptError;
+use crate::framework::hook::Hook;
+use crate::framework::memory::VecMemory;
+use crate::framework::run::PromptOutput::{Text, Tool};
+use crate::framework::tool::{ToolCall, ToolDyn, ToolExecutionResult, ToolFailure, ToolOutcome};
+use serde::Deserialize;
+use serde_json::Value;
+use std::pin::Pin;
+
+pub type TextOutput = String;
+
+#[derive(Debug, Clone)]
+pub struct ToolCallOutput {
+    pub tool_call: ToolCall,
+    pub message: String,
+}
+#[derive(Debug, Clone)]
+pub enum PromptOutput {
+    Text(TextOutput),
+    Tool(ToolCallOutput),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TextFlow {
+    Continue,
+    Stop,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolCallFlow {
+    Continue,
+    Skip,
+    Stop,
+}
+
+pub struct PromptRequest<'a, M: LlmApiAdaptor<Message> + 'a, Message: 'a> {
+    agent: &'a mut Agent<M, Message>,
+    message: Message,
+    system_prompt: Option<Message>,
+    hooks: Vec<Box<dyn Hook + 'static>>,
+    max_turns: usize,
+}
+
+impl<'a, M, Message> PromptRequest<'a, M, Message>
+where
+    M: LlmApiAdaptor<Message> + 'a,
+    Message: 'a,
+{
+    pub fn new(agent: &'a mut Agent<M, Message>, message: Message) -> Self {
+        let max_turns = agent.default_max_turns;
+        Self {
+            agent,
+            message,
+            system_prompt: None,
+            hooks: Vec::new(),
+            max_turns,
+        }
+    }
+
+    pub fn system_prompt(mut self, msg: Message) -> Self {
+        self.system_prompt = Some(msg);
+        self
+    }
+
+    pub fn add_hook(mut self, hook: impl Hook + 'static) -> Self {
+        self.hooks.push(Box::new(hook));
+        self
+    }
+
+    pub fn max_turns(mut self, n: usize) -> Self {
+        self.max_turns = n;
+        self
+    }
+}
+
+impl<'a, M, Message> IntoFuture for PromptRequest<'a, M, Message>
+where
+    M: LlmApiAdaptor<Message> + Send + Sync + 'a,
+    Message: Send + Sync + Clone + 'a + 'static,
+{
+    type Output = Result<Vec<PromptOutput>, PromptError>;
+    type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send + 'a>>;
+
+    fn into_future(self) -> Self::IntoFuture {
+        let agent = self.agent;
+        let message = self.message;
+        let extra_hooks = self.hooks;
+        let max_turns = self.max_turns;
+
+        Box::pin(async move {
+            let memory = agent
+                .memory
+                .get_or_insert_with(|| Box::new(VecMemory::new(Vec::new())));
+            memory.append_message(message);
+            let mut prompt_result: Vec<PromptOutput> = Vec::new();
+
+            for _ in 0..max_turns {
+                let text = {
+                    let messages = agent.system_prompt.iter().chain(memory.get_memory().iter());
+                    agent.model.complete(messages).await?
+                };
+
+                // Try to parse the LLM reply as JSON (handle Markdown fences)
+                let cleaned = clean_json_response(&text);
+                match serde_json::from_str::<LlmJsonResponse>(&cleaned) {
+                    Ok(json_resp) => {
+                        let clean_text = json_resp.reply_text.trim().to_string();
+
+                        // Run on_text_reply hooks
+                        for hook in agent.hooks.iter().chain(extra_hooks.iter()) {
+                            match hook.on_text_reply(&clean_text) {
+                                TextFlow::Stop => {
+                                    return Err(PromptError::ToolError(
+                                        "text reply rejected by hook".to_string(),
+                                    ));
+                                }
+                                TextFlow::Continue => {}
+                            }
+                        }
+                        memory.append_message(agent.model.build_assistant_message(&clean_text));
+                        prompt_result.push(Text(clean_text.clone()));
+
+                        let tool_calls: Vec<ToolCall> = json_resp
+                            .tool_calls
+                            .into_iter()
+                            .enumerate()
+                            .map(|(idx, tc)| ToolCall {
+                                id: format!("{idx}"),
+                                name: tc.tool_name,
+                                args: tc.args,
+                            })
+                            .collect();
+
+                        // no tool call, turn terminate.
+                        if tool_calls.is_empty() {
+                            return Ok(prompt_result);
+                        }
+
+                        for (tc_id, tc) in tool_calls.iter().enumerate() {
+                            // inline run_hooks: before_tool_call hook
+                            let mut should_skip = false;
+                            for hook in agent.hooks.iter().chain(extra_hooks.iter()) {
+                                match hook.before_tool_call(tc) {
+                                    ToolCallFlow::Stop => {
+                                        return Err(PromptError::ToolError(
+                                            "tool call rejected by hook".to_string(),
+                                        ));
+                                    }
+                                    ToolCallFlow::Skip => {
+                                        let msg = agent
+                                            .model
+                                            .tool_result_message(&tc.name, "(skipped by hook)");
+                                        memory.append_message(msg);
+                                        should_skip = true;
+                                        break;
+                                    }
+                                    ToolCallFlow::Continue => {}
+                                }
+                            }
+                            if should_skip {
+                                continue;
+                            }
+
+                            let result = {
+                                let tools: Vec<&Box<dyn ToolDyn>> = agent.tools.iter().collect();
+                                let name = tc.name.clone();
+                                let args = tc.args.clone();
+                                let fut = async move {
+                                    match tools.iter().find(|tool| tool.tool_name() == name) {
+                                        Some(tool) => tool.call(args).await,
+                                        None => ToolExecutionResult::failed(
+                                            Value::Null,
+                                            ToolFailure::invalid_args(format!(
+                                                "unknown tool: {name}"
+                                            )),
+                                        ),
+                                    }
+                                };
+                                fut.await
+                            };
+
+                            match result.outcome {
+                                ToolOutcome::InternalOk => {
+                                    let mut json_output = result.output;
+                                    // Run after_tool_call hooks to allow output modification
+                                    for hook in agent.hooks.iter().chain(extra_hooks.iter()) {
+                                        match hook.after_tool_call(&tc.name, &mut json_output) {
+                                            ToolCallFlow::Stop => {
+                                                return Err(PromptError::ToolError(
+                                                    "tool call output caused this _turn stopped by hook".to_string(),
+                                                ));
+                                            }
+                                            ToolCallFlow::Skip => {
+                                                json_output = serde_json::json!({"message":"tool call is ignored by hook"});
+                                                break;
+                                            }
+                                            ToolCallFlow::Continue => {}
+                                        }
+                                    }
+                                    let arg_json = serde_json::to_string(&tc.args)
+                                        .map_err(|e| PromptError::InternalError(e.to_string()))?;
+                                    let output_json = serde_json::to_string(&json_output)
+                                        .map_err(|e| PromptError::InternalError(e.to_string()))?;
+
+                                    let overall_message = format!(
+                                        "[tool_call:{tc_id}] args: {arg_json} output: {output_json}"
+                                    );
+                                    let msg =
+                                        agent.model.tool_result_message(&tc.name, &overall_message);
+                                    memory.append_message(msg);
+                                    prompt_result.push(Tool(ToolCallOutput {
+                                        tool_call: tc.clone(),
+                                        message: overall_message.clone(),
+                                    }))
+                                }
+                                ToolOutcome::InternalError(failure) if failure.fatal => {
+                                    return Err(PromptError::ToolError(failure.message));
+                                }
+                                ToolOutcome::InternalError(failure) => {
+                                    let msg = agent.model.tool_result_message(
+                                        &tc.name,
+                                        &format!("error: {}", failure.message),
+                                    );
+                                    memory.append_message(msg);
+                                }
+                            }
+                        }
+                    }
+                    Err(_) => {
+                        // Not valid JSON — push as assistant message and continue to next _turn
+                        memory.append_message(agent.model.build_assistant_message(&text));
+                        continue;
+                    }
+                }
+            }
+
+            Err(PromptError::MaxTurnsReached { max_turns })
+        })
+    }
+}
+
+#[derive(Deserialize)]
+struct LlmJsonResponse {
+    reply_text: String,
+    #[serde(default)]
+    tool_calls: Vec<LlmToolCallRequest>,
+}
+
+#[derive(Deserialize)]
+struct LlmToolCallRequest {
+    tool_name: String,
+    #[serde(default)]
+    args: Value,
+}
+
+pub fn clean_json_response(text: &str) -> String {
+    let text = text.trim();
+    if text.starts_with("```") {
+        let lines: Vec<&str> = text.lines().collect();
+        let mut cleaned = Vec::new();
+        let mut in_code = false;
+        for line in lines {
+            if line.trim().starts_with("```") {
+                in_code = !in_code;
+                continue;
+            }
+            if in_code {
+                cleaned.push(line);
+            }
+        }
+        if !cleaned.is_empty() {
+            return cleaned.join("\n").trim().to_string();
+        }
+    }
+    text.to_string()
+}
diff --git a/server-rs/crates/platform-editor-agent/src/framework/tool.rs b/server-rs/crates/platform-editor-agent/src/framework/tool.rs
new file mode 100644
index 000000000..386a9ed36
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/framework/tool.rs
@@ -0,0 +1,206 @@
+use serde::{Deserialize, Serialize};
+use std::pin::Pin;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolCall {
+    pub id: String,
+    pub name: String,
+    pub args: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ToolCallResult {
+    pub tool_name: String,
+    pub output: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToolFailureKind {
+    InvalidArgs,
+    Timeout,
+    Cancelled,
+    NotFound,
+    PermissionDenied,
+    RateLimited,
+    Provider,
+    Network,
+    Internal,
+    Other,
+}
+
+impl ToolFailureKind {
+    pub fn default_retryable(self) -> bool {
+        matches!(
+            self,
+            Self::Timeout | Self::RateLimited | Self::Provider | Self::Network
+        )
+    }
+
+    pub fn default_fatal(self) -> bool {
+        matches!(self, Self::Internal)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ToolFailure {
+    pub kind: ToolFailureKind,
+    pub message: String,
+    pub retryable: bool,
+    pub fatal: bool,
+}
+
+impl ToolFailure {
+    pub fn new(kind: ToolFailureKind, message: impl Into<String>) -> Self {
+        Self {
+            kind,
+            message: message.into(),
+            retryable: kind.default_retryable(),
+            fatal: kind.default_fatal(),
+        }
+    }
+
+    pub fn invalid_args(message: impl Into<String>) -> Self {
+        Self::new(ToolFailureKind::InvalidArgs, message)
+    }
+
+    pub fn internal(message: impl Into<String>) -> Self {
+        Self::new(ToolFailureKind::Internal, message)
+    }
+
+    pub fn other(message: impl Into<String>) -> Self {
+        Self::new(ToolFailureKind::Other, message)
+    }
+
+    pub fn with_retryable(mut self, retryable: bool) -> Self {
+        self.retryable = retryable;
+        self
+    }
+
+    pub fn with_fatal(mut self, fatal: bool) -> Self {
+        self.fatal = fatal;
+        self
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum ToolOutcome {
+    InternalOk,
+    InternalError(ToolFailure),
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolExecutionResult {
+    pub output: serde_json::Value,
+    pub outcome: ToolOutcome,
+}
+
+impl ToolExecutionResult {
+    pub fn success(output: serde_json::Value) -> Self {
+        Self {
+            output,
+            outcome: ToolOutcome::InternalOk,
+        }
+    }
+
+    pub fn failed(output: serde_json::Value, failure: ToolFailure) -> Self {
+        Self {
+            output,
+            outcome: ToolOutcome::InternalError(failure),
+        }
+    }
+
+    pub fn failure(&self) -> Option<&ToolFailure> {
+        match &self.outcome {
+            ToolOutcome::InternalOk => None,
+            ToolOutcome::InternalError(failure) => Some(failure),
+        }
+    }
+
+    pub fn is_fatal(&self) -> bool {
+        self.failure().is_some_and(|failure| failure.fatal)
+    }
+}
+
+pub trait Tool: Sized {
+    const NAME: &'static str;
+    type Error: std::error::Error + 'static;
+    type Args: for<'a> Deserialize<'a>;
+    type Output: Serialize;
+
+    fn tool_name(&self) -> &'static str {
+        Self::NAME
+    }
+
+    /// Human-readable description of what the tool does.
+    fn description(&self) -> String;
+    /// JSON Schema describing the tool's parameters.
+    fn parameters(&self) -> serde_json::Value;
+    fn call(
+        &self,
+        args: Self::Args,
+    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send;
+
+    fn classify_error(&self, error: &Self::Error) -> ToolFailure {
+        ToolFailure::other(error.to_string())
+    }
+}
+
+/// Wrapper trait to allow for dynamic dispatch of simple tools.
+pub trait ToolDyn: Send + Sync {
+    fn tool_name(&self) -> &'static str;
+    fn description(&self) -> String;
+    fn parameters(&self) -> serde_json::Value;
+    fn call(
+        &self,
+        args: serde_json::Value,
+    ) -> Pin<Box<dyn Future<Output = ToolExecutionResult> + Send + '_>>;
+}
+
+impl<T: Tool + Send + Sync> ToolDyn for T {
+    fn tool_name(&self) -> &'static str {
+        T::NAME
+    }
+
+    fn description(&self) -> String {
+        self.description()
+    }
+
+    fn parameters(&self) -> serde_json::Value {
+        self.parameters()
+    }
+
+    fn call(
+        &self,
+        args: serde_json::Value,
+    ) -> Pin<Box<dyn Future<Output = ToolExecutionResult> + Send + '_>> {
+        Box::pin(async move {
+            let parsed: T::Args = match serde_json::from_value(args) {
+                Ok(parsed) => parsed,
+                Err(error) => {
+                    return ToolExecutionResult::failed(
+                        serde_json::Value::Null,
+                        ToolFailure::invalid_args(format!("bad args for {}: {error}", T::NAME)),
+                    );
+                }
+            };
+
+            let output = match self.call(parsed).await {
+                Ok(output) => output,
+                Err(error) => {
+                    return ToolExecutionResult::failed(
+                        serde_json::Value::Null,
+                        self.classify_error(&error),
+                    );
+                }
+            };
+
+            match serde_json::to_value(&output) {
+                Ok(output) => ToolExecutionResult::success(output),
+                Err(error) => ToolExecutionResult::failed(
+                    serde_json::Value::Null,
+                    ToolFailure::internal(error.to_string()),
+                ),
+            }
+        })
+    }
+}
diff --git a/server-rs/crates/platform-editor-agent/src/lib.rs b/server-rs/crates/platform-editor-agent/src/lib.rs
new file mode 100644
index 000000000..9bfb25278
--- /dev/null
+++ b/server-rs/crates/platform-editor-agent/src/lib.rs
@@ -0,0 +1,2 @@
+pub mod agent;
+pub mod framework;
diff --git a/server-rs/crates/platform-image/src/vector_engine/request.rs b/server-rs/crates/platform-image/src/vector_engine/request.rs
index e67771f15..91d6075c4 100644
--- a/server-rs/crates/platform-image/src/vector_engine/request.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/request.rs
@@ -370,4 +370,33 @@ mod tests {
         assert!(!serialized.contains("Bearer"));
         assert!(!serialized.contains("[1,2,3,4,5]"));
     }
+
+    #[test]
+    fn gpt_image_2_request_keeps_direct_1k_and_2k_pixel_sizes() {
+        for expected_size in [
+            "1024x1024",
+            "1024x768",
+            "1024x688",
+            "688x1024",
+            "608x1088",
+            "1088x608",
+            "2048x2048",
+            "2048x1536",
+            "2048x1376",
+            "1376x2048",
+            "1152x2048",
+            "2048x1152",
+        ] {
+            let body = build_vector_engine_image_request_body_with_model(
+                GPT_IMAGE_2_MODEL,
+                "测试",
+                None,
+                expected_size,
+                1,
+                &[],
+            );
+
+            assert_eq!(body["size"], expected_size);
+        }
+    }
 }
diff --git a/server-rs/crates/platform-matting/Cargo.toml b/server-rs/crates/platform-matting/Cargo.toml
index 87a387af0..eacc33dad 100644
--- a/server-rs/crates/platform-matting/Cargo.toml
+++ b/server-rs/crates/platform-matting/Cargo.toml
@@ -5,13 +5,10 @@ version.workspace = true
 license.workspace = true
 
 [dependencies]
-base64 = { workspace = true }
 hmac = { workspace = true }
 hex = { workspace = true }
-httpdate = { workspace = true }
 image = { workspace = true, features = ["png", "jpeg", "webp"] }
-sha1 = { workspace = true }
-reqwest = { workspace = true, features = ["json", "rustls-tls"] }
+reqwest = { workspace = true, features = ["json", "multipart", "rustls-tls"] }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_urlencoded = { workspace = true }
diff --git a/server-rs/crates/platform-matting/examples/segment_smoke.rs b/server-rs/crates/platform-matting/examples/segment_smoke.rs
index a0c817402..ba684b9a5 100644
--- a/server-rs/crates/platform-matting/examples/segment_smoke.rs
+++ b/server-rs/crates/platform-matting/examples/segment_smoke.rs
@@ -1,9 +1,12 @@
-//! 通用抠图冒烟验证：本地图片 → OSS → SegmentCommonImage → 下载结果。
+//! 通用抠图冒烟验证：本地图片 → AuthorizeFileUpload 临时对象 → SegmentCommonImage → 下载结果。
 //!
 //! 运行（在 server-rs 目录下）：
 //! cargo run -p platform-matting --example segment_smoke -- "C:\path\to\input.png"
 //!
-//! 依赖仓库根目录 .env.local（OSS bucket/endpoint）与 .env.secrets.local（AK/SK）。
+//! 依赖仓库根目录 .env / .env.local / .env.secrets.local 中的 AK/SK
+//!（`GENARRATIVE_ALIYUN_MATTING_*` 或 `ALIBABA_CLOUD_ACCESS_KEY_*`）；
+//! 可选 `GENARRATIVE_ALIYUN_MATTING_ENDPOINT`。临时 OSS bucket/endpoint 由
+//! AuthorizeFileUpload 动态下发，不依赖自有 OSS 配置。
 
 use std::path::{Path, PathBuf};
 
@@ -67,17 +70,16 @@ async fn main() {
     let http_client = reqwest::Client::new();
 
     // --- 调用通用抠图 ---
-    // key 优先级：VIAPI 专用 → 官方 SDK 标准命名（#IMAGE_CALL）→ 短信 key 兜底。
+    // key 优先级与 api-server 配置保持一致：抠图专用 → 官方 SDK 标准命名。
     let (matting_key_id, matting_key_secret) = [
         (
-            "ALIYUN_IMAGESEG_ACCESS_KEY_ID",
-            "ALIYUN_IMAGESEG_ACCESS_KEY_SECRET",
+            "GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID",
+            "GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET",
         ),
         (
             "ALIBABA_CLOUD_ACCESS_KEY_ID",
             "ALIBABA_CLOUD_ACCESS_KEY_SECRET",
         ),
-        ("ALIYUN_SMS_ACCESS_KEY_ID", "ALIYUN_SMS_ACCESS_KEY_SECRET"),
     ]
     .iter()
     .find_map(|(id_name, secret_name)| {
@@ -91,7 +93,7 @@ async fn main() {
     })
     .expect("未找到可用的抠图 AccessKey 环境变量");
     let matting_config = MattingConfig::new(
-        std::env::var("ALIYUN_IMAGESEG_ENDPOINT")
+        std::env::var("GENARRATIVE_ALIYUN_MATTING_ENDPOINT")
             .unwrap_or_else(|_| DEFAULT_IMAGESEG_ENDPOINT.to_string()),
         matting_key_id,
         matting_key_secret,
@@ -99,12 +101,12 @@ async fn main() {
     .expect("抠图配置应有效");
     let matting_client = MattingClient::new(matting_config).expect("抠图客户端应可构建");
 
-    // 本地 OSS 在北京地域，抠图服务要求上海地域，走 VIAPI 官方临时桶上传。
+    // 非上海地域输入按新版官方 SDK 的 AdvanceRequest 口径申请单对象 Policy 后上传。
     let temp_url = matting_client
         .upload_temp_image(input_bytes, "segment-input.png", "image/png")
         .await
-        .expect("上传 VIAPI 临时桶应成功");
-    println!("[2/5] 已上传 VIAPI 临时桶");
+        .expect("上传 AuthorizeFileUpload 临时对象应成功");
+    println!("[2/5] 已上传 AuthorizeFileUpload 临时对象");
     println!("[3/5] 输入图 URL host：{}", host_of(&temp_url));
 
     let result = matting_client
diff --git a/server-rs/crates/platform-matting/src/lib.rs b/server-rs/crates/platform-matting/src/lib.rs
index 854fafb19..b4f78d192 100644
--- a/server-rs/crates/platform-matting/src/lib.rs
+++ b/server-rs/crates/platform-matting/src/lib.rs
@@ -18,14 +18,12 @@ pub const DEFAULT_IMAGESEG_ENDPOINT: &str = "imageseg.cn-shanghai.aliyuncs.com";
 const IMAGESEG_API_VERSION: &str = "2019-12-30";
 const SEGMENT_COMMON_IMAGE_ACTION: &str = "SegmentCommonImage";
 
-// VIAPI 官方临时上传通道：抠图输入统一先传官方临时桶（1 天自动过期，无需清理；
-// 全用户共享 QPS）。抠图服务只认上海地域 OSS URL，而我们没有上海地域自有 OSS。
-// 文档：https://help.aliyun.com/document_detail/155645.html
-const VIAPI_UTILS_ENDPOINT: &str = "viapiutils.cn-shanghai.aliyuncs.com";
-const VIAPI_UTILS_VERSION: &str = "2020-04-01";
-const GET_OSS_STS_TOKEN_ACTION: &str = "GetOssStsToken";
-const VIAPI_TEMP_BUCKET: &str = "viapi-customer-temp";
-const VIAPI_TEMP_OSS_HOST: &str = "viapi-customer-temp.oss-cn-shanghai.aliyuncs.com";
+// VIAPI 新版官方 SDK 的 AdvanceRequest 上传通道：先向 Open Platform 申请单对象
+// Policy，再 multipart POST 到授权返回的上海地域临时 OSS。
+const OPEN_PLATFORM_ENDPOINT: &str = "openplatform.aliyuncs.com";
+const AUTHORIZE_FILE_UPLOAD_ACTION: &str = "AuthorizeFileUpload";
+const AUTHORIZE_FILE_UPLOAD_VERSION: &str = "2019-12-19";
+const IMAGESEG_PRODUCT: &str = "imageseg";
 
 pub const DEFAULT_MATTING_REQUEST_TIMEOUT_MS: u64 = 30_000;
 
@@ -142,10 +140,20 @@ pub struct SegmentCommonImageResult {
 pub enum MattingError {
     InvalidConfig(String),
     InvalidRequest(String),
+    LocalProcessing(LocalProcessingFailure),
     Sign(String),
     Upstream(UpstreamFailure),
 }
 
+/// 外部调用已经开始，但本地处理阶段失败。
+///
+/// 这类错误仍然需要进入外部失败审计，但不能被误标成上游 HTTP / 传输故障。
+#[derive(Debug)]
+pub struct LocalProcessingFailure {
+    message: String,
+    failure_stage: &'static str,
+}
+
 /// 结构化的上游调用失败分类。协议层归属（是否传输层故障、是否超时、上游 HTTP 状态）由
 /// platform-matting 在错误发生处直接捕获，调用方（api-server BFF）不再从中文 message 反推。
 #[derive(Debug)]
@@ -157,6 +165,7 @@ pub struct UpstreamFailure {
     transport: bool,
     /// 上游返回的 HTTP 状态码；`None` 表示没拿到状态（传输层故障或响应体不可用）。
     upstream_status: Option<u16>,
+    failure_stage: &'static str,
 }
 
 impl MattingError {
@@ -165,14 +174,17 @@ impl MattingError {
             Self::InvalidConfig(message) | Self::InvalidRequest(message) | Self::Sign(message) => {
                 message
             }
+            Self::LocalProcessing(failure) => &failure.message,
             Self::Upstream(failure) => &failure.message,
         }
     }
 
-    /// 是否真正向阿里云发起过外部调用。`InvalidConfig` / `InvalidRequest` / `Sign` 都是发请求前的
-    /// 本地预检失败，未触达上游。
+    /// 是否已经开始外部调用链路。
+    ///
+    /// `LocalProcessing` 表示外部调用已经开始，但解码、尺寸校验或其它本地处理失败；它不能
+    /// 与真正发请求前的 `InvalidConfig` / `InvalidRequest` / `Sign` 混为一谈。
     pub fn external_call_attempted(&self) -> bool {
-        matches!(self, Self::Upstream(_))
+        matches!(self, Self::LocalProcessing(_) | Self::Upstream(_))
     }
 
     /// 上游调用是否为传输层超时。
@@ -193,6 +205,35 @@ impl MattingError {
         }
     }
 
+    /// 失败发生阶段，供 api-server 生成准确的外部失败审计 metadata。
+    pub fn failure_stage(&self) -> &'static str {
+        match self {
+            Self::InvalidConfig(_) | Self::InvalidRequest(_) | Self::Sign(_) => "preflight",
+            Self::LocalProcessing(failure) => failure.failure_stage,
+            Self::Upstream(failure) => failure.failure_stage,
+        }
+    }
+
+    /// 将一个已经发生外部调用后的本地错误转换为可审计的处理失败。
+    pub fn with_failure_stage(self, failure_stage: &'static str) -> Self {
+        match self {
+            Self::InvalidConfig(message) | Self::InvalidRequest(message) | Self::Sign(message) => {
+                Self::LocalProcessing(LocalProcessingFailure {
+                    message,
+                    failure_stage,
+                })
+            }
+            Self::LocalProcessing(mut failure) => {
+                failure.failure_stage = failure_stage;
+                Self::LocalProcessing(failure)
+            }
+            Self::Upstream(mut failure) => {
+                failure.failure_stage = failure_stage;
+                Self::Upstream(failure)
+            }
+        }
+    }
+
     /// 传输层故障构造器：请求已发出但没拿到有效 HTTP 响应（连接、读体、超时）。
     pub fn upstream_transport_error(message: String, timeout: bool) -> Self {
         Self::Upstream(UpstreamFailure {
@@ -200,6 +241,7 @@ impl MattingError {
             timeout,
             transport: true,
             upstream_status: None,
+            failure_stage: "aliyun_segment",
         })
     }
 
@@ -210,6 +252,7 @@ impl MattingError {
             timeout: false,
             transport: false,
             upstream_status: Some(status),
+            failure_stage: "aliyun_segment",
         })
     }
 
@@ -221,6 +264,7 @@ impl MattingError {
             timeout: false,
             transport: false,
             upstream_status,
+            failure_stage: "aliyun_segment",
         })
     }
 }
@@ -383,74 +427,158 @@ impl MattingClient {
         })
     }
 
-    /// 图片字节 → 通用抠图 → 原尺寸透明 PNG 字节。
+    /// 私有 OSS 签名 URL → 下载 → AuthorizeFileUpload 临时对象 → 通用抠图 → 透明 PNG。
     ///
-    /// - 输入统一上传 VIAPI 官方临时桶（1 天自动过期，无需清理）后作为 ImageURL 送抠。
-    /// - 分辨率守卫：任一边 >= 2000 时先等比缩小送抠，抠完只取结果 alpha 上采样回贴
-    ///   原图 RGB，保证输出与输入同尺寸、画质无损。
-    pub async fn segment_image_to_transparent_png(
+    /// 源图下载缓冲和解码图只活到临时对象上传完成；若输入发生过降尺寸，结果返回后再单独下载
+    /// 一次源图完成 Alpha 回贴，避免在整个阿里云推理期间常驻原图内存。
+    pub async fn segment_image_url_to_transparent_png(
         &self,
-        bytes: &[u8],
+        source_url: &str,
         file_name: &str,
     ) -> Result<Vec<u8>, MattingError> {
-        let source = decode_source_image(bytes)?;
-        let source_rgba = source.to_rgba8();
-        let (source_width, source_height) = source_rgba.dimensions();
-
-        // 阿里云要求每条边 > 32px；过小的图直接拒绝，让调用方走本地兜底，省一次注定 4xx 的往返。
-        if source_width <= MIN_INPUT_EDGE || source_height <= MIN_INPUT_EDGE {
-            return Err(MattingError::InvalidRequest(format!(
-                "待抠图图片尺寸 {source_width}x{source_height} 过小，阿里云通用抠图要求每条边大于 {MIN_INPUT_EDGE} 像素"
-            )));
+        let source_url = source_url.trim();
+        if source_url.is_empty() {
+            return Err(MattingError::InvalidRequest(
+                "待抠图源图 URL 不能为空".to_string(),
+            ));
         }
 
-        // 归一化成阿里云 SegmentCommonImage 接受的输入：统一 8 位 RGBA PNG（消除 MIME 名不副实
-        // 与不支持位深/格式的问题）、最长边 ≤1999、体积 ≤3MB。返回实际上传尺寸，用于判断结果
-        // 是否需要 alpha 上采样回原尺寸。
-        let (upload_bytes, upload_dims) = normalize_matting_input_png(&source)?;
-        let downscaled = upload_dims != (source_width, source_height);
-        let image_url = self
-            .upload_temp_image(upload_bytes, file_name, "image/png")
-            .await?;
+        let (source_dims, upload_dims, image_url) = {
+            let source_bytes = self
+                .download_source_image(source_url)
+                .await
+                .map_err(|error| error.with_failure_stage("source_download"))?;
+            let source = decode_source_image(&source_bytes)
+                .map_err(|error| error.with_failure_stage("source_decode"))?;
+            let source_dims = (source.width(), source.height());
+            validate_source_dimensions(source_dims)
+                .map_err(|error| error.with_failure_stage("source_validate"))?;
+            let (upload_bytes, upload_dims) = normalize_matting_input_png(&source)
+                .map_err(|error| error.with_failure_stage("source_normalize"))?;
+            let image_url = self
+                .upload_temp_image(upload_bytes, file_name, "image/png")
+                .await
+                .map_err(|error| error.with_failure_stage("temp_upload"))?;
+            (source_dims, upload_dims, image_url)
+        };
 
+        let result_image = self
+            .segment_uploaded_input_to_rgba(image_url, source_dims, upload_dims)
+            .await?;
+        if upload_dims == source_dims {
+            return encode_rgba_png(&result_image)
+                .map_err(|error| error.with_failure_stage("result_encode"));
+        }
+
+        // 只有降尺寸送抠时才重新下载源图恢复原始 RGB；第一次下载缓冲已在上传临时对象后释放。
+        let source_rgba = {
+            let source_bytes = self
+                .download_source_image(source_url)
+                .await
+                .map_err(|error| error.with_failure_stage("source_download"))?;
+            let source = decode_source_image(&source_bytes)
+                .map_err(|error| error.with_failure_stage("source_decode"))?;
+            if (source.width(), source.height()) != source_dims {
+                return Err(MattingError::upstream_response_error(
+                    "待抠图源图在处理期间尺寸发生变化".to_string(),
+                    None,
+                )
+                .with_failure_stage("source_validate"));
+            }
+            source.to_rgba8()
+        };
+        compose_source_with_result_alpha(source_rgba, result_image)
+            .map_err(|error| error.with_failure_stage("result_encode"))
+    }
+
+    async fn segment_uploaded_input_to_rgba(
+        &self,
+        image_url: String,
+        source_dims: (u32, u32),
+        upload_dims: (u32, u32),
+    ) -> Result<image::RgbaImage, MattingError> {
         let result = self
             .segment_common_image(SegmentCommonImageRequest {
                 image_url,
                 // 默认 ReturnForm：原尺寸 + 透明背景，无需本地合成。
                 return_form: None,
             })
-            .await?;
-        let result_bytes = self.download_result_image(&result.image_url).await?;
-        let result_image = decode_result_image(&result_bytes)?.to_rgba8();
+            .await
+            .map_err(|error| error.with_failure_stage("aliyun_segment"))?;
+        let result_image = {
+            let result_bytes = self
+                .download_result_image(&result.image_url)
+                .await
+                .map_err(|error| error.with_failure_stage("result_download"))?;
+            decode_result_image(&result_bytes)
+                .map_err(|error| error.with_failure_stage("result_decode"))?
+                .to_rgba8()
+        };
+        if upload_dims == source_dims && result_image.dimensions() != source_dims {
+            return Err(MattingError::upstream_response_error(
+                format!(
+                    "抠图结果尺寸 {}x{} 与输入 {}x{} 不一致",
+                    result_image.width(),
+                    result_image.height(),
+                    source_dims.0,
+                    source_dims.1
+                ),
+                None,
+            )
+            .with_failure_stage("result_validate"));
+        }
+        Ok(result_image)
+    }
 
-        if !downscaled {
-            if result_image.dimensions() != (source_width, source_height) {
-                return Err(MattingError::upstream_response_error(
-                    format!(
-                        "抠图结果尺寸 {}x{} 与输入 {}x{} 不一致",
-                        result_image.width(),
-                        result_image.height(),
-                        source_width,
-                        source_height
-                    ),
-                    None,
-                ));
+    async fn download_source_image(&self, url: &str) -> Result<Vec<u8>, MattingError> {
+        let mut response = self.client.get(url).send().await.map_err(|error| {
+            MattingError::upstream_transport_error(
+                format!(
+                    "下载待抠图源图失败（transport={}, timeout={}, connect={}）",
+                    classify_reqwest_error(&error),
+                    error.is_timeout(),
+                    error.is_connect()
+                ),
+                error.is_timeout(),
+            )
+        })?;
+        let status = response.status();
+        if !status.is_success() {
+            return Err(MattingError::upstream_http_error(
+                format!("下载待抠图源图失败（HTTP {}）", status.as_u16()),
+                status.as_u16(),
+            ));
+        }
+        if response
+            .content_length()
+            .is_some_and(|length| length > MAX_RESULT_RESPONSE_BYTES as u64)
+        {
+            return Err(source_response_too_large_error());
+        }
+        let mut bytes = Vec::new();
+        while let Some(chunk) = response.chunk().await.map_err(|error| {
+            MattingError::upstream_transport_error(
+                format!(
+                    "读取待抠图源图失败（transport={}, timeout={}, connect={}）",
+                    classify_reqwest_error(&error),
+                    error.is_timeout(),
+                    error.is_connect()
+                ),
+                error.is_timeout(),
+            )
+        })? {
+            if bytes.len().saturating_add(chunk.len()) > MAX_RESULT_RESPONSE_BYTES {
+                return Err(source_response_too_large_error());
             }
-            return encode_rgba_png(&result_image);
+            bytes.extend_from_slice(chunk.as_ref());
         }
-
-        // 缩图送抠的场景：只取结果 alpha，上采样回原尺寸后贴回原图 RGB。
-        let alpha_mask = image::DynamicImage::ImageRgba8(result_image).resize_exact(
-            source_width,
-            source_height,
-            image::imageops::FilterType::Triangle,
-        );
-        let alpha_mask = alpha_mask.to_rgba8();
-        let mut output = source_rgba;
-        for (target, mask) in output.pixels_mut().zip(alpha_mask.pixels()) {
-            target.0[3] = target.0[3].min(mask.0[3]);
+        if bytes.is_empty() {
+            return Err(MattingError::upstream_response_error(
+                "待抠图源图为空".to_string(),
+                Some(status.as_u16()),
+            ));
         }
-        encode_rgba_png(&output)
+        Ok(bytes)
     }
 
     async fn download_result_image(&self, url: &str) -> Result<Vec<u8>, MattingError> {
@@ -490,8 +618,8 @@ impl MattingClient {
         Ok(bytes)
     }
 
-    /// 把本地图片字节上传到 VIAPI 官方临时桶，返回可直接作为 ImageURL 的公网地址。
-    /// 抠图输入的统一上传通道（我们没有上海地域自有 OSS，临时桶 1 天自动过期无需清理）。
+    /// 按 VIAPI 新版官方 SDK 的 AdvanceRequest 协议，把本地图片字节上传到授权的
+    /// 上海地域临时 OSS，返回可直接作为 ImageURL 的公网地址。
     pub async fn upload_temp_image(
         &self,
         bytes: Vec<u8>,
@@ -501,162 +629,92 @@ impl MattingClient {
         if bytes.is_empty() {
             return Err(MattingError::InvalidRequest("上传内容不能为空".to_string()));
         }
-        let sts = self.get_oss_sts_token().await?;
         let file_name = file_name.trim().trim_matches('/');
         if file_name.is_empty() {
             return Err(MattingError::InvalidRequest(
                 "file_name 不能为空".to_string(),
             ));
         }
-        // 阿里云要求 ImageURL 不含中文/非 ASCII 字符；object 叶子名只保留 URL 安全的 ASCII 字符，
-        // 唯一性由前缀 uuid 保证。
-        let safe_file_name: String = file_name
-            .chars()
-            .map(|c| {
-                if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
-                    c
-                } else {
-                    '_'
-                }
-            })
-            .collect();
-        let object_key = format!(
-            "{}/{}/{}",
-            self.config.access_key_id,
-            uuid::Uuid::new_v4().simple(),
-            safe_file_name
-        );
-        let date = httpdate::fmt_http_date(std::time::SystemTime::now());
-        // OSS V1 头签名（带 STS security token）。
-        let string_to_sign = format!(
-            "PUT\n\n{content_type}\n{date}\nx-oss-security-token:{}\n/{VIAPI_TEMP_BUCKET}/{object_key}",
-            sts.security_token
-        );
-        let signature =
-            hmac_sha1_base64(sts.access_key_secret.as_bytes(), string_to_sign.as_bytes())?;
-        let authorization = format!("OSS {}:{}", sts.access_key_id, signature);
-
-        let target_url = format!("https://{VIAPI_TEMP_OSS_HOST}/{object_key}");
+        let authorized = self.authorize_file_upload().await?;
+        let upload_host = format!("{}.{}", authorized.bucket, authorized.endpoint);
+        let target_url = format!("https://{upload_host}");
+        let file_part = reqwest::multipart::Part::bytes(bytes)
+            .file_name(file_name.to_string())
+            .mime_str(content_type)
+            .map_err(|error| {
+                MattingError::InvalidRequest(format!("上传内容类型不合法：{error}"))
+            })?;
+        let form = reqwest::multipart::Form::new()
+            .text("OSSAccessKeyId", authorized.access_key_id.clone())
+            .text("policy", authorized.encoded_policy.clone())
+            .text("Signature", authorized.signature.clone())
+            .text("key", authorized.object_key.clone())
+            .text("success_action_status", "201")
+            .part("file", file_part);
         let response = self
             .client
-            .put(&target_url)
-            .header(reqwest::header::CONTENT_TYPE, content_type)
-            .header(reqwest::header::DATE, &date)
-            .header("x-oss-security-token", &sts.security_token)
-            .header(reqwest::header::AUTHORIZATION, &authorization)
-            .body(bytes)
+            .post(&target_url)
+            .multipart(form)
             .send()
             .await
             .map_err(|error| {
                 MattingError::upstream_transport_error(
-                    format!("上传 VIAPI 临时桶请求失败：{error}"),
+                    format!("上传 AuthorizeFileUpload 临时对象请求失败：{error}"),
                     error.is_timeout(),
                 )
             })?;
         let status = response.status();
         if !status.is_success() {
             let body = response.text().await.unwrap_or_default();
-            // OSS 签名类错误体会回显 StringToSign（含 x-oss-security-token 明文）、StringToSignBytes
-            // 和 SignatureProvided；脱敏后再记录，避免 STS 临时凭证进审计元数据与日志。
             return Err(MattingError::upstream_http_error(
                 format!(
-                    "上传 VIAPI 临时桶失败（HTTP {}）：{}",
+                    "上传 AuthorizeFileUpload 临时对象失败（HTTP {}）：{}",
                     status.as_u16(),
-                    sanitize_oss_upload_error_body(&body, &sts.security_token)
+                    sanitize_policy_upload_error_body(&body, &authorized)
                 ),
                 status.as_u16(),
             ));
         }
 
-        Ok(target_url)
+        Ok(format!(
+            "https://{upload_host}/{}",
+            encode_oss_object_key(&authorized.object_key)
+        ))
     }
 
-    async fn get_oss_sts_token(&self) -> Result<ViapiStsToken, MattingError> {
-        let mut form = BTreeMap::new();
-        form.insert("Action".to_string(), GET_OSS_STS_TOKEN_ACTION.to_string());
-        form.insert("Format".to_string(), "json".to_string());
-        form.insert("Version".to_string(), VIAPI_UTILS_VERSION.to_string());
-        let payload = build_aliyun_form_body(&form);
-        let headers = self.build_acs3_headers(
-            VIAPI_UTILS_ENDPOINT,
-            GET_OSS_STS_TOKEN_ACTION,
-            VIAPI_UTILS_VERSION,
-            &payload,
+    async fn authorize_file_upload(&self) -> Result<AuthorizedFileUpload, MattingError> {
+        let canonical_query = format!("Product={IMAGESEG_PRODUCT}");
+        let headers = self.build_acs3_headers_for_request(
+            OPEN_PLATFORM_ENDPOINT,
+            AUTHORIZE_FILE_UPLOAD_ACTION,
+            AUTHORIZE_FILE_UPLOAD_VERSION,
+            "GET",
+            &canonical_query,
+            "",
         )?;
 
         let response = self
             .client
-            .post(format!("https://{VIAPI_UTILS_ENDPOINT}/"))
+            .get(format!(
+                "https://{OPEN_PLATFORM_ENDPOINT}/?{canonical_query}"
+            ))
             .headers(headers)
-            .header(
-                reqwest::header::CONTENT_TYPE,
-                "application/x-www-form-urlencoded",
-            )
-            .body(payload)
             .send()
             .await
             .map_err(|error| {
                 MattingError::upstream_transport_error(
-                    format!("GetOssStsToken 请求失败：{error}"),
+                    format!("AuthorizeFileUpload 请求失败：{error}"),
                     error.is_timeout(),
                 )
             })?;
         let http_status = response.status();
         let body_text = response.text().await.map_err(|error| {
             MattingError::upstream_transport_error(
-                format!("GetOssStsToken 响应读取失败：{error}"),
+                format!("AuthorizeFileUpload 响应读取失败：{error}"),
                 error.is_timeout(),
             )
         })?;
-        let body: serde_json::Value = serde_json::from_str(&body_text).map_err(|error| {
-            MattingError::upstream_response_error(
-                format!(
-                    "GetOssStsToken 响应不是合法 JSON：{error}；原始响应：{}",
-                    truncate_for_log(&body_text)
-                ),
-                Some(http_status.as_u16()),
-            )
-        })?;
-        if http_status != StatusCode::OK {
-            return Err(MattingError::upstream_http_error(
-                format!(
-                    "GetOssStsToken 返回失败（HTTP {}，Code={}）：{}",
-                    http_status.as_u16(),
-                    body.get("Code")
-                        .and_then(|value| value.as_str())
-                        .unwrap_or("unknown"),
-                    body.get("Message")
-                        .and_then(|value| value.as_str())
-                        .unwrap_or("unknown")
-                ),
-                http_status.as_u16(),
-            ));
-        }
-        let data = body.get("Data").ok_or_else(|| {
-            MattingError::upstream_response_error(
-                format!(
-                    "GetOssStsToken 响应缺少 Data；原始响应：{}",
-                    truncate_for_log(&body_text)
-                ),
-                Some(http_status.as_u16()),
-            )
-        })?;
-        let read_field = |name: &str| -> Result<String, MattingError> {
-            data.get(name)
-                .and_then(|value| value.as_str())
-                .map(|value| value.to_string())
-                .ok_or_else(|| {
-                    MattingError::upstream_response_error(
-                        format!("GetOssStsToken 响应缺少 Data.{name}"),
-                        Some(http_status.as_u16()),
-                    )
-                })
-        };
-        Ok(ViapiStsToken {
-            access_key_id: read_field("AccessKeyId")?,
-            access_key_secret: read_field("AccessKeySecret")?,
-            security_token: read_field("SecurityToken")?,
-        })
+        parse_authorized_file_upload_response(&body_text, http_status)
     }
 
     fn build_signature_headers(
@@ -673,6 +731,18 @@ impl MattingClient {
         action: &str,
         version: &str,
         payload: &str,
+    ) -> Result<reqwest::header::HeaderMap, MattingError> {
+        self.build_acs3_headers_for_request(endpoint, action, version, "POST", "", payload)
+    }
+
+    fn build_acs3_headers_for_request(
+        &self,
+        endpoint: &str,
+        action: &str,
+        version: &str,
+        method: &str,
+        canonical_query: &str,
+        payload: &str,
     ) -> Result<reqwest::header::HeaderMap, MattingError> {
         let date = current_aliyun_timestamp();
         let nonce = uuid::Uuid::new_v4().simple().to_string();
@@ -684,8 +754,7 @@ impl MattingClient {
         let signed_headers =
             "host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version";
         let canonical_request = format!(
-            "POST\n/\n\n{}\n{}\n{}",
-            canonical_headers, signed_headers, payload_hash
+            "{method}\n/\n{canonical_query}\n{canonical_headers}\n{signed_headers}\n{payload_hash}"
         );
         let string_to_sign = format!(
             "ACS3-HMAC-SHA256\n{}",
@@ -719,6 +788,33 @@ fn normalize_matting_input_png(
     normalize_matting_input_png_within(source, MAX_INPUT_BYTES)
 }
 
+fn validate_source_dimensions(source_dims: (u32, u32)) -> Result<(), MattingError> {
+    if source_dims.0 <= MIN_INPUT_EDGE || source_dims.1 <= MIN_INPUT_EDGE {
+        return Err(MattingError::InvalidRequest(format!(
+            "待抠图图片尺寸 {}x{} 过小，阿里云通用抠图要求每条边大于 {MIN_INPUT_EDGE} 像素",
+            source_dims.0, source_dims.1
+        )));
+    }
+    Ok(())
+}
+
+fn compose_source_with_result_alpha(
+    mut source_rgba: image::RgbaImage,
+    result_image: image::RgbaImage,
+) -> Result<Vec<u8>, MattingError> {
+    let (source_width, source_height) = source_rgba.dimensions();
+    let alpha_mask = image::DynamicImage::ImageRgba8(result_image).resize_exact(
+        source_width,
+        source_height,
+        image::imageops::FilterType::Triangle,
+    );
+    let alpha_mask = alpha_mask.to_rgba8();
+    for (target, mask) in source_rgba.pixels_mut().zip(alpha_mask.pixels()) {
+        target.0[3] = target.0[3].min(mask.0[3]);
+    }
+    encode_rgba_png(&source_rgba)
+}
+
 /// `normalize_matting_input_png` 的可注入体积上限版本，便于单测用小阈值触发降尺寸循环。
 fn normalize_matting_input_png_within(
     source: &image::DynamicImage,
@@ -773,6 +869,13 @@ fn result_response_too_large_error() -> MattingError {
     )
 }
 
+fn source_response_too_large_error() -> MattingError {
+    MattingError::upstream_response_error(
+        format!("待抠图源图响应过大，超过 {MAX_RESULT_RESPONSE_BYTES} 字节上限"),
+        None,
+    )
+}
+
 /// 解码待抠图源图时套上尺寸 / 分配上限。源图直接来自请求体 / 生成产物，缺省
 /// `image::Limits` 无尺寸上限、仅 512MiB alloc 兜底，12MB 请求体即可构造巨幅压缩图
 /// （解压炸弹）在缩图前撑爆内存；逐帧动画并发调用时风险叠加。
@@ -804,18 +907,75 @@ fn decode_image_within_limits(bytes: &[u8]) -> Result<image::DynamicImage, Strin
     reader.decode().map_err(|error| error.to_string())
 }
 
-struct ViapiStsToken {
+#[derive(Debug)]
+struct AuthorizedFileUpload {
+    bucket: String,
+    endpoint: String,
     access_key_id: String,
-    access_key_secret: String,
-    security_token: String,
+    encoded_policy: String,
+    signature: String,
+    object_key: String,
 }
 
-fn hmac_sha1_base64(key: &[u8], content: &[u8]) -> Result<String, MattingError> {
-    use base64::Engine as _;
-    let mut signer = Hmac::<sha1::Sha1>::new_from_slice(key)
-        .map_err(|error| MattingError::Sign(format!("初始化 OSS V1 签名器失败：{error}")))?;
-    signer.update(content);
-    Ok(base64::engine::general_purpose::STANDARD.encode(signer.finalize().into_bytes()))
+fn parse_authorized_file_upload_response(
+    body_text: &str,
+    http_status: StatusCode,
+) -> Result<AuthorizedFileUpload, MattingError> {
+    // 成功响应包含 Policy 与 Signature；解析错误中不能回显原始正文。
+    let body: serde_json::Value = serde_json::from_str(body_text).map_err(|error| {
+        MattingError::upstream_response_error(
+            format!("AuthorizeFileUpload 响应不是合法 JSON：{error}"),
+            Some(http_status.as_u16()),
+        )
+    })?;
+    if http_status != StatusCode::OK {
+        return Err(MattingError::upstream_http_error(
+            format!(
+                "AuthorizeFileUpload 返回失败（HTTP {}，Code={}）：{}",
+                http_status.as_u16(),
+                body.get("Code")
+                    .and_then(|value| value.as_str())
+                    .unwrap_or("unknown"),
+                body.get("Message")
+                    .and_then(|value| value.as_str())
+                    .unwrap_or("unknown")
+            ),
+            http_status.as_u16(),
+        ));
+    }
+    let read_field = |name: &str| -> Result<String, MattingError> {
+        body.get(name)
+            .and_then(|value| value.as_str())
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::to_string)
+            .ok_or_else(|| {
+                MattingError::upstream_response_error(
+                    format!("AuthorizeFileUpload 响应缺少 {name}"),
+                    Some(http_status.as_u16()),
+                )
+            })
+    };
+    let bucket = read_field("Bucket")?.trim_matches('/').to_string();
+    let endpoint = read_field("Endpoint")?
+        .trim_start_matches("https://")
+        .trim_start_matches("http://")
+        .trim_matches('/')
+        .to_string();
+    if bucket.is_empty() || endpoint.is_empty() {
+        return Err(MattingError::upstream_response_error(
+            "AuthorizeFileUpload 响应中的 Bucket/Endpoint 不合法".to_string(),
+            Some(http_status.as_u16()),
+        ));
+    }
+    Ok(AuthorizedFileUpload {
+        bucket,
+        endpoint,
+        access_key_id: read_field("AccessKeyId")?,
+        encoded_policy: read_field("EncodedPolicy")?,
+        signature: read_field("Signature")?,
+        object_key: read_field("ObjectKey")?,
+    })
 }
 
 fn describe_result_download_transport_error(error: &reqwest::Error) -> String {
@@ -860,21 +1020,38 @@ fn sanitize_result_download_error_message(message: String) -> String {
     message
 }
 
-/// 脱敏 OSS 上传错误体：OSS 签名类错误会回显 StringToSign（含 `x-oss-security-token` 明文）、
-/// StringToSignBytes（其十六进制）和 SignatureProvided（签名串）。剥掉这三个元素，并把已知的
-/// STS 临时凭证在正文任何位置的出现替换为 `***`，保留 `<Code>` 等可诊断信息后再记录。
-fn sanitize_oss_upload_error_body(body: &str, security_token: &str) -> String {
+/// 脱敏 Policy POST 上传错误体：OSS 签名类错误可能回显 StringToSign、Policy 或签名串。
+/// 剥掉已知签名元素，并替换本次授权材料，保留 `<Code>` 等可诊断信息。
+fn sanitize_policy_upload_error_body(body: &str, authorized: &AuthorizedFileUpload) -> String {
     let mut sanitized = body.to_string();
-    for tag in ["StringToSign", "StringToSignBytes", "SignatureProvided"] {
+    for tag in [
+        "StringToSign",
+        "StringToSignBytes",
+        "SignatureProvided",
+        "Policy",
+    ] {
         sanitized = redact_xml_element(&sanitized, tag);
     }
-    let security_token = security_token.trim();
-    if !security_token.is_empty() {
-        sanitized = sanitized.replace(security_token, "***");
+    for secret in [
+        authorized.access_key_id.as_str(),
+        authorized.encoded_policy.as_str(),
+        authorized.signature.as_str(),
+    ] {
+        if !secret.is_empty() {
+            sanitized = sanitized.replace(secret, "***");
+        }
     }
     truncate_for_log(&sanitized)
 }
 
+fn encode_oss_object_key(object_key: &str) -> String {
+    object_key
+        .split('/')
+        .map(|segment| urlencoding_encode(segment).replace('+', "%20"))
+        .collect::<Vec<_>>()
+        .join("/")
+}
+
 /// 把 `<tag>…</tag>` 的内容替换成 `[redacted]`（tag 内容可跨行）；只有开标签无闭标签时丢弃其后全部内容。
 fn redact_xml_element(text: &str, tag: &str) -> String {
     let open = format!("<{tag}>");
@@ -989,6 +1166,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn local_processing_after_external_call_is_auditable_with_stage() {
+        let error = MattingError::InvalidRequest("解析待抠图图片失败：invalid png".to_string())
+            .with_failure_stage("source_decode");
+
+        assert!(error.external_call_attempted());
+        assert_eq!(error.failure_stage(), "source_decode");
+        assert!(!error.is_timeout());
+        assert!(!error.is_transport());
+        assert_eq!(error.upstream_status(), None);
+    }
+
     #[test]
     fn upstream_transport_error_classifies_as_transport() {
         let error = MattingError::upstream_transport_error(
@@ -1081,6 +1270,86 @@ mod tests {
         assert!(!date.contains('.'), "x-acs-date 不能带小数秒：{date}");
     }
 
+    #[test]
+    fn authorize_file_upload_response_parses_policy_fields() {
+        let response = r#"{
+            "RequestId":"request-id",
+            "Bucket":"viapi-customer-pop",
+            "Endpoint":"oss-cn-shanghai.aliyuncs.com",
+            "AccessKeyId":"temporary-key-id",
+            "EncodedPolicy":"encoded-policy",
+            "Signature":"policy-signature",
+            "ObjectKey":"imageseg/2026/07/input image.png"
+        }"#;
+
+        let authorized = parse_authorized_file_upload_response(response, StatusCode::OK)
+            .expect("AuthorizeFileUpload response should parse");
+
+        assert_eq!(authorized.bucket, "viapi-customer-pop");
+        assert_eq!(authorized.endpoint, "oss-cn-shanghai.aliyuncs.com");
+        assert_eq!(authorized.access_key_id, "temporary-key-id");
+        assert_eq!(authorized.encoded_policy, "encoded-policy");
+        assert_eq!(authorized.signature, "policy-signature");
+        assert_eq!(authorized.object_key, "imageseg/2026/07/input image.png");
+        assert_eq!(
+            encode_oss_object_key(&authorized.object_key),
+            "imageseg/2026/07/input%20image.png"
+        );
+    }
+
+    #[test]
+    fn authorize_file_upload_response_does_not_echo_sensitive_body_on_parse_error() {
+        let sensitive_body = "not-json encoded-policy policy-signature temporary-key-id";
+
+        let error = parse_authorized_file_upload_response(sensitive_body, StatusCode::OK)
+            .expect_err("invalid response should fail");
+
+        assert!(error.message().contains("响应不是合法 JSON"));
+        assert!(!error.message().contains("encoded-policy"));
+        assert!(!error.message().contains("policy-signature"));
+        assert!(!error.message().contains("temporary-key-id"));
+    }
+
+    #[test]
+    fn authorize_file_upload_headers_sign_get_query() {
+        let config = MattingConfig::new(
+            DEFAULT_IMAGESEG_ENDPOINT.to_string(),
+            "test-key-id".to_string(),
+            "test-key-secret".to_string(),
+        )
+        .expect("config should build");
+        let client = MattingClient::new(config).expect("client should build");
+        let headers = client
+            .build_acs3_headers_for_request(
+                OPEN_PLATFORM_ENDPOINT,
+                AUTHORIZE_FILE_UPLOAD_ACTION,
+                AUTHORIZE_FILE_UPLOAD_VERSION,
+                "GET",
+                "Product=imageseg",
+                "",
+            )
+            .expect("headers should build");
+
+        assert_eq!(
+            headers
+                .get("x-acs-action")
+                .and_then(|value| value.to_str().ok()),
+            Some(AUTHORIZE_FILE_UPLOAD_ACTION)
+        );
+        assert_eq!(
+            headers
+                .get("x-acs-version")
+                .and_then(|value| value.to_str().ok()),
+            Some(AUTHORIZE_FILE_UPLOAD_VERSION)
+        );
+        assert_eq!(
+            headers
+                .get("x-acs-content-sha256")
+                .and_then(|value| value.to_str().ok()),
+            Some(sha256_hex(b"").as_str())
+        );
+    }
+
     #[test]
     fn result_download_error_message_redacts_signed_oss_url() {
         let message = sanitize_result_download_error_message(
@@ -1106,36 +1375,38 @@ mod tests {
     }
 
     #[test]
-    fn oss_upload_error_body_redacts_signature_material_and_token() {
-        let token = "CAISabcSECRETtoken123";
+    fn policy_upload_error_body_redacts_authorization_material() {
+        let authorized = AuthorizedFileUpload {
+            bucket: "viapi-customer-pop".to_string(),
+            endpoint: "oss-cn-shanghai.aliyuncs.com".to_string(),
+            access_key_id: "temporary-key-id".to_string(),
+            encoded_policy: "encoded-policy".to_string(),
+            signature: "policy-signature".to_string(),
+            object_key: "imageseg/input.png".to_string(),
+        };
         let body = format!(
             "<Error><Code>SignatureDoesNotMatch</Code>\
-             <Message>mismatch for {token}</Message>\
-             <SignatureProvided>sigSECRET==</SignatureProvided>\
+             <Message>mismatch for {} and {}</Message>\
+             <Policy>{}</Policy>\
+             <SignatureProvided>{}</SignatureProvided>\
              <StringToSignBytes>50 55 54 0a</StringToSignBytes>\
-             <StringToSign>PUT\nx-oss-security-token:{token}\n/bucket/key</StringToSign></Error>"
+             <StringToSign>POST\npolicy={}</StringToSign></Error>",
+            authorized.access_key_id,
+            authorized.signature,
+            authorized.encoded_policy,
+            authorized.signature,
+            authorized.encoded_policy
         );
 
-        let sanitized = sanitize_oss_upload_error_body(&body, token);
+        let sanitized = sanitize_policy_upload_error_body(&body, &authorized);
 
-        // 敏感串全部消失：StringToSign 明文、其中的 token、十六进制、签名串、以及 Message 里的 token 明文。
-        assert!(
-            !sanitized.contains(token),
-            "STS token 不能残留（含元素外的明文）"
-        );
-        assert!(
-            !sanitized.contains("x-oss-security-token:CAIS"),
-            "StringToSign 明文不能残留"
-        );
-        assert!(
-            !sanitized.contains("sigSECRET"),
-            "SignatureProvided 不能残留"
-        );
+        assert!(!sanitized.contains(&authorized.access_key_id));
+        assert!(!sanitized.contains(&authorized.encoded_policy));
+        assert!(!sanitized.contains(&authorized.signature));
         assert!(
             !sanitized.contains("50 55 54 0a"),
             "StringToSignBytes 不能残留"
         );
-        // 可诊断信息保留。
         assert!(
             sanitized.contains("SignatureDoesNotMatch"),
             "OSS Code 应保留供诊断"
@@ -1219,4 +1490,45 @@ mod tests {
             "降尺寸后仍是 PNG"
         );
     }
+
+    #[test]
+    fn url_input_upload_scope_ends_before_aliyun_inference() {
+        let source = include_str!("lib.rs");
+        let start = source
+            .find("pub async fn segment_image_url_to_transparent_png")
+            .expect("URL input method should exist");
+        let tail = &source[start..];
+        let end = tail
+            .find("async fn segment_uploaded_input_to_rgba")
+            .expect("uploaded input helper should follow URL method");
+        let body = &tail[..end];
+
+        let download = body
+            .find("let source_bytes = self\n                .download_source_image(source_url)")
+            .expect("source should download lazily");
+        let upload = body
+            .find(".upload_temp_image(upload_bytes, file_name, \"image/png\")")
+            .expect("source should upload to temporary OSS");
+        let scope_end = body
+            .find("let result_image = self")
+            .expect("Aliyun inference should start after upload scope");
+        assert!(download < upload && upload < scope_end);
+        assert!(body.contains("let (source_dims, upload_dims, image_url) = {"));
+        assert_eq!(body.matches("download_source_image(source_url)").count(), 2);
+    }
+
+    #[test]
+    fn compose_source_with_result_alpha_preserves_rgb() {
+        let source = image::RgbaImage::from_pixel(2, 2, image::Rgba([10, 20, 30, 180]));
+        let mask = image::RgbaImage::from_pixel(1, 1, image::Rgba([200, 210, 220, 90]));
+
+        let encoded = compose_source_with_result_alpha(source, mask)
+            .expect("alpha composition should encode");
+        let output = image::load_from_memory(&encoded)
+            .expect("output should decode")
+            .to_rgba8();
+
+        assert_eq!(output.dimensions(), (2, 2));
+        assert!(output.pixels().all(|pixel| pixel.0 == [10, 20, 30, 90]));
+    }
 }
diff --git a/server-rs/crates/shared-contracts/src/assets.rs b/server-rs/crates/shared-contracts/src/assets.rs
index 58e0b3958..27ca2036d 100644
--- a/server-rs/crates/shared-contracts/src/assets.rs
+++ b/server-rs/crates/shared-contracts/src/assets.rs
@@ -1201,7 +1201,7 @@ mod tests {
     }
 
     #[test]
-    fn editor_video_request_supports_seedance_multimodal_references() {
+    fn editor_video_request_supports_stable_seedance_multimodal_references() {
         let payload = serde_json::to_value(EditorVideoGenerateRequest {
             prompt: "参考素材生成视频".to_string(),
             model: "seedance2.0-fast".to_string(),
@@ -1211,11 +1211,15 @@ mod tests {
             mode: "std".to_string(),
             sound: "off".to_string(),
             web_search_enabled: true,
-            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_image_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/image/demo.png".to_string(),
+            ],
             reference_video_srcs: vec![
                 "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
             ],
-            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+            reference_audio_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/audio/demo.mp3".to_string(),
+            ],
             project_id: None,
             canvas_completion: None,
             generation_inputs: None,
@@ -1228,7 +1232,7 @@ mod tests {
 
         assert_eq!(
             payload["referenceImageSrcs"],
-            json!(["data:image/png;base64,image"])
+            json!(["generated-character-drafts/editor/seedance-references/image/demo.png"])
         );
         assert_eq!(
             payload["referenceVideoSrcs"],
@@ -1236,7 +1240,7 @@ mod tests {
         );
         assert_eq!(
             payload["referenceAudioSrcs"],
-            json!(["data:audio/mpeg;base64,audio"])
+            json!(["generated-character-drafts/editor/seedance-references/audio/demo.mp3"])
         );
     }
 
@@ -1288,8 +1292,8 @@ mod tests {
     #[test]
     fn editor_icon_spritesheet_request_omits_price_and_response_includes_price() {
         let request_payload = serde_json::to_value(EditorIconSpritesheetGenerateRequest {
-            reference_image_src: "data:image/png;base64,spec".to_string(),
-            reference_image_srcs: vec!["data:image/png;base64,style".to_string()],
+            reference_image_src: "generated-images/editor/spec.png".to_string(),
+            reference_image_srcs: vec!["generated-images/editor/style.png".to_string()],
             icon_descriptions: vec!["返回按钮".to_string(), "设置按钮".to_string()],
             model: Some("gemini-3.1-flash-image-preview".to_string()),
             aspect_ratio: Some("1:1".to_string()),
@@ -1299,16 +1303,16 @@ mod tests {
 
         assert_eq!(
             request_payload["referenceImageSrc"],
-            json!("data:image/png;base64,spec")
+            json!("generated-images/editor/spec.png")
         );
         assert_eq!(
             request_payload["referenceImageSrcs"],
-            json!(["data:image/png;base64,style"])
+            json!(["generated-images/editor/style.png"])
         );
         assert!(request_payload.get("priceMudPoints").is_none());
 
         let response_payload = serde_json::to_value(EditorIconSpritesheetGenerateResponse {
-            spritesheet_image_src: "data:image/png;base64,sheet".to_string(),
+            spritesheet_image_src: "/generated-images/editor/sheet.png".to_string(),
             spritesheet_width: 512,
             spritesheet_height: 512,
             icon_image_srcs: Vec::new(),
diff --git a/server-rs/crates/shared-contracts/src/editor_agent.rs b/server-rs/crates/shared-contracts/src/editor_agent.rs
index c3790a276..924e885e6 100644
--- a/server-rs/crates/shared-contracts/src/editor_agent.rs
+++ b/server-rs/crates/shared-contracts/src/editor_agent.rs
@@ -1,47 +1,21 @@
 //! 画布Agent对话契约：与 packages/shared/src/contracts/editorAgent.ts 保持同形。
 //! 会话元数据存 SpacetimeDB，消息正文整体存 OSS（editor-agent/{conversationId}.json）。
 
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::json;
 
 pub const EDITOR_AGENT_MAX_ATTACHMENTS: usize = 9;
+pub const EDITOR_AGENT_ERROR_MESSAGE_PREFIX: &str = "ERROR ";
 pub const EDITOR_AGENT_TITLE_MAX_CHARS: usize = 20;
 pub const EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE: &str = "新对话";
-pub const EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION: u32 = 1;
-
-#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "snake_case")]
-pub enum EditorAgentStage {
-    Idle,
-    Thinking,
-    Responding,
-    Generating,
-    Completed,
-    Failed,
-}
+pub const EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION: u32 = 2;
 
 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "lowercase")]
 pub enum EditorAgentMessageRole {
     User,
     Assistant,
-}
-
-#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "snake_case")]
-pub enum EditorAgentMessageKind {
-    Chat,
-    Stage,
-    Error,
-}
-
-#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "snake_case")]
-pub enum EditorAgentMessageStatus {
-    Streaming,
-    Generating,
-    Completed,
-    Failed,
-    Stopped,
+    System,
 }
 
 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
@@ -53,20 +27,16 @@ pub enum EditorAgentAttachmentSource {
 
 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
-pub enum EditorAgentToolName {
-    GenerateImage,
-    EditImage,
-    GenerateCharacter,
-    GenerateIconSpritesheet,
-    GenerateUiDesign,
-}
-
-#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
-#[serde(rename_all = "snake_case")]
-pub enum EditorAgentGenerationStatus {
-    Generating,
+pub enum EditorAgentToolCallStatus {
+    #[serde(alias = "pending_confirmation", alias = "executing")]
+    NotCompleted,
     Completed,
     Failed,
+    Cancelled,
+}
+
+fn default_editor_agent_tool_call_status() -> EditorAgentToolCallStatus {
+    EditorAgentToolCallStatus::NotCompleted
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -107,44 +77,165 @@ pub struct EditorAgentGeneratedImage {
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
-pub struct EditorAgentGenerationRecord {
-    pub tool_call_id: String,
-    pub tool_name: EditorAgentToolName,
+pub struct EditorAgentGeneratedVideo {
     #[serde(default)]
-    pub summary: Option<String>,
+    pub resource_id: Option<String>,
     #[serde(default)]
-    pub task_id: Option<String>,
-    pub status: EditorAgentGenerationStatus,
+    pub object_key: Option<String>,
     #[serde(default)]
-    pub model: Option<String>,
+    pub asset_object_id: Option<String>,
+    pub video_src: String,
     #[serde(default)]
-    pub images: Vec<EditorAgentGeneratedImage>,
+    pub thumbnail_src: Option<String>,
     #[serde(default)]
-    pub error: Option<String>,
+    pub width: Option<u32>,
+    #[serde(default)]
+    pub height: Option<u32>,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
+pub struct EditorAgentGeneratedAudio {
+    #[serde(default)]
+    pub resource_id: Option<String>,
+    #[serde(default)]
+    pub object_key: Option<String>,
+    #[serde(default)]
+    pub asset_object_id: Option<String>,
+    pub audio_src: String,
+}
+
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCallDisplayArgs {
+    pub string_args: Vec<EditorAgentToolCallStringArg>,
+    pub image_args: Vec<EditorAgentToolCallImageArg>,
+    pub extras: EditorAgentToolCallDisplayExtras,
+}
+
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCallDisplayExtras {
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCallStringArg {
+    pub name: String,
+    pub label: String,
+    pub value: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCallImageArg {
+    pub name: String,
+    pub label: String,
+    pub refs: Vec<EditorAgentToolCallImageRef>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCallImageRef {
+    pub image_id: String,
+    pub image_src: String,
+    #[serde(default)]
+    pub object_key: Option<String>,
+    #[serde(default)]
+    pub thumbnail_src: Option<String>,
+    #[serde(default)]
+    pub label: Option<String>,
+    #[serde(default)]
+    pub width: Option<u32>,
+    #[serde(default)]
+    pub height: Option<u32>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAgentToolCall {
+    pub tool_name: String,
+    #[serde(default = "default_editor_agent_tool_call_status")]
+    pub status: EditorAgentToolCallStatus,
+    pub args: serde_json::Value,
+    pub display_args: EditorAgentToolCallDisplayArgs,
+    #[serde(default)]
+    pub external_job_id: Option<String>,
+    #[serde(default)]
+    pub images: Vec<EditorAgentGeneratedImage>,
+    #[serde(default)]
+    pub videos: Vec<EditorAgentGeneratedVideo>,
+    #[serde(default)]
+    pub audios: Vec<EditorAgentGeneratedAudio>,
+    #[serde(default)]
+    pub error: Option<String>,
+}
+#[derive(Clone, Debug, Deserialize)]
+#[serde(untagged)]
+enum RawEditorAgentMessageId {
+    Number(usize),
+    String(String),
+    #[allow(dead_code)]
+    Other(serde_json::Value),
+}
+
+impl Default for RawEditorAgentMessageId {
+    fn default() -> Self {
+        Self::Number(0)
+    }
+}
+
+impl RawEditorAgentMessageId {
+    fn numeric_id(&self) -> usize {
+        match self {
+            Self::Number(id) => *id,
+            Self::String(_) | Self::Other(_) => 0,
+        }
+    }
+
+    fn legacy_client_message_id(&self, role: EditorAgentMessageRole) -> Option<String> {
+        if role != EditorAgentMessageRole::User {
+            return None;
+        }
+        match self {
+            Self::String(id) if !id.trim().is_empty() => Some(id.trim().to_string()),
+            Self::Number(_) | Self::String(_) | Self::Other(_) => None,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
 pub struct EditorAgentMessage {
-    pub id: String,
+    // to compatible for legacy version
+    pub id: usize,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_message_id: Option<String>,
     pub role: EditorAgentMessageRole,
-    pub kind: EditorAgentMessageKind,
     pub text: String,
     #[serde(default)]
     pub attachments: Vec<EditorAgentAttachmentRef>,
-    #[serde(default)]
-    pub generations: Vec<EditorAgentGenerationRecord>,
-    pub status: EditorAgentMessageStatus,
+    // one tool call is inside one system message.
+    pub tool_call: Option<EditorAgentToolCall>,
     pub created_at: String,
 }
 
+impl<'de> Deserialize<'de> for EditorAgentMessage {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        Ok(RawEditorAgentMessage::deserialize(deserializer)?.into_single_message())
+    }
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct EditorAgentConversationSummary {
     pub conversation_id: String,
     pub project_id: String,
     pub title: String,
-    pub created_at: String,
     pub updated_at: String,
 }
 
@@ -159,7 +250,7 @@ pub struct EditorAgentConversationDetail {
     pub messages: Vec<EditorAgentMessage>,
 }
 
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[derive(Clone, Debug, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct EditorAgentConversationMessagesDocument {
     pub version: u32,
@@ -167,6 +258,235 @@ pub struct EditorAgentConversationMessagesDocument {
     pub messages: Vec<EditorAgentMessage>,
 }
 
+// for legacy migration start
+impl<'de> Deserialize<'de> for EditorAgentConversationMessagesDocument {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let raw = RawEditorAgentConversationMessagesDocument::deserialize(deserializer)?;
+        let mut messages = Vec::new();
+        for raw_message in raw.messages {
+            for mut message in raw_message.into_document_messages() {
+                message.id = messages.len();
+                messages.push(message);
+            }
+        }
+        Ok(Self {
+            version: EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION,
+            conversation_id: raw.conversation_id,
+            messages,
+        })
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RawEditorAgentConversationMessagesDocument {
+    #[allow(dead_code)]
+    #[serde(default)]
+    version: u32,
+    conversation_id: String,
+    #[serde(default)]
+    messages: Vec<RawEditorAgentMessage>,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RawEditorAgentMessage {
+    #[serde(default)]
+    id: RawEditorAgentMessageId,
+    #[serde(default)]
+    client_message_id: Option<String>,
+    role: EditorAgentMessageRole,
+    #[serde(default)]
+    text: String,
+    #[serde(default)]
+    attachments: Vec<EditorAgentAttachmentRef>,
+    #[serde(default)]
+    tool_call: Option<EditorAgentToolCall>,
+    #[serde(default)]
+    generations: Vec<LegacyEditorAgentGenerationRecord>,
+    #[serde(default)]
+    created_at: String,
+}
+
+impl RawEditorAgentMessage {
+    fn into_single_message(self) -> EditorAgentMessage {
+        let id = self.id.numeric_id();
+        let client_message_id = self
+            .client_message_id
+            .or_else(|| self.id.legacy_client_message_id(self.role));
+        let tool_call = self
+            .tool_call
+            .or_else(|| legacy_generations_to_tool_call(self.generations));
+        EditorAgentMessage {
+            id,
+            client_message_id,
+            role: self.role,
+            text: self.text,
+            attachments: self.attachments,
+            tool_call,
+            created_at: self.created_at,
+        }
+    }
+
+    fn into_document_messages(self) -> Vec<EditorAgentMessage> {
+        if self.tool_call.is_some() || self.generations.is_empty() {
+            return vec![self.into_single_message()];
+        }
+
+        let id = self.id.numeric_id();
+        let client_message_id = self
+            .client_message_id
+            .clone()
+            .or_else(|| self.id.legacy_client_message_id(self.role));
+        let mut messages = Vec::new();
+        if self.role != EditorAgentMessageRole::Assistant
+            || !self.text.trim().is_empty()
+            || !self.attachments.is_empty()
+        {
+            messages.push(EditorAgentMessage {
+                id,
+                client_message_id,
+                role: self.role,
+                text: self.text.clone(),
+                attachments: self.attachments,
+                tool_call: None,
+                created_at: self.created_at.clone(),
+            });
+        }
+
+        messages.extend(self.generations.into_iter().map(|generation| {
+            let tool_call_message =
+                legacy_generation_to_tool_call_message(generation, self.created_at.as_str());
+            EditorAgentMessage {
+                id,
+                client_message_id: None,
+                role: EditorAgentMessageRole::System,
+                text: tool_call_message.text,
+                attachments: Vec::new(),
+                tool_call: Some(tool_call_message.tool_call),
+                created_at: self.created_at.clone(),
+            }
+        }));
+        messages
+    }
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyEditorAgentGenerationRecord {
+    #[serde(default)]
+    tool_call_id: String,
+    tool_name: String,
+    #[serde(default)]
+    summary: Option<String>,
+    #[serde(default)]
+    task_id: Option<String>,
+    status: LegacyEditorAgentGenerationStatus,
+    #[serde(default)]
+    model: Option<String>,
+    #[serde(default)]
+    images: Vec<EditorAgentGeneratedImage>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+enum LegacyEditorAgentGenerationStatus {
+    Generating,
+    Completed,
+    Failed,
+}
+
+struct LegacyToolCallMessage {
+    text: String,
+    tool_call: EditorAgentToolCall,
+}
+
+fn legacy_generations_to_tool_call(
+    generations: Vec<LegacyEditorAgentGenerationRecord>,
+) -> Option<EditorAgentToolCall> {
+    let mut generations = generations.into_iter();
+    let first = generations.next()?;
+    let mut tool_call_message = legacy_generation_to_tool_call_message(first, "");
+    for generation in generations {
+        tool_call_message.tool_call.images.extend(generation.images);
+        if tool_call_message.tool_call.error.is_none() {
+            tool_call_message.tool_call.error = generation.error;
+        }
+        if tool_call_message.tool_call.status == EditorAgentToolCallStatus::Completed
+            && generation.status != LegacyEditorAgentGenerationStatus::Completed
+        {
+            tool_call_message.tool_call.status = legacy_generation_status(generation.status);
+        }
+    }
+    Some(tool_call_message.tool_call)
+}
+
+fn legacy_generation_to_tool_call_message(
+    generation: LegacyEditorAgentGenerationRecord,
+    created_at: &str,
+) -> LegacyToolCallMessage {
+    let tool_name = normalize_legacy_tool_name(generation.tool_name.as_str());
+    let status = legacy_generation_status(generation.status);
+    let summary = generation.summary.clone();
+    let error = generation.error.clone();
+    let text = legacy_tool_call_text(tool_name.as_str(), summary.as_deref(), error.as_deref());
+    LegacyToolCallMessage {
+        text,
+        tool_call: EditorAgentToolCall {
+            tool_name,
+            status,
+            args: json!({
+                "legacyToolCallId": generation.tool_call_id,
+                "legacySummary": summary,
+                "legacyModel": generation.model,
+                "legacyCreatedAt": created_at,
+            }),
+            display_args: EditorAgentToolCallDisplayArgs::default(),
+            external_job_id: generation.task_id,
+            images: generation.images,
+            videos: Vec::new(),
+            audios: Vec::new(),
+            error,
+        },
+    }
+}
+
+fn legacy_generation_status(
+    status: LegacyEditorAgentGenerationStatus,
+) -> EditorAgentToolCallStatus {
+    match status {
+        LegacyEditorAgentGenerationStatus::Generating => EditorAgentToolCallStatus::NotCompleted,
+        LegacyEditorAgentGenerationStatus::Completed => EditorAgentToolCallStatus::Completed,
+        LegacyEditorAgentGenerationStatus::Failed => EditorAgentToolCallStatus::Failed,
+    }
+}
+
+fn normalize_legacy_tool_name(tool_name: &str) -> String {
+    let normalized = tool_name.trim().replace('_', "-");
+    if normalized.is_empty() {
+        "generate-image".to_string()
+    } else {
+        normalized
+    }
+}
+
+fn legacy_tool_call_text(tool_name: &str, summary: Option<&str>, error: Option<&str>) -> String {
+    if let Some(error) = error.map(str::trim).filter(|value| !value.is_empty()) {
+        return format!("[tool_call:{tool_name}] output: {error}");
+    }
+    let output = summary
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("legacy generation restored");
+    format!("[tool_call:{tool_name}] output: {output}")
+}
+// for legacy migration end
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct CreateEditorAgentConversationRequest {
@@ -188,96 +508,19 @@ pub struct EditorAgentConversationResponse {
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
-pub struct StreamEditorAgentMessageRequest {
+pub struct EditorAgentMessageRequest {
     pub client_message_id: String,
     pub text: String,
     #[serde(default)]
     pub attachments: Vec<EditorAgentAttachmentRef>,
 }
 
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "snake_case")]
-pub enum EditorAgentSseEventType {
-    Stage,
-    MessageDelta,
-    ToolStarted,
-    ToolCompleted,
-    GenerationResult,
-    Error,
-    Done,
-}
-
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
-pub struct EditorAgentSseEnvelope {
-    pub event: EditorAgentSseEventType,
-    pub data: serde_json::Value,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentStageEvent {
-    pub conversation_id: String,
-    pub stage: EditorAgentStage,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentMessageDeltaEvent {
-    pub conversation_id: String,
-    pub message_id: String,
-    pub role: EditorAgentMessageRole,
-    pub kind: EditorAgentMessageKind,
-    pub text_delta: String,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentToolEvent {
-    pub conversation_id: String,
-    pub message_id: String,
-    pub tool_call_id: String,
-    pub tool_name: EditorAgentToolName,
-    #[serde(default)]
-    pub summary: Option<String>,
-    #[serde(default)]
-    pub task_id: Option<String>,
-    #[serde(default)]
-    pub model: Option<String>,
-    #[serde(default)]
-    pub status: Option<EditorAgentGenerationStatus>,
-    #[serde(default)]
-    pub error: Option<String>,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentGenerationResultEvent {
-    pub conversation_id: String,
-    pub message_id: String,
-    pub tool_call_id: String,
-    pub tool_name: EditorAgentToolName,
-    #[serde(default)]
-    pub model: Option<String>,
-    pub images: Vec<EditorAgentGeneratedImage>,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentErrorEvent {
-    #[serde(default)]
-    pub conversation_id: Option<String>,
-    pub code: String,
-    pub message: String,
-    pub recoverable: bool,
-}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct EditorAgentDoneEvent {
-    pub conversation_id: String,
-    #[serde(default)]
-    pub title: Option<String>,
+pub struct EditorAgentMessageResponse {
+    pub conversation: EditorAgentConversationSummary,
+    pub delta_messages: Vec<EditorAgentMessage>,
+    pub error_message: Option<String>,
 }
 
 #[cfg(test)]
@@ -286,111 +529,220 @@ mod tests {
     use serde_json::json;
 
     #[test]
-    fn editor_agent_conversation_detail_uses_camel_case() {
-        let detail = EditorAgentConversationDetail {
-            conversation_id: "editor-agent-conv-1".to_string(),
-            project_id: "project-1".to_string(),
-            title: "新对话".to_string(),
-            created_at: "2026-07-03T00:00:00Z".to_string(),
-            updated_at: "2026-07-03T00:00:01Z".to_string(),
-            messages: vec![EditorAgentMessage {
-                id: "message-1".to_string(),
-                role: EditorAgentMessageRole::User,
-                kind: EditorAgentMessageKind::Chat,
-                text: "帮我生成一张森林背景".to_string(),
-                attachments: vec![EditorAgentAttachmentRef {
-                    source: EditorAgentAttachmentSource::CanvasResource,
-                    reference_id: "resource-1".to_string(),
-                    object_key: Some("editor/resource-1.png".to_string()),
-                    image_src: "https://example.test/resource-1.png".to_string(),
-                    thumbnail_src: None,
-                    label: Some("森林参考".to_string()),
-                    width: Some(1024),
-                    height: Some(768),
-                }],
-                generations: vec![],
-                status: EditorAgentMessageStatus::Completed,
-                created_at: "2026-07-03T00:00:00Z".to_string(),
-            }],
-        };
+    fn message_request_requires_client_message_id_and_user_message_preserves_it() {
+        let missing_client_message_id =
+            serde_json::from_value::<EditorAgentMessageRequest>(json!({
+                "text": "生成一张图",
+                "attachments": []
+            }));
+        assert!(missing_client_message_id.is_err());
 
-        let payload = serde_json::to_value(&detail).expect("detail should serialize");
-        assert_eq!(payload["conversationId"], json!("editor-agent-conv-1"));
-        assert_eq!(payload["messages"][0]["role"], json!("user"));
-        assert_eq!(
-            payload["messages"][0]["attachments"][0]["source"],
-            json!("canvas_resource")
-        );
-        assert_eq!(
-            payload["messages"][0]["attachments"][0]["referenceId"],
-            json!("resource-1")
-        );
-        assert_eq!(payload["messages"][0]["status"], json!("completed"));
-
-        let decoded: EditorAgentConversationDetail =
-            serde_json::from_value(payload).expect("detail should deserialize");
-        assert_eq!(decoded, detail);
-    }
-
-    #[test]
-    fn editor_agent_sse_events_serialize_event_names() {
-        let envelope = EditorAgentSseEnvelope {
-            event: EditorAgentSseEventType::GenerationResult,
-            data: serde_json::to_value(EditorAgentGenerationResultEvent {
-                conversation_id: "editor-agent-conv-1".to_string(),
-                message_id: "message-2".to_string(),
-                tool_call_id: "tool-call-1".to_string(),
-                tool_name: EditorAgentToolName::GenerateImage,
-                model: Some("z-image".to_string()),
-                images: vec![EditorAgentGeneratedImage {
-                    resource_id: Some("resource-2".to_string()),
-                    object_key: Some("generated/result.png".to_string()),
-                    asset_object_id: Some("asset-object-2".to_string()),
-                    image_src: "https://example.test/generated.png".to_string(),
-                    thumbnail_src: None,
-                    width: Some(1024),
-                    height: Some(1024),
-                }],
-            })
-            .expect("event data should serialize"),
-        };
-
-        let payload = serde_json::to_value(envelope).expect("envelope should serialize");
-        assert_eq!(payload["event"], json!("generation_result"));
-        assert_eq!(payload["data"]["toolName"], json!("generate_image"));
-        assert_eq!(
-            payload["data"]["images"][0]["resourceId"],
-            json!("resource-2")
-        );
-        assert_eq!(
-            payload["data"]["images"][0]["objectKey"],
-            json!("generated/result.png")
-        );
-
-        let error_envelope = EditorAgentSseEnvelope {
-            event: EditorAgentSseEventType::Error,
-            data: serde_json::to_value(EditorAgentErrorEvent {
-                conversation_id: Some("editor-agent-conv-1".to_string()),
-                code: "INSUFFICIENT_BALANCE".to_string(),
-                message: "泥点余额不足，本次生成未执行".to_string(),
-                recoverable: true,
-            })
-            .expect("event data should serialize"),
-        };
-        let error_payload =
-            serde_json::to_value(error_envelope).expect("envelope should serialize");
-        assert_eq!(error_payload["event"], json!("error"));
-        assert_eq!(error_payload["data"]["recoverable"], json!(true));
-    }
-
-    #[test]
-    fn stream_request_defaults_attachments_to_empty() {
-        let payload = json!({
+        let request = serde_json::from_value::<EditorAgentMessageRequest>(json!({
             "clientMessageId": "client-message-1",
-            "text": "随便聊聊"
-        });
-        let decoded: StreamEditorAgentMessageRequest =
-            serde_json::from_value(payload).expect("request should deserialize");
-        assert!(decoded.attachments.is_empty());
+            "text": "生成一张图",
+            "attachments": []
+        }))
+        .expect("clientMessageId should deserialize");
+        assert_eq!(request.client_message_id, "client-message-1");
+
+        let message = EditorAgentMessage {
+            id: 0,
+            client_message_id: Some(request.client_message_id),
+            role: EditorAgentMessageRole::User,
+            text: request.text,
+            attachments: request.attachments,
+            tool_call: None,
+            created_at: "2026-07-16T00:00:00Z".to_string(),
+        };
+        let payload = serde_json::to_value(message).expect("message should serialize");
+        assert_eq!(payload["id"], 0);
+        assert_eq!(payload["clientMessageId"], "client-message-1");
+    }
+
+    #[test]
+    fn tool_call_display_args_and_media_use_camel_case() {
+        let missing_display_args = serde_json::from_value::<EditorAgentToolCall>(json!({
+            "toolName": "generate-video",
+            "args": {},
+            "images": []
+        }));
+        assert!(missing_display_args.is_err());
+
+        let tool_call = EditorAgentToolCall {
+            tool_name: "generate-video".to_string(),
+            status: EditorAgentToolCallStatus::Completed,
+            args: json!({}),
+            display_args: EditorAgentToolCallDisplayArgs {
+                string_args: vec![EditorAgentToolCallStringArg {
+                    name: "prompt".to_string(),
+                    label: "提示词".to_string(),
+                    value: "生成像素风角色".to_string(),
+                }],
+                image_args: vec![EditorAgentToolCallImageArg {
+                    name: "reference_image_ids".to_string(),
+                    label: "参考图片".to_string(),
+                    refs: vec![EditorAgentToolCallImageRef {
+                        image_id: "sha256:reference-1".to_string(),
+                        image_src: "/reference.png".to_string(),
+                        object_key: Some("generated/reference.png".to_string()),
+                        thumbnail_src: Some("/reference-thumbnail.png".to_string()),
+                        label: Some("角色参考".to_string()),
+                        width: Some(512),
+                        height: Some(512),
+                    }],
+                }],
+                extras: EditorAgentToolCallDisplayExtras {
+                    price_mud_points: 5,
+                },
+            },
+            external_job_id: Some("task-editor-agent-1".to_string()),
+            images: Vec::new(),
+            videos: vec![EditorAgentGeneratedVideo {
+                resource_id: Some("resource-video-1".to_string()),
+                object_key: Some("generated/video.mp4".to_string()),
+                asset_object_id: Some("asset-video-1".to_string()),
+                video_src: "/generated-video.mp4".to_string(),
+                thumbnail_src: Some("/generated-video.png".to_string()),
+                width: Some(1280),
+                height: Some(720),
+            }],
+            audios: vec![EditorAgentGeneratedAudio {
+                resource_id: Some("resource-audio-1".to_string()),
+                object_key: Some("generated/audio.mp3".to_string()),
+                asset_object_id: Some("asset-audio-1".to_string()),
+                audio_src: "/generated-audio.mp3".to_string(),
+            }],
+            error: None,
+        };
+        let payload = serde_json::to_value(tool_call).expect("tool call should serialize");
+        assert_eq!(payload["videos"][0]["videoSrc"], "/generated-video.mp4");
+        assert_eq!(payload["externalJobId"], "task-editor-agent-1");
+        assert_eq!(payload["status"], "completed");
+        assert_eq!(payload["audios"][0]["audioSrc"], "/generated-audio.mp3");
+        assert_eq!(
+            payload["displayArgs"]["stringArgs"][0]["value"],
+            "生成像素风角色"
+        );
+        assert_eq!(
+            payload["displayArgs"]["imageArgs"][0]["refs"][0]["imageId"],
+            "sha256:reference-1"
+        );
+        assert_eq!(
+            payload["displayArgs"]["imageArgs"][0]["refs"][0]["objectKey"],
+            "generated/reference.png"
+        );
+        assert_eq!(payload["displayArgs"]["extras"]["priceMudPoints"], 5);
+    }
+
+    #[test]
+    fn legacy_tool_call_status_maps_to_not_completed_on_read() {
+        let tool_call = serde_json::from_value::<EditorAgentToolCall>(json!({
+            "toolName": "generate-image",
+            "status": "executing",
+            "args": {},
+            "displayArgs": {
+                "stringArgs": [],
+                "imageArgs": [],
+                "extras": { "priceMudPoints": 3 }
+            },
+            "images": []
+        }))
+        .expect("legacy status should not break persisted OSS documents");
+
+        let payload = serde_json::to_value(tool_call).expect("tool call should serialize");
+        assert_eq!(payload["status"], "not_completed");
+    }
+
+    #[test]
+    fn legacy_message_generations_migrate_to_tool_call_media() {
+        let document = serde_json::from_value::<EditorAgentConversationMessagesDocument>(json!({
+            "version": 1,
+            "conversationId": "editor-agent-conv-legacy",
+            "messages": [
+                {
+                    "id": "message-user-1",
+                    "role": "user",
+                    "kind": "chat",
+                    "text": "帮我生成一张森林背景",
+                    "attachments": [],
+                    "generations": [],
+                    "status": "completed",
+                    "createdAt": "2026-07-03T00:00:00Z"
+                },
+                {
+                    "id": "message-assistant-1",
+                    "role": "assistant",
+                    "kind": "chat",
+                    "text": "已为你生成森林背景。",
+                    "attachments": [],
+                    "generations": [
+                        {
+                            "toolCallId": "tool-call-legacy-1",
+                            "toolName": "generate_image",
+                            "summary": "森林背景",
+                            "taskId": "task-legacy-1",
+                            "status": "completed",
+                            "model": "z-image",
+                            "images": [
+                                {
+                                    "resourceId": "resource-legacy-1",
+                                    "objectKey": "generated/legacy-forest.png",
+                                    "assetObjectId": "asset-legacy-1",
+                                    "imageSrc": "https://example.test/legacy-forest.png",
+                                    "thumbnailSrc": "https://example.test/legacy-forest-thumb.png",
+                                    "width": 1024,
+                                    "height": 1024
+                                }
+                            ]
+                        }
+                    ],
+                    "status": "completed",
+                    "createdAt": "2026-07-03T00:00:01Z"
+                }
+            ]
+        }))
+        .expect("legacy document should deserialize");
+
+        assert_eq!(document.version, EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION);
+        assert_eq!(document.messages.len(), 3);
+        assert_eq!(document.messages[0].id, 0);
+        assert_eq!(
+            document.messages[0].client_message_id.as_deref(),
+            Some("message-user-1")
+        );
+        assert_eq!(document.messages[1].id, 1);
+        assert!(document.messages[1].client_message_id.is_none());
+        assert_eq!(document.messages[1].role, EditorAgentMessageRole::Assistant);
+        assert_eq!(document.messages[1].text, "已为你生成森林背景。");
+        assert!(document.messages[1].tool_call.is_none());
+        assert_eq!(document.messages[2].id, 2);
+        assert_eq!(document.messages[2].role, EditorAgentMessageRole::System);
+
+        let tool_call = document.messages[2]
+            .tool_call
+            .as_ref()
+            .expect("legacy generation should become a tool call");
+        assert_eq!(tool_call.tool_name, "generate-image");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::Completed);
+        assert_eq!(tool_call.external_job_id.as_deref(), Some("task-legacy-1"));
+        assert_eq!(tool_call.images.len(), 1);
+        assert_eq!(
+            tool_call.images[0].object_key.as_deref(),
+            Some("generated/legacy-forest.png")
+        );
+        assert_eq!(
+            tool_call.images[0].image_src,
+            "https://example.test/legacy-forest.png"
+        );
+
+        let payload = serde_json::to_value(&document).expect("document should serialize");
+        assert_eq!(payload["version"], EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION);
+        assert!(payload["messages"][1].get("generations").is_none());
+        assert!(payload["messages"][1].get("kind").is_none());
+        assert!(payload["messages"][2].get("generations").is_none());
+        assert_eq!(
+            payload["messages"][2]["toolCall"]["images"][0]["objectKey"],
+            "generated/legacy-forest.png"
+        );
     }
 }
diff --git a/server-rs/crates/shared-kernel/src/lib.rs b/server-rs/crates/shared-kernel/src/lib.rs
index ba9d67250..613ef14c3 100644
--- a/server-rs/crates/shared-kernel/src/lib.rs
+++ b/server-rs/crates/shared-kernel/src/lib.rs
@@ -30,6 +30,21 @@ pub fn build_prefixed_seed_id(prefix: &str, seed_micros: i64) -> String {
     format!("{prefix}{seed_micros:x}")
 }
 
+/// 统一生成“前缀 + 十六进制微秒种子 + UUID simple 随机后缀”的唯一 ID。
+/// 纯微秒种子在并发写入时会撞主键，带熵版本保留时间前缀的可读排序，同时保证全局唯一。
+#[cfg(not(target_arch = "wasm32"))]
+pub fn build_prefixed_seed_entropy_id(prefix: &str, seed_micros: i64) -> String {
+    format!("{prefix}{seed_micros:x}_{}", Uuid::new_v4().simple())
+}
+
+/// SpacetimeDB 的 wasm32 模块不应走浏览器/本地随机 UUID 生成。
+#[cfg(target_arch = "wasm32")]
+pub fn build_prefixed_seed_entropy_id(_prefix: &str, _seed_micros: i64) -> String {
+    panic!(
+        "shared-kernel::build_prefixed_seed_entropy_id 不支持 wasm32，请改用显式 ID 或 SpacetimeDB 上下文生成能力"
+    )
+}
+
 /// 统一生成“前缀 + UUID simple”随机 ID，适合会话态或一次性票据主键。
 #[cfg(not(target_arch = "wasm32"))]
 pub fn build_prefixed_uuid_id(prefix: &str) -> String {
@@ -124,6 +139,16 @@ mod tests {
         assert_eq!(build_prefixed_seed_id("assetobj_", 255), "assetobj_ff");
     }
 
+    #[test]
+    fn build_prefixed_seed_entropy_id_keeps_seed_prefix_and_never_collides_on_same_seed() {
+        let first = build_prefixed_seed_entropy_id("assetobj_", 255);
+        let second = build_prefixed_seed_entropy_id("assetobj_", 255);
+
+        assert!(first.starts_with("assetobj_ff_"));
+        assert!(second.starts_with("assetobj_ff_"));
+        assert_ne!(first, second);
+    }
+
     #[test]
     fn format_timestamp_micros_is_stable() {
         assert_eq!(
diff --git a/server-rs/crates/spacetime-client/src/external_generation.rs b/server-rs/crates/spacetime-client/src/external_generation.rs
index 6d70087ea..0b2a2abfc 100644
--- a/server-rs/crates/spacetime-client/src/external_generation.rs
+++ b/server-rs/crates/spacetime-client/src/external_generation.rs
@@ -8,6 +8,43 @@ const EXTERNAL_GENERATION_QUEUE_WAKE_SUBSCRIPTION_QUERIES: [&str; 2] = [
     "SELECT * FROM external_generation_job WHERE status = 'running'",
 ];
 
+#[derive(Debug)]
+pub enum ExternalGenerationJobPhaseUpdateError {
+    LeaseFencingRejected(String),
+    Rejected(String),
+    Rpc(SpacetimeClientError),
+}
+
+impl ExternalGenerationJobPhaseUpdateError {
+    pub fn is_lease_fencing_rejected(&self) -> bool {
+        matches!(self, Self::LeaseFencingRejected(_))
+    }
+
+    pub fn is_retryable_transport(&self) -> bool {
+        matches!(
+            self,
+            Self::Rpc(
+                SpacetimeClientError::Build(_)
+                    | SpacetimeClientError::ConnectDropped
+                    | SpacetimeClientError::Timeout(_)
+            )
+        )
+    }
+}
+
+impl std::fmt::Display for ExternalGenerationJobPhaseUpdateError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::LeaseFencingRejected(message) | Self::Rejected(message) => {
+                formatter.write_str(message)
+            }
+            Self::Rpc(error) => std::fmt::Display::fmt(error, formatter),
+        }
+    }
+}
+
+impl std::error::Error for ExternalGenerationJobPhaseUpdateError {}
+
 pub struct ExternalGenerationQueueWakeSubscription {
     connection: DbConnection,
     _subscriptions: Vec<SubscriptionHandle>,
@@ -257,6 +294,47 @@ impl SpacetimeClient {
         .await
     }
 
+    pub async fn update_external_generation_job_phase(
+        &self,
+        input: ExternalGenerationJobPhaseUpdateRecordInput,
+    ) -> Result<ExternalGenerationJobRecord, ExternalGenerationJobPhaseUpdateError> {
+        let procedure_input = input.into();
+
+        let outcome = self
+            .call_after_connect(
+                "update_external_generation_job_phase_and_return",
+                move |connection, sender| {
+                    connection
+                        .procedures()
+                        .update_external_generation_job_phase_and_return_then(
+                            procedure_input,
+                            move |_, result| {
+                                let mapped = result
+                                    .map_err(SpacetimeClientError::from_sdk_error)
+                                    .map(map_external_generation_job_phase_update_procedure_result);
+                                send_once(&sender, mapped);
+                            },
+                        );
+                },
+            )
+            .await
+            .map_err(ExternalGenerationJobPhaseUpdateError::Rpc)?;
+
+        match outcome {
+            ExternalGenerationJobPhaseUpdateProcedureOutcome::Updated(job) => Ok(job),
+            ExternalGenerationJobPhaseUpdateProcedureOutcome::Rejected { kind, message } => {
+                match kind {
+                    ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected => Err(
+                        ExternalGenerationJobPhaseUpdateError::LeaseFencingRejected(message),
+                    ),
+                    ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected => {
+                        Err(ExternalGenerationJobPhaseUpdateError::Rejected(message))
+                    }
+                }
+            }
+        }
+    }
+
     pub async fn fail_external_generation_job(
         &self,
         input: ExternalGenerationJobFailRecordInput,
@@ -307,6 +385,34 @@ impl SpacetimeClient {
         .await
     }
 
+    // TODO icons gen's result query is not prepared for now.
+    pub async fn get_external_generation_job_generated_artifacts(
+        &self,
+        input: ExternalGenerationJobGetRecordInput,
+    ) -> Result<ExternalGenerationJobArtifactsRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "get_external_generation_job_result_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_external_generation_job_result_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(
+                                map_external_generation_job_result_procedure_generated_artifacts,
+                            );
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
     pub async fn get_external_generation_job_summary(
         &self,
         input: ExternalGenerationJobGetRecordInput,
@@ -460,3 +566,46 @@ fn send_external_generation_queue_wake(sender: &watch::Sender<u64>, counter: &At
     let next = counter.fetch_add(1, Ordering::Relaxed).saturating_add(1);
     let _ = sender.send(next);
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn phase_update_only_retries_transport_errors() {
+        let build = ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Build(
+            "initial websocket connect failed".to_string(),
+        ));
+        assert!(build.is_retryable_transport());
+
+        let timeout = ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Timeout(
+            SpacetimeClientStage::ProcedureResult,
+        ));
+        assert!(timeout.is_retryable_transport());
+        assert!(!timeout.is_lease_fencing_rejected());
+
+        let disconnected =
+            ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::ConnectDropped);
+        assert!(disconnected.is_retryable_transport());
+
+        let lease = ExternalGenerationJobPhaseUpdateError::LeaseFencingRejected(
+            "lease token 不匹配".to_string(),
+        );
+        assert!(!lease.is_retryable_transport());
+        assert!(lease.is_lease_fencing_rejected());
+
+        let rejected = ExternalGenerationJobPhaseUpdateError::Rejected("phase 非法".to_string());
+        assert!(!rejected.is_retryable_transport());
+        assert!(!rejected.is_lease_fencing_rejected());
+
+        let procedure = ExternalGenerationJobPhaseUpdateError::Rpc(
+            SpacetimeClientError::Procedure("procedure rejected".to_string()),
+        );
+        assert!(!procedure.is_retryable_transport());
+
+        let runtime = ExternalGenerationJobPhaseUpdateError::Rpc(SpacetimeClientError::Runtime(
+            "runtime invariant failed".to_string(),
+        ));
+        assert!(!runtime.is_retryable_transport());
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/lib.rs b/server-rs/crates/spacetime-client/src/lib.rs
index a8c73dc43..f51015531 100644
--- a/server-rs/crates/spacetime-client/src/lib.rs
+++ b/server-rs/crates/spacetime-client/src/lib.rs
@@ -57,10 +57,11 @@ pub use mapper::{
     EditorShowcaseCampaignConfigRecord, EditorShowcaseCampaignConfigUpsertRecordInput,
     ExternalApiKeyAuthenticateRecordInput, ExternalApiKeyCreateRecordInput, ExternalApiKeyRecord,
     ExternalApiKeyRevokeRecordInput, ExternalGenerationJobAcknowledgeRecordInput,
-    ExternalGenerationJobClaimRecordInput, ExternalGenerationJobCompleteRecordInput,
-    ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobFailRecordInput,
-    ExternalGenerationJobGetRecordInput, ExternalGenerationJobListRecord,
-    ExternalGenerationJobListRecordInput, ExternalGenerationJobRecord,
+    ExternalGenerationJobArtifactsRecord, ExternalGenerationJobClaimRecordInput,
+    ExternalGenerationJobCompleteRecordInput, ExternalGenerationJobEnqueueRecordInput,
+    ExternalGenerationJobFailRecordInput, ExternalGenerationJobGetRecordInput,
+    ExternalGenerationJobListRecord, ExternalGenerationJobListRecordInput,
+    ExternalGenerationJobPhaseUpdateRecordInput, ExternalGenerationJobRecord,
     ExternalGenerationJobRenewLeaseRecordInput, ExternalGenerationJobSummaryListRecord,
     ExternalGenerationJobSummaryRecord, ExternalGenerationQueueStatsRecord,
     FeatureGateConfigRecord, JumpHopActionRequest, JumpHopActionResponse, JumpHopActionType,
@@ -152,7 +153,9 @@ pub mod editor_agent;
 pub mod editor_project;
 pub mod external_api_key;
 pub mod external_generation;
-pub use external_generation::ExternalGenerationQueueWakeSubscription;
+pub use external_generation::{
+    ExternalGenerationJobPhaseUpdateError, ExternalGenerationQueueWakeSubscription,
+};
 pub mod profile_recharge_expiration;
 pub use profile_recharge_expiration::ProfileRechargeExpirationSubscription;
 
@@ -931,14 +934,11 @@ impl SpacetimeClient {
                     .on_connect(move |_, _, _| {
                         send_connect_once(&connect_sender, Ok(()));
                     })
-                    .on_disconnect(move |_, error| {
+                    .on_disconnect(move |_, _error| {
                         broken_flag.store(true, Ordering::SeqCst);
-                        let message = error
-                            .map(|error| error.to_string())
-                            .unwrap_or_else(|| "SpacetimeDB 连接已断开".to_string());
                         send_connect_once(
                             &disconnect_sender,
-                            Err(SpacetimeClientError::Procedure(message)),
+                            Err(SpacetimeClientError::ConnectDropped),
                         );
                     })
                     .build()
diff --git a/server-rs/crates/spacetime-client/src/mapper.rs b/server-rs/crates/spacetime-client/src/mapper.rs
index 0eb851f95..5e8b748d6 100644
--- a/server-rs/crates/spacetime-client/src/mapper.rs
+++ b/server-rs/crates/spacetime-client/src/mapper.rs
@@ -114,14 +114,19 @@ pub use self::external_api_key::{
     ExternalApiKeyRevokeRecordInput,
 };
 pub use self::external_generation::{
-    ExternalGenerationJobAcknowledgeRecordInput, ExternalGenerationJobClaimRecordInput,
-    ExternalGenerationJobCompleteRecordInput, ExternalGenerationJobEnqueueRecordInput,
-    ExternalGenerationJobFailRecordInput, ExternalGenerationJobGetRecordInput,
-    ExternalGenerationJobListRecord, ExternalGenerationJobListRecordInput,
+    ExternalGenerationJobAcknowledgeRecordInput, ExternalGenerationJobArtifactsRecord,
+    ExternalGenerationJobClaimRecordInput, ExternalGenerationJobCompleteRecordInput,
+    ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobFailRecordInput,
+    ExternalGenerationJobGetRecordInput, ExternalGenerationJobListRecord,
+    ExternalGenerationJobListRecordInput, ExternalGenerationJobPhaseUpdateRecordInput,
     ExternalGenerationJobRecord, ExternalGenerationJobRenewLeaseRecordInput,
     ExternalGenerationJobSummaryListRecord, ExternalGenerationJobSummaryRecord,
     ExternalGenerationQueueStatsRecord,
 };
+pub(crate) use self::external_generation::{
+    ExternalGenerationJobPhaseUpdateProcedureOutcome,
+    map_external_generation_job_phase_update_procedure_result,
+};
 pub use self::jump_hop::{
     JumpHopActionRequest, JumpHopActionResponse, JumpHopActionType, JumpHopCharacterAsset,
     JumpHopDifficulty, JumpHopDraftResponse, JumpHopGalleryCardResponse,
@@ -264,7 +269,9 @@ pub(crate) use self::external_api_key::{
 };
 pub(crate) use self::external_generation::{
     map_external_generation_job_claim_result, map_external_generation_job_list_result,
-    map_external_generation_job_procedure_result, map_external_generation_job_summary_list_result,
+    map_external_generation_job_procedure_result,
+    map_external_generation_job_result_procedure_generated_artifacts,
+    map_external_generation_job_summary_list_result,
     map_external_generation_job_summary_procedure_result,
     map_external_generation_queue_stats_result,
 };
diff --git a/server-rs/crates/spacetime-client/src/mapper/external_generation.rs b/server-rs/crates/spacetime-client/src/mapper/external_generation.rs
index e032f20c5..cf9643c32 100644
--- a/server-rs/crates/spacetime-client/src/mapper/external_generation.rs
+++ b/server-rs/crates/spacetime-client/src/mapper/external_generation.rs
@@ -54,6 +54,17 @@ impl From<ExternalGenerationJobRenewLeaseRecordInput> for ExternalGenerationJobR
     }
 }
 
+impl From<ExternalGenerationJobPhaseUpdateRecordInput> for ExternalGenerationJobPhaseUpdateInput {
+    fn from(input: ExternalGenerationJobPhaseUpdateRecordInput) -> Self {
+        Self {
+            job_id: input.job_id,
+            worker_id: input.worker_id,
+            lease_token: input.lease_token,
+            phase: input.phase,
+        }
+    }
+}
+
 impl From<ExternalGenerationJobFailRecordInput> for ExternalGenerationJobFailInput {
     fn from(input: ExternalGenerationJobFailRecordInput) -> Self {
         Self {
@@ -112,6 +123,57 @@ pub(crate) fn map_external_generation_job_procedure_result(
     Ok(map_external_generation_job_snapshot(job))
 }
 
+pub(crate) fn map_external_generation_job_result_procedure_generated_artifacts(
+    result: ExternalGenerationJobResultProcedureResult,
+) -> Result<ExternalGenerationJobArtifactsRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    let result = result.result.ok_or_else(|| {
+        SpacetimeClientError::missing_snapshot("external_generation_job 结果快照")
+    })?;
+    Ok(ExternalGenerationJobArtifactsRecord {
+        job_id: result.job_id,
+        status: result.status,
+        last_error_message: result.last_error_message,
+        result_payload_json: result.result_payload_json,
+    })
+}
+
+pub(crate) enum ExternalGenerationJobPhaseUpdateProcedureOutcome {
+    Updated(ExternalGenerationJobRecord),
+    Rejected {
+        kind: ExternalGenerationJobPhaseUpdateFailureKind,
+        message: String,
+    },
+}
+
+pub(crate) fn map_external_generation_job_phase_update_procedure_result(
+    result: ExternalGenerationJobPhaseUpdateProcedureResult,
+) -> ExternalGenerationJobPhaseUpdateProcedureOutcome {
+    if !result.ok {
+        return ExternalGenerationJobPhaseUpdateProcedureOutcome::Rejected {
+            kind: result
+                .failure_kind
+                .unwrap_or(ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected),
+            message: result
+                .error_message
+                .unwrap_or_else(|| "SpacetimeDB phase update procedure 返回未知拒绝".to_string()),
+        };
+    }
+
+    match result.job {
+        Some(job) => ExternalGenerationJobPhaseUpdateProcedureOutcome::Updated(
+            map_external_generation_job_snapshot(job),
+        ),
+        None => ExternalGenerationJobPhaseUpdateProcedureOutcome::Rejected {
+            kind: ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected,
+            message: "SpacetimeDB phase update procedure 未返回任务快照".to_string(),
+        },
+    }
+}
+
 pub(crate) fn map_external_generation_job_claim_result(
     result: ExternalGenerationJobProcedureResult,
 ) -> Result<Vec<ExternalGenerationJobRecord>, SpacetimeClientError> {
@@ -237,6 +299,7 @@ fn map_external_generation_job_snapshot(
             .notification_acknowledged_at_micros
             .map(format_timestamp_micros),
         notification_acknowledged_at_micros: snapshot.notification_acknowledged_at_micros,
+        phase: snapshot.phase,
     }
 }
 
@@ -264,6 +327,7 @@ fn map_external_generation_job_summary_snapshot(
             .notification_acknowledged_at_micros
             .map(format_timestamp_micros),
         notification_acknowledged_at_micros: snapshot.notification_acknowledged_at_micros,
+        phase: snapshot.phase,
         warning_message: snapshot.warning_message,
     }
 }
@@ -310,6 +374,14 @@ pub struct ExternalGenerationJobRenewLeaseRecordInput {
     pub renewed_at_micros: i64,
 }
 
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ExternalGenerationJobPhaseUpdateRecordInput {
+    pub job_id: String,
+    pub worker_id: String,
+    pub lease_token: String,
+    pub phase: String,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ExternalGenerationJobFailRecordInput {
     pub job_id: String,
@@ -370,6 +442,15 @@ pub struct ExternalGenerationJobRecord {
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
+    pub phase: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ExternalGenerationJobArtifactsRecord {
+    pub job_id: String,
+    pub status: String,
+    pub last_error_message: Option<String>,
+    pub result_payload_json: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
@@ -401,6 +482,7 @@ pub struct ExternalGenerationJobSummaryRecord {
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
+    pub phase: Option<String>,
     pub warning_message: Option<String>,
 }
 
@@ -425,3 +507,45 @@ pub struct ExternalGenerationQueueStatsRecord {
     pub oldest_claimable_age_micros: Option<i64>,
     pub now_micros: i64,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn phase_update_mapper_keeps_structured_rejection_kind() {
+        let lease_rejection = map_external_generation_job_phase_update_procedure_result(
+            ExternalGenerationJobPhaseUpdateProcedureResult {
+                ok: false,
+                job: None,
+                failure_kind: Some(
+                    ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected,
+                ),
+                error_message: Some("lease 已过期".to_string()),
+            },
+        );
+        assert!(matches!(
+            lease_rejection,
+            ExternalGenerationJobPhaseUpdateProcedureOutcome::Rejected {
+                kind: ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected,
+                ..
+            }
+        ));
+
+        let other_rejection = map_external_generation_job_phase_update_procedure_result(
+            ExternalGenerationJobPhaseUpdateProcedureResult {
+                ok: false,
+                job: None,
+                failure_kind: Some(ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected),
+                error_message: Some("phase 非法".to_string()),
+            },
+        );
+        assert!(matches!(
+            other_rejection,
+            ExternalGenerationJobPhaseUpdateProcedureOutcome::Rejected {
+                kind: ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected,
+                ..
+            }
+        ));
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings.rs b/server-rs/crates/spacetime-client/src/module_bindings.rs
index ad0f6cc8e..13162e635 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings.rs
@@ -1,7 +1,7 @@
 // THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
 // WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
 
-// This was generated using spacetimedb cli version 2.6.0 (commit 31fd1c8c3346dfec38dfcc2e89c2ecf457cf26ff).
+// This was generated using spacetimedb cli version 2.6.1 (commit 052c83fe984a4c4eb7bb4f9afa5c6b1903891d87).
 
 #![allow(unused, clippy::all)]
 use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
@@ -516,9 +516,14 @@ pub mod external_generation_job_get_input_type;
 pub mod external_generation_job_list_input_type;
 pub mod external_generation_job_payload_compaction_input_type;
 pub mod external_generation_job_payload_compaction_procedure_result_type;
+pub mod external_generation_job_phase_update_failure_kind_type;
+pub mod external_generation_job_phase_update_input_type;
+pub mod external_generation_job_phase_update_procedure_result_type;
 pub mod external_generation_job_procedure_result_type;
+pub mod external_generation_job_result_procedure_result_type;
 pub mod external_generation_job_renew_lease_input_type;
 pub mod external_generation_job_snapshot_type;
+pub mod external_generation_job_result_snapshot_type;
 pub mod external_generation_job_summary_backfill_input_type;
 pub mod external_generation_job_summary_backfill_procedure_result_type;
 pub mod external_generation_job_summary_procedure_result_type;
@@ -573,6 +578,7 @@ pub mod get_editor_generation_pricing_config_and_return_procedure;
 pub mod get_editor_project_and_return_procedure;
 pub mod get_editor_showcase_campaign_config_and_return_procedure;
 pub mod get_external_generation_job_and_return_procedure;
+pub mod get_external_generation_job_result_and_return_procedure;
 pub mod get_external_generation_job_summary_and_return_procedure;
 pub mod get_external_generation_queue_stats_and_return_procedure;
 pub mod get_feature_gate_config_procedure;
@@ -1326,6 +1332,7 @@ pub mod update_editor_asset_and_return_procedure;
 pub mod update_editor_asset_folder_and_return_procedure;
 pub mod update_editor_project_resource_showcase_and_return_procedure;
 pub mod update_editor_showcase_asset_display_and_return_procedure;
+pub mod update_external_generation_job_phase_and_return_procedure;
 pub mod update_jump_hop_work_procedure;
 pub mod update_match_3_d_work_procedure;
 pub mod update_puzzle_clear_work_procedure;
@@ -1948,9 +1955,14 @@ pub use external_generation_job_get_input_type::ExternalGenerationJobGetInput;
 pub use external_generation_job_list_input_type::ExternalGenerationJobListInput;
 pub use external_generation_job_payload_compaction_input_type::ExternalGenerationJobPayloadCompactionInput;
 pub use external_generation_job_payload_compaction_procedure_result_type::ExternalGenerationJobPayloadCompactionProcedureResult;
+pub use external_generation_job_phase_update_failure_kind_type::ExternalGenerationJobPhaseUpdateFailureKind;
+pub use external_generation_job_phase_update_input_type::ExternalGenerationJobPhaseUpdateInput;
+pub use external_generation_job_phase_update_procedure_result_type::ExternalGenerationJobPhaseUpdateProcedureResult;
 pub use external_generation_job_procedure_result_type::ExternalGenerationJobProcedureResult;
+pub use external_generation_job_result_procedure_result_type::ExternalGenerationJobResultProcedureResult;
 pub use external_generation_job_renew_lease_input_type::ExternalGenerationJobRenewLeaseInput;
 pub use external_generation_job_snapshot_type::ExternalGenerationJobSnapshot;
+pub use external_generation_job_result_snapshot_type::ExternalGenerationJobResultSnapshot;
 pub use external_generation_job_summary_backfill_input_type::ExternalGenerationJobSummaryBackfillInput;
 pub use external_generation_job_summary_backfill_procedure_result_type::ExternalGenerationJobSummaryBackfillProcedureResult;
 pub use external_generation_job_summary_procedure_result_type::ExternalGenerationJobSummaryProcedureResult;
@@ -2005,6 +2017,7 @@ pub use get_editor_generation_pricing_config_and_return_procedure::get_editor_ge
 pub use get_editor_project_and_return_procedure::get_editor_project_and_return;
 pub use get_editor_showcase_campaign_config_and_return_procedure::get_editor_showcase_campaign_config_and_return;
 pub use get_external_generation_job_and_return_procedure::get_external_generation_job_and_return;
+pub use get_external_generation_job_result_and_return_procedure::get_external_generation_job_result_and_return;
 pub use get_external_generation_job_summary_and_return_procedure::get_external_generation_job_summary_and_return;
 pub use get_external_generation_queue_stats_and_return_procedure::get_external_generation_queue_stats_and_return;
 pub use get_feature_gate_config_procedure::get_feature_gate_config;
@@ -2758,6 +2771,7 @@ pub use update_editor_asset_and_return_procedure::update_editor_asset_and_return
 pub use update_editor_asset_folder_and_return_procedure::update_editor_asset_folder_and_return;
 pub use update_editor_project_resource_showcase_and_return_procedure::update_editor_project_resource_showcase_and_return;
 pub use update_editor_showcase_asset_display_and_return_procedure::update_editor_showcase_asset_display_and_return;
+pub use update_external_generation_job_phase_and_return_procedure::update_external_generation_job_phase_and_return;
 pub use update_jump_hop_work_procedure::update_jump_hop_work;
 pub use update_match_3_d_work_procedure::update_match_3_d_work;
 pub use update_puzzle_clear_work_procedure::update_puzzle_clear_work;
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_failure_kind_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_failure_kind_type.rs
new file mode 100644
index 000000000..9c876a3d1
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_failure_kind_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+#[derive(Copy, Eq, Hash)]
+pub enum ExternalGenerationJobPhaseUpdateFailureKind {
+    LeaseFencingRejected,
+
+    OtherRejected,
+}
+
+impl __sdk::InModule for ExternalGenerationJobPhaseUpdateFailureKind {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_input_type.rs
new file mode 100644
index 000000000..4d91f5eea
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_input_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalGenerationJobPhaseUpdateInput {
+    pub job_id: String,
+    pub worker_id: String,
+    pub lease_token: String,
+    pub phase: String,
+}
+
+impl __sdk::InModule for ExternalGenerationJobPhaseUpdateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_procedure_result_type.rs
new file mode 100644
index 000000000..48fa66a08
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_phase_update_procedure_result_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_generation_job_phase_update_failure_kind_type::ExternalGenerationJobPhaseUpdateFailureKind;
+use super::external_generation_job_snapshot_type::ExternalGenerationJobSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalGenerationJobPhaseUpdateProcedureResult {
+    pub ok: bool,
+    pub job: Option<ExternalGenerationJobSnapshot>,
+    pub failure_kind: Option<ExternalGenerationJobPhaseUpdateFailureKind>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for ExternalGenerationJobPhaseUpdateProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_procedure_result_type.rs
new file mode 100644
index 000000000..4b07dda7d
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_generation_job_result_snapshot_type::ExternalGenerationJobResultSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalGenerationJobResultProcedureResult {
+    pub ok: bool,
+    pub result: Option<ExternalGenerationJobResultSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for ExternalGenerationJobResultProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_snapshot_type.rs
new file mode 100644
index 000000000..881d0d786
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_result_snapshot_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalGenerationJobResultSnapshot {
+    pub job_id: String,
+    pub status: String,
+    pub last_error_message: Option<String>,
+    pub result_payload_json: Option<String>,
+}
+
+impl __sdk::InModule for ExternalGenerationJobResultSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_snapshot_type.rs
index a5a208caf..8778d141c 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_snapshot_type.rs
@@ -31,6 +31,7 @@ pub struct ExternalGenerationJobSnapshot {
     pub price_mud_points: u64,
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
+    pub phase: Option<String>,
 }
 
 impl __sdk::InModule for ExternalGenerationJobSnapshot {
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_snapshot_type.rs
index c802d64ae..34d2af96a 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_snapshot_type.rs
@@ -24,6 +24,7 @@ pub struct ExternalGenerationJobSummarySnapshot {
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
     pub warning_message: Option<String>,
+    pub phase: Option<String>,
 }
 
 impl __sdk::InModule for ExternalGenerationJobSummarySnapshot {
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_type.rs
index 38c59d165..ce4fad0a9 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_summary_type.rs
@@ -24,6 +24,7 @@ pub struct ExternalGenerationJobSummary {
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at: Option<__sdk::Timestamp>,
     pub warning_message: Option<String>,
+    pub phase: Option<String>,
 }
 
 impl __sdk::InModule for ExternalGenerationJobSummary {
@@ -55,6 +56,7 @@ pub struct ExternalGenerationJobSummaryCols {
     pub notification_acknowledged_at:
         __sdk::__query_builder::Col<ExternalGenerationJobSummary, Option<__sdk::Timestamp>>,
     pub warning_message: __sdk::__query_builder::Col<ExternalGenerationJobSummary, Option<String>>,
+    pub phase: __sdk::__query_builder::Col<ExternalGenerationJobSummary, Option<String>>,
 }
 
 impl __sdk::__query_builder::HasCols for ExternalGenerationJobSummary {
@@ -81,6 +83,7 @@ impl __sdk::__query_builder::HasCols for ExternalGenerationJobSummary {
                 "notification_acknowledged_at",
             ),
             warning_message: __sdk::__query_builder::Col::new(table_name, "warning_message"),
+            phase: __sdk::__query_builder::Col::new(table_name, "phase"),
         }
     }
 }
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_type.rs
index ec62daa60..f63d494a4 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_generation_job_type.rs
@@ -31,6 +31,7 @@ pub struct ExternalGenerationJob {
     pub price_mud_points: u64,
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at: Option<__sdk::Timestamp>,
+    pub phase: Option<String>,
 }
 
 impl __sdk::InModule for ExternalGenerationJob {
@@ -67,6 +68,7 @@ pub struct ExternalGenerationJobCols {
     pub refund_ledger_id: __sdk::__query_builder::Col<ExternalGenerationJob, Option<String>>,
     pub notification_acknowledged_at:
         __sdk::__query_builder::Col<ExternalGenerationJob, Option<__sdk::Timestamp>>,
+    pub phase: __sdk::__query_builder::Col<ExternalGenerationJob, Option<String>>,
 }
 
 impl __sdk::__query_builder::HasCols for ExternalGenerationJob {
@@ -106,6 +108,7 @@ impl __sdk::__query_builder::HasCols for ExternalGenerationJob {
                 table_name,
                 "notification_acknowledged_at",
             ),
+            phase: __sdk::__query_builder::Col::new(table_name, "phase"),
         }
     }
 }
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_external_generation_job_result_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_external_generation_job_result_and_return_procedure.rs
new file mode 100644
index 000000000..d0ff920cd
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_external_generation_job_result_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_generation_job_get_input_type::ExternalGenerationJobGetInput;
+use super::external_generation_job_result_procedure_result_type::ExternalGenerationJobResultProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetExternalGenerationJobResultAndReturnArgs {
+    pub input: ExternalGenerationJobGetInput,
+}
+
+impl __sdk::InModule for GetExternalGenerationJobResultAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_external_generation_job_result_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_external_generation_job_result_and_return {
+    fn get_external_generation_job_result_and_return(&self, input: ExternalGenerationJobGetInput) {
+        self.get_external_generation_job_result_and_return_then(input, |_, _| {});
+    }
+
+    fn get_external_generation_job_result_and_return_then(
+        &self,
+        input: ExternalGenerationJobGetInput,
+
+        __callback: impl FnOnce(
+            &super::ProcedureEventContext,
+            Result<ExternalGenerationJobResultProcedureResult, __sdk::InternalError>,
+        ) + Send
+        + 'static,
+    );
+}
+
+impl get_external_generation_job_result_and_return for super::RemoteProcedures {
+    fn get_external_generation_job_result_and_return_then(
+        &self,
+        input: ExternalGenerationJobGetInput,
+
+        __callback: impl FnOnce(
+            &super::ProcedureEventContext,
+            Result<ExternalGenerationJobResultProcedureResult, __sdk::InternalError>,
+        ) + Send
+        + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalGenerationJobResultProcedureResult>(
+                "get_external_generation_job_result_and_return",
+                GetExternalGenerationJobResultAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/update_external_generation_job_phase_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/update_external_generation_job_phase_and_return_procedure.rs
new file mode 100644
index 000000000..890d5b4d6
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/update_external_generation_job_phase_and_return_procedure.rs
@@ -0,0 +1,62 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_generation_job_phase_update_input_type::ExternalGenerationJobPhaseUpdateInput;
+use super::external_generation_job_phase_update_procedure_result_type::ExternalGenerationJobPhaseUpdateProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct UpdateExternalGenerationJobPhaseAndReturnArgs {
+    pub input: ExternalGenerationJobPhaseUpdateInput,
+}
+
+impl __sdk::InModule for UpdateExternalGenerationJobPhaseAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `update_external_generation_job_phase_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait update_external_generation_job_phase_and_return {
+    fn update_external_generation_job_phase_and_return(
+        &self,
+        input: ExternalGenerationJobPhaseUpdateInput,
+    ) {
+        self.update_external_generation_job_phase_and_return_then(input, |_, _| {});
+    }
+
+    fn update_external_generation_job_phase_and_return_then(
+        &self,
+        input: ExternalGenerationJobPhaseUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalGenerationJobPhaseUpdateProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl update_external_generation_job_phase_and_return for super::RemoteProcedures {
+    fn update_external_generation_job_phase_and_return_then(
+        &self,
+        input: ExternalGenerationJobPhaseUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalGenerationJobPhaseUpdateProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalGenerationJobPhaseUpdateProcedureResult>(
+                "update_external_generation_job_phase_and_return",
+                UpdateExternalGenerationJobPhaseAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-module/src/editor_project_storage.rs b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
index 70cfc7cea..19f80f00c 100644
--- a/server-rs/crates/spacetime-module/src/editor_project_storage.rs
+++ b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
@@ -1095,7 +1095,8 @@ pub fn find_editor_asset_group_source_and_return(
     ctx: &mut ProcedureContext,
     input: EditorAssetGroupSourceLookupInput,
 ) -> EditorAssetProcedureResult {
-    match ctx.try_with_tx(|tx| find_editor_asset_group_source(tx, input.clone())) {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| find_editor_asset_group_source(tx, caller, input.clone())) {
         Ok(asset) => editor_asset_ok(asset),
         Err(message) => editor_asset_error(message),
     }
@@ -1139,7 +1140,8 @@ pub fn create_editor_asset_and_return(
     ctx: &mut ProcedureContext,
     input: EditorAssetCreateInput,
 ) -> EditorAssetProcedureResult {
-    match ctx.try_with_tx(|tx| create_editor_asset(tx, input.clone())) {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| create_editor_asset(tx, caller, input.clone())) {
         Ok(asset) => editor_asset_ok(Some(asset)),
         Err(message) => editor_asset_error(message),
     }
@@ -1150,7 +1152,8 @@ pub fn complete_editor_asset_group_cohort_and_return(
     ctx: &mut ProcedureContext,
     input: EditorAssetGroupCohortCompleteInput,
 ) -> EditorAssetProcedureResult {
-    match ctx.try_with_tx(|tx| complete_editor_asset_group_cohort(tx, input.clone())) {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| complete_editor_asset_group_cohort(tx, caller, input.clone())) {
         Ok(asset) => editor_asset_ok(Some(asset)),
         Err(message) => editor_asset_error(message),
     }
@@ -1855,9 +1858,10 @@ fn admin_list_editor_assets(
 
 fn find_editor_asset_group_source(
     ctx: &ReducerContext,
+    caller: Identity,
     input: EditorAssetGroupSourceLookupInput,
 ) -> Result<Option<EditorAssetSnapshot>, String> {
-    require_editor_generation_runtime_service_identity(ctx, ctx.sender())?;
+    require_editor_generation_runtime_service_identity(ctx, caller)?;
     let owner_user_id = normalize_required(&input.owner_user_id, "owner_user_id")?;
     let source_resource_ids = input
         .source_resource_ids
@@ -1924,9 +1928,10 @@ fn find_editor_asset_group_source(
 
 fn complete_editor_asset_group_cohort(
     ctx: &ReducerContext,
+    caller: Identity,
     input: EditorAssetGroupCohortCompleteInput,
 ) -> Result<EditorAssetSnapshot, String> {
-    require_editor_generation_runtime_service_identity(ctx, ctx.sender())?;
+    require_editor_generation_runtime_service_identity(ctx, caller)?;
     let owner_user_id = normalize_required(&input.owner_user_id, "owner_user_id")?;
     let task_id = normalize_required(&input.task_id, "task_id")?;
     let group_task_id = normalize_required(&input.group_task_id, "group_task_id")?;
@@ -2101,6 +2106,7 @@ fn delete_editor_asset_folder(
 
 fn create_editor_asset(
     ctx: &ReducerContext,
+    caller: Identity,
     input: EditorAssetCreateInput,
 ) -> Result<EditorAssetSnapshot, String> {
     let asset_id = normalize_required(&input.asset_id, "editor_asset.asset_id")?;
@@ -2131,7 +2137,7 @@ fn create_editor_asset(
         return Err("素材任务预期产物数量必须与归组 Task ID 一起提供".to_string());
     }
     if group_task_id.is_some() {
-        require_editor_generation_runtime_service_identity(ctx, ctx.sender())?;
+        require_editor_generation_runtime_service_identity(ctx, caller)?;
     }
     ctx.db.editor_asset().insert(EditorAsset {
         asset_id: asset_id.clone(),
diff --git a/server-rs/crates/spacetime-module/src/external_generation.rs b/server-rs/crates/spacetime-module/src/external_generation.rs
index 105db0900..ce1a19396 100644
--- a/server-rs/crates/spacetime-module/src/external_generation.rs
+++ b/server-rs/crates/spacetime-module/src/external_generation.rs
@@ -7,6 +7,8 @@ const EXTERNAL_GENERATION_STATUS_RUNNING: &str = "running";
 const EXTERNAL_GENERATION_STATUS_COMPLETED: &str = "completed";
 const EXTERNAL_GENERATION_STATUS_FAILED: &str = "failed";
 const EXTERNAL_GENERATION_STATUS_CANCELLED: &str = "cancelled";
+const EXTERNAL_GENERATION_PHASE_GENERATING: &str = "generating";
+const EXTERNAL_GENERATION_PHASE_PROCESSING: &str = "processing";
 const EXTERNAL_GENERATION_EVENT_ENQUEUED: &str = "enqueued";
 const EXTERNAL_GENERATION_EVENT_CLAIMED: &str = "claimed";
 const EXTERNAL_GENERATION_EVENT_LEASE_RENEWED: &str = "lease_renewed";
@@ -85,6 +87,8 @@ pub struct ExternalGenerationJob {
     pub(crate) refund_ledger_id: Option<String>,
     #[default(None::<Timestamp>)]
     pub(crate) notification_acknowledged_at: Option<Timestamp>,
+    #[default(None::<String>)]
+    pub(crate) phase: Option<String>,
 }
 
 #[spacetimedb::table(
@@ -139,6 +143,8 @@ pub struct ExternalGenerationJobSummary {
     pub(crate) notification_acknowledged_at: Option<Timestamp>,
     #[default(None::<String>)]
     pub(crate) warning_message: Option<String>,
+    #[default(None::<String>)]
+    pub(crate) phase: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
@@ -174,6 +180,20 @@ pub struct ExternalGenerationJobRenewLeaseInput {
     pub renewed_at_micros: i64,
 }
 
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalGenerationJobPhaseUpdateInput {
+    pub job_id: String,
+    pub worker_id: String,
+    pub lease_token: String,
+    pub phase: String,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, SpacetimeType)]
+pub enum ExternalGenerationJobPhaseUpdateFailureKind {
+    LeaseFencingRejected,
+    OtherRejected,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
 pub struct ExternalGenerationJobCompleteInput {
     pub job_id: String,
@@ -257,6 +277,7 @@ pub struct ExternalGenerationJobSnapshot {
     pub price_mud_points: u64,
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
+    pub phase: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
@@ -271,6 +292,30 @@ pub struct ExternalGenerationJobProcedureResult {
     pub error_message: Option<String>,
 }
 
+// Private backend read for reconciliation; it intentionally excludes job request and lease data.
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalGenerationJobResultSnapshot {
+    pub job_id: String,
+    pub status: String,
+    pub last_error_message: Option<String>,
+    pub result_payload_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalGenerationJobResultProcedureResult {
+    pub ok: bool,
+    pub result: Option<ExternalGenerationJobResultSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalGenerationJobPhaseUpdateProcedureResult {
+    pub ok: bool,
+    pub job: Option<ExternalGenerationJobSnapshot>,
+    pub failure_kind: Option<ExternalGenerationJobPhaseUpdateFailureKind>,
+    pub error_message: Option<String>,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
 pub struct ExternalGenerationJobSummarySnapshot {
     pub job_id: String,
@@ -290,6 +335,7 @@ pub struct ExternalGenerationJobSummarySnapshot {
     pub refund_ledger_id: Option<String>,
     pub notification_acknowledged_at_micros: Option<i64>,
     pub warning_message: Option<String>,
+    pub phase: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
@@ -430,6 +476,34 @@ pub fn renew_external_generation_job_lease_and_return(
     }
 }
 
+#[spacetimedb::procedure]
+pub fn update_external_generation_job_phase_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalGenerationJobPhaseUpdateInput,
+) -> ExternalGenerationJobPhaseUpdateProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        crate::editor_project_storage::require_editor_generation_runtime_service_identity(
+            tx, caller,
+        )
+        .map_err(ExternalGenerationJobPhaseUpdateError::other)?;
+        update_external_generation_job_phase_tx(tx, input.clone())
+    }) {
+        Ok(job) => ExternalGenerationJobPhaseUpdateProcedureResult {
+            ok: true,
+            job: Some(job),
+            failure_kind: None,
+            error_message: None,
+        },
+        Err(error) => ExternalGenerationJobPhaseUpdateProcedureResult {
+            ok: false,
+            job: None,
+            failure_kind: Some(error.kind),
+            error_message: Some(error.message),
+        },
+    }
+}
+
 #[spacetimedb::procedure]
 pub fn fail_external_generation_job_and_return(
     ctx: &mut ProcedureContext,
@@ -464,6 +538,23 @@ pub fn get_external_generation_job_and_return(
     }
 }
 
+#[spacetimedb::procedure]
+pub fn get_external_generation_job_result_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalGenerationJobGetInput,
+) -> ExternalGenerationJobResultProcedureResult {
+    let caller = ctx.sender();
+    match ctx.try_with_tx(|tx| {
+        crate::editor_project_storage::require_editor_generation_runtime_service_identity(
+            tx, caller,
+        )?;
+        get_external_generation_job_result_tx(tx, input.clone())
+    }) {
+        Ok(result) => single_external_generation_job_result_read_result(result),
+        Err(message) => failed_external_generation_job_result_read_result(message),
+    }
+}
+
 #[spacetimedb::procedure]
 pub fn list_external_generation_jobs_and_return(
     ctx: &mut ProcedureContext,
@@ -684,6 +775,7 @@ fn enqueue_external_generation_job_tx(
         price_mud_points: input.price_mud_points,
         refund_ledger_id: None,
         notification_acknowledged_at: None,
+        phase: None,
     };
     persist_external_generation_job_row(ctx, row.clone());
     insert_external_generation_job_event(
@@ -758,6 +850,7 @@ fn claim_external_generation_jobs_tx(
             claim_time,
         );
         row.status = EXTERNAL_GENERATION_STATUS_RUNNING.to_string();
+        row.phase = Some(EXTERNAL_GENERATION_PHASE_GENERATING.to_string());
         row.worker_id = Some(worker_id.clone());
         row.lease_expires_at = Some(lease_expires_at);
         row.lease_token = Some(lease_token);
@@ -873,6 +966,34 @@ fn get_external_generation_job_tx(
         .map(map_external_generation_job_summary_to_compat_snapshot)
 }
 
+fn get_external_generation_job_result_tx(
+    ctx: &ReducerContext,
+    input: ExternalGenerationJobGetInput,
+) -> Result<ExternalGenerationJobResultSnapshot, String> {
+    validate_required("external_generation_job.job_id", &input.job_id)?;
+    validate_required(
+        "external_generation_job.owner_user_id",
+        &input.owner_user_id,
+    )?;
+    let job_id = input.job_id.trim().to_string();
+    let owner_user_id = input.owner_user_id.trim();
+    let row = ctx
+        .db
+        .external_generation_job()
+        .job_id()
+        .find(&job_id)
+        .ok_or_else(|| "external_generation_job 不存在".to_string())?;
+    if row.owner_user_id.trim() != owner_user_id {
+        return Err("external_generation_job 不存在".to_string());
+    }
+    Ok(ExternalGenerationJobResultSnapshot {
+        job_id: row.job_id,
+        status: row.status,
+        last_error_message: row.last_error_message,
+        result_payload_json: row.result_payload_json,
+    })
+}
+
 fn list_external_generation_jobs_tx(
     ctx: &ReducerContext,
     input: ExternalGenerationJobListInput,
@@ -1275,6 +1396,24 @@ fn renew_external_generation_job_lease_tx(
     Ok(map_external_generation_job_row(row))
 }
 
+fn update_external_generation_job_phase_tx(
+    ctx: &ReducerContext,
+    input: ExternalGenerationJobPhaseUpdateInput,
+) -> Result<ExternalGenerationJobSnapshot, ExternalGenerationJobPhaseUpdateError> {
+    let phase = normalize_external_generation_job_phase(&input.phase)
+        .map_err(ExternalGenerationJobPhaseUpdateError::other)?;
+    let mut row = get_worker_owned_external_generation_job_for_phase_update(
+        ctx,
+        &input.job_id,
+        &input.worker_id,
+        &input.lease_token,
+    )?;
+    row.phase = Some(phase);
+    row.updated_at = ctx.timestamp;
+    persist_external_generation_job_row(ctx, row.clone());
+    Ok(map_external_generation_job_row(row))
+}
+
 fn fail_external_generation_job_tx(
     ctx: &ReducerContext,
     input: ExternalGenerationJobFailInput,
@@ -1414,28 +1553,96 @@ fn get_worker_owned_external_generation_job(
     worker_id: &str,
     lease_token: &str,
 ) -> Result<ExternalGenerationJob, String> {
-    validate_required("external_generation_job.job_id", job_id)?;
-    validate_required("external_generation_job.worker_id", worker_id)?;
-    validate_required("external_generation_job.lease_token", lease_token)?;
+    get_worker_owned_external_generation_job_for_phase_update(ctx, job_id, worker_id, lease_token)
+        .map_err(|error| error.message)
+}
+
+#[derive(Debug)]
+struct ExternalGenerationJobPhaseUpdateError {
+    kind: ExternalGenerationJobPhaseUpdateFailureKind,
+    message: String,
+}
+
+impl ExternalGenerationJobPhaseUpdateError {
+    fn lease_fencing(message: impl Into<String>) -> Self {
+        Self {
+            kind: ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected,
+            message: message.into(),
+        }
+    }
+
+    fn other(message: impl Into<String>) -> Self {
+        Self {
+            kind: ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected,
+            message: message.into(),
+        }
+    }
+}
+
+impl std::fmt::Display for ExternalGenerationJobPhaseUpdateError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(self.message.as_str())
+    }
+}
+
+impl std::error::Error for ExternalGenerationJobPhaseUpdateError {}
+
+fn get_worker_owned_external_generation_job_for_phase_update(
+    ctx: &ReducerContext,
+    job_id: &str,
+    worker_id: &str,
+    lease_token: &str,
+) -> Result<ExternalGenerationJob, ExternalGenerationJobPhaseUpdateError> {
+    validate_required("external_generation_job.job_id", job_id)
+        .map_err(ExternalGenerationJobPhaseUpdateError::other)?;
+    validate_required("external_generation_job.worker_id", worker_id)
+        .map_err(ExternalGenerationJobPhaseUpdateError::other)?;
+    validate_required("external_generation_job.lease_token", lease_token)
+        .map_err(ExternalGenerationJobPhaseUpdateError::other)?;
     let row = ctx
         .db
         .external_generation_job()
         .job_id()
         .find(&job_id.trim().to_string())
-        .ok_or_else(|| "external_generation_job 不存在".to_string())?;
+        .ok_or_else(|| {
+            ExternalGenerationJobPhaseUpdateError::lease_fencing("external_generation_job 不存在")
+        })?;
+    validate_external_generation_job_phase_update_lease(
+        &row,
+        worker_id,
+        lease_token,
+        ctx.timestamp,
+    )?;
+    Ok(row)
+}
+
+fn validate_external_generation_job_phase_update_lease(
+    row: &ExternalGenerationJob,
+    worker_id: &str,
+    lease_token: &str,
+    now: Timestamp,
+) -> Result<(), ExternalGenerationJobPhaseUpdateError> {
     if row.status != EXTERNAL_GENERATION_STATUS_RUNNING {
-        return Err("external_generation_job 当前不是 running 状态".to_string());
+        return Err(ExternalGenerationJobPhaseUpdateError::lease_fencing(
+            "external_generation_job 当前不是 running 状态",
+        ));
     }
     if !is_external_generation_job_owned_by_worker(&row, worker_id) {
-        return Err("external_generation_job worker lease 不匹配".to_string());
+        return Err(ExternalGenerationJobPhaseUpdateError::lease_fencing(
+            "external_generation_job worker lease 不匹配",
+        ));
     }
     if !is_external_generation_job_owned_by_lease_token(&row, lease_token) {
-        return Err("external_generation_job lease token 不匹配".to_string());
+        return Err(ExternalGenerationJobPhaseUpdateError::lease_fencing(
+            "external_generation_job lease token 不匹配",
+        ));
     }
-    if !is_external_generation_job_lease_active(&row, ctx.timestamp) {
-        return Err("external_generation_job lease 已过期".to_string());
+    if !is_external_generation_job_lease_active(row, now) {
+        return Err(ExternalGenerationJobPhaseUpdateError::lease_fencing(
+            "external_generation_job lease 已过期",
+        ));
     }
-    Ok(row)
+    Ok(())
 }
 
 fn is_external_generation_job_owned_by_worker(
@@ -1679,6 +1886,18 @@ fn normalize_external_generation_job_status_filter(statuses: &[String]) -> Vec<&
         .collect()
 }
 
+fn normalize_external_generation_job_phase(phase: &str) -> Result<String, String> {
+    match phase.trim() {
+        EXTERNAL_GENERATION_PHASE_GENERATING => {
+            Ok(EXTERNAL_GENERATION_PHASE_GENERATING.to_string())
+        }
+        EXTERNAL_GENERATION_PHASE_PROCESSING => {
+            Ok(EXTERNAL_GENERATION_PHASE_PROCESSING.to_string())
+        }
+        _ => Err("external_generation_job.phase 只支持 generating 或 processing".to_string()),
+    }
+}
+
 fn record_external_generation_claimable_age(
     stats: &mut ExternalGenerationQueueStatsSnapshot,
     row: &ExternalGenerationJob,
@@ -1770,6 +1989,7 @@ fn build_external_generation_job_summary_row(
         warning_message: extract_external_generation_warning_message(
             row.result_payload_json.as_deref(),
         ),
+        phase: row.phase.clone(),
     }
 }
 
@@ -2016,6 +2236,7 @@ fn map_external_generation_job_row(row: ExternalGenerationJob) -> ExternalGenera
         price_mud_points: row.price_mud_points,
         refund_ledger_id: row.refund_ledger_id,
         notification_acknowledged_at_micros,
+        phase: row.phase,
     }
 }
 
@@ -2046,6 +2267,7 @@ fn map_external_generation_job_summary_row(
             .notification_acknowledged_at
             .map(|value| value.to_micros_since_unix_epoch()),
         warning_message: row.warning_message,
+        phase: row.phase,
     }
 }
 
@@ -2082,6 +2304,7 @@ fn map_external_generation_job_summary_to_compat_snapshot(
         price_mud_points: summary.price_mud_points,
         refund_ledger_id: summary.refund_ledger_id,
         notification_acknowledged_at_micros: summary.notification_acknowledged_at_micros,
+        phase: summary.phase,
     }
 }
 
@@ -2113,6 +2336,26 @@ fn failed_external_generation_job_result(message: String) -> ExternalGenerationJ
     }
 }
 
+fn single_external_generation_job_result_read_result(
+    result: ExternalGenerationJobResultSnapshot,
+) -> ExternalGenerationJobResultProcedureResult {
+    ExternalGenerationJobResultProcedureResult {
+        ok: true,
+        result: Some(result),
+        error_message: None,
+    }
+}
+
+fn failed_external_generation_job_result_read_result(
+    message: String,
+) -> ExternalGenerationJobResultProcedureResult {
+    ExternalGenerationJobResultProcedureResult {
+        ok: false,
+        result: None,
+        error_message: Some(message),
+    }
+}
+
 fn single_external_generation_job_summary_result(
     job: ExternalGenerationJobSummarySnapshot,
 ) -> ExternalGenerationJobSummaryProcedureResult {
@@ -2409,6 +2652,87 @@ fn normalize_optional_text(value: &str) -> Option<String> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn external_generation_phase_only_accepts_known_execution_phases() {
+        assert_eq!(
+            normalize_external_generation_job_phase(" processing ").as_deref(),
+            Ok(EXTERNAL_GENERATION_PHASE_PROCESSING)
+        );
+        assert!(normalize_external_generation_job_phase("uploading").is_err());
+    }
+
+    #[test]
+    fn external_generation_phase_rejection_kind_is_machine_readable() {
+        let lease = ExternalGenerationJobPhaseUpdateError::lease_fencing("lease 已过期");
+        assert_eq!(
+            lease.kind,
+            ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected
+        );
+        assert_eq!(lease.message, "lease 已过期");
+
+        let other = ExternalGenerationJobPhaseUpdateError::other("phase 非法");
+        assert_eq!(
+            other.kind,
+            ExternalGenerationJobPhaseUpdateFailureKind::OtherRejected
+        );
+        assert_eq!(other.message, "phase 非法");
+    }
+
+    #[test]
+    fn external_generation_phase_lease_guard_classifies_every_fencing_rejection() {
+        let mut row = external_generation_job_fixture(EXTERNAL_GENERATION_STATUS_RUNNING);
+        row.worker_id = Some("worker-a".to_string());
+        row.lease_token = Some("lease-1".to_string());
+        row.lease_expires_at = Some(micros(2_000));
+
+        assert!(
+            validate_external_generation_job_phase_update_lease(
+                &row,
+                "worker-a",
+                "lease-1",
+                micros(1_999),
+            )
+            .is_ok()
+        );
+
+        let mut terminal = row.clone();
+        terminal.status = EXTERNAL_GENERATION_STATUS_COMPLETED.to_string();
+        let cases = [
+            validate_external_generation_job_phase_update_lease(
+                &terminal,
+                "worker-a",
+                "lease-1",
+                micros(1_999),
+            ),
+            validate_external_generation_job_phase_update_lease(
+                &row,
+                "worker-b",
+                "lease-1",
+                micros(1_999),
+            ),
+            validate_external_generation_job_phase_update_lease(
+                &row,
+                "worker-a",
+                "lease-2",
+                micros(1_999),
+            ),
+            validate_external_generation_job_phase_update_lease(
+                &row,
+                "worker-a",
+                "lease-1",
+                micros(2_000),
+            ),
+        ];
+
+        for result in cases {
+            let error = result.expect_err("stale worker 必须被 fencing 拒绝");
+            assert_eq!(
+                error.kind,
+                ExternalGenerationJobPhaseUpdateFailureKind::LeaseFencingRejected
+            );
+        }
+    }
+
     #[test]
     fn external_generation_job_result_failure_is_structured() {
         let result = failed_external_generation_job_result("失败".to_string());
@@ -2948,6 +3272,7 @@ mod tests {
             price_mud_points: 10,
             refund_ledger_id: None,
             notification_acknowledged_at: None,
+            phase: None,
         }
     }
 
diff --git a/server-rs/crates/spacetime-module/src/migration.rs b/server-rs/crates/spacetime-module/src/migration.rs
index c1f42861f..f5be3b9c1 100644
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -254,6 +254,8 @@ macro_rules! migration_tables {
             editor_project_resource,
             editor_asset_folder,
             editor_asset,
+            editor_asset_group_source_provenance,
+            editor_asset_group_cohort,
             editor_showcase_asset,
             editor_showcase_asset_like,
             editor_showcase_campaign_config,
@@ -1376,6 +1378,15 @@ fn normalize_migration_row(table_name: &str, value: &serde_json::Value) -> serde
                 .or_insert(serde_json::Value::Null);
         }
     }
+    if table_name == "external_generation_job" || table_name == "external_generation_job_summary" {
+        if let Some(object) = next_value.as_object_mut() {
+            // 中文注释：执行阶段晚于外部生成主表和摘要投影加入，旧迁移包按未知阶段兼容；
+            // BFF 会把 running + phase=null 视为 generating。
+            object
+                .entry("phase".to_string())
+                .or_insert(serde_json::Value::Null);
+        }
+    }
     if table_name == "big_fish_creation_session" {
         if let Some(object) = next_value.as_object_mut() {
             // 中文注释：旧迁移包没有公开游玩次数字段，导入时按新建作品默认 0 兼容。
diff --git a/server-rs/scripts/spacetime-dev.ps1 b/server-rs/scripts/spacetime-dev.ps1
index b6f6b8ab9..125c3293c 100644
--- a/server-rs/scripts/spacetime-dev.ps1
+++ b/server-rs/scripts/spacetime-dev.ps1
@@ -4,7 +4,7 @@ param(
     [switch]$Help,
     [string]$ListenHost = "127.0.0.1",
     [int]$Port = 3000,
-    [string]$RootDir = ""
+    [string]$DataDir = ""
 )
 
 $ErrorActionPreference = "Stop"
@@ -31,8 +31,8 @@ if ($Help) {
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 $serverRsDir = Split-Path -Parent $scriptDir
 
-if ([string]::IsNullOrWhiteSpace($RootDir)) {
-    $RootDir = Join-Path $serverRsDir ".spacetimedb\local"
+if ([string]::IsNullOrWhiteSpace($DataDir)) {
+    $DataDir = Join-Path $serverRsDir ".spacetimedb\local\data"
 }
 
 if (-not (Test-Path (Join-Path $serverRsDir "crates\spacetime-module\README.md"))) {
@@ -49,19 +49,19 @@ if ($null -eq $spacetimeCommand) {
     ) -join " "
 }
 
-New-Item -ItemType Directory -Force -Path $RootDir | Out-Null
+New-Item -ItemType Directory -Force -Path $DataDir | Out-Null
 
 $listenAddress = "$ListenHost`:$Port"
 
 Write-Host "[server-rs:spacetime-dev] working dir: $serverRsDir"
-Write-Host "[server-rs:spacetime-dev] root dir: $RootDir"
+Write-Host "[server-rs:spacetime-dev] data dir: $DataDir"
 Write-Host "[server-rs:spacetime-dev] listen addr: $listenAddress"
 Write-Host "[server-rs:spacetime-dev] mode: standalone"
 Write-Host "[server-rs:spacetime-dev] note: module scaffold already exists; publish remains manual in this stage"
 
 Push-Location $serverRsDir
 try {
-    & $spacetimeCommand.Source --root-dir $RootDir start --edition standalone --listen-addr $listenAddress
+    & $spacetimeCommand.Source start --data-dir $DataDir --listen-addr $listenAddress --non-interactive
 }
 finally {
     Pop-Location
diff --git a/server-rs/scripts/spacetime-dev.sh b/server-rs/scripts/spacetime-dev.sh
index 4dcd01d1c..c442f8e45 100644
--- a/server-rs/scripts/spacetime-dev.sh
+++ b/server-rs/scripts/spacetime-dev.sh
@@ -27,7 +27,7 @@ SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 SERVER_RS_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
 LISTEN_HOST="${GENARRATIVE_SPACETIME_HOST:-127.0.0.1}"
 PORT="${GENARRATIVE_SPACETIME_PORT:-3000}"
-ROOT_DIR="${GENARRATIVE_SPACETIME_ROOT_DIR:-${SERVER_RS_DIR}/.spacetimedb/local}"
+DATA_DIR="${GENARRATIVE_SPACETIME_DATA_DIR:-${SERVER_RS_DIR}/.spacetimedb/local/data}"
 
 if [[ ! -f "${SERVER_RS_DIR}/crates/spacetime-module/README.md" ]]; then
   echo "[server-rs:spacetime-dev] 未找到 crates/spacetime-module/README.md，无法启动本地 SpacetimeDB 脚本。" >&2
@@ -41,13 +41,13 @@ if ! command -v spacetime >/dev/null 2>&1; then
   exit 1
 fi
 
-mkdir -p "${ROOT_DIR}"
+mkdir -p "${DATA_DIR}"
 
 echo "[server-rs:spacetime-dev] 工作目录: ${SERVER_RS_DIR}"
-echo "[server-rs:spacetime-dev] 数据目录: ${ROOT_DIR}"
+echo "[server-rs:spacetime-dev] 数据目录: ${DATA_DIR}"
 echo "[server-rs:spacetime-dev] 监听地址: ${LISTEN_HOST}:${PORT}"
 echo "[server-rs:spacetime-dev] 模式: standalone"
 echo "[server-rs:spacetime-dev] 说明: 当前阶段已落 crate scaffold，但仍不自动 publish crates/spacetime-module"
 
 cd "${SERVER_RS_DIR}"
-spacetime --root-dir "${ROOT_DIR}" start --edition standalone --listen-addr "${LISTEN_HOST}:${PORT}"
+spacetime start --data-dir "${DATA_DIR}" --listen-addr "${LISTEN_HOST}:${PORT}" --non-interactive
diff --git a/src/App.tsx b/src/App.tsx
index 9a11611d8..571ca2ad3 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -21,8 +21,8 @@ import {
   isAppHistoryState,
   normalizeAppPath,
   pushAppHistoryPath,
-  replaceAppHistoryPath,
   readPublicWorkCodeFromLocationSearch,
+  replaceAppHistoryPath,
   resolveInitialSelectionStageFromPath,
   resolvePathForSelectionStage,
   shouldRedirectEditorCanvasWithoutProject,
diff --git a/src/PuzzlePlaygroundApp.tsx b/src/PuzzlePlaygroundApp.tsx
index 429b0761d..a50ae9d6d 100644
--- a/src/PuzzlePlaygroundApp.tsx
+++ b/src/PuzzlePlaygroundApp.tsx
@@ -7,8 +7,8 @@ import type {
 import type { PuzzleWorkSummary } from '../packages/shared/src/contracts/puzzleWorkSummary';
 import { PuzzleRuntimeShell } from './components/puzzle-runtime/PuzzleRuntimeShell';
 import {
-  applyLocalPuzzleFreezeTime,
   advanceLocalPuzzleLevel,
+  applyLocalPuzzleFreezeTime,
   dragLocalPuzzlePiece,
   setLocalPuzzlePaused,
   startLocalPuzzleRun,
diff --git a/src/components/AdventureEntityModal.tsx b/src/components/AdventureEntityModal.tsx
index 39dc79701..c56d6b77c 100644
--- a/src/components/AdventureEntityModal.tsx
+++ b/src/components/AdventureEntityModal.tsx
@@ -77,8 +77,8 @@ import {
   PlayerLevelProgress,
   StatusRow,
 } from './CharacterInfoShared';
-import { PlatformEmptyState } from './common/PlatformEmptyState';
 import { PlatformActionButton } from './common/PlatformActionButton';
+import { PlatformEmptyState } from './common/PlatformEmptyState';
 import { PlatformPillBadge } from './common/PlatformPillBadge';
 import { PlatformSubpanel } from './common/PlatformSubpanel';
 import { GENERIC_NPC_SCENE_SCALE } from './game-canvas/GameCanvasShared';
diff --git a/src/components/CustomWorldGenerationView.test.tsx b/src/components/CustomWorldGenerationView.test.tsx
index 54557e3a5..f8a2abfc5 100644
--- a/src/components/CustomWorldGenerationView.test.tsx
+++ b/src/components/CustomWorldGenerationView.test.tsx
@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
-import userEvent from '@testing-library/user-event';
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { describe, expect, test, vi } from 'vitest';
 
 import type { CustomWorldGenerationProgress } from '../../packages/shared/src/contracts/runtime';
diff --git a/src/components/InventoryPanel.tsx b/src/components/InventoryPanel.tsx
index 900a1a2b6..d2bdc8bc9 100644
--- a/src/components/InventoryPanel.tsx
+++ b/src/components/InventoryPanel.tsx
@@ -14,8 +14,8 @@ import {
   NarrativeQaReport,
   WorldType,
 } from '../types';
-import { PlatformPillBadge } from './common/PlatformPillBadge';
 import { PlatformActionButton } from './common/PlatformActionButton';
+import { PlatformPillBadge } from './common/PlatformPillBadge';
 import { PlatformStatusMessage } from './common/PlatformStatusMessage';
 import { PlatformSubpanel } from './common/PlatformSubpanel';
 import {
diff --git a/src/components/ResolvedAssetAudio.tsx b/src/components/ResolvedAssetAudio.tsx
new file mode 100644
index 000000000..1cac1c542
--- /dev/null
+++ b/src/components/ResolvedAssetAudio.tsx
@@ -0,0 +1,33 @@
+import type { AudioHTMLAttributes } from 'react';
+
+import { useResolvedAssetReadUrl } from '../hooks/useResolvedAssetReadUrl';
+
+type ResolvedAssetAudioProps = Omit<
+  AudioHTMLAttributes<HTMLAudioElement>,
+  'src'
+> & {
+  src?: string | null;
+  objectKey?: string | null;
+  fallbackSrc?: string | null;
+  refreshKey?: string | number | null;
+};
+
+export function ResolvedAssetAudio({
+  src,
+  objectKey,
+  fallbackSrc,
+  refreshKey,
+  ...rest
+}: ResolvedAssetAudioProps) {
+  const { resolvedUrl } = useResolvedAssetReadUrl(src, {
+    objectKey,
+    refreshKey,
+  });
+  const finalSrc = resolvedUrl || fallbackSrc?.trim() || '';
+
+  if (!finalSrc) {
+    return null;
+  }
+
+  return <audio {...rest} src={finalSrc} />;
+}
diff --git a/src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx b/src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx
index 56358b6a3..8d4eb4df0 100644
--- a/src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx
+++ b/src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx
@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
-import userEvent from '@testing-library/user-event';
 import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
 
 import {
diff --git a/src/components/big-fish-result/BigFishResultView.tsx b/src/components/big-fish-result/BigFishResultView.tsx
index 1bc3336e1..41024366f 100644
--- a/src/components/big-fish-result/BigFishResultView.tsx
+++ b/src/components/big-fish-result/BigFishResultView.tsx
@@ -20,7 +20,6 @@ import { PlatformAcknowledgeStatusDialog } from '../common/PlatformAcknowledgeSt
 import { PlatformActionButton } from '../common/PlatformActionButton';
 import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
-import { PlatformIconBadge } from '../common/PlatformIconBadge';
 import { PlatformIconButton } from '../common/PlatformIconButton';
 import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
 import { PlatformPillBadge } from '../common/PlatformPillBadge';
diff --git a/src/components/common/CopyFeedbackButton.tsx b/src/components/common/CopyFeedbackButton.tsx
index d88a57509..5e0b7c6a1 100644
--- a/src/components/common/CopyFeedbackButton.tsx
+++ b/src/components/common/CopyFeedbackButton.tsx
@@ -1,13 +1,13 @@
 import { Check, Copy } from 'lucide-react';
 import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
+import { PlatformActionButton } from './PlatformActionButton';
 import {
-  type PlatformActionButtonSize,
   type PlatformActionButtonShape,
+  type PlatformActionButtonSize,
   type PlatformActionButtonSurface,
   type PlatformActionButtonTone,
 } from './platformActionButtonModel';
-import { PlatformActionButton } from './PlatformActionButton';
 import {
   getPlatformPillBadgeClassName,
   type PlatformPillBadgeSize,
diff --git a/src/components/common/PlatformBackActionButton.tsx b/src/components/common/PlatformBackActionButton.tsx
index 649903f71..8ed182332 100644
--- a/src/components/common/PlatformBackActionButton.tsx
+++ b/src/components/common/PlatformBackActionButton.tsx
@@ -1,6 +1,5 @@
-import type { ButtonHTMLAttributes } from 'react';
-
 import { ArrowLeft } from 'lucide-react';
+import type { ButtonHTMLAttributes } from 'react';
 
 import { PlatformActionButton } from './PlatformActionButton';
 import type { PlatformActionButtonSurface } from './platformActionButtonModel';
diff --git a/src/components/common/PlatformIconButton.tsx b/src/components/common/PlatformIconButton.tsx
index 4cf90c7f9..106141262 100644
--- a/src/components/common/PlatformIconButton.tsx
+++ b/src/components/common/PlatformIconButton.tsx
@@ -1,4 +1,3 @@
-import { forwardRef } from 'react';
 import type {
   ButtonHTMLAttributes,
   HTMLAttributes,
@@ -7,6 +6,7 @@ import type {
   ReactNode,
   Ref,
 } from 'react';
+import { forwardRef } from 'react';
 
 type PlatformIconButtonBaseProps = {
   label: string;
diff --git a/src/components/common/PlatformInlineOptionButton.tsx b/src/components/common/PlatformInlineOptionButton.tsx
index bc349d4e2..06eee0af4 100644
--- a/src/components/common/PlatformInlineOptionButton.tsx
+++ b/src/components/common/PlatformInlineOptionButton.tsx
@@ -1,4 +1,4 @@
-import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import { type ButtonHTMLAttributes, forwardRef, type ReactNode } from 'react';
 
 type PlatformInlineOptionButtonProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
diff --git a/src/components/common/PlatformSegmentedTabPresets.tsx b/src/components/common/PlatformSegmentedTabPresets.tsx
index 5c26e5a25..6b7858bd6 100644
--- a/src/components/common/PlatformSegmentedTabPresets.tsx
+++ b/src/components/common/PlatformSegmentedTabPresets.tsx
@@ -1,6 +1,6 @@
 import {
-  PlatformSegmentedTabs,
   type PlatformSegmentedTabItem,
+  PlatformSegmentedTabs,
 } from './PlatformSegmentedTabs';
 
 type PlatformSegmentedTabPresetProps<TId extends string> = {
diff --git a/src/components/common/PlatformStatusDialog.test.tsx b/src/components/common/PlatformStatusDialog.test.tsx
index 7e9b37b9c..fffc8c1a1 100644
--- a/src/components/common/PlatformStatusDialog.test.tsx
+++ b/src/components/common/PlatformStatusDialog.test.tsx
@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
-import { Waves } from 'lucide-react';
 import { fireEvent, render, screen } from '@testing-library/react';
+import { Waves } from 'lucide-react';
 import { expect, test, vi } from 'vitest';
 
 import { PlatformStatusDialog } from './PlatformStatusDialog';
diff --git a/src/components/common/PlatformStatusDialog.tsx b/src/components/common/PlatformStatusDialog.tsx
index 7b95ef02e..bd3713052 100644
--- a/src/components/common/PlatformStatusDialog.tsx
+++ b/src/components/common/PlatformStatusDialog.tsx
@@ -1,20 +1,19 @@
-import type { ReactNode } from 'react';
-
 import {
   AlertCircle,
   CheckCircle2,
   Loader2,
   XCircle,
 } from 'lucide-react';
+import type { ReactNode } from 'react';
 
 import { PlatformActionButton } from './PlatformActionButton';
-import { PlatformIconBadge } from './PlatformIconBadge';
-import { UnifiedModal } from './UnifiedModal';
 import type {
   PlatformActionButtonSize,
   PlatformActionButtonSurface,
   PlatformActionButtonTone,
 } from './platformActionButtonModel';
+import { PlatformIconBadge } from './PlatformIconBadge';
+import { UnifiedModal } from './UnifiedModal';
 
 export type PlatformStatusDialogStatus =
   | 'success'
diff --git a/src/components/common/SquareImageCropModal.tsx b/src/components/common/SquareImageCropModal.tsx
index 1b7cc1d78..44a73b373 100644
--- a/src/components/common/SquareImageCropModal.tsx
+++ b/src/components/common/SquareImageCropModal.tsx
@@ -8,13 +8,13 @@ import {
 
 import { PlatformActionButton } from './PlatformActionButton';
 import { PlatformStatusMessage } from './PlatformStatusMessage';
-import { UnifiedModal } from './UnifiedModal';
 import {
   clampNumber,
   clampSquareImageCropRect,
   getSquareCropSizeBounds,
   type SquareImageCropRect,
 } from './squareImageCropModel';
+import { UnifiedModal } from './UnifiedModal';
 
 export type SquareImageCropModalLabels = {
   title: string;
diff --git a/src/components/creation-agent/CreationAgentWorkspace.tsx b/src/components/creation-agent/CreationAgentWorkspace.tsx
index f61513976..3b4fa356b 100644
--- a/src/components/creation-agent/CreationAgentWorkspace.tsx
+++ b/src/components/creation-agent/CreationAgentWorkspace.tsx
@@ -426,6 +426,7 @@ function normalizeCreationAgentExportFileNameSegment(rawValue: string) {
     .trim()
     .split('')
     .map((character) =>
+      // eslint-disable-next-line no-control-regex -- 文件名必须拒绝 C0 控制字符。
       /[\u0000-\u001f<>:"/\\|?*]/u.test(character) ? '-' : character,
     )
     .join('')
diff --git a/src/components/image-editor/EditorAgentConversation/AttachmentChip.tsx b/src/components/image-editor/EditorAgentConversation/AttachmentChip.tsx
new file mode 100644
index 000000000..81b327f57
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/AttachmentChip.tsx
@@ -0,0 +1,43 @@
+import { Image as ImageIcon, X } from 'lucide-react';
+
+import type { EditorAgentAttachmentRef } from '@/packages/shared/src/contracts';
+import { ResolvedAssetImage } from '@/src/components/ResolvedAssetImage.tsx';
+
+function AttachmentChip({
+  attachment,
+  onRemove,
+}: {
+  attachment: EditorAgentAttachmentRef;
+  onRemove?: () => void;
+}) {
+  const label = attachment.label?.trim() || attachment.referenceId;
+  return (
+    <span className="group relative inline-flex max-w-full items-center gap-1.5 rounded-full border border-slate-200 bg-white px-2.5 py-1 text-xs text-slate-600 shadow-sm">
+      <ImageIcon className="h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+      <span className="truncate">{label}</span>
+      {onRemove ? (
+        <button
+          type="button"
+          className="-mr-1 inline-flex h-5 w-5 items-center justify-center rounded-full text-slate-400 hover:bg-slate-100 hover:text-slate-700"
+          aria-label={`移除附件 ${label}`}
+          onClick={onRemove}
+        >
+          <X className="h-3 w-3" aria-hidden="true" />
+        </button>
+      ) : null}
+      {attachment.thumbnailSrc || attachment.imageSrc ? (
+        <span className="pointer-events-none absolute bottom-[calc(100%+0.4rem)] left-0 hidden rounded-2xl border border-white bg-white p-1 shadow-xl group-hover:block">
+          <ResolvedAssetImage
+            src={attachment.thumbnailSrc ?? attachment.imageSrc}
+            objectKey={attachment.objectKey}
+            refreshKey={attachment.referenceId}
+            alt=""
+            className="h-24 w-24 rounded-xl object-cover"
+          />
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+export default AttachmentChip;
diff --git a/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx b/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx
new file mode 100644
index 000000000..737068d1e
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx
@@ -0,0 +1,832 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  EditorAgentMessage,
+  EditorAgentMessageResponse,
+} from '@/packages/shared/src/contracts';
+import type { EditorAgentConversationClient } from '@/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts';
+import { useImageCanvasContextStore } from '@/src/components/image-editor/useImageCanvasContextStore.ts';
+
+import { EditorAgentConversationPanelView } from './EditorAgentConversationPanelView.tsx';
+
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const uploadEditorMediaAssetFileMock = vi.hoisted(() => vi.fn());
+const probeImageFileDimensionsMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@/src/services/image-editor/editorProjectClient.ts', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../../services/image-editor/editorProjectClient.ts')
+  >('@/src/services/image-editor/editorProjectClient.ts');
+  return {
+    ...actual,
+    createEditorProjectResource: createEditorProjectResourceMock,
+  };
+});
+
+vi.mock('@/src/services/image-editor/editorMediaAssetUploadClient.ts', () => ({
+  uploadEditorMediaAssetFile: uploadEditorMediaAssetFileMock,
+}));
+
+vi.mock('@/src/components/image-editor/ImageCanvasFileModel.ts', async () => {
+  const actual = await vi.importActual<
+    typeof import('../ImageCanvasFileModel.ts')
+  >('@/src/components/image-editor/ImageCanvasFileModel.ts');
+  return {
+    ...actual,
+    probeImageFileDimensions: probeImageFileDimensionsMock,
+  };
+});
+
+function createClient(): EditorAgentConversationClient {
+  return {
+    listConversations: vi.fn().mockResolvedValue([
+      {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      },
+    ]),
+    createConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-2',
+      projectId: 'project-1',
+      title: '新对话',
+      messages: [],
+      createdAt: '2026-07-03T00:01:00.000Z',
+      updatedAt: '2026-07-03T00:01:00.000Z',
+    }),
+    getConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [
+        {
+          id: 0,
+          role: 'assistant',
+          text: '已经看到画布内容',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-03T00:00:10.000Z',
+        },
+      ],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:10.000Z',
+    }),
+    deleteConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    }),
+    sendMessage: vi.fn().mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      },
+      deltaMessages: [
+        {
+          id: 1,
+          role: 'assistant',
+          text: '收到，我会参考这张图。',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-03T00:00:00.000Z',
+        },
+      ],
+      errorMessage: null,
+    } as EditorAgentMessageResponse),
+    confirmToolCall: vi.fn(),
+    cancelToolCall: vi.fn(),
+  };
+}
+
+function createPendingToolCallMessage(): EditorAgentMessage {
+  return {
+    id: 2,
+    role: 'system',
+    text: 'internal system prompt that must stay hidden',
+    attachments: [],
+    toolCall: {
+      toolName: 'edit-image',
+      status: 'not_completed',
+      args: {
+        object_image_id: 'source-image-1',
+        reference_image_ids: ['reference-image-1', 'reference-image-2'],
+        prompt: '把角色换成像素风',
+      },
+      displayArgs: {
+        stringArgs: [
+          {
+            name: 'prompt',
+            label: '提示词',
+            value: '把角色换成像素风',
+          },
+        ],
+        imageArgs: [
+          {
+            name: 'object_image_id',
+            label: '目标图片',
+            refs: [
+              {
+                imageId: 'source-image-1',
+                imageSrc: 'data:image/png;base64,c291cmNl',
+                label: '原角色',
+                width: 512,
+                height: 512,
+              },
+            ],
+          },
+          {
+            name: 'reference_image_ids',
+            label: '参考图片',
+            refs: [
+              {
+                imageId: 'reference-image-1',
+                imageSrc: 'data:image/png;base64,cmVmZXJlbmNlLTE=',
+                label: '像素风参考',
+              },
+              {
+                imageId: 'reference-image-2',
+                imageSrc: 'data:image/png;base64,cmVmZXJlbmNlLTI=',
+                label: '配色参考',
+              },
+            ],
+          },
+        ],
+        extras: { priceMudPoints: 3 },
+      },
+      images: [],
+      error: null,
+    },
+    createdAt: '2026-07-10T00:00:00.000Z',
+  };
+}
+
+describe('EditorAgentConversationPanelView', () => {
+  beforeEach(() => {
+    useImageCanvasContextStore.getState().setProjectId('project-1');
+    uploadEditorMediaAssetFileMock.mockReset();
+    uploadEditorMediaAssetFileMock.mockResolvedValue({
+      src: '/generated/pasted.png',
+      objectKey:
+        'generated-character-drafts/editor/agent-paste/image/pasted.png',
+      assetObjectId: 'asset-object-pasted',
+      legacyPublicPath: '/generated/pasted.png',
+    });
+    probeImageFileDimensionsMock.mockReset();
+    probeImageFileDimensionsMock.mockResolvedValue({ width: 320, height: 240 });
+    createEditorProjectResourceMock.mockReset();
+    createEditorProjectResourceMock.mockResolvedValue({
+      resourceId: 'resource-pasted',
+      imageSrc: '/generated/pasted.png',
+      objectKey:
+        'generated-character-drafts/editor/agent-paste/image/pasted.png',
+      label: '粘贴图片',
+      width: 320,
+      height: 240,
+    });
+  });
+
+  it('manages conversations, attachments and message sending inside the panel', async () => {
+    const client = createClient();
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+        layers={[
+          {
+            id: 'layer-1',
+            resourceId: 'resource-1',
+            title: '角色图层',
+            src: '/generated/role.png',
+            x: 0,
+            y: 0,
+            width: 512,
+            height: 512,
+            originalWidth: 512,
+            originalHeight: 512,
+            zIndex: 1,
+            sourceType: 'generated',
+          },
+          {
+            id: 'layer-local-only',
+            resourceId: '',
+            title: '未入库图层',
+            src: '/local-only.png',
+            x: 0,
+            y: 0,
+            width: 256,
+            height: 256,
+            originalWidth: 256,
+            originalHeight: 256,
+            zIndex: 2,
+            sourceType: 'uploaded',
+          },
+        ]}
+        assets={[
+          {
+            id: 'asset-1',
+            label: '素材库角色',
+            src: '/assets/role.png',
+            width: 512,
+            height: 512,
+            folderId: 'project',
+            sourceKind: 'uploaded',
+            sourceType: 'uploaded',
+            persisted: true,
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '新建对话' }));
+    await waitFor(() => {
+      expect(client.createConversation).toHaveBeenCalledWith('project-1', {});
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '添加附件' }));
+    const attachmentDialog = screen.getByRole('dialog', {
+      name: '选择图片附件',
+    });
+    expect(
+      within(attachmentDialog).queryByRole('checkbox', {
+        name: '选择画布图片 未入库图层',
+      }),
+    ).toBeNull();
+    fireEvent.click(
+      within(attachmentDialog).getByRole('checkbox', {
+        name: '选择画布图片 角色图层',
+      }),
+    );
+    fireEvent.click(
+      within(attachmentDialog).getByRole('button', { name: '应用' }),
+    );
+    expect(screen.getByText('角色图层')).toBeTruthy();
+
+    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
+      target: { value: '参考附件做像素风' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    await waitFor(() => {
+      expect(screen.getByText('收到，我会参考这张图。')).toBeTruthy();
+    });
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      'conversation-2',
+      expect.objectContaining({
+        text: '参考附件做像素风',
+        attachments: [
+          expect.objectContaining({
+            source: 'canvas_resource',
+            referenceId: 'resource-1',
+          }),
+        ],
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it('disables sending while a message request is pending without showing stop', async () => {
+    const client = createClient();
+    let resolveSend!: (response: EditorAgentMessageResponse) => void;
+    vi.mocked(client.sendMessage).mockImplementation(
+      () =>
+        new Promise<EditorAgentMessageResponse>((resolve) => {
+          resolveSend = resolve;
+        }),
+    );
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
+      target: { value: '继续规划' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: '发送' }).hasAttribute('disabled'),
+      ).toBe(true);
+    });
+    expect(screen.queryByRole('button', { name: '停止' })).toBeNull();
+
+    await act(async () => {
+      resolveSend({
+        conversation: {
+          conversationId: 'conversation-1',
+          projectId: 'project-1',
+          title: '角色参考',
+          updatedAt: '2026-07-03T00:00:20.000Z',
+        },
+        deltaMessages: [],
+        errorMessage: null,
+      });
+    });
+  });
+
+  it('uploads pasted images as canvas attachments before sending', async () => {
+    const client = createClient();
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    const pastedImage = new File(['pasted-image'], 'pasted.png', {
+      type: 'image/png',
+    });
+    const input = screen.getByLabelText('发送给画布 Agent');
+    fireEvent.paste(input, {
+      clipboardData: {
+        files: [pastedImage],
+      },
+    });
+
+    await waitFor(() => {
+      expect(uploadEditorMediaAssetFileMock).toHaveBeenCalledWith(
+        pastedImage,
+        'image',
+        expect.objectContaining({
+          entityId: 'project-1',
+          metadata: { source: 'agent-input-paste' },
+        }),
+      );
+    });
+    expect(probeImageFileDimensionsMock).toHaveBeenCalledWith(pastedImage);
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: '/generated/pasted.png',
+        objectKey:
+          'generated-character-drafts/editor/agent-paste/image/pasted.png',
+        assetObjectId: 'asset-object-pasted',
+        width: 320,
+        height: 240,
+        sourceType: 'uploaded',
+      }),
+    );
+    await waitFor(() => {
+      expect(screen.getByText('粘贴图片')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    await waitFor(() => {
+      expect(client.sendMessage).toHaveBeenCalledWith(
+        'conversation-1',
+        expect.objectContaining({
+          text: '',
+          attachments: [
+            expect.objectContaining({
+              source: 'canvas_resource',
+              referenceId: 'resource-pasted',
+              imageSrc: '/generated/pasted.png',
+              width: 320,
+              height: 240,
+            }),
+          ],
+        }),
+        expect.any(Object),
+      );
+    });
+    expect(screen.getByRole('option', { name: '角色参考' })).toBeTruthy();
+    expect(
+      screen.queryByRole('option', { name: 'conversation-1' }),
+    ).toBeNull();
+  });
+
+  it('sends selected attachments even when the text input is empty', async () => {
+    const client = createClient();
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+        layers={[
+          {
+            id: 'layer-1',
+            resourceId: 'resource-1',
+            title: '角色图层',
+            src: '/generated/role.png',
+            x: 0,
+            y: 0,
+            width: 512,
+            height: 512,
+            originalWidth: 512,
+            originalHeight: 512,
+            zIndex: 1,
+            sourceType: 'generated',
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '添加附件' }));
+    const attachmentDialog = screen.getByRole('dialog', {
+      name: '选择图片附件',
+    });
+    fireEvent.click(
+      within(attachmentDialog).getByRole('checkbox', {
+        name: '选择画布图片 角色图层',
+      }),
+    );
+    fireEvent.click(
+      within(attachmentDialog).getByRole('button', { name: '应用' }),
+    );
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    await waitFor(() => {
+      expect(client.sendMessage).toHaveBeenCalledWith(
+        'conversation-1',
+        expect.objectContaining({
+          text: '',
+          attachments: [
+            expect.objectContaining({
+              source: 'canvas_resource',
+              referenceId: 'resource-1',
+            }),
+          ],
+        }),
+        expect.any(Object),
+      );
+    });
+  });
+
+  it('restores the draft and selected attachments when sending fails', async () => {
+    const client = createClient();
+    vi.mocked(client.sendMessage).mockRejectedValueOnce(
+      new Error('Network error'),
+    );
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+        layers={[
+          {
+            id: 'layer-1',
+            resourceId: 'resource-1',
+            title: '角色图层',
+            src: '/generated/role.png',
+            x: 0,
+            y: 0,
+            width: 512,
+            height: 512,
+            originalWidth: 512,
+            originalHeight: 512,
+            zIndex: 1,
+            sourceType: 'generated',
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '添加附件' }));
+    const attachmentDialog = screen.getByRole('dialog', {
+      name: '选择图片附件',
+    });
+    fireEvent.click(
+      within(attachmentDialog).getByRole('checkbox', {
+        name: '选择画布图片 角色图层',
+      }),
+    );
+    fireEvent.click(
+      within(attachmentDialog).getByRole('button', { name: '应用' }),
+    );
+    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
+      target: { value: '失败后恢复这条草稿' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    expect(await screen.findByText('Network error')).toBeTruthy();
+    expect(
+      (screen.getByLabelText('发送给画布 Agent') as HTMLTextAreaElement).value,
+    ).toBe('失败后恢复这条草稿');
+    expect(screen.getByText('角色图层')).toBeTruthy();
+    expect(
+      within(screen.getByRole('log', { name: '画布 Agent 消息流' })).queryByText(
+        '失败后恢复这条草稿',
+      ),
+    ).toBeNull();
+  });
+
+  it('preserves messages when the panel is collapsed and reopened', async () => {
+    const client = createClient();
+    vi.mocked(client.sendMessage).mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      },
+      deltaMessages: [
+        {
+          id: 1,
+          role: 'assistant',
+          text: '我来生成图片。',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-03T00:00:00.000Z',
+        },
+      ],
+      errorMessage: null,
+    } as EditorAgentMessageResponse);
+
+    const { rerender } = render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
+      target: { value: '生成一张图片' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+
+    await waitFor(() => {
+      expect(screen.getByText('我来生成图片。')).toBeTruthy();
+    });
+
+    rerender(
+      <EditorAgentConversationPanelView
+        open={false}
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+    expect(screen.getByRole('button', { name: '打开画布 Agent' })).toBeTruthy();
+
+    rerender(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    expect(screen.getByText('我来生成图片。')).toBeTruthy();
+  });
+
+  it('shows structured pending details, hides system text and confirms once', async () => {
+    const client = createClient();
+    const pendingMessage = createPendingToolCallMessage();
+    const confirmedMessage: EditorAgentMessage = {
+      ...pendingMessage,
+      text: 'internal completed tool output that must stay hidden',
+      toolCall: {
+        ...pendingMessage.toolCall!,
+        externalJobId: 'task-edit-panel-1',
+      },
+    };
+    vi.mocked(client.getConversation)
+      .mockResolvedValueOnce({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [pendingMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      })
+      .mockResolvedValue({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [confirmedMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      });
+    let resolveConfirmation: () => void = () => {};
+    vi.mocked(client.confirmToolCall).mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveConfirmation = resolve;
+        }),
+    );
+    const onCanvasRefreshRequested = vi.fn();
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+        onCanvasRefreshRequested={onCanvasRefreshRequested}
+      />,
+    );
+
+    expect(await screen.findByText('把角色换成像素风')).toBeTruthy();
+    expect(screen.getByText('提示词')).toBeTruthy();
+    expect(screen.getByText('2 张')).toBeTruthy();
+    expect(screen.getByAltText('目标图片：原角色')).toBeTruthy();
+    expect(screen.getByAltText('参考图片：像素风参考')).toBeTruthy();
+    expect(screen.getByAltText('参考图片：配色参考')).toBeTruthy();
+    expect(screen.getByText('预计消耗 3泥点')).toBeTruthy();
+    expect(screen.queryByText('source-image-1')).toBeNull();
+    expect(screen.queryByText('reference-image-1')).toBeNull();
+    expect(
+      screen.queryByText('internal system prompt that must stay hidden'),
+    ).toBeNull();
+    const getConversationCallsBeforeConfirm = vi.mocked(client.getConversation)
+      .mock.calls.length;
+
+    fireEvent.click(screen.getByRole('button', { name: '确认' }));
+    await waitFor(() => {
+      expect(client.confirmToolCall).toHaveBeenCalledWith('conversation-1', 2);
+    });
+    expect(screen.getByRole('button', { name: '执行中' })).toBeTruthy();
+    expect(screen.queryByRole('button', { name: '确认' })).toBeNull();
+    expect(screen.getByRole('button', { name: '取消' }).hasAttribute('disabled')).toBe(
+      true,
+    );
+
+    await act(async () => {
+      resolveConfirmation();
+    });
+
+    expect(await screen.findByText('执行中')).toBeTruthy();
+    expect(client.getConversation).toHaveBeenCalledTimes(
+      getConversationCallsBeforeConfirm + 1,
+    );
+    expect(
+      screen.queryByText(
+        'internal completed tool output that must stay hidden',
+      ),
+    ).toBeNull();
+    expect(onCanvasRefreshRequested).not.toHaveBeenCalled();
+    expect(screen.queryByRole('button', { name: '确认' })).toBeNull();
+  });
+
+  it('cancels a pending tool call without exposing its system text', async () => {
+    const client = createClient();
+    const pendingMessage = createPendingToolCallMessage();
+    const cancelledMessage: EditorAgentMessage = {
+      ...pendingMessage,
+      text: 'internal cancelled tool output that must stay hidden',
+      toolCall: {
+        ...pendingMessage.toolCall!,
+        status: 'cancelled',
+      },
+    };
+    vi.mocked(client.getConversation)
+      .mockResolvedValueOnce({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [pendingMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      })
+      .mockResolvedValue({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [cancelledMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:10.000Z',
+      });
+    vi.mocked(client.cancelToolCall).mockResolvedValue(undefined);
+
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    const cancelButton = await screen.findByRole('button', { name: '取消' });
+    const getConversationCallsBeforeCancel = vi.mocked(client.getConversation)
+      .mock.calls.length;
+    fireEvent.click(cancelButton);
+
+    expect(await screen.findByText('已取消')).toBeTruthy();
+    expect(client.cancelToolCall).toHaveBeenCalledWith('conversation-1', 2);
+    expect(client.getConversation).toHaveBeenCalledTimes(
+      getConversationCallsBeforeCancel + 1,
+    );
+    expect(
+      screen.queryByText(
+        'internal cancelled tool output that must stay hidden',
+      ),
+    ).toBeNull();
+    expect(screen.queryByRole('button', { name: '确认' })).toBeNull();
+  });
+
+  it('keeps wheel scrolling inside the message history and input', async () => {
+    const client = createClient();
+    const parentWheel = vi.fn();
+
+    render(
+      <div onWheel={parentWheel}>
+        <EditorAgentConversationPanelView
+          open
+          onToggleOpen={vi.fn()}
+          client={client}
+        />
+      </div>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    const messageWheel = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      deltaY: 120,
+    });
+    fireEvent(
+      screen.getByRole('log', { name: '画布 Agent 消息流' }),
+      messageWheel,
+    );
+    expect(parentWheel).not.toHaveBeenCalled();
+    expect(messageWheel.defaultPrevented).toBe(false);
+
+    const inputWheel = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      deltaY: 120,
+    });
+    fireEvent(screen.getByLabelText('发送给画布 Agent'), inputWheel);
+    expect(parentWheel).not.toHaveBeenCalled();
+    expect(inputWheel.defaultPrevented).toBe(false);
+  });
+
+  it('confirms conversation deletion from an independent dialog', async () => {
+    const client = createClient();
+    render(
+      <EditorAgentConversationPanelView
+        open
+        onToggleOpen={vi.fn()}
+        client={client}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '删除当前对话' }));
+    const confirmDialog = screen.getByRole('dialog', { name: '删除对话' });
+    fireEvent.click(
+      within(confirmDialog).getByRole('button', { name: '确认删除' }),
+    );
+
+    await waitFor(() => {
+      expect(client.deleteConversation).toHaveBeenCalledWith('conversation-1');
+    });
+  });
+});
diff --git a/src/components/image-editor/EditorAgentConversationPanelView.tsx b/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.tsx
similarity index 71%
rename from src/components/image-editor/EditorAgentConversationPanelView.tsx
rename to src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.tsx
index 665162fc8..7846c3b3c 100644
--- a/src/components/image-editor/EditorAgentConversationPanelView.tsx
+++ b/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.tsx
@@ -1,41 +1,45 @@
 import {
   Bot,
-  Image as ImageIcon,
   Loader2,
   MessageCircle,
   Paperclip,
   Plus,
   Send,
-  Square,
   Trash2,
   X,
 } from 'lucide-react';
 import {
   type ClipboardEvent as ReactClipboardEvent,
   type FormEvent,
-  type WheelEvent as ReactWheelEvent,
   useEffect,
   useMemo,
   useState,
+  type WheelEvent as ReactWheelEvent,
 } from 'react';
 
 import {
   EDITOR_AGENT_MAX_ATTACHMENTS,
   type EditorAgentAttachmentRef,
-  type EditorAgentGenerationResultEvent,
-  type EditorAgentGenerationRecord,
-  type EditorAgentMessage,
-  type EditorAgentStage,
-} from '../../../packages/shared/src/contracts/editorAgent';
-import { PlatformActionButton } from '../common/PlatformActionButton';
-import { PlatformDangerConfirmDialog } from '../common/PlatformDangerConfirmDialog';
-import { UnifiedModal } from '../common/UnifiedModal';
-import { ResolvedAssetImage } from '../ResolvedAssetImage';
-import { uploadEditorMediaAssetFile } from '../../services/image-editor/editorMediaAssetUploadClient';
-import { createEditorProjectResource } from '../../services/image-editor/editorProjectClient';
-import type { CanvasLayer, EditorAsset } from './ImageCanvasEditorTypes';
-import { probeImageFileDimensions } from './ImageCanvasFileModel';
-import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
+} from '@/packages/shared/src/contracts';
+import { PlatformActionButton } from '@/src/components/common/PlatformActionButton.tsx';
+import { PlatformDangerConfirmDialog } from '@/src/components/common/PlatformDangerConfirmDialog.tsx';
+import { UnifiedModal } from '@/src/components/common/UnifiedModal.tsx';
+import AttachmentChip from '@/src/components/image-editor/EditorAgentConversation/AttachmentChip.tsx';
+import { attachmentKey } from '@/src/components/image-editor/EditorAgentConversation/common.ts';
+import {
+  MessageBubble,
+  ThinkingBubble,
+} from '@/src/components/image-editor/EditorAgentConversation/MessageBubble.tsx';
+import type {
+  CanvasLayer,
+  EditorAsset,
+} from '@/src/components/image-editor/ImageCanvasEditorTypes.ts';
+import { probeImageFileDimensions } from '@/src/components/image-editor/ImageCanvasFileModel.ts';
+import { ResolvedAssetImage } from '@/src/components/ResolvedAssetImage.tsx';
+import { uploadEditorMediaAssetFile } from '@/src/services/image-editor/editorMediaAssetUploadClient.ts';
+import { createEditorProjectResource } from '@/src/services/image-editor/editorProjectClient.ts';
+
+import { useImageCanvasContextStore } from '../useImageCanvasContextStore.ts';
 import {
   type EditorAgentConversationClient,
   useEditorAgentConversation,
@@ -54,7 +58,9 @@ type EditorAgentConversationPanelViewProps = {
   onToggleOpen: () => void;
   layers?: CanvasLayer[];
   assets?: EditorAsset[];
-  onGenerationResult?: (event: EditorAgentGenerationResultEvent) => void;
+  onCanvasRefreshRequested?: () => void;
+  // TODO refactor: move the task list update seperate
+  onConfirmSent?: () => void;
   client?: EditorAgentConversationClient;
 };
 
@@ -62,10 +68,6 @@ function stopAgentPanelWheel(event: ReactWheelEvent<HTMLElement>) {
   event.stopPropagation();
 }
 
-function attachmentKey(attachment: EditorAgentAttachmentRef) {
-  return `${attachment.source}:${attachment.referenceId}`;
-}
-
 function isImageLayer(layer: CanvasLayer) {
   return (
     (layer.mediaType ?? 'image') === 'image' &&
@@ -122,183 +124,6 @@ function createLibraryAttachmentOptions(
   });
 }
 
-function stageLabel(stage: EditorAgentStage) {
-  if (stage === 'thinking') {
-    return '思考中';
-  }
-  if (stage === 'responding') {
-    return '回复中';
-  }
-  if (stage === 'generating') {
-    return '生成中';
-  }
-  if (stage === 'completed') {
-    return '完成';
-  }
-  if (stage === 'failed') {
-    return '失败';
-  }
-  return '';
-}
-
-function toolLabel(toolName: EditorAgentGenerationRecord['toolName']) {
-  if (toolName === 'edit_image') {
-    return '修改图片';
-  }
-  if (toolName === 'generate_character') {
-    return '生成角色';
-  }
-  if (toolName === 'generate_icon_spritesheet') {
-    return '生成图标';
-  }
-  if (toolName === 'generate_ui_design') {
-    return '生成 UI';
-  }
-  return '生成图片';
-}
-
-function messageRoleLabel(role: EditorAgentMessage['role']) {
-  return role === 'user' ? '你' : 'Agent';
-}
-
-function AttachmentChip({
-  attachment,
-  onRemove,
-}: {
-  attachment: EditorAgentAttachmentRef;
-  onRemove?: () => void;
-}) {
-  const label = attachment.label?.trim() || attachment.referenceId;
-  return (
-    <span className="group relative inline-flex max-w-full items-center gap-1.5 rounded-full border border-slate-200 bg-white px-2.5 py-1 text-xs text-slate-600 shadow-sm">
-      <ImageIcon className="h-3.5 w-3.5 shrink-0" aria-hidden="true" />
-      <span className="truncate">{label}</span>
-      {onRemove ? (
-        <button
-          type="button"
-          className="-mr-1 inline-flex h-5 w-5 items-center justify-center rounded-full text-slate-400 hover:bg-slate-100 hover:text-slate-700"
-          aria-label={`移除附件 ${label}`}
-          onClick={onRemove}
-        >
-          <X className="h-3 w-3" aria-hidden="true" />
-        </button>
-      ) : null}
-      {attachment.thumbnailSrc || attachment.imageSrc ? (
-        <span className="pointer-events-none absolute bottom-[calc(100%+0.4rem)] left-0 hidden rounded-2xl border border-white bg-white p-1 shadow-xl group-hover:block">
-          <ResolvedAssetImage
-            src={attachment.thumbnailSrc ?? attachment.imageSrc}
-            objectKey={attachment.objectKey}
-            refreshKey={attachment.referenceId}
-            alt=""
-            className="h-24 w-24 rounded-xl object-cover"
-          />
-        </span>
-      ) : null}
-    </span>
-  );
-}
-
-function GenerationRecordsView({
-  generations,
-}: {
-  generations: EditorAgentGenerationRecord[];
-}) {
-  if (!generations.length) {
-    return null;
-  }
-  return (
-    <div className="mt-2 space-y-2">
-      {generations.map((generation) => (
-        <div
-          key={generation.toolCallId}
-          className="rounded-2xl border border-slate-200 bg-white/80 p-2 text-xs text-slate-600"
-        >
-          {generation.status === 'generating' || generation.error ? (
-            <div className="flex items-center gap-2">
-              {generation.status === 'generating' ? (
-                <Loader2
-                  className="h-3.5 w-3.5 animate-spin"
-                  aria-hidden="true"
-                />
-              ) : (
-                <ImageIcon className="h-3.5 w-3.5" aria-hidden="true" />
-              )}
-              <span>{toolLabel(generation.toolName)}</span>
-              {generation.model ? <span>{generation.model}</span> : null}
-            </div>
-          ) : null}
-          {generation.error ? (
-            <div className="mt-1 text-red-600">{generation.error}</div>
-          ) : null}
-          {generation.images.length ? (
-            <div className="mt-2 grid grid-cols-3 gap-2">
-              {generation.images.map((image, index) => (
-                <div
-                  key={`${generation.toolCallId}-${image.resourceId ?? index}`}
-                  className="overflow-hidden rounded-xl border border-slate-200 bg-slate-100"
-                >
-                  <ResolvedAssetImage
-                    src={image.thumbnailSrc ?? image.imageSrc}
-                    objectKey={image.objectKey}
-                    refreshKey={
-                      image.resourceId ??
-                      generation.taskId ??
-                      generation.toolCallId
-                    }
-                    alt=""
-                    className="h-20 w-full object-cover"
-                  />
-                </div>
-              ))}
-            </div>
-          ) : null}
-        </div>
-      ))}
-    </div>
-  );
-}
-
-function MessageBubble({
-  message,
-}: {
-  message: EditorAgentMessage;
-}) {
-  const isUser = message.role === 'user';
-  return (
-    <article
-      className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}
-      aria-label={`${messageRoleLabel(message.role)}消息`}
-    >
-      <div
-        className={`max-w-[86%] rounded-3xl px-3.5 py-3 text-sm leading-6 shadow-sm ${
-          isUser
-            ? 'bg-slate-900 text-white'
-            : message.kind === 'error'
-              ? 'border border-red-200 bg-red-50 text-red-700'
-              : 'border border-slate-200 bg-white text-slate-700'
-        }`}
-      >
-        <div className="whitespace-pre-wrap break-words">
-          {message.text || (message.status === 'streaming' ? '...' : '')}
-        </div>
-        {message.attachments.length ? (
-          <div className="mt-2 flex flex-wrap gap-1.5">
-            {message.attachments.map((attachment) => (
-              <AttachmentChip
-                key={attachmentKey(attachment)}
-                attachment={attachment}
-              />
-            ))}
-          </div>
-        ) : null}
-        <GenerationRecordsView
-          generations={message.generations}
-        />
-      </div>
-    </article>
-  );
-}
-
 function AttachmentPickerModal({
   open,
   tab,
@@ -412,7 +237,8 @@ export function EditorAgentConversationPanelView({
   onToggleOpen,
   layers = [],
   assets = [],
-  onGenerationResult,
+  onCanvasRefreshRequested,
+  onConfirmSent,
   client,
 }: EditorAgentConversationPanelViewProps) {
   const [hasConversationMounted, setHasConversationMounted] = useState(open);
@@ -421,30 +247,32 @@ export function EditorAgentConversationPanelView({
       setHasConversationMounted(true);
     }
   }, [open]);
-  const projectId = useImageCanvasContextStore(
-    (state) => state.projectId,
-  );
+  const projectId = useImageCanvasContextStore((state) => state.projectId);
   const effectiveProjectId = hasConversationMounted ? projectId : null;
   const {
     conversations,
     activeConversationId,
     messages,
-    stage,
     isLoadingConversations,
     isLoadingMessages,
     isCreatingConversation,
     isDeletingConversation,
-    isStreaming,
+    isWaiting,
+    toolCallAction,
+    isToolCallActionPending,
     errorMessage,
     createConversation,
     selectConversation,
+    refreshActiveConversation,
     sendMessage,
-    stopCurrentTurn,
+    confirmToolCall,
+    cancelToolCall,
     deleteActiveConversation,
   } = useEditorAgentConversation({
     projectId: effectiveProjectId,
     client,
-    onGenerationResult,
+    onCanvasRefreshRequested,
+    onConfirmSent,
   });
   const [draftText, setDraftText] = useState('');
   const [attachments, setAttachments] = useState<EditorAgentAttachmentRef[]>(
@@ -476,8 +304,8 @@ export function EditorAgentConversationPanelView({
     return optionMap;
   }, [canvasAttachmentOptions, libraryAttachmentOptions]);
 
-  const currentStageLabel = stageLabel(stage);
   const hasProject = Boolean(projectId?.trim());
+  const isConversationBusy = isWaiting || isToolCallActionPending;
 
   const openAttachmentPicker = () => {
     setAttachmentError(null);
@@ -513,8 +341,7 @@ export function EditorAgentConversationPanelView({
 
   const submitMessage = (event: FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    if (isStreaming) {
-      stopCurrentTurn();
+    if (isWaiting) {
       return;
     }
     if (isPastingAttachment) {
@@ -609,7 +436,9 @@ export function EditorAgentConversationPanelView({
     return [...fileItems];
   }
 
-  const handleInputPaste = (event: ReactClipboardEvent<HTMLTextAreaElement>) => {
+  const handleInputPaste = (
+    event: ReactClipboardEvent<HTMLTextAreaElement>,
+  ) => {
     const imageFiles = extractClipboardImageFiles(event.clipboardData);
     if (!imageFiles.length) {
       return;
@@ -625,14 +454,20 @@ export function EditorAgentConversationPanelView({
       return;
     }
 
+    const remainingAttachmentSlots =
+      EDITOR_AGENT_MAX_ATTACHMENTS - attachments.length;
+    const uploadFiles = imageFiles.slice(0, remainingAttachmentSlots);
+    const hasOverflow = uploadFiles.length < imageFiles.length;
     // TODO: deduplicate those existing assets
     setIsPastingAttachment(true);
     setAttachmentError('图片上传中');
     void Promise.all(
-      imageFiles.map((file) => createPastedAgentImageAttachment(file)),
+      uploadFiles.map((file) => createPastedAgentImageAttachment(file)),
     )
       .then((pastedAttachments) => {
-        appendAttachments(pastedAttachments);
+        if (appendAttachments(pastedAttachments) && hasOverflow) {
+          setAttachmentError(`最多 ${EDITOR_AGENT_MAX_ATTACHMENTS} 张`);
+        }
       })
       .catch(() => {
         setAttachmentError('图片粘贴失败，请重试');
@@ -681,7 +516,9 @@ export function EditorAgentConversationPanelView({
             aria-label="当前对话"
             value={activeConversationId ?? ''}
             disabled={
-              !conversations.length || isLoadingConversations || isStreaming
+              !conversations.length ||
+              isLoadingConversations ||
+              isConversationBusy
             }
             onChange={(event) => {
               const nextConversationId = event.currentTarget.value;
@@ -707,7 +544,9 @@ export function EditorAgentConversationPanelView({
             type="button"
             className="inline-flex h-9 w-9 items-center justify-center rounded-full bg-slate-900 text-white disabled:opacity-45"
             aria-label="新建对话"
-            disabled={!hasProject || isCreatingConversation || isStreaming}
+            disabled={
+              !hasProject || isCreatingConversation || isConversationBusy
+            }
             onClick={() => void createConversation()}
           >
             <Plus className="h-4 w-4" aria-hidden="true" />
@@ -717,7 +556,9 @@ export function EditorAgentConversationPanelView({
             className="inline-flex h-9 w-9 items-center justify-center rounded-full bg-white text-slate-500 hover:bg-red-50 hover:text-red-600 disabled:opacity-45"
             aria-label="删除当前对话"
             disabled={
-              !activeConversationId || isDeletingConversation || isStreaming
+              !activeConversationId ||
+              isDeletingConversation ||
+              isConversationBusy
             }
             onClick={() => setDeleteConfirmOpen(true)}
           >
@@ -732,15 +573,16 @@ export function EditorAgentConversationPanelView({
             <X className="h-4 w-4" aria-hidden="true" />
           </button>
         </header>
-        {currentStageLabel ? (
+        {isConversationBusy ? (
           <div className="flex items-center gap-2 border-b border-slate-200 bg-white/60 px-4 py-2 text-xs text-slate-500">
-            {isStreaming ? (
-              <Loader2
-                className="h-3.5 w-3.5 animate-spin"
-                aria-hidden="true"
-              />
-            ) : null}
-            <span>{currentStageLabel}</span>
+            <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+            <span>
+              {toolCallAction?.action === 'confirm'
+                ? '执行中'
+                : toolCallAction?.action === 'cancel'
+                  ? '取消中'
+                  : '思考中'}
+            </span>
           </div>
         ) : null}
         <div
@@ -754,12 +596,26 @@ export function EditorAgentConversationPanelView({
               加载中
             </div>
           ) : messages.length ? (
-            messages.map((message) => (
-              <MessageBubble
-                key={message.id}
-                message={message}
-              />
-            ))
+            <>
+              {messages.map((message, messageIndex) => (
+                <MessageBubble
+                  key={`${message.createdAt}-${messageIndex}`}
+                  message={message}
+                  busyAction={
+                    toolCallAction?.messageId === message.id
+                      ? toolCallAction.action
+                      : null
+                  }
+                  onConfirmToolCall={confirmToolCall}
+                  onCancelToolCall={cancelToolCall}
+                  onJobCompleted={() => {
+                    void refreshActiveConversation();
+                    onCanvasRefreshRequested?.();
+                  }}
+                />
+              ))}
+              {isWaiting ? <ThinkingBubble /> : null}
+            </>
           ) : (
             <div className="rounded-3xl border border-dashed border-slate-200 bg-white/70 px-4 py-8 text-center text-sm text-slate-400">
               暂无消息
@@ -818,21 +674,14 @@ export function EditorAgentConversationPanelView({
               type="submit"
               className="inline-flex h-10 min-w-16 shrink-0 items-center justify-center gap-1.5 rounded-full bg-slate-900 px-3 text-sm font-semibold text-white disabled:opacity-45"
               disabled={
-                !isStreaming &&
-                ((!draftText.trim() && !attachments.length) || !hasProject)
+                isWaiting ||
+                isToolCallActionPending ||
+                (!draftText.trim() && !attachments.length) ||
+                !hasProject
               }
             >
-              {isStreaming ? (
-                <>
-                  <Square className="h-3.5 w-3.5" aria-hidden="true" />
-                  停止
-                </>
-              ) : (
-                <>
-                  <Send className="h-3.5 w-3.5" aria-hidden="true" />
-                  发送
-                </>
-              )}
+              <Send className="h-3.5 w-3.5" aria-hidden="true" />
+              发送
             </button>
           </div>
         </form>
diff --git a/src/components/image-editor/EditorAgentConversation/MessageBubble.test.tsx b/src/components/image-editor/EditorAgentConversation/MessageBubble.test.tsx
new file mode 100644
index 000000000..257892551
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/MessageBubble.test.tsx
@@ -0,0 +1,53 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { EditorAgentMessage } from '@/packages/shared/src/contracts';
+
+import { MessageBubble } from './MessageBubble.tsx';
+
+function renderMessage(message: EditorAgentMessage) {
+  return render(
+    <MessageBubble
+      message={message}
+      busyAction={null}
+      onConfirmToolCall={vi.fn()}
+      onCancelToolCall={vi.fn()}
+    />,
+  );
+}
+
+describe('MessageBubble', () => {
+  it('shows prefixed system errors as red Agent errors without the wire prefix', () => {
+    renderMessage({
+      id: 2,
+      role: 'system',
+      text: 'ERROR planning failed',
+      attachments: [],
+      toolCall: null,
+      createdAt: '2026-07-16T00:00:00Z',
+    });
+
+    const error = screen.getByLabelText('Agent错误');
+    expect(error.textContent).toContain('planning failed');
+    expect(error.textContent).not.toContain('ERROR');
+    expect(error.firstElementChild?.classList.contains('bg-red-50')).toBe(true);
+    expect(error.firstElementChild?.classList.contains('text-red-700')).toBe(
+      true,
+    );
+  });
+
+  it('continues to hide internal system messages without the error prefix', () => {
+    const { container } = renderMessage({
+      id: 3,
+      role: 'system',
+      text: 'internal attachment bookkeeping',
+      attachments: [],
+      toolCall: null,
+      createdAt: '2026-07-16T00:00:00Z',
+    });
+
+    expect(container.childElementCount).toBe(0);
+  });
+});
diff --git a/src/components/image-editor/EditorAgentConversation/MessageBubble.tsx b/src/components/image-editor/EditorAgentConversation/MessageBubble.tsx
new file mode 100644
index 000000000..91e43eb52
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/MessageBubble.tsx
@@ -0,0 +1,136 @@
+import {
+  EDITOR_AGENT_ERROR_MESSAGE_PREFIX,
+  type EditorAgentMessage,
+} from '@/packages/shared/src/contracts';
+import AttachmentChip from '@/src/components/image-editor/EditorAgentConversation/AttachmentChip.tsx';
+import { attachmentKey } from '@/src/components/image-editor/EditorAgentConversation/common.ts';
+import { PendingToolCall } from '@/src/components/image-editor/EditorAgentConversation/PendingToolCall.tsx';
+import ToolCallView from '@/src/components/image-editor/EditorAgentConversation/ToolCallView.tsx';
+
+function messageRoleLabel(role: EditorAgentMessage['role']) {
+  if (role === 'user') {
+    return '你';
+  }
+  return 'Agent';
+}
+
+export function ThinkingBubble() {
+  return (
+    <article className="flex justify-start" aria-label="Agent思考中">
+      <div className="max-w-[86%] rounded-3xl border border-slate-200 bg-white px-3.5 py-3 text-sm leading-6 shadow-sm">
+        <div className="flex items-center gap-1.5">
+          <span className="flex gap-0.5">
+            <span
+              className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400"
+              style={{ animationDelay: '0ms' }}
+            />
+            <span
+              className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400"
+              style={{ animationDelay: '150ms' }}
+            />
+            <span
+              className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400"
+              style={{ animationDelay: '300ms' }}
+            />
+          </span>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+type MessageBubbleProps = {
+  message: EditorAgentMessage;
+  busyAction: 'confirm' | 'cancel' | null;
+  onConfirmToolCall: (messageId: number) => Promise<void>;
+  onCancelToolCall: (messageId: number) => Promise<void>;
+  onJobCompleted?: () => void;
+};
+
+export function MessageBubble({
+  message,
+  busyAction,
+  onConfirmToolCall,
+  onCancelToolCall,
+  onJobCompleted,
+}: MessageBubbleProps) {
+  const systemErrorText =
+    message.role === 'system' &&
+    !message.toolCall &&
+    message.text.startsWith(EDITOR_AGENT_ERROR_MESSAGE_PREFIX)
+      ? message.text.slice(EDITOR_AGENT_ERROR_MESSAGE_PREFIX.length)
+      : null;
+
+  if (message.role === 'system' && !message.toolCall && systemErrorText === null) {
+    return null;
+  }
+  if (
+    message.role === 'system' &&
+    message.toolCall &&
+    message.toolCall.status === 'not_completed' &&
+    !message.toolCall.externalJobId
+  ) {
+    return (
+      <PendingToolCall
+        messageId={message.id}
+        toolCall={message.toolCall}
+        busyAction={busyAction}
+        onConfirm={onConfirmToolCall}
+        onCancel={onCancelToolCall}
+      />
+    );
+  }
+
+  const isUser = message.role === 'user';
+  const isSystem = message.role === 'system';
+  const isSystemError = systemErrorText !== null;
+
+  return (
+    <article
+      className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}
+      aria-label={
+        isSystemError
+          ? 'Agent错误'
+          : isSystem
+            ? 'Agent操作'
+            : `${messageRoleLabel(message.role)}消息`
+      }
+    >
+      <div
+        className={
+          isSystem && !isSystemError
+            ? 'max-w-[86%]'
+            : `max-w-[86%] rounded-3xl px-3.5 py-3 text-sm leading-6 shadow-sm ${
+                isUser
+                  ? 'bg-slate-900 text-white'
+                  : isSystemError || message.toolCall?.status === 'failed'
+                    ? 'border border-red-200 bg-red-50 text-red-700'
+                    : 'border border-slate-200 bg-white text-slate-700'
+              }`
+        }
+      >
+        {(!isSystem || isSystemError) && (systemErrorText ?? message.text) ? (
+          <div className="whitespace-pre-wrap break-words">
+            {systemErrorText ?? message.text}
+          </div>
+        ) : null}
+        {!isSystem && message.attachments.length ? (
+          <div className="mt-2 flex flex-wrap gap-1.5">
+            {message.attachments.map((attachment) => (
+              <AttachmentChip
+                key={attachmentKey(attachment)}
+                attachment={attachment}
+              />
+            ))}
+          </div>
+        ) : null}
+        {message.toolCall ? (
+          <ToolCallView
+            toolCall={message.toolCall}
+            onJobCompleted={onJobCompleted}
+          />
+        ) : null}
+      </div>
+    </article>
+  );
+}
diff --git a/src/components/image-editor/EditorAgentConversation/PendingToolCall.tsx b/src/components/image-editor/EditorAgentConversation/PendingToolCall.tsx
new file mode 100644
index 000000000..cc53e1341
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/PendingToolCall.tsx
@@ -0,0 +1,155 @@
+import { Check, Coins, Loader2, Pencil, X } from 'lucide-react';
+
+import type { EditorAgentToolCall } from '@/packages/shared/src/contracts';
+import { editorAgentToolLabel } from '@/src/components/image-editor/EditorAgentConversation/toolCallPresentation.ts';
+import { ResolvedAssetImage } from '@/src/components/ResolvedAssetImage.tsx';
+
+type PendingToolCallAction = 'confirm' | 'cancel' | null;
+
+type PendingToolCallProps = {
+  messageId: number;
+  toolCall: EditorAgentToolCall;
+  busyAction: PendingToolCallAction;
+  onConfirm: (messageId: number) => Promise<void>;
+  onCancel: (messageId: number) => Promise<void>;
+};
+
+function readString(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+export function PendingToolCall({
+  messageId,
+  toolCall,
+  busyAction,
+  onConfirm,
+  onCancel,
+}: PendingToolCallProps) {
+  const displayArgs = toolCall.displayArgs;
+  const label = editorAgentToolLabel(toolCall.toolName);
+  const isBusy = busyAction !== null;
+  const statusLabel =
+    busyAction === 'confirm'
+      ? '执行中'
+      : busyAction === 'cancel'
+        ? '取消中'
+        : '待确认';
+
+  const handleCancel = () => {
+    void onCancel(messageId).catch(() => undefined);
+  };
+
+  const handleConfirm = () => {
+    void onConfirm(messageId).catch(() => undefined);
+  };
+
+  return (
+    <article className="flex justify-start" aria-label={`待确认的${label}操作`}>
+      <div className="w-full max-w-[86%] rounded-lg border border-slate-200 bg-white p-3 text-sm text-slate-700 shadow-sm">
+        <div className="flex items-center gap-2 font-medium text-slate-900">
+          <Pencil className="h-4 w-4 shrink-0" aria-hidden="true" />
+          <span>{label}</span>
+          <span className="ml-auto text-xs font-normal text-amber-700">
+            {statusLabel}
+          </span>
+        </div>
+
+        <div className="mt-3 space-y-3 empty:hidden">
+          {displayArgs.stringArgs.map((argument, index) => (
+            <div
+              key={`${argument.name}-${index}`}
+              className="rounded-lg bg-slate-50 px-2.5 py-2"
+            >
+              <div className="text-xs font-medium text-slate-500">
+                {argument.label}
+              </div>
+              <div className="mt-1 whitespace-pre-wrap break-words text-sm leading-5 text-slate-800">
+                {argument.value}
+              </div>
+            </div>
+          ))}
+
+          {displayArgs.imageArgs.map((argument, argumentIndex) => (
+            <div key={`${argument.name}-${argumentIndex}`}>
+              <div className="flex items-center gap-2 text-xs font-medium text-slate-500">
+                <span>{argument.label}</span>
+                <span className="font-normal text-slate-400">
+                  {argument.refs.length} 张
+                </span>
+              </div>
+              {argument.refs.length ? (
+                <div className="mt-1.5 flex flex-wrap gap-2">
+                  {argument.refs.map((image, imageIndex) => {
+                    const imageLabel =
+                      readString(image.label) ?? `图片 ${imageIndex + 1}`;
+                    return (
+                      <figure
+                        key={`${image.imageId}-${imageIndex}`}
+                        className="w-20 min-w-0"
+                      >
+                        <div className="overflow-hidden rounded-lg border border-slate-200 bg-slate-100">
+                          <ResolvedAssetImage
+                            src={image.thumbnailSrc ?? image.imageSrc}
+                            objectKey={image.objectKey}
+                            refreshKey={image.imageId}
+                            alt={`${argument.label}：${imageLabel}`}
+                            className="h-20 w-20 object-contain"
+                          />
+                        </div>
+                        {image.label ? (
+                          <figcaption className="mt-1 truncate text-center text-[11px] text-slate-500">
+                            {image.label}
+                          </figcaption>
+                        ) : null}
+                      </figure>
+                    );
+                  })}
+                </div>
+              ) : null}
+            </div>
+          ))}
+        </div>
+
+        <div className="mt-3 flex items-center gap-1.5 rounded-lg border border-amber-200 bg-amber-50 px-2.5 py-2 text-xs font-medium text-amber-800">
+          <Coins className="h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+          <span>预计消耗 {displayArgs.extras.priceMudPoints}泥点</span>
+        </div>
+
+        <div className="mt-3 flex justify-end gap-2">
+          <button
+            type="button"
+            className="inline-flex h-9 items-center justify-center gap-1.5 rounded-md border border-slate-200 bg-white px-3 text-sm text-slate-600 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-50"
+            disabled={isBusy}
+            onClick={handleCancel}
+          >
+            {busyAction === 'cancel' ? (
+              <Loader2
+                className="h-3.5 w-3.5 animate-spin"
+                aria-hidden="true"
+              />
+            ) : (
+              <X className="h-3.5 w-3.5" aria-hidden="true" />
+            )}
+            {busyAction === 'cancel' ? '取消中' : '取消'}
+          </button>
+          <button
+            type="button"
+            className="inline-flex h-9 items-center justify-center gap-1.5 rounded-md bg-slate-900 px-3 text-sm font-medium text-white hover:bg-slate-800 disabled:cursor-not-allowed disabled:opacity-50"
+            disabled={isBusy}
+            onClick={handleConfirm}
+          >
+            {busyAction === 'confirm' ? (
+              <Loader2
+                className="h-3.5 w-3.5 animate-spin"
+                aria-hidden="true"
+              />
+            ) : (
+              <Check className="h-3.5 w-3.5" aria-hidden="true" />
+            )}
+            {busyAction === 'confirm' ? '执行中' : '确认'}
+          </button>
+        </div>
+      </div>
+    </article>
+  );
+}
diff --git a/src/components/image-editor/EditorAgentConversation/ToolCallView.test.tsx b/src/components/image-editor/EditorAgentConversation/ToolCallView.test.tsx
new file mode 100644
index 000000000..8ec8c461f
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/ToolCallView.test.tsx
@@ -0,0 +1,154 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { EditorAgentToolCall } from '@/packages/shared/src/contracts';
+
+import ToolCallView from './ToolCallView.tsx';
+
+const getExternalGenerationJobStatusMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@/src/services/external-generation', () => ({
+  getExternalGenerationJobStatus: getExternalGenerationJobStatusMock,
+}));
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((nextResolve) => {
+    resolve = nextResolve;
+  });
+  return { promise, resolve };
+}
+
+function createToolCall(
+  overrides: Partial<EditorAgentToolCall> = {},
+): EditorAgentToolCall {
+  return {
+    toolName: 'generate-image',
+    status: 'not_completed',
+    args: {},
+    displayArgs: {
+      stringArgs: [],
+      imageArgs: [],
+      extras: { priceMudPoints: 1 },
+    },
+    externalJobId: 'job-a',
+    images: [],
+    error: null,
+    ...overrides,
+  };
+}
+
+function createCompletedJobResponse(jobId: string) {
+  return {
+    job: {
+      operationId: jobId,
+      status: 'completed' as const,
+      phaseLabel: '已完成',
+      phaseDetail: '生成完成',
+      progress: 100,
+      error: null,
+      updatedAtMicros: 1,
+    },
+  };
+}
+
+describe('ToolCallView', () => {
+  beforeEach(() => {
+    getExternalGenerationJobStatusMock.mockReset();
+  });
+
+  it.each([
+    ['failed', '失败', '生成失败'],
+    ['cancelled', '已取消', null],
+  ] as const)(
+    'keeps the server %s state when the pending response arrives late',
+    async (status, statusLabel, error) => {
+      const pendingResponse = createDeferred<
+        ReturnType<typeof createCompletedJobResponse>
+      >();
+      getExternalGenerationJobStatusMock.mockReturnValueOnce(
+        pendingResponse.promise,
+      );
+      const onJobCompleted = vi.fn();
+      const { rerender } = render(
+        <ToolCallView
+          toolCall={createToolCall()}
+          onJobCompleted={onJobCompleted}
+        />,
+      );
+
+      await waitFor(() => {
+        expect(getExternalGenerationJobStatusMock).toHaveBeenCalledWith(
+          'job-a',
+        );
+      });
+
+      rerender(
+        <ToolCallView
+          toolCall={createToolCall({ status, error })}
+          onJobCompleted={onJobCompleted}
+        />,
+      );
+      expect(await screen.findByText(statusLabel)).toBeTruthy();
+
+      await act(async () => {
+        pendingResponse.resolve(createCompletedJobResponse('job-a'));
+        await pendingResponse.promise;
+      });
+
+      expect(screen.getByText(statusLabel)).toBeTruthy();
+      expect(screen.queryByText('已完成')).toBeNull();
+      expect(onJobCompleted).not.toHaveBeenCalled();
+    },
+  );
+
+  it('ignores job A after switching to job B and completes job B once', async () => {
+    const jobAResponse = createDeferred<
+      ReturnType<typeof createCompletedJobResponse>
+    >();
+    const jobBResponse = createDeferred<
+      ReturnType<typeof createCompletedJobResponse>
+    >();
+    getExternalGenerationJobStatusMock.mockImplementation((jobId: string) =>
+      jobId === 'job-a' ? jobAResponse.promise : jobBResponse.promise,
+    );
+    const onJobCompleted = vi.fn();
+    const { rerender } = render(
+      <ToolCallView
+        toolCall={createToolCall()}
+        onJobCompleted={onJobCompleted}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(getExternalGenerationJobStatusMock).toHaveBeenCalledWith('job-a');
+    });
+
+    rerender(
+      <ToolCallView
+        toolCall={createToolCall({ externalJobId: 'job-b' })}
+        onJobCompleted={onJobCompleted}
+      />,
+    );
+    await waitFor(() => {
+      expect(getExternalGenerationJobStatusMock).toHaveBeenCalledWith('job-b');
+    });
+
+    await act(async () => {
+      jobAResponse.resolve(createCompletedJobResponse('job-a'));
+      await jobAResponse.promise;
+    });
+    expect(screen.getByText('执行中')).toBeTruthy();
+    expect(onJobCompleted).not.toHaveBeenCalled();
+
+    await act(async () => {
+      jobBResponse.resolve(createCompletedJobResponse('job-b'));
+      await jobBResponse.promise;
+    });
+
+    expect(await screen.findByText('已完成')).toBeTruthy();
+    expect(onJobCompleted).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/components/image-editor/EditorAgentConversation/ToolCallView.tsx b/src/components/image-editor/EditorAgentConversation/ToolCallView.tsx
new file mode 100644
index 000000000..0c39c9749
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/ToolCallView.tsx
@@ -0,0 +1,174 @@
+import { Check, Image as ImageIcon, Loader2, Volume2, X } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+import type { EditorAgentToolCall } from '@/packages/shared/src/contracts';
+import { editorAgentToolLabel } from '@/src/components/image-editor/EditorAgentConversation/toolCallPresentation.ts';
+import { ResolvedAssetAudio } from '@/src/components/ResolvedAssetAudio.tsx';
+import { ResolvedAssetImage } from '@/src/components/ResolvedAssetImage.tsx';
+import { ResolvedAssetVideo } from '@/src/components/ResolvedAssetVideo.tsx';
+import { getExternalGenerationJobStatus } from '@/src/services/external-generation';
+
+function ToolCallView({
+  toolCall,
+  onJobCompleted,
+}: {
+  toolCall: EditorAgentToolCall;
+  onJobCompleted?: () => void;
+}) {
+  const videos = toolCall.videos ?? [];
+  const audios = toolCall.audios ?? [];
+  const jobId = toolCall.externalJobId?.trim() || null;
+  const initialDisplayStatus =
+    toolCall.status === 'completed'
+      ? 'completed'
+      : toolCall.status === 'failed'
+        ? 'failed'
+        : toolCall.status === 'cancelled'
+          ? 'cancelled'
+          : 'pending';
+  const initialDisplayError = toolCall.error ?? null;
+  const shouldPoll = toolCall.status === 'not_completed' && Boolean(jobId);
+  const [displayStatus, setDisplayStatus] = useState(initialDisplayStatus);
+  const [displayError, setDisplayError] =
+    useState<string | null>(initialDisplayError);
+  const terminalNotifiedRef = useRef(false);
+  const onJobCompletedRef = useRef(onJobCompleted);
+  useEffect(() => {
+    onJobCompletedRef.current = onJobCompleted;
+  }, [onJobCompleted]);
+  useEffect(() => {
+    setDisplayStatus(initialDisplayStatus);
+    setDisplayError(initialDisplayError);
+    terminalNotifiedRef.current = false;
+    if (!shouldPoll || !jobId) return;
+    let disposed = false;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    const poll = async () => {
+      try {
+        const response = await getExternalGenerationJobStatus(jobId);
+        if (disposed) return;
+        if (
+          response.job.status === 'completed' ||
+          response.job.status === 'failed'
+        ) {
+          setDisplayStatus(response.job.status);
+          setDisplayError(response.job.error ?? null);
+          if (!terminalNotifiedRef.current) {
+            terminalNotifiedRef.current = true;
+            onJobCompletedRef.current?.();
+          }
+          return;
+        }
+        timeoutId = setTimeout(poll, 1500);
+      } catch {
+        if (!disposed) timeoutId = setTimeout(poll, 3000);
+      }
+    };
+    void poll();
+    return () => {
+      disposed = true;
+      if (timeoutId) clearTimeout(timeoutId);
+    };
+  }, [initialDisplayError, initialDisplayStatus, jobId, shouldPoll]);
+  const isCancelled = displayStatus === 'cancelled';
+  const isCompleted = displayStatus === 'completed';
+  const isFailed = displayStatus === 'failed';
+  const isExecuting = displayStatus === 'pending' && Boolean(jobId);
+  const statusLabel = isCompleted
+    ? '已完成'
+    : isFailed
+      ? '失败'
+      : isCancelled
+        ? '已取消'
+        : isExecuting
+          ? '执行中'
+          : '待确认';
+  return (
+    <div className="rounded-lg border border-slate-200 bg-white/80 p-2 text-xs text-slate-600">
+      <div className="flex items-center gap-2">
+        {isExecuting ? (
+          <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" />
+        ) : isCompleted ? (
+          <Check className="h-3.5 w-3.5" aria-hidden="true" />
+        ) : isCancelled || isFailed ? (
+          <X className="h-3.5 w-3.5" aria-hidden="true" />
+        ) : (
+          <ImageIcon className="h-3.5 w-3.5" aria-hidden="true" />
+        )}
+        <span>{editorAgentToolLabel(toolCall.toolName)}</span>
+        <span className="ml-auto text-slate-400">{statusLabel}</span>
+      </div>
+      {displayError ? (
+        <div className="mt-1 text-red-600">{displayError}</div>
+      ) : null}
+      {toolCall.images.length ? (
+        <div className="mt-2 grid grid-cols-3 gap-2">
+          {toolCall.images.map((image, index) => (
+            <div
+              key={`${toolCall.toolName}-${image.resourceId ?? index}`}
+              className="overflow-hidden rounded-xl border border-slate-200 bg-slate-100"
+            >
+              <ResolvedAssetImage
+                src={image.thumbnailSrc ?? image.imageSrc}
+                objectKey={image.objectKey}
+                refreshKey={image.resourceId ?? toolCall.toolName}
+                alt=""
+                className="h-20 w-full object-cover"
+              />
+            </div>
+          ))}
+        </div>
+      ) : null}
+      {videos.length ? (
+        <div className="mt-2 grid grid-cols-1 gap-2">
+          {videos.map((video, index) => (
+            <div
+              key={`${toolCall.toolName}-${video.resourceId ?? video.objectKey ?? index}`}
+              className="overflow-hidden rounded-xl border border-slate-200 bg-slate-100"
+            >
+              <ResolvedAssetVideo
+                src={video.videoSrc}
+                objectKey={video.objectKey}
+                refreshKey={
+                  video.resourceId ?? video.objectKey ?? toolCall.toolName
+                }
+                poster={video.thumbnailSrc ?? undefined}
+                controls
+                playsInline
+                preload="metadata"
+                className="max-h-56 w-full bg-black object-contain"
+              />
+            </div>
+          ))}
+        </div>
+      ) : null}
+      {audios.length ? (
+        <div className="mt-2 space-y-2">
+          {audios.map((audio, index) => (
+            <div
+              key={`${toolCall.toolName}-${audio.resourceId ?? audio.objectKey ?? index}`}
+              className="flex items-center gap-2 rounded-xl border border-slate-200 bg-slate-50 p-2"
+            >
+              <Volume2
+                className="h-4 w-4 shrink-0 text-slate-500"
+                aria-hidden="true"
+              />
+              <ResolvedAssetAudio
+                src={audio.audioSrc}
+                objectKey={audio.objectKey}
+                refreshKey={
+                  audio.resourceId ?? audio.objectKey ?? toolCall.toolName
+                }
+                controls
+                preload="metadata"
+                className="min-w-0 flex-1"
+              />
+            </div>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export default ToolCallView;
diff --git a/src/components/image-editor/EditorAgentConversation/common.ts b/src/components/image-editor/EditorAgentConversation/common.ts
new file mode 100644
index 000000000..05f675a8d
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/common.ts
@@ -0,0 +1,5 @@
+import type { EditorAgentAttachmentRef } from '@/packages/shared/src/contracts';
+
+export function attachmentKey(attachment: EditorAgentAttachmentRef) {
+  return `${attachment.source}:${attachment.referenceId}`;
+}
diff --git a/src/components/image-editor/EditorAgentConversation/toolCallPresentation.ts b/src/components/image-editor/EditorAgentConversation/toolCallPresentation.ts
new file mode 100644
index 000000000..8d6304851
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/toolCallPresentation.ts
@@ -0,0 +1,24 @@
+export function editorAgentToolLabel(toolName: string) {
+  if (toolName === 'edit-image') {
+    return '修改图片';
+  }
+  if (toolName === 'generate-character') {
+    return '生成角色';
+  }
+  if (toolName === 'generate-icon-spritesheet') {
+    return '生成图标';
+  }
+  if (toolName === 'generate-ui-design') {
+    return '生成 UI';
+  }
+  if (toolName === 'generate-video') {
+    return '生成视频';
+  }
+  if (toolName === 'generate-sound-effect') {
+    return '生成音效';
+  }
+  if (toolName === 'generate-background-music') {
+    return '生成背景音乐';
+  }
+  return '生成图片';
+}
diff --git a/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx b/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx
new file mode 100644
index 000000000..5dcc6ebf9
--- /dev/null
+++ b/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx
@@ -0,0 +1,860 @@
+/* @vitest-environment jsdom */
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  EditorAgentConversationDetail,
+  EditorAgentMessage,
+  EditorAgentMessageResponse,
+} from '../../../../packages/shared/src/contracts/editorAgent.ts';
+import {
+  type EditorAgentConversationClient,
+  useEditorAgentConversation,
+} from './useEditorAgentConversation.ts';
+
+function createEditImageDisplayArgs(prompt: string) {
+  return {
+    stringArgs: [{ name: 'prompt', label: '修改要求', value: prompt }],
+    imageArgs: [
+      {
+        name: 'object_image_id',
+        label: '目标图片',
+        refs: [
+          {
+            imageId: 'source-image',
+            imageSrc: '/source-image.png',
+            label: '源图片',
+          },
+        ],
+      },
+    ],
+    extras: { priceMudPoints: 3 },
+  };
+}
+
+function createClient(): EditorAgentConversationClient {
+  return {
+    listConversations: vi.fn().mockResolvedValue([
+      {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      },
+    ]),
+    createConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-2',
+      projectId: 'project-1',
+      title: '新对话',
+      messages: [],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:01:00.000Z',
+    }),
+    getConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    }),
+    deleteConversation: vi.fn().mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    }),
+    sendMessage: vi.fn().mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '把这个角色改成像素风',
+        updatedAt: '2026-07-03T00:00:01.000Z',
+      },
+      deltaMessages: [
+        {
+          id: 1,
+          role: 'assistant',
+          text: '我来处理',
+          attachments: [],
+          toolCall: {
+            toolName: 'generate_image',
+            status: 'completed',
+            externalJobId: 'task-generated-1',
+            args: {},
+            displayArgs: {
+              stringArgs: [],
+              imageArgs: [],
+              extras: { priceMudPoints: 0 },
+            },
+            images: [
+              {
+                resourceId: 'resource-result-1',
+                imageSrc: '/result.png',
+                thumbnailSrc: '/result-thumb.png',
+                width: 1024,
+                height: 1024,
+              },
+            ],
+            error: null,
+          },
+          createdAt: '2026-07-03T00:00:00.000Z',
+        },
+      ],
+      errorMessage: null,
+    } as EditorAgentMessageResponse),
+    confirmToolCall: vi.fn(),
+    cancelToolCall: vi.fn(),
+  };
+}
+
+describe('useEditorAgentConversation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('loads conversations and applies delta messages', async () => {
+    const client = createClient();
+    const onCanvasRefreshRequested = vi.fn();
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({
+        projectId: 'project-1',
+        client,
+        onCanvasRefreshRequested,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('把这个角色改成像素风');
+    });
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      'conversation-1',
+      expect.objectContaining({
+        clientMessageId: expect.stringMatching(/^editor-agent-/u),
+        text: '把这个角色改成像素风',
+        attachments: [],
+      }),
+      {},
+    );
+    expect(result.current.isWaiting).toBe(false);
+    expect(result.current.activeConversation?.title).toBe(
+      '把这个角色改成像素风',
+    );
+    expect(onCanvasRefreshRequested).toHaveBeenCalledTimes(1);
+    expect(result.current.messages.map((message) => message.text)).toEqual([
+      '把这个角色改成像素风',
+      '我来处理',
+    ]);
+    expect(result.current.messages[0]?.clientMessageId).toMatch(
+      /^editor-agent-/u,
+    );
+    expect(result.current.messages[1]?.toolCall).toEqual(
+      expect.objectContaining({
+        toolName: 'generate_image',
+        externalJobId: 'task-generated-1',
+        images: [
+          expect.objectContaining({
+            resourceId: 'resource-result-1',
+            thumbnailSrc: '/result-thumb.png',
+          }),
+        ],
+      }),
+    );
+  });
+
+  it('keeps the latest conversation when detail responses arrive out of order', async () => {
+    const client = createClient();
+    let resolveConversation2!: (detail: EditorAgentConversationDetail) => void;
+    let resolveConversation3!: (detail: EditorAgentConversationDetail) => void;
+    const conversation2Promise = new Promise<EditorAgentConversationDetail>(
+      (resolve) => {
+        resolveConversation2 = resolve;
+      },
+    );
+    const conversation3Promise = new Promise<EditorAgentConversationDetail>(
+      (resolve) => {
+        resolveConversation3 = resolve;
+      },
+    );
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversationId).toBe('conversation-1');
+    });
+    vi.mocked(client.getConversation).mockImplementation((conversationId) => {
+      if (conversationId === 'conversation-2') {
+        return conversation2Promise;
+      }
+      if (conversationId === 'conversation-3') {
+        return conversation3Promise;
+      }
+      throw new Error(`Unexpected conversation: ${conversationId}`);
+    });
+
+    let conversation2Load!: Promise<EditorAgentConversationDetail | null>;
+    let conversation3Load!: Promise<EditorAgentConversationDetail | null>;
+    act(() => {
+      conversation2Load = result.current.selectConversation('conversation-2');
+      conversation3Load = result.current.selectConversation('conversation-3');
+    });
+
+    await act(async () => {
+      resolveConversation3({
+        conversationId: 'conversation-3',
+        projectId: 'project-1',
+        title: '第三个会话',
+        messages: [
+          {
+            id: 3,
+            role: 'assistant',
+            text: '第三个会话消息',
+            attachments: [],
+            toolCall: null,
+            createdAt: '2026-07-03T00:03:00.000Z',
+          },
+        ],
+        createdAt: '2026-07-03T00:03:00.000Z',
+        updatedAt: '2026-07-03T00:03:00.000Z',
+      });
+      await conversation3Load;
+    });
+    expect(result.current.activeConversationId).toBe('conversation-3');
+    expect(result.current.messages[0]?.text).toBe('第三个会话消息');
+    expect(result.current.isLoadingMessages).toBe(false);
+
+    await act(async () => {
+      resolveConversation2({
+        conversationId: 'conversation-2',
+        projectId: 'project-1',
+        title: '第二个会话',
+        messages: [
+          {
+            id: 2,
+            role: 'assistant',
+            text: '第二个会话消息',
+            attachments: [],
+            toolCall: null,
+            createdAt: '2026-07-03T00:02:00.000Z',
+          },
+        ],
+        createdAt: '2026-07-03T00:02:00.000Z',
+        updatedAt: '2026-07-03T00:02:00.000Z',
+      });
+      await conversation2Load;
+    });
+    expect(result.current.activeConversationId).toBe('conversation-3');
+    expect(result.current.messages[0]?.text).toBe('第三个会话消息');
+    expect(result.current.isLoadingMessages).toBe(false);
+  });
+
+  it('appends a lazily reconciled tool message delta', async () => {
+    const client = createClient();
+    const pendingMessage: EditorAgentMessage = {
+      id: 0,
+      role: 'system',
+      text: 'pending edit',
+      attachments: [],
+      toolCall: {
+        toolName: 'edit-image',
+        status: 'not_completed',
+        externalJobId: 'task-edit-1',
+        args: {
+          object_image_id: 'source-image',
+          prompt: '换成像素风',
+        },
+        displayArgs: createEditImageDisplayArgs('换成像素风'),
+        images: [],
+        error: null,
+      },
+      createdAt: '2026-07-03T00:00:00.000Z',
+    };
+    vi.mocked(client.getConversation).mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [pendingMessage],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    });
+    vi.mocked(client.sendMessage).mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:01.000Z',
+      },
+      deltaMessages: [
+        {
+          ...pendingMessage,
+          text: '[tool_call:edit-image] output: completed',
+          toolCall: {
+            ...pendingMessage.toolCall!,
+            status: 'completed',
+            images: [{ imageSrc: '/generated/result.png' }],
+          },
+        },
+      ],
+      errorMessage: null,
+    });
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+    await waitFor(() => {
+      expect(result.current.messages).toHaveLength(1);
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('继续');
+    });
+
+    expect(result.current.messages).toHaveLength(3);
+    expect(result.current.messages[2]?.toolCall?.images[0]?.imageSrc).toBe(
+      '/generated/result.png',
+    );
+  });
+
+  it('does not apply a completed message response after switching conversations', async () => {
+    const client = createClient();
+    const onCanvasRefreshRequested = vi.fn();
+    let resolveSend!: (response: EditorAgentMessageResponse) => void;
+    vi.mocked(client.sendMessage).mockImplementation(
+      () =>
+        new Promise<EditorAgentMessageResponse>((resolve) => {
+          resolveSend = resolve;
+        }),
+    );
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({
+        projectId: 'project-1',
+        client,
+        onCanvasRefreshRequested,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversationId).toBe('conversation-1');
+    });
+
+    let sendPromise!: Promise<void>;
+    act(() => {
+      sendPromise = result.current.sendMessage('在第一个会话生成图片');
+    });
+    await waitFor(() => {
+      expect(result.current.isWaiting).toBe(true);
+    });
+
+    vi.mocked(client.getConversation).mockResolvedValueOnce({
+      conversationId: 'conversation-2',
+      projectId: 'project-1',
+      title: '第二个会话',
+      messages: [
+        {
+          id: 20,
+          role: 'assistant',
+          text: '第二个会话原有消息',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-03T00:02:00.000Z',
+        },
+      ],
+      createdAt: '2026-07-03T00:02:00.000Z',
+      updatedAt: '2026-07-03T00:02:00.000Z',
+    });
+    await act(async () => {
+      await result.current.selectConversation('conversation-2');
+    });
+
+    await act(async () => {
+      resolveSend({
+        conversation: {
+          conversationId: 'conversation-1',
+          projectId: 'project-1',
+          title: '第一个会话已更新',
+          updatedAt: '2026-07-03T00:03:00.000Z',
+        },
+        deltaMessages: [
+          {
+            id: 21,
+            role: 'assistant',
+            text: '第一个会话生成完成',
+            attachments: [],
+            toolCall: {
+              toolName: 'generate_image',
+              status: 'completed',
+              externalJobId: 'task-conversation-1',
+              args: {},
+              displayArgs: {
+                stringArgs: [],
+                imageArgs: [],
+                extras: { priceMudPoints: 0 },
+              },
+              images: [{ imageSrc: '/conversation-1-result.png' }],
+              error: null,
+            },
+            createdAt: '2026-07-03T00:03:00.000Z',
+          },
+        ],
+        errorMessage: null,
+      });
+      await sendPromise;
+    });
+
+    expect(result.current.activeConversationId).toBe('conversation-2');
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0]?.text).toBe('第二个会话原有消息');
+    expect(onCanvasRefreshRequested).not.toHaveBeenCalled();
+    expect(
+      result.current.conversations.find(
+        (conversation) => conversation.conversationId === 'conversation-1',
+      )?.title,
+    ).toBe('第一个会话已更新');
+  });
+
+  it('creates a conversation before sending when the project has no history', async () => {
+    const client = createClient();
+    vi.mocked(client.listConversations).mockResolvedValueOnce([]);
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.isLoadingConversations).toBe(false);
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('新建后发送');
+    });
+
+    expect(client.createConversation).toHaveBeenCalledWith('project-1', {});
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      'conversation-2',
+      expect.objectContaining({ text: '新建后发送' }),
+      expect.any(Object),
+    );
+  });
+
+  it('allows sending an attachment-only message', async () => {
+    const client = createClient();
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('', [
+        {
+          source: 'canvas_resource',
+          referenceId: 'resource-1',
+          objectKey: 'generated-editor-assets/resource-1.png',
+          imageSrc: '/resource-1.png',
+          label: '参考图',
+        },
+      ]);
+    });
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      'conversation-1',
+      expect.objectContaining({
+        text: '',
+        attachments: [
+          expect.objectContaining({
+            source: 'canvas_resource',
+            referenceId: 'resource-1',
+          }),
+        ],
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it('applies persisted backend planning errors as system messages', async () => {
+    const client = createClient();
+    vi.mocked(client.sendMessage).mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '这是美术素材',
+        updatedAt: '2026-07-03T00:00:01.000Z',
+      },
+      deltaMessages: [
+        {
+          id: 2,
+          role: 'system',
+          text: 'ERROR LLM 未配置，无法处理这句话。',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-16T00:00:01.000Z',
+        },
+      ],
+      errorMessage: null,
+    } as EditorAgentMessageResponse);
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('这是美术素材');
+    });
+
+    expect(result.current.errorMessage).toBeNull();
+    expect(result.current.messages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: 'system',
+          text: 'ERROR LLM 未配置，无法处理这句话。',
+        }),
+      ]),
+    );
+  });
+
+  it('confirms a pending tool call, replaces its message and requests a canvas refresh', async () => {
+    const client = createClient();
+    vi.mocked(client.sendMessage).mockResolvedValue({
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        updatedAt: '2026-07-03T00:00:01.000Z',
+      },
+      deltaMessages: [
+        {
+          id: 2,
+          role: 'system',
+          text: '需要生成一张图',
+          attachments: [],
+          toolCall: {
+            toolName: 'edit-image',
+            status: 'not_completed',
+            args: {
+              object_image_id: 'source-image',
+              prompt: '换成像素风',
+            },
+            displayArgs: createEditImageDisplayArgs('换成像素风'),
+            images: [],
+            error: null,
+          },
+          createdAt: '2026-07-03T00:00:00.000Z',
+        },
+      ],
+      errorMessage: null,
+    } as EditorAgentMessageResponse);
+    const confirmedMessage: EditorAgentMessage = {
+      id: 2,
+      role: 'system',
+      text: 'internal confirmed tool output',
+      attachments: [],
+      toolCall: {
+        toolName: 'edit-image',
+        status: 'not_completed',
+        externalJobId: 'task-edit-1',
+        args: {
+          object_image_id: 'source-image',
+          prompt: '换成像素风',
+        },
+        displayArgs: createEditImageDisplayArgs('换成像素风'),
+        images: [],
+        error: null,
+      },
+      createdAt: '2026-07-03T00:00:00.000Z',
+    };
+    vi.mocked(client.confirmToolCall).mockResolvedValue(undefined);
+    const onCanvasRefreshRequested = vi.fn();
+    const onConfirmSent = vi.fn();
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({
+        projectId: 'project-1',
+        client,
+        onCanvasRefreshRequested,
+        onConfirmSent,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    await act(async () => {
+      await result.current.sendMessage('生成一张图');
+    });
+
+    const systemMsg = result.current.messages[1];
+    expect(systemMsg?.role).toBe('system');
+    expect(systemMsg?.id).toBe(2);
+    expect(systemMsg?.toolCall?.externalJobId).toBeUndefined();
+    vi.mocked(client.getConversation).mockResolvedValue({
+      conversationId: 'conversation-1',
+      projectId: 'project-1',
+      title: '角色参考',
+      messages: [result.current.messages[0]!, confirmedMessage],
+      createdAt: '2026-07-03T00:00:00.000Z',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    });
+    const getConversationCallsBeforeConfirm = vi.mocked(client.getConversation)
+      .mock.calls.length;
+
+    const messageCount = result.current.messages.length;
+    await act(async () => {
+      await result.current.confirmToolCall(systemMsg!.id);
+    });
+
+    expect(client.confirmToolCall).toHaveBeenCalledWith('conversation-1', 2);
+    expect(client.getConversation).toHaveBeenCalledTimes(
+      getConversationCallsBeforeConfirm + 1,
+    );
+    expect(result.current.messages).toHaveLength(messageCount);
+    expect(result.current.messages[1]?.toolCall?.status).toBe('not_completed');
+    expect(result.current.messages[1]?.toolCall?.externalJobId).toBe(
+      'task-edit-1',
+    );
+    expect(onCanvasRefreshRequested).not.toHaveBeenCalled();
+    expect(onConfirmSent).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the action busy until confirmation succeeds', async () => {
+    const client = createClient();
+    const pendingMessage: EditorAgentMessage = {
+      id: 7,
+      role: 'system',
+      text: '需要生成一张图',
+      attachments: [],
+      toolCall: {
+        toolName: 'edit-image',
+        status: 'not_completed',
+        args: { object_image_id: 'source-image', prompt: '换成像素风' },
+        displayArgs: createEditImageDisplayArgs('换成像素风'),
+        images: [],
+        error: null,
+      },
+      createdAt: '2026-07-03T00:00:00.000Z',
+    };
+    const confirmedMessage: EditorAgentMessage = {
+      ...pendingMessage,
+      toolCall: {
+        ...pendingMessage.toolCall!,
+        externalJobId: 'task-edit-2',
+      },
+    };
+    let resolveConfirmation: (() => void) | undefined;
+    vi.mocked(client.getConversation)
+      .mockResolvedValueOnce({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [pendingMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      })
+      .mockResolvedValue({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [confirmedMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      });
+    vi.mocked(client.confirmToolCall).mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveConfirmation = resolve;
+        }),
+    );
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.messages[0]?.role).toBe('system');
+      expect(
+        result.current.messages[0]?.toolCall?.externalJobId,
+      ).toBeUndefined();
+    });
+    const getConversationCallsBeforeConfirm = vi.mocked(client.getConversation)
+      .mock.calls.length;
+
+    let confirmationPromise: Promise<void> | undefined;
+    act(() => {
+      confirmationPromise = result.current.confirmToolCall(7);
+    });
+    await waitFor(() => expect(resolveConfirmation).toBeTypeOf('function'));
+    expect(client.confirmToolCall).toHaveBeenCalledWith('conversation-1', 7);
+
+    await act(async () => {
+      resolveConfirmation?.();
+      await confirmationPromise;
+    });
+    expect(result.current.toolCallAction).toBeNull();
+    expect(client.getConversation).toHaveBeenCalledTimes(
+      getConversationCallsBeforeConfirm + 1,
+    );
+    expect(result.current.messages[0]?.toolCall?.externalJobId).toBe(
+      'task-edit-2',
+    );
+  });
+
+  it('cancels a pending tool call with the refreshed cancelled message', async () => {
+    const client = createClient();
+    const pendingMessage: EditorAgentMessage = {
+      id: 9,
+      role: 'system' as const,
+      text: 'internal pending tool prompt',
+      attachments: [],
+      toolCall: {
+        toolName: 'edit-image',
+        status: 'not_completed',
+        args: { object_image_id: 'source-image', prompt: '换成像素风' },
+        displayArgs: createEditImageDisplayArgs('换成像素风'),
+        images: [],
+        error: null,
+      },
+      createdAt: '2026-07-03T00:00:00.000Z',
+    };
+    const cancelledMessage: EditorAgentMessage = {
+      ...pendingMessage,
+      text: 'internal cancelled tool output',
+      toolCall: {
+        ...pendingMessage.toolCall!,
+        status: 'cancelled',
+      },
+    };
+    vi.mocked(client.cancelToolCall).mockResolvedValue(undefined);
+    vi.mocked(client.getConversation)
+      .mockResolvedValueOnce({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [pendingMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      })
+      .mockResolvedValue({
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '角色参考',
+        messages: [cancelledMessage],
+        createdAt: '2026-07-03T00:00:00.000Z',
+        updatedAt: '2026-07-03T00:00:00.000Z',
+      });
+    const onCanvasRefreshRequested = vi.fn();
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({
+        projectId: 'project-1',
+        client,
+        onCanvasRefreshRequested,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.messages[0]?.toolCall?.status).toBe('not_completed');
+    });
+    const getConversationCallsBeforeCancel = vi.mocked(client.getConversation)
+      .mock.calls.length;
+    await act(async () => {
+      await result.current.cancelToolCall(9);
+    });
+
+    expect(client.cancelToolCall).toHaveBeenCalledWith('conversation-1', 9);
+    expect(client.getConversation).toHaveBeenCalledTimes(
+      getConversationCallsBeforeCancel + 1,
+    );
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0]?.toolCall?.status).toBe('cancelled');
+    expect(onCanvasRefreshRequested).not.toHaveBeenCalled();
+  });
+
+  it('rethrows fetch errors and rolls back the optimistic message', async () => {
+    const client = createClient();
+    vi.mocked(client.sendMessage).mockRejectedValue(new Error('Network error'));
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    await act(async () => {
+      await expect(result.current.sendMessage('test')).rejects.toThrow(
+        'Network error',
+      );
+    });
+
+    expect(result.current.errorMessage).toBe('Network error');
+    expect(result.current.messages).toHaveLength(0);
+  });
+
+  it('keeps the active request pending without exposing a stop action', async () => {
+    const client = createClient();
+    let capturedSignal: AbortSignal | null = null;
+    let resolveSend!: (response: EditorAgentMessageResponse) => void;
+    vi.mocked(client.sendMessage).mockImplementation(
+      (_conversationId, _payload, options) =>
+        new Promise<EditorAgentMessageResponse>((resolve) => {
+          resolveSend = resolve;
+          capturedSignal = options.signal ?? null;
+        }),
+    );
+    const { result } = renderHook(() =>
+      useEditorAgentConversation({ projectId: 'project-1', client }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.activeConversation?.conversationId).toBe(
+        'conversation-1',
+      );
+    });
+
+    void act(() => {
+      void result.current.sendMessage('请继续');
+    });
+    await waitFor(() => {
+      expect(result.current.isWaiting).toBe(true);
+    });
+
+    expect(capturedSignal).toBeNull();
+    expect('stopCurrentTurn' in result.current).toBe(false);
+
+    await act(async () => {
+      resolveSend({
+        conversation: {
+          conversationId: 'conversation-1',
+          projectId: 'project-1',
+          title: '角色参考',
+          updatedAt: '2026-07-03T00:00:20.000Z',
+        },
+        deltaMessages: [],
+        errorMessage: null,
+      });
+    });
+
+    await waitFor(() => {
+      expect(result.current.isWaiting).toBe(false);
+    });
+  });
+});
diff --git a/src/components/image-editor/useEditorAgentConversation.ts b/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts
similarity index 50%
rename from src/components/image-editor/useEditorAgentConversation.ts
rename to src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts
index 76401dfff..5c1d66326 100644
--- a/src/components/image-editor/useEditorAgentConversation.ts
+++ b/src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts
@@ -5,21 +5,21 @@ import type {
   EditorAgentAttachmentRef,
   EditorAgentConversationDetail,
   EditorAgentConversationSummary,
-  EditorAgentGenerationResultEvent,
-  EditorAgentGenerationRecord,
   EditorAgentMessage,
-  EditorAgentSseEvent,
-  EditorAgentStage,
-  StreamEditorAgentMessageRequest,
-} from '../../../packages/shared/src/contracts/editorAgent';
+  EditorAgentMessageRequest,
+  EditorAgentMessageResponse,
+} from '@/packages/shared/src/contracts';
+
 import {
+  cancelEditorAgentToolCall,
+  confirmEditorAgentToolCall,
   createEditorAgentConversation,
   deleteEditorAgentConversation,
   getEditorAgentConversation,
   listEditorAgentConversations,
-  streamEditorAgentMessage,
-  type StreamEditorAgentMessageOptions,
-} from '../../services/image-editor/editorAgentClient';
+  sendEditorAgentMessage,
+  type SendEditorAgentMessageOptions,
+} from '../../../services/image-editor/editorAgentClient.ts';
 
 export type EditorAgentConversationClient = {
   listConversations: (
@@ -35,141 +35,70 @@ export type EditorAgentConversationClient = {
   deleteConversation: (
     conversationId: string,
   ) => Promise<EditorAgentConversationSummary>;
-  streamMessage: (
+  sendMessage: (
     conversationId: string,
-    payload: StreamEditorAgentMessageRequest,
-    options: StreamEditorAgentMessageOptions,
+    payload: EditorAgentMessageRequest,
+    options: SendEditorAgentMessageOptions,
+  ) => Promise<EditorAgentMessageResponse>;
+  confirmToolCall: (
+    conversationId: string,
+    messageId: number,
+  ) => Promise<void>;
+  cancelToolCall: (
+    conversationId: string,
+    messageId: number,
   ) => Promise<void>;
 };
 
 type UseEditorAgentConversationOptions = {
   projectId?: string | null;
   client?: EditorAgentConversationClient;
-  onGenerationResult?: (event: EditorAgentGenerationResultEvent) => void;
+  onCanvasRefreshRequested?: () => void;
+  onConfirmSent?: () => void;
 };
 
+export type EditorAgentToolCallAction = 'confirm' | 'cancel';
+
+export type EditorAgentToolCallActionState = {
+  messageId: number;
+  action: EditorAgentToolCallAction;
+} | null;
+
 const defaultEditorAgentConversationClient: EditorAgentConversationClient = {
   listConversations: listEditorAgentConversations,
   createConversation: createEditorAgentConversation,
   getConversation: getEditorAgentConversation,
   deleteConversation: deleteEditorAgentConversation,
-  streamMessage: streamEditorAgentMessage,
+  sendMessage: sendEditorAgentMessage,
+  confirmToolCall: confirmEditorAgentToolCall,
+  cancelToolCall: cancelEditorAgentToolCall,
 };
 
-function createClientId(prefix: string) {
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.randomUUID === 'function'
-  ) {
-    return `${prefix}-${crypto.randomUUID()}`;
-  }
-  return `${prefix}-${Date.now().toString(36)}-${Math.random()
-    .toString(36)
-    .slice(2)}`;
-}
-
-function isAbortError(error: unknown) {
-  return (
-    error instanceof Error &&
-    (error.name === 'AbortError' ||
-      (typeof DOMException !== 'undefined' &&
-        error instanceof DOMException &&
-        error.name === 'AbortError'))
-  );
+function createEditorAgentClientMessageId() {
+  const randomId =
+    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  return `editor-agent-${randomId}`;
 }
 
 function createLocalUserMessage(params: {
-  id: string;
+  id: number;
+  clientMessageId: string;
   text: string;
   attachments: EditorAgentAttachmentRef[];
 }): EditorAgentMessage {
   return {
     id: params.id,
+    clientMessageId: params.clientMessageId,
     role: 'user',
-    kind: 'chat',
     text: params.text,
     attachments: params.attachments,
-    generations: [],
-    status: 'completed',
+    toolCall: null,
     createdAt: new Date().toISOString(),
   };
 }
 
-function createAssistantMessage(params: {
-  id: string;
-  role?: EditorAgentMessage['role'];
-  kind?: EditorAgentMessage['kind'];
-  text?: string;
-  status?: EditorAgentMessage['status'];
-  generations?: EditorAgentGenerationRecord[];
-}): EditorAgentMessage {
-  return {
-    id: params.id,
-    role: params.role ?? 'assistant',
-    kind: params.kind ?? 'chat',
-    text: params.text ?? '',
-    attachments: [],
-    generations: params.generations ?? [],
-    status: params.status ?? 'streaming',
-    createdAt: new Date().toISOString(),
-  };
-}
-
-function upsertMessage(
-  messages: EditorAgentMessage[],
-  messageId: string,
-  createMessage: () => EditorAgentMessage,
-  updateMessage: (message: EditorAgentMessage) => EditorAgentMessage,
-) {
-  let updated = false;
-  const nextMessages = messages.map((message) => {
-    if (message.id !== messageId) {
-      return message;
-    }
-    updated = true;
-    return updateMessage(message);
-  });
-  if (updated) {
-    return nextMessages;
-  }
-  return [...messages, updateMessage(createMessage())];
-}
-
-function upsertGenerationRecord(
-  records: EditorAgentGenerationRecord[],
-  nextRecord: EditorAgentGenerationRecord,
-) {
-  const existingIndex = records.findIndex(
-    (record) => record.toolCallId === nextRecord.toolCallId,
-  );
-  if (existingIndex === -1) {
-    return [...records, nextRecord];
-  }
-  return records.map((record, index) =>
-    index === existingIndex
-      ? {
-          ...record,
-          ...nextRecord,
-          summary: nextRecord.summary ?? record.summary,
-          taskId: nextRecord.taskId ?? record.taskId,
-          model: nextRecord.model ?? record.model,
-          images: nextRecord.images.length ? nextRecord.images : record.images,
-        }
-      : record,
-  );
-}
-
-function markStreamingMessages(
-  messages: EditorAgentMessage[],
-  status: EditorAgentMessage['status'],
-) {
-  return messages.map((message) =>
-    message.status === 'streaming' || message.status === 'generating'
-      ? { ...message, status }
-      : message,
-  );
-}
-
 function sortConversationsByUpdatedAt(
   conversations: EditorAgentConversationSummary[],
 ) {
@@ -187,7 +116,6 @@ function summaryFromDetail(
     conversationId: detail.conversationId,
     projectId: detail.projectId,
     title: detail.title,
-    createdAt: detail.createdAt,
     updatedAt: detail.updatedAt,
   };
 }
@@ -211,7 +139,8 @@ function upsertConversationSummary(
 export function useEditorAgentConversation({
   projectId,
   client = defaultEditorAgentConversationClient,
-  onGenerationResult,
+  onCanvasRefreshRequested,
+  onConfirmSent,
 }: UseEditorAgentConversationOptions) {
   const normalizedProjectId = projectId?.trim() ?? '';
   const [conversations, setConversations] = useState<
@@ -221,15 +150,17 @@ export function useEditorAgentConversation({
     string | null
   >(null);
   const [messages, setMessages] = useState<EditorAgentMessage[]>([]);
-  const [stage, setStage] = useState<EditorAgentStage>('idle');
   const [isLoadingConversations, setIsLoadingConversations] = useState(false);
   const [isLoadingMessages, setIsLoadingMessages] = useState(false);
   const [isCreatingConversation, setIsCreatingConversation] = useState(false);
   const [isDeletingConversation, setIsDeletingConversation] = useState(false);
-  const [isStreaming, setIsStreaming] = useState(false);
+  const [isWaiting, setIsWaiting] = useState(false);
+  const [toolCallAction, setToolCallAction] =
+    useState<EditorAgentToolCallActionState>(null);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
-  const activeStreamAbortControllerRef = useRef<AbortController | null>(null);
   const activeConversationIdRef = useRef<string | null>(null);
+  const activeToolCallActionRef = useRef<EditorAgentToolCallActionState>(null);
+  const conversationLoadRequestIdRef = useRef(0);
 
   useEffect(() => {
     activeConversationIdRef.current = activeConversationId;
@@ -248,6 +179,7 @@ export function useEditorAgentConversation({
 
   const applyConversationDetail = useCallback(
     (detail: EditorAgentConversationDetail) => {
+      activeConversationIdRef.current = detail.conversationId;
       setConversations((currentConversations) =>
         upsertConversationSummary(
           currentConversations,
@@ -256,37 +188,52 @@ export function useEditorAgentConversation({
       );
       setActiveConversationId(detail.conversationId);
       setMessages(detail.messages);
-      setStage('idle');
     },
     [],
   );
 
   const loadConversation = useCallback(
-    async (conversationId: string) => {
-      setIsLoadingMessages(true);
+    async (
+      conversationId: string,
+      options: { showLoading?: boolean } = {},
+    ) => {
+      const requestId = conversationLoadRequestIdRef.current + 1;
+      conversationLoadRequestIdRef.current = requestId;
+      const showLoading = options.showLoading ?? true;
+      if (showLoading) {
+        setIsLoadingMessages(true);
+      }
       setErrorMessage(null);
       try {
         const detail = await client.getConversation(conversationId);
-        applyConversationDetail(detail);
+        if (conversationLoadRequestIdRef.current === requestId) {
+          applyConversationDetail(detail);
+        }
         return detail;
       } catch (error) {
-        setErrorMessage(
-          error instanceof Error ? error.message : '读取画布 Agent 会话失败',
-        );
+        if (conversationLoadRequestIdRef.current === requestId) {
+          setErrorMessage(
+            error instanceof Error ? error.message : '读取画布 Agent 会话失败',
+          );
+        }
         throw error;
       } finally {
-        setIsLoadingMessages(false);
+        if (conversationLoadRequestIdRef.current === requestId) {
+          setIsLoadingMessages(false);
+        }
       }
     },
     [applyConversationDetail, client],
   );
 
   useEffect(() => {
+    conversationLoadRequestIdRef.current += 1;
+    setIsLoadingMessages(false);
     if (!normalizedProjectId) {
       setConversations([]);
+      activeConversationIdRef.current = null;
       setActiveConversationId(null);
       setMessages([]);
-      setStage('idle');
       setErrorMessage(null);
       return undefined;
     }
@@ -304,6 +251,7 @@ export function useEditorAgentConversation({
         setConversations(sortedConversations);
         const firstConversation = sortedConversations[0] ?? null;
         if (!firstConversation) {
+          activeConversationIdRef.current = null;
           setActiveConversationId(null);
           setMessages([]);
           return;
@@ -365,156 +313,42 @@ export function useEditorAgentConversation({
     [activeConversationId, loadConversation],
   );
 
-  const handleSseEvent = useCallback((event: EditorAgentSseEvent) => {
-    const eventConversationId = event.data.conversationId;
-    if (
-      eventConversationId &&
-      eventConversationId !== activeConversationIdRef.current
-    ) {
-      return;
+  const refreshActiveConversation = useCallback(async () => {
+    const conversationId = activeConversationIdRef.current;
+    if (!conversationId) {
+      return null;
     }
+    return loadConversation(conversationId, { showLoading: false });
+  }, [loadConversation]);
 
-    if (event.event === 'stage') {
-      setStage(event.data.stage);
-      return;
-    }
-
-    if (event.event === 'message_delta') {
-      if (event.data.kind === 'error') {
-        const nextErrorMessage = event.data.textDelta.trim();
-        if (nextErrorMessage) {
-          setErrorMessage(nextErrorMessage);
-        }
+  const requestCanvasRefreshForMessages = useCallback(
+    (nextMessages: EditorAgentMessage[]) => {
+      if (
+        nextMessages.some((message) => {
+          const toolCall = message.toolCall;
+          return Boolean(
+            toolCall?.externalJobId &&
+            (toolCall.images.length > 0 ||
+              (toolCall.videos?.length ?? 0) > 0 ||
+              (toolCall.audios?.length ?? 0) > 0),
+          );
+        })
+      ) {
+        onCanvasRefreshRequested?.();
       }
-      setMessages((currentMessages) =>
-        upsertMessage(
-          currentMessages,
-          event.data.messageId,
-          () =>
-            createAssistantMessage({
-              id: event.data.messageId,
-              role: event.data.role,
-              kind: event.data.kind,
-            }),
-          (message) => ({
-            ...message,
-            role: event.data.role,
-            kind: event.data.kind,
-            text: `${message.text}${event.data.textDelta}`,
-            status: event.data.kind === 'error' ? 'failed' : 'streaming',
-          }),
-        ),
-      );
-      return;
-    }
+    },
+    [onCanvasRefreshRequested],
+  );
 
-    if (event.event === 'tool_started' || event.event === 'tool_completed') {
-      const status =
-        event.event === 'tool_started'
-          ? 'generating'
-          : (event.data.status ?? 'completed');
-      const nextRecord: EditorAgentGenerationRecord = {
-        toolCallId: event.data.toolCallId,
-        toolName: event.data.toolName,
-        summary: event.data.summary ?? null,
-        taskId: event.data.taskId ?? null,
-        status,
-        model: event.data.model ?? null,
-        images: [],
-        error: event.data.error ?? null,
-      };
-      setMessages((currentMessages) =>
-        upsertMessage(
-          currentMessages,
-          event.data.messageId,
-          () =>
-            createAssistantMessage({
-              id: event.data.messageId,
-              status,
-              generations: [nextRecord],
-            }),
-          (message) => ({
-            ...message,
-            status,
-            generations: upsertGenerationRecord(
-              message.generations,
-              nextRecord,
-            ),
-          }),
-        ),
-      );
-      return;
-    }
-
-    if (event.event === 'generation_result') {
-      onGenerationResult?.(event.data);
-      const nextRecord: EditorAgentGenerationRecord = {
-        toolCallId: event.data.toolCallId,
-        toolName: event.data.toolName,
-        summary: null,
-        taskId: null,
-        status: 'completed',
-        model: event.data.model,
-        images: event.data.images,
-      };
-      setMessages((currentMessages) =>
-        upsertMessage(
-          currentMessages,
-          event.data.messageId,
-          () =>
-            createAssistantMessage({
-              id: event.data.messageId,
-              status: 'completed',
-              generations: [nextRecord],
-            }),
-          (message) => ({
-            ...message,
-            status: 'completed',
-            generations: upsertGenerationRecord(
-              message.generations,
-              nextRecord,
-            ),
-          }),
-        ),
-      );
-      return;
-    }
-
-    if (event.event === 'error') {
-      const messageId = createClientId('agent-error');
-      setStage('failed');
-      setErrorMessage(event.data.message);
-      setMessages((currentMessages) => [
-        ...currentMessages,
-        createAssistantMessage({
-          id: messageId,
-          kind: 'error',
-          text: event.data.message,
-          status: 'failed',
-        }),
-      ]);
-      return;
-    }
-
-    if (event.event === 'done') {
-      setStage((currentStage) =>
-        currentStage === 'failed' ? 'failed' : 'completed',
-      );
-      setMessages((currentMessages) =>
-        markStreamingMessages(currentMessages, 'completed'),
-      );
-      const nextTitle = event.data.title?.trim();
-      if (nextTitle) {
-        setConversations((currentConversations) =>
-          currentConversations.map((conversation) =>
-            conversation.conversationId === event.data.conversationId
-              ? { ...conversation, title: nextTitle }
-              : conversation,
-          ),
-        );
-      }
-    }
-  }, [onGenerationResult]);
+  const applyDeltaMessages = useCallback(
+    (deltaMessages: EditorAgentMessage[]) => {
+      setMessages((currentMessages) => {
+        return [...currentMessages, ...deltaMessages];
+      });
+      requestCanvasRefreshForMessages(deltaMessages);
+    },
+    [requestCanvasRefreshForMessages],
+  );
 
   const ensureConversationForSend = useCallback(async () => {
     if (activeConversationId) {
@@ -529,88 +363,137 @@ export function useEditorAgentConversation({
       const text = rawText.trim();
       if (
         (!text && !attachments.length) ||
-        isStreaming ||
+        isWaiting ||
+        activeToolCallActionRef.current !== null ||
         isLoadingConversations ||
         isLoadingMessages
       ) {
         return;
       }
       const conversationId = await ensureConversationForSend();
-      const clientMessageId = createClientId('client-message');
-      const abortController = new AbortController();
-      activeStreamAbortControllerRef.current = abortController;
+      const clientMessageId = createEditorAgentClientMessageId();
       setErrorMessage(null);
-      setStage('thinking');
-      setIsStreaming(true);
+      setIsWaiting(true);
+      const optimisticMessage = createLocalUserMessage({
+        id: -1,
+        clientMessageId,
+        text,
+        attachments,
+      });
       setMessages((currentMessages) => [
         ...currentMessages,
-        createLocalUserMessage({
-          id: clientMessageId,
-          text,
-          attachments,
-        }),
+        optimisticMessage,
       ]);
 
       try {
-        await client.streamMessage(
+        const response = await client.sendMessage(
           conversationId,
           {
             clientMessageId,
             text,
             attachments,
           },
-          {
-            signal: abortController.signal,
-            onEvent: handleSseEvent,
-          },
+          {},
         );
-        setMessages((currentMessages) =>
-          markStreamingMessages(currentMessages, 'completed'),
+
+        setConversations((currentConversations) =>
+          upsertConversationSummary(
+            currentConversations,
+            response.conversation,
+          ),
         );
-      } catch (error) {
-        if (isAbortError(error) || abortController.signal.aborted) {
+        if (activeConversationIdRef.current !== conversationId) {
           return;
         }
+        if (response.errorMessage) {
+          setErrorMessage(response.errorMessage);
+        } else {
+          applyDeltaMessages(response.deltaMessages);
+        }
+      } catch (error) {
         const message =
           error instanceof Error ? error.message : '发送画布 Agent 消息失败';
-        setErrorMessage(message);
-        setStage('failed');
-        setMessages((currentMessages) => [
-          ...markStreamingMessages(currentMessages, 'failed'),
-          createAssistantMessage({
-            id: createClientId('agent-error'),
-            kind: 'error',
-            text: message,
-            status: 'failed',
-          }),
-        ]);
+        if (activeConversationIdRef.current === conversationId) {
+          setErrorMessage(message);
+          setMessages((currentMessages) =>
+            currentMessages.filter((message) => message !== optimisticMessage),
+          );
+        }
         throw error;
       } finally {
-        if (activeStreamAbortControllerRef.current === abortController) {
-          activeStreamAbortControllerRef.current = null;
-        }
-        setIsStreaming(false);
+        setIsWaiting(false);
       }
     },
     [
       client,
       ensureConversationForSend,
-      handleSseEvent,
+      applyDeltaMessages,
       isLoadingConversations,
       isLoadingMessages,
-      isStreaming,
+      isWaiting,
     ],
   );
 
-  const stopCurrentTurn = useCallback(() => {
-    activeStreamAbortControllerRef.current?.abort();
-    activeStreamAbortControllerRef.current = null;
-    setMessages((currentMessages) =>
-      markStreamingMessages(currentMessages, 'stopped'),
-    );
-    setStage('idle');
-    setIsStreaming(false);
-  }, []);
+  const resolveToolCall = useCallback(
+    async (messageId: number, action: EditorAgentToolCallAction) => {
+      const conversationId = activeConversationIdRef.current;
+      if (!conversationId || activeToolCallActionRef.current) {
+        return;
+      }
+
+      const nextAction = { messageId, action } as const;
+      activeToolCallActionRef.current = nextAction;
+      setToolCallAction(nextAction);
+      setErrorMessage(null);
+
+      try {
+        await (action === 'confirm'
+          ? client.confirmToolCall(conversationId, messageId)
+          : client.cancelToolCall(conversationId, messageId));
+
+        if (activeConversationIdRef.current !== conversationId) {
+          return;
+        }
+
+        const detail = await loadConversation(conversationId, {
+          showLoading: false,
+        });
+        const updatedMessage = detail.messages.find(
+          (message) => message.id === messageId,
+        );
+        if (action === 'confirm' && updatedMessage?.toolCall?.externalJobId) {
+          onConfirmSent?.();
+        }
+      } catch (error) {
+        if (activeConversationIdRef.current === conversationId) {
+          setErrorMessage(
+            error instanceof Error
+              ? error.message
+              : action === 'confirm'
+                ? '确认画布 Agent 操作失败'
+                : '取消画布 Agent 操作失败',
+          );
+        }
+        throw error;
+      } finally {
+        if (activeToolCallActionRef.current === nextAction) {
+          activeToolCallActionRef.current = null;
+          setToolCallAction(null);
+        }
+      }
+    },
+    [client, loadConversation, onConfirmSent],
+  );
+
+  const confirmToolCall = useCallback(
+    (messageId: number) => resolveToolCall(messageId, 'confirm'),
+    [resolveToolCall],
+  );
+
+  const cancelToolCall = useCallback(
+    (messageId: number) => resolveToolCall(messageId, 'cancel'),
+    [resolveToolCall],
+  );
 
   const deleteActiveConversation = useCallback(async () => {
     if (!activeConversationId) {
@@ -631,9 +514,9 @@ export function useEditorAgentConversation({
         await loadConversation(nextConversation.conversationId);
         return;
       }
+      activeConversationIdRef.current = null;
       setActiveConversationId(null);
       setMessages([]);
-      setStage('idle');
     } catch (error) {
       setErrorMessage(
         error instanceof Error ? error.message : '删除画布 Agent 会话失败',
@@ -649,17 +532,20 @@ export function useEditorAgentConversation({
     activeConversation,
     activeConversationId,
     messages,
-    stage,
     isLoadingConversations,
     isLoadingMessages,
     isCreatingConversation,
     isDeletingConversation,
-    isStreaming,
+    isWaiting,
+    toolCallAction,
+    isToolCallActionPending: toolCallAction !== null,
     errorMessage,
     createConversation,
     selectConversation,
+    refreshActiveConversation,
     sendMessage,
-    stopCurrentTurn,
+    confirmToolCall,
+    cancelToolCall,
     deleteActiveConversation,
   };
 }
diff --git a/src/components/image-editor/EditorAgentConversationPanelView.test.tsx b/src/components/image-editor/EditorAgentConversationPanelView.test.tsx
deleted file mode 100644
index 30bf11244..000000000
--- a/src/components/image-editor/EditorAgentConversationPanelView.test.tsx
+++ /dev/null
@@ -1,528 +0,0 @@
-/* @vitest-environment jsdom */
-
-import {
-  act,
-  fireEvent,
-  render,
-  screen,
-  waitFor,
-  within,
-} from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { EditorAgentConversationPanelView } from './EditorAgentConversationPanelView';
-import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
-import type { EditorAgentConversationClient } from './useEditorAgentConversation';
-
-const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
-const uploadEditorMediaAssetFileMock = vi.hoisted(() => vi.fn());
-const probeImageFileDimensionsMock = vi.hoisted(() => vi.fn());
-
-vi.mock('../../services/image-editor/editorProjectClient', async () => {
-  const actual = await vi.importActual<
-    typeof import('../../services/image-editor/editorProjectClient')
-  >('../../services/image-editor/editorProjectClient');
-  return {
-    ...actual,
-    createEditorProjectResource: createEditorProjectResourceMock,
-  };
-});
-
-vi.mock('../../services/image-editor/editorMediaAssetUploadClient', () => ({
-  uploadEditorMediaAssetFile: uploadEditorMediaAssetFileMock,
-}));
-
-vi.mock('./ImageCanvasFileModel', async () => {
-  const actual = await vi.importActual<typeof import('./ImageCanvasFileModel')>(
-    './ImageCanvasFileModel',
-  );
-  return {
-    ...actual,
-    probeImageFileDimensions: probeImageFileDimensionsMock,
-  };
-});
-
-function createClient(): EditorAgentConversationClient {
-  return {
-    listConversations: vi.fn().mockResolvedValue([
-      {
-        conversationId: 'conversation-1',
-        projectId: 'project-1',
-        title: '角色参考',
-        createdAt: '2026-07-03T00:00:00.000Z',
-        updatedAt: '2026-07-03T00:00:00.000Z',
-      },
-    ]),
-    createConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-2',
-      projectId: 'project-1',
-      title: '新对话',
-      messages: [],
-      createdAt: '2026-07-03T00:01:00.000Z',
-      updatedAt: '2026-07-03T00:01:00.000Z',
-    }),
-    getConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-1',
-      projectId: 'project-1',
-      title: '角色参考',
-      messages: [
-        {
-          id: 'assistant-old',
-          role: 'assistant',
-          kind: 'chat',
-          text: '已经看到画布内容',
-          attachments: [],
-          generations: [],
-          status: 'completed',
-          createdAt: '2026-07-03T00:00:10.000Z',
-        },
-      ],
-      createdAt: '2026-07-03T00:00:00.000Z',
-      updatedAt: '2026-07-03T00:00:10.000Z',
-    }),
-    deleteConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-1',
-      projectId: 'project-1',
-      title: '角色参考',
-      messages: [],
-      createdAt: '2026-07-03T00:00:00.000Z',
-      updatedAt: '2026-07-03T00:00:00.000Z',
-    }),
-    streamMessage: vi
-      .fn()
-      .mockImplementation(async (_conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'stage',
-          data: { conversationId: _conversationId, stage: 'responding' },
-        });
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId: _conversationId,
-            messageId: 'assistant-stream',
-            role: 'assistant',
-            kind: 'chat',
-            textDelta: '收到，我会参考这张图。',
-          },
-        });
-        options.onEvent?.({
-          event: 'done',
-          data: { conversationId: _conversationId, title: null },
-        });
-      }),
-  };
-}
-
-describe('EditorAgentConversationPanelView', () => {
-  beforeEach(() => {
-    useImageCanvasContextStore.getState().setProjectId('project-1');
-    uploadEditorMediaAssetFileMock.mockReset();
-    uploadEditorMediaAssetFileMock.mockResolvedValue({
-      src: '/generated/pasted.png',
-      objectKey: 'generated-character-drafts/editor/agent-paste/image/pasted.png',
-      assetObjectId: 'asset-object-pasted',
-      legacyPublicPath: '/generated/pasted.png',
-    });
-    probeImageFileDimensionsMock.mockReset();
-    probeImageFileDimensionsMock.mockResolvedValue({ width: 320, height: 240 });
-    createEditorProjectResourceMock.mockReset();
-    createEditorProjectResourceMock.mockResolvedValue({
-      resourceId: 'resource-pasted',
-      imageSrc: '/generated/pasted.png',
-      objectKey: 'generated-character-drafts/editor/agent-paste/image/pasted.png',
-      label: '粘贴图片',
-      width: 320,
-      height: 240,
-    });
-  });
-
-  it('manages conversations, attachments and message sending inside the panel', async () => {
-    const client = createClient();
-
-    render(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-        layers={[
-          {
-            id: 'layer-1',
-            resourceId: 'resource-1',
-            title: '角色图层',
-            src: '/generated/role.png',
-            x: 0,
-            y: 0,
-            width: 512,
-            height: 512,
-            originalWidth: 512,
-            originalHeight: 512,
-            zIndex: 1,
-            sourceType: 'generated',
-          },
-          {
-            id: 'layer-local-only',
-            resourceId: '',
-            title: '未入库图层',
-            src: '/local-only.png',
-            x: 0,
-            y: 0,
-            width: 256,
-            height: 256,
-            originalWidth: 256,
-            originalHeight: 256,
-            zIndex: 2,
-            sourceType: 'uploaded',
-          },
-        ]}
-        assets={[
-          {
-            id: 'asset-1',
-            label: '素材库角色',
-            src: '/assets/role.png',
-            width: 512,
-            height: 512,
-            folderId: 'project',
-            sourceKind: 'uploaded',
-            sourceType: 'uploaded',
-            persisted: true,
-          },
-        ]}
-      />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: '新建对话' }));
-    await waitFor(() => {
-      expect(client.createConversation).toHaveBeenCalledWith('project-1', {});
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: '添加附件' }));
-    const attachmentDialog = screen.getByRole('dialog', {
-      name: '选择图片附件',
-    });
-    expect(
-      within(attachmentDialog).queryByRole('checkbox', {
-        name: '选择画布图片 未入库图层',
-      }),
-    ).toBeNull();
-    fireEvent.click(
-      within(attachmentDialog).getByRole('checkbox', {
-        name: '选择画布图片 角色图层',
-      }),
-    );
-    fireEvent.click(
-      within(attachmentDialog).getByRole('button', { name: '应用' }),
-    );
-    expect(screen.getByText('角色图层')).toBeTruthy();
-
-    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
-      target: { value: '参考附件做像素风' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: '发送' }));
-
-    await waitFor(() => {
-      expect(screen.getByText('收到，我会参考这张图。')).toBeTruthy();
-    });
-    expect(client.streamMessage).toHaveBeenCalledWith(
-      'conversation-2',
-      expect.objectContaining({
-        text: '参考附件做像素风',
-        attachments: [
-          expect.objectContaining({
-            source: 'canvas_resource',
-            referenceId: 'resource-1',
-          }),
-        ],
-      }),
-      expect.any(Object),
-    );
-  });
-
-  it('uploads pasted images as canvas attachments before sending', async () => {
-    const client = createClient();
-
-    render(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-      />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    const pastedImage = new File(['pasted-image'], 'pasted.png', {
-      type: 'image/png',
-    });
-    const input = screen.getByLabelText('发送给画布 Agent');
-    fireEvent.paste(input, {
-      clipboardData: {
-        files: [pastedImage],
-      },
-    });
-
-    await waitFor(() => {
-      expect(uploadEditorMediaAssetFileMock).toHaveBeenCalledWith(
-        pastedImage,
-        'image',
-        expect.objectContaining({
-          entityId: 'project-1',
-          metadata: { source: 'agent-input-paste' },
-        }),
-      );
-    });
-    expect(probeImageFileDimensionsMock).toHaveBeenCalledWith(pastedImage);
-    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
-      'project-1',
-      expect.objectContaining({
-        imageSrc: '/generated/pasted.png',
-        objectKey: 'generated-character-drafts/editor/agent-paste/image/pasted.png',
-        assetObjectId: 'asset-object-pasted',
-        width: 320,
-        height: 240,
-        sourceType: 'uploaded',
-      }),
-    );
-    await waitFor(() => {
-      expect(screen.getByText('粘贴图片')).toBeTruthy();
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: '发送' }));
-
-    await waitFor(() => {
-      expect(client.streamMessage).toHaveBeenCalledWith(
-        'conversation-1',
-        expect.objectContaining({
-          text: '',
-          attachments: [
-            expect.objectContaining({
-              source: 'canvas_resource',
-              referenceId: 'resource-pasted',
-              imageSrc: '/generated/pasted.png',
-              width: 320,
-              height: 240,
-            }),
-          ],
-        }),
-        expect.any(Object),
-      );
-    });
-  });
-
-  it('sends selected attachments even when the text input is empty', async () => {
-    const client = createClient();
-
-    render(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-        layers={[
-          {
-            id: 'layer-1',
-            resourceId: 'resource-1',
-            title: '角色图层',
-            src: '/generated/role.png',
-            x: 0,
-            y: 0,
-            width: 512,
-            height: 512,
-            originalWidth: 512,
-            originalHeight: 512,
-            zIndex: 1,
-            sourceType: 'generated',
-          },
-        ]}
-      />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: '添加附件' }));
-    const attachmentDialog = screen.getByRole('dialog', {
-      name: '选择图片附件',
-    });
-    fireEvent.click(
-      within(attachmentDialog).getByRole('checkbox', {
-        name: '选择画布图片 角色图层',
-      }),
-    );
-    fireEvent.click(
-      within(attachmentDialog).getByRole('button', { name: '应用' }),
-    );
-    fireEvent.click(screen.getByRole('button', { name: '发送' }));
-
-    await waitFor(() => {
-      expect(client.streamMessage).toHaveBeenCalledWith(
-        'conversation-1',
-        expect.objectContaining({
-          text: '',
-          attachments: [
-            expect.objectContaining({
-              source: 'canvas_resource',
-              referenceId: 'resource-1',
-            }),
-          ],
-        }),
-        expect.any(Object),
-      );
-    });
-  });
-
-  it('keeps streamed reply and generating state when the panel is collapsed and reopened', async () => {
-    const client = createClient();
-    let finishStream = () => {};
-    vi.mocked(client.streamMessage).mockImplementation(
-      async (conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId,
-            messageId: 'assistant-stream',
-            role: 'assistant',
-            kind: 'chat',
-            textDelta: '我来生成图片。',
-          },
-        });
-        options.onEvent?.({
-          event: 'stage',
-          data: { conversationId, stage: 'generating' },
-        });
-        options.onEvent?.({
-          event: 'tool_started',
-          data: {
-            conversationId,
-            messageId: 'assistant-stream',
-            toolCallId: 'tool-call-generating',
-            toolName: 'generate_image',
-            taskId: 'task-generating',
-            model: 'gpt-image-2',
-          },
-        });
-        await new Promise<void>((resolve) => {
-          finishStream = resolve;
-        });
-      },
-    );
-
-    const { rerender } = render(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-      />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    fireEvent.change(screen.getByLabelText('发送给画布 Agent'), {
-      target: { value: '生成一张图片' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: '发送' }));
-
-    await waitFor(() => {
-      expect(screen.getByText('我来生成图片。')).toBeTruthy();
-    });
-    expect(screen.getByText('生成中')).toBeTruthy();
-    expect(screen.getByRole('button', { name: '停止' })).toBeTruthy();
-
-    rerender(
-      <EditorAgentConversationPanelView
-        open={false}
-        onToggleOpen={vi.fn()}
-        client={client}
-      />,
-    );
-    expect(screen.getByRole('button', { name: '打开画布 Agent' })).toBeTruthy();
-
-    rerender(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-      />,
-    );
-
-    expect(screen.getByText('我来生成图片。')).toBeTruthy();
-    expect(screen.getByText('生成中')).toBeTruthy();
-    expect(screen.getByRole('button', { name: '停止' })).toBeTruthy();
-
-    await act(async () => {
-      finishStream();
-    });
-  });
-
-  it('keeps wheel scrolling inside the message history and input', async () => {
-    const client = createClient();
-    const parentWheel = vi.fn();
-
-    render(
-      <div onWheel={parentWheel}>
-        <EditorAgentConversationPanelView
-          open
-          onToggleOpen={vi.fn()}
-          client={client}
-        />
-      </div>,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    const messageWheel = new WheelEvent('wheel', {
-      bubbles: true,
-      cancelable: true,
-      deltaY: 120,
-    });
-    fireEvent(
-      screen.getByRole('log', { name: '画布 Agent 消息流' }),
-      messageWheel,
-    );
-    expect(parentWheel).not.toHaveBeenCalled();
-    expect(messageWheel.defaultPrevented).toBe(false);
-
-    const inputWheel = new WheelEvent('wheel', {
-      bubbles: true,
-      cancelable: true,
-      deltaY: 120,
-    });
-    fireEvent(screen.getByLabelText('发送给画布 Agent'), inputWheel);
-    expect(parentWheel).not.toHaveBeenCalled();
-    expect(inputWheel.defaultPrevented).toBe(false);
-  });
-
-  it('confirms conversation deletion from an independent dialog', async () => {
-    const client = createClient();
-    render(
-      <EditorAgentConversationPanelView
-        open
-        onToggleOpen={vi.fn()}
-        client={client}
-      />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('已经看到画布内容')).toBeTruthy();
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: '删除当前对话' }));
-    const confirmDialog = screen.getByRole('dialog', { name: '删除对话' });
-    fireEvent.click(
-      within(confirmDialog).getByRole('button', { name: '确认删除' }),
-    );
-
-    await waitFor(() => {
-      expect(client.deleteConversation).toHaveBeenCalledWith('conversation-1');
-    });
-  });
-});
diff --git a/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx b/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx
index 595cdce12..5fb1720a7 100644
--- a/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx
@@ -11,24 +11,24 @@ import {
 import type { Dispatch, SetStateAction } from 'react';
 
 import { PlatformTextField } from '../common/PlatformTextField';
-import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type {
+  GroupedEditorAssetFolder,
+  UploadFilesOptions,
+  UploadRequestOptions,
+} from './ImageCanvasAssetLibraryPanelView';
+import { ImageCanvasAssetRowView } from './ImageCanvasAssetRowView';
 import {
   ASSET_DRAG_MIME_TYPE,
   getDraggedAssetId,
   hasDataTransferType,
 } from './ImageCanvasEditorModel';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import type {
   AssetPointerDragState,
   EditorAsset,
   EditorAssetFolder,
   UploadTarget,
 } from './ImageCanvasEditorTypes';
-import { ImageCanvasAssetRowView } from './ImageCanvasAssetRowView';
-import type {
-  GroupedEditorAssetFolder,
-  UploadFilesOptions,
-  UploadRequestOptions,
-} from './ImageCanvasAssetLibraryPanelView';
 
 type ImageCanvasAssetFolderSectionViewProps = {
   folder: GroupedEditorAssetFolder;
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
index 826ee4ba7..6675d690c 100644
--- a/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
+++ b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
@@ -1,9 +1,5 @@
 import { describe, expect, it } from 'vitest';
 
-import type {
-  EditorAsset,
-  EditorAssetFolder,
-} from './ImageCanvasEditorTypes';
 import {
   areAllSelectableAssetsSelected,
   createAssetMarqueeFromPointer,
@@ -13,24 +9,28 @@ import {
   filterGroupedAssetsBySearch,
   getSelectableAssets,
   groupAssetsByFolder,
-  moveAssetToFolderLocally,
   moveAssetMarqueeToPointer,
+  moveAssetToFolderLocally,
   removeAssetById,
   removeSelectedAssets,
   renameAssetById,
   renameAssetFolderById,
   replaceLocalAssetFolder,
   resolveAllAssetSelection,
-  resolveAssetShowcaseSubmissionState,
   resolveAssetFolderIdFromPoint,
+  resolveAssetShowcaseSubmissionState,
   resolveDefaultAssetFolder,
-  resolvePreferredAssetUploadFolder,
   resolvePinnedAssetMoveFolderId,
+  resolvePreferredAssetUploadFolder,
   resolveUploadAssetFolder,
   selectUploadedAssetsInRect,
   toggleAssetFolderCollapsed,
   toggleAssetSelection,
 } from './ImageCanvasAssetLibraryModel';
+import type {
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
 
 function createFolder(
   overrides: Partial<EditorAssetFolder> = {},
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx b/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx
index 0209b88d9..1b5bdab8d 100644
--- a/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx
@@ -16,8 +16,8 @@ import type {
 import { PlatformActionButton } from '../common/PlatformActionButton';
 import { PlatformBatchActionToolbar } from '../common/PlatformBatchActionToolbar';
 import { PlatformTextField } from '../common/PlatformTextField';
-import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import { ImageCanvasAssetFolderSectionView } from './ImageCanvasAssetFolderSectionView';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import type {
   AssetMarqueeState,
   AssetPointerDragState,
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
index 10c12ac0b..becd864a2 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
@@ -4,8 +4,8 @@ import { fireEvent, render, screen } from '@testing-library/react';
 import type { ReactNode } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import type { EditorAsset } from './ImageCanvasEditorTypes';
 import { ImageCanvasAssetRowView } from './ImageCanvasAssetRowView';
+import type { EditorAsset } from './ImageCanvasEditorTypes';
 
 const useResolvedAssetReadUrlMock = vi.hoisted(() => vi.fn());
 
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.tsx b/src/components/image-editor/ImageCanvasAssetRowView.tsx
index ebe252ecc..9f27b5d2f 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.tsx
@@ -1,21 +1,21 @@
 import { Check, Download, Pencil, Video, X } from 'lucide-react';
-import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
 import { PlatformTextField } from '../common/PlatformTextField';
+import { resolveAssetShowcaseSubmissionState } from './ImageCanvasAssetLibraryModel';
 import type { UploadFilesOptions } from './ImageCanvasAssetLibraryPanelView';
-import {
-  EditorIconButton,
-  SidebarMediaItem,
-} from './ImageCanvasEditorPrimitives';
 import {
   ASSET_DRAG_MIME_TYPE,
   clamp,
   getDraggedAssetId,
   hasDataTransferType,
 } from './ImageCanvasEditorModel';
-import { resolveAssetShowcaseSubmissionState } from './ImageCanvasAssetLibraryModel';
+import {
+  EditorIconButton,
+  SidebarMediaItem,
+} from './ImageCanvasEditorPrimitives';
 import type {
   AssetPointerDragState,
   EditorAsset,
diff --git a/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx
index ce63f14c6..8f1eef330 100644
--- a/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx
+++ b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx
@@ -19,8 +19,8 @@ import type {
   UploadTarget,
 } from './ImageCanvasEditorTypes';
 import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
-import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import { calculateEditorImageGenerationPrice } from './ImageCanvasGenerationModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
 
 type ReferenceLabelFormatter = (
diff --git a/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx b/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx
index aab1ed80f..3b83c5a1b 100644
--- a/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx
@@ -1,9 +1,9 @@
 /* @vitest-environment jsdom */
 
-import { createRef, type RefObject } from 'react';
-import { describe, expect, it, vi } from 'vitest';
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import { createRef, type RefObject } from 'react';
+import { describe, expect, it, vi } from 'vitest';
 
 import { ImageCanvasBottomToolbarView } from './ImageCanvasBottomToolbarView';
 
diff --git a/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx
index deca396d4..84e0d5b48 100644
--- a/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx
+++ b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx
@@ -4,8 +4,8 @@ import { fireEvent, render, screen } from '@testing-library/react';
 import { useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
-import type { CanvasLayer, CharacterAnimationPanelState } from './ImageCanvasEditorTypes';
 import { ImageCanvasCharacterAnimationPanelView } from './ImageCanvasCharacterAnimationPanelView';
+import type { CanvasLayer, CharacterAnimationPanelState } from './ImageCanvasEditorTypes';
 
 
 function createSourceLayer(): CanvasLayer {
diff --git a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx
index e7a60f11a..04b89fbb5 100644
--- a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx
+++ b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx
@@ -4,12 +4,12 @@ import { fireEvent, render, screen } from '@testing-library/react';
 import { createRef, useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
+import { ImageCanvasCharacterGenerationComposerView } from './ImageCanvasCharacterGenerationComposerView';
 import type {
   GenerateDialogState,
   SpecGenerationType,
   UploadTarget,
 } from './ImageCanvasEditorTypes';
-import { ImageCanvasCharacterGenerationComposerView } from './ImageCanvasCharacterGenerationComposerView';
 import { IMAGE_MODEL_GPT_IMAGE_2 } from './ImageCanvasGenerationModel';
 
 function createDialog(
diff --git a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx
index 2ddc374dd..a46565b7b 100644
--- a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx
+++ b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx
@@ -13,7 +13,6 @@ import {
 } from '../common/PlatformFloatingMenu';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformTextField } from '../common/PlatformTextField';
-import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import type {
   CharacterReferenceImage,
   GenerateDialogState,
@@ -22,6 +21,7 @@ import type {
 } from './ImageCanvasEditorTypes';
 import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
 import { calculateEditorImageGenerationPrice } from './ImageCanvasGenerationModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
 
 type ImageCanvasCharacterGenerationComposerViewProps = {
diff --git a/src/components/image-editor/ImageCanvasCropExpandModel.ts b/src/components/image-editor/ImageCanvasCropExpandModel.ts
index 6422a1a60..a591ffaed 100644
--- a/src/components/image-editor/ImageCanvasCropExpandModel.ts
+++ b/src/components/image-editor/ImageCanvasCropExpandModel.ts
@@ -1,7 +1,7 @@
 import type {
   CropExpandPanelState,
-  CropExpandResizeHandle,
   CropExpandRatioValue,
+  CropExpandResizeHandle,
 } from './ImageCanvasEditorTypes';
 
 export const CROP_EXPAND_MIN_FRAME_SIZE = 16;
diff --git a/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx b/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx
index db0763e54..381706120 100644
--- a/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx
@@ -4,8 +4,8 @@ import { fireEvent, render, screen } from '@testing-library/react';
 import { useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
-import type { GenerateDialogState } from './ImageCanvasEditorTypes';
 import { ImageCanvasEditGenerationModalView } from './ImageCanvasEditGenerationModalView';
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
 
 function createDialog(
   patch: Partial<GenerateDialogState> = {},
diff --git a/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx b/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx
index edc042dff..7ebb37464 100644
--- a/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx
+++ b/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx
@@ -1,11 +1,11 @@
 import { type Dispatch, type SetStateAction } from 'react';
 
 import { UnifiedModal } from '../common/UnifiedModal';
+import { ImageCanvasBasicGenerationComposerView } from './ImageCanvasBasicGenerationComposerView';
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
 import {
   calculateEditorImageGenerationPrice,
 } from './ImageCanvasGenerationModel';
-import { ImageCanvasBasicGenerationComposerView } from './ImageCanvasBasicGenerationComposerView';
-import type { GenerateDialogState } from './ImageCanvasEditorTypes';
 
 type ImageCanvasEditGenerationModalViewProps = {
   dialog: GenerateDialogState | null;
diff --git a/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx
index 5c0f70c98..54e69454d 100644
--- a/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx
@@ -14,11 +14,11 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   ApiClientError,
   AuthUiContext,
-  ImageCanvasEditorView,
   createAuthValue,
   createDataTransferStub,
   createDeferred,
   dispatchPointerEvent,
+  ImageCanvasEditorView,
   setupImageCanvasEditorViewTestLifecycle,
 } from './ImageCanvasEditorView.test-utils';
 
@@ -830,6 +830,12 @@ describe('ImageCanvasEditorView asset library integration', () => {
     expect(screen.getByAltText('画布图片：账号素材A')).toBeTruthy();
     expect(screen.getByAltText('画布图片：账号素材B')).toBeTruthy();
 
+    fireEvent.keyDown(window, { key: 'ArrowRight', code: 'ArrowRight' });
+    expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(
+      'disabled',
+      false,
+    );
+
     await user.click(screen.getByRole('button', { name: '素材选择模式' }));
     await user.click(
       within(screen.getByRole('toolbar', { name: '素材批量操作' })).getByRole(
@@ -857,6 +863,9 @@ describe('ImageCanvasEditorView asset library integration', () => {
     });
     expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-a');
     expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-b');
+    fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
+    expect(screen.queryByAltText('画布图片：账号素材A')).toBeNull();
+    expect(screen.queryByAltText('画布图片：账号素材B')).toBeNull();
   });
 
   it('saves the canvas layout after deleting an asset linked by source resource id', async () => {
diff --git a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
index 7a75928b8..8bf6dafd2 100644
--- a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
@@ -1236,6 +1236,11 @@ describe('ImageCanvasEditorView generation integration', () => {
       {
         open: () => {
           fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+          selectGenerationDimensions(
+            screen.getByRole('dialog', { name: '生成图片' }),
+            '1:1',
+            '2K',
+          );
           fireEvent.change(screen.getByLabelText('生成提示词'), {
             target: { value: '生成中的普通图片' },
           });
@@ -1243,6 +1248,7 @@ describe('ImageCanvasEditorView generation integration', () => {
         },
         dialogName: '生成图片',
         frameLabel: '图像生成占位图',
+        expectedFrameSize: { width: 2048, height: 2048 },
       },
       {
         open: () => {
@@ -1268,10 +1274,16 @@ describe('ImageCanvasEditorView generation integration', () => {
         },
         dialogName: '生成规范',
         frameLabel: '规范生成占位图',
+        expectedFrameSize: { width: 2048, height: 1152 },
       },
       {
         open: () => {
           fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+          selectGenerationDimensions(
+            screen.getByRole('dialog', { name: '生成角色形象' }),
+            '2:3',
+            '2K',
+          );
           fireEvent.change(screen.getByLabelText('角色设定'), {
             target: { value: '生成中的角色形象' },
           });
@@ -1279,6 +1291,7 @@ describe('ImageCanvasEditorView generation integration', () => {
         },
         dialogName: '生成角色形象',
         frameLabel: '角色生成占位图',
+        expectedFrameSize: { width: 1365, height: 2048 },
       },
     ] as const;
 
@@ -1298,6 +1311,12 @@ describe('ImageCanvasEditorView generation integration', () => {
       expect(frame.className).toContain(
         'image-canvas-editor__generation-frame--generating',
       );
+      expect((frame as HTMLElement).style.width).toBe(
+        `${testCase.expectedFrameSize.width}px`,
+      );
+      expect((frame as HTMLElement).style.height).toBe(
+        `${testCase.expectedFrameSize.height}px`,
+      );
       expect(within(frame).getByRole('status').textContent).toContain('生成中');
 
       unmount();
@@ -2938,7 +2957,7 @@ describe('ImageCanvasEditorView generation integration', () => {
       status: 'completed',
       progress: 100,
       phaseDetail: '生成已完成。',
-      warning: '连通域数量不足',
+      warning: '图集已生成，但自动拆分未完成：连通域数量不足',
       completedAt: '2026-06-21T00:01:00.000Z',
       updatedAt: '2026-06-21T00:01:00.000Z',
       updatedAtMicros: 2,
@@ -3332,6 +3351,17 @@ describe('ImageCanvasEditorView generation integration', () => {
     expect(screen.getByText('1/48')).toBeTruthy();
     expect(screen.queryByLabelText('画布视频：角色动作')).toBeNull();
     expect(screen.getByText('动作')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '选择角色动作' }));
+    fireEvent.click(screen.getByRole('button', { name: '改造' }));
+
+    const remodelPanel = screen.getByRole('dialog', {
+      name: '角色动画生成面板',
+    });
+    expect(
+      (within(remodelPanel).getByLabelText('动画描述') as HTMLTextAreaElement)
+        .value,
+    ).toBe(precisePrompt);
   });
 
   it('extracts UI design assets from the floating toolbar and keeps the spritesheet on canvas', async () => {
diff --git a/src/components/image-editor/ImageCanvasEditorModel.test.ts b/src/components/image-editor/ImageCanvasEditorModel.test.ts
index d5dce4279..b04344799 100644
--- a/src/components/image-editor/ImageCanvasEditorModel.test.ts
+++ b/src/components/image-editor/ImageCanvasEditorModel.test.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+  CANVAS_WORLD_ORIGIN,
   canvasDisplayScaleToViewportScale,
   canvasDisplayViewportToViewport,
-  CANVAS_WORLD_ORIGIN,
   createLayerFromAsset,
   DEFAULT_CANVAS_BACKGROUND_COLOR,
   formatCanvasDisplayScalePercent,
diff --git a/src/components/image-editor/ImageCanvasEditorModel.ts b/src/components/image-editor/ImageCanvasEditorModel.ts
index 503b318d6..f2ce226a8 100644
--- a/src/components/image-editor/ImageCanvasEditorModel.ts
+++ b/src/components/image-editor/ImageCanvasEditorModel.ts
@@ -9,8 +9,8 @@ import type {
   CanvasGenerationDialogState,
   CanvasGenerationInputs,
   CanvasLayer,
-  CanvasSnapItem,
   CanvasMediaType,
+  CanvasSnapItem,
   CanvasViewport,
   CharacterReferenceImage,
   EditorAsset,
diff --git a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
index 88c14ae62..23f387937 100644
--- a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
@@ -163,6 +163,7 @@ function createStageProps(): ImageCanvasStageViewProps {
     contextShouldUnlockLayer: false,
     canUndo: false,
     canRedo: false,
+    historyFeedback: null,
     isZoomMenuOpen: false,
     isBackgroundSettingsOpen: false,
     activeSidebarPanel: null,
diff --git a/src/components/image-editor/ImageCanvasEditorTypes.ts b/src/components/image-editor/ImageCanvasEditorTypes.ts
index 429a7d172..f6d0e73f2 100644
--- a/src/components/image-editor/ImageCanvasEditorTypes.ts
+++ b/src/components/image-editor/ImageCanvasEditorTypes.ts
@@ -274,6 +274,63 @@ export type CanvasHistorySnapshot = {
   selectedLayerIds: string[];
 };
 
+export type CanvasHistoryActionType =
+  | 'move-image'
+  | 'move-generation-result'
+  | 'delete-image'
+  | 'delete-generation-result'
+  | 'cut-image'
+  | 'paste-image'
+  | 'duplicate-image'
+  | 'add-image'
+  | 'upload-image'
+  | 'generate-image'
+  | 'expand-image'
+  | 'remove-background'
+  | 'split-atlas'
+  | 'replace-image'
+  | 'show-image'
+  | 'hide-image'
+  | 'change-layer-order'
+  | 'group-images'
+  | 'ungroup-images'
+  | 'lock-image'
+  | 'unlock-image'
+  | 'flip-image'
+  | 'change-asset-kind'
+  | 'change-viewport';
+
+export type CanvasHistoryAction = {
+  type: CanvasHistoryActionType;
+  count?: number;
+};
+
+export type CanvasHistoryEntry = {
+  snapshot: CanvasHistorySnapshot;
+  action: CanvasHistoryAction;
+  createdAt: number;
+};
+
+export type CanvasHistoryApplyResult =
+  | {
+      status: 'success';
+      action: CanvasHistoryAction;
+    }
+  | {
+      status: 'blocked';
+      action: CanvasHistoryAction;
+      reason: 'content-may-disappear';
+    }
+  | {
+      status: 'empty';
+    };
+
+export type CanvasHistoryFeedback = {
+  id: number;
+  tone: 'neutral' | 'warning';
+  text: string;
+};
+
 export type CanvasClipboard = {
   layers: CanvasLayer[];
   mode: 'copy' | 'cut';
diff --git a/src/components/image-editor/ImageCanvasEditorView.test-utils.ts b/src/components/image-editor/ImageCanvasEditorView.test-utils.ts
index 3fc679b33..7fe6f64c8 100644
--- a/src/components/image-editor/ImageCanvasEditorView.test-utils.ts
+++ b/src/components/image-editor/ImageCanvasEditorView.test-utils.ts
@@ -1,6 +1,6 @@
+import { fireEvent } from '@testing-library/react';
 import JSZip from 'jszip';
 import type { ContextType } from 'react';
-import { fireEvent } from '@testing-library/react';
 import { afterEach, beforeEach, expect, type Mock, vi } from 'vitest';
 
 import { ApiClientError } from '../../services/apiClient';
@@ -232,6 +232,7 @@ export function setupImageCanvasEditorViewTestLifecycle({
   saveEditorProjectLayoutMock,
 }: ImageCanvasEditorViewServiceMocks) {
   beforeEach(() => {
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(null);
     loadOrCreateRecentEditorProjectMock.mockImplementation(() =>
       immediateAsync({
         projectId: 'editor-project-default',
diff --git a/src/components/image-editor/ImageCanvasEditorView.test.tsx b/src/components/image-editor/ImageCanvasEditorView.test.tsx
index 9ac688e74..a1f7704f9 100644
--- a/src/components/image-editor/ImageCanvasEditorView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.test.tsx
@@ -12,19 +12,21 @@ import userEvent from '@testing-library/user-event';
 import JSZip from 'jszip';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import type { EditorProjectResourceSnapshot } from '../../services/image-editor/editorProjectClient';
+import type { EditorAgentConversationClient } from './EditorAgentConversation/useEditorAgentConversation';
 import {
   ApiClientError,
   AuthUiContext,
   createAuthValue,
-  defaultEditorAssetLibraryAssets,
+  createDeferred,
   defaultEditorProjectLayers,
   defaultEditorProjectResources,
   dispatchPointerEvent,
   ImageCanvasEditorView,
+  immediateAsync,
   readZipText,
   setupImageCanvasEditorViewTestLifecycle,
 } from './ImageCanvasEditorView.test-utils';
-import type { EditorAgentConversationClient } from './useEditorAgentConversation';
 
 type EditorAgentListConversations =
   EditorAgentConversationClient['listConversations'];
@@ -34,7 +36,7 @@ type EditorAgentGetConversation =
   EditorAgentConversationClient['getConversation'];
 type EditorAgentDeleteConversation =
   EditorAgentConversationClient['deleteConversation'];
-type EditorAgentStreamMessage = EditorAgentConversationClient['streamMessage'];
+type EditorAgentStreamMessage = EditorAgentConversationClient['sendMessage'];
 type EditorAgentConversationSummary = Awaited<
   ReturnType<EditorAgentListConversations>
 >[number];
@@ -86,12 +88,23 @@ const deleteEditorAgentConversationMock = vi.hoisted(() =>
     updatedAt: '2026-07-03T00:00:00.000Z',
   })),
 );
-const streamEditorAgentMessageMock = vi.hoisted(() =>
+const sendEditorAgentMessageMock = vi.hoisted(() =>
   vi.fn<
     Parameters<EditorAgentStreamMessage>,
     ReturnType<EditorAgentStreamMessage>
-  >(async () => undefined),
+  >(async () => ({
+    conversation: {
+      conversationId: 'editor-agent-conv-test',
+      projectId: 'editor-project-default',
+      title: '画布 Agent',
+      updatedAt: '2026-07-03T00:00:00.000Z',
+    },
+    deltaMessages: [],
+    errorMessage: null,
+  })),
 );
+const confirmEditorAgentToolCallMock = vi.hoisted(() => vi.fn());
+const cancelEditorAgentToolCallMock = vi.hoisted(() => vi.fn());
 const generateEditorImageMock = vi.hoisted(() => vi.fn());
 const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
 const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
@@ -158,11 +171,13 @@ vi.mock('../../services/frontendRuntimeConfigService', () => ({
 }));
 
 vi.mock('../../services/image-editor/editorAgentClient', () => ({
+  cancelEditorAgentToolCall: cancelEditorAgentToolCallMock,
+  confirmEditorAgentToolCall: confirmEditorAgentToolCallMock,
   createEditorAgentConversation: createEditorAgentConversationMock,
   deleteEditorAgentConversation: deleteEditorAgentConversationMock,
   getEditorAgentConversation: getEditorAgentConversationMock,
   listEditorAgentConversations: listEditorAgentConversationsMock,
-  streamEditorAgentMessage: streamEditorAgentMessageMock,
+  sendEditorAgentMessage: sendEditorAgentMessageMock,
 }));
 
 function createEditorAgentConversationSummary(
@@ -172,45 +187,66 @@ function createEditorAgentConversationSummary(
     conversationId: 'editor-agent-conv-test',
     projectId: 'editor-project-default',
     title: '画布 Agent',
-    createdAt: '2026-07-03T00:00:00.000Z',
     updatedAt: '2026-07-03T00:00:00.000Z',
     ...overrides,
   };
 }
 
+function createEditImageToolCallDisplayArgs(prompt: string) {
+  return {
+    stringArgs: [{ name: 'prompt', label: '修改要求', value: prompt }],
+    imageArgs: [
+      {
+        name: 'object_image_id',
+        label: '目标图片',
+        refs: [
+          {
+            imageId: 'source-image',
+            imageSrc: '/source-image.png',
+            label: '源图片',
+          },
+        ],
+      },
+    ],
+    extras: { priceMudPoints: 3 },
+  };
+}
+
 function createEditorAgentDetailWithGeneration(
   resourceId: string,
 ): EditorAgentConversationDetail {
-  const summary = createEditorAgentConversationSummary();
+  const conversationSummary = createEditorAgentConversationSummary();
   return {
-    ...summary,
+    ...conversationSummary,
+    title: '画布 Agent',
+    createdAt: '2026-07-03T00:00:00.000Z',
     messages: [
       {
-        id: 'agent-message-result',
-        role: 'assistant',
-        kind: 'chat',
-        text: '生成完成',
+        id: 0,
+        role: 'system',
+        text: 'internal completed tool output',
         attachments: [],
-        generations: [
-          {
-            toolCallId: 'agent-tool-call-1',
-            toolName: 'generate_image',
-            taskId: 'task-agent-1',
-            status: 'completed',
-            model: 'gpt-image-2',
-            images: [
-              {
-                resourceId,
-                imageSrc: '/agent-result.png',
-                thumbnailSrc: '/agent-result-thumb.png',
-                width: 512,
-                height: 512,
-              },
-            ],
-            error: null,
+        toolCall: {
+          toolName: 'generate_image',
+          status: 'completed',
+          externalJobId: 'task-generation-1',
+          args: {},
+          displayArgs: {
+            stringArgs: [],
+            imageArgs: [],
+            extras: { priceMudPoints: 0 },
           },
-        ],
-        status: 'completed',
+          images: [
+            {
+              resourceId,
+              imageSrc: '/agent-result.png',
+              thumbnailSrc: '/agent-result-thumb.png',
+              width: 512,
+              height: 512,
+            },
+          ],
+          error: null,
+        },
         createdAt: '2026-07-03T00:00:01.000Z',
       },
     ],
@@ -265,24 +301,36 @@ describe('ImageCanvasEditorView', () => {
   });
 
   beforeEach(() => {
-    loadFrontendRuntimeConfigMock.mockResolvedValue({
-      imageEditorAgentSidebarEnabled: false,
-    });
+    loadFrontendRuntimeConfigMock.mockImplementation(() =>
+      immediateAsync({
+        imageEditorAgentSidebarEnabled: false,
+      }),
+    );
     listEditorAgentConversationsMock.mockResolvedValue([]);
     createEditorAgentConversationMock.mockResolvedValue({
       ...createEditorAgentConversationSummary({
         conversationId: 'editor-agent-conv-created',
       }),
+      title: '画布 Agent',
+      createdAt: '2026-07-03T00:00:00.000Z',
       messages: [],
     });
     getEditorAgentConversationMock.mockResolvedValue({
       ...createEditorAgentConversationSummary(),
+      title: '画布 Agent',
+      createdAt: '2026-07-03T00:00:00.000Z',
       messages: [],
     });
     deleteEditorAgentConversationMock.mockResolvedValue(
       createEditorAgentConversationSummary(),
     );
-    streamEditorAgentMessageMock.mockResolvedValue(undefined);
+    sendEditorAgentMessageMock.mockResolvedValue({
+      conversation: createEditorAgentConversationSummary(),
+      deltaMessages: [],
+      errorMessage: null,
+    });
+    confirmEditorAgentToolCallMock.mockReset();
+    cancelEditorAgentToolCallMock.mockReset();
     getPlatformProfileDashboardMock.mockResolvedValue({
       walletBalance: 1234,
       totalPlayTimeMs: 0,
@@ -336,7 +384,9 @@ describe('ImageCanvasEditorView', () => {
     createEditorAgentConversationMock.mockReset();
     getEditorAgentConversationMock.mockReset();
     deleteEditorAgentConversationMock.mockReset();
-    streamEditorAgentMessageMock.mockReset();
+    sendEditorAgentMessageMock.mockReset();
+    confirmEditorAgentToolCallMock.mockReset();
+    cancelEditorAgentToolCallMock.mockReset();
     getPlatformProfileDashboardMock.mockReset();
     getRpgProfileRechargeCenterMock.mockReset();
     getRpgProfileWalletLedgerMock.mockReset();
@@ -596,6 +646,7 @@ describe('ImageCanvasEditorView', () => {
   });
 
   it('opens the shared wallet breakdown and ledger from the canvas topbar', async () => {
+    const user = userEvent.setup();
     render(
       <AuthUiContext.Provider
         value={createAuthValue({
@@ -620,7 +671,7 @@ describe('ImageCanvasEditorView', () => {
       name: '泥点 1,234',
     });
 
-    fireEvent.click(walletButton);
+    await user.hover(walletButton);
 
     const details = await screen.findByRole('dialog', {
       name: '泥点账户详情',
@@ -629,7 +680,7 @@ describe('ImageCanvasEditorView', () => {
     expect(within(details).queryByText('限时泥点')).toBeNull();
     expect(within(details).getByText('每日免费泥点')).toBeTruthy();
 
-    fireEvent.click(within(details).getByRole('button', { name: '使用详情' }));
+    await user.click(within(details).getByRole('button', { name: '使用详情' }));
     expect(
       await screen.findByRole('dialog', { name: '泥点账单' }),
     ).toBeTruthy();
@@ -788,6 +839,53 @@ describe('ImageCanvasEditorView', () => {
     expect(resumedPrompt.value).not.toContain('2号红色圈选框');
   });
 
+  it('locks quick edit selection tools after the edit task starts', async () => {
+    editEditorImageMock.mockReturnValueOnce(new Promise(() => {}));
+    render(<ImageCanvasEditorView />);
+
+    const sourceLayer = (
+      await screen.findByAltText('画布图片：拼图素材')
+    ).closest('button')!;
+    dispatchPointerEvent(sourceLayer, 'pointerdown', {
+      button: 0,
+      pointerId: 74,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑' }));
+
+    const quickEditDialog = screen.getByRole('dialog', {
+      name: '快速编辑图片',
+    });
+    fireEvent.change(within(quickEditDialog).getByLabelText('快速编辑提示词'), {
+      target: { value: '快速修图' },
+    });
+    fireEvent.click(
+      within(
+        screen.getByRole('toolbar', { name: '快速编辑框选工具' }),
+      ).getByRole('button', { name: '矩形框选' }),
+    );
+
+    fireEvent.click(
+      within(quickEditDialog).getByRole('button', { name: '修改' }),
+    );
+
+    await waitFor(() => {
+      expect(editEditorImageMock).toHaveBeenCalledTimes(1);
+    });
+    expect(
+      screen.queryByRole('toolbar', { name: '快速编辑框选工具' }),
+    ).toBeNull();
+    expect(
+      screen.queryByRole('application', { name: 'UI素材框选画布' }),
+    ).toBeNull();
+    const submitButton = within(quickEditDialog).getByRole('button', {
+      name: '修改',
+    });
+    expect((submitButton as HTMLButtonElement).disabled).toBe(true);
+    expect(submitButton.textContent).toBe('生成中');
+  });
+
   it('opens the login modal immediately when entering the editor while logged out', async () => {
     const openLoginModal = vi.fn();
 
@@ -1828,7 +1926,7 @@ describe('ImageCanvasEditorView', () => {
     expect(screen.queryByLabelText('发送给画布 Agent')).toBeNull();
   });
 
-  it('adds assets from the sidebar and supports zoom buttons', () => {
+  it('adds assets from the sidebar and supports zoom buttons', async () => {
     render(<ImageCanvasEditorView />);
 
     expect(
@@ -1842,7 +1940,9 @@ describe('ImageCanvasEditorView', () => {
     ).toBeTruthy();
 
     openAssetSidebar();
-    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    });
 
     expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
     expect(
@@ -1950,6 +2050,84 @@ describe('ImageCanvasEditorView', () => {
     });
   });
 
+  it('persists an undone asset kind and ignores the older pending response', async () => {
+    const characterResource = createDeferred<EditorProjectResourceSnapshot>();
+    const restoredResource = createDeferred<EditorProjectResourceSnapshot>();
+    createEditorProjectResourceMock
+      .mockImplementationOnce(() => characterResource.promise)
+      .mockImplementationOnce(() => restoredResource.promise);
+    render(<ImageCanvasEditorView />);
+
+    const layerButton = await screen.findByRole('button', {
+      name: '选择拼图素材',
+    });
+    fireEvent.click(
+      within(layerButton).getByRole('button', { name: '素材标签：未知' }),
+    );
+    fireEvent.click(
+      within(screen.getByRole('menu', { name: '选择素材标签' })).getByRole(
+        'menuitem',
+        { name: '角色' },
+      ),
+    );
+    await screen.findByRole('button', { name: '素材标签：角色' });
+
+    fireEvent.click(screen.getByRole('button', { name: '撤销' }));
+    await within(layerButton).findByRole('button', { name: '素材标签：未知' });
+    await waitFor(() => {
+      expect(createEditorProjectResourceMock).toHaveBeenCalledTimes(2);
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenNthCalledWith(
+      2,
+      'editor-project-default',
+      expect.objectContaining({ assetKind: null }),
+    );
+
+    await act(async () => {
+      restoredResource.resolve({
+        resourceId: 'resource-restored-kind',
+        projectId: 'editor-project-default',
+        imageSrc: '/creation-type-references/puzzle.webp',
+        width: 640,
+        height: 640,
+        sourceType: 'uploaded',
+        assetKind: null,
+      });
+      await restoredResource.promise;
+    });
+    await waitFor(() => {
+      expect(
+        saveEditorProjectLayoutMock.mock.calls.some((call) =>
+          call[1].layers.some(
+            (layer: { resourceId?: unknown }) =>
+              layer.resourceId === 'resource-restored-kind',
+          ),
+        ),
+      ).toBe(true);
+    });
+
+    await act(async () => {
+      characterResource.resolve({
+        resourceId: 'resource-stale-character',
+        projectId: 'editor-project-default',
+        imageSrc: '/creation-type-references/puzzle.webp',
+        width: 640,
+        height: 640,
+        sourceType: 'uploaded',
+        assetKind: 'character',
+      });
+      await characterResource.promise;
+    });
+    expect(
+      saveEditorProjectLayoutMock.mock.calls.some((call) =>
+        call[1].layers.some(
+          (layer: { resourceId?: unknown }) =>
+            layer.resourceId === 'resource-stale-character',
+        ),
+      ),
+    ).toBe(false);
+  });
+
   it('offers Lovart-style zoom menu commands', async () => {
     render(<ImageCanvasEditorView />);
 
@@ -2060,119 +2238,63 @@ describe('ImageCanvasEditorView', () => {
     expect(loadEditorProjectMock).not.toHaveBeenCalled();
   });
 
-  it('refreshes canvas and asset library when Agent generation finishes', async () => {
+  it('confirms Agent tool calls and refreshes the conversation for the job id', async () => {
     enableEditorAgentSidebarForTest();
-    let showGeneratedAsset = false;
-    loadEditorAssetLibraryMock.mockImplementation(async () => ({
-      folders: [
-        {
-          folderId: 'project',
-          label: '项目素材',
-          sortOrder: 0,
-          collapsed: false,
-          systemDefault: true,
-        },
-      ],
-      assets: showGeneratedAsset
-        ? [
-            ...defaultEditorAssetLibraryAssets,
-            {
-              assetId: 'asset-agent-stream',
-              folderId: 'project',
-              label: 'Agent结果素材',
-              imageSrc: '/agent-stream.png',
-              width: 512,
-              height: 512,
-              sourceType: 'generated',
-              assetKind: 'editor_agent_generated_image',
-            },
-          ]
-        : defaultEditorAssetLibraryAssets,
-    }));
     listEditorAgentConversationsMock.mockResolvedValueOnce([
       createEditorAgentConversationSummary(),
     ]);
-    getEditorAgentConversationMock.mockResolvedValueOnce({
+    const pendingConversation: EditorAgentConversationDetail = {
       ...createEditorAgentConversationSummary(),
-      messages: [],
-    });
-    streamEditorAgentMessageMock.mockImplementation(
-      async (conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId,
-            messageId: 'assistant-agent-stream',
-            role: 'assistant',
-            kind: 'chat',
-            textDelta: '我来生成图片。',
-          },
-        });
-        showGeneratedAsset = true;
-        options.onEvent?.({
-          event: 'generation_result',
-          data: {
-            conversationId,
-            messageId: 'assistant-agent-stream',
-            toolCallId: 'tool-call-agent-stream',
-            toolName: 'generate_image',
-            model: 'gpt-image-2',
-            images: [
-              {
-                resourceId: 'resource-agent-stream',
-                imageSrc: '/agent-stream.png',
-                thumbnailSrc: null,
-                width: 512,
-                height: 512,
-              },
-            ],
-          },
-        });
-        options.onEvent?.({
-          event: 'done',
-          data: { conversationId, title: null },
-        });
-      },
-    );
-    loadEditorProjectMock.mockResolvedValueOnce({
-      projectId: 'editor-project-default',
-      title: '默认项目',
-      viewport: { x: 0, y: 0, scale: 1 },
-      layers: [
-        ...defaultEditorProjectLayers,
+      title: '画布 Agent',
+      createdAt: '2026-07-03T00:00:00.000Z',
+      messages: [
         {
-          layerId: 'layer-agent-stream',
-          resourceId: 'resource-agent-stream',
-          title: 'Agent结果图',
-          src: '/agent-stream.png',
-          x: 1500,
-          y: 300,
-          width: 512,
-          height: 512,
-          originalWidth: 512,
-          originalHeight: 512,
-          zIndex: 3,
-          sourceType: 'generated',
+          id: 3,
+          role: 'system',
+          text: 'internal pending tool prompt',
+          attachments: [],
+          toolCall: {
+            toolName: 'edit-image',
+            status: 'not_completed',
+            args: {
+              object_image_id: 'source-image',
+              prompt: '把图片换成像素风',
+            },
+            displayArgs:
+              createEditImageToolCallDisplayArgs('把图片换成像素风'),
+            images: [],
+            error: null,
+          },
+          createdAt: '2026-07-03T00:00:00.000Z',
         },
       ],
-      resources: [
-        ...defaultEditorProjectResources,
+    };
+    const confirmedConversation: EditorAgentConversationDetail = {
+      ...pendingConversation,
+      messages: [
         {
-          resourceId: 'resource-agent-stream',
-          projectId: 'editor-project-default',
-          imageSrc: '/agent-stream.png',
-          width: 512,
-          height: 512,
-          sourceType: 'generated',
-          prompt: 'Agent生成结果',
-          model: 'gpt-image-2',
-          provider: 'VectorEngine',
-          taskId: 'task-agent-stream',
-          assetKind: 'editor_agent_generated_image',
+          id: 3,
+          role: 'system',
+          text: 'internal confirmed tool output',
+          attachments: [],
+          toolCall: {
+            toolName: 'edit-image',
+            status: 'not_completed',
+            externalJobId: 'task-edit-canvas-1',
+            args: {},
+            displayArgs:
+              createEditImageToolCallDisplayArgs('把图片换成像素风'),
+            images: [],
+            error: null,
+          },
+          createdAt: '2026-07-03T00:00:00.000Z',
         },
       ],
-      updatedAt: '2026-07-03T00:02:00.000Z',
-    });
+    };
+    getEditorAgentConversationMock
+      .mockResolvedValueOnce(pendingConversation)
+      .mockResolvedValue(confirmedConversation);
+    confirmEditorAgentToolCallMock.mockResolvedValue(undefined);
 
     render(<ImageCanvasEditorView />);
 
@@ -2182,20 +2304,21 @@ describe('ImageCanvasEditorView', () => {
         'editor-agent-conv-test',
       );
     });
-    fireEvent.change(await screen.findByLabelText('发送给画布 Agent'), {
-      target: { value: '生成一张图' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: '发送' }));
+    const getConversationCallsBeforeConfirm =
+      getEditorAgentConversationMock.mock.calls.length;
+    fireEvent.click(await screen.findByRole('button', { name: '确认' }));
 
     await waitFor(() => {
-      expect(loadEditorProjectMock).toHaveBeenCalledWith(
-        'editor-project-default',
+      expect(confirmEditorAgentToolCallMock).toHaveBeenCalledWith(
+        'editor-agent-conv-test',
+        3,
       );
     });
-    expect(await screen.findByAltText('画布图片：Agent结果图')).toBeTruthy();
-
-    fireEvent.click(screen.getByRole('button', { name: '打开素材' }));
-    expect(await screen.findByText('Agent结果素材')).toBeTruthy();
+    expect(getEditorAgentConversationMock).toHaveBeenCalledTimes(
+      getConversationCallsBeforeConfirm + 1,
+    );
+    expect(await screen.findByText('执行中')).toBeTruthy();
+    expect(screen.queryByAltText('画布图片：Agent结果图')).toBeNull();
   });
 
   it('resets the canvas view without forwarding the click event to fit layers', () => {
@@ -2237,7 +2360,7 @@ describe('ImageCanvasEditorView', () => {
       clientX: 400,
       clientY: 280,
     });
-    viewport.dispatchEvent(ctrlWheelEvent);
+    fireEvent(viewport, ctrlWheelEvent);
     expect(ctrlWheelEvent.defaultPrevented).toBe(true);
   });
 
@@ -2581,54 +2704,109 @@ describe('ImageCanvasEditorView', () => {
     ).toBeNull();
   });
 
-  it('undoes and redoes canvas layer changes from the panel controls', () => {
+  it('blocks panel undo when an added image would disappear', async () => {
     render(<ImageCanvasEditorView />);
 
     expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(
       'disabled',
       true,
     );
-    expect(screen.getByRole('button', { name: '重做' })).toHaveProperty(
+    expect(screen.getByRole('button', { name: '恢复' })).toHaveProperty(
       'disabled',
       true,
     );
 
     openAssetSidebar();
-    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    });
 
     expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
     expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(
       'disabled',
       false,
     );
-    fireEvent.click(screen.getByRole('button', { name: '撤销' }));
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '撤销' }));
+    });
 
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(
+      screen.getByText('无法撤销：添加图片操作，可能会使图片消失'),
+    ).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
     expect(screen.queryByAltText('画布图片：声浪素材')).toBeNull();
-    expect(screen.getByRole('button', { name: '重做' })).toHaveProperty(
+    fireEvent.click(screen.getByRole('button', { name: '撤销' }));
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(screen.getByText('已撤销：删除图片操作')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '恢复' })).toHaveProperty(
       'disabled',
       false,
     );
-    fireEvent.click(screen.getByRole('button', { name: '重做' }));
-
+    fireEvent.click(screen.getByRole('button', { name: '恢复' }));
     expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(
+      screen.getByText('无法恢复：删除图片操作，可能会使图片消失'),
+    ).toBeTruthy();
   });
 
-  it('supports undo and redo keyboard shortcuts inside the editor', () => {
+  it('blocks protected keyboard undo without creating a restore entry', async () => {
     render(<ImageCanvasEditorView />);
 
     openAssetSidebar();
-    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    });
     expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
 
     fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
-    expect(screen.queryByAltText('画布图片：声浪素材')).toBeNull();
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(
+      screen.getByText('无法撤销：添加图片操作，可能会使图片消失'),
+    ).toBeTruthy();
+    expect(screen.getByRole('button', { name: '恢复' })).toHaveProperty(
+      'disabled',
+      true,
+    );
 
+    await act(async () => {
+      fireEvent.keyDown(window, {
+        key: 'Z',
+        code: 'KeyZ',
+        ctrlKey: true,
+        shiftKey: true,
+      });
+    });
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+  });
+
+  it('restores a safely undone move from the panel and keyboard shortcut', async () => {
+    render(<ImageCanvasEditorView />);
+
+    openAssetSidebar();
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    });
+
+    fireEvent.keyDown(window, { key: 'ArrowRight', code: 'ArrowRight' });
+    fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
+    expect(screen.getByText('已撤销：移动图片操作')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '恢复' })).toHaveProperty(
+      'disabled',
+      false,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '恢复' }));
+    expect(screen.getByText('已恢复：移动图片操作')).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
     fireEvent.keyDown(window, {
       key: 'Z',
       code: 'KeyZ',
       ctrlKey: true,
       shiftKey: true,
     });
-    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(screen.getByText('已恢复：移动图片操作')).toBeTruthy();
   });
 });
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index 551bc50d5..2e4db9067 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -9,7 +9,6 @@ import {
   useState,
 } from 'react';
 
-import type { EditorAgentGenerationResultEvent } from '../../../packages/shared/src/contracts/editorAgent';
 import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
 import { loadFrontendRuntimeConfig } from '../../services/frontendRuntimeConfigService';
 import {
@@ -45,6 +44,8 @@ import type {
   CanvasAssetKind,
   CanvasContextMenuState,
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
+  CanvasHistoryFeedback,
   CanvasLayer,
   CanvasTool,
   CanvasViewport,
@@ -60,6 +61,7 @@ import {
   applyEditorGenerationPricingConfig,
   isCanvasGenerationDialog,
 } from './ImageCanvasGenerationModel';
+import { formatCanvasHistoryAction } from './ImageCanvasHistoryModel';
 import { fitViewportToBounds } from './ImageCanvasInteractionModel';
 import {
   isCanvasGenerationComposerVisible,
@@ -308,7 +310,16 @@ export function ImageCanvasEditorView({
   const canvasGenerationDialogsRef = useRef<CanvasGenerationDialogState[]>([]);
   const viewportRef = useRef<CanvasViewport>(DEFAULT_IMAGE_CANVAS_VIEWPORT);
   const canvasBackgroundColorRef = useRef(DEFAULT_CANVAS_BACKGROUND_COLOR);
-  const captureCanvasHistoryRef = useRef<() => void>(() => {});
+  const captureCanvasHistoryRef = useRef<
+    (action: CanvasHistoryAction) => void
+  >(() => {});
+  const discardCanvasHistoryEntriesContainingLayerRef = useRef<
+    (matchesLayer: (layer: CanvasLayer) => boolean) => void
+  >(() => {});
+  const persistRestoredAssetKindRef = useRef<(layer: CanvasLayer) => void>(
+    () => {},
+  );
+  const layerResourcePersistenceVersionRef = useRef(new Map<string, number>());
   const resetCanvasInteractionStateRef = useRef<() => void>(() => {});
   const closeGenerationTransientStateRef = useRef<() => void>(() => {});
   const specToolWrapRef = useRef<HTMLSpanElement | null>(null);
@@ -409,6 +420,9 @@ export function ImageCanvasEditorView({
   const deleteLayerByIdRef = useRef<(targetLayerId: string | null) => void>(
     () => {},
   );
+  const clearDeletedLayerGenerationStateRef = useRef<
+    (targetLayerId: string) => void
+  >(() => {});
   const suppressAssetClickRef = useRef(false);
   const [layers, setLayers] = useState<CanvasLayer[]>([]);
   const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
@@ -428,7 +442,7 @@ export function ImageCanvasEditorView({
   >(null);
   const [isShortcutDialogOpen, setIsShortcutDialogOpen] = useState(false);
   const captureViewportHistory = useCallback(() => {
-    captureCanvasHistoryRef.current();
+    captureCanvasHistoryRef.current({ type: 'change-viewport' });
   }, []);
   const {
     viewport,
@@ -520,6 +534,10 @@ export function ImageCanvasEditorView({
     requestLogin: () => authUiRef.current?.openLoginModal(),
     currentUser: authUi?.user ?? null,
   });
+  const refreshEditorWalletState = useCallback(() => {
+    refreshEditorWalletBalance();
+    loadRechargeCenter();
+  }, [loadRechargeCenter, refreshEditorWalletBalance]);
   const isAccountPaymentModalOpen =
     isRewardCodeOpen ||
     isRechargeOpen ||
@@ -632,11 +650,19 @@ export function ImageCanvasEditorView({
     toggleMinimap,
   } = useImageCanvasEditorChrome({ openEditorLoginModal });
   canvasBackgroundColorRef.current = canvasBackgroundColor;
+  const discardAssetRelatedCanvasHistory = useCallback(
+    (matchesLayer: (layer: CanvasLayer) => boolean) =>
+      discardCanvasHistoryEntriesContainingLayerRef.current(matchesLayer),
+    [],
+  );
   const removeCanvasLayersLinkedToAssets = useImageCanvasAssetLayerCleanup({
     layers,
     setLayers,
     setSelectedLayerId,
     setSelectedLayerIds,
+    onDeleteLayerSideEffects: (layerId) =>
+      clearDeletedLayerGenerationStateRef.current(layerId),
+    discardHistoryEntriesContainingLayer: discardAssetRelatedCanvasHistory,
   });
   const {
     assetFolders,
@@ -757,18 +783,69 @@ export function ImageCanvasEditorView({
     }),
     [],
   );
+  const canvasHistoryEffects = useMemo(
+    () => ({
+      persistRestoredAssetKind: (layer: CanvasLayer) =>
+        persistRestoredAssetKindRef.current(layer),
+    }),
+    [],
+  );
   const {
     canUndo,
     canRedo,
+    getCanvasHistorySnapshot,
     captureCanvasHistory,
+    discardCanvasHistoryEntriesContainingLayer,
     undoCanvasChange,
     redoCanvasChange,
   } = useCanvasHistory({
     refs: canvasHistoryRefs,
     setters: canvasHistorySetters,
     resetters: canvasHistoryResetters,
+    effects: canvasHistoryEffects,
   });
   captureCanvasHistoryRef.current = captureCanvasHistory;
+  discardCanvasHistoryEntriesContainingLayerRef.current =
+    discardCanvasHistoryEntriesContainingLayer;
+  const [historyFeedback, setHistoryFeedback] =
+    useState<CanvasHistoryFeedback | null>(null);
+  useEffect(() => {
+    if (!historyFeedback) {
+      return;
+    }
+    const timer = window.setTimeout(() => setHistoryFeedback(null), 3000);
+    return () => window.clearTimeout(timer);
+  }, [historyFeedback]);
+  const handleUndoCanvasChange = useCallback(() => {
+    const result = undoCanvasChange();
+    if (result.status === 'empty') {
+      return;
+    }
+    const actionLabel = formatCanvasHistoryAction(result.action);
+    setHistoryFeedback((currentFeedback) => ({
+      id: (currentFeedback?.id ?? 0) + 1,
+      tone: result.status === 'blocked' ? 'warning' : 'neutral',
+      text:
+        result.status === 'blocked'
+          ? `无法撤销：${actionLabel}操作，可能会使图片消失`
+          : `已撤销：${actionLabel}操作`,
+    }));
+  }, [undoCanvasChange]);
+  const handleRedoCanvasChange = useCallback(() => {
+    const result = redoCanvasChange();
+    if (result.status === 'empty') {
+      return;
+    }
+    const actionLabel = formatCanvasHistoryAction(result.action);
+    setHistoryFeedback((currentFeedback) => ({
+      id: (currentFeedback?.id ?? 0) + 1,
+      tone: result.status === 'blocked' ? 'warning' : 'neutral',
+      text:
+        result.status === 'blocked'
+          ? `无法恢复：${actionLabel}操作，可能会使图片消失`
+          : `已恢复：${actionLabel}操作`,
+    }));
+  }, [redoCanvasChange]);
   const selectSingleLayer = useCallback(
     (layerId: string | null) => {
       setSelectedLayerId(layerId);
@@ -1092,26 +1169,24 @@ export function ImageCanvasEditorView({
     setEditorProjectContextId(projectId);
   }, [projectId, setEditorProjectContextId]);
   const applyGeneratedProjectSnapshot = useCallback(
-    (project: EditorProjectSnapshot) => {
+    (
+      project: EditorProjectSnapshot,
+      action: CanvasHistoryAction = { type: 'generate-image', count: 1 },
+    ) => {
+      captureCanvasHistory(action);
       applyProjectSnapshot(project);
       void refreshAssetLibrary();
     },
-    [applyProjectSnapshot, refreshAssetLibrary],
-  );
-  const handleEditorAgentGenerationResult = useCallback(
-    (event: EditorAgentGenerationResultEvent) => {
-      const hasGeneratedResource = event.images.some((image) =>
-        image.resourceId?.trim(),
-      );
-      if (!projectId || !hasGeneratedResource) {
-        return;
-      }
-      void loadEditorProject(projectId)
-        .then(applyGeneratedProjectSnapshot)
-        .catch(() => undefined);
-    },
-    [applyGeneratedProjectSnapshot, projectId],
+    [applyProjectSnapshot, captureCanvasHistory, refreshAssetLibrary],
   );
+  const handleEditorAgentCanvasRefreshRequested = useCallback(() => {
+    if (!projectId) {
+      return;
+    }
+    void loadEditorProject(projectId)
+      .then(applyGeneratedProjectSnapshot)
+      .catch(() => undefined);
+  }, [applyGeneratedProjectSnapshot, projectId]);
   const persistUpdatedLayerResource = useCallback(
     (layer: CanvasLayer) => {
       if (!projectId) {
@@ -1121,6 +1196,9 @@ export function ImageCanvasEditorView({
       if (!imageSrc) {
         return;
       }
+      const requestVersion =
+        (layerResourcePersistenceVersionRef.current.get(layer.id) ?? 0) + 1;
+      layerResourcePersistenceVersionRef.current.set(layer.id, requestVersion);
       void createEditorProjectResource(projectId, {
         imageSrc,
         objectKey: layer.objectKey,
@@ -1138,6 +1216,12 @@ export function ImageCanvasEditorView({
         assetKind: layer.assetKind,
         generationInputs: layer.generationInputs,
       }).then((resource) => {
+        if (
+          layerResourcePersistenceVersionRef.current.get(layer.id) !==
+          requestVersion
+        ) {
+          return;
+        }
         setLayers((currentLayers) => {
           const nextLayers = currentLayers.map((currentLayer) =>
             currentLayer.id === layer.id
@@ -1154,6 +1238,7 @@ export function ImageCanvasEditorView({
     },
     [projectId],
   );
+  persistRestoredAssetKindRef.current = persistUpdatedLayerResource;
   const {
     assetExportStatus,
     isExportingAssets,
@@ -1197,6 +1282,7 @@ export function ImageCanvasEditorView({
     appendUiAssetExtractionReferences: (references) =>
       appendUiAssetExtractionReferencesRef.current(references),
     appendCanvasLayersWithResources,
+    captureCanvasHistory,
     selectSingleLayer,
   });
   const generationSurface = useImageCanvasGenerationSurface({
@@ -1241,8 +1327,15 @@ export function ImageCanvasEditorView({
     assetFolderId: activeUploadFolderId,
     upsertGeneratedAsset,
     applyProjectSnapshot: applyGeneratedProjectSnapshot,
-    onWalletBalanceMayHaveChanged: refreshEditorWalletBalance,
+    onWalletBalanceMayHaveChanged: refreshEditorWalletState,
   });
+  const handleEditorAgentConfirmSent = useCallback(() => {
+    generationSurface.refreshTaskList();
+  }, [generationSurface]);
+  const handleEditorAgentJobCompleted = useCallback(() => {
+    generationSurface.refreshTaskList();
+    handleEditorAgentCanvasRefreshRequested();
+  }, [generationSurface, handleEditorAgentCanvasRefreshRequested]);
   const showGenerationWarning = generationSurface.showGenerationWarning;
   const handleExternalGenerationTasksCompleted = useCallback(
     (tasks: ExternalGenerationTaskRecord[]) => {
@@ -1251,11 +1344,9 @@ export function ImageCanvasEditorView({
       }
       const warning = tasks.find((task) => task.warning?.trim())?.warning?.trim();
       if (warning) {
-        showGenerationWarning(
-          `图集已生成，但自动拆分未完成：${warning}`,
-        );
+        showGenerationWarning(warning);
       }
-      refreshEditorWalletBalance();
+      refreshEditorWalletState();
       void loadEditorProject(projectId)
         .then(applyGeneratedProjectSnapshot)
         .catch(() => undefined);
@@ -1263,7 +1354,7 @@ export function ImageCanvasEditorView({
     [
       applyGeneratedProjectSnapshot,
       projectId,
-      refreshEditorWalletBalance,
+      refreshEditorWalletState,
       showGenerationWarning,
     ],
   );
@@ -1352,6 +1443,7 @@ export function ImageCanvasEditorView({
     openCropExpandPanel,
     removeSelectedLayerBackground,
     splitSelectedIconSpritesheet,
+    splittingIconSpritesheetLayerIds,
     extractUiDesignAssets,
     pickCharacterSpecFromLayer,
     pickGenerationReferenceFromLayer,
@@ -1404,6 +1496,8 @@ export function ImageCanvasEditorView({
     setContextMenu(null);
   };
   setQuickEditPanelRef.current = setQuickEditPanel;
+  clearDeletedLayerGenerationStateRef.current =
+    clearDeletedLayerGenerationState;
   appendUiAssetExtractionReferencesRef.current =
     appendUiAssetExtractionReferences;
   useEffect(() => {
@@ -1609,6 +1703,8 @@ export function ImageCanvasEditorView({
     onViewportInteractionStart: beginViewportInteraction,
     onViewportInteractionEnd: endViewportInteraction,
     onCloseImageContextMenu: () => setImageContextMenu(null),
+    getCanvasHistorySnapshot,
+    captureCanvasHistory,
   });
   resetCanvasInteractionStateRef.current = clearActiveInteraction;
   useEffect(() => {
@@ -1652,7 +1748,7 @@ export function ImageCanvasEditorView({
   );
   const removeCanvasGenerationDialog = useCallback(
     (dialogId: string) => {
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'delete-generation-result', count: 1 });
       removeCanvasGenerationDialogById(dialogId);
       setSelectedLayerId(null);
       setSelectedLayerIds([]);
@@ -1697,7 +1793,7 @@ export function ImageCanvasEditorView({
       if (!targetLayer || targetLayer.assetKind === assetKind) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'change-asset-kind', count: 1 });
       const nextLayer = {
         ...targetLayer,
         assetKind,
@@ -1765,7 +1861,12 @@ export function ImageCanvasEditorView({
       if (!targetLayerIds.length && !targetDialogIds.length) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({
+        type: targetLayerIds.length
+          ? 'move-image'
+          : 'move-generation-result',
+        count: targetLayerIds.length || targetDialogIds.length,
+      });
       if (targetLayerIds.length) {
         setLayers((currentLayers) =>
           currentLayers.map((layer) =>
@@ -1835,8 +1936,8 @@ export function ImageCanvasEditorView({
     generateDialogRef,
     selectedLayerIdRef,
     selectedLayerIdsRef,
-    redoCanvasChange,
-    undoCanvasChange,
+    undoCanvasChange: handleUndoCanvasChange,
+    redoCanvasChange: handleRedoCanvasChange,
     deleteLayerById: deleteLayerByIdFromShortcut,
     deleteSelectedCanvasObjects: deleteSelectedLayer,
     selectAllCanvasObjects,
@@ -2114,6 +2215,7 @@ export function ImageCanvasEditorView({
     quickEditSelectionSourceLayer,
     generationComposerStyle,
     selectedToolbarStyle,
+    splittingIconSpritesheetLayerIds,
     uploadDropTarget,
     contextMenu,
     canvasClipboard,
@@ -2123,6 +2225,7 @@ export function ImageCanvasEditorView({
     contextShouldUnlockLayer,
     canUndo,
     canRedo,
+    historyFeedback,
     isZoomMenuOpen,
     isBackgroundSettingsOpen,
     activeSidebarPanel,
@@ -2154,7 +2257,8 @@ export function ImageCanvasEditorView({
     onActivateGenerationDialog: activateCanvasGenerationDialog,
     onFocusExternalTask: focusExternalGenerationTask,
     onExternalTasksCompleted: handleExternalGenerationTasksCompleted,
-    onEditorAgentGenerationResult: handleEditorAgentGenerationResult,
+    onEditorAgentCanvasRefreshRequested: handleEditorAgentJobCompleted,
+    onEditorAgentConfirmSent: handleEditorAgentConfirmSent,
     onToggleTaskSidebar: toggleTaskSidebar,
     onToggleAgentConversation: toggleAgentConversation,
     onCropExpandHandlePointerDown: generationSurface.startCropExpandFrameResize,
@@ -2196,8 +2300,8 @@ export function ImageCanvasEditorView({
     onCloseImageContextMenu: () => setImageContextMenu(null),
     onUpdateScaleFromCenter: updateScaleFromCenter,
     onFitLayers: fitLayers,
-    onUndoCanvasChange: undoCanvasChange,
-    onRedoCanvasChange: redoCanvasChange,
+    onUndoCanvasChange: handleUndoCanvasChange,
+    onRedoCanvasChange: handleRedoCanvasChange,
     onToggleZoomMenu: toggleZoomMenu,
     onCloseZoomMenu: closeZoomMenu,
     onToggleBackgroundSettings: toggleBackgroundSettings,
diff --git a/src/components/image-editor/ImageCanvasGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasGenerationComposerView.tsx
index 3049a31e5..9d4f3fa96 100644
--- a/src/components/image-editor/ImageCanvasGenerationComposerView.tsx
+++ b/src/components/image-editor/ImageCanvasGenerationComposerView.tsx
@@ -44,14 +44,13 @@ import {
   DEFAULT_VIDEO_ASPECT_RATIO,
   DEFAULT_VIDEO_DURATION_SECONDS,
   DEFAULT_VIDEO_SOUND,
-  DEFAULT_VIDEO_WEB_SEARCH_ENABLED,
-  EDITOR_VIDEO_ASPECT_RATIO_OPTIONS,
   EDITOR_SOUND_EFFECT_MODEL_OPTIONS,
+  EDITOR_VIDEO_ASPECT_RATIO_OPTIONS,
   EDITOR_VIDEO_MODEL_OPTIONS,
   EDITOR_VIDEO_RESOLUTION_OPTIONS,
-  VIDEO_MODEL_SEEDANCE_2_FAST,
   resizeGenerationPlaceholderToVideoSelection,
   SPEC_TYPE_LABEL,
+  VIDEO_MODEL_SEEDANCE_2_FAST,
 } from './ImageCanvasGenerationModel';
 import { ImageCanvasIconSpritesheetComposerView } from './ImageCanvasIconSpritesheetComposerView';
 import { ImageCanvasPublicationMaterialsDemoPanelView } from './ImageCanvasPublicationMaterialsDemoPanelView';
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
index b2300817f..a4011bc1b 100644
--- a/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
@@ -144,7 +144,7 @@ describe('ImageCanvasGenerationDialogModel', () => {
     });
   });
 
-  it('creates character generation drafts with model dimensions and icon drafts with icon frame dimensions', () => {
+  it('creates character and icon generation drafts with the selected model dimensions', () => {
     const canvasSize = { width: 960, height: 720 };
     const viewport = { x: 0, y: 0, scale: 1 };
 
@@ -183,12 +183,12 @@ describe('ImageCanvasGenerationDialogModel', () => {
       iconSpecReference: null,
       iconDescriptions: [],
       placeholder: {
-        x: 300,
-        y: 180,
-        width: 360,
-        height: 360,
-        originalWidth: 512,
-        originalHeight: 512,
+        x: -32,
+        y: -152,
+        width: 1024,
+        height: 1024,
+        originalWidth: 1024,
+        originalHeight: 1024,
       },
     });
   });
@@ -233,10 +233,10 @@ describe('ImageCanvasGenerationDialogModel', () => {
       imageSize: '1K',
       uiDesignSpecReference: null,
       placeholder: {
-        x: -32,
-        y: 72,
-        width: 1024,
-        height: 576,
+        x: -64,
+        y: 56,
+        width: 1088,
+        height: 608,
       },
     });
   });
@@ -383,6 +383,7 @@ describe('ImageCanvasGenerationDialogModel', () => {
     });
 
     expect(createEditDialogDraft(sourceLayer)).toEqual({
+      id: 'edit-dialog:layer-source',
       mode: 'edit',
       prompt: '原图提示',
       status: 'idle',
@@ -538,6 +539,10 @@ describe('ImageCanvasGenerationDialogModel', () => {
       placeholder: {
         x: 472,
         y: 140,
+        width: 1024,
+        height: 768,
+        originalWidth: 1024,
+        originalHeight: 768,
       },
     });
 
@@ -614,9 +619,58 @@ describe('ImageCanvasGenerationDialogModel', () => {
       imageModel: 'gpt-image-2',
       aspectRatio: '2:3',
       imageSize: '2K',
+      placeholder: {
+        x: 472,
+        y: 140,
+        width: 1376,
+        height: 2048,
+        originalWidth: 1376,
+        originalHeight: 2048,
+      },
     });
   });
 
+  it.each([
+    ['character', 'character'],
+    ['icon', 'icon-spritesheet'],
+    ['ui-design', 'ui-design'],
+  ] as const)(
+    'restores %s remodel placeholders to the selected 2K dimensions',
+    (mode, assetKind) => {
+      expect(
+        createSameSourceGenerationDialogDraft({
+          sourceLayer: createLayer({ assetKind }),
+          canvasSize: { width: 960, height: 720 },
+          viewport: { x: 0, y: 0, scale: 1 },
+          sourceDialog: {
+            id: `generation-dialog-${mode}`,
+            mode,
+            prompt: '来源生成器',
+            status: 'idle',
+            generatedLayerId: 'layer-source',
+            imageModel: IMAGE_MODEL_GPT_IMAGE_2,
+            aspectRatio: '2:3',
+            imageSize: '2K',
+          },
+          mode: 'redraw',
+        }),
+      ).toMatchObject({
+        mode,
+        imageModel: IMAGE_MODEL_GPT_IMAGE_2,
+        aspectRatio: '2:3',
+        imageSize: '2K',
+        placeholder: {
+          x: 472,
+          y: 140,
+          width: 1376,
+          height: 2048,
+          originalWidth: 1376,
+          originalHeight: 2048,
+        },
+      });
+    },
+  );
+
   it('restores a plain generated layer from its own metadata', () => {
     const canvasSize = { width: 960, height: 720 };
     const viewport = { x: 0, y: 0, scale: 1 };
@@ -672,6 +726,102 @@ describe('ImageCanvasGenerationDialogModel', () => {
     });
   });
 
+  it('preserves 2K dimensions when reopening a persisted character layer', () => {
+    expect(
+      createLayerGenerationDialogDraft({
+        sourceLayer: createLayer({
+          sourceType: 'generated',
+          assetKind: 'character',
+          model: IMAGE_MODEL_NANOBANANA2,
+          originalWidth: 2048,
+          originalHeight: 2048,
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '香水师角色' }],
+            references: [],
+          },
+        }),
+        canvasSize: { width: 960, height: 720 },
+        viewport: { x: 0, y: 0, scale: 1 },
+      }),
+    ).toMatchObject({
+      mode: 'character',
+      prompt: '香水师角色',
+      imageModel: IMAGE_MODEL_NANOBANANA2,
+      aspectRatio: '1:1',
+      imageSize: '2K',
+      generatedLayerId: 'layer-source',
+    });
+  });
+
+  it('restores video and audio generators from media layer metadata', () => {
+    const context = {
+      canvasSize: { width: 960, height: 720 },
+      viewport: { x: 0, y: 0, scale: 1 },
+    };
+
+    expect(
+      createLayerGenerationDialogDraft({
+        ...context,
+        sourceLayer: createLayer({
+          title: '技能演示',
+          mediaType: 'video',
+          assetKind: 'video',
+          sourceType: 'generated',
+          generationInputs: {
+            fields: [{ title: '视频描述', value: '火球飞行动画' }],
+            references: [],
+          },
+        }),
+      }),
+    ).toMatchObject({
+      mode: 'video',
+      prompt: '火球飞行动画',
+      generatedLayerId: 'layer-source',
+    });
+
+    expect(
+      createLayerGenerationDialogDraft({
+        ...context,
+        sourceLayer: createLayer({
+          title: '金币音效',
+          mediaType: 'audio',
+          assetKind: 'sound-effect',
+          sourceType: 'generated',
+          generationInputs: {
+            fields: [{ title: 'prompt', value: '金币弹出声' }],
+            references: [],
+          },
+        }),
+      }),
+    ).toMatchObject({
+      mode: 'audio-sound-effect',
+      prompt: '金币弹出声',
+      generatedLayerId: 'layer-source',
+    });
+
+    expect(
+      createLayerGenerationDialogDraft({
+        ...context,
+        sourceLayer: createLayer({
+          title: '背景音乐',
+          mediaType: 'audio',
+          assetKind: 'background-music',
+          sourceType: 'generated',
+          generationInputs: {
+            fields: [
+              { title: 'gpt_description_prompt', value: '轻松森林音乐' },
+            ],
+            references: [],
+          },
+        }),
+      }),
+    ).toMatchObject({
+      mode: 'audio-background-music',
+      prompt: '轻松森林音乐',
+      generatedLayerId: 'layer-source',
+    });
+  });
+
   it('inherits and normalizes quick edit model parameters from the source', () => {
     expect(
       createQuickEditPanelDraft(
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
index d238044fe..ee9c2dc0a 100644
--- a/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
@@ -31,13 +31,12 @@ import {
   EDITOR_IMAGE_DIMENSION_OPTIONS,
   EDITOR_IMAGE_MODEL_OPTIONS,
   ICON_DESCRIPTION_LIMIT,
-  ICON_FRAME_DISPLAY_SIZE,
-  ICON_FRAME_ORIGINAL_SIZE,
   IMAGE_MODEL_GPT_IMAGE_2,
   inferEditorImageAspectRatio,
   inferEditorImageSizeLabel,
   normalizeEditorImageModel,
   PUBLICATION_FRAME_ORIGINAL_SIZE,
+  resizeGenerationPlaceholderToImageSelection,
   resolveEditorImageGenerationPixelSize,
   resolveEditorVideoGenerationPixelSize,
   SPEC_FRAME_ORIGINAL_SIZE,
@@ -298,6 +297,11 @@ export function createIconGenerationDialogDraft({
   const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
   const normalizedImageModel = normalizeEditorImageModel(imageModel);
   const dimensionDefaults = resolveImageDimensionDefaults(normalizedImageModel);
+  const placeholderSize = resolveEditorImageGenerationPixelSize({
+    model: normalizedImageModel,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+  });
   return {
     mode: 'icon',
     prompt: '',
@@ -310,12 +314,12 @@ export function createIconGenerationDialogDraft({
     aspectRatio: dimensionDefaults.aspectRatio,
     imageSize: dimensionDefaults.imageSize,
     placeholder: {
-      x: worldCenter.x - ICON_FRAME_DISPLAY_SIZE.width / 2,
-      y: worldCenter.y - ICON_FRAME_DISPLAY_SIZE.height / 2,
-      width: ICON_FRAME_DISPLAY_SIZE.width,
-      height: ICON_FRAME_DISPLAY_SIZE.height,
-      originalWidth: ICON_FRAME_ORIGINAL_SIZE.width,
-      originalHeight: ICON_FRAME_ORIGINAL_SIZE.height,
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
     },
   };
 }
@@ -650,6 +654,21 @@ function resolveGeneratedSourceDialogMode({
   if (sourceLayer.assetKind === 'character-animation') {
     return 'character-animation';
   }
+  if (
+    sourceLayer.assetKind === 'video' ||
+    sourceLayer.mediaType === 'video'
+  ) {
+    return 'video';
+  }
+  if (sourceLayer.assetKind === 'sound-effect') {
+    return 'audio-sound-effect';
+  }
+  if (sourceLayer.assetKind === 'background-music') {
+    return 'audio-background-music';
+  }
+  if (sourceLayer.mediaType === 'audio') {
+    return resolveAudioRedrawMode(sourceLayer);
+  }
   if (sourceLayer.sourceType === 'generated') {
     return 'generate';
   }
@@ -691,8 +710,7 @@ export function createLayerGenerationDialogDraft({
   return {
     ...draft,
     prompt: draft.prompt || sourceLayer.prompt?.trim() || '',
-    imageModel:
-      sourceDialog?.imageModel ?? sourceLayer.model ?? draft.imageModel,
+    imageModel: sourceDialog?.imageModel ?? draft.imageModel,
     status: 'idle',
     composerOpen: true,
     generatedLayerId: sourceLayer.id,
@@ -740,25 +758,47 @@ function restoreSharedImageOptions(
   sourceLayer: CanvasLayer,
   sourceDialog?: CanvasGenerationDialogState | null,
 ): Omit<CanvasGenerationDialogState, 'id'> {
-  const fields = getGenerationInputFieldValues(sourceLayer);
-  return {
+  const requestedModel = normalizeEditorImageModel(
+    sourceDialog?.imageModel ?? sourceLayer.model ?? draft.imageModel,
+  );
+  const imageModel = EDITOR_IMAGE_MODEL_OPTIONS.some(
+    (option) => option.value === requestedModel,
+  )
+    ? requestedModel
+    : DEFAULT_IMAGE_MODEL;
+  const dimensionOptions =
+    EDITOR_IMAGE_DIMENSION_OPTIONS[
+      imageModel as keyof typeof EDITOR_IMAGE_DIMENSION_OPTIONS
+    ] ?? EDITOR_IMAGE_DIMENSION_OPTIONS[DEFAULT_IMAGE_MODEL];
+  const supportedAspectRatios =
+    dimensionOptions.aspectRatios as readonly string[];
+  const supportedImageSizes = dimensionOptions.imageSizes as readonly string[];
+  const inferredAspectRatio = inferEditorImageAspectRatio(
+    sourceLayer.originalWidth,
+    sourceLayer.originalHeight,
+  );
+  const inferredImageSize = inferEditorImageSizeLabel(
+    sourceLayer.originalWidth,
+    sourceLayer.originalHeight,
+  );
+  const preferredAspectRatio = sourceDialog?.aspectRatio ?? inferredAspectRatio;
+  const preferredImageSize = sourceDialog?.imageSize ?? inferredImageSize;
+  return resizeGenerationPlaceholderToImageSelection({
     ...draft,
-    imageModel: sourceDialog?.imageModel ?? draft.imageModel,
-    aspectRatio:
-      sourceDialog?.aspectRatio ??
-      draft.aspectRatio ??
-      inferEditorImageAspectRatio(
-        sourceLayer.originalWidth,
-        sourceLayer.originalHeight,
-      ),
-    imageSize:
-      sourceDialog?.imageSize ??
-      draft.imageSize ??
-      inferEditorImageSizeLabel(
-        sourceLayer.originalWidth,
-        sourceLayer.originalHeight,
-      ),
-  };
+    imageModel,
+    aspectRatio: supportedAspectRatios.includes(preferredAspectRatio)
+      ? preferredAspectRatio
+      : draft.aspectRatio && supportedAspectRatios.includes(draft.aspectRatio)
+        ? draft.aspectRatio
+        : (dimensionOptions.aspectRatios[0] ?? '1:1'),
+    imageSize: supportedImageSizes.includes(preferredImageSize)
+      ? preferredImageSize
+      : draft.imageSize && supportedImageSizes.includes(draft.imageSize)
+        ? draft.imageSize
+        : (dimensionOptions.imageSizes.find((size) => size === '1K') ??
+          dimensionOptions.imageSizes[0] ??
+          '1K'),
+  });
 }
 
 function resolveSpecTypeFromSourceLayer(
@@ -964,6 +1004,51 @@ export function createSameSourceGenerationDialogDraft({
     );
   }
 
+  if (sourceMode === 'video') {
+    const draft = createVideoRedrawGenerationDialogDraft(sourceLayer);
+    if (!draft) {
+      return null;
+    }
+    return {
+      ...draft,
+      prompt,
+      videoModel: sourceDialog?.videoModel ?? draft.videoModel,
+      videoAspectRatio:
+        sourceDialog?.videoAspectRatio ?? draft.videoAspectRatio,
+      videoResolution:
+        sourceDialog?.videoResolution ?? draft.videoResolution,
+      videoDurationSeconds:
+        sourceDialog?.videoDurationSeconds ?? draft.videoDurationSeconds,
+      videoMode: sourceDialog?.videoMode ?? draft.videoMode,
+      videoSound: sourceDialog?.videoSound ?? draft.videoSound,
+      videoWebSearchEnabled:
+        sourceDialog?.videoWebSearchEnabled ?? draft.videoWebSearchEnabled,
+      generationReferences:
+        sourceDialog?.mode === 'video'
+          ? (sourceDialog.generationReferences ?? draft.generationReferences)
+          : draft.generationReferences,
+    };
+  }
+
+  if (
+    sourceMode === 'audio-sound-effect' ||
+    sourceMode === 'audio-background-music'
+  ) {
+    const draft = createAudioRedrawGenerationDialogDraft(sourceLayer);
+    if (!draft) {
+      return null;
+    }
+    return {
+      ...draft,
+      prompt,
+      soundModel: sourceDialog?.soundModel ?? draft.soundModel,
+      soundDurationSeconds:
+        sourceDialog?.soundDurationSeconds ?? draft.soundDurationSeconds,
+      makeInstrumental:
+        sourceDialog?.makeInstrumental ?? draft.makeInstrumental,
+    };
+  }
+
   if (sourceMode === 'character-animation') {
     return createSameSourceCharacterAnimationDraft({
       sourceLayer,
@@ -1159,6 +1244,7 @@ export function createEditDialogDraft(
       sourceLayer.originalHeight,
     );
   return {
+    id: `edit-dialog:${sourceLayer.id}`,
     mode: 'edit',
     prompt: resolveUserGenerationPromptSnapshot(sourceLayer),
     status: 'idle',
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.test.ts b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
index d80c7ed02..7e8309e9a 100644
--- a/src/components/image-editor/ImageCanvasGenerationModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
@@ -6,8 +6,8 @@ import type {
   CanvasLayer,
 } from './ImageCanvasEditorTypes';
 import {
-  BACKGROUND_MUSIC_MODEL_SUNO,
   applyEditorGenerationPricingConfig,
+  BACKGROUND_MUSIC_MODEL_SUNO,
   buildCharacterGenerationInputs,
   buildEditGenerationInputs,
   buildIconGenerationInputs,
@@ -33,8 +33,8 @@ import {
   DEFAULT_VIDEO_MODEL,
   EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG,
   EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG,
-  EDITOR_MODEL_MUD_POINT_CONFIG,
   EDITOR_IMAGE_MODEL_OPTIONS,
+  EDITOR_MODEL_MUD_POINT_CONFIG,
   EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG,
   EDITOR_SOUND_EFFECT_MODEL_OPTIONS,
   EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG,
@@ -42,8 +42,10 @@ import {
   getGenerationFrameAriaLabel,
   getGenerationFrameLabel,
   IMAGE_MODEL_GPT_IMAGE_2,
+  IMAGE_MODEL_NANOBANANA2,
   isQuickEditUnsupportedAssetKind,
   resolveCharacterAnimationSourceImageSrc,
+  resolveEditorImageGenerationPixelSize,
   resolveImageGenerationErrorMessage,
   VIDEO_MODEL_KLING_3,
   VIDEO_MODEL_KLING_3_OMNI,
@@ -101,6 +103,34 @@ describe('ImageCanvasGenerationModel', () => {
     ).toBeTruthy();
   });
 
+  it.each([
+    [IMAGE_MODEL_NANOBANANA2, '1K', '1:1', 1024, 1024],
+    [IMAGE_MODEL_NANOBANANA2, '2K', '2:3', 1365, 2048],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '1:1', 1024, 1024],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '4:3', 1024, 768],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '3:2', 1024, 688],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '2:3', 688, 1024],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '9:16', 608, 1088],
+    [IMAGE_MODEL_GPT_IMAGE_2, '1K', '16:9', 1088, 608],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '1:1', 2048, 2048],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '4:3', 2048, 1536],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '3:2', 2048, 1376],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '2:3', 1376, 2048],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '9:16', 1152, 2048],
+    [IMAGE_MODEL_GPT_IMAGE_2, '2K', '16:9', 2048, 1152],
+  ] as const)(
+    '%s 的 %s %s 占位尺寸与 provider 直接请求尺寸一致',
+    (model, imageSize, aspectRatio, width, height) => {
+      expect(
+        resolveEditorImageGenerationPixelSize({
+          model,
+          aspectRatio,
+          imageSize,
+        }),
+      ).toEqual({ width, height });
+    },
+  );
+
   it('所有生成按钮价格都从模型定价配置推导', () => {
     expect(calculateEditorImageModelPrice(DEFAULT_IMAGE_MODEL)).toBe(
       EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[DEFAULT_IMAGE_MODEL]['1K'],
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.ts b/src/components/image-editor/ImageCanvasGenerationModel.ts
index 105528bbd..e04b43e91 100644
--- a/src/components/image-editor/ImageCanvasGenerationModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationModel.ts
@@ -173,7 +173,38 @@ function resolveImageFrameSizeFromRatio({
   };
 }
 
+function alignImageDimensionUp(value: number, alignment = 16) {
+  return Math.ceil(value / alignment) * alignment;
+}
+
+function resolveGptImage2FrameSize({
+  aspectRatio,
+  imageSize,
+}: {
+  aspectRatio: string | null | undefined;
+  imageSize: string | null | undefined;
+}): EditorImageFrameSize {
+  const requested = resolveImageFrameSizeFromRatio({ aspectRatio, imageSize });
+  let width = requested.width;
+  let height = requested.height;
+  const pixels = width * height;
+
+  // 中文注释：gpt-image-2 要求总像素不少于 655360，且宽高均为 16 的倍数。
+  // 这里只把用户选择的 K 档和比例转换为 provider 可直接生成的真实尺寸，不做生成后放大。
+  if (pixels < 655_360) {
+    const scale = Math.sqrt(655_360 / pixels);
+    width *= scale;
+    height *= scale;
+  }
+
+  return {
+    width: alignImageDimensionUp(width),
+    height: alignImageDimensionUp(height),
+  };
+}
+
 export function resolveEditorImageGenerationPixelSize({
+  model,
   aspectRatio,
   imageSize,
 }: {
@@ -181,6 +212,9 @@ export function resolveEditorImageGenerationPixelSize({
   aspectRatio: string | null | undefined;
   imageSize: string | null | undefined;
 }): EditorImageFrameSize {
+  if (model?.trim() === IMAGE_MODEL_GPT_IMAGE_2) {
+    return resolveGptImage2FrameSize({ aspectRatio, imageSize });
+  }
   return resolveImageFrameSizeFromRatio({ aspectRatio, imageSize });
 }
 
@@ -225,9 +259,9 @@ export function inferEditorImageSizeLabel(width: number, height: number) {
   return '1K';
 }
 
-export function resizeGenerationPlaceholderToImageSelection(
-  dialog: GenerateDialogState,
-): GenerateDialogState {
+export function resizeGenerationPlaceholderToImageSelection<
+  T extends GenerateDialogState,
+>(dialog: T): T {
   if (!dialog.placeholder) {
     return dialog;
   }
@@ -249,7 +283,7 @@ export function resizeGenerationPlaceholderToImageSelection(
       originalWidth: size.width,
       originalHeight: size.height,
     },
-  };
+  } as T;
 }
 
 function resolveEvenVideoWidth(
@@ -411,7 +445,6 @@ export const SEEDANCE_VIDEO_REFERENCE_LIMITS = {
   image: 9,
   video: 3,
   audio: 3,
-  requestBytes: 64 * 1024 * 1024,
 } as const;
 export const QUICK_EDIT_REFERENCE_LIMIT = 8;
 export const CHARACTER_ANIMATION_ACTION_PROMPTS = [
diff --git a/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
index ea26a79ab..f0ce14963 100644
--- a/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
@@ -1,14 +1,14 @@
 import { describe, expect, it } from 'vitest';
 
-import {
-  chooseGenerationPlacement,
-  centerViewportOnPlacement,
-} from './ImageCanvasGenerationPlacementModel';
 import type {
   CanvasGenerationDialogState,
   CanvasLayer,
   CanvasViewport,
 } from './ImageCanvasEditorTypes';
+import {
+  centerViewportOnPlacement,
+  chooseGenerationPlacement,
+} from './ImageCanvasGenerationPlacementModel';
 
 const canvasSize = { width: 900, height: 640 };
 const viewport: CanvasViewport = { x: 10, y: 20, scale: 2 };
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
index 4ce5c8dbe..fd46c6e25 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
@@ -1,15 +1,15 @@
 import { describe, expect, it } from 'vitest';
 
 import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import {
+  IMAGE_MODEL_GPT_IMAGE_2,
+  IMAGE_MODEL_NANOBANANA2,
+} from './ImageCanvasGenerationModel';
 import {
   buildCharacterAnimationSubmissionPlan,
   buildIconSpritesheetGenerationSubmissionPlan,
   buildImageGenerationSubmissionPlan,
 } from './ImageCanvasGenerationSubmissionModel';
-import {
-  IMAGE_MODEL_GPT_IMAGE_2,
-  IMAGE_MODEL_NANOBANANA2,
-} from './ImageCanvasGenerationModel';
 
 function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
   return {
@@ -467,6 +467,7 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
         referenceImageSrcs: ['data:image/png;base64,ref'],
       },
       result: {
+        assetKind: 'publication-material',
         title: '10 宣发素材',
         generationInputs: {
           fields: [
@@ -521,6 +522,7 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
         imageSize: '1K',
       },
       result: {
+        assetKind: 'publication-material',
         title: '11 宣发素材',
       },
     });
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
index 4b073e855..2dae49c16 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
@@ -91,11 +91,6 @@ export function resolveImageReferenceSubmissionSource(reference: {
   return reference.objectKey?.trim() || reference.src;
 }
 
-function estimateReferenceRequestBytes(references: Array<{ src: string }>) {
-  // 中文注释：JSON 包装字段还有少量额外字节；这里按 src 字符串长度估算，前后端都会再兜底校验 64MB。
-  return references.reduce((sum, reference) => sum + reference.src.length, 0);
-}
-
 function buildSeedanceVideoReferenceInput(
   references: NonNullable<GenerateDialogState['generationReferences']>,
 ) {
@@ -129,13 +124,6 @@ function buildSeedanceVideoReferenceInput(
   ) {
     throw new Error('参考音频必须搭配参考图片或参考视频');
   }
-  if (
-    estimateReferenceRequestBytes(references) >
-    SEEDANCE_VIDEO_REFERENCE_LIMITS.requestBytes
-  ) {
-    throw new Error('参考文件总请求体不能超过 64MB');
-  }
-
   return {
     referenceImageSrcs: imageReferences.map(resolveReferenceSource),
     referenceVideoSrcs: videoReferences.map(resolveReferenceSource),
@@ -454,6 +442,7 @@ export function buildImageGenerationSubmissionPlan({
           : {}),
       },
       result: {
+        assetKind: 'publication-material',
         title: resolveGenerationAssetLabel(
           dialog.assetLabel,
           `${nextGeneratedIndex} 宣发素材`,
diff --git a/src/components/image-editor/ImageCanvasHistoryModel.test.ts b/src/components/image-editor/ImageCanvasHistoryModel.test.ts
new file mode 100644
index 000000000..df80f1392
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasHistoryModel.test.ts
@@ -0,0 +1,614 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasHistorySnapshot,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  canRestoreCanvasHistorySnapshotWithoutContentLoss,
+  formatCanvasHistoryAction,
+  isProtectedCanvasHistoryAction,
+  mergeCanvasHistorySnapshotForRestore,
+} from './ImageCanvasHistoryModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '图片',
+    src: '/image-1.png',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    originalWidth: 100,
+    originalHeight: 100,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createSnapshot(layers: CanvasLayer[]): CanvasHistorySnapshot {
+  return {
+    layers,
+    viewport: { x: 0, y: 0, scale: 1 },
+    generateDialog: null,
+    inactiveGenerateDialogs: [],
+    selectedLayerId: null,
+    selectedLayerIds: [],
+  };
+}
+
+describe('ImageCanvasHistoryModel', () => {
+  it('allows restoring position and restoring a previously deleted layer', () => {
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([createLayer({ x: 80 })]),
+        target: createSnapshot([createLayer({ x: 10 })]),
+      }),
+    ).toBe(true);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([createLayer({ resourceId: 'resource-new' })]),
+        target: createSnapshot([createLayer({ resourceId: 'resource-old' })]),
+      }),
+    ).toBe(true);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([]),
+        target: createSnapshot([createLayer()]),
+      }),
+    ).toBe(true);
+  });
+
+  it('blocks removing, hiding, or replacing current canvas content', () => {
+    const current = createSnapshot([createLayer()]);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current,
+        target: createSnapshot([]),
+      }),
+    ).toBe(false);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current,
+        target: createSnapshot([createLayer({ hidden: true })]),
+      }),
+    ).toBe(false);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current,
+        target: createSnapshot([
+          createLayer({ resourceId: 'resource-old', src: '/old.png' }),
+        ]),
+      }),
+    ).toBe(false);
+  });
+
+  it('ignores asynchronously filled relation ids for unchanged media content', () => {
+    const targetLayer = createLayer({
+      resourceId: 'local-resource',
+      sourceResourceId: undefined,
+      sourceAssetId: undefined,
+      objectKey: 'uploads/same.png',
+      assetObjectId: 'asset-object-same',
+      x: 10,
+    });
+    const currentLayer = createLayer({
+      resourceId: 'persisted-resource',
+      sourceResourceId: 'source-resource-late',
+      sourceAssetId: 'source-asset-late',
+      objectKey: 'uploads/same.png',
+      assetObjectId: 'asset-object-same',
+      x: 80,
+    });
+
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([currentLayer]),
+        target: createSnapshot([targetLayer]),
+      }),
+    ).toBe(true);
+  });
+
+  it('restores only reversible layer fields while preserving current content metadata', () => {
+    const targetLayer = createLayer({
+      resourceId: 'local-resource',
+      title: '旧标题',
+      src: '/signed/old.png',
+      thumbnailSrc: '/signed/old-thumbnail.png',
+      x: 10,
+      y: 20,
+      width: 320,
+      height: 240,
+      originalWidth: 320,
+      originalHeight: 240,
+      zIndex: 1,
+      prompt: '旧提示词',
+      objectKey: 'uploads/stable.png',
+      assetObjectId: 'asset-object-stable',
+      sourceResourceId: undefined,
+      sourceAssetId: undefined,
+      groupId: 'target-group',
+      assetKind: 'spec',
+      hidden: false,
+      locked: false,
+      flipX: true,
+      flipY: false,
+    });
+    const currentLayer = createLayer({
+      resourceId: 'persisted-resource',
+      title: '当前标题',
+      src: '/signed/current.png',
+      thumbnailSrc: '/signed/current-thumbnail.png',
+      x: 90,
+      y: 80,
+      width: 640,
+      height: 480,
+      originalWidth: 640,
+      originalHeight: 480,
+      zIndex: 9,
+      prompt: '当前提示词',
+      objectKey: 'uploads/stable.png',
+      assetObjectId: 'asset-object-stable',
+      sourceResourceId: 'source-resource-late',
+      sourceAssetId: 'source-asset-late',
+      groupId: 'current-group',
+      assetKind: 'ui-design',
+      hidden: true,
+      locked: true,
+      flipX: false,
+      flipY: true,
+    });
+
+    const merged = mergeCanvasHistorySnapshotForRestore({
+      current: createSnapshot([currentLayer]),
+      target: createSnapshot([targetLayer]),
+    });
+
+    expect(merged.layers).toEqual([
+      {
+        ...currentLayer,
+        x: targetLayer.x,
+        y: targetLayer.y,
+        zIndex: targetLayer.zIndex,
+        groupId: targetLayer.groupId,
+        assetKind: targetLayer.assetKind,
+        hidden: targetLayer.hidden,
+        locked: targetLayer.locked,
+        flipX: targetLayer.flipX,
+        flipY: targetLayer.flipY,
+      },
+    ]);
+  });
+
+  it('restores the complete target layer after that layer was deleted', () => {
+    const targetLayer = createLayer({
+      resourceId: 'deleted-resource',
+      title: '被删除图片',
+      x: 10,
+      y: 20,
+      width: 320,
+      height: 240,
+    });
+
+    const merged = mergeCanvasHistorySnapshotForRestore({
+      current: createSnapshot([]),
+      target: createSnapshot([targetLayer]),
+    });
+
+    expect(merged.layers).toEqual([targetLayer]);
+  });
+
+  it('uses stable media references while blocking actual media replacement', () => {
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([
+          createLayer({
+            src: '/signed/current.png',
+            objectKey: 'uploads/stable.png',
+          }),
+        ]),
+        target: createSnapshot([
+          createLayer({
+            src: '/signed/expired.png',
+            objectKey: 'uploads/stable.png',
+          }),
+        ]),
+      }),
+    ).toBe(true);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([createLayer({ src: '/current.png' })]),
+        target: createSnapshot([createLayer({ src: '/target.png' })]),
+      }),
+    ).toBe(false);
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([
+          createLayer({ objectKey: 'uploads/current.png' }),
+        ]),
+        target: createSnapshot([
+          createLayer({ objectKey: 'uploads/target.png' }),
+        ]),
+      }),
+    ).toBe(false);
+  });
+
+  it('blocks replacing an image sequence frame', () => {
+    const frame = {
+      frameIndex: 0,
+      imageSrc: '/frames/0.png',
+      objectKey: 'frames/0.png',
+      width: 100,
+      height: 100,
+    };
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: createSnapshot([
+          createLayer({
+            mediaType: 'image-sequence',
+            imageSequenceFrames: [
+              { ...frame, objectKey: 'frames/replacement.png' },
+            ],
+          }),
+        ]),
+        target: createSnapshot([
+          createLayer({
+            mediaType: 'image-sequence',
+            imageSequenceFrames: [frame],
+          }),
+        ]),
+      }),
+    ).toBe(false);
+  });
+
+  it('blocks removing a current generation result from the target snapshot', () => {
+    const current = createSnapshot([]);
+    current.inactiveGenerateDialogs = [
+      {
+        id: 'generation-1',
+        mode: 'generate',
+        prompt: '生成结果',
+        status: 'idle',
+      },
+    ];
+
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current,
+        target: createSnapshot([]),
+      }),
+    ).toBe(false);
+
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-1',
+      mode: 'generate',
+      prompt: '生成结果',
+      status: 'idle',
+    };
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({ current, target }),
+    ).toBe(true);
+  });
+
+  it('protects an edit draft and preserves its latest unsaved state', () => {
+    const current = createSnapshot([createLayer({ x: 80 })]);
+    current.generateDialog = {
+      id: 'edit-dialog:layer-1',
+      mode: 'edit',
+      prompt: '当前未保存提示词',
+      status: 'idle',
+      composerOpen: true,
+      sourceLayerId: 'layer-1',
+      imageModel: 'gpt-image-2',
+    };
+    const targetWithoutDraft = createSnapshot([createLayer({ x: 10 })]);
+
+    expect(
+      canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current,
+        target: targetWithoutDraft,
+      }),
+    ).toBe(false);
+
+    const targetWithOlderDraft = createSnapshot([createLayer({ x: 10 })]);
+    targetWithOlderDraft.generateDialog = {
+      ...current.generateDialog,
+      prompt: '旧提示词',
+    };
+    const merged = mergeCanvasHistorySnapshotForRestore({
+      current,
+      target: targetWithOlderDraft,
+    });
+
+    expect(merged.generateDialog).toMatchObject({
+      id: 'edit-dialog:layer-1',
+      prompt: '当前未保存提示词',
+      composerOpen: true,
+    });
+  });
+
+  it('restores only position for an existing generation dialog', () => {
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-1',
+      mode: 'character-animation',
+      prompt: '旧提示词',
+      status: 'idle',
+      imageSize: '1K',
+      generationReferences: [{ id: 'old', label: '旧参考图', src: '/old.png' }],
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 320,
+        height: 240,
+        originalWidth: 320,
+        originalHeight: 240,
+      },
+    };
+    const current = createSnapshot([]);
+    current.generateDialog = {
+      id: 'generation-1',
+      mode: 'character-animation',
+      prompt: '当前提示词',
+      status: 'generating',
+      imageSize: '2K',
+      generatedLayerId: 'generated-layer-1',
+      generationReferences: [
+        { id: 'current', label: '当前参考图', src: '/current.png' },
+      ],
+      generationStartedAt: 100,
+      placeholder: {
+        x: 90,
+        y: 80,
+        width: 640,
+        height: 480,
+        originalWidth: 640,
+        originalHeight: 480,
+      },
+    };
+
+    const merged = mergeCanvasHistorySnapshotForRestore({ current, target });
+
+    expect(merged.generateDialog).toMatchObject({
+      id: 'generation-1',
+      prompt: '当前提示词',
+      status: 'generating',
+      imageSize: '2K',
+      generatedLayerId: 'generated-layer-1',
+      generationStartedAt: 100,
+      generationReferences: [
+        { id: 'current', label: '当前参考图', src: '/current.png' },
+      ],
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 640,
+        height: 480,
+        originalWidth: 640,
+        originalHeight: 480,
+      },
+    });
+  });
+
+  it('uses the target placeholder when the current dialog has none', () => {
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-1',
+      mode: 'generate',
+      prompt: '旧提示词',
+      status: 'idle',
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 320,
+        height: 240,
+        originalWidth: 320,
+        originalHeight: 240,
+      },
+    };
+    const current = createSnapshot([]);
+    current.generateDialog = {
+      id: 'generation-1',
+      mode: 'generate',
+      prompt: '当前提示词',
+      status: 'generating',
+      imageSize: '2K',
+    };
+
+    const merged = mergeCanvasHistorySnapshotForRestore({ current, target });
+
+    expect(merged.generateDialog).toMatchObject({
+      prompt: '当前提示词',
+      status: 'generating',
+      imageSize: '2K',
+      placeholder: target.generateDialog.placeholder,
+    });
+  });
+
+  it('keeps the target active state while preserving current dialog progress', () => {
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-a',
+      mode: 'generate',
+      prompt: 'A 旧提示词',
+      status: 'idle',
+      composerOpen: true,
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 320,
+        height: 240,
+        originalWidth: 320,
+        originalHeight: 240,
+      },
+    };
+    target.inactiveGenerateDialogs = [
+      {
+        id: 'generation-b',
+        mode: 'icon',
+        prompt: 'B 旧提示词',
+        status: 'idle',
+        composerOpen: false,
+        placeholder: {
+          x: 30,
+          y: 40,
+          width: 320,
+          height: 240,
+          originalWidth: 320,
+          originalHeight: 240,
+        },
+      },
+    ];
+
+    const current = createSnapshot([]);
+    current.generateDialog = {
+      id: 'generation-b',
+      mode: 'icon',
+      prompt: 'B 当前提示词',
+      status: 'generating',
+      composerOpen: true,
+      imageSize: '2K',
+      placeholder: {
+        x: 90,
+        y: 80,
+        width: 640,
+        height: 480,
+        originalWidth: 640,
+        originalHeight: 480,
+      },
+    };
+    current.inactiveGenerateDialogs = [
+      {
+        id: 'generation-a',
+        mode: 'generate',
+        prompt: 'A 当前提示词',
+        status: 'generating',
+        composerOpen: false,
+        imageSize: '2K',
+        placeholder: {
+          x: 70,
+          y: 60,
+          width: 640,
+          height: 480,
+          originalWidth: 640,
+          originalHeight: 480,
+        },
+      },
+    ];
+
+    const merged = mergeCanvasHistorySnapshotForRestore({ current, target });
+
+    expect(merged.generateDialog).toMatchObject({
+      id: 'generation-a',
+      prompt: 'A 当前提示词',
+      status: 'generating',
+      composerOpen: true,
+      imageSize: '2K',
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 640,
+        height: 480,
+        originalWidth: 640,
+        originalHeight: 480,
+      },
+    });
+    expect(merged.inactiveGenerateDialogs).toEqual([
+      expect.objectContaining({
+        id: 'generation-b',
+        prompt: 'B 当前提示词',
+        status: 'generating',
+        composerOpen: false,
+        imageSize: '2K',
+        placeholder: {
+          x: 30,
+          y: 40,
+          width: 640,
+          height: 480,
+          originalWidth: 640,
+          originalHeight: 480,
+        },
+      }),
+    ]);
+  });
+
+  it('keeps the current placeholder when the target dialog has none', () => {
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-1',
+      mode: 'generate',
+      prompt: '旧提示词',
+      status: 'idle',
+      composerOpen: true,
+    };
+    const current = createSnapshot([]);
+    current.generateDialog = {
+      id: 'generation-1',
+      mode: 'generate',
+      prompt: '当前提示词',
+      status: 'generating',
+      composerOpen: false,
+      imageSize: '2K',
+      placeholder: {
+        x: 90,
+        y: 80,
+        width: 640,
+        height: 480,
+        originalWidth: 640,
+        originalHeight: 480,
+      },
+    };
+
+    const merged = mergeCanvasHistorySnapshotForRestore({ current, target });
+
+    expect(merged.generateDialog).toMatchObject({
+      prompt: '当前提示词',
+      status: 'generating',
+      composerOpen: true,
+      imageSize: '2K',
+      placeholder: current.generateDialog.placeholder,
+    });
+  });
+
+  it('restores the complete target dialog after that dialog was deleted', () => {
+    const target = createSnapshot([]);
+    target.generateDialog = {
+      id: 'generation-deleted',
+      mode: 'generate',
+      prompt: '被删除的生成框',
+      status: 'idle',
+      generationReferences: [
+        { id: 'reference-1', label: '参考图', src: '/reference.png' },
+      ],
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 320,
+        height: 240,
+        originalWidth: 320,
+        originalHeight: 240,
+      },
+    };
+
+    const merged = mergeCanvasHistorySnapshotForRestore({
+      current: createSnapshot([]),
+      target,
+    });
+
+    expect(merged.generateDialog).toEqual(target.generateDialog);
+  });
+
+  it('formats action names without duplicating the 操作 suffix', () => {
+    expect(formatCanvasHistoryAction({ type: 'replace-image' })).toBe(
+      '替换图片',
+    );
+    expect(isProtectedCanvasHistoryAction({ type: 'replace-image' })).toBe(
+      true,
+    );
+    expect(isProtectedCanvasHistoryAction({ type: 'move-image' })).toBe(false);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasHistoryModel.ts b/src/components/image-editor/ImageCanvasHistoryModel.ts
new file mode 100644
index 000000000..6f2c2dd71
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasHistoryModel.ts
@@ -0,0 +1,261 @@
+import type {
+  CanvasGenerationDialogState,
+  CanvasHistoryAction,
+  CanvasHistorySnapshot,
+  CanvasLayer,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+
+const CANVAS_HISTORY_ACTION_LABELS: Record<
+  CanvasHistoryAction['type'],
+  string
+> = {
+  'move-image': '移动图片',
+  'move-generation-result': '移动生成结果',
+  'delete-image': '删除图片',
+  'delete-generation-result': '删除生成结果',
+  'cut-image': '剪切图片',
+  'paste-image': '粘贴图片',
+  'duplicate-image': '复制图片',
+  'add-image': '添加图片',
+  'upload-image': '上传图片',
+  'generate-image': '生成图片',
+  'expand-image': '扩展图片',
+  'remove-background': '移除背景',
+  'split-atlas': '拆分图集',
+  'replace-image': '替换图片',
+  'show-image': '显示图片',
+  'hide-image': '隐藏图片',
+  'change-layer-order': '调整图片层级',
+  'group-images': '组合图片',
+  'ungroup-images': '取消组合',
+  'lock-image': '锁定图片',
+  'unlock-image': '解锁图片',
+  'flip-image': '翻转图片',
+  'change-asset-kind': '修改素材类型',
+  'change-viewport': '调整画布视图',
+};
+
+const PROTECTED_CANVAS_HISTORY_ACTION_TYPES = new Set<
+  CanvasHistoryAction['type']
+>([
+  'paste-image',
+  'duplicate-image',
+  'add-image',
+  'upload-image',
+  'generate-image',
+  'expand-image',
+  'remove-background',
+  'split-atlas',
+  'replace-image',
+]);
+
+export function formatCanvasHistoryAction(action: CanvasHistoryAction): string {
+  return CANVAS_HISTORY_ACTION_LABELS[action.type];
+}
+
+export function isProtectedCanvasHistoryAction(
+  action: CanvasHistoryAction,
+): boolean {
+  return PROTECTED_CANVAS_HISTORY_ACTION_TYPES.has(action.type);
+}
+
+function hasSameStableMediaReference(
+  current: {
+    src: string;
+    objectKey?: string | null;
+    assetObjectId?: string | null;
+  },
+  target: {
+    src: string;
+    objectKey?: string | null;
+    assetObjectId?: string | null;
+  },
+): boolean {
+  if (current.objectKey && target.objectKey) {
+    return current.objectKey === target.objectKey;
+  }
+  if (current.assetObjectId && target.assetObjectId) {
+    return current.assetObjectId === target.assetObjectId;
+  }
+  return current.src === target.src;
+}
+
+function hasSameImageSequenceFrames(
+  current: CanvasLayer,
+  target: CanvasLayer,
+): boolean {
+  const currentFrames = current.imageSequenceFrames ?? [];
+  const targetFrames = target.imageSequenceFrames ?? [];
+  if (currentFrames.length !== targetFrames.length) {
+    return false;
+  }
+  return currentFrames.every((currentFrame, index) => {
+    const targetFrame = targetFrames[index];
+    return (
+      targetFrame !== undefined &&
+      currentFrame.frameIndex === targetFrame.frameIndex &&
+      hasSameStableMediaReference(
+        {
+          src: currentFrame.imageSrc,
+          objectKey: currentFrame.objectKey,
+          assetObjectId: currentFrame.assetObjectId,
+        },
+        {
+          src: targetFrame.imageSrc,
+          objectKey: targetFrame.objectKey,
+          assetObjectId: targetFrame.assetObjectId,
+        },
+      )
+    );
+  });
+}
+
+function hasSameLayerContent(
+  current: CanvasLayer,
+  target: CanvasLayer,
+): boolean {
+  return (
+    (current.mediaType ?? 'image') === (target.mediaType ?? 'image') &&
+    hasSameStableMediaReference(current, target) &&
+    hasSameImageSequenceFrames(current, target)
+  );
+}
+
+function cloneDialogPlaceholder(
+  dialog: GenerateDialogState,
+): GenerateDialogState['placeholder'] {
+  return dialog.placeholder ? { ...dialog.placeholder } : undefined;
+}
+
+function mergeLayerForHistoryRestore(
+  target: CanvasLayer,
+  current: CanvasLayer | undefined,
+): CanvasLayer {
+  if (!current) {
+    return { ...target };
+  }
+  return {
+    ...current,
+    x: target.x,
+    y: target.y,
+    zIndex: target.zIndex,
+    groupId: target.groupId,
+    assetKind: target.assetKind,
+    hidden: target.hidden,
+    locked: target.locked,
+    flipX: target.flipX,
+    flipY: target.flipY,
+  };
+}
+
+function mergeDialogPlaceholderForHistoryRestore(
+  target: GenerateDialogState,
+  current: GenerateDialogState,
+): GenerateDialogState['placeholder'] {
+  if (!current.placeholder) {
+    return cloneDialogPlaceholder(target);
+  }
+  if (!target.placeholder) {
+    return cloneDialogPlaceholder(current);
+  }
+  return {
+    ...current.placeholder,
+    x: target.placeholder.x,
+    y: target.placeholder.y,
+  };
+}
+
+function mergeDialogForHistoryRestore<
+  TTarget extends GenerateDialogState,
+  TCurrent extends GenerateDialogState,
+>(target: TTarget, current: TCurrent | undefined): TTarget | TCurrent {
+  if (!current) {
+    return {
+      ...target,
+      placeholder: cloneDialogPlaceholder(target),
+    };
+  }
+  return {
+    ...current,
+    composerOpen: target.composerOpen,
+    placeholder: mergeDialogPlaceholderForHistoryRestore(target, current),
+  };
+}
+
+export function mergeCanvasHistorySnapshotForRestore({
+  current,
+  target,
+}: {
+  current: CanvasHistorySnapshot;
+  target: CanvasHistorySnapshot;
+}): CanvasHistorySnapshot {
+  const currentLayerById = new Map(
+    current.layers.map((layer) => [layer.id, layer] as const),
+  );
+  const currentDialogById = new Map<string, GenerateDialogState>();
+  for (const dialog of current.inactiveGenerateDialogs) {
+    currentDialogById.set(dialog.id, dialog);
+  }
+  if (current.generateDialog?.id) {
+    currentDialogById.set(current.generateDialog.id, current.generateDialog);
+  }
+
+  const mergeTargetDialog = <T extends GenerateDialogState>(dialog: T): T =>
+    mergeDialogForHistoryRestore(
+      dialog,
+      dialog.id ? currentDialogById.get(dialog.id) : undefined,
+    ) as T;
+
+  return {
+    ...target,
+    layers: target.layers.map((layer) =>
+      mergeLayerForHistoryRestore(layer, currentLayerById.get(layer.id)),
+    ),
+    generateDialog: target.generateDialog
+      ? mergeTargetDialog(target.generateDialog)
+      : null,
+    inactiveGenerateDialogs: target.inactiveGenerateDialogs.map(
+      (dialog): CanvasGenerationDialogState => mergeTargetDialog(dialog),
+    ),
+  };
+}
+
+export function canRestoreCanvasHistorySnapshotWithoutContentLoss({
+  current,
+  target,
+}: {
+  current: CanvasHistorySnapshot;
+  target: CanvasHistorySnapshot;
+}): boolean {
+  const targetLayerById = new Map(
+    target.layers.map((layer) => [layer.id, layer] as const),
+  );
+
+  const preservesLayers = current.layers.every((currentLayer) => {
+    const targetLayer = targetLayerById.get(currentLayer.id);
+    if (!targetLayer) {
+      return false;
+    }
+    if (!currentLayer.hidden && targetLayer.hidden) {
+      return false;
+    }
+    return hasSameLayerContent(currentLayer, targetLayer);
+  });
+  if (!preservesLayers) {
+    return false;
+  }
+
+  const getDialogIds = (snapshot: CanvasHistorySnapshot): Set<string> =>
+    new Set(
+      [
+        snapshot.generateDialog?.id,
+        ...snapshot.inactiveGenerateDialogs.map((dialog) => dialog.id),
+      ].filter((dialogId): dialogId is string => Boolean(dialogId)),
+    );
+  const targetDialogIds = getDialogIds(target);
+
+  return [...getDialogIds(current)].every((dialogId) =>
+    targetDialogIds.has(dialogId),
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx
index 10cc79936..17a49a7ed 100644
--- a/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx
+++ b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx
@@ -21,7 +21,6 @@ import type {
 import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
 import {
   calculateEditorIconSpritesheetPrice,
-  DEFAULT_ICON_DESCRIPTIONS,
 } from './ImageCanvasGenerationModel';
 import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
diff --git a/src/components/image-editor/ImageCanvasInteractionModel.test.ts b/src/components/image-editor/ImageCanvasInteractionModel.test.ts
index 0e677d3ee..f9579cf51 100644
--- a/src/components/image-editor/ImageCanvasInteractionModel.test.ts
+++ b/src/components/image-editor/ImageCanvasInteractionModel.test.ts
@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest';
 
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  DragState,
+} from './ImageCanvasEditorTypes';
 import {
   createMinimapModel,
   fitViewportToBounds,
@@ -7,9 +12,9 @@ import {
   getCanvasDropPoint,
   getCanvasPointFromClient,
   getWorldPointFromClient,
+  moveDragSelectedLayers,
   moveGenerationFrameFromDrag,
   moveGenerationFramesFromDrag,
-  moveDragSelectedLayers,
   moveLayersFromDrag,
   moveViewportFromMinimapDrag,
   moveViewportFromMinimapPointer,
@@ -20,11 +25,6 @@ import {
   selectLayersInsideMarquee,
   zoomViewportFromWheel,
 } from './ImageCanvasInteractionModel';
-import type {
-  CanvasGenerationDialogState,
-  CanvasLayer,
-  DragState,
-} from './ImageCanvasEditorTypes';
 import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 
 function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
diff --git a/src/components/image-editor/ImageCanvasInteractionModel.ts b/src/components/image-editor/ImageCanvasInteractionModel.ts
index 664c9ca91..3780870d8 100644
--- a/src/components/image-editor/ImageCanvasInteractionModel.ts
+++ b/src/components/image-editor/ImageCanvasInteractionModel.ts
@@ -1,5 +1,17 @@
 import type { CSSProperties } from 'react';
 
+import {
+  clamp,
+  DEFAULT_CANVAS_SIZE,
+  FIT_VIEW_PADDING,
+  getLayerBounds,
+  MAX_SCALE,
+  MIN_SCALE,
+  MINIMAP_DRAG_SENSITIVITY,
+  MINIMAP_PADDING,
+  MINIMAP_SIZE,
+  resolveSnappedItemPosition,
+} from './ImageCanvasEditorModel';
 import type {
   CanvasGenerationDialogState,
   CanvasLayer,
@@ -7,18 +19,6 @@ import type {
   CanvasViewport,
   DragState,
 } from './ImageCanvasEditorTypes';
-import {
-  DEFAULT_CANVAS_SIZE,
-  FIT_VIEW_PADDING,
-  MAX_SCALE,
-  MIN_SCALE,
-  MINIMAP_DRAG_SENSITIVITY,
-  MINIMAP_PADDING,
-  MINIMAP_SIZE,
-  clamp,
-  getLayerBounds,
-  resolveSnappedItemPosition,
-} from './ImageCanvasEditorModel';
 import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 
 export type CanvasSize = {
diff --git a/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts b/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts
index 4cc91f02a..88b353c96 100644
--- a/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts
+++ b/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
 
+import type {
+  CanvasContextMenuState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
 import {
   createCanvasLayerClipboard,
   duplicateCanvasLayers,
@@ -13,10 +17,6 @@ import {
   toggleCanvasLayersVisibility,
   ungroupCanvasLayers,
 } from './ImageCanvasLayerCommandModel';
-import type {
-  CanvasContextMenuState,
-  CanvasLayer,
-} from './ImageCanvasEditorTypes';
 
 function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
   const id = overrides.id ?? 'layer-a';
diff --git a/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx b/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx
index cdabe319f..41ab7a9aa 100644
--- a/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx
+++ b/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx
@@ -64,7 +64,6 @@ describe('ImageCanvasMetadataModalView', () => {
     expect(within(dialog).queryByText(/VectorEngine/u)).toBeNull();
     expect(within(dialog).queryByText(/task-/u)).toBeNull();
     expect(within(dialog).getByText('123')).toBeTruthy();
-    expect(within(dialog).getByText('generated/object.png')).toBeTruthy();
   });
 
   it('renders nanobanana2 instead of the raw Gemini image model id', () => {
@@ -108,7 +107,6 @@ describe('ImageCanvasMetadataModalView', () => {
     expect(within(dialog).queryByText('上传素材')).toBeNull();
     expect(within(dialog).getByText('上传图片')).toBeTruthy();
     expect(within(dialog).getAllByText('-').length).toBeGreaterThanOrEqual(3);
-    expect(within(dialog).getByText('asset-object-1')).toBeTruthy();
 
     fireEvent.click(within(dialog).getByRole('button', { name: '关闭图片信息' }));
 
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.test.tsx b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
index a594faf01..65d36a7ec 100644
--- a/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
+++ b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
@@ -14,7 +14,7 @@ function renderPanelDock(
     canvasBackgroundColor: '#f8fafc',
     canvasBackgroundHexValue: '#f8fafc',
     canUndo: true,
-    canRedo: false,
+    canRedo: true,
     isZoomMenuOpen: false,
     isBackgroundSettingsOpen: false,
     activeSidebarPanel: null,
@@ -83,17 +83,12 @@ describe('ImageCanvasPanelDockView', () => {
         .getByRole('button', { name: '打开素材' })
         .getAttribute('aria-pressed'),
     ).toBe('true');
-    expect(
-      (
-        within(toolbar).getByRole('button', {
-          name: '重做',
-        }) as HTMLButtonElement
-      ).disabled,
-    ).toBe(true);
+    expect(within(toolbar).getByRole('button', { name: '恢复' })).toBeTruthy();
     expect(screen.getByRole('button', { name: '画布小地图' })).toBeTruthy();
 
     fireEvent.click(screen.getByRole('button', { name: '重置画布视图' }));
     fireEvent.click(within(toolbar).getByRole('button', { name: '撤销' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '恢复' }));
     fireEvent.click(within(toolbar).getByRole('button', { name: '打开图层' }));
     fireEvent.click(
       within(toolbar).getByRole('button', { name: '画布 Agent' }),
@@ -104,6 +99,7 @@ describe('ImageCanvasPanelDockView', () => {
 
     expect(props.onFitLayers).toHaveBeenCalledTimes(1);
     expect(props.onUndoCanvasChange).toHaveBeenCalledTimes(1);
+    expect(props.onRedoCanvasChange).toHaveBeenCalledTimes(1);
     expect(props.onToggleSidebarPanel).toHaveBeenCalledWith('layers');
     expect(props.onToggleAgentConversation).toHaveBeenCalledTimes(1);
     expect(props.onToggleMinimap).toHaveBeenCalledTimes(1);
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.tsx b/src/components/image-editor/ImageCanvasPanelDockView.tsx
index 02b04642a..c53f0b755 100644
--- a/src/components/image-editor/ImageCanvasPanelDockView.tsx
+++ b/src/components/image-editor/ImageCanvasPanelDockView.tsx
@@ -8,12 +8,12 @@ import {
   Undo2,
   X,
 } from 'lucide-react';
-import { useEffect, useRef } from 'react';
 import type {
   CSSProperties,
   KeyboardEvent as ReactKeyboardEvent,
   PointerEvent as ReactPointerEvent,
 } from 'react';
+import { useEffect, useRef } from 'react';
 
 import {
   PlatformFloatingMenu,
@@ -338,8 +338,8 @@ export function ImageCanvasPanelDockView({
           onClick={onUndoCanvasChange}
         />
         <EditorIconButton
-          label="重做"
-          title="重做"
+          label="恢复"
+          title="恢复上一次撤销"
           icon={Redo2}
           disabled={!canRedo}
           onClick={onRedoCanvasChange}
diff --git a/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx b/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx
index 8d96176ad..57837546d 100644
--- a/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx
+++ b/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx
@@ -14,7 +14,6 @@ import {
 } from '../common/PlatformFloatingMenu';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformTextField } from '../common/PlatformTextField';
-import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 import type {
   CharacterReferenceImage,
   GenerateDialogState,
@@ -29,6 +28,7 @@ import {
   IMAGE_MODEL_GPT_IMAGE_2,
 } from './ImageCanvasGenerationModel';
 import type { PublicationMaterialsWorkflow } from './ImageCanvasPublicationMaterialsModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
 
 type ImageCanvasPublicationMaterialsDemoPanelViewProps = {
   dialog: GenerateDialogState;
diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx
index 66953ef42..f59103f95 100644
--- a/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx
+++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx
@@ -1,20 +1,19 @@
-import { ImageIcon } from 'lucide-react';
 import {
   type CSSProperties,
   type Dispatch,
+  type ReactNode,
   type RefObject,
   type SetStateAction,
-  type ReactNode,
 } from 'react';
 
 import { ImageCanvasBasicGenerationComposerView } from './ImageCanvasBasicGenerationComposerView';
-import { QUICK_EDIT_REFERENCE_LIMIT } from './ImageCanvasGenerationModel';
 import type {
   CanvasLayer,
   GenerateDialogState,
   QuickEditPanelState,
   UploadTarget,
 } from './ImageCanvasEditorTypes';
+import { QUICK_EDIT_REFERENCE_LIMIT } from './ImageCanvasGenerationModel';
 
 export type ImageCanvasQuickEditPanelViewProps = {
   panel: QuickEditPanelState;
diff --git a/src/components/image-editor/ImageCanvasRasterEditModel.test.ts b/src/components/image-editor/ImageCanvasRasterEditModel.test.ts
index 6c541c5d1..e0fe9a7c3 100644
--- a/src/components/image-editor/ImageCanvasRasterEditModel.test.ts
+++ b/src/components/image-editor/ImageCanvasRasterEditModel.test.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
 
 import {
-  buildCropExpandInsetsFromFrame,
   buildCropExpandGeometry,
+  buildCropExpandInsetsFromFrame,
   buildCropExpandLayerPatch,
   parseCropExpandInsetValue,
 } from './ImageCanvasRasterEditModel';
diff --git a/src/components/image-editor/ImageCanvasRasterEditModel.ts b/src/components/image-editor/ImageCanvasRasterEditModel.ts
index 4db465040..6facd9461 100644
--- a/src/components/image-editor/ImageCanvasRasterEditModel.ts
+++ b/src/components/image-editor/ImageCanvasRasterEditModel.ts
@@ -1,7 +1,7 @@
 import {
-  removeEditorImageBackground,
   type EditorBackgroundRemovalInput,
   type EditorBackgroundRemovalResult,
+  removeEditorImageBackground,
 } from '../../services/image-editor/editorProjectClient';
 
 export type CropExpandInsets = {
diff --git a/src/components/image-editor/ImageCanvasReferenceSlot.tsx b/src/components/image-editor/ImageCanvasReferenceSlot.tsx
index f35b1e200..f0304f6e2 100644
--- a/src/components/image-editor/ImageCanvasReferenceSlot.tsx
+++ b/src/components/image-editor/ImageCanvasReferenceSlot.tsx
@@ -1,5 +1,5 @@
-import { type ReactNode, type RefObject } from 'react';
 import { X } from 'lucide-react';
+import { type ReactNode, type RefObject } from 'react';
 
 import { ResolvedAssetImage } from '../ResolvedAssetImage';
 
diff --git a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx
index 9ab35425c..ba91a51c7 100644
--- a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx
@@ -42,6 +42,7 @@ function renderSelectedToolbar(
     onOpenRedrawPanel: vi.fn(),
     onOpenCropExpandPanel: vi.fn(),
     onRemoveBackground: vi.fn(),
+    isSplittingIconSpritesheet: false,
     onSplitIconSpritesheet: vi.fn(),
     onExtractUiDesignAssets: vi.fn(),
     onOpenCharacterAnimationPanel: vi.fn(),
@@ -155,6 +156,33 @@ describe('ImageCanvasSelectedLayerToolbarView', () => {
     expect(props.onSplitIconSpritesheet).toHaveBeenCalledWith(layer);
   });
 
+  it('renders a disabled loading state while splitting an icon spritesheet', () => {
+    const layer = createLayer({
+      sourceType: 'generated',
+      assetKind: 'icon-spritesheet',
+    });
+    const props = renderSelectedToolbar({
+      selectedLayer: layer,
+      isSplittingIconSpritesheet: true,
+    });
+    const splitButton = screen.getByRole('button', { name: '拆图中' });
+
+    expect(splitButton.getAttribute('title')).toBe('拆图中');
+    expect(splitButton.getAttribute('aria-busy')).toBe('true');
+    expect((splitButton as HTMLButtonElement).disabled).toBe(true);
+    expect(splitButton.textContent).toContain('拆图中');
+    expect(splitButton.querySelector('.lucide-loader-circle')).toBeTruthy();
+    expect(
+      splitButton.querySelector('.lucide-loader-circle.animate-spin'),
+    ).toBeTruthy();
+    expect(splitButton.querySelector('.lucide-scissors')).toBeNull();
+
+    fireEvent.click(splitButton);
+    fireEvent.click(splitButton);
+
+    expect(props.onSplitIconSpritesheet).not.toHaveBeenCalled();
+  });
+
   it('keeps only remodel and download for audio layers', () => {
     const layer = createLayer({
       title: '游戏音效',
@@ -293,6 +321,7 @@ describe('ImageCanvasSelectedLayerToolbarView', () => {
         onOpenRedrawPanel={vi.fn()}
         onOpenCropExpandPanel={vi.fn()}
         onRemoveBackground={vi.fn()}
+        isSplittingIconSpritesheet={false}
         onSplitIconSpritesheet={vi.fn()}
         onExtractUiDesignAssets={vi.fn()}
         onOpenCharacterAnimationPanel={vi.fn()}
@@ -310,6 +339,7 @@ describe('ImageCanvasSelectedLayerToolbarView', () => {
         onOpenRedrawPanel={vi.fn()}
         onOpenCropExpandPanel={vi.fn()}
         onRemoveBackground={vi.fn()}
+        isSplittingIconSpritesheet={false}
         onSplitIconSpritesheet={vi.fn()}
         onExtractUiDesignAssets={vi.fn()}
         onOpenCharacterAnimationPanel={vi.fn()}
diff --git a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx
index 2f0550523..5c187ea95 100644
--- a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx
+++ b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx
@@ -2,6 +2,7 @@ import {
   Crop,
   Download,
   ImageOff,
+  Loader2,
   PersonStanding,
   Scissors,
   Sparkles,
@@ -21,6 +22,7 @@ type ImageCanvasSelectedLayerToolbarViewProps = {
   onOpenRedrawPanel: (layer: CanvasLayer) => void;
   onOpenCropExpandPanel: (layer: CanvasLayer) => void;
   onRemoveBackground: (layer: CanvasLayer) => void;
+  isSplittingIconSpritesheet: boolean;
   onSplitIconSpritesheet: (layer: CanvasLayer) => void;
   onExtractUiDesignAssets: (layer: CanvasLayer) => void;
   onOpenCharacterAnimationPanel: (layer: CanvasLayer) => void;
@@ -34,6 +36,7 @@ export function ImageCanvasSelectedLayerToolbarView({
   onOpenRedrawPanel,
   onOpenCropExpandPanel,
   onRemoveBackground,
+  isSplittingIconSpritesheet,
   onSplitIconSpritesheet,
   onExtractUiDesignAssets,
   onOpenCharacterAnimationPanel,
@@ -120,12 +123,20 @@ export function ImageCanvasSelectedLayerToolbarView({
       {selectedLayer.assetKind === 'icon-spritesheet' ? (
         <PlatformIconButton
           className="image-canvas-editor__floating-toolbar-text-button"
-          label="拆分图集"
-          title="拆分图集"
-          icon={<Scissors className="h-4 w-4" />}
+          label={isSplittingIconSpritesheet ? '拆图中' : '拆分图集'}
+          title={isSplittingIconSpritesheet ? '拆图中' : '拆分图集'}
+          icon={
+            isSplittingIconSpritesheet ? (
+              <Loader2 className="h-4 w-4 animate-spin" />
+            ) : (
+              <Scissors className="h-4 w-4" />
+            )
+          }
+          disabled={isSplittingIconSpritesheet}
+          aria-busy={isSplittingIconSpritesheet}
           onClick={() => onSplitIconSpritesheet(selectedLayer)}
         >
-          <span>拆分图集</span>
+          <span>{isSplittingIconSpritesheet ? '拆图中' : '拆分图集'}</span>
         </PlatformIconButton>
       ) : null}
       {selectedLayer.assetKind === 'ui-design' ? (
diff --git a/src/components/image-editor/ImageCanvasShortcutModel.ts b/src/components/image-editor/ImageCanvasShortcutModel.ts
index bddf89e5d..518793a36 100644
--- a/src/components/image-editor/ImageCanvasShortcutModel.ts
+++ b/src/components/image-editor/ImageCanvasShortcutModel.ts
@@ -16,7 +16,7 @@ export const IMAGE_CANVAS_SHORTCUT_SECTIONS: ImageCanvasShortcutSection[] = [
     title: '编辑',
     items: [
       { action: '撤销', keys: ['Ctrl', 'Z'], status: 'ready' },
-      { action: '重做', keys: ['Ctrl', 'Shift', 'Z'], status: 'ready' },
+      { action: '恢复', keys: ['Ctrl', 'Shift', 'Z'], status: 'ready' },
       { action: '全选画布元素', keys: ['Ctrl', 'A'], status: 'new' },
       { action: '复制选中图层', keys: ['Ctrl', 'C'], status: 'new' },
       { action: '粘贴图层', keys: ['Ctrl', 'V'], status: 'new' },
diff --git a/src/components/image-editor/ImageCanvasSidebarView.test.tsx b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
index 3605fa5a6..3062bf96e 100644
--- a/src/components/image-editor/ImageCanvasSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
@@ -4,16 +4,16 @@ import { fireEvent, render, screen, within } from '@testing-library/react';
 import { createRef } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
-import { ImageCanvasPanelDockView } from './ImageCanvasPanelDockView';
-import {
-  ImageCanvasSidebarView,
-  type ImageCanvasSidebarViewProps,
-} from './ImageCanvasSidebarView';
 import type {
   CanvasLayer,
   EditorAsset,
   EditorAssetFolder,
 } from './ImageCanvasEditorTypes';
+import { ImageCanvasPanelDockView } from './ImageCanvasPanelDockView';
+import {
+  ImageCanvasSidebarView,
+  type ImageCanvasSidebarViewProps,
+} from './ImageCanvasSidebarView';
 import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
 
 function createAsset(overrides: Partial<EditorAsset> = {}): EditorAsset {
diff --git a/src/components/image-editor/ImageCanvasSidebarView.tsx b/src/components/image-editor/ImageCanvasSidebarView.tsx
index 95430ac21..2fb1e8043 100644
--- a/src/components/image-editor/ImageCanvasSidebarView.tsx
+++ b/src/components/image-editor/ImageCanvasSidebarView.tsx
@@ -12,17 +12,17 @@ import type {
 import { useMemo, useState } from 'react';
 
 import { PlatformTextField } from '../common/PlatformTextField';
-import {
-  ImageCanvasAssetLibraryPanelView,
-  type GroupedEditorAssetFolder,
-  type UploadFilesOptions,
-  type UploadRequestOptions,
-} from './ImageCanvasAssetLibraryPanelView';
 import {
   filterGroupedAssetsBySearch,
   layerMatchesSearch,
   layerStartsWithSearch,
 } from './ImageCanvasAssetLibraryModel';
+import {
+  type GroupedEditorAssetFolder,
+  ImageCanvasAssetLibraryPanelView,
+  type UploadFilesOptions,
+  type UploadRequestOptions,
+} from './ImageCanvasAssetLibraryPanelView';
 import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import type {
   AssetMarqueeState,
diff --git a/src/components/image-editor/ImageCanvasStageControllerModel.ts b/src/components/image-editor/ImageCanvasStageControllerModel.ts
index 0c57aa8eb..30e27c2dd 100644
--- a/src/components/image-editor/ImageCanvasStageControllerModel.ts
+++ b/src/components/image-editor/ImageCanvasStageControllerModel.ts
@@ -1,7 +1,3 @@
-import {
-  getCanvasLayersByIds,
-  resolveContextTargetLayerIds,
-} from './ImageCanvasLayerCommandModel';
 import {
   resolveContextMenuPosition,
 } from './ImageCanvasEditorModel';
@@ -12,6 +8,10 @@ import type {
   CanvasViewport,
   ImageContextMenuState,
 } from './ImageCanvasEditorTypes';
+import {
+  getCanvasLayersByIds,
+  resolveContextTargetLayerIds,
+} from './ImageCanvasLayerCommandModel';
 import {
   resolveSelectedToolbarStyle,
 } from './ImageCanvasOverlayModel';
diff --git a/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts b/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts
index 9d7098514..c05ae0ec7 100644
--- a/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts
+++ b/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts
@@ -5,10 +5,11 @@ import type {
   CanvasLayer,
   GenerateDialogState,
 } from './ImageCanvasEditorTypes';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 import {
-  createGenerationFrameSelectionStart,
   createCanvasMarqueeState,
   createGenerationFrameDragState,
+  createGenerationFrameSelectionStart,
   createLayerDragStart,
   createMinimapDragState,
   createPanDragState,
@@ -21,7 +22,6 @@ import {
   updateGenerateDialogForLayerPointerDown,
   updateMinimapDragMovement,
 } from './ImageCanvasStageInteractionModel';
-import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 
 function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
   const id = overrides.id ?? 'layer-a';
@@ -345,9 +345,9 @@ describe('ImageCanvasStageInteractionModel', () => {
       minimapScale: 0.4,
       moved: false,
     });
-    expect(
-      updateMinimapDragMovement(minimapDrag, { x: 121, y: 90 }),
-    ).toBe(minimapDrag);
+    expect(updateMinimapDragMovement(minimapDrag, { x: 121, y: 90 })).toBe(
+      minimapDrag,
+    );
     expect(updateMinimapDragMovement(minimapDrag, { x: 123, y: 90 })).toEqual({
       ...minimapDrag,
       moved: true,
@@ -385,7 +385,10 @@ describe('ImageCanvasStageInteractionModel', () => {
         dialog: anotherDialog,
         layers,
         generationDialogs: [dialog, anotherDialog],
-        selectedLayerIds: ['layer-a', getCanvasGenerationSelectionId('dialog-1')],
+        selectedLayerIds: [
+          'layer-a',
+          getCanvasGenerationSelectionId('dialog-1'),
+        ],
         isMultiSelectGesture: true,
         pointerId: 12,
         pointer: { x: 360, y: 260 },
diff --git a/src/components/image-editor/ImageCanvasStageInteractionModel.ts b/src/components/image-editor/ImageCanvasStageInteractionModel.ts
index 08ceb1a0d..19445fc06 100644
--- a/src/components/image-editor/ImageCanvasStageInteractionModel.ts
+++ b/src/components/image-editor/ImageCanvasStageInteractionModel.ts
@@ -30,10 +30,13 @@ type PointerSource = {
   };
 };
 
-type CanvasRectLike = {
-  left?: number;
-  top?: number;
-} | null | undefined;
+type CanvasRectLike =
+  | {
+      left?: number;
+      top?: number;
+    }
+  | null
+  | undefined;
 
 const CANVAS_GENERATION_DIALOG_MODES = new Set([
   'generate',
@@ -64,12 +67,22 @@ function hasCanvasGenerationDialogMode(
 
 export function getPointerButton(event: PointerSource) {
   const nativeButtons = Number(event.nativeEvent?.buttons);
-  if (Number.isFinite(nativeButtons) && (nativeButtons & 4) === 4) {
-    return 1;
+  if (Number.isFinite(nativeButtons)) {
+    if ((nativeButtons & 2) === 2) {
+      return 2;
+    }
+    if ((nativeButtons & 4) === 4) {
+      return 1;
+    }
   }
   const syntheticButtons = Number(event.buttons);
-  if (Number.isFinite(syntheticButtons) && (syntheticButtons & 4) === 4) {
-    return 1;
+  if (Number.isFinite(syntheticButtons)) {
+    if ((syntheticButtons & 2) === 2) {
+      return 2;
+    }
+    if ((syntheticButtons & 4) === 4) {
+      return 1;
+    }
   }
   const syntheticButton = Number(event.button);
   if (Number.isFinite(syntheticButton)) {
@@ -200,9 +213,8 @@ export function createLayerDragStart({
     isMultiSelectGesture,
   });
   const selectedCanvasLayerIds = getSelectedLayerIds(nextSelectedLayerIds);
-  const selectedGenerationDialogIds = getSelectedGenerationDialogIds(
-    nextSelectedLayerIds,
-  );
+  const selectedGenerationDialogIds =
+    getSelectedGenerationDialogIds(nextSelectedLayerIds);
   const dragLayerIds = selectedCanvasLayerIds.includes(layer.id)
     ? selectedCanvasLayerIds
     : [layer.id];
@@ -300,9 +312,8 @@ export function createGenerationFrameSelectionStart({
     selectedIds: selectedLayerIds,
     isMultiSelectGesture,
   });
-  const selectedGenerationDialogIds = getSelectedGenerationDialogIds(
-    nextSelectedLayerIds,
-  );
+  const selectedGenerationDialogIds =
+    getSelectedGenerationDialogIds(nextSelectedLayerIds);
   const selectedCanvasLayerIds = getSelectedLayerIds(nextSelectedLayerIds);
   const dragDialogIds = selectedGenerationDialogIds.includes(dialog.id)
     ? selectedGenerationDialogIds
diff --git a/src/components/image-editor/ImageCanvasStageView.tsx b/src/components/image-editor/ImageCanvasStageView.tsx
index 5ce65dd5d..9341e22c2 100644
--- a/src/components/image-editor/ImageCanvasStageView.tsx
+++ b/src/components/image-editor/ImageCanvasStageView.tsx
@@ -7,9 +7,10 @@ import type {
   RefObject,
 } from 'react';
 
-import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
-import type { EditorAgentGenerationResultEvent } from '../../../packages/shared/src/contracts/editorAgent';
-import { EditorAgentConversationPanelView } from './EditorAgentConversationPanelView';
+import type { ExternalGenerationTaskRecord } from '@/packages/shared/src';
+import { EditorAgentConversationPanelView } from '@/src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.tsx';
+
+import { PlatformRuntimeStatusToast } from '../common/PlatformRuntimeStatusToast';
 import { ImageCanvasBottomToolbarView } from './ImageCanvasBottomToolbarView';
 import { ImageCanvasContextMenusView } from './ImageCanvasContextMenusView';
 import type {
@@ -17,6 +18,7 @@ import type {
   CanvasClipboard,
   CanvasContextMenuState,
   CanvasGenerationDialogState,
+  CanvasHistoryFeedback,
   CanvasLayer,
   CanvasMarqueeState,
   CanvasTool,
@@ -40,6 +42,8 @@ import type {
 import { ImageCanvasUiAssetExtractionOverlayView } from './ImageCanvasUiAssetExtractionOverlayView';
 import { ImageCanvasWorldView } from './ImageCanvasWorldView';
 
+const EMPTY_LAYER_ID_SET: ReadonlySet<string> = new Set();
+
 export type ImageCanvasStageViewProps = {
   canvasViewportRef: RefObject<HTMLDivElement | null>;
   specToolWrapRef: RefObject<HTMLSpanElement | null>;
@@ -73,6 +77,7 @@ export type ImageCanvasStageViewProps = {
   quickEditSelectionSourceLayer: CanvasLayer | null;
   generationComposerStyle: CSSProperties | null;
   selectedToolbarStyle: CSSProperties | null;
+  splittingIconSpritesheetLayerIds?: ReadonlySet<string>;
   uploadDropTarget: 'canvas' | 'assets' | null;
   contextMenu: CanvasContextMenuState | null;
   canvasClipboard: CanvasClipboard | null;
@@ -83,6 +88,7 @@ export type ImageCanvasStageViewProps = {
   contextShouldUnlockLayer: boolean;
   canUndo: boolean;
   canRedo: boolean;
+  historyFeedback: CanvasHistoryFeedback | null;
   isZoomMenuOpen: boolean;
   isBackgroundSettingsOpen: boolean;
   activeSidebarPanel: SidebarPanel | null;
@@ -127,9 +133,8 @@ export type ImageCanvasStageViewProps = {
   onActivateGenerationDialog: (dialog: CanvasGenerationDialogState) => void;
   onFocusExternalTask: (task: ExternalGenerationTaskRecord) => void;
   onExternalTasksCompleted?: (tasks: ExternalGenerationTaskRecord[]) => void;
-  onEditorAgentGenerationResult?: (
-    event: EditorAgentGenerationResultEvent,
-  ) => void;
+  onEditorAgentCanvasRefreshRequested?: () => void;
+  onEditorAgentConfirmSent?: () => void;
   onToggleTaskSidebar: () => void;
   onToggleAgentConversation: () => void;
   onCropExpandHandlePointerDown: (
@@ -226,6 +231,7 @@ export function ImageCanvasStageView({
   quickEditSelectionSourceLayer,
   generationComposerStyle,
   selectedToolbarStyle,
+  splittingIconSpritesheetLayerIds = EMPTY_LAYER_ID_SET,
   uploadDropTarget,
   contextMenu,
   canvasClipboard,
@@ -236,6 +242,7 @@ export function ImageCanvasStageView({
   contextShouldUnlockLayer,
   canUndo,
   canRedo,
+  historyFeedback,
   isZoomMenuOpen,
   isBackgroundSettingsOpen,
   activeSidebarPanel,
@@ -262,7 +269,8 @@ export function ImageCanvasStageView({
   onActivateGenerationDialog,
   onFocusExternalTask,
   onExternalTasksCompleted,
-  onEditorAgentGenerationResult,
+  onEditorAgentCanvasRefreshRequested,
+  onEditorAgentConfirmSent,
   onToggleTaskSidebar,
   onToggleAgentConversation,
   onCropExpandHandlePointerDown,
@@ -335,6 +343,15 @@ export function ImageCanvasStageView({
       onDrop={isInteractionPaused ? undefined : onCanvasDrop}
       onContextMenu={isInteractionPaused ? undefined : onCanvasContextMenu}
     >
+      {historyFeedback ? (
+        <PlatformRuntimeStatusToast
+          key={historyFeedback.id}
+          tone={historyFeedback.tone}
+          className="image-canvas-editor__undo-toast"
+        >
+          {historyFeedback.text}
+        </PlatformRuntimeStatusToast>
+      ) : null}
       {uploadDropTarget === 'canvas' ? (
         <div
           className="image-canvas-editor__upload-drop-overlay image-canvas-editor__upload-drop-overlay--canvas"
@@ -356,6 +373,7 @@ export function ImageCanvasStageView({
         cropExpandPanel={cropExpandPanel}
         cropExpandSourceLayer={cropExpandSourceLayer}
         generationComposerStyle={generationComposerStyle}
+        splittingIconSpritesheetLayerIds={splittingIconSpritesheetLayerIds}
         onLayerPointerDown={onLayerPointerDown}
         onLayerClick={onLayerClick}
         onSelectLayer={onSelectLayer}
@@ -377,6 +395,10 @@ export function ImageCanvasStageView({
             : selectedLayer
         }
         selectedToolbarStyle={selectedToolbarStyle}
+        isSplittingIconSpritesheet={Boolean(
+          selectedLayer &&
+            splittingIconSpritesheetLayerIds.has(selectedLayer.id),
+        )}
         onOpenQuickEditPanel={onOpenQuickEditPanel}
         onOpenRedrawPanel={onOpenRedrawPanel}
         onOpenCropExpandPanel={onOpenCropExpandPanel}
@@ -485,7 +507,8 @@ export function ImageCanvasStageView({
           onToggleOpen={onToggleAgentConversation}
           layers={layers}
           assets={editorAgentAssets}
-          onGenerationResult={onEditorAgentGenerationResult}
+          onCanvasRefreshRequested={onEditorAgentCanvasRefreshRequested}
+          onConfirmSent={onEditorAgentConfirmSent}
         />
       ) : null}
 
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
index 0c2957dca..d13243333 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
@@ -220,6 +220,8 @@ describe('ImageCanvasTaskSidebarView', () => {
                 createExternalTask({
                   jobId: 'active-current',
                   startedAt,
+                  phaseDetail: '正在处理。',
+                  progress: 70,
                 }),
                 createExternalTask({
                   jobId: 'active-other-project',
@@ -260,8 +262,8 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     expect(await screen.findByText('图片画布生成图片')).toBeTruthy();
     expect(screen.getByText(/发光猫咪主视觉/u)).toBeTruthy();
-    expect(screen.getByText('正在生成第 2/4 段。')).toBeTruthy();
-    expect(screen.queryByText(/35%/u)).toBeNull();
+    expect(screen.getByText('正在处理。')).toBeTruthy();
+    expect(screen.queryByText(/\d{1,3}%/u)).toBeNull();
     expect(screen.getByText(/已用时 1分/u)).toBeTruthy();
     expect(screen.queryByText(/总进度/u)).toBeNull();
     expect(screen.queryByText(/不该显示的外部项目任务/u)).toBeNull();
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
index 06655f49c..7dcbf6c7a 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
@@ -6,13 +6,13 @@ import {
   XCircle,
 } from 'lucide-react';
 import {
-  type WheelEvent as ReactWheelEvent,
   type UIEvent as ReactUIEvent,
   useCallback,
   useEffect,
   useMemo,
   useRef,
   useState,
+  type WheelEvent as ReactWheelEvent,
 } from 'react';
 
 import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
diff --git a/src/components/image-editor/ImageCanvasTopbarView.test.tsx b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
index c9eb10d4b..2ff3eeaf5 100644
--- a/src/components/image-editor/ImageCanvasTopbarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
@@ -120,7 +120,7 @@ describe('ImageCanvasTopbarView', () => {
 
     await user.click(screen.getByRole('button', { name: '充值' }));
     expect(props.onRecharge).toHaveBeenCalledTimes(1);
-    expect(props.onRequestWalletDetails).not.toHaveBeenCalled();
+    expect(props.onRequestWalletDetails).toHaveBeenCalledTimes(1);
   });
 
   it('shows the current user avatar beside the mud point balance', () => {
diff --git a/src/components/image-editor/ImageCanvasUploadModel.ts b/src/components/image-editor/ImageCanvasUploadModel.ts
index f81aeb71f..fed0c5e1d 100644
--- a/src/components/image-editor/ImageCanvasUploadModel.ts
+++ b/src/components/image-editor/ImageCanvasUploadModel.ts
@@ -1,15 +1,15 @@
+import { resolvePreferredAssetUploadFolder } from './ImageCanvasAssetLibraryModel';
 import { resolveLayerResolutionSize } from './ImageCanvasEditorModel';
 import type {
-  CharacterReferenceImage,
-  CanvasMediaType,
   CanvasLayer,
+  CanvasMediaType,
   CanvasViewport,
+  CharacterReferenceImage,
   EditorAsset,
   EditorAssetFolder,
   GenerateDialogState,
   QuickEditPanelState,
 } from './ImageCanvasEditorTypes';
-import { resolvePreferredAssetUploadFolder } from './ImageCanvasAssetLibraryModel';
 import { appendLimitedQuickEditReferences } from './ImageCanvasGenerationModel';
 
 type CanvasSize = { width: number; height: number };
diff --git a/src/components/image-editor/ImageCanvasWorldView.test.tsx b/src/components/image-editor/ImageCanvasWorldView.test.tsx
index 5c9977ab9..446a3fa26 100644
--- a/src/components/image-editor/ImageCanvasWorldView.test.tsx
+++ b/src/components/image-editor/ImageCanvasWorldView.test.tsx
@@ -138,6 +138,22 @@ describe('ImageCanvasWorldView', () => {
     expect(screen.queryByRole('status', { name: '' })).toBeNull();
   });
 
+  it('shows the atlas splitting treatment on the source layer', () => {
+    const layer = createLayer({ assetKind: 'icon-spritesheet' });
+    renderWorldView({
+      layers: [layer],
+      splittingIconSpritesheetLayerIds: new Set([layer.id]),
+    });
+
+    const sourceLayer = screen.getByRole('button', {
+      name: `选择${layer.title}`,
+    });
+    expect(sourceLayer.className).toContain(
+      'image-canvas-editor__layer--generating',
+    );
+    expect(within(sourceLayer).getByRole('status').textContent).toBe('拆图中');
+  });
+
   it('keeps the image layer frame visible while the image is loading', () => {
     useResolvedAssetReadUrlMock.mockImplementation(() => ({
       resolvedUrl: '',
diff --git a/src/components/image-editor/ImageCanvasWorldView.tsx b/src/components/image-editor/ImageCanvasWorldView.tsx
index a28d6401b..97ef196df 100644
--- a/src/components/image-editor/ImageCanvasWorldView.tsx
+++ b/src/components/image-editor/ImageCanvasWorldView.tsx
@@ -8,20 +8,20 @@ import {
   Megaphone,
   Music,
   Pause,
-  Play,
   PersonStanding,
+  Play,
   Sparkles,
   UserRound,
   Volume2,
   VolumeX,
 } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type {
   CSSProperties,
   KeyboardEvent as ReactKeyboardEvent,
   MouseEvent as ReactMouseEvent,
   PointerEvent as ReactPointerEvent,
 } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
 import {
@@ -250,6 +250,7 @@ export type ImageCanvasWorldViewProps = {
   cropExpandPanel: CropExpandPanelState | null;
   cropExpandSourceLayer: CanvasLayer | null;
   generationComposerStyle: CSSProperties | null;
+  splittingIconSpritesheetLayerIds?: ReadonlySet<string>;
   onLayerPointerDown: (
     event: ReactPointerEvent<HTMLElement>,
     layer: CanvasLayer,
@@ -285,6 +286,8 @@ export type ImageCanvasWorldViewProps = {
   ) => void;
 };
 
+const EMPTY_LAYER_ID_SET: ReadonlySet<string> = new Set();
+
 const CROP_EXPAND_HANDLES: Array<{
   value: CropExpandResizeHandle;
   label: string;
@@ -916,6 +919,7 @@ export function ImageCanvasWorldView({
   cropExpandPanel,
   cropExpandSourceLayer,
   generationComposerStyle,
+  splittingIconSpritesheetLayerIds = EMPTY_LAYER_ID_SET,
   onLayerPointerDown,
   onLayerClick,
   onSelectLayer,
@@ -1007,10 +1011,13 @@ export function ImageCanvasWorldView({
             layer.flipX || layer.flipY
               ? `scale(${layer.flipX ? -1 : 1}, ${layer.flipY ? -1 : 1})`
               : undefined;
-          const layerGeneratingLabel =
-            generateDialog?.mode === 'edit' &&
-            generateDialog.status === 'generating' &&
-            generateDialog.sourceLayerId === layer.id
+          const layerGeneratingLabel = splittingIconSpritesheetLayerIds.has(
+            layer.id,
+          )
+            ? '拆图中'
+            : generateDialog?.mode === 'edit' &&
+                generateDialog.status === 'generating' &&
+                generateDialog.sourceLayerId === layer.id
               ? '修改中'
               : null;
           const isMediaContainer = isCanvasMediaContainerLayer(layer);
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.test.tsx b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
index e845a4a4c..fba896056 100644
--- a/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
+++ b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
@@ -1,6 +1,6 @@
 /* @vitest-environment jsdom */
 
-import { renderHook, act } from '@testing-library/react';
+import { act,renderHook } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 
 import type { CanvasGenerationDialogState } from './ImageCanvasEditorTypes';
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.ts b/src/components/image-editor/useCanvasGenerationDialogs.ts
index 21ab352d5..c386825e7 100644
--- a/src/components/image-editor/useCanvasGenerationDialogs.ts
+++ b/src/components/image-editor/useCanvasGenerationDialogs.ts
@@ -7,11 +7,11 @@ import {
   useState,
 } from 'react';
 
-import { isCanvasGenerationDialog } from './ImageCanvasGenerationModel';
 import type {
   CanvasGenerationDialogState,
   GenerateDialogState,
 } from './ImageCanvasEditorTypes';
+import { isCanvasGenerationDialog } from './ImageCanvasGenerationModel';
 
 type CanvasGenerationDialogUpdater = (
   dialog: CanvasGenerationDialogState,
diff --git a/src/components/image-editor/useCanvasHistory.test.tsx b/src/components/image-editor/useCanvasHistory.test.tsx
index 5e9c502b1..3db9b51e5 100644
--- a/src/components/image-editor/useCanvasHistory.test.tsx
+++ b/src/components/image-editor/useCanvasHistory.test.tsx
@@ -29,7 +29,13 @@ function createLayer(id: string, x: number): CanvasLayer {
   };
 }
 
-function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
+function HistoryHarness({
+  onClearDrag,
+  persistRestoredAssetKind = () => {},
+}: {
+  onClearDrag: () => void;
+  persistRestoredAssetKind?: (layer: CanvasLayer) => void;
+}) {
   const [layers, setLayers] = useState<CanvasLayer[]>([
     createLayer('first', 10),
   ]);
@@ -44,6 +50,7 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       mode: 'generate',
       prompt: 'active prompt',
       status: 'idle',
+      imageSize: '1K',
       placeholder: {
         x: 10,
         y: 20,
@@ -71,8 +78,11 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       },
     },
   ]);
-  const [selectedLayerId, setSelectedLayerId] = useState<string | null>('first');
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(
+    'first',
+  );
   const [selectedLayerIds, setSelectedLayerIds] = useState<string[]>(['first']);
+  const [lastHistoryStatus, setLastHistoryStatus] = useState('empty');
 
   const layersRef = useRef(layers);
   const viewportRef = useRef(viewport);
@@ -110,6 +120,7 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       setMetadataLayer: () => {},
       resetCanvasInteractionState: onClearDrag,
     },
+    effects: { persistRestoredAssetKind },
   });
 
   return (
@@ -117,20 +128,45 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       <span data-testid="layers">
         {layers.map((layer) => `${layer.id}:${layer.x}`).join(',')}
       </span>
+      <span data-testid="layer-relations">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.resourceId}:${layer.sourceResourceId ?? '-'}:${layer.sourceAssetId ?? '-'}`,
+          )
+          .join(',')}
+      </span>
+      <span data-testid="layer-asset-kind">
+        {layers
+          .map((layer) => `${layer.resourceId}:${layer.assetKind ?? '-'}`)
+          .join(',')}
+      </span>
       <span data-testid="viewport">
         {viewport.x},{viewport.y},{viewport.scale}
       </span>
       <span data-testid="dialog">{generateDialog?.prompt ?? '-'}</span>
+      <span data-testid="dialog-state">
+        {generateDialog
+          ? `${generateDialog.status}:${generateDialog.placeholder?.x ?? '-'}:${generateDialog.generatedLayerId ?? '-'}:${generateDialog.generationReferences?.[0]?.label ?? '-'}:${generateDialog.generationStartedAt ?? '-'}`
+          : '-'}
+      </span>
+      <span data-testid="dialog-size">
+        {generateDialog
+          ? `${generateDialog.imageSize ?? '-'}:${generateDialog.placeholder?.width ?? '-'}:${generateDialog.placeholder?.height ?? '-'}:${generateDialog.placeholder?.originalWidth ?? '-'}:${generateDialog.placeholder?.originalHeight ?? '-'}`
+          : '-'}
+      </span>
       <span data-testid="inactive">
         {inactiveGenerateDialogs.map((dialog) => dialog.prompt).join(',')}
       </span>
       <span data-testid="selection">{selectedLayerIds.join(',')}</span>
       <span data-testid="can-undo">{String(history.canUndo)}</span>
       <span data-testid="can-redo">{String(history.canRedo)}</span>
+      <span data-testid="history-status">{lastHistoryStatus}</span>
+      <span data-testid="history-version">{history.historyVersion}</span>
       <button
         type="button"
         onClick={() => {
-          history.captureCanvasHistory();
+          history.captureCanvasHistory({ type: 'move-image', count: 1 });
         }}
       >
         capture
@@ -138,25 +174,125 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       <button
         type="button"
         onClick={() => {
-          setLayers([createLayer('second', 90)]);
-          setViewport({ x: 9, y: 8, scale: 2 });
-          setGenerateDialog({
-            id: 'dialog-next',
-            mode: 'spec',
-            prompt: 'next prompt',
-            status: 'idle',
+          history.captureCanvasHistory({
+            type: 'change-asset-kind',
+            count: 1,
           });
-          setInactiveGenerateDialogs([]);
-          setSelectedLayerId('second');
-          setSelectedLayerIds(['second']);
+        }}
+      >
+        capture-asset-kind
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          setLayers([createLayer('first', 90)]);
+          setViewport({ x: 9, y: 8, scale: 2 });
+          setSelectedLayerId('first');
+          setSelectedLayerIds(['first']);
         }}
       >
         mutate
       </button>
+      <button
+        type="button"
+        onClick={() =>
+          setLayers([
+            {
+              ...createLayer('first', 90),
+              resourceId: 'persisted-resource-first',
+              sourceResourceId: 'source-resource-late',
+              sourceAssetId: 'source-asset-late',
+              objectKey: 'uploads/first.png',
+            },
+          ])
+        }
+      >
+        persist-and-move
+      </button>
+      <button type="button" onClick={() => setLayers([])}>
+        delete
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setLayers((currentLayers) =>
+            currentLayers.map((layer) =>
+              layer.id === 'first'
+                ? {
+                    ...layer,
+                    resourceId: 'resource-first-icon',
+                    assetKind: 'icon',
+                  }
+                : layer,
+            ),
+          )
+        }
+      >
+        change-asset-kind
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          history.discardCanvasHistoryEntriesContainingLayer(
+            (layer) => layer.id === 'first',
+          )
+        }
+      >
+        discard-first-history
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          history.discardCanvasHistoryEntriesContainingLayer(
+            (layer) => layer.id === 'missing',
+          )
+        }
+      >
+        discard-missing-history
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setGenerateDialog((currentDialog) =>
+            currentDialog
+              ? {
+                  ...currentDialog,
+                  prompt: 'current prompt',
+                  status: 'generating',
+                  generatedLayerId: 'generated-layer-current',
+                  generationReferences: [
+                    {
+                      id: 'current-reference',
+                      label: 'current reference',
+                      src: '/current-reference.png',
+                    },
+                  ],
+                  generationStartedAt: 100,
+                  imageSize: '2K',
+                  placeholder: currentDialog.placeholder
+                    ? {
+                        ...currentDialog.placeholder,
+                        x: 90,
+                        width: 640,
+                        height: 480,
+                        originalWidth: 640,
+                        originalHeight: 480,
+                      }
+                    : undefined,
+                }
+              : currentDialog,
+          )
+        }
+      >
+        advance-dialog
+      </button>
+      <button type="button" onClick={() => setGenerateDialog(null)}>
+        delete-dialog
+      </button>
       <button
         type="button"
         onClick={() => {
-          history.undoCanvasChange();
+          setLastHistoryStatus(history.undoCanvasChange().status);
         }}
       >
         undo
@@ -164,7 +300,7 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
       <button
         type="button"
         onClick={() => {
-          history.redoCanvasChange();
+          setLastHistoryStatus(history.redoCanvasChange().status);
         }}
       >
         redo
@@ -174,7 +310,7 @@ function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
 }
 
 describe('useCanvasHistory', () => {
-  it('captures, restores, and replays canvas history snapshots', () => {
+  it('captures, undoes, and redoes safe canvas history snapshots', () => {
     const clearDragState = vi.fn();
     render(<HistoryHarness onClearDrag={clearDragState} />);
 
@@ -186,7 +322,7 @@ describe('useCanvasHistory', () => {
     act(() => {
       screen.getByRole('button', { name: 'mutate' }).click();
     });
-    expect(screen.getByTestId('layers').textContent).toBe('second:90');
+    expect(screen.getByTestId('layers').textContent).toBe('first:90');
     expect(screen.getByTestId('viewport').textContent).toBe('9,8,2');
 
     act(() => {
@@ -204,10 +340,210 @@ describe('useCanvasHistory', () => {
     act(() => {
       screen.getByRole('button', { name: 'redo' }).click();
     });
-
-    expect(screen.getByTestId('layers').textContent).toBe('second:90');
+    expect(screen.getByTestId('layers').textContent).toBe('first:90');
     expect(screen.getByTestId('viewport').textContent).toBe('9,8,2');
-    expect(screen.getByTestId('dialog').textContent).toBe('next prompt');
-    expect(screen.getByTestId('selection').textContent).toBe('second');
+    expect(screen.getByTestId('can-redo').textContent).toBe('false');
+    expect(screen.getByTestId('can-undo').textContent).toBe('true');
+  });
+
+  it('blocks redo when replaying a deletion would remove canvas content', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+      screen.getByRole('button', { name: 'delete' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('layers').textContent).toBe('first:10');
+
+    act(() => {
+      screen.getByRole('button', { name: 'redo' }).click();
+    });
+    expect(screen.getByTestId('history-status').textContent).toBe('blocked');
+    expect(screen.getByTestId('layers').textContent).toBe('first:10');
+    expect(screen.getByTestId('can-redo').textContent).toBe('true');
+  });
+
+  it('clears redo history after a new canvas edit is captured', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+      screen.getByRole('button', { name: 'mutate' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('can-redo').textContent).toBe('true');
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    expect(screen.getByTestId('can-redo').textContent).toBe('false');
+  });
+
+  it('undoes dialog movement without reverting its generation lifecycle', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'advance-dialog' }).click();
+    });
+    expect(screen.getByTestId('dialog-state').textContent).toBe(
+      'generating:90:generated-layer-current:current reference:100',
+    );
+    expect(screen.getByTestId('dialog-size').textContent).toBe(
+      '2K:640:480:640:480',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe('current prompt');
+    expect(screen.getByTestId('dialog-state').textContent).toBe(
+      'generating:10:generated-layer-current:current reference:100',
+    );
+    expect(screen.getByTestId('dialog-size').textContent).toBe(
+      '2K:640:480:640:480',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'redo' }).click();
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe('current prompt');
+    expect(screen.getByTestId('dialog-state').textContent).toBe(
+      'generating:90:generated-layer-current:current reference:100',
+    );
+    expect(screen.getByTestId('dialog-size').textContent).toBe(
+      '2K:640:480:640:480',
+    );
+  });
+
+  it('restores a generation dialog that was deleted after capture', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+      screen.getByRole('button', { name: 'delete-dialog' }).click();
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe('active prompt');
+    expect(screen.getByTestId('dialog-state').textContent).toBe(
+      'idle:10:-:-:-',
+    );
+  });
+
+  it('undoes movement after source asset relation ids arrive asynchronously', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'persist-and-move' }).click();
+    });
+    expect(screen.getByTestId('layers').textContent).toBe('first:90');
+
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('history-status').textContent).toBe('success');
+    expect(screen.getByTestId('layers').textContent).toBe('first:10');
+    expect(screen.getByTestId('layer-relations').textContent).toBe(
+      'persisted-resource-first:source-resource-late:source-asset-late',
+    );
+  });
+
+  it('discards undo and redo entries whose snapshots contain a deleted asset layer', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'mutate' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('can-redo').textContent).toBe('true');
+
+    act(() => {
+      screen.getByRole('button', { name: 'discard-first-history' }).click();
+    });
+
+    expect(screen.getByTestId('can-undo').textContent).toBe('false');
+    expect(screen.getByTestId('can-redo').textContent).toBe('false');
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('history-status').textContent).toBe('empty');
+  });
+
+  it('does not update history state when an invalidation matcher misses', () => {
+    render(<HistoryHarness onClearDrag={() => {}} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    const versionBeforeDiscard =
+      screen.getByTestId('history-version').textContent;
+    act(() => {
+      screen.getByRole('button', { name: 'discard-missing-history' }).click();
+    });
+
+    expect(screen.getByTestId('can-undo').textContent).toBe('true');
+    expect(screen.getByTestId('history-version').textContent).toBe(
+      versionBeforeDiscard,
+    );
+  });
+
+  it('persists asset kind changes restored by undo and redo', () => {
+    const persistRestoredAssetKind = vi.fn();
+    render(
+      <HistoryHarness
+        onClearDrag={() => {}}
+        persistRestoredAssetKind={persistRestoredAssetKind}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture-asset-kind' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'change-asset-kind' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+    expect(screen.getByTestId('layer-asset-kind').textContent).toBe(
+      'resource-first-icon:-',
+    );
+    expect(persistRestoredAssetKind).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        id: 'first',
+        resourceId: 'resource-first-icon',
+        assetKind: undefined,
+      }),
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'redo' }).click();
+    });
+    expect(screen.getByTestId('layer-asset-kind').textContent).toBe(
+      'resource-first-icon:icon',
+    );
+    expect(persistRestoredAssetKind).toHaveBeenLastCalledWith(
+      expect.objectContaining({ assetKind: 'icon' }),
+    );
+    expect(persistRestoredAssetKind).toHaveBeenCalledTimes(2);
   });
 });
diff --git a/src/components/image-editor/useCanvasHistory.ts b/src/components/image-editor/useCanvasHistory.ts
index a9e1ae120..fa91a6117 100644
--- a/src/components/image-editor/useCanvasHistory.ts
+++ b/src/components/image-editor/useCanvasHistory.ts
@@ -3,11 +3,19 @@ import { type RefObject, useCallback, useRef, useState } from 'react';
 import { MAX_HISTORY_STEPS } from './ImageCanvasEditorModel';
 import type {
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
+  CanvasHistoryApplyResult,
+  CanvasHistoryEntry,
   CanvasHistorySnapshot,
   CanvasLayer,
   CanvasViewport,
   GenerateDialogState,
 } from './ImageCanvasEditorTypes';
+import {
+  canRestoreCanvasHistorySnapshotWithoutContentLoss,
+  isProtectedCanvasHistoryAction,
+  mergeCanvasHistorySnapshotForRestore,
+} from './ImageCanvasHistoryModel';
 
 type CanvasHistoryRefs = {
   layersRef: RefObject<CanvasLayer[]>;
@@ -22,9 +30,7 @@ type CanvasHistorySetters = {
   setLayers: (layers: CanvasLayer[]) => void;
   setViewport: (viewport: CanvasViewport) => void;
   setGenerateDialog: (dialog: GenerateDialogState | null) => void;
-  setInactiveGenerateDialogs: (
-    dialogs: CanvasGenerationDialogState[],
-  ) => void;
+  setInactiveGenerateDialogs: (dialogs: CanvasGenerationDialogState[]) => void;
   setSelectedLayerId: (layerId: string | null) => void;
   setSelectedLayerIds: (layerIds: string[]) => void;
 };
@@ -35,6 +41,10 @@ type CanvasHistoryResetters = {
   resetCanvasInteractionState: () => void;
 };
 
+type CanvasHistoryEffects = {
+  persistRestoredAssetKind?: (layer: CanvasLayer) => void;
+};
+
 function cloneGenerateDialog(dialog: GenerateDialogState): GenerateDialogState {
   return {
     ...dialog,
@@ -55,13 +65,15 @@ export function useCanvasHistory({
   refs,
   setters,
   resetters,
+  effects,
 }: {
   refs: CanvasHistoryRefs;
   setters: CanvasHistorySetters;
   resetters: CanvasHistoryResetters;
+  effects?: CanvasHistoryEffects;
 }) {
-  const undoStackRef = useRef<CanvasHistorySnapshot[]>([]);
-  const redoStackRef = useRef<CanvasHistorySnapshot[]>([]);
+  const undoStackRef = useRef<CanvasHistoryEntry[]>([]);
+  const redoStackRef = useRef<CanvasHistoryEntry[]>([]);
   const [historyVersion, setHistoryVersion] = useState(0);
 
   const getCanvasHistorySnapshot = useCallback(
@@ -71,8 +83,9 @@ export function useCanvasHistory({
       generateDialog: refs.generateDialogRef.current
         ? cloneGenerateDialog(refs.generateDialogRef.current)
         : null,
-      inactiveGenerateDialogs:
-        refs.inactiveGenerateDialogsRef.current.map(cloneCanvasGenerationDialog),
+      inactiveGenerateDialogs: refs.inactiveGenerateDialogsRef.current.map(
+        cloneCanvasGenerationDialog,
+      ),
       selectedLayerId: refs.selectedLayerIdRef.current,
       selectedLayerIds: [...refs.selectedLayerIdsRef.current],
     }),
@@ -80,66 +93,144 @@ export function useCanvasHistory({
   );
 
   const restoreCanvasHistorySnapshot = useCallback(
-    (snapshot: CanvasHistorySnapshot) => {
-      setters.setLayers(snapshot.layers.map((layer) => ({ ...layer })));
-      setters.setViewport({ ...snapshot.viewport });
+    (snapshot: CanvasHistorySnapshot, action?: CanvasHistoryAction) => {
+      const currentSnapshot = getCanvasHistorySnapshot();
+      const mergedSnapshot = mergeCanvasHistorySnapshotForRestore({
+        current: currentSnapshot,
+        target: snapshot,
+      });
+      setters.setLayers(mergedSnapshot.layers.map((layer) => ({ ...layer })));
+      setters.setViewport({ ...mergedSnapshot.viewport });
       setters.setGenerateDialog(
-        snapshot.generateDialog
-          ? cloneGenerateDialog(snapshot.generateDialog)
+        mergedSnapshot.generateDialog
+          ? cloneGenerateDialog(mergedSnapshot.generateDialog)
           : null,
       );
       setters.setInactiveGenerateDialogs(
-        snapshot.inactiveGenerateDialogs.map(cloneCanvasGenerationDialog),
+        mergedSnapshot.inactiveGenerateDialogs.map(cloneCanvasGenerationDialog),
       );
-      setters.setSelectedLayerId(snapshot.selectedLayerId);
-      setters.setSelectedLayerIds([...snapshot.selectedLayerIds]);
+      setters.setSelectedLayerId(mergedSnapshot.selectedLayerId);
+      setters.setSelectedLayerIds([...mergedSnapshot.selectedLayerIds]);
       resetters.setHoveredLayerId(null);
       resetters.setMetadataLayer(null);
       resetters.resetCanvasInteractionState();
+
+      if (action?.type === 'change-asset-kind') {
+        const currentLayerById = new Map(
+          currentSnapshot.layers.map((layer) => [layer.id, layer] as const),
+        );
+        for (const layer of mergedSnapshot.layers) {
+          const currentLayer = currentLayerById.get(layer.id);
+          if (currentLayer && currentLayer.assetKind !== layer.assetKind) {
+            effects?.persistRestoredAssetKind?.({ ...layer });
+          }
+        }
+      }
     },
-    [resetters, setters],
+    [effects, getCanvasHistorySnapshot, resetters, setters],
   );
 
   const captureCanvasHistory = useCallback(
-    (options: { clearRedo?: boolean } = {}) => {
+    (
+      action: CanvasHistoryAction,
+      options: { snapshot?: CanvasHistorySnapshot } = {},
+    ) => {
       undoStackRef.current = [
         ...undoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
-        getCanvasHistorySnapshot(),
+        {
+          snapshot: options.snapshot ?? getCanvasHistorySnapshot(),
+          action,
+          createdAt: Date.now(),
+        },
       ];
-      if (options.clearRedo !== false) {
-        redoStackRef.current = [];
-      }
+      redoStackRef.current = [];
       setHistoryVersion((version) => version + 1);
     },
     [getCanvasHistorySnapshot],
   );
 
-  const undoCanvasChange = useCallback(() => {
-    const previousSnapshot = undoStackRef.current.at(-1);
-    if (!previousSnapshot) {
-      return;
+  const discardCanvasHistoryEntriesContainingLayer = useCallback(
+    (matchesLayer: (layer: CanvasLayer) => boolean) => {
+      const keepEntry = (entry: CanvasHistoryEntry) =>
+        !entry.snapshot.layers.some(matchesLayer);
+      const nextUndoStack = undoStackRef.current.filter(keepEntry);
+      const nextRedoStack = redoStackRef.current.filter(keepEntry);
+      if (
+        nextUndoStack.length === undoStackRef.current.length &&
+        nextRedoStack.length === redoStackRef.current.length
+      ) {
+        return;
+      }
+      undoStackRef.current = nextUndoStack;
+      redoStackRef.current = nextRedoStack;
+      setHistoryVersion((version) => version + 1);
+    },
+    [],
+  );
+
+  const undoCanvasChange = useCallback((): CanvasHistoryApplyResult => {
+    const previousEntry = undoStackRef.current.at(-1);
+    if (!previousEntry) {
+      return { status: 'empty' };
+    }
+    const currentSnapshot = getCanvasHistorySnapshot();
+    if (
+      isProtectedCanvasHistoryAction(previousEntry.action) ||
+      !canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: currentSnapshot,
+        target: previousEntry.snapshot,
+      })
+    ) {
+      return {
+        status: 'blocked',
+        action: previousEntry.action,
+        reason: 'content-may-disappear',
+      };
     }
     undoStackRef.current = undoStackRef.current.slice(0, -1);
     redoStackRef.current = [
       ...redoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
-      getCanvasHistorySnapshot(),
+      {
+        snapshot: currentSnapshot,
+        action: previousEntry.action,
+        createdAt: Date.now(),
+      },
     ];
-    restoreCanvasHistorySnapshot(previousSnapshot);
+    restoreCanvasHistorySnapshot(previousEntry.snapshot, previousEntry.action);
     setHistoryVersion((version) => version + 1);
+    return { status: 'success', action: previousEntry.action };
   }, [getCanvasHistorySnapshot, restoreCanvasHistorySnapshot]);
 
-  const redoCanvasChange = useCallback(() => {
-    const nextSnapshot = redoStackRef.current.at(-1);
-    if (!nextSnapshot) {
-      return;
+  const redoCanvasChange = useCallback((): CanvasHistoryApplyResult => {
+    const nextEntry = redoStackRef.current.at(-1);
+    if (!nextEntry) {
+      return { status: 'empty' };
+    }
+    const currentSnapshot = getCanvasHistorySnapshot();
+    if (
+      !canRestoreCanvasHistorySnapshotWithoutContentLoss({
+        current: currentSnapshot,
+        target: nextEntry.snapshot,
+      })
+    ) {
+      return {
+        status: 'blocked',
+        action: nextEntry.action,
+        reason: 'content-may-disappear',
+      };
     }
     redoStackRef.current = redoStackRef.current.slice(0, -1);
     undoStackRef.current = [
       ...undoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
-      getCanvasHistorySnapshot(),
+      {
+        snapshot: currentSnapshot,
+        action: nextEntry.action,
+        createdAt: Date.now(),
+      },
     ];
-    restoreCanvasHistorySnapshot(nextSnapshot);
+    restoreCanvasHistorySnapshot(nextEntry.snapshot, nextEntry.action);
     setHistoryVersion((version) => version + 1);
+    return { status: 'success', action: nextEntry.action };
   }, [getCanvasHistorySnapshot, restoreCanvasHistorySnapshot]);
 
   return {
@@ -149,6 +240,7 @@ export function useCanvasHistory({
     getCanvasHistorySnapshot,
     restoreCanvasHistorySnapshot,
     captureCanvasHistory,
+    discardCanvasHistoryEntriesContainingLayer,
     undoCanvasChange,
     redoCanvasChange,
   };
diff --git a/src/components/image-editor/useEditorAgentConversation.test.tsx b/src/components/image-editor/useEditorAgentConversation.test.tsx
deleted file mode 100644
index 32a8abe36..000000000
--- a/src/components/image-editor/useEditorAgentConversation.test.tsx
+++ /dev/null
@@ -1,428 +0,0 @@
-/* @vitest-environment jsdom */
-
-import { act, renderHook, waitFor } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import {
-  type EditorAgentConversationClient,
-  useEditorAgentConversation,
-} from './useEditorAgentConversation';
-
-function createClient(): EditorAgentConversationClient {
-  return {
-    listConversations: vi.fn().mockResolvedValue([
-      {
-        conversationId: 'conversation-1',
-        projectId: 'project-1',
-        title: '角色参考',
-        createdAt: '2026-07-03T00:00:00.000Z',
-        updatedAt: '2026-07-03T00:00:00.000Z',
-      },
-    ]),
-    createConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-2',
-      projectId: 'project-1',
-      title: '新对话',
-      messages: [],
-      createdAt: '2026-07-03T00:00:00.000Z',
-      updatedAt: '2026-07-03T00:01:00.000Z',
-    }),
-    getConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-1',
-      projectId: 'project-1',
-      title: '角色参考',
-      messages: [],
-      createdAt: '2026-07-03T00:00:00.000Z',
-      updatedAt: '2026-07-03T00:00:00.000Z',
-    }),
-    deleteConversation: vi.fn().mockResolvedValue({
-      conversationId: 'conversation-1',
-      projectId: 'project-1',
-      title: '角色参考',
-      messages: [],
-      createdAt: '2026-07-03T00:00:00.000Z',
-      updatedAt: '2026-07-03T00:00:00.000Z',
-    }),
-    streamMessage: vi
-      .fn()
-      .mockImplementation(async (_conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'stage',
-          data: {
-            conversationId: 'conversation-1',
-            stage: 'thinking',
-          },
-        });
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-1',
-            role: 'assistant',
-            kind: 'chat',
-            textDelta: '我来处理',
-          },
-        });
-        options.onEvent?.({
-          event: 'tool_started',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-1',
-            toolCallId: 'tool-call-1',
-            toolName: 'generate_image',
-            taskId: 'task-1',
-            model: 'gpt-image-2',
-          },
-        });
-        options.onEvent?.({
-          event: 'generation_result',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-1',
-            toolCallId: 'tool-call-1',
-            toolName: 'generate_image',
-            model: null,
-            images: [
-              {
-                resourceId: 'resource-result-1',
-                imageSrc: '/result.png',
-                thumbnailSrc: '/result-thumb.png',
-                width: 1024,
-                height: 1024,
-              },
-            ],
-          },
-        });
-        options.onEvent?.({
-          event: 'done',
-          data: {
-            conversationId: 'conversation-1',
-            title: '像素角色',
-          },
-        });
-      }),
-  };
-}
-
-describe('useEditorAgentConversation', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('loads conversations and applies message stream events', async () => {
-    const client = createClient();
-    const onGenerationResult = vi.fn();
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({
-        projectId: 'project-1',
-        client,
-        onGenerationResult,
-      }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.activeConversation?.conversationId).toBe(
-        'conversation-1',
-      );
-    });
-
-    await act(async () => {
-      await result.current.sendMessage('把这个角色改成像素风');
-    });
-
-    expect(client.streamMessage).toHaveBeenCalledWith(
-      'conversation-1',
-      expect.objectContaining({
-        text: '把这个角色改成像素风',
-        attachments: [],
-      }),
-      expect.objectContaining({
-        onEvent: expect.any(Function),
-        signal: expect.any(AbortSignal),
-      }),
-    );
-    expect(result.current.stage).toBe('completed');
-    expect(result.current.isStreaming).toBe(false);
-    expect(onGenerationResult).toHaveBeenCalledWith(
-      expect.objectContaining({
-        toolCallId: 'tool-call-1',
-        images: [
-          expect.objectContaining({
-            resourceId: 'resource-result-1',
-          }),
-        ],
-      }),
-    );
-    expect(result.current.messages.map((message) => message.text)).toEqual([
-      '把这个角色改成像素风',
-      '我来处理',
-    ]);
-    expect(result.current.messages[1]?.generations).toEqual([
-      expect.objectContaining({
-        toolCallId: 'tool-call-1',
-        taskId: 'task-1',
-        model: 'gpt-image-2',
-        status: 'completed',
-        images: [
-          expect.objectContaining({
-            resourceId: 'resource-result-1',
-            thumbnailSrc: '/result-thumb.png',
-          }),
-        ],
-      }),
-    ]);
-    expect(result.current.conversations[0]?.title).toBe('像素角色');
-  });
-
-  it('creates a conversation before sending when the project has no history', async () => {
-    const client = createClient();
-    vi.mocked(client.listConversations).mockResolvedValueOnce([]);
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({ projectId: 'project-1', client }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.isLoadingConversations).toBe(false);
-    });
-
-    await act(async () => {
-      await result.current.sendMessage('新建后发送');
-    });
-
-    expect(client.createConversation).toHaveBeenCalledWith('project-1', {});
-    expect(client.streamMessage).toHaveBeenCalledWith(
-      'conversation-2',
-      expect.objectContaining({ text: '新建后发送' }),
-      expect.any(Object),
-    );
-  });
-
-  it('allows sending an attachment-only message', async () => {
-    const client = createClient();
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({ projectId: 'project-1', client }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.activeConversation?.conversationId).toBe(
-        'conversation-1',
-      );
-    });
-
-    await act(async () => {
-      await result.current.sendMessage('', [
-        {
-          source: 'canvas_resource',
-          referenceId: 'resource-1',
-          objectKey: 'generated-editor-assets/resource-1.png',
-          imageSrc: '/resource-1.png',
-          label: '参考图',
-        },
-      ]);
-    });
-
-    expect(client.streamMessage).toHaveBeenCalledWith(
-      'conversation-1',
-      expect.objectContaining({
-        text: '',
-        attachments: [
-          expect.objectContaining({
-            source: 'canvas_resource',
-            referenceId: 'resource-1',
-          }),
-        ],
-      }),
-      expect.any(Object),
-    );
-  });
-
-  it('keeps LLM planning failures as one failed assistant message', async () => {
-    const client = createClient();
-    vi.mocked(client.streamMessage).mockImplementation(
-      async (_conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-planning-error',
-            role: 'assistant',
-            kind: 'error',
-            textDelta: '画布 Agent 的 LLM 未配置，无法处理这句话。',
-          },
-        });
-        options.onEvent?.({
-          event: 'stage',
-          data: {
-            conversationId: 'conversation-1',
-            stage: 'failed',
-          },
-        });
-        options.onEvent?.({
-          event: 'done',
-          data: {
-            conversationId: 'conversation-1',
-            title: null,
-          },
-        });
-      },
-    );
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({ projectId: 'project-1', client }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.activeConversation?.conversationId).toBe(
-        'conversation-1',
-      );
-    });
-
-    await act(async () => {
-      await result.current.sendMessage('这是美术素材');
-    });
-
-    expect(result.current.stage).toBe('failed');
-    expect(result.current.errorMessage).toBe(
-      '画布 Agent 的 LLM 未配置，无法处理这句话。',
-    );
-    expect(
-      result.current.messages.filter((message) => message.kind === 'error'),
-    ).toEqual([
-      expect.objectContaining({
-        id: 'assistant-planning-error',
-        text: '画布 Agent 的 LLM 未配置，无法处理这句话。',
-        status: 'failed',
-      }),
-    ]);
-  });
-
-  it('shows a failed tool completion as a generation record', async () => {
-    const client = createClient();
-    vi.mocked(client.streamMessage).mockImplementation(
-      async (_conversationId, _payload, options) => {
-        options.onEvent?.({
-          event: 'message_delta',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-failed',
-            role: 'assistant',
-            kind: 'chat',
-            textDelta: '我先尝试生成。',
-          },
-        });
-        options.onEvent?.({
-          event: 'tool_started',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-failed',
-            toolCallId: 'tool-call-failed',
-            toolName: 'generate_image',
-            taskId: null,
-            model: 'gpt-image-2',
-            status: 'generating',
-          },
-        });
-        options.onEvent?.({
-          event: 'tool_completed',
-          data: {
-            conversationId: 'conversation-1',
-            messageId: 'assistant-failed',
-            toolCallId: 'tool-call-failed',
-            toolName: 'generate_image',
-            taskId: null,
-            model: 'gpt-image-2',
-            status: 'failed',
-            error: '泥点余额不足',
-          },
-        });
-        options.onEvent?.({
-          event: 'error',
-          data: {
-            conversationId: 'conversation-1',
-            code: 'INSUFFICIENT_BALANCE',
-            message: '泥点余额不足',
-            recoverable: true,
-          },
-        });
-      },
-    );
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({ projectId: 'project-1', client }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.activeConversation?.conversationId).toBe(
-        'conversation-1',
-      );
-    });
-
-    await act(async () => {
-      await expect(
-        result.current.sendMessage('生成一张图'),
-      ).resolves.toBeUndefined();
-    });
-
-    const failedMessage = result.current.messages.find(
-      (message) => message.id === 'assistant-failed',
-    );
-    expect(failedMessage?.status).toBe('failed');
-    expect(failedMessage?.generations).toEqual([
-      expect.objectContaining({
-        toolCallId: 'tool-call-failed',
-        status: 'failed',
-        model: 'gpt-image-2',
-        error: '泥点余额不足',
-      }),
-    ]);
-    expect(result.current.errorMessage).toBe('泥点余额不足');
-  });
-
-  it('aborts the active stream and marks streaming messages as stopped', async () => {
-    const client = createClient();
-    let streamSignal: AbortSignal | null = null;
-    vi.mocked(client.streamMessage).mockImplementation(
-      (_conversationId, _payload, options) =>
-        new Promise<void>((resolve) => {
-          streamSignal = options.signal ?? null;
-          options.onEvent?.({
-            event: 'message_delta',
-            data: {
-              conversationId: 'conversation-1',
-              messageId: 'assistant-streaming',
-              role: 'assistant',
-              kind: 'chat',
-              textDelta: '处理中',
-            },
-          });
-          streamSignal?.addEventListener('abort', () => resolve(), {
-            once: true,
-          });
-        }),
-    );
-    const { result } = renderHook(() =>
-      useEditorAgentConversation({ projectId: 'project-1', client }),
-    );
-
-    await waitFor(() => {
-      expect(result.current.activeConversation?.conversationId).toBe(
-        'conversation-1',
-      );
-    });
-
-    void act(() => {
-      void result.current.sendMessage('请继续');
-    });
-    await waitFor(() => {
-      expect(result.current.isStreaming).toBe(true);
-    });
-
-    act(() => {
-      result.current.stopCurrentTurn();
-    });
-
-    await waitFor(() => {
-      expect(streamSignal?.aborted).toBe(true);
-    });
-    expect(result.current.messages.at(-1)?.status).toBe('stopped');
-    expect(result.current.isStreaming).toBe(false);
-  });
-});
diff --git a/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx b/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
index 020386c18..b1d3465cf 100644
--- a/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
@@ -157,9 +157,15 @@ function AssetCleanupHarness({
       sourceAssetId: 'asset-2',
     }),
   ],
+  onDeleteLayerSideEffects = vi.fn(),
+  discardHistoryEntriesContainingLayer = vi.fn(),
 }: {
   deletedAssets?: EditorAsset[];
   initialLayers?: CanvasLayer[];
+  onDeleteLayerSideEffects?: (layerId: string) => void;
+  discardHistoryEntriesContainingLayer?: (
+    matchesLayer: (layer: CanvasLayer) => boolean,
+  ) => void;
 }) {
   const [layers, setLayers] = useState(initialLayers);
   const [selectedLayerId, setSelectedLayerId] = useState<string | null>('linked');
@@ -169,6 +175,8 @@ function AssetCleanupHarness({
     setLayers,
     setSelectedLayerId,
     setSelectedLayerIds,
+    onDeleteLayerSideEffects,
+    discardHistoryEntriesContainingLayer,
   });
 
   return (
@@ -245,7 +253,17 @@ describe('useImageCanvasAssetCanvasBridge', () => {
   });
 
   it('removes canvas layers linked to deleted assets and keeps unrelated selection', () => {
-    render(<AssetCleanupHarness deletedAssets={[defaultAsset]} />);
+    const onDeleteLayerSideEffects = vi.fn();
+    const discardHistoryEntriesContainingLayer = vi.fn();
+    render(
+      <AssetCleanupHarness
+        deletedAssets={[defaultAsset]}
+        onDeleteLayerSideEffects={onDeleteLayerSideEffects}
+        discardHistoryEntriesContainingLayer={
+          discardHistoryEntriesContainingLayer
+        }
+      />,
+    );
 
     act(() => {
       screen.getByRole('button', { name: '清理素材' }).click();
@@ -254,6 +272,46 @@ describe('useImageCanvasAssetCanvasBridge', () => {
     expect(screen.getByTestId('layers').textContent).toBe('kept');
     expect(screen.getByTestId('selected').textContent).toBe('-');
     expect(screen.getByTestId('selected-many').textContent).toBe('kept');
+    expect(onDeleteLayerSideEffects).toHaveBeenCalledWith('linked');
+    const matchesLayer =
+      discardHistoryEntriesContainingLayer.mock.calls[0]?.[0];
+    expect(discardHistoryEntriesContainingLayer).toHaveBeenCalledTimes(1);
+    expect(matchesLayer(createLayer({ sourceAssetId: 'asset-1' }))).toBe(true);
+    expect(
+      matchesLayer(
+        createLayer({
+          id: 'layer-other',
+          resourceId: 'resource-other',
+          src: 'data:image/png;base64,other',
+          objectKey: 'uploads/other.png',
+          assetObjectId: 'asset-object-other',
+          sourceResourceId: 'source-resource-other',
+          sourceAssetId: 'asset-other',
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it('invalidates matching history even when no linked layer is currently mounted', () => {
+    const discardHistoryEntriesContainingLayer = vi.fn();
+    render(
+      <AssetCleanupHarness
+        deletedAssets={[defaultAsset]}
+        initialLayers={[]}
+        discardHistoryEntriesContainingLayer={
+          discardHistoryEntriesContainingLayer
+        }
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '清理素材' }).click();
+    });
+
+    const matchesLayer =
+      discardHistoryEntriesContainingLayer.mock.calls[0]?.[0];
+    expect(discardHistoryEntriesContainingLayer).toHaveBeenCalledTimes(1);
+    expect(matchesLayer(createLayer({ sourceAssetId: 'asset-1' }))).toBe(true);
   });
 
   it('removes canvas layers linked by the asset source resource id', () => {
diff --git a/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts b/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
index 73148f038..345a2dde9 100644
--- a/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
@@ -13,6 +13,7 @@ import {
 } from './ImageCanvasEditorModel';
 import type {
   AssetPointerDragState,
+  CanvasHistoryAction,
   CanvasLayer,
   CanvasViewport,
   EditorAsset,
@@ -34,6 +35,10 @@ type UseImageCanvasAssetLayerCleanupOptions = {
   setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
   setSelectedLayerId: Dispatch<SetStateAction<string | null>>;
   setSelectedLayerIds: Dispatch<SetStateAction<string[]>>;
+  onDeleteLayerSideEffects?: (layerId: string) => void;
+  discardHistoryEntriesContainingLayer?: (
+    matchesLayer: (layer: CanvasLayer) => boolean,
+  ) => void;
 };
 
 type UseImageCanvasAssetCanvasBridgeOptions = {
@@ -53,7 +58,7 @@ type UseImageCanvasAssetCanvasBridgeOptions = {
   setHoveredLayerId: Dispatch<SetStateAction<string | null>>;
   updateAssetMoveDropFolder: (folderId: string | null) => void;
   moveAssetToFolder: (assetId: string, folderId: string) => void;
-  captureCanvasHistory: () => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
   selectSingleLayer: (layerId: string | null) => void;
   addUploadedFiles: (
@@ -67,12 +72,22 @@ export function useImageCanvasAssetLayerCleanup({
   setLayers,
   setSelectedLayerId,
   setSelectedLayerIds,
+  onDeleteLayerSideEffects,
+  discardHistoryEntriesContainingLayer,
 }: UseImageCanvasAssetLayerCleanupOptions) {
   return useCallback(
     (deletedAssets: EditorAsset[]) => {
       if (!deletedAssets.length) {
         return;
       }
+      discardHistoryEntriesContainingLayer?.((layer) =>
+        deletedAssets.some((asset) => isLayerLinkedToAsset(layer, asset)),
+      );
+      const deletedLayerIds = layers
+        .filter((layer) =>
+          deletedAssets.some((asset) => isLayerLinkedToAsset(layer, asset)),
+        )
+        .map((layer) => layer.id);
       setLayers((currentLayers) =>
         currentLayers.filter(
           (layer) =>
@@ -100,8 +115,18 @@ export function useImageCanvasAssetLayerCleanup({
           ? null
           : currentId;
       });
+      deletedLayerIds.forEach((layerId) =>
+        onDeleteLayerSideEffects?.(layerId),
+      );
     },
-    [layers, setLayers, setSelectedLayerId, setSelectedLayerIds],
+    [
+      discardHistoryEntriesContainingLayer,
+      layers,
+      onDeleteLayerSideEffects,
+      setLayers,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    ],
   );
 }
 
@@ -141,7 +166,7 @@ export function useImageCanvasAssetCanvasBridge({
         },
         { applyCascadeOffset: position === undefined },
       );
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'add-image', count: 1 });
       appendCanvasLayersWithResources([nextLayer]);
       selectSingleLayer(nextLayer.id);
       setHoveredLayerId(null);
diff --git a/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts b/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
index 0e6245e4b..c011b1c54 100644
--- a/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
@@ -7,8 +7,8 @@ import type {
   CanvasLayer,
 } from './ImageCanvasEditorTypes';
 import {
-  buildAnimatedGifPreviewBytes,
   blobToUint8Array,
+  buildAnimatedGifPreviewBytes,
   buildLayerExportMetadata,
   buildLayerVisibleExportMetadata,
   buildSpineImageSequenceJson,
diff --git a/src/components/image-editor/useImageCanvasAssetLibrary.ts b/src/components/image-editor/useImageCanvasAssetLibrary.ts
index db016cb2a..f9a5cc191 100644
--- a/src/components/image-editor/useImageCanvasAssetLibrary.ts
+++ b/src/components/image-editor/useImageCanvasAssetLibrary.ts
@@ -19,11 +19,6 @@ import {
   updateEditorAsset,
   updateEditorAssetFolder,
 } from '../../services/image-editor/editorProjectClient';
-import {
-  EDITOR_ASSET_FOLDERS,
-  escapeCssIdentifier,
-  normalizeAssetLibrary,
-} from './ImageCanvasEditorModel';
 import {
   areAllSelectableAssetsSelected,
   createAssetMarqueeFromPointer,
@@ -32,23 +27,28 @@ import {
   deleteAssetFolderLocally,
   getSelectableAssets,
   groupAssetsByFolder,
-  moveAssetToFolderLocally,
   moveAssetMarqueeToPointer,
+  moveAssetToFolderLocally,
   removeAssetById,
   removeSelectedAssets,
   renameAssetById,
   renameAssetFolderById,
   replaceLocalAssetFolder,
-  resolveAssetShowcaseSubmissionState,
   resolveAllAssetSelection,
-  resolveDefaultAssetFolder,
   resolveAssetFolderIdFromPoint,
+  resolveAssetShowcaseSubmissionState,
+  resolveDefaultAssetFolder,
   resolvePinnedAssetMoveFolderId,
   selectUploadedAssetsInRect,
   shouldStartAssetMarquee,
   toggleAssetFolderCollapsed,
   toggleAssetSelection,
 } from './ImageCanvasAssetLibraryModel';
+import {
+  EDITOR_ASSET_FOLDERS,
+  escapeCssIdentifier,
+  normalizeAssetLibrary,
+} from './ImageCanvasEditorModel';
 import type {
   AssetMarqueeState,
   AssetPointerDragState,
diff --git a/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts
index 48f961876..224ebee45 100644
--- a/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts
@@ -1,6 +1,6 @@
 import {
-  type DragEvent as ReactDragEvent,
   type Dispatch,
+  type DragEvent as ReactDragEvent,
   type SetStateAction,
   useCallback,
   useMemo,
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
index 119962679..b7b497ff8 100644
--- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
@@ -13,6 +13,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { ApiClientError } from '../../services/apiClient';
 import type {
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
   CanvasLayer,
   CanvasTool,
   CharacterAnimationPanelState,
@@ -189,10 +190,14 @@ function SubmissionWorkflowHarness({
   initialCharacterAnimationPanel = null,
   initialLayers = [createLayer()],
   projectId = undefined,
+  assetFolderId = projectId ? 'project' : undefined,
   upsertGeneratedAsset = undefined,
   applyProjectSnapshot = undefined,
   onQueuedGenerationTask = undefined,
   onWalletBalanceMayHaveChanged = undefined,
+  captureCanvasHistory = () => undefined,
+  fitLayers = undefined,
+  onAppendCanvasLayers = undefined,
 }: {
   initialDialog?: GenerateDialogState | null;
   initialQuickEditPanel?: QuickEditPanelState | null;
@@ -200,6 +205,7 @@ function SubmissionWorkflowHarness({
   initialCharacterAnimationPanel?: CharacterAnimationPanelState | null;
   initialLayers?: CanvasLayer[];
   projectId?: string | null;
+  assetFolderId?: string | null;
   upsertGeneratedAsset?: Parameters<
     typeof useImageCanvasGenerationSubmissionWorkflow
   >[0]['upsertGeneratedAsset'];
@@ -212,6 +218,12 @@ function SubmissionWorkflowHarness({
   onWalletBalanceMayHaveChanged?: Parameters<
     typeof useImageCanvasGenerationSubmissionWorkflow
   >[0]['onWalletBalanceMayHaveChanged'];
+  captureCanvasHistory?: (action: CanvasHistoryAction) => void;
+  fitLayers?: (
+    targetLayers?: CanvasLayer[],
+    options?: { captureHistory?: boolean },
+  ) => void;
+  onAppendCanvasLayers?: (nextLayers: CanvasLayer[]) => void;
 }) {
   const [layers, setLayers] = useState<CanvasLayer[]>(initialLayers);
   const [activeTool, setActiveTool] = useState<CanvasTool>('generate');
@@ -228,7 +240,14 @@ function SubmissionWorkflowHarness({
     null,
   );
   const rememberedImageModelRef = useRef<string | null>(null);
-  const fitLayersMockRef = useRef(vi.fn());
+  const fitLayersRef = useRef(fitLayers);
+  fitLayersRef.current = fitLayers;
+  const fitLayersMockRef = useRef(
+    vi.fn(
+      (targetLayers?: CanvasLayer[], options?: { captureHistory?: boolean }) =>
+        fitLayersRef.current?.(targetLayers, options),
+    ),
+  );
   const layerCounterRef = useRef(0);
   const dialogs = useCanvasGenerationDialogs();
 
@@ -267,8 +286,11 @@ function SubmissionWorkflowHarness({
     updateCanvasGenerationDialogById: dialogs.updateCanvasGenerationDialogById,
     hasCanvasGenerationDialogById: dialogs.hasCanvasGenerationDialogById,
     getGeneratingDialogPlaceholder: dialogs.getGeneratingDialogPlaceholder,
-    appendCanvasLayersWithResources: (nextLayers) =>
-      setLayers((currentLayers) => [...currentLayers, ...nextLayers]),
+    appendCanvasLayersWithResources: (nextLayers) => {
+      onAppendCanvasLayers?.(nextLayers);
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
+    },
+    captureCanvasHistory,
     updateSourceLayer: (sourceLayerId, updater) =>
       setLayers((currentLayers) =>
         currentLayers.map((layer) =>
@@ -283,7 +305,7 @@ function SubmissionWorkflowHarness({
       rememberedImageModelRef.current = imageModel;
     },
     projectId,
-    assetFolderId: projectId ? 'project' : undefined,
+    assetFolderId,
     upsertGeneratedAsset,
     applyProjectSnapshot,
     onQueuedGenerationTask,
@@ -537,14 +559,47 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(firstOptions.pathSegments).not.toEqual(secondOptions.pathSegments);
   });
 
+  it('uploads image references without an object reference before generation', async () => {
+    resolveEditorImageReferenceDataUrlMock.mockResolvedValueOnce(
+      'data:image/png;base64,ZXhhbXBsZQ==',
+    );
+    const result = await resolveEditorGenerationMediaReference(
+      { src: '/creation-type-references/example.webp' },
+      'image',
+      'project-1',
+    );
+
+    expect(resolveEditorImageReferenceDataUrlMock).toHaveBeenCalledWith(
+      '/creation-type-references/example.webp',
+    );
+    expect(uploadEditorMediaAssetFileMock).toHaveBeenCalledWith(
+      expect.any(File),
+      'image',
+      expect.objectContaining({
+        assetKind: 'editor_generation_reference_image',
+      }),
+    );
+    expect(result).toBe(
+      'generated-character-drafts/editor/generation-references/reference.png',
+    );
+  });
+
   it('submits quick edits and updates the source layer directly', async () => {
     editEditorImageMock.mockResolvedValueOnce(
-      createGenerated({ prompt: '快速修图' }),
+      createGenerated({
+        prompt: '快速修图',
+        model: 'gemini-3.1-flash-image-preview',
+      }),
     );
     render(
       <SubmissionWorkflowHarness
         initialLayers={[
-          createLayer({ originalWidth: 1537, originalHeight: 1025 }),
+          createLayer({
+            originalWidth: 1537,
+            originalHeight: 1025,
+            assetKind: 'icon-spritesheet',
+            model: 'gemini-3.1-flash-image-preview',
+          }),
         ]}
       />,
     );
@@ -564,6 +619,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
           sourceImageSrc: 'resource-source',
           size: '2048x1365',
           model: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '3:2',
+          imageSize: '2K',
         }),
       );
     });
@@ -574,7 +631,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(resolveEditorImageReferenceDataUrlMock).not.toHaveBeenCalled();
     await waitFor(() => {
       expect(screen.getByTestId('layers').textContent).toContain(
-        'layer-source:源图 快速编辑:resource-source:-:-:data:image/png;base64,generated',
+        'layer-source:源图 快速编辑:resource-source:icon-spritesheet:-:data:image/png;base64,generated',
       );
     });
     expect(screen.getByTestId('quick-edit').textContent).toBe('-');
@@ -1029,7 +1086,14 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
 
   it('submits character redraws through the character image prompt contract', async () => {
     generateEditorImageMock.mockResolvedValueOnce(
-      createGenerated({ prompt: '角色换成蓝色披风' }),
+      createGenerated({
+        prompt: '角色换成蓝色披风',
+        warning: {
+          code: 'postprocess-failed-source-preserved',
+          reason:
+            '生成任务成功，后处理失败。',
+        },
+      }),
     );
     render(
       <SubmissionWorkflowHarness
@@ -1080,6 +1144,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(screen.getByTestId('quick-edit').textContent).toBe(
       'layer-source:idle:角色换成蓝色披风:-',
     );
+    expect(screen.getByTestId('generation-warning').textContent).toBe(
+      '生成任务成功，后处理失败。',
+    );
   });
 
   it('submits video quick edits through the video API with the source video', async () => {
@@ -1311,12 +1378,19 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     });
   });
 
-  it('submits edit dialogs beside the source and clears the modal state', async () => {
+  it('captures a local edit fallback when the project response has no snapshot', async () => {
+    const applyProjectSnapshot = vi.fn();
+    const captureCanvasHistory = vi.fn();
+    const fitLayers = vi.fn();
     editEditorImageMock.mockResolvedValueOnce(
       createGenerated({ prompt: '修改当前图片' }),
     );
     render(
       <SubmissionWorkflowHarness
+        projectId="project-edit-size"
+        applyProjectSnapshot={applyProjectSnapshot}
+        captureCanvasHistory={captureCanvasHistory}
+        fitLayers={fitLayers}
         initialDialog={{
           mode: 'edit',
           prompt: '',
@@ -1337,6 +1411,16 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
         expect.objectContaining({
           prompt: '修改当前图片',
           sourceImageSrc: 'resource-source',
+          canvasCompletion: expect.objectContaining({
+            placeholder: {
+              x: 472,
+              y: 140,
+              width: 1024,
+              height: 768,
+              originalWidth: 1024,
+              originalHeight: 768,
+            },
+          }),
         }),
       );
     });
@@ -1348,14 +1432,32 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(screen.getByTestId('dialog').textContent).toBe('-');
     expect(screen.getByTestId('tool').textContent).toBe('select');
     expect(screen.getByTestId('fit-count').textContent).toBe('1');
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+    expect(captureCanvasHistory).toHaveBeenCalledWith({
+      type: 'generate-image',
+      count: 1,
+    });
+    expect(applyProjectSnapshot).not.toHaveBeenCalled();
+    expect(fitLayers).toHaveBeenCalledWith(expect.any(Array), {
+      captureHistory: false,
+    });
   });
 
   it('uses the latest moved canvas placeholder for local-only generation fallback', async () => {
+    const callOrder: string[] = [];
+    const captureCanvasHistory = vi.fn((action: CanvasHistoryAction) => {
+      callOrder.push(`capture:${action.type}:${action.count}`);
+    });
+    const onAppendCanvasLayers = vi.fn(() => {
+      callOrder.push('append');
+    });
     generateEditorImageMock.mockResolvedValueOnce(
       createGenerated({ width: 512, height: 512 }),
     );
     render(
       <SubmissionWorkflowHarness
+        captureCanvasHistory={captureCanvasHistory}
+        onAppendCanvasLayers={onAppendCanvasLayers}
         initialDialog={{
           id: 'dialog-1',
           mode: 'generate',
@@ -1386,10 +1488,17 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(screen.getByTestId('dialog').textContent).toBe(
       'generate:idle:open:layer-generated-1:placeholder:-',
     );
+    expect(captureCanvasHistory).toHaveBeenCalledWith({
+      type: 'generate-image',
+      count: 1,
+    });
+    expect(onAppendCanvasLayers).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual(['capture:generate-image:1', 'append']);
   });
 
   it('passes canvas completion context and refreshes from the backend project snapshot', async () => {
     const applyProjectSnapshot = vi.fn();
+    const captureCanvasHistory = vi.fn();
     generateEditorImageMock.mockResolvedValueOnce({
       ...createGenerated({
         width: 1024,
@@ -1438,6 +1547,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       <SubmissionWorkflowHarness
         projectId="editor-project-1"
         applyProjectSnapshot={applyProjectSnapshot}
+        captureCanvasHistory={captureCanvasHistory}
         initialDialog={{
           id: 'dialog-character',
           mode: 'character',
@@ -1512,6 +1622,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(screen.getByTestId('layers').textContent).not.toContain(
       'layer-generated-1',
     );
+    expect(captureCanvasHistory).not.toHaveBeenCalled();
   });
 
   it('submits audio generations with asset library context and upserts the returned asset', async () => {
@@ -1653,7 +1764,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(uploadEditorMediaAssetFileMock).not.toHaveBeenCalled();
   });
 
-  it('refreshes the wallet balance after a queued generation reaches a terminal state', async () => {
+  it('refreshes the wallet and shows the warning after a queued character generation completes', async () => {
     const applyProjectSnapshot = vi.fn();
     const refreshTaskList = vi.fn();
     const refreshWalletBalance = vi.fn();
@@ -1671,9 +1782,12 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
         imageSrc: '/generated-editor-images/project/image.png',
         width: 1024,
         height: 1024,
-        prompt: '队列生成',
+        prompt: '队列角色生成',
+      }),
+      queueState: createQueueState({
+        warning:
+          '生成任务成功，后处理失败。',
       }),
-      queueState: createQueueState(),
     });
     render(
       <SubmissionWorkflowHarness
@@ -1682,9 +1796,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
         onQueuedGenerationTask={refreshTaskList}
         onWalletBalanceMayHaveChanged={refreshWalletBalance}
         initialDialog={{
-          id: 'dialog-generate',
-          mode: 'generate',
-          prompt: '队列生成',
+          id: 'dialog-character',
+          mode: 'character',
+          prompt: '队列角色生成',
           status: 'idle',
           composerOpen: true,
           imageModel: 'gpt-image-2',
@@ -1712,6 +1826,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(refreshWalletBalance).toHaveBeenCalledTimes(1);
     expect(applyProjectSnapshot).toHaveBeenCalledWith(backendProject);
     expect(getExternalGenerationJobStatusMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('generation-warning').textContent).toBe(
+      '生成任务成功，后处理失败。',
+    );
     expect(screen.getByTestId('layers').textContent).not.toContain(
       'layer-generated-1',
     );
@@ -1805,7 +1922,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     await applyQueuedEditorGenerationProject(
       {
         queueState: createQueueState({
-          warning: '连通域数量不足',
+          warning:
+            '生成任务成功，后处理失败。',
         }),
       },
       'editor-project-1',
@@ -1816,7 +1934,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     );
 
     expect(onGenerationWarning).toHaveBeenCalledWith(
-      '图集已生成，但自动拆分未完成：连通域数量不足',
+      '生成任务成功，后处理失败。',
     );
   });
 
@@ -2004,6 +2122,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
           prompt: expect.stringContaining('【宣发素材类型】详情页单图'),
           size: '720x1280',
           kind: 'publication-material',
+          assetKind: 'publication-material',
           model: 'gpt-image-2',
           aspectRatio: '9:16',
           imageSize: '1K',
@@ -2019,7 +2138,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(prompt).toContain('不是五图合集或拼贴');
     await waitFor(() => {
       expect(screen.getByTestId('layers').textContent).toContain(
-        'layer-generated-1:1 宣发素材:-:-',
+        'layer-generated-1:1 宣发素材:-:publication-material:-',
       );
     });
     expect(screen.getByTestId('layers').textContent).not.toContain(
@@ -2321,6 +2440,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
   });
 
   it('extracts UI design assets into a spritesheet layer and sliced icon layers', async () => {
+    const captureCanvasHistory = vi.fn();
+    const fitLayers = vi.fn();
     extractEditorUiDesignAssetsMock.mockResolvedValueOnce({
       spritesheetImageSrc: 'data:image/png;base64,ui-sheet',
       spritesheetWidth: 512,
@@ -2338,6 +2459,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     });
     render(
       <SubmissionWorkflowHarness
+        captureCanvasHistory={captureCanvasHistory}
+        fitLayers={fitLayers}
         initialLayers={[
           createLayer({
             assetKind: 'ui-design',
@@ -2374,6 +2497,14 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       'layer-icon-spritesheet-1',
     );
     expect(screen.getByTestId('fit-count').textContent).toBe('1');
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+    expect(captureCanvasHistory).toHaveBeenCalledWith({
+      type: 'generate-image',
+      count: 2,
+    });
+    expect(fitLayers).toHaveBeenCalledWith(expect.any(Array), {
+      captureHistory: false,
+    });
   });
 
   it('keeps the extracted spritesheet when extracted icon results are missing', async () => {
@@ -2388,6 +2519,11 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'task-ui-assets',
+      warning: {
+        code: 'postprocess-failed-source-preserved',
+        reason:
+          '生成任务成功，后处理失败。',
+      },
     });
     render(
       <SubmissionWorkflowHarness
@@ -2414,6 +2550,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       'layer-icon-spritesheet-1',
     );
     expect(screen.getByTestId('fit-count').textContent).toBe('1');
+    expect(screen.getByTestId('generation-warning').textContent).toBe(
+      '生成任务成功，后处理失败。',
+    );
   });
 
   it('renders selected UI marks into the extraction reference image and sends derived extraction pricing', async () => {
@@ -2437,6 +2576,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     });
     render(
       <SubmissionWorkflowHarness
+        projectId="project-ui-extraction-size"
         initialLayers={[
           createLayer({
             assetKind: 'ui-design',
@@ -2478,6 +2618,16 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
           segModel: 'birefnet',
           aspectRatio: '1:1',
           imageSize: '2K',
+          canvasCompletion: expect.objectContaining({
+            placeholder: {
+              x: 472,
+              y: 140,
+              width: 2048,
+              height: 2048,
+              originalWidth: 2048,
+              originalHeight: 2048,
+            },
+          }),
           generationInputs: expect.objectContaining({
             fields: expect.arrayContaining([
               expect.objectContaining({
@@ -2545,7 +2695,15 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
 
   it('keeps character generation dialog data after the result is created', async () => {
     generateEditorImageMock.mockResolvedValueOnce(
-      createGenerated({ width: 768, height: 768 }),
+      createGenerated({
+        width: 768,
+        height: 768,
+        warning: {
+          code: 'postprocess-failed-source-preserved',
+          reason:
+            '生成任务成功，后处理失败。',
+        },
+      }),
     );
     render(
       <SubmissionWorkflowHarness
@@ -2584,6 +2742,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     expect(screen.getByTestId('dialog').textContent).toBe(
       'character:idle:open:layer-generated-1:placeholder:-',
     );
+    expect(screen.getByTestId('generation-warning').textContent).toBe(
+      '生成任务成功，后处理失败。',
+    );
   });
 
   it('moves character animation panels from generating to completed', async () => {
@@ -2638,6 +2799,63 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     });
   });
 
+  it('uses updated character animation folder and queue callbacks after rerender', async () => {
+    const firstQueuedTaskCallback = vi.fn();
+    const latestQueuedTaskCallback = vi.fn();
+    generateEditorCharacterAnimationMock.mockResolvedValueOnce({
+      taskId: 'animation-task-queued',
+      queueState: createQueueState({ status: 'queued' }),
+      project: {
+        id: 'editor-project-1',
+      },
+    });
+    const harnessProps = {
+      projectId: 'editor-project-1',
+      initialLayers: [
+        createLayer({
+          id: 'character-layer',
+          assetKind: 'character' as const,
+          objectKey: 'generated/character.png',
+        }),
+      ],
+      initialCharacterAnimationPanel: {
+        sourceLayerId: 'character-layer',
+        promptText: '跑步',
+        resolution: '480p' as const,
+        ratio: 'same' as const,
+        frameCount: 32 as const,
+        durationSeconds: 4 as const,
+        status: 'idle' as const,
+      },
+    };
+    const { rerender } = render(
+      <SubmissionWorkflowHarness
+        {...harnessProps}
+        assetFolderId="folder-before"
+        onQueuedGenerationTask={firstQueuedTaskCallback}
+      />,
+    );
+
+    rerender(
+      <SubmissionWorkflowHarness
+        {...harnessProps}
+        assetFolderId="folder-latest"
+        onQueuedGenerationTask={latestQueuedTaskCallback}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: '提交角色动画' }));
+
+    await waitFor(() => {
+      expect(generateEditorCharacterAnimationMock).toHaveBeenCalledWith(
+        expect.objectContaining({ assetFolderId: 'folder-latest' }),
+      );
+    });
+    await waitFor(() => {
+      expect(latestQueuedTaskCallback).toHaveBeenCalledTimes(1);
+    });
+    expect(firstQueuedTaskCallback).not.toHaveBeenCalled();
+  });
+
   it('does not resubmit character animation while it is already generating', () => {
     render(
       <SubmissionWorkflowHarness
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
index 0a12470a8..9875a0887 100644
--- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
@@ -32,6 +32,7 @@ import {
 import type {
   CanvasGenerationDialogState,
   CanvasGenerationInputs,
+  CanvasHistoryAction,
   CanvasLayer,
   CanvasTool,
   CanvasViewport,
@@ -61,9 +62,6 @@ import {
   DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR,
   DEFAULT_IMAGE_MODEL,
   DEFAULT_VIDEO_MODEL,
-  ICON_FRAME_DISPLAY_SIZE,
-  ICON_FRAME_ORIGINAL_SIZE,
-  IMAGE_MODEL_GPT_IMAGE_2,
   inferEditorImageAspectRatio,
   inferEditorImageSizeLabel,
   isCanvasGenerationDialog,
@@ -88,6 +86,9 @@ import { renderUiDesignAssetExtractionMarkedImage } from './ImageCanvasUiAssetEx
 
 type CanvasSize = { width: number; height: number };
 
+const EDITOR_SPRITESHEET_SLICE_WARNING_PREFIX =
+  '图集已生成，但自动拆分未完成：';
+
 type CanvasGenerationDialogUpdater = (
   dialog: CanvasGenerationDialogState,
 ) => CanvasGenerationDialogState | null;
@@ -215,20 +216,27 @@ export async function resolveEditorGenerationMediaReference(
   projectId?: string | null,
   options: EditorGenerationMediaReferenceOptions = {},
 ) {
+  const resourceId = reference.resourceId?.trim();
+  const hasRegisteredReference =
+    options.allowRegisteredIds !== false &&
+    ((resourceId &&
+      !resourceId.startsWith('local-resource-') &&
+      !resourceId.startsWith('generation-dialog:')) ||
+      reference.sourceAssetId?.trim());
   const source = resolveEditorGenerationMediaReferenceSource(
     reference,
     options.allowRegisteredIds !== false,
   );
   const inlineSource = /^(?:data|blob):/iu.test(source);
-  const remoteImageSource =
-    options.requireImageObjectReference === true &&
+  const imageSourceRequiresUpload =
+    options.requireImageObjectReference !== false &&
     mediaType === 'image' &&
     !reference.objectKey?.trim() &&
-    /^(?:https?:|\/api\/)/iu.test(source);
-  if (!inlineSource && !remoteImageSource) {
+    !hasRegisteredReference;
+  if (!inlineSource && !imageSourceRequiresUpload) {
     return source;
   }
-  const uploadSource = remoteImageSource
+  const uploadSource = imageSourceRequiresUpload && !inlineSource
     ? await resolveEditorImageReferenceDataUrl(source)
     : source;
   return uploadEditorGenerationInlineMediaSource(
@@ -278,13 +286,17 @@ type GenerationSubmissionWorkflowOptions = {
     dialog: GenerateDialogState,
   ) => GenerateDialogState['placeholder'];
   appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   updateSourceLayer: (
     sourceLayerId: string,
     updater: (layer: CanvasLayer) => CanvasLayer,
     options?: { fit?: boolean; persist?: boolean },
   ) => void;
   selectSingleLayer: (layerId: string | null) => void;
-  fitLayers: (targetLayers?: CanvasLayer[]) => void;
+  fitLayers: (
+    targetLayers?: CanvasLayer[],
+    options?: { captureHistory?: boolean },
+  ) => void;
   setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
   setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
   rememberImageModel: (imageModel: string) => void;
@@ -438,7 +450,21 @@ function notifyEditorGenerationWarning(
   if (!reason) {
     return;
   }
-  callback?.(`图集已生成，但自动拆分未完成：${reason}`);
+  callback?.(reason);
+}
+
+function resolveEditorGenerationWarningMessage(
+  warning: string | null | undefined,
+  sliceWarning: string | null | undefined,
+) {
+  const commonReason = warning?.trim();
+  if (commonReason) {
+    return commonReason;
+  }
+  const sliceReason = sliceWarning?.trim();
+  return sliceReason
+    ? `${EDITOR_SPRITESHEET_SLICE_WARNING_PREFIX}${sliceReason}`
+    : undefined;
 }
 
 async function runEditorGenerationWithWalletRefresh<T>(
@@ -579,6 +605,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
   hasCanvasGenerationDialogById,
   getGeneratingDialogPlaceholder,
   appendCanvasLayersWithResources,
+  captureCanvasHistory,
   updateSourceLayer,
   selectSingleLayer,
   fitLayers,
@@ -595,6 +622,13 @@ export function useImageCanvasGenerationSubmissionWorkflow({
 }: GenerationSubmissionWorkflowOptions) {
   const addGeneratedLayersToCanvas = useCallback(
     (nextLayers: CanvasLayer[]) => {
+      if (!nextLayers.length) {
+        return;
+      }
+      captureCanvasHistory({
+        type: 'generate-image',
+        count: nextLayers.length,
+      });
       appendCanvasLayersWithResources(nextLayers);
       nextLayers.forEach((layer) => {
         const asset = layer.generatedAssetSnapshot;
@@ -603,7 +637,11 @@ export function useImageCanvasGenerationSubmissionWorkflow({
         }
       });
     },
-    [appendCanvasLayersWithResources, upsertGeneratedAsset],
+    [
+      appendCanvasLayersWithResources,
+      captureCanvasHistory,
+      upsertGeneratedAsset,
+    ],
   );
 
   const addGeneratedResultLayer = useCallback(
@@ -654,7 +692,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
         }));
       }
       if (options.sourceLayer) {
-        fitLayers([options.sourceLayer, nextLayer]);
+        fitLayers([options.sourceLayer, nextLayer], { captureHistory: false });
       }
     },
     [
@@ -732,7 +770,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
           );
         }
       }
-      fitLayers([sourceLayer, nextLayer]);
+      fitLayers([sourceLayer, nextLayer], { captureHistory: false });
     },
     [
       addGeneratedLayersToCanvas,
@@ -1062,13 +1100,18 @@ export function useImageCanvasGenerationSubmissionWorkflow({
         const extractionPlan = resolveUiAssetExtractionGenerationPlan(
           options.marks?.length ?? 0,
         );
+        const extractionSize = resolveEditorImageGenerationPixelSize({
+          model: options.model ?? DEFAULT_IMAGE_MODEL,
+          aspectRatio: extractionPlan.aspectRatio,
+          imageSize: extractionPlan.imageSize,
+        });
         const extractionFrame = {
           x: sourceLayer.x + sourceLayer.width + 32,
           y: sourceLayer.y,
-          width: ICON_FRAME_DISPLAY_SIZE.width,
-          height: ICON_FRAME_DISPLAY_SIZE.height,
-          originalWidth: ICON_FRAME_ORIGINAL_SIZE.width,
-          originalHeight: ICON_FRAME_ORIGINAL_SIZE.height,
+          width: extractionSize.width,
+          height: extractionSize.height,
+          originalWidth: extractionSize.width,
+          originalHeight: extractionSize.height,
         };
         const generated = await runEditorGenerationWithWalletRefresh(
           extractEditorUiDesignAssets({
@@ -1097,7 +1140,10 @@ export function useImageCanvasGenerationSubmissionWorkflow({
           onWalletBalanceMayHaveChanged,
         );
         notifyEditorGenerationWarning(
-          generated.sliceWarning?.reason,
+          resolveEditorGenerationWarningMessage(
+            generated.warning?.reason,
+            generated.sliceWarning?.reason,
+          ),
           onGenerationWarning,
         );
         if (
@@ -1127,7 +1173,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
           },
         );
         if (nextLayers.length) {
-          fitLayers([sourceLayer, ...nextLayers]);
+          fitLayers([sourceLayer, ...nextLayers], { captureHistory: false });
         }
       } catch (error) {
         if (options.suppressAlert) {
@@ -1147,6 +1193,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
       projectId,
       assetFolderId,
       onGenerationWarning,
+      onQueuedGenerationTask,
       onWalletBalanceMayHaveChanged,
     ],
   );
@@ -1234,7 +1281,10 @@ export function useImageCanvasGenerationSubmissionWorkflow({
         );
         rememberImageModel(submissionPlan.rememberImageModel);
         notifyEditorGenerationWarning(
-          generated.sliceWarning?.reason,
+          resolveEditorGenerationWarningMessage(
+            generated.warning?.reason,
+            generated.sliceWarning?.reason,
+          ),
           onGenerationWarning,
         );
         if (
@@ -1281,6 +1331,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
       assetFolderId,
       updateCanvasGenerationDialogById,
       onGenerationWarning,
+      onQueuedGenerationTask,
       onWalletBalanceMayHaveChanged,
     ],
   );
@@ -1547,6 +1598,8 @@ export function useImageCanvasGenerationSubmissionWorkflow({
                 sourceImageSrc: sourceReferenceImageSrc,
                 size: quickEditSize,
                 model: normalizedQuickEditModel,
+                aspectRatio: quickEditAspectRatio,
+                imageSize: quickEditImageSize,
                 ...(extraReferenceImageSrcs.length
                   ? { referenceImageSrcs: extraReferenceImageSrcs }
                   : {}),
@@ -1590,6 +1643,15 @@ export function useImageCanvasGenerationSubmissionWorkflow({
               }),
               onWalletBalanceMayHaveChanged,
             );
+      const characterWarningCallback = isCharacterRedraw
+        ? onGenerationWarning
+        : undefined;
+      if (isCharacterRedraw) {
+        notifyEditorGenerationWarning(
+          generated.warning?.reason,
+          characterWarningCallback,
+        );
+      }
       if (
         await applyQueuedEditorGenerationProject(
           generated,
@@ -1597,6 +1659,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
           applyProjectSnapshot,
           onQueuedGenerationTask,
           onWalletBalanceMayHaveChanged,
+          characterWarningCallback,
         )
       ) {
         if (panelMode === 'quick-edit') {
@@ -1662,9 +1725,9 @@ export function useImageCanvasGenerationSubmissionWorkflow({
       });
     }
   }, [
-    addCharacterAnimationResultLayer,
     addQuickEditResultLayer,
     addVideoResultLayer,
+    applyQuickEditResultToSourceLayer,
     applyProjectSnapshot,
     canvasGenerationDialogs,
     canvasSize,
@@ -1678,9 +1741,13 @@ export function useImageCanvasGenerationSubmissionWorkflow({
     quickEditSourceLayer,
     quickEditSelectionState,
     selectSingleLayer,
+    setActiveSidebarPanel,
+    setActiveTool,
     setQuickEditPanel,
     updateCanvasGenerationDialogById,
     viewport,
+    onGenerationWarning,
+    onQueuedGenerationTask,
     onWalletBalanceMayHaveChanged,
   ]);
 
@@ -1731,10 +1798,10 @@ export function useImageCanvasGenerationSubmissionWorkflow({
             buildRightSideCanvasCompletionPlaceholder(
               submissionPlan.sourceLayer,
               {
-                width: 1024,
-                height: 1024,
-                originalWidth: 1024,
-                originalHeight: 1024,
+                width: submissionPlan.sourceLayer.originalWidth,
+                height: submissionPlan.sourceLayer.originalHeight,
+                originalWidth: submissionPlan.sourceLayer.originalWidth,
+                originalHeight: submissionPlan.sourceLayer.originalHeight,
               },
             );
           const generated = await runEditorGenerationWithWalletRefresh(
@@ -1999,6 +2066,16 @@ export function useImageCanvasGenerationSubmissionWorkflow({
             }),
             onWalletBalanceMayHaveChanged,
           );
+          const characterWarningCallback =
+            imageGenerationInput.kind === 'character'
+              ? onGenerationWarning
+              : undefined;
+          if (imageGenerationInput.kind === 'character') {
+            notifyEditorGenerationWarning(
+              generated.warning?.reason,
+              characterWarningCallback,
+            );
+          }
           if (
             await applyQueuedEditorGenerationProject(
               generated,
@@ -2006,6 +2083,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
               applyProjectSnapshot,
               onQueuedGenerationTask,
               onWalletBalanceMayHaveChanged,
+              characterWarningCallback,
             )
           ) {
             return;
@@ -2067,6 +2145,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
       addGeneratedResultLayer,
       addAudioResultLayer,
       addVideoResultLayer,
+      applyQuickEditResultToSourceLayer,
       getGeneratingDialogPlaceholder,
       layerCounterRef,
       layers,
@@ -2078,6 +2157,8 @@ export function useImageCanvasGenerationSubmissionWorkflow({
       setGenerateDialog,
       updateCanvasGenerationDialogById,
       upsertGeneratedAsset,
+      onGenerationWarning,
+      onQueuedGenerationTask,
       onWalletBalanceMayHaveChanged,
     ],
   );
@@ -2234,6 +2315,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
     }
   }, [
     addCharacterAnimationResultLayer,
+    assetFolderId,
     characterAnimationDialog,
     characterAnimationPanel,
     characterAnimationSourceLayer,
@@ -2243,6 +2325,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({
     setCharacterAnimationPanel,
     updateCanvasGenerationDialogById,
     onWalletBalanceMayHaveChanged,
+    onQueuedGenerationTask,
   ]);
 
   return useMemo(
diff --git a/src/components/image-editor/useImageCanvasGenerationSurface.tsx b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
index e132fdc64..240379ca1 100644
--- a/src/components/image-editor/useImageCanvasGenerationSurface.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
@@ -1,3 +1,4 @@
+import { X } from 'lucide-react';
 import {
   type CSSProperties,
   type Dispatch,
@@ -10,19 +11,19 @@ import {
   useRef,
 } from 'react';
 import { createPortal } from 'react-dom';
-import { X } from 'lucide-react';
 
+import type {
+  EditorAssetSnapshot,
+  EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
 import {
   PlatformFloatingMenu,
   PlatformFloatingMenuItem,
 } from '../common/PlatformFloatingMenu';
 import { PlatformRuntimeStatusToast } from '../common/PlatformRuntimeStatusToast';
-import type {
-  EditorAssetSnapshot,
-  EditorProjectSnapshot,
-} from '../../services/image-editor/editorProjectClient';
 import type {
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
   CanvasLayer,
   CanvasTool,
   CanvasViewport,
@@ -33,7 +34,6 @@ import type {
   UploadTarget,
 } from './ImageCanvasEditorTypes';
 import { ImageCanvasGenerationComposerView } from './ImageCanvasGenerationComposerView';
-import { PUBLICATION_MATERIALS_WORKFLOWS } from './ImageCanvasPublicationMaterialsModel';
 import {
   resolveCharacterAnimationPanelStyle,
   resolveCropExpandPanelStyle,
@@ -42,6 +42,7 @@ import {
   resolveIconComposerStyle,
   resolveQuickEditPanelStyle,
 } from './ImageCanvasOverlayModel';
+import { PUBLICATION_MATERIALS_WORKFLOWS } from './ImageCanvasPublicationMaterialsModel';
 import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
 
 type CanvasGenerationDialogUpdater = (
@@ -85,8 +86,11 @@ type ImageCanvasGenerationSurfaceOptions = {
   ) => GenerateDialogState['placeholder'];
   appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
   selectSingleLayer: (layerId: string | null) => void;
-  fitLayers: (targetLayers?: CanvasLayer[]) => void;
-  captureCanvasHistory: () => void;
+  fitLayers: (
+    targetLayers?: CanvasLayer[],
+    options?: { captureHistory?: boolean },
+  ) => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
   setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
   setMetadataLayer: Dispatch<SetStateAction<CanvasLayer | null>>;
@@ -98,7 +102,10 @@ type ImageCanvasGenerationSurfaceOptions = {
   currentUserId?: string | null;
   assetFolderId?: string | null;
   upsertGeneratedAsset?: (asset: EditorAssetSnapshot) => void;
-  applyProjectSnapshot?: (project: EditorProjectSnapshot) => void;
+  applyProjectSnapshot?: (
+    project: EditorProjectSnapshot,
+    action?: CanvasHistoryAction,
+  ) => void;
   onWalletBalanceMayHaveChanged?: () => void;
 };
 
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
index 860ad19ac..26ce4d472 100644
--- a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
@@ -461,6 +461,23 @@ function GenerationWorkflowHarness({
       >
         写入普通图来源生成器
       </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.openCanvasGenerationDialog({
+            mode: 'quick-edit',
+            prompt: '去除背景',
+            status: 'generating',
+            composerOpen: false,
+            sourceLayerId: 'layer-source',
+            imageModel: 'gpt-image-2',
+            aspectRatio: '1:1',
+            imageSize: '1K',
+          })
+        }
+      >
+        写入派生快速编辑生成器
+      </button>
       <button
         type="button"
         onClick={() => workflow.openQuickEditPanel(layers[0]!)}
@@ -518,6 +535,11 @@ function GenerationWorkflowHarness({
       >
         拆分图集
       </button>
+      <output aria-label="拆图状态">
+        {workflow.splittingIconSpritesheetLayerIds.has(layers[0]!.id)
+          ? '拆图中'
+          : '空闲'}
+      </output>
       <button
         type="button"
         onClick={() =>
@@ -528,6 +550,12 @@ function GenerationWorkflowHarness({
       >
         打开角色动画
       </button>
+      <button
+        type="button"
+        onClick={() => workflow.openCharacterAnimationPanel(layers[0]!)}
+      >
+        对当前图层生成动作
+      </button>
       <button
         type="button"
         onClick={() =>
@@ -1161,6 +1189,25 @@ describe('useImageCanvasGenerationWorkflow', () => {
     );
   });
 
+  it('ignores a derived quick edit dialog when restoring the source generator', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '写入普通图来源生成器' }),
+    );
+    fireEvent.click(
+      screen.getByRole('button', { name: '写入派生快速编辑生成器' }),
+    );
+    fireEvent.click(screen.getByRole('button', { name: '打开图片改造' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:idle:open:-:placeholder',
+    );
+    expect(screen.getByTestId('dialog-image-options').textContent).toBe(
+      'generate:gpt-image-2:2:3:2K',
+    );
+  });
+
   it('submits audio remodel with restored sound parameters and appends the new audio layer', async () => {
     generateEditorSoundEffectMock.mockResolvedValueOnce({
       audioSrc: 'data:audio/mpeg;base64,generated',
@@ -1864,25 +1911,85 @@ describe('useImageCanvasGenerationWorkflow', () => {
         },
       });
     });
-    expect(applyProjectSnapshot).toHaveBeenCalledWith(project);
+    expect(applyProjectSnapshot).toHaveBeenCalledWith(project, {
+      type: 'split-atlas',
+      count: 1,
+    });
     expect(screen.getByTestId('sidebar').textContent).toBe('layers');
   });
 
-  it('resolves private character image before removing background', async () => {
+  it('exposes a splitting state while the manual atlas request is pending', async () => {
+    let resolveSplit:
+      | ((value: { iconImageSrcs: never[]; project: unknown }) => void)
+      | undefined;
+    splitEditorIconSpritesheetMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveSplit = resolve;
+        }),
+    );
+    render(
+      <GenerationWorkflowHarness
+        projectId="project-1"
+        applyProjectSnapshot={vi.fn()}
+        initialLayers={[
+          createLayer({
+            assetKind: 'icon-spritesheet',
+            originalWidth: 1024,
+            originalHeight: 1024,
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '拆分图集' }));
+    fireEvent.click(screen.getByRole('button', { name: '拆分图集' }));
+
+    expect(screen.getByRole('status', { name: '拆图状态' }).textContent).toBe(
+      '拆图中',
+    );
+    expect(splitEditorIconSpritesheetMock).toHaveBeenCalledTimes(1);
+
+    resolveSplit?.({
+      iconImageSrcs: [],
+      project: {
+        projectId: 'project-1',
+        title: '未命名画布',
+        canvas: {
+          canvasId: 'project-1:canvas:default',
+          projectId: 'project-1',
+          title: '默认画布',
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          updatedAt: '2026-07-18T00:00:00.000Z',
+        },
+        viewport: { x: 0, y: 0, scale: 1 },
+        layers: [],
+        resources: [],
+        updatedAt: '2026-07-18T00:00:00.000Z',
+      },
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('status', { name: '拆图状态' }).textContent,
+      ).toBe('空闲');
+    });
+  });
+
+  it('queues background removal for private character images', async () => {
     resolveEditorImageReferenceDataUrlMock.mockResolvedValueOnce(
       'data:image/png;base64,resolved-character',
     );
     removeImageBackgroundMock.mockResolvedValueOnce({
-      imageSrc:
-        '/generated-character-drafts/editor/background-removal/result.png',
-      objectKey:
-        'generated-character-drafts/editor/background-removal/result.png',
-      assetObjectId: 'asset-object-background-removal',
-      width: 512,
-      height: 768,
-      taskId: 'background-removal-task',
-      elapsedMs: 1234,
-      provider: 'BiRefNet',
+      queueState: {
+        operationId: 'background-removal-task',
+        status: 'completed',
+        phaseLabel: '已完成',
+        phaseDetail: '已完成',
+        progress: 100,
+        updatedAtMicros: 1,
+      },
     });
     render(
       <GenerationWorkflowHarness
@@ -1912,19 +2019,20 @@ describe('useImageCanvasGenerationWorkflow', () => {
         sourceResourceId: 'resource-source',
       });
     });
+    await waitFor(() => {
+      expect(screen.getByTestId('task-refresh-key').textContent).toBe('1');
+    });
     expect(screen.getByTestId('layers').textContent).toContain(
-      'layer-source:源图:resource-source:character:/generated-character-drafts/editor/background-removal/result.png:background-removal-task',
+      '/api/assets/read-url?objectKey=generated-character-drafts/editor/private.png',
+    );
+    expect(screen.getByTestId('layers').textContent).not.toContain(
+      'background-removal-task',
     );
-    expect(screen.getByTestId('task-refresh-key').textContent).toBe('0');
   });
 
   it('opens a generating canvas placeholder when removing background in a project', async () => {
-    let resolveBackgroundRemoval: ((value: unknown) => void) | null = null;
     removeImageBackgroundMock.mockImplementationOnce(
-      () =>
-        new Promise((resolve) => {
-          resolveBackgroundRemoval = resolve;
-        }),
+      () => new Promise(() => {}),
     );
 
     render(
@@ -1960,139 +2068,9 @@ describe('useImageCanvasGenerationWorkflow', () => {
       }),
     );
     expect(resolveEditorImageReferenceDataUrlMock).not.toHaveBeenCalled();
-    await act(async () => {
-      resolveBackgroundRemoval?.({
-        imageSrc:
-          '/generated-character-drafts/editor/background-removal/project-result.png',
-        objectKey:
-          'generated-character-drafts/editor/background-removal/project-result.png',
-        assetObjectId: 'asset-object-background-removal',
-        width: 512,
-        height: 768,
-        taskId: 'background-removal-project-task',
-        elapsedMs: 1234,
-        provider: 'BiRefNet',
-        project: null,
-      });
-    });
-    expect(screen.getByTestId('layers').textContent).not.toContain(
-      'project-result.png',
-    );
-    expect(screen.getByTestId('layers').textContent).not.toContain(
-      'background-removal-project-task',
-    );
     expect(screen.getByTestId('task-refresh-key').textContent).toBe('0');
   });
 
-  it('preserves a just-created crop layer when applying a background removal project snapshot', async () => {
-    const applyProjectSnapshot = vi.fn();
-    let resolveBackgroundRemoval: ((value: unknown) => void) | null = null;
-    removeImageBackgroundMock.mockImplementationOnce(
-      () =>
-        new Promise((resolve) => {
-          resolveBackgroundRemoval = resolve;
-        }),
-    );
-    render(
-      <GenerationWorkflowHarness
-        projectId="project-1"
-        applyProjectSnapshot={applyProjectSnapshot}
-        initialLayers={[
-          createLayer({
-            id: 'layer-crop-expand-1',
-            resourceId: 'resource-crop-expand',
-            title: '源图 裁扩',
-            src: '/generated-character-drafts/editor/crop-expand/project-1/result.png',
-            objectKey:
-              'generated-character-drafts/editor/crop-expand/project-1/result.png',
-            assetObjectId: 'asset-object-crop-expand',
-            sourceType: 'generated',
-            sourceResourceId: 'resource-source',
-          }),
-        ]}
-      />,
-    );
-
-    fireEvent.click(screen.getByRole('button', { name: '去除背景' }));
-
-    await waitFor(() => expect(removeImageBackgroundMock).toHaveBeenCalled());
-    await act(async () => {
-      resolveBackgroundRemoval?.({
-        imageSrc:
-          '/generated-character-drafts/editor/background-removal/project-result.png',
-        objectKey:
-          'generated-character-drafts/editor/background-removal/project-result.png',
-        assetObjectId: 'asset-object-background-removal',
-        width: 512,
-        height: 768,
-        taskId: 'background-removal-project-task',
-        elapsedMs: 1234,
-        provider: 'BiRefNet',
-        project: {
-          projectId: 'project-1',
-          title: '队列项目',
-          viewport: { x: 0, y: 0, scale: 1 },
-          layers: [
-            {
-              layerId: 'layer-background-removal-result',
-              resourceId: 'resource-background-removal',
-              title: '源图 裁扩 去背景',
-              x: 480,
-              y: 140,
-              width: 512,
-              height: 768,
-              originalWidth: 512,
-              originalHeight: 768,
-              zIndex: 9,
-              sourceType: 'generated',
-            },
-          ],
-          resources: [
-            {
-              resourceId: 'resource-background-removal',
-              projectId: 'project-1',
-              imageSrc:
-                '/generated-character-drafts/editor/background-removal/project-result.png',
-              objectKey:
-                'generated-character-drafts/editor/background-removal/project-result.png',
-              assetObjectId: 'asset-object-background-removal',
-              width: 512,
-              height: 768,
-              sourceType: 'generated',
-              sourceResourceId: 'resource-crop-expand',
-            },
-          ],
-          updatedAt: '2026-06-23T08:00:01.000Z',
-        },
-      });
-    });
-
-    const appliedProject = applyProjectSnapshot.mock.calls[0]?.[0];
-    expect(appliedProject?.layers).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          layerId: 'layer-crop-expand-1',
-          resourceId: 'resource-crop-expand',
-          title: '源图 裁扩',
-        }),
-        expect.objectContaining({
-          layerId: 'layer-background-removal-result',
-          resourceId: 'resource-background-removal',
-        }),
-      ]),
-    );
-    expect(appliedProject?.resources).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          resourceId: 'resource-crop-expand',
-          objectKey:
-            'generated-character-drafts/editor/crop-expand/project-1/result.png',
-          assetObjectId: 'asset-object-crop-expand',
-        }),
-      ]),
-    );
-  });
-
   it('opens UI design extraction as a mark selection state before submitting', () => {
     render(<GenerationWorkflowHarness />);
 
@@ -2151,6 +2129,92 @@ describe('useImageCanvasGenerationWorkflow', () => {
     expect(screen.getByTestId('image-context').textContent).toBe('-');
   });
 
+  it('reopens the character generator when remodeling after opening character animation', () => {
+    render(
+      <GenerationWorkflowHarness
+        initialLayers={[
+          createLayer({
+            assetKind: 'character',
+            sourceType: 'generated',
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '对当前图层生成动作' }),
+    );
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character-animation:idle:open:-:placeholder',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图片改造' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character:idle:open:-:placeholder',
+    );
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-1:character-animation:closed|generation-dialog-2:character:open',
+    );
+  });
+
+  it('reopens character animation remodeling from an action result layer', () => {
+    render(
+      <GenerationWorkflowHarness
+        initialLayers={[
+          createLayer({
+            id: 'layer-action',
+            resourceId: 'resource-action',
+            title: '角色动作',
+            mediaType: 'image-sequence',
+            assetKind: 'character-animation',
+            sourceType: 'generated',
+            sourceResourceId: 'resource-character',
+          }),
+          createLayer({
+            id: 'layer-character',
+            resourceId: 'resource-character',
+            title: '角色形象',
+            assetKind: 'character',
+            sourceType: 'generated',
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图片改造' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character-animation:idle:open:-:placeholder',
+    );
+    expect(screen.getByTestId('character-animation').textContent).toBe(
+      'layer-character:idle',
+    );
+  });
+
+  it('warns when an action result has lost its source character layer', () => {
+    render(
+      <GenerationWorkflowHarness
+        initialLayers={[
+          createLayer({
+            title: '角色动作',
+            mediaType: 'image-sequence',
+            assetKind: 'character-animation',
+            sourceType: 'generated',
+            sourceResourceId: 'missing-character-resource',
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图片改造' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+    expect(screen.getByTestId('reference-pick-warning').textContent).toBe(
+      '未找到角色动作关联的原角色图层，无法改造。',
+    );
+  });
+
   it('keeps character animation asset names synchronized with the dialog', () => {
     render(<GenerationWorkflowHarness />);
 
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
index d95ee9052..1e4a630f1 100644
--- a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
@@ -14,15 +14,16 @@ import { resolveEditorImageReferenceDataUrl } from '../../services/image-editor/
 import { uploadEditorMediaAssetFile } from '../../services/image-editor/editorMediaAssetUploadClient';
 import {
   createEditorProjectResource,
-  splitEditorIconSpritesheet,
   type EditorAssetSnapshot,
   type EditorProjectLayerSnapshot,
   type EditorProjectResourceSnapshot,
   type EditorProjectSnapshot,
+  splitEditorIconSpritesheet,
 } from '../../services/image-editor/editorProjectClient';
 import { resizeCropExpandFrame } from './ImageCanvasCropExpandModel';
 import type {
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
   CanvasLayer,
   CanvasTool,
   CanvasViewport,
@@ -242,10 +243,59 @@ function findSourceGenerationDialog(
     .find(
       (dialog) =>
         dialog.generatedLayerId === sourceLayer.id ||
-        (!dialog.generatedLayerId && dialog.sourceLayerId === sourceLayer.id),
+        // sourceLayerId 也用于派生生成器的输入关系，类型不匹配时不能当作图层来源。
+        (!dialog.generatedLayerId &&
+          dialog.sourceLayerId === sourceLayer.id &&
+          isGenerationDialogModeCompatibleWithSourceLayer(
+            dialog.mode,
+            sourceLayer,
+          )),
     );
 }
 
+function isGenerationDialogModeCompatibleWithSourceLayer(
+  mode: CanvasGenerationDialogState['mode'],
+  sourceLayer: CanvasLayer,
+) {
+  if (mode === 'quick-edit') {
+    return false;
+  }
+  if (sourceLayer.assetKind === 'character') {
+    return mode === 'character';
+  }
+  if (sourceLayer.assetKind === 'character-animation') {
+    return mode === 'character-animation';
+  }
+  if (sourceLayer.assetKind === 'ui-design') {
+    return mode === 'ui-design';
+  }
+  if (sourceLayer.assetKind === 'publication-material') {
+    return mode === 'publication';
+  }
+  if (
+    sourceLayer.assetKind === 'icon' ||
+    sourceLayer.assetKind === 'icon-spritesheet'
+  ) {
+    return mode === 'icon';
+  }
+  if (
+    sourceLayer.assetKind === 'spec' ||
+    sourceLayer.assetKind === 'icon-spec'
+  ) {
+    return mode === 'spec';
+  }
+  if (sourceLayer.assetKind === 'video') {
+    return mode === 'video';
+  }
+  if (sourceLayer.assetKind === 'sound-effect') {
+    return mode === 'audio-sound-effect';
+  }
+  if (sourceLayer.assetKind === 'background-music') {
+    return mode === 'audio-background-music';
+  }
+  return true;
+}
+
 function findSourceAnimationLayer(
   layers: CanvasLayer[],
   sourceLayer: CanvasLayer,
@@ -561,8 +611,11 @@ type GenerationWorkflowOptions = {
   ) => GenerateDialogState['placeholder'];
   appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
   selectSingleLayer: (layerId: string | null) => void;
-  fitLayers: (targetLayers?: CanvasLayer[]) => void;
-  captureCanvasHistory: () => void;
+  fitLayers: (
+    targetLayers?: CanvasLayer[],
+    options?: { captureHistory?: boolean },
+  ) => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
   setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
   setMetadataLayer: Dispatch<SetStateAction<CanvasLayer | null>>;
@@ -573,7 +626,10 @@ type GenerationWorkflowOptions = {
   currentUserId?: string | null;
   assetFolderId?: string | null;
   upsertGeneratedAsset?: (asset: EditorAssetSnapshot) => void;
-  applyProjectSnapshot?: (project: EditorProjectSnapshot) => void;
+  applyProjectSnapshot?: (
+    project: EditorProjectSnapshot,
+    action?: CanvasHistoryAction,
+  ) => void;
   onWalletBalanceMayHaveChanged?: () => void;
 };
 
@@ -616,8 +672,13 @@ export function useImageCanvasGenerationWorkflow({
     setIsTaskSidebarOpen(true);
     setTaskListRefreshKey((key) => key + 1);
   }, []);
+  const refreshTaskList = useCallback(() => {
+    setTaskListRefreshKey((key) => key + 1);
+  }, []);
   const previousTaskCountRef = useRef(canvasGenerationDialogs.length);
   const splittingIconSpritesheetLayerIdsRef = useRef(new Set<string>());
+  const [splittingIconSpritesheetLayerIds, setSplittingIconSpritesheetLayerIds] =
+    useState<Set<string>>(() => new Set());
   const [isSpecMenuOpen, setIsSpecMenuOpen] = useState(false);
   const [isGenerationReferenceMenuOpen, setIsGenerationReferenceMenuOpen] =
     useState(false);
@@ -800,12 +861,7 @@ export function useImageCanvasGenerationWorkflow({
         ? currentOptions
         : nextOptions,
     );
-  }, [
-    generateDialog?.aspectRatio,
-    generateDialog?.imageModel,
-    generateDialog?.imageSize,
-    generateDialog?.mode,
-  ]);
+  }, [generateDialog]);
 
   const quickEditSourceLayer = quickEditPanel
     ? (layers.find((layer) => layer.id === quickEditPanel.sourceLayerId) ??
@@ -820,11 +876,12 @@ export function useImageCanvasGenerationWorkflow({
         (layer) => layer.id === uiAssetExtractionState.sourceLayerId,
       ) ?? null)
     : null;
-  const quickEditSelectionSourceLayer = quickEditSelectionState
-    ? (layers.find(
-        (layer) => layer.id === quickEditSelectionState.sourceLayerId,
-      ) ?? null)
-    : null;
+  const quickEditSelectionSourceLayer =
+    quickEditPanel?.status !== 'generating' && quickEditSelectionState
+      ? (layers.find(
+          (layer) => layer.id === quickEditSelectionState.sourceLayerId,
+        ) ?? null)
+      : null;
   const characterAnimationSourceLayer = effectiveCharacterAnimationPanel
     ? (layers.find(
         (layer) => layer.id === effectiveCharacterAnimationPanel.sourceLayerId,
@@ -1181,7 +1238,7 @@ export function useImageCanvasGenerationWorkflow({
         return;
       }
       const updatedLayer = updater(sourceLayer);
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'replace-image', count: 1 });
       setLayers((currentLayers) =>
         currentLayers.map((layer) =>
           layer.id === sourceLayerId ? updatedLayer : layer,
@@ -1192,7 +1249,7 @@ export function useImageCanvasGenerationWorkflow({
       }
       selectSingleLayer(sourceLayerId);
       if (options.fit !== false) {
-        fitLayers([updatedLayer]);
+        fitLayers([updatedLayer], { captureHistory: false });
       }
     },
     [
@@ -1237,19 +1294,24 @@ export function useImageCanvasGenerationWorkflow({
       }
       if (
         sourceLayer.mediaType === undefined ||
-        sourceLayer.mediaType === 'image'
+        sourceLayer.mediaType === 'image' ||
+        sourceLayer.assetKind === 'character-animation'
       ) {
         const sourceDialog = findSourceGenerationDialog(
           canvasGenerationDialogs,
           sourceLayer,
         );
+        const sourceAnimationLayer = findSourceAnimationLayer(
+          layers,
+          sourceLayer,
+        );
         const sameSourceDraft = createSameSourceGenerationDialogDraft({
           sourceLayer,
           canvasSize,
           viewport,
           sourceDialog,
           mode: 'redraw',
-          sourceAnimationLayer: findSourceAnimationLayer(layers, sourceLayer),
+          sourceAnimationLayer,
         });
         if (sameSourceDraft) {
           openPlacedCanvasGenerationDialog(sameSourceDraft);
@@ -1258,6 +1320,10 @@ export function useImageCanvasGenerationWorkflow({
           setActiveTool(getCanvasToolForGenerationMode(sameSourceDraft.mode));
           return;
         }
+        if (sourceLayer.assetKind === 'character-animation') {
+          setGenerationWarning('未找到角色动作关联的原角色图层，无法改造。');
+          return;
+        }
         const redrawPanel = createRedrawPanelDraft(sourceLayer, {
           imageModel: sourceDialog?.imageModel,
           aspectRatio: sourceDialog?.aspectRatio,
@@ -1524,11 +1590,11 @@ export function useImageCanvasGenerationWorkflow({
         sourceAssetId: null,
         assetKind: cropExpandAssetKind,
       };
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'expand-image', count: 1 });
       appendCanvasLayersWithResources([nextLayer]);
       persistGeneratedAsset?.(nextLayer);
       selectSingleLayer(nextLayer.id);
-      fitLayers([cropExpandSourceLayer, nextLayer]);
+      fitLayers([cropExpandSourceLayer, nextLayer], { captureHistory: false });
       setCropExpandPanel(null);
       setActiveSidebarPanel('layers');
     } catch (error) {
@@ -1613,58 +1679,23 @@ export function useImageCanvasGenerationWorkflow({
               }
             : {}),
         });
-        if (
-          await applyQueuedEditorGenerationProject(
-            result,
-            projectId,
-            applyProjectSnapshot,
-            refreshTaskListForQueuedGeneration,
-            onWalletBalanceMayHaveChanged,
-            setGenerationWarning,
-            backgroundRemovalDialogId,
-            applyBackgroundRemovalProjectSnapshot
-              ? (project) =>
-                  preserveSourceLayerInProjectSnapshot(project, sourceLayer)
-              : undefined,
-          )
-        ) {
-          return;
-        }
-        if (result.project && applyBackgroundRemovalProjectSnapshot) {
-          applyBackgroundRemovalProjectSnapshot(result.project);
-          return;
-        }
-        if (backgroundRemovalPlacement?.placeholder && applyProjectSnapshot) {
-          return;
-        }
-        updateSourceLayer(sourceLayer.id, (layer) => ({
-          ...layer,
-          resourceId: result.resource?.resourceId ?? layer.resourceId,
-          src: result.imageSrc,
-          width: result.width,
-          height: result.height,
-          originalWidth: result.width,
-          originalHeight: result.height,
-          sourceType: result.sourceType ?? 'generated',
-          provider: result.provider ?? 'BiRefNet',
-          taskId: result.taskId ?? null,
-          objectKey: result.resource?.objectKey ?? result.objectKey ?? null,
-          assetObjectId:
-            result.resource?.assetObjectId ?? result.assetObjectId ?? null,
-          sourceResourceId:
-            result.resource?.sourceResourceId ?? sourceLayer.resourceId,
-          sourceAssetId: null,
-          prompt: result.resource?.prompt ?? layer.prompt,
-          actualPrompt: result.resource?.actualPrompt ?? layer.actualPrompt,
-          model: result.resource?.model ?? layer.model,
-          assetKind:
-            (result.resource?.assetKind as CanvasLayer['assetKind']) ??
-            layer.assetKind,
-          generationInputs:
-            result.resource?.generationInputs ?? layer.generationInputs,
-          generatedAssetSnapshot: result.asset ?? layer.generatedAssetSnapshot,
-        }));
-        setActiveSidebarPanel('layers');
+        await applyQueuedEditorGenerationProject(
+          result,
+          projectId,
+          (project) =>
+            applyProjectSnapshot?.(project, {
+              type: 'remove-background',
+              count: 1,
+            }),
+          refreshTaskListForQueuedGeneration,
+          onWalletBalanceMayHaveChanged,
+          setGenerationWarning,
+          backgroundRemovalDialogId,
+          applyBackgroundRemovalProjectSnapshot
+            ? (project) =>
+                preserveSourceLayerInProjectSnapshot(project, sourceLayer)
+            : undefined,
+        );
       } catch (error) {
         if (backgroundRemovalDialogId) {
           updateCanvasGenerationDialogById(
@@ -1689,11 +1720,9 @@ export function useImageCanvasGenerationWorkflow({
       openPlacedCanvasGenerationDialog,
       projectId,
       refreshTaskListForQueuedGeneration,
-      setActiveSidebarPanel,
       setImageContextMenu,
       setMetadataLayer,
       updateCanvasGenerationDialogById,
-      updateSourceLayer,
     ],
   );
 
@@ -1708,6 +1737,11 @@ export function useImageCanvasGenerationWorkflow({
         return;
       }
       splittingIconSpritesheetLayerIdsRef.current.add(sourceLayer.id);
+      setSplittingIconSpritesheetLayerIds((currentLayerIds) => {
+        const nextLayerIds = new Set(currentLayerIds);
+        nextLayerIds.add(sourceLayer.id);
+        return nextLayerIds;
+      });
       closeGenerationTransientState();
       setImageContextMenu(null);
       setMetadataLayer(null);
@@ -1730,7 +1764,10 @@ export function useImageCanvasGenerationWorkflow({
             },
           },
         });
-        applyProjectSnapshot(result.project);
+        applyProjectSnapshot(result.project, {
+          type: 'split-atlas',
+          count: 1,
+        });
         setActiveTool('select');
         setActiveSidebarPanel('layers');
       } catch (error) {
@@ -1741,6 +1778,14 @@ export function useImageCanvasGenerationWorkflow({
         );
       } finally {
         splittingIconSpritesheetLayerIdsRef.current.delete(sourceLayer.id);
+        setSplittingIconSpritesheetLayerIds((currentLayerIds) => {
+          if (!currentLayerIds.has(sourceLayer.id)) {
+            return currentLayerIds;
+          }
+          const nextLayerIds = new Set(currentLayerIds);
+          nextLayerIds.delete(sourceLayer.id);
+          return nextLayerIds;
+        });
       }
     },
     [
@@ -1914,6 +1959,7 @@ export function useImageCanvasGenerationWorkflow({
       hasCanvasGenerationDialogById,
       getGeneratingDialogPlaceholder,
       appendCanvasLayersWithResources,
+      captureCanvasHistory,
       updateSourceLayer,
       selectSingleLayer,
       fitLayers,
@@ -1992,6 +2038,7 @@ export function useImageCanvasGenerationWorkflow({
       setCropExpandPanel,
       setMetadataLayer,
       setQuickEditPanel,
+      setViewport,
     ],
   );
 
@@ -2512,7 +2559,9 @@ export function useImageCanvasGenerationWorkflow({
       startCropExpandFrameResize,
       removeSelectedLayerBackground,
       splitSelectedIconSpritesheet,
+      splittingIconSpritesheetLayerIds,
       taskListRefreshKey,
+      refreshTaskList,
       isTaskSidebarOpen,
       toggleTaskSidebar: () => setIsTaskSidebarOpen((open) => !open),
       extractUiDesignAssets,
@@ -2580,6 +2629,7 @@ export function useImageCanvasGenerationWorkflow({
       isMusicMenuOpen,
       isTaskSidebarOpen,
       taskListRefreshKey,
+      refreshTaskList,
       isPublicationMenuOpen,
       isPublicationReferenceMenuOpen,
       isSpecMenuOpen,
@@ -2612,6 +2662,7 @@ export function useImageCanvasGenerationWorkflow({
       quickEditSourceLayer,
       removeSelectedLayerBackground,
       splitSelectedIconSpritesheet,
+      splittingIconSpritesheetLayerIds,
       submitCharacterAnimation,
       submitCropExpand,
       submitIconSpritesheetGeneration,
@@ -2621,7 +2672,6 @@ export function useImageCanvasGenerationWorkflow({
       updateIconDescriptionsText,
       updateSpecFormValue,
       rememberImageModel,
-      refreshTaskListForQueuedGeneration,
     ],
   );
 }
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
index 5b7216ed1..8d14c05b6 100644
--- a/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
@@ -166,8 +166,8 @@ function KeyboardShortcutsHarness({
     generateDialogRef,
     selectedLayerIdRef,
     selectedLayerIdsRef,
-    redoCanvasChange,
     undoCanvasChange,
+    redoCanvasChange,
     deleteLayerById,
     deleteSelectedCanvasObjects,
     selectAllCanvasObjects,
@@ -262,7 +262,7 @@ function KeyboardShortcutsHarness({
 }
 
 describe('useImageCanvasKeyboardShortcuts', () => {
-  it('routes undo and redo shortcuts while ignoring editable inputs', () => {
+  it('routes undo and redo while ignoring editable inputs', () => {
     const undoCanvasChange = vi.fn();
     const redoCanvasChange = vi.fn();
     render(
@@ -276,6 +276,7 @@ describe('useImageCanvasKeyboardShortcuts', () => {
       fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
     });
     expect(undoCanvasChange).toHaveBeenCalledTimes(1);
+    expect(redoCanvasChange).toHaveBeenCalledTimes(0);
 
     act(() => {
       fireEvent.keyDown(window, {
@@ -285,6 +286,7 @@ describe('useImageCanvasKeyboardShortcuts', () => {
         shiftKey: true,
       });
     });
+    expect(undoCanvasChange).toHaveBeenCalledTimes(1);
     expect(redoCanvasChange).toHaveBeenCalledTimes(1);
 
     act(() => {
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
index 390a6ab2b..2cc6b1305 100644
--- a/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
@@ -13,8 +13,8 @@ type UseImageCanvasKeyboardShortcutsOptions = {
   generateDialogRef: RefObject<GenerateDialogState | null>;
   selectedLayerIdRef: RefObject<string | null>;
   selectedLayerIdsRef?: RefObject<string[]>;
-  redoCanvasChange: () => void;
   undoCanvasChange: () => void;
+  redoCanvasChange: () => void;
   deleteLayerById: (layerId: string | null) => void;
   deleteSelectedCanvasObjects?: () => void;
   selectAllCanvasObjects?: () => void;
@@ -161,8 +161,8 @@ export function useImageCanvasKeyboardShortcuts({
   generateDialogRef,
   selectedLayerIdRef,
   selectedLayerIdsRef,
-  redoCanvasChange,
   undoCanvasChange,
+  redoCanvasChange,
   deleteLayerById,
   deleteSelectedCanvasObjects,
   selectAllCanvasObjects,
diff --git a/src/components/image-editor/useImageCanvasLayerCommands.test.tsx b/src/components/image-editor/useImageCanvasLayerCommands.test.tsx
index 8c3ee2d97..3f063c6aa 100644
--- a/src/components/image-editor/useImageCanvasLayerCommands.test.tsx
+++ b/src/components/image-editor/useImageCanvasLayerCommands.test.tsx
@@ -427,7 +427,12 @@ describe('useImageCanvasLayerCommands', () => {
 
   it('copies, cuts, and pastes context layers with history and selection updates', async () => {
     const write = installImageClipboardMock();
-    render(<LayerCommandsHarness />);
+    const onDeleteLayerSideEffects = vi.fn();
+    render(
+      <LayerCommandsHarness
+        onDeleteLayerSideEffects={onDeleteLayerSideEffects}
+      />,
+    );
 
     fireEvent.click(screen.getByRole('button', { name: '复制' }));
     await waitFor(() => expect(write).toHaveBeenCalledTimes(1));
@@ -459,6 +464,7 @@ describe('useImageCanvasLayerCommands', () => {
     expect(screen.getByTestId('layers').textContent).not.toContain('third');
     expect(screen.getByTestId('selection').textContent).toBe('-:');
     expect(screen.getByTestId('image-context-closed').textContent).toBe('3');
+    expect(onDeleteLayerSideEffects).toHaveBeenCalledWith('third');
     expect(Number(screen.getByTestId('history').textContent)).toBeGreaterThan(
       1,
     );
diff --git a/src/components/image-editor/useImageCanvasLayerCommands.ts b/src/components/image-editor/useImageCanvasLayerCommands.ts
index f19c552eb..720f0f78f 100644
--- a/src/components/image-editor/useImageCanvasLayerCommands.ts
+++ b/src/components/image-editor/useImageCanvasLayerCommands.ts
@@ -10,8 +10,10 @@ import type {
   CanvasClipboard,
   CanvasContextMenuState,
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
   CanvasLayer,
 } from './ImageCanvasEditorTypes';
+import { readLayerImageBlob } from './ImageCanvasExportModel';
 import {
   type CanvasLayerFlipAxis,
   type CanvasLayerMoveMode,
@@ -28,7 +30,6 @@ import {
   ungroupCanvasLayers,
   updateCanvasLayersByIds,
 } from './ImageCanvasLayerCommandModel';
-import { readLayerImageBlob } from './ImageCanvasExportModel';
 import {
   getCanvasGenerationDialogIdFromSelectionId,
   getSelectedLayerIds,
@@ -49,7 +50,7 @@ type LayerCommandsOptions = {
   setContextMenu: Dispatch<SetStateAction<CanvasContextMenuState | null>>;
   setImageContextMenu: (menu: null) => void;
   setActiveTool: (tool: 'select') => void;
-  captureCanvasHistory: () => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   selectSingleLayer: (layerId: string | null) => void;
   onDeleteLayerSideEffects: (targetLayerId: string) => void;
   onDeleteGenerationDialogSideEffects?: (targetDialogId: string) => void;
@@ -193,7 +194,7 @@ export function useImageCanvasLayerCommands({
       if (!nextLayers.length) {
         return false;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'paste-image', count: nextLayers.length });
       setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
       setSelectedLayerIds(nextLayers.map((layer) => layer.id));
       setSelectedLayerId(nextLayers[0]?.id ?? null);
@@ -229,7 +230,7 @@ export function useImageCanvasLayerCommands({
         copyLayerImageToSystemClipboard(clipboard.layers);
       }
       if (options.cut) {
-        captureCanvasHistory();
+        captureCanvasHistory({ type: 'cut-image', count: targetIds.length });
         setLayers((currentLayers) =>
           removeCanvasLayers(currentLayers, targetIds),
         );
@@ -239,6 +240,7 @@ export function useImageCanvasLayerCommands({
             ? null
             : currentLayer,
         );
+        targetIds.forEach((targetId) => onDeleteLayerSideEffects(targetId));
       }
       closeContextMenus();
     },
@@ -247,6 +249,7 @@ export function useImageCanvasLayerCommands({
       closeContextMenus,
       getContextTargetLayerIds,
       layers,
+      onDeleteLayerSideEffects,
       selectSingleLayer,
       setLayers,
       setMetadataLayer,
@@ -270,7 +273,7 @@ export function useImageCanvasLayerCommands({
         copyLayerImageToSystemClipboard(clipboard.layers);
       }
       if (options.cut) {
-        captureCanvasHistory();
+        captureCanvasHistory({ type: 'cut-image', count: targetIds.length });
         setLayers((currentLayers) =>
           removeCanvasLayers(currentLayers, targetIds),
         );
@@ -305,7 +308,7 @@ export function useImageCanvasLayerCommands({
     if (!nextLayers.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({ type: 'duplicate-image', count: nextLayers.length });
     setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
     setSelectedLayerIds(nextLayers.map((layer) => layer.id));
     setSelectedLayerId(nextLayers[0]?.id ?? null);
@@ -328,7 +331,7 @@ export function useImageCanvasLayerCommands({
     if (!nextLayers.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({ type: 'duplicate-image', count: nextLayers.length });
     setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
     setSelectedLayerIds(nextLayers.map((layer) => layer.id));
     setSelectedLayerId(nextLayers[0]?.id ?? null);
@@ -352,7 +355,7 @@ export function useImageCanvasLayerCommands({
       if (!targetIds.length) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'change-asset-kind', count: targetIds.length });
       setLayers((currentLayers) =>
         updateCanvasLayersByIds(currentLayers, targetIds, updater),
       );
@@ -372,7 +375,10 @@ export function useImageCanvasLayerCommands({
       if (!targetIds.length) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({
+        type: 'change-layer-order',
+        count: targetIds.length,
+      });
       setLayers((currentLayers) =>
         moveCanvasLayers(currentLayers, targetIds, mode),
       );
@@ -392,7 +398,10 @@ export function useImageCanvasLayerCommands({
       if (!targetIds.length) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({
+        type: 'change-layer-order',
+        count: targetIds.length,
+      });
       setLayers((currentLayers) =>
         moveCanvasLayers(currentLayers, targetIds, mode),
       );
@@ -413,7 +422,7 @@ export function useImageCanvasLayerCommands({
     if (!targetIds.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({ type: 'group-images', count: targetIds.length });
     setLayers((currentLayers) =>
       groupCanvasLayers(currentLayers, targetIds, createGroupId()),
     );
@@ -430,7 +439,7 @@ export function useImageCanvasLayerCommands({
     if (!targetIds.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({ type: 'ungroup-images', count: targetIds.length });
     setLayers((currentLayers) => ungroupCanvasLayers(currentLayers, targetIds));
     closeContextMenus();
   }, [
@@ -445,7 +454,13 @@ export function useImageCanvasLayerCommands({
     if (!targetIds.length) {
       return;
     }
-    captureCanvasHistory();
+    const shouldHide = getCanvasLayersByIds(layers, targetIds).some(
+      (layer) => !layer.hidden,
+    );
+    captureCanvasHistory({
+      type: shouldHide ? 'hide-image' : 'show-image',
+      count: targetIds.length,
+    });
     setLayers((currentLayers) =>
       toggleCanvasLayersVisibility(currentLayers, targetIds),
     );
@@ -454,6 +469,7 @@ export function useImageCanvasLayerCommands({
     captureCanvasHistory,
     closeContextMenus,
     getContextTargetLayerIds,
+    layers,
     setLayers,
   ]);
 
@@ -462,7 +478,13 @@ export function useImageCanvasLayerCommands({
     if (!targetIds.length) {
       return;
     }
-    captureCanvasHistory();
+    const shouldLock = getCanvasLayersByIds(layers, targetIds).some(
+      (layer) => !layer.locked,
+    );
+    captureCanvasHistory({
+      type: shouldLock ? 'lock-image' : 'unlock-image',
+      count: targetIds.length,
+    });
     setLayers((currentLayers) =>
       toggleCanvasLayersLock(currentLayers, targetIds),
     );
@@ -471,6 +493,7 @@ export function useImageCanvasLayerCommands({
     captureCanvasHistory,
     closeContextMenus,
     getContextTargetLayerIds,
+    layers,
     setLayers,
   ]);
 
@@ -480,7 +503,7 @@ export function useImageCanvasLayerCommands({
       if (!targetIds.length) {
         return;
       }
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'flip-image', count: targetIds.length });
       setLayers((currentLayers) =>
         flipCanvasLayers(currentLayers, targetIds, axis),
       );
@@ -506,7 +529,12 @@ export function useImageCanvasLayerCommands({
     if (!targetLayerIds.length && !targetDialogIds.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({
+      type: targetLayerIds.length
+        ? 'delete-image'
+        : 'delete-generation-result',
+      count: targetLayerIds.length || targetDialogIds.length,
+    });
     if (targetLayerIds.length) {
       setLayers((currentLayers) =>
         removeCanvasLayers(currentLayers, targetLayerIds),
@@ -561,7 +589,7 @@ export function useImageCanvasLayerCommands({
       }
       setImageContextMenu(null);
       setContextMenu(null);
-      captureCanvasHistory();
+      captureCanvasHistory({ type: 'delete-image', count: 1 });
       setLayers((currentLayers) => {
         const nextLayers = currentLayers.filter(
           (layer) => layer.id !== targetLayerId,
@@ -610,7 +638,12 @@ export function useImageCanvasLayerCommands({
       deleteLayerById(targetLayerIds[0] ?? null);
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({
+      type: targetLayerIds.length
+        ? 'delete-image'
+        : 'delete-generation-result',
+      count: targetLayerIds.length || targetDialogIds.length,
+    });
     setImageContextMenu(null);
     setContextMenu(null);
     if (targetLayerIds.length) {
@@ -666,7 +699,10 @@ export function useImageCanvasLayerCommands({
     if (!targetLayerIds.length) {
       return;
     }
-    captureCanvasHistory();
+    captureCanvasHistory({
+      type: 'group-images',
+      count: targetLayerIds.length,
+    });
     setLayers((currentLayers) =>
       groupCanvasLayers(currentLayers, targetLayerIds, createGroupId()),
     );
diff --git a/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx b/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx
index 6ad31b075..5ea1a2fa9 100644
--- a/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx
+++ b/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx
@@ -6,15 +6,15 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { ApiClientError } from '../../services/apiClient';
 import type { EditorProjectSnapshot } from '../../services/image-editor/editorProjectClient';
+import {
+  DEFAULT_CANVAS_BACKGROUND_COLOR,
+  normalizeCanvasBackgroundHex,
+} from './ImageCanvasEditorModel';
 import type {
   CanvasGenerationDialogState,
   CanvasLayer,
   CanvasViewport,
 } from './ImageCanvasEditorTypes';
-import {
-  DEFAULT_CANVAS_BACKGROUND_COLOR,
-  normalizeCanvasBackgroundHex,
-} from './ImageCanvasEditorModel';
 import { useImageCanvasProjectPersistence } from './useImageCanvasProjectPersistence';
 
 const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
diff --git a/src/components/image-editor/useImageCanvasProjectPersistence.ts b/src/components/image-editor/useImageCanvasProjectPersistence.ts
index dd2ad92de..f956d5e6c 100644
--- a/src/components/image-editor/useImageCanvasProjectPersistence.ts
+++ b/src/components/image-editor/useImageCanvasProjectPersistence.ts
@@ -6,10 +6,9 @@ import {
   useState,
 } from 'react';
 
-import { ApiClientError } from '../../services/apiClient';
 import { replaceAppHistoryPath } from '../../routing/appPageRoutes';
+import { ApiClientError } from '../../services/apiClient';
 import { uploadEditorMediaAssetFile } from '../../services/image-editor/editorMediaAssetUploadClient';
-import { putEditorProjectCoverCache } from '../../services/image-editor/editorProjectCoverCache';
 import {
   createEditorProjectResource,
   type EditorProjectResourceSnapshot,
@@ -18,6 +17,7 @@ import {
   loadOrCreateRecentEditorProject,
   saveEditorProjectLayout,
 } from '../../services/image-editor/editorProjectClient';
+import { putEditorProjectCoverCache } from '../../services/image-editor/editorProjectCoverCache';
 import {
   canvasDisplayViewportToViewport,
   type CanvasLayerResourceMetadata,
diff --git a/src/components/image-editor/useImageCanvasStageController.ts b/src/components/image-editor/useImageCanvasStageController.ts
index 64ff9c46e..acee21d3e 100644
--- a/src/components/image-editor/useImageCanvasStageController.ts
+++ b/src/components/image-editor/useImageCanvasStageController.ts
@@ -13,13 +13,13 @@ import type {
   CanvasViewport,
   ImageContextMenuState,
 } from './ImageCanvasEditorTypes';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 import {
   createBlankCanvasContextMenu,
   createGenerationDialogCanvasContextMenu,
   createLayerCanvasContextMenus,
   resolveImageCanvasStageControllerModel,
 } from './ImageCanvasStageControllerModel';
-import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
 
 type UseImageCanvasStageControllerOptions = {
   layers: CanvasLayer[];
diff --git a/src/components/image-editor/useImageCanvasStageInteractions.test.tsx b/src/components/image-editor/useImageCanvasStageInteractions.test.tsx
index 33f12ad48..3ec5856a0 100644
--- a/src/components/image-editor/useImageCanvasStageInteractions.test.tsx
+++ b/src/components/image-editor/useImageCanvasStageInteractions.test.tsx
@@ -10,12 +10,14 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type {
   CanvasGenerationDialogState,
+  CanvasHistoryAction,
+  CanvasHistorySnapshot,
   CanvasLayer,
   CanvasViewport,
   GenerateDialogState,
 } from './ImageCanvasEditorTypes';
-import { useImageCanvasStageInteractions } from './useImageCanvasStageInteractions';
 import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+import { useImageCanvasStageInteractions } from './useImageCanvasStageInteractions';
 
 function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
   const id = overrides.id ?? 'layer-a';
@@ -118,6 +120,7 @@ function StageInteractionsHarness({
   flushMinimapViewportDrag = vi.fn(),
   onViewportInteractionStart = vi.fn(),
   onViewportInteractionEnd = vi.fn(),
+  captureCanvasHistory = vi.fn(),
 }: {
   pickCharacterSpecFromLayer?: (layer: CanvasLayer) => void;
   pickGenerationReferenceFromLayer?: (layer: CanvasLayer) => void;
@@ -139,6 +142,10 @@ function StageInteractionsHarness({
   flushMinimapViewportDrag?: () => void;
   onViewportInteractionStart?: () => void;
   onViewportInteractionEnd?: () => void;
+  captureCanvasHistory?: (
+    action: CanvasHistoryAction,
+    options?: { snapshot?: CanvasHistorySnapshot },
+  ) => void;
 }) {
   const canvasViewportRef = useRef<HTMLDivElement | null>(null);
   const worldRef = useRef<HTMLDivElement | null>(null);
@@ -239,6 +246,15 @@ function StageInteractionsHarness({
     onViewportInteractionEnd,
     onCloseImageContextMenu: () =>
       setImageMenuCloseCount((currentCount) => currentCount + 1),
+    getCanvasHistorySnapshot: () => ({
+      layers,
+      viewport,
+      generateDialog,
+      inactiveGenerateDialogs: [],
+      selectedLayerId,
+      selectedLayerIds,
+    }),
+    captureCanvasHistory,
   });
   const getViewportElement = () => {
     const element = canvasViewportRef.current;
@@ -309,7 +325,10 @@ function StageInteractionsHarness({
       </span>
       <span data-testid="layers">
         {layers
-          .map((layer) => `${layer.id}:${layer.x.toFixed(1)},${layer.y.toFixed(1)}`)
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.x.toFixed(1)},${layer.y.toFixed(1)}`,
+          )
           .join('|')}
       </span>
       <span data-testid="viewport-state">
@@ -323,7 +342,9 @@ function StageInteractionsHarness({
       <span data-testid="panning">{String(interaction.isPanning)}</span>
       <span data-testid="tool">{interaction.effectiveTool}</span>
       <span data-testid="snap">
-        {interaction.snapGuide?.vertical ?? interaction.snapGuide?.horizontal ?? '-'}
+        {interaction.snapGuide?.vertical ??
+          interaction.snapGuide?.horizontal ??
+          '-'}
       </span>
       <span data-testid="dialog-position">
         {generateDialog?.placeholder
@@ -337,9 +358,7 @@ function StageInteractionsHarness({
         {String(generateDialog?.composerOpen ?? false)}
       </span>
       <span data-testid="clear-count">{clearCount}</span>
-      <span data-testid="image-menu-close-count">
-        {imageMenuCloseCount}
-      </span>
+      <span data-testid="image-menu-close-count">{imageMenuCloseCount}</span>
       <button
         type="button"
         onClick={() => {
@@ -421,6 +440,20 @@ function StageInteractionsHarness({
       >
         直接移动图层
       </button>
+      <button
+        type="button"
+        onClick={() => {
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 2,
+              clientX: 222,
+              clientY: 61,
+            }),
+          );
+        }}
+      >
+        直接轻微移动图层
+      </button>
       <button
         type="button"
         onClick={(event) => {
@@ -688,13 +721,98 @@ function StageInteractionsHarness({
       >
         直接结束小地图拖拽
       </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleLayerPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 20,
+              clientX: 40,
+              clientY: 40,
+              button: 2,
+              buttons: 2,
+            }),
+            firstLayer,
+          );
+        }}
+      >
+        右键选第一层
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          setActiveTool('hand');
+          interaction.handleLayerPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 21,
+              clientX: 40,
+              clientY: 40,
+              button: 2,
+              buttons: 2,
+            }),
+            firstLayer,
+          );
+        }}
+      >
+        右键抓手模式选第一层
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          const frameElement = document.createElement('div');
+          const dialog = asCanvasGenerationDialog(generateDialog);
+          if (!dialog) {
+            return;
+          }
+          interaction.handleGenerationFramePointerDown(
+            createPointerEvent(frameElement, {
+              pointerId: 22,
+              clientX: 300,
+              clientY: 200,
+              button: 2,
+              buttons: 2,
+            }),
+            dialog,
+          );
+        }}
+      >
+        右键拖生成占位
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          setActiveTool('hand');
+          const frameElement = document.createElement('div');
+          const dialog = asCanvasGenerationDialog(generateDialog);
+          if (!dialog) {
+            return;
+          }
+          interaction.handleGenerationFramePointerDown(
+            createPointerEvent(frameElement, {
+              pointerId: 23,
+              clientX: 300,
+              clientY: 200,
+              button: 2,
+              buttons: 2,
+            }),
+            dialog,
+          );
+        }}
+      >
+        右键抓手模式拖生成占位
+      </button>
     </div>
   );
 }
 
 describe('useImageCanvasStageInteractions', () => {
   it('selects and drags multiple layers from stage pointer events', () => {
-    render(<StageInteractionsHarness />);
+    const captureCanvasHistory = vi.fn();
+    render(
+      <StageInteractionsHarness
+        captureCanvasHistory={captureCanvasHistory}
+      />,
+    );
 
     act(() => {
       screen.getByRole('button', { name: '直接选第一层' }).click();
@@ -718,6 +836,11 @@ describe('useImageCanvasStageInteractions', () => {
     expect(screen.getByTestId('layers').textContent).toContain(
       'second:250.0,90.0',
     );
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+    expect(captureCanvasHistory).toHaveBeenCalledWith(
+      { type: 'move-image', count: 2 },
+      expect.objectContaining({ snapshot: expect.any(Object) }),
+    );
 
     act(() => {
       screen.getByRole('button', { name: '直接结束图层拖拽' }).click();
@@ -745,6 +868,25 @@ describe('useImageCanvasStageInteractions', () => {
     expect(screen.getByTestId('selection').textContent).toBe('second:second');
   });
 
+  it('keeps sub-threshold pointer jitter from moving layers or creating history', () => {
+    const captureCanvasHistory = vi.fn();
+    render(
+      <StageInteractionsHarness
+        captureCanvasHistory={captureCanvasHistory}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接追加第二层' }).click();
+      screen.getByRole('button', { name: '直接轻微移动图层' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'second:220.0,60.0',
+    );
+    expect(captureCanvasHistory).not.toHaveBeenCalled();
+  });
+
   it('handles marquee, temporary hand mode, and generation frame dragging', () => {
     const activateCanvasGenerationDialog = vi.fn();
     render(
@@ -778,7 +920,9 @@ describe('useImageCanvasStageInteractions', () => {
     act(() => {
       screen.getByRole('button', { name: '直接移动平移' }).click();
     });
-    expect(screen.getByTestId('viewport-state').textContent).toBe('30.0,25.0,1');
+    expect(screen.getByTestId('viewport-state').textContent).toBe(
+      '30.0,25.0,1',
+    );
     act(() => {
       screen.getByRole('button', { name: '清理交互' }).click();
     });
@@ -800,9 +944,7 @@ describe('useImageCanvasStageInteractions', () => {
     render(<StageInteractionsHarness />);
 
     act(() => {
-      screen
-        .getByRole('button', { name: '直接贴近图层拖生成占位' })
-        .click();
+      screen.getByRole('button', { name: '直接贴近图层拖生成占位' }).click();
     });
 
     expect(screen.getByTestId('dialog-position').textContent).toBe(
@@ -844,8 +986,9 @@ describe('useImageCanvasStageInteractions', () => {
     act(() => {
       screen.getByRole('button', { name: '直接追加生成器' }).click();
     });
-    const generationSelectionId =
-      screen.getByTestId('dialog-selection-id').textContent;
+    const generationSelectionId = screen.getByTestId(
+      'dialog-selection-id',
+    ).textContent;
     expect(screen.getByTestId('selection').textContent).toBe(
       `first:first,${generationSelectionId}`,
     );
@@ -920,4 +1063,172 @@ describe('useImageCanvasStageInteractions', () => {
     expect(flushMinimapViewportDrag).toHaveBeenCalledTimes(1);
     expect(onViewportInteractionEnd).toHaveBeenCalledTimes(2);
   });
+
+  it('allows middle-button dragging and rejects right-button dragging in select, hand, and Space modes', () => {
+    render(<StageInteractionsHarness />);
+
+    const viewport = screen.getByTestId('viewport');
+
+    act(() => {
+      fireEvent(
+        viewport,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 100,
+          clientY: 100,
+          button: 1,
+          buttons: 4,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('true');
+
+    act(() => {
+      fireEvent(
+        viewport,
+        new MouseEvent('pointerup', {
+          bubbles: true,
+          clientX: 100,
+          clientY: 100,
+          button: 1,
+          buttons: 0,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+
+    act(() => {
+      fireEvent(
+        viewport,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 100,
+          clientY: 100,
+          button: 2,
+          buttons: 2,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+
+    act(() => {
+      screen.getByRole('button', { name: '切抓手' }).click();
+    });
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      fireEvent(
+        viewport,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 100,
+          clientY: 100,
+          button: 2,
+          buttons: 2,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+
+    act(() => {
+      screen.getByRole('button', { name: '松开空格' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '按住空格' }).click();
+    });
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      fireEvent(
+        viewport,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 100,
+          clientY: 100,
+          button: 2,
+          buttons: 2,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+  });
+
+  it('rejects right-click panning on layers in select, hand, and Space modes', () => {
+    render(<StageInteractionsHarness />);
+
+    act(() => {
+      screen.getByRole('button', { name: '右键选第一层' }).click();
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+    expect(screen.getByTestId('selection').textContent).toBe('-:');
+
+    act(() => {
+      screen.getByRole('button', { name: '右键抓手模式选第一层' }).click();
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+    expect(screen.getByTestId('selection').textContent).toBe('-:');
+
+    act(() => {
+      screen.getByRole('button', { name: '松开空格' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '按住空格' }).click();
+    });
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      const layer = screen.getByTestId('layer-first');
+      fireEvent(
+        layer,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 40,
+          clientY: 40,
+          button: 2,
+          buttons: 2,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+    expect(screen.getByTestId('selection').textContent).toBe('-:');
+  });
+
+  it('rejects right-click panning on generation frames in select, hand, and Space modes', () => {
+    render(<StageInteractionsHarness />);
+
+    act(() => {
+      screen.getByRole('button', { name: '右键拖生成占位' }).click();
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+
+    act(() => {
+      screen.getByRole('button', { name: '右键抓手模式拖生成占位' }).click();
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      screen.getByRole('button', { name: '松开空格' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '按住空格' }).click();
+    });
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      const frame = screen.getByTestId('generation-frame');
+      fireEvent(
+        frame,
+        new MouseEvent('pointerdown', {
+          bubbles: true,
+          clientX: 300,
+          clientY: 200,
+          button: 2,
+          buttons: 2,
+        }),
+      );
+    });
+    expect(screen.getByTestId('panning').textContent).toBe('false');
+  });
 });
diff --git a/src/components/image-editor/useImageCanvasStageInteractions.ts b/src/components/image-editor/useImageCanvasStageInteractions.ts
index f6054e3e9..ad0a882b6 100644
--- a/src/components/image-editor/useImageCanvasStageInteractions.ts
+++ b/src/components/image-editor/useImageCanvasStageInteractions.ts
@@ -1,7 +1,7 @@
 import {
   type Dispatch,
-  type PointerEvent as ReactPointerEvent,
   type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
   type RefObject,
   type SetStateAction,
   useCallback,
@@ -10,9 +10,21 @@ import {
   useState,
 } from 'react';
 
+import type {
+  CanvasGenerationDialogState,
+  CanvasHistoryAction,
+  CanvasHistorySnapshot,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasTool,
+  CanvasViewport,
+  DragState,
+  GenerateDialogState,
+  SnapGuide,
+} from './ImageCanvasEditorTypes';
 import {
-  moveGenerationFramesFromDrag,
   moveDragSelectedLayers,
+  moveGenerationFramesFromDrag,
   moveLayersFromDrag,
   moveViewportFromPan,
   selectCanvasObjectsInsideMarquee,
@@ -32,16 +44,6 @@ import {
   updateGenerateDialogForLayerPointerDown,
   updateMinimapDragMovement,
 } from './ImageCanvasStageInteractionModel';
-import type {
-  CanvasGenerationDialogState,
-  CanvasLayer,
-  CanvasMarqueeState,
-  CanvasTool,
-  CanvasViewport,
-  DragState,
-  GenerateDialogState,
-  SnapGuide,
-} from './ImageCanvasEditorTypes';
 
 const CLICK_COLLAPSE_MOVEMENT_THRESHOLD_PX = 3;
 
@@ -92,9 +94,7 @@ type UseImageCanvasStageInteractionsOptions = {
   pickUiDesignSpecFromLayer: (layer: CanvasLayer) => void;
   pickPublicationReferenceFromLayer: (layer: CanvasLayer) => void;
   openLayerGenerationDialog?: (layer: CanvasLayer) => boolean;
-  activateCanvasGenerationDialog: (
-    dialog: CanvasGenerationDialogState,
-  ) => void;
+  activateCanvasGenerationDialog: (dialog: CanvasGenerationDialogState) => void;
   updateCanvasGenerationDialogById: (
     dialogId: string,
     updater: (
@@ -112,6 +112,19 @@ type UseImageCanvasStageInteractionsOptions = {
   onViewportInteractionStart?: () => void;
   onViewportInteractionEnd?: () => void;
   onCloseImageContextMenu: () => void;
+  getCanvasHistorySnapshot: () => CanvasHistorySnapshot;
+  captureCanvasHistory: (
+    action: CanvasHistoryAction,
+    options?: { snapshot?: CanvasHistorySnapshot },
+  ) => void;
+};
+
+type PendingDragHistory = {
+  snapshot: CanvasHistorySnapshot;
+  action: CanvasHistoryAction;
+  startClientX: number;
+  startClientY: number;
+  committed: boolean;
 };
 
 function focusCanvasInteractionTarget(target: HTMLElement) {
@@ -171,8 +184,11 @@ export function useImageCanvasStageInteractions({
   onViewportInteractionStart,
   onViewportInteractionEnd,
   onCloseImageContextMenu,
+  getCanvasHistorySnapshot,
+  captureCanvasHistory,
 }: UseImageCanvasStageInteractionsOptions) {
   const dragStateRef = useRef<DragState | null>(null);
+  const pendingDragHistoryRef = useRef<PendingDragHistory | null>(null);
   const pendingClickCollapseRef = useRef<PendingClickCollapse | null>(null);
   const isShiftPressedRef = useRef(false);
   const suppressNextLayerClickRef = useRef(false);
@@ -207,6 +223,7 @@ export function useImageCanvasStageInteractions({
       flushMinimapViewportDrag();
     }
     dragStateRef.current = null;
+    pendingDragHistoryRef.current = null;
     pendingClickCollapseRef.current = null;
     setCanvasMarquee(null);
     setIsPanning(false);
@@ -216,6 +233,11 @@ export function useImageCanvasStageInteractions({
     }
   }, [finishViewportInteraction, flushMinimapViewportDrag]);
 
+  const rejectRightButtonInteraction = useCallback(() => {
+    // Preserve the pointer event so the matching contextmenu event can still open.
+    clearActiveInteraction();
+  }, [clearActiveInteraction]);
+
   const setShiftPressed = useCallback((pressed: boolean) => {
     isShiftPressedRef.current = pressed;
   }, []);
@@ -239,12 +261,17 @@ export function useImageCanvasStageInteractions({
   const handleCanvasPointerDown = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>) => {
       const button = getPointerButton(event);
-      if (button !== 0 || effectiveTool === 'hand') {
+      if (button === 2) {
+        rejectRightButtonInteraction();
+        return;
+      }
+      if (button === 1 || (button === 0 && effectiveTool === 'hand')) {
         startPan(event);
         return;
       }
 
       if (button !== 0) {
+        event.preventDefault();
         return;
       }
       const target = event.target as HTMLElement;
@@ -269,18 +296,29 @@ export function useImageCanvasStageInteractions({
       }
       clearCanvasFocus();
     },
-    [canvasViewportRef, clearCanvasFocus, effectiveTool, startPan],
+    [
+      canvasViewportRef,
+      clearCanvasFocus,
+      effectiveTool,
+      rejectRightButtonInteraction,
+      startPan,
+    ],
   );
 
   const handleLayerPointerDown = useCallback(
     (event: ReactPointerEvent<HTMLElement>, layer: CanvasLayer) => {
       const button = getPointerButton(event);
-      if (button === 1 || effectiveTool === 'hand') {
+      if (button === 2) {
+        rejectRightButtonInteraction();
+        return;
+      }
+      if (button === 1 || (button === 0 && effectiveTool === 'hand')) {
         event.stopPropagation();
         startPan(event);
         return;
       }
       if (button !== 0) {
+        event.preventDefault();
         event.stopPropagation();
         return;
       }
@@ -362,6 +400,7 @@ export function useImageCanvasStageInteractions({
       event.preventDefault();
       event.stopPropagation();
       const pointer = getPointerClient(event);
+      const dragHistorySnapshot = getCanvasHistorySnapshot();
       canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
       const isMultiSelectGesture = event.shiftKey || isShiftPressedRef.current;
       const layerDragStart = createLayerDragStart({
@@ -380,6 +419,16 @@ export function useImageCanvasStageInteractions({
         updateGenerateDialogForLayerPointerDown(currentDialog, layer.id),
       );
       dragStateRef.current = layerDragStart.dragState;
+      pendingDragHistoryRef.current = {
+        snapshot: dragHistorySnapshot,
+        action: {
+          type: 'move-image',
+          count: layerDragStart.selectedLayerIds.length,
+        },
+        startClientX: pointer.x,
+        startClientY: pointer.y,
+        committed: false,
+      };
       pendingClickCollapseRef.current = {
         kind: 'layer',
         pointerId: getPointerId(event),
@@ -392,6 +441,7 @@ export function useImageCanvasStageInteractions({
     [
       canvasViewportRef,
       canvasGenerationDialogs,
+      getCanvasHistorySnapshot,
       effectiveTool,
       generateDialog?.mode,
       isPickingCharacterSpecFromCanvas,
@@ -399,6 +449,7 @@ export function useImageCanvasStageInteractions({
       isPickingQuickEditReferenceFromCanvas,
       isPickingCharacterReferenceFromCanvas,
       isPickingIconSpecFromCanvas,
+      isPickingUiDesignSpecFromCanvas,
       isPickingPublicationReferenceFromCanvas,
       layers,
       pickGenerationReferenceFromLayer,
@@ -408,6 +459,7 @@ export function useImageCanvasStageInteractions({
       pickIconSpecFromLayer,
       pickPublicationReferenceFromLayer,
       pickUiDesignSpecFromLayer,
+      rejectRightButtonInteraction,
       selectedLayerIds,
       setGenerateDialog,
       setSelectedLayerId,
@@ -480,12 +532,18 @@ export function useImageCanvasStageInteractions({
         return;
       }
       const button = getPointerButton(event);
-      if (button === 1 || effectiveTool === 'hand') {
+      if (button === 2) {
+        rejectRightButtonInteraction();
+        return;
+      }
+      if (button === 1 || (button === 0 && effectiveTool === 'hand')) {
         event.stopPropagation();
         startPan(event);
         return;
       }
       if (button !== 0) {
+        event.preventDefault();
+        event.stopPropagation();
         return;
       }
 
@@ -493,6 +551,7 @@ export function useImageCanvasStageInteractions({
       event.preventDefault();
       event.stopPropagation();
       const pointer = getPointerClient(event);
+      const dragHistorySnapshot = getCanvasHistorySnapshot();
       canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
       const isMultiSelectGesture = event.shiftKey || isShiftPressedRef.current;
       if (!isMultiSelectGesture) {
@@ -511,6 +570,16 @@ export function useImageCanvasStageInteractions({
       setSelectedLayerId(frameDragStart.selectedLayerId);
       setSelectedLayerIds(frameDragStart.selectedLayerIds);
       dragStateRef.current = frameDragStart.dragState;
+      pendingDragHistoryRef.current = {
+        snapshot: dragHistorySnapshot,
+        action: {
+          type: 'move-generation-result',
+          count: frameDragStart.selectedLayerIds.length,
+        },
+        startClientX: pointer.x,
+        startClientY: pointer.y,
+        committed: false,
+      };
       pendingClickCollapseRef.current = {
         kind: 'generation-frame',
         pointerId: getPointerId(event),
@@ -525,7 +594,9 @@ export function useImageCanvasStageInteractions({
       canvasViewportRef,
       canvasGenerationDialogs,
       effectiveTool,
+      getCanvasHistorySnapshot,
       layers,
+      rejectRightButtonInteraction,
       selectedLayerIds,
       setSelectedLayerId,
       setSelectedLayerIds,
@@ -553,6 +624,9 @@ export function useImageCanvasStageInteractions({
 
   const handlePointerMove = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>) => {
+      if ((event.buttons & 2) !== 0 && (event.buttons & (1 | 4)) === 0) {
+        return;
+      }
       if (canvasMarquee && canvasMarquee.pointerId === event.pointerId) {
         event.preventDefault();
         const rect = canvasViewportRef.current?.getBoundingClientRect();
@@ -596,6 +670,22 @@ export function useImageCanvasStageInteractions({
         return;
       }
 
+      const dragPointer = getPointerClient(event);
+      const pendingDragHistory = pendingDragHistoryRef.current;
+      if (pendingDragHistory && !pendingDragHistory.committed) {
+        const movementDistance = Math.hypot(
+          dragPointer.x - pendingDragHistory.startClientX,
+          dragPointer.y - pendingDragHistory.startClientY,
+        );
+        if (movementDistance < CLICK_COLLAPSE_MOVEMENT_THRESHOLD_PX) {
+          return;
+        }
+        captureCanvasHistory(pendingDragHistory.action, {
+          snapshot: pendingDragHistory.snapshot,
+        });
+        pendingDragHistory.committed = true;
+      }
+
       if (dragState.kind === 'pan') {
         const pointer = getPointerClient(event);
         setViewport(moveViewportFromPan(dragState, pointer));
@@ -668,6 +758,7 @@ export function useImageCanvasStageInteractions({
     },
     [
       canvasMarquee,
+      captureCanvasHistory,
       canvasViewportRef,
       canvasGenerationDialogs,
       layers,
@@ -728,6 +819,7 @@ export function useImageCanvasStageInteractions({
           flushMinimapViewportDrag();
         }
         dragStateRef.current = null;
+        pendingDragHistoryRef.current = null;
         setIsPanning(false);
         setSnapGuide(null);
         if (dragState.kind === 'pan' || dragState.kind === 'minimap') {
diff --git a/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx b/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx
index efa115b08..30e2b669c 100644
--- a/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx
@@ -178,6 +178,7 @@ function UploadWorkflowHarness({
     appendCanvasLayersWithResources: (nextLayers) => {
       setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
     },
+    captureCanvasHistory: vi.fn(),
     selectSingleLayer: setSelectedLayerId,
   });
 
diff --git a/src/components/image-editor/useImageCanvasUploadWorkflow.ts b/src/components/image-editor/useImageCanvasUploadWorkflow.ts
index fc718e6af..d73d0fecc 100644
--- a/src/components/image-editor/useImageCanvasUploadWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasUploadWorkflow.ts
@@ -15,9 +15,15 @@ import {
   createEditorProjectResource,
 } from '../../services/image-editor/editorProjectClient';
 import { uploadEditorSeedanceReferenceFile } from '../../services/image-editor/editorReferenceUploadClient';
+import {
+  EDITOR_UPLOAD_ASSET_FOLDER_LABEL,
+  resolvePreferredAssetUploadFolder,
+  resolveUploadAssetFolder,
+} from './ImageCanvasAssetLibraryModel';
 import type {
-  CanvasMediaType,
+  CanvasHistoryAction,
   CanvasLayer,
+  CanvasMediaType,
   CanvasTool,
   CanvasViewport,
   CharacterReferenceImage,
@@ -28,28 +34,23 @@ import type {
   UploadTarget,
 } from './ImageCanvasEditorTypes';
 import {
-  EDITOR_UPLOAD_ASSET_FOLDER_LABEL,
-  resolvePreferredAssetUploadFolder,
-  resolveUploadAssetFolder,
-} from './ImageCanvasAssetLibraryModel';
-import {
-  SEEDANCE_REFERENCE_FILE_LIMITS,
   isImageFile,
-  resolveEditorAssetUploadMediaType,
   isSeedanceReferenceAudioFile,
   isSeedanceReferenceImageFile,
   isSeedanceReferenceVideoFile,
   probeImageFileDimensions,
-  probeMediaFileMetadata,
   probeMediaDurationSeconds,
+  probeMediaFileMetadata,
   readFileAsDataUrl,
   readImageFileAsDataUrl,
+  resolveEditorAssetUploadMediaType,
+  SEEDANCE_REFERENCE_FILE_LIMITS,
 } from './ImageCanvasFileModel';
 import {
   applyGenerationReferenceUpload,
-  applyQuickEditReferenceUpload,
   applyMeasuredUploadAssetSize,
   applyPersistedUploadAsset,
+  applyQuickEditReferenceUpload,
   applyUploadAssetCreateFailure,
   applyUploadAssetCreatePending,
   applyUploadAssetReadFailure,
@@ -97,6 +98,7 @@ type UseImageCanvasUploadWorkflowOptions = {
     references: CharacterReferenceImage[],
   ) => void;
   appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  captureCanvasHistory: (action: CanvasHistoryAction) => void;
   selectSingleLayer: (layerId: string | null) => void;
 };
 
@@ -134,6 +136,7 @@ export function useImageCanvasUploadWorkflow({
   setQuickEditPanel,
   appendUiAssetExtractionReferences,
   appendCanvasLayersWithResources,
+  captureCanvasHistory,
   selectSingleLayer,
 }: UseImageCanvasUploadWorkflowOptions) {
   const uploadInputRef = useRef<HTMLInputElement | null>(null);
@@ -1021,6 +1024,7 @@ export function useImageCanvasUploadWorkflow({
       });
 
       if (options.addToCanvas) {
+        captureCanvasHistory({ type: 'upload-image', count: 1 });
         appendCanvasLayersWithResources([nextLayer]);
         selectSingleLayer(nextLayer.id);
       }
@@ -1112,17 +1116,15 @@ export function useImageCanvasUploadWorkflow({
     [
       activeUploadFolderId,
       appendCanvasLayersWithResources,
+      captureCanvasHistory,
       assetFolders,
-      canvasSize.height,
-      canvasSize.width,
+      canvasSize,
       openEditorLoginModal,
       selectSingleLayer,
       setAssetFolders,
       setAssets,
       setLayers,
-      viewport.scale,
-      viewport.x,
-      viewport.y,
+      viewport,
     ],
   );
 
diff --git a/src/components/image-editor/useImageCanvasViewportControls.ts b/src/components/image-editor/useImageCanvasViewportControls.ts
index 9cbf6b30c..4e5d0ba1d 100644
--- a/src/components/image-editor/useImageCanvasViewportControls.ts
+++ b/src/components/image-editor/useImageCanvasViewportControls.ts
@@ -117,7 +117,10 @@ export function useImageCanvasViewportControls({
   );
 
   const fitLayers = useCallback(
-    (targetLayers: CanvasLayer[] = layers) => {
+    (
+      targetLayers: CanvasLayer[] = layers,
+      options: { captureHistory?: boolean } = {},
+    ) => {
       const nextViewport = fitViewportToLayers({
         layers: targetLayers,
         canvasSize,
@@ -126,7 +129,9 @@ export function useImageCanvasViewportControls({
         return;
       }
 
-      captureCanvasHistory();
+      if (options.captureHistory !== false) {
+        captureCanvasHistory();
+      }
       setViewport(nextViewport);
     },
     [captureCanvasHistory, canvasSize, layers],
diff --git a/src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx b/src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx
index 23281f943..b3da7337b 100644
--- a/src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx
+++ b/src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx
@@ -10,22 +10,22 @@ import type {
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
 import { useJumpHopLeaderboard } from '../../services/jump-hop/useJumpHopLeaderboard';
 import {
-  JUMP_HOP_THREE_CAMERA_UP_Y,
-  JUMP_HOP_THREE_CHARACTER_RENDER_ORDER,
-  JUMP_HOP_THREE_CHARACTER_TOP_FACE_Z_OFFSET,
-  JUMP_HOP_THREE_MATERIAL_FACE_ORDER,
-  JUMP_HOP_THREE_PLATFORM_MATERIAL_TRANSPARENT,
-  JUMP_HOP_THREE_PLATFORM_MESH_RENDER_ORDER_BASE,
-  JUMP_HOP_THREE_PLATFORM_YAW_RAD,
-  JUMP_HOP_THREE_PLATFORM_CUBE_SIZE_MULTIPLIER,
-  JUMP_HOP_THREE_TEXTURE_TRANSFORMS,
-  JumpHopRuntimeShell,
   getJumpHopThreeCharacterFootZ,
   getJumpHopThreeCubeSide,
   getJumpHopThreeProjectedY,
   getJumpHopThreeWorldYForScreenY,
   getJumpHopTileTextureSignature,
   hasCompleteJumpHopTileFaceAssets,
+  JUMP_HOP_THREE_CAMERA_UP_Y,
+  JUMP_HOP_THREE_CHARACTER_RENDER_ORDER,
+  JUMP_HOP_THREE_CHARACTER_TOP_FACE_Z_OFFSET,
+  JUMP_HOP_THREE_MATERIAL_FACE_ORDER,
+  JUMP_HOP_THREE_PLATFORM_CUBE_SIZE_MULTIPLIER,
+  JUMP_HOP_THREE_PLATFORM_MATERIAL_TRANSPARENT,
+  JUMP_HOP_THREE_PLATFORM_MESH_RENDER_ORDER_BASE,
+  JUMP_HOP_THREE_PLATFORM_YAW_RAD,
+  JUMP_HOP_THREE_TEXTURE_TRANSFORMS,
+  JumpHopRuntimeShell,
   resolveJumpHopThreeCharacterFrame,
 } from './JumpHopRuntimeShell';
 
diff --git a/src/components/match3d-result/Match3DResultView.tsx b/src/components/match3d-result/Match3DResultView.tsx
index 2a8d90403..76edece1a 100644
--- a/src/components/match3d-result/Match3DResultView.tsx
+++ b/src/components/match3d-result/Match3DResultView.tsx
@@ -60,8 +60,8 @@ import {
   readPuzzleReferenceImageAsDataUrl,
 } from '../../services/puzzleReferenceImage';
 import { PlatformActionButton } from '../common/PlatformActionButton';
-import { PlatformBackActionButton } from '../common/PlatformBackActionButton';
 import { PlatformAssetPickerGrid } from '../common/PlatformAssetPickerCard';
+import { PlatformBackActionButton } from '../common/PlatformBackActionButton';
 import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
 import { PlatformIconButton } from '../common/PlatformIconButton';
 import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
diff --git a/src/components/match3d-runtime/match3dHotspot.test.ts b/src/components/match3d-runtime/match3dHotspot.test.ts
index fef6d646e..137ee7489 100644
--- a/src/components/match3d-runtime/match3dHotspot.test.ts
+++ b/src/components/match3d-runtime/match3dHotspot.test.ts
@@ -4,8 +4,8 @@ import type { Match3DRunSnapshot } from '../../../packages/shared/src/contracts/
 import {
   findMatch3DHitItem,
   isPointInsideMatch3DItemAlphaHotspot,
-  resolveMatch3DItemSizeScale,
   type Match3DResolvedImageSourceEntry,
+  resolveMatch3DItemSizeScale,
 } from './match3dHotspot';
 import { resolveRenderableItemFrame } from './match3dRuntimePresentation';
 
diff --git a/src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx b/src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx
index e8170da18..fdf784ac3 100644
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx
@@ -11,8 +11,8 @@ import { expect, test, vi } from 'vitest';
 
 import {
   PuzzleOnboardingLoginOverlay,
-  PuzzleOnboardingView,
   type PuzzleOnboardingPhase,
+  PuzzleOnboardingView,
 } from './PuzzleOnboardingView';
 
 function renderOnboarding({
diff --git a/src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx b/src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx
index 366d3dcec..011b25fc7 100644
--- a/src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx
+++ b/src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx
@@ -8,13 +8,12 @@ import type {
 import { PlatformAsyncStatePanel } from '../common/PlatformAsyncStatePanel';
 import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
+import { PlatformPillBadge } from '../common/PlatformPillBadge';
 import { PlatformProfileContentRow } from '../common/PlatformProfileContentRow';
 import { PlatformProfileSkeletonList } from '../common/PlatformProfileSkeletonList';
 import { PlatformProfileSummaryHeader } from '../common/PlatformProfileSummaryHeader';
-import { PlatformPillBadge } from '../common/PlatformPillBadge';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { ResolvedAssetImage } from '../ResolvedAssetImage';
-import { PlatformProfileSecondaryModalShell } from './PlatformProfileModalShell';
 import {
   formatCompactPlayTime,
   formatPlayedWorkId,
@@ -23,6 +22,7 @@ import {
   formatTotalPlayTimeHours,
 } from '../rpg-entry/rpgEntryProfileDashboardPresentation';
 import { formatPlatformWorkDisplayName } from '../rpg-entry/rpgEntryWorldPresentation';
+import { PlatformProfileSecondaryModalShell } from './PlatformProfileModalShell';
 
 type PlatformProfilePlayedWorksModalProps = {
   stats: ProfilePlayStatsResponse | null;
diff --git a/src/components/platform-entry/PlatformProfileQrScannerModal.tsx b/src/components/platform-entry/PlatformProfileQrScannerModal.tsx
index a59c587ab..1c998146d 100644
--- a/src/components/platform-entry/PlatformProfileQrScannerModal.tsx
+++ b/src/components/platform-entry/PlatformProfileQrScannerModal.tsx
@@ -1,8 +1,8 @@
 import { useEffect, useRef } from 'react';
 
+import { scanHostQrCode } from '../../services/host-bridge/hostBridge';
 import { PlatformModalCloseButton } from '../common/PlatformModalCloseButton';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
-import { scanHostQrCode } from '../../services/host-bridge/hostBridge';
 import { PlatformProfileModalShell } from './PlatformProfileModalShell';
 
 const PROFILE_QR_SCAN_INTERVAL_MS = 360;
@@ -165,7 +165,7 @@ export function PlatformProfileQrScannerModal({
       clearScanTimer();
       stopCamera();
     };
-  }, [mode, onError, onResult]);
+  }, [mode, onClose, onError, onResult]);
 
   return (
     <PlatformProfileModalShell
diff --git a/src/components/platform-entry/PlatformProfileTaskCenterModal.tsx b/src/components/platform-entry/PlatformProfileTaskCenterModal.tsx
index 419b3ed39..d966929af 100644
--- a/src/components/platform-entry/PlatformProfileTaskCenterModal.tsx
+++ b/src/components/platform-entry/PlatformProfileTaskCenterModal.tsx
@@ -1,17 +1,17 @@
 import type { ProfileTaskCenterResponse } from '../../../packages/shared/src/contracts/runtime';
 import { PlatformActionButton } from '../common/PlatformActionButton';
 import { PlatformAsyncStatePanel } from '../common/PlatformAsyncStatePanel';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformProfileContentRow } from '../common/PlatformProfileContentRow';
 import { PlatformProfileSkeletonList } from '../common/PlatformProfileSkeletonList';
-import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
-import { PlatformProfileModalShell } from './PlatformProfileModalShell';
 import {
   buildProfileTaskProgressLabel,
   getProfileTaskClaimButtonLabel,
   getProfileTaskStatusLabel,
   selectProfileTaskCenterTasks,
 } from '../rpg-entry/rpgEntryProfileTaskViewModel';
+import { PlatformProfileModalShell } from './PlatformProfileModalShell';
 
 export type PlatformProfileTaskCenterModalProps = {
   center: ProfileTaskCenterResponse | null;
diff --git a/src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx b/src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx
index a5799c623..e02c9bb3a 100644
--- a/src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx
+++ b/src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx
@@ -4,14 +4,14 @@ import type { ProfileWalletLedgerResponse } from '../../../packages/shared/src/c
 import { PlatformActionButton } from '../common/PlatformActionButton';
 import { PlatformAsyncStatePanel } from '../common/PlatformAsyncStatePanel';
 import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import { PlatformPillBadge } from '../common/PlatformPillBadge';
 import { PlatformProfileContentRow } from '../common/PlatformProfileContentRow';
 import { PlatformProfileSkeletonList } from '../common/PlatformProfileSkeletonList';
 import { PlatformProfileSummaryHeader } from '../common/PlatformProfileSummaryHeader';
-import { PlatformPillBadge } from '../common/PlatformPillBadge';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
-import { PlatformProfileSecondaryModalShell } from './PlatformProfileModalShell';
 import { buildWalletLedgerPresentation } from '../rpg-entry/rpgEntryProfileFundsViewModel';
 import { formatPlatformWorldTime } from '../rpg-entry/rpgEntryWorldPresentation';
+import { PlatformProfileSecondaryModalShell } from './PlatformProfileModalShell';
 
 export type PlatformProfileWalletLedgerModalProps = {
   ledger: ProfileWalletLedgerResponse | null;
diff --git a/src/components/platform-entry/index.ts b/src/components/platform-entry/index.ts
index 35b99ca52..9deca9dd8 100644
--- a/src/components/platform-entry/index.ts
+++ b/src/components/platform-entry/index.ts
@@ -1,9 +1,9 @@
+export {
+  PlatformEntryCreationTypeModal,
+  type PlatformEntryCreationTypeModalProps,
+} from './PlatformEntryCreationTypeModal';
 export {
   PlatformEntryFlowShell,
   type PlatformEntryFlowShellProps,
   type SelectionStage,
 } from './PlatformEntryFlowShell';
-export {
-  PlatformEntryCreationTypeModal,
-  type PlatformEntryCreationTypeModalProps,
-} from './PlatformEntryCreationTypeModal';
diff --git a/src/components/platform-entry/platformMiniGameSessionMappingModel.ts b/src/components/platform-entry/platformMiniGameSessionMappingModel.ts
index b11e128d0..373c10637 100644
--- a/src/components/platform-entry/platformMiniGameSessionMappingModel.ts
+++ b/src/components/platform-entry/platformMiniGameSessionMappingModel.ts
@@ -2,12 +2,12 @@ import type {
   JumpHopSessionSnapshotResponse,
   JumpHopWorkSummaryResponse,
 } from '../../../packages/shared/src/contracts/jumpHop';
+import type { PuzzleAgentSessionSnapshot } from '../../../packages/shared/src/contracts/puzzleAgentSession';
 import type {
   PuzzleClearSessionSnapshotResponse,
   PuzzleClearWorkProfileResponse,
   PuzzleClearWorkSummaryResponse,
 } from '../../../packages/shared/src/contracts/puzzleClear';
-import type { PuzzleAgentSessionSnapshot } from '../../../packages/shared/src/contracts/puzzleAgentSession';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type { SquareHoleSessionSnapshot } from '../../../packages/shared/src/contracts/squareHoleAgent';
 import type { SquareHoleWorkProfile } from '../../../packages/shared/src/contracts/squareHoleWorks';
diff --git a/src/components/platform-entry/platformPublicWorkDetailFlow.test.ts b/src/components/platform-entry/platformPublicWorkDetailFlow.test.ts
index a4628e176..88d2b14b9 100644
--- a/src/components/platform-entry/platformPublicWorkDetailFlow.test.ts
+++ b/src/components/platform-entry/platformPublicWorkDetailFlow.test.ts
@@ -4,9 +4,9 @@ import type { BarkBattleWorkSummary } from '../../../packages/shared/src/contrac
 import type { BigFishWorkSummary } from '../../../packages/shared/src/contracts/bigFishWorkSummary';
 import type { JumpHopGalleryCardResponse } from '../../../packages/shared/src/contracts/jumpHop';
 import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
+import type { PuzzleClearGalleryCardResponse } from '../../../packages/shared/src/contracts/puzzleClear';
 import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
-import type { PuzzleClearGalleryCardResponse } from '../../../packages/shared/src/contracts/puzzleClear';
 import type {
   CustomWorldGalleryCard,
   CustomWorldLibraryEntry,
@@ -26,10 +26,10 @@ import {
   mapBarkBattleWorkToPublicWorkDetail,
   mapBigFishWorkToPublicWorkDetail,
   mapJumpHopWorkToPublicWorkDetail,
-  mapPuzzleClearWorkToPublicWorkDetail,
   mapPublicWorkDetailToBigFishWork,
   mapPublicWorkDetailToPuzzleWork,
   mapPublicWorkDetailToSquareHoleWork,
+  mapPuzzleClearWorkToPublicWorkDetail,
   mapPuzzleWorkToPublicWorkDetail,
   mapRpgGalleryCardToPublicWorkDetail,
   mapSquareHoleWorkToPublicWorkDetail,
diff --git a/src/components/platform-entry/platformPublicWorkDetailFlow.ts b/src/components/platform-entry/platformPublicWorkDetailFlow.ts
index 1058cc7e1..4e830065c 100644
--- a/src/components/platform-entry/platformPublicWorkDetailFlow.ts
+++ b/src/components/platform-entry/platformPublicWorkDetailFlow.ts
@@ -5,12 +5,12 @@ import type {
   JumpHopWorkProfileResponse,
 } from '../../../packages/shared/src/contracts/jumpHop';
 import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
-import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
-import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type {
   PuzzleClearGalleryCardResponse,
   PuzzleClearWorkProfileResponse,
 } from '../../../packages/shared/src/contracts/puzzleClear';
+import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
+import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type {
   CustomWorldGalleryCard,
   CustomWorldLibraryEntry,
diff --git a/src/components/platform-entry/puzzleDraftGenerationState.test.ts b/src/components/platform-entry/puzzleDraftGenerationState.test.ts
index fa7b49b33..7e7e0b140 100644
--- a/src/components/platform-entry/puzzleDraftGenerationState.test.ts
+++ b/src/components/platform-entry/puzzleDraftGenerationState.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { isPuzzleCompileActionReady } from './puzzleDraftGenerationState';
 import type { PuzzleAgentSessionSnapshot } from '../../../packages/shared/src/contracts/puzzleAgentSession';
+import { isPuzzleCompileActionReady } from './puzzleDraftGenerationState';
 
 describe('isPuzzleCompileActionReady', () => {
   it('keeps compile action generating until the draft has a cover image', () => {
diff --git a/src/components/platform-entry/usePlatformProfileCenterController.ts b/src/components/platform-entry/usePlatformProfileCenterController.ts
index dafbd71c9..5dc5e7a58 100644
--- a/src/components/platform-entry/usePlatformProfileCenterController.ts
+++ b/src/components/platform-entry/usePlatformProfileCenterController.ts
@@ -385,6 +385,7 @@ export function usePlatformProfileCenterController({
     useCopyFeedback();
   const pendingWechatRechargeOrderIdRef = useRef<string | null>(null);
   const confirmingWechatRechargeOrderIdRef = useRef<string | null>(null);
+  const rechargeCenterReadRevisionRef = useRef(0);
 
   // 中文注释：支持带邀请码 query 的直达场景，登录成功后自动打开兑换面板并复用同一套输入状态。
   useEffect(() => {
@@ -426,18 +427,40 @@ export function usePlatformProfileCenterController({
     loadWalletLedger();
   }, [loadWalletLedger]);
 
+  const applyRechargeCenter = useCallback(
+    (center: ProfileRechargeCenterResponse) => {
+      rechargeCenterReadRevisionRef.current += 1;
+      setIsLoadingRechargeCenter(false);
+      setRechargeError(null);
+      setRechargeCenter(center);
+    },
+    [],
+  );
+
   const loadRechargeCenter = useCallback(() => {
+    const revision = ++rechargeCenterReadRevisionRef.current;
     setRechargeError(null);
     setIsLoadingRechargeCenter(true);
     void getRpgProfileRechargeCenter()
-      .then(setRechargeCenter)
+      .then((center) => {
+        if (revision === rechargeCenterReadRevisionRef.current) {
+          setRechargeCenter(center);
+        }
+      })
       .catch((error: unknown) => {
+        if (revision !== rechargeCenterReadRevisionRef.current) {
+          return;
+        }
         setRechargeCenter(null);
         setRechargeError(
           error instanceof Error ? error.message : '读取泥点购买信息失败',
         );
       })
-      .finally(() => setIsLoadingRechargeCenter(false));
+      .finally(() => {
+        if (revision === rechargeCenterReadRevisionRef.current) {
+          setIsLoadingRechargeCenter(false);
+        }
+      });
   }, []);
 
   const refreshRechargeState = useCallback(() => {
@@ -482,7 +505,7 @@ export function usePlatformProfileCenterController({
         .then((response) => {
           const result = buildRechargePaymentResultForOrder(response.order);
           const isPaid = result.kind === 'success';
-          setRechargeCenter(response.center);
+          applyRechargeCenter(response.center);
           pendingWechatRechargeOrderIdRef.current = null;
           confirmingWechatRechargeOrderIdRef.current = null;
           setWechatRechargeOrderConfirmationState(null);
@@ -525,7 +548,7 @@ export function usePlatformProfileCenterController({
 
     clearWechatPayResultHash();
     return true;
-  }, [onRechargeSuccess, refreshRechargeState]);
+  }, [applyRechargeCenter, onRechargeSuccess, refreshRechargeState]);
 
   const pollWechatPayResultFromHash = useCallback(
     () => handleWechatPayResult(),
@@ -549,7 +572,7 @@ export function usePlatformProfileCenterController({
       .then((response) => {
         const result = buildRechargePaymentResultForOrder(response.order);
         const isPaid = result.kind === 'success';
-        setRechargeCenter(response.center);
+        applyRechargeCenter(response.center);
         pendingWechatRechargeOrderIdRef.current = null;
         confirmingWechatRechargeOrderIdRef.current = null;
         setWechatRechargeOrderConfirmationState(null);
@@ -569,7 +592,7 @@ export function usePlatformProfileCenterController({
         });
       });
     return true;
-  }, [nativeWechatPayment, onRechargeSuccess]);
+  }, [applyRechargeCenter, nativeWechatPayment, onRechargeSuccess]);
 
   const openRechargeModal = useCallback(() => {
     if (!currentUser) {
@@ -625,7 +648,7 @@ export function usePlatformProfileCenterController({
         .then(async (response) => {
           if (paymentChannel === WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_CHANNEL) {
             pendingWechatRechargeOrderIdRef.current = response.order.orderId;
-            setRechargeCenter(response.center);
+            applyRechargeCenter(response.center);
             const paymentHandled = await requestHostPayment({
               payload: response.wechatMiniProgramPayParams,
               orderId: response.order.orderId,
@@ -637,7 +660,7 @@ export function usePlatformProfileCenterController({
           }
           if (paymentChannel === WECHAT_JSAPI_PAYMENT_CHANNEL) {
             pendingWechatRechargeOrderIdRef.current = response.order.orderId;
-            setRechargeCenter(response.center);
+            applyRechargeCenter(response.center);
             setRechargePaymentResult({
               kind: 'pending',
               title: '正在打开微信支付',
@@ -657,7 +680,7 @@ export function usePlatformProfileCenterController({
                   confirmResponse.order,
                 );
                 const isPaid = result.kind === 'success';
-                setRechargeCenter(confirmResponse.center);
+                applyRechargeCenter(confirmResponse.center);
                 setRechargePaymentResult(result);
                 if (result.kind !== 'pending') {
                   pendingWechatRechargeOrderIdRef.current = null;
@@ -681,7 +704,7 @@ export function usePlatformProfileCenterController({
               throw new Error('微信 H5 支付链接生成失败');
             }
             pendingWechatRechargeOrderIdRef.current = response.order.orderId;
-            setRechargeCenter(response.center);
+            applyRechargeCenter(response.center);
             setRechargePaymentResult({
               kind: 'pending',
               title: '正在打开微信支付',
@@ -698,7 +721,7 @@ export function usePlatformProfileCenterController({
               throw new Error('微信 Native 支付链接生成失败');
             }
             pendingWechatRechargeOrderIdRef.current = response.order.orderId;
-            setRechargeCenter(response.center);
+            applyRechargeCenter(response.center);
             setNativeWechatPayment({
               ...wechatNativePayment,
               codeUrl,
@@ -764,7 +787,7 @@ export function usePlatformProfileCenterController({
           setSubmittingRechargeProductId(null);
         });
     },
-    [onRechargeSuccess, submittingRechargeProductId],
+    [applyRechargeCenter, onRechargeSuccess, submittingRechargeProductId],
   );
 
   const confirmNativeWechatPayment = useCallback(() => {
@@ -787,7 +810,7 @@ export function usePlatformProfileCenterController({
         }
         const result = buildRechargePaymentResultForOrder(response.order);
         const isPaid = result.kind === 'success';
-        setRechargeCenter(response.center);
+        applyRechargeCenter(response.center);
         if (result.kind !== 'pending') {
           setNativeWechatPayment(null);
           pendingWechatRechargeOrderIdRef.current = null;
@@ -819,7 +842,7 @@ export function usePlatformProfileCenterController({
         );
       })
       .finally(() => setSubmittingRechargeProductId(null));
-  }, [nativeWechatPayment, onRechargeSuccess]);
+  }, [applyRechargeCenter, nativeWechatPayment, onRechargeSuccess]);
 
   useEffect(() => {
     const orderId = nativeWechatPayment?.orderId;
@@ -845,7 +868,7 @@ export function usePlatformProfileCenterController({
           }
 
           const result = buildRechargePaymentResultForOrder(response.order);
-          setRechargeCenter(response.center);
+          applyRechargeCenter(response.center);
           if (result.kind === 'pending') {
             await waitWechatPayConfirmDelay(WECHAT_NATIVE_WATCH_RETRY_DELAY_MS);
             continue;
@@ -882,6 +905,7 @@ export function usePlatformProfileCenterController({
   }, [
     nativeWechatPayment?.expiresAt,
     nativeWechatPayment?.orderId,
+    applyRechargeCenter,
     onRechargeSuccess,
   ]);
 
diff --git a/src/components/project/ProjectGalleryView.test.tsx b/src/components/project/ProjectGalleryView.test.tsx
index a118a2c76..aea2521e7 100644
--- a/src/components/project/ProjectGalleryView.test.tsx
+++ b/src/components/project/ProjectGalleryView.test.tsx
@@ -387,6 +387,29 @@ describe('ProjectGalleryView', () => {
     });
   });
 
+  it('keeps the project rename modal inside the active platform theme', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    const user = userEvent.setup();
+
+    render(
+      <AuthUiContext.Provider
+        value={createAuthValue({ platformTheme: 'dark' })}
+      >
+        <ProjectGalleryView onOpenProject={vi.fn()} />
+      </AuthUiContext.Provider>,
+    );
+
+    await screen.findByText('角色设定板');
+    await user.click(
+      screen.getByRole('button', { name: '打开项目角色设定板菜单' }),
+    );
+    await user.click(screen.getByRole('menuitem', { name: /重命名/u }));
+
+    const dialog = screen.getByRole('dialog', { name: '重命名' });
+    expect(dialog.closest('.platform-theme--dark')).toBeTruthy();
+    expect(dialog.className).toContain('platform-remap-surface');
+  });
+
   it('supports batch selection actions from the bottom toolbar', async () => {
     listEditorProjectsMock.mockResolvedValueOnce(projectItems);
     deleteEditorProjectMock.mockResolvedValue('deleted');
diff --git a/src/components/project/ProjectGalleryView.tsx b/src/components/project/ProjectGalleryView.tsx
index 4d8286020..a6629c366 100644
--- a/src/components/project/ProjectGalleryView.tsx
+++ b/src/components/project/ProjectGalleryView.tsx
@@ -30,7 +30,7 @@ import { PlatformIconButton } from '../common/PlatformIconButton';
 import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformTextField } from '../common/PlatformTextField';
-import { UnifiedModal } from '../common/UnifiedModal';
+import { PlatformToolModalShell } from '../common/PlatformToolModalShell';
 import {
   LOCAL_PROJECT_COVER_CACHE_ASSET_KIND,
   resolveProjectCoverResource,
@@ -436,7 +436,7 @@ export function ProjectGalleryView({ onOpenProject }: ProjectGalleryViewProps) {
         <section className="project-gallery__grid">{projectCards}</section>
       )}
 
-      <UnifiedModal
+      <PlatformToolModalShell
         open={Boolean(renameDraft)}
         title="重命名"
         size="sm"
@@ -482,7 +482,7 @@ export function ProjectGalleryView({ onOpenProject }: ProjectGalleryViewProps) {
             />
           </form>
         ) : null}
-      </UnifiedModal>
+      </PlatformToolModalShell>
 
       {isSelectionMode ? (
         <PlatformBatchActionToolbar>
diff --git a/src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx b/src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx
index a6dab42df..5bacf860a 100644
--- a/src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx
+++ b/src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx
@@ -1,8 +1,8 @@
 import { ArrowLeft, ChevronRight, RotateCcw } from 'lucide-react';
 import {
   type CSSProperties,
-  type ReactNode,
   type PointerEvent as ReactPointerEvent,
+  type ReactNode,
   useEffect,
   useMemo,
   useRef,
diff --git a/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx b/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx
index 12be18f4d..1d8255e89 100644
--- a/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx
+++ b/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx
@@ -4,8 +4,8 @@ import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { afterEach, expect, test, vi } from 'vitest';
 
-import type { EditableCustomWorldRole } from './roleAssetStudioModel';
 import * as hostBridgeServices from '../../services/host-bridge/hostBridge';
+import type { EditableCustomWorldRole } from './roleAssetStudioModel';
 import { RpgCreationRoleAssetStudioModal } from './RpgCreationRoleAssetStudioModal';
 
 const generateVisualCandidatesForRole = vi.fn();
diff --git a/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx b/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx
index 368d864d4..6b3e4f31e 100644
--- a/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx
+++ b/src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx
@@ -8,6 +8,11 @@ import {
 import { createPortal } from 'react-dom';
 
 import { ROLE_TEMPLATE_CHARACTERS } from '../../data/characterPresets';
+import {
+  canUseNativeHostCapability,
+  importHostImageFile,
+} from '../../services/host-bridge/hostBridge';
+import { puzzleReferenceImageDataUrlToFile } from '../../services/puzzleReferenceImage';
 import {
   AnimationState,
   type Character,
@@ -25,11 +30,6 @@ import { useAuthUi } from '../auth/AuthUiContext';
 import { CharacterAnimator } from '../CharacterAnimator';
 import { PlatformActionButton } from '../common/PlatformActionButton';
 import { PlatformMudPointConfirmDialog } from '../common/PlatformMudPointConfirmDialog';
-import {
-  canUseNativeHostCapability,
-  importHostImageFile,
-} from '../../services/host-bridge/hostBridge';
-import { puzzleReferenceImageDataUrlToFile } from '../../services/puzzleReferenceImage';
 import {
   CORE_ACTIONS,
   type CustomWorldAiActionConfig,
diff --git a/src/components/rpg-creation-asset-studio/useRoleAnimationWorkflow.ts b/src/components/rpg-creation-asset-studio/useRoleAnimationWorkflow.ts
index fa5cd94c4..ce3fc547e 100644
--- a/src/components/rpg-creation-asset-studio/useRoleAnimationWorkflow.ts
+++ b/src/components/rpg-creation-asset-studio/useRoleAnimationWorkflow.ts
@@ -1,11 +1,10 @@
-import { generateCharacterAnimationDraft } from '../asset-studio/characterAssetWorkflowPersistence';
 import type { CharacterAnimationGenerationPayload } from '../asset-studio/characterAssetWorkflowPersistence';
-
-import { roleAssetStudioPublishClient } from './roleAssetStudioPublishClient';
+import { generateCharacterAnimationDraft } from '../asset-studio/characterAssetWorkflowPersistence';
 import type {
   CustomWorldAiActionConfig,
   EditableCustomWorldRole,
 } from './roleAssetStudioModel';
+import { roleAssetStudioPublishClient } from './roleAssetStudioPublishClient';
 
 export function useRoleAnimationWorkflow() {
   const generateAnimationClipForRole = async (params: {
diff --git a/src/components/rpg-creation-asset-studio/useRoleVisualCandidateWorkflow.ts b/src/components/rpg-creation-asset-studio/useRoleVisualCandidateWorkflow.ts
index 576c6c5e2..6c45ee798 100644
--- a/src/components/rpg-creation-asset-studio/useRoleVisualCandidateWorkflow.ts
+++ b/src/components/rpg-creation-asset-studio/useRoleVisualCandidateWorkflow.ts
@@ -1,8 +1,7 @@
-import { generateCharacterVisualCandidates } from '../asset-studio/characterAssetWorkflowPersistence';
 import type { CharacterVisualDraft } from '../asset-studio/characterAssetWorkflowPersistence';
-
-import { roleAssetStudioPublishClient } from './roleAssetStudioPublishClient';
+import { generateCharacterVisualCandidates } from '../asset-studio/characterAssetWorkflowPersistence';
 import type { EditableCustomWorldRole } from './roleAssetStudioModel';
+import { roleAssetStudioPublishClient } from './roleAssetStudioPublishClient';
 
 export function useRoleVisualCandidateWorkflow() {
   const generateVisualCandidatesForRole = async (params: {
diff --git a/src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx b/src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx
index e48d8fe46..8c323fa73 100644
--- a/src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx
+++ b/src/components/rpg-creation-editor/RpgCreationEntityEditorModal.tsx
@@ -1,9 +1,9 @@
 import type { ComponentProps } from 'react';
 
-import RpgCreationEntityEditorModalImpl from './RpgCreationEntityEditorModalImpl';
 import type {
   RpgCreationEditorTarget,
 } from './RpgCreationEntityEditorModalImpl';
+import RpgCreationEntityEditorModalImpl from './RpgCreationEntityEditorModalImpl';
 
 /**
  * 工作包 C 完成后，编辑器 façade 已直接桥接 RPG 创作目录下的目标分发壳层。
diff --git a/src/components/rpg-creation-editor/RpgCreationEntityEditorModalImpl.tsx b/src/components/rpg-creation-editor/RpgCreationEntityEditorModalImpl.tsx
index be0147d72..3c16825f5 100644
--- a/src/components/rpg-creation-editor/RpgCreationEntityEditorModalImpl.tsx
+++ b/src/components/rpg-creation-editor/RpgCreationEntityEditorModalImpl.tsx
@@ -1,5 +1,4 @@
 import type { CustomWorldProfile } from '../../types';
-
 import CampSceneEditor from './CustomWorldCampEditorSection';
 import WorldCoverEditor from './CustomWorldCoverEditorSection';
 import WorldFoundationEditor from './CustomWorldFoundationEditorSection';
diff --git a/src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx b/src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx
index 3c4935c9a..9dde7aa10 100644
--- a/src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx
+++ b/src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx
@@ -56,16 +56,16 @@ import {
   getCustomWorldFoundationAnchorContent,
   parseFoundationTagText,
 } from '../../services/customWorldFoundationEntries';
-import {
-  rpgCreationAssetClient,
-  type RpgCreationHistoryAsset,
-  type RpgCreationHistoryAssetKind,
-} from '../../services/rpg-creation/rpgCreationAssetClient';
 import {
   canUseNativeHostCapability,
   importHostImageFile,
 } from '../../services/host-bridge/hostBridge';
 import { puzzleReferenceImageDataUrlToFile } from '../../services/puzzleReferenceImage';
+import {
+  rpgCreationAssetClient,
+  type RpgCreationHistoryAsset,
+  type RpgCreationHistoryAssetKind,
+} from '../../services/rpg-creation/rpgCreationAssetClient';
 import { createEmptyStoryEngineMemoryState } from '../../services/storyEngine/visibilityEngine';
 import {
   AnimationState,
diff --git a/src/components/rpg-creation-editor/rpgCreationResultFormMapper.ts b/src/components/rpg-creation-editor/rpgCreationResultFormMapper.ts
index 3faa29907..43609cb97 100644
--- a/src/components/rpg-creation-editor/rpgCreationResultFormMapper.ts
+++ b/src/components/rpg-creation-editor/rpgCreationResultFormMapper.ts
@@ -1,13 +1,13 @@
-import type {
-  RpgCreationEditorTarget,
-  RpgCreationEntityEditorModalProps,
-} from './RpgCreationEntityEditorModalImpl';
 import type {
   CustomWorldLandmark,
   CustomWorldNpc,
   CustomWorldPlayableNpc,
   CustomWorldProfile,
 } from '../../types';
+import type {
+  RpgCreationEditorTarget,
+  RpgCreationEntityEditorModalProps,
+} from './RpgCreationEntityEditorModalImpl';
 
 /**
  * 工作包 C 第一轮先把编辑器目标分发需要的 profile 变更收口到 mapper。
diff --git a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
index 7ee66d037..bcc73ac49 100644
--- a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
+++ b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
@@ -9,10 +9,6 @@ import type { PublicUserSummary } from '../../../packages/shared/src/contracts/a
 import type { BarkBattleWorkSummary } from '../../../packages/shared/src/contracts/barkBattle';
 import type { BigFishWorkSummary } from '../../../packages/shared/src/contracts/bigFishWorkSummary';
 import type { CreativeAgentSessionSnapshot } from '../../../packages/shared/src/contracts/creativeAgent';
-import type {
-  HostBridgeCapability,
-  HostBridgeRequest,
-} from '../../../packages/shared/src/contracts/hostBridge';
 import type {
   CustomWorldAgentSessionSnapshot,
   CustomWorldWorkSummary,
@@ -21,6 +17,10 @@ import type {
   BabyObjectMatchDraft,
   CreateBabyObjectMatchDraftRequest,
 } from '../../../packages/shared/src/contracts/edutainmentBabyObject';
+import type {
+  HostBridgeCapability,
+  HostBridgeRequest,
+} from '../../../packages/shared/src/contracts/hostBridge';
 import type {
   JumpHopRuntimeRunSnapshotResponse,
   JumpHopWorkDetailResponse,
diff --git a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
index d9873356c..699cdfe97 100644
--- a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
@@ -4465,6 +4465,98 @@ test('logged in mobile recommend page exposes the shared wallet details and rech
   expect(within(rechargeDialog).queryByText('会员月卡')).toBeNull();
 });
 
+test('the latest recharge center read wins when wallet and recharge overlap', async () => {
+  const user = userEvent.setup();
+  mockNarrowMobileLayout();
+  let resolveWalletRead!: (
+    center: ProfileRechargeCenterResponse,
+  ) => void;
+  let resolveRechargeRead!: (
+    center: ProfileRechargeCenterResponse,
+  ) => void;
+  const walletReadPromise = new Promise<ProfileRechargeCenterResponse>(
+    (resolve) => {
+      resolveWalletRead = resolve;
+    },
+  );
+  const rechargeReadPromise = new Promise<ProfileRechargeCenterResponse>(
+    (resolve) => {
+      resolveRechargeRead = resolve;
+    },
+  );
+  mockGetRpgProfileRechargeCenter
+    .mockReturnValueOnce(walletReadPromise)
+    .mockReturnValueOnce(rechargeReadPromise);
+
+  const { container } = render(
+    <ProfileHomeViewHarness
+      activeTab="home"
+      profileDashboardOverrides={{ walletBalance: 207 }}
+    />,
+  );
+  const walletLayer = container.querySelector(
+    '.platform-mobile-recommend-wallet-entry',
+  );
+  expect(walletLayer).toBeTruthy();
+
+  await user.click(
+    within(walletLayer as HTMLElement).getByRole('button', {
+      name: '泥点 207',
+    }),
+  );
+  const rechargeButtons = within(walletLayer as HTMLElement).getAllByRole(
+    'button',
+    { name: '充值' },
+  );
+  await user.click(rechargeButtons[0]!);
+
+  expect(mockGetRpgProfileRechargeCenter).toHaveBeenCalledTimes(2);
+
+  resolveRechargeRead({
+    walletBalance: 207,
+    mudPointBalance: {
+      totalPoints: 207,
+      permanentPoints: 187,
+      limitedPoints: 0,
+      limitedExpiresAt: null,
+      dailyFreePoints: 20,
+      dailyFreeResetPoints: 20,
+      dailyFreeResetsAt: '2026-07-20T16:00:00Z',
+    },
+    membership: buildNormalMembership(),
+    pointProducts: [buildPointProduct()],
+    membershipProducts: [],
+    benefits: [],
+    latestOrder: null,
+    hasPointsRecharged: false,
+  });
+
+  expect(await screen.findByText('购买更多泥点')).toBeTruthy();
+  expect(screen.getByText('当前余额 207 泥点')).toBeTruthy();
+
+  resolveWalletRead({
+    walletBalance: 0,
+    mudPointBalance: {
+      totalPoints: 0,
+      permanentPoints: 0,
+      limitedPoints: 0,
+      limitedExpiresAt: null,
+      dailyFreePoints: 0,
+      dailyFreeResetPoints: 20,
+      dailyFreeResetsAt: '2026-07-20T16:00:00Z',
+    },
+    membership: buildNormalMembership(),
+    pointProducts: [],
+    membershipProducts: [],
+    benefits: [],
+    latestOrder: null,
+    hasPointsRecharged: false,
+  });
+
+  await act(async () => undefined);
+  expect(screen.getByText('当前余额 207 泥点')).toBeTruthy();
+});
+
 test('mobile discover search submits public work code', async () => {
   const user = userEvent.setup();
   const onSearchPublicCode = vi.fn();
diff --git a/src/components/rpg-entry/rpgEntryTypes.ts b/src/components/rpg-entry/rpgEntryTypes.ts
index da76f6fff..5d4c71fd5 100644
--- a/src/components/rpg-entry/rpgEntryTypes.ts
+++ b/src/components/rpg-entry/rpgEntryTypes.ts
@@ -2,8 +2,8 @@ export type {
   CustomWorldAutoSaveState,
   CustomWorldGenerationViewSource,
   CustomWorldResultViewSource,
-  PlatformEntryFlowShellProps as RpgEntryFlowShellProps,
   PlatformEntryFlowShellProps as RpgCreationShellProps,
+  PlatformEntryFlowShellProps as RpgEntryFlowShellProps,
   SelectionStage,
   SyncedAgentDraftResult,
 } from '../platform-entry/platformEntryTypes';
diff --git a/src/components/rpg-entry/useRpgCreationEnterWorld.ts b/src/components/rpg-entry/useRpgCreationEnterWorld.ts
index b05b079f0..ecf25d7eb 100644
--- a/src/components/rpg-entry/useRpgCreationEnterWorld.ts
+++ b/src/components/rpg-entry/useRpgCreationEnterWorld.ts
@@ -1,10 +1,10 @@
 import { useCallback } from 'react';
 
-import type { RpgCreationResultView } from '../../../packages/shared/src/contracts/rpgCreationResultView';
 import type { CustomWorldAgentSessionSnapshot } from '../../../packages/shared/src/contracts/customWorldAgent';
-import type { CustomWorldRuntimeLaunchOptions } from '../platform-entry/platformEntryTypes';
+import type { RpgCreationResultView } from '../../../packages/shared/src/contracts/rpgCreationResultView';
 import { rpgCreationPreviewAdapter } from '../../services/rpg-creation/rpgCreationPreviewAdapter';
 import type { CustomWorldProfile } from '../../types';
+import type { CustomWorldRuntimeLaunchOptions } from '../platform-entry/platformEntryTypes';
 import { chooseMoreCompleteCustomWorldProfile } from './rpgProfileCompleteness';
 
 type UseRpgCreationEnterWorldParams = {
diff --git a/src/components/rpg-entry/useRpgEntryBootstrap.test.tsx b/src/components/rpg-entry/useRpgEntryBootstrap.test.tsx
index 3d3a5525f..03081f90a 100644
--- a/src/components/rpg-entry/useRpgEntryBootstrap.test.tsx
+++ b/src/components/rpg-entry/useRpgEntryBootstrap.test.tsx
@@ -4,13 +4,13 @@ import { renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, expect, test, vi } from 'vitest';
 
 import type { AuthUser } from '../../services/authService';
+import { listRpgCreationWorks } from '../../services/rpg-creation/index';
 import {
   listRpgEntryWorldGallery,
   listRpgEntryWorldLibrary,
   listRpgProfileBrowseHistory,
   listRpgProfileSaveArchives,
 } from '../../services/rpg-entry';
-import { listRpgCreationWorks } from '../../services/rpg-creation/index';
 import { useRpgEntryBootstrap } from './useRpgEntryBootstrap';
 
 vi.mock('../../services/rpg-entry', () => ({
diff --git a/src/components/rpg-runtime-panels/RpgAdventurePanel.tsx b/src/components/rpg-runtime-panels/RpgAdventurePanel.tsx
index 595a4cbf4..9a406bc4b 100644
--- a/src/components/rpg-runtime-panels/RpgAdventurePanel.tsx
+++ b/src/components/rpg-runtime-panels/RpgAdventurePanel.tsx
@@ -50,8 +50,8 @@ import {
   TAB_ICONS,
   UI_CHROME,
 } from '../../uiAssets';
-import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformPillBadge } from '../common/PlatformPillBadge';
 import { PlatformQuantityBadge } from '../common/PlatformQuantityBadge';
 import { PlatformSubpanel } from '../common/PlatformSubpanel';
diff --git a/src/components/rpg-runtime-shell/RpgRuntimeShell.test.tsx b/src/components/rpg-runtime-shell/RpgRuntimeShell.test.tsx
index 8fb1a421b..41ed4659f 100644
--- a/src/components/rpg-runtime-shell/RpgRuntimeShell.test.tsx
+++ b/src/components/rpg-runtime-shell/RpgRuntimeShell.test.tsx
@@ -6,9 +6,9 @@ import { beforeEach, expect, test, vi } from 'vitest';
 
 import {
   AnimationState,
-  WorldType,
   type GameState,
   type StoryMoment,
+  WorldType,
 } from '../../types';
 import { RpgRuntimeShell } from './RpgRuntimeShell';
 import type { RpgRuntimeShellProps } from './types';
diff --git a/src/components/rpg-runtime-shell/index.ts b/src/components/rpg-runtime-shell/index.ts
index 84f64ee2f..77ee6bd00 100644
--- a/src/components/rpg-runtime-shell/index.ts
+++ b/src/components/rpg-runtime-shell/index.ts
@@ -2,6 +2,10 @@ export {
   RpgRuntimeCanvasStage,
   type RpgRuntimeCanvasStageProps,
 } from './RpgRuntimeCanvasStage';
+export {
+  ModalLoadingFallback,
+  PanelLoadingFallback,
+} from './rpgRuntimeLoaders';
 export {
   RpgRuntimeOverlayHost,
   type RpgRuntimeOverlayHostProps,
@@ -18,19 +22,15 @@ export {
   type RpgAdventureStatistics,
   type RpgRuntimeDialogueIndicator,
 } from './types';
-export {
-  ModalLoadingFallback,
-  PanelLoadingFallback,
-} from './rpgRuntimeLoaders';
-export {
-  useRpgRuntimeShellViewModel,
-  type RpgRuntimeShellViewModelResult,
-  type UseRpgRuntimeShellViewModelParams,
-} from './useRpgRuntimeShellViewModel';
 export { useRpgRuntimeOverlayState } from './useRpgRuntimeOverlayState';
+export {
+  type RpgRuntimeShellViewModelResult,
+  useRpgRuntimeShellViewModel,
+  type UseRpgRuntimeShellViewModelParams,
+} from './useRpgRuntimeShellViewModel';
 export {
   SCENE_TRANSITION_FUNCTION_MODES,
-  useRpgSceneTransitionModel,
   type SceneTransitionPhase,
   type SceneTransitionTriggerMode,
+  useRpgSceneTransitionModel,
 } from './useRpgSceneTransitionModel';
diff --git a/src/components/unified-creation/UnifiedCreationWorkspace.test.tsx b/src/components/unified-creation/UnifiedCreationWorkspace.test.tsx
index 29e0e1cf3..f69ecc8a8 100644
--- a/src/components/unified-creation/UnifiedCreationWorkspace.test.tsx
+++ b/src/components/unified-creation/UnifiedCreationWorkspace.test.tsx
@@ -3,8 +3,8 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, test, vi } from 'vitest';
 
-import { UnifiedCreationWorkspace } from './UnifiedCreationWorkspace';
 import { getUnifiedCreationSpec } from './unifiedCreationSpecs';
+import { UnifiedCreationWorkspace } from './UnifiedCreationWorkspace';
 
 vi.mock('./workspaces/PuzzleCreationWorkspace', () => ({
   PuzzleCreationWorkspace: ({
diff --git a/src/components/unified-creation/UnifiedCreationWorkspace.tsx b/src/components/unified-creation/UnifiedCreationWorkspace.tsx
index 697fafbd0..c0d5ba0e5 100644
--- a/src/components/unified-creation/UnifiedCreationWorkspace.tsx
+++ b/src/components/unified-creation/UnifiedCreationWorkspace.tsx
@@ -2,9 +2,9 @@ import type { ComponentProps } from 'react';
 
 import { UnifiedCreationPage } from './UnifiedCreationPage';
 import type { UnifiedCreationSpec } from './unifiedCreationSpecs';
+import { JumpHopCreationWorkspace } from './workspaces/JumpHopCreationWorkspace';
 import { Match3DCreationWorkspace } from './workspaces/Match3DCreationWorkspace';
 import { PuzzleCreationWorkspace } from './workspaces/PuzzleCreationWorkspace';
-import { JumpHopCreationWorkspace } from './workspaces/JumpHopCreationWorkspace';
 import { WoodenFishCreationWorkspace } from './workspaces/WoodenFishCreationWorkspace';
 
 type PuzzleCreationWorkspaceProps = ComponentProps<
diff --git a/src/components/unified-creation/unifiedCreationSpecs.ts b/src/components/unified-creation/unifiedCreationSpecs.ts
index 1c5f30e21..0468d81da 100644
--- a/src/components/unified-creation/unifiedCreationSpecs.ts
+++ b/src/components/unified-creation/unifiedCreationSpecs.ts
@@ -1,8 +1,8 @@
+import type { PlatformCreationTypeId } from '../../../packages/shared/src/contracts/playTypes';
 import type {
   CreationEntryTypeConfig,
   UnifiedCreationSpec,
 } from '../../services/creationEntryConfigService';
-import type { PlatformCreationTypeId } from '../../../packages/shared/src/contracts/playTypes';
 
 export const UNIFIED_CREATION_PLAY_IDS = [
   'rpg',
diff --git a/src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx b/src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx
index c42685795..5dac6b55b 100644
--- a/src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx
+++ b/src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx
@@ -17,7 +17,6 @@ import {
   CreativeImageInputPanel,
   type CreativeImageInputReferenceImage,
 } from '../../common/CreativeImageInputPanel';
-import { PlatformActionButton } from '../../common/PlatformActionButton';
 import { PlatformBackActionButton } from '../../common/PlatformBackActionButton';
 import { PlatformMudPointConfirmDialog } from '../../common/PlatformMudPointConfirmDialog';
 import { PlatformPillBadge } from '../../common/PlatformPillBadge';
diff --git a/src/components/visual-novel-result/VisualNovelResultView.tsx b/src/components/visual-novel-result/VisualNovelResultView.tsx
index 673c89881..6962e5790 100644
--- a/src/components/visual-novel-result/VisualNovelResultView.tsx
+++ b/src/components/visual-novel-result/VisualNovelResultView.tsx
@@ -46,8 +46,8 @@ import {
 } from '../../services/visual-novel-creation';
 import { useAuthUi } from '../auth/AuthUiContext';
 import { PlatformActionButton } from '../common/PlatformActionButton';
-import { PlatformBackActionButton } from '../common/PlatformBackActionButton';
 import { PlatformAssetPickerGrid } from '../common/PlatformAssetPickerCard';
+import { PlatformBackActionButton } from '../common/PlatformBackActionButton';
 import { PlatformEmptyState } from '../common/PlatformEmptyState';
 import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
 import { PlatformIconButton } from '../common/PlatformIconButton';
@@ -56,12 +56,12 @@ import { PlatformModalCloseButton } from '../common/PlatformModalCloseButton';
 import { PlatformSegmentedTabs } from '../common/PlatformSegmentedTabs';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformSubpanel } from '../common/PlatformSubpanel';
-import { PlatformToolModalShell } from '../common/PlatformToolModalShell';
 import {
   PlatformSelectField,
   PlatformTextField,
 } from '../common/PlatformTextField';
 import { PlatformToggleRow } from '../common/PlatformToggleRow';
+import { PlatformToolModalShell } from '../common/PlatformToolModalShell';
 import { visualNovelLocalPreviewDraft } from '../visual-novel-runtime/visualNovelLocalPreviewData';
 
 type VisualNovelResultViewProps = {
diff --git a/src/data/customWorldLibrary.ts b/src/data/customWorldLibrary.ts
index 3b4971a73..cd7f55b1d 100644
--- a/src/data/customWorldLibrary.ts
+++ b/src/data/customWorldLibrary.ts
@@ -20,6 +20,7 @@ import {
   CharacterBackstoryChapter,
   CharacterBackstoryRevealConfig,
   CustomWorldAnchorPack,
+  CustomWorldCoverProfile,
   CustomWorldItem,
   CustomWorldLandmark,
   CustomWorldNpc,
@@ -28,7 +29,6 @@ import {
   CustomWorldNpcVisualGearType,
   CustomWorldNpcVisualRace,
   CustomWorldOpeningCgProfile,
-  CustomWorldCoverProfile,
   CustomWorldPlayableNpc,
   CustomWorldProfile,
   CustomWorldRoleInitialItem,
diff --git a/src/data/customWorldNpcMonsters.ts b/src/data/customWorldNpcMonsters.ts
index 897002663..c21f4896a 100644
--- a/src/data/customWorldNpcMonsters.ts
+++ b/src/data/customWorldNpcMonsters.ts
@@ -2,13 +2,13 @@ import {
   collectCreatureArchetypeSignals,
   resolveCreatureArchetypeForSource,
 } from '../services/customWorldReferenceSignals';
+import { resolveCustomWorldCompatibilityTemplateWorldType } from '../services/customWorldTheme';
 import {
   type CustomWorldNpc,
   type CustomWorldPlayableNpc,
   type CustomWorldProfile,
   WorldType,
 } from '../types';
-import { resolveCustomWorldCompatibilityTemplateWorldType } from '../services/customWorldTheme';
 import {
   getMonsterPresetsByWorld,
   type HostileNpcPreset,
diff --git a/src/data/customWorldVisuals.ts b/src/data/customWorldVisuals.ts
index d81c304c2..420271c31 100644
--- a/src/data/customWorldVisuals.ts
+++ b/src/data/customWorldVisuals.ts
@@ -4,13 +4,13 @@ import {
   resolveSceneBucketForLandmark,
 } from '../services/customWorldReferenceSignals';
 import { detectCustomWorldThemeMode } from '../services/customWorldTheme';
+import { resolveCustomWorldCompatibilityTemplateWorldType } from '../services/customWorldTheme';
 import {
   type CustomWorldLandmark,
   type CustomWorldProfile,
   type WorldTemplateType,
   WorldType,
 } from '../types';
-import { resolveCustomWorldCompatibilityTemplateWorldType } from '../services/customWorldTheme';
 
 const CUSTOM_WORLD_NPC_IMAGE_POOL = [
   '/character/Sword%20Princess/Original/Hero/idle/Idle01.png',
diff --git a/src/data/hostileNpcPresets.test.ts b/src/data/hostileNpcPresets.test.ts
index 13b36ca06..ac5299f8d 100644
--- a/src/data/hostileNpcPresets.test.ts
+++ b/src/data/hostileNpcPresets.test.ts
@@ -69,9 +69,11 @@ function createGameState(): GameState {
 describe('hostileNpcPresets', () => {
   it('combines preset loot with runtime semantic drops', async () => {
     const randomSpy = vi.spyOn(Math, 'random').mockReturnValue(0);
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const networkError = new TypeError('network disabled in test');
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockRejectedValue(new TypeError('network disabled in test')),
+      vi.fn().mockRejectedValue(networkError),
     );
 
     try {
@@ -89,9 +91,18 @@ describe('hostileNpcPresets', () => {
       expect(
         loot.find(item => item.id === 'monster-loot:bone-dust')?.runtimeMetadata?.storyFingerprint,
       ).toBeTruthy();
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[HostileNpcPresets] preset loot narrative fallback',
+        networkError,
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[RuntimeItemDirector] falling back to deterministic item intent',
+        networkError,
+      );
     } finally {
       vi.unstubAllGlobals();
       randomSpy.mockRestore();
+      warnSpy.mockRestore();
     }
   });
 });
diff --git a/src/data/itemCatalog.ts b/src/data/itemCatalog.ts
index f4e32fdaa..e0e56a04f 100644
--- a/src/data/itemCatalog.ts
+++ b/src/data/itemCatalog.ts
@@ -1,3 +1,6 @@
+import {
+  EDITOR_ITEM_CATALOG_API_PATH,
+} from '../editor/shared/editorApiClient';
 import type {
   InventoryItem,
   ItemCatalogEntry,
@@ -5,9 +8,6 @@ import type {
   ItemRarity,
   WorldType,
 } from '../types';
-import {
-  EDITOR_ITEM_CATALOG_API_PATH,
-} from '../editor/shared/editorApiClient';
 import { buildDesignedItemMetadata } from './itemDesign';
 
 export { EDITOR_ITEM_CATALOG_API_PATH as ITEM_CATALOG_API_PATH };
diff --git a/src/data/stateFunctions.test.ts b/src/data/stateFunctions.test.ts
index 3a4ea5f6e..0ec3e657a 100644
--- a/src/data/stateFunctions.test.ts
+++ b/src/data/stateFunctions.test.ts
@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
+import type { SceneHostileNpc, StoryOption } from '../types';
+import { AnimationState, WorldType } from '../types';
+import {
+  getScenePresetsByWorld,
+  getTravelScenePreset,
+  getWorldCampScenePreset,
+} from './scenePresets';
+import type { FunctionAvailabilityContext } from './stateFunctions';
 import {
   buildStateFunctionDefinitions,
   getExecutableFunctions,
@@ -7,14 +15,6 @@ import {
   resolveFunctionOption,
   sortStoryOptionsByPriority,
 } from './stateFunctions';
-import {
-  getScenePresetsByWorld,
-  getTravelScenePreset,
-  getWorldCampScenePreset,
-} from './scenePresets';
-import type { FunctionAvailabilityContext } from './stateFunctions';
-import type { SceneHostileNpc, StoryOption } from '../types';
-import { AnimationState, WorldType } from '../types';
 
 function createMonster(
   overrides: Partial<SceneHostileNpc> = {},
diff --git a/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx b/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
index 20918be75..69fe0d3ef 100644
--- a/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
+++ b/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
@@ -3,8 +3,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type {
   BarkBattleDerivedMetrics,
   BarkBattlePublishedConfig,
-  BarkBattleRuntimeConfig,
   BarkBattleRunStartResponse,
+  BarkBattleRuntimeConfig,
   BarkBattleServerResult,
 } from '../../../../packages/shared/src/contracts/barkBattle';
 import {
diff --git a/src/hooks/rpg-runtime-story/index.ts b/src/hooks/rpg-runtime-story/index.ts
index 321ac8c70..8e74f03a2 100644
--- a/src/hooks/rpg-runtime-story/index.ts
+++ b/src/hooks/rpg-runtime-story/index.ts
@@ -1,23 +1,22 @@
 export {
   loadRpgRuntimeOptionCatalog,
-  resolveRpgRuntimeChoice,
-  resumeRpgRuntimeStory,
   type LoadRpgRuntimeOptionCatalogParams,
+  resolveRpgRuntimeChoice,
   type ResolveRpgRuntimeChoiceParams,
+  resumeRpgRuntimeStory,
 } from './rpgRuntimeStoryGateway';
 export {
-  useRpgRuntimeInteractionFlow,
   createRpgRuntimeInteractionUiResetter,
   type RpgRuntimeInteractionFlowResult,
+  useRpgRuntimeInteractionFlow,
   type UseRpgRuntimeInteractionFlowParams,
 } from './useRpgRuntimeInteractionFlow';
 export {
-  useRpgRuntimeNpcInteraction,
   type RpgRuntimeNpcInteractionResult,
+  useRpgRuntimeNpcInteraction,
   type UseRpgRuntimeNpcInteractionParams,
 } from './useRpgRuntimeNpcInteraction';
 export {
-  useRpgRuntimeStory,
   type BattleRewardSummary,
   type BattleRewardUi,
   type CharacterChatModalState,
@@ -32,21 +31,22 @@ export {
   type RpgRuntimeStoryResult,
   type StoryGenerationNpcUi,
   type TradeModalState,
+  useRpgRuntimeStory,
   type UseRpgRuntimeStoryParams,
 } from './useRpgRuntimeStory';
 export {
-  useRpgRuntimeStoryController,
   type RpgRuntimeStoryControllerResult,
+  useRpgRuntimeStoryController,
   type UseRpgRuntimeStoryControllerParams,
 } from './useRpgRuntimeStoryController';
 export {
-  useRpgRuntimeStoryFlow,
   type RpgRuntimeStoryFlowResult,
+  useRpgRuntimeStoryFlow,
   type UseRpgRuntimeStoryFlowParams,
 } from './useRpgRuntimeStoryFlow';
 export {
   createRpgRuntimeStoryUiResetter,
-  useRpgRuntimeStoryState,
   type RpgRuntimeStoryStateResult,
+  useRpgRuntimeStoryState,
   type UseRpgRuntimeStoryStateParams,
 } from './useRpgRuntimeStoryState';
diff --git a/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.test.ts b/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.test.ts
index bd84f35fe..e5bfe5f56 100644
--- a/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.test.ts
+++ b/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.test.ts
@@ -29,10 +29,10 @@ vi.mock('../../services/rpg-runtime/rpgRuntimeStoryClient', async () => {
   };
 });
 
+import type { StoryRuntimeProjectionResponse } from '../../../packages/shared/src/contracts/story';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
 import type { GameState, StoryMoment, StoryOption } from '../../types';
 import { WorldType } from '../../types';
-import type { StoryRuntimeProjectionResponse } from '../../../packages/shared/src/contracts/story';
 import {
   loadServerRuntimeOptionCatalog,
   resolveServerRuntimeChoice,
diff --git a/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.ts b/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.ts
index c7fe01b87..d25218b6e 100644
--- a/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.ts
+++ b/src/hooks/rpg-runtime-story/runtimeStoryCoordinator.ts
@@ -1,7 +1,7 @@
 export {
+  type LoadRpgRuntimeOptionCatalogParams,
   loadRpgRuntimeOptionCatalog as loadServerRuntimeOptionCatalog,
+  type ResolveRpgRuntimeChoiceParams,
   resolveRpgRuntimeChoice as resolveServerRuntimeChoice,
   resumeRpgRuntimeStory as resumeServerRuntimeStory,
-  type LoadRpgRuntimeOptionCatalogParams,
-  type ResolveRpgRuntimeChoiceParams,
 } from './rpgRuntimeStoryGateway';
diff --git a/src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts b/src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts
index aa84420c3..77e45f50f 100644
--- a/src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts
+++ b/src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts
@@ -1,5 +1,6 @@
 import type { Dispatch, SetStateAction } from 'react';
 
+import type { StoryGenerationContext } from '../../services/aiTypes';
 import type {
   Character,
   Encounter,
@@ -9,9 +10,8 @@ import type {
 } from '../../types';
 import type { EscapePlaybackSync as ResolvedChoicePlaybackSync } from '../combat/escapeFlow';
 import type { ResolvedChoiceState } from '../combat/resolvedChoice';
-import type { BattleRewardSummary } from './uiTypes';
 import type { StoryRuntimeSupport } from './storyRuntimeSupport';
-import type { StoryGenerationContext } from '../../services/aiTypes';
+import type { BattleRewardSummary } from './uiTypes';
 
 export type ChoiceRuntimeController = {
   buildStoryContextFromState: (
diff --git a/src/hooks/rpg-runtime-story/storyGenerationState.ts b/src/hooks/rpg-runtime-story/storyGenerationState.ts
index fdba30983..dcd85796a 100644
--- a/src/hooks/rpg-runtime-story/storyGenerationState.ts
+++ b/src/hooks/rpg-runtime-story/storyGenerationState.ts
@@ -7,10 +7,10 @@
   NPC_TRADE_FUNCTION,
   shouldNpcRecruitOpenModal,
 } from '../../data/functionCatalog';
+import { MAX_COMPANIONS } from '../../data/npcInteractions';
 import {
   applyQuestProgressFromSceneReached,
 } from '../../data/questFlow';
-import { MAX_COMPANIONS } from '../../data/npcInteractions';
 import { incrementGameRuntimeStats } from '../../data/runtimeStats';
 import { ensureSceneEncounterPreview } from '../../data/sceneEncounterPreviews';
 import { getScenePresetById } from '../../data/scenePresets';
diff --git a/src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts b/src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts
index 47f9e58e1..70840ad36 100644
--- a/src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts
+++ b/src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts
@@ -3,7 +3,6 @@
 import type { StoryGenerationContext } from '../../services/aiTypes';
 import type {
   Character,
-  Encounter,
   GameState,
   StoryMoment,
   StoryOption,
diff --git a/src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts b/src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts
index 1a761da23..43f58d770 100644
--- a/src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts
+++ b/src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts
@@ -1,6 +1,6 @@
-import { useCallback, type Dispatch, type SetStateAction } from 'react';
+import { type Dispatch, type SetStateAction,useCallback } from 'react';
 
-import type { StoryMoment, GameState, Character } from '../../types';
+import type { Character,GameState, StoryMoment } from '../../types';
 import type { CommitGeneratedState } from '../generatedState';
 import { createStorySessionActions } from './sessionActions';
 
diff --git a/src/hooks/rpg-runtime-story/useStoryChoiceCoordinator.ts b/src/hooks/rpg-runtime-story/useStoryChoiceCoordinator.ts
index 8d72b5904..005033e4c 100644
--- a/src/hooks/rpg-runtime-story/useStoryChoiceCoordinator.ts
+++ b/src/hooks/rpg-runtime-story/useStoryChoiceCoordinator.ts
@@ -1,12 +1,5 @@
 import { useCallback, useState } from 'react';
 
-import { createStoryChoiceActions } from './choiceActions';
-import {
-  createStoryChoiceCoordinatorConfig,
-  type ChoiceRuntimeController,
-  type ChoiceRuntimeSupport,
-} from './storyChoiceCoordinator';
-import type { BattleRewardSummary } from './uiTypes';
 import type {
   Character,
   Encounter,
@@ -14,8 +7,15 @@ import type {
   StoryMoment,
   StoryOption,
 } from '../../types';
-import type { ResolvedChoiceState } from '../combat/resolvedChoice';
 import type { EscapePlaybackSync as ResolvedChoicePlaybackSync } from '../combat/escapeFlow';
+import type { ResolvedChoiceState } from '../combat/resolvedChoice';
+import { createStoryChoiceActions } from './choiceActions';
+import {
+  type ChoiceRuntimeController,
+  type ChoiceRuntimeSupport,
+  createStoryChoiceCoordinatorConfig,
+} from './storyChoiceCoordinator';
+import type { BattleRewardSummary } from './uiTypes';
 
 type StoryChoiceCoordinatorParams = {
   gameState: GameState;
diff --git a/src/hooks/rpg-session/index.ts b/src/hooks/rpg-session/index.ts
index f64abe236..d5fbcbccb 100644
--- a/src/hooks/rpg-session/index.ts
+++ b/src/hooks/rpg-session/index.ts
@@ -1,12 +1,12 @@
-export { type RpgSessionBootstrapResult, useRpgSessionBootstrap } from './useRpgSessionBootstrap';
 export type { BottomTab } from './rpgSessionTypes';
+export type { BottomTab as RpgBottomTab } from './rpgSessionTypes';
 export {
   type RpgRuntimeSessionResult,
   useRpgRuntimeSession,
 } from './useRpgRuntimeSession';
+export { type RpgSessionBootstrapResult, useRpgSessionBootstrap } from './useRpgSessionBootstrap';
 export {
   type RpgSessionPersistenceResult,
-  type UseRpgSessionPersistenceParams,
   useRpgSessionPersistence,
+  type UseRpgSessionPersistenceParams,
 } from './useRpgSessionPersistence';
-export type { BottomTab as RpgBottomTab } from './rpgSessionTypes';
diff --git a/src/hooks/rpg-session/useRpgRuntimeSession.ts b/src/hooks/rpg-session/useRpgRuntimeSession.ts
index 5970c34da..dae1b1d9b 100644
--- a/src/hooks/rpg-session/useRpgRuntimeSession.ts
+++ b/src/hooks/rpg-session/useRpgRuntimeSession.ts
@@ -10,10 +10,10 @@ import {
 } from '../../data/companionRoster';
 import { syncGameStatePlayTime } from '../../data/runtimeStats';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
+import { useRpgRuntimeStory } from '../rpg-runtime-story/useRpgRuntimeStory';
 import { useBackgroundMusic } from '../useBackgroundMusic';
 import { useCombatFlow } from '../useCombatFlow';
 import { useNpcInteractionFlow } from '../useNpcInteractionFlow';
-import { useRpgRuntimeStory } from '../rpg-runtime-story/useRpgRuntimeStory';
 import { useRpgSessionBootstrap } from './useRpgSessionBootstrap';
 import { useRpgSessionPersistence } from './useRpgSessionPersistence';
 
diff --git a/src/hooks/rpg-session/useRpgSessionBootstrap.ts b/src/hooks/rpg-session/useRpgSessionBootstrap.ts
index 2611dc34e..6c42c984a 100644
--- a/src/hooks/rpg-session/useRpgSessionBootstrap.ts
+++ b/src/hooks/rpg-session/useRpgSessionBootstrap.ts
@@ -15,8 +15,8 @@ import {
   AnimationState,
   Character,
   CustomWorldProfile,
-  GameState,
   GameRuntimeMode,
+  GameState,
   WorldType,
 } from '../../types';
 import type { BottomTab } from './rpgSessionTypes';
diff --git a/src/hooks/useResolvedAssetReadUrl.test.tsx b/src/hooks/useResolvedAssetReadUrl.test.tsx
index ab5efe032..a5094abb1 100644
--- a/src/hooks/useResolvedAssetReadUrl.test.tsx
+++ b/src/hooks/useResolvedAssetReadUrl.test.tsx
@@ -4,12 +4,12 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
 import { ResolvedAssetImage } from '../components/ResolvedAssetImage';
-import { useResolvedAssetReadUrl } from './useResolvedAssetReadUrl';
 import {
   clearStoredAccessToken,
   setStoredAccessToken,
 } from '../services/apiClient';
 import { clearSignedAssetReadUrlCache } from '../services/assetReadUrlService';
+import { useResolvedAssetReadUrl } from './useResolvedAssetReadUrl';
 
 describe('useResolvedAssetReadUrl', () => {
   beforeEach(() => {
diff --git a/src/hooks/useTreasureFlow.ts b/src/hooks/useTreasureFlow.ts
index 0d8036c51..854c0486e 100644
--- a/src/hooks/useTreasureFlow.ts
+++ b/src/hooks/useTreasureFlow.ts
@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
 
-import { resolveRpgRuntimeChoice } from './rpg-runtime-story';
 import { Character, GameState, StoryMoment, StoryOption } from '../types';
+import { resolveRpgRuntimeChoice } from './rpg-runtime-story';
 
 export function useTreasureFlow({
   gameState,
diff --git a/src/index.css b/src/index.css
index 86b43d828..6894f4a08 100644
--- a/src/index.css
+++ b/src/index.css
@@ -5044,6 +5044,16 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   cursor: grab;
 }
 
+.image-canvas-editor__undo-toast {
+  position: absolute;
+  top: 1rem;
+  left: 50%;
+  z-index: 73;
+  max-width: min(32rem, calc(100% - 2rem));
+  transform: translateX(-50%);
+  pointer-events: none;
+}
+
 .image-canvas-editor__world {
   position: absolute;
   left: 0;
diff --git a/src/routing/appPageRoutes.ts b/src/routing/appPageRoutes.ts
index 7b5186859..44e43474a 100644
--- a/src/routing/appPageRoutes.ts
+++ b/src/routing/appPageRoutes.ts
@@ -1,5 +1,5 @@
-import type { SelectionStage } from '../components/platform-entry';
 import { HOST_BRIDGE_PRESERVED_RUNTIME_CONTEXT_QUERY_KEYS } from '../../packages/shared/src/contracts/hostBridge';
+import type { SelectionStage } from '../components/platform-entry';
 import {
   buildCreationUrlSearchFromParams,
   isCreationRestorePath,
diff --git a/src/services/ai.test.ts b/src/services/ai.test.ts
index 784540708..7597707af 100644
--- a/src/services/ai.test.ts
+++ b/src/services/ai.test.ts
@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import type { StoryRuntimeProjectionResponse } from '../../packages/shared/src/contracts/story';
 import { AFFINITY_BACKSTORY_CHAPTER_THRESHOLDS } from '../data/affinityLevels';
-import { getScenePresetsByWorld } from '../data/scenePresets';
 import type {
   Character,
   Encounter,
@@ -10,7 +10,6 @@ import type {
   StoryOption,
 } from '../types';
 import { AnimationState, WorldType } from '../types';
-import type { StoryRuntimeProjectionResponse } from '../../packages/shared/src/contracts/story';
 
 const {
   connectivityError,
diff --git a/src/services/ai.ts b/src/services/ai.ts
index ee52ee63f..427274865 100644
--- a/src/services/ai.ts
+++ b/src/services/ai.ts
@@ -5,7 +5,6 @@ import type {
 } from '../../packages/shared/src/contracts/runtime';
 import { unwrapApiResponse } from '../../packages/shared/src/http';
 import { createSceneHostileNpcsFromEncounters } from '../data/hostileNpcs';
-import { hasMixedNarrativeLanguage } from './narrativeLanguage';
 import {
   buildEncounterFromSceneNpc,
   getScenePresetById,
@@ -34,7 +33,6 @@ import {
   DEFAULT_CUSTOM_WORLD_SCENE_IMAGE_NEGATIVE_PROMPT,
 } from '../prompts/customWorldPrompts';
 import {
-  AIResponse,
   Character,
   CustomWorldCreatorIntent,
   CustomWorldGenerationMode,
@@ -47,13 +45,6 @@ import {
   WorldStoryGraph,
   WorldType,
 } from '../types';
-import {
-  CustomWorldSceneImageRequest,
-  CustomWorldSceneImageResult,
-  StoryGenerationContext,
-  StoryRequestOptions,
-  TextStreamOptions,
-} from './aiTypes';
 import {
   generateCharacterPanelChatSuggestions as generateCharacterPanelChatSuggestionsFromServer,
   generateCharacterPanelChatSummary as generateCharacterPanelChatSummaryFromServer,
@@ -63,6 +54,11 @@ import {
   streamNpcChatDialogue as streamNpcChatDialogueFromServer,
   streamNpcRecruitDialogue as streamNpcRecruitDialogueFromServer,
 } from './aiService';
+import {
+  CustomWorldSceneImageRequest,
+  CustomWorldSceneImageResult,
+  StoryGenerationContext,
+} from './aiTypes';
 import { fetchWithApiAuth } from './apiClient';
 import {
   buildCustomWorldRawProfileFromFramework,
@@ -91,12 +87,10 @@ import {
   CUSTOM_WORLD_REQUEST_TIMEOUT_MS as CLIENT_CUSTOM_WORLD_REQUEST_TIMEOUT_MS,
   isLlmConnectivityError as isLlmConnectivityErrorFromClient,
   isLlmTimeoutError as isLlmTimeoutErrorFromClient,
-  requestChatMessageContent,
   requestPlainTextCompletion as requestPlainTextCompletionFromClient,
-  streamPlainTextCompletion as streamPlainTextCompletionFromClient,
 } from './llmClient';
 import { parseJsonResponseText as parseJsonResponseTextFromParser } from './llmParsers';
-import type { CharacterChatTargetStatus } from './rpgRuntimeChatTypes';
+import { hasMixedNarrativeLanguage } from './narrativeLanguage';
 import {
   buildFallbackActorNarrativeProfile,
   normalizeActorNarrativeProfile,
diff --git a/src/services/aiTypes.ts b/src/services/aiTypes.ts
index d62db93b5..8eac5b02f 100644
--- a/src/services/aiTypes.ts
+++ b/src/services/aiTypes.ts
@@ -1,3 +1,4 @@
+import type { SavedGameSnapshotInput } from '../../packages/shared/src/contracts/runtime';
 import type {
   ActorNarrativeProfile,
   ActState,
@@ -30,8 +31,8 @@ import type {
   NpcAnswerMode,
   NpcDisclosureStage,
   NpcWarmthStage,
-  PlayerStyleProfile,
   PlayerProgressionState,
+  PlayerStyleProfile,
   QuestStatus,
   ReleaseGateReport,
   ScenarioPack,
@@ -44,7 +45,6 @@ import type {
   WorldMutation,
   WorldType,
 } from '../types';
-import type { SavedGameSnapshotInput } from '../../packages/shared/src/contracts/runtime';
 import type { ConversationPressure, ConversationSituation } from '../types';
 
 export interface StoryRequestOptions {
diff --git a/src/services/apiClient.test.ts b/src/services/apiClient.test.ts
index 79eecfac1..d411171bf 100644
--- a/src/services/apiClient.test.ts
+++ b/src/services/apiClient.test.ts
@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
-  AUTH_STATE_EVENT,
   ApiClientError,
   BACKGROUND_AUTH_REQUEST_OPTIONS,
   clearStoredAccessToken,
@@ -599,6 +598,60 @@ describe('apiClient', () => {
     expect(result).toEqual({ value: 42 });
   });
 
+  it('reuses the exact post body and request id for an enabled unsafe transport retry', async () => {
+    setStoredAccessToken('editor-agent-token', { emit: false });
+    fetchMock
+      .mockRejectedValueOnce(new TypeError('network unavailable'))
+      .mockResolvedValueOnce(
+        createResponseMock({
+          status: 200,
+          body: JSON.stringify({
+            ok: true,
+            data: { deltaMessages: [] },
+            error: null,
+            meta: { apiVersion: '2026-06-16' },
+          }),
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      );
+    const body = JSON.stringify({
+      clientMessageId: 'client-message-1',
+      text: '生成一张图',
+      attachments: [],
+    });
+
+    await requestJson(
+      '/api/editor/agent-conversations/conversation-1/messages',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      },
+      '发送画布 Agent 消息失败',
+      {
+        authImpact: 'local',
+        retry: {
+          maxRetries: 1,
+          baseDelayMs: 1,
+          maxDelayMs: 1,
+          retryUnsafeMethods: true,
+        },
+      },
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const firstInit = fetchMock.mock.calls[0]?.[1] as RequestInit;
+    const secondInit = fetchMock.mock.calls[1]?.[1] as RequestInit;
+    expect(firstInit.body).toBe(body);
+    expect(secondInit.body).toBe(body);
+    expect((firstInit.headers as Record<string, string>)['x-request-id']).toBe(
+      'web-11111111-2222-3333-4444-555555555555',
+    );
+    expect((secondInit.headers as Record<string, string>)['x-request-id']).toBe(
+      (firstInit.headers as Record<string, string>)['x-request-id'],
+    );
+  });
+
   it('aborts requests when timeoutMs is reached', async () => {
     setStoredAccessToken('timeout-token', { emit: false });
     fetchMock.mockImplementation(
diff --git a/src/services/authService.test.ts b/src/services/authService.test.ts
index f37075577..d275cf9f4 100644
--- a/src/services/authService.test.ts
+++ b/src/services/authService.test.ts
@@ -45,8 +45,8 @@ import {
   getCaptchaChallengeFromError,
   getCurrentAuthUser,
   getPublicAuthUserById,
-  liftAuthRiskBlock,
   isWechatMiniProgramWebViewRuntime,
+  liftAuthRiskBlock,
   loginWithPhoneCode,
   logoutAllAuthSessions,
   redeemRegistrationInviteCode,
diff --git a/src/services/creation-agent/creationAgentChat.test.ts b/src/services/creation-agent/creationAgentChat.test.ts
index ec9e6a7d7..03ad02262 100644
--- a/src/services/creation-agent/creationAgentChat.test.ts
+++ b/src/services/creation-agent/creationAgentChat.test.ts
@@ -1,9 +1,9 @@
 import { expect, test } from 'vitest';
 
 import {
-  CREATION_AGENT_QUICK_FILL_MESSAGE,
   buildCreationAgentChatMessage,
   createCreationAgentChatQuickActions,
+  CREATION_AGENT_QUICK_FILL_MESSAGE,
   resolveCreationAgentQuickActionMessage,
 } from './creationAgentChat';
 
diff --git a/src/services/creation-agent/index.ts b/src/services/creation-agent/index.ts
index 9911c2de8..1a63c7daa 100644
--- a/src/services/creation-agent/index.ts
+++ b/src/services/creation-agent/index.ts
@@ -1,5 +1,5 @@
-export * from './creationAgentClientFactory';
 export * from './creationAgentChat';
+export * from './creationAgentClientFactory';
 export * from './creationAgentDocumentInput';
 export * from './creationAgentProgress';
 export * from './creationAgentSse';
diff --git a/src/services/customWorld.ts b/src/services/customWorld.ts
index d0d0f52f0..a23a9443b 100644
--- a/src/services/customWorld.ts
+++ b/src/services/customWorld.ts
@@ -5,11 +5,10 @@ import {
 } from '../data/affinityLevels';
 import { coerceWorldAttributeSchema } from '../data/attributeValidation';
 import {
-  CUSTOM_WORLD_SCENE_RELATIVE_POSITION_OPTIONS,
   type CustomWorldLandmarkDraft,
   getCustomWorldSceneRelativePositionLabel,
-  normalizeCustomWorldSceneRelativePosition,
   normalizeCustomWorldLandmarks,
+  normalizeCustomWorldSceneRelativePosition,
 } from '../data/customWorldSceneGraph';
 import {
   ActorNarrativeProfile,
@@ -22,7 +21,6 @@ import {
   CustomWorldCoverProfile,
   CustomWorldCoverSourceType,
   CustomWorldItem,
-  CustomWorldLandmark,
   CustomWorldNpc,
   CustomWorldPlayableNpc,
   CustomWorldProfile,
diff --git a/src/services/customWorldBuilder.ts b/src/services/customWorldBuilder.ts
index 1ca073cc6..e3c0728de 100644
--- a/src/services/customWorldBuilder.ts
+++ b/src/services/customWorldBuilder.ts
@@ -5,10 +5,9 @@ import {
 } from '../data/attributeProfileGenerator';
 import { mergeCustomWorldPlayableNpcTags } from '../data/customWorldBuildTags';
 import { normalizeCustomWorldLandmarks } from '../data/customWorldSceneGraph';
-import { CustomWorldProfile, WorldType } from '../types';
+import { CustomWorldProfile } from '../types';
 import { normalizeCustomWorldProfile } from './customWorld';
 import { normalizeCustomWorldOwnedSettingLayers } from './customWorldOwnedSettingLayers';
-import { resolveCustomWorldCompatibilityTemplateWorldType } from './customWorldTheme';
 import {
   buildFallbackActorNarrativeProfile,
   normalizeActorNarrativeProfile,
diff --git a/src/services/customWorldCover.test.ts b/src/services/customWorldCover.test.ts
index 62448337a..d81a0658f 100644
--- a/src/services/customWorldCover.test.ts
+++ b/src/services/customWorldCover.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { WorldType, type CustomWorldProfile } from '../types';
+import { type CustomWorldProfile,WorldType } from '../types';
 import { resolveCustomWorldCoverPresentation } from './customWorldCover';
 
 function createBaseProfile(): CustomWorldProfile {
diff --git a/src/services/customWorldCoverAssetService.ts b/src/services/customWorldCoverAssetService.ts
index 2fb903464..5e9bb6b7c 100644
--- a/src/services/customWorldCoverAssetService.ts
+++ b/src/services/customWorldCoverAssetService.ts
@@ -1,5 +1,5 @@
-import { requestJson } from './apiClient';
 import type { CustomWorldCoverCropRect, CustomWorldProfile } from '../types';
+import { requestJson } from './apiClient';
 
 const CUSTOM_WORLD_COVER_API_BASE = '/api/runtime/custom-world';
 
diff --git a/src/services/customWorldFoundationEntries.ts b/src/services/customWorldFoundationEntries.ts
index 73802f375..41985932c 100644
--- a/src/services/customWorldFoundationEntries.ts
+++ b/src/services/customWorldFoundationEntries.ts
@@ -1,6 +1,6 @@
 import type { EightAnchorContent } from '../../packages/shared/src/contracts/customWorldAgent';
-import { normalizeCustomWorldCreatorIntent } from './customWorldCreatorIntent';
 import type { CustomWorldProfile } from '../types';
+import { normalizeCustomWorldCreatorIntent } from './customWorldCreatorIntent';
 
 export type CustomWorldFoundationEntryId =
   | 'world-promise'
diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts
index 1640c6a1b..a526bf758 100644
--- a/src/services/host-bridge/hostBridge.ts
+++ b/src/services/host-bridge/hostBridge.ts
@@ -26,21 +26,16 @@ import type {
   ShareOpenPayload,
 } from '../../../packages/shared/src/contracts/hostBridge';
 import {
-  HOST_BRIDGE_AUDIO_MIME_TYPES,
-  HOST_BRIDGE_APP_TITLE_MAX_LENGTH,
-  HOST_BRIDGE_DOCUMENT_MIME_TYPES,
-  HOST_BRIDGE_IMAGE_MIME_TYPES,
   HOST_BRIDGE_NATIVE_APP_QUERY,
   HOST_BRIDGE_PUBLIC_WEB_ORIGIN,
-  HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS,
   HOST_BRIDGE_RUNTIME_CONTEXT_QUERY_KEY,
+  HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS,
   HOST_BRIDGE_SCANNER_TIMEOUT_MS,
-  HOST_BRIDGE_TEXT_MIME_TYPES,
   HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS,
   HOST_BRIDGE_WECHAT_MINI_PROGRAM_SOURCE_QUERY,
   isHostBridgeCapability,
-  normalizeHostBridgeBadgeCount,
   normalizeHostBridgeAppTitle,
+  normalizeHostBridgeBadgeCount,
   normalizeHostBridgeClipboardText,
   normalizeHostBridgeColorScheme,
   normalizeHostBridgeConnectionType,
@@ -622,6 +617,7 @@ function buildAbsoluteUrl(value: string) {
 
 function normalizeNativeAppPageUrl(url: string) {
   const trimmedUrl = url.trim();
+  // eslint-disable-next-line no-control-regex -- 宿主导航必须拒绝 C0/DEL 控制字符。
   if (!trimmedUrl || /[\u0000-\u001f\u007f]/u.test(trimmedUrl)) {
     return null;
   }
diff --git a/src/services/hyper3dModelGenerationService.ts b/src/services/hyper3dModelGenerationService.ts
index e23a2374a..7aea106a5 100644
--- a/src/services/hyper3dModelGenerationService.ts
+++ b/src/services/hyper3dModelGenerationService.ts
@@ -7,7 +7,6 @@ import type {
   Hyper3dTaskSubmitResponse,
   Hyper3dTextToModelRequest,
 } from '../../packages/shared/src/contracts/hyper3d';
-
 import { requestJson } from './apiClient';
 
 const HYPER3D_API_BASE = '/api/assets/hyper3d';
diff --git a/src/services/image-editor/editorAgentClient.test.ts b/src/services/image-editor/editorAgentClient.test.ts
index 32c0f140f..98b6f785a 100644
--- a/src/services/image-editor/editorAgentClient.test.ts
+++ b/src/services/image-editor/editorAgentClient.test.ts
@@ -1,41 +1,24 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
+  cancelEditorAgentToolCall,
+  confirmEditorAgentToolCall,
   createEditorAgentConversation,
   deleteEditorAgentConversation,
   getEditorAgentConversation,
   listEditorAgentConversations,
-  streamEditorAgentMessage,
+  sendEditorAgentMessage,
 } from './editorAgentClient';
 
 const requestJsonMock = vi.hoisted(() => vi.fn());
-const fetchWithApiAuthMock = vi.hoisted(() => vi.fn());
 
 vi.mock('../apiClient', () => ({
   requestJson: requestJsonMock,
-  fetchWithApiAuth: fetchWithApiAuthMock,
 }));
 
-function createSseResponse(payload: string) {
-  const encoder = new TextEncoder();
-  return new Response(
-    new ReadableStream<Uint8Array>({
-      start(controller) {
-        controller.enqueue(encoder.encode(payload));
-        controller.close();
-      },
-    }),
-    {
-      status: 200,
-      headers: { 'Content-Type': 'text/event-stream; charset=utf-8' },
-    },
-  );
-}
-
 describe('editorAgentClient', () => {
   afterEach(() => {
     requestJsonMock.mockReset();
-    fetchWithApiAuthMock.mockReset();
   });
 
   it('uses the planned editor agent conversation CRUD routes', async () => {
@@ -117,40 +100,37 @@ describe('editorAgentClient', () => {
     );
   });
 
-  it('posts editor agent message streams and emits typed SSE events', async () => {
-    fetchWithApiAuthMock.mockResolvedValueOnce(
-      createSseResponse(
-        [
-          'event: stage',
-          'data: {"conversationId":"conversation-1","stage":"thinking"}',
-          '',
-          'event: message_delta',
-          'data: {"conversationId":"conversation-1","messageId":"assistant-1","role":"assistant","kind":"chat","textDelta":"我先看一下"}',
-          '',
-          'event: done',
-          'data: {"conversationId":"conversation-1","title":"生成角色"}',
-          '',
-          '',
-        ].join('\n'),
-      ),
-    );
-    const events: string[] = [];
-
-    await streamEditorAgentMessage(
-      'conversation-1',
-      {
-        clientMessageId: 'client-message-1',
-        text: '帮我把角色改成像素风',
-        attachments: [],
+  it('sends an editor agent message and returns delta messages', async () => {
+    const responseBody = {
+      conversation: {
+        conversationId: 'conversation-1',
+        projectId: 'project-1',
+        title: '帮我把角色改成像素风',
+        updatedAt: '2026-07-03T00:00:01.000Z',
       },
-      {
-        onEvent: (event) => events.push(event.event),
-      },
-    );
+      deltaMessages: [
+        {
+          id: 1,
+          role: 'assistant',
+          text: '我来处理',
+          attachments: [],
+          toolCall: null,
+          createdAt: '2026-07-03T00:00:00.000Z',
+        },
+      ],
+      errorMessage: null,
+    };
+    requestJsonMock.mockResolvedValueOnce(responseBody);
 
-    expect(events).toEqual(['stage', 'message_delta', 'done']);
-    expect(fetchWithApiAuthMock).toHaveBeenCalledWith(
-      '/api/editor/agent-conversations/conversation-1/messages/stream',
+    const result = await sendEditorAgentMessage('conversation-1', {
+      clientMessageId: 'client-message-1',
+      text: '帮我把角色改成像素风',
+      attachments: [],
+    });
+
+    expect(result).toEqual(responseBody);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/agent-conversations/conversation-1/messages',
       expect.objectContaining({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -160,10 +140,48 @@ describe('editorAgentClient', () => {
           attachments: [],
         }),
       }),
+      '发送画布 Agent 消息失败',
       expect.objectContaining({
         timeoutMs: 1_200_000,
         authImpact: 'local',
+        retry: {
+          maxRetries: 1,
+          baseDelayMs: 250,
+          maxDelayMs: 250,
+          retryUnsafeMethods: true,
+        },
       }),
     );
   });
+
+  it('confirms and cancels a pending tool call by numeric message id', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({ ok: true })
+      .mockResolvedValueOnce({ ok: true });
+
+    await expect(
+      confirmEditorAgentToolCall('conversation/1', 7),
+    ).resolves.toBeUndefined();
+    await expect(
+      cancelEditorAgentToolCall('conversation/1', 7),
+    ).resolves.toBeUndefined();
+
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/editor/agent-conversations/conversation%2F1/messages/7/confirm',
+      { method: 'POST' },
+      '确认画布 Agent 操作失败',
+      {
+        timeoutMs: 1_200_000,
+        authImpact: 'local',
+      },
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/editor/agent-conversations/conversation%2F1/messages/7/cancel',
+      { method: 'POST' },
+      '取消画布 Agent 操作失败',
+      { authImpact: 'local' },
+    );
+  });
 });
diff --git a/src/services/image-editor/editorAgentClient.ts b/src/services/image-editor/editorAgentClient.ts
index 252bc5d30..d5a6113fe 100644
--- a/src/services/image-editor/editorAgentClient.ts
+++ b/src/services/image-editor/editorAgentClient.ts
@@ -4,23 +4,23 @@ import type {
   EditorAgentConversationListResponse,
   EditorAgentConversationResponse,
   EditorAgentConversationSummary,
-  EditorAgentSseEvent,
-  StreamEditorAgentMessageRequest,
+  EditorAgentMessageRequest,
+  EditorAgentMessageResponse,
 } from '../../../packages/shared/src/contracts/editorAgent';
-import {
-  appendApiErrorRequestId,
-  parseApiErrorMessage,
-} from '../../../packages/shared/src/http';
-import { fetchWithApiAuth, requestJson } from '../apiClient';
-import { readEditorAgentSseEvents } from './editorAgentSse';
+import { requestJson } from '../apiClient';
 
 const EDITOR_PROJECT_AGENT_CONVERSATION_API_BASE = '/api/editor/projects';
 const EDITOR_AGENT_CONVERSATION_API_BASE = '/api/editor/agent-conversations';
-const EDITOR_AGENT_STREAM_TIMEOUT_MS = 1_200_000;
+const EDITOR_AGENT_MESSAGE_TIMEOUT_MS = 1_200_000;
+const EDITOR_AGENT_MESSAGE_RETRY = {
+  maxRetries: 1,
+  baseDelayMs: 250,
+  maxDelayMs: 250,
+  retryUnsafeMethods: true,
+} as const;
 
-export type StreamEditorAgentMessageOptions = {
+export type SendEditorAgentMessageOptions = {
   signal?: AbortSignal;
-  onEvent?: (event: EditorAgentSseEvent) => void;
 };
 
 type DeleteEditorAgentConversationResponse = {
@@ -48,6 +48,16 @@ function agentConversationPath(conversationId: string) {
   )}`;
 }
 
+function agentToolCallActionPath(
+  conversationId: string,
+  messageId: number,
+  action: 'confirm' | 'cancel',
+) {
+  return `${agentConversationPath(conversationId)}/messages/${encodeURIComponent(
+    String(messageId),
+  )}/${action}`;
+}
+
 export async function listEditorAgentConversations(
   projectId: string,
 ): Promise<EditorAgentConversationSummary[]> {
@@ -97,36 +107,49 @@ export async function deleteEditorAgentConversation(
   return response.conversation;
 }
 
-export async function streamEditorAgentMessage(
+export async function sendEditorAgentMessage(
   conversationId: string,
-  payload: StreamEditorAgentMessageRequest,
-  options: StreamEditorAgentMessageOptions = {},
-) {
-  const response = await fetchWithApiAuth(
-    `${agentConversationPath(conversationId)}/messages/stream`,
+  payload: EditorAgentMessageRequest,
+  options: SendEditorAgentMessageOptions = {},
+): Promise<EditorAgentMessageResponse> {
+  return requestJson<EditorAgentMessageResponse>(
+    `${agentConversationPath(conversationId)}/messages`,
     {
       ...jsonRequest('POST', payload as unknown as Record<string, unknown>),
       signal: options.signal,
     },
+    '发送画布 Agent 消息失败',
     {
-      timeoutMs: EDITOR_AGENT_STREAM_TIMEOUT_MS,
+      timeoutMs: EDITOR_AGENT_MESSAGE_TIMEOUT_MS,
+      authImpact: 'local',
+      retry: EDITOR_AGENT_MESSAGE_RETRY,
+    },
+  );
+}
+
+export async function confirmEditorAgentToolCall(
+  conversationId: string,
+  messageId: number,
+): Promise<void> {
+  await requestJson<unknown>(
+    agentToolCallActionPath(conversationId, messageId, 'confirm'),
+    { method: 'POST' },
+    '确认画布 Agent 操作失败',
+    {
+      timeoutMs: EDITOR_AGENT_MESSAGE_TIMEOUT_MS,
       authImpact: 'local',
     },
   );
-
-  if (!response.ok) {
-    const responseText = await response.text();
-    throw new Error(
-      appendApiErrorRequestId(
-        parseApiErrorMessage(responseText, '发送画布 Agent 消息失败'),
-        response.headers.get('x-request-id'),
-      ),
-    );
-  }
-
-  if (!response.body) {
-    throw new Error('streaming response body is unavailable');
-  }
-
-  await readEditorAgentSseEvents(response, (event) => options.onEvent?.(event));
+}
+
+export async function cancelEditorAgentToolCall(
+  conversationId: string,
+  messageId: number,
+): Promise<void> {
+  await requestJson<unknown>(
+    agentToolCallActionPath(conversationId, messageId, 'cancel'),
+    { method: 'POST' },
+    '取消画布 Agent 操作失败',
+    { authImpact: 'local' },
+  );
 }
diff --git a/src/services/image-editor/editorAgentSse.test.ts b/src/services/image-editor/editorAgentSse.test.ts
deleted file mode 100644
index 7fd222503..000000000
--- a/src/services/image-editor/editorAgentSse.test.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { expect, test, vi } from 'vitest';
-
-import { readEditorAgentSseEvents } from './editorAgentSse';
-
-function createSseResponse(chunks: string[]) {
-  const encoder = new TextEncoder();
-  return new Response(
-    new ReadableStream<Uint8Array>({
-      start(controller) {
-        for (const chunk of chunks) {
-          controller.enqueue(encoder.encode(chunk));
-        }
-        controller.close();
-      },
-    }),
-    {
-      headers: {
-        'Content-Type': 'text/event-stream; charset=utf-8',
-      },
-    },
-  );
-}
-
-test('readEditorAgentSseEvents parses stage, generation result and done events', async () => {
-  const onEvent = vi.fn();
-  await readEditorAgentSseEvents(
-    createSseResponse([
-      'event: stage\r\ndata: {"conversationId":"conversation-1","stage":"generating"}\r\n\r\n',
-      'event: generation_result\r\ndata: {"conversationId":"conversation-1","messageId":"assistant-1","toolCallId":"tool-1","toolName":"generate_image","model":"gpt-image-2","images":[{"resourceId":"resource-1","imageSrc":"/generated/1.png","thumbnailSrc":null,"width":512,"height":512}]}\r\n\r\n',
-      'event: done\r\ndata: {"conversationId":"conversation-1","title":"像素角色"}\r\n\r\n',
-    ]),
-    onEvent,
-  );
-
-  expect(onEvent).toHaveBeenNthCalledWith(1, {
-    event: 'stage',
-    data: {
-      conversationId: 'conversation-1',
-      stage: 'generating',
-    },
-  });
-  expect(onEvent).toHaveBeenNthCalledWith(
-    2,
-    expect.objectContaining({
-      event: 'generation_result',
-      data: expect.objectContaining({
-        toolCallId: 'tool-1',
-        images: [
-          {
-            resourceId: 'resource-1',
-            imageSrc: '/generated/1.png',
-            thumbnailSrc: null,
-            width: 512,
-            height: 512,
-          },
-        ],
-      }),
-    }),
-  );
-  expect(onEvent).toHaveBeenNthCalledWith(3, {
-    event: 'done',
-    data: {
-      conversationId: 'conversation-1',
-      title: '像素角色',
-    },
-  });
-});
-
-test('readEditorAgentSseEvents accepts fallback event name from message payload', async () => {
-  const onEvent = vi.fn();
-
-  await readEditorAgentSseEvents(
-    createSseResponse([
-      'data: {"event":"error","data":{"conversationId":"conversation-1","code":"INSUFFICIENT_BALANCE","message":"泥点不足","recoverable":true}}\n\n',
-    ]),
-    onEvent,
-  );
-
-  expect(onEvent).toHaveBeenCalledWith({
-    event: 'error',
-    data: {
-      conversationId: 'conversation-1',
-      code: 'INSUFFICIENT_BALANCE',
-      message: '泥点不足',
-      recoverable: true,
-    },
-  });
-});
diff --git a/src/services/image-editor/editorAgentSse.ts b/src/services/image-editor/editorAgentSse.ts
deleted file mode 100644
index 7eefd3120..000000000
--- a/src/services/image-editor/editorAgentSse.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import type { EditorAgentSseEvent } from '../../../packages/shared/src/contracts/editorAgent';
-import { readSseJsonStream } from '../sseStream';
-
-const EDITOR_AGENT_SSE_EVENT_NAMES = new Set<EditorAgentSseEvent['event']>([
-  'stage',
-  'message_delta',
-  'tool_started',
-  'tool_completed',
-  'generation_result',
-  'error',
-  'done',
-]);
-
-function isEditorAgentSseEventName(
-  value: unknown,
-): value is EditorAgentSseEvent['event'] {
-  return (
-    typeof value === 'string' &&
-    EDITOR_AGENT_SSE_EVENT_NAMES.has(value as EditorAgentSseEvent['event'])
-  );
-}
-
-function readEventNameFromPayload(parsed: Record<string, unknown>) {
-  return isEditorAgentSseEventName(parsed.event) ? parsed.event : null;
-}
-
-function readEventDataFromPayload(parsed: Record<string, unknown>) {
-  const data = parsed.data;
-  return typeof data === 'object' && data !== null
-    ? (data as Record<string, unknown>)
-    : null;
-}
-
-export function normalizeEditorAgentSseEvent(
-  eventName: string,
-  parsed: Record<string, unknown>,
-): EditorAgentSseEvent | null {
-  const payloadEventName = readEventNameFromPayload(parsed);
-  if (payloadEventName) {
-    const payloadData = readEventDataFromPayload(parsed);
-    if (!payloadData) {
-      return null;
-    }
-    return {
-      event: payloadEventName,
-      data: payloadData,
-    } as unknown as EditorAgentSseEvent;
-  }
-
-  if (!isEditorAgentSseEventName(eventName)) {
-    return null;
-  }
-
-  return {
-    event: eventName,
-    data: parsed,
-  } as unknown as EditorAgentSseEvent;
-}
-
-export async function readEditorAgentSseEvents(
-  response: Response,
-  onEvent: (event: EditorAgentSseEvent) => void,
-) {
-  await readSseJsonStream(response, ({ eventName, parsed }) => {
-    const event = normalizeEditorAgentSseEvent(eventName, parsed);
-    if (event) {
-      onEvent(event);
-    }
-  });
-}
diff --git a/src/services/image-editor/editorImageReference.ts b/src/services/image-editor/editorImageReference.ts
index 37d1c6619..67fcc0ce7 100644
--- a/src/services/image-editor/editorImageReference.ts
+++ b/src/services/image-editor/editorImageReference.ts
@@ -28,9 +28,8 @@ function encodeBytesAsBase64(bytes: Uint8Array) {
 }
 
 /**
- * 图片画布的生成编辑接口只接收图片 Data URL。
- * 画布里既有上传 / 生成图，也有内置 public 参考图和历史 generated 路径；
- * 提交给后端前统一读取成 Data URL，避免后端误收到普通 URL 后进入 Data URL 校验错误。
+ * 将画布图片读取为浏览器临时 Data URL，供压缩、标注等本地处理使用。
+ * 生成请求提交前必须再上传 OSS，并把 objectKey 传给后端；Data URL 不属于接口契约。
  */
 export async function resolveEditorImageReferenceDataUrl(
   source: string,
@@ -121,7 +120,7 @@ export async function compressEditorImageReferenceDataUrlForGeneration(
       return dataUrl;
     }
 
-    // 中文注释：参考图只用于模型理解视觉方向，提交前压缩可避免原图 Data URL 撑爆 JSON 请求体。
+    // 中文注释：参考图只用于模型理解视觉方向，上传 OSS 前压缩可减少传输与存储体积。
     if (mimeType === 'image/jpeg') {
       context.fillStyle = '#fff';
       context.fillRect(0, 0, targetWidth, targetHeight);
diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts
index 545d70efa..71ba9169c 100644
--- a/src/services/image-editor/editorProjectClient.test.ts
+++ b/src/services/image-editor/editorProjectClient.test.ts
@@ -18,8 +18,8 @@ import {
   generateEditorVideo,
   listEditorProjects,
   listPublicEditorProjectResources,
-  loadEditorGenerationPricing,
   loadEditorAssetLibrary,
+  loadEditorGenerationPricing,
   loadEditorProject,
   loadOrCreateRecentEditorProject,
   removeEditorImageBackground,
@@ -743,6 +743,11 @@ describe('editorProjectClient', () => {
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'vector-task-1',
+      warning: {
+        code: 'postprocess-failed-source-preserved',
+        reason:
+          '生成任务成功，后处理失败。',
+      },
     });
 
     const result = await generateEditorImage({
@@ -750,6 +755,11 @@ describe('editorProjectClient', () => {
     });
 
     expect(result.taskId).toBe('vector-task-1');
+    expect(result.warning).toEqual({
+      code: 'postprocess-failed-source-preserved',
+      reason:
+        '生成任务成功，后处理失败。',
+    });
     expect(requestJsonMock).toHaveBeenCalledWith(
       '/api/editor/images/generations',
       expect.objectContaining({
@@ -764,6 +774,47 @@ describe('editorProjectClient', () => {
     );
   });
 
+  it('rejects inline media before submitting editor generation requests', async () => {
+    await expect(
+      generateEditorImage({
+        prompt: '一张画布图片',
+        referenceImageSrcs: ['data:image/png;base64,inline'],
+      }),
+    ).rejects.toThrow('必须先上传 OSS');
+
+    await expect(
+      generateEditorVideo({
+        prompt: '生成视频',
+        model: 'seedance2.0-fast',
+        aspectRatio: '16:9',
+        durationSeconds: 5,
+        resolution: '720p',
+        mode: 'std',
+        sound: 'off',
+        referenceVideoSrcs: ['blob:local-video'],
+      }),
+    ).rejects.toThrow('必须先上传 OSS');
+
+    expect(requestJsonMock).not.toHaveBeenCalled();
+  });
+
+  it('rejects oversized stable video reference fields before submission', async () => {
+    await expect(
+      generateEditorVideo({
+        prompt: '生成视频',
+        model: 'seedance2.0-fast',
+        aspectRatio: '16:9',
+        durationSeconds: 5,
+        resolution: '720p',
+        mode: 'std',
+        sound: 'off',
+        referenceVideoSrcs: [`https://assets.example.test/${'a'.repeat(256 * 1024)}`],
+      }),
+    ).rejects.toThrow('稳定引用字段总长度不能超过 256KB');
+
+    expect(requestJsonMock).not.toHaveBeenCalled();
+  });
+
   it('passes image model options to editor image generation', async () => {
     requestJsonMock.mockResolvedValueOnce({
       imageSrc: 'data:image/png;base64,character',
@@ -909,8 +960,8 @@ describe('editorProjectClient', () => {
     });
 
     const result = await generateEditorIconSpritesheet({
-      referenceImageSrc: 'data:image/png;base64,spec',
-      referenceImageSrcs: ['data:image/png;base64,icon-ref'],
+      referenceImageSrc: '/generated-images/editor/spec.png',
+      referenceImageSrcs: ['/generated-images/editor/icon-ref.png'],
       iconDescriptions: ['返回按钮', '设置按钮'],
       assetLabel: '冒险游戏图标',
     });
@@ -926,8 +977,8 @@ describe('editorProjectClient', () => {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          referenceImageSrc: 'data:image/png;base64,spec',
-          referenceImageSrcs: ['data:image/png;base64,icon-ref'],
+          referenceImageSrc: '/generated-images/editor/spec.png',
+          referenceImageSrcs: ['/generated-images/editor/icon-ref.png'],
           iconDescriptions: ['返回按钮', '设置按钮'],
           model: 'gemini-3.1-flash-image-preview',
           assetLabel: '冒险游戏图标',
@@ -955,7 +1006,7 @@ describe('editorProjectClient', () => {
     });
 
     await generateEditorIconSpritesheet({
-      referenceImageSrc: 'data:image/png;base64,spec',
+      referenceImageSrc: '/generated-images/editor/spec.png',
       iconDescriptions: ['返回按钮'],
       model: 'gpt-image-2',
       screenColor: '#E6D8FF',
@@ -976,7 +1027,7 @@ describe('editorProjectClient', () => {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          referenceImageSrc: 'data:image/png;base64,spec',
+          referenceImageSrc: '/generated-images/editor/spec.png',
           iconDescriptions: ['返回按钮'],
           model: 'gpt-image-2',
           screenColor: '#E6D8FF',
@@ -1095,11 +1146,11 @@ describe('editorProjectClient', () => {
     });
 
     const result = await extractEditorUiDesignAssets({
-      sourceImageSrc: 'data:image/png;base64,ui-design',
+      sourceImageSrc: '/generated-images/editor/ui-design.png',
       model: 'gpt-image-2',
       screenColor: '#7FB3FF',
       segModel: 'anime-seg',
-      referenceImageSrcs: ['data:image/png;base64,ui-ref'],
+      referenceImageSrcs: ['/generated-images/editor/ui-ref.png'],
       projectId: 'editor-project-1',
       assetFolderId: 'project',
       spritesheetLabel: '战斗UI设计图 素材图集',
@@ -1118,11 +1169,11 @@ describe('editorProjectClient', () => {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          sourceImageSrc: 'data:image/png;base64,ui-design',
+          sourceImageSrc: '/generated-images/editor/ui-design.png',
           model: 'gpt-image-2',
           screenColor: '#7FB3FF',
           segModel: 'anime-seg',
-          referenceImageSrcs: ['data:image/png;base64,ui-ref'],
+          referenceImageSrcs: ['/generated-images/editor/ui-ref.png'],
           projectId: 'editor-project-1',
           generationInputs: {
             fields: [{ title: '来源', value: '战斗UI设计图' }],
@@ -1202,7 +1253,7 @@ describe('editorProjectClient', () => {
       kind: 'publication-material',
       aspectRatio: '9:16',
       imageSize: '1K',
-      referenceImageSrcs: ['data:image/png;base64,ref'],
+      referenceImageSrcs: ['/generated-images/editor/publication-ref.png'],
     });
 
     expect(result.height).toBe(1280);
@@ -1217,7 +1268,7 @@ describe('editorProjectClient', () => {
           kind: 'publication-material',
           aspectRatio: '9:16',
           imageSize: '1K',
-          referenceImageSrcs: ['data:image/png;base64,ref'],
+          referenceImageSrcs: ['/generated-images/editor/publication-ref.png'],
         }),
       }),
       '生成图片失败',
@@ -1249,7 +1300,7 @@ describe('editorProjectClient', () => {
 
     const result = await generateEditorCharacterAnimation({
       sourceLayerId: 'layer-character',
-      sourceImageSrc: 'data:image/png;base64,character',
+      sourceImageSrc: '/generated-images/editor/character.png',
       sourceWidth: 1024,
       sourceHeight: 1024,
       promptText: '待机',
@@ -1269,7 +1320,7 @@ describe('editorProjectClient', () => {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           sourceLayerId: 'layer-character',
-          sourceImageSrc: 'data:image/png;base64,character',
+          sourceImageSrc: '/generated-images/editor/character.png',
           sourceWidth: 1024,
           sourceHeight: 1024,
           promptText: '待机',
@@ -1385,7 +1436,7 @@ describe('editorProjectClient', () => {
       resolution: '720p',
       mode: 'std',
       sound: 'off',
-      referenceImageSrcs: ['data:image/png;base64,image'],
+      referenceImageSrcs: ['/generated-images/editor/video-reference.png'],
       referenceVideoSrcs: [
         'generated-character-drafts/editor/seedance-references/video/video.mp4',
       ],
@@ -1408,7 +1459,7 @@ describe('editorProjectClient', () => {
           mode: 'std',
           sound: 'off',
           webSearchEnabled: true,
-          referenceImageSrcs: ['data:image/png;base64,image'],
+          referenceImageSrcs: ['/generated-images/editor/video-reference.png'],
           referenceVideoSrcs: [
             'generated-character-drafts/editor/seedance-references/video/video.mp4',
           ],
@@ -1568,10 +1619,12 @@ describe('editorProjectClient', () => {
 
     const result = await editEditorImage({
       prompt: '把画面改成黄昏光线',
-      sourceImageSrc: 'data:image/png;base64,source',
+      sourceImageSrc: '/generated-images/editor/source.png',
       size: '1024x1024',
       model: 'gpt-image-2',
-      referenceImageSrcs: ['data:image/png;base64,style'],
+      aspectRatio: '1:1',
+      imageSize: '1K',
+      referenceImageSrcs: ['/generated-images/editor/style.png'],
       projectId: 'editor-project-1',
       assetKind: 'character',
       assetFolderId: 'project',
@@ -1592,10 +1645,12 @@ describe('editorProjectClient', () => {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           prompt: '把画面改成黄昏光线',
-          sourceImageSrc: 'data:image/png;base64,source',
+          sourceImageSrc: '/generated-images/editor/source.png',
           size: '1024x1024',
           model: 'gpt-image-2',
-          referenceImageSrcs: ['data:image/png;base64,style'],
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          referenceImageSrcs: ['/generated-images/editor/style.png'],
           projectId: 'editor-project-1',
           assetKind: 'character',
           generationInputs: {
@@ -1618,19 +1673,18 @@ describe('editorProjectClient', () => {
 
   it('passes canvas completion context to background removal', async () => {
     requestJsonMock.mockResolvedValueOnce({
-      imageSrc: 'data:image/png;base64,cutout',
-      width: 512,
-      height: 512,
-      objectKey: 'generated-character-drafts/editor-cutouts/cutout.png',
-      assetObjectId: 'asset-object-cutout',
-      taskId: 'background-removal-1',
-      elapsedMs: 1200,
-      provider: 'BiRefNet',
-      project: null,
+      queueState: {
+        operationId: 'background-removal-1',
+        status: 'queued',
+        phaseLabel: '排队中',
+        phaseDetail: '排队中',
+        progress: 0,
+        updatedAtMicros: 1,
+      },
     });
 
-    await removeEditorImageBackground({
-      sourceImageSrc: 'data:image/png;base64,source',
+    const response = await removeEditorImageBackground({
+      sourceImageSrc: '/generated-images/editor/source.png',
       projectId: 'editor-project-1',
       targetLayerId: 'layer-source',
       canvasCompletion: {
@@ -1647,13 +1701,15 @@ describe('editorProjectClient', () => {
       },
     });
 
+    expect(response.queueState.operationId).toBe('background-removal-1');
+
     expect(requestJsonMock).toHaveBeenCalledWith(
       '/api/editor/images/background-removals',
       expect.objectContaining({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          sourceImageSrc: 'data:image/png;base64,source',
+          sourceImageSrc: '/generated-images/editor/source.png',
           projectId: 'editor-project-1',
           targetLayerId: 'layer-source',
           canvasCompletion: {
diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
index d4d1e8360..93a5c90ed 100644
--- a/src/services/image-editor/editorProjectClient.ts
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -1,5 +1,5 @@
-import { requestJson } from '../apiClient';
 import type { ExternalGenerationJobStatusRecord } from '../../../packages/shared/src/contracts/externalGeneration';
+import { requestJson } from '../apiClient';
 import { EDITOR_REQUEST_RETRY_OPTIONS } from './editorRetryOptions';
 
 const EDITOR_PROJECT_API_BASE = '/api/editor/projects';
@@ -25,8 +25,38 @@ const EDITOR_BACKGROUND_MUSIC_GENERATION_API =
   '/api/editor/audios/background-music/generations';
 const EDITOR_GENERATION_PRICING_API = '/api/editor/generation-pricing';
 const EDITOR_IMAGE_MODEL_NANOBANANA2 = 'gemini-3.1-flash-image-preview';
+const EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES = 256 * 1024;
 const DEFAULT_PROJECT_TITLE = '未命名画布';
 
+function assertStableEditorMediaReference(value: string, fieldLabel: string) {
+  const normalized = value.trimStart().toLowerCase();
+  if (normalized.startsWith('data:') || normalized.startsWith('blob:')) {
+    throw new Error(
+      `${fieldLabel}必须先上传 OSS，并使用 objectKey、项目资源、素材 ID 或支持的 URL 引用。`,
+    );
+  }
+}
+
+function assertStableEditorMediaReferences(
+  values: readonly string[] | undefined,
+  fieldLabel: string,
+) {
+  values?.forEach((value) => assertStableEditorMediaReference(value, fieldLabel));
+}
+
+function assertStableEditorVideoReferences(input: EditorVideoGenerationInput) {
+  const references = [
+    ...(input.referenceImageSrcs ?? []),
+    ...(input.referenceVideoSrcs ?? []),
+    ...(input.referenceAudioSrcs ?? []),
+  ];
+  assertStableEditorMediaReferences(references, '视频参考素材');
+  const requestBytes = new TextEncoder().encode(references.join('')).byteLength;
+  if (requestBytes > EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES) {
+    throw new Error('视频参考素材稳定引用字段总长度不能超过 256KB');
+  }
+}
+
 export type EditorCanvasViewport = {
   x: number;
   y: number;
@@ -234,6 +264,8 @@ export type EditorImageEditInput = {
   sourceImageSrc: string;
   size?: string;
   model?: string;
+  aspectRatio?: string;
+  imageSize?: string;
   referenceImageSrcs?: string[];
   projectId?: string | null;
   assetKind?: string | null;
@@ -273,23 +305,12 @@ export type EditorImageGenerationResult = {
   resource?: EditorProjectResourceSnapshot | null;
   asset?: EditorAssetSnapshot | null;
   project?: EditorProjectSnapshot | null;
+  warning?: EditorGenerationWarning | null;
   queueState?: ExternalGenerationJobStatusRecord | null;
 };
 
 export type EditorBackgroundRemovalResult = {
-  imageSrc: string;
-  objectKey?: string | null;
-  assetObjectId?: string | null;
-  width: number;
-  height: number;
-  sourceType?: 'generated';
-  taskId?: string | null;
-  elapsedMs?: number;
-  provider?: string;
-  resource?: EditorProjectResourceSnapshot | null;
-  asset?: EditorAssetSnapshot | null;
-  project?: EditorProjectSnapshot | null;
-  queueState?: ExternalGenerationJobStatusRecord | null;
+  queueState: ExternalGenerationJobStatusRecord;
 };
 
 export type EditorIconSpritesheetIconResult = {
@@ -301,11 +322,13 @@ export type EditorIconSpritesheetIconResult = {
   asset?: EditorAssetSnapshot | null;
 };
 
-export type EditorIconSpritesheetSliceWarning = {
+export type EditorGenerationWarning = {
   code: string;
   reason: string;
 };
 
+export type EditorIconSpritesheetSliceWarning = EditorGenerationWarning;
+
 export type EditorIconSpritesheetGenerationResult = {
   spritesheetImageSrc: string;
   spritesheetWidth: number;
@@ -321,6 +344,7 @@ export type EditorIconSpritesheetGenerationResult = {
   spritesheetResource?: EditorProjectResourceSnapshot | null;
   spritesheetAsset?: EditorAssetSnapshot | null;
   project?: EditorProjectSnapshot | null;
+  warning?: EditorGenerationWarning | null;
   queueState?: ExternalGenerationJobStatusRecord | null;
 };
 
@@ -880,6 +904,7 @@ export async function toggleEditorShowcaseAssetLike(
 }
 
 export async function generateEditorImage(input: EditorImageGenerationInput) {
+  assertStableEditorMediaReferences(input.referenceImageSrcs, '生成参考图');
   return requestJson<EditorImageGenerationResponse>(
     EDITOR_IMAGE_GENERATION_API,
     jsonRequest('POST', {
@@ -919,6 +944,11 @@ export async function generateEditorImage(input: EditorImageGenerationInput) {
 export async function generateEditorIconSpritesheet(
   input: EditorIconSpritesheetGenerationInput,
 ) {
+  assertStableEditorMediaReference(input.referenceImageSrc, '图标素材规范');
+  assertStableEditorMediaReferences(
+    input.referenceImageSrcs,
+    '图标素材参考图',
+  );
   return requestJson<EditorIconSpritesheetGenerationResponse>(
     EDITOR_ICON_SPRITESHEET_GENERATION_API,
     jsonRequest('POST', {
@@ -968,6 +998,8 @@ export async function splitEditorIconSpritesheet(
 export async function extractEditorUiDesignAssets(
   input: EditorUiDesignAssetExtractionInput,
 ) {
+  assertStableEditorMediaReference(input.sourceImageSrc, 'UI设计图');
+  assertStableEditorMediaReferences(input.referenceImageSrcs, 'UI素材参考图');
   return requestJson<EditorIconSpritesheetGenerationResponse>(
     EDITOR_UI_DESIGN_ASSET_EXTRACTION_API,
     jsonRequest('POST', {
@@ -1001,6 +1033,8 @@ export async function extractEditorUiDesignAssets(
 }
 
 export async function editEditorImage(input: EditorImageEditInput) {
+  assertStableEditorMediaReference(input.sourceImageSrc, '待修改图片');
+  assertStableEditorMediaReferences(input.referenceImageSrcs, '修改参考图');
   return requestJson<EditorImageGenerationResponse>(
     EDITOR_IMAGE_EDIT_API,
     jsonRequest('POST', {
@@ -1008,6 +1042,8 @@ export async function editEditorImage(input: EditorImageEditInput) {
       sourceImageSrc: input.sourceImageSrc,
       ...(input.size ? { size: input.size } : {}),
       ...(input.model ? { model: input.model } : {}),
+      ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
+      ...(input.imageSize ? { imageSize: input.imageSize } : {}),
       ...(input.referenceImageSrcs?.length
         ? { referenceImageSrcs: input.referenceImageSrcs }
         : {}),
@@ -1037,6 +1073,7 @@ export async function editEditorImage(input: EditorImageEditInput) {
 export async function removeEditorImageBackground(
   input: EditorBackgroundRemovalInput,
 ) {
+  assertStableEditorMediaReference(input.sourceImageSrc, '待去除背景图片');
   return requestJson<EditorBackgroundRemovalResponse>(
     EDITOR_BACKGROUND_REMOVAL_API,
     jsonRequest('POST', {
@@ -1068,6 +1105,7 @@ export async function removeEditorImageBackground(
 export async function generateEditorCharacterAnimation(
   input: EditorCharacterAnimationGenerationInput,
 ) {
+  assertStableEditorMediaReference(input.sourceImageSrc, '角色动画源图');
   return requestJson<EditorCharacterAnimationGenerationResult>(
     EDITOR_CHARACTER_ANIMATION_GENERATION_API,
     jsonRequest('POST', {
@@ -1092,6 +1130,7 @@ export async function generateEditorCharacterAnimation(
 }
 
 export async function generateEditorVideo(input: EditorVideoGenerationInput) {
+  assertStableEditorVideoReferences(input);
   return requestJson<EditorVideoGenerationResponse>(
     EDITOR_VIDEO_GENERATION_API,
     jsonRequest('POST', {
diff --git a/src/services/jump-hop/jumpHopClient.ts b/src/services/jump-hop/jumpHopClient.ts
index ca559edd4..da2ca3cb5 100644
--- a/src/services/jump-hop/jumpHopClient.ts
+++ b/src/services/jump-hop/jumpHopClient.ts
@@ -8,10 +8,10 @@ import type {
   JumpHopJumpRequest,
   JumpHopLeaderboardResponse,
   JumpHopRunResponse,
-  JumpHopStartRunRequest,
   JumpHopRuntimeRunSnapshotResponse,
   JumpHopSessionResponse,
   JumpHopSessionSnapshotResponse,
+  JumpHopStartRunRequest,
   JumpHopWorkDetailResponse,
   JumpHopWorkMutationResponse,
   JumpHopWorkProfileResponse,
diff --git a/src/services/llmClient.ts b/src/services/llmClient.ts
index 9af0aefc5..f783c1e76 100644
--- a/src/services/llmClient.ts
+++ b/src/services/llmClient.ts
@@ -1,5 +1,5 @@
 import type {TextStreamOptions} from './aiTypes';
-import { fetchWithApiAuth, type ApiRequestOptions } from './apiClient';
+import { type ApiRequestOptions,fetchWithApiAuth } from './apiClient';
 import { parseSseJsonObject, readSseStream } from './sseStream';
 
 const ENV: Partial<ImportMetaEnv> = import.meta.env ?? {};
diff --git a/src/services/match3dGeneratedModelCache.test.ts b/src/services/match3dGeneratedModelCache.test.ts
index 598d03a6a..44426429e 100644
--- a/src/services/match3dGeneratedModelCache.test.ts
+++ b/src/services/match3dGeneratedModelCache.test.ts
@@ -1,19 +1,19 @@
 import { afterEach, describe, expect, test, vi } from 'vitest';
 
-import { setStoredAccessToken, clearStoredAccessToken } from './apiClient';
+import { clearStoredAccessToken,setStoredAccessToken } from './apiClient';
 import { clearSignedAssetReadUrlCache } from './assetReadUrlService';
 import {
   clearMatch3DGeneratedModelBytesCache,
-  getMatch3DGeneratedImageViewSources,
   getMatch3DGeneratedImageAssetSources,
-  getMatch3DGeneratedRuntimeUiAssetSources,
+  getMatch3DGeneratedImageViewSources,
   getMatch3DGeneratedModelAssetSources,
+  getMatch3DGeneratedRuntimeUiAssetSources,
   hasMatch3DGeneratedImageAsset,
   mergeMatch3DGeneratedItemAssetsForRuntime,
   normalizeMatch3DGeneratedItemAssetsForRuntime,
   preloadMatch3DGeneratedImageAssets,
-  preloadMatch3DGeneratedRuntimeAssets,
   preloadMatch3DGeneratedModelAssets,
+  preloadMatch3DGeneratedRuntimeAssets,
   readMatch3DGeneratedModelBytes,
 } from './match3dGeneratedModelCache';
 
diff --git a/src/services/puzzle-clear/puzzleClearClient.ts b/src/services/puzzle-clear/puzzleClearClient.ts
index 88cd3787b..1c05ab173 100644
--- a/src/services/puzzle-clear/puzzleClearClient.ts
+++ b/src/services/puzzle-clear/puzzleClearClient.ts
@@ -13,8 +13,8 @@ import type {
   PuzzleClearWorkDetailResponse,
   PuzzleClearWorkMutationResponse,
   PuzzleClearWorkProfileResponse,
-  PuzzleClearWorksResponse,
   PuzzleClearWorkspaceCreateRequest,
+  PuzzleClearWorksResponse,
   PuzzleClearWorkSummaryResponse,
 } from '../../../packages/shared/src/contracts/puzzleClear';
 import { type ApiRetryOptions, requestJson } from '../apiClient';
@@ -57,8 +57,8 @@ export type {
   PuzzleClearWorkDetailResponse,
   PuzzleClearWorkMutationResponse,
   PuzzleClearWorkProfileResponse,
-  PuzzleClearWorksResponse,
   PuzzleClearWorkspaceCreateRequest,
+  PuzzleClearWorksResponse,
   PuzzleClearWorkSummaryResponse,
 };
 export type CreatePuzzleClearSessionRequest =
diff --git a/src/services/puzzle-gallery/puzzleGalleryClient.ts b/src/services/puzzle-gallery/puzzleGalleryClient.ts
index 2ee76b627..313927cbc 100644
--- a/src/services/puzzle-gallery/puzzleGalleryClient.ts
+++ b/src/services/puzzle-gallery/puzzleGalleryClient.ts
@@ -3,7 +3,6 @@ import type {
 } from '../../../packages/shared/src/contracts/puzzleAgentSession';
 import type {
   PuzzleGalleryResponse,
-  PuzzleWorksResponse,
   PuzzleWorkSummary,
 } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import { type ApiRetryOptions, requestJson } from '../apiClient';
diff --git a/src/services/puzzleReferenceImage.test.ts b/src/services/puzzleReferenceImage.test.ts
index a09c30c29..34dfd39bf 100644
--- a/src/services/puzzleReferenceImage.test.ts
+++ b/src/services/puzzleReferenceImage.test.ts
@@ -3,11 +3,11 @@
 import { afterEach, describe, expect, test, vi } from 'vitest';
 
 import {
-  PUZZLE_REFERENCE_IMAGE_MAX_DATA_URL_LENGTH,
   cropPuzzleReferenceImageDataUrl,
   isPuzzleReferenceImageSquare,
-  readPuzzleReferenceImageForUpload,
+  PUZZLE_REFERENCE_IMAGE_MAX_DATA_URL_LENGTH,
   readPuzzleReferenceImageAsDataUrl,
+  readPuzzleReferenceImageForUpload,
 } from './puzzleReferenceImage';
 
 afterEach(() => {
diff --git a/src/services/recommendedRuntimeGuestLaunch.test.ts b/src/services/recommendedRuntimeGuestLaunch.test.ts
index 5844cb1cb..d0254d671 100644
--- a/src/services/recommendedRuntimeGuestLaunch.test.ts
+++ b/src/services/recommendedRuntimeGuestLaunch.test.ts
@@ -33,6 +33,7 @@ import {
   startMatch3DRun,
   stopMatch3DRun,
 } from './match3d-runtime/match3dRuntimeClient';
+import { puzzleClearClient } from './puzzle-clear/puzzleClearClient';
 import {
   advancePuzzleNextLevel,
   dragPuzzlePieceOrGroup,
@@ -43,7 +44,6 @@ import {
   updatePuzzleRunPause,
   usePuzzleRuntimeProp,
 } from './puzzle-runtime/puzzleRuntimeClient';
-import { puzzleClearClient } from './puzzle-clear/puzzleClearClient';
 import {
   dropSquareHoleShape,
   finishSquareHoleTimeUp,
@@ -52,17 +52,17 @@ import {
   startSquareHoleRun,
   stopSquareHoleRun,
 } from './square-hole-runtime/squareHoleRuntimeClient';
-import {
-  checkpointWoodenFishRun,
-  finishWoodenFishRun,
-  startWoodenFishRuntimeRun,
-} from './wooden-fish/woodenFishClient';
 import {
   getVisualNovelHistory,
   getVisualNovelRun,
   regenerateVisualNovelRun,
   startVisualNovelRun,
 } from './visual-novel-runtime/visualNovelRuntimeClient';
+import {
+  checkpointWoodenFishRun,
+  finishWoodenFishRun,
+  startWoodenFishRuntimeRun,
+} from './wooden-fish/woodenFishClient';
 
 describe('recommended runtime guest launch clients', () => {
   beforeEach(() => {
diff --git a/src/services/rpg-creation/rpgCreationAgentClient.ts b/src/services/rpg-creation/rpgCreationAgentClient.ts
index 0a9090095..425835a56 100644
--- a/src/services/rpg-creation/rpgCreationAgentClient.ts
+++ b/src/services/rpg-creation/rpgCreationAgentClient.ts
@@ -2,10 +2,10 @@ import type {
   CreateRpgAgentSessionRequest,
   CreateRpgAgentSessionResponse,
   GetRpgAgentCardDetailResponse,
-  RpgCreationResultView,
   RpgAgentDraftCardDetail,
   RpgAgentOperationRecord,
   RpgAgentSessionSnapshot,
+  RpgCreationResultView,
   SendRpgAgentMessageRequest,
 } from '../../../packages/shared/src';
 import type { RpgAgentActionRequest } from '../../../packages/shared/src';
diff --git a/src/services/rpg-creation/rpgCreationAssetClient.test.ts b/src/services/rpg-creation/rpgCreationAssetClient.test.ts
index 922a477c9..4e6a1b700 100644
--- a/src/services/rpg-creation/rpgCreationAssetClient.test.ts
+++ b/src/services/rpg-creation/rpgCreationAssetClient.test.ts
@@ -7,8 +7,8 @@ const { requestJsonMock } = vi.hoisted(() => ({
 }));
 
 import {
-  generateRpgWorldOpeningCg,
   generateRpgWorldLandmark,
+  generateRpgWorldOpeningCg,
   generateRpgWorldSceneImage,
   generateRpgWorldSceneNpc,
 } from './rpgCreationAssetClient';
diff --git a/src/services/rpg-creation/rpgCreationPreviewAdapter.ts b/src/services/rpg-creation/rpgCreationPreviewAdapter.ts
index f4d90a376..7f82f90c0 100644
--- a/src/services/rpg-creation/rpgCreationPreviewAdapter.ts
+++ b/src/services/rpg-creation/rpgCreationPreviewAdapter.ts
@@ -36,6 +36,6 @@ export const rpgCreationPreviewAdapter = {
 
 export {
   buildCustomWorldProfileFromResultPreview as buildRpgCreationPreviewFromResultPreview,
-  buildCustomWorldProfileFromAgentSession as buildRpgCreationPreviewFromSession,
   buildCustomWorldProfileFromResultView as buildRpgCreationPreviewFromResultView,
+  buildCustomWorldProfileFromAgentSession as buildRpgCreationPreviewFromSession,
 };
diff --git a/src/services/rpg-creation/rpgCreationRuntimeClient.ts b/src/services/rpg-creation/rpgCreationRuntimeClient.ts
index cb509d1f1..0aa095850 100644
--- a/src/services/rpg-creation/rpgCreationRuntimeClient.ts
+++ b/src/services/rpg-creation/rpgCreationRuntimeClient.ts
@@ -1,7 +1,7 @@
 import {
-  BACKGROUND_AUTH_REQUEST_OPTIONS,
   type ApiAuthImpact,
   type ApiRetryOptions,
+  BACKGROUND_AUTH_REQUEST_OPTIONS,
   requestJson,
 } from '../apiClient';
 
diff --git a/src/services/rpg-entry/index.ts b/src/services/rpg-entry/index.ts
index 535d45e28..27d2f1c45 100644
--- a/src/services/rpg-entry/index.ts
+++ b/src/services/rpg-entry/index.ts
@@ -2,9 +2,9 @@ export {
   deleteRpgEntryWorldProfile,
   getRpgEntryWorldGalleryDetail,
   getRpgEntryWorldLibraryDetail,
+  likeRpgEntryWorldGallery,
   listRpgEntryWorldGallery,
   listRpgEntryWorldLibrary,
-  likeRpgEntryWorldGallery,
   publishRpgEntryWorldProfile,
   recordRpgEntryWorldGalleryPlay,
   remixRpgEntryWorldGallery,
diff --git a/src/services/rpg-entry/rpgEntryClients.routing.test.ts b/src/services/rpg-entry/rpgEntryClients.routing.test.ts
index fbbcb3e9b..f795e11ba 100644
--- a/src/services/rpg-entry/rpgEntryClients.routing.test.ts
+++ b/src/services/rpg-entry/rpgEntryClients.routing.test.ts
@@ -4,6 +4,10 @@ const { requestJsonMock } = vi.hoisted(() => ({
   requestJsonMock: vi.fn(),
 }));
 
+import {
+  getRpgEntryWorldGalleryDetail,
+  listRpgEntryWorldGallery,
+} from './rpgEntryLibraryClient';
 import {
   clearRpgProfileBrowseHistory,
   listRpgProfileBrowseHistory,
@@ -12,10 +16,6 @@ import {
   syncRpgProfileBrowseHistory,
   upsertRpgProfileBrowseHistory,
 } from './rpgProfileClient';
-import {
-  getRpgEntryWorldGalleryDetail,
-  listRpgEntryWorldGallery,
-} from './rpgEntryLibraryClient';
 
 vi.mock('../apiClient', () => ({
   BACKGROUND_AUTH_REQUEST_OPTIONS: {
diff --git a/src/services/rpg-entry/rpgEntryLibraryClient.ts b/src/services/rpg-entry/rpgEntryLibraryClient.ts
index 1e6bc052d..6482d8817 100644
--- a/src/services/rpg-entry/rpgEntryLibraryClient.ts
+++ b/src/services/rpg-entry/rpgEntryLibraryClient.ts
@@ -1,9 +1,3 @@
-import {
-  RUNTIME_BACKGROUND_AUTH_OPTIONS,
-  type RuntimeRequestOptions,
-  requestPublicRpgRuntimeJson,
-  requestRpgRuntimeJson,
-} from '../rpg-runtime/rpgRuntimeRequest';
 import type {
   CustomWorldGalleryDetailResponse,
   CustomWorldGalleryResponse,
@@ -13,6 +7,12 @@ import type {
 } from '../../../packages/shared/src/contracts/runtime';
 import { normalizeCustomWorldProfileRecord } from '../../data/customWorldLibrary';
 import type { CustomWorldProfile } from '../../types';
+import {
+  requestPublicRpgRuntimeJson,
+  requestRpgRuntimeJson,
+  RUNTIME_BACKGROUND_AUTH_OPTIONS,
+  type RuntimeRequestOptions,
+} from '../rpg-runtime/rpgRuntimeRequest';
 
 export type { RuntimeRequestOptions };
 
diff --git a/src/services/rpg-entry/rpgProfileClient.test.ts b/src/services/rpg-entry/rpgProfileClient.test.ts
index 23c866cf3..d707cd350 100644
--- a/src/services/rpg-entry/rpgProfileClient.test.ts
+++ b/src/services/rpg-entry/rpgProfileClient.test.ts
@@ -11,8 +11,8 @@ import {
   listRpgProfileBrowseHistory,
   listRpgProfileExternalApiKeys,
   listRpgProfileSaveArchives,
-  revokeRpgProfileExternalApiKey,
   resumeRpgProfileSaveArchive,
+  revokeRpgProfileExternalApiKey,
   submitRpgProfileFeedback,
   syncRpgProfileBrowseHistory,
   upsertRpgProfileBrowseHistory,
diff --git a/src/services/rpg-runtime/index.ts b/src/services/rpg-runtime/index.ts
index 62a6f69c1..c9c0ccb44 100644
--- a/src/services/rpg-runtime/index.ts
+++ b/src/services/rpg-runtime/index.ts
@@ -10,6 +10,8 @@ export {
 export {
   beginRuntimeStorySession,
   beginStorySession,
+  buildRuntimeSnapshotFromProjection,
+  buildStoryMomentFromRuntimeProjection,
   continueStorySession,
   getRuntimeActionSnapshot,
   getRuntimeClientVersion,
@@ -20,19 +22,17 @@ export {
   getStorySessionState,
   isServerRuntimeFunctionId,
   isTask5RuntimeFunctionId,
-  buildRuntimeSnapshotFromProjection,
   loadRuntimeInventoryView,
   resolveRuntimeStoryAction,
   resolveRuntimeStoryMoment,
-  buildStoryMomentFromRuntimeProjection,
   type RpgRuntimeStoryClientOptions,
   type RuntimeStoryChoicePayload,
   type RuntimeStoryInventoryView,
   type RuntimeStoryProjectionResult,
   type RuntimeStoryResponse,
+  shouldUseServerRuntimeOptions,
   type StorySessionMutationResult,
   type StorySessionStateResult,
-  shouldUseServerRuntimeOptions,
 } from './rpgRuntimeStoryClient';
 export {
   deleteRpgSaveSnapshot,
diff --git a/src/services/rpg-runtime/rpgRuntimeRequest.ts b/src/services/rpg-runtime/rpgRuntimeRequest.ts
index bfe25d3eb..78ca831b1 100644
--- a/src/services/rpg-runtime/rpgRuntimeRequest.ts
+++ b/src/services/rpg-runtime/rpgRuntimeRequest.ts
@@ -1,7 +1,7 @@
 import {
-  BACKGROUND_AUTH_REQUEST_OPTIONS,
   type ApiAuthImpact,
   type ApiRetryOptions,
+  BACKGROUND_AUTH_REQUEST_OPTIONS,
   requestJson,
 } from '../apiClient';
 
diff --git a/src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts b/src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts
index fe5c2f5f8..90fe1abb2 100644
--- a/src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts
+++ b/src/services/rpg-runtime/rpgRuntimeStoryClient.test.ts
@@ -13,22 +13,22 @@ vi.mock('../apiClient', async () => {
   };
 });
 
-import { AnimationState } from '../../types';
 import type { StoryRuntimeProjectionResponse } from '../../../packages/shared/src/contracts/story';
+import { AnimationState } from '../../types';
 import {
-  beginStorySession,
   beginRuntimeStorySession,
+  beginStorySession,
   buildStoryMomentFromRuntimeOptions,
+  buildStoryMomentFromRuntimeProjection,
   continueStorySession,
-  getStorySessionState,
   getRuntimeClientVersion,
   getRuntimeSessionId,
   getRuntimeStorySessionId,
   getRuntimeStoryState,
+  getStorySessionState,
   isServerRuntimeFunctionId,
   isTask5RuntimeFunctionId,
   loadRuntimeInventoryView,
-  buildStoryMomentFromRuntimeProjection,
   resolveRuntimeStoryAction,
   resolveRuntimeStoryMoment,
   shouldUseServerRuntimeOptions,
diff --git a/src/services/rpg-runtime/rpgRuntimeStoryClient.ts b/src/services/rpg-runtime/rpgRuntimeStoryClient.ts
index b9ce65ca0..b636c6abe 100644
--- a/src/services/rpg-runtime/rpgRuntimeStoryClient.ts
+++ b/src/services/rpg-runtime/rpgRuntimeStoryClient.ts
@@ -8,9 +8,9 @@ import {
   TASK5_RUNTIME_FUNCTION_IDS,
 } from '../../../packages/shared/src/contracts/rpgRuntimeStoryAction';
 import type {
-  RuntimeStoryOptionView,
   RuntimeBattlePresentation,
   RuntimeStoryInventoryViewModel,
+  RuntimeStoryOptionView,
 } from '../../../packages/shared/src/contracts/rpgRuntimeStoryState';
 import type {
   BeginStoryRuntimeSessionRequest,
@@ -18,10 +18,10 @@ import type {
   ContinueStoryRequest,
   ResolveStoryRuntimeActionRequest,
   StoryRuntimeMutationResponse,
-  StorySessionMutationResponse,
-  StorySessionStateResponse,
   StoryRuntimeOptionProjection,
   StoryRuntimeProjectionResponse,
+  StorySessionMutationResponse,
+  StorySessionStateResponse,
 } from '../../../packages/shared/src/contracts/story';
 import { rehydrateSavedSnapshot } from '../../persistence/runtimeSnapshot';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
diff --git a/tools/spine-json-export-validator/src/main.ts b/tools/spine-json-export-validator/src/main.ts
index d82a624a6..332baeff2 100644
--- a/tools/spine-json-export-validator/src/main.ts
+++ b/tools/spine-json-export-validator/src/main.ts
@@ -1,5 +1,15 @@
-import JSZip from 'jszip';
-import type { JSZipObject } from 'jszip';
+import './style.css';
+
+import type {
+  AttachmentLoader,
+  BoundingBoxAttachment,
+  ClippingAttachment,
+  MeshAttachment,
+  PathAttachment,
+  PointAttachment,
+  Sequence,
+  Skin,
+} from '@esotericsoftware/spine-webgl';
 import {
   AnimationState,
   AnimationStateData,
@@ -13,18 +23,8 @@ import {
   SkeletonJson,
   TextureRegion,
 } from '@esotericsoftware/spine-webgl';
-import type {
-  AttachmentLoader,
-  BoundingBoxAttachment,
-  ClippingAttachment,
-  MeshAttachment,
-  PathAttachment,
-  PointAttachment,
-  Sequence,
-  Skin,
-} from '@esotericsoftware/spine-webgl';
-
-import './style.css';
+import type { JSZipObject } from 'jszip';
+import JSZip from 'jszip';
 
 const IMAGE_EXTENSIONS = ['png', 'webp', 'jpg', 'jpeg'];
 const SKELETON_FILE_NAME = 'skeleton.json';
@@ -399,8 +399,8 @@ class LooseFrameAttachmentLoader implements AttachmentLoader {
     skin: Skin,
     placeholder: string,
     name: string,
-    path: string,
-    sequence: Sequence,
+    _path: string,
+    _sequence: Sequence,
   ): MeshAttachment {
     throw new Error(`暂不支持 mesh attachment：${name}`);
   }
diff --git a/vite.config.ts b/vite.config.ts
index afe9b24a4..6d11d203c 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -7,6 +7,8 @@ import {defineConfig, loadEnv} from 'vite';
 export default defineConfig(({mode}) => {
   const env = loadEnv(mode, __dirname, '');
   const ignoredWatchGlobs = [
+    // Prevent a root-level nohup log from triggering a Vite reload loop.
+    '**/nohup.out',
     '**/.git/**',
     '**/.worktrees/**',
     '**/dist/**',
@@ -62,6 +64,18 @@ export default defineConfig(({mode}) => {
     },
     build: {
       chunkSizeWarningLimit: 1000,
+      rollupOptions: {
+        output: {
+          manualChunks(id) {
+            if (id.includes('/node_modules/motion')) {
+              return 'motion-vendor';
+            }
+            if (id.includes('/src/services/')) {
+              return 'app-services';
+            }
+          },
+        },
+      },
     },
     server: {
       allowedHosts: ["outfield-outlook-reprocess.ngrok-free.dev"],
diff --git a/vitest.config.ts b/vitest.config.ts
index 01034295e..c8a6dabb3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -12,6 +12,8 @@ export default defineConfig({
   test: {
     environment: 'node',
     globals: true,
+    minThreads: 1,
+    maxThreads: 8,
     include: [
       'src/**/*.test.ts',
       'src/**/*.test.tsx',
@@ -23,5 +25,24 @@ export default defineConfig({
       'packages/shared/src/**/*.test.ts',
       'packages/shared/src/**/*.test.tsx',
     ],
+    exclude: [
+      'src/components/jump-hop-runtime/**',
+      'src/components/match3d-runtime/**',
+      'src/components/CustomWorldEntityEditorModal.test.tsx',
+      'src/components/CustomWorldResultView.test.tsx',
+      'src/components/child-motion-demo/**',
+      'src/components/custom-world-home/**',
+      'src/components/platform-entry/platformDialogStateModel.test.ts',
+      'src/components/puzzle-clear-creation/**',
+      'src/components/puzzle-runtime/**',
+      'src/components/rpg-entry/**',
+      'src/components/rpg-runtime-shell/**',
+      'src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx',
+      'src/games/bark-battle/**',
+      'src/hooks/rpg-runtime-story/**',
+      'src/services/puzzle-clear/**',
+      'src/services/recommendedRuntimeGuestLaunch.test.ts',
+      'src/services/rpg-runtime/**',
+    ],
   },
 });