合并 master 最新图集切片更新

保留 master 的图集切片资源边界、尺寸校验和 deadline 处理
保留派生资源继承生图模型并隐藏内部处理模型的现有修复

docs/openapi/genarrative-external-v1.openapi.json

@@ -3190,7 +3190,7 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "自动拆分未完成的稳定原因码。"
+            "description": "自动拆分未完成的稳定原因码，包括原始连通域超限、局部候选拥挤、输出切片超限、处理超时、未识别到素材或切片持久化失败。"
           },
           "reason": {
             "type": "string",
@@ -3263,7 +3263,7 @@
                 "type": "null"
               }
             ],
-            "description": "图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。自动拆分不按 iconDescriptions 数量校验切片数。透明背景最终失败时不会进入拆分；风格归一化或像素规整产生通用 warning 时，两者可以并存。"
+            "description": "可信透明图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
           },
           "prompt": {
             "type": "string"
@@ -3327,7 +3327,7 @@
                 "type": "null"
               }
             ],
-            "description": "生成成功但风格归一化、尺寸恢复、透明背景处理或像素规整发生非阻断降级时返回。透明背景最终失败时不会进入拆分；其它通用告警可以与 sliceWarning 并存。"
+            "description": "生成成功但风格归一化、尺寸恢复、透明背景处理、Alpha 回贴、provider 原图修复性回读、透明图完整解码或像素规整发生非阻断降级时返回。source-only 降级只返回 provider 原图且不会进入拆分；其它通用告警可以与 sliceWarning 并存。"
           }
         }
       },

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

@@ -16,11 +16,22 @@
 
 ---
 
+## 2026-07-29 图集切片必须受前置容量和有界 CPU 保护
+
+- 背景：图标与 UI 图集的 alpha 连通域识别会在 async handler 上同步执行；原始连通域合并采用全量两两比较，`64` 个输出限制又晚于排序、裁剪和 PNG 编码。碎块或噪点图会放大 CPU 与内存成本，手动拆分、图标自动拆分和 UI 提取都受影响。另一方面，图标与 UI 的 Alpha 尺寸恢复、provider 原图回读或透明图解码失败此前只记日志，仍会把不可信透明图持久化并拆分。
+- 决策：`platform-image` 在每次 flood-fill 后累计所有原始连通域（包括随后过滤的噪点）并以 `4096` 为硬上限；合并只通过 `64px` 空间网格查询 `48px` 最大邻域内且满足辅助部件尺寸条件的候选，单网格最多登记 `256` 个组件、单 source 最多保留 `512` 个候选，拥挤时明确返回资源限制错误；调用方把固定 `maxOutputSlices=64` 传入 platform slicer，并在排序、裁剪和 PNG 编码前拒绝超限。三条入口统一走 2 路 semaphore、30 秒本地上界与请求绝对 deadline 共同保护的 `spawn_blocking`，permit 必须由 blocking 闭包持有。自动图标 / UI 超限以空切片和稳定 `sliceWarning` 完成，手动拆分返回 `422`，两者都不得产生任何切片 PUT、资源或画布切片；自动路径已成功的整张图集仍按既有契约保留。
+- source-only 收口：角色、图标和 UI 共用同一个 provider 原图收口 helper。BgFilter 最终失败、Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败或透明图完整解码失败时，只用已保存 provider 原图完成占位，返回 `completed + warning`；图标 / UI 固定 `iconImageSrcs=[]`、`sliceWarning=null`，不写透明图、不拆分。provider 原图本身无法解码时在首次持久化前失败，不再伪造 `512×512` 元数据。
+- 影响范围：`server-rs/crates/platform-image/src/generated_asset_sheets/`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布图标与 UI 素材生成 / 手动拆分链路；不修改请求 DTO、扣费退款、SpacetimeDB schema 或成功路径多产物布局。
+- 验证方式：platform-image 覆盖大量独立 `4×4` 块、单像素噪点和 65 个有效输出；api-server 覆盖比例漂移、原图回读失败、截断透明 PNG、共享 source-only helper 无持久化副作用，以及三入口统一 bounded slicer。运行 `cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`、`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 check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+---
+
 ## 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 尺寸天然正确，不再经守卫。像素路径函数因此需要显式接收交付宽高。
-- 生效范围（不承诺超出这一范围）：本决策只保证像素路径不再谎报「尺寸无误」，即不再把 BgFilter 原始输出连同 `None` 尺寸错误交回调用方。拿到尺寸错误之后怎么处理仍由各调用方既有语义决定，本次不改变任何调用方语义：角色生成会据此走「改用已保存的同尺寸原图完成画布」的安全降级，因此角色链路闭环；图标图集沿用 master 既有的非致命语义，只记录告警后继续持久化并拆分，因此在「BgFilter 尺寸漂移且回贴修复失败」时，图标仍可能持久化尺寸异常的透明图集——该残留属于 master 既有行为，未在本次范围内解决。
+- 生效范围（由同日后续决策补齐）：像素路径继续保证不把 BgFilter 原始输出连同 `None` 尺寸错误交回调用方；角色、图标和 UI 拿到尺寸 / Alpha 错误后现已统一走 provider 原图 source-only 收口，不再持久化或拆分尺寸异常、比例异常或不可解码的透明图。
 - 影响范围：`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 图片生成风格使用可扩展字段并以纯内存像素规整首发」。

