修正抠图文档现行与历史口径

补全图标素材 BgFilter OSS 签名 URL 与 multipart 字段契约

扩展短期签名 URL 决策的角色动作影响范围

为已被取代的 file 和独立 BiRefNet 历史决策添加更正标记

docs/project-memory/shared-memory/decision-log.md

@@ -27,7 +27,7 @@
 
 - 背景：角色形象、图标图集、UI 素材图集、角色动作抽取帧和手动去背景在调用 BgFilter 前都已有私有 OSS object key；继续由 api-server 下载或保留图片并作为 multipart `file` 再上传，会重复传输图片字节并占用 API 进程网络与内存。
 - 决策：上述抠图链路统一复用 object key，签发 600 秒 OSS GET URL，并通过 BgFilter multipart 的 `image_url` 字段提交；请求中不再携带 `file`。签名 URL 只交给 BgFilter，不写日志或持久化。2026-07-17 起，生成原图和动作帧上传后不再保留图片字节；进入“阿里云通用抠图 → 本地键色”兜底链时按阶段从私有 OSS 重新下载。
-- 影响范围：仅 `api-server/editor_project` 的 BgFilter 请求输入与相关文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、相关测试与文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。
 - 验证方式：定向测试必须断言 BgFilter 请求函数包含 `image_url` 与 600 秒 OSS 换签，不包含 multipart `file` 或源图字节读取；随后运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
 
 ## 2026-07-15 阿里云通用抠图上传切换到 AuthorizeFileUpload 正式链路
@@ -55,6 +55,8 @@
 
 ## 2026-07-14 手动去背景迁移到 BgFilter complex 模式
 
+> 后续更正：本条关于 multipart 图片文件输入的描述已由 2026-07-15「BgFilter 输入改用私有 OSS 短期签名 URL」和 2026-07-17「生成后抠图原图以 OSS 作为内存生命周期边界」取代；当前手动路径不下载原图，只提交 `image_url`。下文保留作历史记录。
+
 - 背景：图片画布手动“去除背景”此前单独代理 BiRefNet 服务；BgFilter 已增加 `background_mode=complex`，可直接处理非纯色背景，继续保留独立服务会形成重复的上游、配置和错误处理链路。
 - 决策：`POST /api/editor/images/background-removals` 保持前端与 BFF 契约不变，worker 改用现有 BgFilter 地址、token、超时和共享 HTTP client。multipart 提交图片文件、`background_mode=complex`、`seg_model=birefnet` 与 `cross_check=off`，不提交 `screen_color`。标准纯色背景的角色形象、图标 spritesheet、UI 素材提取和角色动作逐帧抠图继续使用 `background_mode=flat`。删除独立 BiRefNet base URL / timeout 配置；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 仅作为 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 的兼容回退别名。
 - 影响范围：图片画布手动去背景 worker、BgFilter HTTP 协议、api-server 配置、资源元数据、前端 provider 展示和相关文档。
@@ -238,6 +240,8 @@
 
 ## 2026-07-05 BgFilter 失败时本地纯色去背兜底
 
+> 后续更正：本条关于手动去背景仍使用独立 BiRefNet BFF 的描述已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：曾用一次性 BgFilter live probe 稳定复现 BgFilter 对 2K 输入返回 `HTTP 500 {"detail":"inference failed"}`，浏览器生成链路会因此收到“BgFilter 服务返回非成功状态”。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取仍优先调用独立 BgFilter；若 BgFilter 请求失败、返回非成功状态、返回空图片或非法图片，api-server 记录 warning 后使用本地 `editor_green_screen` 按解析后的纯色背景执行确定性去背兜底，不中断生成。手动任意图片去背景仍只走独立 BiRefNet BFF，不使用该兜底。
 - 更正（截至 2026-07-10 实现）：BgFilter 失败/熔断后不再直接本地兜底，而是先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 键色兜底；口径统一见 2026-07-09「角色动作视频…阿里云抠帧」决策，并已扩展到本条的角色形象/图标/UI 三条静态生图链路。
@@ -247,6 +251,8 @@
 
 ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
 
+> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
 - 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
@@ -304,6 +310,8 @@
 
 ## 2026-06-29 图片画布手动抠图走远端 BiRefNet BFF
 
+> 后续更正：本条独立 BiRefNet 服务、专用 base URL 以及 api-server 下载并解析原图的实现，已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：用户手动“去除背景”面对任意图片，前端 `chromaKey` 和标准绿幕后处理不适合复杂人物、自然背景或非纯色背景；远端 image host 已部署 BiRefNet 服务，需要让手动抠图走高质量模型，同时避免把服务令牌暴露到浏览器。
 - 决策：画布手动“去除背景”默认调用登录态同源 BFF `POST /api/editor/images/background-removals`。api-server 解析当前图片后代理到 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认指向 `http://58.87.105.82/remove-background`，可选 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只在服务端注入。api-server 对上游结果做字节和尺寸上限保护，并先落 OSS / asset object 再返回给前端。编辑器自己生成的标准绿幕资产不属于该决策，见 2026-06-30 绿幕契约收口。
 - 影响范围：api-server 编辑器图片接口、图片画布手动去背景、画布右上角任务侧栏、图片画布 MVP 技术文档。
@@ -441,6 +449,8 @@
 
 ## 2026-06-30 图片画布标准绿幕契约收口
 
+> 后续更正：本条关于生成资产只使用本地透明化、手动路径继续使用独立 BiRefNet 的描述，已由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代；当前 flat 链路为 `BgFilter → 阿里云 → 本地键色`。下文保留作历史记录。
+
 - 背景：角色形象、图标 spritesheet、UI 提取 spritesheet 和角色动作帧都要求模型生成标准绿幕，但提示词片段和后处理入口分散在多个模块中，容易把标准绿幕资产误接到远端 BiRefNet。
 - 决策：编辑器标准绿幕提示词和本地确定性绿幕透明化统一收口到 `server-rs/crates/api-server/src/editor_green_screen.rs`。手动 `POST /api/editor/images/background-removals` 继续面向用户任意图片并走 BiRefNet；编辑器自己生成的标准绿幕资产统一复用 `platform-image::generated_asset_sheets` 的本地透明化能力，不再依赖 BiRefNet。角色图、图标 spritesheet、UI 提取 spritesheet 和角色动作抽帧源图必须在绿幕透明化前先保存一份带绿幕原图到 OSS，便于追溯和重处理。
 - 影响范围：`editor_project.rs` 的角色图 / 图标图集 / UI 提取图集、`character_animation_assets.rs` 的编辑器角色动作帧、编辑器绿幕相关文档。

docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md

@@ -59,7 +59,7 @@
 
 ## 去背与保存
 
-- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 透明化；BgFilter multipart 固定传 `background_mode=flat`、`cross_check=off`，请求字段同时包含 `screenColor` 和 `segModel`。前端用户路径固定提交 `screenColor=auto` 与默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。
+- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲，再签发 600 秒 GET URL 调用 BgFilter 透明化；BgFilter multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。
 - 透明背景处理正常成功时，带背景原图和去背后的透明 spritesheet 都先写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。
 - 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
 - 响应通过 `iconImageSrcs` 返回成功切片素材；自动生成使用用户输入的素材描述命名，UI 设计提取和手动拆分按从上到下、从左到右自动命名为 `素材 N`。