diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 42506a86f..bb68a0651 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -2893,3 +2893,11 @@
 - 处理：`applyGateTarget` 进入不存在的新 target 时必须重置为新建态：`enabled=false`、`rolloutPercent=0`、allow / deny 列表为空，并使用 target 默认描述。只有显式点已有 gate 才 `fillForm` 复制服务端规则。
 - 验证：`npm run test -- apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx`。
 - 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.test.tsx`。
+
+## 背景色决策喂 gpt-5-mini 的图不必按阿里云抠图那样归一化
+
+- 现象：担心带图背景色决策把源角色图原样 base64 塞给 gpt-5-mini（`resolve_media_source_as_data_url` 不做 resize / 字节上限），会像阿里云通用抠图那样因超尺寸 / 超体积被上游拒绝，于是想给决策链路也补一套图片归一化。
+- 原因：两条链路的上游限制完全不同。阿里云 SegmentCommonImage 有硬限制（≤3MB、分辨率 <2000×2000、最长边 ≤1999），必须归一化；而 gpt-5-mini（经 VectorEngine `/v1/responses`，Responses 协议 + `input_image`）对图片输入宽松得多，实测远超 App 真实源图范围仍全部 HTTP 200：纯色图到 5000×5000（隔离像素维度）正常识别；噪声图到 base64 请求体 34MB（隔离字节维度，PNG 25.8MB）仍成功返回。App 真实源角色图一般 ≤2048px、几 MB，稳落在安全区。
+- 处理：**不要**给 `resolve_editor_screen_background_color` 的带图路径加图片归一化——那是阿里云抠图链路（`platform-matting`）专属需求，两者别混。真要加保护也应放在字节 / 像素远高于当前实测通过档（如 base64 >40MB 或长边 >6000px）才截断，避免无谓重编码开销与画质损失。
+- 验证：探针脚本 `Myscripts/probe_gpt5mini_image_limits.py`（本地不入库，逐级放大纯色 / 噪声图打 `/v1/responses`，记录 HTTP 状态与响应）。2026-07-10 实测：solid 512²~5000² 全 200；noise 900²(4.1MB)~2600²(34.4MB) 全 200，无拒绝阈值出现在实用范围内。
+- 关联：`server-rs/crates/api-server/src/character_animation_assets.rs`（`resolve_media_source_as_data_url`）、`server-rs/crates/api-server/src/editor_screen_background_decision.rs`、`server-rs/crates/platform-matting/src/lib.rs`（对照：阿里云输入归一化）。