docs/project-memory/shared-memory/pitfalls.md

@@ -14,6 +14,22 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## 图集切片上限必须早于合并、裁剪和编码
+
+- 现象：透明图集含大量独立碎块或噪点时，接口长时间占用 async worker；最终即使报“超过 64 个切片”，此前仍已完成全量两两合并、裁剪和 PNG 编码。
+- 原因：原始连通域无上限，辅助部件合并全量扫描所有 pair，输出限制只在 platform slicer 返回后由 api-server 检查；UI 提取还绕过了该 wrapper。
+- 处理：platform slicer 对全部 flood-fill 连通域设置 `4096` 硬上限，用空间网格只查 `48px` 邻域候选；单网格最多 `256` 个组件、单 source 最多 `512` 个候选，避免拥挤网格重新退化为全量 pair。`maxOutputSlices` 在排序、裁剪和编码前拒绝。图标自动、手动和 UI 三入口统一在 2 路 semaphore 与 30 秒 / 请求 deadline 共同保护的 `spawn_blocking` 中执行，permit 留在 blocking 闭包直到 CPU 工作退出。
+- 验证：覆盖大量独立 `4×4` 块、超过上限的单像素噪点、65 个有效输出和既有高光 / 阴影合并样本；手动超限必须发生在首次持久化前，自动超限不得产生切片 PUT、资源或画布切片。
+- 关联：`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、`server-rs/crates/api-server/src/editor_project.rs`。
+
+## Alpha 恢复失败后不能继续持久化原始后处理图
+
+- 现象：BgFilter 返回比例漂移、损坏或低分辨率图片，provider 原图修复性回读又失败时，图标 / UI 仍可能落库透明图与切片，尺寸元数据甚至回退为 `512×512`。
+- 原因：Alpha helper 会同时返回原后处理字节和错误；角色调用方会 source-only 早退，图标 / UI 却只写日志后继续。相同尺寸快路径还只读图片 header，没有完整解码。
+- 处理：角色、图标、UI 共用 provider 原图 source-only helper；比例漂移超过 `5%`、原图回读、Alpha 回贴或透明图完整解码任一失败都立即返回原图、通用 warning、空切片和空 `sliceWarning`，禁止透明图 PUT、派生资源、拆分和透明 / 切片画布层。provider 原图尺寸必须完整解码取得，不得伪造兜底值。
+- 验证：覆盖错比例 Alpha、缺失 provider 原图、合法 PNG header 但截断正文；结构断言 source-only helper 不含任何透明持久化、切片或多图层完成调用。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 工具 JSON Schema 的条件约束必须覆盖运行时默认值
 
 - 现象：LLM 按工具 schema 生成的参数可以通过结构约束，但参数补默认值后被运行时校验拒绝，白白消耗一次工具修复轮次。例如固定 `gpt-image-2` 的 UI 工具仍暴露 `0.5K`，或视频调用省略 `model` 时 schema 允许 `1080p`，运行时却默认成 `seedance2.0-fast` 后拒绝。

docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md

@@ -85,6 +85,8 @@
 
 ## 后端接口
 
+- 角色、图标 spritesheet 与 UI 素材提取共用 provider 原图 source-only 收口：BgFilter 最终失败、Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败或透明图完整解码失败时，只把已保存 provider 原图作为唯一主图完成占位，以 `completed + warning` 收口且不退款；图标 / UI 固定 `iconImageSrcs=[]`、`sliceWarning=null`，不写透明图、不拆分，也不创建透明图或切片画布层。provider 原图本身无法完整解码时在首次持久化前失败，不得用 `512×512` 伪造元数据。图标自动拆分、手动拆分和 UI 提取共用有界 CPU helper：全部 flood-fill 原始连通域最多 `4096` 个，辅助部件合并使用空间网格邻近候选，`maxOutputSlices=64` 在排序、裁剪和 PNG 编码前检查；整段 CPU 工作由 2 路 semaphore、30 秒本地上限与请求 deadline 共同保护的 `spawn_blocking` 执行。自动超限保留可信透明整图、返回稳定 `sliceWarning` 且不写任何切片；手动超限在首次持久化前返回 `422`。
+
 - `GET /api/editor/projects/recent`：读取当前用户最近编辑的图片画布工程，没有则返回 `project: null`。
 - `GET /api/editor/projects`：读取当前用户所有图片画布工程，按更新时间倒序返回。
 - `POST /api/editor/projects`：创建图片画布工程。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -298,6 +298,8 @@ npm run check:server-rs-ddd
 - 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用。画布 Agent 来源的任务可在 `result_payload_json.editor-agent-tool-call-result` 中保存有界的轻量结果和已登记媒体引用，供后端按已有 `externalJobId + owner_user_id` 定向懒回填；其它编辑器任务保持元数据结果，并可保存有界的 `warning.code/reason`。其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行、受控维护以及画布 Agent 的定向结果回填读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得返回或解析这两个 payload。画布 Agent 懒回填必须经对应工具 formatter 归一为有界轻量媒体引用后写入 OSS 会话，不能把原始 payload 直接透传前端。
 - 非阻断告警：角色形象、图标图集和 UI 素材提取已保存 provider 原图、但透明背景处理最终失败时，以原图唯一主图完成任务；透明图和切片不写入画布。这个 source-only 降级只包住透明背景处理的最终失败，phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。图标 / UI 透明图集成功但自动拆分降级时仍保留透明图集；通用 `warning` 与 `sliceWarning` 只在「透明背景最终失败」这一条上互斥，风格归一化或像素规整产生的通用 `warning` 可与 `sliceWarning` 并存。两类成功降级都以既有 `completed` 状态收口，不新增状态值：source-only 的 inline / external v1 响应使用结构化 `warning.code/reason`，仅拆分失败的 inline / external v1 响应继续使用既有 `sliceWarning.code/reason`，其 `reason` 保留原始诊断；queue worker 才把两者归一为有界的 `result_payload_json.warning`：只有一条时原样保留完整 `reason`，两条并存时按“通用在前、拆分在后”拼接且 `code` 收敛为 `multiple-generation-warnings`（两条 `code` 相同则沿用原 `code`），不允许任何一条被丢弃；`sliceWarning.reason` 无论是否并存都由 worker 添加“图集已生成，但自动拆分未完成：”前缀，拼接结果最后统一做长度上界收敛。除上述画布 Agent 定向回填的轻量结果外，队列结果不保存图片、切片列表或媒体 URL。
 
+- 2026-07-29 收口补充：上条 source-only 的“透明背景处理最终失败”同时包含 Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败和透明图完整解码失败；三条链路共用 helper，只写已保存 provider 原图画布层，图标 / UI 固定 `iconImageSrcs=[]`、`sliceWarning=null`，不得写透明图、派生资源或切片。provider 原图本身解码失败时在首次持久化前失败，不允许 `512×512` 元数据兜底。图标自动拆分、手动拆分与 UI 提取共用受 2 路 semaphore、30 秒 / 请求 deadline 保护的 blocking helper；platform 对全部原始连通域设置 `4096` 硬上限、用空间网格查询邻近辅助候选，并在裁剪 / PNG 编码前执行 `maxOutputSlices=64`。自动超限只保留整张可信透明图并返回稳定 `sliceWarning`，不写切片；手动超限在首次持久化前返回 `422`。
+
 ### `external_generation_job_summary`
 
 - Rust 结构体：`ExternalGenerationJobSummary`

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

@@ -70,15 +70,15 @@
 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级，随后仍可进入原有自动拆分。
 - 逻辑低分辨率图只存在内存；snapper 在规整内部使用 nearest 恢复到当前 RGBA 输入尺寸，即前述平底 provider 原图的实际尺寸。图标链路不执行角色链路的前置 Lanczos 交付尺寸归一，nearest 也不是规整后的独立交付尺寸恢复。实现应复用 Alpha 回贴阶段读取的平底 provider 原图；必要时最多增加一次读取已有 provider 对象的 OSS GET，不得增加 OSS PUT。
 - 开启或关闭像素风格都保持现有 provider 原图、透明图集和实际成功切片的持久化与画布数量不变。禁止上传逻辑低分辨率图、像素化前后双份图集、预览或诊断图，也不新增 asset kind、项目资源、画布 item、任务类型或数据库字段。
-- 图标图集的 BgFilter `flat` 调用固定使用 `cross_check=on`，fallback、Alpha 回贴和默认关闭 despill 的行为保持不变。BgFilter 最终失败时沿用只保留 provider 原图且不拆分的既有收口，像素规整不运行；像素规整自身失败时保留已成功的透明图并继续上传和拆分，通过通用 `warning` 非致命提示，不退款。`sliceWarning` 继续只表达透明图成功后的自动拆分失败，可与风格归一化或像素规整产生的通用 `warning` 并存。
+- 图标图集的 BgFilter `flat` 调用固定使用 `cross_check=on`。BgFilter 最终失败、Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败或透明图完整解码失败时，都统一只保留 provider 原图且不拆分，像素规整不运行；像素规整自身失败但透明图仍通过完整解码和尺寸守卫时，才保留该透明图并继续上传和拆分，通过通用 `warning` 非致命提示，不退款。`sliceWarning` 继续只表达可信透明图成功后的自动拆分失败。
 
 ## 去背与保存
 
 - 父流程收到 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 / 资源 / 画布持久化仍全部由父流程负责。
+- 透明背景处理正常成功时，父流程把带背景原图和经完整解码 / 尺寸守卫验证的透明 spritesheet 写入 OSS、项目资源和账号素材库，再识别 alpha 连通域并执行附加拆分。BgFilter 最终失败或后续 Alpha / 尺寸恢复、原图回读、透明图完整解码失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`、`sliceWarning=null`。该收口不捕获 phase 上报、provider 原图持久化或 `canvasCompletion` 写回错误；provider 原图本身解码失败时在首次持久化前失败，不允许用 `512×512` 伪造元数据。
 - 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，因为透明背景失败时不会进入拆分，但可与风格归一化或像素规整产生的通用 `warning` 并存。前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
