# AI 开发入口

## 一句话定位

本项目验证管理后台创建的图片和文字采购任务，能否由 Android App 领取并借助 VLM
在拼多多中找到合理候选商品，同时安全地停在人工确认位置并回传证据。

## 当前 MVP

只做：

- 管理 Web 创建和查看采购任务。
- 一台 Android 设备由采购人员手动领取下一条任务。
- AI 把图片和文字解析为结构化检索条件。
- App 在拼多多搜索、检查少量结果并选择候选。
- App 停在候选确认或订单确认页，由人判断是否通过。
- 回传任务状态、候选摘要、截图和失败原因。

不做：

- 推送到达后无人确认地立即执行。
- 最终提交订单、自动付款或处理退款。
- 绕过验证码、风控或登录校验。
- 多电商平台、多设备并发调度和生产级 RBAC。

## 首次读取顺序

1. `../AGENTS.md`
2. `01-vision.md`
3. `02-requirements.md`
4. `03-tech-stack.md`
5. `04-architecture.md`
6. `05-coding-rules.md`
7. `06-tasks.md`
8. `tasks/README.md`
9. `current-state.md`

有界面任务时再读 `07-user-stories.md`、`08-interaction-checklist.md`、`routes.md`
和关联原型；API 任务读 `api.md`。

## 固定开工流程

1. 确认工作目录是仓库根目录。
2. 读取 `agent-context.json`、`current-state.md` 和当前任务文件。
3. 仓库已启用 Git 时查看最近五条提交；当前未启用时，以 `current-state.md` 为准。
4. 运行 `./init.ps1`（Windows）或 `./init.sh`（WSL/Linux）。
5. 如果脚本失败，先记录并修复基线；不要在失败状态领取依赖它的后续任务。
6. 有真实基线后先跑 smoke；基线失败时先修基线。
7. 领取编号最小、依赖已完成的一个 `TODO` 任务并改成 `DOING`。
8. 完成实现、验证、任务执行记录和当前状态同步后再结束。

## 当前阶段与优先路径

当前已完成 Phase 0 和 Phase 1：Android 可运行、设备就绪、workflow、私有样本导入、
动态词搜索、最多 5 个候选截图采集、结构化需求提取、候选评估和人工确认停止点均已
验证。T-201 后端骨架、T-202 P0 原型、T-203 任务 API/管理 Web、T-204 最小鉴权
T-205 原子领取/租约状态机、T-206 Android 登录/有限离线和 T-207 本地 VLM、候选、
证据及结果回传均已完成。下一步按编号开始 T-208，建立逐候选结构化人工理由、修订
历史和优化数据闭环；不得提前建设报表、训练管线或外部商品抓取。
手机从管理后端领取任务并回传结果，VLM、拼多多自动化和人工确认在 App 本地完成。
T-206 增加有限离线执行；T-207 已复用 Roubao 端上 OpenAI 兼容适配器并加密本地 Key。
管理后端不保存/代理 VLM，后台任务不能覆盖手机 provider 配置。

严格按以下顺序推进：

1. 接入并构建 Roubao Android 基线。
2. 用本机蝦皮订单样本生成固定探针任务，验证拼多多搜索和页面操作。
3. 接入 VLM，验证结构化需求提取和候选判断。
4. 建立最小后端和管理页面。
5. 接入手动领取、租约、状态和结果回传。
6. 用真实样本完成 20 条任务试验。

不允许先建设完整后台、消息推送或多设备调度来代替第 2 步的高风险验证。

## 事实来源

- 产品范围：`02-requirements.md`
- 角色目标：`07-user-stories.md`
- 交互行为：`08-interaction-checklist.md`
- 技术和模块边界：`03-tech-stack.md`、`04-architecture.md`
- API：`api.md`
- 当前现实：`current-state.md`、当前代码和实际命令输出
- 任务：`docs/tasks/T-<编号>.md`
- 原始讨论摘要：`../deepseek总结.txt`，仅作背景；与正式文档冲突时不作为权威

Roubao、拼多多页面、Android 包名、上游分支和依赖版本必须从接入的源码和测试设备
核实，不能仅凭讨论摘要推断。

## 常见任务路由

- Android 自动化：需求 -> 架构“自动化边界” -> 编码规则 -> 当前任务。
- VLM：需求约束 -> 架构“AI 决策边界” -> API/模块合约 -> 当前任务。
- 管理 Web：用户故事 -> 交互清单 -> 路由 -> API -> 架构。
- 后端/数据：API -> 架构数据模型和状态机 -> 编码规则。
- 安全相关：需求风险 -> 架构安全边界 -> 编码规则，无法满足时停止。

## 当前验证命令

Windows 默认验证：

```powershell
.\init.ps1
```

连接并授权真机后执行安装和冷启动：

```powershell
$env:RUN_START_COMMAND = "1"
.\init.ps1
```

脚本先执行 Android `test assembleDebug`，再以 `GOTOOLCHAIN=local` 执行后端
`go test ./...`、`go vet ./...` 并构建 API、migration 与 authctl 三个入口。后端
单独运行：

```powershell
Set-Location backend-api
$env:GOTOOLCHAIN = "local"
go run ./cmd/migrate up
$env:CMROUBAO_AUTH_PASSWORD = "至少 6 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
go run ./cmd/api
```