|
1 | | -# MyRustTools 开发规范 |
| 1 | +# RustTools — YOLO Desktop App |
2 | 2 |
|
3 | | -## 开发语言 |
4 | | - |
5 | | -# MyRustTools 开发规范(Agent 指南) |
6 | | - |
7 | | -## 开发语言 |
8 | | - |
9 | | -**所有开发对话必须使用中文** |
10 | | - |
11 | | ---- |
12 | | - |
13 | | -## 架构文档位置(重要) |
14 | | - |
15 | | -- 项目的详细架构说明(模块结构、接口规范、状态管理、约束与演进路线)已移至仓库根的 `README.md`。 |
16 | | -- 请将 `README.md` 作为“事实性”架构来源(Source of Truth),不要在 `CLAUDE.md` 中重复完整架构说明。 |
17 | | - |
18 | | ---- |
19 | | - |
20 | | -## 给 agent 的操作指南(何时做、如何做) |
21 | | - |
22 | | -- 任务规划:任何多步骤任务必须先使用 `manage_todo_list` 创建并维护 TODO 列表。 |
23 | | -- 编辑代码:使用 `apply_patch`(遵循 repo 的 applyPatchInstructions)对文件做修改;每次改动后运行相关测试并调用 `code-reviewer` 进行审查。 |
24 | | -- 模块开发:新增模块需在 `modules/<name>/manifest.ts` 定义清单,并在模块入口注册(`moduleRegistry.register()`)。不要直接修改 `core/`。 |
25 | | -- 后端命令:在 `src-tauri/src/modules/<mod>/commands/` 添加命令,使用 `#[tauri::command]` 并返回 `Result<T, String>`。 |
26 | | -- 测试优先:采用 TDD(使用 `tdd-guide`);模块需要单元测试、集成测试,关键流程需要 E2E 测试,目标覆盖率为 80%。 |
27 | | -- 代码审查:完成实现后调用 `code-reviewer`,安全/敏感变更同时调用 `security-reviewer`。 |
28 | | -- 构建与运行:前端开发先运行 `npm run dev`(或 `pnpm dev`),如需启动 Tauri 调试请运行 `npm run tauri dev`(或等价命令)。 |
29 | | -- 构建失败:遇到构建/编译失败,请调用相应的构建解析 agent(如 `rust-build-resolver`等)。 |
30 | | -- 前端编写代码时如果需要打印信息请使用 `shared/components/ui/Toast.tsx` 组件 |
31 | | -- 文档要求:任何新功能必须先在 `doc/进行中/` 创建文档并在 `doc/0-index.md` 注册条目。 |
32 | | -- 验证与发布:修改完成后优先运行受影响模块的测试并手动验证关键交互(路由、项目创建、训练命令等)。 |
33 | | - |
34 | | ---- |
35 | | - |
36 | | -## 快速参考(文件与命名) |
37 | | - |
38 | | -- `core/`:只读,核心基础设施,禁止日常修改。 |
39 | | -- `modules/`:模块实现,包含 `manifest.ts`、`pages/`、`components/` 等。 |
40 | | -- `shared/`:跨模块共享工具与组件。 |
41 | | -- 前端组件:`PascalCase.tsx`;工具函数:`camelCase.ts`。 |
42 | | -- 后端模块入口:`mod.rs`;命令文件采用 `snake_case`。 |
43 | | - |
44 | | ---- |
45 | | - |
46 | | -## 变更流程要点 |
47 | | - |
48 | | -- 进行重大结构变更前,先在 `doc/` 提交变更提案并获得团队确认。 |
49 | | -- 所有敏感改动必须走安全审查和回滚计划。 |
50 | | - |
51 | | ---- |
52 | | - |
53 | | -如需查看完整架构细节,请打开仓库根的 `README.md`。 |
54 | | - |
55 | | -- 阅读 `doc/进行中/` 下相关文档 |
56 | | -- 确认当前进度和待办事项 |
57 | | - |
58 | | -2. **开发过程中** |
59 | | - - 每完成一个功能点,更新文档进度 |
60 | | - - 使用 `[x]` 标记已完成项 |
61 | | - |
62 | | -3. **功能完成时** |
63 | | - - 更新文档状态为"已完成" |
64 | | - - 移动文档到 `已完成/正在维护` |
65 | | - - **必须由用户检查确认后才能视为完成** |
66 | | - - 未经过用户检查的功能不得标记为完成 |
67 | | - |
68 | | ---- |
69 | | - |
70 | | -## 示例对话 |
| 3 | +## Project Stack |
| 4 | +- **Backend**: Rust + Tauri 2.x, Burn framework for ML training |
| 5 | +- **Frontend**: React 18 + TypeScript + Vite |
| 6 | +- **ML**: YOLO models (YOLOv8/11/12), pure Rust inference via Burn/onnxruntime-rs |
| 7 | +- **Styling**: CSS Modules (no Tailwind, no inline styles in new code) |
| 8 | +- **State**: Zustand for frontend state management |
71 | 9 |
|
| 10 | +## Key Directories |
72 | 11 | ``` |
73 | | -用户: 我们来实现模块化架构吧 |
74 | | -
|
75 | | -助手: 好的,我先查看一下当前进行中的文档。 |
76 | | - 发现相关文档: 01-模块化架构设计-20260405.md |
77 | | - 当前进度: 30% |
78 | | - 待完成: |
79 | | - - [ ] 创建模块类型定义 |
80 | | - - [x] 设计架构方案 |
81 | | -
|
82 | | - 开始实现模块类型定义... |
| 12 | +src/ # React frontend |
| 13 | +src/modules/yolo/pages/ # Page components (TrainingPage, VideoPage, etc.) |
| 14 | +src/shared/components/ui/ # Shared UI (Toast, Modal, etc.) |
| 15 | +src/core/stores/ # Zustand stores |
| 16 | +src-tauri/src/ # Rust backend |
| 17 | +src-tauri/src/modules/yolo/ # YOLO domain (commands, services) |
| 18 | +src-tauri/src/modules/yolo/services/trainer.rs # Burn training |
| 19 | +src-tauri/src/modules/yolo/services/inference_core.rs # Rust inference |
83 | 20 | ``` |
84 | 21 |
|
85 | | ---- |
86 | | - |
87 | | -## 文档模板 |
88 | | - |
89 | | -### 进行中文档模板 |
90 | | - |
91 | | -```markdown |
92 | | -# {功能名称} |
93 | | - |
94 | | -## 基本信息 |
95 | | - |
96 | | -- 开始日期: {YYYY-MM-DD} |
97 | | -- 预计完成: {YYYY-MM-DD} |
98 | | -- 状态: 进行中 |
99 | | -- 进度: {X%} |
100 | | - |
101 | | -## 功能描述 |
102 | | - |
103 | | -{简要说明} |
104 | | - |
105 | | -## 任务分解 |
106 | | - |
107 | | -### Phase 1: {阶段名} |
108 | | - |
109 | | -- [ ] 子任务1 |
110 | | -- [ ] 子任务2 |
111 | | - |
112 | | -### Phase 2: {阶段名} |
113 | | - |
114 | | -- [ ] 子任务3 |
115 | | - |
116 | | -## 当前进度 |
117 | | - |
118 | | -{具体进度说明} |
119 | | - |
120 | | -## 备注 |
121 | | - |
122 | | -{待解决的问题等} |
| 22 | +## Critical Conventions |
| 23 | +- **No Python env checks** — pure Rust with CUDA detection only |
| 24 | +- **Proxy config**: `~/.config/rust-tools/proxy.json` (no hardcoded proxy URLs) |
| 25 | +- **Model download**: GitHub release URLs + configurable proxy |
| 26 | +- **num_classes**: always read from project's `data.yaml` (nc field), never hardcode |
| 27 | +- **CSS Modules required** for all new page components (no inline `style={{}}`) |
| 28 | +- **Toast over alert()** — use shared Toast component, never browser alert |
| 29 | + |
| 30 | +## Build Commands |
| 31 | +```bash |
| 32 | +npm run dev # Frontend dev |
| 33 | +cargo build --manifest-path src-tauri/Cargo.toml # Rust build |
| 34 | +cargo check --manifest-path src-tauri/Cargo.toml # Rust type check |
| 35 | +npm run build # Frontend production build |
123 | 36 | ``` |
124 | 37 |
|
125 | | -### 已完成文档模板 |
126 | | - |
127 | | -```markdown |
128 | | -# {功能名称} |
129 | | - |
130 | | -## 基本信息 |
131 | | - |
132 | | -- 完成日期: {YYYY-MM-DD} |
133 | | -- 状态: 正在维护 | 已归档 |
134 | | -- 版本: {v1.0.0} |
135 | | - |
136 | | -## 功能描述 |
137 | | - |
138 | | -{已完成的功能说明} |
139 | | - |
140 | | -## 核心实现 |
141 | | - |
142 | | -{技术要点简述} |
143 | | - |
144 | | -## 相关文件 |
145 | | - |
146 | | -- `src/xxx.ts` |
147 | | -- `src/yyy.tsx` |
148 | | - |
149 | | -## 更新日志 |
150 | | - |
151 | | -| 日期 | 版本 | 更新内容 | |
152 | | -| ---------- | ------ | -------- | |
153 | | -| YYYY-MM-DD | v1.0.0 | 初始完成 | |
154 | | -``` |
155 | | - |
156 | | ---- |
157 | | - |
158 | | -## 规则一致性 |
159 | | - |
160 | | -- 所有开发对话使用中文 |
161 | | -- 每次开发前先阅读进行中文档 |
162 | | -- 每完成一个功能点立即更新文档 |
163 | | -- 功能完成后及时移动文档位置 |
164 | | -- 保持索引文件 (0-index.md) 最新状态 |
| 38 | +## Development Workflow |
| 39 | +When asked to implement a feature or fix: |
| 40 | +1. Read relevant files first |
| 41 | +2. Check existing patterns in similar code |
| 42 | +3. Follow the adversarial-dev-workflow skill for significant changes |
| 43 | +4. Always verify with cargo check / npm run build before committing |
| 44 | + |
| 45 | +## Style Rules |
| 46 | +- TypeScript: strict mode, explicit types on all function signatures |
| 47 | +- Rust: clippy-compliant, no unsafe unless necessary |
| 48 | +- CSS: CSS Modules only, modern dark theme colors (bg: #0f0f1a, accent: #00d4ff) |
| 49 | +- Components: functional React with hooks, no class components |
0 commit comments