135 lines
4.1 KiB
Markdown
135 lines
4.1 KiB
Markdown
|
# Agent 开发指南
|
|||
|
|
|
|||
|
|
## 项目入口规则
|
|||
|
|
|
|||
|
|
本文件是 Codex、Claude Code 或其他 coding agent 进入本项目后的第一入口。执行任何开发、修复、重构或检查任务前，必须先阅读本文件。
|
|||
|
|
|
|||
|
|
## 必读文档
|
|||
|
|
|
|||
|
|
开始任务前，必须先阅读：
|
|||
|
|
|
|||
|
|
- `docs/04-development-rules.md`
|
|||
|
|
- `docs/05-project-architecture.md`
|
|||
|
|
- `tasks.md`
|
|||
|
|
|
|||
|
|
根据任务类型继续阅读：
|
|||
|
|
|
|||
|
|
- 需求或功能范围：`docs/02-prd.md`
|
|||
|
|
- 技术栈或依赖：`docs/03-technical-stack.md`
|
|||
|
|
- UI 布局和交互：`docs/07-ui-design.md`
|
|||
|
|
- 图片预览、拖动、缩放、旋转、坐标换算、导出一致性：`docs/08-image-editor-design.md`
|
|||
|
|
- 打包发布：`docs/09-packaging-release.md`
|
|||
|
|
- 项目愿景和边界：`docs/01-product-vision.md`
|
|||
|
|
|
|||
|
|
## 执行方式
|
|||
|
|
|
|||
|
|
默认执行流程：
|
|||
|
|
|
|||
|
|
1. 阅读本文件。
|
|||
|
|
2. 阅读必读文档。
|
|||
|
|
3. 打开 `tasks.md`。
|
|||
|
|
4. 找到第一个未完成任务。
|
|||
|
|
5. 只完成这一个任务。
|
|||
|
|
6. 不扩大任务范围。
|
|||
|
|
7. 修改前先阅读相关已有代码。
|
|||
|
|
8. 完成后更新 `tasks.md` 中对应任务状态。
|
|||
|
|
9. 运行必要验证。
|
|||
|
|
10. 创建 Git 提交。
|
|||
|
|
11. 汇报修改内容、验证结果和未完成事项。
|
|||
|
|
|
|||
|
|
如果用户指定了某个任务，以用户指定任务为准，但仍必须阅读相关文档。
|
|||
|
|
|
|||
|
|
## 任务边界
|
|||
|
|
|
|||
|
|
必须遵守：
|
|||
|
|
|
|||
|
|
- 每次只做一个明确任务。
|
|||
|
|
- 不顺手重构无关代码。
|
|||
|
|
- 不修改与当前任务无关的文件。
|
|||
|
|
- 不替换技术栈。
|
|||
|
|
- 不新增未经说明的第三方依赖。
|
|||
|
|
- 不删除用户素材、输出图片、配置或日志。
|
|||
|
|
- 不把临时调试代码作为正式代码提交。
|
|||
|
|
|
|||
|
|
如任务需求不清楚：
|
|||
|
|
|
|||
|
|
- 优先按已有文档保守实现。
|
|||
|
|
- 若会影响架构、技术栈、数据结构或用户流程，必须先询问用户。
|
|||
|
|
|
|||
|
|
## 技术约束
|
|||
|
|
|
|||
|
|
必须遵守：
|
|||
|
|
|
|||
|
|
- Python 版本：Python 3.7。
|
|||
|
|
- GUI 框架：PySide6。
|
|||
|
|
- PySide6 版本：`PySide6==6.5.3`。
|
|||
|
|
- 图片处理：Pillow。
|
|||
|
|
- 配置和模板：JSON。
|
|||
|
|
- 打包：PyInstaller，优先 `onedir`。
|
|||
|
|
- 第一阶段目标系统：Windows 10 / Windows 11。
|
|||
|
|
|
|||
|
|
禁止：
|
|||
|
|
|
|||
|
|
- 禁止切换到 Electron、Web、C#、C++、Tkinter、wxPython 或其他 GUI 技术栈。
|
|||
|
|
- 禁止将项目改造成前后端分离应用。
|
|||
|
|
- 禁止依赖公网服务完成核心功能。
|
|||
|
|
- 禁止使用只支持 Python 3.8 及以上的依赖版本。
|
|||
|
|
|
|||
|
|
## 代码结构约束
|
|||
|
|
|
|||
|
|
必须遵守 `docs/05-project-architecture.md` 中的分层：
|
|||
|
|
|
|||
|
|
- `src/app/`：GUI 层。
|
|||
|
|
- `src/app/widgets/`：UI 组件。
|
|||
|
|
- `src/core/`：与 GUI 无关的核心模型、合成和批量逻辑。
|
|||
|
|
- `src/services/`：配置、模板、文件、日志等服务。
|
|||
|
|
- `tests/`：测试。
|
|||
|
|
|
|||
|
|
禁止：
|
|||
|
|
|
|||
|
|
- 禁止把所有功能写进 `src/main.py` 或一个窗口类。
|
|||
|
|
- 禁止让 `core/` 依赖 PySide6 UI 控件。
|
|||
|
|
- 禁止在 UI 按钮事件中直接堆叠大量图片处理代码。
|
|||
|
|
- 禁止复制两套单张合成和批量合成逻辑。
|
|||
|
|
|
|||
|
|
## 验证要求
|
|||
|
|
|
|||
|
|
根据任务范围执行验证：
|
|||
|
|
|
|||
|
|
- 文档修改：检查路径、标题、引用和明显格式问题。
|
|||
|
|
- Python 代码修改：运行语法检查。
|
|||
|
|
- GUI 修改：尽量启动程序确认窗口可打开。
|
|||
|
|
- 图片处理修改：验证至少一张衣服图和一张印花图合成结果。
|
|||
|
|
- 批量处理修改：验证成功、失败和进度反馈路径。
|
|||
|
|
- 打包修改：验证 PyInstaller 打包产物能启动。
|
|||
|
|
|
|||
|
|
如果无法验证，最终回复必须明确说明未验证项和原因。
|
|||
|
|
|
|||
|
|
## Git 要求
|
|||
|
|
|
|||
|
|
完成任务后：
|
|||
|
|
|
|||
|
|
- 查看 `git status`。
|
|||
|
|
- 只提交本任务相关文件。
|
|||
|
|
- 提交信息使用简洁英文，例如：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
feat: implement file scanning service
|
|||
|
|
fix: handle invalid template config
|
|||
|
|
docs: update task plan
|
|||
|
|
chore: add logging setup
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
如果远端推送失败，需要说明失败原因；本地提交仍应保留。
|
|||
|
|
|
|||
|
|
## 标准接续提示
|
|||
|
|
|
|||
|
|
当用户要求继续开发时，agent 应按以下方式理解任务：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
请先阅读 AGENTS.md、docs/04-development-rules.md、docs/05-project-architecture.md 和 tasks.md。
|
|||
|
|
然后从 tasks.md 中找到第一个未完成任务，只完成这一个任务。
|
|||
|
|
不要扩大范围。
|
|||
|
|
完成后更新 tasks.md，运行必要验证，提交 git，并汇报结果。
|
|||
|
|
```
|