补充AGC抠图模式透传方案
新增主站与BgFilter模式及背景色契约 补充AGC客户端同步任务与兼容性规则 记录联调验收和发布回滚边界
This commit is contained in:
@@ -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 调用与结果持久化边界。
|
||||
|
||||
@@ -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` 通过。
|
||||
Reference in New Issue
Block a user