cmroubao/AGENTS.md

AGENTS.md

本仓库的 AI coding agent 权威入口。进入仓库后先读本文，再进入 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 收尾。