cmroubao/docs/tasks/T-103.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-103	接入 VLM 需求提取	1	T-004 T-101	DONE	2026-07-25	c25d63c	main	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 兼容供应商进行，每次用户操作最多发出一次模型调用。

验收要点

• 私有样本标题、SKU、数量和 JPEG 可形成不含订单号、店铺名的 VLM 请求。
• 有效模型响应可解析为版本化 schema。
• SKU 和数量与原始 ProbeTask 完全一致，模型不能改写。
• 未提供预算时不会由模型猜测，并产生结构化警告。
• 低置信度、冲突、无效 JSON、额外动作字段和图片校验失败均安全转人工或明确失败。
• API Key、原图 Base64、订单号、店铺名和模型原始响应不进入普通日志。
• Fake gateway 测试覆盖成功、隐私、硬约束、低置信度和错误路径。
• lintDebug test assembleDebug 通过，默认 APK 不含私有 fixture。
• 设备无真实测试凭证；已记录外部 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 验证集成；没有真实凭证时不能宣称候选 匹配质量已验证。