From 41327a528c21517bd998eeb5327532c271337864 Mon Sep 17 00:00:00 2001 From: Linghong Date: Fri, 31 Jul 2026 05:45:21 +0000 Subject: [PATCH] =?UTF-8?q?=E6=81=A2=E5=A4=8D=E7=94=BB=E5=B8=83=E6=8A=A0?= =?UTF-8?q?=E5=9B=BE=E6=A8=A1=E5=9E=8B=E9=BB=98=E8=AE=A4=E8=AF=B7=E6=B1=82?= =?UTF-8?q?=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 恢复角色、图标和 UI 素材提取自动提交默认 segModel。 后端重新接收并校验 segModel，非法值不回显内部 provider 或模型。 保持普通用户响应、搜索、详情、导出与错误文本的内部信息脱敏。 修正 Owner/Public、External OpenAPI 与站内 BFF 请求边界文档。 补齐前后端请求序列化和安全回归测试。 --- .../shared-memory/decision-log.md | 6 +- ...架构】图片画布编辑器MVP接入方案-2026-06-11.md | 10 +-- ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 6 +- ...构】外部OpenAPI与APIKey接入方案-2026-06-19.md | 2 +- .../api-server/src/editor_agent/tool.rs | 4 + .../crates/api-server/src/editor_project.rs | 73 +++++++++++++------ ...CanvasEditorGenerationIntegration.test.tsx | 1 + .../ImageCanvasGenerationModel.ts | 1 + ...ageCanvasGenerationSubmissionModel.test.ts | 2 + .../ImageCanvasGenerationSubmissionModel.ts | 5 ++ ...anvasGenerationSubmissionWorkflow.test.tsx | 3 + ...ImageCanvasGenerationSubmissionWorkflow.ts | 3 + .../image-editor/editorProjectClient.test.ts | 6 ++ .../image-editor/editorProjectClient.ts | 6 ++ 14 files changed, 94 insertions(+), 34 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 5b79a6fdd..a07714bc1 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -19,9 +19,9 @@ ## 2026-07-30 抠图实际后端作为 generationInputs 顶层内部元数据保存 - 背景：角色、图标图集和 UI 图集抠图派生资产需要保留最终实际执行的处理后端，供后台诊断 BgFilter、阿里云通用抠图和本地键色的降级结果；把抠图模型写成 `generationInputs.fields` 的“处理模型”会进入图片信息，与用户可见输入快照语义冲突，而覆盖正式资产 `model` 又会丢失源生图模型。 -- 决策：继续使用现有 `generation_inputs_json` JSON 包络，不修改 SpacetimeDB schema。`fields` / `references` 只保存用户可见生成输入；仿照顶层 `screenColorHex`，抠图派生资产在顶层写入 `mattingProvider` / `mattingModel`。BgFilter 记录本次实际 `seg_model`；阿里云记录 `Aliyun Matting / segment-common-image`；本地键色记录 `Genarrative Local / screen-color-keying`。三条链路的正式资产 `model` 继续继承源生图模型，图片信息不读取顶层内部字段。`screenColorHex`、`mattingProvider`、`mattingModel` 和素材顶层 `provider` 属于内部执行信息：素材 owner、精选提交响应和后台管理接口仍按既有权限读取原始值，匿名 `GET /api/editor/showcase/resources` 必须在 public payload 边界删除三个 `generationInputs` 顶层内部键并省略 `provider`，历史精选快照不做数据迁移。角色动作逐帧可能混用多个 fallback，本次不把单帧结果提升为整组动画模型。 +- 决策：继续使用现有 `generation_inputs_json` JSON 包络，不修改 SpacetimeDB schema。`fields` / `references` 只保存用户可见生成输入；仿照顶层 `screenColorHex`，抠图派生资产在顶层写入 `mattingProvider` / `mattingModel`。BgFilter 记录本次实际 `seg_model`；阿里云记录 `Aliyun Matting / segment-common-image`；本地键色记录 `Genarrative Local / screen-color-keying`。三条链路的正式资产 `model` 继续继承源生图模型，图片信息不读取顶层内部字段。`screenColorHex`、`mattingProvider`、`mattingModel` 和素材顶层 `provider` 属于内部执行信息：普通用户（包括素材 owner）、精选提交 / 点赞响应与匿名公开读取统一省略，只有后台管理和服务端 raw 审计读取原始值；历史数据不迁移，在 User/Public mapper 边界清理。角色动作逐帧可能混用多个 fallback，本次不把单帧结果提升为整组动画模型。 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs` 的抠图结果和角色 / 图标 / UI 派生资产持久化、图片信息兼容测试、后端数据契约与图片画布 MVP 文档；不修改前端生产展示逻辑、请求 DTO、SpacetimeDB 表、迁移或生成绑定。 -- 验证方式：后端单测覆盖三种实际结果映射、顶层元数据不改写 `fields`，结构断言覆盖三条派生资产持久化链路仍保留源生图模型；public mapper 测试同时证明匿名响应省略 `provider` 和三个内部键、owner 精选快照仍保留原始值；前端测试覆盖顶层字段不在图片信息出现。运行 `cargo test -p api-server editor_project::tests --manifest-path server-rs/Cargo.toml`、图片信息定向前端测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。 +- 验证方式：后端单测覆盖三种实际结果映射、顶层元数据不改写 `fields`，结构断言覆盖三条派生资产持久化链路仍保留源生图模型；User/Public mapper 测试同时证明素材 owner、精选提交 / 点赞与匿名响应均省略 `provider` 和三个内部键，Admin raw payload 保留原始值；前端测试覆盖顶层字段不在图片信息或搜索索引出现。运行 `cargo test -p api-server editor_project::tests --manifest-path server-rs/Cargo.toml`、图片信息定向前端测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 --- @@ -31,7 +31,7 @@ - 背景：2026-07-30 的记录误把素材 owner 与后台审计并列为原始抠图执行信息的读取方。owner 是普通用户，前端不展示字段不能阻止其从项目资源、素材库、精选提交 / 点赞回包、画布布局或任务完成响应的网络 payload 读取 BgFilter、阿里云、本地键色、具体分割模型或背景色。 - 决策：本条取代 2026-07-30 决策中“素材 owner、精选提交响应仍可读取原始值”的表述。普通用户（包括素材 owner）和匿名公开读取必须共同过滤素材顶层 `provider`、内部处理 `model`，以及 `generationInputs` 顶层 `screenColorHex`、`mattingProvider`、`mattingModel`；正常用户可见生成 `model` 和其他合法功能性顶层字段（例如 `characterAnimation`）保持不变。User/Owner mapper 先完成该清理，public mapper 在其基础上叠加公开字段规则；后台管理与服务端审计继续使用 raw mapper 和持久化原值。历史数据不迁移，统一在读取边界清理。 - 入站与持久化：客户端提交的 `generationInputs` 不得伪造上述内部键，服务端在实际处理完成后才写入可信值。手动去背景的正式素材 `model` 必须继承经服务端验证的正常源生图模型；若来源或祖先链不存在正常模型则为 `null`，不得写入 `BgFilter complex` 等内部处理模型。内部抠图 provider / model 可继续持久化供后台审计，普通用户完成响应和用户可见错误文本均不得暴露它们；手动去背景与角色动作透明化失败在 Owner HTTP / 任务状态边界统一替换为稳定业务文案，原始错误只留在任务记录、tracing 和后台审计。 -- 影响范围：项目资源、素材库、精选提交 / 点赞、图片 / 图标 / 视频 / 音频 / 角色动画生成完成、Agent 紧凑结果和识别出的画布资源 / 图层快照的 User/Public mapper；手动去背景持久化和完成响应；External Editor API 创建素材 / 资源时的保留键入站清理；相应 API / OpenAPI 契约、前端搜索 / 详情 / ZIP 过滤测试与后台 raw 审计测试。不修改 SpacetimeDB schema、迁移或 bindings。 +- 影响范围：项目资源、素材库、精选提交 / 点赞、图片 / 图标 / 视频 / 音频 / 角色动画生成完成、Agent 紧凑结果和识别出的画布资源 / 图层快照的 User/Public mapper；手动去背景持久化和完成响应；External Editor API 创建素材 / 资源时的保留键入站清理；相应响应 / OpenAPI 契约、前端搜索 / 详情 / ZIP 过滤测试与后台 raw 审计测试。同源画布 BFF 的角色、图标和 UI 请求继续由前端自动提交默认 `segModel=birefnet`，后端继续校验并在缺失时回落默认值；该请求控制字段不进入 `generationInputs`、普通用户响应、搜索、详情、导出或错误详情。角色动作的 `seg_model` 继续由后端固定。不修改 SpacetimeDB schema、迁移或 bindings。 - 验证方式：Owner 和匿名响应覆盖无 `provider`、无内部 `model`、无三个内部 `generationInputs` 键，且正常 `model` 与 `characterAnimation` 仍保留；Admin raw payload 保持完整。覆盖历史 `BgFilter complex`、三类入站伪造键、手动去背景源模型回溯和用户错误文本过滤；运行 api-server 定向测试、前端定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding` 与 `git diff --check`。 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index 995b55582..ceb253072 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -22,8 +22,8 @@ - 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。重绘 / 改造输入框只允许从 `generationInputs.fields` 中恢复用户可见输入快照，例如普通生成提示词、视频描述、音效 `prompt`、背景音乐 `gpt_description_prompt`、角色设定、UI 用户输入、图标素材描述、规范表单和宣发素材字段；禁止回退展示资源 `prompt` / `actualPrompt` 中的后端拼接 Prompt、固定生成模板或模型默认提示词。没有用户输入快照的旧图层打开改造时保持空输入，等待用户重新填写。 - 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑统一打开框选区域 + 单提示词 + 模型选择面板，默认沿用原图模型，不展示参考图或比例 / 尺寸控件；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型；两类面板不展示抠图背景色或抠图模型选择；前端用户路径固定提交 `screenColor=auto` 和 `segModel=birefnet`，由后端自动决策具体抠图背景色，`anime-seg` 作为内部保留能力不在用户界面暴露。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材三个工作流（游戏首图、详情五图、运营海报）固定使用 `gpt-image-2`，面板模型胶囊为禁用态，不提供 `nanobanana2` 入口；前端按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；后端收到 `kind: "publication-material"` 时也强制归一为 `gpt-image-2` 生成和计费，生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端优先复用当前图层 objectKey；尚未登记的本地图片先上传 OSS，再把 objectKey 交给同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；普通图片、角色、图标图集、UI 设计图及其重绘 / 改造入口必须在比例或清晰度恢复、切换时同步把占位框 `width/height/originalWidth/originalHeight` 更新为目标像素尺寸，生成中不得继续显示默认 1K 框；UI 素材提取的 1K / 2K 图集占位和旧图片修改入口也分别使用本次目标尺寸与源图真实尺寸。待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片解析为已上传的 objectKey 或资源 ID；浏览器临时图片需先上传 OSS；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作的 `生成动画` 仍固定使用 `seedance2.0-fast` 动作 / 视频模型，角色动作素材的 `快速编辑` 按当前帧图片走图片编辑。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。 - 图片画布抠图统一通过唯一、只监听 loopback 的 `bgfilter-worker` 调用 BgFilter provider。手动去除背景面向用户任意图片，仍走登录态同源 BFF `POST /api/editor/images/background-removals` 和外部生成队列；API 在入队前拒绝 `data:` / `blob:` 内联媒体，父流程将稳定引用解析为当前账号已登记且归属已校验的私有 OSS 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`。四条 flat 路径同时把默认 `segModel=birefnet` 传为 `seg_model`，并显式传 `cross_check`：角色形象生成、图标 spritesheet 和角色动作逐帧去背传 `on`，UI 设计图素材提取传 `off`，不依赖 BgFilter 服务端默认值；后端仍保留识别 `anime-seg` 的内部兼容能力，但前端用户入口不展示也不提交 `seg_model`、`background_mode` 或 `cross_check`。子 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）→ 父侧阿里云 → 父侧本地键色` 链路。 -- 公开请求契约校正（取代本节与下文旧 `segModel` 表述）：普通前端只提交 `screenColor=auto`，不提交也不声明 `segModel`；公开 request DTO 不含 `segModel`、`background_mode` 或 `cross_check`。角色、图标 spritesheet、UI 设计图素材提取和角色动作四条 flat 路径均由 api-server 固定内部 `seg_model` 策略，并连同固定 `background_mode=flat`、按链路决定的 `cross_check` 通过 loopback RPC 传给 worker；手动去背景的 complex 参数同样只属于后端内部调用。 +- 编辑器自己生成的标准纯色背景抠图资产在保存源图后统一以 `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）→ 父侧阿里云 → 父侧本地键色` 链路。 +- 请求与可见性边界：同源画布 BFF 的角色、图标 spritesheet 和 UI 设计图素材提取 request DTO 保留 `segModel`，前端固定自动填充 `birefnet`，该字段不是用户选择或用户可见生成输入。External OpenAPI 是否接受 `segModel` 是独立契约，不能由站内 BFF 自动外推。`background_mode`、`cross_check` 以及角色动作的 `seg_model` 只由 api-server 决定并通过 loopback RPC 传给 worker。 - 普通用户生成结果不携带生成 provider：图片、图标图集、视频、音频和角色动画完成响应的公开类型均无 `provider`，前端也不得把 provider 写入新建结果图层；项目资源、素材和历史画布快照中的 provider 由后端 User/Public mapper 统一省略。真实 provider 仅留在服务端持久化、tracking / tracing 与后台原始审计。 - 手动去背景与角色动作透明化失败时，前端只消费后端按任务类型返回的稳定业务文案；不得从队列 `lastErrorMessage`、HTTP error details 或图层状态恢复和展示 BgFilter、分割模型、provider 等内部诊断。 - BgFilter 单次真实 provider attempt 不再使用独立固定 timeout，而由父子共同按 `attempt = N × est × 2` 运行时派生；一次逻辑调用的 `callBudgetMs = 2 × attempt + 1s`，从子 worker 取得 provider permit 后才开始计时。当前冻结 `N=16 / est=5000ms` 时为 `160s / 321s`。父侧继续管理父 job / request 总预算，为每个内部 RPC 单独派生 `maxQueueWaitMs`；排队只消耗该字段，不侵蚀 `callBudgetMs`，flat 还需预留阿里云和本地键色 fallback 时间。角色动作不再按本次实际帧数增加 attempt，`32 / 40 / 48` 帧使用同一公式。角色动画继续用 `buffer_unordered(frame_count.max(1))` 同时提交单帧逻辑调用，由唯一子 worker 保证健康进程内实际在飞的 provider 请求不超过 `N`、admission 不超过默认保险丝 `Q=2048`；父流程仍按“对应绿幕源图上传 OSS 并释放原帧字节 → 以 object key 调内部 worker / 按 object key 降级 → 父侧完成透明帧处理并落 OSS”连续组成无序在途流水线，允许响应乱序，并在收口时 collect / drain 全部已提交 frame future、按 `frameIndex` 恢复顺序。任一帧最终失败时仍先排空全部已启动请求，再使整个动作任务失败退款，不发布缺帧动画；最终图片处理、OSS、画布写回和计费始终属于父流程。 @@ -115,10 +115,10 @@ - `POST /api/editor/icon-spritesheets/generations`：按图标规范图和完整用户需求生成 spritesheet；为兼容现有契约，画布前端把完整文本作为 `iconDescriptions` 的唯一数组元素提交，不按分隔符或语义枚举解析数量。api-server 先保存带纯色背景 spritesheet 源图，透明处理成功后再保存透明 spritesheet，并与手动 `POST /api/editor/icon-spritesheets/slices` 复用同一套全连通域识别：识别多少个有效素材就拆多少个，按视觉阅读顺序命名为 `素材 N`，不读取 `iconDescriptions` 数量决定切片数。两条拆分路径共同限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置中对应生图模型的尺寸档位（如 `nanobanana2` 的 `0.5K / 1K / 2K` 或 `gpt-image-2` 的 `1K / 2K`），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。透明处理最终失败时只保存并返回原图主结果，不生成透明图或切片；透明图成功但自动拆分失败时保留整张透明图并返回非阻断 `sliceWarning`，手动拆分失败时返回接口错误。响应只返回实际产物对应的 project / resource / asset 快照及可选通用 `warning`。 - `POST /api/editor/images/generations` 与 `POST /api/editor/icon-spritesheets/generations` 还可携带可选 `style`；公开合法字符串为 `none / pixelArt`，兼容归一化、支持的 `kind`、非阻断告警和零新增持久化规则以“静态图片风格与像素规整边界”为准。`POST /api/editor/ui-designs/assets/extractions` 不接受该字段。 - `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`；前端按后端快照落画布，不补造缺失产物。 -- 图片生成接口公开请求契约校正（取代第 23、110、112、114 条中旧 `segModel` 字段枚举）：角色生成、图标 spritesheet 和 UI 素材提取只允许普通前端提交 `screenColor=auto`（以及各接口其余用户业务字段）；`segModel`、`background_mode`、`cross_check` 一律不是公开 DTO 字段。后端负责选择并固定四条 flat 路径的内部 `seg_model`，并在 loopback worker RPC 中传递该参数及每条链路的 `background_mode` / `cross_check`。 +- 图片生成请求边界：角色生成、图标 spritesheet 和 UI 素材提取的同源画布 request DTO 保留 `segModel`，前端不提供选择控件而是自动提交默认 `birefnet`；api-server 继续校验并在字段缺失时回落默认值。`background_mode`、`cross_check` 与角色动作逐帧去背的 `seg_model` 不属于前端请求字段，只在 api-server 到 loopback worker 的内部 RPC 中传递。请求中的 `segModel` 不进入用户可见 `generationInputs` 或任何普通用户响应。 - `POST /api/editor/images/edits`：按提示词和当前图片的已登记 `objectKey` / `resourceId` 修改图片，返回新的生成图片元数据；图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`，并随用户当前选择提交 `model / aspectRatio / imageSize / size`。api-server 必须先归一模型再选择 VectorEngine 协议：`nanobanana2` 调用 `/v1beta/models/{model}:generateContent` 并把原图作为 `inline_data`、比例和清晰度写入 `generationConfig.imageConfig`；`gpt-image-2` 调用 `/v1/images/edits` multipart。gpt-image-2 路径在 provider 边界把目标尺寸和所有 multipart 参考图临时补齐到 16 的倍数；nanobanana2 路径保留 provider 的比例 / 清晰度请求，但两条路径回图后都以统一业务目标尺寸尝试归一。只允许缩小和轻微裁切；回图任意一边小于目标或比例偏差过大时保留 provider 实际回图及尺寸，并返回通用 `warning`，不得放大伪造所选档位。无论是否发生尺寸恢复都只创建一个 project resource / 账号素材，不显示重复“原始输出”。provider 对齐尺寸或原生 K 档像素不得泄漏到正常完成的最终响应、资源或图层 Resolution；变换失败降级时以实际 provider 原图尺寸为准。本地红框标记图必须先上传再提交 objectKey；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。 -- `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音、默认联网搜索标记和泥点价格生成视频。前端可选模型为 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，默认 `seedance2.0-fast`；后端必须将 `seedance2.0-fast` 映射到 `doubao-seedance-2-0-fast-260128`，将 `seedance2.0` 映射到 `doubao-seedance-2-0-260128`，两者不得混用。后端允许 6 类比例、4 到 15 秒整数、`480p / 720p / 1080p`，并拒绝 `seedance2.0-fast + 1080p`；`sound=on/off` 映射 Ark `generate_audio=true/false`。后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `asset` 快照，基础响应返回 `videoSrc`、尺寸、prompt、model、provider、taskId、durationSeconds、resolution 和 `priceMudPoints`。 -- `POST /api/editor/audios/sound-effects/generations` 与 `POST /api/editor/audios/background-music/generations`：按音效 / 背景音乐参数生成音频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `resource` / `asset` 快照，基础响应返回 `audioSrc`、prompt、model、provider、taskId、duration、歌词和 `priceMudPoints`。 +- `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音、默认联网搜索标记和泥点价格生成视频。前端可选模型为 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，默认 `seedance2.0-fast`；后端必须将 `seedance2.0-fast` 映射到 `doubao-seedance-2-0-fast-260128`，将 `seedance2.0` 映射到 `doubao-seedance-2-0-260128`，两者不得混用。后端允许 6 类比例、4 到 15 秒整数、`480p / 720p / 1080p`，并拒绝 `seedance2.0-fast + 1080p`；`sound=on/off` 映射 Ark `generate_audio=true/false`。后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `asset` 快照，基础响应返回 `videoSrc`、尺寸、prompt、model、taskId、durationSeconds、resolution 和 `priceMudPoints`，不返回生成 provider。 +- `POST /api/editor/audios/sound-effects/generations` 与 `POST /api/editor/audios/background-music/generations`：按音效 / 背景音乐参数生成音频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `resource` / `asset` 快照，基础响应返回 `audioSrc`、prompt、model、taskId、duration、歌词和 `priceMudPoints`，不返回生成 provider。 所有写接口都必须校验 Bearer 登录态和 owner；接口只返回当前用户有权读取的工程与资源。 diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index f1df3caf1..22d844f4a 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -294,8 +294,8 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复 - 抠图输入以私有 OSS 作为内存生命周期边界：生成原图和角色动作抽取帧上传时消费图片字节所有权，上传完成后不保留原图缓冲；手动去背景直接解析并校验已有 OSS object key，不下载原图。BgFilter 必须为 object key 签发 600 秒 GET URL 并通过 multipart `image_url` 提交，不用 `file` 重传；flat 链路进入阿里云 fallback 时由 `platform-matting` URL 接口单独下载并上传 `AuthorizeFileUpload` 临时对象，在推理前释放下载缓冲，继续 fallback 到本地键色时再单独下载一次原图，本地产出后释放本次原图下载缓冲。签名 URL 不得写入日志、审计或持久化。 - 角色动作抠图输入像素边界：仅图片画布角色动作链路在 FFmpeg 抽帧后、源帧上传 OSS 前，把帧解码为 RGB8，并按最终 `frameWidth × frameHeight` 的 contain 比例使用 `Triangle` 只缩放到内容尺寸；该阶段不得创建最终目标尺寸画布、不得引入 Alpha 通道，也不得插入任何 padding。BgFilter、阿里云通用抠图和本地键色降级共享这个无补边源帧 object key。抠图返回后才统一转为 RGBA8，按相同比例居中放入最终目标尺寸画布，并用 `RGBA(0,0,0,0)` 补齐透明 padding。以 `560×752 → 323×480` 为例，抠图输入固定为无 Alpha、无补边的 `323×434 RGB8 PNG`，最终输出为上下各 `23px` 透明补边的 `323×480 RGBA8 PNG`。旧 `/api/assets/character-animation/*` 动作发布链路继续保留原有帧 finalizer，不适用该输入规则。抽帧解码后若携带 Alpha 通道，必须先把像素按白底合成为不透明再转 RGB8，禁止直接丢弃 Alpha——全透明像素下未定义的 RGB 值会以杂色进入抠图输入，重新引入杂色边缘；共享 FFmpeg 抽帧命令保持不固定 `-pix_fmt`，白底合成只属于该链路的 BgFilter 输入准备阶段。 - 阿里云通用抠图的非上海地域输入不得使用 `viapiutils/GetOssStsToken`、固定 `viapi-customer-temp` 或 OSS V1 PUT。`platform-matting` 必须按官方新版 SDK Advance 协议调用 `AuthorizeFileUpload`，使用动态返回的单对象 Policy 执行 multipart POST，再把临时上海 OSS URL 交给 `SegmentCommonImage`；输入归一化、结果下载与原尺寸 Alpha 回贴继续留在同一适配器内。该协议仍上传图片字节，不等同于阿里云服务端直接抓取任意公网 URL，也不改变上层 BgFilter → 阿里云 → 本地降级顺序。 -- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 与角色形象生成、图标 spritesheet 生成、UI 设计图素材提取、角色动作抽帧后的透明化统一通过唯一 loopback `bgfilter-worker` 调用 BgFilter provider。provider 配置继续使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL` 与 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，默认 base URL 为 `http://58.87.105.82/bgfilter`；单次 provider attempt 上限不再独立配置，由公式 `N × est × 2` 运行时派生，其中 `est = GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS`（默认 `5000`，依据为服务端高并发单图处理约 1-3s、网络约 3-5s），旧 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 已删除；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 provider token 的兼容回退别名，原手动去背景专用 base URL / timeout 配置已经删除。父流程先把候选 `objectKey`、`resourceId` 或 `assetId` 解析为当前 owner 已登记的私有 OSS object key；BFF 入队前统一拒绝 `data:` / `blob:`，底层 resolver 在解析引用前再次拒绝内联媒体并完成登记状态与 owner 校验。父流程只通过一次内部 HTTP RPC 传递 object key、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 与模式参数，不传图片字节或签名 URL，并同步等待子 worker 返回的受限图片二进制 body。子 worker 在每次真实 provider attempt 前签发短期 OSS URL，承担 admission 保险丝 `Q`（默认 `2048`，仅防连接风暴）、provider 并发 `N`（生产 `16`）；排队 deadline 从 `Q` admission 时刻起算，完成 JSON 校验并进入 provider permit 等待队列时再取得队长快照，按 `min((队长+5)×est×2, maxQueueWaitMs)` 约束排队等待。子 worker 还负责严格最多两次顺序 attempt、结果校验和按 flat / complex 隔离的进程级熔断；两种模式共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 和 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 默认值，但失败和成功只更新当前模式，且只由子 worker 读写。手动去背景固定使用 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或 `screen_color`；complex provider 失败累计自身熔断，任意失败或自身熔断都直接返回父流程失败，不接 flat fallback，也不影响 flat 熔断。标准纯色背景四条链路固定使用 `background_mode=flat`、`screen_color=`、`seg_model=` 和 `cross_check=`，其中角色形象生成、图标 spritesheet 生成和角色动作逐帧去背传 `cross_check=on`，UI 设计图素材提取传 `cross_check=off`。前端用户路径不展示抠图模型、模式或 cross-check，固定提交默认 `birefnet`，后端仍识别内部保留的 `anime-seg`；这些参数只属于后端内部供应商策略，不进入前端或外部 OpenAPI。父侧不重试已建立连接的内部 RPC，仅对 TCP 连接从未建立的失败按父预算有界退避重试（跨过 worker 重启与开机排序窗口，收到任何 HTTP 响应即停止）；flat 两次 provider attempt 失败、熔断、overload、内部 deadline 或断连后，只要父业务预算仍有效，父流程才继续“阿里云通用抠图 → 本地 `editor_green_screen` 键色扣除”，熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后每帧先上传私有 OSS 并释放原帧缓冲，再以 object key 固定使用 `seg_model=birefnet`、`cross_check=on` 进入上述三段式链路。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。标准纯色背景链路中，子 worker 已发出的 BgFilter provider 失败（含被剩余预算截短后发生的 timeout 与 response 阶段超时，这类失败不计入熔断但仍是审计候选）由进程级 `1024` 个审计任务硬上限保护，获准任务写入共享 tracking outbox 根目录下独立的 `bgfilter-worker/` 子目录并批量落库；满载、outbox 缺失、达到磁盘保护阈值或写盘失败时允许丢弃并记录指标，不回退逐条同步直写 SpacetimeDB。父侧阿里云抠图链路已开始后的失败（包括源 OSS GET 成功后的解码、尺寸校验和归一化失败）继续按通用外部 API 审计策略处理。真正开始外部调用前的本地预检不写该审计，并在 `failureStage` 中保留 `source_decode`、`source_validate` 等阶段。成功图片字节返回后，最终 Alpha / 尺寸恢复、OSS / asset object、画布写回、计费和父任务终态仍全部由父流程负责。 -- 公开请求契约校正（取代上段“前端固定提交默认 `birefnet`”及 `seg_model=` 的旧表述）：前端只提交 `screenColor=auto`，公开 DTO / OpenAPI 均不含 `segModel`、`background_mode` 或 `cross_check`。api-server 对角色、图标、UI、角色动作四条 flat 链路固定内部 `seg_model`，并按链路固定 `background_mode=flat` 与 `cross_check` 后再调用 loopback worker；这些参数及其历史兼容识别均是服务端供应商策略。 +- 编辑器抠图服务：手动 `POST /api/editor/images/background-removals` 与角色形象生成、图标 spritesheet 生成、UI 设计图素材提取、角色动作抽帧后的透明化统一通过唯一 loopback `bgfilter-worker` 调用 BgFilter provider。provider 配置继续使用 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL` 与 `GENARRATIVE_EDITOR_BGFILTER_TOKEN`，默认 base URL 为 `http://58.87.105.82/bgfilter`；单次 provider attempt 上限不再独立配置，由公式 `N × est × 2` 运行时派生，其中 `est = GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS`（默认 `5000`，依据为服务端高并发单图处理约 1-3s、网络约 3-5s），旧 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 已删除；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只作为 provider token 的兼容回退别名，原手动去背景专用 base URL / timeout 配置已经删除。父流程先把候选 `objectKey`、`resourceId` 或 `assetId` 解析为当前 owner 已登记的私有 OSS object key；BFF 入队前统一拒绝 `data:` / `blob:`，底层 resolver 在解析引用前再次拒绝内联媒体并完成登记状态与 owner 校验。父流程只通过一次内部 HTTP RPC 传递 object key、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 与模式参数，不传图片字节或签名 URL，并同步等待子 worker 返回的受限图片二进制 body。子 worker 在每次真实 provider attempt 前签发短期 OSS URL，承担 admission 保险丝 `Q`（默认 `2048`，仅防连接风暴）、provider 并发 `N`（生产 `16`）；排队 deadline 从 `Q` admission 时刻起算，完成 JSON 校验并进入 provider permit 等待队列时再取得队长快照，按 `min((队长+5)×est×2, maxQueueWaitMs)` 约束排队等待。子 worker 还负责严格最多两次顺序 attempt、结果校验和按 flat / complex 隔离的进程级熔断；两种模式共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 和 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120` 默认值，但失败和成功只更新当前模式，且只由子 worker 读写。手动去背景固定使用 `background_mode=complex`、`seg_model=birefnet`、`cross_check=off`，不传 `file` 或 `screen_color`；complex provider 失败累计自身熔断，任意失败或自身熔断都直接返回父流程失败，不接 flat fallback，也不影响 flat 熔断。标准纯色背景四条链路固定使用 `background_mode=flat`、`screen_color=`、`seg_model=` 和 `cross_check=`，其中角色形象生成、图标 spritesheet 生成和角色动作逐帧去背传 `cross_check=on`，UI 设计图素材提取传 `cross_check=off`。角色、图标 spritesheet 和 UI 设计图素材提取的同源画布请求不展示抠图模型选择，但自动提交默认 `segModel=birefnet`；api-server 负责 allowlist 校验并在字段缺失时回落默认值，角色动作逐帧去背的 `seg_model` 则由后端固定。`background_mode` 与 `cross_check` 只存在于 api-server 到 worker 的内部 RPC；请求中的 `segModel` 不进入 `generationInputs`、普通用户响应、搜索、详情、导出或错误详情，External OpenAPI 是否接受该字段按独立契约决定。父侧不重试已建立连接的内部 RPC，仅对 TCP 连接从未建立的失败按父预算有界退避重试（跨过 worker 重启与开机排序窗口，收到任何 HTTP 响应即停止）；flat 两次 provider attempt 失败、熔断、overload、内部 deadline 或断连后，只要父业务预算仍有效，父流程才继续“阿里云通用抠图 → 本地 `editor_green_screen` 键色扣除”，熔断期不得直接退化到本地兜底。角色动作视频生成的背景色已与生图链路统一：`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、low 推理档）读源角色图自动决策，并经硬过滤器剔除与前景 / 皮肤撞色的候选，手动 hex 则尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景等于抠图键色；抽帧后每帧先上传私有 OSS 并释放原帧缓冲，再以 object key 固定使用 `seg_model=birefnet`、`cross_check=on` 进入上述三段式链路。阿里云通用抠图配置为 `GENARRATIVE_ALIYUN_MATTING_ENABLED`、`GENARRATIVE_ALIYUN_MATTING_ENDPOINT`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_ID`、`GENARRATIVE_ALIYUN_MATTING_ACCESS_KEY_SECRET` 和 `GENARRATIVE_ALIYUN_MATTING_REQUEST_TIMEOUT_MS`；未配置专用 AK/SK 时可复用 `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`，默认 endpoint 为 `imageseg.cn-shanghai.aliyuncs.com`。标准纯色背景链路中，子 worker 已发出的 BgFilter provider 失败（含被剩余预算截短后发生的 timeout 与 response 阶段超时，这类失败不计入熔断但仍是审计候选）由进程级 `1024` 个审计任务硬上限保护，获准任务写入共享 tracking outbox 根目录下独立的 `bgfilter-worker/` 子目录并批量落库；满载、outbox 缺失、达到磁盘保护阈值或写盘失败时允许丢弃并记录指标，不回退逐条同步直写 SpacetimeDB。父侧阿里云抠图链路已开始后的失败（包括源 OSS GET 成功后的解码、尺寸校验和归一化失败）继续按通用外部 API 审计策略处理。真正开始外部调用前的本地预检不写该审计，并在 `failureStage` 中保留 `source_decode`、`source_validate` 等阶段。成功图片字节返回后，最终 Alpha / 尺寸恢复、OSS / asset object、画布写回、计费和父任务终态仍全部由父流程负责。 +- 请求与可见性边界：同源画布 BFF 的角色、图标 spritesheet 和 UI 设计图素材提取 request DTO 保留 `segModel`；前端只自动提交默认值，不提供用户选择控件。api-server 对该字段执行 allowlist 校验并提供缺省回退，再按链路固定 `background_mode=flat` 与 `cross_check` 后调用 loopback worker。普通用户与 External API 的响应、资源 read model、`generationInputs`、搜索、详情、导出和错误文本均不返回该请求控制字段或实际抠图模型；后台管理与服务端 raw 审计仍保留实际执行信息。 - BgFilter 连接复用、超时与动作帧流水线：`AppState` 分别复用父侧内部 worker HTTP Client 和子 worker 专用 BgFilter provider HTTP Client；父侧对一次逻辑调用至多让 worker 接收一次内部 RPC，不重试已建立连接后的失败；仅 TCP 连接从未建立时（worker 重启 / 开机排序窗口）按每轮重算 `maxQueueWaitMs` 的有界退避序列重连——增加的只是连接尝试次数，不产生第二次被接收的 RPC。重连配额按本进程是否已连通过 worker 分档：首连前（冷启动）flat 22.5s / complex 约 62.5s，首连后 flat ≤1.5s / complex 22.5s；每次重连计 `bgfilter_internal_connect_retry_total` 指标。子 worker 在同一个 `N` permit 内严格最多执行两次顺序 provider attempt。唯一子 worker 使用 `GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=N`（生产 `16`）限制真实 provider 在途数；`GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS=Q` 降级为可选 admission 保险丝（默认 `2048`，仅防连接风暴，显式配置时必须 `>= N`）。超时全部由 `N` 与 `est` 运行时派生：单 attempt 上限 `N × est × 2`、调用预算 `callBudgetMs = 2 × attempt + 1s`（自取得 `N` permit 起算）、排队等待受 `min((provider 等待队列队长+5)×est×2, maxQueueWaitMs)` 双重上界（动态项充当自适应过载探测，超时带 `bound = estimate | parent` 标记），排队不侵蚀调用预算；`N` 与 `est` 必须同放共享 API 基础环境；请求携带的 `callBudgetMs` 只是父侧配置指纹，worker 比对后不一致只告警并计 `bgfilter_internal_call_budget_drift_total` 指标、始终以本进程公式值执行——发布调优 N / est 的新旧进程共存窗口不得误伤在途任务，持久漂移由部署脚本共享 env 对齐校验在启动前拦截。角色动作不再增加 `2000ms × 本次实际帧数`，`32 / 40 / 48` 帧使用相同公式。父侧按剩余绝对预算派生 `maxQueueWaitMs`（flat 扣除 `39s` 父侧预留（`37s` fallback + `2s` 传输窗），complex 只留 `2s` 传输窗；`<= 0` 时不发请求直接降级 / 失败），client timeout 取 `maxQueueWaitMs + callBudgetMs + 2s`；每次 attempt 前重新签发短期 OSS URL，剩余时间不足时不开始新的 attempt。父侧成功响应解码槽 `P = 8`。角色动作继续以 `buffer_unordered(frame_count.max(1))` 将全部单帧逻辑调用加入无序在途集合；返回结果携带原始帧序并在最终 collect / drain 全部已提交 Future 后排序，任一帧最终失败时必须先排空全部已启动 Future，再让整个动作任务失败退款，不能发布缺帧动画。单帧按“绿幕源图 owned 上传 OSS 并释放原帧 → 以 object key 调内部 worker / 按 object key 由父侧降级 → 父侧处理透明帧并落 OSS”流水化。角色动画源帧 PUT、透明帧 PUT 和最终帧 HEAD 仍统一复用 `AppState` 内初始化一次的 OSS HTTP Client（连接池参数为 connect 30 秒、request 60 秒、idle 300 秒、每 host 8 个 idle 连接、TCP keepalive 60 秒），并受进程级 8 路 OSS semaphore 限制；BgFilter provider 的 `N` 不占该 OSS permit，阿里云和本地处理既不占 OSS permit，也不受 `N / Q` 限制。每个 OSS 网络 attempt 单独获取 permit，退避期间释放；PUT/HEAD 动画帧请求最多 3 次（250ms、500ms 退避），只重试无 HTTP 响应的传输错误、timeout、OSS PutObject 的 `400 + RequestTimeout`、PUT `400` 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 5xx。动作帧 PUT 只在 400 响应中有界读取最多 16 KiB OSS 错误 XML，并保留 `Code` 与响应头优先的 `x-oss-request-id`；错误体读取超时/断流时保留已读字节，已解析出的 `Code` 优先生效，未解析出 `Code` 则按 timeout/transport 归类重试；除 `RequestTimeout` 与该错误体读取失败情形外的其他 400、401/403/404、配置、URL/签名和空请求体错误不重试。最终帧 HEAD 失败只重试 HEAD，不重复 PUT。 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。 @@ -619,7 +619,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复 - Rust 结构体：`EditorProjectResource` - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs` - 说明：图片画布工程资源元数据表，保存已经放入某个 project 画布的上传 / 生成图片资源快照、OSS 引用、尺寸、来源类型、prompt、provider、task、源资源关系、`asset_kind`、`generation_inputs_json` 和历史 `public_showcase_enabled`。`asset_kind` 标记角色、图标、UI 设计图、视频、音频等素材类别；`generation_inputs_json` 保存用户可见生成输入快照，供图片信息页刷新后恢复。`public_showcase_enabled` 只保留旧接口兼容，不再作为 `/creation` 的 `陶泥儿精选` 事实源；精选公开改由账号级生成素材提交 `editor_showcase_asset` 审核决定。图片 / 图标 / UI 提取等生成 BFF 在请求携带 `project_id` 时负责创建该表记录并把 resource 快照返回前端；前端只保存稳定 `resource_id` 布局引用，不能把同一生成结果再次作为正式业务真相写入。项目封面快照也落在该表，使用 `asset_kind = project-cover-snapshot`、`source_type = uploaded` 和私有 OSS / asset object 引用，代表画布当前视口栅格化后的静态封面；项目列表和创作主页最近项目只读取最新封面快照资源，不在列表页根据 layout 临时拼画布。从账号级素材库把同一生成素材拖回同一项目画布时，后端优先复用同项目内同源同媒体资源，避免每个图层实例都插入新的资源行。账号级素材删除不级联删除该表，避免历史画布丢图。结构化 canvas 的几何、层级、分组和资源引用以 `editor_canvas_layer` 为权威，生成器对象以 `editor_canvas_generation_dialog` 为权威；legacy canvas 才在 2 MiB 上限内从 `editor_canvas.layers_json` 兼容读取。新写入不再把素材生成输入快照作为图层布局真相保存。历史普通图层缺资源只能由 migration operator 调用 `repair_editor_canvas_resources_and_return` 定向修复：procedure 每次只处理一个尚无迁移记录的 legacy canvas，校验 owner/project、revision、canvas/project 两份 raw layout SHA-256、精确 layer/resource/sourceResourceId、同工程替换资源与 private asset_object 谱系；图片只替换引用，音频只恢复经核验的 `420x120` 项目资源行。运维入口 `npm run spacetime:editor-canvas-resources:repair` 默认 dry-run，apply 必须绑定 plan SHA-256 并在成功后自动复核 already-repaired，禁止手工 SQL 绕过事务 guard。 -- `generation_inputs_json` 包络契约：`fields` / `references` 是图片信息读取的用户可见生成输入快照；顶层允许保存后端内部结果扩展。现有 `screenColorHex` 保存实际背景色，角色、图标图集和 UI 图集抠图派生资产使用 `mattingProvider` / `mattingModel` 保存实际成功的处理后端与模型。BgFilter 保存本次 `seg_model`，阿里云通用抠图保存 `Aliyun Matting / segment-common-image`，本地键色保存 `Genarrative Local / screen-color-keying`。公开生成请求只允许把 `screenColor=auto` 作为用户可见抠图输入；`segModel`、`background_mode` 和 `cross_check` 不属于公开 DTO，服务端完成实际策略选择。上述内部结果字段不写入 `fields`，普通用户（包括素材 owner）与匿名公开读取均不得取得；普通用户响应还必须省略素材顶层 `provider` 和内部处理 `model`，但保留正常用户可见 `model` 与其他合法的顶层功能字段。后台管理和服务端审计可读取原始值。过滤只作用于普通用户 / 公开响应边界，不修改素材或精选快照，因此历史数据无需迁移。 +- `generation_inputs_json` 包络契约：`fields` / `references` 是图片信息读取的用户可见生成输入快照；顶层允许保存后端内部结果扩展。现有 `screenColorHex` 保存实际背景色，角色、图标图集和 UI 图集抠图派生资产使用 `mattingProvider` / `mattingModel` 保存实际成功的处理后端与模型。BgFilter 保存本次 `seg_model`，阿里云通用抠图保存 `Aliyun Matting / segment-common-image`，本地键色保存 `Genarrative Local / screen-color-keying`。同源画布 BFF 的角色、图标和 UI 请求由前端自动提交 `screenColor=auto` 与默认 `segModel=birefnet`，其中 `segModel` 是不可由用户选择的请求控制字段，不进入 `generationInputs`；`background_mode` 和 `cross_check` 只属于 api-server 到 worker 的内部 RPC。External OpenAPI 不开放 `segModel`。上述内部结果字段不写入 `fields`，普通用户（包括素材 owner）与匿名公开读取均不得取得；普通用户响应还必须省略素材顶层 `provider` 和内部处理 `model`，但保留正常用户可见 `model` 与其他合法的顶层功能字段。后台管理和服务端审计可读取原始值。过滤只作用于普通用户 / 公开响应边界，不修改素材或精选快照，因此历史数据无需迁移。 - 普通用户生成结果契约：图片、图标图集、视频、音频和角色动画的完成响应与新建画布图层均不返回或写入生成 provider；项目资源、素材、精选和 Agent 紧凑结果使用同一读取边界。真实 provider 只保留在持久化、tracking / tracing 和后台管理原始审计中。该规则针对生成供应商元数据，不改变直传票据等必须由客户端执行的存储协议字段。 - 普通用户错误契约：手动去背景和角色动作透明化的原始服务端错误可能包含 BgFilter、分割模型或 provider 细节；Owner HTTP 响应与外部任务状态必须按 job kind 返回稳定业务文案，原始错误只保留在任务记录、tracing 与后台审计。 - 索引：`by_editor_project_resource_project_id`、`by_editor_project_resource_owner_user_id`。 diff --git a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md index 19b2f5de9..4197e7d97 100644 --- a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md +++ b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md @@ -116,7 +116,7 @@ SpacetimeDB procedure： 1. 通过 OSS / asset object adapter 持久化媒体文件。 2. 写入 `editor_asset`，让生成素材进入账号级素材库。 3. 如果请求带 `projectId`，写入 `editor_project_resource`。 -4. 返回图片读取地址、素材 ID、资源 ID、尺寸、prompt、model、provider 和 taskId。 +4. 返回图片读取地址、素材 ID、资源 ID、尺寸、prompt、model 和 taskId；普通 External API 响应、项目资源与素材 read model 不返回生成 provider 或内部抠图审计字段。同源画布前端自动提交默认 `segModel` 属于站内 BFF 请求契约，不因此向 External OpenAPI 开放该字段。 如果请求未带 `projectId`，只生成并写入素材库；调用方可随后创建项目或自行保存画板布局。 diff --git a/server-rs/crates/api-server/src/editor_agent/tool.rs b/server-rs/crates/api-server/src/editor_agent/tool.rs index 8e9199453..a14b96efd 100644 --- a/server-rs/crates/api-server/src/editor_agent/tool.rs +++ b/server-rs/crates/api-server/src/editor_agent/tool.rs @@ -333,6 +333,7 @@ impl EditorAgentTool for GenerateImageTool { style: None, model: Some(args.model), screen_color: None, + seg_model: None, aspect_ratio: Some(args.aspect_ratio), image_size: Some(args.image_size), reference_image_srcs: Some(reference_image_srcs), @@ -440,6 +441,7 @@ impl EditorAgentTool for GenerateCharacterTool { style: None, model: Some(args.model), screen_color: Some("auto".to_string()), + seg_model: Some("birefnet".to_string()), aspect_ratio: Some(args.aspect_ratio), image_size: Some(args.image_size), reference_image_srcs: Some(reference_image_srcs), @@ -549,6 +551,7 @@ impl EditorAgentTool for GenerateUiDesignTool { style: None, model: Some(args.model), screen_color: None, + seg_model: None, aspect_ratio: Some(args.aspect_ratio), image_size: Some(args.image_size), reference_image_srcs: Some(reference_image_srcs), @@ -802,6 +805,7 @@ impl EditorAgentTool for GenerateIconSpritesheetTool { style: None, model: Some(args.model), screen_color: Some("auto".to_string()), + seg_model: Some("birefnet".to_string()), aspect_ratio: Some(args.aspect_ratio), image_size: Some(args.image_size), project_id: Some(context.conversation.project_id.clone()), diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs index 2227cb190..a20362ebb 100644 --- a/server-rs/crates/api-server/src/editor_project.rs +++ b/server-rs/crates/api-server/src/editor_project.rs @@ -151,7 +151,6 @@ const EDITOR_UI_DESIGN_ASSET_IMAGE_KIND: &str = "editor_ui_design_asset"; const EDITOR_LEGACY_GREEN_SCREEN_SOURCE_ASSET_KIND: &str = "editor_green_screen_source"; const EDITOR_PROVIDER_SOURCE_SLOT: &str = "provider_source"; pub(crate) const EDITOR_BGFILTER_DEFAULT_SEG_MODEL: &str = "birefnet"; -#[cfg(test)] const EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG: &str = "anime-seg"; const EDITOR_BGFILTER_MATTING_PROVIDER: &str = "BgFilter"; const EDITOR_ALIYUN_MATTING_PROVIDER: &str = "Aliyun Matting"; @@ -270,6 +269,7 @@ pub struct EditorImageGenerationRequest { pub(crate) style: Option, pub(crate) model: Option, pub(crate) screen_color: Option, + pub(crate) seg_model: Option, pub(crate) aspect_ratio: Option, pub(crate) image_size: Option, pub(crate) reference_image_srcs: Option>, @@ -327,6 +327,7 @@ pub struct EditorIconSpritesheetGenerationRequest { pub(crate) style: Option, pub(crate) model: Option, pub(crate) screen_color: Option, + pub(crate) seg_model: Option, pub(crate) aspect_ratio: Option, pub(crate) image_size: Option, pub(crate) project_id: Option, @@ -351,6 +352,7 @@ pub struct EditorUiDesignAssetExtractionRequest { pub(crate) source_image_src: String, pub(crate) model: Option, pub(crate) screen_color: Option, + pub(crate) seg_model: Option, pub(crate) reference_image_srcs: Option>, pub(crate) aspect_ratio: String, pub(crate) image_size: String, @@ -1673,7 +1675,13 @@ pub(crate) async fn generate_editor_image_for_owner( // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要、但随后会被 payload 消费掉的输入。 let requested_screen_color = payload.screen_color.clone(); let reference_count = payload.reference_image_srcs.as_ref().map_or(0, Vec::len); - let seg_model = is_character_generation.then_some(EDITOR_BGFILTER_DEFAULT_SEG_MODEL); + let seg_model = if is_character_generation { + Some(parse_editor_bgfilter_seg_model( + payload.seg_model.as_deref(), + )?) + } else { + None + }; let is_ui_design_generation = matches!(normalized_kind, Some("ui-design")); let is_publication_material_generation = matches!(normalized_kind, Some("publication-material")); @@ -4380,6 +4388,22 @@ fn sign_editor_private_object_read_url( .map_err(|error| map_oss_error(error, "aliyun-oss")) } +fn parse_editor_bgfilter_seg_model(value: Option<&str>) -> Result<&'static str, AppError> { + let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else { + return Ok(EDITOR_BGFILTER_DEFAULT_SEG_MODEL); + }; + match value.to_ascii_lowercase().as_str() { + EDITOR_BGFILTER_DEFAULT_SEG_MODEL => Ok(EDITOR_BGFILTER_DEFAULT_SEG_MODEL), + EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG => Ok(EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG), + _ => Err( + AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({ + "field": "segModel", + "message": "抠图参数无效。", + })), + ), + } +} + struct PersistEditorSpritesheetSlicesInput { owner_user_id: String, project_id: Option, @@ -4588,7 +4612,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( // 仍白发一次 gpt-5-mini 决策。这里先固化决策需要的输入。 let requested_screen_color = payload.screen_color.clone(); let reference_count = 1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len); - let seg_model = EDITOR_BGFILTER_DEFAULT_SEG_MODEL; + let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?; let mut reference_images = Vec::with_capacity(1 + payload.reference_image_srcs.as_ref().map_or(0, Vec::len)); reference_images.push( @@ -5519,7 +5543,7 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner( "从 UI 设计图提取被红色框选的素材，输出 spritesheet。目标规格 {} {}。", payload.aspect_ratio, payload.image_size ); - let seg_model = EDITOR_BGFILTER_DEFAULT_SEG_MODEL; + let seg_model = parse_editor_bgfilter_seg_model(payload.seg_model.as_deref())?; let reference_image = parse_editor_reference_image( state, caller.owner_user_id.as_str(), @@ -12355,12 +12379,7 @@ mod tests { })) .expect("UI extraction request should deserialize dimensions"); assert_eq!(request.screen_color.as_deref(), Some("#E6D8FF")); - assert!( - serde_json::to_value(&request) - .expect("request should serialize") - .get("segModel") - .is_none() - ); + assert_eq!(request.seg_model.as_deref(), Some("anime-seg")); let generation_options = normalize_editor_ui_design_asset_extraction_options( request.model.as_deref(), request.aspect_ratio.as_str(), @@ -12426,12 +12445,7 @@ mod tests { assert_eq!(request.prompt, "生成图片"); assert_eq!(request.screen_color.as_deref(), Some("#CFEFFF")); - assert!( - serde_json::to_value(&request) - .expect("request should serialize") - .get("segModel") - .is_none() - ); + assert_eq!(request.seg_model.as_deref(), Some("anime-seg")); assert_eq!(request.style, None); } @@ -12698,12 +12712,7 @@ mod tests { Some(vec!["/generated-images/editor/style.png".to_string()]) ); assert_eq!(request.screen_color.as_deref(), Some("#7FB3FF")); - assert!( - serde_json::to_value(&request) - .expect("request should serialize") - .get("segModel") - .is_none() - ); + assert_eq!(request.seg_model.as_deref(), Some("anime-seg")); assert_eq!(request.asset_label.as_deref(), Some(" 冒险界面图标 ")); assert_eq!(request.style, None); @@ -12811,6 +12820,26 @@ mod tests { ); } + #[test] + fn editor_bgfilter_seg_model_parser_defaults_and_rejects_unknown_without_internal_details() { + assert_eq!( + parse_editor_bgfilter_seg_model(None).expect("default should parse"), + EDITOR_BGFILTER_DEFAULT_SEG_MODEL + ); + assert_eq!( + parse_editor_bgfilter_seg_model(Some("Anime-Seg")).expect("anime seg should parse"), + EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG + ); + + let error = + parse_editor_bgfilter_seg_model(Some("u2net")).expect_err("unknown model should fail"); + let body = error.body_text(); + assert!(body.contains("抠图参数无效")); + assert!(!body.to_ascii_lowercase().contains("bgfilter")); + assert!(!body.contains(EDITOR_BGFILTER_DEFAULT_SEG_MODEL)); + assert!(!body.contains(EDITOR_BGFILTER_SEG_MODEL_ANIME_SEG)); + } + #[test] fn editor_bgfilter_worker_budget_covers_two_attempts_and_parent_reserves() { let config = AppConfig::default(); diff --git a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx index 833e6e3d0..c307a36ee 100644 --- a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx +++ b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx @@ -3529,6 +3529,7 @@ describe('ImageCanvasEditorView generation integration', () => { sourceImageSrc: 'generated-character-drafts/editor/generation-references/marked-ui-design.png', screenColor: 'auto', + segModel: 'birefnet', aspectRatio: '1:1', imageSize: '1K', projectId: 'editor-project-ui-extract', diff --git a/src/components/image-editor/ImageCanvasGenerationModel.ts b/src/components/image-editor/ImageCanvasGenerationModel.ts index 069ed6b6f..396d10029 100644 --- a/src/components/image-editor/ImageCanvasGenerationModel.ts +++ b/src/components/image-editor/ImageCanvasGenerationModel.ts @@ -100,6 +100,7 @@ export const DEFAULT_ICON_DESCRIPTIONS = [ '冻结按钮', ]; export const DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR = 'auto'; +export const DEFAULT_EDITOR_BGFILTER_SEG_MODEL = 'birefnet'; export const UI_DESIGN_ASSET_EXTRACTION_PROMPT = '仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用所选单一纯色抠图背景。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。'; export const QUICK_EDIT_SIZE_PRESETS = [ diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts index 12f2a4548..1784b7056 100644 --- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts +++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts @@ -343,6 +343,7 @@ describe('ImageCanvasGenerationSubmissionModel', () => { kind: 'character', model: 'gpt-image-2', screenColor: 'auto', + segModel: 'birefnet', style: 'pixelArt', aspectRatio: '2:3', imageSize: '2K', @@ -716,6 +717,7 @@ describe('ImageCanvasGenerationSubmissionModel', () => { iconDescriptions: ['返回按钮\n\n设置按钮'], model: 'gpt-image-2', screenColor: 'auto', + segModel: 'birefnet', style: 'pixelArt', aspectRatio: '3:2', imageSize: '2K', diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts index 89f83d817..f33d4f55f 100644 --- a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts +++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts @@ -29,6 +29,7 @@ import { buildUiDesignGenerationInputs, buildVideoGenerationInputs, CHARACTER_ANIMATION_MODEL, + DEFAULT_EDITOR_BGFILTER_SEG_MODEL, DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR, DEFAULT_SOUND_EFFECT_DURATION_SECONDS, DEFAULT_SOUND_EFFECT_MODEL, @@ -342,6 +343,7 @@ export function buildImageGenerationSubmissionPlan({ ].filter((src): src is string => Boolean(src)); const imageModel = normalizeEditorImageModel(dialog.imageModel); const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR; + const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL; return { kind: 'image', normalizedPrompt, @@ -350,6 +352,7 @@ export function buildImageGenerationSubmissionPlan({ kind: 'character', model: imageModel, screenColor, + segModel, style: dialog.style === 'pixelArt' ? 'pixelArt' : 'none', aspectRatio: dialog.aspectRatio ?? '1:1', imageSize: dialog.imageSize ?? '1K', @@ -616,6 +619,7 @@ export function buildIconSpritesheetGenerationSubmissionPlan( const rememberImageModel = normalizeEditorImageModel(dialog.imageModel); const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR; + const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL; return { ok: true, iconDescriptions, @@ -633,6 +637,7 @@ export function buildIconSpritesheetGenerationSubmissionPlan( iconDescriptions, model: rememberImageModel, screenColor, + segModel, style: dialog.style === 'pixelArt' ? 'pixelArt' : 'none', aspectRatio: dialog.aspectRatio ?? '1:1', imageSize: dialog.imageSize ?? '1K', diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx index cff9acb33..038ecf126 100644 --- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx +++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx @@ -2573,6 +2573,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => { sourceImageSrc: 'generated/ui-design.png', model: 'gemini-3.1-flash-image-preview', screenColor: 'auto', + segModel: 'birefnet', }), ); }); @@ -2709,6 +2710,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => { 'generated-character-drafts/editor/generation-references/reference.png', model: 'gemini-3.1-flash-image-preview', screenColor: 'auto', + segModel: 'birefnet', aspectRatio: '1:1', imageSize: '2K', canvasCompletion: expect.objectContaining({ @@ -2770,6 +2772,7 @@ describe('useImageCanvasGenerationSubmissionWorkflow', () => { expect(extractEditorUiDesignAssetsMock).toHaveBeenCalledWith( expect.objectContaining({ screenColor: 'auto', + segModel: 'birefnet', referenceImageSrcs: ['generated/ref-style.png'], generationInputs: expect.objectContaining({ references: expect.arrayContaining([ diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts index e98227ad5..ff4df781d 100644 --- a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts +++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts @@ -58,6 +58,7 @@ import { buildQuickEditGenerationInputs, buildUiDesignAssetExtractionGenerationInputs, buildVideoGenerationInputs, + DEFAULT_EDITOR_BGFILTER_SEG_MODEL, DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR, DEFAULT_IMAGE_MODEL, DEFAULT_VIDEO_MODEL, @@ -1085,6 +1086,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({ ); } const screenColor = DEFAULT_EDITOR_GENERATION_BACKGROUND_COLOR; + const segModel = DEFAULT_EDITOR_BGFILTER_SEG_MODEL; const generationInputs = buildUiDesignAssetExtractionGenerationInputs( sourceLayer, options.references, @@ -1121,6 +1123,7 @@ export function useImageCanvasGenerationSubmissionWorkflow({ options.model ?? DEFAULT_IMAGE_MODEL, ), screenColor, + segModel, ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}), projectId, generationInputs, diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts index 9d4ef9952..ce9133c08 100644 --- a/src/services/image-editor/editorProjectClient.test.ts +++ b/src/services/image-editor/editorProjectClient.test.ts @@ -837,6 +837,7 @@ describe('editorProjectClient', () => { kind: 'character', model: 'gpt-image-2', screenColor: '#FFD6C2', + segModel: 'anime-seg', style: 'pixelArt', aspectRatio: '2:3', imageSize: '1K', @@ -861,6 +862,7 @@ describe('editorProjectClient', () => { kind: 'character', model: 'gpt-image-2', screenColor: '#FFD6C2', + segModel: 'anime-seg', style: 'pixelArt', aspectRatio: '2:3', imageSize: '1K', @@ -1014,6 +1016,7 @@ describe('editorProjectClient', () => { iconDescriptions: ['返回按钮'], model: 'gpt-image-2', screenColor: '#E6D8FF', + segModel: 'anime-seg', style: 'none', aspectRatio: '1:1', imageSize: '2K', @@ -1035,6 +1038,7 @@ describe('editorProjectClient', () => { iconDescriptions: ['返回按钮'], model: 'gpt-image-2', screenColor: '#E6D8FF', + segModel: 'anime-seg', style: 'none', aspectRatio: '1:1', imageSize: '2K', @@ -1153,6 +1157,7 @@ describe('editorProjectClient', () => { sourceImageSrc: '/generated-images/editor/ui-design.png', model: 'gpt-image-2', screenColor: '#7FB3FF', + segModel: 'anime-seg', referenceImageSrcs: ['/generated-images/editor/ui-ref.png'], projectId: 'editor-project-1', assetFolderId: 'project', @@ -1175,6 +1180,7 @@ describe('editorProjectClient', () => { sourceImageSrc: '/generated-images/editor/ui-design.png', model: 'gpt-image-2', screenColor: '#7FB3FF', + segModel: 'anime-seg', referenceImageSrcs: ['/generated-images/editor/ui-ref.png'], projectId: 'editor-project-1', generationInputs: { diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts index 8c03182fa..a830d8095 100644 --- a/src/services/image-editor/editorProjectClient.ts +++ b/src/services/image-editor/editorProjectClient.ts @@ -197,6 +197,7 @@ export type EditorImageGenerationInput = { | 'publication-material'; model?: string; screenColor?: string; + segModel?: string; style?: EditorImageGenerationStyle; aspectRatio?: string; imageSize?: string; @@ -229,6 +230,7 @@ export type EditorIconSpritesheetGenerationInput = { iconDescriptions: string[]; model?: string; screenColor?: string; + segModel?: string; style?: EditorImageGenerationStyle; aspectRatio?: string; imageSize?: string; @@ -250,6 +252,7 @@ export type EditorUiDesignAssetExtractionInput = { sourceImageSrc: string; model?: string; screenColor?: string; + segModel?: string; referenceImageSrcs?: string[]; aspectRatio?: string; imageSize?: string; @@ -916,6 +919,7 @@ export async function generateEditorImage(input: EditorImageGenerationInput) { ...(input.kind ? { kind: input.kind } : {}), ...(input.model ? { model: input.model } : {}), ...(input.screenColor ? { screenColor: input.screenColor } : {}), + ...(input.segModel ? { segModel: input.segModel } : {}), ...(input.style ? { style: input.style } : {}), ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}), ...(input.imageSize ? { imageSize: input.imageSize } : {}), @@ -962,6 +966,7 @@ export async function generateEditorIconSpritesheet( iconDescriptions: input.iconDescriptions, model: input.model?.trim() || EDITOR_IMAGE_MODEL_NANOBANANA2, ...(input.screenColor ? { screenColor: input.screenColor } : {}), + ...(input.segModel ? { segModel: input.segModel } : {}), ...(input.style ? { style: input.style } : {}), ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}), ...(input.imageSize ? { imageSize: input.imageSize } : {}), @@ -1009,6 +1014,7 @@ export async function extractEditorUiDesignAssets( sourceImageSrc: input.sourceImageSrc, ...(input.model ? { model: input.model } : {}), ...(input.screenColor ? { screenColor: input.screenColor } : {}), + ...(input.segModel ? { segModel: input.segModel } : {}), ...(input.referenceImageSrcs?.length ? { referenceImageSrcs: input.referenceImageSrcs } : {}),