diff --git a/T-211.-.md b/T-211.-.md new file mode 100644 index 0000000..e7c9613 --- /dev/null +++ b/T-211.-.md @@ -0,0 +1,104 @@ + +> 同步来源：[`docs/tasks/T-211.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-211.md) · commit `afc651f75a3a` + +--- +id: T-211 +title: 参考图召回与 SKU 颜色尺码 Top 5 回传 +phase: 2 +deps: + - T-207 + - T-210 +status: DONE +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/api.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/procurement/** + - android-buyer/app/src/main/java/com/roubao/autopilot/ui/screens/SearchProbeScreen.kt + - 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/procurement/** + - android-buyer/app/src/test/java/com/roubao/autopilot/vlm/** + - backend-api/internal/usecase/execution_result_service.go + - backend-api/internal/usecase/execution_result_service_test.go + - backend-api/internal/transport/httpapi/device_handlers_test.go +--- + +## 问题 / 背景 + +当前 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`，不点击购物车、订单或支付控件。 + +## 验收要点 + +- [x] 单元测试证明任务参考图是图片搜索的唯一输入，图片无效时不会启动拼多多。 +- [x] 单元测试覆盖颜色/尺码规范化、匹配/不匹配/未知、缺少硬约束和不足 5 个不凑数。 +- [x] 候选评估 prompt/schema 明确颜色和尺码硬约束；模型不能把未知规格判为通过。 +- [x] 后端收到的 AI 候选最多 5 个、ordinal 连续，包含逐项评估与推荐理由。 +- [x] Android 单元测试和 Debug 构建通过。 +- [x] PKG110、Android 16、拼多多 8.17.0 真机 smoke 能选择本任务参考图、进入图片 + 搜索结果并采集候选；记录 App/拼多多版本。 +- [x] 真机确认未进入购物车、订单确认、提交订单或支付页面；未知页、验证码、风控和 + 登录页仍安全停止。 + +## 边界 + +- 第一版只检查拼多多图片搜索返回的前 5 个有界候选，不宣称为全平台 Top 5。 +- 不实现跨平台检索、无界滚动、自动选择商品规格、加入购物车、提交订单或支付。 +- 不建设 T-208 的完整人工标签数据集，也不让后端配置或代理手机 VLM。 +- 拼多多 UI 不提供可验证商品链接或图片链接时，保留空字段和证据截图，不伪造 URL。 + +## 执行记录 + +- 2026-07-27：根据新需求登记任务；复用 T-207 候选批次接口，先实现 Android 图片 + 召回和 SKU 硬约束，不新增后端 AI 服务。 +- 2026-07-27：任务登记提交 `667a64f` 后开始实现。 +- 2026-07-27：实现任务参考 JPEG 严格校验、MediaStore 一次性图片、拼多多拍照搜索/ + 最近图片选择/图片结果页识别，并在流程结束或停止后删除临时图片。真机首次验证发现 + 相机结果页竞态和 `external_primary`/`external` URI 表示差异，修复后均增加回归覆盖。 +- 2026-07-27：新增 SKU 颜色/尺码确定性提取、候选 schema/prompt v2、逐项 + `MATCH/MISMATCH/UNKNOWN` 校验和 Top 5 策略；只回传分数、置信度和两个硬约束均通过 + 的 `0..5` 个候选，重新生成连续 ordinal。后端 schema v2 拒绝弱匹配、未知/缺失硬 + 约束和非首项推荐，schema v1 保持兼容。 +- 2026-07-27：`.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug --no-daemon` + 通过，20 个 suite 共 108 个测试、0 失败；`go test -count=1 ./...` 和 + `go vet ./...` 通过。 +- 2026-07-27：PKG110（Android 16/API 36）、肉包 `1.4.2 (7)`、拼多多 + `8.17.0 (81700)` 真机以后台测试任务完成参考图选择、图片结果页识别、4 个有界候选 + 详情和证据回传；后台审计值为 `PDD_IMAGE_SEARCH`，不足 5 个未凑数。测试任务随后 + 取消，临时图库图片已删除，全程未进入购物车、订单或支付。该 smoke 验证检索和回传 + 链路，不代表真实 VLM provider 的匹配质量。