diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index 6136c634d..1be7dfbb6 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -23,7 +23,7 @@ - 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端读入当前图层图片 Data URL 后走同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片源读取为图片 Data URL；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。 - 图片画布抠图分两类：手动去除背景面向用户任意图片，走登录态同源 BFF `POST /api/editor/images/background-removals` 并转发远端 BiRefNet；编辑器自己生成的标准纯色背景抠图资产在保存源图后统一调用独立 BgFilter 服务 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL/remove-background`，默认 `http://58.87.105.82/bgfilter/remove-background`，默认请求超时 `180000ms`（BgFilter CPU 推理）。角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取的前端用户路径都固定把 `screenColor=auto` 注入请求体，但用户可见 `generationInputs.fields` 不再记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt 和 BgFilter `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。三条 BgFilter 路径还必须固定把默认 `segModel=birefnet` 传为 `seg_model`；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交该值。这里的 `birefnet` 只是 BgFilter 管线内部后端，不等同于手动去背景的独立 BiRefNet 服务。后端在调用 BgFilter 前必须先把带纯色背景 / 绿幕源图写入 OSS；BgFilter 请求失败、返回非成功状态、空图片或非法图片时，以及连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 后的 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300` 秒熔断期，api-server 都先调用阿里云通用抠图，只有阿里云失败才用本地 `editor_green_screen` 按同一 `screenColor` 兜底去背。角色动作生成的序列帧背景色已与生图统一：前端固定提交 `screenColor=auto`，后端视觉决策出具体 hex 并把源角色图合成到该背景色后再图生视频；抽帧后逐帧优先阿里云通用抠图，失败降级本地 `editor_green_screen`（按选定背景色，而非固定 `#00FF00`）。BiRefNet 手动去背景服务地址为 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认 `http://58.87.105.82/remove-background`；BgFilter 可选访问令牌来自 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`，所有令牌都只在服务端注入，前端不持有令牌。api-server 对上游结果做响应字节和图片尺寸上限保护，并先落 OSS / asset object，再返回 `imageSrc/objectKey/assetObjectId/taskId`；queue 模式下手动去背景进入 SpacetimeDB 外部生成队列，画布任务侧栏只展示服务器任务阶段，生成中才显示耗时，不显示百分比；有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端，完成后由后端写入结果图层和最新项目快照。 - 多产物生成以后端项目快照为唯一画布真相：同一任务的原始产物、抠图 / 透明化结果和拆分结果都要先登记为 `editor_project_resource`，再通过一次 `canvasCompletion` 原子写入画布。角色形象、图标 spritesheet 和 UI 素材提取的纯色背景原图不能只留在 OSS；透明后处理结果保持主图层和 `generatedLayerId` 锚点，原图及其它附属产物从主结果右侧开始错开放置。无项目上下文时不创建项目资源或画布图层。 -- 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并显示错误。 +- 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。完整图标图集 `icon-spritesheet` 支持快速编辑，拆分后的单个 `icon` 不提供该入口，前后端必须使用同一素材类型规则。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并在错误红框中显示具体错误文案。 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。 - 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。 - 画布底部工具栏 / 面板 Dock 提供“画布 Agent”入口。点击后打开右侧独立 Agent 对话面板；桌面端为右侧窄面板，移动端占满可用宽度。该面板与素材侧栏、图层侧栏、右上角任务侧栏互斥，打开 Agent 时必须收起其它侧栏，打开其它侧栏或任务侧栏时也必须收起 Agent。Agent 面板不得在当前画布内容下方追加内联内容，也不默认展示大段功能说明文案。 diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs index f78b08ef3..b07b63629 100644 --- a/server-rs/crates/api-server/src/editor_project.rs +++ b/server-rs/crates/api-server/src/editor_project.rs @@ -2099,14 +2099,14 @@ fn ensure_editor_image_edit_asset_kind_allowed(asset_kind: Option<&str>) -> Resu let Some(asset_kind) = asset_kind.map(str::trim).filter(|value| !value.is_empty()) else { return Ok(()); }; - if !matches!(asset_kind, "icon" | "icon-spritesheet") { + if asset_kind != "icon" { return Ok(()); } Err( AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({ "provider": "editor-image-edit", - "message": "图标与图标图集不支持快速编辑", + "message": "单个图标不支持快速编辑", "assetKind": asset_kind, })), ) @@ -9186,21 +9186,20 @@ mod tests { } #[test] - fn editor_image_edit_rejects_icons_but_allows_icon_specs() { - for asset_kind in ["icon", "icon-spritesheet"] { - let error = ensure_editor_image_edit_asset_kind_allowed(Some(asset_kind)) - .expect_err("icon assets should not support quick edit"); - assert_eq!(error.status_code(), StatusCode::BAD_REQUEST); - assert_eq!( - error.details().and_then(|details| details.get("message")), - Some(&json!("图标与图标图集不支持快速编辑")), - ); - assert_eq!( - error.details().and_then(|details| details.get("assetKind")), - Some(&json!(asset_kind)), - ); - } + fn editor_image_edit_rejects_individual_icons_but_allows_spritesheets_and_specs() { + let error = ensure_editor_image_edit_asset_kind_allowed(Some("icon")) + .expect_err("individual icon assets should not support quick edit"); + assert_eq!(error.status_code(), StatusCode::BAD_REQUEST); + assert_eq!( + error.details().and_then(|details| details.get("message")), + Some(&json!("单个图标不支持快速编辑")), + ); + assert_eq!( + error.details().and_then(|details| details.get("assetKind")), + Some(&json!("icon")), + ); + assert!(ensure_editor_image_edit_asset_kind_allowed(Some("icon-spritesheet")).is_ok()); assert!(ensure_editor_image_edit_asset_kind_allowed(Some("icon-spec")).is_ok()); assert!(ensure_editor_image_edit_asset_kind_allowed(Some("image")).is_ok()); assert!(ensure_editor_image_edit_asset_kind_allowed(None).is_ok()); diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx index 776d1fbac..f5b06841a 100644 --- a/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx +++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx @@ -124,6 +124,27 @@ describe('ImageCanvasQuickEditPanelView', () => { expect(rememberImageModel).toHaveBeenCalledWith('gpt-image-2'); }); + it('renders the failure message inside the quick edit alert', () => { + render( + , + ); + + expect(screen.getByRole('alert').textContent).toContain( + '图集快速编辑失败', + ); + }); + it('submits without rendering a standalone close button', () => { const submitQuickEdit = vi.fn(); render( diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx index b95d23b8b..66953ef42 100644 --- a/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx +++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx @@ -53,6 +53,7 @@ function createQuickEditDialog( mode: isQuickEdit ? 'quick-edit' : 'generate', prompt: panel.prompt, status: panel.status, + errorMessage: panel.errorMessage, sourceLayerId: panel.sourceLayerId, generationReferences: panel.quickEditReferences, assetLabel: panel.assetLabel,