docs(t211): define image-search SKU matching task

2026-07-27 17:46:17 +08:00
parent 30841f8827
commit 667a64f6c2
3 changed files with 106 additions and 10 deletions
@@ -29,7 +29,7 @@
 | F-002 | 查看任务状态 | 管理员看到任务阶段、候选摘要、截图和失败原因。 | P0 | US-002 |
 | F-003 | 手动领取任务 | 空闲且就绪的 App 点击后只领取一条待处理任务。 | P0 | US-003 |
 | F-004 | 解析采购需求 | 系统从图片和文字提取搜索词、属性及约束，并保留原始输入。 | P0 | US-004 |
-| F-005 | 拼多多搜索与候选判断 | App 搜索并检查少量结果，得到一个候选或明确无匹配。 | P0 | US-004 |
+| F-005 | 参考图搜索与规格候选判断 | App 用参考图在拼多多召回商品，以 SKU 颜色/尺码硬约束检查最多 5 个结果，回传匹配候选或明确无匹配。 | P0 | US-004 |
 | F-006 | 人工确认停止点 | 自动化停在候选/订单确认位置，采购员确认结果或拒绝候选。 | P0 | US-005 |
 | F-007 | 结果与异常回传 | 管理员和采购员看到成功、失败、取消及可恢复建议。 | P0 | US-002、US-006 |
 | F-009 | 手机独立执行与 VLM | App 本地完成模型判断和自动化，后端只控制任务并接收结果。 | P0 | US-009 |
@@ -124,6 +124,9 @@ T-206/T-207 先跑通领取、执行、候选/证据和最小结果回传；T-20
    生效，恢复连接后必须在继续动作前同步。
 19. App 本地 VLM 配置不能来自任务 payload。后端不代理模型；端上 Key 必须加密存储，
    模型不可用时允许显式切换 `MANUAL_FIRST`，不能阻塞人工完成任务。
+20. 拼多多候选召回必须使用当前任务参考图；标题和 SKU 不能替代图片作为召回输入。
+    SKU 中可唯一识别的颜色、尺码是候选硬约束：任一不匹配或无法确认时不得进入自动
+    Top 5。回传可以少于 5 个，禁止用弱匹配凑数。

 ## 六、第一层本地样本约定

@@ -172,8 +175,9 @@ T-004 已固定首版规则：推荐私有目录为被 Git 忽略的 `private-fi
 - F-004/US-004/IX-006：解析结果包含搜索词、识别属性、预算、数量、置信度和警告；
  原始输入保留，硬约束与输入一致。T-103 已实现版本化 schema、0.75 置信阈值、
  冲突转人工以及 SKU/数量的本地确定性回填；当前样本未提供预算，因此预算保持空。
- F-005/US-004/IX-006：在已验证的拼多多版本上，App 能从任务进入搜索结果并检查
-  最多 5 个候选；T-104 已把需求搜索词、当前候选证据和严格评估 schema 绑定，
+- F-005/US-004/IX-006：在已验证的拼多多版本上，App 能把当前任务参考图作为图片
+  搜索输入，进入结果并检查最多 5 个候选；候选只有在原始 SKU 的颜色、尺码硬约束
+  均确认匹配时才能进入回传列表。匹配项按评估结果排序且最多 5 个，不足时不得凑数；
  无合理候选时明确结束而不是随意选择。
 - F-006/US-005/IX-007：流程到达人工确认点后停止；MVP 任意路径都不能触发最终
  提交订单或支付。T-104 的本地确认只允许标记建议候选可用或拒绝本次候选，
@@ -205,8 +209,8 @@ T-004 已固定首版规则：推荐私有目录为被 Git 忽略的 `private-fi
 | --- | --- |
 | 客户端形态 | 管理人员用 Web，采购人员用 Android App，共享统一后端。 |
 | 任务到达 | MVP 由 App 手动领取；后续通知只作唤醒/提示。 |
-| 搜索方式 | 先验证关键词搜索；拼多多原生以图搜图作为后续可选路径。 |
-| 搜索结果 | 最多检查前 5 个可见候选，避免无界遍历。 |
+| 搜索方式 | 正式候选召回使用当前任务参考图进入拼多多原生以图搜图；关键词只保留为开发诊断能力，不作为该业务链路的召回输入。 |
+| 搜索结果 | 最多检查图片搜索返回的前 5 个可见候选，以 SKU 颜色/尺码硬约束过滤后回传 `0..5` 个，避免无界遍历和凑数。 |
 | 下单边界 | MVP 停在候选或订单确认页，不提交订单、不支付。 |
 | 账号边界 | 验证版为 ADMIN 会话 + BUYER/预授权设备联合身份；完整人员 RBAC 后置。 |
 | 第一层任务输入 | 从本机私有蝦皮订单文件生成测试任务，不先建设 Go-Gin。 |
