diff --git a/T-103.-.md b/T-103.-.md new file mode 100644 index 0000000..ce7303d --- /dev/null +++ b/T-103.-.md @@ -0,0 +1,150 @@ + +> 同步来源:[`docs/tasks/T-103.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/tasks/T-103.md) · commit `afc651f75a3a` + +--- +id: T-103 +title: 接入 VLM 需求提取 +phase: 1 +deps: + - T-004 + - T-101 +status: DONE +created: 2026-07-25 +context_ref: c25d63c +work_branch: main +write_paths: + - android-buyer/app/src/main/java/com/roubao/autopilot/MainActivity.kt + - android-buyer/app/src/main/java/com/roubao/autopilot/data/SettingsManager.kt + - android-buyer/app/src/main/java/com/roubao/autopilot/task/** + - 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/vlm/** + - docs/00-ai-start-here.md + - docs/02-requirements.md + - docs/03-tech-stack.md + - docs/04-architecture.md + - docs/05-coding-rules.md + - docs/api.md + - docs/current-state.md + - docs/tasks/T-103.md + - progress.md +--- + +## 问题 / 背景 + +T-004 已把本机私有蝦皮文本和 JPEG 严格导入为 `ProbeTask`,T-101 已证明固定搜索词 +可以进入拼多多结果页,但业务工作流尚不能从标题、SKU、数量和参考图得到受约束的 +搜索需求。T-103 只验证结构化需求提取,不让模型控制页面、不评估候选,也不提交订单。 + +## 关联需求与交互 + +- 功能:F-004 结构化需求提取、F-007 安全失败。 +- 用户故事:US-004、US-006。 +- 交互:Android“探针”页提供独立的需求提取入口,展示脱敏状态、SKU、数量、置信度、 + 警告和是否需要人工复核。 +- 架构:`ProbeTask` -> 隐私映射 -> `RequirementExtractor` -> provider-neutral gateway + -> 严格 schema -> 确定性硬约束复核。 + +## 方案 + +1. 建立与供应商无关的需求提取输入、输出、错误码和 JSON schema。 +2. VLM 请求只保留标题、SKU 和参考图;数量留在本地,订单号、店铺名及本机路径不 + 进入 prompt。 +3. SKU、数量和预算只从原始任务产生;模型响应无权覆盖。当前 `ProbeTask` 没有预算, + 输出固定为未知并产生警告。 +4. 严格校验图片大小、媒体类型和 SHA-256;严格解析模型 JSON,拒绝额外字段、坐标、 + 动作授权和格式不明输出。 +5. 置信度低于固定探针阈值或输出无效时进入人工复核,不扩大搜索或触发拼多多动作。 +6. 普通测试使用 Fake gateway;真实调用只通过用户已配置且声明支持需求提取的 + OpenAI 兼容供应商进行,每次用户操作最多发出一次模型调用。 + +## 验收要点 + +- [x] 私有样本标题、SKU、数量和 JPEG 可形成不含订单号、店铺名的 VLM 请求。 +- [x] 有效模型响应可解析为版本化 schema。 +- [x] SKU 和数量与原始 `ProbeTask` 完全一致,模型不能改写。 +- [x] 未提供预算时不会由模型猜测,并产生结构化警告。 +- [x] 低置信度、冲突、无效 JSON、额外动作字段和图片校验失败均安全转人工或明确失败。 +- [x] API Key、原图 Base64、订单号、店铺名和模型原始响应不进入普通日志。 +- [x] Fake gateway 测试覆盖成功、隐私、硬约束、低置信度和错误路径。 +- [x] `lintDebug test assembleDebug` 通过,默认 APK 不含私有 fixture。 +- [x] 设备无真实测试凭证;已记录外部 blocker,并用一次性本机 mock 验证真实 Android + 请求链路,不把 mock 结果当成模型效果证据。 + +## 边界 + +- 不让 VLM 输出或执行坐标、点击、状态迁移、下单或支付动作。 +- 不把候选截图交给模型;候选评估属于 T-104。 +- 不引入新的供应商 SDK;沿用现有 OpenAI 兼容客户端。 +- 不提交私有订单、图片、生成 fixture、API Key 或模型原始响应。 +- 不把技术探针的端上密钥路径当作正式架构;正式密钥仍由后端保管。 + +## 执行记录 + +### 2026-07-25:任务开始 + +- 基于 T-102 提交 `c25d63c` 开始。 +- 已确认现有 `VLMClient` 可复用 OpenAI 兼容多模态调用,但业务层缺少 schema、隐私 + 映射、确定性复核和低置信度处理。 +- 当前外部 blocker 仍是供应商、模型、测试凭证、成本上限和数据留存未确认;先完成 + provider-neutral 契约、Fake 测试和可配置真实探针,不使用默认付费调用。 + +### 2026-07-25:实现 + +- 新增 `RequirementExtractionInput/Result`、版本化最终 JSON、严格模型响应 parser 和 + `RequirementExtractor`。模型只能返回搜索词、类目、带来源属性、置信度和警告; + 额外字段、动作/坐标语义、格式或边界错误统一转人工。 +- 隐私映射只把标题、SKU 和参考图交给 gateway。订单号、店铺名、相对路径和数量不 + 进入 prompt;SKU、数量、空预算和图片 SHA-256 由确定性代码组装。 +- 固定探针阈值为 `0.75`;低于阈值以及图片歧义、标题/图片冲突或 SKU 不清晰均进入 + 人工复核,不触发拼多多动作。 +- 新增 `predictStructuredOnce`,每次按钮操作最多调用 provider 一次;禁用连接自动 + 重试和 HTTP/HTTPS 重定向,协程取消会取消底层 call,调用上限 75 秒。HTTP 错误不 + 读取响应正文,成功响应上限 64 KiB。 +- 远程端点只允许 HTTPS;无 API Key 的本机回环 HTTP 可用于受控 mock。标题和 SKU + 分别限制为 2048、512 个 UTF-8 字节。JPEG 在调用前复核媒体类型、20 MiB 上限、 + 魔数、大小和 SHA-256,按声明长度精确读取,解码后最长边限制为 2048 px。 +- `ApiProvider` 增加 `supportsRequirementExtraction`;GUI-Owl 和 MAI-UI 明确禁用。 + 加密凭证存储不可用时需求探针 fail closed。 +- “采购验证探针”增加独立 VLM 入口和 IDLE/RUNNING/READY/MANUAL_REVIEW/FAILED/ + STOPPED 状态;展示 schema 摘要,但不展示订单号、店铺名或图片路径。 + +### 2026-07-25:自动化验证 + +- `$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk";` + `$env:ANDROID_SDK_ROOT=$env:ANDROID_HOME;` + `.\gradlew.bat lintDebug test assembleDebug --no-daemon` 成功。 +- App Debug/Release、task contract 和导入器共 20 份报告、122 次测试,0 failure、 + 0 error、0 skipped;默认 Debug APK 中 `assets/probe-fixtures/` 条目数为 0。 +- Fake gateway 覆盖有效 schema、订单/店铺/路径/数量不进入 prompt、单次调用、 + 原始 SKU/数量保持、空预算、0.75 阈值边界、冲突转人工、无效/动作字段、JPEG + 魔数/哈希失败、输入长度、provider 失败、调用取消和安全端点策略。 +- 静态检查确认需求链路没有记录 prompt、图片字节或原始响应,也没有可执行动作输出。 + +### 2026-07-25:真机集成 smoke + +- OnePlus PKG110、Android 16/API 36、肉包 `1.4.2 (7)` 上显式注入 T-004 私有 + fixture;设备未配置真实 API Key,直接点击时稳定显示“未配置模型”且不发网络请求。 +- 为验证网络链路,临时选择自定义 provider,通过 `adb reverse` 连接一次性本机 + OpenAI 兼容 mock。App 只发出 1 次 `/v1/chat/completions` POST,包含 1 张 JPEG + data URL;布尔审计确认 prompt 不含订单/店铺字段和数量键。 +- mock 返回的严格 schema 以 `0.82` 置信度进入 READY;UI 显示类目、属性、原始 + SKU/数量、空预算和 `MAX_BUDGET_NOT_PROVIDED`。截图/XML 和 mock 布尔审计位于 + 被忽略的 `.local/`,请求正文和图片未落盘。 +- 最新 APK 再次 smoke 后,将 provider 恢复为无密钥的阿里云配置并重新触发;UI + 显示“未配置模型”,此前 READY 的搜索词和类目不再存在,证明失败路径会清空旧结果。 +- smoke 后已移除 `adb reverse`、停止本机 listener 并恢复设备原 API provider。 + logcat 未写入订单号、店铺名、标题、SKU、prompt、Base64 或原始响应。 + +### 未验证范围 + +- 没有可用的真实 VLM 测试凭证,因此未验证任何供应商的真实提取质量、时延和费用。 +- 真实供应商、模型、成本上限、数据留存地区和图片隐私规则仍是外部 blocker;启用 + 前必须由用户显式配置并确认,不得把本机 mock 结果计入 20 条业务试验。 + +## 后续 + +- T-104 读取 T-102 的受控候选证据和本任务的 `RequirementExtraction`,输出匹配项、 + 缺失项和拒绝原因,并停在人工确认点。 +- T-104 继续使用 Fake gateway 和本机 mock 验证集成;没有真实凭证时不能宣称候选 + 匹配质量已验证。