docs(tasks): define app and backend VLM integration
This commit is contained in:
QiuSW
@@ -58,6 +58,9 @@
|
||||
`HttpTaskSource`、前台服务和已确认的任务页面接到设备 API。
|
||||
候选优化数据集已经登记为 T-208；不得跳过 T-206/T-207 的第一版端到端闭环，提前
|
||||
建设报表、训练管线或外部商品抓取。
|
||||
生产采购 App 只连接肉包后端；T-207 由 ADMIN 在管理 Web 配置 OpenAI 兼容 VLM，
|
||||
后端代理调用且供应商 API Key 永不下发手机。Roubao 原有端上 provider 设置不能用于
|
||||
后端采购任务。
|
||||
|
||||
严格按以下顺序推进：
|
||||
|
||||
|
||||
@@ -32,6 +32,22 @@
|
||||
| F-005 | 拼多多搜索与候选判断 | App 搜索并检查少量结果，得到一个候选或明确无匹配。 | P0 | US-004 |
|
||||
| F-006 | 人工确认停止点 | 自动化停在候选/订单确认位置，采购员确认结果或拒绝候选。 | P0 | US-005 |
|
||||
| F-007 | 结果与异常回传 | 管理员和采购员看到成功、失败、取消及可恢复建议。 | P0 | US-002、US-006 |
|
||||
| F-009 | 集中配置 VLM 服务 | 管理员配置 OpenAI 兼容服务，App 经后端使用且不持有供应商密钥。 | P0 | US-009 |
|
||||
|
||||
### F-009 集中配置 VLM 服务
|
||||
|
||||
1. 正式采购链路固定为 `Android App -> 肉包后端 -> VLM Provider`。采购执行员不能
|
||||
在 App 选择或修改 provider、Base URL、model、prompt、超时、重试或 API Key。
|
||||
2. ADMIN 在管理 Web 配置 OpenAI 兼容服务；第一版只支持
|
||||
`/v1/chat/completions` 多模态协议和一个供新 execution 使用的默认 provider。
|
||||
3. API Key 只写不读，使用后端环境 master key 加密落库；明文不得出现在 HTML、
|
||||
JSON、日志、事件、崩溃报告、Android 存储或 Git。
|
||||
4. 配置更新创建版本。execution 首次调用时绑定 provider/model/config/prompt
|
||||
版本，后续调用不能因管理员修改默认配置而漂移。
|
||||
5. 远程服务必须使用 HTTPS；后端阻断重定向、私网/本机/链路本地/metadata 目标和
|
||||
DNS rebinding。Debug 本机无 Key mock 与生产配置隔离。
|
||||
6. App 只能看到肉包后端返回的 AI 可用/不可用状态和结构化结果，不能获得供应商
|
||||
地址、密钥或原始响应正文。
|
||||
|
||||
## 四、后续迭代
|
||||
|
||||
|
||||
+24
-4
@@ -115,6 +115,23 @@ evidence/ # 截图、步骤日志、脱敏和上传
|
||||
1. **需求提取**：参考图 + 标题 + SKU -> 搜索词、类目、属性、置信度、警告。
|
||||
2. **候选评估**：候选截图/文本 + 原始约束 -> 匹配项、缺失项、拒绝原因、建议分。
|
||||
|
||||
正式数据流固定为 `Android App -> 肉包后端 -> VLM Provider`。生产采购 App 不选择
|
||||
provider、不保存供应商 API Key，也不直连模型地址；它只调用 task-scoped AI API。
|
||||
ADMIN 在管理 Web 维护一个供新 execution 使用的默认 OpenAI 兼容 provider 版本。
|
||||
第一版只支持 `/v1/chat/completions` 多模态协议。
|
||||
|
||||
provider 配置采用追加版本：保存名称、HTTPS Base URL、model、timeout、retry 上限、
|
||||
启用状态和非秘密审计字段。API Key 使用环境提供的 256 bit master key，通过 AEAD
|
||||
随机 nonce 加密；AAD 绑定 provider/version。读取接口只返回 `has_secret`，永不返回
|
||||
明文或密文。execution 在第一次 AI 调用时绑定 config/provider/model/prompt version，
|
||||
后续调用不随默认配置变化。master key 缺失或解密失败时真实调用安全失败，但管理任务、
|
||||
领取和非 AI 功能继续可用。
|
||||
|
||||
后端 provider transport 禁止重定向，并在解析和连接时阻断 loopback、私网、链路
|
||||
本地、组播、云 metadata 和 DNS rebinding；生产只允许 HTTPS。无 Key 的 loopback
|
||||
HTTP 只属于显式 Debug mock，不能从生产管理 Web 创建。连接测试只使用内置脱敏文字
|
||||
和测试图片，不读取订单或任务资产。
|
||||
|
||||
模型输出是不可信建议，必须通过 schema 和确定性校验：
|
||||
|
||||
- `sku`、`quantity` 和 `max_budget` 使用原始任务值；数量和预算不进入模型 prompt。
|
||||
@@ -137,12 +154,15 @@ T-103 的模型响应只允许
|
||||
输出并转人工。最终领域结果再由确定性代码补回原 SKU、数量、空预算、人工复核原因和
|
||||
`provider/model/prompt_version/reference_image_sha256`。
|
||||
|
||||
技术探针每次点击最多发出一次 VLM 请求，不沿用通用 Agent 的重试循环。该结构化
|
||||
HTTP 客户端关闭连接自动重试、HTTP/HTTPS 重定向，整体调用超时为 75 秒；协程取消
|
||||
技术探针每次点击最多发出一次 VLM 请求，不沿用通用 Agent 的重试循环。T-207 后端
|
||||
默认不重试，管理员最多允许一次仅限确定未收到响应的临时网络失败；schema、4xx 和
|
||||
安全错误绝不重试。该结构化 HTTP 客户端关闭连接自动重试和 HTTP/HTTPS 重定向，
|
||||
整体调用超时为 75 秒；协程取消
|
||||
会取消底层 HTTP call，成功响应正文上限为 64 KiB，非成功响应不读取正文。
|
||||
|
||||
远程 provider 只允许 HTTPS；HTTP 仅允许无 API Key 的 `localhost`、`127.0.0.1`
|
||||
或 `::1` 本机 mock。端点不得包含 userinfo、query 或 fragment。标题和 SKU 在进入
|
||||
远程 provider 只允许 HTTPS；HTTP 仅允许 Debug 下无 API Key 的 `localhost`、
|
||||
`127.0.0.1` 或 `::1` 本机 mock。端点不得包含 userinfo、query 或 fragment。标题
|
||||
和 SKU 在进入
|
||||
prompt 前分别限制为 2048 和 512 个 UTF-8 字节。JPEG 在调用前复核媒体类型、20 MiB
|
||||
上限、魔数和 SHA-256，按声明长度一次分配并精确读取，Android 解码后最长边限制为
|
||||
2048 px。请求和响应正文、Base64、API Key 不写普通日志；加密密钥存储不可用且存在
|
||||
|
||||
@@ -116,7 +116,13 @@
|
||||
|
||||
## 7. 安全与隐私
|
||||
|
||||
- 密钥只来自环境变量或被忽略的本地配置。
|
||||
- 通用密钥只来自环境变量或被忽略的本地配置。T-207 的 provider API Key 是唯一
|
||||
例外：只能由 ADMIN write-only 写入，使用环境 master key + AEAD 随机 nonce
|
||||
加密落库；读取接口、HTML、日志、事件、错误和 App 永不返回明文或密文。
|
||||
- 生产采购 App 只调用肉包后端，不保存或直连 VLM provider。Debug 本机 mock 必须
|
||||
位于 Debug source set，配置被 Git 忽略且不得进入 Release APK。
|
||||
- provider HTTP transport 必须禁用重定向，并在解析和连接阶段阻断私网、本机、
|
||||
链路本地、组播、metadata 与 DNS rebinding；生产远程目标只允许 HTTPS。
|
||||
- 真实蝦皮订单文本、参考图及其规范化生成物只能位于仓库外或 `.local/`、
|
||||
`private-fixtures/` 等被忽略目录；测试使用脱敏 fixture。
|
||||
- 普通日志不得输出完整蝦皮订单号、店铺名或本机原图绝对路径。
|
||||
|
||||
+2
-2
@@ -38,8 +38,8 @@
|
||||
| T-203 | 实现任务创建 API 与管理 Web | T-201、T-202 | 合法任务进入 PENDING；校验、列表和详情状态可见 |
|
||||
| T-204 | 实现用户/设备最小鉴权 | T-201、T-202 | 管理会话和设备令牌隔离；未授权访问被拒绝；无明文凭证 |
|
||||
| T-205 | 实现原子 claim、租约和状态机 | T-203、T-204 | 并发领取不重复；非法迁移、过期租约和错误设备被拒绝 |
|
||||
| T-206 | App 接入手动领取和执行进度 | T-202、T-205 | 用户点击后领取一条；前台服务显示步骤；取消安全停止 |
|
||||
| T-207 | 接入候选、事件和截图回传 | T-206 | 幂等回传；管理详情可查看；资源访问受鉴权保护 |
|
||||
| T-206 | App 接入手动领取和执行进度 | T-202、T-205 | 用户点击后领取一条；前台服务显示步骤；生产 App 只连接肉包后端；取消安全停止 |
|
||||
| T-207 | 接入后端 VLM、候选、事件和结果回传 | T-206 | ADMIN 配置 OpenAI 兼容服务；密钥不下发 App；幂等回传且管理详情可审计 |
|
||||
| T-208 | 建立候选决策数据与人工理由闭环 | T-207 | 观测/预测/推荐/人工标签分离；逐候选结构化理由；截图受控留存；不阻塞第一版流程 |
|
||||
|
||||
## Phase 3：端到端验证
|
||||
|
||||
@@ -15,6 +15,7 @@
|
||||
| US-006 | 看懂失败并安全恢复 | P0 | 采购执行员、采购管理员 | 知道失败位置和下一步，避免重复操作 | F-007 | IX-008 | 已定 |
|
||||
| US-007 | 建立受控会话和设备身份 | P0 | 采购管理员、采购执行员 | 未授权人员和设备不能接触任务 | F-001、F-003 | IX-001、IX-004 | 已定 |
|
||||
| US-008 | 积累可信的候选决策样本 | P1 | 采购执行员、优化人员 | 用真实曝光和人工理由评估并改进模型 | F-008 | IX-009 | 已定，T-208 后置 |
|
||||
| US-009 | 集中管理 VLM 服务 | P0 | 采购管理员 | 安全切换兼容服务而不向采购手机分发密钥 | F-009 | IX-010 | 已定，T-207 |
|
||||
|
||||
## US-001 创建清晰的采购任务
|
||||
|
||||
@@ -181,6 +182,28 @@
|
||||
4. 人工修正保留旧版本、actor 和时间；离线指标只使用当前有效人工 review。
|
||||
5. 外链失效后，授权人员仍能读取保留期内的受控截图证据。
|
||||
|
||||
## US-009 集中管理 VLM 服务
|
||||
|
||||
- 关联页面：管理 Web `/settings/vlm`；Android 设置页只显示后端 AI 状态。
|
||||
- 前置条件：管理员已登录；后端已配置加密 master key。
|
||||
|
||||
作为采购管理员，我想在后端配置 OpenAI 兼容的 VLM 服务，从而可以统一切换模型、
|
||||
控制调用和审计 provenance，而不需要采购员在每台手机保存供应商 API Key。
|
||||
|
||||
**范围**
|
||||
|
||||
- 包含：服务名称、HTTPS Base URL、模型、Chat Completions 协议、超时、有限重试、
|
||||
启用/默认版本、write-only API Key、脱敏连接测试和配置审计。
|
||||
- 不包含：采购员按任务选择模型、多 provider 自动路由、供应商私有协议、费用报表。
|
||||
|
||||
**验收场景**
|
||||
|
||||
1. ADMIN 保存合法配置后，新 execution 使用该版本；修改默认配置不改变已绑定任务。
|
||||
2. Key 保存后页面只显示“已配置”，留空更新保留原 Key，显式替换才产生新密文版本。
|
||||
3. 非 ADMIN 无法查看或修改配置；任何响应和日志都不包含 Key 或供应商原始正文。
|
||||
4. 非 HTTPS、重定向和私网/本机/metadata 目标被拒绝；连接测试使用内置脱敏样本。
|
||||
5. App 只显示后端 AI 可用状态，不能看到或覆盖 provider、模型、地址和 Key。
|
||||
|
||||
## 待确认
|
||||
|
||||
- 密码重置流程后置；T-204 使用本地 `authctl` 显式创建种子 ADMIN/BUYER 和预授权
|
||||
|
||||
@@ -16,6 +16,7 @@
|
||||
| IX-007 | US-005 | App 候选确认 | 接受/拒绝/转人工 | 停止自动化并回传人员结论 | P0 | 已定 |
|
||||
| IX-008 | US-006 | App/管理端错误状态 | 自动失败、取消、重试上传 | 显示结构化原因和恢复动作 | P0 | 已定 |
|
||||
| IX-009 | US-008 | App 候选理由/管理端决策详情 | 接受、拒绝、改选或修正 | 保存逐候选结构化人工标签 | P1 | 已定，T-208 后置 |
|
||||
| IX-010 | US-009 | 管理 Web VLM 设置 | 保存、测试或启用配置版本 | 后端代理模型且密钥不下发 App | P0 | 已定，T-207 |
|
||||
|
||||
## IX-001 管理 Web 登录
|
||||
|
||||
@@ -278,6 +279,38 @@
|
||||
- 理由使用 checkbox/radio 和明确 label，不依赖颜色；主要理由可用单选控件指定。
|
||||
- 批量应用前显示候选数量和标题摘要，默认不选中。
|
||||
|
||||
## IX-010 管理 VLM 服务
|
||||
|
||||
- 页面：管理 Web `/settings/vlm`；Android 设置页只读显示后端 AI 状态。
|
||||
- 角色：采购管理员。
|
||||
- 前置条件：后端加密 master key 已配置。
|
||||
- 服务依赖：T-207 provider 配置、加密存储、安全 HTTP transport 和连接测试。
|
||||
|
||||
**正常路径**
|
||||
|
||||
1. ADMIN 填写服务名称、HTTPS Base URL、模型、超时和重试上限，选择
|
||||
`/v1/chat/completions`，输入 write-only API Key。
|
||||
2. 保存前显示非秘密配置摘要；提交成功创建不可变新版本，并可设为新 execution 的
|
||||
默认版本。
|
||||
3. “测试连接”使用内置脱敏文字和测试图片，不读取或发送任何采购任务。
|
||||
4. 页面显示当前默认版本、启用状态、最近测试时间和稳定结果，不显示 Key。
|
||||
|
||||
**状态与异常**
|
||||
|
||||
- Key 字段始终为空；已有 Key 只显示“已配置”。留空表示沿用，替换必须明确确认。
|
||||
- master key 缺失时禁止保存含 Key 的配置和测试真实服务，但不阻塞任务管理页面。
|
||||
- URL 非 HTTPS、指向受限网络、发生重定向/DNS rebinding 或模型字段非法时在字段
|
||||
附近提示，不发出供应商请求。
|
||||
- 超时、鉴权失败、限流和 schema 不兼容显示稳定分类和 request ID；供应商响应正文
|
||||
只进入受控诊断且默认不持久化。
|
||||
- 非 ADMIN 返回拒绝且不泄露配置是否存在；所有 POST 使用 CSRF 和防重复提交。
|
||||
|
||||
**App 边界**
|
||||
|
||||
- App 只显示“后端 AI 可用/不可用”和可操作建议，不显示 provider 名称、模型、
|
||||
Base URL、Key 或选择控件。
|
||||
- Release App 不保留可用于后端任务的端上 provider 配置；Debug mock 与生产隔离。
|
||||
|
||||
## 通用交互约束
|
||||
|
||||
- Web 和 App 的所有提交都防重复，网络超时后以服务端状态为准。
|
||||
|
||||
+10
@@ -409,6 +409,16 @@ execution、清除 claim 秘密并追加带用户/设备 actor 的事件。同 k
|
||||
|
||||
## AI 合约
|
||||
|
||||
生产 App 不接收 provider、Base URL、model、timeout、retry 或 API Key，也不能通过
|
||||
AI 请求覆盖这些字段。后端在 execution 第一次 AI 调用时绑定 ADMIN 配置的默认
|
||||
provider version，后续调用使用同一 provenance。管理 Web 的 `/settings/vlm` 使用
|
||||
ADMIN session + CSRF 管理追加配置版本；Key 是 write-only，任何 GET/HTML/JSON 均
|
||||
只返回 `has_secret`。连接测试使用内置脱敏样本，不读取任务内容。
|
||||
|
||||
第一版 provider adapter 只支持 OpenAI 兼容 `/v1/chat/completions` 多模态请求。
|
||||
远程地址必须是受 SSRF/DNS rebinding 防护的 HTTPS 端点且不跟随重定向。App 看到的
|
||||
错误只包含稳定 code、可读 message 和 request ID，不包含供应商正文。
|
||||
|
||||
### `POST /api/v1/tasks/{task_id}/ai/extract-requirements`
|
||||
|
||||
只允许当前 execution 调用。后端从任务读取原始图片和文字，客户端不能替换硬约束。
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 当前快照
|
||||
|
||||
- 日期：2026-07-26
|
||||
- 日期：2026-07-27
|
||||
- 阶段：T-205 原子领取、租约和状态机完成，下一步 T-206
|
||||
- Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-205
|
||||
均已纳入 Git 历史；T-205 提交为 `ce875af`
|
||||
@@ -43,6 +43,9 @@
|
||||
SKU/数量由本地原值回填，预算保持空，订单提交状态固定为 false
|
||||
- 后置数据闭环：已登记 T-208，在第一版 T-206/T-207 跑通后分离保存候选观测、
|
||||
模型预测、确定性推荐和人工标签；人工接受/拒绝使用结构化理由，20 条试验依赖它
|
||||
- VLM 部署决策：生产采购 App 只连接肉包后端；T-207 由 ADMIN 配置版本化的
|
||||
OpenAI 兼容 `/v1/chat/completions` 服务，Key 在后端加密且永不下发 App；
|
||||
Debug 本机 mock 继续与 Release 隔离
|
||||
- 测试设备：OnePlus PKG110，Android 16/API 36；肉包 `1.4.2 (7)`；拼多多
|
||||
`8.17.0 (81700)`
|
||||
- 设备就绪：肉包采购无障碍已启用并连接；拼多多首页、搜索输入、固定词结果页、
|
||||
@@ -52,7 +55,7 @@
|
||||
已用 CLI 真实导入并逐字段/图片哈希验证，生成物位于被忽略的 `.local/`
|
||||
- 标准启动路径：`$env:RUN_START_COMMAND="1"; .\init.ps1`
|
||||
- 标准验证路径：`.\init.ps1`
|
||||
- 当前 blocker：真实 VLM 供应商、模型、测试凭证、成本上限和数据留存尚未确认；
|
||||
- 当前 blocker：真实 VLM 服务地址、模型、测试凭证、成本上限和数据留存尚未确认；
|
||||
当前只支持单 SKU/JPEG；候选探针截图要求 Android 11/API 30+
|
||||
|
||||
## 当前目录
|
||||
@@ -74,6 +77,8 @@
|
||||
| `docs/tasks/T-203.md` | DONE | 图片/任务 API、SQLite 业务层和 SSR 管理 Web |
|
||||
| `docs/tasks/T-204.md` | DONE | 用户、管理会话和预授权设备联合身份 |
|
||||
| `docs/tasks/T-205.md` | DONE | 原子 claim、租约、execution 和取消安全确认 |
|
||||
| `docs/tasks/T-206.md` | TODO | App 登录、手动领取、前台执行进度和安全停止 |
|
||||
| `docs/tasks/T-207.md` | TODO | 后端 VLM 配置/代理、候选、事件、截图和结果回传 |
|
||||
| `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 |
|
||||
| `deepseek总结.txt` | 已有 | 历史讨论摘要，不是正式需求权威 |
|
||||
| `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 |
|
||||
|
||||
+6
-2
@@ -11,9 +11,11 @@ T-202 的离线 P0 页面入口见[原型索引](design/index.html)。原型仅
|
||||
| `/tasks` | 任务列表 | 查看状态、筛选并进入详情 | US-002 | IX-003 |
|
||||
| `/tasks/new` | 新建任务 | 提交图片和采购约束 | US-001 | IX-002 |
|
||||
| `/tasks/{id}` | 任务详情 | 查看原始输入、时间线、候选和证据 | US-002、US-006 | IX-003、IX-008 |
|
||||
| `/settings/vlm` | VLM 服务设置 | 配置和测试后端 OpenAI 兼容服务 | US-009 | IX-010 |
|
||||
|
||||
MVP 登录后默认进入 `/tasks`。未登录访问受保护页面时跳转 `/login` 并携带安全的
|
||||
站内返回路径；只接受 `/tasks` 及其本站子路径，拒绝绝对 URL、`//` 和反斜杠。
|
||||
站内返回路径；只接受 `/tasks`、`/settings/vlm` 及其本站子路径，拒绝绝对 URL、
|
||||
`//` 和反斜杠。
|
||||
不存在和无权限必须使用不同内部原因，但页面均不得泄露任务内容。
|
||||
|
||||
## Android 页面
|
||||
@@ -28,7 +30,7 @@ Android 导航名称是逻辑目的地，具体 Compose/Fragment 形式待接入
|
||||
| `task/{id}/running` | 任务执行 | 显示步骤、返回拼多多、安全停止 | US-004、US-006 | IX-006、IX-008 |
|
||||
| `task/{id}/confirm` | 候选确认 | 接受、拒绝、无匹配或转人工；T-208 增加逐候选结构化理由 | US-005、US-008 | IX-007、IX-009 |
|
||||
| `task/{id}/result` | 任务结果 | 查看终态和同步状态 | US-002、US-006 | IX-007、IX-008 |
|
||||
| `settings` | 设备设置 | 查看权限、版本、后端和模型连接状态 | US-003、US-007 | IX-004、IX-005 |
|
||||
| `settings` | 设备设置 | 查看权限、版本、后端和只读 AI 可用状态 | US-003、US-007、US-009 | IX-004、IX-005、IX-010 |
|
||||
|
||||
## App 后端路由
|
||||
|
||||
@@ -56,6 +58,8 @@ release 和 cancel-ack 都必须匹配当前 `X-Claim-Token` 与 `claim_generati
|
||||
- 候选确认页返回不能恢复自动化。
|
||||
- 登录过期时先保存非敏感本地状态，再跳转登录；重新登录后查询服务端状态。
|
||||
- 设备设置不是首屏，任务主页是采购人员的工作入口。
|
||||
- 生产 App 的设置页不提供 VLM provider、模型、Base URL 或 API Key 控件；这些只由
|
||||
ADMIN 在管理 Web 配置。
|
||||
|
||||
## 页面组件边界
|
||||
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
id: T-206
|
||||
title: App 接入手动领取和执行进度
|
||||
phase: 2
|
||||
deps:
|
||||
- T-202
|
||||
- T-205
|
||||
status: TODO
|
||||
created: 2026-07-27
|
||||
context_ref: 45d4d11
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- README.md
|
||||
- android-buyer/**
|
||||
- backend-api/**
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/02-requirements.md
|
||||
- docs/04-architecture.md
|
||||
- docs/05-coding-rules.md
|
||||
- docs/07-user-stories.md
|
||||
- docs/08-interaction-checklist.md
|
||||
- docs/api.md
|
||||
- docs/current-state.md
|
||||
- docs/routes.md
|
||||
- docs/tasks/T-206.md
|
||||
- progress.md
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-205 已实现 BUYER + 设备联合鉴权、readiness heartbeat、原子 claim、任务参考图、
|
||||
start、租约 heartbeat、release 和取消确认，但当前 Android 仍只消费本地 fixture。
|
||||
管理员创建的 `PENDING` 任务无法在手机领取，真实端到端流程因此被阻塞。
|
||||
|
||||
现有 Roubao 基线包含端上模型服务商、Base URL 和 API Key 设置。正式采购工作流必须
|
||||
把模型调用收口到肉包后端，避免采购手机持有供应商密钥或由执行员改变模型策略。
|
||||
|
||||
## 关联需求与交互
|
||||
|
||||
- 功能：F-003、F-007、F-009。
|
||||
- 用户故事：US-003、US-006、US-007、US-009。
|
||||
- 交互：IX-004、IX-005、IX-006、IX-008、IX-010。
|
||||
- 架构/API：`HttpTaskSource`、设备联合身份、claim 租约状态机、前台服务和后端托管
|
||||
VLM 边界。
|
||||
|
||||
## 已定合约
|
||||
|
||||
1. 采购 App 只配置肉包后端 HTTPS 地址，不直接配置或调用 VLM 服务商。模型名称、
|
||||
Base URL 和 API Key 不进入生产采购页面、任务缓存、日志或网络响应。
|
||||
2. Debug 技术探针可保留本机直连 OpenAI 兼容 mock，但必须位于 Debug source set，
|
||||
不得进入 Release APK，也不得用于后端任务。
|
||||
3. BUYER 登录必须同时提交预授权 device ID/secret；access token、device secret、
|
||||
claim token 和幂等 key 使用 Android Keystore 支撑的安全存储。敏感值不进入
|
||||
SavedState、普通 SharedPreferences、崩溃报告或日志。
|
||||
4. App 每次领取前先发设备 heartbeat。无障碍未连接、拼多多未安装、网络不可用、
|
||||
服务端认为设备不就绪或已有活跃任务时不生成新的 claim 请求。
|
||||
5. claim token 和幂等 key 必须在请求前持久化；结果不确定时原样重放，不能生成新
|
||||
token。领取成功后下载 task-scoped 参考图并校验媒体类型、大小和解码结果。
|
||||
6. 用户在预览页确认后调用 start 并启动前台服务；运行中每 30 秒 heartbeat。服务端
|
||||
version、generation、execution 和租约是权威状态。
|
||||
7. T-206 先验证登录、领取、预览、start、前台步骤、续租、release、取消安全停止和
|
||||
进程恢复。真实后端 VLM、候选/截图/事件/结果回传属于 T-207。
|
||||
8. T-206 的执行进度使用 fake/受控步骤到达明确的“等待 T-207 AI 接入”结果，不把
|
||||
未上传的本地结果伪装成服务端完成，也不触发拼多多不可逆操作。
|
||||
|
||||
## 方案
|
||||
|
||||
1. 在 Android 增加严格的后端配置、认证 client、token 安全存储和稳定错误映射；
|
||||
Release 只接受 HTTPS，Debug 可显式信任开发证书或使用受控本机测试路径。
|
||||
2. 实现 `HttpTaskSource`，把 claim 响应和参考图规范化为现有 `ProbeTask`/领域输入，
|
||||
workflow 不判断任务来自 fixture 还是 HTTP。
|
||||
3. 按已确认原型接入登录、任务主页、任务预览、运行和结果状态；重复点击、空队列、
|
||||
登录过期、租约过期和服务端冲突都有稳定反馈。
|
||||
4. 使用前台服务持有当前 execution、定时 heartbeat 并轮询取消标志；取消只在
|
||||
workflow 安全检查点停止，再调用 `cancel-ack`。
|
||||
5. App 重启后先用 heartbeat/任务详情核对服务端活跃任务；不能证明可恢复时停止
|
||||
自动化并显示人工处理，不自行领取第二条任务。
|
||||
6. 后端如缺少 App 当前任务查询所需字段，只做兼容性最小补充，不改变 T-205 的
|
||||
token、幂等、租约和状态机语义。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- [ ] 预授权 BUYER 在真机登录成功，错误账号、错误设备、禁用和过期状态均不能进入
|
||||
任务页；敏感值不出现在日志和普通存储。
|
||||
- [ ] 真机 heartbeat 后点击“获取任务”能领取管理 Web 创建的一条 `PENDING` 任务，
|
||||
显示标题、SKU、数量、描述和参考图；无任务显示空状态。
|
||||
- [ ] 重复点击和模拟响应丢失不会重复领取；App 重启后能继续同一 `CLAIMED` 任务。
|
||||
- [ ] 预览可开始或释放；开始后前台服务显示步骤并按约 30 秒续租，不领取第二条任务。
|
||||
- [ ] 管理 Web 请求安全停止后，App 在安全检查点停止并确认，服务端最终为
|
||||
`CANCELED`；过期租约不会被 App 擅自续作。
|
||||
- [ ] 生产采购页面没有 VLM 服务商、Base URL 或 API Key 输入；后端任务不会读取
|
||||
Roubao 旧的端上 provider 配置；Release APK 不含 Debug mock 配置。
|
||||
- [ ] Android 单元/集成测试、后端回归测试、根 `init.ps1` 和 OnePlus PKG110
|
||||
Android 16 真机端到端 smoke 通过。
|
||||
|
||||
## 边界
|
||||
|
||||
- 不实现真实 VLM 代理、候选/截图/事件、complete/fail 和人工理由回传；属于 T-207。
|
||||
- 不实现后台推送、自动领取、自动下单、支付、多任务并行或跨设备调度。
|
||||
- 不允许生产 App 绕过后端直连任意模型地址，不提交真实账号、设备 secret 或订单。
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 尚未开始。
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
id: T-207
|
||||
title: 接入后端 VLM、候选、事件和结果回传
|
||||
phase: 2
|
||||
deps:
|
||||
- T-206
|
||||
status: TODO
|
||||
created: 2026-07-27
|
||||
context_ref: 45d4d11
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- README.md
|
||||
- android-buyer/**
|
||||
- backend-api/**
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/02-requirements.md
|
||||
- docs/04-architecture.md
|
||||
- docs/05-coding-rules.md
|
||||
- docs/07-user-stories.md
|
||||
- docs/08-interaction-checklist.md
|
||||
- docs/api.md
|
||||
- docs/current-state.md
|
||||
- docs/routes.md
|
||||
- docs/tasks/T-207.md
|
||||
- progress.md
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-206 跑通任务领取和执行生命周期后，App 仍不能安全使用真实 VLM，也不能把候选、
|
||||
步骤、截图、失败和人工结论保存到后端。Roubao 原有端上 provider 设置会把供应商
|
||||
选择和密钥交给采购手机，难以统一审计、限流、切换模型和积累可比较数据。
|
||||
|
||||
第一版需要支持管理员配置一个 OpenAI 兼容 VLM 服务商，由后端代理所有模型调用；
|
||||
App 只传任务/execution 标识和受控候选证据。候选优化用的完整结构化人工标签仍由
|
||||
T-208 后置，不能阻塞本任务的端到端闭环。
|
||||
|
||||
## 关联需求与交互
|
||||
|
||||
- 功能：F-002、F-004、F-005、F-006、F-007、F-009。
|
||||
- 用户故事：US-002、US-004、US-005、US-006、US-009。
|
||||
- 交互：IX-003、IX-006、IX-007、IX-008、IX-010。
|
||||
- 架构/API：后端托管 VLM、OpenAI 兼容 adapter、AI 合约、执行事件/资产、
|
||||
`complete`/`fail` 和管理 Web VLM 设置。
|
||||
|
||||
## 已定合约
|
||||
|
||||
1. 生产数据流固定为 `Android App -> 肉包后端 -> VLM Provider`。BUYER 不能读取、
|
||||
选择或覆盖 provider、Base URL、model、prompt version、timeout、retry 或 API Key。
|
||||
2. 第一版 provider 协议只支持 OpenAI 兼容 `/v1/chat/completions` 多模态请求；
|
||||
`/v1/responses` 和供应商私有协议后置。管理员配置名称、HTTPS Base URL、模型、
|
||||
超时、重试上限、启用状态和默认版本。
|
||||
3. MVP 同时只有一个默认 provider 版本供新 execution 使用。配置修改创建新版本；
|
||||
execution 在首次 AI 调用时绑定不可变的 provider/model/config version 和
|
||||
prompt version，后续调用不得漂移。
|
||||
4. API Key 是 write-only secret。后端使用环境变量提供的 256 bit master key，以
|
||||
AEAD 和随机 nonce 加密后落库；AAD 绑定 provider/version。GET、HTML、日志、
|
||||
错误、审计事件和备份说明均不回显明文。缺少 master key 时禁止保存含 Key 的配置
|
||||
和真实调用，但仍可启动管理/任务功能。
|
||||
5. 远程端点只允许 HTTPS，禁止 userinfo、query、fragment 和重定向；解析/连接阶段
|
||||
阻断 loopback、私网、链路本地、组播和云 metadata 地址，避免 SSRF/DNS rebinding。
|
||||
无 Key 的 loopback HTTP 仅允许显式 Debug 测试配置，不能从生产管理页面创建。
|
||||
6. 管理员可用内置脱敏文本和测试图片检查连接，不发送订单、店铺、SKU 或任务图片。
|
||||
测试失败只显示稳定分类和 request ID，不显示供应商响应正文或密钥。
|
||||
7. 后端从原任务读取需求图片/文字；App 不能替换 SKU、数量、预算或参考图。候选评估
|
||||
只接受当前 execution 已上传、已鉴权和解码的截图资产。
|
||||
8. 每个 execution 最多一次需求提取、最多 5 次按 ordinal 串行候选评估。默认不重试；
|
||||
配置最多允许 1 次仅限确定未收到响应的临时网络失败，schema/4xx/安全错误不重试。
|
||||
9. provider 响应经过严格 schema、大小、置信度和确定性硬约束校验。模型不能产生
|
||||
点击动作、候选授权、人工结论或订单授权，MVP 始终 `order_submitted=false`。
|
||||
10. App 用本地持久 outbox 幂等回传步骤事件、受控截图、候选摘要、complete/fail；
|
||||
上传失败可以补报，但不得恢复已经安全停止的自动化。
|
||||
11. T-207 保存第一版候选和模型理由及必填 `operator_reason`，足以审计完整流程；
|
||||
逐候选结构化 reason code、改选修订和训练/离线评估数据合约属于 T-208。
|
||||
|
||||
## 方案
|
||||
|
||||
1. 新增版本化 provider 配置、加密 secret、execution provenance、候选、执行事件、
|
||||
outcome/error 和 evidence 资产 migration；原始任务事实与模型派生值分表保存。
|
||||
2. 后端实现 provider 管理 usecase、SSR 设置页和 CSRF 保护的写入动作。配置更新只
|
||||
追加版本，停用只影响新 execution，审计记录 actor、时间和非秘密字段。
|
||||
3. 实现安全 HTTP transport、OpenAI Chat Completions adapter、严格请求映射/响应
|
||||
schema、调用预算、取消、超时、重试和错误分类；普通测试只连接本机 mock。
|
||||
4. 实现 `extract-requirements`、`evaluate-candidate`、event、asset、complete 和
|
||||
fail API；全部验证 BUYER/device/claim/execution/version/租约和幂等键。
|
||||
5. Android 用后端 AI client 替换生产工作流的端上 provider client，上传受控截图，
|
||||
按最多 5 个候选执行并在硬停止点要求人工填写简短理由。
|
||||
6. 管理任务详情展示原始需求、provider provenance、候选评估、人员结论、事件和鉴权
|
||||
证据；模型理由、确定性推荐和人员理由视觉及数据上保持分离。
|
||||
7. 清除采购模式遗留的端上 provider secret，并用测试证明 Release 不再读取或发出
|
||||
直连 provider 请求。Debug 探针继续使用独立、被忽略的本机配置。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- [ ] ADMIN 能新增/更新/启用一个 OpenAI 兼容 provider 版本并执行脱敏连接测试；
|
||||
非 ADMIN/BUYER 不能访问，API Key 永不回显。
|
||||
- [ ] 数据库只含带随机 nonce 的密文；错误 master key、篡改密文和缺少 master key
|
||||
均安全失败，日志/HTML/JSON/事件不包含 Key 或供应商正文。
|
||||
- [ ] 私网、loopback、metadata、重定向、DNS rebinding 和非法 URL 被拒绝；生产只
|
||||
连接受控 HTTPS 目标。
|
||||
- [ ] 真机领取后台任务后，需求提取和最多 5 个候选评估均经肉包后端完成，抓包/测试
|
||||
证明 App 不直连 VLM，不携带 provider Key。
|
||||
- [ ] SKU、数量、预算和参考图只能来自原任务；低置信度、无效 schema、超预算、
|
||||
证据不完整和模型越权输出均转人工或拒绝。
|
||||
- [ ] 事件、截图、候选、complete/fail 在断网重试后不重复，管理详情可以还原执行
|
||||
过程；人工接受/拒绝/无匹配/转人工均要求 `operator_reason`。
|
||||
- [ ] 任一路径不提交订单，终态明确保存 `order_submitted=false`；取消和安全错误不
|
||||
自动重试或继续点击。
|
||||
- [ ] migration up/down/up、Go unit/integration/race/vet、Android unit/instrumented、
|
||||
Playwright 三视口、根 `init.ps1` 和 OnePlus PKG110 真机 smoke 通过。
|
||||
|
||||
## 边界
|
||||
|
||||
- 不支持 `/v1/responses`、供应商私有协议、多 provider 按任务选择、采购员切换模型、
|
||||
自动模型路由、实时价格或成本报表。
|
||||
- 不实现 T-208 的逐候选结构化人工标签、修订历史、离线评估或训练管线。
|
||||
- 不下载客户端提交的任意商品/图片 URL，不自动提交订单、支付或绕过平台风险控制。
|
||||
- 不把真实 provider Key、订单、截图、模型正文或解密 master key 纳入 Git。
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 尚未开始。
|
||||
Reference in New Issue
Block a user