# AGENTS.md

> 本仓库的 AI coding agent 权威入口。进入仓库后先读本文，再进入
> [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。

## 项目定位

本项目用于验证并逐步实现“采购任务 -> Android App 领取 -> AI 理解图片和文字
-> 拼多多检索与候选判断 -> 人工确认 -> 结果回传”的采购闭环。

当前处于文档和技术验证准备阶段。首版不是生产级无人值守采购系统，不允许自动
提交订单或自动支付。

## 必读顺序

首次接入按顺序读取：

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

日常任务读取 `docs/agent-context.json` 指定的最小文件、本轮任务文件和命中的任务
类型路由。

## Codebase Knowledge Graph

本项目使用 codebase-memory-mcp 维护代码知识图谱。代码发现按以下优先级执行：

1. `search_graph`：按模式定位函数、类、路由和变量。
2. `trace_path`：追踪调用方或被调用方。
3. `get_code_snippet`：读取指定函数或类的源码。
4. `query_graph`：复杂关系使用 Cypher 查询。
5. `get_architecture`：获取项目级架构概览。

以下情况才回退到 `rg`、文件列表或直接读取：

- 查字符串字面量、错误消息和配置值。
- 查 Markdown、Dockerfile、Shell、JSON 等非代码文件。
- 图谱尚未建立、不可用或结果不足。

## 任务规则

- 真实任务一任务一文件，存放于 `docs/tasks/T-<编号>.md`。
- 每个 agent 同时只做一个 `TODO` 且依赖已完成的任务。
- 开始时将任务状态改为 `DOING`；只有验收证据齐全时才能改为 `DONE`。
- 任务的修改路径必须在 `write_paths` 中，不能顺手扩大范围。
- 路线图 `docs/06-tasks.md` 不跟踪单任务状态。
- 当前目录、命令或 blocker 变化时同步 `docs/current-state.md`。
- 执行记录和验证证据写入当前任务文件，不逐任务追加 `progress.md`。

## 业务硬边界

- MVP 只允许操作拼多多，包名和页面结构必须在测试设备上验证后记录。
- MVP 由采购人员点击“获取任务”并开始，后台不强推后立即执行。
- 自动化到达候选商品或订单确认页后必须停止，不能点击最终提交订单或支付。
- 不绕过验证码、登录验证、平台风控、权限校验或生物识别。
- 遇到验证码、账号失效、风控提示、页面结构未知或价格超预算时停止并回报。
- 用户输入的数量和最高预算是权威约束，模型输出不能覆盖。
- 不记录拼多多密码、支付密码、Cookie、会话令牌或完整个人敏感信息。

## 工作规则

- 需求、接口、状态机或数据模型有变化时，先更新对应文档再改代码。
- 优先沿用接入后的 Roubao 代码结构和既有依赖，不并存第二套自动化框架。
- Android 自动化优先使用可访问性节点和稳定语义；截图/VLM 是辅助判断，不把
  裸坐标当成唯一定位方式。
- VLM 输出必须经过结构校验、范围校验和确定性规则复核，不能直接触发不可逆动作。
- 所有外部调用设置超时；重试必须有上限；任务领取和结果上报必须幂等。
- 不提交真实密钥。配置只保存环境变量名、占位值或本地忽略文件。
- 不删除或重置用户已有改动。

## 验证

Android 基线使用根目录 `init.ps1` 或 `init.sh` 验证。默认执行单元测试任务并构建
Debug APK；设置 `RUN_START_COMMAND=1` 时还会在已授权真机上安装和启动 App。
后端建立后再把后端测试加入同一标准入口。

结束任务前按 `docs/clean-state-checklist.md` 收尾。