补齐抠图参数透传与验收

修复flat自动识别门禁并严格校验模式和颜色保持旧请求幂等指纹并区分客户端抠图意图同步工具说明和Skill契约并补充定向测试记录真实BgFilter验证及本地数据库阻塞的待验收项
2026-09-16 22:06:08 +08:00
parent af9078cb97
commit 3ffd37236f
15 changed files with 464 additions and 79 deletions
@@ -0,0 +1,14 @@
+# 抠图模式联调验收实施计划
+
+依据：[里程碑](./【里程碑】抠图模式联调验收-2026-09-16.md)。
+
+1. 主站修复 worker 对 auto/省略的门禁、空值契约和旧指纹；补接口、队列与 worker 定向测试。
+2. 客户端独立核对 schema、参数校验、幂等意图、Skill 与契约说明。
+3. 串行请求真实 BgFilter，凭据仅在进程内读取，不输出或落库。
+4. 运行 cargo test 的 background_removal、bgfilter、OpenAPI 定向过滤，客户端定向测试；运行 doc-index、encoding、diff 检查。
+5. 尝试 npm run dev:api-server 与 healthz smoke；记录真实登录/全链路未验证项。
+6. 收敛证据到主规范，删除临时计划。
+
+检查点：先通过契约测试，再开展运行时核验；不因环境缺失修改生产配置。回滚仅限本次局部补丁。
+
+当前收口：主站及客户端修复和定向检查已执行，真实 BgFilter 四组成功及自动检测失败分支已验证；本地 API 启动被现有数据库连接配置阻塞。仅完整登录/队列/资源回写运行时证据尚待补齐，测试凭据和临时日志不得提交。
@@ -0,0 +1,14 @@
+# 抠图模式联调验收
+
+Version: 1
+Status: 自动化与真实上游验收已执行；完整主站链路待本地数据库恢复
+Date: 2026-09-16
+Parent Spec: ../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md
+
+交付：证明客户端、External v1、队列和 BgFilter 的模式/颜色契约一致；修正范围内缺漏。
+不做：401 专题、部署、主站前端变化、生成角色与图集自动选色行为变化、数据库 schema 修改。
+
+验收：旧请求 complex；flat 三种颜色输入贯通；非法组合入队前 400；幂等包含新意图并保留旧请求指纹；真实服务返回可解码透明 PNG；实际证据与未验证环境分开记录。
+依赖：既有方案及前五步代码。
+
+剩余门禁：当前本地 SpacetimeDB 连接拒绝，导致 api-server 启动恢复未就绪。环境恢复后，用 npm run dev:api-server 验证 healthz，再以真实登录客户端提交三种 flat 请求及旧 complex 请求，确认队列完成和资源回写。不得用直连 BgFilter 测试替代此门禁；完成后将结论回写主规范并删除本计划和实施计划。
@@ -2,6 +2,13 @@

 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+## 2026-09-16 抠图模式与背景色契约
+
+- External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
+- flat 的颜色允许 `auto`、`#RRGGBB` 或省略，自动识别完全由 BgFilter 负责。主站只校验、透传，不调用视觉模型选色；complex 携带颜色、非法值和空字符串在入队前拒绝。
+- 来源、名称、模式与颜色共同区分客户端请求意图；旧参数调用及旧 External 请求的幂等指纹须保持稳定。
+- 权威合同：[AGC 抠图模式与背景色透传](../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)。
+
 ## 2026-09-16 策划 Agent 工具执行退出项目级写锁并自动接续中断批次

 - 背景：策划 Agent 每个 `read_file` / `write_file` / `patch_file` 工具都在执行前竞争全局项目写锁，但同一会话已由 `.agent/design-agent/active.lock` 串行化，工具目标又限定在 `design_artifacts`；项目锁既不覆盖「工具 + 会话 checkpoint」事务，还把进程中断时的 `executing=true` 不确定窗口扩大到等锁与工具执行全程。真机项目出现 `pendingBatch.executing=true`、`function_call` 无配对 output、UI 只显示工作中且无错误的状态。