From 8f2b8891600c63f0e6ec7e58a7a9675a14c822b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Mon, 10 Aug 2026 12:00:10 +0800 Subject: [PATCH] =?UTF-8?q?=E7=A7=BB=E9=99=A4=E8=A7=86=E9=A2=91=E7=B4=A0?= =?UTF-8?q?=E6=9D=90=E7=9A=84=E5=BF=AB=E9=80=9F=E7=BC=96=E8=BE=91=E6=94=AF?= =?UTF-8?q?=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 清理相关逻辑 清理测试用例。 --- .../shared-memory/decision-log.md | 5 +- docs/project-memory/shared-memory/pitfalls.md | 2 +- ...架构】图片画布编辑器MVP接入方案-2026-06-11.md | 33 +- ...端架构】外部生成Worker化方案-2026-06-03.md | 2 +- ...】生成类面板Lovart统一改造方案-2026-06-17.md | 4 +- .../ImageCanvasContextMenusView.test.tsx | 5 + .../ImageCanvasGenerationModel.test.ts | 9 +- .../ImageCanvasGenerationModel.ts | 2 - .../ImageCanvasQuickEditPanelView.test.tsx | 34 +- .../ImageCanvasQuickEditPanelView.tsx | 36 +- ...ageCanvasSelectedLayerToolbarView.test.tsx | 2 +- ...anvasGenerationSubmissionWorkflow.test.tsx | 95 +--- ...ImageCanvasGenerationSubmissionWorkflow.ts | 513 +++++++++--------- .../useImageCanvasGenerationWorkflow.test.tsx | 22 + .../useImageCanvasGenerationWorkflow.ts | 2 - 15 files changed, 374 insertions(+), 392 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 7df22658b..3a59b3929 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -13755,14 +13755,15 @@ ## 2026-08-04 图片画布快速编辑改用统一正向白名单（2026-08-05 修订） - 背景：画布生成结果统一显示快速编辑，但部分角色动作 / 序列帧和音频结果会进入不受支持的图片编辑链路；不同入口各自判断时也容易继续漂移。 -- 决策：快速编辑只支持普通静态图片、角色图、规范图、完整图标图集、图标规范、UI 设计图、宣发图、游戏场景图和视频。单个拆分图标、角色动作 / 序列帧、音效与背景音乐不支持；新增媒体或素材类型默认不开放。浮动工具栏、图层右键菜单、独立图片菜单、打开面板入口和提交门禁统一调用同一个正向白名单；后端图片编辑 BFF 基于目标图层的有效素材类型与媒体类型执行同一正向门禁，视频快速编辑只走视频生成接口。 +- 决策：快速编辑只支持普通静态图片、角色图、规范图、完整图标图集、图标规范、UI 设计图、宣发图和游戏场景图。视频、单个拆分图标、角色动作 / 序列帧、音效与背景音乐不支持；新增媒体或素材类型默认不开放。浮动工具栏、图层右键菜单、独立图片菜单、打开面板入口和提交门禁统一调用同一个正向白名单；后端图片编辑 BFF 基于目标图层的有效素材类型与媒体类型执行同一正向门禁。 - 边界：角色动作继续通过对应的动作生成链路处理，不再把当前帧当作可快速编辑图片。 - 2026-08-06 修订：画布 Agent 的 `edit_image` 只接受图片输入，新任务以 `assetKind=null` 表示普通静态图片，不再使用 synthetic `editor_agent_edit_image`。worker 仅按服务端生成的 `editor-agent:` dedupe namespace 识别并归一历史排队 payload；普通调用伪造旧值继续被拒绝。已持久化资源中的旧值只有在后端从真实目标图层 / 项目资源解析后才兼容为空类型，避免历史 Agent 结果失去快速编辑能力，同时不扩大请求白名单。 - 2026-08-07 修订：站内与 External v1 图片编辑请求统一只接受必填 `sourceReferenceId`，且该值必须是当前账号已登记的项目资源 ID 或素材 ID；objectKey、URL、Data URL、Blob URL 以及旧 `sourceImageSrc/sourceResourceId/assetKind` 字段全部返回 400，不提供兼容别名。后端用共享窄查询分别按两张表主键定点解析，双表同 ID、未命中、跨账号、对象缺失或越权均失败关闭；权威类型完全来自业务记录，只允许普通静态图片、规范图、角色图、完整图标图集、图标规范、宣发图和 UI 设计图。请求带 `targetLayerId` 时必须同时带 `projectId`，来源与目标优先比较 `assetObjectId`，任一方缺失才比较 canonical `(bucket, objectKey)`，且来源默认类型必须与目标资源默认类型一致；最终类型取目标覆盖值或目标资源类型。HTTP 入队写入版本化服务端解析快照，worker 执行前按同一业务 ID 再次定点解析，身份或类型漂移即失败关闭。旧任务只把已有资源 ID 或旧来源字符串本身当业务 ID 迁移，绝不按 objectKey 反查。Canvas Agent 必须从 `ImageMetadata.reference_id` 取主来源；红框标注上传图只作为辅助 `referenceImageSrcs`，不能冒充被编辑资源。仅以素材 ID 编辑时，队列审计与 `generationInputs.references` 保留素材 ID，不伪造项目资源关系。 - 2026-08-08 修订：`scene` 是单张静态图片素材，加入前端快速编辑正向白名单和 api-server 权威来源白名单；编辑结果继续保留 `scene`。用户标签覆盖侧的前端菜单与 SpacetimeDB 结构化布局白名单也必须显式覆盖 `scene`。通用图片生成接口仍拒绝 `scene`，避免绕过结构化场景生成契约。 - 2026-08-08 修订：画布 Agent 的 `edit_image` 工具内部可先形成待确认的 `EditorImageEditRequest`，但确认接口必须在通用入队前复用站内图片编辑的来源解析与目标预检，写入 `{ version, request, source }` 服务端快照。worker 只解析正式 versioned payload 与既有历史 payload，不接受当前 direct request 作为 fallback；这样未上线的 Agent 路径在生产端原位修正，不扩大消费端协议。 - 2026-08-08 修订：图片编辑业务引用按 `objectKey` 找到权威 `asset_object` 后，若资源或素材记录同时保存了 `assetObjectId`，必须验证两者指向同一对象；不一致时在 SpacetimeDB resolver 边界失败关闭，不能把未验证的记录 ID 与已验证的对象路径组合进 snapshot。缺少 ID 的历史记录继续以 canonical `(bucket, objectKey)` 作为对象身份。 -- 验证：模型测试覆盖允许与拒绝类型，工具栏和两类右键菜单测试覆盖单个拆分图标、角色动作及音频不展示，提交工作流测试覆盖单个拆分图标和角色动作绕过入口时仍拒绝；后端表驱动测试覆盖全部现役素材 / 媒体类型与未知类型，锁定图片编辑端点失败关闭。 +- 2026-08-10 永久修订：画布视频快速编辑永久下线，上传、生成和历史视频图层均不再展示入口，程序化打开与直接提交同样失败关闭；不设置 feature flag、兼容桥或数据迁移。普通视频生成、视频“改造”、下载、`referenceVideoSrcs` 以及 V2 `videoReference` 恢复保持不变。External v1 从未正式声明“视频快速编辑”，只提供带可选 `referenceVideoSrcs` 的通用视频生成，因此不修改 `/api/external/v1` 路由、DTO、异步语义或 OpenAPI。当前服务已完全停止且无在途 / 可重试任务，不新增旧任务收口逻辑。 +- 验证：模型测试覆盖允许与拒绝类型，工具栏和两类右键菜单覆盖视频、单个拆分图标、角色动作及音频不展示，打开与提交工作流覆盖视频等不支持类型绕过入口时仍拒绝；后端表驱动测试覆盖全部现役图片素材 / 媒体类型与未知类型，锁定图片编辑端点失败关闭。 - 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`ImageCanvasSelectedLayerToolbarView.tsx`、`ImageCanvasContextMenusView.tsx`、`useImageCanvasGenerationWorkflow.ts`、`useImageCanvasGenerationSubmissionWorkflow.ts`。 ## 2026-08-05 game-chat Canvas 区间证明与 parent wake 持久收口 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 43dceb324..1362ae087 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -848,7 +848,7 @@ - 现象：用户点击图片素材的“快速编辑”后，画布上额外出现 `Quick Edit Generator` 占位，像是新建了一个生成器；但用户预期是在原图下方框选区域、填写一个提示词和模型，然后直接修改当前图。 - 原因：快速编辑入口和提交链路误用了 `createQuickEditGenerationDialogDraft(...)` / `CanvasGenerationDialogState`，把“覆盖源图”的快速编辑伪装成会产出新图层的生成器占位。 -- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，主来源始终使用当前图片已登记的 `resourceId` 或 `sourceAssetId`。带编号标注的图片上传后只作为辅助 `referenceImageSrcs`，不能替换主来源身份；成功后覆盖源图，失败时保留快速编辑面板。快速编辑任务进入 `generating` 后必须移除框选工具和覆盖层，禁止继续新增框选；失败恢复面板后可继续调整框选再重试。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。 +- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，主来源始终使用当前图片已登记的 `resourceId` 或 `sourceAssetId`。带编号标注的图片上传后只作为辅助 `referenceImageSrcs`，不能替换主来源身份；成功后覆盖源图，失败时保留快速编辑面板。快速编辑任务进入 `generating` 后必须移除框选工具和覆盖层，禁止继续新增框选；失败恢复面板后可继续调整框选再重试。图片重绘、去背景等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。 - 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。 - 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。 diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index db8847913..0214f69af 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -18,11 +18,13 @@ - 默认工具为选择模式；底部工具栏采用 AI 画布工作流工具组：选择、抓手、上传、生成图片、生成视频、生成音乐、生成规范、生成角色形象、生成图标素材、生成 UI 设计图。底部栏不再展示文字工具、形状标注工具和导出工具；上传与生成图片之间、生成音乐与生成规范之间各有一个半图标高度分割线。 - 鼠标中键拖拽始终平移画布；长按 Space 临时进入抓手模式，松开后恢复原工具。 - 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层、生成占位框或画板的边缘与中心线；当移动元素接近两个同轴元素形成的等距位置时，支持横向或纵向等距吸附。 -- 快速编辑使用统一正向白名单：只支持普通静态图片、角色图、规范图、完整图标图集、图标规范、UI 设计图、宣发图、游戏场景图和视频；单个拆分图标、角色动作 / 序列帧、音效与背景音乐不支持。浮动工具栏、图层右键菜单、独立图片菜单、打开面板入口和提交门禁必须复用同一白名单，新增媒体或素材类型默认不开放。图片编辑请求只提交必填 `sourceReferenceId`，取正式 `resourceId ?? sourceAssetId`；没有正式业务 ID 的本地图层、生成对话临时图层或未登记上传图必须先走既有资源登记，否则前端失败关闭。objectKey、URL、Data URL、Blob URL 不得作为主来源身份，旧 `sourceImageSrc/sourceResourceId/assetKind` 也不得发送。带红框的快速编辑仍以原图业务 ID 为主来源，上传后的编号标注图只放入辅助 `referenceImageSrcs`。`/api/editor/images/edits` 入队前通过当前账号窄查询解析来源对象与权威类型；带 `targetLayerId` 时必须同时带 `projectId`，目标图层须关联有效项目资源，双方对象和默认类型必须一致，最终有效类型取目标覆盖值或目标资源类型。来源默认类型只用于绑定一致性，不得在应用同媒体族标签覆盖前提前拒绝；因此默认 `icon` 且无覆盖时仍禁止快速编辑，但同一图片图层覆盖为 `scene` 或 `spec` 后必须按覆盖类型放行。视频快速编辑只能走视频生成接口，角色动作只能走对应动作生成链路。画布 Agent 的 `edit_image` 必须从 `ImageMetadata.reference_id` 获取项目资源 ID 或素材 ID，缺失时拒绝创建任务，不得用 `image_data_key` 或 objectKey 代替。 -- 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片，并提供“复制信息”复制当前可见字段。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。 +- 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词、重绘提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片，并提供“复制信息”复制当前可见字段。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。 +- 快速编辑使用统一正向白名单：只支持普通静态图片、角色图、规范图、完整图标图集、图标规范、UI 设计图、宣发图和游戏场景图；视频、单个拆分图标、角色动作 / 序列帧、音效与背景音乐不支持。浮动工具栏、图层右键菜单、独立图片菜单、打开面板入口和提交门禁必须复用同一白名单，新增媒体或素材类型默认不开放。图片编辑请求只提交必填 `sourceReferenceId`，取正式 `resourceId ?? sourceAssetId`；没有正式业务 ID 的本地图层、生成对话临时图层或未登记上传图必须先走既有资源登记，否则前端失败关闭。objectKey、URL、Data URL、Blob URL 不得作为主来源身份，旧 `sourceImageSrc/sourceResourceId/assetKind` 也不得发送。带红框的快速编辑仍以原图业务 ID 为主来源，上传后的编号标注图只放入辅助 `referenceImageSrcs`。`/api/editor/images/edits` 入队前通过当前账号窄查询解析来源对象与权威类型；带 `targetLayerId` 时必须同时带 `projectId`，目标图层须关联有效项目资源，双方对象和默认类型必须一致，最终有效类型取目标覆盖值或目标资源类型。来源默认类型只用于绑定一致性，不得在应用同媒体族标签覆盖前提前拒绝；因此默认 `icon` 且无覆盖时仍禁止快速编辑，但同一图片图层覆盖为 `scene` 或 `spec` 后必须按覆盖类型放行。视频仍支持普通生成、改造和下载，但不提供快速编辑；角色动作只能走对应动作生成链路。画布 Agent 的 `edit_image` 必须从 `ImageMetadata.reference_id` 获取项目资源 ID 或素材 ID，缺失时拒绝创建任务，不得用 `image_data_key` 或 objectKey 代替。 +- 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。重绘 / 改造输入框只允许从 `generationInputs.fields` 中恢复用户可见输入快照，例如普通生成提示词、视频描述、音效 `prompt`、背景音乐 `gpt_description_prompt`、角色设定、UI 用户输入、图标素材描述、规范表单和宣发素材字段；禁止回退展示资源 `prompt` / `actualPrompt` 中可能存在的后端拼接 Prompt、固定生成模板或模型默认提示词。当前 BGM 是字段语义上的例外：其新记录中的 `prompt` 与 `actualPrompt` 必须等于输入框已经写回的 canonical `gpt_description_prompt`，不得包含隐藏内容；但改造输入仍只从 `generationInputs.fields` 恢复，不能因此放宽为从资源审计字段回退。没有用户输入快照的旧图层打开改造时保持空输入，等待用户重新填写。 +- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端优先复用当前图层 objectKey；尚未登记的本地图片先上传 OSS，再把 objectKey 交给同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；普通图片、角色、图标图集、UI 设计图及其重绘 / 改造入口必须在比例或清晰度恢复、切换时同步把占位框 `width/height/originalWidth/originalHeight` 更新为目标像素尺寸，生成中不得继续显示默认 1K 框；UI 素材提取的 1K / 2K 图集占位和旧图片修改入口也分别使用本次目标尺寸与源图真实尺寸。待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片解析为已上传的 objectKey 或资源 ID；浏览器临时图片需先上传 OSS；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材不提供 `快速编辑`，只能通过角色动作生成链路继续编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。 - 生成类产物的工具栏动作 `改造` 不在原产物上原地修改，而是把当次生成输入恢复到对应面板，允许编辑后生成新产物。按钮显隐只按 action capability 判断：确定性派生等不支持改造的 action 隐藏；支持改造的 action 即使参数损坏或必需来源丢失也保留按钮，点击后再显示准确错误，禁止用恢复状态静默隐藏入口。`image.edit` 明确不属于可改造 action：图片快速编辑使用 `targetLayerId` 原位替换画布层，结果层就是被覆盖后的原层，其配方 source 指向替换前的编辑目标，不能再可靠恢复为“改造”新产物；这类结果继续显示“快速编辑”，不显示“改造”。 - V2 恢复严格按顶层 `action`、`fields[].id` 和 `references[].id/refType/refId` 定位，`title` / `label` 只是展示快照，不作为参数键。引用只在当前已 hydrate 的画布图层中按 `refType/refId` 匹配，媒体类型取匹配图层的运行时数据，不重复写入 `generationInputs.references`，也不新增 owner-only 工程资源 / 素材库查询。面板直接上传的参考素材不进入素材库、不是画布图层，因此改造时不恢复；原参考图层已移出画布时同样不恢复。**引用在提交时是否必填，不是恢复时拒绝打开面板的依据**：凡目标面板提供重新选择入口的槽位，无论可选还是必填，缺失时都必须 best effort 打开面板、留空槽位并提示用户重新选择，最终由提交门禁校验；例如角色生成缺少必填角色规范、图标生成缺少必填图标规范、普通图片 / 视频缺少参考图时，都必须打开原 action 面板让用户补选。只有已支持改造但目标面板没有手动替换入口、缺少 source 就无法构造请求时才允许拒绝，当前严格限定为两个例外：`character-animation.generate` 的 source 决定角色动作面板绑定的原角色图层，面板内部不能换角色；`ui-design.extract-assets` 的 source 同时决定框选覆盖层的坐标系，素材提取面板不能改绑另一张设计图。两个例外仍按 action capability 保留改造按钮；source 缺失时点击按钮才显示“无法改造”并分别说明不可替换原因，点击后 source 变化也必须在恢复路径再次校验并拒绝；该失败规则不得用于任何可手动补选的槽位。 -- 改造恢复顺序为：有效 V2；完整的历史生成对话框；按 `assetKind/mediaType`、历史中英文标题别名、资源模型 / 尺寸 / 时长 / `sourceResourceId` 的 legacy adapter，最后缺失值使用当前默认值并显示“已按旧版数据恢复，部分参数可能使用当前默认值。”。legacy adapter 必须先按 `assetKind/mediaType` 映射角色、图标、UI、场景、视频、音频等原工具；只有图片族且 `assetKind` 为空或未知时才使用默认的普通图片生成工具。legacy adapter 只恢复映射后目标 action / 工具声明的输入，不得额外把当前图片附加为参考图，也不得把普通图片生成改写为 `quick-edit` 或 `character` 请求。无法映射到可用工具时准确提示无法改造。一旦识别为有效 V2，即使引用缺失也不得降级到 legacy adapter。禁止从中文标题、产物尺寸或 prompt 反推 V2 参数；legacy fallback 除外，但不得回退展示 `actualPrompt` 中的后端拼接 Prompt。当前 BGM 是字段语义上的例外：其新记录中的 `prompt` 与 `actualPrompt` 必须等于输入框已经写回的 canonical `gpt_description_prompt`，不得包含隐藏内容；但改造输入仍只从 `generationInputs.fields` 恢复，不能因此放宽为从资源审计字段回退。定向测试必须至少覆盖未知图片回退普通 `image.generate` 和一种已知 `assetKind` 恢复原工具的真实提交闭环，并校验请求输入、V2 action / references、结果落点及 dialog / composer 终态。 +- 改造恢复顺序为：有效 V2；完整的历史生成对话框；按 `assetKind/mediaType`、历史中英文标题别名、资源模型 / 尺寸 / 时长 / `sourceResourceId` 的 legacy adapter，最后缺失值使用当前默认值并显示旧版恢复告警；一旦识别为有效 V2，即使引用缺失也不得降级到 legacy adapter。禁止从中文标题、产物尺寸或 prompt 反推 V2 参数；legacy fallback 除外，但不得回退展示 `actualPrompt` 中的后端拼接 Prompt。当前 BGM 是字段语义上的例外：其新记录中的 `prompt` 与 `actualPrompt` 必须等于输入框已经写回的 canonical `gpt_description_prompt`，不得包含隐藏内容；但改造输入仍只从 `generationInputs.fields` 恢复，不能因此放宽为从资源审计字段回退。 - V2 资源 / 素材 hydrate 为前向兼容读取：顶层、`fields[]` 和 `references[]` 出现未来可选属性时只复制当前已知字段，不得让整份配方消失；完美像素操作快照等精确重放路径仍执行递归白名单，并保留历史空字符串的字节级兼容。hydrate 结果必须保留 `absent | valid | invalid-versioned` 运行时来源状态：只有 `absent` 可走 legacy adapter；结构损坏或版本不支持的版本化配方标为 `invalid-versioned`，所有恢复入口都必须拒绝自动降级，并提示“保存的生成参数版本不受支持或数据损坏，无法可靠恢复”。该标记不属于持久化 generationInputs 契约，也不得把原始损坏 JSON 回写。对模型、比例、尺寸、时长、开关等具有明确运行默认值的 V2 参数，缺失与非法值统一补写默认值并告警；允许为空的提示词 / 表单自由文本不因缺失产生参数失效告警。 - 图片画布抠图统一通过唯一、只监听 loopback 的 `bgfilter-worker` 调用 BgFilter provider。手动去除背景面向用户任意图片，仍走登录态同源 BFF `POST /api/editor/images/background-removals` 和外部生成队列；API 在入队前拒绝 `data:` / `blob:` 内联媒体，父流程将稳定引用解析为当前账号已登记且归属已校验的私有 OSS object key，并在同一轮账号项目 / 素材快照读取中同时恢复用户可见源模型，禁止为 object key、所有权和源模型分别重复拉取全量快照；随后只通过一次内部 HTTP RPC 传递 object key、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和固定的 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传源图字节、签名 URL、`file` 或 `screen_color`。子 worker 在每次真实 provider attempt 前签发 600 秒 URL，承担默认 `Q=2048` admission 保险丝、provider 并发 `N=16`、严格最多两次顺序 attempt、响应字节与图片尺寸校验，并把成功图片作为内部 HTTP 二进制 body 直接返回；父流程同步等待该响应且不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`；attempt 按 `N × est × 2`、调用预算按 `2 × attempt + 1s` 派生，冻结 `est=5000ms` 时分别为 `160s / 321s`。complex 的真实 provider 失败会累计并打开自身熔断，但与 flat 状态隔离；complex 任意失败或熔断仍直接返回父流程失败，不接入阿里云 / 本地键色降级。provider 配置继续统一使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL` 和 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，父子共同使用 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY` 与 `GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS` 派生预算；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 provider token 兼容别名；内部调用另使用 `GENARRATIVE_BGFILTER_WORKER_BASE_URL` 和独立内部 Token。所有令牌只在服务端注入，前端不持有令牌。成功字节返回父流程后，仍由父流程完成最终处理、OSS / asset object 持久化、结果图层与最新项目快照写回；接口只向前端返回 `queueState`，有项目上下文时前端同时创建去背景生成占位并把 `canvasCompletion` 交给后端。 - 编辑器自己生成的标准纯色背景抠图资产在保存源图后统一以 `background_mode=flat` 调用内部 `bgfilter-worker`。角色形象生成、图标 spritesheet 生成、UI 设计图素材提取和角色动作的用户路径都固定使用 `screenColor=auto`，但用户可见 `generationInputs.fields` 不记录 `抠图背景色` 或 `抠图模型`；api-server 在组装 prompt 前调用背景决策模块，从 12 个候选色中选择具体 hex，最多重试 3 次，失败后兜底 `#CFEFFF`。后端仍保留手动 hex 解析能力供内部兼容。最终生图 prompt、动作视频实色背景和子 worker 发往 provider 的 `screen_color` multipart 字段只接收解析后的具体 hex，不透传 `auto`。角色、图标 spritesheet 和 UI 设计图素材提取的同源画布请求由前端自动提交默认 `segModel=birefnet`，api-server 负责 allowlist 校验并在缺失时回落默认值；角色动作逐帧去背的 `seg_model` 由后端固定。四条 flat 路径再由 api-server 向 worker 显式传递 `background_mode=flat` 与 `cross_check`：角色形象生成、图标 spritesheet 和角色动作逐帧去背传 `on`，UI 设计图素材提取传 `off`，不依赖 BgFilter 服务端默认值。前端不展示抠图模型选择，`segModel` 不进入 `generationInputs`、响应、搜索、详情或导出；`background_mode`、`cross_check` 只存在于 api-server 到 worker 的内部 RPC。子 worker 为 flat / complex 分别维护独立进程级熔断，并对一次逻辑调用严格最多执行两次顺序 provider attempt；两种模式共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 和 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 默认值，但失败和成功只更新当前模式；父侧至多让 worker 接收一次内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。flat 两次失败、熔断、overload、内部 deadline 或断连后，只要父业务预算仍有效，父流程才按同一 object key 进入“阿里云通用抠图 → 本地 `editor_green_screen` 键色”降级；阿里云 fallback 不属于 `bgfilter-worker`。角色动作生成的序列帧背景色已与生图统一：后端把源角色图合成到视觉决策出的具体 hex 后再图生视频；抽帧后逐帧进入同一条 `内部 bgfilter-worker（background_mode=flat，cross_check=on）→ 父侧阿里云 → 父侧本地键色` 链路。 @@ -52,10 +54,10 @@ - 普通图片与角色在 provider 回图后先按统一业务像素矩阵尝试交付尺寸归一：允许无放大恢复时使用 Lanczos 重采样并居中裁切，无法安全恢复时保留 provider 实际尺寸并返回非阻断告警。普通图片随后以这张实际交付尺寸图同时作为网格分析源和 RGBA 采样源；角色先持久化同尺寸平底原图并交给 BgFilter，正常成功后把 Alpha 蒙版回贴到该平底原图，再以平底原图分析网格、以透明 RGBA 图采样。图标仍以已持久化的平底 provider 图尺寸为基准，BgFilter 成功并回贴 Alpha 后执行同样的双输入规整。固定首版参数为：分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、相邻边缘峰间距使用线性插值 `P30` 估算步长、固定色板关闭、K-means 最大采样 `262144`。 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均按像素后处理失败的 best-effort 规则保留进入该步骤前的图片。 - 单格颜色按 `Σ(A × RGB) / ΣA` 进行 Alpha 加权；单格覆盖率按 `Σ(A / 255) / N` 计算。覆盖率大于等于 `0.375` 且 `ΣA > 0` 时输出硬 Alpha `255`，否则输出严格的 `[0,0,0,0]`；最终 Alpha 只允许 `0 / 255`。分析用 16 色只负责网格识别，不限制最终输出色数。 -- snapper 在内存中把每对相邻横纵切线围成的采样单元各压成一个输出像素，最终直接编码并持久化唯一的逻辑分辨率 PNG；不得再用 nearest 或其它插值把逻辑图恢复到当前 RGBA 输入尺寸或业务交付尺寸。普通图片和角色仍先执行既有 Lanczos 交付尺寸归一，无法安全归一时仍保留 provider 实际尺寸；图标输入仍以已持久化平底原图的实际尺寸为准。这些规则只定义网格检测与 RGBA 采样输入，不构成成功输出与输入同尺寸的承诺。角色和图标应复用 Alpha 回贴阶段已经读取的平底原图；确需重新读取时，最多增加一次对已有 provider 对象的 OSS GET，不得新增 OSS PUT。 -- 像素模式的持久化增量必须为零：普通图片仍只上传一张最终逻辑分辨率主图；角色仍只保留原有 provider 原图与一张最终透明逻辑分辨率主图；图标仍只保留原有 provider 原图、一张最终透明逻辑分辨率图集和实际成功的切片。禁止另存输入尺寸恢复版、像素化前后双份主图、预览图、网格诊断图或报告，禁止新增 asset / resource 类型、项目资源、画布 item、队列 job kind 或数据库字段。 +- 逻辑低分辨率图只存在于内存；snapper 在规整内部使用 nearest 恢复到当前 RGBA 输入尺寸，并直接替换原本即将持久化的最终图片字节。普通图片和角色的该输入已经过前置 Lanczos 交付尺寸归一，或在无法安全归一时保留 provider 实际尺寸；图标输入以已持久化平底原图的实际尺寸为准。nearest 不替代前置尺寸归一，规整完成后不再执行第二次 Lanczos 或其它尺寸恢复。角色和图标应复用 Alpha 回贴阶段已经读取的平底原图；确需重新读取时，最多增加一次对已有 provider 对象的 OSS GET，不得新增 OSS PUT。 +- 像素模式的持久化增量必须为零：普通图片仍只上传原有一张最终主图；角色仍只保留原有 provider 原图与透明主图；图标仍只保留原有 provider 原图、透明图集和实际成功的切片。禁止保存逻辑低分辨率图、像素化前后双份主图、预览图、网格诊断图或报告，禁止新增 asset / resource 类型、项目资源、画布 item、队列 job kind 或数据库字段。 - 像素后处理属于 best-effort：失败时保留进入该步骤前的图片，继续原有最终上传与画布完成，并通过既有通用 `warning` 返回非阻断原因，不把任务改为失败或退款。BgFilter 自身失败时仍按原 source-only fallback 收口，像素处理不运行；图标后处理成功后再执行原有自动拆分，拆分告警继续使用现有 `sliceWarning` 语义。 -- 选中已有静态栅格图层后的 `完美像素` 是独立的一键派生操作，不等同于生成请求上的 `style="pixelArt"`。它不打开参数面板，只处理当前活动图层，保留源图，并在源图右侧创建一张逻辑分辨率 PNG 派生结果；派生 PNG 的内在宽高取最终网格列数和行数，可以与源图及占位尺寸不同。音频、视频、图片序列和 `character-animation` 不显示该按钮。 +- 选中已有静态栅格图层后的 `完美像素` 是独立的一键派生操作，不等同于生成请求上的 `style="pixelArt"`。它不打开参数面板，只处理当前活动图层，保留源图，并在源图右侧创建同尺寸 PNG 派生结果；音频、视频、图片序列和 `character-animation` 不显示该按钮。 - 完美像素、手动去背景、裁扩和所有图集切片是确定性派生操作，分别保存 `image.perfect-pixel`、`image.remove-background`、`image.crop-expand`、`spritesheet.split` 的 V2 `generationInputs`。四者固定 `fields: []`；存在正式来源资源 / 素材行时只保存服务端权威的 `references[id="source"]`，引用仅用于来源溯源，不是算法参数或可编辑槽位，没有正式行时保存空数组。改造 capability 使用独立 allowlist，四者及历史 `pixel-art-snap-*` 结果永不允许改造；自动切片的 source 是实际被切的透明图集，整张生成图集仍保留原生成 action。 - 裁扩创建资源时，未携带 `sourceResourceId` 仍允许保存无正式来源引用的确定性结果；一旦携带该 ID，api-server 必须确认它属于当前 owner 和当前项目，否则以 `400` 拒绝，禁止同时持久化悬空 / 越权 `sourceResourceId` 和空来源配方。 - 已有图片像素规整固定调用登录态同源 `POST /api/editor/images/pixel-art-snaps`，复用同一纯内存 Rust snapper、CPU 并发许可和输入尺寸上限。该入口免费、只走当前 HTTP 请求内的 inline 处理，不创建 `external_generation_job`，不刷新或自动打开任务侧栏，也不进入泥点扣费 / 退款链路。它另有一层端点级并发闸（最大 4、等待队列上限 2048），设在首次 IO 之前；队列满返回 `503` 并带 `Retry-After`，等待超预算返回 `504`。30 秒总预算从 handler 入口起算，覆盖归属校验的 SpacetimeDB 读取、OSS 下载、两层排队与规整，不是只算 CPU 部分。 @@ -65,9 +67,8 @@ - B 层的边界是可验证的、且已确认只服务完美像素：`requiresLiveSession: true` 全仓仅有一处置位（完美像素提交路径），`claimActiveInlineGenerationDialog` / `releaseActiveInlineGenerationDialog` / `hasActiveInlineGenerationDialog` 的全部五个调用点也都在完美像素的提交、重试与恢复上。直接体量：`perfectPixelOperationStore.ts` 203 行（测试 228 行）、`useInlineGenerationPlaceholderExpiry.ts` 140 行（测试 401 行）、`hydratePerfectPixelOperation` 128 行，加上工作流里的恢复 effect 与窗口锚定，生产代码约 1100 行、测试约 2500 行（后两个数字是估算，前面几个是实测）。同为免费、同步、无 durable job 的手动图集拆分只用约 85 行客户端代码（失败即报错，`taskId` 用随机 UUID，无幂等、无对账），是本仓库对同类问题的既有廉价答案；完美像素额外的 B 层是**特例而非范式**，不得据它给其它链路加同样的机制。 - 前端提交前先创建关闭 composer 的右侧生成占位，再解析或上传源图以取得稳定引用，随后把版本化 `perfectPixelOperation` 请求快照写入**本机账本**（占位本身只带 `perfectPixelOperationId` 标记）并 flush 当前项目布局，最后才发送 POST。`canvasCompletion.dialogId` 同时作为 operation identity、稳定 task identity 的输入和本地源图上传 ID；同一 operation 的上传路径与后续 POST 请求都不得随机漂移。`sourceImageSrc` 优先由当前图层已有的 `objectKey / resourceId / sourceAssetId` 解析；尚未登记的浏览器本地图片只执行 `ticket → OSS PUT → confirm → objectKey`，不为这条持久化输入换取 signed URL。一个 `AbortSignal` 必须贯穿源文件 fetch / 图片解析边界、ticket、PUT、confirm，完整上传 helper 的可选换签也必须透传同一 signal。正式请求不得包含 `data:` / `blob:`、signed URL 或普通外链。后端在读取源图前必须把该字段解析为当前 owner 已登记的私有 OSS object key，并核对 project / resource / asset 归属。 - 源准备与 operation journal 使用两段绝对预算：`ticket → PUT → confirm` 连同源解析共用 90 秒；confirm 成功后形成稳定 `perfectPixelOperation` 并**同步写入本机账本**（`perfectPixelOperationStore`，owner + project 双键的 localStorage），布局里只留 `perfectPixelOperationId` 标记。原先的 strict layout save 通道（60 秒绝对预算、revision ACK 前 POST 为零）已整体删除：账本不再寄生在用户布局上，本机写入不过网络也不受服务端校验影响，同样能保证请求可被追溯。被解除的是**客户端侧**「拿不到 revision ack 就拒发」这一层阻断；端到端依赖仍在——布局 PATCH 被校验拒绝、占位因此从未落库时，POST 仍会被服务端以 409 拒收。POST 前仍然 `await` 一次 best-effort 布局保存——服务端要求占位**此前已经持久化**，否则 `validate_editor_pixel_art_snap_placeholder_exists` 直接 409；但 best-effort 不再提供成功 ACK，因此客户端**无法证明**该前置已满足，只能提高满足它的概率（占位可能已由此前的自动保存落库，PATCH 也可能成功而 ACK 丢失）。该 flush 没有整体上限，所以 75 秒对账窗口必须在 flush 返回、authority 复核通过之后才锚定，且首次提交与人工重试同此口径；锚定只覆盖 `submittedAt / reconcileUntil`，按同一 `operationId` 覆盖账本，request 与 dialog / operation / task identity 逐字节不变。此阶段失败持久化为 `failed + perfectPixelOperation`，保留同一 `sourceImageSrc / dialogId / taskId / request`；重试请求必须与账本中的 POST JSON byte-for-byte 一致且不得重新上传。**明确接受的行为，不是缺口**：占位恢复可删除之后，用户删掉未收口占位再从源图发起会得到第二个 identity，旧的服务端操作若迟到落库就会多出一份素材，两个 `taskId` 无法幂等合并。按上文的优先级判据，这属于「已生成资源丢失关联」而非主链路故障，代价是用户自行删掉多余素材，**不得**通过让本机账本参与防重来「闭合」——那是被明令禁止的「禁止一张图处理两遍」。confirm 成功后浏览器在 operation 首次 PATCH 落库前立即崩溃仍可能留下 object-only 记录；完全消除该窗口需要服务端 durable upload journal，不属于当前前端修复。 -- 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对唯一的逻辑分辨率 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；resource、asset、响应与图层使用该 PNG 的实际宽高，不要求与源图或占位尺寸相等，也不得另存输入尺寸恢复版、诊断图或前后对比图。 +- 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对最终 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；不得保存逻辑低分辨率图、诊断图或前后对比图。 - strict 的本次结果事实零写入边界截至首个最终 PNG PUT：所有可预判的引用、归属、类型、静态编码、元数据、网格适用性和 CPU 处理错误必须在此前失败；前置 owner-scoped 项目 / 素材读取仍可能按既有语义懒建默认 canvas / folder，这些基础记录不属于本次完美像素结果。后端先纯计算精确 object key 和候选 project resource，再调用只读 SpacetimeDB preflight 校验自定义素材目录归属、复用权威 completion planner，并执行 legacy / structured 的 2 MiB 总量与 512 KiB 单项门禁；默认目录尚未创建时允许通过，preflight 不写库。preflight 与 PUT / HEAD / 原子 persist 共用 60 秒绝对 deadline；preflight 失败或超时不得 PUT，也不得带 `resultPersistenceStarted`。最终 PNG 的 OSS PUT / HEAD 位于数据库事务外；验证上传结果后，asset object、project resource、账号素材与可选 canvas completion 由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中原子提交，并重新校验目录、布局、幂等身份与 revision。preflight 不加锁或 reservation，所以通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下 OSS 孤儿对象；这是本次最小修复明确保留的 TOCTOU 边界。operation 以 `owner + project + canvasCompletion.dialogId` 为作用域，task / object / resource / asset ID 稳定派生，object key 携带规范请求与输入 / 输出摘要形成的 fingerprint；同内容重放只返回原结果，输入漂移或部分既有事实失败关闭。HTTP timeout/drop 不能撤销已发往远端的 procedure，客户端仍须按稳定 `taskId / objectKey / resourceId` 对账，不能把未收到回包等同于未提交。 -- 手动入口的算法指纹随逻辑分辨率输出升级为 `perfect-pixel-v2`。若 owner-scoped 项目快照中同一稳定 resource 已存在，candidate object key 相同才继续 exact replay；key 不同或既有 resource 缺 key 时，后端必须在 preflight / OSS PUT 前返回 `operationResultAlreadyExists=true`，前端 initial 与 retry 两条 catch 都按稳定 task GET 项目对账。该标记表示旧权威结果已存在，不得与“本次 PUT 已开始”的 `resultPersistenceStarted` 混用；发布时仍须排空旧算法实例以规避 preflight 到提交之间的跨版本 TOCTOU。 - `POST /api/editor/images/pixel-art-snaps` 是有副作用的 unsafe POST。客户端不得为它配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前以 `401` 拒绝、刷新 token 后的既有认证恢复不属于业务副作用重放，保持通用行为。POST 回包中的 `project / resource / asset` 不是结果 verdict；首次成功回包、未知异常、人工 exact replay 和刷新恢复都只读取项目 GET。`perfectPixelOperation.submittedAt / reconcileUntil` 在 pre-POST flush 返回、authority 复核通过之后、POST 发出之前建立统一 75 秒绝对窗口（该 flush 没有整体上限，锚在它之前会让窗口在请求发出前就烧光），POST 回包不能续期；读取必须立即执行一次，随后退避间隔不超过 5 秒，窗口已过期时仍执行一次即时 GET。每次项目读取使用 `requestJson.deadlineAt` 覆盖缺 token 补票、业务 fetch、401 refresh、重试退避与响应体读取；窗口内单次最多 10 秒且不得越过 `reconcileUntil`，过期后的唯一即时读取最多额外 10 秒。固定判据为：匹配 task 的唯一 resource 加已收口 dialog / 关联图层才是画布成功；dialog 不存在但存在匹配 task resource 才是 asset-only 成功；dialog 仍 generating、dialog 不存在且无匹配 resource、项目始终不可读或窗口耗尽均保持 unknown。素材库刷新只在项目终态后 fire-and-forget，同步抛错、异步拒绝或永久挂起都不得阻塞 verdict、项目快照应用和执行锁释放。 - unknown 状态持久化为原 generation dialog 上的 `pending-confirmation + perfectPixelOperation`（账本在本机，布局只留 `perfectPixelOperationId`）。**用户可以随时删除该占位**，任何状态都不例外、也不弹确认：删除不撤销任何在途请求，结果照常落库并进素材库，服务端发现 dialog 已不在会返回 `DialogMissing`；封锁用户删除自己画布上的元素不是可接受的代价。删除后**结果不再自动回填画布**（服务端发现 dialog 已不在会返回 `DialogMissing`），这是用户主动放弃的结果，不得判定为缺陷；但对账本身不会因此停止——当前标签页已经在飞的 Promise 会继续读到终态，本机账本也会以孤儿身份在下次加载被读一次，结果确已落库时仍会提示用户去素材库取。未删除时用户可继续 GET 对账或显式按原 identity 重放。人工重试在 pre-POST flush **之后**才刷新观察窗口（同上一节的锚定口径），POST JSON 必须与持久请求 byte-for-byte 一致，不得按当前画布、目录、类型或标题重建，也不得创建第二个 dialog / task / object / resource / asset。hydrate 后只做 GET，不自动 POST、上传或重建请求。处理成功但事务内权威 dialog 已删除时，后端保留 object / resource / asset 并返回 asset-only 事实，canvas / revision 不变；前端只有在项目 GET 看见匹配 task resource 后才能提示“已保存到素材库”。现有布局 CAS 没有 deletion tombstone，completion 与其它已持久化布局编辑冲突时继续按权威 revision 守卫收口；尚未防抖落库的本地编辑合并不在本批范围。 - 删除 generation dialog 的按钮、快捷键和右键菜单必须在写画布历史、清选择或执行低层移除前经过同一请求保护入口。未收口完美像素 operation 与其它占位同样可被立即删除，写正常的 `delete-generation-result` 历史并清理 identity；删除确认只对**计费**生成成立（现成弹窗讲的是「已消耗的泥点不会返还」，而完美像素 `generation_cost_mud_points = 0`），判据收敛为具名的 `requiresGenerationDeleteConfirmation`。低层 `removeCanvasGenerationDialogById` 必须无条件删除——低层对上层抗命正是「占位未删却写出伪历史」的根因。 @@ -107,9 +108,9 @@ - 封面图层读取与栅格化集中在 `ImageCanvasProjectCoverSnapshotRenderer`：先排除不与封面输出区相交的图层，再以最多 6 路并发加载实际可绘制图层，最终仍按 z-index 顺序绘制。封面换签必须复用画布预览的 `taskId ?? resourceId` cache version，序列帧和视频 poster 继续使用同源后缀，以命中已有 pending / 内存 / session signed-URL 缓存并尽量复用同一 OSS URL 的浏览器缓存。封面上传只需 `objectKey / assetObjectId / legacyPublicPath`，使用 object-only 上传路径，不得为从未使用的立即预览 `src` 强制 `bypassCache` 换签。 - 图片、音频、视频和角色动画帧文件本体继续走 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` 和 `assetObjectId`；未登录演示态可以在内存里使用 Data URL 预览，但项目、素材库、项目资源和 `editor_canvas.layers_json` 不得写入 `data:image/*`、`data:video/*`、`data:audio/*` 或 `blob:`。旧数据读取时如果已有 `objectKey`，`imageSrc` 归一成 `/`；没有 `objectKey` 的旧 Data URL 需要走修复上传并回写轻量引用。裁扩在项目上下文中虽然由前端 canvas 本地渲染 PNG，也必须先上传 OSS / asset object 并创建 `editor_project_resource`，再把带正式 `resourceId/objectKey/assetObjectId` 的裁扩图层加入画布；不能先把 `local-resource-*` + Data URL 图层交给项目保存或后续去背景。上传到生成面板参考图槽位的图片必须先创建 `editor_project_resource` 行；没有当前工程 ID 时才创建账号级 `editor_asset` 行，随后把对应 `resourceId` 或 `assetId` 写入参考图临时状态；生成请求提交前必须把临时状态解析成 `objectKey`、项目资源 ID 或素材 ID，未登记的本地图片和普通图片路径先上传 OSS，不能直接提交 Data URL、Blob URL 或临时图片源。 -- 资源表保存资源和素材级元数据，其中 `editor_project_resource.asset_kind` 是资源默认类型；图层位置、层级、分组选中所需 ID、groupId 和可空 `assetKindOverride` 保存在画布布局。legacy 布局 JSON 是混合数组：普通图层按 `layerId/resourceId/assetKindOverride` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存；结构化模式下 `asset_kind_override` 必须是 `editor_canvas_layer` 的 typed 列，不得塞回 `item_json`。普通图层的新保存不再把资源默认 `assetKind` 或 `generationInputs` 写入布局；刷新时从 `editor_project_resource` 恢复资源默认类型，再与图层覆盖合并为 `effectiveAssetKind`，不得把合并结果反写为新的资源或覆盖。旧布局中的 `assetKind` 只用于迁移：与资源默认类型相同则归一为无 override，不同则迁移为图层 override；资源尚无默认值且允许补齐时先补资源默认值，不制造新的资源行。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；角色、图标等纯色抠图生成器的前端用户路径不保存或恢复 `screenColor` / `segModel`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成成功后仍保存对话框快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。V2 `generationInputs` 沿用现有 JSON 列，不新增表或字段：顶层为 `{ version: 2, action, fields, references }`，`fields` 只保存 `{ id, title, value }`，其中 `value` 为 `string | number | boolean`；`references` 只保存 `{ id, title, label?, refType, refId }`，`refType="project-resource"` 和 `refType="asset"` 仅作为当前画布图层的稳定匹配键，媒体类型从匹配图层获得，不据此额外查询资源行或素材库。提交前对面板值只归一一次，同一份归一值同时进入生成请求与 `fields/references`；Data URL、Blob URL、signed URL 和 `objectKey` 均不进入元数据。面板直接上传的引用即使为生成请求创建了工程资源，也不作为可长期恢复的素材库或画布引用。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。 +- 资源表保存资源和素材级元数据，其中 `editor_project_resource.asset_kind` 是资源默认类型；图层位置、层级、分组选中所需 ID、groupId 和可空 `assetKindOverride` 保存在画布布局。legacy 布局 JSON 是混合数组：普通图层按 `layerId/resourceId/assetKindOverride` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存；结构化模式下 `asset_kind_override` 必须是 `editor_canvas_layer` 的 typed 列，不得塞回 `item_json`。普通图层的新保存不再把资源默认 `assetKind` 或 `generationInputs` 写入布局；刷新时从 `editor_project_resource` 恢复资源默认类型，再与图层覆盖合并为 `effectiveAssetKind`，不得把合并结果反写为新的资源或覆盖。旧布局中的 `assetKind` 只用于迁移：与资源默认类型相同则归一为无 override，不同则迁移为图层 override；资源尚无默认值且允许补齐时先补资源默认值，不制造新的资源行。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；角色、图标等纯色抠图生成器的前端用户路径不保存或恢复 `screenColor` / `segModel`，同源重绘也不再从 `generationInputs.fields` 恢复 `抠图背景色` 或 `抠图模型`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成成功后仍保存对话框快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。V2 `generationInputs` 沿用现有 JSON 列，不新增表或字段：顶层为 `{ version: 2, action, fields, references }`，`fields` 只保存 `{ id, title, value }`，其中 `value` 为 `string | number | boolean`；`references` 只保存 `{ id, title, label?, refType, refId }`，`refType="project-resource"` 和 `refType="asset"` 仅作为当前画布图层的稳定匹配键，媒体类型从匹配图层获得，不据此额外查询资源行或素材库。提交前对面板值只归一一次，同一份归一值同时进入生成请求与 `fields/references`；Data URL、Blob URL、signed URL 和 `objectKey` 均不进入元数据。面板直接上传的引用即使为生成请求创建了工程资源，也不作为可长期恢复的素材库或画布引用。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。 - 图片类、生成视频和音频结果除作为 `editor_project_resource` 和画布图层保存外，还要写入账号级 `editor_asset` 素材库；该写入由生成 BFF 在请求携带 `assetFolderId` 时完成。角色、图标图集、UI 提取和角色动作等多产物任务把实际产生的 provider 原始输出及后处理结果分别入库：所有条目沿用 `character`、`icon-spritesheet`、`character-animation` 等真实类型，provider 原始输出承载任务模型成本，后处理派生产物阶段成本为 0。后台素材查询以最终产物为父行、每个中间产物为可展开的独立子行，分页只计算父任务；手动重拆图集保留独立 `taskId` 用于存储隔离和日志排障，通过私有 provenance 从服务端生成账号素材的 source resource、asset object 或 Object Key 取得可信来源任务，并把它写入 `groupTaskId`，不信任客户端可提交的 resource `taskId/assetKind`；跨项目复用后仍可通过稳定媒体引用找回来源。没有可信来源的新拆分显式归到自身任务，不走历史资源链回溯。每个手动切片同时写入 `groupTaskExpectedAssetCount`，全部切片落库后写独立 cohort 完成事实；后台 read model 只让同一根任务的一个已完成拆分批次并入原图集父项，用户后来删除单片不会让批次脱组，部分失败批次和后续重复拆分批次按各自真实任务分页，避免残缺批次抢占根任务、单组无限增长或素材丢失。历史行在项目资源仍存在时兼容回溯，删除项目资源前只固化直接受影响行的真实来源字段，有界展示 ID 不反写数据库。`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画布图片、改图、图标素材、UI 素材提取、角色动作、视频、音效和背景音乐生成都先返回 `queueState`，前端轮询 `/api/runtime/external-generation/jobs/{jobId}` 到完成后重新读取项目快照；`inline` 或无项目上下文时才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。生成请求失败、inline 完成或 queue 任务终态完成 / 失败后，右上角泥点 chip 必须通过 `/profile/dashboard` 回读余额，不做本地乐观扣减。生成视频会单独抽取首帧封面写入 `thumbnailSrc`，素材栏和拖回画布时沿用该封面作为 poster。 -- 生成面板不展示资源名称输入，默认使用原有自动编号；提示词输入保持统一可见边框。图片生成、快速编辑、修改图片、视频、音频、角色、图标、UI / 自定义规范、角色动画和宣发素材描述统一直接使用公共 `AutoGrowTextArea`，不经 `PlatformTextField` 的 textarea 分支；`AutoGrowTextArea` 负责尺寸、溢出及统一的 disabled 光标 / 透明度反馈，画布内生成面板统一由 `image-canvas-editor__generation-prompt` 承载边框、背景、padding、圆角和 focus chrome，独立修改图片弹窗继续使用 `image-canvas-editor__generate-prompt`，用途专属类只追加最小高度等差异，不得新建第三套 textarea chrome。两套 chrome 均通过 `--auto-grow-scrollbar-radius` 与内部滚动条共用圆角；WebKit 轨道按该圆角上下内缩，滑块在透明横向 gutter 内保持浏览器原生长度比例，拉至顶部或底部不得越过输入框边界。Enter 继续输入换行而不提交表单。内部命名契约仍使用可选 `assetLabel`，最大 80 字符并在提交时 trim；历史状态或内部调用携带非空名称时，同一个名称必须贯穿 `assetLabel`、`canvasCompletion.title`、项目资源、账号素材和本地兜底图层，刷新后不得退回模板名。图标图集与角色动作请求同样兼容该字段，中间原图使用主名称加固定后缀；图标拆分素材按全连通域视觉顺序自动命名为 `素材 N`。 +- 生成面板不展示资源名称输入，默认使用原有自动编号；提示词输入保持统一可见边框。图片生成、快速编辑、重绘、修改图片、视频、音频、角色、图标、UI / 自定义规范、角色动画和宣发素材描述统一直接使用公共 `AutoGrowTextArea`，不经 `PlatformTextField` 的 textarea 分支；`AutoGrowTextArea` 负责尺寸、溢出及统一的 disabled 光标 / 透明度反馈，画布内生成面板统一由 `image-canvas-editor__generation-prompt` 承载边框、背景、padding、圆角和 focus chrome，独立修改图片弹窗继续使用 `image-canvas-editor__generate-prompt`，用途专属类只追加最小高度等差异，不得新建第三套 textarea chrome。两套 chrome 均通过 `--auto-grow-scrollbar-radius` 与内部滚动条共用圆角；WebKit 轨道按该圆角上下内缩，滑块在透明横向 gutter 内保持浏览器原生长度比例，拉至顶部或底部不得越过输入框边界。Enter 继续输入换行而不提交表单。内部命名契约仍使用可选 `assetLabel`，最大 80 字符并在提交时 trim；历史状态或内部调用携带非空名称时，同一个名称必须贯穿 `assetLabel`、`canvasCompletion.title`、项目资源、账号素材和本地兜底图层，刷新后不得退回模板名。图标图集与角色动作请求同样兼容该字段，中间原图使用主名称加固定后缀；图标拆分素材按全连通域视觉顺序自动命名为 `素材 N`。 - 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和工具结果回填由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。 - Agent 消息附件只允许引用当前工程画布资源或账号素材库图片，来源类型为 `canvas_resource` / `library_asset`，最多 9 张。附件请求可携带展示用 `imageSrc/thumbnailSrc/objectKey/width/height/label`，但持久化真相仍以后端校验后的 resource / asset 行和 OSS 对象为准；不得把 Data URL、signed URL 或 blob URL 当作会话长期事实。 - 前端不直接订阅 SpacetimeDB，统一通过 api-server 的 `/api/editor/projects*` BFF 读写。 @@ -148,10 +149,10 @@ - `POST /api/editor/assets`：批量或单个创建账号级素材，登录态上传必须写入 OSS / asset object 引用和 `/` 轻量路径，不允许把 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` 的用户生成以统一业务像素矩阵创建前端占位和最终画布资源，例如两种图片模型的 `2K·16:9` 都交付 `2048x1152`；不得先请求固定 1K 再放大为 2K。`gpt-image-2` 在 provider 边界使用其接口支持的对齐请求尺寸，该尺寸不是业务交付尺寸；`nanobanana2` 仍把比例和清晰度档位写入 `generateContent`。provider 回图大于业务目标且比例偏差在允许范围内时，在内存中缩小并轻微裁切到业务尺寸后只上传最终结果。任意一边小于业务目标或比例偏差过大时禁止放大或大幅裁切，只上传 provider 实际回图，以实际尺寸写入结果并通过通用 `warning` 提示用户。主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`；父流程在持久化带纯色背景原图前先将回图归一到业务交付尺寸，再以该原图的 object key 向唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC；子 worker 在每次真实 provider attempt 前签发短期 OSS URL，并向 BgFilter 传入 `screen_color=`、`seg_model=`。父流程不直连 BgFilter、不签发该 URL，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。带背景原图和透明结果必须使用同一实际像素尺寸，1K 的长边固定为 `1024`；若 provider 回图不允许无放大地恢复到业务尺寸，两张图一同保留 provider 实际尺寸并返回通用 `warning`。透明处理结果发生尺寸漂移时，只允许在宽高比偏差不超过 `5%` 时重采样 alpha 蒙版并应用回已归一原图 RGB；蒙版比例超限、回贴失败或尺寸验证失败时不保存透明图，只以已保存原图和同时保留尺寸原因的通用 `warning` 完成画布。最终失败时按前述多产物降级规则以原图主结果和通用 `warning` 收口。图标图集和 UI 图集的透明处理正常成功但返回尺寸与 provider 原图不同时，同样只重采样 alpha 蒙版并应用回 provider 原图，不放大低分辨率后处理成品。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`，并继续按固定交付像素处理。从既有图层重新打开生成器且没有仍存活的对话框快照时，前端按该图层真实 `originalWidth / originalHeight` 恢复比例和清晰度，不得回落到新建面板的 1K 默认值。图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成完成后在响应中返回实际产物的 project / resource / asset 快照。 +- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片。带 `model / aspectRatio / imageSize` 的用户生成以统一业务像素矩阵创建前端占位和最终画布资源，例如两种图片模型的 `2K·16:9` 都交付 `2048x1152`；不得先请求固定 1K 再放大为 2K。`gpt-image-2` 在 provider 边界使用其接口支持的对齐请求尺寸，该尺寸不是业务交付尺寸；`nanobanana2` 仍把比例和清晰度档位写入 `generateContent`。provider 回图大于业务目标且比例偏差在允许范围内时，在内存中缩小并轻微裁切到业务尺寸后只上传最终结果。任意一边小于业务目标或比例偏差过大时禁止放大或大幅裁切，只上传 provider 实际回图，以实际尺寸写入结果并通过通用 `warning` 提示用户。主结果只写一次 OSS 且不额外创建“原始输出”。角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`；父流程在持久化带纯色背景原图前先将回图归一到业务交付尺寸，再以该原图的 object key 向唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC；子 worker 在每次真实 provider attempt 前签发短期 OSS URL，并向 BgFilter 传入 `screen_color=`、`seg_model=`。父流程不直连 BgFilter、不签发该 URL，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。带背景原图和透明结果必须使用同一实际像素尺寸，1K 的长边固定为 `1024`；若 provider 回图不允许无放大地恢复到业务尺寸，两张图一同保留 provider 实际尺寸并返回通用 `warning`。透明处理结果发生尺寸漂移时，只允许在宽高比偏差不超过 `5%` 时重采样 alpha 蒙版并应用回已归一原图 RGB；蒙版比例超限、回贴失败或尺寸验证失败时不保存透明图，只以已保存原图和同时保留尺寸原因的通用 `warning` 完成画布。最终失败时按前述多产物降级规则以原图主结果和通用 `warning` 收口。图标图集和 UI 图集的透明处理正常成功但返回尺寸与 provider 原图不同时，同样只重采样 alpha 蒙版并应用回 provider 原图，不放大低分辨率后处理成品。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`，并继续按固定交付像素处理。从既有图层重新打开生成器且没有仍存活的对话框快照时，前端按该图层真实 `originalWidth / originalHeight` 恢复比例和清晰度，不得回落到新建面板的 1K 默认值。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成完成后在响应中返回实际产物的 project / resource / asset 快照。 - `POST /api/editor/images/background-removals`：接收当前图片的 `objectKey`、`resourceId` 或 `assetId` 候选引用，登录态和稳定引用入口校验通过后创建外部生成任务，响应只返回 `queueState`。父 `external-generation-worker` 负责把候选引用解析为已登记、已校验当前账号归属的私有 OSS object key，只向唯一 `bgfilter-worker` 发起一次内部 HTTP RPC，传递 object key、`maxQueueWaitMs`、公式化 `callBudgetMs` 以及固定的 `background_mode=complex + seg_model=birefnet + cross_check=off`；父侧不下载原图、不签发 URL，也不发送 `file` 或 `screen_color`。子 worker 在每次真实 provider attempt 前签发 600 秒 OSS URL，以默认 `Q=2048` admission 保险丝和 provider 并发 `N=16` 限流，取得 provider permit 后才启动 `callBudgetMs`，并对同一次逻辑调用最多执行两次顺序 provider attempt；成功图片以内部 HTTP 二进制 body 返回父流程，父侧不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。complex 任意最终失败都直接使父任务失败，不进入阿里云或本地键色 fallback。请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`；成功后仍由父流程完成最终 OSS / project resource 持久化，有 `canvasCompletion` 时按生成占位写入结果图层，否则沿用旧的目标图层替换路径。provider 令牌只在子 worker 服务端通过 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 注入，未配置时兼容回退旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`；父子内部调用另使用独立内部 Token。 - `POST /api/editor/icon-spritesheets/generations`：主图标规范使用必填 `referenceId`，只接受当前 owner 的项目资源 ID 或素材 ID，不接受 `objectKey`、URL、临时 key 或 `referenceImageSrc` 作为主规范引用；普通附加参考图仍可使用独立 `referenceImageSrcs`。画布前端把完整用户需求作为 `iconDescriptions` 的唯一数组元素提交，不按分隔符或语义枚举解析数量。api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet，并与手动 `POST /api/editor/icon-spritesheets/slices` 复用同一套全连通域识别：识别多少个有效素材就拆多少个，按视觉阅读顺序命名为 `素材 N`，不读取 `iconDescriptions` 数量决定切片数。两条拆分路径共同限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片。切片只在有界管线中按需编码，共享单个 HTTP client 并以最多 `2` 路并发执行 OSS `PUT + HEAD`；client 的连接与单请求超时分别固定为 `10s / 60s`，手动入口在下载最大 `32 MiB` 来源对象前取得 memory admission，上传收齐后立即释放整图 admission，不跨数据库等待持有。所有对象验证通过后，由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中批量确认 `asset_object`、创建 project resource / account asset 并写入 cohort 完成事实，不得逐片发起三组 procedure 或在部分素材落库后伪造完整批次。resource / asset ID 由 owner、task 与切片序号稳定派生；同一批次不确定结果后重放只能复用内容完全一致的素材，冲突内容必须拒绝，来源资源还必须存在且与派生资源属于同一 owner / project。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`projectId`、`assetFolderId` 和 `generationInputs`，不接受客户端 `priceMudPoints`；后端按归一化后的模型和尺寸从运行时定价配置计算价格，queue 入队时冻结该价格，worker 的预扣、退款和结果投影均使用同一入队价格；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但自动拆分失败时保留整张透明图并返回非阻断 `sliceWarning`，手动拆分失败时返回接口错误。响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`。 -- `POST /api/editor/images/generations` 与 `POST /api/editor/icon-spritesheets/generations` 还可携带可选 `style`；公开合法字符串为 `none / pixelArt`，兼容归一化、支持的 `kind`、非阻断告警和零新增持久化规则以“静态图片风格与像素规整边界”为准。前述“带背景原图和透明结果必须使用同一实际像素尺寸”只约束 BgFilter 输出校验、Alpha 回贴以及进入 snapper 前的内部共同坐标系；`pixelArt` 的 Alpha 回贴结果随后进入 snapper，最终逻辑分辨率 PNG 允许与带背景原图不同。`POST /api/editor/ui-designs/assets/extractions` 不接受该字段。 +- `POST /api/editor/images/generations` 与 `POST /api/editor/icon-spritesheets/generations` 还可携带可选 `style`；公开合法字符串为 `none / pixelArt`，兼容归一化、支持的 `kind`、非阻断告警和零新增持久化规则以“静态图片风格与像素规整边界”为准。`POST /api/editor/ui-designs/assets/extractions` 不接受该字段。 - `POST /api/editor/images/pixel-art-snaps`：对已登记的静态图片执行免费的同步完美像素化。请求使用 `sourceImageSrc` 承载当前 owner 可读取的 `objectKey / resourceId / assetId` 候选稳定引用，`projectId / canvasCompletion` 必填且 `canvasCompletion.dialogId` 必须非空，`sourceResourceId / assetKind / generationInputs / assetFolderId / assetLabel` 可选；拒绝内联媒体、未登记对象和非静态栅格素材。客户端提交的 `generationInputs` 必须与其余生成入口一样先经 `sanitize_editor_client_generation_inputs` 剥离 `screenColorHex / mattingProvider / mattingModel` 三个服务端保留审计字段，再进入任何 IO——这三项是背景色决策与 bgfilter 实际执行后由服务端写入的处理事实，不接受客户端声明；本端点是纯几何规整、不抠图，任何 matting 元数据出现在这类记录上本身就是伪造。源图已有正式 project resource 时前端应带上 `sourceResourceId`：该资源随 owner-scoped 项目读取一并鉴权，服务端可直接取用其 objectKey，省去按注册 ID 的全账号项目与素材库扫描；此时 `sourceImageSrc` 应传该 objectKey 或同一个 `resourceId`，两者指向不同图片会被直接拒绝。不带 `sourceResourceId` 时仍需按注册 ID 解析，但全账号项目与素材库只取一次快照，注册 ID 解析、归属校验和跨记录 `assetKind` 收集全部在该快照上用 `_from_records` 纯函数完成，命中已登记记录即短路、两份记录都查不到才回落 asset object 点查；不得再调用内部自带两轮扫描的 `resolve_editor_reference_object_key_for_owner`。`get_editor_project` 到来源解析结束整体套同一份绝对处理预算，超时返回 `504` 且文案指向归属校验——预算从 handler 入口起算不等于覆盖该阶段，裸 `await` 会让请求一路走到下载才发现预算耗尽，并全程占用端点准入名额。像素处理使用 strict 失败语义且不进入外部生成队列；成功时只持久化一张最终 PNG，并返回对应 project / resource / asset 快照。服务端把规范化 `canvasCompletion.dialogId` 作为 operationId，以 owner / project 共同限定作用域，并从该 operation 稳定派生 task、asset object、resource、asset 身份；请求 fingerprint 覆盖来源 object key、来源与输出字节摘要、来源资源、素材类型、规范目录 / 标签、规范 generationInputs、completion 和算法版本。OSS PUT / HEAD 之后只调用一次原子 SpacetimeDB procedure；权威 dialog 仍存在时在源图右侧完成占位，已删除时只提交 object / resource / asset 而不推进 canvas revision。完整同内容重放返回 `AlreadyApplied`，同 operation 输入漂移或只有部分记录存在返回幂等冲突。 - `POST /api/editor/ui-designs/assets/extractions`：前端把红色框选轮廓绘入本地临时图后，先将该图上传 OSS 并确认 asset object，再以返回的 `objectKey` 作为参考图入队；Data URL / Blob URL 只允许停留在上传前的浏览器临时态。接口固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet；api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet 并按连通域尝试拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但拆分失败时保留整张透明图并返回 `sliceWarning`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`；前端按后端快照落画布，不补造缺失产物。 - 图片生成请求边界：角色生成、图标 spritesheet 和 UI 素材提取的同源画布 request DTO 保留 `segModel`，前端不提供选择控件而是自动提交默认 `birefnet`；api-server 继续校验并在字段缺失时回落默认值。`background_mode`、`cross_check` 与角色动作逐帧去背的 `seg_model` 不属于前端请求字段，只在 api-server 到 loopback worker 的内部 RPC 中传递。请求中的 `segModel` 不进入用户可见 `generationInputs` 或任何普通用户响应。 @@ -180,7 +181,7 @@ - 生成图片点击后显示画布内 `Image Generator` 占位框和跟随占位框的生成输入框，生成失败保留占位和输入状态，生成成功后在占位位置创建真实图层，并让输入框继续跟随该生成图。 - 选择 `1K / 2K` 或切换比例后，占位框在待生成和生成中阶段都必须立即显示对应目标像素尺寸；从普通图片、角色、图标图集或 UI 设计图进入改造时同样适用，完成落图前后不得从默认 1K 框跳变为 2K 成品。 - 普通图片、角色和图标面板显示 `像素艺术` 勾选项并正确提交 / 恢复 `style: "none" | "pixelArt"`；其它生成或编辑面板不显示该选项。旧 payload、未知字符串、不支持 `kind` 和非字符串输入分别按本方案约定的兼容或错误语义处理。 -- `pixelArt` 输出 Alpha 只包含 `0 / 255`；普通图片和角色仍先完成 Lanczos 交付尺寸归一，snapper 随后直接把一格一像素的逻辑网格编码为最终 PNG，不再 nearest 恢复到输入或交付尺寸，也不得执行其它后置尺寸插值。最终 PNG 宽高可以与规整输入不同，响应与资源快照按实际 PNG 尺寸记录。成功和后处理失败两条路径都不得比 `none` 增加 OSS PUT、项目资源、账号素材或画布 item。 +- `pixelArt` 输出 Alpha 只包含 `0 / 255`；普通图片和角色先完成 Lanczos 交付尺寸归一，再由 snapper 使用 nearest 把逻辑网格恢复到同一输入尺寸，规整后不得再次执行尺寸插值。成功和后处理失败两条路径都不得比 `none` 增加 OSS PUT、项目资源、账号素材或画布 item，逻辑低分辨率图不得出现在 OSS 或响应资源快照中。 - 生成中的占位图聚焦后支持键盘 `Delete` / `Backspace` 删除，不新增可见删除按钮；删除后对应异步回写必须按生成器 ID 判空并丢弃，不能把已删除素材重新落回画布。音乐 / 音频生成占位和已生成音频图层同样必须支持键盘删除。 - 画布常用快捷键必须与右上角快捷键弹窗一致；新增快捷键时应同步更新 `ImageCanvasShortcutModel`、快捷键 hook 单测和本方案。输入框、文本域和 contenteditable 聚焦时不得触发画布编辑快捷键。 - 撤销或恢复画布布局时不得覆盖同 ID 生成对象当前的任务生命周期、提示词、参考图和结果；上传持久化延迟回填内部资源 ID 不得把安全移动误判为素材替换。生成结果必须在加入画布前写入生成历史，自动适合视图不得覆盖这条栈顶记录。 @@ -198,15 +199,15 @@ - 发送消息后，面板先展示本地用户消息和请求等待态，再应用普通 JSON 响应中的 `deltaMessages`；客户端取消等待只终止本次 transport 等待，不把已经确认入队的外部生成任务改成停止态。 - Agent 工具任务完成并懒回填后，消息内缩略图不显示名称；前端通过编辑器作用域 Action Context 的 `refreshCanvas()` 直接重新读取工程快照和素材库，不从 Editor 经 Stage、Panel 和 MessageBubble 透传刷新 callback。图片、视频和音频结果携带有效 `resourceId` 时，在素材右键菜单显示“在画布中定位”；有效图片结果的普通单击也直接通过同一 Context 的 `focusResource(resourceId)` 请求画布在 `420ms` 内平滑 fit 到对应图层。结果卡片不声明按钮语义或 `tabIndex`，Enter 和 Space 不得触发定位；视频和音频的普通点击及原生播放器交互保持独立。定位只改变 viewport，不选择图层、不切换工具或侧栏、不收起 Agent 面板，也不避让面板覆盖区。缺少 `resourceId` 时单击无动作且不显示定位菜单项，目标图层已删除时保持无动作。对话入口触发生成时不创建“即将生成”画布占位，生成完成后由后端 `canvasCompletion` 落新图层。规划或工具失败时消息内必须保留可回读的失败状态和错误气泡，不能只弹一次性 toast 或返回瞬时 `errorMessage`。 - 画布 Agent 会话刷新后能从后端恢复会话标题、消息、附件和生成记录；前端不得根据本地临时状态伪造会话持久化结果。 -- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、完美像素按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、下载按钮。完美像素只对当前静态栅格图层一键执行，按钮在请求期间按 layer id 进入 disabled / busy，首个 await 前用同步 ref 抢占，连续点击不得重复提交；完成后保留源图并在右侧显示派生 PNG，明确失败的占位保留错误且释放 busy。该路由是 unsafe POST 且不得配置自动重放；纯校验、排队或预算等明确未进入结果持久化的响应可直接失败，transport、网关、abort、客户端超时或 `details.resultPersistenceStarted = true` 属于未知结果，必须按下列 durable operation 与 GET-only 契约收口。该图层的素材类型保存在途时（`persistingAssetKindLayerIds`）完美像素按钮同样必须 disabled / busy，并在 handler 里用同步 ref 二次拦截——请求同时携带 `assetKind` 与 `sourceResourceId`，本地类型已改而资源尚未落库时两者不一致，后端 `resolve_editor_pixel_art_snap_asset_kind` 直接返回 `400`，只留下需要手动清理的失败占位。这与相邻的拆分图集按钮共用同一套门禁，但保存态的无障碍名称必须区分（完美像素用 `完美像素等待素材类型保存`），否则 `icon-spritesheet` 图层上两个按钮会同时叫「素材类型保存中」。 -- `details.operationResultAlreadyExists = true` 是另一种必须 GET-only 收口的明确结果：它说明同一稳定 operation 的旧权威资源已经存在、当前请求尚未 PUT。客户端不得把它显示为普通失败、不得自动 POST 重放，也不得据此声称当前请求的持久化已开始。 +- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、完美像素按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。完美像素只对当前静态栅格图层一键执行，按钮在请求期间按 layer id 进入 disabled / busy，首个 await 前用同步 ref 抢占，连续点击不得重复提交；完成后保留源图并在右侧显示派生 PNG，明确失败的占位保留错误且释放 busy。该路由是 unsafe POST 且不得配置自动重放；纯校验、排队或预算等明确未进入结果持久化的响应可直接失败，transport、网关、abort、客户端超时或 `details.resultPersistenceStarted = true` 属于未知结果，必须按下列 durable operation 与 GET-only 契约收口。该图层的素材类型保存在途时（`persistingAssetKindLayerIds`）完美像素按钮同样必须 disabled / busy，并在 handler 里用同步 ref 二次拦截——请求同时携带 `assetKind` 与 `sourceResourceId`，本地类型已改而资源尚未落库时两者不一致，后端 `resolve_editor_pixel_art_snap_asset_kind` 直接返回 `400`，只留下需要手动清理的失败占位。这与相邻的拆分图集按钮共用同一套门禁，但保存态的无障碍名称必须区分（完美像素用 `完美像素等待素材类型保存`），否则 `icon-spritesheet` 图层上两个按钮会同时叫「素材类型保存中」。 - 裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`；父流程解析并校验私有 OSS object key 后只调用一次唯一内部 `bgfilter-worker` 的 complex 链路，子 worker 负责签发 600 秒 URL、`N / Q` 限流和最多两次顺序 provider attempt，complex 失败不接入 fallback，成功二进制返回后仍由父流程完成最终持久化。有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。 - 2026-08-04 修订：完美像素前端已经让素材刷新退出 verdict，持久化 operation 请求快照与 `pending-confirmation`，并接入刷新后的 GET-only 恢复；是否成功只能由下面的项目 GET 正向证据判定。 - 完美像素以 durable operation 为提交边界：请求账本 `perfectPixelOperation = { version: 1, kind: "perfect-pixel", operationId, taskId, request, submittedAt, reconcileUntil }` 存在**本机** `perfectPixelOperationStore`（owner + project 双键的 localStorage），其中 `operationId` 等于规范化 dialog id、`taskId` 固定为 `pixel-art-snap-{operationId}`，`request` 是稳定源引用解析完成后的完整 `EditorPixelArtSnapInput`，其新请求配方固定为 `version: 2 / action: image.perfect-pixel / fields: []`。账本外层版本不升级；嵌套 generationInputs 以共享严格白名单恢复，V2 完整接受稳定 `id`、有限数字、布尔值和可省略 `label`，旧 `{fields,references}` 请求继续按原形恢复以维持历史 fingerprint，未知键或畸形 V2 失败关闭。`submittedAt / reconcileUntil` 构成 **从 POST 发出时刻起算**、不得被 POST 回包续期的 75 秒整链绝对窗口——pre-POST flush 没有整体上限，锚在它之前会让窗口在请求发出前就烧光。项目布局里只保留 `perfectPixelOperationId` 标记，用于把这类占位与队列型占位区分开。**标记与账本的寿命必须对齐**：账本在收口那一刻清除，因此收口态占位（带非空 `generatedLayerId` 且状态不是 `generating` / `pending-confirmation`）既不再写出标记，也不得因为「有标记、没账本」被判成无效——服务端完成 completion 时只做字段级改写、从不摘标记，任何忽略这一点的判据都会把每一次成功判成失败。账本读不到（换设备、清缓存、隐私模式、配额写满）时，**未收口**占位收口成可删除的失败态，不得据此阻断用户删除或重做。完美像素 dialog id 使用跨标签随机 identity，不能复用每个标签页都会从 1 开始的局部计数器。inline 源图以该 identity 作为稳定 upload ID，只执行 object-only 上传，不等待 signed URL；快照不得包含 Data URL、Blob URL 或 signed URL。POST 前仍需 `await` 一次 best-effort 布局保存（服务端要求占位此前已持久化，见上文 409 条款），但保存冲突、鉴权失败或重试耗尽**不再让 POST 为零**——账本已在本机、请求可被追溯，客户端照常发出，由服务端裁决。人工重试只能原样重放该快照与同一 operation，不得重新 placement、上传、读取当前图层字段或暗中换 identity；快照缺失、损坏或与 dialog / project / task / completion 不匹配时失败关闭。首次提交或人工重试在途期间若 owner、project 或组件生命周期已经变化，旧响应的素材写入、项目应用、提示与对账副作用必须全部忽略，不能把前一账号的结果写入当前账号状态。 - 完美像素 unknown-result 的 verdict 只来自项目 GET，POST 响应体不得直接判成功：找到唯一稳定 task resource 且 dialog 已收口、结果层精确指向该 resource 时为 `Applied`；resource 存在且 dialog 不存在时为 `DialogMissing`，结果只在素材库；dialog 仍 generating（包括匹配 resource 已先可见）或 dialog 不存在且无匹配 resource 时继续有界轮询；resource 与 dialog / layer 出现原子事务不可能产生的错配时保持待确认并提示冲突，禁止自动 POST。首个 GET 立即执行，此后退避不超过 5 秒；即使绝对窗口已过期也必须读取一次。GET 的绝对 deadline 从进入 `requestJson` 起覆盖鉴权恢复、所有 attempt 和响应体读取；不能把只覆盖响应头的 `timeoutMs` 当成整次读取上界。单次 deadline 到期按一次读取失败处理，随后由轮询返回 `pending`，首次提交必须进入 `finally` 释放 dialog ownership 与图层锁，hydrate 恢复必须清理 recovery controller。`refreshAssetLibrary` 只在终态后 best-effort 触发，不进入轮询 deadline、`Promise.all` 或成功判断，同步 throw、异步 reject 和永久挂起均不得阻塞。轮询到期或 GET 失败后 dialog 转 `pending-confirmation`，保留 operation 与请求快照并释放页面 busy，不得伪装成普通失败或声称素材已保存。 - 完美像素恢复只对账、不重新执行：项目 hydrate 后识别带有效 operation 账本的 `generating` / `pending-confirmation` dialog，只按稳定 task/resource 做 GET-only 轮询，绝不 POST、重新上传、重新准备来源或为了恢复而先写布局；owner/project 切换、卸载或更高 revision 到来时旧轮询结果不得生效。恢复还必须覆盖**孤儿账本**——本机有账本、布局里却没有对应占位，这正是「POST 已发、布局尽力保存没落盘、标签页关闭」的结局。孤儿走一次确定性的读（不轮询）：`reconcileUntil` 只描述「结果可能还在飞」，而孤儿来自已经消失的会话，按它短路会让这条兜底分支在唯一的目标场景（稍后重开，必然晚于 75 秒）下永不生效。收口口径：`dialog-missing` 提示结果只进素材库；`applied` 静默刷新素材库（读到的就是当前权威状态，结果本就在眼前）；未落库完全静默。三者都清账本，读失败不清——那是「不知道」而非「知道没有」。新写入的 v1 operation 固定使用 75 秒跨度；为兼容第一批和滚动升级中的旧标签页，hydrate 仍接受跨度及未来时钟偏差不超过 240 秒的旧 v1 journal。若旧 `submittedAt` 位于可接受的未来区间，先把它规范化到当前时间，再把 `reconcileUntil` 压到 `min(持久截止, 规范化 submittedAt + 75 秒, 当前时间 + 75 秒)`；写回形状必须继续满足 `reconcileUntil >= submittedAt`，确保下次 hydrate 仍保留同一 identity。带 operation 的占位不受 `requiresLiveSession` TTL 清理（系统不替用户删），但**用户主动删除始终允许**——两者是不同的事。TTL 只兼容完全没有 operation 标记字段的历史 inline 孤儿，字段存在但内容损坏时必须保留并失败关闭，清理 legacy 孤儿时必须同时更新 `project.layers` 与 `project.canvas.layers`。恢复到期仍持久保持 `pending-confirmation`，只有用户明确点击重试才进入 exact replay。滚动升级期间从布局读到的 legacy 内联账本必须在 hydrate 后一次性迁入本机账本——布局里的内联快照会在下一次保存时被剥成标记，不迁移就再没有任何路径能补写，部署那一刻仍在途的操作会在第二次加载失去 exact retry identity。**已知限制**：本会话的「已观察」记账按 operation 记录，用于避免同一次 operation 被并发轮询两遍；若用户删除仍在处理中的占位、待原请求收口后再 `Ctrl+Z` 撤销删除，复活的占位在**当前会话内**不会被重新对账，会一直显示处理中。刷新页面即自愈（hydrate 会按标记与账本重新判定），且用户随时可以再删一次。该记账同时承担「并发保护」与「本会话已驱动过」两种语义，要根治需先拆开这两件事；在此之前不接受以「删除路径显式清观察记录」等跨 hook 埋线的方式局部绕过。 - legacy inline 占位的本会话归属必须由同一份封装 ownership 管理：同步 Set 在首个 await 前完成 `claim`，保证到期判定即时可见；`claim / release` 仅在 membership 真变化时推进 React 可观察的 version，`release` 即使发生时 dialogs 与 callbacks identity 都不变，也必须立即唤醒到期 effect 重新判定。禁止重新暴露可变 Set ref 或直接修改 `.current`，React 不会因为 ref 内容变化而重跑 effect。 -- 快速编辑站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；尚未登记且没有稳定引用的浏览器本地图片或普通 public 图片路径都必须先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。 +- 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。 +- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；尚未登记且没有稳定引用的浏览器本地图片或普通 public 图片路径都必须先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。 - 快速编辑不保留用户可添加的额外参考图入口；点击修改时把原图已登记业务 ID 作为 `/api/editor/images/edits` 的 `sourceReferenceId`，红框序号标注图上传后作为辅助 `referenceImageSrcs`。 - 素材文件夹可以新建、折叠、重命名和删除；删除普通文件夹后，其素材移动到“项目素材”。普通上传默认落入“上传素材”文件夹；素材库缺少该文件夹时，前端在首次普通上传前创建一次并复用，拖到指定文件夹或点击指定文件夹上传时仍进入目标文件夹。 - 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入“上传素材”并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入“上传素材”并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；上传视频同样在创建素材和图层前读取视频 metadata 宽高，保证单层下载或 ZIP 导出的真实视频文件重新导入后仍按文件自身尺寸入画布；仅在无法解析尺寸时才使用对应媒体兜底尺寸。普通静态图片的 `assetKind` 为空；`"image"` 只是前端 `CanvasMediaType`，不是 `CanvasAssetKind`，两者不得混用。OSS 直传确认成功后，即时占位素材、即时画布图层和补充图片尺寸探测必须使用本次换签得到的 signed URL，不得把私有对象的裸 `/generated-*` 兼容路径交给浏览器读取；账号素材持久化仍只写 `legacyPublicPath`、`objectKey` 和 `assetObjectId`，禁止把会过期的 signed URL 写入资源或素材记录。 diff --git a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md index 426e7df7f..2dffcf68f 100644 --- a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md +++ b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md @@ -205,7 +205,7 @@ controller 配置： - `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。 - `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。 - `editor_character_animation_generation`：角色动作视频和帧素材生成。 -- `editor_video_generation`：画布视频生成和视频素材快速编辑。 +- `editor_video_generation`：画布视频生成。 - `editor_sound_effect_generation` / `editor_background_music_generation`：画布音效与背景音乐。 画板结果的业务真相仍是 `asset_object`、`editor_project_resource`、账号级 `editor_asset`、可选 `asset_entity_binding` 和对应的 legacy / structured canvas 表；`editor_generation_operation` 只是提交回执，不替代这些 read model。worker 在 Provider 与 OSS 完成后只做 prepare：使用 owner + operation kind + job ID + stable slot 派生 resource/asset ID，构造可选 object/binding、候选 layout 和 compact job result，然后一次调用 `persist_editor_generation_result_and_return`。该 procedure 必须在当前事务快照校验 owner、job kind、由 `request_payload_json` 重算的 fingerprint 与未过期 lease，最后与业务记录一起完成 job 和 receipt。任一验证、binding 或 canvas CAS 失败都回滚全部数据库事实；worker 不得随后再调用 `complete_external_generation_job_and_return`。前端轮询单 job 到 completed 后重新读取项目快照，不从队列 payload、receipt 或本地临时响应重建正式图层。 diff --git a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md index 403a65806..153ed2722 100644 --- a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md +++ b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md @@ -113,10 +113,10 @@ - 占位图的生成器名称 / 原始尺寸、图片图层右上角素材类型标签、查看信息按钮和悬浮尺寸标签都按 viewport 反向缩放，画布缩小时保持屏幕可读尺寸。 - 查看信息按钮固定使用圆形 `i` 图标，不使用中括号、花括号或文本符号样式。 - 视频 / 角色 / 角色动作 / 音效 / 背景音乐待生成占位的角标同样按 viewport 反向缩放，不随画布缩放变小。 -- 已生成角色图、角色动作图或其它生成结果图被点击时只选中图层并收起已有生成输入框；重绘、快速编辑和生成动画面板必须由对应工具栏按钮或右键菜单显式打开。快速编辑使用统一正向白名单，只支持普通静态图片、角色图、规范图、完整图标图集、UI 设计图、宣发图和视频；单个拆分图标(backend reject)、角色动作 / 序列帧、音效与背景音乐不显示快速编辑入口，提交层也必须拒绝绕过入口的调用。 +- 已生成角色图、角色动作图或其它生成结果图被点击时只选中图层并收起已有生成输入框；重绘、快速编辑和生成动画面板必须由对应工具栏按钮或右键菜单显式打开。快速编辑使用统一正向白名单，只支持普通静态图片、角色图、规范图、完整图标图集、图标规范、UI 设计图、宣发图和游戏场景图；视频、单个拆分图标(backend reject)、角色动作 / 序列帧、音效与背景音乐不显示快速编辑入口，程序化打开和提交层也必须拒绝绕过入口的调用。 - 角色图层打开“生成动作”后再点击“改造”，必须重新打开角色形象生成器；动作生成对话框只把角色图层作为输入来源，不得被识别为该角色图层自身的来源生成器。 - 角色动作结果图层点击“改造”时，V2 必须通过 `references[id="source"]` 找回原角色图层，legacy 数据才允许以 `sourceResourceId` 回退；关联原角色已不存在时应显示明确提示，不得无响应或降级成图片生成器。 -- `改造` 覆盖图片、规范、角色、图标、UI、宣发、游戏场景、视频、音效、背景音乐、角色动作和生成型图片编辑。有效 V2 只按 `action + fields[].id + references[].id` 恢复，引用只匹配当前画布图层；面板直接上传引用和已移出画布的引用不恢复。V2 不新增后续版本，读取时统一经 action 级 runtime decoder 原地收紧：已存在但未知、非法、已下线或与当前模型能力不兼容的参数统一回落到该 action 当前默认值，历史 Veo 也回落到当前默认视频模型；图片比例 / 尺寸按回落后的模型联动校验，角色动作帧数 / 时长按完整档位成对校验。发生参数回落时显示明确告警，再次提交和新快照只使用规范值并继续保存为 `version: 2`。服务端以实际媒体时长覆盖 V2 配方时必须保留 `fields[id="durationSeconds"]`，并写入归一后的有限数值，不能改写为无 `id` 的 legacy 展示字符串。可重新选择的引用缺失时打开面板、留空槽位并提示，提交门禁继续校验必填槽位；必须依赖原 `source` 图层才能构造面板的 action 也始终按 capability 保留改造入口，source 缺失时点击后显示不可替换原因并拒绝改造，运行期间来源变化时仍必须复检并拒绝。有效 V2 不得因引用缺失降级到 legacy。生成型图片编辑 V2 中已持久化的附加 `reference` 应恢复到可见参考槽，并让再次提交的模型、比例、尺寸、像素尺寸、参考图和新快照保持一致；普通快速编辑仍不得提交未展示的隐藏参考图。视频快速编辑必须把实际送入请求的源视频同步保存为 `references[id="videoReference"]`，不能只依赖 `sourceResourceId`；视频 V2 同步保存并恢复 `webSearchEnabled`。历史对话框和 legacy 数据保留 `assetKind/mediaType`、标题别名、资源尺寸 / 模型 / 时长 / `sourceResourceId` 回退，并对默认值恢复显示告警。V2 结构水合必须完整保留 `version/action`、字段与引用 `id`、有限数字、布尔值和无标签引用；一旦出现 `version` 或 `action` 却不满足 V2 合同，必须失败关闭，禁止降级成 legacy。 +- `改造` 覆盖图片、规范、角色、图标、UI、宣发、游戏场景、视频、音效、背景音乐、角色动作和生成型图片编辑。有效 V2 只按 `action + fields[].id + references[].id` 恢复，引用只匹配当前画布图层；面板直接上传引用和已移出画布的引用不恢复。V2 不新增后续版本，读取时统一经 action 级 runtime decoder 原地收紧：已存在但未知、非法、已下线或与当前模型能力不兼容的参数统一回落到该 action 当前默认值，历史 Veo 也回落到当前默认视频模型；图片比例 / 尺寸按回落后的模型联动校验，角色动作帧数 / 时长按完整档位成对校验。发生参数回落时显示明确告警，再次提交和新快照只使用规范值并继续保存为 `version: 2`。服务端以实际媒体时长覆盖 V2 配方时必须保留 `fields[id="durationSeconds"]`，并写入归一后的有限数值，不能改写为无 `id` 的 legacy 展示字符串。可重新选择的引用缺失时打开面板、留空槽位并提示，提交门禁继续校验必填槽位；必须依赖原 `source` 图层才能构造面板的 action 也始终按 capability 保留改造入口，source 缺失时点击后显示不可替换原因并拒绝改造，运行期间来源变化时仍必须复检并拒绝。有效 V2 不得因引用缺失降级到 legacy。生成型图片编辑 V2 中已持久化的附加 `reference` 应恢复到可见参考槽，并让再次提交的模型、比例、尺寸、像素尺寸、参考图和新快照保持一致；普通快速编辑仍不得提交未展示的隐藏参考图。普通视频生成继续按现有 V2 合同保存并恢复 `references[id="videoReference"]` 与 `webSearchEnabled`，该合同不表示支持视频快速编辑。历史对话框和 legacy 数据保留 `assetKind/mediaType`、标题别名、资源尺寸 / 模型 / 时长 / `sourceResourceId` 回退，并对默认值恢复显示告警。V2 结构水合必须完整保留 `version/action`、字段与引用 `id`、有限数字、布尔值和无标签引用；一旦出现 `version` 或 `action` 却不满足 V2 合同，必须失败关闭，禁止降级成 legacy。 - 配方元数据不等于改造 capability。完美像素、手动去背景、裁扩、手动图集拆分以及图标 / UI 自动切片分别保存 `image.perfect-pixel`、`image.remove-background`、`image.crop-expand`、`spritesheet.split`，统一使用 `fields: []`；有正式来源行时只保留不可编辑的 `references[id="source"]` 权威来源，没有正式行时保留空引用。这四个确定性 action 永不显示或执行“改造”，历史 `pixel-art-snap-*` 结果也按 task identity 拒绝改造。整张生成图集仍保留原生成 action；生成任务内部自动抠图仍属于同源后处理，不提升为独立用户 action。 - 任何会移除画布图层的入口，包括删除、右键剪切和素材库删除关联素材，都必须同步清理该图层关联的生成面板和派生状态，不得在保存或刷新后恢复成孤立占位。 diff --git a/src/components/image-editor/ImageCanvasContextMenusView.test.tsx b/src/components/image-editor/ImageCanvasContextMenusView.test.tsx index cd4e225ab..634ca8275 100644 --- a/src/components/image-editor/ImageCanvasContextMenusView.test.tsx +++ b/src/components/image-editor/ImageCanvasContextMenusView.test.tsx @@ -371,6 +371,11 @@ describe('ImageCanvasContextMenusView', () => { mediaType: 'audio' as const, assetKind: 'background-music' as const, }, + { + title: '视频', + mediaType: 'video' as const, + assetKind: 'video' as const, + }, ])('hides quick edit from both menus for $title', (overrides) => { const layer = createLayer(overrides); renderContextMenus({ diff --git a/src/components/image-editor/ImageCanvasGenerationModel.test.ts b/src/components/image-editor/ImageCanvasGenerationModel.test.ts index d0fd5bb6a..bd11f7060 100644 --- a/src/components/image-editor/ImageCanvasGenerationModel.test.ts +++ b/src/components/image-editor/ImageCanvasGenerationModel.test.ts @@ -964,9 +964,16 @@ describe('ImageCanvasGenerationModel', () => { isQuickEditSupportedLayer({ ...buildSourceLayer(), mediaType: 'video', + assetKind: null, + }), + ).toBe(false); + expect( + isQuickEditSupportedLayer({ + ...buildSourceLayer(), + mediaType: 'image', assetKind: 'video', }), - ).toBe(true); + ).toBe(false); }); it('adds reference image semantics and snapshots for spec generation references', () => { diff --git a/src/components/image-editor/ImageCanvasGenerationModel.ts b/src/components/image-editor/ImageCanvasGenerationModel.ts index 409572301..6e7fee548 100644 --- a/src/components/image-editor/ImageCanvasGenerationModel.ts +++ b/src/components/image-editor/ImageCanvasGenerationModel.ts @@ -712,7 +712,6 @@ export function buildQuickEditModelOptions(currentModel: string) { const QUICK_EDIT_SUPPORTED_MEDIA_TYPES = new Set([ undefined, 'image', - 'video', ]); const QUICK_EDIT_SUPPORTED_ASSET_KINDS = new Set([ @@ -725,7 +724,6 @@ const QUICK_EDIT_SUPPORTED_ASSET_KINDS = new Set([ 'publication-material', 'ui-design', 'scene', - 'video', ]); export function isQuickEditSupportedLayer(layer: CanvasLayer) { diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx index a7d9e6b28..3d8c2db54 100644 --- a/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx +++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx @@ -13,23 +13,6 @@ import type { } from './ImageCanvasEditorTypes'; import { ImageCanvasQuickEditPanelView } from './ImageCanvasQuickEditPanelView'; -function createLayer(): CanvasLayer { - return { - id: 'layer-a', - resourceId: 'resource-a', - title: '源图', - src: 'data:image/png;base64,c291cmNl', - x: 0, - y: 0, - width: 320, - height: 180, - originalWidth: 320, - originalHeight: 180, - zIndex: 1, - sourceType: 'uploaded', - }; -} - function QuickEditPanelHarness({ initialPanel, onSubmit = vi.fn(), @@ -45,12 +28,27 @@ function QuickEditPanelHarness({ const [isReferenceMenuOpen, setIsReferenceMenuOpen] = useState(false); const [isPickingReference, setIsPickingReference] = useState(false); const referenceButtonRef = useRef(null); + const sourceLayer: CanvasLayer = { + id: 'layer-a', + resourceId: 'resource-a', + title: '源图片', + src: '/source.png', + mediaType: 'image', + originalWidth: 1024, + originalHeight: 1024, + width: 512, + height: 512, + x: 0, + y: 0, + zIndex: 1, + sourceType: 'uploaded', + }; return panel ? (
diff --git a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx index 2bf656347..2f2146ed2 100644 --- a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx +++ b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx @@ -444,7 +444,7 @@ describe('ImageCanvasSelectedLayerToolbarView', () => { within(videoToolbar) .getAllByRole('button') .map((button) => button.getAttribute('aria-label')), - ).toEqual(['快速编辑', '改造', '下载按钮']); + ).toEqual(['改造', '下载按钮']); cleanup(); renderSelectedToolbar({ diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx index 7c6531de2..66cd4da61 100644 --- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx +++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx @@ -337,14 +337,12 @@ function SubmissionWorkflowHarness({ quickEditPanel, quickEditSourceLayer, quickEditSelectionState: initialQuickEditSelectionState, - canvasGenerationDialogs: dialogs.canvasGenerationDialogs, setQuickEditPanel, characterAnimationPanel, characterAnimationDialog: activeCanvasDialog, characterAnimationSourceLayer, setCharacterAnimationPanel, setGenerateDialog: dialogs.setGenerateDialog, - openCanvasGenerationDialog: dialogs.openCanvasGenerationDialog, updateCanvasGenerationDialogById: dialogs.updateCanvasGenerationDialogById, hasCanvasGenerationDialogById: dialogs.hasCanvasGenerationDialogById, getCanvasGenerationDialogById: dialogs.getCanvasGenerationDialogById, @@ -1496,47 +1494,15 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => { expect(refreshWalletBalance).toHaveBeenCalledTimes(1); }); - it('submits video quick edits through the video API with the source video', async () => { - const applyProjectSnapshot = vi.fn(); - const upsertGeneratedAsset = vi.fn(); - generateEditorVideoMock.mockResolvedValueOnce( - createVideoGenerated({ - prompt: '把当前图改成雨天', - project: { - projectId: 'editor-project-1', - title: '项目', - coverImageSrc: null, - viewport: { x: 0, y: 0, scale: 1 }, - layers: [], - resources: [], - createdAt: '2026-06-27T00:00:00.000Z', - updatedAt: '2026-06-27T00:00:00.000Z', - }, - asset: { - assetId: 'asset-video-quick-edit', - folderId: 'user-1:asset-folder:project', - label: '源视频 快速编辑', - imageSrc: 'https://assets.example.test/generated-video.mp4', - thumbnailSrc: 'https://assets.example.test/generated-video-cover.png', - width: 854, - height: 480, - sourceType: 'generated', - assetKind: 'video', - }, - }), - ); + it('rejects direct video quick-edit submission without calling generation APIs', () => { render( { size: '854x480', model: 'gpt-image-2', status: 'idle', - quickEditReferences: [ - { - id: 'ref-style', - label: '风格参考', - src: 'https://assets.example.test/style.png', - }, - ], }} />, ); fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' })); - await waitFor(() => { - expect(generateEditorVideoMock).toHaveBeenCalledWith( - expect.objectContaining({ - prompt: '把当前图改成雨天', - model: 'seedance2.0-fast', - aspectRatio: '16:9', - durationSeconds: 4, - resolution: '480p', - mode: 'std', - sound: 'off', - referenceVideoSrcs: [ - 'generated-character-drafts/editor/generation-references/reference.png', - ], - generationInputs: expect.objectContaining({ - version: 2, - action: 'video.generate', - references: [ - { - id: 'videoReference', - title: '参考视频 1', - label: '源视频', - refType: 'project-resource', - refId: 'resource-source', - }, - ], - }), - assetFolderId: 'project', - assetLabel: '源视频 快速编辑', - }), - ); - }); - expect(generateEditorVideoMock.mock.calls[0]?.[0]).not.toHaveProperty( - 'referenceImageSrcs', - ); + expect(editEditorImageMock).not.toHaveBeenCalled(); expect(generateEditorImageMock).not.toHaveBeenCalled(); expect(generateEditorCharacterAnimationMock).not.toHaveBeenCalled(); - await waitFor(() => { - expect(applyProjectSnapshot).toHaveBeenCalledWith( - expect.objectContaining({ projectId: 'editor-project-1' }), - ); - expect(upsertGeneratedAsset).toHaveBeenCalledWith( - expect.objectContaining({ - assetId: 'asset-video-quick-edit', - thumbnailSrc: 'https://assets.example.test/generated-video-cover.png', - }), - ); - }); + expect(generateEditorVideoMock).not.toHaveBeenCalled(); + expect(screen.getByTestId('quick-edit').textContent).toContain( + 'failed:把当前图改成雨天:当前素材类型不支持快速编辑', + ); }); it('uploads inline video references and keeps image objectKey and asset URLs', async () => { diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts index d97836218..156ab1cde 100644 --- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts +++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts @@ -50,25 +50,23 @@ import type { QuickEditPanelState, SidebarPanel, } from './ImageCanvasEditorTypes'; -import { createQuickEditGenerationDialogDraft } from './ImageCanvasGenerationDialogModel'; import { applyImageEditResultToSourceLayer, createAudioResultLayer, createCharacterAnimationResultLayer, createGeneratedResultLayer, createIconSpritesheetResultLayers, + createQuickEditResultLayer, createVideoResultLayer, } from './ImageCanvasGenerationLayerModel'; import { buildCharacterAnimationGenerationInputs, + buildEditGenerationInputs, buildQuickEditGenerationInputs, buildUiDesignAssetExtractionGenerationInputs, - buildVideoGenerationInputs, - createCanvasLayerReference, DEFAULT_EDITOR_BGFILTER_SEG_MODEL, DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR, DEFAULT_IMAGE_MODEL, - DEFAULT_VIDEO_MODEL, inferEditorImageAspectRatio, inferEditorImageSizeLabel, isCanvasGenerationDialog, @@ -77,7 +75,6 @@ import { resolveEditorImageGenerationPixelSize, resolveImageGenerationErrorMessage, } from './ImageCanvasGenerationModel'; -import { chooseGenerationPlacement } from './ImageCanvasGenerationPlacementModel'; import { buildCharacterAnimationSubmissionPlan, buildIconSpritesheetGenerationSubmissionPlan, @@ -338,7 +335,6 @@ type GenerationSubmissionWorkflowOptions = { quickEditPanel: QuickEditPanelState | null; quickEditSourceLayer: CanvasLayer | null; quickEditSelectionState: UiAssetExtractionState | null; - canvasGenerationDialogs: CanvasGenerationDialogState[]; setQuickEditPanel: Dispatch>; characterAnimationPanel: CharacterAnimationPanelState | null; characterAnimationDialog: CanvasGenerationDialogState | null; @@ -347,9 +343,6 @@ type GenerationSubmissionWorkflowOptions = { SetStateAction >; setGenerateDialog: Dispatch>; - openCanvasGenerationDialog: ( - dialog: Omit, - ) => string; updateCanvasGenerationDialogById: ( dialogId: string, updater: CanvasGenerationDialogUpdater, @@ -650,10 +643,6 @@ function buildRightSideCanvasCompletionPlaceholder( }; } -function isVideoQuickEditSource(layer: CanvasLayer) { - return layer.mediaType === 'video' || layer.assetKind === 'video'; -} - export function useImageCanvasGenerationSubmissionWorkflow({ layers, canvasSize, @@ -662,14 +651,12 @@ export function useImageCanvasGenerationSubmissionWorkflow({ quickEditPanel, quickEditSourceLayer, quickEditSelectionState, - canvasGenerationDialogs, setQuickEditPanel, characterAnimationPanel, characterAnimationDialog, characterAnimationSourceLayer, setCharacterAnimationPanel, setGenerateDialog, - openCanvasGenerationDialog, updateCanvasGenerationDialogById, hasCanvasGenerationDialogById, getCanvasGenerationDialogById, @@ -871,6 +858,81 @@ export function useImageCanvasGenerationSubmissionWorkflow({ ], ); + const addQuickEditResultLayer = useCallback( + ( + generated: Parameters[0]['generated'], + sourceLayer: CanvasLayer, + generationInputs: CanvasGenerationInputs, + mode: QuickEditPanelState['mode'] = 'quick-edit', + options: { + frame?: GenerateDialogState['placeholder']; + dialogId?: string; + title?: string; + } = {}, + ) => { + if ( + options.dialogId && + !hasCanvasGenerationDialogById(options.dialogId) + ) { + return; + } + layerCounterRef.current += 1; + const generatedIndex = layerCounterRef.current; + const nextLayer = createQuickEditResultLayer({ + generated, + generatedIndex, + sourceLayer, + generationInputs, + mode, + frame: options.frame, + title: options.title, + }); + + addGeneratedLayersToCanvas([nextLayer]); + selectSingleLayer(mode === 'redraw' ? sourceLayer.id : nextLayer.id); + setActiveSidebarPanel('layers'); + if (mode === 'redraw') { + setQuickEditPanel((currentPanel) => + currentPanel?.sourceLayerId === sourceLayer.id + ? { + ...currentPanel, + mode: 'redraw', + status: 'idle', + errorMessage: undefined, + } + : currentPanel, + ); + } else { + setQuickEditPanel(null); + setActiveTool('select'); + if (options.dialogId) { + updateCanvasGenerationDialogById( + options.dialogId, + (currentDialog) => ({ + ...currentDialog, + status: 'idle', + composerOpen: false, + generatedLayerId: nextLayer.id, + errorMessage: undefined, + }), + ); + } + } + fitLayers([sourceLayer, nextLayer], { captureHistory: false }); + }, + [ + addGeneratedLayersToCanvas, + fitLayers, + layerCounterRef, + selectSingleLayer, + setActiveSidebarPanel, + setActiveTool, + setQuickEditPanel, + updateCanvasGenerationDialogById, + hasCanvasGenerationDialogById, + ], + ); + const applyQuickEditResultToSourceLayer = useCallback( ( generated: Parameters< @@ -1431,9 +1493,10 @@ export function useImageCanvasGenerationSubmissionWorkflow({ return; } + const panelMode = quickEditPanel.mode ?? 'quick-edit'; const quickEditResultTitle = resolveGenerationAssetLabel( quickEditPanel.assetLabel, - `${quickEditSourceLayer.title} 快速编辑`, + `${quickEditSourceLayer.title} ${panelMode === 'redraw' ? '重绘' : '快速编辑'}`, ); const quickEditReferences: CharacterReferenceImage[] = []; const quickEditAspectRatio = @@ -1451,175 +1514,54 @@ export function useImageCanvasGenerationSubmissionWorkflow({ const normalizedQuickEditModel = normalizeEditorImageModel( quickEditPanel.model, ); - const quickEditOutputSize = isVideoQuickEditSource(quickEditSourceLayer) - ? { - width: quickEditSourceLayer.originalWidth, - height: quickEditSourceLayer.originalHeight, - } - : resolveEditorImageGenerationPixelSize({ - model: normalizedQuickEditModel, - aspectRatio: quickEditAspectRatio, - imageSize: quickEditImageSize, - }); + const quickEditOutputSize = resolveEditorImageGenerationPixelSize({ + model: normalizedQuickEditModel, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + }); const quickEditSize = `${quickEditOutputSize.width}x${quickEditOutputSize.height}`; - const normalizedPrompt = quickEditPanel.prompt.trim() || '快速编辑图片'; - let quickEditDialogId: string | undefined; - const shouldUseCanvasPlaceholder = - isVideoQuickEditSource(quickEditSourceLayer); - if (shouldUseCanvasPlaceholder) { - const quickEditDraft = createQuickEditGenerationDialogDraft({ - sourceLayer: quickEditSourceLayer, - prompt: normalizedPrompt, - status: 'generating', - references: quickEditReferences, - model: quickEditPanel.model, - aspectRatio: quickEditAspectRatio, - imageSize: quickEditImageSize, - frame: { - width: quickEditOutputSize.width, - height: quickEditOutputSize.height, - }, - assetLabel: quickEditResultTitle, - }); - const quickEditPlacement = quickEditDraft.placeholder - ? chooseGenerationPlacement({ - canvasSize, - viewport, - frame: quickEditDraft.placeholder, - layers, - generationDialogs: canvasGenerationDialogs, - }) - : quickEditDraft.placeholder; - quickEditDialogId = openCanvasGenerationDialog({ - ...quickEditDraft, - // 中文注释：视频快速编辑仍落到独立视频结果占位，图片快速编辑直接替换源图。 - placeholder: quickEditPlacement, - }); - setQuickEditPanel(null); - selectSingleLayer(null); - } else { - setQuickEditPanel({ - ...quickEditPanel, - aspectRatio: quickEditAspectRatio, - imageSize: quickEditImageSize, - size: quickEditSize, - prompt: normalizedPrompt, - status: 'generating', - errorMessage: undefined, - }); - } + const normalizedPrompt = + quickEditPanel.prompt.trim() || + (panelMode === 'redraw' ? '重绘图片' : '快速编辑图片'); + setQuickEditPanel({ + ...quickEditPanel, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + size: quickEditSize, + prompt: normalizedPrompt, + status: 'generating', + errorMessage: undefined, + }); try { - const extraReferenceImageSrcs = await Promise.all( - quickEditReferences.map((reference) => - resolveEditorGenerationMediaReference(reference, 'image', projectId), - ), - ); - const quickEditFrame = quickEditDialogId - ? getGeneratingDialogPlaceholder({ - id: quickEditDialogId, - mode: 'quick-edit', - prompt: normalizedPrompt, - status: 'generating', - }) - : undefined; + const needsExtraReferenceImageSrcs = + panelMode === 'quick-edit' || panelMode === 'redraw'; + const extraReferenceImageSrcs = needsExtraReferenceImageSrcs + ? await Promise.all( + quickEditReferences.map((reference) => + resolveEditorGenerationMediaReference( + reference, + 'image', + projectId, + ), + ), + ) + : []; const quickEditCanvasCompletionPlaceholder = - quickEditFrame ?? buildRightSideCanvasCompletionPlaceholder(quickEditSourceLayer, { width: quickEditOutputSize.width, height: quickEditOutputSize.height, originalWidth: quickEditOutputSize.width, originalHeight: quickEditOutputSize.height, }); - if (isVideoQuickEditSource(quickEditSourceLayer)) { - const videoModel = DEFAULT_VIDEO_MODEL; - const videoResolution = '480p' as const; - const videoDurationSeconds = 4 as const; - const sourceVideoSrc = await resolveEditorGenerationMediaReference( - quickEditSourceLayer, - 'video', - projectId, - { allowRegisteredIds: false }, - ); - const generationInputs = buildVideoGenerationInputs( - normalizedPrompt, - [createCanvasLayerReference(quickEditSourceLayer)], - { - model: videoModel, - aspectRatio: '16:9', - resolution: videoResolution, - durationSeconds: videoDurationSeconds, - sound: 'off', - }, - ); - const generated = await runEditorGenerationWithWalletRefresh( - generateEditorVideo({ - prompt: normalizedPrompt, - model: videoModel, - aspectRatio: '16:9', - durationSeconds: videoDurationSeconds, - resolution: videoResolution, - mode: 'std', - sound: 'off', - ...(extraReferenceImageSrcs.length - ? { referenceImageSrcs: extraReferenceImageSrcs } - : {}), - referenceVideoSrcs: [sourceVideoSrc], - projectId, - generationInputs, - sourceResourceId: quickEditSourceLayer.resourceId, - assetKind: quickEditSourceLayer.assetKind, - assetFolderId, - assetLabel: quickEditResultTitle, - ...(projectId && quickEditCanvasCompletionPlaceholder - ? { - canvasCompletion: { - dialogId: quickEditDialogId, - title: quickEditResultTitle, - placeholder: quickEditCanvasCompletionPlaceholder, - }, - } - : {}), - }), - onWalletBalanceMayHaveChanged, - ); - if ( - await applyQueuedEditorGenerationProject( - generated, - projectId, - applyProjectSnapshot, - onQueuedGenerationTask, - onWalletBalanceMayHaveChanged, - ) - ) { - return; - } - if (generated.project && applyProjectSnapshot) { - applyProjectSnapshot(generated.project); - if (generated.asset) { - upsertGeneratedAsset?.(generated.asset); - } - return; - } - addVideoResultLayer( - generated, - quickEditResultTitle, - generationInputs, - quickEditFrame, - quickEditDialogId, - { - sourceLayer: quickEditSourceLayer, - assetKind: quickEditSourceLayer.assetKind, - }, - ); - return; - } const quickEditSelectionMarks = + panelMode === 'quick-edit' && quickEditSelectionState?.sourceLayerId === quickEditSourceLayer.id ? quickEditSelectionState.marks : []; - const sourceReferenceId = - resolveRegisteredEditorReferenceId(quickEditSourceLayer); + const sourceReferenceId = resolveRegisteredEditorReferenceId( + quickEditSourceLayer, + ); let markedReferenceImageSrc: string | null = null; if (quickEditSelectionMarks.length > 0) { const renderSourceImageSrc = await resolveEditorImageReferenceDataUrl( @@ -1640,36 +1582,92 @@ export function useImageCanvasGenerationSubmissionWorkflow({ ...extraReferenceImageSrcs, ...(markedReferenceImageSrc ? [markedReferenceImageSrc] : []), ]; - const generationInputs = buildQuickEditGenerationInputs( - '快速编辑提示词', - normalizedPrompt, - quickEditSourceLayer, - quickEditReferences, - { - model: normalizedQuickEditModel, - aspectRatio: quickEditAspectRatio, - imageSize: quickEditImageSize, - }, - ); - const generated = await runEditorGenerationWithWalletRefresh( - editEditorImage({ - prompt: normalizedPrompt, - sourceReferenceId, - size: quickEditSize, - model: normalizedQuickEditModel, - aspectRatio: quickEditAspectRatio, - imageSize: quickEditImageSize, - ...(imageEditReferenceSrcs.length - ? { referenceImageSrcs: imageEditReferenceSrcs } - : {}), - projectId, - generationInputs, - assetFolderId, - assetLabel: quickEditResultTitle, - targetLayerId: quickEditSourceLayer.id, - }), - onWalletBalanceMayHaveChanged, - ); + const redrawSourceReferenceImageSrc = + panelMode === 'redraw' + ? await resolveEditorGenerationMediaReference( + quickEditSourceLayer, + 'image', + projectId, + ) + : null; + const generationInputs = + panelMode === 'redraw' + ? buildEditGenerationInputs( + '重绘提示词', + normalizedPrompt, + quickEditSourceLayer, + { + model: normalizedQuickEditModel, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + }, + ) + : buildQuickEditGenerationInputs( + '快速编辑提示词', + normalizedPrompt, + quickEditSourceLayer, + quickEditReferences, + { + model: normalizedQuickEditModel, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + }, + ); + const isCharacterRedraw = + panelMode === 'redraw' && + quickEditSourceLayer.assetKind === 'character'; + const generated = + panelMode === 'quick-edit' + ? await runEditorGenerationWithWalletRefresh( + editEditorImage({ + prompt: normalizedPrompt, + sourceReferenceId, + size: quickEditSize, + model: normalizedQuickEditModel, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + ...(imageEditReferenceSrcs.length + ? { referenceImageSrcs: imageEditReferenceSrcs } + : {}), + projectId, + generationInputs, + assetFolderId, + assetLabel: quickEditResultTitle, + targetLayerId: quickEditSourceLayer.id, + }), + onWalletBalanceMayHaveChanged, + ) + : await runEditorGenerationWithWalletRefresh( + generateEditorImage({ + prompt: normalizedPrompt, + size: quickEditSize, + aspectRatio: quickEditAspectRatio, + imageSize: quickEditImageSize, + kind: isCharacterRedraw ? 'character' : 'quick-edit', + model: normalizedQuickEditModel, + referenceImageSrcs: [ + ...extraReferenceImageSrcs, + ...(redrawSourceReferenceImageSrc + ? [redrawSourceReferenceImageSrc] + : []), + ], + projectId, + assetKind: quickEditSourceLayer.assetKind, + generationInputs, + assetFolderId, + assetLabel: quickEditResultTitle, + sourceResourceId: quickEditSourceLayer.resourceId, + ...(projectId && quickEditCanvasCompletionPlaceholder + ? { + canvasCompletion: { + title: quickEditResultTitle, + placeholder: quickEditCanvasCompletionPlaceholder, + }, + } + : {}), + }), + onWalletBalanceMayHaveChanged, + ); notifyEditorGenerationWarning( generated.warning?.reason, onGenerationWarning, @@ -1684,38 +1682,40 @@ export function useImageCanvasGenerationSubmissionWorkflow({ onGenerationWarning, ) ) { - setQuickEditPanel(null); - setActiveTool('select'); - setActiveSidebarPanel('layers'); + if (panelMode === 'quick-edit') { + setQuickEditPanel(null); + setActiveTool('select'); + setActiveSidebarPanel('layers'); + } return; } if (generated.project && applyProjectSnapshot) { applyProjectSnapshot(generated.project); - setQuickEditPanel(null); - setActiveTool('select'); - setActiveSidebarPanel('layers'); + if (panelMode === 'quick-edit') { + setQuickEditPanel(null); + setActiveTool('select'); + setActiveSidebarPanel('layers'); + } return; } - applyQuickEditResultToSourceLayer( - generated, - quickEditSourceLayer, - generationInputs, - quickEditDialogId, - quickEditResultTitle, - ); - } catch (error) { - if (quickEditDialogId) { - updateCanvasGenerationDialogById( - quickEditDialogId, - (currentDialog) => ({ - ...currentDialog, - prompt: normalizedPrompt, - status: 'failed', - composerOpen: false, - errorMessage: resolveImageGenerationErrorMessage(error), - }), + if (panelMode === 'quick-edit') { + applyQuickEditResultToSourceLayer( + generated, + quickEditSourceLayer, + generationInputs, + undefined, + quickEditResultTitle, + ); + } else { + addQuickEditResultLayer( + generated, + quickEditSourceLayer, + generationInputs, + panelMode, + { title: quickEditResultTitle }, ); } + } catch (error) { setQuickEditPanel({ ...quickEditPanel, aspectRatio: quickEditAspectRatio, @@ -1727,26 +1727,17 @@ export function useImageCanvasGenerationSubmissionWorkflow({ }); } }, [ - addVideoResultLayer, + addQuickEditResultLayer, applyQuickEditResultToSourceLayer, applyProjectSnapshot, - canvasGenerationDialogs, - canvasSize, - getGeneratingDialogPlaceholder, - layers, - openCanvasGenerationDialog, projectId, assetFolderId, - upsertGeneratedAsset, quickEditPanel, quickEditSourceLayer, quickEditSelectionState, - selectSingleLayer, setActiveSidebarPanel, setActiveTool, setQuickEditPanel, - updateCanvasGenerationDialogById, - viewport, onGenerationWarning, onQueuedGenerationTask, onWalletBalanceMayHaveChanged, @@ -1952,6 +1943,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({ const sourceReferenceId = resolveRegisteredEditorReferenceId( submissionPlan.sourceLayer, ); + const isRedrawAsNewArtifact = Boolean(dialog.isRedrawAsNewArtifact); const quickEditSelectionMarks = quickEditSelectionState?.sourceLayerId === submissionPlan.sourceLayer.id @@ -1990,6 +1982,11 @@ export function useImageCanvasGenerationSubmissionWorkflow({ ), ), ); + const quickEditPlaceholderSize = + getCanvasCompletionPlaceholderSizeFromPlan({ + sourceLayer: submissionPlan.sourceLayer, + outputSize: submissionPlan.editInput.size, + }); const referenceImageSrcs = [ ...normalizedReferenceImageSrcs, ...(markedReferenceImageSrc ? [markedReferenceImageSrc] : []), @@ -1999,12 +1996,32 @@ export function useImageCanvasGenerationSubmissionWorkflow({ prompt: submissionPlan.normalizedPrompt, sourceReferenceId, ...submissionPlan.editInput, - ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}), + ...(referenceImageSrcs.length + ? { referenceImageSrcs } + : {}), projectId, generationInputs: submissionPlan.result.generationInputs, assetFolderId, assetLabel: submissionPlan.result.title, - targetLayerId: submissionPlan.sourceLayer.id, + ...(isRedrawAsNewArtifact + ? { + canvasCompletion: { + dialogId: canvasDialog?.id, + title: submissionPlan.result.title, + placeholder: + getGeneratingDialogPlaceholder(dialog) ?? + buildRightSideCanvasCompletionPlaceholder( + submissionPlan.sourceLayer, + { + width: quickEditPlaceholderSize.width, + height: quickEditPlaceholderSize.height, + originalWidth: quickEditPlaceholderSize.width, + originalHeight: quickEditPlaceholderSize.height, + }, + ), + }, + } + : { targetLayerId: submissionPlan.sourceLayer.id }), }), onWalletBalanceMayHaveChanged, ); @@ -2026,13 +2043,21 @@ export function useImageCanvasGenerationSubmissionWorkflow({ } return; } - applyQuickEditResultToSourceLayer( - generated, - submissionPlan.sourceLayer, - submissionPlan.result.generationInputs, - canvasDialog?.id, - submissionPlan.result.title, - ); + if (isRedrawAsNewArtifact) { + addGeneratedResultLayer(generated, { + sourceLayer: submissionPlan.sourceLayer, + title: submissionPlan.result.title, + generationInputs: submissionPlan.result.generationInputs, + }); + } else { + applyQuickEditResultToSourceLayer( + generated, + submissionPlan.sourceLayer, + submissionPlan.result.generationInputs, + canvasDialog?.id, + submissionPlan.result.title, + ); + } } else if (submissionPlan.kind === 'icon-spec') { const iconSpecInput = submissionPlan.input; const canvasCompletionPlaceholder = diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx index b78294d65..d69c8ca5e 100644 --- a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx +++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx @@ -1493,6 +1493,28 @@ describe('useImageCanvasGenerationWorkflow', () => { ); }); + it('does not open quick edit programmatically for video layers', () => { + render( + , + ); + + fireEvent.click(screen.getByRole('button', { name: '打开快速编辑' })); + + expect(screen.getByTestId('tool').textContent).toBe('select'); + expect(screen.getByTestId('selected').textContent).toBe('-'); + expect(screen.getByTestId('quick-edit').textContent).toBe('-'); + expect(screen.getByTestId('quick-edit-selection').textContent).toBe('-'); + }); + it('calculates character animation button price from the model pricing config', () => { render(); diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts index 26b9efab1..e9998dacb 100644 --- a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts +++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts @@ -3829,14 +3829,12 @@ export function useImageCanvasGenerationWorkflow({ quickEditPanel, quickEditSourceLayer, quickEditSelectionState, - canvasGenerationDialogs, setQuickEditPanel, characterAnimationPanel: effectiveCharacterAnimationPanel, characterAnimationDialog, characterAnimationSourceLayer, setCharacterAnimationPanel, setGenerateDialog, - openCanvasGenerationDialog, updateCanvasGenerationDialogById, hasCanvasGenerationDialogById, getCanvasGenerationDialogById,