From 667a64f6c2e6af8a3eed2c2a4e48c2d9df429bc8 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 27 Jul 2026 17:46:17 +0800 Subject: [PATCH] docs(t211): define image-search SKU matching task --- docs/02-requirements.md | 16 ++++++--- docs/04-architecture.md | 22 +++++++++--- docs/tasks/T-211.md | 78 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 10 deletions(-) create mode 100644 docs/tasks/T-211.md diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 3235e9d..13f2970 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -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 集成已实现，但尚无真实模型质量证据。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index d011dd8..1373e70 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -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 导入工具生成的本地私有样本。 diff --git a/docs/tasks/T-211.md b/docs/tasks/T-211.md new file mode 100644 index 0000000..f2ae1c2 --- /dev/null +++ b/docs/tasks/T-211.md @@ -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 服务。