cmpdd/AGENTS.md

AGENTS.md

本文件是 Codex / AI coding agent 进入本项目时的仓库级入口。开始任何编码、改文档或执行任务前，先读本文件。

项目定位

本项目是一个内部运营使用的拼多多批量下单执行器。

第一版目标：

• 从固定表头 Excel 导入已审核的商品下单任务。
• 在 Windows 桌面 GUI 中展示、勾选并按顺序执行任务。
• 通过 uiautomator2 + ADB 控制一台 Android 真机操作拼多多 App。
• 自动选择商品 SKU、数量并进入下单流程。
• 默认支付前人工确认；预留受控自动支付开关。
• 成功后读取订单号，失败时记录原因，并回写 Excel 结果文件。

必读顺序

每次开始工作前按顺序读取：

1. docs/00-ai-start-here.md：项目入口、MVP 边界、任务规则。
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. tasks.md：任务定义、依赖、验收标准。
8. progress.md：历史执行记录、验证结果、阻塞点。
9. docs/current-state.md：当前仓库现实、运行命令、下一步入口。

涉及界面时再读 docs/routes.md。 涉及本地模块接口时再读 docs/api.md。

任务规则

• 每轮只领取 tasks.md 中第一个状态为 TODO 且依赖均为 DONE 的任务。
• 开始前把该任务状态改为 DOING。
• 本轮只完成这一个任务，不顺手做后续任务。
• 验收通过后把任务状态改为 DONE。
• 完成后更新：
  • progress.md：记录做了什么、验证命令、结果、阻塞点。
  • docs/current-state.md：同步当前代码结构、可运行命令、下一步入口。
• 如果任务、代码现实、需求文档冲突，先说明冲突，不要擅自跳步或重排任务。

技术边界

既定 MVP 技术路线：

• Python 3.x
• PySide6 桌面 GUI
• openpyxl 读取和回写 Excel
• uiautomator2 + ADB 控制 Android 真机
• 本地文件日志、截图、UI XML 归档
• 暂不引入 Web 后台、数据库、多设备调度

新增依赖前必须说明用途、替代方案和维护成本，并同步更新 docs/03-tech-stack.md。

安全与合规边界

允许做：

• 控制公司/用户有权限使用的 Android 真机。
• 操作已登录的拼多多 App。
• 根据运营审核过的 Excel 自动选择 SKU、数量并下单。
• 在显式开启、金额上限和二次校验通过时执行受控自动支付。
• 出现异常时截图、保存 UI XML、记录失败原因。

禁止做：

• 绕过验证码、风控、人脸、短信、安全校验或平台限制。
• 无配置、无金额上限、无二次校验的自动支付。
• 保存支付密码、短信验证码、账号密码等敏感信息。
• 调用、逆向或改造拼多多非公开接口。
• 在页面识别失败时盲目点击不确定区域继续下单。

遇到验证码、风控、人脸、短信、安全验证时，必须进入 待人工 或失败分支。

文档维护

• 需求变化先改 docs/02-requirements.md，再改代码。
• 技术选型变化先改 docs/03-tech-stack.md。
• 模块职责、数据模型、任务状态变化先改 docs/04-architecture.md 和 docs/api.md。
• GUI 区域或交互变化同步 docs/routes.md。
• 任务状态变化同步 tasks.md 和 progress.md。
• 代码现实变化同步 docs/current-state.md。

当前下一步

当前项目处于 MVP 起步 / 原型验证前。

下一个任务以 tasks.md 为准，当前应从：

T-001 初始化 Python 项目骨架

开始。