From 0b766c8bf9c2d6916569bfeb1938bf26b6d28f96 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 14:10:16 +0800
Subject: [PATCH 01/24] =?UTF-8?q?=E7=BB=9F=E4=B8=80=E9=9F=B3=E9=A2=91?=
 =?UTF-8?q?=E7=B4=A0=E6=9D=90=E5=B0=81=E9=9D=A2=E7=BC=A9=E7=95=A5=E5=9B=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增音频素材统一封面图。
素材库、创作主页精选和后台缩略图改为使用音频封面。
补充音频封面展示回归测试。
---
 .../pages/AdminEditorAssetQueryPage.test.tsx  | 107 ++++++----
 .../src/pages/AdminEditorAssetQueryPage.tsx   |  43 ++--
 .../AdminEditorShowcaseReviewPage.test.tsx    |  73 +++++--
 .../pages/AdminEditorShowcaseReviewPage.tsx   |  65 +++---
 public/creation-home/audio-asset-cover.svg    |  19 ++
 .../CreationLandingView.test.tsx              |  97 ++++++---
 .../creation-home/CreationLandingView.tsx     | 199 +++++++++++-------
 .../creationShowcaseModel.test.ts             |   3 +
 .../creation-home/creationShowcaseModel.ts    | 127 ++++++++---
 .../ImageCanvasAssetRowView.test.tsx          | 118 +++++++----
 .../image-editor/ImageCanvasAssetRowView.tsx  |  35 +--
 src/index.css                                 | 192 +++++++++++------
 12 files changed, 717 insertions(+), 361 deletions(-)
 create mode 100644 public/creation-home/audio-asset-cover.svg

diff --git a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
index 9c7612f3d..3d075d2ed 100644
--- a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
@@ -1,14 +1,20 @@
 /* @vitest-environment jsdom */
 
-import {fireEvent, render, screen, waitFor, within} from '@testing-library/react';
-import {beforeEach, expect, test, vi} from 'vitest';
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { beforeEach, expect, test, vi } from 'vitest';
 
 import {
   getAdminAssetReadUrl,
   listAdminEditorAssets,
 } from '../api/adminApiClient';
-import type {AdminEditorAssetPayload} from '../api/adminApiTypes';
-import {AdminEditorAssetQueryPage} from './AdminEditorAssetQueryPage';
+import type { AdminEditorAssetPayload } from '../api/adminApiTypes';
+import { AdminEditorAssetQueryPage } from './AdminEditorAssetQueryPage';
 
 vi.mock('../api/adminApiClient', () => ({
   getAdminAssetReadUrl: vi.fn(),
@@ -34,7 +40,7 @@ const generatedAsset: AdminEditorAssetPayload = {
   provider: 'character',
   taskId: 'task-1',
   assetKind: 'character',
-  generationInputs: {style: 'clay'},
+  generationInputs: { style: 'clay' },
   sourceResourceId: 'resource-1',
   thumbnailSrc: null,
   generationCostMudPoints: 12,
@@ -60,10 +66,7 @@ beforeEach(() => {
 
 test('后台素材查询展示作者昵称和陶泥号', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
   expect(await screen.findByText('作者昵称')).toBeTruthy();
@@ -73,25 +76,22 @@ test('后台素材查询展示作者昵称和陶泥号', async () => {
 
 test('后台素材查询按用户、搜索和时间调用查询接口', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
-  await screen.findByRole('img', {name: '素材：角色形象 1'});
+  await screen.findByRole('img', { name: '素材：角色形象 1' });
 
   fireEvent.change(screen.getByLabelText('用户 ID'), {
-    target: {value: 'user-1'},
+    target: { value: 'user-1' },
   });
   fireEvent.change(screen.getByLabelText('搜索'), {
-    target: {value: '陶泥角色'},
+    target: { value: '陶泥角色' },
   });
   fireEvent.change(screen.getByLabelText('开始时间'), {
-    target: {value: '2026-07-01'},
+    target: { value: '2026-07-01' },
   });
   fireEvent.change(screen.getByLabelText('结束时间'), {
-    target: {value: '2026-07-04'},
+    target: { value: '2026-07-04' },
   });
 
   await waitFor(() => {
@@ -107,26 +107,20 @@ test('后台素材查询按用户、搜索和时间调用查询接口', async ()
 
 test('后台素材查询不展示分类筛选和分类列', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
   expect(await screen.findByText('角色形象 1')).toBeTruthy();
   expect(screen.queryByLabelText('分类')).toBeNull();
-  expect(screen.queryByRole('columnheader', {name: '分类'})).toBeNull();
+  expect(screen.queryByRole('columnheader', { name: '分类' })).toBeNull();
 });
 
 test('后台素材查询缩略图使用 objectKey 换签后展示', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
-  const image = await screen.findByRole('img', {name: '素材：角色形象 1'});
+  const image = await screen.findByRole('img', { name: '素材：角色形象 1' });
 
   await waitFor(() => {
     expect(image.getAttribute('src')).toBe(
@@ -139,6 +133,32 @@ test('后台素材查询缩略图使用 objectKey 换签后展示', async () =>
   });
 });
 
+test('后台素材查询音频素材使用统一封面缩略图', async () => {
+  vi.mocked(listAdminEditorAssets).mockResolvedValueOnce({
+    entries: [
+      {
+        ...generatedAsset,
+        assetId: 'asset-audio-1',
+        label: '胜利音效',
+        imageSrc: '/generated-editor-audios/sfx.mp3',
+        objectKey: 'generated-editor-audios/sfx.mp3',
+        assetKind: 'sound-effect',
+      },
+    ],
+    nextCursor: null,
+  });
+
+  render(
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
+  );
+
+  const image = await screen.findByRole('img', { name: '素材：胜利音效' });
+  expect(image.getAttribute('src')).toBe(
+    '/creation-home/audio-asset-cover.svg',
+  );
+  expect(getAdminAssetReadUrl).not.toHaveBeenCalled();
+});
+
 test('后台素材查询格式化微秒时间文本', async () => {
   vi.mocked(listAdminEditorAssets).mockResolvedValueOnce({
     entries: [
@@ -152,10 +172,7 @@ test('后台素材查询格式化微秒时间文本', async () => {
   });
 
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
   expect(await screen.findByText('角色形象 1')).toBeTruthy();
@@ -164,15 +181,12 @@ test('后台素材查询格式化微秒时间文本', async () => {
 
 test('后台素材查询可查看素材详情', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
-  fireEvent.click(await screen.findByRole('button', {name: '详情'}));
+  fireEvent.click(await screen.findByRole('button', { name: '详情' }));
 
-  const dialog = screen.getByRole('dialog', {name: '素材详情'});
+  const dialog = screen.getByRole('dialog', { name: '素材详情' });
   expect(within(dialog).getByText('asset-1')).toBeTruthy();
   expect(within(dialog).getByText('1024 x 1024')).toBeTruthy();
   expect(within(dialog).getByText('12 泥点')).toBeTruthy();
@@ -181,20 +195,21 @@ test('后台素材查询可查看素材详情', async () => {
 
 test('后台素材查询可打开弹窗查看完整提示词', async () => {
   render(
-    <AdminEditorAssetQueryPage
-      token="admin-token"
-      onUnauthorized={vi.fn()}
-    />,
+    <AdminEditorAssetQueryPage token="admin-token" onUnauthorized={vi.fn()} />,
   );
 
-  fireEvent.click(await screen.findByRole('button', {name: '完整提示词内容'}));
+  fireEvent.click(
+    await screen.findByRole('button', { name: '完整提示词内容' }),
+  );
 
-  const dialog = screen.getByRole('dialog', {name: '完整提示词'});
+  const dialog = screen.getByRole('dialog', { name: '完整提示词' });
   expect(within(dialog).getByText('完整提示词内容')).toBeTruthy();
 
-  fireEvent.click(within(dialog).getByRole('button', {name: '关闭完整提示词'}));
+  fireEvent.click(
+    within(dialog).getByRole('button', { name: '关闭完整提示词' }),
+  );
 
   await waitFor(() => {
-    expect(screen.queryByRole('dialog', {name: '完整提示词'})).toBeNull();
+    expect(screen.queryByRole('dialog', { name: '完整提示词' })).toBeNull();
   });
 });
diff --git a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
index b5b705e9a..50f588c25 100644
--- a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
@@ -1,17 +1,17 @@
-import {Eye, FileText, RefreshCcw, X} from 'lucide-react';
-import type {ReactNode} from 'react';
-import {useEffect, useState} from 'react';
+import { Eye, FileText, RefreshCcw, X } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { useEffect, useState } from 'react';
 
 import {
   getAdminAssetReadUrl,
   listAdminEditorAssets,
 } from '../api/adminApiClient';
-import type {AdminAssetReadUrlResponse} from '../api/adminApiClient';
+import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import type {
   AdminEditorAssetListQuery,
   AdminEditorAssetPayload,
 } from '../api/adminApiTypes';
-import {handlePageError} from './pageUtils';
+import { handlePageError } from './pageUtils';
 
 interface AdminEditorAssetQueryPageProps {
   token: string;
@@ -19,6 +19,7 @@ interface AdminEditorAssetQueryPageProps {
 }
 
 const ADMIN_ASSET_READ_EXPIRE_SECONDS = 300;
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
 
 export function AdminEditorAssetQueryPage({
   token,
@@ -274,10 +275,11 @@ export function AdminEditorAssetQueryPage({
   );
 }
 
-function AdminAssetThumbnail({entry}: {entry: AdminEditorAssetPayload}) {
+function AdminAssetThumbnail({ entry }: { entry: AdminEditorAssetPayload }) {
+  const isAudio = isAdminAudioAsset(entry);
   const imageSrc = useAdminResolvedAssetImageSrc(
-    entry.thumbnailSrc || entry.imageSrc,
-    entry.objectKey,
+    isAudio ? AUDIO_ASSET_COVER_SRC : entry.thumbnailSrc || entry.imageSrc,
+    isAudio ? null : entry.objectKey,
   );
   const alt = `素材：${entry.label || entry.assetId}`;
 
@@ -288,6 +290,16 @@ function AdminAssetThumbnail({entry}: {entry: AdminEditorAssetPayload}) {
   );
 }
 
+function isAdminAudioAsset(entry: AdminEditorAssetPayload) {
+  const assetKind = entry.assetKind?.trim() ?? '';
+  return (
+    assetKind === 'sound-effect' ||
+    assetKind === 'background-music' ||
+    assetKind === 'editor_uploaded_audio' ||
+    /\.(?:mp3|wav|m4a|aac|ogg)(?:$|[?#])/iu.test(entry.imageSrc.trim())
+  );
+}
+
 function AdminAssetDetailDialog({
   entry,
   onClose,
@@ -334,7 +346,9 @@ function AdminAssetDetailDialog({
               {entry.generationCostMudPoints} 泥点
             </AdminInfoItem>
             <AdminInfoItem label="模型">{entry.model || '-'}</AdminInfoItem>
-            <AdminInfoItem label="Provider">{entry.provider || '-'}</AdminInfoItem>
+            <AdminInfoItem label="Provider">
+              {entry.provider || '-'}
+            </AdminInfoItem>
             <AdminInfoItem label="Task ID">{entry.taskId || '-'}</AdminInfoItem>
             <AdminInfoItem label="Object Key">
               {entry.objectKey || '-'}
@@ -463,7 +477,8 @@ function mergeAssetEntries(
   [...current, ...incoming].forEach((entry) => byId.set(entry.assetId, entry));
   return [...byId.values()].sort(
     (left, right) =>
-      parseAdminTimestamp(right.createdAt) - parseAdminTimestamp(left.createdAt) ||
+      parseAdminTimestamp(right.createdAt) -
+        parseAdminTimestamp(left.createdAt) ||
       right.assetId.localeCompare(left.assetId),
   );
 }
@@ -505,13 +520,13 @@ function parseAdminTimestamp(value: string | null | undefined) {
 
 function authorDisplayName(entry: AdminEditorAssetPayload) {
   return (
-    entry.authorDisplayName?.trim() ||
-    entry.authorPublicUserCode?.trim() ||
-    '-'
+    entry.authorDisplayName?.trim() || entry.authorPublicUserCode?.trim() || '-'
   );
 }
 
-function formatGenerationInputs(value: Record<string, unknown> | null | undefined) {
+function formatGenerationInputs(
+  value: Record<string, unknown> | null | undefined,
+) {
   if (!value) {
     return '-';
   }
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
index f67e00914..ac11c94bd 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
@@ -1,7 +1,13 @@
 /* @vitest-environment jsdom */
 
-import {fireEvent, render, screen, waitFor, within} from '@testing-library/react';
-import {beforeEach, expect, test, vi} from 'vitest';
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { beforeEach, expect, test, vi } from 'vitest';
 
 import {
   getAdminAssetReadUrl,
@@ -11,8 +17,8 @@ import {
   updateAdminEditorShowcaseDisplay,
   upsertAdminEditorShowcaseCampaign,
 } from '../api/adminApiClient';
-import type {AdminEditorShowcaseAssetPayload} from '../api/adminApiTypes';
-import {AdminEditorShowcaseReviewPage} from './AdminEditorShowcaseReviewPage';
+import type { AdminEditorShowcaseAssetPayload } from '../api/adminApiTypes';
+import { AdminEditorShowcaseReviewPage } from './AdminEditorShowcaseReviewPage';
 
 vi.mock('../api/adminApiClient', () => ({
   getAdminAssetReadUrl: vi.fn(),
@@ -40,7 +46,7 @@ const pendingShowcaseAsset: AdminEditorShowcaseAssetPayload = {
   provider: 'character',
   taskId: 'task-1',
   assetKind: 'character',
-  generationInputs: {style: 'clay'},
+  generationInputs: { style: 'clay' },
   generationCostMudPoints: 12,
   refundMudPoints: 6,
   reviewStatus: 'pending',
@@ -169,6 +175,36 @@ test('后台精选审核格式化微秒时间并显示素材名', async () => {
   expect(screen.queryByText('1783231493.573727Z')).toBeNull();
 });
 
+test('后台精选审核音频素材使用统一封面缩略图', async () => {
+  vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
+    entries: [
+      {
+        ...pendingShowcaseAsset,
+        showcaseId: 'showcase-audio-1',
+        assetId: 'asset-audio-1',
+        label: '胜利音效',
+        imageSrc: '/generated-editor-audios/sfx.mp3',
+        objectKey: 'generated-editor-audios/sfx.mp3',
+        assetKind: 'sound-effect',
+      },
+    ],
+    nextCursor: null,
+  });
+
+  render(
+    <AdminEditorShowcaseReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  const image = await screen.findByRole('img', { name: '精选素材：胜利音效' });
+  expect(image.getAttribute('src')).toBe(
+    '/creation-home/audio-asset-cover.svg',
+  );
+  expect(getAdminAssetReadUrl).not.toHaveBeenCalled();
+});
+
 test('后台精选审核可以通过素材并查看完整提示词', async () => {
   render(
     <AdminEditorShowcaseReviewPage
@@ -177,11 +213,10 @@ test('后台精选审核可以通过素材并查看完整提示词', async () =>
     />,
   );
 
-  fireEvent.change(
-    await screen.findByLabelText('审核备注：角色形象 1'),
-    {target: {value: '质量通过'}},
-  );
-  fireEvent.click(screen.getByRole('button', {name: '通过'}));
+  fireEvent.change(await screen.findByLabelText('审核备注：角色形象 1'), {
+    target: { value: '质量通过' },
+  });
+  fireEvent.click(screen.getByRole('button', { name: '通过' }));
 
   await waitFor(() => {
     expect(reviewAdminEditorShowcaseAsset).toHaveBeenCalledWith('admin-token', {
@@ -191,8 +226,8 @@ test('后台精选审核可以通过素材并查看完整提示词', async () =>
     });
   });
 
-  fireEvent.click(screen.getByRole('button', {name: '完整提示词内容'}));
-  const dialog = screen.getByRole('dialog', {name: '完整提示词'});
+  fireEvent.click(screen.getByRole('button', { name: '完整提示词内容' }));
+  const dialog = screen.getByRole('dialog', { name: '完整提示词' });
   expect(within(dialog).getByText('完整提示词内容')).toBeTruthy();
 });
 
@@ -209,7 +244,7 @@ test('后台精选审核可以切换展示和保存活动卡', async () => {
     />,
   );
 
-  fireEvent.click(await screen.findByRole('button', {name: '隐藏'}));
+  fireEvent.click(await screen.findByRole('button', { name: '隐藏' }));
   await waitFor(() => {
     expect(updateAdminEditorShowcaseDisplay).toHaveBeenCalledWith(
       'admin-token',
@@ -222,15 +257,15 @@ test('后台精选审核可以切换展示和保存活动卡', async () => {
   });
 
   fireEvent.change(await screen.findByLabelText('标题'), {
-    target: {value: '新活动卡'},
+    target: { value: '新活动卡' },
   });
   fireEvent.change(screen.getByLabelText('图片地址'), {
-    target: {value: '/new-campaign.png'},
+    target: { value: '/new-campaign.png' },
   });
   fireEvent.change(screen.getByLabelText('成本文案'), {
-    target: {value: '6 泥点'},
+    target: { value: '6 泥点' },
   });
-  fireEvent.click(screen.getByRole('button', {name: '保存活动卡'}));
+  fireEvent.click(screen.getByRole('button', { name: '保存活动卡' }));
 
   await waitFor(() => {
     expect(upsertAdminEditorShowcaseCampaign).toHaveBeenCalledWith(
@@ -271,7 +306,7 @@ test('后台精选审核已通过素材可以设置精选分类', async () => {
   );
 
   fireEvent.change(await screen.findByLabelText('精选分类：角色形象 2'), {
-    target: {value: 'ui'},
+    target: { value: 'ui' },
   });
 
   await waitFor(() => {
@@ -307,7 +342,7 @@ test('后台精选审核清空精选分类时自动隐藏素材', async () => {
   );
 
   fireEvent.change(await screen.findByLabelText('精选分类：角色形象 2'), {
-    target: {value: ''},
+    target: { value: '' },
   });
 
   await waitFor(() => {
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
index f3fbd561c..302d4d074 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
@@ -1,6 +1,6 @@
-import {Eye, FileText, RefreshCcw, X} from 'lucide-react';
-import type {ReactNode} from 'react';
-import {useEffect, useState} from 'react';
+import { Eye, FileText, RefreshCcw, X } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { useEffect, useState } from 'react';
 
 import {
   getAdminAssetReadUrl,
@@ -10,13 +10,13 @@ import {
   updateAdminEditorShowcaseDisplay,
   upsertAdminEditorShowcaseCampaign,
 } from '../api/adminApiClient';
-import type {AdminAssetReadUrlResponse} from '../api/adminApiClient';
+import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import type {
   AdminEditorShowcaseAssetPayload,
   AdminEditorShowcaseCampaignPayload,
   AdminEditorShowcaseListQuery,
 } from '../api/adminApiTypes';
-import {handlePageError} from './pageUtils';
+import { handlePageError } from './pageUtils';
 
 interface AdminEditorShowcaseReviewPageProps {
   token: string;
@@ -24,20 +24,21 @@ interface AdminEditorShowcaseReviewPageProps {
 }
 
 const ADMIN_SHOWCASE_READ_EXPIRE_SECONDS = 300;
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
 
 const showcaseCategoryOptions = [
-  {value: 'packs', label: '素材包'},
-  {value: 'characters', label: '角色'},
-  {value: 'ui', label: 'UI'},
-  {value: 'music', label: '音乐'},
-  {value: 'marketing', label: '美宣'},
+  { value: 'packs', label: '素材包' },
+  { value: 'characters', label: '角色' },
+  { value: 'ui', label: 'UI' },
+  { value: 'music', label: '音乐' },
+  { value: 'marketing', label: '美宣' },
 ];
 
 const reviewStatusOptions = [
-  {value: '', label: '全部'},
-  {value: 'pending', label: '待审核'},
-  {value: 'approved', label: '已通过'},
-  {value: 'rejected', label: '已拒绝'},
+  { value: '', label: '全部' },
+  { value: 'pending', label: '待审核' },
+  { value: 'approved', label: '已通过' },
+  { value: 'rejected', label: '已拒绝' },
 ];
 
 export function AdminEditorShowcaseReviewPage({
@@ -314,9 +315,7 @@ export function AdminEditorShowcaseReviewPage({
                       </button>
                       <small>{entry.label || '-'}</small>
                     </td>
-                    <td>
-                      {formatDateTime(entry.submittedAt)}
-                    </td>
+                    <td>{formatDateTime(entry.submittedAt)}</td>
                     <td>
                       {authorDisplayName(entry)}
                       <small>{entry.authorPublicUserCode?.trim() || '-'}</small>
@@ -342,7 +341,9 @@ export function AdminEditorShowcaseReviewPage({
                       )}
                     </td>
                     <td>
-                      <span className={reviewStatusClassName(entry.reviewStatus)}>
+                      <span
+                        className={reviewStatusClassName(entry.reviewStatus)}
+                      >
                         {reviewStatusLabel(entry.reviewStatus)}
                       </span>
                       {entry.reviewStatus === 'approved' ? (
@@ -589,7 +590,11 @@ function AdminShowcaseThumbnail({
 }: {
   entry: AdminEditorShowcaseAssetPayload;
 }) {
-  const imageSrc = useAdminResolvedAssetImageSrc(entry.imageSrc, entry.objectKey);
+  const isAudio = isAdminShowcaseAudioAsset(entry);
+  const imageSrc = useAdminResolvedAssetImageSrc(
+    isAudio ? AUDIO_ASSET_COVER_SRC : entry.imageSrc,
+    isAudio ? null : entry.objectKey,
+  );
   const alt = `精选素材：${entry.label || entry.showcaseId}`;
 
   return imageSrc ? (
@@ -599,6 +604,16 @@ function AdminShowcaseThumbnail({
   );
 }
 
+function isAdminShowcaseAudioAsset(entry: AdminEditorShowcaseAssetPayload) {
+  const assetKind = entry.assetKind?.trim() ?? '';
+  return (
+    assetKind === 'sound-effect' ||
+    assetKind === 'background-music' ||
+    assetKind === 'editor_uploaded_audio' ||
+    /\.(?:mp3|wav|m4a|aac|ogg)(?:$|[?#])/iu.test(entry.imageSrc.trim())
+  );
+}
+
 function AdminShowcaseDetailDialog({
   entry,
   onClose,
@@ -659,7 +674,9 @@ function AdminShowcaseDetailDialog({
             </AdminInfoItem>
             <AdminInfoItem label="点赞数">{entry.likeCount}</AdminInfoItem>
             <AdminInfoItem label="模型">{entry.model || '-'}</AdminInfoItem>
-            <AdminInfoItem label="Provider">{entry.provider || '-'}</AdminInfoItem>
+            <AdminInfoItem label="Provider">
+              {entry.provider || '-'}
+            </AdminInfoItem>
             <AdminInfoItem label="Task ID">{entry.taskId || '-'}</AdminInfoItem>
             <AdminInfoItem label="Object Key">
               {entry.objectKey || '-'}
@@ -869,13 +886,13 @@ function reviewStatusClassName(value: string) {
 
 function authorDisplayName(entry: AdminEditorShowcaseAssetPayload) {
   return (
-    entry.authorDisplayName?.trim() ||
-    entry.authorPublicUserCode?.trim() ||
-    '-'
+    entry.authorDisplayName?.trim() || entry.authorPublicUserCode?.trim() || '-'
   );
 }
 
-function formatGenerationInputs(value: Record<string, unknown> | null | undefined) {
+function formatGenerationInputs(
+  value: Record<string, unknown> | null | undefined,
+) {
   if (!value) {
     return '-';
   }
diff --git a/public/creation-home/audio-asset-cover.svg b/public/creation-home/audio-asset-cover.svg
new file mode 100644
index 000000000..0e96909aa
--- /dev/null
+++ b/public/creation-home/audio-asset-cover.svg
@@ -0,0 +1,19 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 256 256"
+  role="img"
+  aria-label="音频素材"
+>
+  <g
+    fill="none"
+    stroke="#dc7f58"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    stroke-width="16"
+  >
+    <path d="M92 185V35l152-24v149" />
+    <path d="M92 87l152-24" />
+    <ellipse cx="53" cy="207" rx="41" ry="24" transform="rotate(4 53 207)" />
+    <ellipse cx="201" cy="193" rx="41" ry="24" transform="rotate(-4 201 193)" />
+  </g>
+</svg>
diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
index 82449027e..b80a8d7f6 100644
--- a/src/components/creation-home/CreationLandingView.test.tsx
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -125,12 +125,10 @@ function installIntersectionObserverMock() {
   return observers;
 }
 
-function triggerIntersection(
-  observer: {
-    callback: IntersectionObserverCallback;
-    instance: IntersectionObserver;
-  },
-) {
+function triggerIntersection(observer: {
+  callback: IntersectionObserverCallback;
+  instance: IntersectionObserver;
+}) {
   act(() => {
     observer.callback(
       [{ isIntersecting: true } as IntersectionObserverEntry],
@@ -157,15 +155,15 @@ describe('CreationLandingView', () => {
 
     renderCreationLanding();
 
-    expect(
-      screen.getByRole('main', { name: '陶泥儿创作主页' }),
-    ).toBeTruthy();
+    expect(screen.getByRole('main', { name: '陶泥儿创作主页' })).toBeTruthy();
     expect(
       screen.getByRole('heading', {
         name: '陶泥儿 - 开启全民精品游戏创作',
       }),
     ).toBeTruthy();
-    expect(screen.getByText('登录即送100泥点，可以免费制作50个素材')).toBeTruthy();
+    expect(
+      screen.getByText('登录即送100泥点，可以免费制作50个素材'),
+    ).toBeTruthy();
     expect(screen.getByRole('heading', { name: '创作工具' })).toBeTruthy();
     expect(screen.getByText('游戏视觉规范')).toBeTruthy();
     expect(screen.getByRole('heading', { name: '陶泥儿精选' })).toBeTruthy();
@@ -193,7 +191,9 @@ describe('CreationLandingView', () => {
       </AuthUiContext.Provider>,
     );
 
-    expect(await screen.findByRole('heading', { name: '最近项目' })).toBeTruthy();
+    expect(
+      await screen.findByRole('heading', { name: '最近项目' }),
+    ).toBeTruthy();
     expect(screen.getByText('最新项目')).toBeTruthy();
     expect(screen.getByText('旧项目')).toBeTruthy();
     await user.click(screen.getByRole('button', { name: '查看全部' }));
@@ -302,10 +302,7 @@ describe('CreationLandingView', () => {
 
     render(
       <AuthUiContext.Provider value={createAuthValue()}>
-        <CreationLandingView
-          onOpenProject={vi.fn()}
-          onOpenProjects={vi.fn()}
-        />
+        <CreationLandingView onOpenProject={vi.fn()} onOpenProjects={vi.fn()} />
       </AuthUiContext.Provider>,
     );
 
@@ -375,9 +372,13 @@ describe('CreationLandingView', () => {
     const assetCard = await screen.findByText('角色英雄');
     const card = assetCard.closest('.creation-landing__asset-card');
     expect(card).toBeTruthy();
-    expect(within(card as HTMLElement).getByText('character hero prompt')).toBeTruthy();
+    expect(
+      within(card as HTMLElement).getByText('character hero prompt'),
+    ).toBeTruthy();
     expect(within(card as HTMLElement).getByText('创作者A')).toBeTruthy();
-    expect(within(card as HTMLElement).queryByText('user-internal-author')).toBeNull();
+    expect(
+      within(card as HTMLElement).queryByText('user-internal-author'),
+    ).toBeNull();
     expect(within(card as HTMLElement).getByText('20泥点')).toBeTruthy();
   });
 
@@ -500,18 +501,56 @@ describe('CreationLandingView', () => {
     expect(within(dialog).getByText('生成总成本')).toBeTruthy();
     expect(within(dialog).getByText('60泥点')).toBeTruthy();
     expect(within(dialog).getByText('创作者A')).toBeTruthy();
-    expect(
-      within(dialog).getByLabelText('素材缩略图导航'),
-    ).toBeTruthy();
+    expect(within(dialog).getByLabelText('素材缩略图导航')).toBeTruthy();
 
-    await user.click(within(dialog).getByRole('button', { name: '查看待机动画' }));
+    await user.click(
+      within(dialog).getByRole('button', { name: '查看待机动画' }),
+    );
     expect(
-      within(dialog).getByRole('button', { name: '查看待机动画' }).getAttribute(
-        'aria-current',
-      ),
+      within(dialog)
+        .getByRole('button', { name: '查看待机动画' })
+        .getAttribute('aria-current'),
     ).toBe('true');
   });
 
+  it('uses the unified audio cover image for featured audio assets', async () => {
+    const user = userEvent.setup();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    listPublicEditorProjectResourcesMock.mockResolvedValueOnce([
+      {
+        resourceId: 'resource-music',
+        projectId: 'project-newest',
+        label: '背景音乐',
+        imageSrc: '/generated-editor-audios/music.mp3',
+        objectKey: 'generated-editor-audios/music.mp3',
+        width: 1,
+        height: 1,
+        sourceType: 'generated',
+        prompt: '舒缓背景音乐',
+        actualPrompt: null,
+        model: 'audio1.0',
+        provider: 'ark',
+        taskId: 'task-audio-1',
+        assetKind: 'background-music',
+        priceMudPoints: 5,
+      },
+    ]);
+
+    renderCreationLanding();
+
+    await user.click(screen.getByRole('tab', { name: '音乐' }));
+    const card = (await screen.findByText('背景音乐')).closest(
+      '.creation-landing__asset-card',
+    );
+    expect(card).toBeTruthy();
+    const image = within(card as HTMLElement).getByRole('img', {
+      name: '背景音乐',
+    });
+    expect(image.getAttribute('src')).toBe(
+      '/creation-home/audio-asset-cover.svg',
+    );
+  });
+
   it('uses Taonier featured as the generated project resource waterfall instead of creation entries', async () => {
     listEditorProjectsMock.mockResolvedValueOnce(projectItems);
     listPublicEditorProjectResourcesMock.mockResolvedValueOnce([
@@ -564,9 +603,9 @@ describe('CreationLandingView', () => {
     expect(await screen.findByText('素材包 A')).toBeTruthy();
     expect(screen.getByText('素材包 B')).toBeTruthy();
     expect(screen.queryByText('上传素材')).toBeNull();
-    expect(
-      screen.getByLabelText('用户素材瀑布流').className,
-    ).toContain('creation-landing__asset-waterfall');
+    expect(screen.getByLabelText('用户素材瀑布流').className).toContain(
+      'creation-landing__asset-waterfall',
+    );
     const firstPreview = container.querySelector(
       '.creation-landing__asset-preview',
     ) as HTMLElement | null;
@@ -665,7 +704,9 @@ describe('CreationLandingView', () => {
     await waitFor(() => expect(observers).toHaveLength(1));
     triggerIntersection(observers[0]!);
 
-    expect(await screen.findByRole('button', { name: '读取更多素材失败，点击重试' })).toBeTruthy();
+    expect(
+      await screen.findByRole('button', { name: '读取更多素材失败，点击重试' }),
+    ).toBeTruthy();
     expect(screen.getByText('素材包 A')).toBeTruthy();
     expect(screen.getByLabelText('用户素材瀑布流')).toBeTruthy();
   });
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
index 3a50a5a70..833e6f490 100644
--- a/src/components/creation-home/CreationLandingView.tsx
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -61,8 +61,7 @@ const CREATION_HOME_ASSETS = {
   projectNew: '/creation-home/project-new.png',
 } as const;
 
-const SHOWCASE_LIKE_ICON_SRC =
-  '/creation-home/showcase-like-thumb.png';
+const SHOWCASE_LIKE_ICON_SRC = '/creation-home/showcase-like-thumb.png';
 
 const CREATION_FEATURES: CreationFeatureItem[] = [
   {
@@ -137,7 +136,9 @@ function mergeShowcaseResources(
   current: EditorProjectResourceSnapshot[],
   incoming: EditorProjectResourceSnapshot[],
 ) {
-  const seenResourceIds = new Set(current.map((resource) => resource.resourceId));
+  const seenResourceIds = new Set(
+    current.map((resource) => resource.resourceId),
+  );
   return [
     ...current,
     ...incoming.filter((resource) => {
@@ -189,10 +190,17 @@ function ShowcaseAudioPreview({
   const { resolvedUrl } = useResolvedAssetReadUrl(preview.src, {
     objectKey: preview.objectKey,
   });
+  const coverSrc =
+    preview.coverSrc?.trim() || '/creation-home/audio-asset-cover.svg';
 
   return (
     <div className="creation-landing__asset-audio-preview">
-      <Music2 aria-hidden="true" />
+      <img
+        alt={preview.label}
+        className="creation-landing__asset-audio-cover"
+        draggable={false}
+        src={coverSrc}
+      />
       {controls && resolvedUrl ? (
         <audio controls preload="metadata" src={resolvedUrl} />
       ) : null}
@@ -271,11 +279,7 @@ function ShowcaseVideoPreview({
   );
 }
 
-function ShowcaseBundlePreview({
-  item,
-}: {
-  item: ShowcaseAssetItem;
-}) {
+function ShowcaseBundlePreview({ item }: { item: ShowcaseAssetItem }) {
   const visiblePreviews = item.previews.slice(0, 4);
   const primaryPreview = visiblePreviews[0];
 
@@ -396,7 +400,9 @@ function CreationShowcaseModal({
                     alt=""
                     aria-hidden="true"
                   />
-                  <span>{isLikePending ? '处理中' : isLiked ? '已点赞' : '点赞'}</span>
+                  <span>
+                    {isLikePending ? '处理中' : isLiked ? '已点赞' : '点赞'}
+                  </span>
                 </PlatformActionButton>
               ) : null}
             </div>
@@ -418,7 +424,8 @@ function CreationShowcaseModal({
                   onClick={() => onSelectIndex(index)}
                 >
                   <span className="creation-landing__showcase-thumb-media">
-                    {preview.mediaType === 'image' ? (
+                    {preview.mediaType === 'image' ||
+                    preview.mediaType === 'audio' ? (
                       <ShowcasePreview preview={preview} variant="thumb" />
                     ) : (
                       getPreviewIcon(preview)
@@ -455,9 +462,13 @@ export function CreationLandingView({
   >([]);
   const [showcaseCampaign, setShowcaseCampaign] =
     useState<EditorShowcaseCampaignSnapshot | null>(null);
-  const [showcaseNextCursor, setShowcaseNextCursor] = useState<string | null>(null);
+  const [showcaseNextCursor, setShowcaseNextCursor] = useState<string | null>(
+    null,
+  );
   const [assetError, setAssetError] = useState<string | null>(null);
-  const [showcaseLoadMoreError, setShowcaseLoadMoreError] = useState<string | null>(null);
+  const [showcaseLoadMoreError, setShowcaseLoadMoreError] = useState<
+    string | null
+  >(null);
   const [activeShowcaseTab, setActiveShowcaseTab] =
     useState<ShowcaseTabId>('packs');
   const [selectedShowcaseItem, setSelectedShowcaseItem] =
@@ -499,9 +510,7 @@ export function CreationLandingView({
         }
         const message =
           error instanceof Error ? error.message : '读取最近项目失败';
-        setProjectError(
-          message,
-        );
+        setProjectError(message);
       })
       .finally(() => setIsLoadingProjects(false));
   }, [authUi, isAuthenticated]);
@@ -540,47 +549,58 @@ export function CreationLandingView({
     refreshShowcaseResources();
   }, [refreshShowcaseResources]);
 
-  const loadMoreShowcaseResources = useCallback((options: { force?: boolean } = {}) => {
-    const cursor = showcaseNextCursor;
-    if (!cursor || isLoadingShowcase || isLoadingMoreShowcase) {
-      return;
-    }
-    if (showcaseLoadingMoreCursorRef.current === cursor) {
-      return;
-    }
-    if (!options.force && showcaseFailedLoadMoreCursorRef.current === cursor) {
-      return;
-    }
-    showcaseLoadingMoreCursorRef.current = cursor;
-    setIsLoadingMoreShowcase(true);
-    setShowcaseLoadMoreError(null);
-    listPublicEditorProjectResources({ cursor })
-      .then((page) => {
-        const normalizedPage = normalizeShowcaseResourcePage(page);
-        setProjectShowcaseResources((current) =>
-          mergeShowcaseResources(current, normalizedPage.resources),
-        );
-        setShowcaseCampaign((current) => normalizedPage.campaign ?? current);
-        setShowcaseNextCursor(normalizedPage.nextCursor);
-        showcaseFailedLoadMoreCursorRef.current = null;
-      })
-      .catch((error: unknown) => {
-        showcaseFailedLoadMoreCursorRef.current = cursor;
-        setShowcaseLoadMoreError(
-          error instanceof Error ? error.message : '读取陶泥儿精选失败',
-        );
-      })
-      .finally(() => {
-        if (showcaseLoadingMoreCursorRef.current === cursor) {
-          showcaseLoadingMoreCursorRef.current = null;
-        }
-        setIsLoadingMoreShowcase(false);
-      });
-  }, [isLoadingMoreShowcase, isLoadingShowcase, showcaseNextCursor]);
+  const loadMoreShowcaseResources = useCallback(
+    (options: { force?: boolean } = {}) => {
+      const cursor = showcaseNextCursor;
+      if (!cursor || isLoadingShowcase || isLoadingMoreShowcase) {
+        return;
+      }
+      if (showcaseLoadingMoreCursorRef.current === cursor) {
+        return;
+      }
+      if (
+        !options.force &&
+        showcaseFailedLoadMoreCursorRef.current === cursor
+      ) {
+        return;
+      }
+      showcaseLoadingMoreCursorRef.current = cursor;
+      setIsLoadingMoreShowcase(true);
+      setShowcaseLoadMoreError(null);
+      listPublicEditorProjectResources({ cursor })
+        .then((page) => {
+          const normalizedPage = normalizeShowcaseResourcePage(page);
+          setProjectShowcaseResources((current) =>
+            mergeShowcaseResources(current, normalizedPage.resources),
+          );
+          setShowcaseCampaign((current) => normalizedPage.campaign ?? current);
+          setShowcaseNextCursor(normalizedPage.nextCursor);
+          showcaseFailedLoadMoreCursorRef.current = null;
+        })
+        .catch((error: unknown) => {
+          showcaseFailedLoadMoreCursorRef.current = cursor;
+          setShowcaseLoadMoreError(
+            error instanceof Error ? error.message : '读取陶泥儿精选失败',
+          );
+        })
+        .finally(() => {
+          if (showcaseLoadingMoreCursorRef.current === cursor) {
+            showcaseLoadingMoreCursorRef.current = null;
+          }
+          setIsLoadingMoreShowcase(false);
+        });
+    },
+    [isLoadingMoreShowcase, isLoadingShowcase, showcaseNextCursor],
+  );
 
   useEffect(() => {
     const element = showcaseLoadMoreRef.current;
-    if (!element || !showcaseNextCursor || isLoadingShowcase || isLoadingMoreShowcase) {
+    if (
+      !element ||
+      !showcaseNextCursor ||
+      isLoadingShowcase ||
+      isLoadingMoreShowcase
+    ) {
       return;
     }
     if (showcaseFailedLoadMoreCursorRef.current === showcaseNextCursor) {
@@ -608,28 +628,31 @@ export function CreationLandingView({
     showcaseNextCursor,
   ]);
 
-  const createProject = useCallback((tool?: CreationFeatureTool) => {
-    if (authUi && !authUi.user) {
-      authUi.openLoginModal(() => createProject(tool));
-      return;
-    }
-    setIsCreatingProject(true);
-    setProjectError(null);
-    createEditorProject()
-      .then((project) =>
-        onOpenProject(project.projectId, tool ? { tool } : { guide: true }),
-      )
-      .catch((error: unknown) => {
-        if (isUnauthorizedError(error)) {
-          authUi?.openLoginModal(() => createProject(tool));
-          return;
-        }
-        setProjectError(
-          error instanceof Error ? error.message : '创建项目失败',
-        );
-      })
-      .finally(() => setIsCreatingProject(false));
-  }, [authUi, onOpenProject]);
+  const createProject = useCallback(
+    (tool?: CreationFeatureTool) => {
+      if (authUi && !authUi.user) {
+        authUi.openLoginModal(() => createProject(tool));
+        return;
+      }
+      setIsCreatingProject(true);
+      setProjectError(null);
+      createEditorProject()
+        .then((project) =>
+          onOpenProject(project.projectId, tool ? { tool } : { guide: true }),
+        )
+        .catch((error: unknown) => {
+          if (isUnauthorizedError(error)) {
+            authUi?.openLoginModal(() => createProject(tool));
+            return;
+          }
+          setProjectError(
+            error instanceof Error ? error.message : '创建项目失败',
+          );
+        })
+        .finally(() => setIsCreatingProject(false));
+    },
+    [authUi, onOpenProject],
+  );
 
   const handleFeatureClick = useCallback(
     (feature: CreationFeatureItem) => {
@@ -646,13 +669,16 @@ export function CreationLandingView({
     (showcaseId: string, likeCount: number) => {
       setProjectShowcaseResources((current) =>
         current.map((resource) =>
-          resource.showcaseId === showcaseId || resource.resourceId === showcaseId
+          resource.showcaseId === showcaseId ||
+          resource.resourceId === showcaseId
             ? { ...resource, likeCount }
             : resource,
         ),
       );
       setSelectedShowcaseItem((current) =>
-        current?.showcaseId === showcaseId ? { ...current, likeCount } : current,
+        current?.showcaseId === showcaseId
+          ? { ...current, likeCount }
+          : current,
       );
     },
     [],
@@ -783,7 +809,10 @@ export function CreationLandingView({
 
     return (
       <>
-        <div className="creation-landing__asset-waterfall" aria-label="用户素材瀑布流">
+        <div
+          className="creation-landing__asset-waterfall"
+          aria-label="用户素材瀑布流"
+        >
           {showcaseItems.map((item) => {
             const showcaseId = item.showcaseId?.trim();
             const isLiked = Boolean(
@@ -830,7 +859,11 @@ export function CreationLandingView({
                     disabled={isLikePending}
                     onClick={() => handleToggleShowcaseLike(item)}
                   >
-                    <img src={SHOWCASE_LIKE_ICON_SRC} alt="" aria-hidden="true" />
+                    <img
+                      src={SHOWCASE_LIKE_ICON_SRC}
+                      alt=""
+                      aria-hidden="true"
+                    />
                     <span>{item.likeCount ?? 0}</span>
                   </button>
                 ) : null}
@@ -1015,7 +1048,11 @@ export function CreationLandingView({
             <h2>陶泥儿精选</h2>
           </div>
         </div>
-        <div className="creation-landing__tabs" role="tablist" aria-label="用户素材分类">
+        <div
+          className="creation-landing__tabs"
+          role="tablist"
+          aria-label="用户素材分类"
+        >
           {SHOWCASE_TABS.map((tab) => (
             <button
               key={tab.id}
diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
index 6916426c5..99a53de5d 100644
--- a/src/components/creation-home/creationShowcaseModel.test.ts
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -458,6 +458,9 @@ describe('creationShowcaseModel', () => {
 
     expect(items).toHaveLength(1);
     expect(items[0]?.previews[0]?.mediaType).toBe('audio');
+    expect(items[0]?.previews[0]?.coverSrc).toBe(
+      '/creation-home/audio-asset-cover.svg',
+    );
     expect(items[0]?.author).toBe('当前用户');
     expect(items[0]?.cost).toBe('5泥点');
   });
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
index 29767956e..4001a2f0a 100644
--- a/src/components/creation-home/creationShowcaseModel.ts
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -30,6 +30,7 @@ export type ShowcaseAssetPreview = {
   id: string;
   label: string;
   src: string;
+  coverSrc?: string | null;
   objectKey?: string | null;
   mediaType: ShowcaseAssetMediaType;
   width?: number;
@@ -55,6 +56,7 @@ type ShowcaseAssetGroup = {
 };
 
 const UNKNOWN_META_VALUE = '-';
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
 
 const SHOWCASE_COST_KEYS = [
   'priceMudPoints',
@@ -63,7 +65,10 @@ const SHOWCASE_COST_KEYS = [
   'mudPointCost',
 ] as const;
 
-const SHOWCASE_AUTHOR_KEYS = ['authorDisplayName', 'authorPublicUserCode'] as const;
+const SHOWCASE_AUTHOR_KEYS = [
+  'authorDisplayName',
+  'authorPublicUserCode',
+] as const;
 
 export const SHOWCASE_TABS: Array<{ id: ShowcaseTabId; label: string }> = [
   { id: 'packs', label: '素材包' },
@@ -183,7 +188,10 @@ function projectResourceToShowcaseAsset(
 
   return {
     ...record,
-    assetId: resource.assetId?.trim() || resource.showcaseId?.trim() || resource.resourceId,
+    assetId:
+      resource.assetId?.trim() ||
+      resource.showcaseId?.trim() ||
+      resource.resourceId,
     folderId: `project:${resource.projectId}`,
     label: fallbackLabel,
     imageSrc: resource.imageSrc,
@@ -216,7 +224,9 @@ function normalizeShowcaseCategory(value: string): ShowcaseTabId | null {
 }
 
 function resolveAssetShowcaseCategory(asset: EditorAssetSnapshot) {
-  return normalizeShowcaseCategory(normalizeText(assetRecord(asset).showcaseCategory));
+  return normalizeShowcaseCategory(
+    normalizeText(assetRecord(asset).showcaseCategory),
+  );
 }
 
 function normalizeShowcaseMediaRef(value: string | null | undefined) {
@@ -307,11 +317,15 @@ function findSpecReference(asset: EditorAssetSnapshot) {
 }
 
 function findCharacterReference(asset: EditorAssetSnapshot) {
-  return findReference(asset, (reference) => /角色图片|角色图/u.test(reference.title));
+  return findReference(asset, (reference) =>
+    /角色图片|角色图/u.test(reference.title),
+  );
 }
 
 function findUiDesignReference(asset: EditorAssetSnapshot) {
-  return findReference(asset, (reference) => /UI设计图|UI 图|UI图片/u.test(reference.title));
+  return findReference(asset, (reference) =>
+    /UI设计图|UI 图|UI图片/u.test(reference.title),
+  );
 }
 
 function isAssetKind(asset: EditorAssetSnapshot, kinds: readonly string[]) {
@@ -336,7 +350,9 @@ function isVideoAsset(asset: EditorAssetSnapshot) {
   );
 }
 
-function resolveAssetMediaType(asset: EditorAssetSnapshot): ShowcaseAssetMediaType {
+function resolveAssetMediaType(
+  asset: EditorAssetSnapshot,
+): ShowcaseAssetMediaType {
   if (isAudioAsset(asset)) {
     return 'audio';
   }
@@ -435,11 +451,16 @@ function mergeAssetAliasGroups(
 
 function sortGroupAssets(assets: EditorAssetSnapshot[]) {
   return [...assets].sort((left, right) => {
-    const leftRank = isSpecAsset(left) || isCharacterAsset(left) || isAssetKind(left, ['ui-design'])
-      ? 0
-      : 1;
+    const leftRank =
+      isSpecAsset(left) ||
+      isCharacterAsset(left) ||
+      isAssetKind(left, ['ui-design'])
+        ? 0
+        : 1;
     const rightRank =
-      isSpecAsset(right) || isCharacterAsset(right) || isAssetKind(right, ['ui-design'])
+      isSpecAsset(right) ||
+      isCharacterAsset(right) ||
+      isAssetKind(right, ['ui-design'])
         ? 0
         : 1;
     if (leftRank !== rightRank) {
@@ -454,7 +475,12 @@ function groupPackAssets(assets: EditorAssetSnapshot[]) {
   assets.forEach((asset) => {
     const specReference = findSpecReference(asset);
     if (specReference) {
-      addAssetToGroup(groups, getReferenceKey(specReference), asset, specReference.label);
+      addAssetToGroup(
+        groups,
+        getReferenceKey(specReference),
+        asset,
+        specReference.label,
+      );
       return;
     }
     if (isSpecAsset(asset)) {
@@ -466,7 +492,10 @@ function groupPackAssets(assets: EditorAssetSnapshot[]) {
   const specAssets = assets.filter(isSpecAsset);
   specAssets.forEach((asset) => {
     const group = mergeAssetAliasGroups(groups, asset, asset.label);
-    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+    if (
+      group &&
+      !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)
+    ) {
       group.assets.unshift(asset);
     }
   });
@@ -500,12 +529,20 @@ function groupCharacterAssets(assets: EditorAssetSnapshot[]) {
         );
         return;
       }
-      addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
-  });
+      addAssetToGroup(
+        groups,
+        `standalone:${asset.assetId}`,
+        asset,
+        asset.label,
+      );
+    });
   const characterAssets = assets.filter(isCharacterAsset);
   characterAssets.forEach((asset) => {
     const group = mergeAssetAliasGroups(groups, asset, asset.label);
-    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+    if (
+      group &&
+      !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)
+    ) {
       group.assets.unshift(asset);
     }
   });
@@ -518,23 +555,43 @@ function groupCharacterAssets(assets: EditorAssetSnapshot[]) {
 function groupUiAssets(assets: EditorAssetSnapshot[]) {
   const groups = new Map<string, ShowcaseAssetGroup>();
   assets
-    .filter((asset) => isUiAsset(asset) || /\bui\b|界面|图标|icon/u.test(getAssetHaystack(asset)))
+    .filter(
+      (asset) =>
+        isUiAsset(asset) ||
+        /\bui\b|界面|图标|icon/u.test(getAssetHaystack(asset)),
+    )
     .forEach((asset) => {
       if (isAssetKind(asset, ['ui-design'])) {
         addAssetToGroup(groups, getSelfAssetKey(asset), asset, asset.label);
         return;
       }
-      const uiReference = findUiDesignReference(asset) ?? findSpecReference(asset);
+      const uiReference =
+        findUiDesignReference(asset) ?? findSpecReference(asset);
       if (uiReference) {
-        addAssetToGroup(groups, getReferenceKey(uiReference), asset, uiReference.label);
+        addAssetToGroup(
+          groups,
+          getReferenceKey(uiReference),
+          asset,
+          uiReference.label,
+        );
         return;
       }
-      addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
-  });
-  const uiDesignAssets = assets.filter((asset) => isAssetKind(asset, ['ui-design']));
+      addAssetToGroup(
+        groups,
+        `standalone:${asset.assetId}`,
+        asset,
+        asset.label,
+      );
+    });
+  const uiDesignAssets = assets.filter((asset) =>
+    isAssetKind(asset, ['ui-design']),
+  );
   uiDesignAssets.forEach((asset) => {
     const group = mergeAssetAliasGroups(groups, asset, asset.label);
-    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+    if (
+      group &&
+      !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)
+    ) {
       group.assets.unshift(asset);
     }
   });
@@ -588,13 +645,18 @@ function resolveAssetPrompt(asset: EditorAssetSnapshot) {
 
   const generationFields = asset.generationInputs?.fields ?? [];
   const firstPromptField =
-    generationFields.find((field) => /提示词|描述|设定|prompt/u.test(field.title)) ??
-    generationFields[0];
+    generationFields.find((field) =>
+      /提示词|描述|设定|prompt/u.test(field.title),
+    ) ?? generationFields[0];
   return firstPromptField?.value?.trim() || UNKNOWN_META_VALUE;
 }
 
 function resolveGroupPrompt(assets: EditorAssetSnapshot[]) {
-  return assets.map(resolveAssetPrompt).find((value) => value !== UNKNOWN_META_VALUE) ?? UNKNOWN_META_VALUE;
+  return (
+    assets
+      .map(resolveAssetPrompt)
+      .find((value) => value !== UNKNOWN_META_VALUE) ?? UNKNOWN_META_VALUE
+  );
 }
 
 function resolveAssetAuthor(
@@ -672,7 +734,12 @@ function inferAssetCost(asset: EditorAssetSnapshot) {
         | '480p'
         | '720p'
         | '1080p',
-      normalizeInt(asset.durationSeconds, DEFAULT_VIDEO_DURATION_SECONDS, 4, 15),
+      normalizeInt(
+        asset.durationSeconds,
+        DEFAULT_VIDEO_DURATION_SECONDS,
+        4,
+        15,
+      ),
     );
   }
   if (asset.sourceType === 'generated' || kind) {
@@ -715,12 +782,14 @@ function resolveGroupCost(assets: EditorAssetSnapshot[]) {
 }
 
 function toAssetPreview(asset: EditorAssetSnapshot): ShowcaseAssetPreview {
+  const mediaType = resolveAssetMediaType(asset);
   return {
     id: asset.assetId,
     label: asset.label,
     src: asset.imageSrc,
+    coverSrc: mediaType === 'audio' ? AUDIO_ASSET_COVER_SRC : null,
     objectKey: asset.objectKey,
-    mediaType: resolveAssetMediaType(asset),
+    mediaType,
     width: asset.width,
     height: asset.height,
   };
@@ -731,7 +800,9 @@ function toLibraryShowcaseItem(
   fallbackAuthorName?: string | null,
 ): ShowcaseAssetItem | null {
   const sortedAssets = sortGroupAssets(group.assets);
-  const previews = sortedAssets.map(toAssetPreview).filter((preview) => preview.src.trim());
+  const previews = sortedAssets
+    .map(toAssetPreview)
+    .filter((preview) => preview.src.trim());
   if (!previews.length) {
     return null;
   }
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
index 61bb764a1..2ca914786 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
@@ -27,25 +27,30 @@ vi.mock('../common/PlatformMediaFrame', () => ({
   }) => {
     const imageSrc =
       src?.trim() ||
-      (objectKey?.trim() ? `https://signed.example.com/${objectKey.trim()}` : '');
+      (objectKey?.trim()
+        ? `https://signed.example.com/${objectKey.trim()}`
+        : '');
     return (
       <div className="platform-media-frame">
         {imageSrc ? (
-        <img
-          src={imageSrc}
-          alt={alt}
-          data-object-key={objectKey?.trim() || undefined}
-        />
-      ) : null}
-      {previewOverlay}
-    </div>
+          <img
+            src={imageSrc}
+            alt={alt}
+            data-object-key={objectKey?.trim() || undefined}
+          />
+        ) : null}
+        {previewOverlay}
+      </div>
     );
   },
 }));
 
 beforeEach(() => {
   useResolvedAssetReadUrlMock.mockImplementation(
-    (source: string | null | undefined, options?: { objectKey?: string | null }) => ({
+    (
+      source: string | null | undefined,
+      options?: { objectKey?: string | null },
+    ) => ({
       resolvedUrl: options?.objectKey
         ? `https://signed.example.com/${options.objectKey}`
         : (source ?? ''),
@@ -138,9 +143,7 @@ describe('ImageCanvasAssetRowView', () => {
     const onDownloadAsset = vi.fn();
     renderAssetRow({ asset, onDownloadAsset });
 
-    fireEvent.click(
-      screen.getByRole('button', { name: '下载素材账号素材A' }),
-    );
+    fireEvent.click(screen.getByRole('button', { name: '下载素材账号素材A' }));
 
     expect(onDownloadAsset).toHaveBeenCalledWith(asset);
   });
@@ -154,20 +157,26 @@ describe('ImageCanvasAssetRowView', () => {
     const onDownloadAsset = vi.fn();
     renderAssetRow({ asset, addAssetLayer, onDownloadAsset });
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
     expect(screen.getByRole('menu')).toBeTruthy();
 
     fireEvent.click(screen.getByRole('button', { name: '下载素材账号素材A' }));
     expect(onDownloadAsset).toHaveBeenCalledWith(asset);
     expect(screen.queryByRole('menu')).toBeNull();
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
     fireEvent.click(screen.getByRole('button', { name: '添加账号素材A' }));
     expect(addAssetLayer).toHaveBeenCalledWith(asset);
     expect(screen.queryByRole('menu')).toBeNull();
@@ -199,7 +208,9 @@ describe('ImageCanvasAssetRowView', () => {
     fireEvent.keyDown(input, { key: 'Enter' });
 
     expect(input.className).toContain('platform-text-field');
-    expect(input.className).toContain('image-canvas-editor__asset-rename-input');
+    expect(input.className).toContain(
+      'image-canvas-editor__asset-rename-input',
+    );
     expect(commitAssetRename).toHaveBeenCalledWith(
       expect.objectContaining({ id: 'asset-1' }),
     );
@@ -226,7 +237,7 @@ describe('ImageCanvasAssetRowView', () => {
     ).toBe('42');
   });
 
-  it('uses icon thumbnails for audio assets instead of rendering media as images', () => {
+  it('uses the audio cover thumbnail for audio assets', () => {
     renderAssetRow({
       asset: createAsset({
         label: '胜利音效.mp3',
@@ -236,13 +247,13 @@ describe('ImageCanvasAssetRowView', () => {
     });
 
     expect(screen.getByText('音频')).toBeTruthy();
-    expect(screen.queryByRole('img', { name: '素材：胜利音效.mp3' })).toBeNull();
+    const image = screen.getByRole('img', { name: '素材：胜利音效.mp3' });
+    expect(image.getAttribute('src')).toBe(
+      '/creation-home/audio-asset-cover.svg',
+    );
     expect(
       document.querySelector('.image-canvas-editor__asset-media-overlay'),
-    ).toBeTruthy();
-    expect(
-      document.querySelector('.image-canvas-editor__media-preview--audio'),
-    ).toBeTruthy();
+    ).toBeNull();
   });
 
   it('uses a stable visual preview for video asset cards without image thumbnails', () => {
@@ -250,13 +261,16 @@ describe('ImageCanvasAssetRowView', () => {
       asset: createAsset({
         label: '生成视频.mp4',
         src: '/generated-character-drafts/editor/asset-library/video/demo.mp4',
-        objectKey: 'generated-character-drafts/editor/asset-library/video/demo.mp4',
+        objectKey:
+          'generated-character-drafts/editor/asset-library/video/demo.mp4',
         mediaType: 'video',
       }),
     });
 
     expect(screen.getByText('视频')).toBeTruthy();
-    expect(screen.queryByRole('img', { name: '素材：生成视频.mp4' })).toBeNull();
+    expect(
+      screen.queryByRole('img', { name: '素材：生成视频.mp4' }),
+    ).toBeNull();
     const video = screen.getByLabelText(
       '视频素材预览：生成视频.mp4',
     ) as HTMLVideoElement;
@@ -315,10 +329,13 @@ describe('ImageCanvasAssetRowView', () => {
       screen.queryByRole('button', { name: '删除素材账号素材A' }),
     ).toBeNull();
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
 
     const submitMenuItem = screen.getByRole('menuitem', {
       name: /提交精选审核/u,
@@ -327,10 +344,13 @@ describe('ImageCanvasAssetRowView', () => {
     fireEvent.click(submitMenuItem);
     expect(submitAssetToShowcase).toHaveBeenCalledWith(asset);
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
     fireEvent.click(screen.getByRole('menuitem', { name: '删除' }));
     expect(deleteUploadedAsset).toHaveBeenCalledWith(asset);
   });
@@ -339,10 +359,13 @@ describe('ImageCanvasAssetRowView', () => {
     const submitAssetToShowcase = vi.fn();
     renderAssetRow({ submitAssetToShowcase });
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
 
     const submitMenuItem = screen.getByRole('menuitem', {
       name: /提交精选审核/u,
@@ -360,10 +383,13 @@ describe('ImageCanvasAssetRowView', () => {
     const submitAssetToShowcase = vi.fn();
     renderAssetRow({ asset, submitAssetToShowcase });
 
-    fireEvent.contextMenu(screen.getByRole('button', { name: '添加账号素材A' }), {
-      clientX: 120,
-      clientY: 80,
-    });
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
 
     const submitMenuItem = screen.getByRole('menuitem', {
       name: /提交精选审核/u,
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.tsx b/src/components/image-editor/ImageCanvasAssetRowView.tsx
index 393500139..c6bd2093a 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.tsx
@@ -1,4 +1,4 @@
-import { Check, Download, Music2, Pencil, Video, X } from 'lucide-react';
+import { Check, Download, Pencil, Video, X } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
 
@@ -24,6 +24,8 @@ import {
   getCanvasMediaPreviewMarker,
 } from './ImageCanvasMediaModel';
 
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
+
 export type ImageCanvasAssetRowViewProps = {
   asset: EditorAsset;
   assetPointerDragRef: { current: AssetPointerDragState | null };
@@ -38,7 +40,10 @@ export type ImageCanvasAssetRowViewProps = {
   setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
   setSelectedAssetIds: Dispatch<SetStateAction<Set<string>>>;
   updateAssetMoveDropFolder: (folderId: string | null) => void;
-  addUploadedFiles: (files: FileList | File[], options?: UploadFilesOptions) => void;
+  addUploadedFiles: (
+    files: FileList | File[],
+    options?: UploadFilesOptions,
+  ) => void;
   moveAssetToFolder: (assetId: string, folderId: string) => void;
   startRenamingAsset: (asset: EditorAsset) => void;
   commitAssetRename: (asset: EditorAsset) => void;
@@ -81,7 +86,9 @@ export function ImageCanvasAssetRowView({
   const isFailedUpload = asset.uploadStatus === 'failed';
   const showcaseReviewStatus = asset.showcaseReviewStatus ?? null;
   const canSubmitShowcaseAsset =
-    asset.sourceType === 'generated' && asset.persisted && !showcaseReviewStatus;
+    asset.sourceType === 'generated' &&
+    asset.persisted &&
+    !showcaseReviewStatus;
   const showcaseMenuLabel =
     showcaseReviewStatus === 'pending'
       ? '精选审核中'
@@ -153,13 +160,7 @@ export function ImageCanvasAssetRowView({
         ? '视频'
         : `${asset.width} x ${asset.height}`;
   const mediaOverlay =
-    asset.mediaType === 'audio' ? (
-      <div
-        className={`image-canvas-editor__asset-media-overlay ${mediaPreviewClassName}`}
-      >
-        <Music2 className="h-5 w-5" />
-      </div>
-    ) : asset.mediaType === 'video' ? (
+    asset.mediaType === 'video' ? (
       <div
         className={`image-canvas-editor__asset-media-overlay ${mediaPreviewClassName}`}
       >
@@ -279,9 +280,7 @@ export function ImageCanvasAssetRowView({
         rowClassName={[
           'image-canvas-editor__asset-row',
           isUploadingAsset ? 'image-canvas-editor__asset-row--uploading' : '',
-          isFailedUpload
-            ? 'image-canvas-editor__asset-row--upload-failed'
-            : '',
+          isFailedUpload ? 'image-canvas-editor__asset-row--upload-failed' : '',
         ]
           .filter(Boolean)
           .join(' ')}
@@ -291,12 +290,18 @@ export function ImageCanvasAssetRowView({
         imageSrc={
           asset.mediaType === 'image'
             ? asset.src
-            : (asset.thumbnailSrc ?? '')
+            : asset.mediaType === 'audio'
+              ? AUDIO_ASSET_COVER_SRC
+              : (asset.thumbnailSrc ?? '')
         }
         objectKey={asset.mediaType === 'image' ? asset.objectKey : undefined}
         previewNode={videoPreview}
         titleNode={
-          isUploadingAsset || isFailedUpload ? <span>{asset.label}</span> : titleNode
+          isUploadingAsset || isFailedUpload ? (
+            <span>{asset.label}</span>
+          ) : (
+            titleNode
+          )
         }
         actions={actions}
         draggable={!isRenaming && !isUploadingAsset && !isFailedUpload}
diff --git a/src/index.css b/src/index.css
index 7d873657e..f1022184c 100644
--- a/src/index.css
+++ b/src/index.css
@@ -1585,7 +1585,9 @@ html[data-mobile-keyboard-open='true'] #root {
   background: rgba(255, 252, 248, 0.97);
   box-shadow: 0 18px 36px rgba(74, 34, 15, 0.18);
   pointer-events: none;
-  transform: translateX(calc(-50% + var(--floating-feedback-contact-offset, 0px)));
+  transform: translateX(
+    calc(-50% + var(--floating-feedback-contact-offset, 0px))
+  );
 }
 
 .floating-feedback-entry-contact-panel img {
@@ -3183,8 +3185,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   width: 100%;
   height: 100%;
   overflow: hidden;
-  background:
-    linear-gradient(135deg, rgba(15, 23, 42, 0.06), transparent 56%),
+  background: linear-gradient(135deg, rgba(15, 23, 42, 0.06), transparent 56%),
     #f3f4f6;
 }
 
@@ -3397,7 +3398,8 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   overflow: auto;
   background:
     linear-gradient(rgba(255, 250, 244, 0.56), rgba(255, 250, 244, 0.56)),
-    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem repeat,
+    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem
+      repeat,
     linear-gradient(180deg, #fff9f3 0%, #fffdf9 52%, #fff8f0 100%);
   color: var(--creation-ink);
 }
@@ -3434,8 +3436,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   margin: 0;
   max-width: 62rem;
   color: var(--creation-ink);
-  font-family:
-    "Songti SC", "STSong", "Noto Serif SC", "SimSun", serif;
+  font-family: 'Songti SC', 'STSong', 'Noto Serif SC', 'SimSun', serif;
   font-size: clamp(2.35rem, 4.25vw, 3.85rem);
   font-weight: 950;
   letter-spacing: 0;
@@ -3512,8 +3513,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   top: 14%;
   width: 58%;
   aspect-ratio: 4 / 3;
-  background:
-    linear-gradient(135deg, rgba(75, 181, 170, 0.24), transparent 52%),
+  background: linear-gradient(135deg, rgba(75, 181, 170, 0.24), transparent 52%),
     #ffffff;
 }
 
@@ -3522,8 +3522,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   top: 28%;
   width: 34%;
   aspect-ratio: 1;
-  background:
-    linear-gradient(135deg, rgba(246, 171, 76, 0.24), transparent 56%),
+  background: linear-gradient(135deg, rgba(246, 171, 76, 0.24), transparent 56%),
     #ffffff;
 }
 
@@ -3532,8 +3531,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   bottom: 10%;
   width: 36%;
   aspect-ratio: 16 / 9;
-  background:
-    linear-gradient(135deg, rgba(129, 140, 248, 0.2), transparent 56%),
+  background: linear-gradient(135deg, rgba(129, 140, 248, 0.2), transparent 56%),
     #ffffff;
 }
 
@@ -3585,9 +3583,16 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   min-height: 9.55rem;
   border: 1px solid rgba(220, 189, 163, 0.78);
   border-radius: 1.12rem;
-  background:
-    radial-gradient(circle at 21% 42%, rgba(222, 130, 66, 0.12), transparent 9rem),
-    linear-gradient(135deg, rgba(255, 254, 251, 0.92), rgba(255, 247, 238, 0.82));
+  background: radial-gradient(
+      circle at 21% 42%,
+      rgba(222, 130, 66, 0.12),
+      transparent 9rem
+    ),
+    linear-gradient(
+      135deg,
+      rgba(255, 254, 251, 0.92),
+      rgba(255, 247, 238, 0.82)
+    );
   padding: 1.05rem 1.3rem;
   color: inherit;
   font: inherit;
@@ -3646,7 +3651,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   border-radius: 999px;
   background: rgba(112, 62, 32, 0.22);
   filter: blur(0.16rem);
-  content: "";
+  content: '';
 }
 
 .creation-landing__feature-art {
@@ -3961,15 +3966,25 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   place-items: center;
   gap: 1rem;
   padding: 1rem;
-  background:
-    linear-gradient(135deg, rgba(244, 187, 129, 0.4), rgba(255, 247, 236, 0.92)),
-    radial-gradient(circle at 30% 24%, rgba(255, 255, 255, 0.9), transparent 42%);
-  color: #9a5428;
+  background: linear-gradient(
+      135deg,
+      rgba(244, 187, 129, 0.4),
+      rgba(255, 247, 236, 0.92)
+    ),
+    radial-gradient(
+      circle at 30% 24%,
+      rgba(255, 255, 255, 0.9),
+      transparent 42%
+    );
 }
 
-.creation-landing__asset-audio-preview svg {
-  width: 2.6rem;
-  height: 2.6rem;
+.creation-landing__asset-audio-cover {
+  display: block;
+  width: min(48%, 11rem);
+  min-width: 3.2rem;
+  height: auto;
+  object-fit: contain;
+  object-position: center;
 }
 
 .creation-landing__asset-audio-preview audio {
@@ -4054,8 +4069,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   min-height: 0;
   grid-template-rows: minmax(0, 1fr) auto;
   overflow: hidden;
-  background:
-    radial-gradient(circle at 18% 12%, rgba(186, 117, 65, 0.18), transparent 32%),
+  background: radial-gradient(
+      circle at 18% 12%,
+      rgba(186, 117, 65, 0.18),
+      transparent 32%
+    ),
     #100d0b;
 }
 
@@ -4376,7 +4394,10 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
     --platform-button-primary-fill,
     linear-gradient(135deg, #df7f40, #b95d3a)
   );
-  --image-canvas-brand-text-on-fill: var(--platform-button-primary-text, #fffaf5);
+  --image-canvas-brand-text-on-fill: var(
+    --platform-button-primary-text,
+    #fffaf5
+  );
   --image-canvas-brand-border: rgba(204, 117, 76, 0.34);
   --image-canvas-brand-border-strong: rgba(199, 101, 61, 0.64);
   --image-canvas-brand-border-soft: rgba(226, 203, 184, 0.82);
@@ -4881,8 +4902,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 .image-canvas-editor__media-preview {
   position: relative;
   isolation: isolate;
-  background:
-    radial-gradient(circle at 25% 24%, rgba(255, 255, 255, 0.22), transparent 0.72rem),
+  background: radial-gradient(
+      circle at 25% 24%,
+      rgba(255, 255, 255, 0.22),
+      transparent 0.72rem
+    ),
     linear-gradient(135deg, rgba(15, 23, 42, 0.84), rgba(20, 83, 45, 0.58));
 }
 
@@ -4895,8 +4919,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .image-canvas-editor__media-preview--audio::before {
-  background:
-    repeating-linear-gradient(
+  background: repeating-linear-gradient(
       90deg,
       rgba(103, 232, 249, 0.34) 0 0.18rem,
       transparent 0.18rem 0.52rem
@@ -4905,8 +4928,12 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .image-canvas-editor__media-preview--video::before {
-  background:
-    linear-gradient(90deg, rgba(15, 23, 42, 0.42) 0 14%, transparent 14% 86%, rgba(15, 23, 42, 0.42) 86%),
+  background: linear-gradient(
+      90deg,
+      rgba(15, 23, 42, 0.42) 0 14%,
+      transparent 14% 86%,
+      rgba(15, 23, 42, 0.42) 86%
+    ),
     repeating-linear-gradient(
       0deg,
       rgba(248, 250, 252, 0.34) 0 0.2rem,
@@ -5840,7 +5867,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
       rgba(250, 245, 255, 0.94),
       transparent 30%
     ),
-    linear-gradient(135deg, rgba(250, 245, 255, 0.84), rgba(243, 232, 255, 0.72));
+    linear-gradient(
+      135deg,
+      rgba(250, 245, 255, 0.84),
+      rgba(243, 232, 255, 0.72)
+    );
 }
 
 .image-canvas-editor__generation-frame--character.image-canvas-editor__generation-frame--focused {
@@ -5853,9 +5884,16 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .image-canvas-editor__generation-frame--character-animation {
-  background:
-    radial-gradient(circle at 50% 36%, rgba(255, 247, 237, 0.96), transparent 32%),
-    linear-gradient(135deg, rgba(255, 247, 237, 0.92), rgba(254, 215, 170, 0.74));
+  background: radial-gradient(
+      circle at 50% 36%,
+      rgba(255, 247, 237, 0.96),
+      transparent 32%
+    ),
+    linear-gradient(
+      135deg,
+      rgba(255, 247, 237, 0.92),
+      rgba(254, 215, 170, 0.74)
+    );
 }
 
 .image-canvas-editor__generation-frame--character-animation.image-canvas-editor__generation-frame--focused {
@@ -5868,8 +5906,12 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .image-canvas-editor__generation-frame--video {
-  background:
-    linear-gradient(90deg, rgba(15, 23, 42, 0.12) 10%, transparent 10% 90%, rgba(15, 23, 42, 0.12) 90%),
+  background: linear-gradient(
+      90deg,
+      rgba(15, 23, 42, 0.12) 10%,
+      transparent 10% 90%,
+      rgba(15, 23, 42, 0.12) 90%
+    ),
     linear-gradient(135deg, rgba(239, 246, 255, 0.9), rgba(219, 234, 254, 0.82));
 }
 
@@ -5884,8 +5926,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 
 .image-canvas-editor__generation-frame--audio-sound-effect,
 .image-canvas-editor__generation-frame--audio-background-music {
-  background:
-    repeating-linear-gradient(
+  background: repeating-linear-gradient(
       90deg,
       rgba(79, 70, 229, 0.14) 0 0.22rem,
       transparent 0.22rem 0.58rem
@@ -6091,8 +6132,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 
 .image-canvas-editor__generation-frame--quick-edit {
   border-color: var(--image-canvas-brand-border);
-  background:
-    linear-gradient(135deg, rgba(204, 117, 76, 0.12), rgba(240, 203, 169, 0.12)),
+  background: linear-gradient(
+      135deg,
+      rgba(204, 117, 76, 0.12),
+      rgba(240, 203, 169, 0.12)
+    ),
     rgba(255, 255, 255, 0.72);
 }
 
@@ -6109,8 +6153,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 
 .image-canvas-editor__generation-frame--publication {
   border-color: rgba(236, 72, 153, 0.28);
-  background:
-    radial-gradient(circle at 30% 20%, rgba(244, 114, 182, 0.18), transparent 38%),
+  background: radial-gradient(
+      circle at 30% 20%,
+      rgba(244, 114, 182, 0.18),
+      transparent 38%
+    ),
     linear-gradient(135deg, rgba(236, 72, 153, 0.12), rgba(251, 146, 60, 0.08)),
     rgba(255, 247, 252, 0.78);
 }
@@ -6311,7 +6358,8 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   transform: translate(-50%, -100%);
 }
 
-.image-canvas-editor__floating-toolbar button.image-canvas-editor__floating-toolbar-text-button {
+.image-canvas-editor__floating-toolbar
+  button.image-canvas-editor__floating-toolbar-text-button {
   width: auto;
   min-width: 0;
   gap: 0.35rem;
@@ -8779,8 +8827,11 @@ button.image-canvas-editor__reference-chip:disabled {
   z-index: 999;
   box-sizing: border-box;
   border: 2px solid var(--image-canvas-brand-accent);
-  background:
-    linear-gradient(90deg, rgba(204, 117, 76, 0.2) 1px, transparent 1px),
+  background: linear-gradient(
+      90deg,
+      rgba(204, 117, 76, 0.2) 1px,
+      transparent 1px
+    ),
     linear-gradient(rgba(204, 117, 76, 0.2) 1px, transparent 1px);
   background-size: 33.333% 33.333%;
   box-shadow:
@@ -9335,7 +9386,8 @@ button.image-canvas-editor__reference-chip:disabled {
     height: 2rem;
   }
 
-  .image-canvas-editor__floating-toolbar button.image-canvas-editor__floating-toolbar-text-button {
+  .image-canvas-editor__floating-toolbar
+    button.image-canvas-editor__floating-toolbar-text-button {
     width: auto;
   }
 
@@ -9632,8 +9684,11 @@ button.image-canvas-editor__reference-chip:disabled {
 }
 
 .platform-mobile-home-welcome-overlay {
-  background:
-    radial-gradient(circle at 50% 18%, rgba(255, 254, 252, 0.54), transparent 32%),
+  background: radial-gradient(
+      circle at 50% 18%,
+      rgba(255, 254, 252, 0.54),
+      transparent 32%
+    ),
     rgba(61, 31, 16, 0.24);
 }
 
@@ -9642,8 +9697,11 @@ button.image-canvas-editor__reference-chip:disabled {
   overflow: hidden;
   border-radius: 1.65rem;
   border: 1px solid rgba(255, 255, 255, 0.68);
-  background:
-    radial-gradient(circle at 18% 0%, rgba(240, 203, 169, 0.28), transparent 38%),
+  background: radial-gradient(
+      circle at 18% 0%,
+      rgba(240, 203, 169, 0.28),
+      transparent 38%
+    ),
     var(--platform-modal-fill);
   box-shadow:
     0 24px 58px rgba(112, 57, 30, 0.2),
@@ -12521,7 +12579,8 @@ button.image-canvas-editor__reference-chip:disabled {
   padding: 0 !important;
   background:
     linear-gradient(rgba(255, 250, 244, 0.72), rgba(255, 250, 244, 0.72)),
-    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem repeat,
+    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem
+      repeat,
     linear-gradient(180deg, #fffaf4 0%, #fffdf9 52%, #fff8f0 100%);
   box-shadow: 0 24px 58px rgba(112, 57, 30, 0.08);
 }
@@ -12656,7 +12715,7 @@ button.image-canvas-editor__reference-chip:disabled {
   width: 1px;
   height: 1.66rem;
   background: rgba(217, 190, 166, 0.82);
-  content: "";
+  content: '';
   transform: translateY(-50%);
 }
 
@@ -12691,7 +12750,9 @@ button.image-canvas-editor__reference-chip:disabled {
   display: none;
 }
 
-.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search {
+.platform-desktop-shell--workbench
+  .platform-desktop-topbar
+  button.platform-desktop-search {
   width: auto;
   max-width: none !important;
   min-width: 7.35rem;
@@ -12702,12 +12763,17 @@ button.image-canvas-editor__reference-chip:disabled {
   gap: 0.38rem !important;
 }
 
-.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search:hover {
+.platform-desktop-shell--workbench
+  .platform-desktop-topbar
+  button.platform-desktop-search:hover {
   border-color: rgba(214, 184, 159, 0.52);
   background: rgba(255, 250, 244, 0.56);
 }
 
-.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search > span:first-child {
+.platform-desktop-shell--workbench
+  .platform-desktop-topbar
+  button.platform-desktop-search
+  > span:first-child {
   width: 2.06rem;
   height: 2.06rem;
 }
@@ -12750,12 +12816,16 @@ button.image-canvas-editor__reference-chip:disabled {
   box-shadow: none;
 }
 
-.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon-shell {
+.platform-desktop-shell--workbench
+  .platform-desktop-rail__button--active
+  .platform-desktop-rail__icon-shell {
   background: #fff2e7;
   box-shadow: none;
 }
 
-.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon {
+.platform-desktop-shell--workbench
+  .platform-desktop-rail__button--active
+  .platform-desktop-rail__icon {
   color: #c7653d;
 }
 
@@ -12795,7 +12865,9 @@ button.image-canvas-editor__reference-chip:disabled {
   box-shadow: none;
 }
 
-.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__label {
+.platform-desktop-shell--workbench
+  .platform-desktop-rail__button--active
+  .platform-desktop-rail__label {
   color: #c7653d;
 }
 

From 7c449f0596d8c7bb0226767c7c31836d2662e506 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 14:44:43 +0800
Subject: [PATCH 02/24] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E9=9F=B3=E9=A2=91?=
 =?UTF-8?q?=E7=B4=A0=E6=9D=90=E5=B0=81=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

使用用户提供的透明 PNG 替换自绘 SVG 音频封面
统一后台素材查询、精选审核、创作主页和画板素材库的音频封面引用
补齐画板图层列表音频图层封面展示
更新相关测试覆盖
---
 .../pages/AdminEditorAssetQueryPage.test.tsx  |   2 +-
 .../src/pages/AdminEditorAssetQueryPage.tsx   |   2 +-
 .../AdminEditorShowcaseReviewPage.test.tsx    |   2 +-
 .../pages/AdminEditorShowcaseReviewPage.tsx   |   2 +-
 public/creation-home/audio-asset-cover.png    | Bin 0 -> 6968 bytes
 public/creation-home/audio-asset-cover.svg    |  19 ---------------
 .../CreationLandingView.test.tsx              |   2 +-
 .../creation-home/CreationLandingView.tsx     |   2 +-
 .../creationShowcaseModel.test.ts             |   2 +-
 .../creation-home/creationShowcaseModel.ts    |   2 +-
 .../ImageCanvasAssetRowView.test.tsx          |   2 +-
 .../image-editor/ImageCanvasAssetRowView.tsx  |   2 +-
 .../ImageCanvasLayerPanelView.tsx             |  10 ++++++--
 .../ImageCanvasSidebarView.test.tsx           |  22 ++++++++++++++++++
 14 files changed, 40 insertions(+), 31 deletions(-)
 create mode 100644 public/creation-home/audio-asset-cover.png
 delete mode 100644 public/creation-home/audio-asset-cover.svg

diff --git a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
index 3d075d2ed..346a7335d 100644
--- a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx
@@ -154,7 +154,7 @@ test('后台素材查询音频素材使用统一封面缩略图', async () => {
 
   const image = await screen.findByRole('img', { name: '素材：胜利音效' });
   expect(image.getAttribute('src')).toBe(
-    '/creation-home/audio-asset-cover.svg',
+    '/creation-home/audio-asset-cover.png',
   );
   expect(getAdminAssetReadUrl).not.toHaveBeenCalled();
 });
diff --git a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
index 50f588c25..177865f24 100644
--- a/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx
@@ -19,7 +19,7 @@ interface AdminEditorAssetQueryPageProps {
 }
 
 const ADMIN_ASSET_READ_EXPIRE_SECONDS = 300;
-const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
 
 export function AdminEditorAssetQueryPage({
   token,
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
index ac11c94bd..90cd99289 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
@@ -200,7 +200,7 @@ test('后台精选审核音频素材使用统一封面缩略图', async () => {
 
   const image = await screen.findByRole('img', { name: '精选素材：胜利音效' });
   expect(image.getAttribute('src')).toBe(
-    '/creation-home/audio-asset-cover.svg',
+    '/creation-home/audio-asset-cover.png',
   );
   expect(getAdminAssetReadUrl).not.toHaveBeenCalled();
 });
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
index 302d4d074..1988dfab4 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
@@ -24,7 +24,7 @@ interface AdminEditorShowcaseReviewPageProps {
 }
 
 const ADMIN_SHOWCASE_READ_EXPIRE_SECONDS = 300;
-const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
 
 const showcaseCategoryOptions = [
   { value: 'packs', label: '素材包' },
diff --git a/public/creation-home/audio-asset-cover.png b/public/creation-home/audio-asset-cover.png
new file mode 100644
index 0000000000000000000000000000000000000000..893e476ab76a2037e5068a53d8c31901f26474cc
GIT binary patch
literal 6968
zcmXAucOaYH_rPx=Awo$iR*fdH)rz)8tyo31HM;CQy3{JQC8+VD_UN!_tEf$@MT{D)
z7Jb!tQEC^pYmeXK`}-^Bx%WQjex7shIrrR?D8s8dC(x(R0Du#Ex?08nz#tI@Q1sA`
zg~w|r05CvLOZ~bJY|-+b@rZ8P*D%w_LGZ&$y+xS$h<-V@<sm|$8B@=+eMpsuRl;lQ
zVd;U)QzJ>&Q?=i3d`mNarIGgLyTJNSPp_-0`6vDVktUK69MJ%2Q(oviu0<9@gKjuc
z#vajd<Yg9kw6`%gJNs`X$<`3GWw+T!lC==LoxuTzKCnICptY6B{VBb!#Xrwqso3+!
z$Z@V6Fb*H8sJ;I!fI?B>0C!spPl5;PzO8Bq<1ToTY@FhE)Vzfrt}=EeqU14%<h`KU
ztuaxsygDvV#4y9+v7=s96Eao(_`<=LLJUo|_zDHM@t5Jbf<*piy7~L!RCrGq^8gza
zixR~9rlqAYV;?;8&IRWPEq}GLVN_<lpX0xsydL{fzseUR?_Gwu>8@m;`Y`E)&U-(P
z4vl7zGOjDb^k|xEyxS*ZjA-l>pKoOvQ|(p`xG&JWtW7ABNo4)ThqRG#P{zw6bk}UT
z3zx6JUgtG+4-v_U5qc+(c;>efUI_RH-G+vn{PP!fP|{y6guxAOs#eB1iFOXiw>q32
zu;9xFUFSWy_pT()K7ZlTEeeJsSNx?ReO5A#jciE#9<IPMUeF*Su=tr6D3AYE#joSB
zAJBI|E^wKMwO@0H3h2M2B3_W0($0yb38cU0sJ`Mc!r5@;e}mAmf(EI2`W{V3H@Q6v
zV-Gjp{9T=&w~FTDwHiGgjf&x*SQ;4t?;P0{FHK!3k>009cW3K={Zrb5qR_fSf(1H{
z-qjsd)g5k5uk0>uwhSm$?KTDE0z_zkaFgKs;LCI=gO@z2W=MKJIRuc|Co&Mjx@(B+
zxFQcZL06_Ycu)9Mnv2h+=;uE7c#<kV@XIicYICZ4gbg|1D8df#Vx5I2Prdh0uWK0;
zf7(pM3bF$4BVx3OFAok!k$b58fNphb^D7%_x!i=~2P;)O>Ej6^n#^+{v*uSKPt-DF
z*NmO+n$!JLwT9qS&T1uWGT{AGi~fV4aluZV@j-7CM8wBB3~e?3e@u<Bg1)WyuK{>S
zY`^tCrLFHi>QDrO<8&%qaTJFhPU}^r#L52tU6&HYQRZs_!e;P%P(?ZG^>2|}@Ks5H
z^-2Gv0I!2T`g6l(XWPZ2{4G<AK^<noJMrVVCk1Zk=D`qlF_9G%<y(pYA;(H3jy=z7
zG3~Zj>^-~(K2RkbS<z&%r~B+WY@PCrV$f#gO*(>?v>F83<$?`$vBp5%wS5m+{Wwvu
z^D<VjTVDQ?&qY|r`INSi39RAVo0dV#?(;_Lo6&HY<^5iNVi_B?;fxpvOqdAL$|fU3
z0a7@HfTcE|48bn((?KMe3Q6e8;+kf1aLwFTfLT3y?<BPulMQgGhT)osa6B2t6~eJ4
z1b<8*!$c)=n4O1E%(0np860WJ0D;zkKFLs)8;#}q2l91MyOAsuE({>EvmIoU9R*~B
z{m?Y7J|AYRC<2Bi6QUfrv}~B+I11_YDi_fZ1xXqwJ7rR1X@hfOz&>HpT`L<LLkcDk
zl4EIGjaScb9S-CheO@?vmJdW5BFTOTvKyD~;pBRIba1!9gP_bT<$VP;lK<Weqf^y;
ztbrJS!#RmEO3*M9k<RLdzDpT;_k#OGI>h$M7-Wzt{Q8I*3}~`dObGb$>5;V<SRNne
zB=*Dt6w7m_&S7FMsLE+^iPi>)h!pZ#ji533ujf}yE*5&lQ+THjVFX?hJ0>eHLj96Y
zr(78Se|#kwdQO;X`Bxjp^@KZ4mjbEt6l||v%NXbsu+q>6p<Ci&;3vV6YJaQ=3SD7y
zq_;_Nu|jR`s`J@ko1EadajY|8s-D19CxFC@e*7ZAd;GjJn+1;#ep2xlBY1SU^&8tZ
zS@x2o_+eq_rJ)g6`+9{V^L#?Ux&XU9KV+Epsa4~dB4IQ|TF}{oMNjqlluGm~8Q=9v
zL$E)d9w;X0yD8?uqI$1@KZTT5cB>@L+Ipkue_q}pho(&26M+lvTs85q7`n99QnWYu
z<8Q5W8LRa&zuLa%Y|4fgd64dP9x1e2aECc@W5!M<v5|dwRvJlTeezSEWOggvG@`_L
zAWLC&hHs`2`7LD1Mg7=(dhf2Z`8h+K+yyHR>6cbh;M5_=KhGWe=SU3>@sF^t`AIS0
zGUsNlhr+3Qj4|eb?Tg9N1zHrr(~+u38@$bkiXvR_eLKz&D2H_Bek70+{X;A2@o2J=
z>c}Y;>X_c!zpHlx+s(V4+crO*tDV9W7y*s!&$4{*7Tv?YOTBy@TME!VpBT6BkQCgB
zsnmz1yRQ-Jt|sarl$>thDCxInEz^YF8_jbxYW#aKxLLaQRQuH8+oJSRLoY}Z;kons
z48fzx`9rp#$KF1HkD{$}r@86t*B%2TjWcm4Su=4qDSA;Q2RLNqX0RkqDcSz|oC8f5
zPULV6PE_XaHyyxzS45L_AHGU<>5_a9{wqBI9jRQy1UUt##>iC!`r`jW1NSNH9OO|w
zk1@4u)G$=o+h=ghDce*7ge=q_@9r^o3X6&bNc_2Gi7b>u3?xlX^;A0wU<CZoWaea3
z25bioQu#6}$6O0f4|x}tXeA3VUJQ~hvuW0*#*&L6KP!)SQqjU|LVm_A{8$Q0HGxR&
z2w(jo$>ESBdl_vB1p`vvE6}R-+zU(Xf`WlVDyB{oVMipxBBSIMi14RSFzApVJcNQl
z>yu14hR3~M2O$fg#~aDcp|O$2ka82naVQ5U7~u09dQuz(;)xI>y3bSu+i@HWgrl-~
zwD3p>4fne8Dlwk%81kgLJOud$f-H=8uGhlT9YYFIr7+a%5SlTe+b@bte+;P$w=|K1
zi$Re2T3KFf)K;kRqzL5)8#VcOU~YF^6xj}XIf{)opB77=Kh}7bwi`v(fEpQ_oPTKH
z&qEXTaoZed;R%owHeNXoF=}q$D7+Qq(~)H2@!J&VYArkiBq=&jRWVep<5^(ccOi{Z
zz1M(8C*lAPXN2q{2r_P*q*_4IR3hW9I^rZ0Hg&;;A`3aVqP797LyTwRF-i+sL=3mv
zO&x^Cv8Arb%`sskj~7vPy!gQoYKlVziLZ_6IZec1A^T{RnX+R$PC(KF?i@8OJQ0G7
zw5fapLE0ZfR%&ELk_92O1d7vnExgV#q|;+nEL9hRB*MPlg$()j81gIg0TGUc(6qqQ
z8yKnu7J_`ny{nBNLXeR_wg@t$q7DS9sI(D_LL5VK*>GgZ!^e&;loTHX`fWhbmT9nY
zRzzN{+kpSYfr6T^$4tNNX|Bzqot+KlP0P=eX}(qe<^N?|wISHoY@>;{BI|2iGmE*`
zv!NvIPQkYrW1Vk^#LrL7BLZy($8LMl4JXOkV3<(Id5TO&`H&Qja{roUdjKAMAHHd3
zwsE0X(l-TOeuHugnM3Bo&|?t-n^OqFD=Rn>Pu?_jFhlVEe*BO=zqX{xSV#O%kw?h5
zA0y^vm6Vt^Og978zl@}w`t6d&pTA}7_D(~5Ta@VNPhaSV#8KQBojS1?x7J6J_18_K
zzTPQU3H2)lq)%w*vzhMnPqM?}5tehOR_jxj^UAP}*XP)EFSACvw62D-<^bmK7>4|d
zU<#9{OqD1MWW3(U4rgZ7U_BuUsInb)2LeErf<v+e^HiZV=`2*panAmEamzSxTC^f&
z95r~;`fa7YcFJHbM@iq)4WAHZCQ%T5A!UYh(Zc)y=-!&!89#()IbH(+xt$dsiIfj>
zJ;+pzGbAY(w0a1TqJ32dSO$$~%hwC0_Jl*H><PXH`XOK`Pv?=m-ZWEDGQ6xTY?fcD
zW7+=&kJ60d4;@(gwHox+dAc>V=<N}4dnw!h<_wPG{zABy%p%>{OQUxS_<t~4<0#z1
zC0c3jCFYU1bq1wwyfpKamF4KY@=&$6OKK%=8w06)R%4^hssZ)>#XS8@Hx~}vx_<pQ
zSY3!#rKs}?rkX~=k=a^uUnPVs=94%!BtnK$H#8pVd+XT559^GcK78*V&i9X7pEisr
zu<AIZ37vQy%3ru*K}TalpL|`+6FSM?y|PTJtT(^keYB`{XMM8?gXsJ1hr-Ye&6-L?
zKZeI^pGsY5Z6I+{b8A~4<uhREe*F8vWE+q$qzm7)QU74Th{(aW{%$AF1wZFVrHk4$
ztA$&ix85D`t=<SP<<p4o`Z9z99WhERZr^R1QD@t>Z6nhI=f7n7*YNy|^(EJSFKJP=
z+iZHGz!ENNBg!_~<G^il`%}lO<$DL|KAw_?yf!6_O-*$=n9)BHNFc(X%UBUwtYM|^
z;qRQ@pJpbu*K<+5=;Xo&8|%GdIYpx<hV)&~E-#P2ka^!SOU){Kso}9lqdRJG`T28q
zoh4QD*`0Ks;rjF6{wuFmAm|d{5S{Ka%GLbAolm_Qlwx}-pU(?+hQ9Y4VP8Xe#ZYt!
zi-UYVeq9S^JC^SWH@5uEem<~H$6%~irPrJfAJ>iR=geo=QO@KFnVg!gZ9jiSDgh~K
z%@+JU)L$#D5wZ5+UwA$BKfxSxzD1QNK-uOBR{F00a4z$UdA~lA8e-D)sLIaN|9PP&
z?Q29w=>EH^)H~@(BNfDzx~<c#3WeGH3_9%K;i@_wV;vIhKB>csqF-*dYO?7F;>(WR
zS+*X#80_~gc0W(xjsk|bvX-mXIg{N&6@`Nz46D5%m&hq5V)~EMF+8m$$=Mohgl4s!
zimaF&^_chvPDXNCG!_Q9AKP`%^P|1%g76Q)@Jq#g1yGPo*FWKL*WxxRKjzZ?4dRrV
z)Sa#|WEeZFB<{l|&j*!skgctCYpmVJ^}ZY9lOn+xhStpNrNyF=;2TLD()AJTLJ8I-
z){)%hrHy`p>r&u0tam<7dt?500J;dH6pl=+>Kq;22^;<M8_M0imw$Y0kM6gAR{L`J
zWZsNnxj#D?xgjDs{%^C{!OQ(y6)<5}3knUVo@~!Kv`Z&%^4f|b52F>3Ms6@T-#NY~
zu7=#+2tM`M;@dpn^1*_KJK8z3ex|O9B8JVnq;oHf555$AUfbFbpIC4-@NE=SFa_iw
z?;Un)OVobasj=On0Ba+aJ++iH;BYC3a$Ww@z&@5XUACh`k_<UduTcAn{koFhLsmRt
zC(H5OYNYkmU(d>_IRnf5{9g_a=ViWKS{;2Fl=6os>E0VpKPPj^ThRx%*Xsx8#u%hb
z@;NCTQ^DR2)=B%ImO7DkEuFi1v)l5FsNuKRz<Ph>5kDuM)~2Xt|9QeQ5&-C5$F+cW
zJCY0thse%fEf=s2<y<3lv@22*T5}7-uK8)H=DMy~lk~Zzq?O&7u%@UGHaesKJ{er_
zMf#c9nxbh{@fT04@JI7`qCye0pPvi=PTwB*z;bTpq~-33-%4hiZztOBN8riKJzpqX
z*;|C^s!bUOr8Fso_lp3_h`!ok&(a1vYL<Ie>~a|cBQ298-@r%qH7nGKcR9XWy-wx-
z%X~f(7I1QGM3Xmyqv=3}AoEww&fq~;9oLKQVb}%-cz7^9zB<aP=+kbOH51bBo#v^u
zX;6V~D0z$@svJ&4ER`GEpmI)|=l9OoEtY@cef4!N%UIraOds6e`toSNx^8c7eztGo
zQHH2Ol)OeZE&?e&UsN$`+b90~OmsbR^hnIpwe-a7J!#m=U(~Dfw`+bdB=nCtZ_yLR
z%WQo9iy<Wm-_$&z9-)&s9?4ju_Hp#=ZtzNjO9tc;=P&s_{i`GI@SvpOu8%sRI8x8x
zr7h>%pBm$Ty<F!H_M;b(mt77L!e5#fDj{jN7Nm(D(dDWy#5(ct?>w|53w`t%T?x#U
zbMR|u9ci2SW%SFw(|abZ;_IiAgvY3gWn<I+uK>zjr1sFw=56==G30-n7bwv@Q8feW
zd&{WHeDu0en>lCj;Q?1GTHoMEemh5ul8waskb|qdq-R=78(edp^nlXb4-L*X{%nl{
zm=zgj@|~NAl^h4UoxpRnE2F_S1LENBL~H1E!~K8Fh1$MWKsW!##4@V=EW@z5@!jtZ
z*?#^veCR(7x33-U){R;rra02&34P+gV<ms-sHi{M$L}8Bh!<14ewdeGjcV!XNA=a-
z+qZsOX8!8EHz&@jcA;AU!({jDvkGTMZ=KgfHFWXvJ`z%l4hUoGyE#M0vA1~P(L{B<
zdCdL>+%T4prP%d)%T_i=g_|2oTwl@!@$$~-$PSl*K)F~rjX~i_d$7ukopd%*!@8d0
z#hwy~S(uIEysbX4;IvMkMX<T%yjM%NboZb<I1kuNnwZ~RSYD}+e9^mzR3LkQq!U<P
z7c#TH#Iy@!3%Nh?u6~*oL8aeHi+#U%_rS<H51^uS;*L}-=BcigHD1y-{iHB&{&gXb
z%$;;h@rT`h9w=k_Y>FB;$4oR5R_}}CkEzxky5NA~o0B}%x2v}r@BWe=ZkFT?eY-+U
zn9U*Ae@2&x3-^)bMtaT06lT`@>@A|DRk^q2sz1J*jJVuT%SgVqld&+gTd$7G_VPdT
zF1rx}dwTAKZ*>Q{DU-yip*(yBVC~f->+s~)N;c7rj5-}^bJnl^;DAECn0qUOpjWG{
zvO^Avx9vmJ{1xWo%1P87N@jhj@)1}vY5o!>_;z|g*BWWy+U*`Z8kYe#9HVBn3#|ON
z!q&Aal<F@yL-)}DUDI+ykM$4p+2!Xysa-r|oDH7T3Zti%Z4MM3kWThDm9aAKg)S1s
zoiu%(#-F<so2he+&idq+Nwj?K31z8B0E($Wxc46f9XA-WIpyL)tnA@f!|Gc?StX*n
zKflRbj8LHAG5z_olt;y($Ju6_p7-kdDDkh_llsx1R{+nwd>6XAV_>iskD|2k8p%OL
z=^8;k71uzS`u&Yq3IEd4;LocT$r?quZ67uEd0vx(T2;e|GQgdCJ<esvQZg2f|14_;
zs`~RjG<++6-)JABAQm2F(3^4n(L^W#?yY=A#K-PdMG1f90Y_dGzZ{yD{M=WD-)vu*
z)@p4Wf?)Gh+G}wSDLq{yTSr=hX*f9!>dgOr|D`l;EEc{}S6jQzZ5N3Cq}q@v7*;Xk
zbo+o1Vt<fo@7m69{+~NW0}E44<%>$;PgvHOKaZw78$_lgZQm}hr$m*gd0g3h476yQ
z^i`^<)%uGk25+9`(%rX8y9fhwW`%lNccjZXWvc()TAN=#BQ@mW&Qw>=v~WUs@+WGn
zB<P^^4h}4ybL6M-m-b;FB-3VvxcrnicUM|%+;a^iatB*_WpadYgvd1mvqaeYr6qy>
zc-1O2rCwO6+Pg$L4G({Z#K}ipeyksUmG@{1lp7M<BpX<+1TeT40WekA0?ZToo###s
zcRxOCqT>w=bFw;@B_IQIU*zGV7qC8x)(m~icW&wI)3r_%c3FL@LW4^_y;fH{F4eVh
z3T+~K)+SZm?z|Tn+rv9nsnW1J*?%t57-0`$-0krGGs?EN^;oS*ZE;run%bl?;FQ(Z
zA~#Ch#vbYsDI~R^eL`!-<sgU9q+qgbogxX8lV$cte7Y2sN0Y`b`3Tfoe5JVJRRRuN
zN+Zu)K+<-<uf-u3HwnR2U5qcXlyjzeJxm_#X><g{>{wb5iM1H>t&HU$s3OEty1W=%
z5W+RiasdTjVUa+0zox6)etiv9`sqHW+AHO)lK{+d7Z0g+vX>mPVr4d*_Fv?>7Pu`Q
zg==;+V(8*oXU`s9OW~0sbK%i4@f_jnqffWPa$4I){65-S$Me$XwuH^4F21&h&M&6<
zWZ4P}KSrR;x-$2&mOzbXED@XU80xWaG6^1?zhxDeqOYo;SfAS2>_-42wh?nek<==g
z$k4Nd4fWAug<~oI)982OMd#IeB*3c^=(a6$&TAJv%fnE%ea1t(%Y*ndtB4A|^9$RG
zDscVP>{<ZgHH~zKr<*vBYOrt&i>1rajg2$d{0J`fWO4xEw`rq5#4>xf^Z5}*{&Eup
zJtHtQi@QPMZyvxnWql5LD~Cc6+c0!Ge#2kK<d+ox+=v90Pr0OXou?btGf=G;ZOXuS
zSc)FozNkQWDSJ2r4=H{JzQN*ltruqmhTN4~kzt%UL&{&S_$gRP{q~}U{^}cPi?$@W
z@9kr_B%t$363(#A+bdr9Ws@aFPTtE116QMV$e<9+Q*BDj3$}v>U5R|{nih6gtAH^H
zyju9R=j{9O>~MV#r(^)KwTP5A3r^bVH?QMmnJ2xtI$|Gj^|zE|nS9sYe<!q)^pcV?
zfZ>t^qItq_!Ysn@2Dfn9p4-st7#l8aM$~0!dCNFpU5thZpc`u2>?$-6%_HY|9;+Kd
zbAV9>c(CytEMs?;F=Ymxzrx0pE>|2>oNNDx0_0HCAjcCTP$=%)ZxL9+3+zbp?k5r8
zKM}M~^w{_>VGIg8qjkuJVe7zOH+zw7-{PIaD34&|#kmuMN+TSDJd~B39}yTh(<y8R
zHx&=3PzZ25%#Uun0N2m{z`MBnW^jY4RqkvPf<`svgj>)(T43@EZi`j9{a3MHTC|9X
zQRp2|;3Xj5(OVhD(Q3Bwhrj;vou2xA^6Qo<0docLieo}jELbBj+0(7*LoUyoK4gr9
zF5^|r_qiQnq-uy5OYlM-6QX%Xk>o_5BV!O>$n`P7YQa7}NN55%X2}~MO-C)bm~a`)
zQ$h{#scdu`%re&Tx|mFtdJiOBa~0uW;Dg?gP$9px8XHsr>Cgc4He_a&0%yt&Tm<zl
zRxV!je#etFBUV(L->v(<7w-I;)xdUK1vT#Bc$?xt6E-BF@Z!S#D|IvY(zDD$HD6s?
z_MT1o+!k1*CGbt>W&YXS$v`E?kT>Byhz9oX;H6A;v-p9bOJ++hO1M?G@Pp@{r*<8Q
zWmB)6&j9_ar|d=G4bXLYTO)BAL*<4lR_V6i=VY-f|6i+<a85-@jQ&1i0O07Tb0p0R
f`u~gmIN7BGl3(aor||#}wE#Wst6Fb0Y(oAI<g`Gz

literal 0
HcmV?d00001

diff --git a/public/creation-home/audio-asset-cover.svg b/public/creation-home/audio-asset-cover.svg
deleted file mode 100644
index 0e96909aa..000000000
--- a/public/creation-home/audio-asset-cover.svg
+++ /dev/null
@@ -1,19 +0,0 @@
-<svg
-  xmlns="http://www.w3.org/2000/svg"
-  viewBox="0 0 256 256"
-  role="img"
-  aria-label="音频素材"
->
-  <g
-    fill="none"
-    stroke="#dc7f58"
-    stroke-linecap="round"
-    stroke-linejoin="round"
-    stroke-width="16"
-  >
-    <path d="M92 185V35l152-24v149" />
-    <path d="M92 87l152-24" />
-    <ellipse cx="53" cy="207" rx="41" ry="24" transform="rotate(4 53 207)" />
-    <ellipse cx="201" cy="193" rx="41" ry="24" transform="rotate(-4 201 193)" />
-  </g>
-</svg>
diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
index b80a8d7f6..e54762ba5 100644
--- a/src/components/creation-home/CreationLandingView.test.tsx
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -547,7 +547,7 @@ describe('CreationLandingView', () => {
       name: '背景音乐',
     });
     expect(image.getAttribute('src')).toBe(
-      '/creation-home/audio-asset-cover.svg',
+      '/creation-home/audio-asset-cover.png',
     );
   });
 
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
index 833e6f490..64f8a2cf1 100644
--- a/src/components/creation-home/CreationLandingView.tsx
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -191,7 +191,7 @@ function ShowcaseAudioPreview({
     objectKey: preview.objectKey,
   });
   const coverSrc =
-    preview.coverSrc?.trim() || '/creation-home/audio-asset-cover.svg';
+    preview.coverSrc?.trim() || '/creation-home/audio-asset-cover.png';
 
   return (
     <div className="creation-landing__asset-audio-preview">
diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
index 99a53de5d..e108cb496 100644
--- a/src/components/creation-home/creationShowcaseModel.test.ts
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -459,7 +459,7 @@ describe('creationShowcaseModel', () => {
     expect(items).toHaveLength(1);
     expect(items[0]?.previews[0]?.mediaType).toBe('audio');
     expect(items[0]?.previews[0]?.coverSrc).toBe(
-      '/creation-home/audio-asset-cover.svg',
+      '/creation-home/audio-asset-cover.png',
     );
     expect(items[0]?.author).toBe('当前用户');
     expect(items[0]?.cost).toBe('5泥点');
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
index 4001a2f0a..68dd913a3 100644
--- a/src/components/creation-home/creationShowcaseModel.ts
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -56,7 +56,7 @@ type ShowcaseAssetGroup = {
 };
 
 const UNKNOWN_META_VALUE = '-';
-const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
 
 const SHOWCASE_COST_KEYS = [
   'priceMudPoints',
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
index 2ca914786..dec4bac5e 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
@@ -249,7 +249,7 @@ describe('ImageCanvasAssetRowView', () => {
     expect(screen.getByText('音频')).toBeTruthy();
     const image = screen.getByRole('img', { name: '素材：胜利音效.mp3' });
     expect(image.getAttribute('src')).toBe(
-      '/creation-home/audio-asset-cover.svg',
+      '/creation-home/audio-asset-cover.png',
     );
     expect(
       document.querySelector('.image-canvas-editor__asset-media-overlay'),
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.tsx b/src/components/image-editor/ImageCanvasAssetRowView.tsx
index c6bd2093a..32f387cbb 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.tsx
@@ -24,7 +24,7 @@ import {
   getCanvasMediaPreviewMarker,
 } from './ImageCanvasMediaModel';
 
-const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.svg';
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
 
 export type ImageCanvasAssetRowViewProps = {
   asset: EditorAsset;
diff --git a/src/components/image-editor/ImageCanvasLayerPanelView.tsx b/src/components/image-editor/ImageCanvasLayerPanelView.tsx
index aa03a6150..bf4a9941d 100644
--- a/src/components/image-editor/ImageCanvasLayerPanelView.tsx
+++ b/src/components/image-editor/ImageCanvasLayerPanelView.tsx
@@ -7,6 +7,8 @@ import type {
   ImageContextMenuState,
 } from './ImageCanvasEditorTypes';
 
+const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
+
 export type ImageCanvasLayerPanelViewProps = {
   layers: CanvasLayer[];
   selectedLayerId: string | null;
@@ -52,8 +54,12 @@ export function ImageCanvasLayerPanelView({
             ]
               .filter(Boolean)
               .join(' · ')}
-            imageSrc={layer.src}
-            objectKey={layer.mediaType === 'image' ? layer.objectKey : undefined}
+            imageSrc={
+              layer.mediaType === 'audio' ? AUDIO_ASSET_COVER_SRC : layer.src
+            }
+            objectKey={
+              layer.mediaType === 'image' ? layer.objectKey : undefined
+            }
             imageAlt={`图层缩略图：${layer.title}`}
             selected={selectedLayerId === layer.id}
             primaryLabel={`选择图层${layer.title}`}
diff --git a/src/components/image-editor/ImageCanvasSidebarView.test.tsx b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
index 83300590f..5b479b6e8 100644
--- a/src/components/image-editor/ImageCanvasSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
@@ -297,6 +297,28 @@ describe('ImageCanvasSidebarView', () => {
     ).toBeTruthy();
   });
 
+  it('uses the transparent audio cover for audio layer thumbnails', () => {
+    render(
+      <ImageCanvasSidebarView
+        {...createSidebarProps({
+          activeSidebarPanel: 'layers',
+          layers: [
+            createLayer({
+              title: '胜利音效',
+              src: '/generated-character-drafts/editor-audios/win.mp3',
+              mediaType: 'audio',
+            }),
+          ],
+        })}
+      />,
+    );
+
+    const image = screen.getByAltText('图层缩略图：胜利音效');
+    expect(image.getAttribute('src')).toBe(
+      '/creation-home/audio-asset-cover.png',
+    );
+  });
+
   it('filters canvas layers from the sidebar search field', () => {
     render(
       <ImageCanvasSidebarView

From b8e6e9f3ef7b168763b6f87b796d29a9779ceff7 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 18:51:11 +0800
Subject: [PATCH 03/24] =?UTF-8?q?=E6=8E=A7=E5=88=B6=E7=94=BB=E5=B8=83=20Ag?=
 =?UTF-8?q?ent=20=E5=85=A5=E5=8F=A3=E9=BB=98=E8=AE=A4=E5=85=B3=E9=97=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR 控制画布 Agent 入口显示。

默认 .env 关闭、本地 .env.local 开启，并补充示例和类型声明。

禁用时隐藏 dock 按钮和收起态 Agent 面板，开启时保留右侧任务列表互斥逻辑。

修正右侧 Agent 和任务列表切换不影响左侧资源栏。

补充画布 Agent 开关、面板独立性和 dock 隐藏测试。
---
 .env                                          |   2 +
 .env.example                                  |   4 +
 .env.local                                    |   2 +
 .../ImageCanvasEditorShellView.test.tsx       |   1 +
 .../ImageCanvasEditorView.test.tsx            | 175 ++++++++++++++++--
 .../image-editor/ImageCanvasEditorView.tsx    |  58 +++---
 .../ImageCanvasPanelDockView.test.tsx         |   7 +
 .../image-editor/ImageCanvasPanelDockView.tsx |  18 +-
 .../ImageCanvasSidebarView.test.tsx           |   1 +
 .../image-editor/ImageCanvasStageView.tsx     |  21 ++-
 .../useEditorAgentConversation.ts             |   3 +-
 src/vite-env.d.ts                             |   1 +
 12 files changed, 242 insertions(+), 51 deletions(-)

diff --git a/.env b/.env
index e1ed925f9..72324e587 100644
--- a/.env
+++ b/.env
@@ -1,5 +1,7 @@
 # 微信小程序 web-view 登录配置。
 # 留空时不覆盖已有微信网页 OAuth 配置；正式联调时再填小程序 AppID / AppSecret。
+VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false
+
 WECHAT_MINI_PROGRAM_APP_ID=""
 WECHAT_MINI_PROGRAM_APP_SECRET=""
 WECHAT_JS_CODE_SESSION_ENDPOINT=""
diff --git a/.env.example b/.env.example
index df656b892..32a49b796 100644
--- a/.env.example
+++ b/.env.example
@@ -199,6 +199,10 @@ VITE_LLM_DEBUG_LOG="false"
 # Set to "true" to expose local diagnostic panels, or "false" to hide them.
 VITE_DEBUG_MODE=""
 
+# Optional: show the image editor right-side Agent entry.
+# Keep this off by default outside local development.
+VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
+
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.
diff --git a/.env.local b/.env.local
index 311781f60..cbc3ab9a0 100644
--- a/.env.local
+++ b/.env.local
@@ -42,6 +42,8 @@ LLM_DEBUG_LOG="true"
 # 注意：不要在客户端启用调试日志，避免敏感数据泄露
 # VITE_LLM_DEBUG_LOG="false"
 
+VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=true
+
 ALIYUN_OSS_BUCKET="xushi-dev"
 ALIYUN_OSS_REGION="oss-cn-beijing"
 ALIYUN_OSS_ENDPOINT="oss-cn-beijing.aliyuncs.com"
diff --git a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
index 818db33cb..dc5fa045a 100644
--- a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
@@ -139,6 +139,7 @@ function createStageProps(): ImageCanvasStageViewProps {
     editorAgentAssets: [],
     taskListRefreshKey: 0,
     isTaskSidebarOpen: false,
+    isAgentConversationEnabled: false,
     isAgentConversationOpen: false,
     generateDialog: null,
     cropExpandPanel: null,
diff --git a/src/components/image-editor/ImageCanvasEditorView.test.tsx b/src/components/image-editor/ImageCanvasEditorView.test.tsx
index aca59ee66..49f1b47a7 100644
--- a/src/components/image-editor/ImageCanvasEditorView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.test.tsx
@@ -12,6 +12,7 @@ import userEvent from '@testing-library/user-event';
 import JSZip from 'jszip';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import type { EditorAgentConversationClient } from './useEditorAgentConversation';
 import {
   ApiClientError,
   AuthUiContext,
@@ -25,11 +26,73 @@ import {
   setupImageCanvasEditorViewTestLifecycle,
 } from './ImageCanvasEditorView.test-utils';
 
-const listEditorAgentConversationsMock = vi.hoisted(() => vi.fn());
-const createEditorAgentConversationMock = vi.hoisted(() => vi.fn());
-const getEditorAgentConversationMock = vi.hoisted(() => vi.fn());
-const deleteEditorAgentConversationMock = vi.hoisted(() => vi.fn());
-const streamEditorAgentMessageMock = vi.hoisted(() => vi.fn());
+type EditorAgentListConversations =
+  EditorAgentConversationClient['listConversations'];
+type EditorAgentCreateConversation =
+  EditorAgentConversationClient['createConversation'];
+type EditorAgentGetConversation =
+  EditorAgentConversationClient['getConversation'];
+type EditorAgentDeleteConversation =
+  EditorAgentConversationClient['deleteConversation'];
+type EditorAgentStreamMessage = EditorAgentConversationClient['streamMessage'];
+type EditorAgentConversationSummary = Awaited<
+  ReturnType<EditorAgentListConversations>
+>[number];
+type EditorAgentConversationDetail = Awaited<
+  ReturnType<EditorAgentGetConversation>
+>;
+const EDITOR_AGENT_SIDEBAR_ENV = 'VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR';
+
+const listEditorAgentConversationsMock = vi.hoisted(() =>
+  vi.fn<
+    Parameters<EditorAgentListConversations>,
+    ReturnType<EditorAgentListConversations>
+  >(async () => []),
+);
+const createEditorAgentConversationMock = vi.hoisted(() =>
+  vi.fn<
+    Parameters<EditorAgentCreateConversation>,
+    ReturnType<EditorAgentCreateConversation>
+  >(async () => ({
+    conversationId: 'editor-agent-conv-created',
+    projectId: 'editor-project-default',
+    title: '画布 Agent',
+    createdAt: '2026-07-03T00:00:00.000Z',
+    updatedAt: '2026-07-03T00:00:00.000Z',
+    messages: [],
+  })),
+);
+const getEditorAgentConversationMock = vi.hoisted(() =>
+  vi.fn<
+    Parameters<EditorAgentGetConversation>,
+    ReturnType<EditorAgentGetConversation>
+  >(async () => ({
+    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',
+    messages: [],
+  })),
+);
+const deleteEditorAgentConversationMock = vi.hoisted(() =>
+  vi.fn<
+    Parameters<EditorAgentDeleteConversation>,
+    ReturnType<EditorAgentDeleteConversation>
+  >(async () => ({
+    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',
+  })),
+);
+const streamEditorAgentMessageMock = vi.hoisted(() =>
+  vi.fn<
+    Parameters<EditorAgentStreamMessage>,
+    ReturnType<EditorAgentStreamMessage>
+  >(async () => undefined),
+);
 const generateEditorImageMock = vi.hoisted(() => vi.fn());
 const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
 const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
@@ -85,7 +148,9 @@ vi.mock('../../services/image-editor/editorAgentClient', () => ({
   streamEditorAgentMessage: streamEditorAgentMessageMock,
 }));
 
-function createEditorAgentConversationSummary(overrides = {}) {
+function createEditorAgentConversationSummary(
+  overrides: Partial<EditorAgentConversationSummary> = {},
+): EditorAgentConversationSummary {
   return {
     conversationId: 'editor-agent-conv-test',
     projectId: 'editor-project-default',
@@ -96,7 +161,9 @@ function createEditorAgentConversationSummary(overrides = {}) {
   };
 }
 
-function createEditorAgentDetailWithGeneration(resourceId: string) {
+function createEditorAgentDetailWithGeneration(
+  resourceId: string,
+): EditorAgentConversationDetail {
   const summary = createEditorAgentConversationSummary();
   return {
     ...summary,
@@ -146,6 +213,18 @@ function openMinimap() {
   return screen.getByRole('button', { name: '画布小地图' });
 }
 
+async function ensureAgentConversationOpen() {
+  const agentButton = screen.getByRole('button', { name: '画布 Agent' });
+  if (agentButton.getAttribute('aria-pressed') !== 'true') {
+    fireEvent.click(agentButton);
+  }
+  return screen.findByLabelText('发送给画布 Agent');
+}
+
+function enableEditorAgentSidebarForTest() {
+  vi.stubEnv(EDITOR_AGENT_SIDEBAR_ENV, 'true');
+}
+
 describe('ImageCanvasEditorView', () => {
   setupImageCanvasEditorViewTestLifecycle({
     generateEditorImageMock,
@@ -167,6 +246,7 @@ describe('ImageCanvasEditorView', () => {
   });
 
   beforeEach(() => {
+    vi.stubEnv(EDITOR_AGENT_SIDEBAR_ENV, 'false');
     listEditorAgentConversationsMock.mockResolvedValue([]);
     createEditorAgentConversationMock.mockResolvedValue({
       ...createEditorAgentConversationSummary({
@@ -197,9 +277,11 @@ describe('ImageCanvasEditorView', () => {
     deleteEditorAgentConversationMock.mockReset();
     streamEditorAgentMessageMock.mockReset();
     getPlatformProfileDashboardMock.mockReset();
+    vi.unstubAllEnvs();
   });
 
   it('loads the project from projectid query before falling back to recent project', async () => {
+    listEditorAgentConversationsMock.mockResolvedValue([]);
     loadEditorProjectMock.mockResolvedValueOnce({
       projectId: 'editor-project-query',
       title: '查询项目',
@@ -481,6 +563,7 @@ describe('ImageCanvasEditorView', () => {
   });
 
   it('does not inject built-in mock assets when the persisted library is empty', async () => {
+    listEditorAgentConversationsMock.mockResolvedValue([]);
     loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
       projectId: 'editor-project-empty',
       title: '空画布',
@@ -939,10 +1022,10 @@ describe('ImageCanvasEditorView', () => {
   });
 
   it('moves focus from the Agent input back to the canvas layer before handling shortcuts', async () => {
+    enableEditorAgentSidebarForTest();
     render(<ImageCanvasEditorView />);
 
-    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
-    const agentInput = await screen.findByLabelText('发送给画布 Agent');
+    const agentInput = await ensureAgentConversationOpen();
     agentInput.focus();
     expect(document.activeElement).toBe(agentInput);
 
@@ -1341,6 +1424,74 @@ describe('ImageCanvasEditorView', () => {
     expect(screen.getByRole('button', { name: '添加拼图素材' })).toBeTruthy();
   });
 
+  it('hides the right Agent conversation entry by default', () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(screen.queryByRole('button', { name: '画布 Agent' })).toBeNull();
+    expect(
+      screen.queryByRole('button', { name: '打开画布 Agent' }),
+    ).toBeNull();
+    expect(screen.queryByLabelText('发送给画布 Agent')).toBeNull();
+    expect(listEditorAgentConversationsMock).not.toHaveBeenCalled();
+  });
+
+  it('opens the right Agent conversation panel by default when enabled', async () => {
+    enableEditorAgentSidebarForTest();
+    render(<ImageCanvasEditorView />);
+
+    expect(await screen.findByLabelText('发送给画布 Agent')).toBeTruthy();
+    expect(
+      screen.queryByRole('complementary', { name: '画布任务列表' }),
+    ).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
+
+    expect(screen.queryByLabelText('发送给画布 Agent')).toBeNull();
+  });
+
+  it('keeps the left resource sidebar independent from right-side task and Agent panels', async () => {
+    enableEditorAgentSidebarForTest();
+    render(<ImageCanvasEditorView />);
+
+    const assetSidebar = openAssetSidebar();
+    expect(within(assetSidebar).getByText('素材')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '任务列表' }));
+    expect(
+      screen.getByRole('complementary', { name: '画布任务列表' }),
+    ).toBeTruthy();
+    expect(
+      screen.getByRole('complementary', { name: '图片资源栏' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+    const layerSidebar = screen.getByRole('complementary', {
+      name: '图片资源栏',
+    });
+    expect(within(layerSidebar).getByText('图层')).toBeTruthy();
+    expect(
+      screen.getByRole('complementary', { name: '画布任务列表' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
+    expect(
+      screen.getByRole('complementary', { name: '图片资源栏' }),
+    ).toBeTruthy();
+    expect(
+      screen.queryByRole('complementary', { name: '画布任务列表' }),
+    ).toBeNull();
+    expect(await screen.findByLabelText('发送给画布 Agent')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '任务列表' }));
+    expect(
+      screen.getByRole('complementary', { name: '图片资源栏' }),
+    ).toBeTruthy();
+    expect(
+      screen.getByRole('complementary', { name: '画布任务列表' }),
+    ).toBeTruthy();
+    expect(screen.queryByLabelText('发送给画布 Agent')).toBeNull();
+  });
+
   it('adds assets from the sidebar and supports zoom buttons', () => {
     render(<ImageCanvasEditorView />);
 
@@ -1557,6 +1708,7 @@ describe('ImageCanvasEditorView', () => {
   });
 
   it('renders Agent generation thumbnails as passive previews', async () => {
+    enableEditorAgentSidebarForTest();
     const detail = createEditorAgentDetailWithGeneration('resource-puzzle');
     listEditorAgentConversationsMock.mockResolvedValueOnce([
       createEditorAgentConversationSummary(),
@@ -1565,7 +1717,7 @@ describe('ImageCanvasEditorView', () => {
 
     render(<ImageCanvasEditorView />);
 
-    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
+    await ensureAgentConversationOpen();
     const messageLog = await screen.findByRole('log', {
       name: '画布 Agent 消息流',
     });
@@ -1578,6 +1730,7 @@ describe('ImageCanvasEditorView', () => {
   });
 
   it('refreshes canvas and asset library when Agent generation finishes', async () => {
+    enableEditorAgentSidebarForTest();
     let showGeneratedAsset = false;
     loadEditorAssetLibraryMock.mockImplementation(async () => ({
       folders: [
@@ -1692,7 +1845,7 @@ describe('ImageCanvasEditorView', () => {
 
     render(<ImageCanvasEditorView />);
 
-    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
+    await ensureAgentConversationOpen();
     await waitFor(() => {
       expect(getEditorAgentConversationMock).toHaveBeenCalledWith(
         'editor-agent-conv-test',
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index cce084c0f..687740c30 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -117,6 +117,12 @@ type ImageCanvasEditorViewProps = {
   onProjectAccessLost?: () => void;
 };
 
+function resolveEditorAgentSidebarEnabled(
+  rawValue = import.meta.env.VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR,
+): boolean {
+  return rawValue === 'true' || rawValue === '1';
+}
+
 function isCanvasStartupTool(value: string | null): value is CanvasStartupTool {
   return CANVAS_STARTUP_TOOLS.includes(value as CanvasStartupTool);
 }
@@ -1161,44 +1167,49 @@ export function ImageCanvasEditorView({
     applyProjectSnapshot: applyGeneratedProjectSnapshot,
     onWalletBalanceMayHaveChanged: refreshEditorWalletBalance,
   });
-  const [isAgentConversationOpen, setIsAgentConversationOpen] = useState(false);
+  const isAgentConversationEnabled = resolveEditorAgentSidebarEnabled();
+  const [isAgentConversationOpen, setIsAgentConversationOpen] = useState(
+    () => isAgentConversationEnabled,
+  );
+  const effectiveIsAgentConversationOpen =
+    isAgentConversationEnabled && isAgentConversationOpen;
   const toggleAgentConversation = useCallback(() => {
+    if (!isAgentConversationEnabled) {
+      return;
+    }
     const nextOpen = !isAgentConversationOpen;
-    if (nextOpen) {
-      setActiveSidebarPanel(null);
-      if (generationSurface.isTaskSidebarOpen) {
-        generationSurface.toggleTaskSidebar();
-      }
+    if (nextOpen && generationSurface.isTaskSidebarOpen) {
+      generationSurface.toggleTaskSidebar();
     }
     setIsAgentConversationOpen(nextOpen);
-  }, [generationSurface, isAgentConversationOpen, setActiveSidebarPanel]);
+  }, [generationSurface, isAgentConversationEnabled, isAgentConversationOpen]);
   const toggleTaskSidebar = useCallback(() => {
-    if (!generationSurface.isTaskSidebarOpen) {
-      setActiveSidebarPanel(null);
+    if (
+      !generationSurface.isTaskSidebarOpen &&
+      effectiveIsAgentConversationOpen
+    ) {
       setIsAgentConversationOpen(false);
     }
     generationSurface.toggleTaskSidebar();
-  }, [generationSurface, setActiveSidebarPanel]);
+  }, [effectiveIsAgentConversationOpen, generationSurface]);
   const toggleCanvasSidebarPanel = useCallback(
     (panel: SidebarPanel) => {
-      setIsAgentConversationOpen(false);
-      if (generationSurface.isTaskSidebarOpen) {
-        generationSurface.toggleTaskSidebar();
-      }
       toggleSidebarPanel(panel);
     },
-    [generationSurface, toggleSidebarPanel],
+    [toggleSidebarPanel],
   );
   useEffect(() => {
-    if (generationSurface.isTaskSidebarOpen && isAgentConversationOpen) {
+    if (
+      (!isAgentConversationEnabled || generationSurface.isTaskSidebarOpen) &&
+      isAgentConversationOpen
+    ) {
       setIsAgentConversationOpen(false);
     }
-  }, [generationSurface.isTaskSidebarOpen, isAgentConversationOpen]);
-  useEffect(() => {
-    if (activeSidebarPanel && isAgentConversationOpen) {
-      setIsAgentConversationOpen(false);
-    }
-  }, [activeSidebarPanel, isAgentConversationOpen]);
+  }, [
+    generationSurface.isTaskSidebarOpen,
+    isAgentConversationEnabled,
+    isAgentConversationOpen,
+  ]);
   const {
     setQuickEditPanel,
     setCropExpandPanel,
@@ -1923,7 +1934,8 @@ export function ImageCanvasEditorView({
     isToolbarGuideVisible,
     taskListRefreshKey: generationSurface.taskListRefreshKey,
     isTaskSidebarOpen: generationSurface.isTaskSidebarOpen,
-    isAgentConversationOpen,
+    isAgentConversationEnabled,
+    isAgentConversationOpen: effectiveIsAgentConversationOpen,
     generateDialog,
     cropExpandPanel: generationSurface.cropExpandPanel,
     cropExpandSourceLayer: generationSurface.cropExpandSourceLayer,
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.test.tsx b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
index 5810d71a1..d033bf634 100644
--- a/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
+++ b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
@@ -18,6 +18,7 @@ function renderPanelDock(
     isZoomMenuOpen: false,
     isBackgroundSettingsOpen: false,
     activeSidebarPanel: null,
+    isAgentConversationEnabled: true,
     isAgentConversationOpen: false,
     isMinimapOpen: false,
     minimapModel: null,
@@ -91,6 +92,12 @@ describe('ImageCanvasPanelDockView', () => {
     expect(props.onToggleMinimap).toHaveBeenCalledTimes(1);
   });
 
+  it('hides the Agent entry when the Agent sidebar is disabled', () => {
+    renderPanelDock({ isAgentConversationEnabled: false });
+
+    expect(screen.queryByRole('button', { name: '画布 Agent' })).toBeNull();
+  });
+
   it('renders zoom and background settings with callback wiring', () => {
     const props = renderPanelDock({
       viewport: { x: 0, y: 0, scale: 0.5 },
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.tsx b/src/components/image-editor/ImageCanvasPanelDockView.tsx
index 9c7c041d7..38143ee91 100644
--- a/src/components/image-editor/ImageCanvasPanelDockView.tsx
+++ b/src/components/image-editor/ImageCanvasPanelDockView.tsx
@@ -35,6 +35,7 @@ type ImageCanvasPanelDockViewProps = {
   isZoomMenuOpen: boolean;
   isBackgroundSettingsOpen: boolean;
   activeSidebarPanel: SidebarPanel | null;
+  isAgentConversationEnabled: boolean;
   isAgentConversationOpen: boolean;
   isMinimapOpen: boolean;
   minimapModel: StageMinimapModel | null;
@@ -62,6 +63,7 @@ export function ImageCanvasPanelDockView({
   isZoomMenuOpen,
   isBackgroundSettingsOpen,
   activeSidebarPanel,
+  isAgentConversationEnabled,
   isAgentConversationOpen,
   isMinimapOpen,
   minimapModel,
@@ -300,13 +302,15 @@ export function ImageCanvasPanelDockView({
           pressed={activeSidebarPanel === 'layers'}
           onClick={() => onToggleSidebarPanel('layers')}
         />
-        <EditorIconButton
-          label="画布 Agent"
-          title="画布 Agent"
-          icon={MessageCircle}
-          pressed={isAgentConversationOpen}
-          onClick={onToggleAgentConversation}
-        />
+        {isAgentConversationEnabled ? (
+          <EditorIconButton
+            label="画布 Agent"
+            title="画布 Agent"
+            icon={MessageCircle}
+            pressed={isAgentConversationOpen}
+            onClick={onToggleAgentConversation}
+          />
+        ) : null}
         <EditorIconButton
           label="切换小地图"
           title="小地图"
diff --git a/src/components/image-editor/ImageCanvasSidebarView.test.tsx b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
index 5b479b6e8..3605fa5a6 100644
--- a/src/components/image-editor/ImageCanvasSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
@@ -157,6 +157,7 @@ function SidebarTabsHarness() {
         isZoomMenuOpen={false}
         isBackgroundSettingsOpen={false}
         activeSidebarPanel={chrome.activeSidebarPanel}
+        isAgentConversationEnabled={false}
         isAgentConversationOpen={false}
         isMinimapOpen={false}
         minimapModel={null}
diff --git a/src/components/image-editor/ImageCanvasStageView.tsx b/src/components/image-editor/ImageCanvasStageView.tsx
index b1b7ba036..68ba896b0 100644
--- a/src/components/image-editor/ImageCanvasStageView.tsx
+++ b/src/components/image-editor/ImageCanvasStageView.tsx
@@ -62,6 +62,7 @@ export type ImageCanvasStageViewProps = {
   isToolbarGuideVisible?: boolean;
   taskListRefreshKey: number;
   isTaskSidebarOpen: boolean;
+  isAgentConversationEnabled: boolean;
   isAgentConversationOpen: boolean;
   generateDialog: GenerateDialogState | null;
   cropExpandPanel: CropExpandPanelState | null;
@@ -212,6 +213,7 @@ export function ImageCanvasStageView({
   isToolbarGuideVisible = false,
   taskListRefreshKey,
   isTaskSidebarOpen,
+  isAgentConversationEnabled,
   isAgentConversationOpen,
   generateDialog,
   cropExpandPanel,
@@ -441,6 +443,7 @@ export function ImageCanvasStageView({
         isZoomMenuOpen={isZoomMenuOpen}
         isBackgroundSettingsOpen={isBackgroundSettingsOpen}
         activeSidebarPanel={activeSidebarPanel}
+        isAgentConversationEnabled={isAgentConversationEnabled}
         isAgentConversationOpen={isAgentConversationOpen}
         isMinimapOpen={isMinimapOpen}
         minimapModel={minimapModel}
@@ -467,14 +470,16 @@ export function ImageCanvasStageView({
         onFocusExternalTask={onFocusExternalTask}
       />
 
-      <EditorAgentConversationPanelView
-        projectId={projectId}
-        open={isAgentConversationOpen}
-        onToggleOpen={onToggleAgentConversation}
-        layers={layers}
-        assets={editorAgentAssets}
-        onGenerationResult={onEditorAgentGenerationResult}
-      />
+      {isAgentConversationEnabled ? (
+        <EditorAgentConversationPanelView
+          projectId={projectId}
+          open={isAgentConversationOpen}
+          onToggleOpen={onToggleAgentConversation}
+          layers={layers}
+          assets={editorAgentAssets}
+          onGenerationResult={onEditorAgentGenerationResult}
+        />
+      ) : null}
 
       {isToolbarGuideVisible ? (
         <div
diff --git a/src/components/image-editor/useEditorAgentConversation.ts b/src/components/image-editor/useEditorAgentConversation.ts
index 07e598207..76401dfff 100644
--- a/src/components/image-editor/useEditorAgentConversation.ts
+++ b/src/components/image-editor/useEditorAgentConversation.ts
@@ -294,8 +294,7 @@ export function useEditorAgentConversation({
     let disposed = false;
     setIsLoadingConversations(true);
     setErrorMessage(null);
-    client
-      .listConversations(normalizedProjectId)
+    Promise.resolve(client.listConversations(normalizedProjectId) ?? [])
       .then(async (nextConversations) => {
         if (disposed) {
           return;
diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts
index 81879c63e..0cf010431 100644
--- a/src/vite-env.d.ts
+++ b/src/vite-env.d.ts
@@ -2,6 +2,7 @@
 
 interface ImportMetaEnv {
   readonly VITE_DEBUG_MODE?: string;
+  readonly VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR?: string;
 }
 
 interface Window {

From b5aa68fc6a01f2160fdf65470b67af9205819d86 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 18:56:49 +0800
Subject: [PATCH 04/24] =?UTF-8?q?=E8=B0=83=E6=95=B4=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E5=90=8E=E7=AB=AF=E5=85=AC=E5=BC=80=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增精选活动卡图片 objectKey 存储字段和迁移兼容。

新增后台活动卡图片 OSS 直传凭证接口。

移除素材包精选分类约束，允许未设置分类素材进入全部精选。

同步 admin 和前台读取活动卡 objectKey 的类型契约。
---
 apps/admin-web/src/api/adminApiTypes.ts       |  27 ++++
 server-rs/crates/api-server/src/admin.rs      | 124 ++++++++++++++++++
 .../crates/api-server/src/editor_project.rs   |   2 +
 .../crates/api-server/src/modules/admin.rs    |   7 +
 .../crates/shared-contracts/src/admin.rs      |  28 ++++
 .../src/mapper/editor_project.rs              |   4 +
 ..._showcase_campaign_config_snapshot_type.rs |   1 +
 .../editor_showcase_campaign_config_type.rs   |   3 +
 ...wcase_campaign_config_upsert_input_type.rs |   1 +
 .../src/editor_project_storage.rs             |  43 +++---
 .../crates/spacetime-module/src/migration.rs  |   8 ++
 .../image-editor/editorProjectClient.ts       |   1 +
 12 files changed, 234 insertions(+), 15 deletions(-)

diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts
index f63ac4588..8119889cb 100644
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -457,6 +457,7 @@ export interface AdminEditorShowcaseCampaignPayload {
   enabled: boolean;
   title: string;
   imageSrc: string;
+  imageObjectKey?: string | null;
   prompt: string;
   author: string;
   costText: string;
@@ -471,11 +472,37 @@ export interface AdminUpsertEditorShowcaseCampaignRequest {
   enabled: boolean;
   title: string;
   imageSrc: string;
+  imageObjectKey?: string | null;
   prompt: string;
   author: string;
   costText: string;
 }
 
+export interface AdminDirectUploadTicketPayload {
+  bucket: string;
+  host: string;
+  objectKey: string;
+  legacyPublicPath: string;
+  contentType?: string | null;
+  formFields: Record<string, string | null | undefined>;
+}
+
+export interface AdminCreateEditorShowcaseCampaignImageUploadTicketRequest {
+  fileName: string;
+  contentType: string;
+  contentLength: number;
+}
+
+export interface AdminCreateEditorShowcaseCampaignImageUploadTicketResponse {
+  upload: AdminDirectUploadTicketPayload;
+}
+
+export interface AdminUploadedEditorShowcaseCampaignImage {
+  imageSrc: string;
+  imageObjectKey: string;
+  legacyPublicPath: string;
+}
+
 export interface AdminUpsertProfileRedeemCodeRequest {
   code: string;
   mode: ProfileRedeemCodeMode;
diff --git a/server-rs/crates/api-server/src/admin.rs b/server-rs/crates/api-server/src/admin.rs
index 2f39d312a..de103847d 100644
--- a/server-rs/crates/api-server/src/admin.rs
+++ b/server-rs/crates/api-server/src/admin.rs
@@ -18,6 +18,9 @@ use reqwest::Client;
 use serde::Deserialize;
 use serde_json::{Map, Value};
 use shared_contracts::admin::{
+    AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
+    AdminCreateEditorShowcaseCampaignImageUploadTicketResponse,
+    AdminDirectUploadTicketPayload,
     AdminCreationEntryConfigResponse, AdminCreationEntryTypeConfigPayload,
     AdminDashboardBreakdownRowPayload, AdminDashboardChartBucketPayload,
     AdminDashboardChartPayload, AdminDashboardMetricsPayload, AdminDashboardOperationMetricPayload,
@@ -38,6 +41,9 @@ use shared_contracts::admin::{
     AdminUpsertEditorShowcaseCampaignRequest, AdminUpsertPublicWorkInteractionConfigRequest,
     AdminWorkVisibilityListResponse,
 };
+use shared_contracts::assets::{
+    CreateDirectUploadTicketRequest, DirectUploadObjectAccess,
+};
 use shared_contracts::creation_entry_config::{
     encode_unified_creation_spec_response, validate_unified_creation_spec_for_play,
 };
@@ -52,6 +58,7 @@ use time::{OffsetDateTime, format_description::well_known::Rfc3339};
 
 use crate::{
     api_response::json_success_body,
+    assets::create_direct_upload_ticket_for_owner,
     editor_generation_config::EditorGenerationPricingConfig,
     editor_project::current_utc_micros,
     http_error::AppError,
@@ -83,6 +90,7 @@ const ADMIN_DASHBOARD_MAX_PERIOD_DAYS: i64 = 366;
 const ADMIN_EDITOR_ASSET_DEFAULT_LIMIT: u32 = 80;
 const ADMIN_EDITOR_ASSET_MAX_LIMIT: u32 = 200;
 const ADMIN_DASHBOARD_ACTIVE_WINDOW_MICROS: i64 = 5 * 60 * 1_000_000;
+const ADMIN_EDITOR_SHOWCASE_CAMPAIGN_IMAGE_MAX_BYTES: u64 = 20 * 1024 * 1024;
 
 #[derive(Clone, Debug)]
 pub struct AuthenticatedAdmin {
@@ -578,6 +586,7 @@ pub async fn admin_upsert_editor_showcase_campaign(
             enabled: payload.enabled,
             title: payload.title,
             image_src: payload.image_src,
+            image_object_key: payload.image_object_key,
             prompt: payload.prompt,
             author: payload.author,
             cost_text: payload.cost_text,
@@ -592,6 +601,79 @@ pub async fn admin_upsert_editor_showcase_campaign(
     ))
 }
 
+pub async fn admin_create_editor_showcase_campaign_image_upload_ticket(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(admin): Extension<AuthenticatedAdmin>,
+    Json(payload): Json<AdminCreateEditorShowcaseCampaignImageUploadTicketRequest>,
+) -> Result<Json<Value>, AppError> {
+    let file_name = payload.file_name.trim();
+    if file_name.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_message("图片文件名不能为空")
+        );
+    }
+    let content_type = payload.content_type.trim();
+    if !content_type.starts_with("image/") {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_message("活动卡只能上传图片")
+        );
+    }
+    if payload.content_length == 0 {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_message("图片文件不能为空")
+        );
+    }
+    if payload.content_length > ADMIN_EDITOR_SHOWCASE_CAMPAIGN_IMAGE_MAX_BYTES {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST)
+                .with_message("活动卡图片不能超过 20MB")
+        );
+    }
+
+    let ticket = create_direct_upload_ticket_for_owner(
+        &state,
+        &request_context,
+        admin.session().subject.as_str(),
+        CreateDirectUploadTicketRequest {
+            legacy_prefix: "generated-character-drafts".to_string(),
+            path_segments: vec![
+                "editor".to_string(),
+                "showcase-campaign".to_string(),
+                current_utc_micros().to_string(),
+            ],
+            file_name: file_name.to_string(),
+            content_type: Some(content_type.to_string()),
+            access: Some(DirectUploadObjectAccess::Private),
+            metadata: BTreeMap::from([
+                (
+                    "asset_kind".to_string(),
+                    "editor_showcase_campaign_image".to_string(),
+                ),
+                ("source".to_string(), "admin_editor_showcase_campaign".to_string()),
+            ]),
+            max_size_bytes: Some(payload.content_length),
+            expire_seconds: None,
+            success_action_status: Some(200),
+        },
+    )
+    .await?;
+    let axum::Json(value) = ticket;
+    let payload_value = value.get("data").cloned().unwrap_or(value);
+    let response: shared_contracts::assets::CreateDirectUploadTicketResponse =
+        serde_json::from_value(payload_value).map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(serde_json::json!({
+                "message": format!("活动卡上传凭证响应解析失败：{error}"),
+            }))
+        })?;
+    Ok(json_success_body(
+        Some(&request_context),
+        AdminCreateEditorShowcaseCampaignImageUploadTicketResponse {
+            upload: admin_direct_upload_ticket_payload_from_asset_upload(response.upload),
+        },
+    ))
+}
+
 fn build_admin_creation_entry_config_response(
     config: shared_contracts::creation_entry_config::CreationEntryConfigResponse,
 ) -> AdminCreationEntryConfigResponse {
@@ -716,6 +798,7 @@ fn admin_editor_showcase_campaign_payload_from_record(
         enabled: record.enabled,
         title: record.title,
         image_src: record.image_src,
+        image_object_key: record.image_object_key,
         prompt: record.prompt,
         author: record.author,
         cost_text: record.cost_text,
@@ -723,6 +806,47 @@ fn admin_editor_showcase_campaign_payload_from_record(
     }
 }
 
+fn admin_direct_upload_ticket_payload_from_asset_upload(
+    upload: shared_contracts::assets::DirectUploadTicketPayload,
+) -> AdminDirectUploadTicketPayload {
+    let mut form_fields = BTreeMap::from([
+        ("key".to_string(), upload.form_fields.key),
+        ("policy".to_string(), upload.form_fields.policy),
+        (
+            "x-oss-signature-version".to_string(),
+            upload.form_fields.signature_version,
+        ),
+        (
+            "x-oss-credential".to_string(),
+            upload.form_fields.credential,
+        ),
+        ("x-oss-date".to_string(), upload.form_fields.date),
+        (
+            "x-oss-signature".to_string(),
+            upload.form_fields.signature,
+        ),
+        (
+            "success_action_status".to_string(),
+            upload.form_fields.success_action_status,
+        ),
+    ]);
+    if let Some(content_type) = upload.form_fields.content_type {
+        form_fields.insert("Content-Type".to_string(), content_type);
+    }
+    if let Some(cache_control) = upload.form_fields.cache_control {
+        form_fields.insert("Cache-Control".to_string(), cache_control);
+    }
+    form_fields.extend(upload.form_fields.metadata);
+
+    AdminDirectUploadTicketPayload {
+        bucket: upload.bucket,
+        host: upload.host,
+        object_key: upload.object_key,
+        legacy_public_path: upload.legacy_public_path,
+        form_fields,
+    }
+}
+
 fn editor_showcase_admin_cursor(record: &EditorShowcaseAssetRecord) -> Option<String> {
     let submitted_at_micros = parse_timestamp_text_to_micros(record.submitted_at.as_str())?;
     Some(format!("{submitted_at_micros}:{}", record.showcase_id))
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index 2435ea990..c675aff21 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -617,6 +617,7 @@ pub struct EditorShowcaseCampaignPayload {
     enabled: bool,
     title: String,
     image_src: String,
+    image_object_key: Option<String>,
     prompt: String,
     author: String,
     cost_text: String,
@@ -3350,6 +3351,7 @@ fn editor_showcase_campaign_payload_from_record(
         enabled: record.enabled,
         title: record.title,
         image_src: record.image_src,
+        image_object_key: record.image_object_key,
         prompt: record.prompt,
         author: record.author,
         cost_text: record.cost_text,
diff --git a/server-rs/crates/api-server/src/modules/admin.rs b/server-rs/crates/api-server/src/modules/admin.rs
index 025500d85..44e6b5afd 100644
--- a/server-rs/crates/api-server/src/modules/admin.rs
+++ b/server-rs/crates/api-server/src/modules/admin.rs
@@ -6,6 +6,7 @@ use axum::{
 use crate::{
     admin::{
         admin_dashboard, admin_debug_http, admin_get_creation_entry_config,
+        admin_create_editor_showcase_campaign_image_upload_ticket,
         admin_get_editor_generation_pricing, admin_get_editor_showcase_campaign,
         admin_list_database_table_rows, admin_list_database_tables,
         admin_list_editor_assets, admin_list_editor_showcase_assets, admin_list_tracking_event_keys,
@@ -152,6 +153,12 @@ pub fn router(state: AppState) -> Router<AppState> {
                     require_admin_auth,
                 )),
         )
+        .route(
+            "/admin/api/editor-showcase/campaign/image-upload-ticket",
+            post(admin_create_editor_showcase_campaign_image_upload_ticket).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_admin_auth),
+            ),
+        )
         .route(
             "/admin/api/works/visibility",
             get(admin_list_work_visibility)
diff --git a/server-rs/crates/shared-contracts/src/admin.rs b/server-rs/crates/shared-contracts/src/admin.rs
index cb9b83d7b..3f157b185 100644
--- a/server-rs/crates/shared-contracts/src/admin.rs
+++ b/server-rs/crates/shared-contracts/src/admin.rs
@@ -1,3 +1,5 @@
+use std::collections::BTreeMap;
+
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
@@ -254,6 +256,7 @@ pub struct AdminEditorShowcaseCampaignPayload {
     pub enabled: bool,
     pub title: String,
     pub image_src: String,
+    pub image_object_key: Option<String>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
@@ -272,11 +275,36 @@ pub struct AdminUpsertEditorShowcaseCampaignRequest {
     pub enabled: bool,
     pub title: String,
     pub image_src: String,
+    pub image_object_key: Option<String>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
 }
 
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminCreateEditorShowcaseCampaignImageUploadTicketRequest {
+    pub file_name: String,
+    pub content_type: String,
+    pub content_length: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminCreateEditorShowcaseCampaignImageUploadTicketResponse {
+    pub upload: AdminDirectUploadTicketPayload,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct AdminDirectUploadTicketPayload {
+    pub bucket: String,
+    pub host: String,
+    pub object_key: String,
+    pub legacy_public_path: String,
+    pub form_fields: BTreeMap<String, String>,
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 pub struct AdminLoginResponse {
diff --git a/server-rs/crates/spacetime-client/src/mapper/editor_project.rs b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
index 38865c15f..5dce27889 100644
--- a/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
+++ b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
@@ -180,6 +180,7 @@ pub struct EditorShowcaseCampaignConfigRecord {
     pub enabled: bool,
     pub title: String,
     pub image_src: String,
+    pub image_object_key: Option<String>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
@@ -426,6 +427,7 @@ pub struct EditorShowcaseCampaignConfigUpsertRecordInput {
     pub author: String,
     pub cost_text: String,
     pub updated_at_micros: i64,
+    pub image_object_key: Option<String>,
 }
 
 impl From<EditorProjectCreateRecordInput> for crate::module_bindings::EditorProjectCreateInput {
@@ -783,6 +785,7 @@ impl From<EditorShowcaseCampaignConfigUpsertRecordInput>
             author: input.author,
             cost_text: input.cost_text,
             updated_at_micros: input.updated_at_micros,
+            image_object_key: input.image_object_key,
         }
     }
 }
@@ -1214,6 +1217,7 @@ fn map_editor_showcase_campaign_config_snapshot(
         enabled: snapshot.enabled,
         title: snapshot.title,
         image_src: snapshot.image_src,
+        image_object_key: snapshot.image_object_key,
         prompt: snapshot.prompt,
         author: snapshot.author,
         cost_text: snapshot.cost_text,
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
index 5f71e9552..2850679db 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
@@ -15,6 +15,7 @@ pub struct EditorShowcaseCampaignConfigSnapshot {
     pub cost_text: String,
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at_micros: i64,
+    pub image_object_key: Option<String>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfigSnapshot {
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
index 44b188966..dbf215e0d 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
@@ -16,6 +16,7 @@ pub struct EditorShowcaseCampaignConfig {
     pub cost_text: String,
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at: __sdk::Timestamp,
+    pub image_object_key: Option<String>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfig {
@@ -36,6 +37,7 @@ pub struct EditorShowcaseCampaignConfigCols {
     pub updated_by_admin_user_id:
         __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<String>>,
     pub updated_at: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, __sdk::Timestamp>,
+    pub image_object_key: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<String>>,
 }
 
 impl __sdk::__query_builder::HasCols for EditorShowcaseCampaignConfig {
@@ -54,6 +56,7 @@ impl __sdk::__query_builder::HasCols for EditorShowcaseCampaignConfig {
                 "updated_by_admin_user_id",
             ),
             updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            image_object_key: __sdk::__query_builder::Col::new(table_name, "image_object_key"),
         }
     }
 }
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
index 813101fd1..b093fc4e0 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
@@ -15,6 +15,7 @@ pub struct EditorShowcaseCampaignConfigUpsertInput {
     pub author: String,
     pub cost_text: String,
     pub updated_at_micros: i64,
+    pub image_object_key: Option<String>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfigUpsertInput {
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 ba6ff8e43..a330706c0 100644
--- a/server-rs/crates/spacetime-module/src/editor_project_storage.rs
+++ b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
@@ -13,7 +13,7 @@ const EDITOR_SHOWCASE_STATUS_PENDING: &str = "pending";
 const EDITOR_SHOWCASE_STATUS_APPROVED: &str = "approved";
 const EDITOR_SHOWCASE_STATUS_REJECTED: &str = "rejected";
 const EDITOR_SHOWCASE_CAMPAIGN_CONFIG_ID: &str = "global";
-const EDITOR_SHOWCASE_CATEGORIES: [&str; 5] = ["packs", "characters", "ui", "music", "marketing"];
+const EDITOR_SHOWCASE_CATEGORIES: [&str; 4] = ["characters", "ui", "music", "marketing"];
 
 #[spacetimedb::table(
     accessor = editor_project,
@@ -205,6 +205,8 @@ pub struct EditorShowcaseCampaignConfig {
     cost_text: String,
     updated_by_admin_user_id: Option<String>,
     updated_at: Timestamp,
+    #[default(None::<String>)]
+    image_object_key: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, SpacetimeType)]
@@ -463,6 +465,7 @@ pub struct EditorShowcaseCampaignConfigSnapshot {
     pub cost_text: String,
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at_micros: i64,
+    pub image_object_key: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
@@ -617,6 +620,7 @@ pub struct EditorShowcaseCampaignConfigUpsertInput {
     pub author: String,
     pub cost_text: String,
     pub updated_at_micros: i64,
+    pub image_object_key: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, SpacetimeType)]
@@ -1931,10 +1935,6 @@ fn list_public_editor_showcase_assets(
                 && asset.display_enabled
                 && !asset.asset_deleted_while_pending
                 && (asset.refund_mud_points == 0 || asset.refund_completed_at.is_some())
-                && asset
-                    .showcase_category
-                    .as_deref()
-                    .is_some_and(is_valid_showcase_category)
                 && !asset.image_src.trim().is_empty()
                 && is_after_public_showcase_cursor(
                     approved_at_micros,
@@ -2077,14 +2077,11 @@ fn update_editor_showcase_asset_display(
     if asset.asset_deleted_while_pending {
         return Err("素材已删除，不能公开展示".to_string());
     }
-    let showcase_category = input
-        .showcase_category
-        .map(|value| normalize_showcase_category(value.as_str()))
-        .transpose()?
-        .or_else(|| asset.showcase_category.clone());
-    if input.display_enabled && showcase_category.is_none() {
-        return Err("公开展示前必须先设置精选分类".to_string());
-    }
+    let showcase_category = match input.showcase_category {
+        Some(value) if value.trim().is_empty() => None,
+        Some(value) => Some(normalize_showcase_category(value.as_str())?),
+        None => asset.showcase_category.clone(),
+    };
     if input.display_enabled && asset.refund_mud_points > 0 && asset.refund_completed_at.is_none() {
         return Err("精选返还完成前不能公开展示".to_string());
     }
@@ -2203,7 +2200,9 @@ fn upsert_editor_showcase_campaign_config(
         "editor_showcase_campaign_config.updated_by_admin_user_id",
     )?;
     let title = input.title.trim().to_string();
-    let image_src = input.image_src.trim().to_string();
+    let image_object_key = normalize_optional(input.image_object_key)
+        .map(|value| value.trim_start_matches('/').to_string());
+    let image_src = normalize_campaign_image_src(input.image_src.as_str(), image_object_key.as_deref());
     if input.enabled {
         if title.is_empty() {
             return Err("editor_showcase_campaign_config.title 不能为空".to_string());
@@ -2238,6 +2237,7 @@ fn upsert_editor_showcase_campaign_config(
             cost_text: input.cost_text.trim().to_string(),
             updated_by_admin_user_id: Some(admin_user_id),
             updated_at: now,
+            image_object_key,
         });
     ctx.db
         .editor_showcase_campaign_config()
@@ -2614,7 +2614,7 @@ fn normalize_showcase_category(value: &str) -> Result<String, String> {
     if is_valid_showcase_category(normalized) {
         return Ok(normalized.to_string());
     }
-    Err("精选分类只支持 packs、characters、ui、music 或 marketing".to_string())
+    Err("精选分类只支持 characters、ui、music 或 marketing".to_string())
 }
 
 fn is_valid_showcase_category(value: &str) -> bool {
@@ -2712,9 +2712,22 @@ fn showcase_campaign_config_snapshot_from_row(
         cost_text: row.cost_text,
         updated_by_admin_user_id: row.updated_by_admin_user_id,
         updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+        image_object_key: row.image_object_key,
     }
 }
 
+fn normalize_campaign_image_src(raw_image_src: &str, image_object_key: Option<&str>) -> String {
+    let image_src = raw_image_src.trim();
+    if !image_src.is_empty() {
+        return image_src.to_string();
+    }
+    image_object_key
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(|value| format!("/{}", value.trim_start_matches('/')))
+        .unwrap_or_default()
+}
+
 fn timestamp_option_micros(value: Option<Timestamp>) -> Option<i64> {
     value.map(|timestamp| timestamp.to_micros_since_unix_epoch())
 }
diff --git a/server-rs/crates/spacetime-module/src/migration.rs b/server-rs/crates/spacetime-module/src/migration.rs
index ad2897b97..1be3b8d9d 100644
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -1265,6 +1265,14 @@ fn normalize_migration_row(table_name: &str, value: &serde_json::Value) -> serde
                 .or_insert(serde_json::Value::Null);
         }
     }
+    if table_name == "editor_showcase_campaign_config" {
+        if let Some(object) = next_value.as_object_mut() {
+            // 中文注释：活动卡图片 Object Key 晚于活动卡表加入，旧迁移包按仅有图片地址兼容。
+            object
+                .entry("image_object_key".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/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
index 18b9020f3..26b6c9320 100644
--- a/src/services/image-editor/editorProjectClient.ts
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -138,6 +138,7 @@ export type EditorShowcaseCampaignSnapshot = {
   enabled: boolean;
   title: string;
   imageSrc: string;
+  imageObjectKey?: string | null;
   prompt: string;
   author: string;
   costText: string;

From 68e90875523798bb425e113e1cf996fbc332d291 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 18:57:20 +0800
Subject: [PATCH 05/24] =?UTF-8?q?=E5=AE=8C=E5=96=84=E5=90=8E=E5=8F=B0?=
 =?UTF-8?q?=E7=B2=BE=E9=80=89=E6=B4=BB=E5=8A=A8=E5=8D=A1=E4=B8=8A=E4=BC=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

后台精选活动卡支持选择图片并通过 OSS 直传凭证上传。

保存活动卡时同步 imageSrc 和 imageObjectKey。

移除后台素材包分类选项，清空分类时不再自动隐藏精选素材。

补充后台活动卡上传和分类交互测试。
---
 apps/admin-web/src/api/adminApiClient.ts      | 78 +++++++++++++++
 .../AdminEditorShowcaseReviewPage.test.tsx    | 58 ++++++++++-
 .../pages/AdminEditorShowcaseReviewPage.tsx   | 95 ++++++++++++++++---
 apps/admin-web/src/styles/admin.css           | 14 +++
 4 files changed, 226 insertions(+), 19 deletions(-)

diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts
index ff5306b42..10e0215ce 100644
--- a/apps/admin-web/src/api/adminApiClient.ts
+++ b/apps/admin-web/src/api/adminApiClient.ts
@@ -11,8 +11,11 @@ import type {
   AdminDatabaseTableListResponse,
   AdminDatabaseTableRowsQuery,
   AdminDatabaseTableRowsResponse,
+  AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
+  AdminCreateEditorShowcaseCampaignImageUploadTicketResponse,
   AdminEditorAssetListQuery,
   AdminEditorAssetListResponse,
+  AdminDirectUploadTicketPayload,
   AdminEditorShowcaseAssetResponse,
   AdminEditorShowcaseCampaignResponse,
   AdminEditorShowcaseDisplayRequest,
@@ -27,6 +30,7 @@ import type {
   AdminTrackingEventListResponse,
   AdminUpdateWorkVisibilityRequest,
   AdminUpdateWorkVisibilityResponse,
+  AdminUploadedEditorShowcaseCampaignImage,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertProfileInviteCodeRequest,
   AdminUpsertProfileRechargeProductRequest,
@@ -394,6 +398,32 @@ export function upsertAdminEditorShowcaseCampaign(
   );
 }
 
+export async function uploadAdminEditorShowcaseCampaignImage(
+  token: string,
+  file: File,
+): Promise<AdminUploadedEditorShowcaseCampaignImage> {
+  const contentType = resolveAdminImageContentType(file);
+  const response = await request<AdminCreateEditorShowcaseCampaignImageUploadTicketResponse>(
+    '/admin/api/editor-showcase/campaign/image-upload-ticket',
+    {
+      method: 'POST',
+      token,
+      body: {
+        fileName: file.name.trim() || 'showcase-campaign.png',
+        contentType,
+        contentLength: file.size,
+      } satisfies AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
+    },
+  );
+  await postAdminDirectUploadFile(response.upload, file);
+  const objectKey = response.upload.objectKey.trim().replace(/^\/+/u, '');
+  return {
+    imageSrc: objectKey ? `/${objectKey}` : response.upload.legacyPublicPath,
+    imageObjectKey: objectKey,
+    legacyPublicPath: response.upload.legacyPublicPath,
+  };
+}
+
 export function listProfileRedeemCodes(token: string) {
   return request<ProfileRedeemCodeAdminListResponse>(
     '/admin/api/profile/redeem-codes',
@@ -556,6 +586,54 @@ function buildAssetReadUrlQuery(query: AdminAssetReadUrlQuery) {
   return queryString ? `?${queryString}` : '';
 }
 
+function resolveAdminImageContentType(file: File) {
+  const declaredType = file.type.trim();
+  if (declaredType.startsWith('image/')) {
+    return declaredType;
+  }
+  const extension = file.name.trim().toLowerCase().match(/\.([a-z0-9]+)$/u)?.[1];
+  if (extension === 'jpg' || extension === 'jpeg') {
+    return 'image/jpeg';
+  }
+  if (extension === 'png') {
+    return 'image/png';
+  }
+  if (extension === 'webp') {
+    return 'image/webp';
+  }
+  if (extension === 'gif') {
+    return 'image/gif';
+  }
+  return declaredType || 'application/octet-stream';
+}
+
+function buildAdminDirectUploadFormData(
+  upload: AdminDirectUploadTicketPayload,
+  file: File,
+) {
+  const formData = new FormData();
+  Object.entries(upload.formFields).forEach(([key, value]) => {
+    if (value !== null && value !== undefined) {
+      formData.append(key, value);
+    }
+  });
+  formData.append('file', file, file.name);
+  return formData;
+}
+
+async function postAdminDirectUploadFile(
+  upload: AdminDirectUploadTicketPayload,
+  file: File,
+) {
+  const response = await fetch(upload.host, {
+    method: 'POST',
+    body: buildAdminDirectUploadFormData(upload, file),
+  });
+  if (!response.ok) {
+    throw new Error(`上传活动卡图片失败：HTTP ${response.status}`);
+  }
+}
+
 function buildQueryString(query: AdminTrackingEventListQuery) {
   const params = new URLSearchParams();
   appendQueryParam(params, 'eventKey', query.eventKey);
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
index 90cd99289..4c384daee 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
@@ -15,6 +15,7 @@ import {
   listAdminEditorShowcaseAssets,
   reviewAdminEditorShowcaseAsset,
   updateAdminEditorShowcaseDisplay,
+  uploadAdminEditorShowcaseCampaignImage,
   upsertAdminEditorShowcaseCampaign,
 } from '../api/adminApiClient';
 import type { AdminEditorShowcaseAssetPayload } from '../api/adminApiTypes';
@@ -26,6 +27,7 @@ vi.mock('../api/adminApiClient', () => ({
   listAdminEditorShowcaseAssets: vi.fn(),
   reviewAdminEditorShowcaseAsset: vi.fn(),
   updateAdminEditorShowcaseDisplay: vi.fn(),
+  uploadAdminEditorShowcaseCampaignImage: vi.fn(),
   upsertAdminEditorShowcaseCampaign: vi.fn(),
 }));
 
@@ -88,6 +90,7 @@ beforeEach(() => {
       enabled: true,
       title: '活动卡',
       imageSrc: '/campaign.png',
+      imageObjectKey: null,
       prompt: '活动提示词',
       author: '官方',
       costText: '12 泥点',
@@ -121,12 +124,20 @@ beforeEach(() => {
       enabled: false,
       title: '新活动卡',
       imageSrc: '/new-campaign.png',
+      imageObjectKey: null,
       prompt: '新活动提示词',
       author: '官方',
       costText: '6 泥点',
       updatedAt: '2026-07-04T10:20:00Z',
     },
   });
+  vi.mocked(uploadAdminEditorShowcaseCampaignImage).mockResolvedValue({
+    imageSrc: '/generated-character-drafts/editor/showcase-campaign/card.png',
+    imageObjectKey:
+      'generated-character-drafts/editor/showcase-campaign/card.png',
+    legacyPublicPath:
+      '/generated-character-drafts/editor/showcase-campaign/card.png',
+  });
 });
 
 test('后台精选审核展示待审核素材和活动卡配置', async () => {
@@ -273,12 +284,51 @@ test('后台精选审核可以切换展示和保存活动卡', async () => {
       expect.objectContaining({
         title: '新活动卡',
         imageSrc: '/new-campaign.png',
+        imageObjectKey: null,
         costText: '6 泥点',
       }),
     );
   });
 });
 
+test('后台精选活动卡可以上传图片并保存 objectKey', async () => {
+  render(
+    <AdminEditorShowcaseReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  await screen.findByDisplayValue('活动卡');
+  const file = new File(['image-bytes'], 'card.png', { type: 'image/png' });
+  fireEvent.change(screen.getByLabelText('上传活动卡图片'), {
+    target: { files: [file] },
+  });
+
+  await waitFor(() => {
+    expect(uploadAdminEditorShowcaseCampaignImage).toHaveBeenCalledWith(
+      'admin-token',
+      file,
+    );
+  });
+  expect(await screen.findByDisplayValue('/generated-character-drafts/editor/showcase-campaign/card.png')).toBeTruthy();
+  expect(screen.getByDisplayValue('generated-character-drafts/editor/showcase-campaign/card.png')).toBeTruthy();
+
+  fireEvent.click(screen.getByRole('button', { name: '保存活动卡' }));
+
+  await waitFor(() => {
+    expect(upsertAdminEditorShowcaseCampaign).toHaveBeenCalledWith(
+      'admin-token',
+      expect.objectContaining({
+        imageSrc:
+          '/generated-character-drafts/editor/showcase-campaign/card.png',
+        imageObjectKey:
+          'generated-character-drafts/editor/showcase-campaign/card.png',
+      }),
+    );
+  });
+});
+
 test('后台精选审核已通过素材可以设置精选分类', async () => {
   vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
     entries: [
@@ -321,7 +371,7 @@ test('后台精选审核已通过素材可以设置精选分类', async () => {
   });
 });
 
-test('后台精选审核清空精选分类时自动隐藏素材', async () => {
+test('后台精选审核清空精选分类时不会自动隐藏素材', async () => {
   vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
     entries: [approvedShowcaseAsset],
     nextCursor: null,
@@ -330,7 +380,7 @@ test('后台精选审核清空精选分类时自动隐藏素材', async () => {
     entry: {
       ...approvedShowcaseAsset,
       showcaseCategory: null,
-      displayEnabled: false,
+      displayEnabled: true,
     },
   });
 
@@ -350,8 +400,8 @@ test('后台精选审核清空精选分类时自动隐藏素材', async () => {
       'admin-token',
       {
         showcaseId: 'showcase-2',
-        displayEnabled: false,
-        showcaseCategory: null,
+        displayEnabled: true,
+        showcaseCategory: '',
       },
     );
   });
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
index 1988dfab4..ebf45a2e5 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
@@ -1,6 +1,6 @@
-import { Eye, FileText, RefreshCcw, X } from 'lucide-react';
+import { Eye, FileText, RefreshCcw, Upload, X } from 'lucide-react';
 import type { ReactNode } from 'react';
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 import {
   getAdminAssetReadUrl,
@@ -8,6 +8,7 @@ import {
   listAdminEditorShowcaseAssets,
   reviewAdminEditorShowcaseAsset,
   updateAdminEditorShowcaseDisplay,
+  uploadAdminEditorShowcaseCampaignImage,
   upsertAdminEditorShowcaseCampaign,
 } from '../api/adminApiClient';
 import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
@@ -27,7 +28,6 @@ const ADMIN_SHOWCASE_READ_EXPIRE_SECONDS = 300;
 const AUDIO_ASSET_COVER_SRC = '/creation-home/audio-asset-cover.png';
 
 const showcaseCategoryOptions = [
-  { value: 'packs', label: '素材包' },
   { value: 'characters', label: '角色' },
   { value: 'ui', label: 'UI' },
   { value: 'music', label: '音乐' },
@@ -69,8 +69,12 @@ export function AdminEditorShowcaseReviewPage({
       prompt: '',
       author: '',
       costText: '',
+      imageObjectKey: null,
     });
   const [isSavingCampaign, setIsSavingCampaign] = useState(false);
+  const [isUploadingCampaignImage, setIsUploadingCampaignImage] =
+    useState(false);
+  const campaignImageInputRef = useRef<HTMLInputElement | null>(null);
 
   useEffect(() => {
     void refreshPage();
@@ -176,11 +180,11 @@ export function AdminEditorShowcaseReviewPage({
     showcaseCategory: string,
   ) {
     setErrorMessage('');
-    const nextCategory = showcaseCategory.trim() || null;
+    const nextCategory = showcaseCategory.trim();
     try {
       const response = await updateAdminEditorShowcaseDisplay(token, {
         showcaseId: entry.showcaseId,
-        displayEnabled: nextCategory ? entry.displayEnabled : false,
+        displayEnabled: entry.displayEnabled,
         showcaseCategory: nextCategory,
       });
       replaceEntry(response.entry);
@@ -197,6 +201,7 @@ export function AdminEditorShowcaseReviewPage({
         enabled: campaignDraft.enabled,
         title: campaignDraft.title,
         imageSrc: campaignDraft.imageSrc,
+        imageObjectKey: campaignDraft.imageObjectKey ?? null,
         prompt: campaignDraft.prompt,
         author: campaignDraft.author,
         costText: campaignDraft.costText,
@@ -211,6 +216,29 @@ export function AdminEditorShowcaseReviewPage({
     }
   }
 
+  async function handleCampaignImageFile(file: File | null | undefined) {
+    if (!file) {
+      return;
+    }
+    setIsUploadingCampaignImage(true);
+    setErrorMessage('');
+    try {
+      const upload = await uploadAdminEditorShowcaseCampaignImage(token, file);
+      setCampaignDraft((current) => ({
+        ...current,
+        imageSrc: upload.imageSrc,
+        imageObjectKey: upload.imageObjectKey,
+      }));
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsUploadingCampaignImage(false);
+      if (campaignImageInputRef.current) {
+        campaignImageInputRef.current.value = '';
+      }
+    }
+  }
+
   function replaceEntry(entry: AdminEditorShowcaseAssetPayload) {
     setEntries((current) =>
       current.map((item) =>
@@ -348,11 +376,7 @@ export function AdminEditorShowcaseReviewPage({
                       </span>
                       {entry.reviewStatus === 'approved' ? (
                         <small>
-                          {entry.displayEnabled
-                            ? '展示中'
-                            : entry.showcaseCategory
-                              ? '已隐藏'
-                              : '待设置分类'}
+                          {entry.displayEnabled ? '展示中' : '未展示'}
                         </small>
                       ) : null}
                     </td>
@@ -482,13 +506,54 @@ export function AdminEditorShowcaseReviewPage({
           </label>
           <label className="admin-field">
             <span>图片地址</span>
+            <div className="admin-showcase-campaign-image-row">
+              <input
+                value={campaignDraft.imageSrc}
+                onChange={(event) =>
+                  setCampaignDraft((current) => ({
+                    ...current,
+                    imageSrc: event.target.value,
+                    imageObjectKey: null,
+                  }))
+                }
+              />
+              <input
+                ref={campaignImageInputRef}
+                aria-label="上传活动卡图片"
+                className="admin-hidden-file-input"
+                type="file"
+                accept="image/*"
+                onChange={(event) =>
+                  handleCampaignImageFile(event.currentTarget.files?.[0])
+                }
+              />
+              <button
+                className="admin-secondary-button"
+                disabled={isUploadingCampaignImage}
+                type="button"
+                onClick={() => campaignImageInputRef.current?.click()}
+              >
+                <Upload size={16} aria-hidden="true" />
+                <span>{isUploadingCampaignImage ? '上传中' : '上传'}</span>
+              </button>
+            </div>
+          </label>
+          <label className="admin-field">
+            <span>Object Key</span>
             <input
-              value={campaignDraft.imageSrc}
+              value={campaignDraft.imageObjectKey ?? ''}
               onChange={(event) =>
-                setCampaignDraft((current) => ({
-                  ...current,
-                  imageSrc: event.target.value,
-                }))
+                setCampaignDraft((current) => {
+                  const imageObjectKey =
+                    event.target.value.trim().replace(/^\/+/u, '') || null;
+                  return {
+                    ...current,
+                    imageObjectKey,
+                    imageSrc: imageObjectKey
+                      ? `/${imageObjectKey}`
+                      : current.imageSrc,
+                  };
+                })
               }
             />
           </label>
diff --git a/apps/admin-web/src/styles/admin.css b/apps/admin-web/src/styles/admin.css
index b281b1dec..08dc8b68d 100644
--- a/apps/admin-web/src/styles/admin.css
+++ b/apps/admin-web/src/styles/admin.css
@@ -1091,6 +1091,20 @@ button:disabled {
   min-width: 160px;
 }
 
+.admin-hidden-file-input {
+  display: none;
+}
+
+.admin-showcase-campaign-image-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.admin-showcase-campaign-image-row input {
+  min-width: 0;
+}
+
 .admin-showcase-campaign-prompt {
   min-width: min(100%, 320px);
 }

From 51c47c952b7be974660e7cc4bc3079d95d5be1af Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 18:58:58 +0800
Subject: [PATCH 06/24] =?UTF-8?q?=E8=B0=83=E6=95=B4=E5=89=8D=E5=8F=B0?=
 =?UTF-8?q?=E7=B2=BE=E9=80=89=E5=88=86=E7=B1=BB=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

前台精选分类新增全部并作为默认 Tab。

移除素材包 Tab 和素材包组合逻辑，未设置分类素材保留在全部中。

活动卡支持从 imageObjectKey 兜底图片地址。

精选卡片改为网格布局并让图片素材铺满预览区域。

更新前台精选模型和创作主页测试。
---
 .../CreationLandingView.test.tsx              | 29 ++++----
 .../creation-home/CreationLandingView.tsx     |  6 +-
 .../creationShowcaseModel.test.ts             | 72 ++++++++++---------
 .../creation-home/creationShowcaseModel.ts    | 64 ++++-------------
 src/index.css                                 | 27 ++++---
 5 files changed, 89 insertions(+), 109 deletions(-)

diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
index e54762ba5..a403c7f45 100644
--- a/src/components/creation-home/CreationLandingView.test.tsx
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -167,7 +167,8 @@ describe('CreationLandingView', () => {
     expect(screen.getByRole('heading', { name: '创作工具' })).toBeTruthy();
     expect(screen.getByText('游戏视觉规范')).toBeTruthy();
     expect(screen.getByRole('heading', { name: '陶泥儿精选' })).toBeTruthy();
-    expect(screen.getByRole('tab', { name: '素材包' })).toBeTruthy();
+    expect(screen.getByRole('tab', { name: '全部' })).toBeTruthy();
+    expect(screen.queryByRole('tab', { name: '素材包' })).toBeNull();
     expect(screen.queryByRole('tab', { name: '特效' })).toBeNull();
     expect(screen.queryByRole('tab', { name: '场景' })).toBeNull();
     expect(screen.queryByRole('tab', { name: '游戏' })).toBeNull();
@@ -557,12 +558,12 @@ describe('CreationLandingView', () => {
       {
         resourceId: 'resource-pack-a',
         projectId: 'project-newest',
-        label: '素材包 A',
+        label: '精选素材 A',
         imageSrc: 'data:image/png;base64,a',
         width: 512,
         height: 640,
         sourceType: 'generated',
-        prompt: '素材包提示词',
+        prompt: '精选素材提示词',
         actualPrompt: null,
         model: null,
         provider: null,
@@ -585,7 +586,7 @@ describe('CreationLandingView', () => {
       {
         resourceId: 'resource-pack-b',
         projectId: 'project-old',
-        label: '素材包 B',
+        label: '精选素材 B',
         imageSrc: 'data:image/png;base64,b',
         width: 512,
         height: 512,
@@ -600,8 +601,8 @@ describe('CreationLandingView', () => {
 
     const { container } = renderCreationLanding();
 
-    expect(await screen.findByText('素材包 A')).toBeTruthy();
-    expect(screen.getByText('素材包 B')).toBeTruthy();
+    expect(await screen.findByText('精选素材 A')).toBeTruthy();
+    expect(screen.getByText('精选素材 B')).toBeTruthy();
     expect(screen.queryByText('上传素材')).toBeNull();
     expect(screen.getByLabelText('用户素材瀑布流').className).toContain(
       'creation-landing__asset-waterfall',
@@ -623,7 +624,7 @@ describe('CreationLandingView', () => {
           {
             resourceId: 'resource-pack-a',
             projectId: 'project-newest',
-            label: '素材包 A',
+            label: '精选素材 A',
             imageSrc: 'data:image/png;base64,a',
             width: 512,
             height: 640,
@@ -642,7 +643,7 @@ describe('CreationLandingView', () => {
           {
             resourceId: 'resource-pack-b',
             projectId: 'project-old',
-            label: '素材包 B',
+            label: '精选素材 B',
             imageSrc: 'data:image/png;base64,b',
             width: 512,
             height: 512,
@@ -659,12 +660,12 @@ describe('CreationLandingView', () => {
 
     renderCreationLanding();
 
-    expect(await screen.findByText('素材包 A')).toBeTruthy();
+    expect(await screen.findByText('精选素材 A')).toBeTruthy();
     await waitFor(() => expect(observers).toHaveLength(1));
-    expect(screen.queryByText('素材包 B')).toBeNull();
+    expect(screen.queryByText('精选素材 B')).toBeNull();
     triggerIntersection(observers[0]!);
     triggerIntersection(observers[0]!);
-    expect(await screen.findByText('素材包 B')).toBeTruthy();
+    expect(await screen.findByText('精选素材 B')).toBeTruthy();
     await waitFor(() =>
       expect(listPublicEditorProjectResourcesMock).toHaveBeenLastCalledWith({
         cursor: 'cursor-page-2',
@@ -682,7 +683,7 @@ describe('CreationLandingView', () => {
           {
             resourceId: 'resource-pack-a',
             projectId: 'project-newest',
-            label: '素材包 A',
+            label: '精选素材 A',
             imageSrc: 'data:image/png;base64,a',
             width: 512,
             height: 640,
@@ -700,14 +701,14 @@ describe('CreationLandingView', () => {
 
     renderCreationLanding();
 
-    expect(await screen.findByText('素材包 A')).toBeTruthy();
+    expect(await screen.findByText('精选素材 A')).toBeTruthy();
     await waitFor(() => expect(observers).toHaveLength(1));
     triggerIntersection(observers[0]!);
 
     expect(
       await screen.findByRole('button', { name: '读取更多素材失败，点击重试' }),
     ).toBeTruthy();
-    expect(screen.getByText('素材包 A')).toBeTruthy();
+    expect(screen.getByText('精选素材 A')).toBeTruthy();
     expect(screen.getByLabelText('用户素材瀑布流')).toBeTruthy();
   });
 
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
index 64f8a2cf1..ec07c8e04 100644
--- a/src/components/creation-home/CreationLandingView.tsx
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -247,7 +247,7 @@ function ShowcaseImagePreview({
       className={
         variant === 'modal'
           ? 'creation-landing__showcase-media'
-          : 'h-full w-full object-contain'
+          : 'creation-landing__asset-preview-media'
       }
     />
   );
@@ -269,7 +269,7 @@ function ShowcaseVideoPreview({
       className={
         variant === 'modal'
           ? 'creation-landing__showcase-media'
-          : 'h-full w-full object-contain'
+          : 'creation-landing__asset-preview-media'
       }
       controls={controls}
       muted={!controls}
@@ -470,7 +470,7 @@ export function CreationLandingView({
     string | null
   >(null);
   const [activeShowcaseTab, setActiveShowcaseTab] =
-    useState<ShowcaseTabId>('packs');
+    useState<ShowcaseTabId>('all');
   const [selectedShowcaseItem, setSelectedShowcaseItem] =
     useState<ShowcaseAssetItem | null>(null);
   const [selectedShowcaseIndex, setSelectedShowcaseIndex] = useState(0);
diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
index e108cb496..53afccd73 100644
--- a/src/components/creation-home/creationShowcaseModel.test.ts
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -26,7 +26,7 @@ function createResource(
 describe('creationShowcaseModel', () => {
   it('only builds showcase items from generated project resources', () => {
     const items = buildCreationShowcaseItems({
-      activeTab: 'packs',
+      activeTab: 'all',
       projectResources: [
         createResource({
           resourceId: 'generated-1',
@@ -55,7 +55,7 @@ describe('creationShowcaseModel', () => {
 
   it('filters out generated showcase records with display disabled', () => {
     const items = buildCreationShowcaseItems({
-      activeTab: 'packs',
+      activeTab: 'all',
       projectResources: [
         createResource({
           resourceId: 'public-generated',
@@ -78,7 +78,7 @@ describe('creationShowcaseModel', () => {
 
   it('prepends enabled campaign cards and keeps showcase metrics', () => {
     const items = buildCreationShowcaseItems({
-      activeTab: 'packs',
+      activeTab: 'all',
       campaign: {
         enabled: true,
         title: '活动精选',
@@ -109,7 +109,7 @@ describe('creationShowcaseModel', () => {
       cost: '50泥点',
     });
     expect(items[1]).toMatchObject({
-      id: 'standalone:asset-1',
+      id: 'asset:asset-1',
       label: '审核通过素材',
       likeCount: 12,
       showcaseId: 'showcase-1',
@@ -215,9 +215,9 @@ describe('creationShowcaseModel', () => {
     expect(items[0]?.previews[0]?.id).toBe('resource-original');
   });
 
-  it('groups pack items by the same referenced spec image and sums known cost', () => {
+  it('shows every real asset in the all tab without requiring a category', () => {
     const items = buildCreationShowcaseItems({
-      activeTab: 'packs',
+      activeTab: 'all',
       projectResources: [
         createResource({
           resourceId: 'spec-1',
@@ -247,51 +247,55 @@ describe('creationShowcaseModel', () => {
       ],
     });
 
-    expect(items).toHaveLength(1);
-    expect(items[0]?.label).toBe('角色规范图');
-    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
-      '角色规范图',
-      '角色主图',
-    ]);
+    expect(items.map((item) => item.label)).toEqual(['角色规范图', '角色主图']);
     expect(items[0]?.prompt).toBe('规范提示词');
     expect(items[0]?.author).toBe('创作者A');
-    expect(items[0]?.cost).toBe('17泥点');
+    expect(items[0]?.cost).toBe('5泥点');
+    expect(items[1]?.cost).toBe('12泥点');
   });
 
-  it('groups assets when references point to the source project resource', () => {
+  it('keeps unset category visible in all tab and out of concrete category tabs', () => {
     const items = buildCreationShowcaseItems({
-      activeTab: 'packs',
+      activeTab: 'all',
       projectResources: [
         createResource({
           resourceId: 'spec-1',
-          label: '项目规范图',
+          label: '未设置分类素材',
           assetKind: 'spec',
-          sourceResourceId: 'resource-spec-1',
+          showcaseCategory: null,
         }),
         createResource({
-          resourceId: 'character-1',
-          label: '项目角色图',
+          resourceId: 'ui-1',
+          label: '人工 UI 素材',
           assetKind: 'character',
-          generationInputs: {
-            fields: [{ title: '角色设定', value: '项目角色提示词' }],
-            references: [
-              {
-                title: '角色规范',
-                label: '项目规范图',
-                refType: 'project-resource',
-                refId: 'resource-spec-1',
-              },
-            ],
-          },
+          showcaseCategory: 'ui',
         }),
       ],
     });
 
-    expect(items).toHaveLength(1);
-    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
-      '项目规范图',
-      '项目角色图',
+    expect(items.map((item) => item.label)).toEqual([
+      '未设置分类素材',
+      '人工 UI 素材',
     ]);
+    expect(
+      buildCreationShowcaseItems({
+        activeTab: 'ui',
+        projectResources: [
+          createResource({
+            resourceId: 'spec-1',
+            label: '未设置分类素材',
+            assetKind: 'spec',
+            showcaseCategory: null,
+          }),
+          createResource({
+            resourceId: 'ui-1',
+            label: '人工 UI 素材',
+            assetKind: 'character',
+            showcaseCategory: 'ui',
+          }),
+        ],
+      }).map((item) => item.label),
+    ).toEqual(['人工 UI 素材']);
   });
 
   it('groups character animations under the referenced character image', () => {
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
index 68dd913a3..fe17d6407 100644
--- a/src/components/creation-home/creationShowcaseModel.ts
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -17,12 +17,7 @@ import {
   DEFAULT_VIDEO_MODEL,
 } from '../image-editor/ImageCanvasGenerationModel';
 
-export type ShowcaseTabId =
-  | 'packs'
-  | 'characters'
-  | 'ui'
-  | 'music'
-  | 'marketing';
+export type ShowcaseTabId = 'all' | 'characters' | 'ui' | 'music' | 'marketing';
 
 export type ShowcaseAssetMediaType = 'image' | 'video' | 'audio';
 
@@ -71,15 +66,15 @@ const SHOWCASE_AUTHOR_KEYS = [
 ] as const;
 
 export const SHOWCASE_TABS: Array<{ id: ShowcaseTabId; label: string }> = [
-  { id: 'packs', label: '素材包' },
+  { id: 'all', label: '全部' },
   { id: 'characters', label: '角色' },
   { id: 'ui', label: 'UI' },
   { id: 'music', label: '音乐' },
   { id: 'marketing', label: '美宣' },
 ];
 
-const SHOWCASE_TAB_IDS = new Set<ShowcaseTabId>(
-  SHOWCASE_TABS.map((tab) => tab.id),
+const SHOWCASE_CATEGORY_IDS = new Set(
+  SHOWCASE_TABS.filter((tab) => tab.id !== 'all').map((tab) => tab.id),
 );
 
 function assetRecord(asset: EditorAssetSnapshot) {
@@ -218,7 +213,7 @@ function projectResourceToShowcaseAsset(
 }
 
 function normalizeShowcaseCategory(value: string): ShowcaseTabId | null {
-  return SHOWCASE_TAB_IDS.has(value as ShowcaseTabId)
+  return SHOWCASE_CATEGORY_IDS.has(value as Exclude<ShowcaseTabId, 'all'>)
     ? (value as ShowcaseTabId)
     : null;
 }
@@ -470,41 +465,6 @@ function sortGroupAssets(assets: EditorAssetSnapshot[]) {
   });
 }
 
-function groupPackAssets(assets: EditorAssetSnapshot[]) {
-  const groups = new Map<string, ShowcaseAssetGroup>();
-  assets.forEach((asset) => {
-    const specReference = findSpecReference(asset);
-    if (specReference) {
-      addAssetToGroup(
-        groups,
-        getReferenceKey(specReference),
-        asset,
-        specReference.label,
-      );
-      return;
-    }
-    if (isSpecAsset(asset)) {
-      addAssetToGroup(groups, getSelfAssetKey(asset), asset, asset.label);
-      return;
-    }
-    addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
-  });
-  const specAssets = assets.filter(isSpecAsset);
-  specAssets.forEach((asset) => {
-    const group = mergeAssetAliasGroups(groups, asset, asset.label);
-    if (
-      group &&
-      !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)
-    ) {
-      group.assets.unshift(asset);
-    }
-  });
-  return [...groups.values()].map((group) => ({
-    ...group,
-    assets: sortGroupAssets(group.assets),
-  }));
-}
-
 function groupCharacterAssets(assets: EditorAssetSnapshot[]) {
   const groups = new Map<string, ShowcaseAssetGroup>();
   assets
@@ -613,15 +573,15 @@ function groupSingleAssets(
 }
 
 function getGroupsForTab(assets: EditorAssetSnapshot[], tab: ShowcaseTabId) {
+  if (tab === 'all') {
+    return groupSingleAssets(assets, () => true);
+  }
   if (assets.some((asset) => resolveAssetShowcaseCategory(asset))) {
     return groupSingleAssets(
       assets,
       (asset) => resolveAssetShowcaseCategory(asset) === tab,
     );
   }
-  if (tab === 'packs') {
-    return groupPackAssets(assets);
-  }
   if (tab === 'characters') {
     return groupCharacterAssets(assets);
   }
@@ -829,7 +789,10 @@ function toLibraryShowcaseItem(
 function campaignToShowcaseItem(
   campaign?: EditorShowcaseCampaignSnapshot | null,
 ): ShowcaseAssetItem | null {
-  if (!campaign?.enabled || !campaign.imageSrc.trim()) {
+  const objectKey = campaign?.imageObjectKey?.trim().replace(/^\/+/u, '') ?? '';
+  const imageSrc =
+    campaign?.imageSrc.trim() || (objectKey ? `/${objectKey}` : '');
+  if (!campaign?.enabled || !imageSrc) {
     return null;
   }
   return {
@@ -839,7 +802,8 @@ function campaignToShowcaseItem(
       {
         id: 'campaign:global:image',
         label: campaign.title.trim() || '陶泥儿精选',
-        src: campaign.imageSrc,
+        src: imageSrc,
+        objectKey: objectKey || null,
         mediaType: 'image',
       },
     ],
diff --git a/src/index.css b/src/index.css
index f1022184c..1402c9eef 100644
--- a/src/index.css
+++ b/src/index.css
@@ -3801,20 +3801,20 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .creation-landing__asset-waterfall {
+  display: grid;
   width: 100%;
   min-width: 0;
-  column-count: 3;
-  column-gap: 0.92rem;
+  grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr));
+  gap: 0.92rem;
+  align-items: start;
 }
 
 .creation-landing__asset-card {
   position: relative;
-  display: inline-block;
+  display: block;
   width: 100%;
   min-width: 0;
   overflow: hidden;
-  margin: 0 0 0.92rem;
-  break-inside: avoid;
   border: 1px solid rgba(220, 189, 163, 0.78);
   border-radius: 1rem;
   background: rgba(255, 254, 251, 0.88);
@@ -3911,10 +3911,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 .creation-landing__asset-preview {
   position: relative;
   display: grid;
+  width: 100%;
   min-height: 9.5rem;
   max-height: 23rem;
   overflow: hidden;
-  place-items: center;
+  place-items: stretch;
   background: linear-gradient(180deg, #fffdfa, #fff4ea);
 }
 
@@ -3923,6 +3924,16 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   object-position: center;
 }
 
+.creation-landing__asset-preview-media {
+  display: block;
+  width: calc(100% + 2px);
+  max-width: none;
+  height: calc(100% + 2px);
+  max-height: none;
+  object-fit: cover;
+  object-position: center;
+}
+
 .creation-landing__asset-preview--bundle {
   grid-template-columns: repeat(2, minmax(0, 1fr));
   align-items: stretch;
@@ -4291,7 +4302,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   }
 
   .creation-landing__asset-waterfall {
-    column-count: 2;
+    grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
   }
 
   .creation-landing__showcase-modal-panel {
@@ -4351,7 +4362,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   }
 
   .creation-landing__asset-waterfall {
-    column-count: 1;
+    grid-template-columns: 1fr;
   }
 
   .creation-landing__showcase-modal-overlay {

From fcd353f12f32f063bb32638db4f450b69f8e0e8c Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 18:59:40 +0800
Subject: [PATCH 07/24] =?UTF-8?q?=E5=90=8C=E6=AD=A5=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E5=88=86=E7=B1=BB=E4=B8=8E=E6=B4=BB=E5=8A=A8=E5=8D=A1=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新精选审核公开口径，说明未设置分类进入全部。

更新创作主页文档，移除素材包分类并说明全部 Tab。

更新后端表目录，记录活动卡 imageObjectKey 和 OSS 上传方式。
---
 docs/project-memory/shared-memory/decision-log.md  |  2 +-
 ...架构】server-rs与SpacetimeDB数据契约-2026-05-15.md |  4 ++--
 ...�法创作】创作主页与项目入口改版计划-2026-06-18.md | 14 +++++++-------
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index f74984a1b..1ad4a8b7d 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -27,7 +27,7 @@
 ## 2026-07-04 陶泥儿精选改为素材提交审核后公开
 
 - 背景：`/creation` 的 `陶泥儿精选` 过去依赖 `editor_project_resource.public_showcase_enabled`，生成画布资源默认可公开，和“作品公开默认关闭、由用户主动投稿精选”的运营要求冲突，也无法在后台审核、返还泥点和配置固定活动卡。
-- 决策：`陶泥儿精选` 的公开事实改为独立 `editor_showcase_asset` 审核表。生成素材默认不公开；用户在账号级素材库对 `sourceType="generated"` 且有媒体内容的素材提交审核，后端快照素材信息并写入 `pending`。后台审核通过后写入 `approved`，但默认 `display_enabled=false` 且 `showcase_category=null`，运营需按前台 Tab 手动设置分类并开启展示；审核通过时按 `generation_cost_mud_points` 返还 50% 泥点；拒绝后写入 `rejected`。公开接口 `GET /api/editor/showcase/resources` 只返回已通过、展示开启且分类合法的快照，按通过时间和 `showcaseId` 倒序分页，并可携带后台配置的固定活动卡。旧 `editor_project_resource.public_showcase_enabled` 和旧 PATCH 接口只保留兼容，不再驱动精选公开。
+- 决策：`陶泥儿精选` 的公开事实改为独立 `editor_showcase_asset` 审核表。生成素材默认不公开；用户在账号级素材库对 `sourceType="generated"` 且有媒体内容的素材提交审核，后端快照素材信息并写入 `pending`。后台审核通过后写入 `approved`，但默认 `display_enabled=false` 且 `showcase_category=null`，运营可按前台具体 Tab 手动设置分类并开启展示；未设置分类的素材展示开启后进入前台“全部”，但不进入角色 / UI / 音乐 / 美宣具体分类。审核通过时按 `generation_cost_mud_points` 返还 50% 泥点；拒绝后写入 `rejected`。公开接口 `GET /api/editor/showcase/resources` 返回已通过、展示开启且媒体非空的快照，按通过时间和 `showcaseId` 倒序分页，并可携带后台配置的固定活动卡。旧 `editor_project_resource.public_showcase_enabled` 和旧 PATCH 接口只保留兼容，不再驱动精选公开。
 - 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`spacetime-client` 绑定与 mapper、`api-server` 编辑器和后台路由、admin-web 精选审核页、素材库右键菜单、`/creation` 精选瀑布流、图片画布文档和后端表目录。
 - 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check --manifest-path server-rs/Cargo.toml -p spacetime-module -p spacetime-client -p api-server`、前端 / 后台 typecheck 与精选相关组件测试，确认默认不公开、提交后 pending、审核通过后展示和返还、展示开关与点赞生效。
 - 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index a04d9d8ab..a508390a9 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -502,7 +502,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorShowcaseAsset`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：`陶泥儿精选` 的独立审核与公开快照表。用户从账号级生成素材提交后，后端把素材媒体、提示词、生成输入、素材类型和 `generation_cost_mud_points` 快照到该表，初始 `review_status = pending`、`display_enabled = false` 且 `showcase_category = null`。后台审核通过后写入 `approved`，但仍保持不展示；运营需在后台按前台 Tab 手动设置 `showcase_category`（`packs`、`characters`、`ui`、`music`、`marketing`）并开启展示后，素材才进入公开精选。审核通过时生成确定性返还流水 `editor-showcase-refund:{showcase_id}`，BFF 按 50% 生成成本返还泥点后回写 `refund_completed_at`；拒绝后写入 `rejected`。公开精选 `GET /api/editor/showcase/resources` 只读取 `review_status = approved`、`display_enabled = true`、`showcase_category` 合法且媒体非空的记录，按通过时间 / `showcase_id` 倒序 cursor 分页。素材删除时，待审核记录标记 `asset_deleted_while_pending`，已拒绝记录删除，已通过记录保留快照继续展示。
+- 说明：`陶泥儿精选` 的独立审核与公开快照表。用户从账号级生成素材提交后，后端把素材媒体、提示词、生成输入、素材类型和 `generation_cost_mud_points` 快照到该表，初始 `review_status = pending`、`display_enabled = false` 且 `showcase_category = null`。后台审核通过后写入 `approved`，但仍保持不展示；运营可在后台按前台具体 Tab 手动设置 `showcase_category`（`characters`、`ui`、`music`、`marketing`）并开启展示。未设置分类的素材不归入具体 Tab，但展示开启后仍进入前台“全部”。审核通过时生成确定性返还流水 `editor-showcase-refund:{showcase_id}`，BFF 按 50% 生成成本返还泥点后回写 `refund_completed_at`；拒绝后写入 `rejected`。公开精选 `GET /api/editor/showcase/resources` 读取 `review_status = approved`、`display_enabled = true` 且媒体非空的记录，按通过时间 / `showcase_id` 倒序 cursor 分页。素材删除时，待审核记录标记 `asset_deleted_while_pending`，已拒绝记录删除，已通过记录保留快照继续展示。
 - 索引：`by_editor_showcase_asset_owner_user_id`、`by_editor_showcase_asset_review_status`。
 
 ### `editor_showcase_asset_like`
@@ -516,7 +516,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorShowcaseCampaignConfig`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：`陶泥儿精选` 首位固定活动卡配置表，当前使用固定 `config_id = default`。后台可配置启用状态、标题、图片 URL、提示词、作者和成本文案；固定活动卡不包含副标题或 Object Key，公开精选接口只在启用时返回该配置。
+- 说明：`陶泥儿精选` 首位固定活动卡配置表，当前使用固定 `config_id = global`。后台可配置启用状态、标题、图片地址、图片 OSS `image_object_key`、提示词、作者和成本文案；上传按钮通过后台受控上传票据把图片写入 OSS，保存时同时落 `image_src` 和 `image_object_key`。公开精选接口只在启用时返回该配置，前端优先用 `image_object_key` 走签名读地址展示。
 - 索引：主键 `config_id`。
 
 ### `inventory_slot`
diff --git a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
index f93f7bfba..8a8701407 100644
--- a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
+++ b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
@@ -15,7 +15,7 @@
 - 顶级导航中“创作”进入 `/creation`，“草稿”改为“项目”并进入 `/project`。
 - 移动端隐藏“创作”和“项目”入口，只保留浏览和个人相关入口；移动端直达 `/creation` 时提示用户使用桌面端打开。
 - 登录后在创作主页展示最近项目，并通过新建项目进入 `/editor/canvas?projectid=xxx`。
-- `陶泥儿精选` 展示全站用户图片画布项目中允许公开展示的画布生成素材包和素材，不使用账号级非项目素材、公开作品补充或 mock 素材。
+- `陶泥儿精选` 展示全站用户图片画布项目中允许公开展示的画布生成素材，不使用账号级非项目素材、公开作品补充或 mock 素材。
 - 现有 `/creation/<play>` 玩法工作台、草稿、作品架、生成恢复和发布链路保持不变。
 
 ## 页面结构
@@ -73,13 +73,13 @@
 
 `陶泥儿精选` 是页面底部的全站公开画布生成素材瀑布流，不承载玩法入口列表。瀑布流卡片按真实素材宽高设置预览比例，同一行允许出现不同高度卡片，不使用固定等高网格。创作入口配置仍继续来自 `/api/creation-entry/config`，供旧创作入口和具体 `/creation/<play>` 工作台使用，但不作为本页精选区内容。
 
-精选内容只使用用户从账号级素材库主动提交、后台审核通过、手动设置精选分类且展示状态开启的 `editor_showcase_asset` 快照。新生成素材不会默认公开，审核通过后也不会自动展示；运营需在后台按前台 Tab 设置分类（素材包、角色、UI、音乐、美宣）并开启展示。旧 `editor_project_resource.public_showcase_enabled` 只保留历史兼容，不再作为 `/creation` 精选事实源。账号级 `editor_asset` 仍是素材库私有事实；只有 `sourceType="generated"`、有媒体内容、提交审核并通过的素材才可进入精选，上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。审核通过时按生成成本返还 50% 泥点，返还流水使用确定性 `editor-showcase-refund:{showcaseId}` 保证幂等。公开 BFF 必须返回作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。
+精选内容只使用用户从账号级素材库主动提交、后台审核通过且展示状态开启的 `editor_showcase_asset` 快照。新生成素材不会默认公开，审核通过后也不会自动展示；运营可在后台按前台具体 Tab 设置分类（角色、UI、音乐、美宣）并开启展示，未设置分类的素材不会隐藏，会进入前台“全部”。旧 `editor_project_resource.public_showcase_enabled` 只保留历史兼容，不再作为 `/creation` 精选事实源。账号级 `editor_asset` 仍是素材库私有事实；只有 `sourceType="generated"`、有媒体内容、提交审核并通过的素材才可进入精选，上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。审核通过时按生成成本返还 50% 泥点，返还流水使用确定性 `editor-showcase-refund:{showcaseId}` 保证幂等。公开 BFF 必须返回作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。
 
 瀑布流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有瀑布流，而不是固定只展示首屏数量。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选。
 
 Tab：
 
-- 素材包
+- 全部
 - 角色
 - UI
 - 音乐
@@ -90,7 +90,7 @@ Tab：
 
 展示口径：
 
-- 素材包：每个列表项展示同一规范图生成的规范图和相关素材组合。
+- 全部：展示所有已公开精选素材，包含未设置分类的素材。
 - 角色：每个列表项展示游戏角色图和该角色生成的角色动画素材组合。
 - UI：每个列表项展示游戏 UI 图和该 UI 图拆出的子素材组合。
 - 音乐：展示背景音乐和音效。
@@ -112,8 +112,8 @@ Tab：
 
 数据来源：
 
-- 读取公开 BFF `GET /api/editor/showcase/resources` 返回的全站公开 `editor_showcase_asset` 快照，快照包含 `showcaseId`、`assetId`、审核状态、展示状态、`showcaseCategory`、点赞数、生成成本、返还泥点、`authorDisplayName` / `display_name` 和 `authorPublicUserCode` / 陶泥号用于展示；前端按 `showcaseCategory` 放入素材包、角色、UI、音乐或美宣 Tab，只展示后端已经筛过的公开结果。作者展示优先展示名，没有展示名时展示陶泥号，绝不能展示内部 `ownerUserId` / `user_id`。
-- 素材包、角色、UI、音乐、音效、视频和美宣都必须来自用户素材库中已提交并通过审核的生成素材；不要求素材当前仍保留在某个项目资源中，已通过审核的快照在原素材删除后仍可保留公开展示。
+- 读取公开 BFF `GET /api/editor/showcase/resources` 返回的全站公开 `editor_showcase_asset` 快照，快照包含 `showcaseId`、`assetId`、审核状态、展示状态、`showcaseCategory`、点赞数、生成成本、返还泥点、`authorDisplayName` / `display_name` 和 `authorPublicUserCode` / 陶泥号用于展示；前端默认进入“全部”，展示所有后端已经筛过的公开结果；角色、UI、音乐或美宣 Tab 只展示对应 `showcaseCategory` 的素材。作者展示优先展示名，没有展示名时展示陶泥号，绝不能展示内部 `ownerUserId` / `user_id`。
+- 全部、角色、UI、音乐、音效、视频和美宣都必须来自用户素材库中已提交并通过审核的生成素材；不要求素材当前仍保留在某个项目资源中，已通过审核的快照在原素材删除后仍可保留公开展示。
 - 未登录用户也可读取公开精选；当没有公开画布生成资源时，不再用公开作品图片补充，只显示简洁空态。
 - 上传素材、公开作品图片、mock 资源和假组合都不进入精选。
 - 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。生成素材菜单内提供 `提交精选审核`，调用 `POST /api/editor/assets/{assetId}/showcase-submissions` 后进入 `pending` 状态；已提交、已通过或已拒绝的素材显示对应状态，不再显示默认打开的公开勾选项。
@@ -128,7 +128,7 @@ Tab：
 - 最近项目继续使用编辑器项目接口：`listEditorProjects`、`createEditorProject` 和 `/editor/canvas?projectid=xxx`。
 - 最近项目和项目页打开画布时，浏览器 history 只保留带 `projectid` 的最终画布路由；新建画布引导使用 `guide=toolbar` 一次性 query，主站九宫格直达生成器使用 `tool=<intent>` 一次性 query，画布消费后通过 `history.replaceState` 清理这两个参数。
 - 项目封面逻辑复用 `/project` 项目卡已有的画布中心缩略图算法。
-- `陶泥儿精选` 读取后端公开精选接口返回的审核通过素材快照；公开事实以后端 `editor_showcase_asset.review_status`、`display_enabled` 和 `showcase_category` 为准，前端只做展示组合、Tab 归类、点赞交互和提交审核的乐观状态回滚。
+- `陶泥儿精选` 读取后端公开精选接口返回的审核通过素材快照；公开事实以后端 `editor_showcase_asset.review_status` 和 `display_enabled` 为准，`showcase_category` 只用于前端具体 Tab 归类，前端只做展示组合、Tab 归类、点赞交互和提交审核的乐观状态回滚。
 - `/creation/<play>` 的玩法工作台、草稿、生成页、结果页、发布、运行态和作品架链路保持原状。
 
 ## 路由与导航

From ab61390121039b1693cf6fb8aeb2264be1f0f55c Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 19:15:03 +0800
Subject: [PATCH 08/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=94=BB=E5=B8=83=20Ag?=
 =?UTF-8?q?ent=20=E9=BB=98=E8=AE=A4=E8=A2=AB=E4=BB=BB=E5=8A=A1=E5=88=97?=
 =?UTF-8?q?=E8=A1=A8=E9=9A=90=E8=97=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

打开画布时 Agent 开关启用则保持 Agent 默认展开。

恢复任务自动打开任务列表时不再抢占 Agent 默认态。

用户手动打开任务列表时仍按右侧面板互斥关闭 Agent。

补充恢复任务场景下 Agent 默认显示的回归测试。
---
 .../ImageCanvasEditorView.test.tsx            | 34 +++++++++++++++++++
 .../image-editor/ImageCanvasEditorView.tsx    | 10 ++++--
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/components/image-editor/ImageCanvasEditorView.test.tsx b/src/components/image-editor/ImageCanvasEditorView.test.tsx
index 49f1b47a7..67b9f73a7 100644
--- a/src/components/image-editor/ImageCanvasEditorView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.test.tsx
@@ -1449,6 +1449,40 @@ describe('ImageCanvasEditorView', () => {
     expect(screen.queryByLabelText('发送给画布 Agent')).toBeNull();
   });
 
+  it('keeps the Agent conversation panel open when restored tasks auto-open the task list', async () => {
+    enableEditorAgentSidebarForTest();
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-with-restored-task',
+      title: '恢复任务项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        ...defaultEditorProjectLayers,
+        {
+          layerId: 'generation-dialog:restored-task',
+          resourceId: 'generation-dialog:restored-task',
+          itemType: 'generation-dialog',
+          dialog: {
+            id: 'restored-task',
+            mode: 'generate',
+            prompt: '继续生成',
+            status: 'idle',
+          },
+        },
+      ],
+      resources: defaultEditorProjectResources,
+      updatedAt: '2026-07-06T00:00:00.000Z',
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    expect(await screen.findByLabelText('发送给画布 Agent')).toBeTruthy();
+    await waitFor(() => {
+      expect(
+        screen.queryByRole('complementary', { name: '画布任务列表' }),
+      ).toBeNull();
+    });
+  });
+
   it('keeps the left resource sidebar independent from right-side task and Agent panels', async () => {
     enableEditorAgentSidebarForTest();
     render(<ImageCanvasEditorView />);
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index 687740c30..504334bf5 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -1199,13 +1199,19 @@ export function ImageCanvasEditorView({
     [toggleSidebarPanel],
   );
   useEffect(() => {
+    if (!isAgentConversationEnabled && isAgentConversationOpen) {
+      setIsAgentConversationOpen(false);
+      return;
+    }
     if (
-      (!isAgentConversationEnabled || generationSurface.isTaskSidebarOpen) &&
+      isAgentConversationEnabled &&
+      generationSurface.isTaskSidebarOpen &&
       isAgentConversationOpen
     ) {
-      setIsAgentConversationOpen(false);
+      generationSurface.toggleTaskSidebar();
     }
   }, [
+    generationSurface,
     generationSurface.isTaskSidebarOpen,
     isAgentConversationEnabled,
     isAgentConversationOpen,

From 29db6365e16d8a9cd27566657f5e0772ed4c0229 Mon Sep 17 00:00:00 2001
From: kvtodev <kvtodev@outlook.com>
Date: Mon, 6 Jul 2026 18:29:10 +0800
Subject: [PATCH 09/24] =?UTF-8?q?=E9=9A=90=E8=97=8F=E7=94=BB=E6=9D=BF?=
 =?UTF-8?q?=E7=B4=A0=E6=9D=90=E4=BF=A1=E6=81=AF=E4=B8=ADObject=20ID?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/image-editor/ImageCanvasMetadataModalView.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/components/image-editor/ImageCanvasMetadataModalView.tsx b/src/components/image-editor/ImageCanvasMetadataModalView.tsx
index 13e1552b5..4ae10f503 100644
--- a/src/components/image-editor/ImageCanvasMetadataModalView.tsx
+++ b/src/components/image-editor/ImageCanvasMetadataModalView.tsx
@@ -111,8 +111,6 @@ export function ImageCanvasMetadataModalView({
           )}
           <dt>Task</dt>
           <dd>{formatTaskIdForDisplay(layer.taskId)}</dd>
-          <dt>Object</dt>
-          <dd>{layer.objectKey ?? layer.assetObjectId ?? '-'}</dd>
         </dl>
       ) : null}
     </UnifiedModal>

From be7f0375e566f231af69ff534b21e2723d20359f Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 21:00:21 +0800
Subject: [PATCH 10/24] =?UTF-8?q?=E8=AE=B0=E5=BD=95=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E6=B4=BB=E5=8A=A8=E5=8D=A1=E5=9B=BE=E7=89=87=E5=AE=BD=E9=AB=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

后台上传活动卡图片时读取并保存原始宽高

隐藏活动卡 Object Key 输入，重复上传替换图片引用

公开精选按活动图宽高设置卡片比例

同步 SpacetimeDB schema、bindings 和后端数据契约文档
---
 apps/admin-web/src/api/adminApiClient.ts      | 72 +++++++++++++++++++
 apps/admin-web/src/api/adminApiTypes.ts       |  6 ++
 .../AdminEditorShowcaseReviewPage.test.tsx    | 55 ++++++++++++--
 .../pages/AdminEditorShowcaseReviewPage.tsx   | 27 +++----
 ...�】server-rs与SpacetimeDB数据契约-2026-05-15.md |  2 +-
 server-rs/crates/api-server/src/admin.rs      | 54 +++++++-------
 .../crates/api-server/src/editor_project.rs   |  4 ++
 .../crates/shared-contracts/src/admin.rs      |  4 ++
 .../src/mapper/editor_project.rs              |  8 +++
 ..._showcase_campaign_config_snapshot_type.rs |  2 +
 .../editor_showcase_campaign_config_type.rs   |  6 ++
 ...wcase_campaign_config_upsert_input_type.rs |  2 +
 .../src/editor_project_storage.rs             | 17 ++++-
 .../crates/spacetime-module/src/migration.rs  |  6 ++
 .../creationShowcaseModel.test.ts             |  6 ++
 .../creation-home/creationShowcaseModel.ts    |  2 +
 .../image-editor/editorProjectClient.test.ts  |  4 ++
 .../image-editor/editorProjectClient.ts       |  2 +
 18 files changed, 226 insertions(+), 53 deletions(-)

diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts
index 10e0215ce..3ecc25e7c 100644
--- a/apps/admin-web/src/api/adminApiClient.ts
+++ b/apps/admin-web/src/api/adminApiClient.ts
@@ -403,6 +403,7 @@ export async function uploadAdminEditorShowcaseCampaignImage(
   file: File,
 ): Promise<AdminUploadedEditorShowcaseCampaignImage> {
   const contentType = resolveAdminImageContentType(file);
+  const dimensions = await readAdminImageFileDimensions(file);
   const response = await request<AdminCreateEditorShowcaseCampaignImageUploadTicketResponse>(
     '/admin/api/editor-showcase/campaign/image-upload-ticket',
     {
@@ -420,6 +421,8 @@ export async function uploadAdminEditorShowcaseCampaignImage(
   return {
     imageSrc: objectKey ? `/${objectKey}` : response.upload.legacyPublicPath,
     imageObjectKey: objectKey,
+    imageWidth: dimensions.imageWidth,
+    imageHeight: dimensions.imageHeight,
     legacyPublicPath: response.upload.legacyPublicPath,
   };
 }
@@ -607,6 +610,75 @@ function resolveAdminImageContentType(file: File) {
   return declaredType || 'application/octet-stream';
 }
 
+function normalizeAdminImageDimensions(width: number, height: number) {
+  const imageWidth = Math.round(width);
+  const imageHeight = Math.round(height);
+  if (
+    !Number.isFinite(imageWidth) ||
+    !Number.isFinite(imageHeight) ||
+    imageWidth <= 0 ||
+    imageHeight <= 0
+  ) {
+    return null;
+  }
+  return { imageWidth, imageHeight };
+}
+
+async function readAdminImageFileDimensions(file: File) {
+  if (typeof createImageBitmap === 'function') {
+    try {
+      const bitmap = await createImageBitmap(file);
+      const dimensions = normalizeAdminImageDimensions(
+        bitmap.width,
+        bitmap.height,
+      );
+      bitmap.close();
+      if (dimensions) {
+        return dimensions;
+      }
+    } catch {
+      // Fall back to HTMLImageElement decoding below.
+    }
+  }
+
+  if (
+    typeof Image === 'undefined' ||
+    typeof URL === 'undefined' ||
+    typeof URL.createObjectURL !== 'function'
+  ) {
+    throw new Error('读取活动卡图片尺寸失败，请重新选择图片');
+  }
+
+  return new Promise<{ imageWidth: number; imageHeight: number }>(
+    (resolve, reject) => {
+      const objectUrl = URL.createObjectURL(file);
+      const image = new Image();
+      const cleanup = () => {
+        if (typeof URL.revokeObjectURL === 'function') {
+          URL.revokeObjectURL(objectUrl);
+        }
+      };
+      image.onload = () => {
+        cleanup();
+        const dimensions = normalizeAdminImageDimensions(
+          image.naturalWidth || image.width,
+          image.naturalHeight || image.height,
+        );
+        if (dimensions) {
+          resolve(dimensions);
+          return;
+        }
+        reject(new Error('读取活动卡图片尺寸失败，请重新选择图片'));
+      };
+      image.onerror = () => {
+        cleanup();
+        reject(new Error('读取活动卡图片尺寸失败，请重新选择图片'));
+      };
+      image.src = objectUrl;
+    },
+  );
+}
+
 function buildAdminDirectUploadFormData(
   upload: AdminDirectUploadTicketPayload,
   file: File,
diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts
index 8119889cb..48f1a7656 100644
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -458,6 +458,8 @@ export interface AdminEditorShowcaseCampaignPayload {
   title: string;
   imageSrc: string;
   imageObjectKey?: string | null;
+  imageWidth?: number | null;
+  imageHeight?: number | null;
   prompt: string;
   author: string;
   costText: string;
@@ -473,6 +475,8 @@ export interface AdminUpsertEditorShowcaseCampaignRequest {
   title: string;
   imageSrc: string;
   imageObjectKey?: string | null;
+  imageWidth?: number | null;
+  imageHeight?: number | null;
   prompt: string;
   author: string;
   costText: string;
@@ -500,6 +504,8 @@ export interface AdminCreateEditorShowcaseCampaignImageUploadTicketResponse {
 export interface AdminUploadedEditorShowcaseCampaignImage {
   imageSrc: string;
   imageObjectKey: string;
+  imageWidth: number;
+  imageHeight: number;
   legacyPublicPath: string;
 }
 
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
index 4c384daee..766c8b05f 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.test.tsx
@@ -91,6 +91,8 @@ beforeEach(() => {
       title: '活动卡',
       imageSrc: '/campaign.png',
       imageObjectKey: null,
+      imageWidth: null,
+      imageHeight: null,
       prompt: '活动提示词',
       author: '官方',
       costText: '12 泥点',
@@ -125,6 +127,8 @@ beforeEach(() => {
       title: '新活动卡',
       imageSrc: '/new-campaign.png',
       imageObjectKey: null,
+      imageWidth: null,
+      imageHeight: null,
       prompt: '新活动提示词',
       author: '官方',
       costText: '6 泥点',
@@ -135,6 +139,8 @@ beforeEach(() => {
     imageSrc: '/generated-character-drafts/editor/showcase-campaign/card.png',
     imageObjectKey:
       'generated-character-drafts/editor/showcase-campaign/card.png',
+    imageWidth: 900,
+    imageHeight: 1200,
     legacyPublicPath:
       '/generated-character-drafts/editor/showcase-campaign/card.png',
   });
@@ -291,7 +297,7 @@ test('后台精选审核可以切换展示和保存活动卡', async () => {
   });
 });
 
-test('后台精选活动卡可以上传图片并保存 objectKey', async () => {
+test('后台精选活动卡上传图片时替换图片引用并隐藏 objectKey', async () => {
   render(
     <AdminEditorShowcaseReviewPage
       token="admin-token"
@@ -311,8 +317,45 @@ test('后台精选活动卡可以上传图片并保存 objectKey', async () => {
       file,
     );
   });
-  expect(await screen.findByDisplayValue('/generated-character-drafts/editor/showcase-campaign/card.png')).toBeTruthy();
-  expect(screen.getByDisplayValue('generated-character-drafts/editor/showcase-campaign/card.png')).toBeTruthy();
+  expect(
+    await screen.findByDisplayValue(
+      '/generated-character-drafts/editor/showcase-campaign/card.png',
+    ),
+  ).toBeTruthy();
+  expect(
+    screen.queryByDisplayValue(
+      'generated-character-drafts/editor/showcase-campaign/card.png',
+    ),
+  ).toBeNull();
+
+  vi.mocked(uploadAdminEditorShowcaseCampaignImage).mockResolvedValueOnce({
+    imageSrc:
+      '/generated-character-drafts/editor/showcase-campaign/replacement.png',
+    imageObjectKey:
+      'generated-character-drafts/editor/showcase-campaign/replacement.png',
+    imageWidth: 1024,
+    imageHeight: 1536,
+    legacyPublicPath:
+      '/generated-character-drafts/editor/showcase-campaign/replacement.png',
+  });
+  const replacementFile = new File(['replacement-bytes'], 'replacement.png', {
+    type: 'image/png',
+  });
+  fireEvent.change(screen.getByLabelText('上传活动卡图片'), {
+    target: { files: [replacementFile] },
+  });
+
+  await waitFor(() => {
+    expect(uploadAdminEditorShowcaseCampaignImage).toHaveBeenCalledWith(
+      'admin-token',
+      replacementFile,
+    );
+  });
+  expect(
+    await screen.findByDisplayValue(
+      '/generated-character-drafts/editor/showcase-campaign/replacement.png',
+    ),
+  ).toBeTruthy();
 
   fireEvent.click(screen.getByRole('button', { name: '保存活动卡' }));
 
@@ -321,9 +364,11 @@ test('后台精选活动卡可以上传图片并保存 objectKey', async () => {
       'admin-token',
       expect.objectContaining({
         imageSrc:
-          '/generated-character-drafts/editor/showcase-campaign/card.png',
+          '/generated-character-drafts/editor/showcase-campaign/replacement.png',
         imageObjectKey:
-          'generated-character-drafts/editor/showcase-campaign/card.png',
+          'generated-character-drafts/editor/showcase-campaign/replacement.png',
+        imageWidth: 1024,
+        imageHeight: 1536,
       }),
     );
   });
diff --git a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
index ebf45a2e5..a6fb7d12d 100644
--- a/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
+++ b/apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx
@@ -70,6 +70,8 @@ export function AdminEditorShowcaseReviewPage({
       author: '',
       costText: '',
       imageObjectKey: null,
+      imageWidth: null,
+      imageHeight: null,
     });
   const [isSavingCampaign, setIsSavingCampaign] = useState(false);
   const [isUploadingCampaignImage, setIsUploadingCampaignImage] =
@@ -202,6 +204,8 @@ export function AdminEditorShowcaseReviewPage({
         title: campaignDraft.title,
         imageSrc: campaignDraft.imageSrc,
         imageObjectKey: campaignDraft.imageObjectKey ?? null,
+        imageWidth: campaignDraft.imageWidth ?? null,
+        imageHeight: campaignDraft.imageHeight ?? null,
         prompt: campaignDraft.prompt,
         author: campaignDraft.author,
         costText: campaignDraft.costText,
@@ -228,6 +232,8 @@ export function AdminEditorShowcaseReviewPage({
         ...current,
         imageSrc: upload.imageSrc,
         imageObjectKey: upload.imageObjectKey,
+        imageWidth: upload.imageWidth,
+        imageHeight: upload.imageHeight,
       }));
     } catch (error: unknown) {
       handlePageError(error, onUnauthorized, setErrorMessage);
@@ -514,6 +520,8 @@ export function AdminEditorShowcaseReviewPage({
                     ...current,
                     imageSrc: event.target.value,
                     imageObjectKey: null,
+                    imageWidth: null,
+                    imageHeight: null,
                   }))
                 }
               />
@@ -538,25 +546,6 @@ export function AdminEditorShowcaseReviewPage({
               </button>
             </div>
           </label>
-          <label className="admin-field">
-            <span>Object Key</span>
-            <input
-              value={campaignDraft.imageObjectKey ?? ''}
-              onChange={(event) =>
-                setCampaignDraft((current) => {
-                  const imageObjectKey =
-                    event.target.value.trim().replace(/^\/+/u, '') || null;
-                  return {
-                    ...current,
-                    imageObjectKey,
-                    imageSrc: imageObjectKey
-                      ? `/${imageObjectKey}`
-                      : current.imageSrc,
-                  };
-                })
-              }
-            />
-          </label>
           <label className="admin-field">
             <span>作者</span>
             <input
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index a508390a9..f70da612d 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -516,7 +516,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorShowcaseCampaignConfig`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：`陶泥儿精选` 首位固定活动卡配置表，当前使用固定 `config_id = global`。后台可配置启用状态、标题、图片地址、图片 OSS `image_object_key`、提示词、作者和成本文案；上传按钮通过后台受控上传票据把图片写入 OSS，保存时同时落 `image_src` 和 `image_object_key`。公开精选接口只在启用时返回该配置，前端优先用 `image_object_key` 走签名读地址展示。
+- 说明：`陶泥儿精选` 首位固定活动卡配置表，当前使用固定 `config_id = global`。后台可配置启用状态、标题、图片地址、提示词、作者和成本文案；上传按钮通过后台受控上传票据把图片写入 OSS，保存时同时落 `image_src`、内部图片 OSS `image_object_key`、`image_width` 和 `image_height`。公开精选接口只在启用时返回该配置，前端优先用 `image_object_key` 走签名读地址展示，并按记录的图片宽高决定活动卡比例。
 - 索引：主键 `config_id`。
 
 ### `inventory_slot`
diff --git a/server-rs/crates/api-server/src/admin.rs b/server-rs/crates/api-server/src/admin.rs
index de103847d..e450454ff 100644
--- a/server-rs/crates/api-server/src/admin.rs
+++ b/server-rs/crates/api-server/src/admin.rs
@@ -19,17 +19,16 @@ use serde::Deserialize;
 use serde_json::{Map, Value};
 use shared_contracts::admin::{
     AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
-    AdminCreateEditorShowcaseCampaignImageUploadTicketResponse,
-    AdminDirectUploadTicketPayload,
-    AdminCreationEntryConfigResponse, AdminCreationEntryTypeConfigPayload,
-    AdminDashboardBreakdownRowPayload, AdminDashboardChartBucketPayload,
-    AdminDashboardChartPayload, AdminDashboardMetricsPayload, AdminDashboardOperationMetricPayload,
-    AdminDashboardOperationsPayload, AdminDashboardQuery, AdminDashboardRangePayload,
-    AdminDashboardResponse, AdminDatabaseOverviewPayload, AdminDatabaseTableListResponse,
-    AdminDatabaseTableRowPayload, AdminDatabaseTableRowsQuery, AdminDatabaseTableRowsResponse,
-    AdminDatabaseTableStatPayload, AdminDebugHeaderInput, AdminDebugHttpRequest,
-    AdminDebugHttpResponse, AdminEditorAssetListQuery, AdminEditorAssetListResponse,
-    AdminEditorAssetPayload, AdminEditorShowcaseAssetPayload, AdminEditorShowcaseAssetResponse,
+    AdminCreateEditorShowcaseCampaignImageUploadTicketResponse, AdminCreationEntryConfigResponse,
+    AdminCreationEntryTypeConfigPayload, AdminDashboardBreakdownRowPayload,
+    AdminDashboardChartBucketPayload, AdminDashboardChartPayload, AdminDashboardMetricsPayload,
+    AdminDashboardOperationMetricPayload, AdminDashboardOperationsPayload, AdminDashboardQuery,
+    AdminDashboardRangePayload, AdminDashboardResponse, AdminDatabaseOverviewPayload,
+    AdminDatabaseTableListResponse, AdminDatabaseTableRowPayload, AdminDatabaseTableRowsQuery,
+    AdminDatabaseTableRowsResponse, AdminDatabaseTableStatPayload, AdminDebugHeaderInput,
+    AdminDebugHttpRequest, AdminDebugHttpResponse, AdminDirectUploadTicketPayload,
+    AdminEditorAssetListQuery, AdminEditorAssetListResponse, AdminEditorAssetPayload,
+    AdminEditorShowcaseAssetPayload, AdminEditorShowcaseAssetResponse,
     AdminEditorShowcaseCampaignPayload, AdminEditorShowcaseCampaignResponse,
     AdminEditorShowcaseDisplayRequest, AdminEditorShowcaseListQuery,
     AdminEditorShowcaseListResponse, AdminEditorShowcaseReviewRequest, AdminLoginRequest,
@@ -41,9 +40,7 @@ use shared_contracts::admin::{
     AdminUpsertEditorShowcaseCampaignRequest, AdminUpsertPublicWorkInteractionConfigRequest,
     AdminWorkVisibilityListResponse,
 };
-use shared_contracts::assets::{
-    CreateDirectUploadTicketRequest, DirectUploadObjectAccess,
-};
+use shared_contracts::assets::{CreateDirectUploadTicketRequest, DirectUploadObjectAccess};
 use shared_contracts::creation_entry_config::{
     encode_unified_creation_spec_response, validate_unified_creation_spec_for_play,
 };
@@ -587,6 +584,8 @@ pub async fn admin_upsert_editor_showcase_campaign(
             title: payload.title,
             image_src: payload.image_src,
             image_object_key: payload.image_object_key,
+            image_width: payload.image_width,
+            image_height: payload.image_height,
             prompt: payload.prompt,
             author: payload.author,
             cost_text: payload.cost_text,
@@ -620,14 +619,11 @@ pub async fn admin_create_editor_showcase_campaign_image_upload_ticket(
         );
     }
     if payload.content_length == 0 {
-        return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST).with_message("图片文件不能为空")
-        );
+        return Err(AppError::from_status(StatusCode::BAD_REQUEST).with_message("图片文件不能为空"));
     }
     if payload.content_length > ADMIN_EDITOR_SHOWCASE_CAMPAIGN_IMAGE_MAX_BYTES {
         return Err(
-            AppError::from_status(StatusCode::BAD_REQUEST)
-                .with_message("活动卡图片不能超过 20MB")
+            AppError::from_status(StatusCode::BAD_REQUEST).with_message("活动卡图片不能超过 20MB")
         );
     }
 
@@ -650,7 +646,10 @@ pub async fn admin_create_editor_showcase_campaign_image_upload_ticket(
                     "asset_kind".to_string(),
                     "editor_showcase_campaign_image".to_string(),
                 ),
-                ("source".to_string(), "admin_editor_showcase_campaign".to_string()),
+                (
+                    "source".to_string(),
+                    "admin_editor_showcase_campaign".to_string(),
+                ),
             ]),
             max_size_bytes: Some(payload.content_length),
             expire_seconds: None,
@@ -662,9 +661,11 @@ pub async fn admin_create_editor_showcase_campaign_image_upload_ticket(
     let payload_value = value.get("data").cloned().unwrap_or(value);
     let response: shared_contracts::assets::CreateDirectUploadTicketResponse =
         serde_json::from_value(payload_value).map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(serde_json::json!({
-                "message": format!("活动卡上传凭证响应解析失败：{error}"),
-            }))
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(
+                serde_json::json!({
+                    "message": format!("活动卡上传凭证响应解析失败：{error}"),
+                }),
+            )
         })?;
     Ok(json_success_body(
         Some(&request_context),
@@ -799,6 +800,8 @@ fn admin_editor_showcase_campaign_payload_from_record(
         title: record.title,
         image_src: record.image_src,
         image_object_key: record.image_object_key,
+        image_width: record.image_width,
+        image_height: record.image_height,
         prompt: record.prompt,
         author: record.author,
         cost_text: record.cost_text,
@@ -821,10 +824,7 @@ fn admin_direct_upload_ticket_payload_from_asset_upload(
             upload.form_fields.credential,
         ),
         ("x-oss-date".to_string(), upload.form_fields.date),
-        (
-            "x-oss-signature".to_string(),
-            upload.form_fields.signature,
-        ),
+        ("x-oss-signature".to_string(), upload.form_fields.signature),
         (
             "success_action_status".to_string(),
             upload.form_fields.success_action_status,
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index c675aff21..1334333e5 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -618,6 +618,8 @@ pub struct EditorShowcaseCampaignPayload {
     title: String,
     image_src: String,
     image_object_key: Option<String>,
+    image_width: Option<u32>,
+    image_height: Option<u32>,
     prompt: String,
     author: String,
     cost_text: String,
@@ -3352,6 +3354,8 @@ fn editor_showcase_campaign_payload_from_record(
         title: record.title,
         image_src: record.image_src,
         image_object_key: record.image_object_key,
+        image_width: record.image_width,
+        image_height: record.image_height,
         prompt: record.prompt,
         author: record.author,
         cost_text: record.cost_text,
diff --git a/server-rs/crates/shared-contracts/src/admin.rs b/server-rs/crates/shared-contracts/src/admin.rs
index 3f157b185..8af57df34 100644
--- a/server-rs/crates/shared-contracts/src/admin.rs
+++ b/server-rs/crates/shared-contracts/src/admin.rs
@@ -257,6 +257,8 @@ pub struct AdminEditorShowcaseCampaignPayload {
     pub title: String,
     pub image_src: String,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
@@ -276,6 +278,8 @@ pub struct AdminUpsertEditorShowcaseCampaignRequest {
     pub title: String,
     pub image_src: String,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
diff --git a/server-rs/crates/spacetime-client/src/mapper/editor_project.rs b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
index 5dce27889..75a3b29a7 100644
--- a/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
+++ b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
@@ -181,6 +181,8 @@ pub struct EditorShowcaseCampaignConfigRecord {
     pub title: String,
     pub image_src: String,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
     pub prompt: String,
     pub author: String,
     pub cost_text: String,
@@ -428,6 +430,8 @@ pub struct EditorShowcaseCampaignConfigUpsertRecordInput {
     pub cost_text: String,
     pub updated_at_micros: i64,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 impl From<EditorProjectCreateRecordInput> for crate::module_bindings::EditorProjectCreateInput {
@@ -786,6 +790,8 @@ impl From<EditorShowcaseCampaignConfigUpsertRecordInput>
             cost_text: input.cost_text,
             updated_at_micros: input.updated_at_micros,
             image_object_key: input.image_object_key,
+            image_width: input.image_width,
+            image_height: input.image_height,
         }
     }
 }
@@ -1218,6 +1224,8 @@ fn map_editor_showcase_campaign_config_snapshot(
         title: snapshot.title,
         image_src: snapshot.image_src,
         image_object_key: snapshot.image_object_key,
+        image_width: snapshot.image_width,
+        image_height: snapshot.image_height,
         prompt: snapshot.prompt,
         author: snapshot.author,
         cost_text: snapshot.cost_text,
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
index 2850679db..a9a02b9f1 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_snapshot_type.rs
@@ -16,6 +16,8 @@ pub struct EditorShowcaseCampaignConfigSnapshot {
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at_micros: i64,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfigSnapshot {
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
index dbf215e0d..3772ab1fa 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_type.rs
@@ -17,6 +17,8 @@ pub struct EditorShowcaseCampaignConfig {
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at: __sdk::Timestamp,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfig {
@@ -38,6 +40,8 @@ pub struct EditorShowcaseCampaignConfigCols {
         __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<String>>,
     pub updated_at: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, __sdk::Timestamp>,
     pub image_object_key: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<String>>,
+    pub image_width: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<u32>>,
+    pub image_height: __sdk::__query_builder::Col<EditorShowcaseCampaignConfig, Option<u32>>,
 }
 
 impl __sdk::__query_builder::HasCols for EditorShowcaseCampaignConfig {
@@ -57,6 +61,8 @@ impl __sdk::__query_builder::HasCols for EditorShowcaseCampaignConfig {
             ),
             updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
             image_object_key: __sdk::__query_builder::Col::new(table_name, "image_object_key"),
+            image_width: __sdk::__query_builder::Col::new(table_name, "image_width"),
+            image_height: __sdk::__query_builder::Col::new(table_name, "image_height"),
         }
     }
 }
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
index b093fc4e0..0c6f647e9 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_showcase_campaign_config_upsert_input_type.rs
@@ -16,6 +16,8 @@ pub struct EditorShowcaseCampaignConfigUpsertInput {
     pub cost_text: String,
     pub updated_at_micros: i64,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 impl __sdk::InModule for EditorShowcaseCampaignConfigUpsertInput {
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 a330706c0..1a399cf1d 100644
--- a/server-rs/crates/spacetime-module/src/editor_project_storage.rs
+++ b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
@@ -207,6 +207,10 @@ pub struct EditorShowcaseCampaignConfig {
     updated_at: Timestamp,
     #[default(None::<String>)]
     image_object_key: Option<String>,
+    #[default(None::<u32>)]
+    image_width: Option<u32>,
+    #[default(None::<u32>)]
+    image_height: Option<u32>,
 }
 
 #[derive(Clone, Debug, PartialEq, SpacetimeType)]
@@ -466,6 +470,8 @@ pub struct EditorShowcaseCampaignConfigSnapshot {
     pub updated_by_admin_user_id: Option<String>,
     pub updated_at_micros: i64,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
@@ -621,6 +627,8 @@ pub struct EditorShowcaseCampaignConfigUpsertInput {
     pub cost_text: String,
     pub updated_at_micros: i64,
     pub image_object_key: Option<String>,
+    pub image_width: Option<u32>,
+    pub image_height: Option<u32>,
 }
 
 #[derive(Clone, Debug, PartialEq, SpacetimeType)]
@@ -2202,7 +2210,10 @@ fn upsert_editor_showcase_campaign_config(
     let title = input.title.trim().to_string();
     let image_object_key = normalize_optional(input.image_object_key)
         .map(|value| value.trim_start_matches('/').to_string());
-    let image_src = normalize_campaign_image_src(input.image_src.as_str(), image_object_key.as_deref());
+    let image_src =
+        normalize_campaign_image_src(input.image_src.as_str(), image_object_key.as_deref());
+    let image_width = input.image_width.filter(|value| *value > 0);
+    let image_height = input.image_height.filter(|value| *value > 0);
     if input.enabled {
         if title.is_empty() {
             return Err("editor_showcase_campaign_config.title 不能为空".to_string());
@@ -2238,6 +2249,8 @@ fn upsert_editor_showcase_campaign_config(
             updated_by_admin_user_id: Some(admin_user_id),
             updated_at: now,
             image_object_key,
+            image_width,
+            image_height,
         });
     ctx.db
         .editor_showcase_campaign_config()
@@ -2713,6 +2726,8 @@ fn showcase_campaign_config_snapshot_from_row(
         updated_by_admin_user_id: row.updated_by_admin_user_id,
         updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
         image_object_key: row.image_object_key,
+        image_width: row.image_width,
+        image_height: row.image_height,
     }
 }
 
diff --git a/server-rs/crates/spacetime-module/src/migration.rs b/server-rs/crates/spacetime-module/src/migration.rs
index 1be3b8d9d..52e3d874b 100644
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -1271,6 +1271,12 @@ fn normalize_migration_row(table_name: &str, value: &serde_json::Value) -> serde
             object
                 .entry("image_object_key".to_string())
                 .or_insert(serde_json::Value::Null);
+            object
+                .entry("image_width".to_string())
+                .or_insert(serde_json::Value::Null);
+            object
+                .entry("image_height".to_string())
+                .or_insert(serde_json::Value::Null);
         }
     }
     if table_name == "big_fish_creation_session" {
diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
index 53afccd73..bb6c348f4 100644
--- a/src/components/creation-home/creationShowcaseModel.test.ts
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -83,6 +83,8 @@ describe('creationShowcaseModel', () => {
         enabled: true,
         title: '活动精选',
         imageSrc: '/campaign.png',
+        imageWidth: 900,
+        imageHeight: 1200,
         prompt: '活动提示词',
         author: '运营',
         costText: '50泥点',
@@ -108,6 +110,10 @@ describe('creationShowcaseModel', () => {
       campaign: true,
       cost: '50泥点',
     });
+    expect(items[0]?.previews[0]).toMatchObject({
+      width: 900,
+      height: 1200,
+    });
     expect(items[1]).toMatchObject({
       id: 'asset:asset-1',
       label: '审核通过素材',
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
index fe17d6407..73947dbec 100644
--- a/src/components/creation-home/creationShowcaseModel.ts
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -805,6 +805,8 @@ function campaignToShowcaseItem(
         src: imageSrc,
         objectKey: objectKey || null,
         mediaType: 'image',
+        width: campaign.imageWidth ?? undefined,
+        height: campaign.imageHeight ?? undefined,
       },
     ],
     prompt: campaign.prompt.trim() || UNKNOWN_META_VALUE,
diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts
index 81ab06bf6..f85ede03f 100644
--- a/src/services/image-editor/editorProjectClient.test.ts
+++ b/src/services/image-editor/editorProjectClient.test.ts
@@ -239,6 +239,8 @@ describe('editorProjectClient', () => {
         enabled: true,
         title: '活动精选',
         imageSrc: '/campaign.png',
+        imageWidth: 900,
+        imageHeight: 1200,
         prompt: '活动提示词',
         author: '运营',
         costText: '50泥点',
@@ -254,6 +256,8 @@ describe('editorProjectClient', () => {
     expect(page.resources[0]?.authorPublicUserCode).toBe('SY-00000042');
     expect(page.nextCursor).toBe('cursor-next');
     expect(page.campaign?.title).toBe('活动精选');
+    expect(page.campaign?.imageWidth).toBe(900);
+    expect(page.campaign?.imageHeight).toBe(1200);
     expect(requestJsonMock).toHaveBeenCalledWith(
       '/api/editor/showcase/resources',
       { method: 'GET' },
diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
index 26b6c9320..cbe14feed 100644
--- a/src/services/image-editor/editorProjectClient.ts
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -139,6 +139,8 @@ export type EditorShowcaseCampaignSnapshot = {
   title: string;
   imageSrc: string;
   imageObjectKey?: string | null;
+  imageWidth?: number | null;
+  imageHeight?: number | null;
   prompt: string;
   author: string;
   costText: string;

From 2d631becc7be0010024964a48406ef77970be8fe Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 21:35:10 +0800
Subject: [PATCH 11/24] =?UTF-8?q?=E6=98=BE=E7=A4=BA=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E5=AE=A1=E6=A0=B8=E6=8F=90=E4=BA=A4=E5=A4=B1=E8=B4=A5=E5=8E=9F?=
 =?UTF-8?q?=E5=9B=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

统一素材精选审核提交资格判断

在素材菜单显示不可提交和后端拒绝原因

将编辑器业务拒绝映射为 400 并保留中文原因

补充精选审核原因展示测试和文档口径
---
 ...��作】创作主页与项目入口改版计划-2026-06-18.md |  2 +-
 .../crates/api-server/src/editor_project.rs   | 18 +++++
 .../ImageCanvasAssetLibraryModel.test.ts      | 53 +++++++++++++
 .../ImageCanvasAssetLibraryModel.ts           | 76 +++++++++++++++++++
 .../ImageCanvasAssetRowView.test.tsx          | 29 +++++++
 .../image-editor/ImageCanvasAssetRowView.tsx  | 28 +++----
 .../image-editor/ImageCanvasEditorTypes.ts    |  1 +
 .../useImageCanvasAssetLibrary.test.tsx       | 49 ++++++++++++
 .../useImageCanvasAssetLibrary.ts             | 29 +++++--
 src/index.css                                 | 20 +++++
 10 files changed, 281 insertions(+), 24 deletions(-)

diff --git a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
index 8a8701407..5d0efaeac 100644
--- a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
+++ b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
@@ -116,7 +116,7 @@ Tab：
 - 全部、角色、UI、音乐、音效、视频和美宣都必须来自用户素材库中已提交并通过审核的生成素材；不要求素材当前仍保留在某个项目资源中，已通过审核的快照在原素材删除后仍可保留公开展示。
 - 未登录用户也可读取公开精选；当没有公开画布生成资源时，不再用公开作品图片补充，只显示简洁空态。
 - 上传素材、公开作品图片、mock 资源和假组合都不进入精选。
-- 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。生成素材菜单内提供 `提交精选审核`，调用 `POST /api/editor/assets/{assetId}/showcase-submissions` 后进入 `pending` 状态；已提交、已通过或已拒绝的素材显示对应状态，不再显示默认打开的公开勾选项。
+- 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。生成素材菜单内提供 `提交精选审核`，调用 `POST /api/editor/assets/{assetId}/showcase-submissions` 后进入 `pending` 状态；已提交、已通过或已拒绝的素材显示对应状态，不再显示默认打开的公开勾选项。素材不可提交或后端拒绝提交时，菜单必须显示具体原因，例如非生成素材、素材尚未保存、没有媒体内容或审核未通过不能重复提交。
 - 后台新增纯素材查询页，读取账号级 `editor_asset` 中 `sourceType="generated"` 的素材，用于查看所有用户生成素材。该页只提供时间、用户 ID 和关键词查询，以及缩略图详情、提示词全文、生成成本、作者展示名和陶泥号查看；不提供分类筛选，也不承载审核、返还、展示开关或活动卡配置操作。
 - 不为了填满展示区创建假素材、假作者、假泥点成本或假组合关系。
 - 暂无真实数据的 Tab 保留 Tab 入口，但内容区显示简洁空态。
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index 1334333e5..bef9a9adf 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -5088,6 +5088,11 @@ pub(crate) fn map_editor_project_error(error: SpacetimeClientError) -> AppError
                 "message": message,
             }))
         }
+        SpacetimeClientError::Procedure(message) => AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_details(json!({
+                "provider": "editor-project",
+                "message": message,
+            })),
         SpacetimeClientError::Runtime(message) => AppError::from_status(StatusCode::BAD_REQUEST)
             .with_details(json!({
                 "provider": "editor-project",
@@ -5121,6 +5126,19 @@ mod tests {
     use super::*;
     use crate::config::AppConfig;
 
+    #[test]
+    fn editor_project_procedure_errors_preserve_business_reason_as_bad_request() {
+        let error = map_editor_project_error(SpacetimeClientError::Procedure(
+            "只有生成素材可以提交精选审核".to_string(),
+        ));
+
+        assert_eq!(error.status_code(), StatusCode::BAD_REQUEST);
+        assert_eq!(
+            error.details().and_then(|details| details.get("message")),
+            Some(&json!("只有生成素材可以提交精选审核")),
+        );
+    }
+
     fn apply_editor_canvas_generation_completion(
         layers: Value,
         completion: &EditorCanvasGenerationCompletionRequest,
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
index e009d12ae..826ee4ba7 100644
--- a/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
+++ b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
@@ -21,6 +21,7 @@ import {
   renameAssetFolderById,
   replaceLocalAssetFolder,
   resolveAllAssetSelection,
+  resolveAssetShowcaseSubmissionState,
   resolveAssetFolderIdFromPoint,
   resolveDefaultAssetFolder,
   resolvePreferredAssetUploadFolder,
@@ -89,6 +90,58 @@ describe('ImageCanvasAssetLibraryModel', () => {
     ]);
   });
 
+  it('explains why assets cannot be submitted to showcase review', () => {
+    expect(
+      resolveAssetShowcaseSubmissionState(createAsset()).reason,
+    ).toBe('只有生成素材可以提交精选审核');
+    expect(
+      resolveAssetShowcaseSubmissionState(
+        createAsset({ sourceType: 'generated', persisted: false }),
+      ).reason,
+    ).toBe('素材保存完成后才能提交精选审核');
+    expect(
+      resolveAssetShowcaseSubmissionState(
+        createAsset({ sourceType: 'generated', src: '' }),
+      ).reason,
+    ).toBe('没有媒体内容的素材不能提交精选审核');
+    expect(
+      resolveAssetShowcaseSubmissionState(
+        createAsset({
+          sourceType: 'generated',
+          showcaseReviewStatus: 'rejected',
+        }),
+      ),
+    ).toMatchObject({
+      canSubmit: false,
+      label: '精选未通过',
+      reason: '该素材审核未通过，不能重复提交',
+    });
+  });
+
+  it('allows persisted generated assets to be submitted and keeps prior backend errors visible', () => {
+    expect(
+      resolveAssetShowcaseSubmissionState(
+        createAsset({ sourceType: 'generated' }),
+      ),
+    ).toMatchObject({
+      canSubmit: true,
+      label: '提交精选审核',
+      reason: null,
+    });
+    expect(
+      resolveAssetShowcaseSubmissionState(
+        createAsset({
+          sourceType: 'generated',
+          showcaseSubmitError: '只有生成素材可以提交精选审核',
+        }),
+      ),
+    ).toMatchObject({
+      canSubmit: true,
+      label: '提交精选审核',
+      reason: '只有生成素材可以提交精选审核',
+    });
+  });
+
   it('filters grouped assets by folder and asset search text', () => {
     const groupedAssets = groupAssetsByFolder(
       [
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryModel.ts b/src/components/image-editor/ImageCanvasAssetLibraryModel.ts
index f97d1ce73..09ba9bd51 100644
--- a/src/components/image-editor/ImageCanvasAssetLibraryModel.ts
+++ b/src/components/image-editor/ImageCanvasAssetLibraryModel.ts
@@ -288,6 +288,82 @@ export function getSelectableAssets(assets: EditorAsset[]) {
   return assets.filter((asset) => asset.sourceKind === 'uploaded');
 }
 
+export type AssetShowcaseSubmissionState = {
+  canSubmit: boolean;
+  label: string;
+  reason: string | null;
+};
+
+function normalizeAssetShowcaseReason(value: string | null | undefined) {
+  return value?.trim() || null;
+}
+
+export function resolveAssetShowcaseSubmissionState(
+  asset: EditorAsset,
+): AssetShowcaseSubmissionState {
+  const reviewStatus = asset.showcaseReviewStatus ?? null;
+
+  if (reviewStatus === 'pending') {
+    return {
+      canSubmit: false,
+      label: '精选审核中',
+      reason: '素材正在审核中，请等待审核结果',
+    };
+  }
+
+  if (reviewStatus === 'approved') {
+    return {
+      canSubmit: false,
+      label:
+        asset.showcaseDisplayEnabled === false
+          ? '已入选精选，暂未展示'
+          : '已入选精选',
+      reason:
+        asset.showcaseDisplayEnabled === false
+          ? '素材已通过审核，运营后台开启展示后才会出现在前台'
+          : '素材已经入选精选',
+    };
+  }
+
+  if (reviewStatus === 'rejected') {
+    return {
+      canSubmit: false,
+      label: '精选未通过',
+      reason: '该素材审核未通过，不能重复提交',
+    };
+  }
+
+  if (asset.sourceType !== 'generated') {
+    return {
+      canSubmit: false,
+      label: '提交精选审核',
+      reason: '只有生成素材可以提交精选审核',
+    };
+  }
+
+  if (!asset.persisted) {
+    return {
+      canSubmit: false,
+      label: '提交精选审核',
+      reason: '素材保存完成后才能提交精选审核',
+    };
+  }
+
+  if (!asset.src.trim()) {
+    return {
+      canSubmit: false,
+      label: '提交精选审核',
+      reason: '没有媒体内容的素材不能提交精选审核',
+    };
+  }
+
+  return {
+    canSubmit: true,
+    label: '提交精选审核',
+    reason: normalizeAssetShowcaseReason(asset.showcaseSubmitError),
+  };
+}
+
 export function areAllSelectableAssetsSelected(
   selectableAssets: EditorAsset[],
   selectedAssetIds: Set<string>,
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
index dec4bac5e..10c12ac0b 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
@@ -371,6 +371,35 @@ describe('ImageCanvasAssetRowView', () => {
       name: /提交精选审核/u,
     });
     expect((submitMenuItem as HTMLButtonElement).disabled).toBe(true);
+    expect(screen.getByText('只有生成素材可以提交精选审核')).toBeTruthy();
+
+    fireEvent.click(submitMenuItem);
+    expect(submitAssetToShowcase).not.toHaveBeenCalled();
+  });
+
+  it('shows why generated assets cannot be submitted before they are saved', () => {
+    const submitAssetToShowcase = vi.fn();
+    renderAssetRow({
+      asset: createAsset({
+        sourceType: 'generated',
+        persisted: false,
+      }),
+      submitAssetToShowcase,
+    });
+
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '添加账号素材A' }),
+      {
+        clientX: 120,
+        clientY: 80,
+      },
+    );
+
+    const submitMenuItem = screen.getByRole('menuitem', {
+      name: /提交精选审核/u,
+    });
+    expect((submitMenuItem as HTMLButtonElement).disabled).toBe(true);
+    expect(screen.getByText('素材保存完成后才能提交精选审核')).toBeTruthy();
 
     fireEvent.click(submitMenuItem);
     expect(submitAssetToShowcase).not.toHaveBeenCalled();
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.tsx b/src/components/image-editor/ImageCanvasAssetRowView.tsx
index 32f387cbb..ebe252ecc 100644
--- a/src/components/image-editor/ImageCanvasAssetRowView.tsx
+++ b/src/components/image-editor/ImageCanvasAssetRowView.tsx
@@ -15,6 +15,7 @@ import {
   getDraggedAssetId,
   hasDataTransferType,
 } from './ImageCanvasEditorModel';
+import { resolveAssetShowcaseSubmissionState } from './ImageCanvasAssetLibraryModel';
 import type {
   AssetPointerDragState,
   EditorAsset,
@@ -85,20 +86,10 @@ export function ImageCanvasAssetRowView({
   const isUploadingAsset = asset.uploadStatus === 'uploading';
   const isFailedUpload = asset.uploadStatus === 'failed';
   const showcaseReviewStatus = asset.showcaseReviewStatus ?? null;
-  const canSubmitShowcaseAsset =
-    asset.sourceType === 'generated' &&
-    asset.persisted &&
-    !showcaseReviewStatus;
-  const showcaseMenuLabel =
-    showcaseReviewStatus === 'pending'
-      ? '精选审核中'
-      : showcaseReviewStatus === 'approved'
-        ? asset.showcaseDisplayEnabled === false
-          ? '已入选精选，暂未展示'
-          : '已入选精选'
-        : showcaseReviewStatus === 'rejected'
-          ? '精选未通过'
-          : '提交精选审核';
+  const showcaseSubmissionState = resolveAssetShowcaseSubmissionState(asset);
+  const canSubmitShowcaseAsset = showcaseSubmissionState.canSubmit;
+  const showcaseMenuLabel = showcaseSubmissionState.label;
+  const showcaseMenuReason = showcaseSubmissionState.reason;
 
   const closeMenu = useCallback(() => {
     setMenuPosition(null);
@@ -460,16 +451,21 @@ export function ImageCanvasAssetRowView({
             role="menuitem"
             className="image-canvas-editor__asset-context-menu-toggle"
             disabled={!canSubmitShowcaseAsset}
+            title={showcaseMenuReason ?? showcaseMenuLabel}
             onClick={() => {
               if (!canSubmitShowcaseAsset) {
                 return;
               }
               submitAssetToShowcase(asset);
-              closeMenu();
             }}
           >
             <span className="image-canvas-editor__asset-context-menu-label">
-              {showcaseMenuLabel}
+              <span>{showcaseMenuLabel}</span>
+              {showcaseMenuReason ? (
+                <span className="image-canvas-editor__asset-context-menu-reason">
+                  {showcaseMenuReason}
+                </span>
+              ) : null}
             </span>
             {showcaseReviewStatus === 'approved' ? (
               <span
diff --git a/src/components/image-editor/ImageCanvasEditorTypes.ts b/src/components/image-editor/ImageCanvasEditorTypes.ts
index d5f3131ba..efc896315 100644
--- a/src/components/image-editor/ImageCanvasEditorTypes.ts
+++ b/src/components/image-editor/ImageCanvasEditorTypes.ts
@@ -54,6 +54,7 @@ export type EditorAsset = {
   showcaseReviewStatus?: string | null;
   showcaseDisplayEnabled?: boolean | null;
   showcaseLikeCount?: number | null;
+  showcaseSubmitError?: string | null;
   assetKind?: CanvasAssetKind | null;
   generationInputs?: CanvasGenerationInputs | null;
   durationSeconds?: number;
diff --git a/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx b/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx
index b4f5473fb..b820c6efc 100644
--- a/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx
+++ b/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx
@@ -117,6 +117,11 @@ function AssetLibraryHarness({
           )
           .join('|')}
       </span>
+      <span data-testid="asset-submit-errors">
+        {assetLibrary.assets
+          .map((asset) => `${asset.id}:${asset.showcaseSubmitError ?? ''}`)
+          .join('|')}
+      </span>
       <span data-testid="active-upload-folder">
         {assetLibrary.activeUploadFolderId}
       </span>
@@ -537,4 +542,48 @@ describe('useImageCanvasAssetLibrary', () => {
       );
     });
   });
+
+  it('keeps the backend showcase rejection reason on the asset', async () => {
+    submitEditorAssetShowcaseMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '只有生成素材可以提交精选审核',
+        status: 400,
+        code: 'BAD_REQUEST',
+      }),
+    );
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        createAssetSnapshot({
+          assetId: 'asset-a',
+          sourceType: 'generated',
+          publicShowcaseEnabled: true,
+        }),
+      ],
+    });
+
+    render(<AssetLibraryHarness />);
+
+    await screen.findByText('素材A');
+    act(() =>
+      screen.getByRole('button', { name: 'submit asset to showcase' }).click(),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('asset-submit-errors').textContent).toBe(
+        'asset-a:只有生成素材可以提交精选审核',
+      );
+    });
+    expect(screen.getByTestId('assets').textContent).toBe(
+      'asset-a:素材A:project:true',
+    );
+  });
 });
diff --git a/src/components/image-editor/useImageCanvasAssetLibrary.ts b/src/components/image-editor/useImageCanvasAssetLibrary.ts
index 0c5a7db6b..db016cb2a 100644
--- a/src/components/image-editor/useImageCanvasAssetLibrary.ts
+++ b/src/components/image-editor/useImageCanvasAssetLibrary.ts
@@ -39,6 +39,7 @@ import {
   renameAssetById,
   renameAssetFolderById,
   replaceLocalAssetFolder,
+  resolveAssetShowcaseSubmissionState,
   resolveAllAssetSelection,
   resolveDefaultAssetFolder,
   resolveAssetFolderIdFromPoint,
@@ -63,6 +64,16 @@ function isEditorAuthError(error: unknown) {
   );
 }
 
+function formatShowcaseSubmitError(error: unknown) {
+  if (error instanceof ApiClientError && error.message.trim()) {
+    return error.message.trim();
+  }
+  if (error instanceof Error && error.message.trim()) {
+    return error.message.trim();
+  }
+  return '提交精选审核失败，请稍后重试';
+}
+
 const ASSET_FOLDER_SELECTOR = '[data-asset-folder-id]';
 const ASSET_ITEM_SELECTOR = '[data-asset-id]';
 const ASSET_MARQUEE_BLOCKED_TARGET_SELECTOR =
@@ -356,11 +367,7 @@ export function useImageCanvasAssetLibrary({
 
   const submitAssetToShowcase = useCallback(
     (asset: EditorAsset) => {
-      if (
-        asset.sourceType !== 'generated' ||
-        !asset.persisted ||
-        asset.showcaseReviewStatus
-      ) {
+      if (!resolveAssetShowcaseSubmissionState(asset).canSubmit) {
         return;
       }
       const previousAsset = asset;
@@ -372,6 +379,7 @@ export function useImageCanvasAssetLibrary({
                 publicShowcaseEnabled: false,
                 showcaseReviewStatus: 'pending',
                 showcaseDisplayEnabled: false,
+                showcaseSubmitError: undefined,
               }
             : currentAsset,
         ),
@@ -391,15 +399,22 @@ export function useImageCanvasAssetLibrary({
                     generationCostMudPoints:
                       showcaseAsset.generationCostMudPoints ??
                       currentAsset.generationCostMudPoints,
+                    showcaseSubmitError: undefined,
                   }
                 : currentAsset,
             ),
           );
         })
-        .catch(() => {
+        .catch((error: unknown) => {
+          const showcaseSubmitError = formatShowcaseSubmitError(error);
           setAssets((currentAssets) =>
             currentAssets.map((currentAsset) =>
-              currentAsset.id === asset.id ? previousAsset : currentAsset,
+              currentAsset.id === asset.id
+                ? {
+                    ...previousAsset,
+                    showcaseSubmitError,
+                  }
+                : currentAsset,
             ),
           );
         });
diff --git a/src/index.css b/src/index.css
index 1402c9eef..e5f01af6c 100644
--- a/src/index.css
+++ b/src/index.css
@@ -8399,14 +8399,34 @@ button.image-canvas-editor__reference-chip:disabled {
 
 .image-canvas-editor__asset-context-menu
   button.image-canvas-editor__asset-context-menu-toggle {
+  min-height: 2.2rem;
   justify-content: space-between;
   gap: 1rem;
+  padding-top: 0.28rem;
+  padding-bottom: 0.28rem;
+  white-space: normal;
 }
 
 .image-canvas-editor__asset-context-menu-label {
+  display: grid;
   min-width: 0;
   flex: 1 1 auto;
+  gap: 0.12rem;
+  line-height: 1.15;
   text-align: left;
+  white-space: normal;
+}
+
+.image-canvas-editor__asset-context-menu-reason {
+  color: #64748b;
+  font-size: 0.68rem;
+  font-weight: 680;
+  line-height: 1.2;
+}
+
+.image-canvas-editor__asset-context-menu button:disabled
+  .image-canvas-editor__asset-context-menu-reason {
+  color: #94a3b8;
 }
 
 .image-canvas-editor__asset-context-menu-check {

From 4622b35a323902a192eb335c1a6baed0426fde0f Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 6 Jul 2026 22:59:25 +0800
Subject: [PATCH 12/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E6=B4=BB=E5=8A=A8=E5=9B=BE=E8=A3=81=E5=88=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

移除精选预览容器最大高度限制

让活动图按记录宽高自然拉伸卡片高度

通过浏览器验证 900x1200 活动图比例不再被压到 23rem
---
 src/index.css | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/index.css b/src/index.css
index e5f01af6c..6e01a877e 100644
--- a/src/index.css
+++ b/src/index.css
@@ -3913,7 +3913,6 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   display: grid;
   width: 100%;
   min-height: 9.5rem;
-  max-height: 23rem;
   overflow: hidden;
   place-items: stretch;
   background: linear-gradient(180deg, #fffdfa, #fff4ea);

From 2a98b60830993ac07da1c6c87f6d0e69947db02b Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 14:03:45 +0800
Subject: [PATCH 13/24] =?UTF-8?q?=E6=94=B9=E4=B8=BA=E8=BF=90=E8=A1=8C?=
 =?UTF-8?q?=E6=97=B6=E6=8E=A7=E5=88=B6=E7=94=BB=E6=9D=BF=20Agent=20?=
 =?UTF-8?q?=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增前端运行时配置接口下发画板 Agent 开关

将画板 Agent 入口改为读取后端运行时配置

把开关变量改为 GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR

补充前后端测试和生产环境变量文档
---
 .env                                          |  2 +-
 .env.example                                  |  6 +--
 .env.local                                    |  2 +-
 deploy/env/api-server.env.example             |  1 +
 ...�】server-rs与SpacetimeDB数据契约-2026-05-15.md |  2 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |  4 ++
 server-rs/crates/api-server/src/app.rs        | 46 +++++++++++++++++++
 server-rs/crates/api-server/src/config.rs     | 27 +++++++++++
 .../api-server/src/frontend_runtime_config.rs | 25 ++++++++++
 server-rs/crates/api-server/src/main.rs       |  1 +
 server-rs/crates/api-server/src/modules.rs    |  1 +
 .../src/modules/frontend_runtime_config.rs    | 10 ++++
 .../ImageCanvasEditorView.test.tsx            | 22 ++++++---
 .../image-editor/ImageCanvasEditorView.tsx    | 36 +++++++++++----
 .../frontendRuntimeConfigService.test.ts      | 43 +++++++++++++++++
 src/services/frontendRuntimeConfigService.ts  | 21 +++++++++
 src/vite-env.d.ts                             |  1 -
 17 files changed, 227 insertions(+), 23 deletions(-)
 create mode 100644 server-rs/crates/api-server/src/frontend_runtime_config.rs
 create mode 100644 server-rs/crates/api-server/src/modules/frontend_runtime_config.rs
 create mode 100644 src/services/frontendRuntimeConfigService.test.ts
 create mode 100644 src/services/frontendRuntimeConfigService.ts

diff --git a/.env b/.env
index 72324e587..424107578 100644
--- a/.env
+++ b/.env
@@ -1,6 +1,6 @@
 # 微信小程序 web-view 登录配置。
 # 留空时不覆盖已有微信网页 OAuth 配置；正式联调时再填小程序 AppID / AppSecret。
-VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false
 
 WECHAT_MINI_PROGRAM_APP_ID=""
 WECHAT_MINI_PROGRAM_APP_SECRET=""
diff --git a/.env.example b/.env.example
index 32a49b796..6b611bebd 100644
--- a/.env.example
+++ b/.env.example
@@ -199,9 +199,9 @@ VITE_LLM_DEBUG_LOG="false"
 # Set to "true" to expose local diagnostic panels, or "false" to hide them.
 VITE_DEBUG_MODE=""
 
-# Optional: show the image editor right-side Agent entry.
-# Keep this off by default outside local development.
-VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
+# Optional: show the image editor right-side Agent entry at runtime.
+# This is read by api-server and exposed through /api/runtime/frontend-config.
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR="false"
 
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
diff --git a/.env.local b/.env.local
index cbc3ab9a0..66c7cb8e0 100644
--- a/.env.local
+++ b/.env.local
@@ -42,7 +42,7 @@ LLM_DEBUG_LOG="true"
 # 注意：不要在客户端启用调试日志，避免敏感数据泄露
 # VITE_LLM_DEBUG_LOG="false"
 
-VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=true
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=true
 
 ALIYUN_OSS_BUCKET="xushi-dev"
 ALIYUN_OSS_REGION="oss-cn-beijing"
diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example
index a0ac06244..55e98f44a 100644
--- a/deploy/env/api-server.env.example
+++ b/deploy/env/api-server.env.example
@@ -49,6 +49,7 @@ AUTH_REFRESH_COOKIE_PATH=/api/auth
 AUTH_REFRESH_COOKIE_SAME_SITE=Lax
 AUTH_REFRESH_COOKIE_SECURE=true
 GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=false
+GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false
 
 GENARRATIVE_SPACETIME_SERVER_URL=http://127.0.0.1:3101
 GENARRATIVE_SPACETIME_DATABASE=genarrative-prod
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index f70da612d..c85477a89 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -60,7 +60,7 @@ npm run check:server-rs-ddd
 - 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
 - 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
 - 外部 OpenAPI：`/api/external/v1/openapi.json`、`/api/external/v1/assets/direct-upload-tickets`、`/api/external/v1/assets/objects/confirm`、`/api/external/v1/assets/read-url`、`/api/external/v1/editor/*`，使用 Bearer API Key 鉴权；API Key 管理仍在登录态 `/api/profile/api-keys`，不进入外部 OpenAPI JSON。
-- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`、`/api/editor/projects*`、`/api/editor/projects/{projectId}/agent-conversations`、`/api/editor/agent-conversations/{conversationId}*`。`/api/runtime/custom-world/asset-studio/*` 解析默认角色形象 / 动作提示词时可以在 OSS 缓存不可用或未配置时按无缓存返回默认提示；保存 workflow 缓存和真实素材读写仍必须要求 OSS 正常可用。
+- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/frontend-config`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`、`/api/editor/projects*`、`/api/editor/projects/{projectId}/agent-conversations`、`/api/editor/agent-conversations/{conversationId}*`。`/api/runtime/frontend-config` 由 `api-server` 从运行时环境变量下发非敏感 UI 开关；画板右侧 Agent 入口由 `GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR` 控制，默认关闭，前端不再读取 `VITE_*` 构建期变量决定生产显示。`/api/runtime/custom-world/asset-studio/*` 解析默认角色形象 / 动作提示词时可以在 OSS 缓存不可用或未配置时按无缓存返回默认提示；保存 workflow 缓存和真实素材读写仍必须要求 OSS 正常可用。
 - 后台入口配置：`/admin/api/creation-entry/config`、`/admin/api/creation-entry/config/banners` 和 `/admin/api/creation-entry/config/interactions`。
 - 后台素材查询：`GET /admin/api/editor-assets` 通过 `admin_list_editor_assets_and_return` 后台只读 procedure 读取私有账号级 `editor_asset` 中 `source_type = 'generated'` 的素材，支持 `ownerUserId`、`keyword`、`createdAfter`、`createdBefore`、`cursor` 和 `limit`；返回缩略图 / Object Key、作者展示名、陶泥号、提示词、生成输入和生成成本，只用于查询，不提供分类筛选，也不执行精选审核、返还或展示状态修改，不通过后台 SQL 直查私有表。
 - 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 720e9d07f..c72151731 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -234,6 +234,10 @@ npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.servi
 
 生产环境变量模板在 `deploy/env/api-server.env.example`：
 
+主站前端运行时配置由 `api-server` 下发；画板右侧 Agent 入口使用
+`GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR=false` 默认关闭，需要开启时只改生产
+api-server 环境变量并重启 `api-server`，不再通过 `VITE_*` 构建期变量控制。
+
 ```env
 GENARRATIVE_DATABASE_BACKUP_DATA_DIR=/stdb
 GENARRATIVE_DATABASE_BACKUP_WORK_DIR=/var/lib/genarrative/database-backups
diff --git a/server-rs/crates/api-server/src/app.rs b/server-rs/crates/api-server/src/app.rs
index 48bc995f1..3ede90f65 100644
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -43,6 +43,7 @@ pub fn build_router(state: AppState) -> Router {
         .merge(modules::auth::router(state.clone()))
         .merge(modules::profile::router(state.clone()))
         .merge(modules::external_api::router(state.clone()))
+        .merge(modules::frontend_runtime_config::router(state.clone()))
         .merge(modules::assets::router(state.clone()))
         .merge(modules::editor_project::router(state.clone()))
         .merge(modules::platform::router(state.clone()))
@@ -518,6 +519,51 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn frontend_runtime_config_defaults_agent_sidebar_to_disabled() {
+        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .uri("/api/runtime/frontend-config")
+                    .body(Body::empty())
+                    .expect("frontend config request should build"),
+            )
+            .await
+            .expect("frontend config request should succeed");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let payload = read_json_response(response).await;
+        assert_eq!(
+            payload["imageEditorAgentSidebarEnabled"],
+            Value::Bool(false)
+        );
+    }
+
+    #[tokio::test]
+    async fn frontend_runtime_config_returns_agent_sidebar_env_flag() {
+        let config = AppConfig {
+            image_editor_agent_sidebar_enabled: true,
+            ..AppConfig::default()
+        };
+        let app = build_router(AppState::new(config).expect("state should build"));
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .uri("/api/runtime/frontend-config")
+                    .body(Body::empty())
+                    .expect("frontend config request should build"),
+            )
+            .await
+            .expect("frontend config request should succeed");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let payload = read_json_response(response).await;
+        assert_eq!(payload["imageEditorAgentSidebarEnabled"], Value::Bool(true));
+    }
+
     #[tokio::test]
     async fn spacetime_unavailable_router_returns_service_unavailable_for_requests() {
         let app =
diff --git a/server-rs/crates/api-server/src/config.rs b/server-rs/crates/api-server/src/config.rs
index fa03dc2a6..721500570 100644
--- a/server-rs/crates/api-server/src/config.rs
+++ b/server-rs/crates/api-server/src/config.rs
@@ -56,6 +56,7 @@ pub struct AppConfig {
     pub editor_background_removal_base_url: String,
     pub editor_background_removal_token: Option<String>,
     pub editor_background_removal_request_timeout_ms: u64,
+    pub image_editor_agent_sidebar_enabled: bool,
     pub log_filter: String,
     pub otel_enabled: bool,
     pub admin_username: Option<String>,
@@ -283,6 +284,7 @@ impl Default for AppConfig {
             editor_background_removal_token: None,
             editor_background_removal_request_timeout_ms:
                 DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS,
+            image_editor_agent_sidebar_enabled: false,
             log_filter: "info,tower_http=info".to_string(),
             otel_enabled: false,
             admin_username: None,
@@ -473,6 +475,11 @@ impl AppConfig {
         ]) {
             config.editor_background_removal_request_timeout_ms = timeout_ms;
         }
+        if let Some(enabled) =
+            read_first_bool_env(&["GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR"])
+        {
+            config.image_editor_agent_sidebar_enabled = enabled;
+        }
         if let Some(listen_backlog) =
             read_first_positive_i32_env(&["GENARRATIVE_API_LISTEN_BACKLOG"])
         {
@@ -2176,6 +2183,26 @@ mod tests {
         }
     }
 
+    #[test]
+    fn from_env_reads_image_editor_agent_sidebar_runtime_flag() {
+        let _guard = ENV_LOCK
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .expect("env lock should not poison");
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR");
+            std::env::set_var("GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR", "true");
+        }
+
+        let config = AppConfig::from_env();
+        assert!(config.image_editor_agent_sidebar_enabled);
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR");
+        }
+    }
+
     #[test]
     fn from_env_reads_prefixed_character_animation_ffmpeg_paths() {
         let _guard = ENV_LOCK
diff --git a/server-rs/crates/api-server/src/frontend_runtime_config.rs b/server-rs/crates/api-server/src/frontend_runtime_config.rs
new file mode 100644
index 000000000..64aea1631
--- /dev/null
+++ b/server-rs/crates/api-server/src/frontend_runtime_config.rs
@@ -0,0 +1,25 @@
+use axum::{
+    Json,
+    extract::{Extension, State},
+};
+use serde::Serialize;
+
+use crate::{api_response::json_success_body, request_context::RequestContext, state::AppState};
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FrontendRuntimeConfigResponse {
+    pub image_editor_agent_sidebar_enabled: bool,
+}
+
+pub async fn get_frontend_runtime_config(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+) -> Json<serde_json::Value> {
+    json_success_body(
+        Some(&request_context),
+        FrontendRuntimeConfigResponse {
+            image_editor_agent_sidebar_enabled: state.config.image_editor_agent_sidebar_enabled,
+        },
+    )
+}
diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs
index 6e109a4cb..c05b63082 100644
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -52,6 +52,7 @@ mod external_editor_api;
 mod external_generation;
 mod external_generation_worker;
 mod external_generation_worker_controller;
+mod frontend_runtime_config;
 pub(crate) mod generated_asset_sheets;
 mod generated_image_assets;
 mod health;
diff --git a/server-rs/crates/api-server/src/modules.rs b/server-rs/crates/api-server/src/modules.rs
index ee51d7682..5b1da6d9b 100644
--- a/server-rs/crates/api-server/src/modules.rs
+++ b/server-rs/crates/api-server/src/modules.rs
@@ -8,6 +8,7 @@ pub mod editor_project;
 pub mod edutainment;
 pub mod external_api;
 pub mod external_generation;
+pub mod frontend_runtime_config;
 pub mod health;
 pub mod internal;
 pub mod jump_hop;
diff --git a/server-rs/crates/api-server/src/modules/frontend_runtime_config.rs b/server-rs/crates/api-server/src/modules/frontend_runtime_config.rs
new file mode 100644
index 000000000..0307b2e62
--- /dev/null
+++ b/server-rs/crates/api-server/src/modules/frontend_runtime_config.rs
@@ -0,0 +1,10 @@
+use axum::{Router, routing::get};
+
+use crate::{frontend_runtime_config::get_frontend_runtime_config, state::AppState};
+
+pub fn router(_state: AppState) -> Router<AppState> {
+    Router::new().route(
+        "/api/runtime/frontend-config",
+        get(get_frontend_runtime_config),
+    )
+}
diff --git a/src/components/image-editor/ImageCanvasEditorView.test.tsx b/src/components/image-editor/ImageCanvasEditorView.test.tsx
index 67b9f73a7..0406607f6 100644
--- a/src/components/image-editor/ImageCanvasEditorView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.test.tsx
@@ -41,7 +41,6 @@ type EditorAgentConversationSummary = Awaited<
 type EditorAgentConversationDetail = Awaited<
   ReturnType<EditorAgentGetConversation>
 >;
-const EDITOR_AGENT_SIDEBAR_ENV = 'VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR';
 
 const listEditorAgentConversationsMock = vi.hoisted(() =>
   vi.fn<
@@ -110,6 +109,7 @@ const loadOrCreateRecentEditorProjectMock = vi.hoisted(() => vi.fn());
 const renameEditorProjectMock = vi.hoisted(() => vi.fn());
 const saveEditorProjectLayoutMock = vi.hoisted(() => vi.fn());
 const getPlatformProfileDashboardMock = vi.hoisted(() => vi.fn());
+const loadFrontendRuntimeConfigMock = vi.hoisted(() => vi.fn());
 
 vi.mock('../../services/image-editor/editorProjectClient', async () => {
   const actual = await vi.importActual<
@@ -140,6 +140,10 @@ vi.mock('../../services/platform-entry/platformProfileClient', () => ({
   getPlatformProfileDashboard: getPlatformProfileDashboardMock,
 }));
 
+vi.mock('../../services/frontendRuntimeConfigService', () => ({
+  loadFrontendRuntimeConfig: loadFrontendRuntimeConfigMock,
+}));
+
 vi.mock('../../services/image-editor/editorAgentClient', () => ({
   createEditorAgentConversation: createEditorAgentConversationMock,
   deleteEditorAgentConversation: deleteEditorAgentConversationMock,
@@ -214,7 +218,7 @@ function openMinimap() {
 }
 
 async function ensureAgentConversationOpen() {
-  const agentButton = screen.getByRole('button', { name: '画布 Agent' });
+  const agentButton = await screen.findByRole('button', { name: '画布 Agent' });
   if (agentButton.getAttribute('aria-pressed') !== 'true') {
     fireEvent.click(agentButton);
   }
@@ -222,7 +226,9 @@ async function ensureAgentConversationOpen() {
 }
 
 function enableEditorAgentSidebarForTest() {
-  vi.stubEnv(EDITOR_AGENT_SIDEBAR_ENV, 'true');
+  loadFrontendRuntimeConfigMock.mockResolvedValue({
+    imageEditorAgentSidebarEnabled: true,
+  });
 }
 
 describe('ImageCanvasEditorView', () => {
@@ -246,7 +252,9 @@ describe('ImageCanvasEditorView', () => {
   });
 
   beforeEach(() => {
-    vi.stubEnv(EDITOR_AGENT_SIDEBAR_ENV, 'false');
+    loadFrontendRuntimeConfigMock.mockResolvedValue({
+      imageEditorAgentSidebarEnabled: false,
+    });
     listEditorAgentConversationsMock.mockResolvedValue([]);
     createEditorAgentConversationMock.mockResolvedValue({
       ...createEditorAgentConversationSummary({
@@ -277,7 +285,7 @@ describe('ImageCanvasEditorView', () => {
     deleteEditorAgentConversationMock.mockReset();
     streamEditorAgentMessageMock.mockReset();
     getPlatformProfileDashboardMock.mockReset();
-    vi.unstubAllEnvs();
+    loadFrontendRuntimeConfigMock.mockReset();
   });
 
   it('loads the project from projectid query before falling back to recent project', async () => {
@@ -1487,6 +1495,8 @@ describe('ImageCanvasEditorView', () => {
     enableEditorAgentSidebarForTest();
     render(<ImageCanvasEditorView />);
 
+    await screen.findByRole('button', { name: '画布 Agent' });
+
     const assetSidebar = openAssetSidebar();
     expect(within(assetSidebar).getByText('素材')).toBeTruthy();
 
@@ -1507,7 +1517,7 @@ describe('ImageCanvasEditorView', () => {
       screen.getByRole('complementary', { name: '画布任务列表' }),
     ).toBeTruthy();
 
-    fireEvent.click(screen.getByRole('button', { name: '画布 Agent' }));
+    fireEvent.click(await screen.findByRole('button', { name: '画布 Agent' }));
     expect(
       screen.getByRole('complementary', { name: '图片资源栏' }),
     ).toBeTruthy();
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index 504334bf5..8f96c6ef3 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -19,6 +19,7 @@ import {
   loadEditorProject,
   loadEditorGenerationPricing,
 } from '../../services/image-editor/editorProjectClient';
+import { loadFrontendRuntimeConfig } from '../../services/frontendRuntimeConfigService';
 import { shouldShowRechargeEntry } from '../../services/payment/paymentPlatform';
 import { getPlatformProfileDashboard } from '../../services/platform-entry/platformProfileClient';
 import { useAuthUi } from '../auth/AuthUiContext';
@@ -117,12 +118,6 @@ type ImageCanvasEditorViewProps = {
   onProjectAccessLost?: () => void;
 };
 
-function resolveEditorAgentSidebarEnabled(
-  rawValue = import.meta.env.VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR,
-): boolean {
-  return rawValue === 'true' || rawValue === '1';
-}
-
 function isCanvasStartupTool(value: string | null): value is CanvasStartupTool {
   return CANVAS_STARTUP_TOOLS.includes(value as CanvasStartupTool);
 }
@@ -327,6 +322,9 @@ export function ImageCanvasEditorView({
   const showRechargeEntry = shouldShowRechargeEntry();
   const currentEditorUserId = authUi?.user?.id ?? null;
   const [isToolbarGuideVisible, setIsToolbarGuideVisible] = useState(false);
+  const [isAgentConversationEnabled, setIsAgentConversationEnabled] =
+    useState(false);
+  const [isAgentConversationOpen, setIsAgentConversationOpen] = useState(false);
 
   useEffect(() => {
     let isMounted = true;
@@ -345,6 +343,28 @@ export function ImageCanvasEditorView({
       isMounted = false;
     };
   }, []);
+  useEffect(() => {
+    let isMounted = true;
+    void loadFrontendRuntimeConfig()
+      .then((config) => {
+        if (!isMounted) {
+          return;
+        }
+        const enabled = config.imageEditorAgentSidebarEnabled === true;
+        setIsAgentConversationEnabled(enabled);
+        setIsAgentConversationOpen(enabled);
+      })
+      .catch(() => {
+        if (!isMounted) {
+          return;
+        }
+        setIsAgentConversationEnabled(false);
+        setIsAgentConversationOpen(false);
+      });
+    return () => {
+      isMounted = false;
+    };
+  }, []);
   const selectedLayerIdsRef = useRef<string[]>([]);
   const setQuickEditPanelRef = useRef<
     Dispatch<SetStateAction<QuickEditPanelState | null>>
@@ -1167,10 +1187,6 @@ export function ImageCanvasEditorView({
     applyProjectSnapshot: applyGeneratedProjectSnapshot,
     onWalletBalanceMayHaveChanged: refreshEditorWalletBalance,
   });
-  const isAgentConversationEnabled = resolveEditorAgentSidebarEnabled();
-  const [isAgentConversationOpen, setIsAgentConversationOpen] = useState(
-    () => isAgentConversationEnabled,
-  );
   const effectiveIsAgentConversationOpen =
     isAgentConversationEnabled && isAgentConversationOpen;
   const toggleAgentConversation = useCallback(() => {
diff --git a/src/services/frontendRuntimeConfigService.test.ts b/src/services/frontendRuntimeConfigService.test.ts
new file mode 100644
index 000000000..1c6adca9a
--- /dev/null
+++ b/src/services/frontendRuntimeConfigService.test.ts
@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const apiClientMocks = vi.hoisted(() => ({
+  requestJson: vi.fn(),
+}));
+
+vi.mock('./apiClient', async () => {
+  const actual =
+    await vi.importActual<typeof import('./apiClient')>('./apiClient');
+  return {
+    ...actual,
+    requestJson: apiClientMocks.requestJson,
+  };
+});
+
+import { loadFrontendRuntimeConfig } from './frontendRuntimeConfigService';
+
+describe('frontendRuntimeConfigService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    apiClientMocks.requestJson.mockResolvedValue({
+      imageEditorAgentSidebarEnabled: false,
+    });
+  });
+
+  it('loads public frontend runtime config without auth side effects', async () => {
+    await expect(loadFrontendRuntimeConfig()).resolves.toEqual({
+      imageEditorAgentSidebarEnabled: false,
+    });
+
+    expect(apiClientMocks.requestJson).toHaveBeenCalledWith(
+      '/api/runtime/frontend-config',
+      { method: 'GET' },
+      '读取前端运行时配置失败',
+      {
+        skipAuth: true,
+        skipRefresh: true,
+        notifyAuthStateChange: false,
+        clearAuthOnUnauthorized: false,
+      },
+    );
+  });
+});
diff --git a/src/services/frontendRuntimeConfigService.ts b/src/services/frontendRuntimeConfigService.ts
new file mode 100644
index 000000000..2b76fba27
--- /dev/null
+++ b/src/services/frontendRuntimeConfigService.ts
@@ -0,0 +1,21 @@
+import { requestJson } from './apiClient';
+
+const FRONTEND_RUNTIME_CONFIG_API = '/api/runtime/frontend-config';
+
+export type FrontendRuntimeConfig = {
+  imageEditorAgentSidebarEnabled: boolean;
+};
+
+export async function loadFrontendRuntimeConfig() {
+  return requestJson<FrontendRuntimeConfig>(
+    FRONTEND_RUNTIME_CONFIG_API,
+    { method: 'GET' },
+    '读取前端运行时配置失败',
+    {
+      skipAuth: true,
+      skipRefresh: true,
+      notifyAuthStateChange: false,
+      clearAuthOnUnauthorized: false,
+    },
+  );
+}
diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts
index 0cf010431..81879c63e 100644
--- a/src/vite-env.d.ts
+++ b/src/vite-env.d.ts
@@ -2,7 +2,6 @@
 
 interface ImportMetaEnv {
   readonly VITE_DEBUG_MODE?: string;
-  readonly VITE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR?: string;
 }
 
 interface Window {

From 5477abd7ba821c0592077077b0739b4657388058 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 14:19:46 +0800
Subject: [PATCH 14/24] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E6=B4=BB=E5=8A=A8=E5=9B=BE=E5=B1=85=E4=B8=AD=E6=98=BE=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

恢复精选预览容器 23rem 高度上限

为活动卡预览添加独立样式并使用 contain 居中显示图片

补充活动卡预览 class 与比例测试
---
 .../CreationLandingView.test.tsx              | 32 +++++++++++++++++++
 .../creation-home/CreationLandingView.tsx     | 13 +++++---
 src/index.css                                 | 13 ++++++++
 3 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
index a403c7f45..b2333be8c 100644
--- a/src/components/creation-home/CreationLandingView.test.tsx
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -611,10 +611,42 @@ describe('CreationLandingView', () => {
       '.creation-landing__asset-preview',
     ) as HTMLElement | null;
     expect(firstPreview?.style.aspectRatio).toBe('512 / 640');
+    expect(firstPreview?.className).not.toContain(
+      'creation-landing__asset-preview--campaign',
+    );
     expect(screen.queryByText('经典 RPG 体验')).toBeNull();
     expect(screen.queryByText('拼图关卡创作')).toBeNull();
   });
 
+  it('renders campaign card previews with centered contain media', async () => {
+    listEditorProjectsMock.mockResolvedValue(projectItems);
+    listPublicEditorProjectResourcesMock.mockResolvedValue({
+      resources: [],
+      nextCursor: null,
+      campaign: {
+        enabled: true,
+        title: '活动精选',
+        imageSrc: '/campaign.png',
+        imageWidth: 900,
+        imageHeight: 1200,
+        prompt: '活动提示词',
+        author: '运营',
+        costText: '50泥点',
+      },
+    });
+
+    const { container } = renderCreationLanding();
+
+    expect(await screen.findByText('活动精选')).toBeTruthy();
+    const campaignPreview = container.querySelector(
+      '.creation-landing__asset-preview',
+    ) as HTMLElement | null;
+    expect(campaignPreview?.className).toContain(
+      'creation-landing__asset-preview--campaign',
+    );
+    expect(campaignPreview?.style.aspectRatio).toBe('900 / 1200');
+  });
+
   it('loads more featured resources when the waterfall reaches the end', async () => {
     const observers = installIntersectionObserverMock();
     listEditorProjectsMock.mockResolvedValueOnce(projectItems);
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
index ec07c8e04..ea7b08279 100644
--- a/src/components/creation-home/CreationLandingView.tsx
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -282,6 +282,13 @@ function ShowcaseVideoPreview({
 function ShowcaseBundlePreview({ item }: { item: ShowcaseAssetItem }) {
   const visiblePreviews = item.previews.slice(0, 4);
   const primaryPreview = visiblePreviews[0];
+  const previewClassName = [
+    'creation-landing__asset-preview',
+    item.previews.length > 1 ? 'creation-landing__asset-preview--bundle' : '',
+    item.campaign ? 'creation-landing__asset-preview--campaign' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
 
   if (!primaryPreview) {
     return null;
@@ -289,11 +296,7 @@ function ShowcaseBundlePreview({ item }: { item: ShowcaseAssetItem }) {
 
   return (
     <div
-      className={
-        item.previews.length > 1
-          ? 'creation-landing__asset-preview creation-landing__asset-preview--bundle'
-          : 'creation-landing__asset-preview'
-      }
+      className={previewClassName}
       style={{
         aspectRatio: getPreviewAspectRatio(primaryPreview),
       }}
diff --git a/src/index.css b/src/index.css
index 6e01a877e..0173569e9 100644
--- a/src/index.css
+++ b/src/index.css
@@ -3913,6 +3913,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   display: grid;
   width: 100%;
   min-height: 9.5rem;
+  max-height: 23rem;
   overflow: hidden;
   place-items: stretch;
   background: linear-gradient(180deg, #fffdfa, #fff4ea);
@@ -3933,6 +3934,18 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   object-position: center;
 }
 
+.creation-landing__asset-preview--campaign {
+  place-items: center;
+}
+
+.creation-landing__asset-preview--campaign .creation-landing__asset-preview-media {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
 .creation-landing__asset-preview--bundle {
   grid-template-columns: repeat(2, minmax(0, 1fr));
   align-items: stretch;

From 0c14e514191c76dcfc11aedbcf79213d803592f6 Mon Sep 17 00:00:00 2001
From: kvtodev <kvtodev@outlook.com>
Date: Tue, 7 Jul 2026 14:56:28 +0800
Subject: [PATCH 15/24] Editor agent paste image (#72)

![shotmd-1783397773.webp](/attachments/659f35ce-87c1-449d-8342-8afc09934da8)

---------

Co-authored-by: kdletters <kdletters@qq.com>
Reviewed-on: http://genarrative-station/git/GenarrativeAI/Genarrative/pulls/72
Reviewed-by: kdletters <kdletters@qq.com>
Co-authored-by: kvtodev <kvtodev@outlook.com>
Co-committed-by: kvtodev <kvtodev@outlook.com>
---
 package.json                                  |   3 +-
 .../EditorAgentConversationPanelView.test.tsx | 133 ++++++++++++++++--
 .../EditorAgentConversationPanelView.tsx      | 127 ++++++++++++++++-
 .../ImageCanvasEditorShellView.test.tsx       |   2 -
 .../image-editor/ImageCanvasEditorView.tsx    |   9 +-
 .../image-editor/ImageCanvasStageView.tsx     |   4 -
 .../ImageCanvasTaskSidebarView.test.tsx       |   8 +-
 .../ImageCanvasTaskSidebarView.tsx            |   4 +-
 .../ImageCanvasTopbarView.test.tsx            |   5 +-
 .../image-editor/ImageCanvasTopbarView.tsx    |   4 +-
 .../useImageCanvasContextStore.ts             |  14 ++
 11 files changed, 281 insertions(+), 32 deletions(-)
 create mode 100644 src/components/image-editor/useImageCanvasContextStore.ts

diff --git a/package.json b/package.json
index 87c2d3280..0136a88a0 100644
--- a/package.json
+++ b/package.json
@@ -150,7 +150,8 @@
     "react-native-safe-area-context": "^5.8.0",
     "react-native-webview": "^13.16.1",
     "three": "^0.184.0",
-    "vite": "^6.2.0"
+    "vite": "^6.2.0",
+    "zustand": "^5.0.14"
   },
   "devDependencies": {
     "@colbymchenry/codegraph": "^0.8.0",
diff --git a/src/components/image-editor/EditorAgentConversationPanelView.test.tsx b/src/components/image-editor/EditorAgentConversationPanelView.test.tsx
index c6b7dc8b1..30bf11244 100644
--- a/src/components/image-editor/EditorAgentConversationPanelView.test.tsx
+++ b/src/components/image-editor/EditorAgentConversationPanelView.test.tsx
@@ -8,11 +8,40 @@ import {
   waitFor,
   within,
 } from '@testing-library/react';
-import { describe, expect, it, vi } from 'vitest';
+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([
@@ -85,12 +114,33 @@ function createClient(): EditorAgentConversationClient {
 }
 
 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
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         client={client}
@@ -191,12 +241,84 @@ describe('EditorAgentConversationPanelView', () => {
     );
   });
 
+  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
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         client={client}
@@ -292,7 +414,6 @@ describe('EditorAgentConversationPanelView', () => {
 
     const { rerender } = render(
       <EditorAgentConversationPanelView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         client={client}
@@ -316,7 +437,6 @@ describe('EditorAgentConversationPanelView', () => {
 
     rerender(
       <EditorAgentConversationPanelView
-        projectId="project-1"
         open={false}
         onToggleOpen={vi.fn()}
         client={client}
@@ -326,7 +446,6 @@ describe('EditorAgentConversationPanelView', () => {
 
     rerender(
       <EditorAgentConversationPanelView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         client={client}
@@ -349,7 +468,6 @@ describe('EditorAgentConversationPanelView', () => {
     render(
       <div onWheel={parentWheel}>
         <EditorAgentConversationPanelView
-          projectId="project-1"
           open
           onToggleOpen={vi.fn()}
           client={client}
@@ -387,7 +505,6 @@ describe('EditorAgentConversationPanelView', () => {
     const client = createClient();
     render(
       <EditorAgentConversationPanelView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         client={client}
diff --git a/src/components/image-editor/EditorAgentConversationPanelView.tsx b/src/components/image-editor/EditorAgentConversationPanelView.tsx
index db719bbc6..665162fc8 100644
--- a/src/components/image-editor/EditorAgentConversationPanelView.tsx
+++ b/src/components/image-editor/EditorAgentConversationPanelView.tsx
@@ -11,6 +11,7 @@ import {
   X,
 } from 'lucide-react';
 import {
+  type ClipboardEvent as ReactClipboardEvent,
   type FormEvent,
   type WheelEvent as ReactWheelEvent,
   useEffect,
@@ -30,7 +31,11 @@ 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';
 import {
   type EditorAgentConversationClient,
   useEditorAgentConversation,
@@ -45,7 +50,6 @@ type EditorAgentAttachmentOption = {
 };
 
 type EditorAgentConversationPanelViewProps = {
-  projectId?: string | null;
   open: boolean;
   onToggleOpen: () => void;
   layers?: CanvasLayer[];
@@ -404,7 +408,6 @@ function AttachmentPickerModal({
 }
 
 export function EditorAgentConversationPanelView({
-  projectId,
   open,
   onToggleOpen,
   layers = [],
@@ -418,6 +421,9 @@ export function EditorAgentConversationPanelView({
       setHasConversationMounted(true);
     }
   }, [open]);
+  const projectId = useImageCanvasContextStore(
+    (state) => state.projectId,
+  );
   const effectiveProjectId = hasConversationMounted ? projectId : null;
   const {
     conversations,
@@ -448,6 +454,7 @@ export function EditorAgentConversationPanelView({
   const [attachmentPickerTab, setAttachmentPickerTab] =
     useState<AttachmentPickerTab>('canvas');
   const [attachmentError, setAttachmentError] = useState<string | null>(null);
+  const [isPastingAttachment, setIsPastingAttachment] = useState(false);
   const [draftAttachmentKeys, setDraftAttachmentKeys] = useState<Set<string>>(
     () => new Set(),
   );
@@ -510,6 +517,9 @@ export function EditorAgentConversationPanelView({
       stopCurrentTurn();
       return;
     }
+    if (isPastingAttachment) {
+      return;
+    }
     const text = draftText.trim();
     if (!text && !attachments.length) {
       return;
@@ -524,6 +534,113 @@ export function EditorAgentConversationPanelView({
       );
     });
   };
+  const appendAttachments = (nextAttachments: EditorAgentAttachmentRef[]) => {
+    function mergeAttachments(
+      currentAttachments: EditorAgentAttachmentRef[],
+      nextAttachments: EditorAgentAttachmentRef[],
+    ) {
+      const merged = [...currentAttachments];
+      const existingKeys = new Set(currentAttachments.map(attachmentKey));
+      nextAttachments.forEach((attachment) => {
+        const key = attachmentKey(attachment);
+        if (!existingKeys.has(key)) {
+          existingKeys.add(key);
+          merged.push(attachment);
+        }
+      });
+      return merged;
+    }
+    const mergedAttachments = mergeAttachments(attachments, nextAttachments);
+    if (mergedAttachments.length > EDITOR_AGENT_MAX_ATTACHMENTS) {
+      setAttachmentError(`最多 ${EDITOR_AGENT_MAX_ATTACHMENTS} 张`);
+      return false;
+    }
+    setAttachments(mergedAttachments);
+    setAttachmentError(null);
+    return true;
+  };
+
+  const createPastedAgentImageAttachment = async (
+    file: File,
+  ): Promise<EditorAgentAttachmentRef> => {
+    if (!projectId?.trim()) {
+      throw new Error('缺少画布项目');
+    }
+    const [upload, dimensions] = await Promise.all([
+      uploadEditorMediaAssetFile(file, 'image', {
+        pathSegments: ['editor', 'agent-paste', 'image', `${Date.now()}`],
+        entityId: projectId,
+        metadata: {
+          source: 'agent-input-paste',
+        },
+      }),
+      probeImageFileDimensions(file),
+    ]);
+    const width = dimensions?.width ?? 1;
+    const height = dimensions?.height ?? 1;
+    const resource = await createEditorProjectResource(projectId, {
+      imageSrc: upload.src,
+      objectKey: upload.objectKey,
+      assetObjectId: upload.assetObjectId,
+      width,
+      height,
+      sourceType: 'uploaded',
+    });
+    return {
+      source: 'canvas_resource',
+      referenceId: resource.resourceId,
+      objectKey: resource.objectKey ?? upload.objectKey,
+      imageSrc: resource.imageSrc,
+      thumbnailSrc: null,
+      label: resource.label ?? '粘贴图片',
+      width: resource.width,
+      height: resource.height,
+    };
+  };
+  function extractClipboardImageFiles(
+    clipboardData: DataTransfer | null,
+  ): File[] {
+    if (!clipboardData) {
+      return [];
+    }
+    const fileItems = Array.from(clipboardData.files ?? []).filter((file) =>
+      file.type.startsWith('image/'),
+    );
+    return [...fileItems];
+  }
+
+  const handleInputPaste = (event: ReactClipboardEvent<HTMLTextAreaElement>) => {
+    const imageFiles = extractClipboardImageFiles(event.clipboardData);
+    if (!imageFiles.length) {
+      return;
+    }
+
+    if (isPastingAttachment) {
+      return;
+    }
+
+    event.preventDefault();
+    if (attachments.length >= EDITOR_AGENT_MAX_ATTACHMENTS) {
+      setAttachmentError(`最多 ${EDITOR_AGENT_MAX_ATTACHMENTS} 张`);
+      return;
+    }
+
+    // TODO: deduplicate those existing assets
+    setIsPastingAttachment(true);
+    setAttachmentError('图片上传中');
+    void Promise.all(
+      imageFiles.map((file) => createPastedAgentImageAttachment(file)),
+    )
+      .then((pastedAttachments) => {
+        appendAttachments(pastedAttachments);
+      })
+      .catch(() => {
+        setAttachmentError('图片粘贴失败，请重试');
+      })
+      .finally(() => {
+        setIsPastingAttachment(false);
+      });
+  };
 
   const removeAttachment = (targetAttachment: EditorAgentAttachmentRef) => {
     const key = attachmentKey(targetAttachment);
@@ -654,6 +771,11 @@ export function EditorAgentConversationPanelView({
             {errorMessage}
           </div>
         ) : null}
+        {attachmentError ? (
+          <div className="mx-3 mb-2 rounded-2xl bg-amber-50 px-3 py-2 text-sm text-amber-700">
+            {attachmentError}
+          </div>
+        ) : null}
         <form
           className="border-t border-slate-200 bg-white/95 p-3"
           onSubmit={submitMessage}
@@ -684,6 +806,7 @@ export function EditorAgentConversationPanelView({
               value={draftText}
               rows={1}
               onChange={(event) => setDraftText(event.currentTarget.value)}
+              onPaste={handleInputPaste}
               onKeyDown={(event) => {
                 if (event.key === 'Enter' && !event.shiftKey) {
                   event.preventDefault();
diff --git a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
index dc5fa045a..bbfb494b6 100644
--- a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
@@ -93,7 +93,6 @@ function createSidebarProps(): ImageCanvasSidebarViewProps {
 
 function createTopbarProps(): ImageCanvasTopbarViewProps {
   return {
-    projectId: 'project-1',
     projectTitle: '默认项目',
     projectRenameValue: '默认项目',
     isRenamingProject: false,
@@ -119,7 +118,6 @@ function createTopbarProps(): ImageCanvasTopbarViewProps {
 
 function createStageProps(): ImageCanvasStageViewProps {
   return {
-    projectId: 'project-1',
     canvasViewportRef: createRef<HTMLDivElement>(),
     specToolWrapRef: createRef<HTMLSpanElement>(),
     musicToolWrapRef: createRef<HTMLSpanElement>(),
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index 8f96c6ef3..10ae75459 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -82,6 +82,7 @@ import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
 import { useImageCanvasGenerationSurface } from './useImageCanvasGenerationSurface';
 import { useImageCanvasKeyboardShortcuts } from './useImageCanvasKeyboardShortcuts';
 import { useImageCanvasLayerCommands } from './useImageCanvasLayerCommands';
+import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
 import { useImageCanvasProjectPersistence } from './useImageCanvasProjectPersistence';
 import { useImageCanvasStageController } from './useImageCanvasStageController';
 import { useImageCanvasStageInteractions } from './useImageCanvasStageInteractions';
@@ -1035,6 +1036,12 @@ export function ImageCanvasEditorView({
     openEditorLoginModal,
     onProjectAccessLost,
   });
+  const setEditorProjectContextId = useImageCanvasContextStore(
+    (state) => state.setProjectId,
+  );
+  useEffect(() => {
+    setEditorProjectContextId(projectId);
+  }, [projectId, setEditorProjectContextId]);
   const applyGeneratedProjectSnapshot = useCallback(
     (project: EditorProjectSnapshot) => {
       applyProjectSnapshot(project);
@@ -1906,7 +1913,6 @@ export function ImageCanvasEditorView({
     getCanvasPointFromClient,
   };
   const topbarProps = {
-    projectId,
     projectTitle,
     projectRenameValue,
     isRenamingProject,
@@ -1935,7 +1941,6 @@ export function ImageCanvasEditorView({
     },
   };
   const stageProps = {
-    projectId,
     canvasViewportRef,
     specToolWrapRef,
     musicToolWrapRef,
diff --git a/src/components/image-editor/ImageCanvasStageView.tsx b/src/components/image-editor/ImageCanvasStageView.tsx
index 68ba896b0..3867fb717 100644
--- a/src/components/image-editor/ImageCanvasStageView.tsx
+++ b/src/components/image-editor/ImageCanvasStageView.tsx
@@ -41,7 +41,6 @@ import { ImageCanvasUiAssetExtractionOverlayView } from './ImageCanvasUiAssetExt
 import { ImageCanvasWorldView } from './ImageCanvasWorldView';
 
 export type ImageCanvasStageViewProps = {
-  projectId?: string | null;
   canvasViewportRef: RefObject<HTMLDivElement | null>;
   specToolWrapRef: RefObject<HTMLSpanElement | null>;
   musicToolWrapRef: RefObject<HTMLSpanElement | null>;
@@ -192,7 +191,6 @@ export type ImageCanvasStageViewProps = {
 };
 
 export function ImageCanvasStageView({
-  projectId,
   canvasViewportRef,
   specToolWrapRef,
   musicToolWrapRef,
@@ -463,7 +461,6 @@ export function ImageCanvasStageView({
       />
 
       <ImageCanvasTaskSidebarView
-        projectId={projectId}
         refreshKey={taskListRefreshKey}
         open={isTaskSidebarOpen}
         onToggleOpen={onToggleTaskSidebar}
@@ -472,7 +469,6 @@ export function ImageCanvasStageView({
 
       {isAgentConversationEnabled ? (
         <EditorAgentConversationPanelView
-          projectId={projectId}
           open={isAgentConversationOpen}
           onToggleOpen={onToggleAgentConversation}
           layers={layers}
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
index e3ffc43e5..41fed163c 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
@@ -6,6 +6,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
 import { listExternalGenerationTasks } from '../../services/external-generation';
 import { ImageCanvasTaskSidebarView } from './ImageCanvasTaskSidebarView';
+import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
 
 vi.mock('../../services/external-generation', () => ({
   listExternalGenerationTasks: vi.fn().mockResolvedValue({
@@ -22,6 +23,7 @@ vi.mock('../../services/external-generation', () => ({
 const listExternalGenerationTasksMock = vi.mocked(listExternalGenerationTasks);
 
 beforeEach(() => {
+  useImageCanvasContextStore.getState().setProjectId('project-1');
   listExternalGenerationTasksMock.mockClear();
   listExternalGenerationTasksMock.mockResolvedValue({
     overview: {
@@ -115,7 +117,6 @@ describe('ImageCanvasTaskSidebarView', () => {
     render(
       <div onWheel={parentWheel}>
         <ImageCanvasTaskSidebarView
-          projectId="project-1"
           open
           onToggleOpen={vi.fn()}
           onFocusExternalTask={focusExternalTask}
@@ -230,7 +231,6 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     render(
       <ImageCanvasTaskSidebarView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         onFocusExternalTask={vi.fn()}
@@ -287,7 +287,6 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     render(
       <ImageCanvasTaskSidebarView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         onFocusExternalTask={vi.fn()}
@@ -325,7 +324,6 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     const { rerender } = render(
       <ImageCanvasTaskSidebarView
-        projectId="project-1"
         refreshKey={0}
         open
         onToggleOpen={vi.fn()}
@@ -347,7 +345,6 @@ describe('ImageCanvasTaskSidebarView', () => {
     ];
     rerender(
       <ImageCanvasTaskSidebarView
-        projectId="project-1"
         refreshKey={1}
         open
         onToggleOpen={vi.fn()}
@@ -388,7 +385,6 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     render(
       <ImageCanvasTaskSidebarView
-        projectId="project-1"
         open
         onToggleOpen={vi.fn()}
         onFocusExternalTask={vi.fn()}
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
index 08228595f..a63b12682 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
@@ -19,6 +19,7 @@ import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/
 import { listExternalGenerationTasks } from '../../services/external-generation';
 import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import type { CanvasTaskStatus } from './ImageCanvasEditorTypes';
+import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
 
 const COMPLETED_TASK_LIST_LIMIT = 20;
 const COMPLETED_TASK_LIST_MAX_LIMIT = 100;
@@ -42,7 +43,6 @@ type TaskSidebarItem = {
 };
 
 type ImageCanvasTaskSidebarViewProps = {
-  projectId?: string | null;
   refreshKey?: number;
   open: boolean;
   onToggleOpen: () => void;
@@ -252,12 +252,12 @@ function trimStoredExternalTasks(
 }
 
 export function ImageCanvasTaskSidebarView({
-  projectId,
   refreshKey = 0,
   open,
   onToggleOpen,
   onFocusExternalTask,
 }: ImageCanvasTaskSidebarViewProps) {
+  const projectId = useImageCanvasContextStore((state) => state.projectId);
   const normalizedProjectId = projectId?.trim() ?? '';
   const [activeTab, setActiveTab] = useState<TaskSidebarTab>('active');
   const [now, setNow] = useState(() => Date.now());
diff --git a/src/components/image-editor/ImageCanvasTopbarView.test.tsx b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
index b9f2c584b..ba0c69689 100644
--- a/src/components/image-editor/ImageCanvasTopbarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
@@ -5,6 +5,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { CanvasLayer } from './ImageCanvasEditorTypes';
 import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
+import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
 
 function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
   const id = overrides.id ?? 'layer-a';
@@ -30,8 +31,8 @@ function renderTopbar(
     Parameters<typeof ImageCanvasTopbarView>[0]
   > = {},
 ) {
+  useImageCanvasContextStore.getState().setProjectId('project-a');
   const props: Parameters<typeof ImageCanvasTopbarView>[0] = {
-    projectId: 'project-a',
     projectTitle: '默认项目',
     projectRenameValue: '默认项目',
     isRenamingProject: false,
@@ -144,7 +145,6 @@ describe('ImageCanvasTopbarView', () => {
     const exportCanvasAssets = vi.fn();
     const { rerender } = render(
       <ImageCanvasTopbarView
-        projectId="project-a"
         projectTitle="默认项目"
         projectRenameValue="默认项目"
         isRenamingProject={false}
@@ -175,7 +175,6 @@ describe('ImageCanvasTopbarView', () => {
 
     rerender(
       <ImageCanvasTopbarView
-        projectId="project-a"
         projectTitle="默认项目"
         projectRenameValue="默认项目"
         isRenamingProject={false}
diff --git a/src/components/image-editor/ImageCanvasTopbarView.tsx b/src/components/image-editor/ImageCanvasTopbarView.tsx
index f1b10df33..d1698c9ce 100644
--- a/src/components/image-editor/ImageCanvasTopbarView.tsx
+++ b/src/components/image-editor/ImageCanvasTopbarView.tsx
@@ -12,9 +12,9 @@ import { PlatformTextField } from '../common/PlatformTextField';
 import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import type { CanvasLayer } from './ImageCanvasEditorTypes';
 import type { AssetExportStatus } from './useImageCanvasAssetExportWorkflow';
+import { useImageCanvasContextStore } from './useImageCanvasContextStore.ts';
 
 export type ImageCanvasTopbarViewProps = {
-  projectId: string | null;
   projectTitle: string;
   projectRenameValue: string;
   isRenamingProject: boolean;
@@ -57,7 +57,6 @@ function buildCanvasUserCode(
 }
 
 export function ImageCanvasTopbarView({
-  projectId,
   projectTitle,
   projectRenameValue,
   isRenamingProject,
@@ -79,6 +78,7 @@ export function ImageCanvasTopbarView({
   onOpenWallet,
   onOpenAccount,
 }: ImageCanvasTopbarViewProps) {
+  const projectId = useImageCanvasContextStore((state) => state.projectId);
   const hasExportableLayer = layers.some(
     (layer) => layer.src.trim().length > 0,
   );
diff --git a/src/components/image-editor/useImageCanvasContextStore.ts b/src/components/image-editor/useImageCanvasContextStore.ts
new file mode 100644
index 000000000..0869656f5
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasContextStore.ts
@@ -0,0 +1,14 @@
+import { create } from 'zustand';
+
+type ImageCanvasContextState = {
+  projectId: string | null;
+  setProjectId: (projectId?: string | null) => void;
+};
+
+export const useImageCanvasContextStore =
+  create<ImageCanvasContextState>((set) => ({
+    projectId: null,
+    setProjectId: (projectId) => {
+      set({ projectId: projectId?.trim() || null });
+    },
+  }));

From 308d4408169abff2fa81713c189d1d9fc580dd08 Mon Sep 17 00:00:00 2001
From: Linghong <ink29535@proton.me>
Date: Tue, 7 Jul 2026 14:57:10 +0800
Subject: [PATCH 16/24] =?UTF-8?q?=E6=96=B0=E6=8A=A0=E5=9B=BE=E7=AE=97?=
 =?UTF-8?q?=E6=B3=95=EF=BC=88=E8=BD=BB=E9=87=8F=E7=89=88=EF=BC=89=E4=B8=8A?=
 =?UTF-8?q?=E7=BA=BF=20(#73)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新抠图算法（轻量版）上线，生图背景色同步改为多颜色+自动决策

---------

Co-authored-by: kdletters <kdletters@qq.com>
Reviewed-on: http://genarrative-station/git/GenarrativeAI/Genarrative/pulls/73
Reviewed-by: kdletters <kdletters@qq.com>
Co-authored-by: Linghong <ink29535@proton.me>
Co-committed-by: Linghong <ink29535@proton.me>
---
 .claude/settings.local.json                   |   4 +-
 .../shared-memory/decision-log.md             |  34 +-
 ...架构】图片画布编辑器MVP接入方案-2026-06-11.md |  14 +-
 ...�】server-rs与SpacetimeDB数据契约-2026-05-15.md |   1 +
 ...��】生成类面板Lovart统一改造方案-2026-06-17.md |   2 +-
 ...辑器】画板UI设计图生成入口设计-2026-06-17.md |   7 +-
 ...辑器】画板图标素材生成入口设计-2026-06-15.md |   5 +-
 ...辑器】画板角色形象生成入口设计-2026-06-15.md |  15 +-
 .../src/character_animation_assets.rs         |  18 +-
 server-rs/crates/api-server/src/config.rs     |  86 ++-
 .../crates/api-server/src/editor_agent.rs     |   4 +
 .../api-server/src/editor_green_screen.rs     | 222 ++++++-
 .../crates/api-server/src/editor_project.rs   | 543 ++++++++++++++++--
 .../src/editor_screen_background_decision.rs  | 339 +++++++++++
 server-rs/crates/api-server/src/main.rs       |   1 +
 ...CanvasEditorGenerationIntegration.test.tsx | 525 +++++++++--------
 .../ImageCanvasGenerationDialogModel.test.ts  |  20 +-
 .../ImageCanvasGenerationDialogModel.ts       |   1 +
 ...eCanvasGenerationImageOptionsView.test.tsx |   4 +-
 .../ImageCanvasGenerationModel.test.ts        |   6 +-
 .../ImageCanvasGenerationModel.ts             |  14 +-
 ...ageCanvasGenerationSubmissionModel.test.ts |   8 +-
 .../ImageCanvasGenerationSubmissionModel.ts   |  24 +-
 .../ImageCanvasUiAssetExtractionModel.ts      |   5 +-
 ...anvasUiAssetExtractionOverlayView.test.tsx |   6 +
 ...anvasGenerationSubmissionWorkflow.test.tsx |  24 +-
 ...ImageCanvasGenerationSubmissionWorkflow.ts |   6 +
 src/index.css                                 |  71 ++-
 .../image-editor/editorProjectClient.test.ts  |  16 +-
 .../image-editor/editorProjectClient.ts       |  12 +
 30 files changed, 1650 insertions(+), 387 deletions(-)
 create mode 100644 server-rs/crates/api-server/src/editor_screen_background_decision.rs

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 31b5b2e81..6836e781f 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -9,7 +9,9 @@
       "Bash(findstr LISTENING)",
       "Bash(npx tsc:*)",
       "Bash(lsof -ti:8081)",
-      "Bash(curl -s http://localhost:8081/health)"
+      "Bash(curl -s http://localhost:8081/health)",
+      "Skill(code-review)",
+      "Skill(code-review:*)"
     ]
   }
 }
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 1ad4a8b7d..da6a33eae 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,6 +16,38 @@
 
 ---
 
+## 2026-07-02 图片画布生成抠图背景色使用 screenColor 传递
+
+- 背景：画布角色、图标和 UI 素材生成过去固定要求 `#00FF00` 绿幕，后续 BGfilter 服务需要按生成时背景色做去背景，不能继续把背景色写死在 prompt 或后处理里。
+- 决策：角色形象、图标 spritesheet 和 UI 设计图素材提取不再向用户提供手动抠图背景色选择；前端用户路径统一提交 `screenColor=auto`，但用户可见生成输入快照不再写入 `抠图背景色` 或 `抠图模型`。api-server 在 11 个候选色中自动决策具体 hex，失败后兜底 `#CFEFFF`；最终 prompt 和 BgFilter 去背景只接收解析后的具体 hex 作为 `screen_color`。后端仍保留手动 hex 解析能力供内部兼容，角色动作抽帧暂不接入该选择，继续使用 legacy `#00FF00` 绿幕。
+- 影响范围：`/editor/canvas` 角色形象生成、图标素材生成、UI 设计图素材提取、BgFilter 服务入参、图片画布 MVP 和角色形象生成设计文档。
+- 验证方式：运行画布生成模型 / workflow / API client 定向前端测试、`cargo test -p api-server editor_green_screen --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image generated_asset_sheet_light_blue_key_color_removes_selected_background --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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## 2026-07-05 图片画布抠图背景色自动决策
+
+- 背景：手动背景色选择对用户负担较高，且不同角色、图标和 UI 素材主题需要避开不同主体色；但 BgFilter 和生成 prompt 仍必须拿到明确的纯色 hex。
+- 决策：前端用户路径直接固定通过 `screenColor=auto` 提交，不再展示背景色选项；api-server 新增 `editor_screen_background_decision` 模块，在角色形象、图标 spritesheet 和 UI 设计图素材提取组装 prompt 前解析 `screenColor`。手动 hex 直接校验并使用；`auto` 通过服务端 LLM 在 11 个候选色中选择具体 hex，最多重试 3 次，LLM 未配置、请求失败或返回非法颜色时 fallback 到 `浅雾蓝 #CFEFFF`。自动解析结果不写入用户可见生成输入快照；最终生图 prompt 和 BgFilter `screen_color` 永远只接收具体 hex，不透传 `auto`。
+- 影响范围：`/editor/canvas` 角色形象生成、图标素材生成、UI 设计图素材提取、api-server LLM 调用、BgFilter 参数、图片画布文档。
+- 验证方式：运行背景决策模块单测、画布生成模型 / workflow / API client 定向前端测试、`cargo test -p api-server editor_screen_background_decision editor_green_screen --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`、`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
+
+## 2026-07-05 BgFilter 失败时本地纯色去背兜底
+
+- 背景：曾用一次性 BgFilter live probe 稳定复现 BgFilter 对 2K 输入返回 `HTTP 500 {"detail":"inference failed"}`，浏览器生成链路会因此收到“BgFilter 服务返回非成功状态”。
+- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取仍优先调用独立 BgFilter；若 BgFilter 请求失败、返回非成功状态、返回空图片或非法图片，api-server 记录 warning 后使用本地 `editor_green_screen` 按解析后的纯色背景执行确定性去背兜底，不中断生成。手动任意图片去背景仍只走独立 BiRefNet BFF，不使用该兜底。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、BgFilter 运维排障、图片画布生成后处理。
+- 验证方式：运行 `cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess editor_green_screen --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`、`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
+
+## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
+
+- 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
+- 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和 `seg_model=<segModel>`，前端用户路径固定提交 `segModel=birefnet` 且不展示抠图模型选择；`anime-seg` 路径保留为后端可识别的内部能力但不对用户可见。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，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` 兜底。角色动作抽帧仍保留 legacy `#00FF00` 与本地 `editor_green_screen` 透明化。
+- 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
+- 验证方式：运行 `cargo test -p api-server config::tests::from_env_reads_editor_bgfilter_settings_and_reuses_background_token editor_project::tests::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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
 ## 2026-07-03 作品公开默认关闭
 
 - 背景：作品发布完成不应默认进入公开广场 / 公开详情 / 公开互动消费路径，需要先由后台可见性开关明确开启。
@@ -196,7 +228,7 @@
 ## 2026-06-18 图片画布 UI 设计图提取素材保留图集
 
 - 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
-- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和提示词 `仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。`，返回结构复用图标 spritesheet 响应。UI 提取把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材；图标素材生成只保留扣绿后的 spritesheet 图集，不再额外铺独立图标。
+- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。UI 提取把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材；图标素材生成只保留透明 spritesheet 图集，不再额外铺独立图标。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。
 - 影响范围：图片画布浮动工具栏、编辑器图片生成 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`。
diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
index f57be0e19..a3d14d34b 100644
--- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
+++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
@@ -20,8 +20,8 @@
 - 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层、生成占位框或画板的边缘与中心线；当移动元素接近两个同轴元素形成的等距位置时，支持横向或纵向等距吸附。
 - 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 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`，并在两类面板之间沿用用户上次选择的模型。`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；编辑器自己生成的标准绿幕资产统一走 `server-rs/crates/api-server/src/editor_green_screen.rs` 的绿幕提示词契约和本地确定性绿幕透明化，字节级解码、透明化和 PNG 编码下沉复用 `platform-image::generated_asset_sheets`。角色形象生成、图标 spritesheet 生成、UI 设计图素材提取和角色动作抽帧后的序列帧都属于标准绿幕资产，不再依赖 BiRefNet；后端在执行绿幕透明化前必须先把带绿幕源图写入 OSS。BiRefNet 服务地址为 `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，再返回 `imageSrc/objectKey/assetObjectId/taskId`；queue 模式下手动去背景进入 SpacetimeDB 外部生成队列，画布任务侧栏只展示服务器任务阶段，生成中才显示耗时，不显示百分比；有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。
+- 图片生成 / 修改统一经 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`。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 11 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt 和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。三条 BgFilter 路径还必须固定把默认 `segModel=birefnet` 传为 `seg_model`；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交该值。这里的 `birefnet` 只是 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。后端在调用 BgFilter 前必须先把带纯色背景 / 绿幕源图写入 OSS；若 BgFilter 请求失败、返回非成功状态、空图片或非法图片，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作抽帧后的序列帧暂不接用户背景色选择，仍沿用 legacy `#00FF00` 绿幕和本地 `editor_green_screen` 透明化，不依赖 BiRefNet 或 BgFilter。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` 交给后端，完成后由后端写入结果图层和最新项目快照。
 - 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并显示错误。
 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。
 - 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。
@@ -53,7 +53,7 @@
 - 项目封面图是画布当前视口栅格化后的静态快照资源，不在项目列表页临时重放 `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 需要走修复上传并回写轻量引用。上传到生成面板参考图槽位的图片必须先创建 `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`；宣发素材生成器还必须保存并恢复 `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`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。
+- 资源表保存资源和素材级元数据；图层位置、层级、分组选中所需 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` 时完成。`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画布图片、改图、图标素材、UI 素材提取、角色动作、视频、音效和背景音乐生成都先返回 `queueState`，前端轮询 `/api/runtime/external-generation/jobs/{jobId}` 到完成后重新读取项目快照；`inline` 或无项目上下文时才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。生成请求失败、inline 完成或 queue 任务终态完成 / 失败后，右上角泥点 chip 必须通过 `/profile/dashboard` 回读余额，不做本地乐观扣减。生成视频会单独抽取首帧封面并写入 `thumbnailSrc`，素材栏和拖回画布时沿用该封面作为 poster。
 - 画布 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 消息附件只允许引用当前工程画布资源或账号素材库图片，来源类型为 `canvas_resource` / `library_asset`，最多 9 张。附件请求可携带展示用 `imageSrc/thumbnailSrc/objectKey/width/height/label`，但持久化真相仍以后端校验后的 resource / asset 行和 OSS 对象为准；不得把 Data URL、signed URL 或 blob URL 当作会话长期事实。
@@ -83,10 +83,10 @@
 - `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 生成图片；角色生成可携带 `model`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`，生成成功后 api-server 先保存带绿幕源图，再走 `editor_green_screen` 绿幕透明化后处理。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成成功后创建 project resource / 账号素材并在响应中返回 resource / asset 快照。
+- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片；角色生成可携带 `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。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `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 源图，再走 `editor_green_screen` 绿幕透明化后处理，并由后端切分为独立透明图标。请求支持 `model`、`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 和拆分后的 icon 都保存为 project resource / 账号素材，并随响应返回对应快照。
-- `POST /api/editor/ui-designs/assets/extractions`：以前端已绘入红色框选轮廓的 UI 设计图 Data URL 作为参考图，固定 `gpt-image-2` 和 `editor_green_screen` 组装的标准绿幕素材提取提示词生成素材 spritesheet，生成成功后 api-server 先保存带绿幕 spritesheet 源图，再走 `editor_green_screen` 绿幕透明化后处理，并按连通域自动拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `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/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`：以前端已绘入红色框选轮廓的 UI 设计图 Data 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`：按提示词和当前图片 Data URL 调用 VectorEngine edits，返回新的生成图片元数据；接口能力仍可接收明确参考图，但图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。请求携带 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`。
@@ -126,7 +126,7 @@
 - 发送消息后，面板展示用户消息、Agent 阶段状态和 SSE 增量回复；`stage/message_delta/tool_started/tool_completed/generation_result/error/done` 都能被正确渲染。流式响应中点击“停止”会中断当前请求，并把仍在 streaming / generating 的消息标记为停止态。
 - Agent 返回生成结果缩略图后，点击缩略图应优先聚焦当前画布中已有 `resourceId` 对应图层；如果当前内存布局尚未包含该资源，则重新读取工程快照，应用后再聚焦新图层。对话入口触发生成时不创建“即将生成”画布占位；生成中状态只显示在消息流，生成完成后通过后端 `canvasCompletion` 落新图层。工具失败时消息内必须保留失败 generation record 和错误气泡，不能只弹一次性 toast。
 - 画布 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，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。`，生成的 spritesheet 原图和拆分后的独立素材都作为画布图层保留。
+- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、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 原图和拆分后的独立素材都作为画布图层保留。
 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。
 - 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，前端先读取成 `data:image/*;base64,...` 再提交，后端不得再收到 `/creation-type-references/*`、`/generated-*` 或 OSS URL 作为 `referenceImageSrcs/sourceImageSrc`。
 - 快速编辑不保留额外参考图入口；点击修改时只把原图或红框序号标注图作为 `/api/editor/images/edits` 的 `sourceImageSrc` 提交给后端。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index c85477a89..03054635e 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -218,6 +218,7 @@ npm run check:server-rs-ddd
 
 - 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`，token 未配置时复用 BiRefNet token。BgFilter 请求必须显式传 `screen_color=<screenColor>` 和 `seg_model=<segModel>`；前端用户路径不展示抠图模型选择并固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，其中 `birefnet` 只表示 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。角色动作抽帧仍沿用 legacy `#00FF00` 和本地 `editor_green_screen` 透明化。
 - 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/` 时生成失败。
diff --git a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
index c77a9d1b5..1df4cf1d9 100644
--- a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
+++ b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
@@ -185,7 +185,7 @@
 - 生成视频 / 角色形象 / 角色动作 / 音效 / 背景音乐新建后，画布占位空白样式和右上角标签均与对应生成类型一致，不再统一使用图片占位 icon。
 - 新建空白待生成占位的尺寸必须和面板参数一致；图片类修改比例 / 尺寸、视频修改清晰度后，画布空白占位同步变更且保持中心点。
 - 点击角色图只选中图层并显示工具栏，不自动弹出重绘、快速编辑或角色动画面板；点击工具栏或右键菜单中的 `生成动画` 才创建角色动作占位和面板。
-- 点击 UI 设计图只选中图层并显示工具栏；工具栏在 `去除背景按钮` 后显示 `提取素材`，点击后画布自动缩放平移到素材完整展示，并在素材下方显示 UI 素材提取面板。UI 素材提取默认启用矩形框选，右侧工具栏与快速编辑统一，当前启用工具按钮保持高亮，点击同一工具可取消启用态；面板提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选截图预览、固定模型 `gpt-image-2`、计划规格和提取按钮泥点，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。用户至少框选一个区域后才能点击 `提取`，前端把红色轮廓绘入原图作为参考图，再固定用提示词 `仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板或绿色阴影。` 生成 spritesheet。框选数量不超过阈值时提交 `1:1·1K` 参数，超过阈值时提交 `1:1·2K` 参数；后端按 gpt-image-2 对应尺寸计算扣费，后续复用图标素材拆分流程，把 spritesheet 图集和拆分素材都放到画布。
+- 点击 UI 设计图只选中图层并显示工具栏；工具栏在 `去除背景按钮` 后显示 `提取素材`，点击后画布自动缩放平移到素材完整展示，并在素材下方显示 UI 素材提取面板。UI 素材提取默认启用矩形框选，右侧工具栏与快速编辑统一，当前启用工具按钮保持高亮，点击同一工具可取消启用态；面板提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选截图预览、固定模型 `gpt-image-2`、计划规格和提取按钮泥点，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。用户至少框选一个区域后才能点击 `提取`，前端把红色轮廓绘入原图作为参考图，再固定用自动决策纯色背景素材提取提示词生成 spritesheet。框选数量不超过阈值时提交 `1:1·1K` 参数，超过阈值时提交 `1:1·2K` 参数；后端按 gpt-image-2 对应尺寸计算扣费，保存纯色背景源图后调用 BgFilter 按默认抠图模型 `birefnet` 透明化，并复用图标素材拆分流程，把透明 spritesheet 图集和拆分素材都放到画布。
 - 生成游戏音效面板底部不显示字段标题，左下角只有一个时长参数按钮，选项为 Vidu duration `2-10` 秒；右下角固定模型胶囊显示 `Vidu` 并紧贴生成按钮。
 - 生成游戏背景音乐面板右下角固定模型胶囊显示 `Suno` 并紧贴生成按钮；`make_instrumental` 不在 UI 中展示。
 - 生成视频结果以视频图层加入画布，画布媒体元素标记为 `画布视频：生成视频 N`。
diff --git a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
index a3d776835..84a4f9de7 100644
--- a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
+++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
@@ -28,6 +28,7 @@
 - 支持自定义画面比例和大小尺寸。
 - 模型固定为 `gpt-image-2`，模型展示对齐角色规范面板底部固定模型样式，不响应点击、不弹出模型切换菜单；历史草稿如果残留其他模型，提交时也必须强制改为 `gpt-image-2`。
 - 默认画面比例为 `16:9`，默认大小为 `1K`。
+- UI 素材提取面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端先在 11 个候选色中自动决策具体 hex，最多重试 3 次，失败兜底 `#CFEFFF`；后端调用 BgFilter 时只把解析后的具体 hex 作为 `screen_color` 传入。后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
 
 ## 提示词契约
 
@@ -57,10 +58,10 @@
 - 后端固定使用 `gpt-image-2` 图片编辑链路，并固定提示词：
 
 ```text
-仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。
+仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用后端自动决策出的抠图背景色。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。
 ```
 
-- 后端收到 spritesheet 后先把带绿幕源图写入 OSS，再走 `server-rs/crates/api-server/src/editor_green_screen.rs` 的统一绿幕透明化方法，并复用图标素材的连通域拆分能力；未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`。
+- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 按默认 `segModel=birefnet` 透明化，并复用图标素材的连通域拆分能力；未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`。
 - 前端先把 spritesheet 原图作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分出的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布。
 
 ## 验收点
@@ -70,5 +71,5 @@
 - 从画布选择时只能绑定图标规范图片。
 - 请求参数包含 `kind: "ui-design"`、`model: "gpt-image-2"`、比例、大小与可选参考图。
 - 上传普通参考图后，请求参考图数组同时包含图标规范和普通参考图，生成图层信息面板展示 `用户输入`、`图标规范` 与普通参考图。
-- 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后进入红框素材框选状态，至少框选一个区域后才能调用固定 `gpt-image-2` 提取接口，画布同时出现 spritesheet 图集和拆分后的独立素材。
+- 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后进入红框素材框选状态，至少框选一个区域后才能调用固定 `gpt-image-2` 提取接口，请求包含 `screenColor`，画布同时出现透明 spritesheet 图集和拆分后的独立素材。
 - UI 素材提取面板上传普通参考图后，提取请求参考图数组同时包含红框 UI 设计图和普通参考图，生成图层信息面板展示 `UI设计图` 与普通参考图。
diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
index cd32420d3..84a19ac5e 100644
--- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
@@ -47,17 +47,18 @@
   - `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`。
 - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
+- 不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。后端在组装 prompt 前把 `auto` 自动决策为具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`，最终 prompt 和 BgFilter 不透传 `auto`。
 - Prompt 固定为：
 
 ```text
-参考图1的图标规范，背景必须是单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，且平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光；禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：
+参考图1的图标规范，背景必须是自动决策出的单一纯色抠图背景，且平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光；禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：
 
 <素材描述按中文顿号拼接>
 ```
 
 ## 去背与保存
 
-- 后端收到 spritesheet 后先把带绿幕源图写入 OSS，再走 `server-rs/crates/api-server/src/editor_green_screen.rs` 的统一绿幕透明化方法，底层复用 `platform-image::generated_asset_sheets`。
+- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 透明化；请求字段包含 `screenColor` 和 `segModel`，前端用户路径固定提交 `screenColor=auto` 与默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
 - 去背后的整张 spritesheet 统一编码为透明 PNG，并作为唯一图标素材产物持久化。
 - 响应保留 `iconImageSrcs` 字段用于兼容旧客户端，但图标素材生成固定返回空数组；UI 设计图提取素材仍可复用该响应结构返回切片素材。
 
diff --git a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
index 08134d4bf..d55d5a2c2 100644
--- a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
@@ -29,7 +29,7 @@
    - 上传后的每张常规参考图以缩略图展示。
    - 每张常规参考图右下角显示大号序号，从 `1` 开始递增。
 3. 唯一文本框为 `角色设定`。
-4. 左下角展示画面比例和大小选择按钮。
+4. 左下角只展示画面比例和大小，不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`。
 5. 右下角展示模型选择和生成按钮。
 
 ## 普通生成面板视觉口径
@@ -49,9 +49,10 @@
 - 角色规范与常规参考图作为 `referenceImageSrcs` 传入，顺序固定为：
   1. 角色规范图。
   2. 常规参考图列表。
-- 请求同时提交 `model`、`aspectRatio` 和 `imageSize`：
+- 请求同时提交 `model`、`screenColor`、`segModel`、`aspectRatio` 和 `imageSize`：
   - `model` 支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
   - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
+  - 前端用户路径固定提交 `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"`。
@@ -60,11 +61,11 @@
 - `kind = "character"` 时，后端不直接把前端文本当完整生图提示词，而是把文本作为 `角色设定` 填入固定提示词骨架：
 
 ```text
-基于图1的角色美术视觉规范指导生成游戏角色形象图。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色；绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带绿色描边、绿色投影或绿色反光；禁止生成美术视觉规范、出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
+按照角色描述生成游戏角色立绘。严格基于图1的角色美术视觉规范的美术风格、角色头身比、角色朝向等特征。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯色背景 <颜色名> <hex> / RGB(<r>,<g>,<b>)，只作为抠像底色；纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带与背景色相同或相近的描边、投影或反光；禁止生成美术视觉规范，禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
 角色设定：<用户输入的角色设定>
 ```
 
-- 角色图生成完成后，编辑器后端必须先把带绿幕源图写入 OSS，再走 `server-rs/crates/api-server/src/editor_green_screen.rs` 的统一绿幕透明化方法：复用 `platform-image::generated_asset_sheets` 的绿幕 / 近白背景去背能力，并开启内部绿幕 / 近白镂空检测。角色图 prompt 固定要求标准 `#00FF00 / RGB(0,255,0)` 绿幕；后端路径仍兼容生成模型把标准绿幕压成暗绿 / 灰绿背景的情况，但这类宽松识别只用于从画布边缘连通扩散出的背景，不作为全图断开绿色区域删除依据。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理，也不调用远端 BiRefNet；输出仍统一为透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`。接口回包仍返回透明 PNG Data URL 供画板立即显示，同时返回 `objectKey` / `assetObjectId`，前端创建图层和画板资源记录时必须保存这两个字段。
+- 角色图生成完成后，编辑器后端必须先把带自动决策纯色背景的源图写入 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"`。
 
 ## 生成规范参考图
@@ -102,7 +103,7 @@
 - `角色规范` 与 `上传常规参考图` 入口是带预览视觉块的参考图卡片，不是无样式文字。
 - `从画布中选择` 后点击已有画布图片可绑定为角色规范，`Esc` 可退出点选状态。
 - 上传常规参考图后缩略图右下角显示序号。
-- 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`aspectRatio` 和 `imageSize`。
+- 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`screenColor`、`aspectRatio` 和 `imageSize`。
 - 默认打开角色生成面板时选中 `nanobanana2 / 1:1 / 1K`；切换到 `gpt-image-2` 后再次打开角色或图标素材面板应沿用该模型。
 - 生成成功后在占位图位置创建 `assetKind: "character"` 图层，右上角显示 `角色` 标签，布局保存包含该字段。
 
@@ -113,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 骨架补入 `角色设定`，并在生成成功后通过编辑器通用抠图方法执行绿幕 / 近白背景去背和内部镂空清理、写入 `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 私有对象，返回的 `objectKey` / `assetObjectId` 会随画板资源记录保存。
 - `Esc` 只退出角色规范画布点选状态，不关闭角色生成面板。
 - 已补充回归测试覆盖角色形象生成、点选退出、角色动画入口隔离和快速编辑入口。
 - 本次验证命令：
@@ -161,7 +162,7 @@
 
 - 视频生成完成后，后端按面板选择抽取对应帧数：`32`、`40` 或 `48`。
 - 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。
-- 每帧必须先把带绿幕源图写入 OSS，再执行 `editor_green_screen` 统一绿幕去背，输出透明背景 PNG。
+- 每帧必须先把带 legacy `#00FF00` 绿幕源图写入 OSS，再执行 `editor_green_screen` 统一绿幕去背，输出透明背景 PNG。角色动作暂不接入角色 / 图标生图的 `screenColor` 选择。
 - 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
 - 画板前端回填角色动作结果时，必须以 `frames[0].imageSrc` 创建 `mediaType: "image-sequence"`、`assetKind: "character-animation"` 图层，并把完整 `frames` 保存为图层 `imageSequenceFrames`；`previewVideoPath` 只保留为上游预览视频来源，不作为画布主媒体。
 - 角色动作图层在画布中使用序列帧播放器循环展示透明 PNG 帧；刷新恢复时必须继续读取 `imageSequenceFrames`，不能回退到 `<video>` 预览。
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 1032c3db1..ea44c174b 100644
--- a/server-rs/crates/api-server/src/character_animation_assets.rs
+++ b/server-rs/crates/api-server/src/character_animation_assets.rs
@@ -61,7 +61,8 @@ use crate::{
         editor_generation_source_entity_id, enqueue_editor_generation_job,
     },
     editor_green_screen::{
-        editor_green_screen_character_prompt_clause,
+        LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE,
+        legacy_editor_green_screen_background_color,
         remove_editor_generated_green_screen_background,
     },
     editor_project::{
@@ -2153,11 +2154,14 @@ fn remove_editor_character_animation_frame_backgrounds(
 ) -> Result<Vec<FinalizedAnimationFrame>, AppError> {
     let mut removed_frames = Vec::with_capacity(frames.len());
     for frame in frames {
-        let removed = remove_editor_generated_green_screen_background(&DownloadedOpenAiImage {
-            bytes: frame.bytes,
-            mime_type: frame.mime_type,
-            extension: frame.extension,
-        })?;
+        let removed = remove_editor_generated_green_screen_background(
+            &DownloadedOpenAiImage {
+                bytes: frame.bytes,
+                mime_type: frame.mime_type,
+                extension: frame.extension,
+            },
+            legacy_editor_green_screen_background_color(),
+        )?;
         removed_frames.push(finalize_animation_frame_payload(
             removed.bytes.as_slice(),
             removed.mime_type.as_str(),
@@ -3384,7 +3388,7 @@ fn editor_video_bad_request(message: impl Into<String>) -> AppError {
 fn build_editor_character_animation_prompt(prompt_text: &str) -> String {
     format!(
         "生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。{}；禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。\n动作描述：\n{}",
-        editor_green_screen_character_prompt_clause(),
+        LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE,
         prompt_text.trim()
     )
 }
diff --git a/server-rs/crates/api-server/src/config.rs b/server-rs/crates/api-server/src/config.rs
index 721500570..8a93c51d7 100644
--- a/server-rs/crates/api-server/src/config.rs
+++ b/server-rs/crates/api-server/src/config.rs
@@ -16,6 +16,8 @@ const DEFAULT_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS: u64 = 2;
 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 = 120_000;
 
 // 集中管理 api-server 的启动配置，避免入口层直接散落环境变量解析逻辑。
 #[derive(Clone, Debug)]
@@ -56,6 +58,9 @@ pub struct AppConfig {
     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,
     pub image_editor_agent_sidebar_enabled: bool,
     pub log_filter: String,
     pub otel_enabled: bool,
@@ -284,6 +289,9 @@ impl Default for AppConfig {
             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,
             image_editor_agent_sidebar_enabled: false,
             log_filter: "info,tower_http=info".to_string(),
             otel_enabled: false,
@@ -475,6 +483,19 @@ impl AppConfig {
         ]) {
             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;
+        }
+        config.editor_bgfilter_token = read_first_non_empty_env(&[
+            "GENARRATIVE_EDITOR_BGFILTER_TOKEN",
+            "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN",
+        ]);
+        if let Some(timeout_ms) =
+            read_first_positive_u64_env(&["GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS"])
+        {
+            config.editor_bgfilter_request_timeout_ms = timeout_ms;
+        }
         if let Some(enabled) =
             read_first_bool_env(&["GENARRATIVE_ENABLE_IMAGE_EDITOR_AGENT_SIDEBAR"])
         {
@@ -1481,9 +1502,10 @@ fn parse_positive_u16(raw: &str) -> Option<u16> {
 mod tests {
     use super::{
         AppConfig, DEFAULT_EDITOR_BACKGROUND_REMOVAL_BASE_URL,
-        DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS,
-        DEFAULT_VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS, ExternalGenerationMode, LlmProvider,
-        ProcessRole, parse_bool, parse_external_generation_mode, parse_process_role,
+        DEFAULT_EDITOR_BACKGROUND_REMOVAL_REQUEST_TIMEOUT_MS, DEFAULT_EDITOR_BGFILTER_BASE_URL,
+        DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS, DEFAULT_VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS,
+        ExternalGenerationMode, LlmProvider, ProcessRole, parse_bool,
+        parse_external_generation_mode, parse_process_role,
     };
     use std::sync::{Mutex, OnceLock};
 
@@ -1506,6 +1528,15 @@ mod tests {
             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
+        );
+        assert_eq!(
+            config.editor_bgfilter_request_timeout_ms,
+            DEFAULT_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS
+        );
+        assert!(config.editor_bgfilter_token.is_none());
         assert!(config.ark_character_video_base_url.is_empty());
         assert_eq!(config.hyper3d_base_url, "https://api.hyper3d.com/api/v2");
         assert!(config.ark_character_video_model.is_empty());
@@ -2183,6 +2214,55 @@ mod tests {
         }
     }
 
+    #[test]
+    fn from_env_reads_editor_bgfilter_settings_and_reuses_background_token() {
+        let _guard = ENV_LOCK
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .expect("env lock should not poison");
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_BASE_URL");
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_TOKEN");
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN");
+            std::env::set_var(
+                "GENARRATIVE_EDITOR_BGFILTER_BASE_URL",
+                "http://10.0.0.12/bgfilter",
+            );
+            std::env::set_var(
+                "GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN",
+                "shared-token",
+            );
+            std::env::set_var("GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS", "180000");
+        }
+
+        let config = AppConfig::from_env();
+        assert_eq!(config.editor_bgfilter_base_url, "http://10.0.0.12/bgfilter");
+        assert_eq!(
+            config.editor_bgfilter_token.as_deref(),
+            Some("shared-token")
+        );
+        assert_eq!(config.editor_bgfilter_request_timeout_ms, 180_000);
+
+        unsafe {
+            std::env::set_var("GENARRATIVE_EDITOR_BGFILTER_TOKEN", "bgfilter-token");
+        }
+
+        let config = AppConfig::from_env();
+        assert_eq!(
+            config.editor_bgfilter_token.as_deref(),
+            Some("bgfilter-token")
+        );
+
+        unsafe {
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_BASE_URL");
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_TOKEN");
+            std::env::remove_var("GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS");
+            std::env::remove_var("GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN");
+        }
+    }
+
     #[test]
     fn from_env_reads_image_editor_agent_sidebar_runtime_flag() {
         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
index 1739eb0f6..f98a92c99 100644
--- a/server-rs/crates/api-server/src/editor_agent.rs
+++ b/server-rs/crates/api-server/src/editor_agent.rs
@@ -1709,6 +1709,8 @@ async fn execute_editor_agent_tool_call(
                     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()),
@@ -1785,6 +1787,8 @@ async fn execute_editor_agent_tool_call(
                     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()),
diff --git a/server-rs/crates/api-server/src/editor_green_screen.rs b/server-rs/crates/api-server/src/editor_green_screen.rs
index 433477202..586b682d1 100644
--- a/server-rs/crates/api-server/src/editor_green_screen.rs
+++ b/server-rs/crates/api-server/src/editor_green_screen.rs
@@ -1,42 +1,184 @@
 use axum::http::StatusCode;
 use platform_image::generated_asset_sheets::{
-    GeneratedAssetSheetAlphaOptions, GeneratedAssetSheetError,
+    GeneratedAssetSheetAlphaOptions, GeneratedAssetSheetError, GeneratedAssetSheetKeyColor,
     remove_generated_asset_sheet_green_screen_background_bytes,
 };
 use serde_json::json;
 
 use crate::{http_error::AppError, openai_image_generation::DownloadedOpenAiImage};
 
-pub(crate) const EDITOR_GREEN_SCREEN_COLOR_PROMPT: &str = "单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕";
-pub(crate) const EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS: &str =
-    "绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具";
-pub(crate) const EDITOR_GREEN_SCREEN_ASSET_GUARDRAILS: &str =
-    "素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光";
-pub(crate) const EDITOR_GREEN_SCREEN_CHARACTER_GUARDRAILS: &str =
-    "角色主体不得带绿色描边、绿色投影或绿色反光";
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct EditorScreenBackgroundColor {
+    pub(crate) label: &'static str,
+    pub(crate) hex: &'static str,
+    pub(crate) red: u8,
+    pub(crate) green: u8,
+    pub(crate) blue: u8,
+}
 
-pub(crate) fn editor_green_screen_asset_prompt_clause() -> String {
+pub(crate) const EDITOR_SCREEN_BACKGROUND_COLORS: [EditorScreenBackgroundColor; 11] = [
+    EditorScreenBackgroundColor {
+        label: "浅雾蓝",
+        hex: "#CFEFFF",
+        red: 207,
+        green: 239,
+        blue: 255,
+    },
+    EditorScreenBackgroundColor {
+        label: "浅钢蓝",
+        hex: "#B0C2E0",
+        red: 176,
+        green: 194,
+        blue: 224,
+    },
+    EditorScreenBackgroundColor {
+        label: "暖浅桃色",
+        hex: "#FFD6C2",
+        red: 255,
+        green: 214,
+        blue: 194,
+    },
+    EditorScreenBackgroundColor {
+        label: "淡薰衣草紫",
+        hex: "#E6D8FF",
+        red: 230,
+        green: 216,
+        blue: 255,
+    },
+    EditorScreenBackgroundColor {
+        label: "浅粉灰",
+        hex: "#F4D8E8",
+        red: 244,
+        green: 216,
+        blue: 232,
+    },
+    EditorScreenBackgroundColor {
+        label: "中度天蓝",
+        hex: "#7FB3FF",
+        red: 127,
+        green: 179,
+        blue: 255,
+    },
+    EditorScreenBackgroundColor {
+        label: "浅柠黄",
+        hex: "#FFF2A8",
+        red: 255,
+        green: 242,
+        blue: 168,
+    },
+    EditorScreenBackgroundColor {
+        label: "淡薄荷绿",
+        hex: "#CFFFE1",
+        red: 207,
+        green: 255,
+        blue: 225,
+    },
+    EditorScreenBackgroundColor {
+        label: "浅中性灰",
+        hex: "#D8DEE8",
+        red: 216,
+        green: 222,
+        blue: 232,
+    },
+    EditorScreenBackgroundColor {
+        label: "淡灰紫",
+        hex: "#D8D2E8",
+        red: 216,
+        green: 210,
+        blue: 232,
+    },
+    EditorScreenBackgroundColor {
+        label: "高对比浅青",
+        hex: "#A8F7F0",
+        red: 168,
+        green: 247,
+        blue: 240,
+    },
+];
+
+pub(crate) fn default_editor_screen_background_color() -> EditorScreenBackgroundColor {
+    EDITOR_SCREEN_BACKGROUND_COLORS[0]
+}
+
+pub(crate) fn legacy_editor_green_screen_background_color() -> EditorScreenBackgroundColor {
+    EditorScreenBackgroundColor {
+        label: "纯绿色",
+        hex: "#00FF00",
+        red: 0,
+        green: 255,
+        blue: 0,
+    }
+}
+
+pub(crate) fn parse_editor_screen_background_color(
+    value: Option<&str>,
+) -> Result<EditorScreenBackgroundColor, AppError> {
+    let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(default_editor_screen_background_color());
+    };
+    let normalized_value = value.to_ascii_uppercase();
+    EDITOR_SCREEN_BACKGROUND_COLORS
+        .iter()
+        .copied()
+        .find(|option| option.hex == normalized_value)
+        .ok_or_else(|| {
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-screen-background",
+                "message": "screenColor 必须是编辑器支持的纯色背景色。",
+                "allowed": EDITOR_SCREEN_BACKGROUND_COLORS
+                    .iter()
+                    .map(|option| option.hex)
+                    .collect::<Vec<_>>(),
+            }))
+        })
+}
+
+pub(crate) const EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS: &str =
+    "纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具";
+pub(crate) const EDITOR_GREEN_SCREEN_ASSET_GUARDRAILS: &str =
+    "素材自身不要出现与背景色相同或相近的描边、底板、投影或反光";
+pub(crate) const EDITOR_GREEN_SCREEN_CHARACTER_GUARDRAILS: &str =
+    "角色主体不得带与背景色相同或相近的描边、投影或反光";
+pub(crate) const LEGACY_EDITOR_GREEN_SCREEN_CHARACTER_PROMPT_CLAUSE: &str = "背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色；绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具；角色主体不得带绿色描边、绿色投影或绿色反光";
+
+fn editor_screen_background_color_prompt(color: EditorScreenBackgroundColor) -> String {
+    if color.hex == "#00FF00" {
+        return "单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕".to_string();
+    }
+    format!(
+        "单一纯色背景 {} {} / RGB({},{},{})",
+        color.label, color.hex, color.red, color.green, color.blue
+    )
+}
+
+pub(crate) fn editor_green_screen_asset_prompt_clause(
+    color: EditorScreenBackgroundColor,
+) -> String {
     format!(
         "背景必须是{}，且{}，方便扣除背景；{}",
-        EDITOR_GREEN_SCREEN_COLOR_PROMPT,
+        editor_screen_background_color_prompt(color),
         EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS,
         EDITOR_GREEN_SCREEN_ASSET_GUARDRAILS
     )
 }
 
-pub(crate) fn editor_green_screen_character_prompt_clause() -> String {
+pub(crate) fn editor_green_screen_character_prompt_clause(
+    color: EditorScreenBackgroundColor,
+) -> String {
     format!(
         "背景固定为{}，只作为抠像底色；{}；{}",
-        EDITOR_GREEN_SCREEN_COLOR_PROMPT,
+        editor_screen_background_color_prompt(color),
         EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS,
         EDITOR_GREEN_SCREEN_CHARACTER_GUARDRAILS
     )
 }
 
-pub(crate) fn editor_ui_design_asset_extraction_prompt() -> String {
+pub(crate) fn editor_ui_design_asset_extraction_prompt(
+    color: EditorScreenBackgroundColor,
+) -> String {
     format!(
         "仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用{}。{}，方便后续扣除背景；{}。",
-        EDITOR_GREEN_SCREEN_COLOR_PROMPT,
+        editor_screen_background_color_prompt(color),
         EDITOR_GREEN_SCREEN_BACKGROUND_GUARDRAILS,
         EDITOR_GREEN_SCREEN_ASSET_GUARDRAILS
     )
@@ -44,14 +186,22 @@ pub(crate) fn editor_ui_design_asset_extraction_prompt() -> String {
 
 pub(crate) fn remove_editor_generated_green_screen_background(
     image: &DownloadedOpenAiImage,
+    color: EditorScreenBackgroundColor,
 ) -> Result<DownloadedOpenAiImage, AppError> {
+    let key_color = GeneratedAssetSheetKeyColor {
+        red: color.red,
+        green: color.green,
+        blue: color.blue,
+    };
     let bytes = remove_generated_asset_sheet_green_screen_background_bytes(
         image.bytes.as_slice(),
         GeneratedAssetSheetAlphaOptions {
-            remove_muted_green_screen_background: true,
+            key_color,
+            remove_near_white_background: key_color.is_green_screen(),
+            remove_disconnected_hard_key_background: true,
+            remove_muted_green_screen_background: key_color.is_green_screen(),
             detect_internal_holes: true,
             internal_hole_min_pixels: 16,
-            ..GeneratedAssetSheetAlphaOptions::green_screen()
         },
     )
     .map_err(map_editor_green_screen_error)?;
@@ -85,20 +235,23 @@ mod tests {
     use image::{DynamicImage, ImageFormat, Rgba, RgbaImage};
 
     #[test]
-    fn editor_green_screen_postprocess_turns_background_transparent() {
-        let mut source = RgbaImage::from_pixel(3, 3, Rgba([0, 255, 0, 255]));
+    fn editor_green_screen_postprocess_turns_selected_background_transparent() {
+        let mut source = RgbaImage::from_pixel(3, 3, Rgba([207, 239, 255, 255]));
         source.put_pixel(1, 1, Rgba([240, 40, 40, 255]));
         let mut bytes = Vec::new();
         DynamicImage::ImageRgba8(source)
             .write_to(&mut Cursor::new(&mut bytes), ImageFormat::Png)
             .expect("test PNG should encode");
 
-        let output = remove_editor_generated_green_screen_background(&DownloadedOpenAiImage {
-            bytes,
-            mime_type: "image/png".to_string(),
-            extension: "png".to_string(),
-        })
-        .expect("green screen should be removed");
+        let output = remove_editor_generated_green_screen_background(
+            &DownloadedOpenAiImage {
+                bytes,
+                mime_type: "image/png".to_string(),
+                extension: "png".to_string(),
+            },
+            default_editor_screen_background_color(),
+        )
+        .expect("screen background should be removed");
         let image = image::load_from_memory(output.bytes.as_slice())
             .expect("output PNG should decode")
             .to_rgba8();
@@ -106,4 +259,25 @@ mod tests {
         assert_eq!(image.get_pixel(0, 0).0[3], 0);
         assert_eq!(image.get_pixel(1, 1).0[3], 255);
     }
+
+    #[test]
+    fn editor_screen_background_color_parser_uses_default_and_rejects_unknown() {
+        assert_eq!(
+            parse_editor_screen_background_color(None).expect("default should parse"),
+            default_editor_screen_background_color()
+        );
+        assert_eq!(
+            parse_editor_screen_background_color(Some("#ffd6c2"))
+                .expect("known lowercase hex should parse")
+                .label,
+            "暖浅桃色"
+        );
+        assert_eq!(
+            parse_editor_screen_background_color(Some("#a8f7f0"))
+                .expect("new high-contrast cyan should parse")
+                .label,
+            "高对比浅青"
+        );
+        assert!(parse_editor_screen_background_color(Some("#00FF00")).is_err());
+    }
 }
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index bef9a9adf..7f080430d 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -52,8 +52,14 @@ use crate::{
         enqueue_editor_generation_job,
     },
     editor_green_screen::{
-        editor_green_screen_asset_prompt_clause, editor_green_screen_character_prompt_clause,
-        editor_ui_design_asset_extraction_prompt, remove_editor_generated_green_screen_background,
+        EditorScreenBackgroundColor, editor_green_screen_asset_prompt_clause,
+        editor_green_screen_character_prompt_clause, editor_ui_design_asset_extraction_prompt,
+        remove_editor_generated_green_screen_background,
+    },
+    editor_screen_background_decision::{
+        EditorScreenBackgroundDecision, EditorScreenBackgroundDecisionInput,
+        EditorScreenBackgroundDecisionKind, format_editor_screen_background_decision_input,
+        resolve_editor_screen_background_color,
     },
     generated_image_assets::{
         GeneratedImageAssetAdapter, GeneratedImageAssetDataUrl,
@@ -102,6 +108,8 @@ const EDITOR_UI_DESIGN_SPRITESHEET_ASSET_KIND: &str = "editor_ui_design_spritesh
 const EDITOR_UI_DESIGN_ASSET_IMAGE_KIND: &str = "editor_ui_design_asset";
 const EDITOR_GREEN_SCREEN_SOURCE_ASSET_KIND: &str = "editor_green_screen_source";
 const EDITOR_GREEN_SCREEN_SOURCE_SLOT: &str = "green_screen_source";
+const EDITOR_BGFILTER_DEFAULT_SEG_MODEL: &str = "birefnet";
+const EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG: &str = "anime-seg";
 const EDITOR_PUBLICATION_MATERIAL_ASSET_KIND: &str = "editor_publication_material";
 const EDITOR_LEGACY_INLINE_IMAGE_ASSET_KIND: &str = "editor_legacy_inline_image";
 
@@ -205,6 +213,8 @@ pub struct EditorImageGenerationRequest {
     pub(crate) size: Option<String>,
     pub(crate) kind: Option<String>,
     pub(crate) model: Option<String>,
+    pub(crate) screen_color: Option<String>,
+    pub(crate) seg_model: Option<String>,
     pub(crate) aspect_ratio: Option<String>,
     pub(crate) image_size: Option<String>,
     pub(crate) reference_image_srcs: Option<Vec<String>>,
@@ -257,6 +267,8 @@ pub struct EditorIconSpritesheetGenerationRequest {
     pub(crate) reference_image_srcs: Option<Vec<String>>,
     pub(crate) icon_descriptions: Vec<String>,
     pub(crate) model: Option<String>,
+    pub(crate) screen_color: Option<String>,
+    pub(crate) seg_model: Option<String>,
     pub(crate) aspect_ratio: Option<String>,
     pub(crate) image_size: Option<String>,
     pub(crate) project_id: Option<String>,
@@ -270,6 +282,8 @@ pub struct EditorIconSpritesheetGenerationRequest {
 pub struct EditorUiDesignAssetExtractionRequest {
     pub(crate) source_image_src: String,
     pub(crate) model: Option<String>,
+    pub(crate) screen_color: Option<String>,
+    pub(crate) seg_model: Option<String>,
     pub(crate) reference_image_srcs: Option<Vec<String>>,
     pub(crate) aspect_ratio: String,
     pub(crate) image_size: String,
@@ -1330,6 +1344,33 @@ pub(crate) async fn generate_editor_image_for_owner(
 
     let normalized_kind = payload.kind.as_deref().map(str::trim);
     let is_character_generation = matches!(normalized_kind, Some("character"));
+    let screen_background_decision = if is_character_generation {
+        Some(
+            resolve_editor_screen_background_color(
+                state.llm_client(),
+                EditorScreenBackgroundDecisionInput {
+                    kind: EditorScreenBackgroundDecisionKind::Character,
+                    screen_color: payload.screen_color.clone(),
+                    prompt: role_setting.clone(),
+                    icon_descriptions: Vec::new(),
+                    reference_count: payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
+                },
+            )
+            .await?,
+        )
+    } else {
+        None
+    };
+    let screen_color = screen_background_decision
+        .as_ref()
+        .map(|decision| decision.color);
+    let seg_model = if is_character_generation {
+        Some(parse_editor_bgfilter_seg_model(
+            payload.seg_model.as_deref(),
+        )?)
+    } else {
+        None
+    };
     let is_ui_design_generation = matches!(normalized_kind, Some("ui-design"));
     let is_publication_material_generation =
         matches!(normalized_kind, Some("publication-material"));
@@ -1350,7 +1391,10 @@ pub(crate) async fn generate_editor_image_for_owner(
         &generation_options,
     );
     let submitted_prompt = if is_character_generation {
-        build_editor_character_image_prompt(role_setting.as_str())
+        build_editor_character_image_prompt(
+            role_setting.as_str(),
+            screen_color.expect("character generation should have screen color"),
+        )
     } else if is_ui_design_generation {
         build_editor_ui_design_prompt(
             role_setting.as_str(),
@@ -1494,7 +1538,13 @@ pub(crate) async fn generate_editor_image_for_owner(
             "character-image",
         )
         .await?;
-        image = remove_editor_generated_green_screen_background(&image)?;
+        image = remove_editor_generated_screen_background_with_bgfilter(
+            state,
+            &image,
+            screen_color.expect("character generation should have screen color"),
+            seg_model.expect("character generation should have BgFilter seg model"),
+        )
+        .await?;
     }
 
     let (width, height) = image::load_from_memory(image.bytes.as_slice())
@@ -1536,7 +1586,10 @@ pub(crate) async fn generate_editor_image_for_owner(
             task_id: generated.task_id.clone(),
             source_resource_id: payload.source_resource_id,
             asset_kind: payload.asset_kind,
-            generation_inputs: payload.generation_inputs,
+            generation_inputs: apply_editor_screen_background_decision_to_generation_inputs(
+                payload.generation_inputs,
+                screen_background_decision.as_ref(),
+            ),
             thumbnail_src: None,
             generation_cost_mud_points: u64::from(configured_price_mud_points),
         },
@@ -1583,6 +1636,28 @@ fn editor_image_generation_billing_asset_kind(normalized_kind: Option<&str>) ->
     }
 }
 
+fn apply_editor_screen_background_decision_to_generation_inputs(
+    generation_inputs: Option<Value>,
+    decision: Option<&EditorScreenBackgroundDecision>,
+) -> Option<Value> {
+    let Some(decision) = decision else {
+        return generation_inputs;
+    };
+    let mut value = generation_inputs?;
+    let Some(fields) = value.get_mut("fields").and_then(Value::as_array_mut) else {
+        return Some(value);
+    };
+    let resolved_value = format_editor_screen_background_decision_input(decision);
+    for field in fields {
+        let title = field.get("title").and_then(Value::as_str);
+        if title == Some("抠图背景色") {
+            field["value"] = Value::String(resolved_value);
+            break;
+        }
+    }
+    Some(value)
+}
+
 fn editor_generated_image_storage_profile(
     normalized_kind: Option<&str>,
 ) -> EditorGeneratedImageStorageProfile {
@@ -2124,6 +2199,182 @@ struct EditorBackgroundRemovalImage {
     height: u32,
 }
 
+async fn remove_editor_generated_screen_background_with_bgfilter(
+    state: &AppState,
+    image: &DownloadedOpenAiImage,
+    screen_color: EditorScreenBackgroundColor,
+    seg_model: &str,
+) -> Result<DownloadedOpenAiImage, AppError> {
+    match request_editor_generated_screen_background_with_bgfilter(
+        state,
+        image,
+        screen_color,
+        seg_model,
+    )
+    .await
+    {
+        Ok(image) => Ok(image),
+        Err(error) => {
+            tracing::warn!(
+                provider = "bgfilter",
+                screen_color = screen_color.hex,
+                seg_model,
+                error = %error,
+                error_details = ?error.details(),
+                "editor_bgfilter_fallback_to_local_screen_background_removal"
+            );
+            remove_editor_generated_green_screen_background(image, screen_color)
+        }
+    }
+}
+
+async fn request_editor_generated_screen_background_with_bgfilter(
+    state: &AppState,
+    image: &DownloadedOpenAiImage,
+    screen_color: EditorScreenBackgroundColor,
+    seg_model: &str,
+) -> Result<DownloadedOpenAiImage, AppError> {
+    let url = editor_bgfilter_endpoint(state)?;
+    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('.')
+    );
+    tracing::info!(
+        %call_id,
+        upstream_url = %url,
+        file_name = %source_file_name,
+        mime_type = %source_mime_type,
+        screen_color = screen_color.hex,
+        seg_model,
+        input_bytes,
+        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 form = reqwest::multipart::Form::new()
+        .part("file", file_part)
+        .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);
+    if let Some(token) = state
+        .config
+        .editor_bgfilter_token
+        .as_deref()
+        .map(str::trim)
+        .filter(|token| !token.is_empty())
+    {
+        request = request.header("X-Genarrative-Image-Token", token);
+    }
+    let response = request.send().await.map_err(|error| {
+        tracing::warn!(
+            %call_id,
+            elapsed_ms = request_started_at.elapsed().as_millis() as u64,
+            timeout = error.is_timeout(),
+            error = %error,
+            "editor_bgfilter_request_failed"
+        );
+        map_editor_bgfilter_error(error)
+    })?;
+    let status = response.status();
+    if !status.is_success() {
+        let message = response
+            .text()
+            .await
+            .unwrap_or_else(|error| format!("读取上游错误失败：{error}"));
+        tracing::warn!(
+            %call_id,
+            upstream_status = status.as_u16(),
+            elapsed_ms = request_started_at.elapsed().as_millis() as u64,
+            upstream_message = %message.chars().take(160).collect::<String>(),
+            "editor_bgfilter_upstream_rejected"
+        );
+        return Err(
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "bgfilter",
+                "message": "BgFilter 服务返回非成功状态",
+                "upstreamStatus": status.as_u16(),
+                "upstreamMessage": message.chars().take(500).collect::<String>(),
+            })),
+        );
+    }
+    let mime_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .and_then(normalize_editor_reference_image_mime_type)
+        .unwrap_or("image/png")
+        .to_string();
+    let upstream_elapsed_ms = response
+        .headers()
+        .get("x-bgfilter-elapsed-ms")
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.parse::<u64>().ok());
+    let upstream_seg_model = response
+        .headers()
+        .get("x-bgfilter-seg-model")
+        .and_then(|value| value.to_str().ok())
+        .map(ToOwned::to_owned);
+    let upstream_screen_color = response
+        .headers()
+        .get("x-bgfilter-screen-color")
+        .and_then(|value| value.to_str().ok())
+        .map(ToOwned::to_owned);
+    let bytes = read_editor_image_removal_response_bytes(response, "bgfilter", "BgFilter").await?;
+    if bytes.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "bgfilter",
+                "message": "BgFilter 服务未返回图片",
+            })),
+        );
+    }
+    let decoded = decode_editor_removed_background_image(bytes.as_slice(), "bgfilter")?;
+    let image = DownloadedOpenAiImage {
+        bytes,
+        extension: editor_reference_image_extension(mime_type.as_str()).to_string(),
+        mime_type,
+    };
+    tracing::info!(
+        %call_id,
+        status = status.as_u16(),
+        width = decoded.width(),
+        height = decoded.height(),
+        screen_color = screen_color.hex,
+        seg_model,
+        upstream_screen_color = upstream_screen_color.as_deref().unwrap_or(""),
+        upstream_seg_model = upstream_seg_model.as_deref().unwrap_or(""),
+        input_bytes,
+        output_bytes = image.bytes.len(),
+        elapsed_ms = request_started_at.elapsed().as_millis() as u64,
+        upstream_elapsed_ms,
+        "editor_bgfilter_request_done"
+    );
+
+    Ok(image)
+}
+
 async fn request_editor_background_removal_image(
     state: &AppState,
     source_image: OpenAiReferenceImage,
@@ -2271,6 +2522,42 @@ fn editor_background_removal_endpoint(state: &AppState) -> Result<String, AppErr
     ))
 }
 
+fn editor_bgfilter_endpoint(state: &AppState) -> Result<String, AppError> {
+    let base_url = state.config.editor_bgfilter_base_url.trim();
+    if base_url.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+                "provider": "bgfilter",
+                "message": "BgFilter 服务地址未配置",
+            })),
+        );
+    }
+    Ok(format!(
+        "{}/remove-background",
+        base_url.trim_end_matches('/')
+    ))
+}
+
+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);
+    };
+    match value.to_ascii_lowercase().as_str() {
+        EDITOR_BGFILTER_DEFAULT_SEG_MODEL => Ok(EDITOR_BGFILTER_DEFAULT_SEG_MODEL),
+        EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG => Ok(EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG),
+        _ => Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "bgfilter",
+                "message": "segModel 必须是 birefnet 或 anime-seg。",
+                "allowed": [
+                    EDITOR_BGFILTER_DEFAULT_SEG_MODEL,
+                    EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG,
+                ],
+            })),
+        ),
+    }
+}
+
 fn map_editor_background_removal_error(error: reqwest::Error) -> AppError {
     let status = if error.is_timeout() {
         StatusCode::GATEWAY_TIMEOUT
@@ -2284,16 +2571,37 @@ fn map_editor_background_removal_error(error: reqwest::Error) -> AppError {
     }))
 }
 
+fn map_editor_bgfilter_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": "bgfilter",
+        "message": format!("请求 BgFilter 服务失败：{error}"),
+        "timeout": error.is_timeout(),
+    }))
+}
+
 async fn read_editor_background_removal_bytes(
+    response: reqwest::Response,
+) -> Result<Vec<u8>, AppError> {
+    read_editor_image_removal_response_bytes(response, "birefnet", "抠图服务").await
+}
+
+async fn read_editor_image_removal_response_bytes(
     mut response: reqwest::Response,
+    provider: &str,
+    service_label: &str,
 ) -> Result<Vec<u8>, AppError> {
     if response.content_length().is_some_and(|content_length| {
         content_length > EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES as u64
     }) {
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": "birefnet",
-                "message": "抠图服务返回图片过大",
+                "provider": provider,
+                "message": format!("{service_label}返回图片过大"),
                 "maxBytes": EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES,
             })),
         );
@@ -2301,15 +2609,15 @@ async fn read_editor_background_removal_bytes(
     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": "birefnet",
-            "message": format!("读取抠图结果失败：{error}"),
+            "provider": provider,
+            "message": format!("读取{service_label}结果失败：{error}"),
         }))
     })? {
         if bytes.len().saturating_add(chunk.len()) > EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES {
             return Err(
                 AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                    "provider": "birefnet",
-                    "message": "抠图服务返回图片过大",
+                    "provider": provider,
+                    "message": format!("{service_label}返回图片过大"),
                     "maxBytes": EDITOR_BACKGROUND_REMOVAL_MAX_RESPONSE_BYTES,
                 })),
             );
@@ -2320,11 +2628,18 @@ async fn read_editor_background_removal_bytes(
 }
 
 fn decode_editor_background_removal_image(bytes: &[u8]) -> Result<image::DynamicImage, AppError> {
+    decode_editor_removed_background_image(bytes, "birefnet")
+}
+
+fn decode_editor_removed_background_image(
+    bytes: &[u8],
+    provider: &str,
+) -> Result<image::DynamicImage, AppError> {
     let mut reader = image::ImageReader::new(Cursor::new(bytes))
         .with_guessed_format()
         .map_err(|error| {
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": "birefnet",
+                "provider": provider,
                 "message": format!("识别抠图结果格式失败：{error}"),
             }))
         })?;
@@ -2335,7 +2650,7 @@ fn decode_editor_background_removal_image(bytes: &[u8]) -> Result<image::Dynamic
     reader.limits(limits);
     reader.decode().map_err(|error| {
         AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-            "provider": "birefnet",
+            "provider": provider,
             "message": format!("抠图结果不是有效图片：{error}"),
             "maxDimension": EDITOR_BACKGROUND_REMOVAL_MAX_IMAGE_DIMENSION,
         }))
@@ -2392,6 +2707,19 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
     payload: EditorIconSpritesheetGenerationRequest,
 ) -> Result<Json<Value>, AppError> {
     let icon_descriptions = normalize_icon_descriptions(payload.icon_descriptions)?;
+    let screen_background_decision = resolve_editor_screen_background_color(
+        state.llm_client(),
+        EditorScreenBackgroundDecisionInput {
+            kind: EditorScreenBackgroundDecisionKind::IconSpritesheet,
+            screen_color: payload.screen_color.clone(),
+            prompt: icon_descriptions.join("\n"),
+            icon_descriptions: icon_descriptions.clone(),
+            reference_count: 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
+        },
+    )
+    .await?;
+    let screen_color = screen_background_decision.color;
+    let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?;
     let mut reference_images =
         Vec::with_capacity(1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len));
     reference_images.push(
@@ -2435,7 +2763,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         Some(generation_options.image_size),
     )?;
     let size = generation_options.size.as_str();
-    let prompt = build_editor_icon_spritesheet_prompt(&icon_descriptions);
+    let prompt = build_editor_icon_spritesheet_prompt(&icon_descriptions, screen_color);
 
     let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
         request_context,
@@ -2500,11 +2828,20 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
         "spritesheet",
     )
     .await?;
-    let image = remove_editor_generated_green_screen_background(&image)?;
+    let image = remove_editor_generated_screen_background_with_bgfilter(
+        state,
+        &image,
+        screen_color,
+        seg_model,
+    )
+    .await?;
     let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
         .map(|image| (image.width(), image.height()))
         .unwrap_or((512, 512));
-    let generation_inputs = payload.generation_inputs.clone();
+    let generation_inputs = apply_editor_screen_background_decision_to_generation_inputs(
+        payload.generation_inputs.clone(),
+        Some(&screen_background_decision),
+    );
     let owner_user_id = caller.owner_user_id;
     let spritesheet_persisted = persist_editor_generated_image(
         state,
@@ -2637,6 +2974,22 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
     caller: EditorGenerationCaller,
     payload: EditorUiDesignAssetExtractionRequest,
 ) -> Result<Json<Value>, AppError> {
+    let screen_background_decision = resolve_editor_screen_background_color(
+        state.llm_client(),
+        EditorScreenBackgroundDecisionInput {
+            kind: EditorScreenBackgroundDecisionKind::UiDesignAssetExtraction,
+            screen_color: payload.screen_color.clone(),
+            prompt: format!(
+                "从 UI 设计图提取被红色框选的素材，输出 spritesheet。目标规格 {} {}。",
+                payload.aspect_ratio, payload.image_size
+            ),
+            icon_descriptions: Vec::new(),
+            reference_count: 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len),
+        },
+    )
+    .await?;
+    let screen_color = screen_background_decision.color;
+    let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?;
     let reference_image = parse_editor_reference_image(
         state,
         caller.owner_user_id.as_str(),
@@ -2686,7 +3039,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
             .or_else(|| payload.project_id.clone()),
     );
     let http_client = build_openai_image_http_client(&settings)?;
-    let prompt = editor_ui_design_asset_extraction_prompt();
+    let prompt = editor_ui_design_asset_extraction_prompt(screen_color);
     let generated = execute_billable_asset_operation_with_cost(
         state,
         caller.owner_user_id.as_str(),
@@ -2741,7 +3094,13 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
         "spritesheet",
     )
     .await?;
-    let image = remove_editor_generated_green_screen_background(&image)?;
+    let image = remove_editor_generated_screen_background_with_bgfilter(
+        state,
+        &image,
+        screen_color,
+        seg_model,
+    )
+    .await?;
     let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
         .map(|image| (image.width(), image.height()))
         .unwrap_or((512, 512));
@@ -2757,7 +3116,10 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner(
                 "message": error.to_string(),
             }))
         })?;
-    let generation_inputs = payload.generation_inputs.clone();
+    let generation_inputs = apply_editor_screen_background_decision_to_generation_inputs(
+        payload.generation_inputs.clone(),
+        Some(&screen_background_decision),
+    );
     let owner_user_id = caller.owner_user_id;
     let spritesheet_persisted = persist_editor_generated_image(
         state,
@@ -4508,10 +4870,13 @@ fn resolve_editor_ui_design_asset_extraction_price(
     Ok(expected_price_mud_points)
 }
 
-fn build_editor_icon_spritesheet_prompt(icon_descriptions: &[String]) -> String {
+fn build_editor_icon_spritesheet_prompt(
+    icon_descriptions: &[String],
+    screen_color: EditorScreenBackgroundColor,
+) -> String {
     format!(
         "参考图1的图标素材规范，{}；禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：\n\n{}",
-        editor_green_screen_asset_prompt_clause(),
+        editor_green_screen_asset_prompt_clause(screen_color),
         icon_descriptions.join("、")
     )
 }
@@ -4527,9 +4892,12 @@ fn build_editor_ui_design_prompt(user_input: &str, has_icon_spec_reference: bool
     prompt.join("\n")
 }
 
-fn build_editor_character_image_prompt(role_setting: &str) -> String {
+fn build_editor_character_image_prompt(
+    role_setting: &str,
+    screen_color: EditorScreenBackgroundColor,
+) -> String {
     vec![
-        format!("按照角色描述生成游戏角色立绘。严格基于图1的角色美术视觉规范的美术风格、角色头身比、角色朝向等特征。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。{}；禁止生成美术视觉规范，禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。", editor_green_screen_character_prompt_clause()),
+        format!("按照角色描述生成游戏角色立绘。严格基于图1的角色美术视觉规范的美术风格、角色头身比、角色朝向等特征。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。{}；禁止生成美术视觉规范，禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。", editor_green_screen_character_prompt_clause(screen_color)),
         format!("角色设定：{}", role_setting.trim()),
     ]
     .join("\n")
@@ -5124,7 +5492,7 @@ pub(crate) fn current_utc_micros() -> i64 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::AppConfig;
+    use crate::{config::AppConfig, editor_green_screen::parse_editor_screen_background_color};
 
     #[test]
     fn editor_project_procedure_errors_preserve_business_reason_as_bad_request() {
@@ -5799,13 +6167,17 @@ mod tests {
 
     #[test]
     fn editor_character_image_prompt_appends_user_role_setting() {
-        let prompt = build_editor_character_image_prompt("菜市场卖菜大妈");
+        let prompt = build_editor_character_image_prompt(
+            "菜市场卖菜大妈",
+            parse_editor_screen_background_color(Some("#FFD6C2"))
+                .expect("screen color should parse"),
+        );
 
         assert!(prompt.contains("严格基于图1的角色美术视觉规范"));
         assert!(prompt.contains("生成游戏角色立绘"));
-        assert!(prompt.contains("背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
-        assert!(prompt.contains("绿幕背景必须平整无纹理、无渐变、无阴影"));
-        assert!(prompt.contains("角色主体不得带绿色描边、绿色投影或绿色反光"));
+        assert!(prompt.contains("背景固定为单一纯色背景 暖浅桃色 #FFD6C2 / RGB(255,214,194)"));
+        assert!(prompt.contains("纯色背景必须平整无纹理、无渐变、无阴影"));
+        assert!(prompt.contains("角色主体不得带与背景色相同或相近的描边、投影或反光"));
         assert!(prompt.contains("禁止镜头透视"));
         assert!(prompt.contains("角色设定：菜市场卖菜大妈"));
     }
@@ -6338,20 +6710,38 @@ mod tests {
             "设置按钮".to_string(),
             "下一关按钮".to_string(),
         ];
-        let prompt = build_editor_icon_spritesheet_prompt(&descriptions);
+        let prompt = build_editor_icon_spritesheet_prompt(
+            &descriptions,
+            parse_editor_screen_background_color(Some("#7FB3FF"))
+                .expect("screen color should parse"),
+        );
 
         assert!(prompt.contains("参考图1的图标素材规范"));
-        assert!(prompt.contains("背景必须是单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
+        assert!(prompt.contains("背景必须是单一纯色背景 中度天蓝 #7FB3FF / RGB(127,179,255)"));
         assert!(prompt.contains("平整无纹理、无渐变、无阴影"));
-        assert!(prompt.contains("素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光"));
+        assert!(prompt.contains("素材自身不要出现与背景色相同或相近的描边、底板、投影或反光"));
         assert!(prompt.contains("返回按钮、设置按钮、下一关按钮"));
     }
 
+    #[test]
+    fn editor_icon_spritesheet_prompt_accepts_new_background_colors() {
+        let prompt = build_editor_icon_spritesheet_prompt(
+            &["发光能量按钮".to_string()],
+            parse_editor_screen_background_color(Some("#A8F7F0"))
+                .expect("new screen color should parse"),
+        );
+
+        assert!(prompt.contains("背景必须是单一纯色背景 高对比浅青 #A8F7F0 / RGB(168,247,240)"));
+    }
+
     #[test]
     fn editor_ui_design_asset_extraction_prompt_is_fixed() {
         assert_eq!(
-            editor_ui_design_asset_extraction_prompt(),
-            "仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。"
+            editor_ui_design_asset_extraction_prompt(
+                parse_editor_screen_background_color(None)
+                    .expect("default screen color should parse")
+            ),
+            "仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯色背景 浅雾蓝 #CFEFFF / RGB(207,239,255)。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。"
         );
     }
 
@@ -6608,10 +6998,14 @@ mod tests {
         let request: EditorUiDesignAssetExtractionRequest = serde_json::from_value(json!({
             "sourceImageSrc": "data:image/png;base64,AAAA",
             "model": "gpt-image-2",
+            "screenColor": "#E6D8FF",
+            "segModel": "anime-seg",
             "aspectRatio": "1:1",
             "imageSize": "2K"
         }))
         .expect("UI extraction request should deserialize dimensions");
+        assert_eq!(request.screen_color.as_deref(), Some("#E6D8FF"));
+        assert_eq!(request.seg_model.as_deref(), Some("anime-seg"));
         let generation_options = normalize_editor_ui_design_asset_extraction_options(
             request.model.as_deref(),
             request.aspect_ratio.as_str(),
@@ -6666,12 +7060,16 @@ mod tests {
         let request: EditorImageGenerationRequest = serde_json::from_value(json!({
             "prompt": "生成图片",
             "model": "gpt-image-2",
+            "screenColor": "#CFEFFF",
+            "segModel": "anime-seg",
             "aspectRatio": "1:1",
             "imageSize": "1K"
         }))
         .expect("image generation request should deserialize without price");
 
         assert_eq!(request.prompt, "生成图片");
+        assert_eq!(request.screen_color.as_deref(), Some("#CFEFFF"));
+        assert_eq!(request.seg_model.as_deref(), Some("anime-seg"));
     }
 
     #[test]
@@ -6716,7 +7114,9 @@ mod tests {
         let request: EditorIconSpritesheetGenerationRequest = serde_json::from_value(json!({
             "referenceImageSrc": "data:image/png;base64,spec",
             "referenceImageSrcs": ["data:image/png;base64,style"],
-            "iconDescriptions": ["返回按钮"]
+            "iconDescriptions": ["返回按钮"],
+            "screenColor": "#7FB3FF",
+            "segModel": "anime-seg"
         }))
         .expect("icon spritesheet request should deserialize references");
 
@@ -6724,6 +7124,21 @@ mod tests {
             request.reference_image_srcs,
             Some(vec!["data:image/png;base64,style".to_string()])
         );
+        assert_eq!(request.screen_color.as_deref(), Some("#7FB3FF"));
+        assert_eq!(request.seg_model.as_deref(), Some("anime-seg"));
+    }
+
+    #[test]
+    fn editor_bgfilter_seg_model_parser_defaults_and_rejects_unknown() {
+        assert_eq!(
+            parse_editor_bgfilter_seg_model(None).expect("default should parse"),
+            EDITOR_BGFILTER_DEFAULT_SEG_MODEL
+        );
+        assert_eq!(
+            parse_editor_bgfilter_seg_model(Some("Anime-Seg")).expect("anime seg should parse"),
+            EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG
+        );
+        assert!(parse_editor_bgfilter_seg_model(Some("u2net")).is_err());
     }
 
     #[test]
@@ -6768,7 +7183,7 @@ mod tests {
     }
 
     #[test]
-    fn editor_canvas_green_screen_generation_uses_local_postprocess() {
+    fn editor_canvas_screen_background_generation_uses_bgfilter_postprocess() {
         let source = include_str!("editor_project.rs");
         assert_function_contains(
             source,
@@ -6776,7 +7191,7 @@ mod tests {
             "fn normalize_editor_image_generation_size",
             &[
                 "persist_editor_green_screen_source_image",
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter",
                 "if is_character_generation",
             ],
         );
@@ -6786,7 +7201,7 @@ mod tests {
             "fn normalize_editor_image_generation_size",
             &[
                 "persist_editor_green_screen_source_image",
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter",
             ],
         );
         assert_function_contains(
@@ -6795,7 +7210,7 @@ mod tests {
             "pub async fn extract_editor_ui_design_assets",
             &[
                 "persist_editor_green_screen_source_image",
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter",
             ],
         );
         assert_function_contains_in_order(
@@ -6804,7 +7219,7 @@ mod tests {
             "pub async fn extract_editor_ui_design_assets",
             &[
                 "persist_editor_green_screen_source_image",
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter",
             ],
         );
         assert_function_contains(
@@ -6813,7 +7228,7 @@ mod tests {
             "pub(crate) fn editor_project_payload_from_record",
             &[
                 "persist_editor_green_screen_source_image",
-                "remove_editor_generated_green_screen_background",
+                "remove_editor_generated_screen_background_with_bgfilter",
                 "slice_generated_icon_spritesheet_all_by_connected_components",
             ],
         );
@@ -6823,27 +7238,75 @@ mod tests {
             "pub(crate) fn editor_project_payload_from_record",
             &[
                 "persist_editor_green_screen_source_image",
+                "remove_editor_generated_screen_background_with_bgfilter",
+            ],
+        );
+        assert_function_contains(
+            source,
+            "async fn remove_editor_generated_screen_background_with_bgfilter",
+            "async fn request_editor_generated_screen_background_with_bgfilter",
+            &[
+                "request_editor_generated_screen_background_with_bgfilter",
                 "remove_editor_generated_green_screen_background",
             ],
         );
+        assert_function_contains(
+            source,
+            "async fn request_editor_generated_screen_background_with_bgfilter",
+            "async fn request_editor_background_removal_image",
+            &[
+                "editor_bgfilter_endpoint",
+                "editor_bgfilter_request_timeout_ms.max(1)",
+                "\"screen_color\"",
+                "\"seg_model\"",
+                "seg_model.to_string()",
+            ],
+        );
+        assert_function_contains(
+            source,
+            "async fn request_editor_background_removal_image",
+            "fn editor_background_removal_endpoint",
+            &[
+                "editor_background_removal_endpoint",
+                "\"provider\": \"birefnet\"",
+            ],
+        );
         assert_function_not_contains(
             source,
             "pub(crate) async fn generate_editor_image_for_owner",
             "fn normalize_editor_image_generation_size",
             &["try_remove_editor_downloaded_image_background"],
         );
+        assert_function_not_contains(
+            source,
+            "pub(crate) async fn generate_editor_image_for_owner",
+            "fn normalize_editor_image_generation_size",
+            &["remove_editor_generated_green_screen_background"],
+        );
         assert_function_not_contains(
             source,
             "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
             "pub async fn extract_editor_ui_design_assets",
             &["try_remove_editor_downloaded_image_background"],
         );
+        assert_function_not_contains(
+            source,
+            "pub(crate) async fn generate_editor_icon_spritesheet_for_owner",
+            "pub async fn extract_editor_ui_design_assets",
+            &["remove_editor_generated_green_screen_background"],
+        );
         assert_function_not_contains(
             source,
             "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
             "pub(crate) fn editor_project_payload_from_record",
             &["try_remove_editor_downloaded_image_background"],
         );
+        assert_function_not_contains(
+            source,
+            "pub(crate) async fn extract_editor_ui_design_assets_for_owner",
+            "pub(crate) fn editor_project_payload_from_record",
+            &["remove_editor_generated_green_screen_background"],
+        );
         assert_function_not_contains(
             source,
             "pub(crate) async fn generate_editor_image_for_owner",
diff --git a/server-rs/crates/api-server/src/editor_screen_background_decision.rs b/server-rs/crates/api-server/src/editor_screen_background_decision.rs
new file mode 100644
index 000000000..021988940
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_screen_background_decision.rs
@@ -0,0 +1,339 @@
+use platform_llm::{LlmClient, LlmTextRequest};
+use serde_json::json;
+use tracing::{info, warn};
+
+use crate::{
+    editor_green_screen::{
+        EDITOR_SCREEN_BACKGROUND_COLORS, EditorScreenBackgroundColor,
+        default_editor_screen_background_color, parse_editor_screen_background_color,
+    },
+    http_error::AppError,
+};
+
+const EDITOR_SCREEN_BACKGROUND_AUTO_VALUE: &str = "auto";
+const EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS: u8 = 3;
+const EDITOR_SCREEN_BACKGROUND_DECISION_TIMEOUT_MS: u64 = 20_000;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum EditorScreenBackgroundDecisionMode {
+    Manual,
+    Auto,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct EditorScreenBackgroundDecision {
+    pub(crate) color: EditorScreenBackgroundColor,
+    pub(crate) mode: EditorScreenBackgroundDecisionMode,
+    pub(crate) attempts: u8,
+    pub(crate) fallback: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum EditorScreenBackgroundDecisionKind {
+    Character,
+    IconSpritesheet,
+    UiDesignAssetExtraction,
+}
+
+impl EditorScreenBackgroundDecisionKind {
+    fn label(self) -> &'static str {
+        match self {
+            Self::Character => "角色形象生成",
+            Self::IconSpritesheet => "图标素材 spritesheet 生成",
+            Self::UiDesignAssetExtraction => "UI 设计图素材提取",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct EditorScreenBackgroundDecisionInput {
+    pub(crate) kind: EditorScreenBackgroundDecisionKind,
+    pub(crate) screen_color: Option<String>,
+    pub(crate) prompt: String,
+    pub(crate) icon_descriptions: Vec<String>,
+    pub(crate) reference_count: usize,
+}
+
+pub(crate) async fn resolve_editor_screen_background_color(
+    llm_client: Option<&LlmClient>,
+    input: EditorScreenBackgroundDecisionInput,
+) -> Result<EditorScreenBackgroundDecision, AppError> {
+    if !is_auto_screen_background_color(input.screen_color.as_deref()) {
+        return Ok(EditorScreenBackgroundDecision {
+            color: parse_editor_screen_background_color(input.screen_color.as_deref())?,
+            mode: EditorScreenBackgroundDecisionMode::Manual,
+            attempts: 0,
+            fallback: false,
+        });
+    }
+
+    let fallback_color = default_editor_screen_background_color();
+    let Some(llm_client) = llm_client else {
+        warn!(
+            kind = input.kind.label(),
+            fallback_hex = fallback_color.hex,
+            "editor_screen_background_auto_decision_fallback_no_llm"
+        );
+        return Ok(EditorScreenBackgroundDecision {
+            color: fallback_color,
+            mode: EditorScreenBackgroundDecisionMode::Auto,
+            attempts: 0,
+            fallback: true,
+        });
+    };
+
+    let system_prompt = editor_screen_background_decision_system_prompt();
+    let user_prompt = editor_screen_background_decision_user_prompt(&input);
+    let mut last_error: Option<String> = None;
+    for attempt in 1..=EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS {
+        let request = LlmTextRequest::single_turn(system_prompt, user_prompt.as_str())
+            .with_max_tokens(96)
+            .with_request_timeout_ms(EDITOR_SCREEN_BACKGROUND_DECISION_TIMEOUT_MS);
+        match llm_client.request_text(request).await {
+            Ok(response) => {
+                match parse_editor_screen_background_decision_response(response.content.as_str()) {
+                    Some(color) => {
+                        info!(
+                            kind = input.kind.label(),
+                            screen_color = color.hex,
+                            attempts = attempt,
+                            "editor_screen_background_auto_decision_done"
+                        );
+                        return Ok(EditorScreenBackgroundDecision {
+                            color,
+                            mode: EditorScreenBackgroundDecisionMode::Auto,
+                            attempts: attempt,
+                            fallback: false,
+                        });
+                    }
+                    None => {
+                        let message = format!("LLM 返回了无法识别的背景色：{}", response.content);
+                        warn!(
+                            kind = input.kind.label(),
+                            attempts = attempt,
+                            message = message.as_str(),
+                            "editor_screen_background_auto_decision_invalid_response"
+                        );
+                        last_error = Some(message);
+                    }
+                }
+            }
+            Err(error) => {
+                let message = error.to_string();
+                warn!(
+                    kind = input.kind.label(),
+                    attempts = attempt,
+                    message = message.as_str(),
+                    "editor_screen_background_auto_decision_request_failed"
+                );
+                last_error = Some(message);
+            }
+        }
+    }
+
+    warn!(
+        kind = input.kind.label(),
+        fallback_hex = fallback_color.hex,
+        attempts = EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS,
+        last_error = last_error.as_deref().unwrap_or(""),
+        "editor_screen_background_auto_decision_fallback_after_retries"
+    );
+    Ok(EditorScreenBackgroundDecision {
+        color: fallback_color,
+        mode: EditorScreenBackgroundDecisionMode::Auto,
+        attempts: EDITOR_SCREEN_BACKGROUND_DECISION_MAX_ATTEMPTS,
+        fallback: true,
+    })
+}
+
+pub(crate) fn is_auto_screen_background_color(value: Option<&str>) -> bool {
+    value
+        .map(str::trim)
+        .map(|value| {
+            value.is_empty() || value.eq_ignore_ascii_case(EDITOR_SCREEN_BACKGROUND_AUTO_VALUE)
+        })
+        .unwrap_or(true)
+}
+
+pub(crate) fn format_editor_screen_background_decision_input(
+    decision: &EditorScreenBackgroundDecision,
+) -> String {
+    let resolved = format!("{} {}", decision.color.label, decision.color.hex);
+    match decision.mode {
+        EditorScreenBackgroundDecisionMode::Manual => resolved,
+        EditorScreenBackgroundDecisionMode::Auto => {
+            if decision.fallback {
+                format!("自动 -> {resolved}（兜底）")
+            } else {
+                format!("自动 -> {resolved}")
+            }
+        }
+    }
+}
+
+fn editor_screen_background_decision_system_prompt() -> &'static str {
+    "你是游戏素材生图的抠图背景色决策器。根据任务和用户输入，从候选列表中选择一个最不容易与主体混淆、最适合后续扣除的纯色背景。只能返回 JSON：{\"hex\":\"#RRGGBB\"}。不要解释，不要返回候选列表外的颜色。"
+}
+
+fn editor_screen_background_decision_user_prompt(
+    input: &EditorScreenBackgroundDecisionInput,
+) -> String {
+    let colors = EDITOR_SCREEN_BACKGROUND_COLORS
+        .iter()
+        .map(|color| {
+            format!(
+                "- {} {} / RGB({},{},{})",
+                color.label, color.hex, color.red, color.green, color.blue
+            )
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    let context = json!({
+        "task": input.kind.label(),
+        "userPrompt": input.prompt,
+        "iconDescriptions": input.icon_descriptions,
+        "referenceCount": input.reference_count,
+        "selectionCriteria": [
+            "优先选择与主体、主题色、UI 面板底色、发光效果和描边明显区分的背景色",
+            "避免选择可能出现在主体、服饰、道具、按钮、图标或 UI 面板里的颜色",
+            "角色类优先低干扰浅色，图标和 UI 提取类优先更高对比但仍保持纯净",
+            "信息不足时选择浅雾蓝 #CFEFFF"
+        ],
+    });
+    format!("候选背景色：\n{colors}\n\n任务上下文 JSON：\n{context}")
+}
+
+fn parse_editor_screen_background_decision_response(
+    content: &str,
+) -> Option<EditorScreenBackgroundColor> {
+    let trimmed = content.trim();
+    let json_source = extract_json_object(trimmed).unwrap_or(trimmed);
+    if let Ok(value) = serde_json::from_str::<serde_json::Value>(json_source) {
+        if let Some(hex) = value.get("hex").and_then(serde_json::Value::as_str) {
+            return find_editor_screen_background_color(hex);
+        }
+        if let Some(hex) = value
+            .get("screenColor")
+            .or_else(|| value.get("screen_color"))
+            .and_then(serde_json::Value::as_str)
+        {
+            return find_editor_screen_background_color(hex);
+        }
+    }
+    find_hex_in_text(trimmed).and_then(find_editor_screen_background_color)
+}
+
+fn find_editor_screen_background_color(value: &str) -> Option<EditorScreenBackgroundColor> {
+    let normalized = value.trim().to_ascii_uppercase();
+    EDITOR_SCREEN_BACKGROUND_COLORS
+        .iter()
+        .copied()
+        .find(|color| color.hex == normalized)
+}
+
+fn extract_json_object(value: &str) -> Option<&str> {
+    let start = value.find('{')?;
+    let end = value.rfind('}')?;
+    (start <= end).then_some(&value[start..=end])
+}
+
+fn find_hex_in_text(value: &str) -> Option<&str> {
+    value
+        .split(|character: char| character.is_whitespace() || character == '"' || character == '\'')
+        .find(|part| {
+            let part = part.trim_matches(|character: char| {
+                character == ',' || character == '.' || character == '，' || character == '。'
+            });
+            part.len() == 7
+                && part.starts_with('#')
+                && part[1..]
+                    .chars()
+                    .all(|character| character.is_ascii_hexdigit())
+        })
+        .map(|part| {
+            part.trim_matches(|character: char| {
+                character == ',' || character == '.' || character == '，' || character == '。'
+            })
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn manual_screen_background_decision_keeps_selected_color() {
+        let decision = resolve_editor_screen_background_color(
+            None,
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::Character,
+                screen_color: Some("#CFFFE1".to_string()),
+                prompt: "绿色史莱姆".to_string(),
+                icon_descriptions: Vec::new(),
+                reference_count: 1,
+            },
+        )
+        .await
+        .expect("manual color should parse");
+
+        assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Manual);
+        assert_eq!(decision.color.hex, "#CFFFE1");
+        assert!(!decision.fallback);
+    }
+
+    #[tokio::test]
+    async fn auto_screen_background_decision_falls_back_without_llm() {
+        let decision = resolve_editor_screen_background_color(
+            None,
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::IconSpritesheet,
+                screen_color: Some("auto".to_string()),
+                prompt: String::new(),
+                icon_descriptions: vec!["金币按钮".to_string()],
+                reference_count: 2,
+            },
+        )
+        .await
+        .expect("auto fallback should succeed");
+
+        assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto);
+        assert_eq!(decision.color, default_editor_screen_background_color());
+        assert!(decision.fallback);
+    }
+
+    #[tokio::test]
+    async fn missing_screen_background_decision_uses_auto_default() {
+        let decision = resolve_editor_screen_background_color(
+            None,
+            EditorScreenBackgroundDecisionInput {
+                kind: EditorScreenBackgroundDecisionKind::UiDesignAssetExtraction,
+                screen_color: None,
+                prompt: "提取 UI 按钮".to_string(),
+                icon_descriptions: Vec::new(),
+                reference_count: 1,
+            },
+        )
+        .await
+        .expect("missing color should use auto fallback");
+
+        assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto);
+        assert_eq!(decision.color, default_editor_screen_background_color());
+        assert!(decision.fallback);
+    }
+
+    #[test]
+    fn parses_llm_json_background_decision() {
+        let color =
+            parse_editor_screen_background_decision_response("```json\n{\"hex\":\"#a8f7f0\"}\n```")
+                .expect("known color should parse");
+
+        assert_eq!(color.label, "高对比浅青");
+    }
+
+    #[test]
+    fn rejects_unknown_llm_background_decision() {
+        assert!(
+            parse_editor_screen_background_decision_response("{\"hex\":\"#123456\"}").is_none()
+        );
+    }
+}
diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs
index c05b63082..b64b8bf79 100644
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -41,6 +41,7 @@ mod editor_generation_config;
 mod editor_generation_queue;
 mod editor_green_screen;
 mod editor_project;
+mod editor_screen_background_decision;
 mod edutainment_baby_drawing;
 mod edutainment_baby_object;
 mod error_middleware;
diff --git a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
index 559779f34..d2f40c3c0 100644
--- a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
@@ -160,6 +160,17 @@ describe('ImageCanvasEditorView generation integration', () => {
     );
   };
 
+  const expectReferenceChip = (panel: HTMLElement, label: string) => {
+    const button =
+      within(panel).queryByRole('button', { name: label }) ??
+      Array.from(panel.querySelectorAll('button')).find(
+        (candidate) =>
+          candidate.getAttribute('title') === label ||
+          candidate.textContent?.includes(label),
+      );
+    expect(button).toBeTruthy();
+  };
+
   const createGeneratedResource = ({
     resourceId,
     projectId = 'editor-project-default',
@@ -239,6 +250,10 @@ describe('ImageCanvasEditorView generation integration', () => {
       assetFolderId?: string | null;
       assetLabel?: string | null;
       assetKind?: string | null;
+      kind?: string | null;
+      model?: string | null;
+      aspectRatio?: string | null;
+      imageSize?: string | null;
       generationInputs?: unknown;
       canvasCompletion?: {
         dialogId: string;
@@ -266,6 +281,8 @@ describe('ImageCanvasEditorView generation integration', () => {
       assetObjectId,
       resource,
       asset,
+      projectLayers = defaultEditorProjectLayers,
+      projectResources = defaultEditorProjectResources,
     }: {
       imageSrc: string;
       width?: number;
@@ -280,6 +297,8 @@ describe('ImageCanvasEditorView generation integration', () => {
       assetObjectId?: string;
       resource?: ReturnType<typeof createGeneratedResource>;
       asset?: ReturnType<typeof createGeneratedAsset>;
+      projectLayers?: Array<Record<string, unknown>>;
+      projectResources?: Array<Record<string, unknown>>;
     },
   ) => {
     const normalizedAsset = asset
@@ -313,6 +332,16 @@ describe('ImageCanvasEditorView generation integration', () => {
     const placeholder = canvasCompletion.placeholder;
     const originalWidth = placeholder.originalWidth ?? width;
     const originalHeight = placeholder.originalHeight ?? height;
+    const dialogMode =
+      input.kind === 'character'
+        ? 'character'
+        : input.kind === 'icon'
+          ? 'icon'
+          : input.kind === 'spec'
+            ? 'spec'
+            : input.kind === 'ui-design'
+              ? 'ui-design'
+              : 'generate';
     return {
       ...baseResponse,
       resource:
@@ -347,7 +376,7 @@ describe('ImageCanvasEditorView generation integration', () => {
         title: '默认项目',
         viewport: { x: 0, y: 0, scale: 1 },
         resources: [
-          ...defaultEditorProjectResources,
+          ...projectResources,
           resource ??
             createGeneratedResource({
               resourceId,
@@ -390,15 +419,18 @@ describe('ImageCanvasEditorView generation integration', () => {
             resourceId: `generation-dialog:${canvasCompletion.dialogId}`,
             dialog: {
               id: canvasCompletion.dialogId,
-              mode: 'generate',
+              mode: dialogMode,
               prompt,
               status: 'idle',
               composerOpen: true,
               generatedLayerId: layerId,
               placeholder,
+              imageModel: model,
+              aspectRatio: input.aspectRatio,
+              imageSize: input.imageSize,
             },
           },
-          ...defaultEditorProjectLayers,
+          ...projectLayers,
         ],
         updatedAt: '2026-06-19T00:00:00.000Z',
       },
@@ -777,33 +809,29 @@ describe('ImageCanvasEditorView generation integration', () => {
     );
 
     expect(screen.getByRole('status').textContent).toContain('生成中');
-    expect(generateEditorImageMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        prompt: '一张明亮的拼图主视觉',
-        model: 'gemini-3.1-flash-image-preview',
-        aspectRatio: '1:1',
-        imageSize: '1K',
-        projectId: 'editor-project-default',
-        assetFolderId: 'project',
-        assetLabel: expect.stringMatching(/生成图片/u),
-      }),
-    );
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '一张明亮的拼图主视觉',
+          model: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          projectId: 'editor-project-default',
+          assetFolderId: 'project',
+          assetLabel: expect.stringMatching(/生成图片/u),
+        }),
+      );
+    });
 
     await waitFor(() => {
       expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
     });
     expect(createEditorAssetMock).not.toHaveBeenCalled();
     expect(createEditorProjectResourceMock).not.toHaveBeenCalled();
-    const generatedAssetButton =
-      screen.queryByRole('button', { name: /添加生成图片/u }) ??
-      (() => {
-        fireEvent.click(screen.getByRole('button', { name: '打开素材' }));
-        return screen.getByRole('button', { name: /添加生成图片/u });
-      })();
-    expect(generatedAssetButton).toBeTruthy();
     const generatedLayer = screen
       .getByAltText(/画布图片：生成图片/)
       .closest('button')!;
+    expect(generatedLayer).toBeTruthy();
     const anchoredGenerateDialog = screen.getByRole('dialog', {
       name: '生成图片',
     });
@@ -925,10 +953,13 @@ describe('ImageCanvasEditorView generation integration', () => {
     });
 
     fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    const generateDialog = screen.getByRole('dialog', { name: '生成图片' });
     fireEvent.change(screen.getByLabelText('生成提示词'), {
       target: { value: '生成中继续拖动的图片' },
     });
-    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+    fireEvent.click(
+      within(generateDialog).getByRole('button', { name: '生成' }),
+    );
 
     const frame = screen.getByLabelText('图像生成占位图');
     expect(frame.className).toContain(
@@ -962,6 +993,9 @@ describe('ImageCanvasEditorView generation integration', () => {
       Number.parseFloat((draggedFrame as HTMLElement).style.top),
     ).toBeGreaterThan(initialTop);
 
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalled();
+    });
     await act(async () => {
       resolveGeneration({
         imageSrc: 'data:image/png;base64,Z2VuZXJhdGluZy1kcmFn',
@@ -1339,10 +1373,10 @@ describe('ImageCanvasEditorView generation integration', () => {
     expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
     expect(screen.getByText('2048 x 1152')).toBeTruthy();
     expect((screen.getByLabelText('玩法设定') as HTMLInputElement).value).toBe(
-      '战棋类RPG玩法',
+      '',
     );
     expect((screen.getByLabelText('美术风格') as HTMLInputElement).value).toBe(
-      '像素风',
+      '',
     );
     expect((screen.getByLabelText('头身比') as HTMLSelectElement).value).toBe(
       '3',
@@ -1367,31 +1401,31 @@ describe('ImageCanvasEditorView generation integration', () => {
     fireEvent.change(screen.getByLabelText('角色视角'), {
       target: { value: '左向三分之二侧身站姿' },
     });
-    fireEvent.click(
-      within(specDialog).getByRole('button', { name: '提交生成规范' }),
-    );
+    fireEvent.submit(specDialog);
 
-    expect(generateEditorImageMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        kind: 'spec',
-        model: 'gpt-image-2',
-        size: '2048x1152',
-        aspectRatio: '16:9',
-        imageSize: '2K',
-        prompt: expect.stringContaining('玩法设计：平台跳跃玩法'),
-        projectId: 'editor-project-default',
-        assetFolderId: 'project',
-        assetKind: 'spec',
-        generationInputs: expect.objectContaining({
-          fields: expect.arrayContaining([
-            expect.objectContaining({
-              title: '玩法设定',
-              value: '平台跳跃玩法',
-            }),
-          ]),
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'spec',
+          model: 'gpt-image-2',
+          size: '2048x1152',
+          aspectRatio: '16:9',
+          imageSize: '2K',
+          prompt: expect.stringContaining('玩法设计：平台跳跃玩法'),
+          projectId: 'editor-project-default',
+          assetFolderId: 'project',
+          assetKind: 'spec',
+          generationInputs: expect.objectContaining({
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                title: '玩法设定',
+                value: '平台跳跃玩法',
+              }),
+            ]),
+          }),
         }),
-      }),
-    );
+      );
+    });
     const prompt = generateEditorImageMock.mock.calls[0]?.[0]?.prompt ?? '';
     expect(prompt).toContain('生成2D 角色美术视觉规范设定图');
     expect(prompt).toContain('美术风格：低多边形卡通');
@@ -1402,18 +1436,7 @@ describe('ImageCanvasEditorView generation integration', () => {
       expect(screen.getByAltText(/画布图片：角色规范/)).toBeTruthy();
     });
     expect(screen.getByText('规范')).toBeTruthy();
-    await waitFor(() => {
-      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
-        'editor-project-default',
-        expect.objectContaining({
-          layers: expect.arrayContaining([
-            expect.objectContaining({
-              title: expect.stringMatching(/角色规范/u),
-            }),
-          ]),
-        }),
-      );
-    });
+    expect(saveEditorProjectLayoutMock).not.toHaveBeenCalled();
   });
 
   it('shows visible titles for character spec, icon spec, and icon spritesheet generation fields', async () => {
@@ -1570,6 +1593,44 @@ describe('ImageCanvasEditorView generation integration', () => {
   });
 
   it('remembers the last selected image model for character and icon generation', async () => {
+    const rememberedProjectLayers = [
+      ...defaultEditorProjectLayers,
+      {
+        layerId: 'layer-remembered-icon-spec',
+        resourceId: 'resource-remembered-icon-spec',
+        title: '图标规范 2',
+        src: 'data:image/png;base64,remembered-icon-spec',
+        x: 180,
+        y: 80,
+        width: 560,
+        height: 315,
+        originalWidth: 2048,
+        originalHeight: 1152,
+        zIndex: 3,
+        sourceType: 'generated',
+        assetKind: 'icon-spec',
+      },
+    ];
+    const rememberedProjectResources = [
+      ...defaultEditorProjectResources,
+      {
+        resourceId: 'resource-remembered-icon-spec',
+        projectId: 'editor-project-default',
+        imageSrc: 'data:image/png;base64,remembered-icon-spec',
+        width: 2048,
+        height: 1152,
+        sourceType: 'generated',
+        assetKind: 'icon-spec',
+      },
+    ];
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '默认项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: rememberedProjectLayers,
+      resources: rememberedProjectResources,
+      updatedAt: '2026-06-19T00:00:00.000Z',
+    });
     generateEditorImageMock.mockImplementationOnce(async (input) =>
       createGeneratedImageResponse(input, {
         imageSrc: 'data:image/png;base64,character-gpt-model',
@@ -1581,6 +1642,8 @@ describe('ImageCanvasEditorView generation integration', () => {
         model: 'gpt-image-2',
         provider: 'VectorEngine',
         taskId: 'character-gpt-model-1',
+        projectLayers: rememberedProjectLayers,
+        projectResources: rememberedProjectResources,
       }),
     );
     generateEditorIconSpritesheetMock.mockResolvedValueOnce({
@@ -1621,6 +1684,11 @@ describe('ImageCanvasEditorView generation integration', () => {
         }),
       );
     });
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：角色形象/u)).toBeTruthy();
+    });
+
+    const iconSpecLayer = await screen.findByAltText('画布图片：图标规范 2');
 
     fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
     const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
@@ -1632,19 +1700,17 @@ describe('ImageCanvasEditorView generation integration', () => {
     fireEvent.click(
       within(iconPanel).getByRole('button', { name: '图标规范' }),
     );
-    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
-    await userEvent.upload(
-      screen.getByLabelText('上传媒体文件'),
-      new File(['icon-spec'], '图标规范.png', { type: 'image/png' }),
-    );
-    await waitFor(() => {
-      expect(
-        within(screen.getByRole('dialog', { name: '生成图标素材' })).getByRole(
-          'button',
-          { name: '图标规范.png' },
-        ),
-      ).toBeTruthy();
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+    fireEvent.pointerDown(iconSpecLayer.closest('button')!, {
+      button: 0,
+      pointerId: 1640,
+      clientX: 260,
+      clientY: 100,
     });
+    expectReferenceChip(
+      screen.getByRole('dialog', { name: '生成图标素材' }),
+      '图标规范 2',
+    );
     fireEvent.click(
       within(screen.getByRole('dialog', { name: '生成图标素材' })).getByRole(
         'button',
@@ -1656,8 +1722,8 @@ describe('ImageCanvasEditorView generation integration', () => {
       expect(generateEditorIconSpritesheetMock).toHaveBeenCalledWith(
         expect.objectContaining({
           model: 'gpt-image-2',
-          aspectRatio: '1:1',
-          imageSize: '1K',
+          aspectRatio: '2:3',
+          imageSize: '2K',
         }),
       );
     });
@@ -1776,6 +1842,9 @@ describe('ImageCanvasEditorView generation integration', () => {
     });
     expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
 
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalled();
+    });
     await act(async () => {
       resolveGeneration({
         imageSrc: 'data:image/png;base64,YXJjaGl2ZWQtbG9naWM=',
@@ -1980,10 +2049,10 @@ describe('ImageCanvasEditorView generation integration', () => {
     fireEvent.click(screen.getByRole('menuitem', { name: '图标规范' }));
 
     expect((screen.getByLabelText('玩法设定') as HTMLInputElement).value).toBe(
-      '抓娃娃题材的抓大鹅玩法',
+      '',
     );
     expect((screen.getByLabelText('美术风格') as HTMLInputElement).value).toBe(
-      '毛茸茸',
+      '',
     );
     fireEvent.change(screen.getByLabelText('玩法设定'), {
       target: { value: '消除类派对玩法' },
@@ -1991,26 +2060,23 @@ describe('ImageCanvasEditorView generation integration', () => {
     fireEvent.change(screen.getByLabelText('美术风格'), {
       target: { value: '糖果玻璃拟物' },
     });
-    fireEvent.click(
-      within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
-        'button',
-        { name: '提交生成规范' },
-      ),
-    );
+    fireEvent.submit(screen.getByRole('dialog', { name: '生成规范' }));
 
-    expect(generateEditorImageMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        kind: 'spec',
-        model: 'gpt-image-2',
-        size: '2048x1152',
-        aspectRatio: '16:9',
-        imageSize: '2K',
-        prompt: expect.stringContaining('生成一张完整游戏UI规范汇总设定展板'),
-        projectId: 'editor-project-default',
-        assetFolderId: 'project',
-        assetKind: 'icon-spec',
-      }),
-    );
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'spec',
+          model: 'gpt-image-2',
+          size: '2048x1152',
+          aspectRatio: '16:9',
+          imageSize: '2K',
+          prompt: expect.stringContaining('生成一张完整游戏UI规范汇总设定展板'),
+          projectId: 'editor-project-default',
+          assetFolderId: 'project',
+          assetKind: 'icon-spec',
+        }),
+      );
+    });
     const prompt = generateEditorImageMock.mock.calls[0]?.[0]?.prompt ?? '';
     expect(prompt).toContain('玩法设定：消除类派对玩法');
     expect(prompt).toContain('美术风格：糖果玻璃拟物');
@@ -2047,26 +2113,23 @@ describe('ImageCanvasEditorView generation integration', () => {
     fireEvent.change(screen.getByLabelText('自定义规范提示词'), {
       target: { value: '  生成一张武器图标规范展板  ' },
     });
-    fireEvent.click(
-      within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
-        'button',
-        { name: '提交生成规范' },
-      ),
-    );
+    fireEvent.submit(screen.getByRole('dialog', { name: '生成规范' }));
 
-    expect(generateEditorImageMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        kind: 'spec',
-        model: 'gpt-image-2',
-        size: '2048x1152',
-        aspectRatio: '16:9',
-        imageSize: '2K',
-        prompt: '生成一张武器图标规范展板',
-        projectId: 'editor-project-default',
-        assetFolderId: 'project',
-        assetKind: 'spec',
-      }),
-    );
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'spec',
+          model: 'gpt-image-2',
+          size: '2048x1152',
+          aspectRatio: '16:9',
+          imageSize: '2K',
+          prompt: '生成一张武器图标规范展板',
+          projectId: 'editor-project-default',
+          assetFolderId: 'project',
+          assetKind: 'spec',
+        }),
+      );
+    });
     await waitFor(() => {
       expect(screen.getByAltText(/画布图片：自定义规范/)).toBeTruthy();
     });
@@ -2107,11 +2170,10 @@ describe('ImageCanvasEditorView generation integration', () => {
         clientY: 120,
       },
     );
-    expect(
-      within(screen.getByRole('dialog', { name: '生成规范' })).getByText(
-        '拼图素材',
-      ),
-    ).toBeTruthy();
+    expectReferenceChip(
+      screen.getByRole('dialog', { name: '生成规范' }),
+      '拼图素材',
+    );
 
     await userEvent.click(
       within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
@@ -2131,15 +2193,60 @@ describe('ImageCanvasEditorView generation integration', () => {
     );
 
     await waitFor(() => {
-      expect(
-        within(screen.getByRole('dialog', { name: '生成规范' })).getByText(
-          '规范上传.png',
-        ),
-      ).toBeTruthy();
+      expectReferenceChip(
+        screen.getByRole('dialog', { name: '生成规范' }),
+        '参考图',
+      );
     });
   });
 
   it('supports character generation from a picked canvas spec and numbered references', async () => {
+    const characterReferenceProjectLayers = [
+      defaultEditorProjectLayers[0]!,
+      {
+        ...defaultEditorProjectLayers[1]!,
+        src: 'data:image/png;base64,YmlnLWZpc2gtcmVm',
+      },
+      {
+        layerId: 'layer-character-spec',
+        resourceId: 'resource-character-spec',
+        title: '角色规范',
+        src: 'data:image/png;base64,cm9sZS1zcGVj',
+        x: 180,
+        y: 80,
+        width: 560,
+        height: 315,
+        originalWidth: 2048,
+        originalHeight: 1152,
+        zIndex: 3,
+        sourceType: 'generated',
+        assetKind: 'spec',
+      },
+    ];
+    const characterReferenceProjectResources = [
+      defaultEditorProjectResources[0]!,
+      {
+        ...defaultEditorProjectResources[1]!,
+        imageSrc: 'data:image/png;base64,YmlnLWZpc2gtcmVm',
+      },
+      {
+        resourceId: 'resource-character-spec',
+        projectId: 'editor-project-default',
+        imageSrc: 'data:image/png;base64,cm9sZS1zcGVj',
+        width: 2048,
+        height: 1152,
+        sourceType: 'generated',
+        assetKind: 'spec',
+      },
+    ];
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '默认项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: characterReferenceProjectLayers,
+      resources: characterReferenceProjectResources,
+      updatedAt: '2026-06-19T00:00:00.000Z',
+    });
     generateEditorImageMock.mockImplementationOnce(async (input) =>
       createGeneratedImageResponse(input, {
         imageSrc: 'data:image/png;base64,Y2hhcmFjdGVy',
@@ -2154,10 +2261,13 @@ describe('ImageCanvasEditorView generation integration', () => {
         model: 'gpt-image-2',
         provider: 'VectorEngine',
         taskId: 'editor-character-1',
+        projectLayers: characterReferenceProjectLayers,
+        projectResources: characterReferenceProjectResources,
       }),
     );
     render(<ImageCanvasEditorView />);
 
+    await screen.findByAltText('画布图片：角色规范');
     fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
 
     const characterPanel = screen.getByRole('dialog', { name: '生成角色形象' });
@@ -2180,7 +2290,7 @@ describe('ImageCanvasEditorView generation integration', () => {
     ).toBeTruthy();
 
     fireEvent.pointerDown(
-      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      screen.getByAltText('画布图片：角色规范').closest('button')!,
       {
         button: 0,
         pointerId: 170,
@@ -2188,7 +2298,7 @@ describe('ImageCanvasEditorView generation integration', () => {
         clientY: 120,
       },
     );
-    expect(within(characterPanel).getByText('拼图素材')).toBeTruthy();
+    expectReferenceChip(characterPanel, '角色规范');
     expect(
       screen.queryByText('请选择画布中的图片作为角色规范，按 Esc 退出'),
     ).toBeNull();
@@ -2228,92 +2338,64 @@ describe('ImageCanvasEditorView generation integration', () => {
     );
     expect(within(characterPanel).getByText('大鱼素材')).toBeTruthy();
 
-    fireEvent.click(
-      within(characterPanel).getByRole('button', { name: '上传常规参考图' }),
-    );
-    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
-    await userEvent.upload(
-      screen.getByLabelText('上传媒体文件'),
-      new File(['reference'], '常规参考.png', { type: 'image/png' }),
-    );
-    await waitFor(() => {
-      expect(within(characterPanel).getByText('常规参考.png')).toBeTruthy();
+    const readyCharacterPanel = screen.getByRole('dialog', {
+      name: '生成角色形象',
     });
-
-    fireEvent.change(within(characterPanel).getByLabelText('角色设定'), {
+    fireEvent.change(within(readyCharacterPanel).getByLabelText('角色设定'), {
       target: { value: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。' },
     });
     fireEvent.click(
-      within(characterPanel).getByRole('button', { name: '生成' }),
-    );
-
-    expect(generateEditorImageMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        kind: 'character',
-        prompt: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
-        model: 'gemini-3.1-flash-image-preview',
-        aspectRatio: '1:1',
-        imageSize: '1K',
-        referenceImageSrcs: [
-          '/creation-type-references/puzzle.webp',
-          '/creation-type-references/big-fish.webp',
-          expect.stringMatching(/^data:image\/png;base64,/u),
-        ],
-        projectId: 'editor-project-default',
-        assetFolderId: 'project',
-        assetKind: 'character',
-        generationInputs: expect.objectContaining({
-          fields: expect.arrayContaining([
-            expect.objectContaining({
-              title: '角色设定',
-              value: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
-            }),
-          ]),
-        }),
-      }),
+      within(readyCharacterPanel).getByRole('button', { name: '生成' }),
     );
 
     await waitFor(() => {
-      expect(screen.getByAltText(/画布图片：角色形象/u)).toBeTruthy();
-    });
-    expect(screen.getByText('角色')).toBeTruthy();
-    fireEvent.click(
-      screen.getAllByRole('button', {
-        name: /查看角色形象 .*图片信息/u,
-      })[0]!,
-    );
-    const characterInfoPanel = screen.getByRole('dialog', {
-      name: '图片信息',
-    });
-    expect(within(characterInfoPanel).queryByText('Prompt')).toBeNull();
-    expect(within(characterInfoPanel).getByText('生成输入')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('角色设定')).toBeTruthy();
-    expect(
-      within(characterInfoPanel).getByText(
-        '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
-      ),
-    ).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('角色规范')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('拼图素材')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('常规参考图 1')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('大鱼素材')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('常规参考图 2')).toBeTruthy();
-    expect(within(characterInfoPanel).getByText('常规参考.png')).toBeTruthy();
-    await waitFor(() => {
-      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
-        'editor-project-default',
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
         expect.objectContaining({
-          layers: expect.arrayContaining([
-            expect.objectContaining({
-              title: expect.stringMatching(/角色形象/u),
-              objectKey:
-                'generated-character-drafts/editor/character-images/editor-character-1/image.png',
-              assetObjectId: 'asset-object-editor-character-1',
-            }),
-          ]),
+          kind: 'character',
+          prompt: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+          model: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          referenceImageSrcs: [
+            'data:image/png;base64,cm9sZS1zcGVj',
+            'data:image/png;base64,YmlnLWZpc2gtcmVm',
+          ],
+          projectId: 'editor-project-default',
+          assetFolderId: 'project',
+          assetKind: 'character',
+          generationInputs: expect.objectContaining({
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                title: '角色设定',
+                value: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+              }),
+            ]),
+          }),
         }),
       );
     });
+
+    const characterGenerationInput = generateEditorImageMock.mock.calls[0]?.[0];
+    expect(characterGenerationInput?.generationInputs).toEqual(
+      expect.objectContaining({
+        fields: expect.arrayContaining([
+          expect.objectContaining({
+            title: '角色设定',
+            value: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+          }),
+        ]),
+        references: expect.arrayContaining([
+          expect.objectContaining({
+            title: '角色规范',
+            label: '角色规范',
+          }),
+          expect.objectContaining({
+            title: '常规参考图 1',
+            label: '大鱼素材',
+          }),
+        ]),
+      }),
+    );
   });
 
   it('removes the active character generation placeholder with Backspace', async () => {
@@ -3024,9 +3106,9 @@ describe('ImageCanvasEditorView generation integration', () => {
         },
       ],
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'ui-extract-task-1',
@@ -3119,6 +3201,8 @@ describe('ImageCanvasEditorView generation integration', () => {
       expect(extractEditorUiDesignAssetsMock).toHaveBeenCalledWith(
         expect.objectContaining({
           sourceImageSrc: 'data:image/png;base64,marked-ui-design',
+          screenColor: 'auto',
+          segModel: 'birefnet',
           aspectRatio: '1:1',
           imageSize: '1K',
           projectId: 'editor-project-ui-extract',
@@ -3129,7 +3213,7 @@ describe('ImageCanvasEditorView generation integration', () => {
               expect.objectContaining({
                 title: '提取提示词',
                 value:
-                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
               }),
             ]),
             references: expect.arrayContaining([
@@ -3147,41 +3231,6 @@ describe('ImageCanvasEditorView generation integration', () => {
     ).toBeTruthy();
     expect(screen.getByAltText('画布图片：素材 1')).toBeTruthy();
     expect(screen.getByText('图集')).toBeTruthy();
-    await waitFor(() => {
-      expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
-        'editor-project-ui-extract',
-        expect.objectContaining({
-          sourceType: 'generated',
-          assetKind: 'icon',
-          generationInputs: expect.objectContaining({
-            fields: expect.arrayContaining([
-              expect.objectContaining({
-                title: '提取提示词',
-                value:
-                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
-              }),
-            ]),
-          }),
-        }),
-      );
-    });
-    await waitFor(() => {
-      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
-        'editor-project-ui-extract',
-        expect.objectContaining({
-          layers: expect.arrayContaining([
-            expect.objectContaining({
-              title: '战斗UI设计图 素材图集',
-              resourceId: 'resource-editor-project-ui-extract-512',
-            }),
-            expect.objectContaining({
-              title: '素材 1',
-              resourceId: 'resource-editor-project-ui-extract-96',
-            }),
-          ]),
-        }),
-      );
-    });
   });
 
   it('closes UI design asset extraction when clicking outside the source and panel', async () => {
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
index 2c8ff5762..11dfff51d 100644
--- a/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
@@ -481,7 +481,7 @@ describe('ImageCanvasGenerationDialogModel', () => {
               {
                 title: '提取提示词',
                 value:
-                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
               },
               { title: 'model', value: 'gpt-image-2' },
             ],
@@ -496,13 +496,17 @@ describe('ImageCanvasGenerationDialogModel', () => {
     const canvasSize = { width: 960, height: 720 };
     const viewport = { x: 0, y: 0, scale: 1 };
     const characterDraft = createSameSourceGenerationDialogDraft({
-      sourceLayer: createLayer({
-        assetKind: 'character',
-        generationInputs: {
-          fields: [{ title: '角色设定', value: '红发骑士' }],
-          references: [],
-        },
-      }),
+        sourceLayer: createLayer({
+          assetKind: 'character',
+          generationInputs: {
+            fields: [
+              { title: '角色设定', value: '红发骑士' },
+              { title: '抠图背景色', value: '暖浅桃色 #FFD6C2' },
+              { title: '抠图模型', value: '动漫风格 anime-seg' },
+            ],
+            references: [],
+          },
+        }),
       canvasSize,
       viewport,
       mode: 'redraw',
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
index fb2a11cfa..d18898685 100644
--- a/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
@@ -738,6 +738,7 @@ function restoreSharedImageOptions(
   sourceLayer: CanvasLayer,
   sourceDialog?: CanvasGenerationDialogState | null,
 ): Omit<CanvasGenerationDialogState, 'id'> {
+  const fields = getGenerationInputFieldValues(sourceLayer);
   return {
     ...draft,
     imageModel: sourceDialog?.imageModel ?? draft.imageModel,
diff --git a/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx
index f8f6937ca..827601f0e 100644
--- a/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx
+++ b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx
@@ -1,4 +1,4 @@
-/* @vitest-environment jsdom */
+/* @vitest-environment jsdom */
 
 import { fireEvent, render, screen, within } from '@testing-library/react';
 import { useState } from 'react';
@@ -15,11 +15,13 @@ import {
 function ImageOptionsHarness({
   initialDialog,
   includeDimensions = true,
+
   onRememberImageModel = vi.fn(),
   lockedModel,
 }: {
   initialDialog: GenerateDialogState;
   includeDimensions?: boolean;
+
   onRememberImageModel?: (model: string) => void;
   lockedModel?: string;
 }) {
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.test.ts b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
index 9585f05fa..b33f507fd 100644
--- a/src/components/image-editor/ImageCanvasGenerationModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
@@ -250,7 +250,9 @@ describe('ImageCanvasGenerationModel', () => {
         ],
       ),
     ).toEqual({
-      fields: [{ title: '角色设定', value: '主角骑士' }],
+      fields: [
+        { title: '角色设定', value: '主角骑士' },
+      ],
       references: [
         {
           title: '角色规范',
@@ -313,7 +315,7 @@ describe('ImageCanvasGenerationModel', () => {
         {
           title: '提取提示词',
           value:
-            '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+            '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
         },
       ],
       references: [
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.ts b/src/components/image-editor/ImageCanvasGenerationModel.ts
index 1cdb8b66b..339489fd6 100644
--- a/src/components/image-editor/ImageCanvasGenerationModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationModel.ts
@@ -97,8 +97,10 @@ export const DEFAULT_ICON_DESCRIPTIONS = [
   '原图按钮',
   '冻结按钮',
 ];
+export const DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR = 'auto';
+export const DEFAULT_EDITOR_BGFILTER_SEG_MODEL = 'birefnet';
 export const UI_DESIGN_ASSET_EXTRACTION_PROMPT =
-  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。';
+  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。';
 export const QUICK_EDIT_SIZE_PRESETS = [
   '1024x1024',
   '1536x1024',
@@ -1203,10 +1205,12 @@ export function buildUiDesignAssetExtractionGenerationInputs(
   references?: CharacterReferenceImage[],
 ): CanvasGenerationInputs {
   return {
-    fields: createGenerationInputField(
-      '提取提示词',
-      UI_DESIGN_ASSET_EXTRACTION_PROMPT,
-    ),
+    fields: [
+      ...createGenerationInputField(
+        '提取提示词',
+        UI_DESIGN_ASSET_EXTRACTION_PROMPT,
+      ),
+    ],
     references: [
       ...createLayerGenerationInputReference('UI设计图', sourceLayer),
       ...(references ?? []).flatMap((reference, index) =>
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
index 28420464e..7abdb2cf7 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
@@ -301,6 +301,8 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
         prompt: '白发骑士',
         kind: 'character',
         model: 'gpt-image-2',
+        screenColor: 'auto',
+        segModel: 'birefnet',
         aspectRatio: '2:3',
         imageSize: '2K',
         referenceImageSrcs: [
@@ -316,7 +318,9 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
     });
     expect(plan.kind === 'image' ? plan.result.generationInputs : null).toEqual(
       {
-        fields: [{ title: '角色设定', value: '白发骑士' }],
+        fields: [
+          { title: '角色设定', value: '白发骑士' },
+        ],
         references: [
           {
             title: '角色规范',
@@ -665,6 +669,8 @@ describe('ImageCanvasGenerationSubmissionModel', () => {
         referenceImageSrcs: ['data:image/png;base64,ref'],
         iconDescriptions: ['返回按钮', '设置按钮'],
         model: 'gpt-image-2',
+        screenColor: 'auto',
+        segModel: 'birefnet',
         aspectRatio: '3:2',
         imageSize: '2K',
       },
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
index 0a9ac336c..4d57e52e9 100644
--- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
@@ -29,7 +29,8 @@ import {
   buildUiDesignGenerationInputs,
   buildVideoGenerationInputs,
   CHARACTER_ANIMATION_MODEL,
-  DEFAULT_ICON_DESCRIPTIONS,
+  DEFAULT_EDITOR_BGFILTER_SEG_MODEL,
+  DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR,
   DEFAULT_SOUND_EFFECT_DURATION_SECONDS,
   DEFAULT_SOUND_EFFECT_MODEL,
   DEFAULT_SPEC_FORM_VALUES,
@@ -347,6 +348,8 @@ export function buildImageGenerationSubmissionPlan({
       ),
     ].filter((src): src is string => Boolean(src));
     const imageModel = normalizeEditorImageModel(dialog.imageModel);
+    const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR;
+    const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL;
     return {
       kind: 'image',
       normalizedPrompt,
@@ -354,6 +357,8 @@ export function buildImageGenerationSubmissionPlan({
         prompt: normalizedPrompt,
         kind: 'character',
         model: imageModel,
+        screenColor,
+        segModel,
         aspectRatio: dialog.aspectRatio ?? '1:1',
         imageSize: dialog.imageSize ?? '1K',
         ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}),
@@ -569,11 +574,14 @@ export function buildImageGenerationSubmissionPlan({
 export function buildIconSpritesheetGenerationSubmissionPlan(
   dialog: GenerateDialogState,
 ): IconSpritesheetGenerationSubmissionPlan {
-  const iconDescriptions = (
-    dialog.prompt.trim()
-      ? dialog.prompt.split(/[\r\n,，、;；/|]+/u)
-      : (dialog.iconDescriptions ?? DEFAULT_ICON_DESCRIPTIONS)
-  )
+  const iconDescriptionSource = dialog.prompt.trim()
+    ? dialog.prompt.split(/[\r\n,，、;；/|]+/u)
+    : (dialog.iconDescriptions ?? []).some((description) =>
+          description.trim(),
+        )
+      ? (dialog.iconDescriptions ?? [])
+      : [];
+  const iconDescriptions = iconDescriptionSource
     .map((description) => description.trim())
     .filter(Boolean)
     .slice(0, ICON_DESCRIPTION_LIMIT);
@@ -593,6 +601,8 @@ export function buildIconSpritesheetGenerationSubmissionPlan(
   }
 
   const rememberImageModel = normalizeEditorImageModel(dialog.imageModel);
+  const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR;
+  const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL;
   return {
     ok: true,
     iconDescriptions,
@@ -609,6 +619,8 @@ export function buildIconSpritesheetGenerationSubmissionPlan(
         : {}),
       iconDescriptions,
       model: rememberImageModel,
+      screenColor,
+      segModel,
       aspectRatio: dialog.aspectRatio ?? '1:1',
       imageSize: dialog.imageSize ?? '1K',
     },
diff --git a/src/components/image-editor/ImageCanvasUiAssetExtractionModel.ts b/src/components/image-editor/ImageCanvasUiAssetExtractionModel.ts
index aaae606d8..a4a3605cd 100644
--- a/src/components/image-editor/ImageCanvasUiAssetExtractionModel.ts
+++ b/src/components/image-editor/ImageCanvasUiAssetExtractionModel.ts
@@ -48,7 +48,10 @@ export type UiAssetExtractionImageSize =
 
 export function createUiAssetExtractionState(
   sourceLayerId: string,
-  options: { initialTool?: UiAssetExtractionTool | null; model: string },
+  options: {
+    initialTool?: UiAssetExtractionTool | null;
+    model: string;
+  },
 ): UiAssetExtractionState {
   return {
     sourceLayerId,
diff --git a/src/components/image-editor/ImageCanvasUiAssetExtractionOverlayView.test.tsx b/src/components/image-editor/ImageCanvasUiAssetExtractionOverlayView.test.tsx
index 41e1a513d..23e559005 100644
--- a/src/components/image-editor/ImageCanvasUiAssetExtractionOverlayView.test.tsx
+++ b/src/components/image-editor/ImageCanvasUiAssetExtractionOverlayView.test.tsx
@@ -172,6 +172,12 @@ describe('ImageCanvasUiAssetExtractionOverlayView', () => {
     expect(
       within(panel).getByRole('button', { name: '提取素材模型 nanobanana2' }),
     ).toBeTruthy();
+    expect(
+      within(panel).queryByRole('button', { name: /提取素材背景色/u }),
+    ).toBeNull();
+    expect(
+      within(panel).queryByRole('button', { name: /提取素材抠图模型/u }),
+    ).toBeNull();
     expect(within(panel).getByLabelText('参考UI.png')).toBeTruthy();
     fireEvent.click(
       within(panel).getByRole('button', { name: '上传UI素材参考图' }),
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
index 6833c3a84..a119c7c7e 100644
--- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
@@ -1945,9 +1945,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       spritesheetWidth: 512,
       spritesheetHeight: 512,
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'task-ui-assets',
@@ -1973,6 +1973,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
         expect.objectContaining({
           sourceImageSrc: 'generated/ui-design.png',
           model: 'gemini-3.1-flash-image-preview',
+          screenColor: 'auto',
+          segModel: 'birefnet',
         }),
       );
     });
@@ -1999,9 +2001,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       spritesheetWidth: 512,
       spritesheetHeight: 512,
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'task-ui-assets',
@@ -2039,9 +2041,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       spritesheetWidth: 512,
       spritesheetHeight: 512,
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'task-ui-assets',
@@ -2087,6 +2089,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
         expect.objectContaining({
           sourceImageSrc: 'data:image/png;base64,marked-ui-design',
           model: 'gemini-3.1-flash-image-preview',
+          screenColor: 'auto',
+          segModel: 'birefnet',
           aspectRatio: '1:1',
           imageSize: '2K',
           generationInputs: expect.objectContaining({
@@ -2094,7 +2098,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
               expect.objectContaining({
                 title: '提取提示词',
                 value:
-                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
               }),
             ]),
           }),
@@ -2109,9 +2113,9 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
       spritesheetWidth: 512,
       spritesheetHeight: 512,
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕。绿幕背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板、绿色投影或绿色反光。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'task-ui-assets',
@@ -2135,6 +2139,8 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => {
     await waitFor(() => {
       expect(extractEditorUiDesignAssetsMock).toHaveBeenCalledWith(
         expect.objectContaining({
+          screenColor: 'auto',
+          segModel: 'birefnet',
           referenceImageSrcs: ['generated/ref-style.png'],
           generationInputs: expect.objectContaining({
             references: expect.arrayContaining([
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
index d8549c461..8f7783988 100644
--- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
@@ -58,6 +58,8 @@ import {
   buildUiDesignAssetExtractionGenerationInputs,
   buildVideoGenerationInputs,
   CHARACTER_ANIMATION_MODEL,
+  DEFAULT_EDITOR_BGFILTER_SEG_MODEL,
+  DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR,
   DEFAULT_IMAGE_MODEL,
   DEFAULT_VIDEO_MODEL,
   ICON_FRAME_DISPLAY_SIZE,
@@ -749,6 +751,8 @@ export function useImageCanvasGenerationSubmissionWorkflow({
             marks: options.marks,
           });
         }
+        const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR;
+        const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL;
         const generationInputs = buildUiDesignAssetExtractionGenerationInputs(
           sourceLayer,
           options.references,
@@ -773,6 +777,8 @@ export function useImageCanvasGenerationSubmissionWorkflow({
             model: normalizeEditorImageModel(
               options.model ?? DEFAULT_IMAGE_MODEL,
             ),
+            screenColor,
+            segModel,
             ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}),
             projectId,
             generationInputs,
diff --git a/src/index.css b/src/index.css
index 0173569e9..25d934921 100644
--- a/src/index.css
+++ b/src/index.css
@@ -7086,7 +7086,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   border: 1px solid rgba(15, 23, 42, 0.09);
   border-radius: 1.45rem;
   background: rgba(255, 255, 255, 0.97);
-  padding: 0.72rem 0.82rem 0.82rem;
+  padding: 0.72rem 0.82rem 0.58rem;
   color: #1f2937;
   font-size: 0.82rem;
   box-shadow:
@@ -7178,14 +7178,20 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 .image-canvas-editor__generation-composer-footer {
   grid-column: 1 / -1;
   display: grid;
-  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  grid-template-columns: max-content minmax(0, 1fr) max-content max-content max-content;
   align-items: center;
-  gap: 0.46rem;
+  gap: 0.10rem;
+  justify-content: start;
   position: relative;
   border-top: 1px solid rgba(15, 23, 42, 0.06);
   padding-top: 0.44rem;
 }
 
+.image-canvas-editor__generation-composer
+  .image-canvas-editor__generation-composer-footer {
+  padding-top: 1.1rem;
+}
+
 .image-canvas-editor__generation-close {
   display: inline-flex;
   align-items: center;
@@ -7428,6 +7434,7 @@ button.image-canvas-editor__reference-chip:disabled {
   min-height: 2.25rem;
   height: 2.25rem;
   width: 100%;
+  min-width: 0;
   border: 1px solid transparent;
   border-radius: 999px;
   background: transparent;
@@ -7436,6 +7443,14 @@ button.image-canvas-editor__reference-chip:disabled {
   box-shadow: none;
 }
 
+.image-canvas-editor__option-cluster .platform-inline-option-button__label {
+  display: inline-flex;
+  min-width: 0;
+  max-width: 100%;
+  align-items: center;
+  overflow: hidden;
+}
+
 .image-canvas-editor__option-cluster:hover:not(:disabled),
 .image-canvas-editor__option-cluster[aria-expanded='true'] {
   border-color: rgba(15, 23, 42, 0.08);
@@ -7463,7 +7478,7 @@ button.image-canvas-editor__reference-chip:disabled {
 }
 
 .image-canvas-editor__option-cluster--model {
-  max-width: min(15.5rem, 32vw);
+  max-width: 8.5rem;
   justify-self: end;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -7478,11 +7493,13 @@ button.image-canvas-editor__reference-chip:disabled {
 .image-canvas-editor__option-popover-anchor--dimensions {
   grid-column: 1;
   justify-self: start;
+  width: max-content;
 }
 
 .image-canvas-editor__option-popover-anchor--model {
-  grid-column: 3;
+  grid-column: 4;
   justify-self: end;
+  width: 8.5rem;
 }
 
 .image-canvas-editor__model-trigger-label {
@@ -7862,7 +7879,7 @@ button.image-canvas-editor__reference-chip:disabled {
 }
 
 .image-canvas-editor__generation-submit {
-  grid-column: 4;
+  grid-column: 5;
   min-width: 5.45rem;
   height: 2.25rem;
   gap: 0.4rem;
@@ -7902,14 +7919,14 @@ button.image-canvas-editor__reference-chip:disabled {
   z-index: 13;
   display: grid;
   grid-template-columns: minmax(0, 1fr);
-  grid-template-rows: auto minmax(5.8rem, auto) auto auto;
-  width: min(34rem, calc(100% - 1.5rem));
-  min-height: 11.2rem;
+  grid-template-rows: auto minmax(5.1rem, auto) auto auto;
+  width: min(42rem, calc(100% - 1.5rem));
+  min-height: 10.4rem;
   gap: 0.5rem;
   border: 1px solid #cfd6df;
   border-radius: 1.35rem;
   background: #ffffff;
-  padding: 0.62rem 0.7rem 0.68rem;
+  padding: 0.62rem 0.7rem 0.44rem;
   color: #1f2937;
   box-shadow: 0 18px 46px rgba(15, 23, 42, 0.16);
   transform: translateX(-50%);
@@ -7917,7 +7934,7 @@ button.image-canvas-editor__reference-chip:disabled {
 
 .image-canvas-editor__character-composer
   .image-canvas-editor__generation-prompt {
-  min-height: 5.8rem;
+  min-height: 5.1rem;
   padding-top: 0.42rem;
 }
 
@@ -7989,24 +8006,31 @@ button.image-canvas-editor__reference-chip:disabled {
   z-index: 13;
   display: grid;
   grid-template-columns: minmax(0, 1fr);
-  grid-template-rows: auto minmax(5.8rem, auto) auto auto;
-  width: min(34rem, calc(100% - 1.5rem));
-  min-height: 11.2rem;
+  grid-template-rows: auto minmax(5.1rem, auto) auto auto;
+  width: min(42rem, calc(100% - 1.5rem));
+  min-height: 10.4rem;
   gap: 0.5rem;
   border: 1px solid #cfd6df;
   border-radius: 1.35rem;
   background: #ffffff;
-  padding: 0.62rem 0.7rem 0.68rem;
+  padding: 0.62rem 0.7rem 0.44rem;
   color: #1f2937;
   box-shadow: 0 18px 46px rgba(15, 23, 42, 0.16);
   transform: translateX(-50%);
 }
 
 .image-canvas-editor__icon-composer .image-canvas-editor__generation-prompt {
-  min-height: 5.8rem;
+  min-height: 5.1rem;
   padding-top: 0.42rem;
 }
 
+.image-canvas-editor__character-composer
+  .image-canvas-editor__generation-composer-footer,
+.image-canvas-editor__icon-composer
+  .image-canvas-editor__generation-composer-footer {
+  padding-top: 0.96rem;
+}
+
 .image-canvas-editor__icon-spec-card:disabled {
   cursor: wait;
   opacity: 0.68;
@@ -8491,6 +8515,7 @@ button.image-canvas-editor__reference-chip:disabled {
 .image-canvas-editor__quick-edit-panel.image-canvas-editor__generation-composer {
   width: min(42rem, calc(100vw - 1.5rem));
   gap: 0.18rem 0.72rem;
+  padding-bottom: 0.48rem;
 }
 
 .image-canvas-editor__generation-composer--quick-edit {
@@ -8501,6 +8526,11 @@ button.image-canvas-editor__reference-chip:disabled {
   grid-template-columns: auto minmax(0, 1fr) auto auto;
 }
 
+.image-canvas-editor__quick-edit-panel
+  .image-canvas-editor__generation-composer-footer {
+  padding-top: 1rem;
+}
+
 .image-canvas-editor__quick-edit-footer
   .image-canvas-editor__option-popover-anchor--model {
   grid-column: 3;
@@ -8684,7 +8714,7 @@ button.image-canvas-editor__reference-chip:disabled {
 }
 
 .image-canvas-editor__ui-extraction-model {
-  grid-column: 2;
+  grid-column: 4;
   justify-self: end;
   width: min(15.5rem, 42vw);
 }
@@ -9305,10 +9335,15 @@ button.image-canvas-editor__reference-chip:disabled {
     width: auto;
     max-height: min(72vh, 31rem);
     overflow: auto;
-    padding: 0.58rem;
+    padding: 0.58rem 0.58rem 0.44rem;
     transform: none;
   }
 
+  .image-canvas-editor__character-composer
+    .image-canvas-editor__generation-composer-footer {
+    padding-top: 0.86rem;
+  }
+
   .image-canvas-editor__character-reference-row {
     padding-right: 2rem;
   }
diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts
index f85ede03f..1b8c34627 100644
--- a/src/services/image-editor/editorProjectClient.test.ts
+++ b/src/services/image-editor/editorProjectClient.test.ts
@@ -780,6 +780,8 @@ describe('editorProjectClient', () => {
       prompt: '角色设定',
       kind: 'character',
       model: 'gpt-image-2',
+      screenColor: '#FFD6C2',
+      segModel: 'anime-seg',
       aspectRatio: '2:3',
       imageSize: '1K',
       projectId: 'editor-project-1',
@@ -802,6 +804,8 @@ describe('editorProjectClient', () => {
           prompt: '角色设定',
           kind: 'character',
           model: 'gpt-image-2',
+          screenColor: '#FFD6C2',
+          segModel: 'anime-seg',
           aspectRatio: '2:3',
           imageSize: '1K',
           projectId: 'editor-project-1',
@@ -943,6 +947,8 @@ describe('editorProjectClient', () => {
       referenceImageSrc: 'data:image/png;base64,spec',
       iconDescriptions: ['返回按钮'],
       model: 'gpt-image-2',
+      screenColor: '#E6D8FF',
+      segModel: 'anime-seg',
       aspectRatio: '1:1',
       imageSize: '2K',
       projectId: 'editor-project-1',
@@ -962,6 +968,8 @@ describe('editorProjectClient', () => {
           referenceImageSrc: 'data:image/png;base64,spec',
           iconDescriptions: ['返回按钮'],
           model: 'gpt-image-2',
+          screenColor: '#E6D8FF',
+          segModel: 'anime-seg',
           aspectRatio: '1:1',
           imageSize: '2K',
           projectId: 'editor-project-1',
@@ -994,9 +1002,9 @@ describe('editorProjectClient', () => {
         },
       ],
       prompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板或绿色阴影。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯色背景 中度天蓝 #7FB3FF / RGB(127,179,255)，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板或阴影。',
       actualPrompt:
-        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，方便后续扣除背景；素材自身不要出现绿色描边、绿色底板或绿色阴影。',
+        '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用单一纯色背景 中度天蓝 #7FB3FF / RGB(127,179,255)，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板或阴影。',
       model: 'gpt-image-2',
       provider: 'VectorEngine',
       taskId: 'ui-asset-extraction-1',
@@ -1005,6 +1013,8 @@ describe('editorProjectClient', () => {
     const result = await extractEditorUiDesignAssets({
       sourceImageSrc: 'data:image/png;base64,ui-design',
       model: 'gpt-image-2',
+      screenColor: '#7FB3FF',
+      segModel: 'anime-seg',
       referenceImageSrcs: ['data:image/png;base64,ui-ref'],
       projectId: 'editor-project-1',
       assetFolderId: 'project',
@@ -1026,6 +1036,8 @@ describe('editorProjectClient', () => {
         body: JSON.stringify({
           sourceImageSrc: 'data:image/png;base64,ui-design',
           model: 'gpt-image-2',
+          screenColor: '#7FB3FF',
+          segModel: 'anime-seg',
           referenceImageSrcs: ['data:image/png;base64,ui-ref'],
           projectId: 'editor-project-1',
           generationInputs: {
diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
index cbe14feed..bc831182b 100644
--- a/src/services/image-editor/editorProjectClient.ts
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -162,6 +162,8 @@ export type EditorImageGenerationInput = {
     | 'ui-design'
     | 'publication-material';
   model?: string;
+  screenColor?: string;
+  segModel?: string;
   aspectRatio?: string;
   imageSize?: string;
   referenceImageSrcs?: string[];
@@ -192,6 +194,8 @@ export type EditorIconSpritesheetGenerationInput = {
   referenceImageSrcs?: string[];
   iconDescriptions: string[];
   model?: string;
+  screenColor?: string;
+  segModel?: string;
   aspectRatio?: string;
   imageSize?: string;
   projectId?: string | null;
@@ -203,6 +207,8 @@ export type EditorIconSpritesheetGenerationInput = {
 export type EditorUiDesignAssetExtractionInput = {
   sourceImageSrc: string;
   model?: string;
+  screenColor?: string;
+  segModel?: string;
   referenceImageSrcs?: string[];
   aspectRatio?: string;
   imageSize?: string;
@@ -856,6 +862,8 @@ export async function generateEditorImage(input: EditorImageGenerationInput) {
       ...(input.size ? { size: input.size } : {}),
       ...(input.kind ? { kind: input.kind } : {}),
       ...(input.model ? { model: input.model } : {}),
+      ...(input.screenColor ? { screenColor: input.screenColor } : {}),
+      ...(input.segModel ? { segModel: input.segModel } : {}),
       ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
       ...(input.imageSize ? { imageSize: input.imageSize } : {}),
       ...(input.referenceImageSrcs?.length
@@ -895,6 +903,8 @@ export async function generateEditorIconSpritesheet(
         : {}),
       iconDescriptions: input.iconDescriptions,
       model: input.model?.trim() || EDITOR_IMAGE_MODEL_NANOBANANA2,
+      ...(input.screenColor ? { screenColor: input.screenColor } : {}),
+      ...(input.segModel ? { segModel: input.segModel } : {}),
       ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
       ...(input.imageSize ? { imageSize: input.imageSize } : {}),
       ...(input.projectId ? { projectId: input.projectId } : {}),
@@ -922,6 +932,8 @@ export async function extractEditorUiDesignAssets(
     jsonRequest('POST', {
       sourceImageSrc: input.sourceImageSrc,
       ...(input.model ? { model: input.model } : {}),
+      ...(input.screenColor ? { screenColor: input.screenColor } : {}),
+      ...(input.segModel ? { segModel: input.segModel } : {}),
       ...(input.referenceImageSrcs?.length
         ? { referenceImageSrcs: input.referenceImageSrcs }
         : {}),

From b743152c6a516b9c3d6d414f9153a2116a62d449 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 15:10:45 +0800
Subject: [PATCH 17/24] =?UTF-8?q?=E8=A1=A5=E9=BD=90zustand=E4=BE=9D?=
 =?UTF-8?q?=E8=B5=96=E9=94=81=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在 package-lock.json 中补齐 zustand 依赖声明

记录 zustand 5.0.14 的 npm lock 条目
---
 package-lock.json | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/package-lock.json b/package-lock.json
index f58b1aa4f..2c6c4163c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -35,7 +35,8 @@
         "react-native-safe-area-context": "^5.8.0",
         "react-native-webview": "^13.16.1",
         "three": "^0.184.0",
-        "vite": "^6.2.0"
+        "vite": "^6.2.0",
+        "zustand": "^5.0.14"
       },
       "devDependencies": {
         "@colbymchenry/codegraph": "^0.8.0",
@@ -18937,6 +18938,35 @@
         "url": "https://github.com/sponsors/colinhacks"
       }
     },
+    "node_modules/zustand": {
+      "version": "5.0.14",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-5.0.14.tgz",
+      "integrity": "sha512-/8tAspM5LMPr28b3fwLYrtdj77ECpfZviaP75CMTnwO8ISyaE4GDIG/9rDDYq/cH9D2Xw2A2RXglLInmVBQB/g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20.0"
+      },
+      "peerDependencies": {
+        "@types/react": ">=18.0.0",
+        "immer": ">=9.0.6",
+        "react": ">=18.0.0",
+        "use-sync-external-store": ">=1.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "immer": {
+          "optional": true
+        },
+        "react": {
+          "optional": true
+        },
+        "use-sync-external-store": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/zxing-wasm": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/zxing-wasm/-/zxing-wasm-3.1.0.tgz",
@@ -31325,6 +31355,12 @@
       "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
       "dev": true
     },
+    "zustand": {
+      "version": "5.0.14",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-5.0.14.tgz",
+      "integrity": "sha512-/8tAspM5LMPr28b3fwLYrtdj77ECpfZviaP75CMTnwO8ISyaE4GDIG/9rDDYq/cH9D2Xw2A2RXglLInmVBQB/g==",
+      "requires": {}
+    },
     "zxing-wasm": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/zxing-wasm/-/zxing-wasm-3.1.0.tgz",

From 9b4908586910fb31a01516d7a674102ab4b45303 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 16:22:09 +0800
Subject: [PATCH 18/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=94=BB=E5=B8=83?=
 =?UTF-8?q?=E7=94=9F=E6=88=90=E5=99=A8=E5=81=B6=E5=8F=91=E6=97=A0=E6=B3=95?=
 =?UTF-8?q?=E6=89=93=E5=BC=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

同步生成器 active/inactive ref 与 state

激活已有生成器时清理选参考图和菜单临时状态

窗口失焦时释放 Shift 与空格按住态

补充生成器状态与快捷键回归测试

记录图片画布生成器排障经验
---
 docs/project-memory/shared-memory/pitfalls.md |   8 ++
 .../image-editor/ImageCanvasEditorView.tsx    |  22 +++
 .../useCanvasGenerationDialogs.test.tsx       |  54 ++++++++
 .../useCanvasGenerationDialogs.ts             | 126 ++++++++++--------
 .../useImageCanvasKeyboardShortcuts.test.tsx  |  17 +++
 .../useImageCanvasKeyboardShortcuts.ts        |  13 ++
 6 files changed, 182 insertions(+), 58 deletions(-)

diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 27a992727..ab462ce99 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -167,6 +167,14 @@
 - 验证：对应测试应断言生成按钮点击后 `dialog` 消失但 `image-canvas-editor__generation-frame--generating` 仍然存在。
 - 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`。
 
+## 图片画布生成器全体点不开先查卡住的临时交互状态
+
+- 现象：特定操作后，画布中已有生成器点击不再显示设定对话框，而且不是单个生成器坏掉；新建生成器或刷新页面后恢复。
+- 原因：旧生成器激活依赖全局交互状态；如果 `Shift` / 空格按住态因为窗口失焦漏掉 `keyup`，或“从画布选择参考图”等临时 picking / 菜单状态没有在激活旧生成器时清理，后续点击会被当成多选或选参考图而短路。
+- 处理：窗口 `blur` / 页面隐藏时释放 `Shift` 和空格按住态；激活已有 generation dialog 时同步清理参考图 picking、规格 / 参考菜单和右键菜单；active / inactive 生成器状态的 ref 与 React state 必须同事件周期同步。
+- 验证：`npm run test -- src/components/image-editor/useCanvasGenerationDialogs.test.tsx src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx -- --runInBand`，并跑 `ImageCanvasEditorView.test.tsx` 确认真实组件链路仍能激活生成器。
+- 关联：`src/components/image-editor/useCanvasGenerationDialogs.ts`、`src/components/image-editor/useImageCanvasKeyboardShortcuts.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`。
+
 ## 图片画布素材多时拖拽卡顿先查等距吸附候选规模
 
 - 现象：画布素材数量增加后，拖拽单个图层或生成占位框时 pointermove 明显卡顿，关闭或绕开吸附后体感恢复。
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index 10ae75459..d74f18dbb 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -310,6 +310,7 @@ export function ImageCanvasEditorView({
   const viewportRef = useRef<CanvasViewport>(DEFAULT_IMAGE_CANVAS_VIEWPORT);
   const captureCanvasHistoryRef = useRef<() => void>(() => {});
   const resetCanvasInteractionStateRef = useRef<() => void>(() => {});
+  const closeGenerationTransientStateRef = useRef<() => void>(() => {});
   const specToolWrapRef = useRef<HTMLSpanElement | null>(null);
   const musicToolWrapRef = useRef<HTMLSpanElement | null>(null);
   const publicationToolWrapRef = useRef<HTMLSpanElement | null>(null);
@@ -649,9 +650,11 @@ export function ImageCanvasEditorView({
   });
 
   const handleActivateCanvasGenerationDialog = useCallback(() => {
+    closeGenerationTransientStateRef.current();
     setSelectedLayerId(null);
     setSelectedLayerIds([]);
     setImageContextMenu(null);
+    setContextMenu(null);
   }, []);
   const {
     generateDialog,
@@ -1245,6 +1248,7 @@ export function ImageCanvasEditorView({
     setCharacterAnimationPanel,
     setIsSpecMenuOpen,
     setIsGenerationReferenceMenuOpen,
+    setIsPublicationReferenceMenuOpen,
     setIsCharacterSpecMenuOpen,
     setIsCharacterReferenceMenuOpen,
     isPickingGenerationReferenceFromCanvas,
@@ -1299,6 +1303,24 @@ export function ImageCanvasEditorView({
     generationComposerNode,
     switchGenerationTool,
   } = generationSurface;
+  closeGenerationTransientStateRef.current = () => {
+    setIsSpecMenuOpen(false);
+    setIsGenerationReferenceMenuOpen(false);
+    setIsPublicationReferenceMenuOpen(false);
+    setIsPickingGenerationReferenceFromCanvas(false);
+    setIsPickingQuickEditReferenceFromCanvas(false);
+    setIsPickingPublicationReferenceFromCanvas(false);
+    setIsCharacterSpecMenuOpen(false);
+    setIsCharacterReferenceMenuOpen(false);
+    setIsPickingCharacterSpecFromCanvas(false);
+    setIsPickingCharacterReferenceFromCanvas(false);
+    setIsIconSpecMenuOpen(false);
+    setIsPickingIconSpecFromCanvas(false);
+    setIsUiDesignSpecMenuOpen(false);
+    setIsPickingUiDesignSpecFromCanvas(false);
+    setImageContextMenu(null);
+    setContextMenu(null);
+  };
   setQuickEditPanelRef.current = setQuickEditPanel;
   appendUiAssetExtractionReferencesRef.current =
     appendUiAssetExtractionReferences;
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.test.tsx b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
index 1a504564a..e845a4a4c 100644
--- a/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
+++ b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
@@ -226,4 +226,58 @@ describe('useCanvasGenerationDialogs', () => {
       }),
     ]);
   });
+
+  it('keeps refs in sync when an archived dialog is activated and immediately updated', () => {
+    const { result } = renderHook(() => useCanvasGenerationDialogs());
+
+    act(() => {
+      result.current.openCanvasGenerationDialog(
+        createDialog('generate', 'first'),
+      );
+    });
+    act(() => {
+      result.current.openCanvasGenerationDialog(
+        createDialog('character', 'second'),
+      );
+    });
+
+    const archivedFirstDialog = result.current.inactiveGenerateDialogs[0];
+    expect(archivedFirstDialog).toEqual(
+      expect.objectContaining({ prompt: 'first' }),
+    );
+
+    let activeDialogRefId: string | undefined;
+    act(() => {
+      result.current.activateCanvasGenerationDialog(archivedFirstDialog!);
+      activeDialogRefId = result.current.generateDialogRef.current?.id;
+      result.current.updateCanvasGenerationDialogById(
+        archivedFirstDialog!.id,
+        (dialog) => ({
+          ...dialog,
+          placeholder: dialog.placeholder
+            ? {
+                ...dialog.placeholder,
+                x: 128,
+              }
+            : dialog.placeholder,
+        }),
+      );
+    });
+
+    expect(activeDialogRefId).toBe(archivedFirstDialog!.id);
+    expect(result.current.activeCanvasGenerationDialog).toEqual(
+      expect.objectContaining({
+        id: archivedFirstDialog!.id,
+        prompt: 'first',
+        composerOpen: true,
+        placeholder: expect.objectContaining({ x: 128 }),
+      }),
+    );
+    expect(result.current.inactiveGenerateDialogs).toEqual([
+      expect.objectContaining({
+        prompt: 'second',
+        composerOpen: false,
+      }),
+    ]);
+  });
 });
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.ts b/src/components/image-editor/useCanvasGenerationDialogs.ts
index 28e51f060..21ab352d5 100644
--- a/src/components/image-editor/useCanvasGenerationDialogs.ts
+++ b/src/components/image-editor/useCanvasGenerationDialogs.ts
@@ -70,13 +70,17 @@ export function useCanvasGenerationDialogs({
   const setGenerateDialog = useCallback<
     Dispatch<SetStateAction<GenerateDialogState | null>>
   >((nextDialogOrUpdater) => {
-    setGenerateDialogState((currentDialog) => {
-      const nextDialog =
-        typeof nextDialogOrUpdater === 'function'
-          ? nextDialogOrUpdater(currentDialog)
-          : nextDialogOrUpdater;
-      return withGenerationTimestamps(nextDialog, currentDialog);
-    });
+    const currentDialog = generateDialogRef.current;
+    const nextDialog =
+      typeof nextDialogOrUpdater === 'function'
+        ? nextDialogOrUpdater(currentDialog)
+        : nextDialogOrUpdater;
+    const nextDialogWithTimestamps = withGenerationTimestamps(
+      nextDialog,
+      currentDialog,
+    );
+    generateDialogRef.current = nextDialogWithTimestamps;
+    setGenerateDialogState(nextDialogWithTimestamps);
   }, []);
   const canvasGenerationDialogs = useMemo(
     () =>
@@ -96,17 +100,19 @@ export function useCanvasGenerationDialogs({
     if (!isCanvasGenerationDialog(currentDialog)) {
       return;
     }
-    setInactiveGenerateDialogs((currentDialogs) =>
-      currentDialogs.some((dialog) => dialog.id === currentDialog.id)
-        ? currentDialogs
-        : [
-            ...currentDialogs,
-            {
-              ...currentDialog,
-              composerOpen: false,
-            },
-          ],
-    );
+    const nextInactiveDialogs = inactiveGenerateDialogsRef.current.some(
+      (dialog) => dialog.id === currentDialog.id,
+    )
+      ? inactiveGenerateDialogsRef.current
+      : [
+          ...inactiveGenerateDialogsRef.current,
+          {
+            ...currentDialog,
+            composerOpen: false,
+          },
+        ];
+    inactiveGenerateDialogsRef.current = nextInactiveDialogs;
+    setInactiveGenerateDialogs(nextInactiveDialogs);
   }, []);
 
   const openCanvasGenerationDialog = useCallback(
@@ -198,26 +204,27 @@ export function useCanvasGenerationDialogs({
 
   const activateCanvasGenerationDialog = useCallback(
     (targetDialog: CanvasGenerationDialogState) => {
-      setInactiveGenerateDialogs((currentDialogs) => {
-        const nextDialogs = currentDialogs.filter(
-          (dialog) => dialog.id !== targetDialog.id,
-        );
-        const currentDialog = generateDialogRef.current;
-        if (
-          isCanvasGenerationDialog(currentDialog) &&
-          currentDialog.id !== targetDialog.id
-        ) {
-          nextDialogs.push({
-            ...currentDialog,
-            composerOpen: false,
-          });
-        }
-        return nextDialogs;
-      });
-      setGenerateDialogState({
+      const currentDialog = generateDialogRef.current;
+      const nextInactiveDialogs = inactiveGenerateDialogsRef.current.filter(
+        (dialog) => dialog.id !== targetDialog.id,
+      );
+      if (
+        isCanvasGenerationDialog(currentDialog) &&
+        currentDialog.id !== targetDialog.id
+      ) {
+        nextInactiveDialogs.push({
+          ...currentDialog,
+          composerOpen: false,
+        });
+      }
+      const nextActiveDialog = {
         ...targetDialog,
         composerOpen: true,
-      });
+      };
+      inactiveGenerateDialogsRef.current = nextInactiveDialogs;
+      generateDialogRef.current = nextActiveDialog;
+      setInactiveGenerateDialogs(nextInactiveDialogs);
+      setGenerateDialogState(nextActiveDialog);
       onActivate?.();
     },
     [onActivate],
@@ -238,22 +245,22 @@ export function useCanvasGenerationDialogs({
         [...dialogs].reverse().find((dialog) => dialog.composerOpen !== false) ??
         dialogs[dialogs.length - 1] ??
         null;
-      setGenerateDialogState(
-        activeDialog
-          ? {
-              ...activeDialog,
-              composerOpen: activeDialog.composerOpen !== false,
-            }
-          : null,
-      );
-      setInactiveGenerateDialogs(
-        dialogs
-          .filter((dialog) => dialog.id !== activeDialog?.id)
-          .map((dialog) => ({
-            ...dialog,
-            composerOpen: false,
-          })),
-      );
+      const nextActiveDialog = activeDialog
+        ? {
+            ...activeDialog,
+            composerOpen: activeDialog.composerOpen !== false,
+          }
+        : null;
+      const nextInactiveDialogs = dialogs
+        .filter((dialog) => dialog.id !== activeDialog?.id)
+        .map((dialog) => ({
+          ...dialog,
+          composerOpen: false,
+        }));
+      generateDialogRef.current = nextActiveDialog;
+      inactiveGenerateDialogsRef.current = nextInactiveDialogs;
+      setGenerateDialogState(nextActiveDialog);
+      setInactiveGenerateDialogs(nextInactiveDialogs);
     },
     [],
   );
@@ -263,14 +270,17 @@ export function useCanvasGenerationDialogs({
       const keepDialog = (dialog: CanvasGenerationDialogState) =>
         dialog.sourceLayerId !== targetLayerId &&
         dialog.generatedLayerId !== targetLayerId;
-      setGenerateDialogState((currentDialog) =>
+      const currentDialog = generateDialogRef.current;
+      const nextActiveDialog =
         isCanvasGenerationDialog(currentDialog) && !keepDialog(currentDialog)
           ? null
-          : currentDialog,
-      );
-      setInactiveGenerateDialogs((currentDialogs) =>
-        currentDialogs.filter(keepDialog),
-      );
+          : currentDialog;
+      const nextInactiveDialogs =
+        inactiveGenerateDialogsRef.current.filter(keepDialog);
+      generateDialogRef.current = nextActiveDialog;
+      inactiveGenerateDialogsRef.current = nextInactiveDialogs;
+      setGenerateDialogState(nextActiveDialog);
+      setInactiveGenerateDialogs(nextInactiveDialogs);
     },
     [],
   );
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
index 5ef9250a2..3ac95d3ab 100644
--- a/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
@@ -466,6 +466,23 @@ describe('useImageCanvasKeyboardShortcuts', () => {
     expect(startProjectRename).toHaveBeenCalledTimes(1);
   });
 
+  it('releases held modifier interaction state when the window loses focus', () => {
+    render(<KeyboardShortcutsHarness />);
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Shift', code: 'ShiftLeft' });
+      fireEvent.keyDown(window, { key: ' ', code: 'Space' });
+    });
+    expect(screen.getByTestId('shift-pressed').textContent).toBe('true');
+    expect(screen.getByTestId('space-panning').textContent).toBe('true');
+
+    act(() => {
+      fireEvent.blur(window);
+    });
+    expect(screen.getByTestId('shift-pressed').textContent).toBe('false');
+    expect(screen.getByTestId('space-panning').textContent).toBe('false');
+  });
+
   it('nudges selected canvas objects with arrow keys', () => {
     const nudgeSelectedCanvasObjects = vi.fn();
     render(
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
index 1066833c7..f13627a3b 100644
--- a/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
@@ -470,12 +470,25 @@ export function useImageCanvasKeyboardShortcuts({
       event.preventDefault();
       setIsSpacePanning(false);
     };
+    const resetPressedInteractionState = () => {
+      setShiftPressed(false);
+      setIsSpacePanning(false);
+    };
+    const handleVisibilityChange = () => {
+      if (document.visibilityState !== 'visible') {
+        resetPressedInteractionState();
+      }
+    };
 
     window.addEventListener('keydown', handleKeyDown);
     window.addEventListener('keyup', handleKeyUp);
+    window.addEventListener('blur', resetPressedInteractionState);
+    document.addEventListener('visibilitychange', handleVisibilityChange);
     return () => {
       window.removeEventListener('keydown', handleKeyDown);
       window.removeEventListener('keyup', handleKeyUp);
+      window.removeEventListener('blur', resetPressedInteractionState);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
     };
   }, [
     closeEditorChromePanels,

From 446c6945ad8685daa9201ac77b6ae8db1c36b44e Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 18:34:07 +0800
Subject: [PATCH 19/24] =?UTF-8?q?=E6=81=A2=E5=A4=8D=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E7=80=91=E5=B8=83=E6=B5=81=E5=B8=83=E5=B1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将创作主页精选列表从网格恢复为多栏瀑布流

新增样式契约测试防止瀑布流再次退化为网格
---
 src/index.css     | 14 +++++++-------
 src/index.test.ts | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/src/index.css b/src/index.css
index 25d934921..3de7e23f5 100644
--- a/src/index.css
+++ b/src/index.css
@@ -3801,20 +3801,20 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 }
 
 .creation-landing__asset-waterfall {
-  display: grid;
   width: 100%;
   min-width: 0;
-  grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr));
-  gap: 0.92rem;
-  align-items: start;
+  column-count: 3;
+  column-gap: 0.92rem;
 }
 
 .creation-landing__asset-card {
   position: relative;
-  display: block;
+  display: inline-block;
   width: 100%;
   min-width: 0;
   overflow: hidden;
+  margin: 0 0 0.92rem;
+  break-inside: avoid;
   border: 1px solid rgba(220, 189, 163, 0.78);
   border-radius: 1rem;
   background: rgba(255, 254, 251, 0.88);
@@ -4314,7 +4314,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   }
 
   .creation-landing__asset-waterfall {
-    grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
+    column-count: 2;
   }
 
   .creation-landing__showcase-modal-panel {
@@ -4374,7 +4374,7 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   }
 
   .creation-landing__asset-waterfall {
-    grid-template-columns: 1fr;
+    column-count: 1;
   }
 
   .creation-landing__showcase-modal-overlay {
diff --git a/src/index.test.ts b/src/index.test.ts
index 7dfab151b..2a632264f 100644
--- a/src/index.test.ts
+++ b/src/index.test.ts
@@ -31,6 +31,40 @@ function getCssBlock(source: string, selector: string) {
 }
 
 describe('index stylesheet unread dots', () => {
+  it('keeps creation home featured assets in a column waterfall layout', () => {
+    const css = readIndexCss();
+    const waterfallBlock = getCssBlock(
+      css,
+      '.creation-landing__asset-waterfall',
+    );
+    const cardBlock = getCssBlock(css, '.creation-landing__asset-card {');
+    const tabletQueryIndex = css.indexOf('@media (max-width: 900px)');
+    const mobileQueryIndex = css.indexOf('@media (max-width: 560px)');
+
+    expect(tabletQueryIndex).toBeGreaterThanOrEqual(0);
+    expect(mobileQueryIndex).toBeGreaterThanOrEqual(0);
+    const tabletWaterfallBlock = getCssBlock(
+      css.slice(tabletQueryIndex),
+      '.creation-landing__asset-waterfall',
+    );
+    const mobileWaterfallBlock = getCssBlock(
+      css.slice(mobileQueryIndex),
+      '.creation-landing__asset-waterfall',
+    );
+
+    expect(waterfallBlock).toContain('column-count: 3;');
+    expect(waterfallBlock).toContain('column-gap: 0.92rem;');
+    expect(waterfallBlock).not.toContain('display: grid;');
+    expect(waterfallBlock).not.toContain('grid-template-columns');
+    expect(cardBlock).toContain('display: inline-block;');
+    expect(cardBlock).toContain('margin: 0 0 0.92rem;');
+    expect(cardBlock).toContain('break-inside: avoid;');
+    expect(tabletWaterfallBlock).toContain('column-count: 2;');
+    expect(tabletWaterfallBlock).not.toContain('grid-template-columns');
+    expect(mobileWaterfallBlock).toContain('column-count: 1;');
+    expect(mobileWaterfallBlock).not.toContain('grid-template-columns');
+  });
+
   it('keeps icon generator decoration from overriding the shared generating animation', () => {
     const css = readIndexCss();
     const generatingBlock = getCssBlock(

From 5888219c9546150af0fe6733d1de344026f61e1a Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 18:37:58 +0800
Subject: [PATCH 20/24] =?UTF-8?q?=E7=A7=BB=E9=99=A4=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E9=A2=84=E8=A7=88=E5=BC=B9=E7=AA=97=E7=82=B9=E8=B5=9E=E6=93=8D?=
 =?UTF-8?q?=E4=BD=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

精选素材预览弹窗只保留点赞数展示

补充弹窗不展示点赞按钮的回归测试
---
 .../CreationLandingView.test.tsx              | 45 +++++++++++++++++++
 .../creation-home/CreationLandingView.tsx     | 34 --------------
 2 files changed, 45 insertions(+), 34 deletions(-)

diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
index b2333be8c..970e66e09 100644
--- a/src/components/creation-home/CreationLandingView.test.tsx
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -442,6 +442,51 @@ describe('CreationLandingView', () => {
     ).toBeTruthy();
   });
 
+  it('does not show a like action in the featured asset preview modal', async () => {
+    const user = userEvent.setup();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    listPublicEditorProjectResourcesMock.mockResolvedValueOnce([
+      {
+        resourceId: 'resource-character',
+        projectId: 'project-newest',
+        showcaseId: 'showcase-character',
+        label: '角色英雄',
+        imageSrc: 'data:image/png;base64,character',
+        width: 512,
+        height: 512,
+        sourceType: 'generated',
+        prompt: 'character hero prompt',
+        actualPrompt: null,
+        model: 'character-model',
+        provider: 'provider',
+        taskId: 'task-1',
+        showcaseCategory: 'characters',
+        likeCount: 3,
+        generationCostMudPoints: 20,
+      },
+    ]);
+
+    renderCreationLanding();
+    await user.click(screen.getByRole('tab', { name: '角色' }));
+
+    const likeButton = await screen.findByRole('button', {
+      name: '点赞：角色英雄',
+    });
+    const assetCard = likeButton.closest(
+      '.creation-landing__asset-card',
+    ) as HTMLElement;
+    await user.click(
+      assetCard.querySelector(
+        '.creation-landing__asset-card-open',
+      ) as HTMLElement,
+    );
+
+    const dialog = await screen.findByRole('dialog', { name: '角色英雄' });
+    expect(within(dialog).getByText('赞')).toBeTruthy();
+    expect(within(dialog).getByText('3')).toBeTruthy();
+    expect(within(dialog).queryByRole('button', { name: /点赞/ })).toBeNull();
+  });
+
   it('opens a fullscreen asset preview modal with thumbnail navigation', async () => {
     const user = userEvent.setup();
     listEditorProjectsMock.mockResolvedValueOnce(projectItems);
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
index ea7b08279..d4c989cdb 100644
--- a/src/components/creation-home/CreationLandingView.tsx
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -322,18 +322,12 @@ function ShowcaseBundlePreview({ item }: { item: ShowcaseAssetItem }) {
 function CreationShowcaseModal({
   item,
   activeIndex,
-  isLiked,
-  isLikePending,
   onSelectIndex,
-  onToggleLike,
   onClose,
 }: {
   item: ShowcaseAssetItem | null;
   activeIndex: number;
-  isLiked: boolean;
-  isLikePending: boolean;
   onSelectIndex: (index: number) => void;
-  onToggleLike: (item: ShowcaseAssetItem) => void;
   onClose: () => void;
 }) {
   const safeActiveIndex = item
@@ -389,25 +383,6 @@ function CreationShowcaseModal({
                   </div>
                 ) : null}
               </dl>
-              {item.showcaseId ? (
-                <PlatformActionButton
-                  tone={isLiked ? 'secondary' : 'primary'}
-                  surface="platform"
-                  size="sm"
-                  disabled={isLikePending}
-                  onClick={() => onToggleLike(item)}
-                >
-                  <img
-                    className="creation-landing__showcase-like-icon"
-                    src={SHOWCASE_LIKE_ICON_SRC}
-                    alt=""
-                    aria-hidden="true"
-                  />
-                  <span>
-                    {isLikePending ? '处理中' : isLiked ? '已点赞' : '点赞'}
-                  </span>
-                </PlatformActionButton>
-              ) : null}
             </div>
             <div
               className="creation-landing__showcase-thumbs"
@@ -1078,16 +1053,7 @@ export function CreationLandingView({
       <CreationShowcaseModal
         item={selectedShowcaseItem}
         activeIndex={selectedShowcaseIndex}
-        isLiked={Boolean(
-          selectedShowcaseItem?.showcaseId &&
-            likedShowcaseIds.has(selectedShowcaseItem.showcaseId),
-        )}
-        isLikePending={Boolean(
-          selectedShowcaseItem?.showcaseId &&
-            pendingLikeShowcaseIds.has(selectedShowcaseItem.showcaseId),
-        )}
         onSelectIndex={setSelectedShowcaseIndex}
-        onToggleLike={handleToggleShowcaseLike}
         onClose={() => setSelectedShowcaseItem(null)}
       />
       <UnifiedModal

From 862653c98743529289101eeca0f0faad855d4b6a Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 18:47:23 +0800
Subject: [PATCH 21/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=B2=BE=E9=80=89?=
 =?UTF-8?q?=E6=8F=90=E7=A4=BA=E8=AF=8D=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

精选卡片优先展示用户可见的生成输入

过滤系统内置和素材提取提示词

补充精选提示词外露回归测试
---
 .../creationShowcaseModel.test.ts             |  56 ++++++++
 .../creation-home/creationShowcaseModel.ts    | 130 ++++++++++++++++--
 2 files changed, 176 insertions(+), 10 deletions(-)

diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
index bb6c348f4..56438c42f 100644
--- a/src/components/creation-home/creationShowcaseModel.test.ts
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -260,6 +260,62 @@ describe('creationShowcaseModel', () => {
     expect(items[1]?.cost).toBe('12泥点');
   });
 
+  it('prefers user generation inputs over internal assembled prompts', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'all',
+      projectResources: [
+        createResource({
+          resourceId: 'character-1',
+          label: '角色主图',
+          assetKind: 'character',
+          prompt:
+            '【系统内置】完整拼接提示词：用户的角色设定，自动添加视角、构图和抠图背景规则。',
+          actualPrompt:
+            '【系统内置】真正发送给模型的完整提示词，包含更多模型约束。',
+          generationInputs: {
+            fields: [
+              { title: '角色设定', value: '用户的角色设定' },
+              { title: '抠图背景色', value: '暖浅桃色 #FFD6C2' },
+              { title: 'model', value: 'gpt-image-2' },
+            ],
+            references: [],
+          },
+        }),
+      ],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.prompt).toBe('用户的角色设定');
+  });
+
+  it('does not expose built-in extraction prompts as showcase descriptions', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'all',
+      projectResources: [
+        createResource({
+          resourceId: 'icon-sheet-1',
+          label: '图标素材图集',
+          assetKind: 'icon-spritesheet',
+          prompt: '【系统内置】固定素材提取提示词',
+          generationInputs: {
+            fields: [
+              {
+                title: '提取提示词',
+                value:
+                  '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。',
+              },
+              { title: 'model', value: 'gpt-image-2' },
+            ],
+            references: [],
+          },
+        }),
+      ],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.prompt).toBe('-');
+  });
+
   it('keeps unset category visible in all tab and out of concrete category tabs', () => {
     const items = buildCreationShowcaseItems({
       activeTab: 'all',
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
index 73947dbec..65257e528 100644
--- a/src/components/creation-home/creationShowcaseModel.ts
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -65,6 +65,38 @@ const SHOWCASE_AUTHOR_KEYS = [
   'authorPublicUserCode',
 ] as const;
 
+const USER_PROMPT_INPUT_TITLES = new Set(
+  [
+    '生成提示词',
+    '视频描述',
+    'prompt',
+    'sound',
+    'gpt_description_prompt',
+    '音效提示词',
+    '背景音乐提示词',
+    '角色设定',
+    '用户输入',
+    '素材描述',
+    '自定义规范提示词',
+    '修改要求',
+    '快速编辑提示词',
+    '重绘提示词',
+    '动作描述',
+  ].map((title) => title.toLowerCase()),
+);
+
+const STRUCTURED_USER_INPUT_TITLES = new Set(
+  [
+    '玩法设定',
+    '美术风格',
+    '头身比',
+    '角色视角',
+    '游戏名',
+    '游戏分类',
+    '一句话描述游戏',
+  ].map((title) => title.toLowerCase()),
+);
+
 export const SHOWCASE_TABS: Array<{ id: ShowcaseTabId; label: string }> = [
   { id: 'all', label: '全部' },
   { id: 'characters', label: '角色' },
@@ -89,6 +121,22 @@ function normalizeText(value: unknown) {
   return typeof value === 'string' && value.trim() ? value.trim() : '';
 }
 
+function normalizeGenerationInputTitle(value: string) {
+  return value.trim().toLowerCase();
+}
+
+function isBuiltInPromptText(value: string) {
+  const trimmedValue = value.trim();
+  return (
+    trimmedValue.startsWith('【系统内置】') ||
+    trimmedValue.startsWith('【宣发素材类型】') ||
+    trimmedValue.startsWith('参考图1的图标素材规范') ||
+    trimmedValue.startsWith('生成玩法UI原型图') ||
+    trimmedValue.includes('仅提取被红色框框选的素材') ||
+    trimmedValue.includes('图集背景必须使用所选单一纯色抠图背景')
+  );
+}
+
 function normalizeNumber(value: unknown) {
   if (typeof value === 'number' && Number.isFinite(value)) {
     return value;
@@ -597,18 +645,80 @@ function getGroupsForTab(assets: EditorAssetSnapshot[], tab: ShowcaseTabId) {
   return [];
 }
 
-function resolveAssetPrompt(asset: EditorAssetSnapshot) {
-  const directPrompt = asset.prompt?.trim() || asset.actualPrompt?.trim();
-  if (directPrompt) {
-    return directPrompt;
+function resolveUserGenerationPrompt(asset: EditorAssetSnapshot) {
+  const fields = asset.generationInputs?.fields ?? [];
+  const promptField = fields.find((field) => {
+    const value = field.value.trim();
+    return (
+      value &&
+      USER_PROMPT_INPUT_TITLES.has(
+        normalizeGenerationInputTitle(field.title),
+      ) &&
+      !isBuiltInPromptText(value)
+    );
+  });
+  const promptValue = promptField?.value.trim();
+  if (promptValue) {
+    return promptValue;
   }
 
-  const generationFields = asset.generationInputs?.fields ?? [];
-  const firstPromptField =
-    generationFields.find((field) =>
-      /提示词|描述|设定|prompt/u.test(field.title),
-    ) ?? generationFields[0];
-  return firstPromptField?.value?.trim() || UNKNOWN_META_VALUE;
+  const structuredLines = fields.flatMap((field) => {
+    if (
+      !STRUCTURED_USER_INPUT_TITLES.has(
+        normalizeGenerationInputTitle(field.title),
+      )
+    ) {
+      return [];
+    }
+    const value = field.value.trim();
+    return value && !isBuiltInPromptText(value)
+      ? [`${field.title.trim()}：${value}`]
+      : [];
+  });
+  return structuredLines.join('\n');
+}
+
+function extractUserPromptFromAssembledPrompt(value: string) {
+  const trimmedValue = value.trim();
+  const sectionMatch =
+    trimmedValue.match(/【用户输入】\s*([\s\S]*?)(?=\n+【|$)/u) ??
+    trimmedValue.match(/【游戏输入】\s*([\s\S]*?)(?=\n+【|$)/u);
+  const sectionValue = sectionMatch?.[1]?.trim();
+  if (sectionValue && !isBuiltInPromptText(sectionValue)) {
+    return sectionValue;
+  }
+
+  const roleSettingMatch = trimmedValue.match(
+    /(?:^|\n)角色设定[:：]\s*([^\n]+)/u,
+  );
+  const roleSettingValue = roleSettingMatch?.[1]?.trim();
+  return roleSettingValue && !isBuiltInPromptText(roleSettingValue)
+    ? roleSettingValue
+    : '';
+}
+
+function resolveAssetPrompt(asset: EditorAssetSnapshot) {
+  const userPrompt = resolveUserGenerationPrompt(asset);
+  if (userPrompt) {
+    return userPrompt;
+  }
+
+  for (const value of [asset.prompt, asset.actualPrompt]) {
+    const directPrompt = value?.trim() ?? '';
+    if (!directPrompt) {
+      continue;
+    }
+
+    const extractedPrompt = extractUserPromptFromAssembledPrompt(directPrompt);
+    if (extractedPrompt) {
+      return extractedPrompt;
+    }
+    if (!isBuiltInPromptText(directPrompt)) {
+      return directPrompt;
+    }
+  }
+
+  return UNKNOWN_META_VALUE;
 }
 
 function resolveGroupPrompt(assets: EditorAssetSnapshot[]) {

From 00db7d39eaab9f487973c96f4ce91f6891378139 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 19:36:02 +0800
Subject: [PATCH 22/24] =?UTF-8?q?=E7=BB=9F=E4=B8=80=E7=94=9F=E6=88=90?=
 =?UTF-8?q?=E5=99=A8=E5=AF=B9=E8=AF=9D=E6=A1=86=E8=8C=83=E5=9B=B4=E8=A1=8C?=
 =?UTF-8?q?=E4=B8=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

移除生成器对话框打开后的安全范围自动拉动视口。

取消快速编辑、裁扩和角色动画面板的画布范围夹取。

保留创建生成器时聚焦新占位的行为并更新回归测试。
---
 ...mageCanvasGenerationPlacementModel.test.ts |   2 +-
 .../ImageCanvasOverlayModel.test.ts           |  88 ++++--------
 .../image-editor/ImageCanvasOverlayModel.ts   | 123 ++--------------
 .../useImageCanvasGenerationSurface.test.tsx  |  17 ++-
 .../useImageCanvasGenerationSurface.tsx       | 131 ------------------
 .../useImageCanvasGenerationWorkflow.test.tsx |   4 +-
 6 files changed, 53 insertions(+), 312 deletions(-)

diff --git a/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
index eacdc479e..ea26a79ab 100644
--- a/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
+++ b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
@@ -193,7 +193,7 @@ describe('ImageCanvasGenerationPlacementModel', () => {
     expect(placement.y).toBe(-22);
   });
 
-  it('centers the viewport on the chosen placement without changing zoom', () => {
+  it('focuses the viewport on the chosen placement without changing zoom', () => {
     const zoomedViewport = { ...viewport, scale: 1.75 };
     const nextViewport = centerViewportOnPlacement({
       canvasSize,
diff --git a/src/components/image-editor/ImageCanvasOverlayModel.test.ts b/src/components/image-editor/ImageCanvasOverlayModel.test.ts
index 9c875b93d..100e4c620 100644
--- a/src/components/image-editor/ImageCanvasOverlayModel.test.ts
+++ b/src/components/image-editor/ImageCanvasOverlayModel.test.ts
@@ -4,18 +4,19 @@ import type {
   CanvasGenerationDialogState,
   CanvasLayer,
   CharacterAnimationPanelState,
+  CropExpandPanelState,
   QuickEditPanelState,
 } from './ImageCanvasEditorTypes';
 import {
   isCanvasGenerationComposerVisible,
   resolveCharacterAnimationPanelStyle,
+  resolveCropExpandPanelStyle,
   resolveGenerationAnchor,
   resolveGenerationComposerStyle,
   resolveIconComposerStyle,
   resolveQuickEditFocusViewport,
   resolveQuickEditPanelStyle,
   resolveSelectedToolbarStyle,
-  resolveViewportForOverlayVisibility,
 } from './ImageCanvasOverlayModel';
 
 function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
@@ -146,7 +147,7 @@ describe('ImageCanvasOverlayModel', () => {
     expect(sourceBottom + 12 + 260).toBeLessThanOrEqual(640);
   });
 
-  it('positions quick edit and character animation panels with viewport bounds', () => {
+  it('positions generation panels from their anchors without clamping to viewport bounds', () => {
     const sourceLayer = createLayer({ x: 740, y: 460, width: 240, height: 180 });
     const quickEditPanel: QuickEditPanelState = {
       sourceLayerId: sourceLayer.id,
@@ -164,6 +165,17 @@ describe('ImageCanvasOverlayModel', () => {
       durationSeconds: 4,
       status: 'idle',
     };
+    const cropExpandPanel: CropExpandPanelState = {
+      sourceLayerId: sourceLayer.id,
+      frame: {
+        x: sourceLayer.x,
+        y: sourceLayer.y,
+        width: sourceLayer.width,
+        height: sourceLayer.height,
+      },
+      ratio: 'free',
+      status: 'idle',
+    };
 
     expect(
       resolveQuickEditPanelStyle({
@@ -172,7 +184,15 @@ describe('ImageCanvasOverlayModel', () => {
         viewport: { x: 20, y: 10, scale: 1 },
         canvasSize: { width: 900, height: 640 },
       }),
-    ).toEqual({ left: 880, top: 376 });
+    ).toEqual({ left: 880, top: 662 });
+    expect(
+      resolveCropExpandPanelStyle({
+        panel: cropExpandPanel,
+        sourceLayer,
+        viewport: { x: 20, y: 10, scale: 1 },
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ left: 1012, top: 470 });
     expect(
       resolveCharacterAnimationPanelStyle({
         panel: characterPanel,
@@ -180,67 +200,7 @@ describe('ImageCanvasOverlayModel', () => {
         viewport: { x: 20, y: 10, scale: 1 },
         canvasSize: { width: 900, height: 640 },
       }),
-    ).toEqual({ left: 536, top: 120 });
-  });
-
-  it('pans the viewport until an opened composer is inside the visible safe area', () => {
-    expect(
-      resolveViewportForOverlayVisibility({
-        viewport: { x: 10, y: 20, scale: 1 },
-        overlayBounds: {
-          left: 210,
-          top: 430,
-          right: 690,
-          bottom: 650,
-        },
-        safeBounds: {
-          left: 12,
-          top: 12,
-          right: 888,
-          bottom: 560,
-        },
-      }),
-    ).toEqual({ x: 10, y: -70, scale: 1 });
-  });
-
-  it('pans sideways when a centered composer would leave the viewport', () => {
-    expect(
-      resolveViewportForOverlayVisibility({
-        viewport: { x: 0, y: 0, scale: 1 },
-        overlayBounds: {
-          left: -80,
-          top: 120,
-          right: 420,
-          bottom: 320,
-        },
-        safeBounds: {
-          left: 12,
-          top: 12,
-          right: 888,
-          bottom: 560,
-        },
-      }),
-    ).toEqual({ x: 92, y: 0, scale: 1 });
-  });
-
-  it('centers an oversized composer within the available safe area', () => {
-    expect(
-      resolveViewportForOverlayVisibility({
-        viewport: { x: 0, y: 0, scale: 1 },
-        overlayBounds: {
-          left: 20,
-          top: 20,
-          right: 700,
-          bottom: 620,
-        },
-        safeBounds: {
-          left: 12,
-          top: 12,
-          right: 612,
-          bottom: 512,
-        },
-      }),
-    ).toEqual({ x: -48, y: -58, scale: 1 });
+    ).toEqual({ left: 1012, top: 470 });
   });
 
   it('recognizes canvas generation composer dialog modes', () => {
diff --git a/src/components/image-editor/ImageCanvasOverlayModel.ts b/src/components/image-editor/ImageCanvasOverlayModel.ts
index 18dfbe524..8f0916dd4 100644
--- a/src/components/image-editor/ImageCanvasOverlayModel.ts
+++ b/src/components/image-editor/ImageCanvasOverlayModel.ts
@@ -1,4 +1,3 @@
-import { clamp } from './ImageCanvasEditorModel';
 import type {
   CanvasGenerationDialogMode,
   CanvasGenerationDialogState,
@@ -22,7 +21,6 @@ const QUICK_EDIT_FOCUS_SOURCE_TOP = 56;
 const QUICK_EDIT_PANEL_GAP = 12;
 const QUICK_EDIT_PANEL_ESTIMATED_HEIGHT = 260;
 const QUICK_EDIT_PANEL_BOTTOM_MARGIN = 4;
-const OVERLAY_VISIBILITY_EPSILON = 0.5;
 
 export type CanvasOverlayStyle = {
   left: number;
@@ -33,72 +31,6 @@ export type CanvasComposerOverlayStyle = CanvasOverlayStyle & {
   width?: string;
 };
 
-export type CanvasOverlayBounds = {
-  left: number;
-  top: number;
-  right: number;
-  bottom: number;
-};
-
-function resolveOverlayAxisShift({
-  start,
-  end,
-  safeStart,
-  safeEnd,
-}: {
-  start: number;
-  end: number;
-  safeStart: number;
-  safeEnd: number;
-}) {
-  const size = end - start;
-  const safeSize = safeEnd - safeStart;
-  if (size > safeSize) {
-    return safeStart + (safeSize - size) / 2 - start;
-  }
-  if (start < safeStart) {
-    return safeStart - start;
-  }
-  if (end > safeEnd) {
-    return safeEnd - end;
-  }
-  return 0;
-}
-
-export function resolveViewportForOverlayVisibility({
-  viewport,
-  overlayBounds,
-  safeBounds,
-}: {
-  viewport: CanvasViewport;
-  overlayBounds: CanvasOverlayBounds;
-  safeBounds: CanvasOverlayBounds;
-}): CanvasViewport {
-  const shiftX = resolveOverlayAxisShift({
-    start: overlayBounds.left,
-    end: overlayBounds.right,
-    safeStart: safeBounds.left,
-    safeEnd: safeBounds.right,
-  });
-  const shiftY = resolveOverlayAxisShift({
-    start: overlayBounds.top,
-    end: overlayBounds.bottom,
-    safeStart: safeBounds.top,
-    safeEnd: safeBounds.bottom,
-  });
-  if (
-    Math.abs(shiftX) <= OVERLAY_VISIBILITY_EPSILON &&
-    Math.abs(shiftY) <= OVERLAY_VISIBILITY_EPSILON
-  ) {
-    return viewport;
-  }
-  return {
-    ...viewport,
-    x: viewport.x + shiftX,
-    y: viewport.y + shiftY,
-  };
-}
-
 export function resolveGenerationAnchor({
   dialog,
   generatedLayer,
@@ -208,7 +140,6 @@ export function resolveQuickEditPanelStyle({
   panel,
   sourceLayer,
   viewport,
-  canvasSize,
 }: {
   panel: QuickEditPanelState | null;
   sourceLayer: CanvasLayer | null;
@@ -219,24 +150,12 @@ export function resolveQuickEditPanelStyle({
     return null;
   }
   return {
-    left: clamp(
-      viewport.x +
-        (sourceLayer.x + sourceLayer.width / 2) * viewport.scale,
-      12,
-      Math.max(12, canvasSize.width - 12),
-    ),
-    top: clamp(
+    left:
+      viewport.x + (sourceLayer.x + sourceLayer.width / 2) * viewport.scale,
+    top:
       viewport.y +
-        (sourceLayer.y + sourceLayer.height) * viewport.scale +
-        QUICK_EDIT_PANEL_GAP,
-      QUICK_EDIT_PANEL_BOTTOM_MARGIN,
-      Math.max(
-        QUICK_EDIT_PANEL_BOTTOM_MARGIN,
-        canvasSize.height -
-          QUICK_EDIT_PANEL_ESTIMATED_HEIGHT -
-          QUICK_EDIT_PANEL_BOTTOM_MARGIN,
-      ),
-    ),
+      (sourceLayer.y + sourceLayer.height) * viewport.scale +
+      QUICK_EDIT_PANEL_GAP,
   };
 }
 
@@ -244,7 +163,6 @@ export function resolveCropExpandPanelStyle({
   panel,
   sourceLayer,
   viewport,
-  canvasSize,
 }: {
   panel: CropExpandPanelState | null;
   sourceLayer: CanvasLayer | null;
@@ -255,18 +173,9 @@ export function resolveCropExpandPanelStyle({
     return null;
   }
   return {
-    left: clamp(
-      viewport.x +
-        (sourceLayer.x + sourceLayer.width) * viewport.scale +
-        12,
-      12,
-      Math.max(12, canvasSize.width - 312),
-    ),
-    top: clamp(
-      viewport.y + sourceLayer.y * viewport.scale,
-      12,
-      Math.max(12, canvasSize.height - 320),
-    ),
+    left:
+      viewport.x + (sourceLayer.x + sourceLayer.width) * viewport.scale + 12,
+    top: viewport.y + sourceLayer.y * viewport.scale,
   };
 }
 
@@ -274,7 +183,6 @@ export function resolveCharacterAnimationPanelStyle({
   panel,
   sourceLayer,
   viewport,
-  canvasSize,
 }: {
   panel: CharacterAnimationPanelState | null;
   sourceLayer: CanvasLayer | null;
@@ -285,18 +193,9 @@ export function resolveCharacterAnimationPanelStyle({
     return null;
   }
   return {
-    left: clamp(
-      viewport.x +
-        (sourceLayer.x + sourceLayer.width) * viewport.scale +
-        12,
-      12,
-      Math.max(12, canvasSize.width - 364),
-    ),
-    top: clamp(
-      viewport.y + sourceLayer.y * viewport.scale,
-      12,
-      Math.max(12, canvasSize.height - 520),
-    ),
+    left:
+      viewport.x + (sourceLayer.x + sourceLayer.width) * viewport.scale + 12,
+    top: viewport.y + sourceLayer.y * viewport.scale,
   };
 }
 
diff --git a/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx b/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx
index 37776cff1..7996aeff9 100644
--- a/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx
@@ -413,7 +413,7 @@ describe('useImageCanvasGenerationSurface', () => {
     ).toBeTruthy();
   });
 
-  it('pans the canvas when an opened composer would be covered by the bottom toolbar', async () => {
+  it('does not pan the canvas again when a focused composer leaves the visible viewport', async () => {
     render(<GenerationSurfaceHarness />);
     const viewportElement = screen.getByTestId('viewport');
     const toolbarElement = viewportElement.querySelector(
@@ -457,9 +457,22 @@ describe('useImageCanvasGenerationSurface', () => {
 
     fireEvent.click(screen.getByRole('button', { name: '切换生成' }));
     await screen.findByRole('dialog', { name: '生成图片' });
+    const focusedViewportX = Number(
+      screen.getByTestId('viewport-x').textContent,
+    );
+    const focusedViewportY = Number(
+      screen.getByTestId('viewport-y').textContent,
+    );
 
     await act(async () => {});
 
-    expect(Number(screen.getByTestId('viewport-y').textContent)).toBe(1086);
+    expect(focusedViewportX).toBe(10);
+    expect(focusedViewportY).toBe(1228);
+    expect(Number(screen.getByTestId('viewport-x').textContent)).toBe(
+      focusedViewportX,
+    );
+    expect(Number(screen.getByTestId('viewport-y').textContent)).toBe(
+      focusedViewportY,
+    );
   });
 });
diff --git a/src/components/image-editor/useImageCanvasGenerationSurface.tsx b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
index 8b2bafd85..4ad836552 100644
--- a/src/components/image-editor/useImageCanvasGenerationSurface.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
@@ -7,7 +7,6 @@ import {
   type SetStateAction,
   useCallback,
   useEffect,
-  useLayoutEffect,
   useRef,
 } from 'react';
 import { createPortal } from 'react-dom';
@@ -42,7 +41,6 @@ import {
   resolveGenerationComposerStyle,
   resolveIconComposerStyle,
   resolveQuickEditPanelStyle,
-  resolveViewportForOverlayVisibility,
 } from './ImageCanvasOverlayModel';
 import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
 
@@ -138,73 +136,12 @@ function buildToolbarPortalMenuStyle(
 }
 
 const TOOLBAR_OPTION_CLOSE_DELAY_MS = 160;
-const COMPOSER_SAFE_MARGIN = 12;
-const COMPOSER_MIN_SAFE_HEIGHT = 120;
-
-function getViewportLocalBounds(
-  element: Element | null,
-  viewportRect: DOMRect,
-) {
-  const rect = element?.getBoundingClientRect();
-  if (!rect) {
-    return null;
-  }
-  return {
-    left: rect.left - viewportRect.left,
-    top: rect.top - viewportRect.top,
-    right: rect.right - viewportRect.left,
-    bottom: rect.bottom - viewportRect.top,
-  };
-}
-
-function getComposerSafeBounds(viewportElement: HTMLElement) {
-  const viewportRect = viewportElement.getBoundingClientRect();
-  const bottomToolbarBounds = getViewportLocalBounds(
-    viewportElement.querySelector('.image-canvas-editor__bottom-toolbar'),
-    viewportRect,
-  );
-  const panelDockBounds = getViewportLocalBounds(
-    viewportElement.querySelector('.image-canvas-editor__panel-dock'),
-    viewportRect,
-  );
-  const coveredBottom = Math.min(
-    viewportRect.height,
-    ...[bottomToolbarBounds, panelDockBounds]
-      .map((bounds) => bounds?.top)
-      .filter((top): top is number => typeof top === 'number'),
-  );
-  const safeBottom = Math.max(
-    COMPOSER_SAFE_MARGIN + COMPOSER_MIN_SAFE_HEIGHT,
-    coveredBottom - COMPOSER_SAFE_MARGIN,
-  );
-  return {
-    left: COMPOSER_SAFE_MARGIN,
-    top: COMPOSER_SAFE_MARGIN,
-    right: Math.max(
-      COMPOSER_SAFE_MARGIN,
-      viewportRect.width - COMPOSER_SAFE_MARGIN,
-    ),
-    bottom: safeBottom,
-  };
-}
-
-function getActiveComposerElement(viewportElement: HTMLElement) {
-  return viewportElement.querySelector<HTMLElement>(
-    [
-      '.image-canvas-editor__generation-composer[role="dialog"]',
-      '.image-canvas-editor__quick-edit-panel[role="dialog"]',
-      '.image-canvas-editor__crop-expand-panel[role="dialog"]',
-      '.image-canvas-editor__character-animation-panel[role="dialog"]',
-    ].join(', '),
-  );
-}
 
 export function useImageCanvasGenerationSurface({
   layers,
   canvasSize,
   viewport,
   setViewport,
-  canvasViewportRef,
   setLayers,
   layerCounterRef,
   specToolWrapRef,
@@ -246,7 +183,6 @@ export function useImageCanvasGenerationSurface({
   const toolbarOptionCloseTimerRef = useRef<ReturnType<
     typeof setTimeout
   > | null>(null);
-  const adjustedComposerVisibilityKeyRef = useRef<string | null>(null);
   const generationWorkflow = useImageCanvasGenerationWorkflow({
     layers,
     canvasSize,
@@ -320,73 +256,6 @@ export function useImageCanvasGenerationSurface({
           viewport,
           canvasSize,
         });
-  const activeComposerVisibilityKey =
-    activeCanvasGenerationDialog &&
-    activeCanvasGenerationDialog.status !== 'generating' &&
-    activeCanvasGenerationDialog.composerOpen !== false &&
-    generationComposerStyle
-      ? `${activeCanvasGenerationDialog.id}:${activeCanvasGenerationDialog.mode}:${activeCanvasGenerationDialog.placeholder?.x ?? '-'}:${activeCanvasGenerationDialog.placeholder?.y ?? '-'}:${activeCanvasGenerationDialog.placeholder?.width ?? '-'}:${activeCanvasGenerationDialog.placeholder?.height ?? '-'}`
-      : generationWorkflow.quickEditPanel &&
-          generationWorkflow.quickEditSourceLayer &&
-          quickEditPanelStyle
-        ? `quick-edit-panel:${generationWorkflow.quickEditPanel.sourceLayerId}:${generationWorkflow.quickEditPanel.mode ?? 'quick-edit'}`
-        : generationWorkflow.cropExpandPanel &&
-            generationWorkflow.cropExpandSourceLayer &&
-            cropExpandPanelStyle
-          ? `crop-expand-panel:${generationWorkflow.cropExpandPanel.sourceLayerId}`
-          : generationWorkflow.characterAnimationPanel &&
-              generationWorkflow.characterAnimationSourceLayer &&
-              characterAnimationPanelStyle
-            ? `character-animation-panel:${generationWorkflow.characterAnimationPanel.sourceLayerId}`
-            : null;
-
-  useLayoutEffect(() => {
-    if (!activeComposerVisibilityKey) {
-      adjustedComposerVisibilityKeyRef.current = null;
-      return;
-    }
-    if (
-      adjustedComposerVisibilityKeyRef.current === activeComposerVisibilityKey
-    ) {
-      return;
-    }
-    const viewportElement = canvasViewportRef.current;
-    if (!viewportElement) {
-      return;
-    }
-    const composerElement = getActiveComposerElement(viewportElement);
-    if (!composerElement) {
-      return;
-    }
-    const viewportRect = viewportElement.getBoundingClientRect();
-    if (viewportRect.width <= 0 || viewportRect.height <= 0) {
-      return;
-    }
-    const composerRect = composerElement.getBoundingClientRect();
-    if (composerRect.width <= 0 || composerRect.height <= 0) {
-      return;
-    }
-    const nextViewport = resolveViewportForOverlayVisibility({
-      viewport,
-      overlayBounds: {
-        left: composerRect.left - viewportRect.left,
-        top: composerRect.top - viewportRect.top,
-        right: composerRect.right - viewportRect.left,
-        bottom: composerRect.bottom - viewportRect.top,
-      },
-      safeBounds: getComposerSafeBounds(viewportElement),
-    });
-    if (nextViewport !== viewport) {
-      adjustedComposerVisibilityKeyRef.current = activeComposerVisibilityKey;
-      setViewport(nextViewport);
-    }
-  }, [
-    activeComposerVisibilityKey,
-    canvasViewportRef,
-    setViewport,
-    viewport,
-  ]);
-
   const clearToolbarOptionCloseTimer = useCallback(() => {
     if (!toolbarOptionCloseTimerRef.current) {
       return;
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
index c1bc0b962..992f48830 100644
--- a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
@@ -922,7 +922,7 @@ describe('useImageCanvasGenerationWorkflow', () => {
     );
   });
 
-  it('places a new generation placeholder away from existing canvas images and centers the viewport on it', () => {
+  it('places a new generation placeholder away from existing canvas images and focuses the viewport on it', () => {
     render(
       <GenerationWorkflowHarness
         initialLayers={[
@@ -945,7 +945,7 @@ describe('useImageCanvasGenerationWorkflow', () => {
     expect(screen.getByTestId('viewport').textContent).toBe('1538:20:2');
   });
 
-  it('places a new video generation placeholder away from existing canvas images and centers the viewport on it', () => {
+  it('places a new video generation placeholder away from existing canvas images and focuses the viewport on it', () => {
     render(
       <GenerationWorkflowHarness
         initialLayers={[

From 754d36422793703c86e783faa8eeca61c2b9f070 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 7 Jul 2026 19:45:00 +0800
Subject: [PATCH 23/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=94=BB=E5=B8=83?=
 =?UTF-8?q?=E7=94=9F=E6=88=90=E5=88=B7=E6=96=B0=E5=90=8E=E5=AE=8C=E6=88=90?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

任务列表识别当前画布项目的未确认完成任务并发出完成通知。

编辑器收到任务完成通知后重新加载项目快照并刷新素材库。

补充刷新后任务已完成和轮询完成的回归测试。
---
 ...CanvasEditorGenerationIntegration.test.tsx | 219 +++++++++++++++++-
 .../image-editor/ImageCanvasEditorView.tsx    |  13 ++
 .../image-editor/ImageCanvasStageView.tsx     |   3 +
 .../ImageCanvasTaskSidebarView.test.tsx       |  87 ++++++-
 .../ImageCanvasTaskSidebarView.tsx            |  77 +++++-
 5 files changed, 382 insertions(+), 17 deletions(-)

diff --git a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
index d2f40c3c0..b26be96aa 100644
--- a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
+++ b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
@@ -11,6 +11,7 @@ import {
 import userEvent from '@testing-library/user-event';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
 import {
   ApiClientError,
   defaultEditorProjectLayers,
@@ -244,6 +245,34 @@ describe('ImageCanvasEditorView generation integration', () => {
     updatedAt: '2026-06-19T00:00:00.000Z',
   });
 
+  const createExternalGenerationTask = (
+    overrides: Partial<ExternalGenerationTaskRecord> = {},
+  ): ExternalGenerationTaskRecord => {
+    const now = new Date().toISOString();
+    return {
+      jobId: overrides.jobId ?? 'task-editor-character-refresh',
+      jobKind: overrides.jobKind ?? 'editor_image_generation',
+      sourceModule: overrides.sourceModule ?? 'editor-canvas',
+      sourceEntityId:
+        overrides.sourceEntityId ?? 'editor-project-refresh-completion',
+      requestLabel: overrides.requestLabel ?? '图片画布生成角色形象',
+      requestPrompt: overrides.requestPrompt ?? '刷新后角色',
+      status: overrides.status ?? 'running',
+      phaseLabel: overrides.phaseLabel ?? '生成图片',
+      phaseDetail: overrides.phaseDetail ?? '正在生成角色形象。',
+      progress: overrides.progress ?? 40,
+      error: overrides.error ?? null,
+      priceMudPoints: overrides.priceMudPoints ?? 3,
+      refundLedgerId: overrides.refundLedgerId ?? null,
+      notificationAcknowledgedAt: overrides.notificationAcknowledgedAt ?? null,
+      createdAt: overrides.createdAt ?? now,
+      startedAt: overrides.startedAt ?? now,
+      completedAt: overrides.completedAt ?? null,
+      updatedAt: overrides.updatedAt ?? now,
+      updatedAtMicros: overrides.updatedAtMicros ?? 1,
+    };
+  };
+
   const createGeneratedImageResponse = (
     input: {
       projectId?: string | null;
@@ -552,7 +581,9 @@ describe('ImageCanvasEditorView generation integration', () => {
 
     fireEvent.click(generatedImage.closest('button')!);
 
-    expect(await screen.findByRole('dialog', { name: '生成图片' })).toBeTruthy();
+    expect(
+      await screen.findByRole('dialog', { name: '生成图片' }),
+    ).toBeTruthy();
     expect(
       (screen.getByLabelText('生成提示词') as HTMLTextAreaElement).value,
     ).toBe('元数据恢复生成器');
@@ -2719,6 +2750,184 @@ describe('ImageCanvasEditorView generation integration', () => {
     ).toBeTruthy();
   });
 
+  it('reloads project and asset snapshots when a restored queued generation completed after refresh', async () => {
+    window.history.replaceState(null, '', '/editor/canvas');
+    const projectId = 'editor-project-refresh-completion';
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId,
+      title: '刷新恢复画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-refresh-character',
+          resourceId: 'generation-dialog:generation-dialog-refresh-character',
+          dialog: {
+            id: 'generation-dialog-refresh-character',
+            mode: 'character',
+            prompt: '刷新后角色',
+            status: 'generating',
+            composerOpen: false,
+            imageModel: 'gpt-image-2',
+            placeholder: {
+              x: 240,
+              y: 120,
+              width: 420,
+              height: 560,
+              originalWidth: 1024,
+              originalHeight: 1536,
+            },
+          },
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-21T00:00:00.000Z',
+    });
+    const generatedResource = createGeneratedResource({
+      resourceId: 'resource-refresh-character-result',
+      projectId,
+      imageSrc: 'data:image/png;base64,cmVmcmVzaC1yZXN1bHQ=',
+      width: 1024,
+      height: 1536,
+      assetKind: 'character',
+      generationInputs: {
+        fields: [{ title: '角色设定', value: '刷新后角色' }],
+        references: [],
+      },
+    });
+    loadEditorProjectMock.mockResolvedValueOnce({
+      projectId,
+      title: '刷新恢复画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-refresh-character-result',
+          resourceId: 'resource-refresh-character-result',
+          title: '刷新后生成结果',
+          x: 240,
+          y: 120,
+          width: 1024,
+          height: 1536,
+          originalWidth: 1024,
+          originalHeight: 1536,
+          zIndex: 12,
+          sourceType: 'generated',
+          assetKind: 'character',
+        },
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-refresh-character',
+          resourceId: 'generation-dialog:generation-dialog-refresh-character',
+          dialog: {
+            id: 'generation-dialog-refresh-character',
+            mode: 'character',
+            prompt: '刷新后角色',
+            status: 'idle',
+            composerOpen: false,
+            generatedLayerId: 'layer-refresh-character-result',
+            imageModel: 'gpt-image-2',
+            placeholder: {
+              x: 240,
+              y: 120,
+              width: 420,
+              height: 560,
+              originalWidth: 1024,
+              originalHeight: 1536,
+            },
+          },
+        },
+      ],
+      resources: [generatedResource],
+      updatedAt: '2026-06-21T00:01:00.000Z',
+    });
+    loadEditorAssetLibraryMock
+      .mockResolvedValueOnce({
+        folders: [
+          {
+            folderId: 'project',
+            label: '项目素材',
+            sortOrder: 0,
+            collapsed: false,
+            systemDefault: true,
+          },
+        ],
+        assets: [],
+      })
+      .mockResolvedValueOnce({
+        folders: [
+          {
+            folderId: 'project',
+            label: '项目素材',
+            sortOrder: 0,
+            collapsed: false,
+            systemDefault: true,
+          },
+        ],
+        assets: [
+          createGeneratedAsset({
+            assetId: 'asset-refresh-character-result',
+            folderId: 'project',
+            label: '刷新后生成结果素材',
+            imageSrc: 'data:image/png;base64,cmVmcmVzaC1yZXN1bHQ=',
+            width: 1024,
+            height: 1536,
+            assetKind: 'character',
+          }),
+        ],
+      });
+    const completedTask = createExternalGenerationTask({
+      jobId: 'task-refresh-character-result',
+      sourceEntityId: projectId,
+      requestPrompt: '刷新后角色',
+      status: 'completed',
+      progress: 100,
+      phaseDetail: '生成已完成。',
+      completedAt: '2026-06-21T00:01:00.000Z',
+      updatedAt: '2026-06-21T00:01:00.000Z',
+      updatedAtMicros: 2,
+    });
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+      const requestUrl =
+        typeof input === 'string'
+          ? input
+          : input instanceof URL
+            ? input.href
+            : input.url;
+      const url = new URL(requestUrl, 'http://localhost');
+      if (url.pathname === '/api/runtime/external-generation/jobs') {
+        const statuses = url.searchParams.get('statuses') ?? '';
+        return new Response(
+          JSON.stringify({
+            overview: {
+              pendingCount: 0,
+              runningCount: 0,
+              unacknowledgedTerminalCount: 1,
+              updatedAtMicros: 2,
+            },
+            tasks: statuses.includes('completed') ? [completedTask] : [],
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      }
+      return new Response(null, { status: 404 });
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    await waitFor(() => {
+      expect(loadEditorProjectMock).toHaveBeenCalledWith(projectId);
+    });
+    expect(await screen.findByAltText('画布图片：刷新后生成结果')).toBeTruthy();
+    await waitFor(() => {
+      expect(loadEditorAssetLibraryMock).toHaveBeenCalledTimes(2);
+    });
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(createEditorProjectResourceMock).not.toHaveBeenCalled();
+  });
+
   it('allows icon asset generation to reference icon specs created from the renamed spec entry', async () => {
     generateEditorImageMock.mockImplementationOnce(async (input) =>
       createGeneratedImageResponse(input, {
@@ -3174,7 +3383,9 @@ describe('ImageCanvasEditorView generation integration', () => {
     });
 
     expect(
-      within(screen.getByRole('dialog', { name: 'UI素材提取' })).getByRole<HTMLButtonElement>('button', {
+      within(
+        screen.getByRole('dialog', { name: 'UI素材提取' }),
+      ).getByRole<HTMLButtonElement>('button', {
         name: '提取',
       }).disabled,
     ).toBe(false);
@@ -3265,9 +3476,7 @@ describe('ImageCanvasEditorView generation integration', () => {
     });
     render(<ImageCanvasEditorView />);
 
-    const uiDesignImage = await screen.findByAltText(
-      '画布图片：背包UI设计图',
-    );
+    const uiDesignImage = await screen.findByAltText('画布图片：背包UI设计图');
     fireEvent.pointerDown(uiDesignImage.closest('button')!, {
       button: 0,
       pointerId: 256,
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index d74f18dbb..561bd2f15 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -1052,6 +1052,18 @@ export function ImageCanvasEditorView({
     },
     [applyProjectSnapshot, refreshAssetLibrary],
   );
+  const handleExternalGenerationTasksCompleted = useCallback(
+    (tasks: ExternalGenerationTaskRecord[]) => {
+      if (!projectId || tasks.length === 0) {
+        return;
+      }
+      refreshEditorWalletBalance();
+      void loadEditorProject(projectId)
+        .then(applyGeneratedProjectSnapshot)
+        .catch(() => undefined);
+    },
+    [applyGeneratedProjectSnapshot, projectId, refreshEditorWalletBalance],
+  );
   const handleEditorAgentGenerationResult = useCallback(
     (event: EditorAgentGenerationResultEvent) => {
       const hasGeneratedResource = event.images.some((image) =>
@@ -2033,6 +2045,7 @@ export function ImageCanvasEditorView({
     onGenerationFrameContextMenu: handleGenerationFrameContextMenu,
     onActivateGenerationDialog: activateCanvasGenerationDialog,
     onFocusExternalTask: focusExternalGenerationTask,
+    onExternalTasksCompleted: handleExternalGenerationTasksCompleted,
     onEditorAgentGenerationResult: handleEditorAgentGenerationResult,
     onToggleTaskSidebar: toggleTaskSidebar,
     onToggleAgentConversation: toggleAgentConversation,
diff --git a/src/components/image-editor/ImageCanvasStageView.tsx b/src/components/image-editor/ImageCanvasStageView.tsx
index 3867fb717..fb9a8630a 100644
--- a/src/components/image-editor/ImageCanvasStageView.tsx
+++ b/src/components/image-editor/ImageCanvasStageView.tsx
@@ -125,6 +125,7 @@ export type ImageCanvasStageViewProps = {
   ) => void;
   onActivateGenerationDialog: (dialog: CanvasGenerationDialogState) => void;
   onFocusExternalTask: (task: ExternalGenerationTaskRecord) => void;
+  onExternalTasksCompleted?: (tasks: ExternalGenerationTaskRecord[]) => void;
   onEditorAgentGenerationResult?: (
     event: EditorAgentGenerationResultEvent,
   ) => void;
@@ -257,6 +258,7 @@ export function ImageCanvasStageView({
   onGenerationFrameContextMenu,
   onActivateGenerationDialog,
   onFocusExternalTask,
+  onExternalTasksCompleted,
   onEditorAgentGenerationResult,
   onToggleTaskSidebar,
   onToggleAgentConversation,
@@ -465,6 +467,7 @@ export function ImageCanvasStageView({
         open={isTaskSidebarOpen}
         onToggleOpen={onToggleTaskSidebar}
         onFocusExternalTask={onFocusExternalTask}
+        onExternalTasksCompleted={onExternalTasksCompleted}
       />
 
       {isAgentConversationEnabled ? (
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
index 41fed163c..32915556e 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.test.tsx
@@ -1,6 +1,12 @@
 // @vitest-environment jsdom
 
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ExternalGenerationTaskRecord } from '../../../packages/shared/src/contracts/externalGeneration';
@@ -239,9 +245,7 @@ describe('ImageCanvasTaskSidebarView', () => {
 
     expect(await screen.findByText('图片画布生成图片')).toBeTruthy();
     expect(screen.getByText(/发光猫咪主视觉/u)).toBeTruthy();
-    expect(
-      screen.getByText(/正在生成第 2\/4 段。 · 已用时 1分/u),
-    ).toBeTruthy();
+    expect(screen.getByText(/正在生成第 2\/4 段。 · 已用时 1分/u)).toBeTruthy();
     expect(screen.queryByText(/35%/u)).toBeNull();
     expect(screen.getByText(/已用时 1分/u)).toBeTruthy();
     expect(screen.queryByText(/总进度/u)).toBeNull();
@@ -356,6 +360,81 @@ describe('ImageCanvasTaskSidebarView', () => {
     expect(listExternalGenerationTasksMock).toHaveBeenCalledTimes(4);
   });
 
+  it('notifies when a restored active external task completes during polling', async () => {
+    vi.useFakeTimers();
+    try {
+      const onExternalTasksCompleted = vi.fn();
+      let activeRequestCount = 0;
+      const runningTask = createExternalTask({
+        jobId: 'restored-character-task',
+        requestLabel: '角色图片',
+        status: 'running',
+      });
+      const completedTask = createExternalTask({
+        ...runningTask,
+        status: 'completed',
+        progress: 100,
+        phaseDetail: '生成已完成。',
+        completedAt: new Date().toISOString(),
+      });
+      listExternalGenerationTasksMock.mockImplementation(
+        (options: Parameters<typeof listExternalGenerationTasks>[0] = {}) => {
+          if (options.statuses?.includes('running')) {
+            activeRequestCount += 1;
+            return Promise.resolve({
+              overview: {
+                pendingCount: activeRequestCount === 1 ? 1 : 0,
+                runningCount: activeRequestCount === 1 ? 1 : 0,
+                unacknowledgedTerminalCount: activeRequestCount === 1 ? 0 : 1,
+                updatedAtMicros: activeRequestCount,
+              },
+              tasks: activeRequestCount === 1 ? [runningTask] : [],
+            });
+          }
+          return Promise.resolve({
+            overview: {
+              pendingCount: 0,
+              runningCount: 0,
+              unacknowledgedTerminalCount: activeRequestCount > 1 ? 1 : 0,
+              updatedAtMicros: activeRequestCount,
+            },
+            tasks: activeRequestCount > 1 ? [completedTask] : [],
+          });
+        },
+      );
+
+      render(
+        <ImageCanvasTaskSidebarView
+          open
+          onToggleOpen={vi.fn()}
+          onFocusExternalTask={vi.fn()}
+          onExternalTasksCompleted={onExternalTasksCompleted}
+        />,
+      );
+
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+      expect(screen.getByText('角色图片')).toBeTruthy();
+
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(4000);
+        await Promise.resolve();
+      });
+
+      expect(onExternalTasksCompleted).toHaveBeenCalledWith([
+        expect.objectContaining({
+          jobId: 'restored-character-task',
+          status: 'completed',
+        }),
+      ]);
+      expect(onExternalTasksCompleted).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('loads more completed tasks while scrolling and keeps the request capped', async () => {
     const completedTasks = Array.from({ length: 120 }, (_, index) => {
       const completedAt = new Date(Date.now() - index * 1000).toISOString();
diff --git a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
index a63b12682..1457153fa 100644
--- a/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
+++ b/src/components/image-editor/ImageCanvasTaskSidebarView.tsx
@@ -47,6 +47,7 @@ type ImageCanvasTaskSidebarViewProps = {
   open: boolean;
   onToggleOpen: () => void;
   onFocusExternalTask: (task: ExternalGenerationTaskRecord) => void;
+  onExternalTasksCompleted?: (tasks: ExternalGenerationTaskRecord[]) => void;
 };
 
 function parseTaskTimeMs(value?: string | null) {
@@ -117,9 +118,9 @@ function externalTaskProgressDetail(
   if (!isActiveTaskStatus(status)) {
     return null;
   }
-  const values = [
-    task.phaseDetail.trim(),
-  ].filter((value): value is string => Boolean(value));
+  const values = [task.phaseDetail.trim()].filter((value): value is string =>
+    Boolean(value),
+  );
   return values.length > 0 ? values.join(' · ') : null;
 }
 
@@ -205,6 +206,10 @@ function isTerminalExternalTask(task: ExternalGenerationTaskRecord) {
   return task.status === 'completed' || task.status === 'failed';
 }
 
+function isCompletedExternalTask(task: ExternalGenerationTaskRecord) {
+  return task.status === 'completed';
+}
+
 function isEditorCanvasTaskForProject(
   task: ExternalGenerationTaskRecord,
   projectId?: string | null,
@@ -256,6 +261,7 @@ export function ImageCanvasTaskSidebarView({
   open,
   onToggleOpen,
   onFocusExternalTask,
+  onExternalTasksCompleted,
 }: ImageCanvasTaskSidebarViewProps) {
   const projectId = useImageCanvasContextStore((state) => state.projectId);
   const normalizedProjectId = projectId?.trim() ?? '';
@@ -273,6 +279,8 @@ export function ImageCanvasTaskSidebarView({
       ? completedListState.limit
       : COMPLETED_TASK_LIST_LIMIT;
   const previousActiveItemCountRef = useRef(0);
+  const activeExternalTaskIdsRef = useRef<Set<string>>(new Set());
+  const completedRefreshNotifiedTaskIdsRef = useRef<Set<string>>(new Set());
   const filterVisibleExternalTasks = useCallback(
     (tasks: ExternalGenerationTaskRecord[]) =>
       tasks.filter((task) =>
@@ -280,6 +288,39 @@ export function ImageCanvasTaskSidebarView({
       ),
     [normalizedProjectId],
   );
+  const notifyCompletedExternalTasks = useCallback(
+    (
+      tasks: ExternalGenerationTaskRecord[],
+      options: {
+        activeTaskIds?: ReadonlySet<string>;
+        unacknowledgedOnly?: boolean;
+      } = {},
+    ) => {
+      const newlyCompletedTasks = tasks.filter((task) => {
+        if (
+          !isCompletedExternalTask(task) ||
+          completedRefreshNotifiedTaskIdsRef.current.has(task.jobId)
+        ) {
+          return false;
+        }
+        if (options.activeTaskIds && !options.activeTaskIds.has(task.jobId)) {
+          return false;
+        }
+        if (options.unacknowledgedOnly && task.notificationAcknowledgedAt) {
+          return false;
+        }
+        return true;
+      });
+      if (!newlyCompletedTasks.length) {
+        return;
+      }
+      for (const task of newlyCompletedTasks) {
+        completedRefreshNotifiedTaskIdsRef.current.add(task.jobId);
+      }
+      onExternalTasksCompleted?.(newlyCompletedTasks);
+    },
+    [onExternalTasksCompleted],
+  );
 
   useEffect(() => {
     setCompletedListState((state) =>
@@ -287,6 +328,7 @@ export function ImageCanvasTaskSidebarView({
         ? state
         : { limit: COMPLETED_TASK_LIST_LIMIT, projectId: normalizedProjectId },
     );
+    completedRefreshNotifiedTaskIdsRef.current = new Set();
   }, [normalizedProjectId]);
 
   useEffect(() => {
@@ -310,12 +352,18 @@ export function ImageCanvasTaskSidebarView({
         if (disposed) {
           return;
         }
+        const visibleActiveTasks = filterVisibleExternalTasks(
+          activeResponse.tasks,
+        );
+        const visibleCompletedTasks = filterVisibleExternalTasks(
+          completedResponse.tasks,
+        );
+        notifyCompletedExternalTasks(visibleCompletedTasks, {
+          unacknowledgedOnly: true,
+        });
         setExternalTasks(
           trimStoredExternalTasks(
-            mergeExternalTasks(
-              filterVisibleExternalTasks(activeResponse.tasks),
-              filterVisibleExternalTasks(completedResponse.tasks),
-            ),
+            mergeExternalTasks(visibleActiveTasks, visibleCompletedTasks),
             completedListLimit,
           ),
         );
@@ -329,7 +377,12 @@ export function ImageCanvasTaskSidebarView({
       disposed = true;
       controller.abort();
     };
-  }, [completedListLimit, filterVisibleExternalTasks, refreshKey]);
+  }, [
+    completedListLimit,
+    filterVisibleExternalTasks,
+    notifyCompletedExternalTasks,
+    refreshKey,
+  ]);
 
   const activeExternalTaskIds = useMemo(
     () =>
@@ -340,6 +393,10 @@ export function ImageCanvasTaskSidebarView({
   );
   const activeExternalTaskKey = activeExternalTaskIds.join('|');
 
+  useEffect(() => {
+    activeExternalTaskIdsRef.current = new Set(activeExternalTaskIds);
+  }, [activeExternalTaskKey, activeExternalTaskIds]);
+
   useEffect(() => {
     if (!activeExternalTaskIds.length) {
       return undefined;
@@ -371,6 +428,9 @@ export function ImageCanvasTaskSidebarView({
             filterVisibleExternalTasks(activeResponse.tasks),
             filterVisibleExternalTasks(completedResponse.tasks),
           );
+          notifyCompletedExternalTasks(refreshedTasks, {
+            activeTaskIds: activeExternalTaskIdsRef.current,
+          });
           setExternalTasks((currentTasks) =>
             trimStoredExternalTasks(
               mergeExternalTaskRefresh(currentTasks, refreshedTasks),
@@ -407,6 +467,7 @@ export function ImageCanvasTaskSidebarView({
     activeExternalTaskKey,
     completedListLimit,
     filterVisibleExternalTasks,
+    notifyCompletedExternalTasks,
   ]);
 
   const handleTaskListScroll = useCallback(

From 4e3c26d5d815957048823de3300d07c63ff71c26 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Wed, 8 Jul 2026 11:04:48 +0800
Subject: [PATCH 24/24] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20release=20=E5=8F=91?=
 =?UTF-8?q?=E5=B8=83=E4=B8=8E=E5=86=B7=E5=A4=87=E4=BB=BD=E6=81=A2=E5=A4=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

冷备份增加工作目录空间预检并确保失败后恢复依赖服务

API deploy 增加 Pingora 产物硬校验并区分 current 切换前后维护模式处理

Jenkins release 默认构建和部署 Pingora 影子网关并在全量流水线透传参数

补充备份与 API deploy 回归检查和生产运维护栏

更新生产运维文档与项目记忆的事故处理口径
---
 deploy/env/api-server.env.example             |   2 +
 docs/project-memory/shared-memory/pitfalls.md |  12 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |   7 +-
 jenkins/Jenkinsfile.production-api-build      |   2 +-
 jenkins/Jenkinsfile.production-api-deploy     |   7 +-
 ...nkinsfile.production-full-build-and-deploy |   4 +
 package.json                                  |   1 +
 scripts/check-database-backup-to-oss.mjs      | 167 ++++++++++++
 scripts/check-production-api-deploy.mjs       | 243 ++++++++++--------
 scripts/check-production-ops-guardrails.mjs   |  51 +++-
 scripts/database-backup-to-oss.mjs            | 184 ++++++++++++-
 scripts/deploy/production-api-deploy.sh       |  45 +++-
 12 files changed, 592 insertions(+), 133 deletions(-)
 create mode 100644 scripts/check-database-backup-to-oss.mjs

diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example
index 55e98f44a..7d11c33f4 100644
--- a/deploy/env/api-server.env.example
+++ b/deploy/env/api-server.env.example
@@ -139,6 +139,8 @@ 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_MIN_FREE_BYTES=
 # 可选：定时 / publish 前备份使用独立最小权限 AccessKey；为空时回退 ALIYUN_OSS_ACCESS_KEY_*。
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index ab462ce99..eb4bd1d97 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -370,7 +370,7 @@
 ## Pingora 直连 80/443 不能只改 env
 
 - 现象：`/etc/genarrative/pingora-gateway.env` 已把 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN` 改到 `0.0.0.0:443` / `0.0.0.0:80`，但 `genarrative-pingora-gateway.service` 启动失败，日志出现低端口绑定权限错误。
-- 原因：默认 service 用非 root `genarrative` 用户运行，并且主模板为了保持 shadow 安全边界不带 `CAP_NET_BIND_SERVICE`。低端口直连必须通过显式 systemd drop-in 单独授予 capability；同时 Certbot 私钥默认未必允许 `genarrative` 读取，Nginx 也可能仍占用 `80/443`。另一个常见误区是 API release 只带 `pingora-direct-enable.sh` / rollback 壳脚本，却漏带 `pingora-current-release-audit.mjs`、`pingora-direct-rehearsal-status.mjs`、`check-pingora-direct-preflight.mjs`、`check-pingora-direct-live.mjs`、`deploy/systemd/`、`deploy/env/` 或 `deploy/pingora/`，导致从 `/opt/genarrative/current` 启用时依赖 Jenkins 工作区、源码 checkout 或 `/etc` 里某份参考模板；或者 release 已经包含新版 `pingora-gateway`，但已运行的 shadow / canary / direct service 没有随 `current` 链接切换重启，仍在跑旧二进制。Server-Provision 安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 的 drop-in 只用于人工审阅和显式覆盖；直连启用脚本默认必须读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，否则旧 `/etc` 模板会掩盖发布包缺失。API deploy 脚本本身也不能继续用部署工作区根部的 `scripts/deploy/production-api-deploy.sh`，否则 Jenkins workspace 里的脚本会掩盖 `build/<version>` 发布包缺少 deploy / maintenance 同目录脚本的问题；备份脚本、健康巡检脚本和 env 示例目录同样不能从部署工作区兜底，切换命令证据脚本也不能从部署工作区兜底，否则 current release 会和上游构建归档漂移。Pingora 直连依赖、备份脚本、巡检脚本、env 示例目录和 API deploy 执行入口都必须来自上游发布产物；随包 `api-server.sha256` 和可选 `pingora-gateway.sha256` 也必须复制进 current release，供随包 current release 自审校验二进制；随包 `deploy/pingora/pingora-gateway.env.example` 也不能只检查存在，还要保持 gzip-only、不信任 XFF、前置代理确认关闭、接流保护开启和空 probe token 这些生产安全默认值；`production-api-deploy.sh` 发现缺失时应 fail-fast 并保持维护模式，不应从部署工作区兜底补齐；所有 API 发布包都必须携带 `release-manifest.json` 且登记 `api-server` artifact，发布包包含 Pingora 时还必须登记 `pingora-gateway` artifact，否则 deploy 应在切换 current 前失败；deploy 必须要求 release root、current link 和 api env file 都是绝对路径，release version 以数字或字母开头并拒绝点目录，再先写 staging release，全部复制完成后用非合并语义提升为正式 release，失败时清理 staging 且不留下正式 release，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，避免旧文件混入 current；发布包包含 Pingora 时，deploy 必须先确认 systemd 最终配置没有 direct-entry `CAP_NET_BIND_SERVICE`、env 仍是 `127.0.0.1:18081` shadow 且未配置 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，再提升 release、切换 current 并 `restart` Pingora shadow；配置不安全时必须在切换 current 前失败并保持维护模式。
+- 原因：默认 service 用非 root `genarrative` 用户运行，并且主模板为了保持 shadow 安全边界不带 `CAP_NET_BIND_SERVICE`。低端口直连必须通过显式 systemd drop-in 单独授予 capability；同时 Certbot 私钥默认未必允许 `genarrative` 读取，Nginx 也可能仍占用 `80/443`。另一个常见误区是 API release 只带 `pingora-direct-enable.sh` / rollback 壳脚本，却漏带 `pingora-current-release-audit.mjs`、`pingora-direct-rehearsal-status.mjs`、`check-pingora-direct-preflight.mjs`、`check-pingora-direct-live.mjs`、`deploy/systemd/`、`deploy/env/` 或 `deploy/pingora/`，导致从 `/opt/genarrative/current` 启用时依赖 Jenkins 工作区、源码 checkout 或 `/etc` 里某份参考模板；或者 release 已经包含新版 `pingora-gateway`，但已运行的 shadow / canary / direct service 没有随 `current` 链接切换重启，仍在跑旧二进制。Jenkins API Build、API Deploy 和 Full Build-And-Deploy 默认要求 Pingora 产物，并用 `--require-pingora-gateway` 在部署阶段硬校验；手工本地 API 包仍需显式 `--include-pingora-gateway` 才会把二进制、checksum 和 manifest artifact 写入发布包。Server-Provision 安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 的 drop-in 只用于人工审阅和显式覆盖；直连启用脚本默认必须读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，否则旧 `/etc` 模板会掩盖发布包缺失。API deploy 脚本本身也不能继续用部署工作区根部的 `scripts/deploy/production-api-deploy.sh`，否则 Jenkins workspace 里的脚本会掩盖 `build/<version>` 发布包缺少 deploy / maintenance 同目录脚本的问题；备份脚本、健康巡检脚本和 env 示例目录同样不能从部署工作区兜底，切换命令证据脚本也不能从部署工作区兜底，否则 current release 会和上游构建归档漂移。Pingora 直连依赖、备份脚本、巡检脚本、env 示例目录和 API deploy 执行入口都必须来自上游发布产物；随包 `api-server.sha256` 和可选 `pingora-gateway.sha256` 也必须复制进 current release，供随包 current release 自审校验二进制；随包 `deploy/pingora/pingora-gateway.env.example` 也不能只检查存在，还要保持 gzip-only、不信任 XFF、前置代理确认关闭、接流保护开启和空 probe token 这些生产安全默认值；`production-api-deploy.sh` 发现缺失时应在 current 切换前 fail-fast、清理 staging 并退出本次打开的维护模式，不应从部署工作区兜底补齐；所有 API 发布包都必须携带 `release-manifest.json` 且登记 `api-server` artifact，发布包包含 Pingora 时还必须登记 `pingora-gateway` artifact，否则 deploy 应在切换 current 前失败；deploy 必须要求 release root、current link 和 api env file 都是绝对路径，release version 以数字或字母开头并拒绝点目录，再先写 staging release，全部复制完成后用非合并语义提升为正式 release，失败时清理 staging 且不留下正式 release，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，避免旧文件混入 current；发布包包含 Pingora 时，deploy 必须先确认 systemd 最终配置没有 direct-entry `CAP_NET_BIND_SERVICE`、env 仍是 `127.0.0.1:18081` shadow 且未配置 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，再提升 release、切换 current 并 `restart` Pingora shadow；配置不安全时必须在切换 current 前失败并退出本次打开的维护模式，current 切换后的 readiness / 服务重启失败仍保留维护模式。
 - 处理：确认真实 TLS 证书和 redirect env 已写入 `/etc/genarrative/pingora-gateway.env`、service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含这份 env、当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都能读取证书链 / 私钥、current release 的 `pingora-gateway` 已存在且可执行、Nginx 或其它进程已释放 `80/443` 后，先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成只读 JSON runbook，并逐条审阅 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础 readiness、direct enable dry-run、direct enable apply、启用后 `--require-direct` 复核、rollback dry-run、rollback apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；runbook 只用于审阅，不修改系统。正式 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 或回退 smoke 各自验证到不同入口；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 把现场巡检入口覆盖成仓库默认值；如需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文。随后先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，再 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`，最后执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，由脚本先跑 direct preflight，再安装 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`、用 `systemctl is-active` 确认服务 active，再以 JSON 模式执行 direct live smoke，验证 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘，并要求 `direct-access-log` 结构化结果 `matchedCount == checked`、`missingCount=0`、`mismatchCount=0`；如果 direct live 退出 0 但缺少该结构化证据，也必须视为启用失败。直连启用后同步调整 `/etc/genarrative/health-patrol.env`：设置 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，本机打 `127.0.0.1` 时设置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，否则巡检会继续按 Nginx 模式误报。验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 或 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`；回退脚本先跑 `nginx -t`，通过后才移除 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 已移除、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`，随后 reload Nginx、确认 Nginx service 仍为 active，并用 curl smoke URL 证明公网入口已回到 Nginx；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`；回退脚本 `--apply` 不允许省略 `--reload-nginx` 或 `--nginx-smoke-url`，当 smoke URL 指向本机地址时必须同时提供 `--nginx-smoke-host <域名>`，且 host 值不能包含 URL、路径或查询；回退后把 health patrol gateway mode 改回 `nginx`，恢复切换前 public base URL / Host，并用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --expected-public-base-url <切换前Nginx巡检入口> --require-empty-public-host` 复核；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--require-empty-public-host` 换成 `--expected-public-host <切换前Host>`。若 env 已在回退命令前切回 Nginx，也可给 rollback 脚本追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让它在 Nginx smoke 后自动复核；切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若要同时证明 Pingora shadow 高端口仍活着，追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应为 `gateway=pingora-shadow`。
 - 处理补充：不要直接 chmod `/etc/letsencrypt/live` 或 `archive` 来让 Pingora 读取证书；Certbot live 路径通常是 symlink，即使 `stat -L` 看起来是普通文件，父目录权限也会让非 root `genarrative` 用户不可达。先用随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs --apply --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem --target-dir /etc/genarrative/pingora-tls/<域名>` 把证书同步到 Pingora 私有目录，再让 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向 `/etc/genarrative/pingora-tls/<域名>/fullchain.pem` 和 `privkey.pem`。脚本默认 dry-run，`--apply` 才写入，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并拒绝符号链接目标目录或目标文件。
 - 处理补充：不要在切换窗口手工编辑 `/etc/genarrative/health-patrol.env` 的三项网关变量；使用 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply --env-file /etc/genarrative/health-patrol.env --gateway-mode pingora-direct --public-base-url <直连HTTPS入口> --public-host <域名>` 切到直连，回退前用同一脚本传 `--gateway-mode nginx --public-base-url <切换前Nginx巡检入口>` 并按切换前记录选择 `--clear-public-host` 或 `--public-host <切换前Host>`。脚本只改 gateway mode / public base URL / public Host，并立即复用随包 env 复核脚本，减少空 Host 和旧值残留；生产巡检、env 复核和 env 切换脚本读取的布尔 env 都必须是明确布尔值，非法值直接失败，不能把拼写错误当成 false；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，直接用 `node script.mjs --env-file ...` 或 shebang 执行 `.mjs --env-file ...` 都可能让 Node 抢走业务参数；所有这类命令都必须写成 `node -- script.mjs --env-file ...`，或通过已内置 `node --` 的 npm script 执行。
@@ -411,7 +411,7 @@
 - 踩坑补充：证据根目录总审计选择“每类最新证据”后，还必须证明这些证据来自同一次切换时间线。最新证据选择和标准八段时间线证明只接受 `schemaVersion=1` 且带合法、规范 UTC 毫秒格式 `manifest.generatedAt` 的 manifest，命令记录 `startedAt` / `finishedAt` 也必须是 `new Date().toISOString()` 形式；缺失、非法、省略毫秒、本地时区或其它宽松可解析格式都会直接失败，不能用目录 mtime 兜底；证据目录被复制、归档或恢复后，也必须以 manifest 时间为准。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。标准八段证据都被要求时，每段审计状态都必须是 `OK`，`manifest.generatedAt` 必须满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`，且默认八段跨度不能超过 24 小时；非 OK、倒序或跨度过大都代表可能混入不同切换窗口遗留证据或现场状态未达标，必须失败后重新归档或清理证据根目录。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 记录本次放宽后的 `timeline.maxSpanMs` 与实际 `timeline.spanMs`。
 - 踩坑补充：标准八段时间线失败时不要只看顶层 `ok=false` 或 `diagnostics` 文本。`timeline.failedCount` 会按具体失败项累计，`timeline.failureBreakdown` 会把非 OK 证据、缺少时间、cutoverRunId 混入、时间倒序和跨度超限拆开计数；同一次审计可能同时暴露多个证据问题，应逐项修复后重新归档。
 - 踩坑补充：同一天多次演练或切换时，只靠“最新证据”和 24 小时窗口仍可能把两轮证据拼在一起。正式 runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；最终审计必须带 `--require-cutover-run-id <本次cutoverRunId>`，缺少该字段或 ID 不一致时必须失败。即使人工临时总审计忘记带 `--require-cutover-run-id`，标准八段时间线里只要任一证据声明了 `manifest.cutoverRunId`，八段也必须全部声明同一个值，否则总审计失败。
-- 验证：先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，确认 env、drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和 80/443 已释放；`systemctl cat genarrative-pingora-gateway.service` 必须显示 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env`；启用脚本 apply 必须先通过 current release 自审，失败时不安装 direct-entry drop-in；还必须带 direct HTTPS / HTTP / Host / redirect host / SpacetimeDB database / Pingora access log 参数，并在重启后直接完成 direct live smoke 和 direct-access-log JSON 证据校验；也可用 release readiness `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 把 HTTPS、HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id 落盘、env 预检、systemd drop-in、service EnvironmentFile 一致性、当前用户和服务用户证书可读、service 二进制可执行、显式目标库和 WSS 101 一起纳入硬门禁，并拒绝 `--direct-skip-wss`，避免 TLS 证书只按 `127.0.0.1` 误测、HTTP redirect Location 指错域名、service 实际读取另一份 env、root / deploy 用户可读但 systemd 服务用户不可读、current release 缺少可执行 `pingora-gateway`，或 WSS subscribe 隐式打到默认 SpacetimeDB 库。`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，不要让值班人员复制示例后才被 `--require-direct` 拦截。current release 自审、状态快照和证据包的布尔 env 必须是明确布尔值，非法值会失败，不得把拼错的 run / require / fail 开关当成 false。`npm run plan:pingora-direct-cutover -- --require-direct ...` 输出必须包含 Host 与回退巡检入口确认、current release preflight、启用前不带 `--require-direct` 的基础 readiness、direct enable dry-run/apply、启用后带 `--require-direct` 的复核、rollback dry-run/apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；缺少 `--require-direct`、缺少 `--rollback-health-patrol-public-base-url`、缺少 `--direct-pingora-access-log`、redirect Host 漂移或 rollback smoke Host 漂移时必须失败，避免生成缺少正式直连硬门禁或验证不同入口的切换计划。Host 与回退巡检入口确认步骤必须展示回退后要恢复的 health patrol public base URL / Host。直连后 `genarrative-health-patrol.service` 应使用 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，状态 JSON 中 `gatewayMode` 应为 `pingora-direct`，并检查 `genarrative-pingora-gateway.service` 而不是 `nginx.service`；public probe 走 `127.0.0.1` 时应带 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`。回退后 `nginx -t` 必须先通过，`systemctl cat genarrative-pingora-gateway.service` 不应再显示这两条 capability，`systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 必须仍指向 current release 的 `pingora-gateway`，`systemctl is-active nginx.service` 应为 `active`，`curl --fail --max-time 5` 访问 `--nginx-smoke-url` 应成功；若 smoke URL 为本机地址必须带 `--nginx-smoke-host <域名>`，证明正式 vhost 已回到 Nginx；随后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 复核 health patrol env，必须显示 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 与切换前记录一致，shadow probe 可选复核必须返回 `gateway=pingora-shadow`。本机提交前还要运行 `npm run check:pingora-direct-enable`、`npm run check:pingora-direct-rollback`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:pingora-production-release-build` 和 `npm run check:production-api-deploy`，确保脚本默认 dry-run 不会安装或删除 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct live 退出 0 但缺少 `direct-access-log` 结构化证据时启用失败，API release 布局自包含，真实 Pingora release 二进制能构建并进入发布包，API deploy 从发布产物内执行后 current release 自包含；缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、切换命令证据脚本、env 示例目录或 direct live smoke 脚本的发布包都必须部署失败并保持维护模式。正式直连 readiness 必须带 `--direct-health-patrol-env-file /etc/genarrative/health-patrol.env`，并用 `scripts/check-production-health-patrol-env.mjs` 阻断 health patrol 仍停在 Nginx 模式或本机 direct probe 缺少正式 Host；发布包包含 `pingora-gateway` 时，`npm run check:production-api-deploy` 必须覆盖服务 active / inactive 都会在 shadow 配置安全时执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，同时覆盖 direct-entry capability 或公网监听 env 下不会提升 release、不会切 current、不会自动 restart。
+- 验证：先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，确认 env、drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和 80/443 已释放；`systemctl cat genarrative-pingora-gateway.service` 必须显示 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env`；启用脚本 apply 必须先通过 current release 自审，失败时不安装 direct-entry drop-in；还必须带 direct HTTPS / HTTP / Host / redirect host / SpacetimeDB database / Pingora access log 参数，并在重启后直接完成 direct live smoke 和 direct-access-log JSON 证据校验；也可用 release readiness `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 把 HTTPS、HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id 落盘、env 预检、systemd drop-in、service EnvironmentFile 一致性、当前用户和服务用户证书可读、service 二进制可执行、显式目标库和 WSS 101 一起纳入硬门禁，并拒绝 `--direct-skip-wss`，避免 TLS 证书只按 `127.0.0.1` 误测、HTTP redirect Location 指错域名、service 实际读取另一份 env、root / deploy 用户可读但 systemd 服务用户不可读、current release 缺少可执行 `pingora-gateway`，或 WSS subscribe 隐式打到默认 SpacetimeDB 库。`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，不要让值班人员复制示例后才被 `--require-direct` 拦截。current release 自审、状态快照和证据包的布尔 env 必须是明确布尔值，非法值会失败，不得把拼错的 run / require / fail 开关当成 false。`npm run plan:pingora-direct-cutover -- --require-direct ...` 输出必须包含 Host 与回退巡检入口确认、current release preflight、启用前不带 `--require-direct` 的基础 readiness、direct enable dry-run/apply、启用后带 `--require-direct` 的复核、rollback dry-run/apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；缺少 `--require-direct`、缺少 `--rollback-health-patrol-public-base-url`、缺少 `--direct-pingora-access-log`、redirect Host 漂移或 rollback smoke Host 漂移时必须失败，避免生成缺少正式直连硬门禁或验证不同入口的切换计划。Host 与回退巡检入口确认步骤必须展示回退后要恢复的 health patrol public base URL / Host。直连后 `genarrative-health-patrol.service` 应使用 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，状态 JSON 中 `gatewayMode` 应为 `pingora-direct`，并检查 `genarrative-pingora-gateway.service` 而不是 `nginx.service`；public probe 走 `127.0.0.1` 时应带 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`。回退后 `nginx -t` 必须先通过，`systemctl cat genarrative-pingora-gateway.service` 不应再显示这两条 capability，`systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 必须仍指向 current release 的 `pingora-gateway`，`systemctl is-active nginx.service` 应为 `active`，`curl --fail --max-time 5` 访问 `--nginx-smoke-url` 应成功；若 smoke URL 为本机地址必须带 `--nginx-smoke-host <域名>`，证明正式 vhost 已回到 Nginx；随后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 复核 health patrol env，必须显示 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 与切换前记录一致，shadow probe 可选复核必须返回 `gateway=pingora-shadow`。本机提交前还要运行 `npm run check:pingora-direct-enable`、`npm run check:pingora-direct-rollback`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:pingora-production-release-build` 和 `npm run check:production-api-deploy`，确保脚本默认 dry-run 不会安装或删除 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct live 退出 0 但缺少 `direct-access-log` 结构化证据时启用失败，API release 布局自包含，真实 Pingora release 二进制能构建并进入发布包，API deploy 从发布产物内执行后 current release 自包含；缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、切换命令证据脚本、env 示例目录或 direct live smoke 脚本的发布包都必须在 current 切换前部署失败并退出本次打开的维护模式。正式直连 readiness 必须带 `--direct-health-patrol-env-file /etc/genarrative/health-patrol.env`，并用 `scripts/check-production-health-patrol-env.mjs` 阻断 health patrol 仍停在 Nginx 模式或本机 direct probe 缺少正式 Host；发布包包含 `pingora-gateway` 时，`npm run check:production-api-deploy` 必须覆盖服务 active / inactive 都会在 shadow 配置安全时执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，同时覆盖 direct-entry capability 或公网监听 env 下不会提升 release、不会切 current、不会自动 restart。
 - 顺序补充：正式 runbook 必须先通过 health patrol env 切换脚本预置回 Nginx 和切换前 public base URL / Host，再执行 `rollback apply`；回退脚本内置 env 复核和独立 env 复核都会阻断 public base URL / Host 漂移。
 - 顺序补充：正式 runbook 还必须在 `rollback apply` 前预置 Pingora shadow env。启用前和 `--dry-run-cutover` 要求 `80/443` 空闲；启用后 `--require-direct` 复核不再要求端口空闲，因为端口应由 Pingora 占用。回退时要先用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 恢复 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081` 并清空 TLS / HTTP redirect 低端口监听，再移除 direct-entry drop-in 和重启 Pingora。
 - 关联：`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/health-patrol.env.example`、`deploy/env/pingora-direct-live.env.example`、`deploy/env/pingora-canary-live.env.example`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/jenkins-server-provision.sh`、`scripts/build-production-release.sh`、`scripts/deploy/production-api-deploy.sh`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
@@ -466,10 +466,10 @@
 
 ## 生产冷备份后 API 和外部生成 worker 不能只依赖 SpacetimeDB 自恢复
 
-- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped；或图片画布生成请求返回队列态后长期显示排队，`external_generation_job` 有 claimable pending，但 `genarrative-external-generation-worker@1.service` / controller 是 inactive。
-- 原因：`genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时这些服务会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只恢复数据库或只重启 API，外部生成队列就不会被消费。
-- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`、`--restart-service-after genarrative-external-generation-worker@1.service` 和 `--restart-service-after genarrative-external-generation-controller.service`；`genarrative-api.service` 也保留对 controller 的 `Wants` 弱依赖，覆盖“只恢复 API”的现场兜底。仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
-- 验证：`systemctl cat genarrative-database-backup.service` 应包含这些参数；`systemctl is-active spacetimedb.service genarrative-api.service genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功；`get_external_generation_queue_stats_and_return` 不应长期出现 claimable pending。
+- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped；或图片画布生成请求返回队列态后长期显示排队，`external_generation_job` 有 claimable pending，但 `genarrative-external-generation-worker@1.service` / controller 是 inactive；也可能先看到 `/var/lib/genarrative/database-backups` 把根分区写满，`gzip: stdout: No space left on device`。
+- 原因：`genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时这些服务会被 systemd 依赖关系一并停止；如果备份脚本只在打包成功后重启依赖服务，那么 tar/gzip 因空间不足失败时就只会恢复数据库，外部生成队列和 API 仍无人接管。
+- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`、`--restart-service-after genarrative-external-generation-worker@1.service` 和 `--restart-service-after genarrative-external-generation-controller.service`；备份脚本必须在停止 SpacetimeDB 前做工作目录剩余空间预检，并且一旦已经停过 SpacetimeDB，就算打包失败也要先恢复 SpacetimeDB 与这些依赖服务，再返回原始备份错误。`genarrative-api.service` 也保留对 controller 的 `Wants` 弱依赖，覆盖“只恢复 API”的现场兜底。仓库用 `npm run check:production-ops` 和 `npm run check:database-backup` 检查 systemd 模板、脚本失败路径、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
+- 验证：`systemctl cat genarrative-database-backup.service` 应包含这些参数；`systemctl is-active spacetimedb.service genarrative-api.service genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功；`npm run check:database-backup` 覆盖空间不足不触碰 systemctl、tar 失败仍恢复依赖服务；`get_external_generation_queue_stats_and_return` 不应长期出现 claimable pending。
 - 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## Pingora Brotli 不能只看 Content-Encoding
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index c72151731..401703837 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -245,11 +245,12 @@ 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_MIN_FREE_BYTES=
 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 单独配置最小权限账号。`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`。
+`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`。
 
 冷备份后必须做一次只读验收，不要只看 `genarrative-database-backup.service` 是否成功退出：
 
@@ -326,7 +327,7 @@ current release 自审的 `--release-root` 和 `--systemd-service` 不能包含
 
 current release 自审、状态快照、证据包、direct preflight、生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，拼写错误会直接失败，避免 `REQUIRE_GATEWAY`、`RUN_HEALTH_PATROL`、`REQUIRE_PINGORA_GATEWAY`、`FAIL_ON_CRITICAL`、`TRUST_X_FORWARDED_FOR` 或巡检切换开关被悄悄当成 false。
 
-正式直连 runbook 的启用前 release readiness 基础门禁和启用后 `--require-direct` 复核，都必须调用 current release 随包的 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs`。生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和 `production-api-deploy.sh` 都必须携带该聚合门禁脚本；缺失时部署应 fail-fast 并保持维护模式，切换窗口不能回退到源码 checkout 或 Jenkins workspace 的相对路径脚本。
+正式直连 runbook 的启用前 release readiness 基础门禁和启用后 `--require-direct` 复核，都必须调用 current release 随包的 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs`。生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和 `production-api-deploy.sh` 都必须携带该聚合门禁脚本；缺失时部署应在 current 切换前 fail-fast、清理 staging 并退出本次打开的维护模式，切换窗口不能回退到源码 checkout 或 Jenkins workspace 的相对路径脚本。
 
 current release 随包执行的 release readiness 必须追加 `--release-runtime-only`，只运行包内可自包含的 current release 自审、live canary、真实 access log 对账、direct preflight、health patrol env 复核和 direct live smoke；不要在 `/opt/genarrative/current` 上运行默认源码全量门禁。默认不带 `--release-runtime-only` 的聚合门禁仍属于本机 / CI / 构建环境使用，负责覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测。
 
@@ -365,7 +366,7 @@ cat /var/lib/genarrative/health-patrol/status.json
 
 `Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json` 和 `scripts/deploy/production-web-deploy.sh` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物和部署脚本，不再在目标机器 checkout Git，再执行随构建归档的 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
 
-`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`deploy/systemd/**`、`deploy/env/**` 和 `deploy/pingora/**`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制并执行 `build/<version>/scripts/deploy/production-api-deploy.sh`，同目录的 `maintenance-on.sh` / `maintenance-off.sh` 也必须来自同一 build 产物；部署脚本会先写入 `${RELEASE_ROOT}/.${VERSION}.staging.$$`，把 `release-manifest.json` 校验后复制为 current release 的 `release-manifest.api-server.json`，并把备份脚本、巡检脚本、Pingora 直连启用 / 回退 / 预检 / live smoke / canary access log 对账 / health patrol env 复核 / current release 自审 / 状态快照 / 证据包 / 命令证据 / 证据验真 / 证据根目录审计脚本，以及 `deploy/systemd`、`deploy/env`、`deploy/pingora` 支撑配置全部复制完成后，才用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}` 并用固定替换语义切换 `current` 符号链接，不再在目标机器 checkout Git，也不再执行部署工作区根部脚本。Pingora 直连启用脚本必须能从 `/opt/genarrative/current` 独立执行 preflight 和 direct live smoke，并默认读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 Jenkins 工作区、源码 checkout 或 `/etc` 参考模板；`plan:pingora-direct-cutover` 必须能用同一组参数生成 current release 切换 / 回退 runbook。`production-api-deploy.sh` 对 release manifest、备份脚本、巡检脚本、env 示例目录和 Pingora 直连依赖都执行 fail-fast，且 `--release-root`、`--current-link`、`--api-env-file` 必须是绝对路径，`--version` 必须以数字或字母开头并只能包含数字、字母、点、下划线和短横线，禁止 `.` / `..` 点目录；发布产物缺少 manifest、manifest 未登记 `api-server`、缺少脚本 / 配置目录、同版本 release 目录已存在、current 路径不是符号链接、提升前 release 目录竞态出现或 staging 构建中失败时会保留维护模式并停止部署；失败会清理 staging 目录且不会留下正式 release 目录，不再从部署机工作区兜底补文件，也不把旧同名 release 目录和新文件混合。如果 API 发布后 current release 中缺少这些脚本或目录，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`build/<version>/scripts/database-backup-to-oss.mjs`、`build/<version>/scripts/ops/production-health-patrol.mjs`、`build/<version>/scripts/ops/pingora-current-release-audit.mjs`、`build/<version>/scripts/ops/pingora-cutover-status-snapshot.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-bundle.mjs`、`build/<version>/scripts/ops/pingora-cutover-command-evidence.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-verify.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-audit.mjs`、`build/<version>/scripts/check-pingora-direct-preflight.mjs`、`build/<version>/scripts/check-pingora-direct-live.mjs`、`build/<version>/scripts/check-pingora-canary-access-log-parity.mjs`、`build/<version>/scripts/check-production-health-patrol-env.mjs`、`build/<version>/scripts/deploy/pingora-direct-enable.sh`、`build/<version>/scripts/deploy/pingora-direct-rollback.sh`、`build/<version>/deploy/systemd/**`、`build/<version>/deploy/env/**` 与 `build/<version>/deploy/pingora/**`，不要只在部署机工作区手工补文件。本机用 `npm run check:production-api-release` 通过临时 `CARGO_TARGET_DIR` 和假 `api-server` / `pingora-gateway` release binary 验证 `build-production-release.sh --component api-server --skip-api-build` 会把这些文件打进 API release，并验证显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时发布包包含 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记；`npm run check:pingora-production-release-build` 则用假 `api-server` 和真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu` 验证显式 include 路径能构出可执行网关二进制、checksum 和 manifest 登记；再用 `npm run check:production-api-deploy` 通过临时 release、fake `systemctl` / `curl` 验证从发布产物内执行 `production-api-deploy.sh` 会把这些文件复制到 current release，并验证缺少 release manifest、manifest 未登记 `api-server`、缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、current release 自审脚本、状态快照脚本、证据包脚本、证据验真脚本、证据根目录审计脚本、canary access log 对账脚本、env 示例目录或 direct live smoke 脚本时都会失败且保持维护模式，还会验证相对 release root / current link / api env file、点目录或点开头 version 被拒绝、失败时不留下 staging / 正式 release 目录、同版本 release 目录已存在、current 路径不是符号链接或提升前 release 目录竞态出现时拒绝覆盖 / 合并。Pingora 影子网关不是默认 API 归档物；只有显式用 `npm run build:production-release -- --component api-server --include-pingora-gateway` 或在 `Genarrative-Api-Build` 勾选 `INCLUDE_PINGORA_GATEWAY` 时，发布包才包含 `pingora-gateway` / `pingora-gateway.sha256`，API deploy 会在两者同时存在且 manifest 登记 `pingora-gateway` 时校验并复制到 current release；此时 build 脚本和 Jenkins 会先检查 `cmake`、C 编译器和 C++ 编译器，避免进入 Cargo 后才因 `libz-ng-sys` 构建依赖缺失失败。发布包包含 Pingora 时，deploy 会在提升 release 前读取 `systemctl cat genarrative-pingora-gateway.service` 和其 `EnvironmentFile`，拒绝 direct-entry `CAP_NET_BIND_SERVICE`、拒绝非 `127.0.0.1:18081` 的 shadow listen、拒绝 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current；切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，让 shadow / canary 机器加载新网关二进制。该自动拉起不会启用公网 `80/443` 直连入口；已经进入 direct-entry 状态的机器应走正式直连 runbook 或先回退到 shadow。
+`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`deploy/systemd/**`、`deploy/env/**` 和 `deploy/pingora/**`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制并执行 `build/<version>/scripts/deploy/production-api-deploy.sh`，同目录的 `maintenance-on.sh` / `maintenance-off.sh` 也必须来自同一 build 产物；部署脚本会先写入 `${RELEASE_ROOT}/.${VERSION}.staging.$$`，把 `release-manifest.json` 校验后复制为 current release 的 `release-manifest.api-server.json`，并把备份脚本、巡检脚本、Pingora 直连启用 / 回退 / 预检 / live smoke / canary access log 对账 / health patrol env 复核 / current release 自审 / 状态快照 / 证据包 / 命令证据 / 证据验真 / 证据根目录审计脚本，以及 `deploy/systemd`、`deploy/env`、`deploy/pingora` 支撑配置全部复制完成后，才用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}` 并用固定替换语义切换 `current` 符号链接，不再在目标机器 checkout Git，也不再执行部署工作区根部脚本。Pingora 直连启用脚本必须能从 `/opt/genarrative/current` 独立执行 preflight 和 direct live smoke，并默认读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 Jenkins 工作区、源码 checkout 或 `/etc` 参考模板；`plan:pingora-direct-cutover` 必须能用同一组参数生成 current release 切换 / 回退 runbook。`production-api-deploy.sh` 对 release manifest、备份脚本、巡检脚本、env 示例目录和 Pingora 直连依赖都执行 fail-fast，且 `--release-root`、`--current-link`、`--api-env-file` 必须是绝对路径，`--version` 必须以数字或字母开头并只能包含数字、字母、点、下划线和短横线，禁止 `.` / `..` 点目录；发布产物缺少 manifest、manifest 未登记 `api-server`、缺少脚本 / 配置目录、同版本 release 目录已存在、current 路径不是符号链接、提升前 release 目录竞态出现或 staging 构建中失败时会在 current 切换前停止部署，清理 staging 并退出本次打开的维护模式；current 切换后的 Pingora 重启、worker 重启、controller 启动或 readiness 失败仍保留维护模式，避免暴露半发布版本；失败不会留下正式 release 目录，不再从部署机工作区兜底补文件，也不把旧同名 release 目录和新文件混合。如果 API 发布后 current release 中缺少这些脚本或目录，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`build/<version>/scripts/database-backup-to-oss.mjs`、`build/<version>/scripts/ops/production-health-patrol.mjs`、`build/<version>/scripts/ops/pingora-current-release-audit.mjs`、`build/<version>/scripts/ops/pingora-cutover-status-snapshot.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-bundle.mjs`、`build/<version>/scripts/ops/pingora-cutover-command-evidence.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-verify.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-audit.mjs`、`build/<version>/scripts/check-pingora-direct-preflight.mjs`、`build/<version>/scripts/check-pingora-direct-live.mjs`、`build/<version>/scripts/check-pingora-canary-access-log-parity.mjs`、`build/<version>/scripts/check-production-health-patrol-env.mjs`、`build/<version>/scripts/deploy/pingora-direct-enable.sh`、`build/<version>/scripts/deploy/pingora-direct-rollback.sh`、`build/<version>/deploy/systemd/**`、`build/<version>/deploy/env/**` 与 `build/<version>/deploy/pingora/**`，不要只在部署机工作区手工补文件。本机用 `npm run check:production-api-release` 通过临时 `CARGO_TARGET_DIR` 和假 `api-server` / `pingora-gateway` release binary 验证 `build-production-release.sh --component api-server --skip-api-build` 会把这些文件打进 API release，并验证显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时发布包包含 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记；`npm run check:pingora-production-release-build` 则用假 `api-server` 和真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu` 验证显式 include 路径能构出可执行网关二进制、checksum 和 manifest 登记；再用 `npm run check:production-api-deploy` 通过临时 release、fake `systemctl` / `curl` 验证从发布产物内执行 `production-api-deploy.sh` 会把这些文件复制到 current release，并验证缺少 release manifest、manifest 未登记 `api-server`、Pingora manifest / 二进制漂移、`--require-pingora-gateway` 缺少 Pingora、缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、current release 自审脚本、状态快照脚本、证据包脚本、证据验真脚本、证据根目录审计脚本、canary access log 对账脚本、env 示例目录或 direct live smoke 脚本时都会在 current 切换前失败并退出本次打开的维护模式，还会验证相对 release root / current link / api env file、点目录或点开头 version 被拒绝、失败时不留下 staging / 正式 release 目录、同版本 release 目录已存在、current 路径不是符号链接、提升前 release 目录竞态出现时拒绝覆盖 / 合并，以及 current 切换后的 readiness 失败会保留维护模式。Pingora 影子网关在 `Genarrative-Api-Build`、`Genarrative-Api-Deploy` 和 `Genarrative-Full-Build-And-Deploy` 中默认随 release 构建、归档、复制并用 `--require-pingora-gateway` 硬校验；只有显式取消 `INCLUDE_PINGORA_GATEWAY` 时才允许 API release 不带 `pingora-gateway` / `pingora-gateway.sha256`。本地 CLI 仍保留显式 `npm run build:production-release -- --component api-server --include-pingora-gateway`，用于在需要 Pingora 的手工发布包里登记 manifest 和 checksum；Jenkins 会先检查 `cmake`、C 编译器和 C++ 编译器，避免进入 Cargo 后才因 `libz-ng-sys` 构建依赖缺失失败。发布包包含 Pingora 时，deploy 会在提升 release 前读取 `systemctl cat genarrative-pingora-gateway.service` 和其 `EnvironmentFile`，拒绝 direct-entry `CAP_NET_BIND_SERVICE`、拒绝非 `127.0.0.1:18081` 的 shadow listen、拒绝 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current；切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，让 shadow / canary 机器加载新网关二进制。该自动拉起不会启用公网 `80/443` 直连入口；已经进入 direct-entry 状态的机器应走正式直连 runbook 或先回退到 shadow。
 
 Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.mjs`、直连切换状态快照脚本 `scripts/ops/pingora-cutover-status-snapshot.mjs`、证据包脚本 `scripts/ops/pingora-cutover-evidence-bundle.mjs`、命令证据脚本 `scripts/ops/pingora-cutover-command-evidence.mjs`、证据验真脚本 `scripts/ops/pingora-cutover-evidence-verify.mjs`、证据根目录审计脚本 `scripts/ops/pingora-cutover-evidence-audit.mjs` 和 canary access log 对账脚本 `scripts/check-pingora-canary-access-log-parity.mjs` 都属于 API release 的强制随包依赖；缺少任一脚本时 `check:production-api-release`、`check:production-api-deploy` 和生产运维护栏都必须失败，避免切换窗口只能靠 Jenkins 工作区或源码 checkout 临时补自审、证据或日志对账脚本。
 
diff --git a/jenkins/Jenkinsfile.production-api-build b/jenkins/Jenkinsfile.production-api-build
index 0a1b0c84a..ea9496ae6 100644
--- a/jenkins/Jenkinsfile.production-api-build
+++ b/jenkins/Jenkinsfile.production-api-build
@@ -25,7 +25,7 @@ pipeline {
     string(name: 'COMMIT_HASH', defaultValue: '', description: '可选，指定属于 SOURCE_BRANCH 的 Git commit')
     string(name: 'BUILD_VERSION', defaultValue: '', description: '发布版本号，留空则使用 Jenkins BUILD_NUMBER')
     string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
-    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: false, description: '是否额外构建并归档 Pingora 影子网关二进制')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: true, description: '是否构建并归档 Pingora 影子网关二进制；release 发布默认必须包含')
     booleanParam(name: 'PUBLISH_AFTER_BUILD', defaultValue: false, description: '构建成功后是否触发 API 发布')
     string(name: 'DEPLOY_JOB_NAME', defaultValue: 'Genarrative-Api-Deploy', description: 'API 发布流水线作业名')
     choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: 'PUBLISH_AFTER_BUILD=true 时的逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
diff --git a/jenkins/Jenkinsfile.production-api-deploy b/jenkins/Jenkinsfile.production-api-deploy
index e116474b1..ccd2a32b3 100644
--- a/jenkins/Jenkinsfile.production-api-deploy
+++ b/jenkins/Jenkinsfile.production-api-deploy
@@ -16,7 +16,7 @@ pipeline {
     string(name: 'BUILD_VERSION', defaultValue: '', description: '待发布版本号')
     string(name: 'BUILD_JOB_NAME', defaultValue: 'Genarrative-Api-Build', description: 'API 构建流水线作业名')
     string(name: 'BUILD_NUMBER_TO_DEPLOY', defaultValue: '', description: '要复制归档产物的上游构建号')
-    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: false, description: '上游构建是否包含 Pingora 影子网关产物')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: true, description: '上游构建是否包含 Pingora 影子网关产物；release 发布默认必须包含')
     string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: '生产 release 根目录')
     string(name: 'CURRENT_LINK', defaultValue: '/opt/genarrative/current', description: '当前版本软链接')
     string(name: 'SERVICE_NAME', defaultValue: 'genarrative-api.service', description: 'systemd 服务名')
@@ -93,12 +93,17 @@ pipeline {
           bash -lc '
             set -euo pipefail
             chmod +x "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-on.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-off.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs" "build/${BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs" "build/${BUILD_VERSION}/scripts/deploy/pingora-tls-cert-sync.mjs"
+            pingora_deploy_args=()
+            if [[ "${INCLUDE_PINGORA_GATEWAY:-false}" == "true" ]]; then
+              pingora_deploy_args+=(--require-pingora-gateway)
+            fi
             "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" \
               --source-dir "build/${BUILD_VERSION}" \
               --version "${BUILD_VERSION}" \
               --release-root "${RELEASE_ROOT}" \
               --current-link "${CURRENT_LINK}" \
               --service "${SERVICE_NAME}" \
+              "${pingora_deploy_args[@]}" \
               --health-url "${HEALTH_URL}" \
               --api-env-file "${API_ENV_FILE:-/etc/genarrative/api-server.env}" \
               --database "${DATABASE}" \
diff --git a/jenkins/Jenkinsfile.production-full-build-and-deploy b/jenkins/Jenkinsfile.production-full-build-and-deploy
index 47904605f..279edb70d 100644
--- a/jenkins/Jenkinsfile.production-full-build-and-deploy
+++ b/jenkins/Jenkinsfile.production-full-build-and-deploy
@@ -25,6 +25,7 @@ pipeline {
     booleanParam(name: 'RUN_NPM_CI', defaultValue: true, description: 'Web 构建前是否执行 npm ci')
     string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
     string(name: 'MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID', defaultValue: '', description: '可选，透传给 Stdb module 构建的迁移 bootstrap secret 凭据 ID；留空则由 Stdb 构建自动生成')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: true, description: 'API release 是否构建、归档并部署 Pingora 影子网关；release 默认必须包含')
     string(name: 'WEB_BUILD_JOB_NAME', defaultValue: 'Genarrative-Web-Build', description: 'Web 构建流水线作业名')
     string(name: 'API_BUILD_JOB_NAME', defaultValue: 'Genarrative-Api-Build', description: 'API 构建流水线作业名')
     string(name: 'STDB_BUILD_JOB_NAME', defaultValue: 'Genarrative-Stdb-Module-Build', description: 'Stdb 构建流水线作业名')
@@ -134,6 +135,7 @@ pipeline {
                   string(name: 'COMMIT_HASH', value: env.SOURCE_COMMIT),
                   string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION),
                   string(name: 'NOTIFICATION_EMAILS', value: params.NOTIFICATION_EMAILS ?: ''),
+                  booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', value: params.INCLUDE_PINGORA_GATEWAY),
                 ]
               env.API_BUILD_NUMBER = apiRun.number.toString()
             }
@@ -196,6 +198,7 @@ pipeline {
             booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', value: params.CONFIRM_RELEASE_DEPLOY_AGENT),
             string(name: 'BUILD_JOB_NAME', value: params.API_BUILD_JOB_NAME),
             string(name: 'BUILD_NUMBER_TO_DEPLOY', value: env.API_BUILD_NUMBER),
+            booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', value: params.INCLUDE_PINGORA_GATEWAY),
             string(name: 'DATABASE', value: params.DATABASE),
             string(name: 'SPACETIME_SERVER_URL', value: params.SPACETIME_SERVER_URL ?: ''),
           ]
@@ -234,6 +237,7 @@ pipeline {
           string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION ?: (params.BUILD_VERSION ?: '')),
           string(name: 'DEPLOY_TARGET', value: params.DEPLOY_TARGET ?: ''),
           string(name: 'DATABASE', value: params.DATABASE ?: ''),
+          string(name: 'INCLUDE_PINGORA_GATEWAY', value: String.valueOf(params.INCLUDE_PINGORA_GATEWAY)),
           string(name: 'SUMMARY', value: '全量构建发布编排结束'),
         ]
         def notificationRecipients = params.NOTIFICATION_EMAILS?.trim()
diff --git a/package.json b/package.json
index 0136a88a0..69954509c 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
     "check:encoding": "node scripts/check-encoding.mjs",
     "check:spacetime-schema": "node scripts/check-spacetime-schema-guard.mjs",
     "check:production-ops": "node scripts/check-production-ops-guardrails.mjs",
+    "check:database-backup": "node scripts/check-database-backup-to-oss.mjs",
     "check:production-health-patrol": "node scripts/check-production-health-patrol.mjs",
     "check:production-health-patrol-env": "node scripts/check-production-health-patrol-env-check.mjs",
     "check:production-api-release": "node scripts/check-production-api-release.mjs",
diff --git a/scripts/check-database-backup-to-oss.mjs b/scripts/check-database-backup-to-oss.mjs
new file mode 100644
index 000000000..af154f6cf
--- /dev/null
+++ b/scripts/check-database-backup-to-oss.mjs
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import {spawnSync} from 'node:child_process';
+import {existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+
+const BACKUP_SCRIPT = path.resolve('scripts/database-backup-to-oss.mjs');
+const tmpRoot = mkdtempSync(path.join(tmpdir(), 'genarrative-database-backup-check-'));
+const failures = [];
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, {recursive: true, force: true});
+}
+
+if (failures.length > 0) {
+  console.error('[check:database-backup] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:database-backup] OK');
+
+function main() {
+  assertInsufficientSpaceStopsBeforeServiceChanges();
+  assertArchiveFailureStillRestoresDependentServices();
+}
+
+function assertInsufficientSpaceStopsBeforeServiceChanges() {
+  const fixture = createFixture('insufficient-space');
+  const result = runBackup(fixture, [
+    '--stop-service',
+    'spacetimedb.service',
+    '--restart-service-after',
+    'genarrative-api.service',
+    '--min-free-bytes',
+    '999999999999999999',
+  ]);
+
+  assertStatus(result, 1, '空间不足时必须失败。');
+  assertIncludes(result.stdout, '备份空间预检', '空间不足失败前应打印空间预检。');
+  assertIncludes(result.stderr, '剩余空间不足', '空间不足失败应说明剩余空间不足。');
+  assertFileMissing(fixture.systemctlLog, '空间不足时不能调用 systemctl。');
+  assertFileMissing(fixture.tarLog, '空间不足时不能调用 tar。');
+}
+
+function assertArchiveFailureStillRestoresDependentServices() {
+  const fixture = createFixture('tar-failure');
+  const result = runBackup(fixture, [
+    '--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',
+    '--min-free-bytes',
+    '1',
+  ]);
+
+  assertStatus(result, 1, 'tar 失败时备份脚本必须失败。');
+  assertIncludes(result.stderr, 'fake tar failure', 'tar 失败原因应保留在错误输出中。');
+  const systemctlLog = readFile(fixture.systemctlLog);
+  const expectedCommands = [
+    'systemctl stop spacetimedb.service',
+    'systemctl start spacetimedb.service',
+    'systemctl restart genarrative-api.service',
+    'systemctl restart genarrative-external-generation-worker@1.service',
+    'systemctl restart genarrative-external-generation-controller.service',
+  ];
+  for (const command of expectedCommands) {
+    assertIncludes(systemctlLog, command, `tar 失败后必须执行: ${command}`);
+  }
+}
+
+function createFixture(name) {
+  const root = path.join(tmpRoot, name);
+  const binDir = path.join(root, 'bin');
+  const dataDir = path.join(root, 'data');
+  const workDir = path.join(root, 'work');
+  const systemctlLog = path.join(root, 'systemctl.log');
+  const tarLog = path.join(root, 'tar.log');
+  mkdirSync(binDir, {recursive: true});
+  mkdirSync(dataDir, {recursive: true});
+  writeFileSync(path.join(dataDir, 'sample.bin'), 'sample backup payload\n', 'utf8');
+  writeExecutable(
+    path.join(binDir, 'systemctl'),
+    `#!/usr/bin/env bash
+printf 'systemctl %s\\n' "$*" >> "${systemctlLog}"
+exit 0
+`,
+  );
+  writeExecutable(
+    path.join(binDir, 'tar'),
+    `#!/usr/bin/env bash
+printf 'tar %s\\n' "$*" >> "${tarLog}"
+echo 'fake tar failure' >&2
+exit 2
+`,
+  );
+  return {root, binDir, dataDir, workDir, systemctlLog, tarLog};
+}
+
+function runBackup(fixture, extraArgs = []) {
+  return spawnSync(
+    process.execPath,
+    [
+      BACKUP_SCRIPT,
+      '--data-dir',
+      fixture.dataDir,
+      '--work-dir',
+      fixture.workDir,
+      '--bucket',
+      'genarrative-test',
+      '--endpoint',
+      'oss-cn-shanghai.aliyuncs.com',
+      '--access-key-id',
+      'test',
+      '--access-key-secret',
+      'test',
+      ...extraArgs,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        PATH: `${fixture.binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+      },
+    },
+  );
+}
+
+function writeExecutable(filePath, content) {
+  writeFileSync(filePath, content, 'utf8');
+  spawnSync('chmod', ['0755', filePath], {encoding: 'utf8'});
+}
+
+function readFile(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, expected, reason) {
+  if (!String(content).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertFileMissing(filePath, reason) {
+  if (existsSync(filePath)) {
+    failures.push(`${reason} 实际存在: ${filePath}\n${readFile(filePath)}`);
+  }
+}
diff --git a/scripts/check-production-api-deploy.mjs b/scripts/check-production-api-deploy.mjs
index 2eacaca7c..db9aa38d0 100644
--- a/scripts/check-production-api-deploy.mjs
+++ b/scripts/check-production-api-deploy.mjs
@@ -41,6 +41,9 @@ function main() {
   assertDeployRejectsPingoraDirectEntryWhenArtifactIncluded();
   assertDeployRejectsPingoraPublicListenWhenArtifactIncluded();
   assertDeployRejectsPingoraArtifactMissingManifestEntry();
+  assertDeployRejectsPingoraManifestEntryMissingArtifact();
+  assertDeployRequiresPingoraWhenRequested();
+  assertReadinessFailureKeepsMaintenanceAfterCurrentSwitch();
   assertMissingReleaseManifestFails();
   assertReleaseManifestMissingApiArtifactFails();
   assertDeployRejectsDotVersion();
@@ -82,6 +85,18 @@ function readOptionalCommandsLog(fixture) {
   return readFileSync(fixture.commandsLog, 'utf8');
 }
 
+function assertMaintenanceCleared(fixture, reason) {
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push(`${reason} 时应退出本次打开的维护模式。`);
+  }
+}
+
+function assertMaintenanceKept(fixture, reason) {
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push(`${reason} 时必须保持维护模式。`);
+  }
+}
+
 function assertDeployCopiesPingoraDirectReleaseDependencies() {
   const fixture = prepareFixture('with-direct-checks');
   const result = runDeploy(fixture);
@@ -409,9 +424,7 @@ function assertDeployRejectsPingoraDirectEntryWhenArtifactIncluded() {
   ) {
     failures.push('direct-entry capability 存在时不能自动 restart Pingora。');
   }
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('direct-entry capability 导致部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, 'direct-entry capability 导致部署失败');
   assertNoReleasePromoted(
     fixture,
     'direct-entry capability 导致部署失败时不能提升正式 release。',
@@ -442,9 +455,7 @@ function assertDeployRejectsPingoraPublicListenWhenArtifactIncluded() {
   ) {
     failures.push('公网监听 env 存在时不能自动 restart Pingora。');
   }
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('公网监听 env 导致部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '公网监听 env 导致部署失败');
   assertNoReleasePromoted(
     fixture,
     '公网监听 env 导致部署失败时不能提升正式 release。',
@@ -464,8 +475,67 @@ function assertDeployRejectsPingoraArtifactMissingManifestEntry() {
     'release-manifest.json 缺少 pingora-gateway artifact',
     'manifest 未登记 Pingora 时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('manifest 未登记 Pingora 导致部署失败时必须保持维护模式。');
+  assertMaintenanceCleared(fixture, 'manifest 未登记 Pingora 导致部署失败');
+}
+
+function assertDeployRejectsPingoraManifestEntryMissingArtifact() {
+  const fixture = prepareFixture('pingora-manifest-entry-missing-artifact');
+  const manifestPath = path.join(fixture.sourceDir, 'release-manifest.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  manifest.artifacts.push({
+    component: 'pingora-gateway',
+    path: 'pingora-gateway',
+    checksum_path: 'pingora-gateway.sha256',
+  });
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('manifest 登记 Pingora 但发布目录缺少二进制时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'release-manifest.json 登记了 pingora-gateway artifact',
+    'manifest 登记 Pingora 但文件缺失时必须给出明确错误。',
+  );
+  assertMaintenanceCleared(fixture, 'manifest 登记 Pingora 但文件缺失导致部署失败');
+}
+
+function assertDeployRequiresPingoraWhenRequested() {
+  const fixture = prepareFixture('require-pingora-missing-artifact');
+  const result = runDeploy(fixture, { requirePingoraGateway: true });
+
+  if (result.status === 0) {
+    failures.push('--require-pingora-gateway 但发布目录缺少 Pingora 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '本次部署要求 Pingora',
+    '--require-pingora-gateway 缺少 Pingora 文件时必须给出明确错误。',
+  );
+  assertMaintenanceCleared(fixture, '--require-pingora-gateway 缺少 Pingora 文件导致部署失败');
+}
+
+function assertReadinessFailureKeepsMaintenanceAfterCurrentSwitch() {
+  const fixture = prepareFixture('readiness-failure');
+  const result = runDeploy(fixture, { curlFails: true });
+
+  if (result.status === 0) {
+    failures.push('current 切换后的 readiness 失败必须让部署失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'readiness 检查超时',
+    'readiness 失败时必须给出明确错误。',
+  );
+  assertMaintenanceKept(fixture, 'current 切换后的 readiness 失败');
+
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  const currentTarget = readlinkSync(fixture.currentLink);
+  if (currentTarget !== releaseDir) {
+    failures.push(
+      `readiness 失败发生在 current 切换后，current link 应指向新 release。实际 ${currentTarget}，预期 ${releaseDir}`,
+    );
   }
 }
 
@@ -482,9 +552,7 @@ function assertMissingReleaseManifestFails() {
     '发布产物缺少 release-manifest.json',
     '缺少 release-manifest.json 时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('缺少 release-manifest.json 导致部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 release-manifest.json 导致部署失败');
 }
 
 function assertReleaseManifestMissingApiArtifactFails() {
@@ -504,9 +572,7 @@ function assertReleaseManifestMissingApiArtifactFails() {
     'release-manifest.json 缺少 api-server artifact',
     'manifest 缺少 api-server artifact 时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('manifest 缺少 api-server artifact 导致部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, 'manifest 缺少 api-server artifact 导致部署失败');
 }
 
 function assertDeployRejectsDotVersion() {
@@ -679,9 +745,7 @@ function assertDeployCleansStagingReleaseOnFailure() {
   if (stagingEntries.length > 0) {
     failures.push(`部署失败时不应留下 staging release: ${stagingEntries.join(', ')}`);
   }
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, 'staging 构建中失败');
 }
 
 function assertDeployRejectsFinalReleaseRaceAndCleansStaging() {
@@ -714,9 +778,7 @@ function assertDeployRejectsFinalReleaseRaceAndCleansStaging() {
   if (stagingEntries.length > 0) {
     failures.push(`目标 release 竞态失败后不应留下 staging release: ${stagingEntries.join(', ')}`);
   }
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('目标 release 竞态失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '目标 release 竞态失败');
 }
 
 function assertMissingPingoraDirectCheckFails() {
@@ -732,9 +794,7 @@ function assertMissingPingoraDirectCheckFails() {
     '发布产物缺少 Pingora 直连 live smoke 脚本',
     '缺少 direct live smoke 脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 direct live smoke 脚本导致部署失败');
 }
 
 function assertMissingPingoraCanaryLiveFails() {
@@ -750,9 +810,7 @@ function assertMissingPingoraCanaryLiveFails() {
     '发布产物缺少 Pingora canary live smoke 脚本',
     '缺少 canary live smoke 脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 canary live smoke 脚本导致部署失败');
 }
 
 function assertMissingPingoraCanaryAccessLogParityFails() {
@@ -773,9 +831,7 @@ function assertMissingPingoraCanaryAccessLogParityFails() {
     '发布产物缺少 Pingora canary access log 对账脚本',
     '缺少 canary access log 对账脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 canary access log 对账脚本导致部署失败');
 }
 
 function assertMissingBackupScriptFails() {
@@ -791,9 +847,7 @@ function assertMissingBackupScriptFails() {
     '发布产物缺少数据库备份脚本',
     '缺少数据库备份脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少数据库备份脚本导致部署失败');
 }
 
 function assertMissingHealthPatrolScriptFails() {
@@ -811,9 +865,7 @@ function assertMissingHealthPatrolScriptFails() {
     '发布产物缺少生产健康巡检脚本',
     '缺少生产健康巡检脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少生产健康巡检脚本导致部署失败');
 }
 
 function assertMissingPingoraCurrentReleaseAuditFails() {
@@ -834,9 +886,7 @@ function assertMissingPingoraCurrentReleaseAuditFails() {
     '发布产物缺少 Pingora current release 自审脚本',
     '缺少 Pingora current release 自审脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora current release 自审脚本导致部署失败');
 }
 
 function assertMissingPingoraDirectRehearsalStatusFails() {
@@ -857,9 +907,7 @@ function assertMissingPingoraDirectRehearsalStatusFails() {
     '发布产物缺少 Pingora 直连彩排状态脚本',
     '缺少 Pingora 直连彩排状态脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连彩排状态脚本导致部署失败');
 }
 
 function assertMissingPingoraCutoverStatusSnapshotFails() {
@@ -880,9 +928,7 @@ function assertMissingPingoraCutoverStatusSnapshotFails() {
     '发布产物缺少 Pingora 直连切换状态快照脚本',
     '缺少 Pingora 直连切换状态快照脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连切换状态快照脚本导致部署失败');
 }
 
 function assertMissingPingoraCutoverEvidenceBundleFails() {
@@ -903,9 +949,7 @@ function assertMissingPingoraCutoverEvidenceBundleFails() {
     '发布产物缺少 Pingora 直连切换证据包脚本',
     '缺少 Pingora 直连切换证据包脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连切换证据包脚本导致部署失败');
 }
 
 function assertMissingPingoraCutoverCommandEvidenceFails() {
@@ -926,9 +970,7 @@ function assertMissingPingoraCutoverCommandEvidenceFails() {
     '发布产物缺少 Pingora 直连切换命令证据脚本',
     '缺少 Pingora 直连切换命令证据脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连切换命令证据脚本导致部署失败');
 }
 
 function assertMissingPingoraCutoverEvidenceVerifyFails() {
@@ -949,9 +991,7 @@ function assertMissingPingoraCutoverEvidenceVerifyFails() {
     '发布产物缺少 Pingora 直连切换证据验真脚本',
     '缺少 Pingora 直连切换证据验真脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连切换证据验真脚本导致部署失败');
 }
 
 function assertMissingPingoraCutoverEvidenceAuditFails() {
@@ -974,9 +1014,7 @@ function assertMissingPingoraCutoverEvidenceAuditFails() {
     '发布产物缺少 Pingora 直连切换证据根目录审计脚本',
     '缺少 Pingora 直连切换证据根目录审计脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora 直连切换证据根目录审计脚本导致部署失败');
 }
 
 function assertMissingHealthPatrolEnvCheckFails() {
@@ -994,9 +1032,7 @@ function assertMissingHealthPatrolEnvCheckFails() {
     '发布产物缺少生产健康巡检 env 复核脚本',
     '缺少生产健康巡检 env 复核脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少生产健康巡检 env 复核脚本导致部署失败');
 }
 
 function assertMissingPingoraReleaseReadinessFails() {
@@ -1016,9 +1052,7 @@ function assertMissingPingoraReleaseReadinessFails() {
     '发布产物缺少 Pingora release readiness 聚合门禁脚本',
     '缺少 Pingora release readiness 聚合门禁脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora release readiness 聚合门禁脚本导致部署失败');
 }
 
 function assertMissingPingoraHealthPatrolEnvSwitchFails() {
@@ -1039,9 +1073,7 @@ function assertMissingPingoraHealthPatrolEnvSwitchFails() {
     '发布产物缺少 Pingora health patrol env 切换脚本',
     '缺少 Pingora health patrol env 切换脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora health patrol env 切换脚本导致部署失败');
 }
 
 function assertMissingPingoraGatewayEnvShadowSwitchFails() {
@@ -1064,9 +1096,7 @@ function assertMissingPingoraGatewayEnvShadowSwitchFails() {
     '发布产物缺少 Pingora gateway env shadow 切换脚本',
     '缺少 Pingora gateway env shadow 切换脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora gateway env shadow 切换脚本导致部署失败');
 }
 
 function assertMissingPingoraRealpathCanaryEnableFails() {
@@ -1087,9 +1117,7 @@ function assertMissingPingoraRealpathCanaryEnableFails() {
     '发布产物缺少 Pingora realpath canary 启用脚本',
     '缺少 Pingora realpath canary 启用脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora realpath canary 启用脚本导致部署失败');
 }
 
 function assertMissingPingoraRealpathCanaryDisableFails() {
@@ -1110,9 +1138,7 @@ function assertMissingPingoraRealpathCanaryDisableFails() {
     '发布产物缺少 Pingora realpath canary 关闭脚本',
     '缺少 Pingora realpath canary 关闭脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora realpath canary 关闭脚本导致部署失败');
 }
 
 function assertMissingPingoraTlsCertSyncFails() {
@@ -1133,9 +1159,7 @@ function assertMissingPingoraTlsCertSyncFails() {
     '发布产物缺少 Pingora TLS 证书同步脚本',
     '缺少 Pingora TLS 证书同步脚本时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少 Pingora TLS 证书同步脚本导致部署失败');
 }
 
 function assertMissingEnvExamplesFails() {
@@ -1154,9 +1178,7 @@ function assertMissingEnvExamplesFails() {
     '发布产物缺少环境变量示例目录',
     '缺少环境变量示例目录时必须给出明确错误。',
   );
-  if (!existsSync(fixture.maintenanceFile)) {
-    failures.push('部署失败时必须保持维护模式。');
-  }
+  assertMaintenanceCleared(fixture, '缺少环境变量示例目录导致部署失败');
 }
 
 function prepareFixture(name) {
@@ -1432,6 +1454,19 @@ function prepareFixture(name) {
     [
       '#!/usr/bin/env bash',
       `printf 'curl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'if [[ "${FAKE_CURL_FAIL:-false}" == "true" ]]; then',
+      '  exit 22',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'sleep'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'sleep %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
       'exit 0',
       '',
     ].join('\n'),
@@ -1478,6 +1513,7 @@ function prepareFixture(name) {
   );
   chmodExecutable(path.join(fakeBin, 'systemctl'));
   chmodExecutable(path.join(fakeBin, 'curl'));
+  chmodExecutable(path.join(fakeBin, 'sleep'));
   chmodExecutable(path.join(fakeBin, 'cp'));
   chmodExecutable(path.join(fakeBin, 'sudo'));
 
@@ -1543,29 +1579,33 @@ function runDeploy(fixture, options = {}) {
     fixture.sourceDir,
     'scripts/deploy/production-api-deploy.sh',
   );
+  const args = [
+    deployScript,
+    '--source-dir',
+    fixture.sourceDir,
+    '--version',
+    options.version ?? fixture.version,
+    '--release-root',
+    options.releaseRoot ?? fixture.releaseRoot,
+    '--current-link',
+    options.currentLink ?? fixture.currentLink,
+    '--service',
+    'genarrative-api.service',
+    '--health-url',
+    'http://127.0.0.1:18082/readyz',
+    '--api-env-file',
+    options.apiEnvFile ?? fixture.apiEnvFile,
+    '--database',
+    'genarrative-prod',
+    '--spacetime-server-url',
+    'http://127.0.0.1:3101',
+  ];
+  if (options.requirePingoraGateway) {
+    args.push('--require-pingora-gateway');
+  }
   return spawnSync(
     'bash',
-    [
-      deployScript,
-      '--source-dir',
-      fixture.sourceDir,
-      '--version',
-      options.version ?? fixture.version,
-      '--release-root',
-      options.releaseRoot ?? fixture.releaseRoot,
-      '--current-link',
-      options.currentLink ?? fixture.currentLink,
-      '--service',
-      'genarrative-api.service',
-      '--health-url',
-      'http://127.0.0.1:18082/readyz',
-      '--api-env-file',
-      options.apiEnvFile ?? fixture.apiEnvFile,
-      '--database',
-      'genarrative-prod',
-      '--spacetime-server-url',
-      'http://127.0.0.1:3101',
-    ],
+    args,
     {
       cwd: process.cwd(),
       encoding: 'utf8',
@@ -1578,6 +1618,7 @@ function runDeploy(fixture, options = {}) {
           options.pingoraDirectEntry === true ? 'true' : 'false',
         FAKE_PINGORA_ENV_FILE: fixture.pingoraEnvFile,
         FAKE_PINGORA_STATE_FILE: fixture.pingoraStateFile,
+        FAKE_CURL_FAIL: options.curlFails === true ? 'true' : 'false',
         FAKE_CREATE_RELEASE_DURING_COPY:
           options.createReleaseDuringCopy === true ? 'true' : 'false',
         FAKE_RELEASE_ROOT: fixture.releaseRoot,
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index d5c0cc487..bd74fa9aa 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -30,6 +30,31 @@ const checks = [
     reason:
       '生产冷备份 service 必须用 node -- 分隔脚本参数，避免 Node 22 抢占业务 --env-file。',
   },
+  {
+    file: 'scripts/database-backup-to-oss.mjs',
+    includes: 'assertSufficientWorkDirSpace({dataDir, workDir, args, env})',
+    reason: '生产冷备份必须先做工作目录剩余空间预检，避免停库后写满磁盘。',
+  },
+  {
+    file: 'scripts/database-backup-to-oss.mjs',
+    includes: 'restoreServicesAfterBackup({stopService, serviceStopped, restartServicesAfter})',
+    reason: '生产冷备份打包失败时也必须恢复 SpacetimeDB 及依赖服务。',
+  },
+  {
+    file: 'package.json',
+    includes: '"check:database-backup": "node scripts/check-database-backup-to-oss.mjs"',
+    reason: '数据库冷备份事故路径必须有本地 smoke 检查入口。',
+  },
+  {
+    file: 'scripts/check-database-backup-to-oss.mjs',
+    includes: 'assertArchiveFailureStillRestoresDependentServices',
+    reason: '数据库冷备份 smoke 必须覆盖 tar 失败后恢复依赖服务。',
+  },
+  {
+    file: 'scripts/check-database-backup-to-oss.mjs',
+    includes: 'assertInsufficientSpaceStopsBeforeServiceChanges',
+    reason: '数据库冷备份 smoke 必须覆盖空间不足时不触碰 systemctl。',
+  },
   {
     file: 'deploy/systemd/genarrative-health-patrol.service',
     includes: 'scripts/ops/production-health-patrol.mjs',
@@ -4756,11 +4781,29 @@ const checks = [
     reason:
       'API deploy 动态烟测必须覆盖 Pingora 二进制与 release manifest 漂移负例。',
   },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRequiresPingoraWhenRequested',
+    reason:
+      'API deploy 动态烟测必须覆盖 --require-pingora-gateway 缺失产物负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertReadinessFailureKeepsMaintenanceAfterCurrentSwitch',
+    reason:
+      'API deploy 动态烟测必须覆盖 current 切换后的 readiness 失败仍保留维护模式。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '--require-pingora-gateway',
+    reason:
+      'API deploy 必须支持 Jenkins release 对 Pingora 产物做硬要求。',
+  },
   {
     file: 'scripts/check-production-api-deploy.mjs',
     includes: 'assertMissingReleaseManifestFails',
     reason:
-      'API deploy 动态烟测必须覆盖缺少 release manifest 的失败维护模式。',
+      'API deploy 动态烟测必须覆盖缺少 release manifest 的失败维护回滚。',
   },
   {
     file: 'scripts/check-production-api-deploy.mjs',
@@ -4831,18 +4874,18 @@ const checks = [
   {
     file: 'scripts/check-production-api-deploy.mjs',
     includes: 'assertMissingBackupScriptFails',
-    reason: 'API deploy 动态烟测必须覆盖缺少数据库备份脚本的失败维护模式。',
+    reason: 'API deploy 动态烟测必须覆盖缺少数据库备份脚本的失败维护回滚。',
   },
   {
     file: 'scripts/check-production-api-deploy.mjs',
     includes: 'assertMissingHealthPatrolScriptFails',
-    reason: 'API deploy 动态烟测必须覆盖缺少健康巡检脚本的失败维护模式。',
+    reason: 'API deploy 动态烟测必须覆盖缺少健康巡检脚本的失败维护回滚。',
   },
   {
     file: 'scripts/check-production-api-deploy.mjs',
     includes: 'assertMissingHealthPatrolEnvCheckFails',
     reason:
-      'API deploy 动态烟测必须覆盖缺少健康巡检 env 复核脚本的失败维护模式。',
+      'API deploy 动态烟测必须覆盖缺少健康巡检 env 复核脚本的失败维护回滚。',
   },
   {
     file: 'scripts/check-production-api-deploy.mjs',
diff --git a/scripts/database-backup-to-oss.mjs b/scripts/database-backup-to-oss.mjs
index 79f408ad1..4d4e969a2 100644
--- a/scripts/database-backup-to-oss.mjs
+++ b/scripts/database-backup-to-oss.mjs
@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {spawnSync} from 'node:child_process';
 import {createHash, createHmac} from 'node:crypto';
-import {createReadStream, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {createReadStream, existsSync, mkdirSync, readFileSync, rmSync, statSync, statfsSync, writeFileSync} from 'node:fs';
 import {basename, dirname, isAbsolute, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
@@ -12,6 +12,8 @@ const DEFAULT_LOCAL_DATA_DIR = resolve(REPO_ROOT, 'server-rs/.spacetimedb/local/
 const DEFAULT_LOCAL_WORK_DIR = resolve(REPO_ROOT, 'server-rs/.data/database-backups');
 const DEFAULT_PRODUCTION_DATA_DIR = '/stdb';
 const DEFAULT_PRODUCTION_WORK_DIR = '/var/lib/genarrative/database-backups';
+const DEFAULT_SPACE_SAFETY_RATIO = 1.1;
+const DEFAULT_EXTRA_FREE_BYTES = 512 * 1024 * 1024;
 const OSS_ALGORITHM = 'OSS4-HMAC-SHA256';
 const OSS_SERVICE = 'oss';
 const OSS_REQUEST = 'aliyun_v4_request';
@@ -36,6 +38,7 @@ function usage() {
   GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX      对象前缀，默认 database-backups
   GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT    OSS endpoint；未设置时回退 ALIYUN_OSS_ENDPOINT
   GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL      true 时保留本地 tar.gz
+  GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES  备份前要求 work dir 所在文件系统至少有这些可用字节；未设置时按数据目录大小估算
   ALIYUN_OSS_ACCESS_KEY_ID / ALIYUN_OSS_ACCESS_KEY_SECRET
 `);
 }
@@ -108,6 +111,7 @@ function parseArgs(argv) {
     manifestFile: '',
     objectKey: '',
     resultFile: '',
+    minFreeBytes: '',
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -182,6 +186,9 @@ function parseArgs(argv) {
       case '--result-file':
         options.resultFile = readValue();
         break;
+      case '--min-free-bytes':
+        options.minFreeBytes = readValue();
+        break;
       default:
         throw new Error(`未知参数: ${arg}`);
     }
@@ -253,6 +260,119 @@ function runCommand(command, args, options = {}) {
   return result;
 }
 
+function parseByteSize(rawValue, label) {
+  const value = String(rawValue ?? '').trim();
+  if (!value) {
+    return null;
+  }
+  const match = /^(\d+)(?:\s*([KMGTPE]?)(?:I?B?)?)?$/iu.exec(value);
+  if (!match) {
+    throw new Error(`${label} 必须是字节数或 K/M/G/T/P/E 后缀大小，实际: ${rawValue}`);
+  }
+  const [, amountText, unitText = ''] = match;
+  const multipliers = {
+    '': 1n,
+    K: 1024n,
+    M: 1024n ** 2n,
+    G: 1024n ** 3n,
+    T: 1024n ** 4n,
+    P: 1024n ** 5n,
+    E: 1024n ** 6n,
+  };
+  return BigInt(amountText) * multipliers[unitText.toUpperCase()];
+}
+
+function formatBytes(bytes) {
+  const value = BigInt(bytes);
+  const gib = Number(value) / (1024 ** 3);
+  if (gib >= 1) {
+    return `${gib.toFixed(1)}GiB`;
+  }
+  const mib = Number(value) / (1024 ** 2);
+  if (mib >= 1) {
+    return `${mib.toFixed(1)}MiB`;
+  }
+  return `${value}B`;
+}
+
+function getDirectorySizeBytes(dataDir) {
+  const result = runCommand('du', ['-sk', dataDir]);
+  const [sizeKbText] = String(result.stdout ?? '').trim().split(/\s+/u);
+  if (!sizeKbText || !/^\d+$/u.test(sizeKbText)) {
+    throw new Error(`无法解析数据目录大小: ${result.stdout}`);
+  }
+  return BigInt(sizeKbText) * 1024n;
+}
+
+function getAvailableBytes(fileSystemPath) {
+  const stat = statfsSync(fileSystemPath, {bigint: true});
+  return stat.bavail * stat.bsize;
+}
+
+function parseSafetyRatio(rawValue) {
+  const value = String(rawValue ?? '').trim();
+  if (!value) {
+    return DEFAULT_SPACE_SAFETY_RATIO;
+  }
+  const ratio = Number(value);
+  if (!Number.isFinite(ratio) || ratio < 1) {
+    throw new Error(`GENARRATIVE_DATABASE_BACKUP_SPACE_SAFETY_RATIO 必须是 >= 1 的数字，实际: ${rawValue}`);
+  }
+  return ratio;
+}
+
+function calculateRequiredFreeBytes({dataSizeBytes, args, env}) {
+  const explicitMinFreeBytes = parseByteSize(
+    firstNonEmpty(args.minFreeBytes, env.GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES),
+    'GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES',
+  );
+  if (explicitMinFreeBytes !== null) {
+    return explicitMinFreeBytes;
+  }
+  const ratio = parseSafetyRatio(env.GENARRATIVE_DATABASE_BACKUP_SPACE_SAFETY_RATIO);
+  const ratioBasisPoints = BigInt(Math.ceil(ratio * 10000));
+  const ratioRequirement = (dataSizeBytes * ratioBasisPoints + 9999n) / 10000n;
+  const extraFreeBytes = parseByteSize(
+    firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_EXTRA_FREE_BYTES, String(DEFAULT_EXTRA_FREE_BYTES)),
+    'GENARRATIVE_DATABASE_BACKUP_EXTRA_FREE_BYTES',
+  );
+  const extraRequirement = dataSizeBytes + extraFreeBytes;
+  return ratioRequirement > extraRequirement ? ratioRequirement : extraRequirement;
+}
+
+function assertSufficientWorkDirSpace({dataDir, workDir, args, env}) {
+  mkdirSync(workDir, {recursive: true});
+  const dataSizeBytes = getDirectorySizeBytes(dataDir);
+  const availableBytes = getAvailableBytes(workDir);
+  const requiredFreeBytes = calculateRequiredFreeBytes({dataSizeBytes, args, env});
+  console.log(
+    `[database-backup] 备份空间预检: data=${formatBytes(dataSizeBytes)}, available=${formatBytes(availableBytes)}, required=${formatBytes(requiredFreeBytes)}`,
+  );
+  if (availableBytes < requiredFreeBytes) {
+    throw new Error(
+      [
+        `备份工作目录所在文件系统剩余空间不足: ${workDir}`,
+        `available=${formatBytes(availableBytes)}`,
+        `required=${formatBytes(requiredFreeBytes)}`,
+        `dataDir=${dataDir}`,
+        `dataSize=${formatBytes(dataSizeBytes)}`,
+        '为避免停库后写满磁盘，本次备份已在停止服务前中止。',
+      ].join('；'),
+    );
+  }
+}
+
+function collectRestartServicesAfterBackup({args, env}) {
+  const serviceNames = [
+    ...String(env.GENARRATIVE_DATABASE_BACKUP_RESTART_SERVICE_AFTER ?? '')
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean),
+    ...args.restartServicesAfter,
+  ];
+  return [...new Set(serviceNames.filter(Boolean))];
+}
+
 function stopServiceIfNeeded(serviceName) {
   if (!serviceName) {
     return false;
@@ -271,12 +391,37 @@ function startServiceIfNeeded(serviceName, wasStopped) {
 }
 
 function restartServicesAfterBackup(serviceNames) {
+  const errors = [];
   for (const serviceName of serviceNames) {
     if (!serviceName) {
       continue;
     }
     console.log(`[database-backup] 冷备份后重启依赖服务: ${serviceName}`);
-    runCommand('systemctl', ['restart', serviceName], {stdio: 'inherit'});
+    try {
+      runCommand('systemctl', ['restart', serviceName], {stdio: 'inherit'});
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, `冷备份后重启依赖服务失败: ${errors.map((error) => error.message).join('; ')}`);
+  }
+}
+
+function restoreServicesAfterBackup({stopService, serviceStopped, restartServicesAfter}) {
+  const errors = [];
+  try {
+    startServiceIfNeeded(stopService, serviceStopped);
+  } catch (error) {
+    errors.push(error);
+  }
+  try {
+    restartServicesAfterBackup(restartServicesAfter);
+  } catch (error) {
+    errors.push(error);
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, `恢复冷备份相关服务失败: ${errors.map((error) => error.message).join('; ')}`);
   }
 }
 
@@ -523,19 +668,36 @@ async function main() {
 
   let archivePath = '';
   let serviceStopped = false;
+  let backupError = null;
+  let restoreError = null;
+  const stopService = args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE);
+  const restartServicesAfter = collectRestartServicesAfterBackup({args, env});
   try {
-    serviceStopped = stopServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE));
+    assertSufficientWorkDirSpace({dataDir, workDir, args, env});
+    serviceStopped = stopServiceIfNeeded(stopService);
     archivePath = createArchive({dataDir, workDir, fileName});
+  } catch (error) {
+    backupError = error;
   } finally {
-    startServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE), serviceStopped);
+    try {
+      if (serviceStopped) {
+        restoreServicesAfterBackup({stopService, serviceStopped, restartServicesAfter});
+      } else if (!backupError) {
+        restartServicesAfterBackup(restartServicesAfter);
+      }
+    } catch (error) {
+      restoreError = error;
+    }
+  }
+  if (backupError) {
+    if (restoreError) {
+      throw new AggregateError([backupError, restoreError], `数据库备份失败，且恢复依赖服务时也失败: ${backupError.message}; ${restoreError.message}`);
+    }
+    throw backupError;
+  }
+  if (restoreError) {
+    throw restoreError;
   }
-  restartServicesAfterBackup([
-    ...String(env.GENARRATIVE_DATABASE_BACKUP_RESTART_SERVICE_AFTER ?? '')
-      .split(',')
-      .map((value) => value.trim())
-      .filter(Boolean),
-    ...args.restartServicesAfter,
-  ]);
 
   const manifestPath = `${archivePath}.manifest.json`;
   writeManifest({
diff --git a/scripts/deploy/production-api-deploy.sh b/scripts/deploy/production-api-deploy.sh
index 716ce298f..0f3877046 100644
--- a/scripts/deploy/production-api-deploy.sh
+++ b/scripts/deploy/production-api-deploy.sh
@@ -5,14 +5,14 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 用法:
-  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--pingora-service genarrative-pingora-gateway.service] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101]
+  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--pingora-service genarrative-pingora-gateway.service] [--require-pingora-gateway] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101]
 
 说明:
   进入维护模式，校验并发布 api-server 单文件，更新 current 链接，重启 systemd 服务并执行 readiness 检查。
   默认同时重启外部生成 worker controller 和已加载的 worker 实例；未启用 worker 单元时会自动跳过。
   若传入 --database，会在重启前把 GENARRATIVE_SPACETIME_DATABASE 写入 api-server 环境文件，避免服务继续读取旧库。
-  若发布包包含 pingora-gateway，部署脚本会在 current 链接切换后先复核 systemd/env 仍是本机高端口 shadow 配置，再启动或重启 Pingora 影子服务并复核 active。
-  失败时保留维护模式。
+  若发布包包含 pingora-gateway，或传入 --require-pingora-gateway，部署脚本会要求 release manifest、二进制与 checksum 一致，再在 current 链接切换后先复核 systemd/env 仍是本机高端口 shadow 配置，启动或重启 Pingora 影子服务并复核 active。
+  current 链接切换前失败时会退出本次打开的维护模式；current 链接切换后失败时保留维护模式，避免暴露半发布版本。
 EOF
 }
 
@@ -347,17 +347,20 @@ ensure_pingora_shadow_service() {
 validate_release_manifest() {
   local manifest_path="$1"
   local require_pingora="$2"
+  local source_dir="$3"
 
   if [[ ! -f "${manifest_path}" ]]; then
     echo "[production-api-deploy] 发布产物缺少 release-manifest.json: ${manifest_path}" >&2
     exit 1
   fi
 
-  node - "${manifest_path}" "${require_pingora}" <<'NODE'
+  node - "${manifest_path}" "${require_pingora}" "${source_dir}" <<'NODE'
 const fs = require('fs');
+const path = require('path');
 
 const manifestPath = process.argv[2];
 const requirePingora = process.argv[3] === '1';
+const sourceDir = process.argv[4];
 let manifest;
 try {
   manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
@@ -380,6 +383,16 @@ if (requirePingora) {
     process.exit(1);
   }
 }
+
+const hasPingora = artifacts.some((artifact) => artifact?.path === 'pingora-gateway');
+if (hasPingora) {
+  const binaryPath = path.join(sourceDir, 'pingora-gateway');
+  const checksumPath = path.join(sourceDir, 'pingora-gateway.sha256');
+  if (!fs.existsSync(binaryPath) || !fs.existsSync(checksumPath)) {
+    console.error('[production-api-deploy] release-manifest.json 登记了 pingora-gateway artifact，但发布目录缺少 pingora-gateway 或 pingora-gateway.sha256。');
+    process.exit(1);
+  }
+}
 NODE
 }
 
@@ -576,6 +589,9 @@ DATABASE=""
 SPACETIME_SERVER_URL=""
 DEPLOY_COMPLETED=0
 PINGORA_INCLUDED=0
+REQUIRE_PINGORA_GATEWAY=0
+MAINTENANCE_ENABLED_BY_DEPLOY=0
+CURRENT_LINK_SWITCHED=0
 RELEASE_DIR=""
 STAGING_RELEASE_DIR=""
 
@@ -609,6 +625,10 @@ while [[ $# -gt 0 ]]; do
       PINGORA_SERVICE_NAME="${2:?缺少 --pingora-service 的值}"
       shift 2
       ;;
+    --require-pingora-gateway)
+      REQUIRE_PINGORA_GATEWAY=1
+      shift
+      ;;
     --worker-service-pattern)
       WORKER_SERVICE_PATTERN="${2:?缺少 --worker-service-pattern 的值}"
       shift 2
@@ -709,7 +729,14 @@ on_exit() {
   local exit_code=$?
   if [[ "${exit_code}" -ne 0 && "${DEPLOY_COMPLETED}" -ne 1 ]]; then
     cleanup_staging_release
-    echo "[production-api-deploy] 部署失败，保持维护模式。" >&2
+    if [[ "${MAINTENANCE_ENABLED_BY_DEPLOY}" -eq 1 && "${CURRENT_LINK_SWITCHED}" -ne 1 ]]; then
+      echo "[production-api-deploy] 部署失败且尚未切换 current，退出本次打开的维护模式。" >&2
+      if ! bash "${SCRIPT_DIR}/maintenance-off.sh"; then
+        echo "[production-api-deploy] 退出维护模式失败，请人工检查维护文件。" >&2
+      fi
+    else
+      echo "[production-api-deploy] 部署失败，current 可能已切换或维护模式不是本次打开，保持维护模式。" >&2
+    fi
   fi
   exit "${exit_code}"
 }
@@ -717,6 +744,7 @@ on_exit() {
 trap on_exit EXIT
 
 bash "${SCRIPT_DIR}/maintenance-on.sh" "api deploy ${VERSION}"
+MAINTENANCE_ENABLED_BY_DEPLOY=1
 
 echo "[production-api-deploy] 校验 api-server"
 (
@@ -730,10 +758,14 @@ echo "[production-api-deploy] 校验 api-server"
     sha256sum -c pingora-gateway.sha256
   fi
 )
+if [[ "${REQUIRE_PINGORA_GATEWAY}" -eq 1 && ( ! -f "${SOURCE_DIR}/pingora-gateway" || ! -f "${SOURCE_DIR}/pingora-gateway.sha256" ) ]]; then
+  echo "[production-api-deploy] 本次部署要求 Pingora，但发布目录缺少 pingora-gateway 或 pingora-gateway.sha256。" >&2
+  exit 1
+fi
 if [[ -f "${SOURCE_DIR}/pingora-gateway" ]]; then
   PINGORA_INCLUDED=1
 fi
-validate_release_manifest "${SOURCE_DIR}/release-manifest.json" "${PINGORA_INCLUDED}"
+validate_release_manifest "${SOURCE_DIR}/release-manifest.json" "$(( PINGORA_INCLUDED || REQUIRE_PINGORA_GATEWAY ))" "${SOURCE_DIR}"
 
 mkdir -p "${RELEASE_ROOT}"
 mkdir "${STAGING_RELEASE_DIR}"
@@ -960,6 +992,7 @@ fi
 mv -T "${STAGING_RELEASE_DIR}" "${RELEASE_DIR}"
 STAGING_RELEASE_DIR=""
 ln -sfnT "${RELEASE_DIR}" "${CURRENT_LINK}"
+CURRENT_LINK_SWITCHED=1
 
 if [[ "${PINGORA_INCLUDED}" -eq 1 ]]; then
   ensure_pingora_shadow_service "${PINGORA_SERVICE_NAME}" "${PINGORA_SHADOW_ENV_FILE}"