-- 响应通过 `iconImageSrcs` 返回成功切片素材。图标素材生成的自动拆分与手动 `拆分图集` 复用同一套全连通域识别、视觉阅读顺序和自动命名规则：识别多少个有效素材就返回多少个，依次命名为 `素材 N`；用户提示词及 `iconDescriptions` 数组长度都不控制切片数量。
-- 手动拆分调用 `POST /api/editor/icon-spritesheets/slices`，只允许读取当前用户项目中的 `icon-spritesheet` 资源，不调用图片生成 provider，不扣除泥点。自动拆分和手动拆分共同限制单边最多 `4096` 像素、总像素最多 `2048×2048`、单次最多持久化 `64` 个切片；超限在任何切片写入前拒绝。自动拆分失败以 `sliceWarning` 非阻断降级，手动拆分失败则返回接口错误。
+- 响应通过 `iconImageSrcs` 返回成功切片素材。图标自动拆分、手动 `拆分图集` 和 UI 提取复用同一个 bounded CPU helper 和 platform 实现：全部原始连通域（包括随后过滤的噪点）最多 `4096` 个，辅助部件通过 `64px` 空间网格只检查最大 `48px` 邻域候选；有效输出按视觉阅读顺序命名为 `素材 N`。
+- 三条拆分路径共同限制单边最多 `4096` 像素、总像素最多 `2048×2048`、最多 `64` 个输出；输出限制在排序、裁剪和 PNG 编码前检查。整段图片 CPU 工作在 2 路 semaphore、30 秒本地上限与请求 deadline 共同保护的 `spawn_blocking` 中执行，permit 由 blocking 闭包持有。自动拆分超限以稳定 `sliceWarning` 非阻断降级且不产生切片 PUT、资源或画布切片；手动拆分超限在首次持久化前返回 `422`。
 
 ## 前端铺放规则
 