@@ -221,6 +225,8 @@ T-004 已固定首版规则：推荐私有目录为被 Git 忽略的 `private-fi
  样例和独立任务。
 - OnePlus PKG110、Android 16/API 36、拼多多 8.17.0 的首页、搜索输入、结果页、
  候选卡和详情返回已形成可复现基线；不同账号、类目和页面实验的差异仍是风险。
+- 拼多多 8.17.0 的图片搜索入口、相册选择页和图片结果页仍需在 T-211 建立真机结构
+  基线；UI 无法唯一确认当前任务图片时必须停止，不能选择“最近图片”后盲目继续。
 - VLM 需求提取的 provider-neutral 合约和 OpenAI 兼容适配器已实现；真实供应商、
  模型、测试凭证、成本上限、数据留存地区和图片隐私规则仍待确认。候选评估契约和
  本机 mock 集成已实现，但尚无真实模型质量证据。
@@ -114,8 +114,10 @@ evidence/            # 截图、步骤日志、脱敏和上传

 只负责两类能力：

-1. **需求提取**：参考图 + 标题 + SKU -> 搜索词、类目、属性、置信度、警告。
-2. **候选评估**：候选截图/文本 + 原始约束 -> 匹配项、缺失项、拒绝原因、建议分。
+1. **需求提取**：参考图 + 标题 + SKU -> 类目、属性、置信度、警告；搜索词只用于
+   诊断和人工模式，不替代正式链路的参考图召回。
+2. **候选评估**：候选详情截图/文本 + 原始约束 -> 颜色/尺码硬约束结果、匹配项、
+   缺失项、拒绝原因、建议分。

 正式数据流固定为 `Android App -> VLM Provider`。管理后端只下发原始任务并接收
 结构化结果，不保存/下发 provider 配置或 Key，也不实现 `/tasks/{id}/ai/*` 代理。
@@ -137,6 +139,8 @@ provider Key 从旧设置迁移到 Android Keystore 包装的加密存储；迁
 模型输出是不可信建议，必须通过 schema 和确定性校验：

 - `sku`、`quantity` 和 `max_budget` 使用原始任务值；数量和预算不进入模型 prompt。
+- 原始 SKU 可唯一提取的颜色、尺码由本地代码固定为硬约束。候选必须对每个硬约束
+  返回 `MATCH/MISMATCH/UNKNOWN`；只有全部为 `MATCH` 才能进入自动 Top 5。
 - 价格未知、超预算或关键属性无法确认时不能判为可接受。
 - T-103 探针阈值为 `0.75`；低于阈值或标题/图片冲突时进入人工处理，不自动扩大
  浏览范围。
@@ -179,15 +183,23 @@ prompt 前分别限制为 2048 和 512 个 UTF-8 字节。JPEG 在调用前复
 -> 规范化为 ProbeTask
 -> Android FixtureTaskSource
 -> 校验设备就绪
- -> 解析为固定/模型搜索词
- -> 打开拼多多并搜索
- -> 检查最多 5 个候选
+ -> 校验参考图并提取 SKU 颜色/尺码硬约束
+ -> 将一次执行专用参考图写入受控 MediaStore
+ -> 通过拼多多可见图片搜索入口选择该图
+ -> 检查图片结果页最多 5 个候选
+ -> 过滤并排序颜色/尺码均确认匹配的 0..5 个候选
 -> 到达候选详情或确认页
 -> 停止并记录结论
 ```

 该阶段不依赖后台，用于尽早判断 Android 自动化是否可行。

+图片搜索临时资产只保存匿名执行标识，不使用订单号或标题作为文件名。App 在写入前
+复核任务参考图的媒体类型、长度和 SHA-256，并在完成、失败或安全停止后 best-effort
+删除自己创建的媒体。拼多多图片入口、相册页、当前图片或结果页无法唯一确认时停止；
+不得从用户相册中猜选其他图片。图片搜索只负责召回，VLM 不能改变原始 SKU，也不能
+把 `UNKNOWN` 规格提升为通过。
+
 `TaskSource` 是工作流读取任务的唯一边界：

 - 第一层使用 `FixtureTaskSource`，消费 Debug 导入工具生成的本地私有样本。
@@ -0,0 +1,78 @@
+---
+id: T-211
+title: 参考图召回与 SKU 颜色尺码 Top 5 回传
+phase: 2
+deps:
+  - T-207
+  - T-210
+status: TODO
+created: 2026-07-27
+context_ref: 30841f8
+work_branch: null
+write_paths:
+  - docs/tasks/T-211.md
+  - docs/02-requirements.md
+  - docs/04-architecture.md
+  - docs/current-state.md
+  - android-buyer/app/src/main/AndroidManifest.xml
+  - android-buyer/app/src/main/java/com/roubao/autopilot/MainActivity.kt
+  - android-buyer/app/src/main/java/com/roubao/autopilot/accessibility/**
+  - android-buyer/app/src/main/java/com/roubao/autopilot/pinduoduo/**
+  - android-buyer/app/src/main/java/com/roubao/autopilot/vlm/**
+  - android-buyer/app/src/test/java/com/roubao/autopilot/pinduoduo/**
+  - android-buyer/app/src/test/java/com/roubao/autopilot/vlm/**
+---
+
+## 问题 / 背景
+
+当前 T-210 已能按文字搜索并采集拼多多前 5 个候选，但新业务规则要求以任务参考图
+作为拼多多召回输入，再使用原始 SKU 中的颜色、尺码核对结果。继续使用标题和 SKU
+拼接搜索词会偏离该规则，也无法区分“图片相似但规格不符”和“规格已确认匹配”。
+
+## 关联需求与交互
+
+- 功能：F-004、F-005、F-007、F-009。
+- 用户故事：US-004、US-005、US-006、US-009。
+- 交互：IX-006、IX-007、IX-008、IX-010。
+- 架构/API：`docs/04-architecture.md` 的 Android 自动化、VLM Gateway 和 execution
+  candidate batch；后端继续使用 T-207 的有界候选接口。
+
+## 方案
+
+1. App 复核当前任务参考图的类型、长度和 SHA-256，将其以一次执行专用的匿名文件
+   暂存到 Android MediaStore，再通过拼多多可见的“拍照搜索/相册”入口选择该图片。
+   不接受其他相册图片；图片入口、相册页或结果页无法唯一确认时安全停止。
+2. 以图搜图只负责召回。原始 SKU 不由模型改写；本地先从 SKU 提取并规范化颜色和
+   尺码硬约束，无法唯一提取时转人工，不猜测。
+3. 复用当前最多 5 个详情截图的有界采集。候选评估必须分别返回颜色和尺码的
+   `MATCH/MISMATCH/UNKNOWN`。只有任务要求的所有硬约束均为 `MATCH`，且现有分数和
+   置信度门槛也通过的候选，才能进入回传 Top 5。
+4. 回传数量为 `0..5`，按评估分、置信度、原始曝光顺序排序并重新生成连续 ordinal；
+   匹配不足 5 个不得用弱匹配或未知项凑数。后端沿用 T-207 candidate batch 保存候选、
+   评估理由、推荐和证据，不增加 VLM 代理。
+5. 临时图库图片在流程结束或安全停止后 best-effort 删除。任意路径保持
+   `order_submitted=false`，不点击购物车、订单或支付控件。
+
+## 验收要点
+
+- [ ] 单元测试证明任务参考图是图片搜索的唯一输入，图片无效时不会启动拼多多。
+- [ ] 单元测试覆盖颜色/尺码规范化、匹配/不匹配/未知、缺少硬约束和不足 5 个不凑数。
+- [ ] 候选评估 prompt/schema 明确颜色和尺码硬约束；模型不能把未知规格判为通过。
+- [ ] 后端收到的 AI 候选最多 5 个、ordinal 连续，包含逐项评估与推荐理由。
+- [ ] Android 单元测试和 Debug 构建通过。
+- [ ] PKG110、Android 16、拼多多 8.17.0 真机 smoke 能选择本任务参考图、进入图片
+  搜索结果并采集候选；记录 App/拼多多版本。
+- [ ] 真机确认未进入购物车、订单确认、提交订单或支付页面；未知页、验证码、风控和
+  登录页仍安全停止。
+
+## 边界
+
+- 第一版只检查拼多多图片搜索返回的前 5 个有界候选，不宣称为全平台 Top 5。
+- 不实现跨平台检索、无界滚动、自动选择商品规格、加入购物车、提交订单或支付。
+- 不建设 T-208 的完整人工标签数据集，也不让后端配置或代理手机 VLM。
+- 拼多多 UI 不提供可验证商品链接或图片链接时，保留空字段和证据截图，不伪造 URL。
+
+## 执行记录
+
+- 2026-07-27：根据新需求登记任务；复用 T-207 候选批次接口，先实现 Android 图片
+  召回和 SKU 硬约束，不新增后端 AI 服务。