From 4b6df610af365aed29dbfd9340f0107023ab2222 Mon Sep 17 00:00:00 2001
From: Linghong <ink29535@proton.me>
Date: Wed, 16 Sep 2026 19:58:12 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85AGC=E6=8A=A0=E5=9B=BE?=
 =?UTF-8?q?=E6=A8=A1=E5=BC=8F=E9=80=8F=E4=BC=A0=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增主站与BgFilter模式及背景色契约

补充AGC客户端同步任务与兼容性规则

记录联调验收和发布回滚边界
---
 docs/README.md                                |  2 +
 ...��方案】AGC抠图模式与背景色透传-2026-09-16.md | 92 +++++++++++++++++++
 2 files changed, 94 insertions(+)
 create mode 100644 docs/technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md

diff --git a/docs/README.md b/docs/README.md
index 6450b77c5..244df1992 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -59,6 +59,8 @@
 
 ## 图片画布与媒体
 
+- [AGC 抠图模式与背景色透传方案](./technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)：External v1 与 AGC 客户端扩展 `flat`/`complex` 及 BgFilter `auto` 透传。
+
 - [共享基础组件库与展示页](./technical/【前端架构】共享基础组件库与展示页-2026-08-26.md)：网站与客户端复用的无业务 UI chrome、样式边界和 `/components` 展示页。
 - [Raw GPT Image 2 图片编辑代理](./technical/【技术方案】Raw GPT Image 2图片编辑代理-2026-09-07.md)：主站客户端调用的同步图片编辑代理、multipart 输入、预检查与计费边界。
 - [UI 编辑器自动切分素材工作流](./technical/【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md)：UI 设计图素材切分、Raw GPT Image 2 调用与结果持久化边界。
diff --git a/docs/technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md b/docs/technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md
new file mode 100644
index 000000000..754e8b005
--- /dev/null
+++ b/docs/technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md
@@ -0,0 +1,92 @@
+# AGC 抠图模式与背景色透传方案
+
+## 目标
+
+主站编辑器保持现有前端行为（继续使用 `complex`），同时扩展 External v1 抠图接口和 AGC 客户端，使客户端可以选择 `complex` / `flat`，并把 `screenColor` 原样交给 BgFilter。`auto` 的背景色识别完全由 BgFilter 负责，主站不读取图片、不调用模型决策颜色、不生成颜色兜底值。
+
+## 当前 BgFilter 契约
+
+生产服务器 `/root/BGfilter` 的服务契约为 `POST /remove-background` multipart：
+
+- `background_mode`：可选，`flat` 或 `complex`；
+- `screen_color`：可选，支持 `#RRGGBB`、`auto` 或省略；省略/`auto` 时由 BgFilter 从图片边框自动检测；
+- `complex` 模式忽略 `screen_color`；
+- 自动检测失败由 BgFilter 返回 400。
+
+主站向 BgFilter 发送 `#RRGGBB` 时保留 `#`，`auto` 也原样发送，不做所谓的“hex 转换”。
+
+## External v1 请求契约
+
+接口保持：
+
+```text
+POST /api/external/v1/editor/images/background-removals
+```
+
+新增可选字段：
+
+| 字段 | 取值 | 缺省/行为 |
+| --- | --- | --- |
+| `backgroundMode` | `complex`、`flat` | 不填按 `complex`，保证旧客户端兼容 |
+| `screenColor` | `auto` 或 `#RRGGBB` | 不填则不向 BgFilter 发送该字段 |
+
+组合规则：
+
+1. 不传新增字段：按 `complex` 执行。
+2. `complex` 不允许传 `screenColor`，返回 400。
+3. `flat` 可以传具体 `#RRGGBB`、`auto`，也可以省略颜色。
+4. 非法模式、非法颜色、空字符串颜色返回 400。
+5. 主站只做格式和组合校验；`auto` 不在主站解析，直接转发给 BgFilter。
+
+主站前端继续不传新增字段，因此用户行为不变。
+
+## AGC 客户端改动
+
+`agc_remove_background` 增加可选参数：
+
+```json
+{
+  "sourceLocalAssetId": "...",
+  "assetName": "...",
+  "backgroundMode": "flat",
+  "screenColor": "auto"
+}
+```
+
+客户端保留旧参数调用；新字段不填时不改变旧调用语义。客户端不读取图片、不自动选色、不把 `auto` 改写为具体颜色，使用原有 Bearer 认证、幂等键和队列返回模型。
+
+需要同步 `direct_tool_bridge.rs`、工具 manifest/schema、`agc-client-projection` 的 Skill/契约说明及客户端测试。
+
+## 实施任务
+
+### 任务一：冻结 BgFilter 契约
+
+记录服务器已支持的模式、颜色格式、自动检测和错误行为。不得把 SSH 地址、服务器凭据写入客户端或公开契约。
+
+### 任务二：更新主站 DTO 与 OpenAPI
+
+为 External v1 和内部任务 DTO 增加可选字段，更新 `docs/openapi/genarrative-external-v1.openapi.json`，写明默认值、组合约束和 400 响应。
+
+### 任务三：更新主站归一化与队列
+
+缺省模式归一化为 `complex`；`complex + screenColor` 拒绝；`flat` 允许颜色、省略或 `auto`。队列保存字段，worker 始终发送 `background_mode`，仅在调用方提供颜色时发送 `screen_color`，值原样透传。
+
+### 任务四：更新 AGC 客户端
+
+增加参数 schema、请求体字段和本地校验，更新 Skill、projection contract 与测试。旧客户端请求必须继续有效。
+
+### 任务五：联调与验收
+
+覆盖旧请求、`flat + auto`、`flat + #RRGGBB`、`flat` 不传颜色、`complex`、`complex + screenColor` 和非法值；使用真实 BgFilter 验证 multipart 字段及自动检测错误传播。
+
+## 依赖、发布与回滚
+
+先发布兼容的新主站，再发布支持新参数的 AGC 客户端。主站前端无需发布改动。若联调失败，客户端可回退为只传旧字段，主站仍按 `complex` 处理；主站回滚时不改变旧字段语义。
+
+## 验收证据
+
+- OpenAPI、Rust DTO、队列任务和客户端请求字段一致；
+- 旧客户端不传新增字段仍成功入队并使用 `complex`；
+- `auto` 未被主站改写，BgFilter 收到 `auto` 或未收到 `screen_color`；
+- 主站前端继续使用 `complex`；
+- 定向测试、`npm run check:doc-index`、`npm run check:encoding` 和 `git diff --check` 通过。