server-rs/crates/api-server/src/editor_green_screen.rs

@@ -211,7 +211,10 @@ pub(crate) fn remove_editor_generated_green_screen_background(
 fn map_editor_green_screen_error(error: GeneratedAssetSheetError) -> AppError {
     let status = match error {
         GeneratedAssetSheetError::DecodeImage { .. } => StatusCode::BAD_GATEWAY,
-        GeneratedAssetSheetError::InvalidRequest { .. } => StatusCode::BAD_REQUEST,
+        GeneratedAssetSheetError::InvalidRequest { .. }
+        | GeneratedAssetSheetError::RawConnectedComponentLimitExceeded { .. }
+        | GeneratedAssetSheetError::OutputSliceLimitExceeded { .. }
+        | GeneratedAssetSheetError::MergeCandidateLimitExceeded { .. } => StatusCode::BAD_REQUEST,
         GeneratedAssetSheetError::EncodeImage { .. }
         | GeneratedAssetSheetError::BuildHttpClient { .. }
         | GeneratedAssetSheetError::Oss(_) => StatusCode::INTERNAL_SERVER_ERROR,

server-rs/crates/platform-image/src/generated_asset_sheets/error.rs

@@ -6,10 +6,30 @@ pub const GENERATED_ASSET_SHEET_PROVIDER: &str = "generated-asset-sheets";
 
 #[derive(Debug)]
 pub enum GeneratedAssetSheetError {
-    InvalidRequest { message: String },
-    DecodeImage { message: String },
-    EncodeImage { message: String },
-    BuildHttpClient { message: String },
+    InvalidRequest {
+        message: String,
+    },
+    RawConnectedComponentLimitExceeded {
+        component_count: usize,
+        max_component_count: usize,
+    },
+    OutputSliceLimitExceeded {
+        slice_count: usize,
+        max_slice_count: usize,
+    },
+    MergeCandidateLimitExceeded {
+        candidate_count: usize,
+        max_candidate_count: usize,
+    },
+    DecodeImage {
+        message: String,
+    },
+    EncodeImage {
+        message: String,
+    },
+    BuildHttpClient {
+        message: String,
+    },
     Oss(OssError),
 }
 
@@ -24,6 +44,24 @@ impl GeneratedAssetSheetError {
             | Self::DecodeImage { message }
             | Self::EncodeImage { message }
             | Self::BuildHttpClient { message } => message.clone(),
+            Self::RawConnectedComponentLimitExceeded {
+                component_count,
+                max_component_count,
+            } => format!(
+                "图标 spritesheet 原始连通域数量超过处理上限：{component_count}，最多允许 {max_component_count} 个。"
+            ),
+            Self::OutputSliceLimitExceeded {
+                slice_count,
+                max_slice_count,
+            } => format!(
+                "图标 spritesheet 识别出的素材数量超过输出上限：{slice_count}，最多允许 {max_slice_count} 个。"
+            ),
+            Self::MergeCandidateLimitExceeded {
+                candidate_count,
+                max_candidate_count,
+            } => format!(
+                "图标 spritesheet 局部连通域过于拥挤：{candidate_count}，单个邻域最多允许 {max_candidate_count} 个合并候选。"
+            ),
             Self::Oss(error) => error.to_string(),
         }
     }