100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
|
# AGENTS.md
|
||
|
|
|
||
|
|
> 本文件是 Codex / AI coding agent 进入本项目时的仓库级入口。开始任何编码、改文档或执行任务前，先读本文件。
|
||
|
|
|
||
|
|
## 项目定位
|
||
|
|
|
||
|
|
本项目是一个内部运营使用的拼多多批量下单执行器。
|
||
|
|
|
||
|
|
第一版目标：
|
||
|
|
|
||
|
|
- 从固定表头 Excel 导入已审核的商品下单任务。
|
||
|
|
- 在 Windows 桌面 GUI 中展示、勾选并按顺序执行任务。
|
||
|
|
- 通过 `uiautomator2 + ADB` 控制一台 Android 真机操作拼多多 App。
|
||
|
|
- 自动选择商品 SKU、数量并进入下单流程。
|
||
|
|
- 默认支付前人工确认；预留受控自动支付开关。
|
||
|
|
- 成功后读取订单号，失败时记录原因，并回写 Excel 结果文件。
|
||
|
|
|
||
|
|
## 必读顺序
|
||
|
|
|
||
|
|
每次开始工作前按顺序读取：
|
||
|
|
|
||
|
|
1. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：项目入口、MVP 边界、任务规则。
|
||
|
|
2. [`docs/01-vision.md`](docs/01-vision.md)：项目愿景、目标用户、非目标。
|
||
|
|
3. [`docs/02-requirements.md`](docs/02-requirements.md)：需求与验收标准。
|
||
|
|
4. [`docs/03-tech-stack.md`](docs/03-tech-stack.md)：技术选型和运行方式。
|
||
|
|
5. [`docs/04-architecture.md`](docs/04-architecture.md)：架构、模块职责、数据模型。
|
||
|
|
6. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：编码规则和安全边界。
|
||
|
|
7. [`tasks.md`](tasks.md)：任务定义、依赖、验收标准。
|
||
|
|
8. [`progress.md`](progress.md)：历史执行记录、验证结果、阻塞点。
|
||
|
|
9. [`docs/current-state.md`](docs/current-state.md)：当前仓库现实、运行命令、下一步入口。
|
||
|
|
|
||
|
|
涉及界面时再读 [`docs/routes.md`](docs/routes.md)。
|
||
|
|
涉及本地模块接口时再读 [`docs/api.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` 为准，当前应从：
|
||
|
|
|
||
|
|
```text
|
||
|
|
T-001 初始化 Python 项目骨架
|
||
|
|
```
|
||
|
|
|
||
|
|
开始。
|
||
|
|
|