From 9a37deeaf08d4816849e9f0d5a315c8143d2895b Mon Sep 17 00:00:00 2001 From: Linghong Date: Wed, 29 Jul 2026 12:56:37 +0000 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E7=AA=84=E5=83=8F=E7=B4=A0=E8=A7=84?= =?UTF-8?q?=E6=95=B4=E5=B0=BA=E5=AF=B8=E5=AE=88=E5=8D=AB=E7=9A=84=E7=94=9F?= =?UTF-8?q?=E6=95=88=E8=8C=83=E5=9B=B4=E8=A1=A8=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 决策记录原文写「修复失败返回尺寸错误交由调用方降级」，读起来像是角色和 图标两条链路都会降级。实际上守卫只保证像素路径不再谎报「尺寸无误」， 拿到尺寸错误之后如何处置仍由各调用方既有语义决定，本次未改动任何调用方。 改为显式写明生效范围：角色据此走原图安全降级、链路闭环；图标沿用 master 既有的非致命语义，只记录告警后继续持久化并拆分，因此 BgFilter 尺寸漂移且 回贴修复失败时仍可能持久化尺寸异常的透明图集，该残留属 master 既有行为， 不在本次范围内解决。守卫断言的注释同步收窄。 仅调整表述，不改代码行为，不新增承诺。 Co-Authored-By: Claude Opus 5 --- docs/project-memory/shared-memory/decision-log.md | 3 ++- server-rs/crates/api-server/src/editor_project.rs | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 938a77df2..0371e37b8 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -19,7 +19,8 @@ ## 2026-07-29 像素规整降级必须复用交付尺寸守卫 - 背景：像素模式接入「角色带背景原图与透明图统一交付尺寸」后，删除了原先像素路径末尾的后置尺寸恢复。但像素规整的 best-effort 降级分支（预算耗尽、回读 provider 原图失败或超时、CPU permit 获取失败、worker 内 deadline、join 异常、worker 超时）都直接返回 BgFilter 原始输出并把尺寸错误置为 `None`，跳过了非像素路径已有的尺寸比对与 alpha 回贴。BgFilter 回图尺寸漂移是已知现象，叠加并发上限 2 导致的 permit 超时后，角色会绕过「改用已保存的同尺寸原图完成画布」的安全降级，角色和图标都可能持久化尺寸漂移的低分辨率透明图。 -- 决策：像素路径的每一条降级都必须经 `degrade_editor_pixel_art_to_postprocessed_with_dimension_guard` 收口，该守卫复用非像素路径的 `apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original`：先做纯内存尺寸比对，与交付尺寸一致就原样返回且不产生额外 OSS GET；漂移才回读原图重贴 alpha；修复失败返回尺寸错误交由调用方降级。由 provider 原图逐像素合成的 `rgba_source` fallback 尺寸天然正确，不再经守卫。像素路径函数因此需要显式接收交付宽高。 +- 决策：像素路径的每一条降级都必须经 `degrade_editor_pixel_art_to_postprocessed_with_dimension_guard` 收口，该守卫复用非像素路径的 `apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original`：先做纯内存尺寸比对，与交付尺寸一致就原样返回且不产生额外 OSS GET；漂移才回读原图重贴 alpha；修复失败如实返回尺寸错误，由调用方按各自既有语义处理。由 provider 原图逐像素合成的 `rgba_source` fallback 尺寸天然正确，不再经守卫。像素路径函数因此需要显式接收交付宽高。 +- 生效范围（不承诺超出这一范围）：本决策只保证像素路径不再谎报「尺寸无误」，即不再把 BgFilter 原始输出连同 `None` 尺寸错误交回调用方。拿到尺寸错误之后怎么处理仍由各调用方既有语义决定，本次不改变任何调用方语义：角色生成会据此走「改用已保存的同尺寸原图完成画布」的安全降级，因此角色链路闭环；图标图集沿用 master 既有的非致命语义，只记录告警后继续持久化并拆分，因此在「BgFilter 尺寸漂移且回贴修复失败」时，图标仍可能持久化尺寸异常的透明图集——该残留属于 master 既有行为，未在本次范围内解决。 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs` 的角色与图标像素规整降级路径；不改变成功路径、OSS PUT 次数、资源类型、画布项或前端契约，OSS GET 仍只在尺寸漂移时发生。 - 验证方式：`pixel_art_degrade_paths_guard_postprocessed_delivery_dimensions` 结构断言固定"降级分支不得返回 `(postprocessed, None, …)`"与守卫的委托实现；运行 `cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`、`npm run check:rustfmt`、`npm run check:encoding` 和 `git diff --check`。 - 关联文档：本文件「2026-07-29 角色带背景原图与透明图统一交付尺寸」与「2026-07-28 图片生成风格使用可扩展字段并以纯内存像素规整首发」。 diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs index 9011cfb43..e694ce906 100644 --- a/server-rs/crates/api-server/src/editor_project.rs +++ b/server-rs/crates/api-server/src/editor_project.rs @@ -9376,8 +9376,10 @@ mod tests { let source = include_str!("editor_project.rs"); // 中文注释：像素规整的每一条 best-effort 降级（预算耗尽、回读原图失败或超时、 // permit 获取失败、worker 内 deadline、join 异常、worker 超时）都不能把 BgFilter - // 原始输出连同 None 尺寸错误直接交回调用方，否则角色会绕过原图安全降级、 - // 角色和图标都可能持久化尺寸漂移的低分辨率透明图。 + // 原始输出连同 None 尺寸错误直接交回调用方——那等于谎报「尺寸无误」。 + // 本断言只覆盖「如实上报尺寸错误」这一层：拿到错误后如何处置仍由各调用方 + // 既有语义决定，角色据此走原图安全降级，图标沿用 master 的非致命语义（只告警、 + // 继续持久化与拆分），后者不在本断言的保证范围内。 assert_function_not_contains( source, "async fn apply_editor_postprocessed_alpha_and_pixel_art_from_persisted_provider_source_or_original",