开启图标图集BgFilter交叉校验
将生成图标素材的 flat 请求固定切换为 cross_check=on。 同步调整现有结构断言与编辑器、后端和共享决策文档。
This commit is contained in:
@@ -16,6 +16,16 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-29 图标图集 BgFilter 开启 cross-check
|
||||
|
||||
- 背景：图标 spritesheet 的透明化需要提高主体内部孔洞、轮廓和相邻小图标边缘的交叉校验质量。
|
||||
- 决策：生成图标素材的 BgFilter `background_mode=flat` 请求固定显式传 `cross_check=on`，与角色形象和角色动作逐帧去背一致；UI 设计图素材提取及手动 complex 去背景继续传 `off`。该参数仍属于后端内部供应商策略，不进入前端 DTO 或外部 OpenAPI。
|
||||
- 边界：不修改 BgFilter fallback、Alpha 回贴、默认关闭 despill、图标切片、OSS / 资源 / 画布持久化和任务告警语义。
|
||||
- 验证方式：运行 `cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:rustfmt`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 画布 Agent 工具生命周期统一经 object-safe trait 分派
|
||||
|
||||
- 背景：画布 Agent 八类工具的参数规范化、确认展示、计价与 worker payload、完成结果格式化和媒体投影分别在 `tool_args.rs`、`display_args.rs`、`api.rs`、`reconcile.rs` 重复按工具名分派；新增或调整工具时容易漏改其中一处。
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -69,11 +69,11 @@
|
||||
- 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级，随后仍可进入原有自动拆分。
|
||||
- 逻辑低分辨率图只存在内存，并以 nearest 恢复到图集原有交付尺寸；像素模式不再经过 Lanczos。实现应复用 Alpha 回贴阶段读取的 provider 原图；必要时最多增加一次读取已有 provider 对象的 OSS GET，不得增加 OSS PUT。
|
||||
- 开启或关闭像素风格都保持现有 provider 原图、透明图集和实际成功切片的持久化与画布数量不变。禁止上传逻辑低分辨率图、像素化前后双份图集、预览或诊断图，也不新增 asset kind、项目资源、画布 item、任务类型或数据库字段。
|
||||
- 本功能不修改 BgFilter `flat` 调用、`cross_check=off`、fallback、Alpha 回贴或默认关闭 despill 的现状。BgFilter 最终失败时沿用只保留 provider 原图且不拆分的既有收口，像素规整不运行；像素规整自身失败时保留已成功的透明图并继续上传和拆分，通过通用 `warning` 非致命提示，不退款。`sliceWarning` 继续只表达透明图成功后的自动拆分失败，可与风格归一化或像素规整产生的通用 `warning` 并存。
|
||||
- 图标图集的 BgFilter `flat` 调用固定使用 `cross_check=on`，fallback、Alpha 回贴和默认关闭 despill 的行为保持不变。BgFilter 最终失败时沿用只保留 provider 原图且不拆分的既有收口，像素规整不运行；像素规整自身失败时保留已成功的透明图并继续上传和拆分，通过通用 `warning` 非致命提示，不退款。`sliceWarning` 继续只表达透明图成功后的自动拆分失败，可与风格归一化或像素规整产生的通用 `warning` 并存。
|
||||
|
||||
## 去背与保存
|
||||
|
||||
- 父流程收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。
|
||||
- 父流程收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=on`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。
|
||||
- 透明背景处理正常成功时，父流程把带背景原图和去背后的透明 spritesheet 写入 OSS、项目资源和账号素材库，再识别透明图集中全部有效 alpha 连通域并执行附加拆分；若 BgFilter 返回较小图集，只把 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不放大低分辨率后处理成品。画布完成快照同时写入透明主图与右侧 provider 原图（二者均已登记为 project resource / 账号素材），`generatedLayerId` 仍锚定透明主图；成功拆出的切片从 provider 原图右侧继续排列。调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。BgFilter 与父侧 fallback 最终均失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。最终透明结果及切片的 OSS / 资源 / 画布持久化仍全部由父流程负责。
|
||||
- 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，因为透明背景失败时不会进入拆分，但可与风格归一化或像素规整产生的通用 `warning` 并存。前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
|
||||
- 响应通过 `iconImageSrcs` 返回成功切片素材。图标素材生成的自动拆分与手动 `拆分图集` 复用同一套全连通域识别、视觉阅读顺序和自动命名规则：识别多少个有效素材就返回多少个，依次命名为 `素材 N`；用户提示词及 `iconDescriptions` 数组长度都不控制切片数量。
|
||||
|
||||
@@ -4577,7 +4577,7 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
|
||||
source_object_key.as_str(),
|
||||
screen_color,
|
||||
seg_model,
|
||||
EDITOR_BGFILTER_CROSS_CHECK_DISABLED,
|
||||
EDITOR_BGFILTER_CROSS_CHECK_ENABLED,
|
||||
&matting_audit,
|
||||
)
|
||||
.await;
|
||||
@@ -11519,7 +11519,7 @@ mod tests {
|
||||
"persist_editor_provider_source_image",
|
||||
"caller.report_processing_phase(state).await?",
|
||||
"remove_editor_generated_screen_background_with_bgfilter",
|
||||
"EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
|
||||
"EDITOR_BGFILTER_CROSS_CHECK_ENABLED",
|
||||
"persist_editor_provider_source_resource",
|
||||
"slice_editor_icon_spritesheet_all",
|
||||
"persist_editor_spritesheet_slices",
|
||||
@@ -11534,7 +11534,7 @@ mod tests {
|
||||
"persist_editor_provider_source_resource",
|
||||
"caller.report_processing_phase(state).await?",
|
||||
"remove_editor_generated_screen_background_with_bgfilter",
|
||||
"EDITOR_BGFILTER_CROSS_CHECK_DISABLED",
|
||||
"EDITOR_BGFILTER_CROSS_CHECK_ENABLED",
|
||||
],
|
||||
);
|
||||
assert_function_contains_in_order(
|
||||
|
||||
Reference in New Issue
Block a user