docs: 更新 AGENTS.md 开发指南，反映最新的架构变更
This commit is contained in:
crypto_predictor committed
1 parent
a12e035c1c
commit
6182630203
1 file changed
+43
-81
@@ -8,104 +8,66 @@
|
||||
* **语言要求**：所有回答必须使用**中文**。
|
||||
* **称呼要求**：每次回答必须加上**“主人”**。
|
||||
* **最小改动 (Minimal Change)**：只修改完成任务所必须的代码。**禁止**为了“最佳实践”或“代码美观”而进行未被请求的重构。
|
||||
* **环境约束**：本项目严格使用 **Conda** 环境。禁止使用 venv/poetry/pipenv。
|
||||
* **复用优先**：在编写新功能前，必须检查 `data/`, `models/`, `utils/` 下是否已有类似实现。
|
||||
* **环境约束**：本项目严格使用 **Conda** 环境 (`crypto_pred_312`)。禁止使用 venv/poetry/pipenv。
|
||||
* **复用优先**：在编写新功能前，必须检查 `data/`, `models/`, `api/` 下是否已有类似实现。
|
||||
|
||||
## 2. 环境与构建 (Environment & Build)
|
||||
|
||||
本项目依赖管理基于 `requirements.txt`, conda环境名称**crypto_pred_312**
|
||||
* **Python 环境**: `conda activate crypto_pred_312`
|
||||
* **依赖安装**: `pip install -r requirements.txt`
|
||||
* **数据库**:
|
||||
* **仅支持 MySQL**。禁止引入 SQLite 代码。
|
||||
* 配置：通过 `.env` 文件配置 `MYSQL_HOST`, `MYSQL_USER` 等参数。
|
||||
* 连接管理：使用 `data/database.py` 中的 `DatabaseManager` 或 `api/models.py` 中的 `get_db_connection`。
|
||||
|
||||
* **安装依赖**:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
## 3. 项目结构说明 (Project Structure)
|
||||
|
||||
## 3. 测试与质量保证 (Testing & QA)
|
||||
* **`api/`**: 核心服务层
|
||||
* `main.py`: FastAPI 主应用入口。
|
||||
* `models.py`: 数据库模型与操作（MySQL），包含时区转换逻辑。
|
||||
* `prediction_service.py`: 预测业务逻辑。
|
||||
* `static/`: Vue 3 前端静态资源（Dashboard）。
|
||||
* **`data/`**: 数据层
|
||||
* `database.py`: 市场数据 (OHLCV) 数据库管理。
|
||||
* `trading_db.py`: 交易历史数据库管理。
|
||||
* **`models/`**: 机器学习模型定义 (DLinear, TTM-R2 等) 及训练产物。
|
||||
* **`scripts/`**: 辅助工具脚本。
|
||||
* **根目录**:
|
||||
* `start_system.py`: **系统统一启动脚本**（同时启动 API 和自动交易）。
|
||||
* `auto_trade_polymarket.py`: 自动交易主程序。
|
||||
|
||||
使用 `pytest` 作为测试框架。在提交修改前，必须确保相关测试通过。
|
||||
## 4. 开发规范 (Development Standards)
|
||||
|
||||
* **运行所有测试**:
|
||||
```bash
|
||||
pytest
|
||||
```
|
||||
### 4.1 时区处理 (Timezone)
|
||||
* **存储**: 数据库中时间戳通常为 **UTC** 或 **ET (美东时间)**。
|
||||
* **展示**: 前端及日志输出必须转换为 **CST (北京时间)**。
|
||||
* **工具**: 使用 `api.models.convert_to_cst` 进行转换。
|
||||
|
||||
* **运行单个测试文件 (常用)**:
|
||||
```bash
|
||||
pytest tests/test_example.py
|
||||
```
|
||||
### 4.2 代码风格
|
||||
* **注释**: 必须使用**中文**解释“为什么这样做”。
|
||||
* **命名**: 变量/函数 `snake_case`，类名 `PascalCase`。
|
||||
* **类型提示**: 推荐在关键接口使用 Type Hints。
|
||||
|
||||
* **运行单个测试用例 (推荐)**:
|
||||
用于专注调试某一个功能：
|
||||
```bash
|
||||
pytest tests/test_example.py::test_specific_function
|
||||
```
|
||||
### 4.3 数据库操作
|
||||
* **禁止**使用 SQLite。
|
||||
* 使用 `pymysql` 或 `sqlalchemy` 进行操作。
|
||||
* 确保所有数据库连接都使用上下文管理器 (`with` 语句) 以自动关闭。
|
||||
|
||||
* **显示打印输出 (Debug模式)**:
|
||||
```bash
|
||||
pytest -s tests/test_example.py
|
||||
```
|
||||
## 5. 测试与验证 (Testing & QA)
|
||||
|
||||
* **代码格式化与检查**:
|
||||
```bash
|
||||
black . # 格式化代码
|
||||
flake8 . # 代码风格检查
|
||||
```
|
||||
* **运行测试**: `pytest`
|
||||
* **代码检查**: `flake8 .`
|
||||
* **本地验证**:
|
||||
* 修改 API 或前端后，运行 `./start_system.py` 并访问 `http://localhost:8000` 验证。
|
||||
* 修改模型后，运行 `python ensemble_predict.py` 验证预测逻辑。
|
||||
|
||||
## 4. 代码风格规范 (Code Style)
|
||||
|
||||
* **注释 (Comments)**:
|
||||
* **必须使用中文**编写所有注释和文档字符串 (Docstrings)。
|
||||
* Docstring 风格推荐 Google Style 或简单的多行注释。
|
||||
* 注释应解释“为什么这样做” (Why)，而不是“做了什么” (What)。
|
||||
|
||||
* **命名约定 (Naming)**:
|
||||
* 变量/函数: `snake_case` (如 `add_technical_features`)
|
||||
* 类名: `PascalCase` (如 `BinanceDataFetcher`)
|
||||
* 常量: `UPPER_CASE` (如 `MAX_RETRIES`)
|
||||
* 私有成员: `_snake_case` (前缀下划线)
|
||||
|
||||
* **导入 (Imports)**:
|
||||
* 顺序：标准库 -> 第三方库 -> 本地模块。
|
||||
* 尽量使用绝对导入。
|
||||
* 注意：项目中部分脚本使用了 `sys.path.insert` hack，修改时需保持兼容，不要随意删除。
|
||||
|
||||
* **类型提示 (Type Hints)**:
|
||||
* 推荐在函数签名中添加类型提示，但不强制要求全覆盖。
|
||||
* 示例: `def process_data(df: pd.DataFrame) -> np.ndarray:`
|
||||
|
||||
* **错误处理 (Error Handling)**:
|
||||
* 使用具体的异常类型 (如 `ValueError`, `FileNotFoundError`)，避免裸 `except:`。
|
||||
* 在 API 调用或网络请求处必须添加重试或错误捕获逻辑。
|
||||
|
||||
## 5. 项目结构说明 (Project Structure)
|
||||
|
||||
在修改代码前，请参考以下结构定位文件：
|
||||
|
||||
* **`api/`**: FastAPI 接口服务代码。
|
||||
* **`data/`**: 数据获取 (BinanceFetcher等) 和预处理逻辑。
|
||||
* **`models/`**: 模型定义 (N-BEATS, DLinear, CatBoost 等) 和 训练好的模型文件。
|
||||
* **`tests/`**: 单元测试和集成测试。
|
||||
* **`scripts/`**: 辅助脚本。
|
||||
* **`training/`** & **`logs/`**: 训练日志和过程文件。
|
||||
* **根目录脚本**: 包含多个入口脚本 (如 `ensemble_predict.py`, `train_catboost.py`)，修改时需格外小心，避免破坏生产流程。
|
||||
|
||||
## 6. 开发流程 (Workflow)
|
||||
|
||||
1. **理解需求**: 先阅读代码，确认需求范围。如果有歧义，**先询问主人**。
|
||||
2. **定位代码**: 使用 `grep` 或 `glob` 查找相关文件。
|
||||
3. **制定计划**: 思考修改方案，优先考虑不破坏现有逻辑的“加法”修改。
|
||||
4. **实施修改**: 编辑代码，保持风格一致。
|
||||
5. **验证**:
|
||||
* 运行 `flake8` 检查语法错误。
|
||||
* 运行 `pytest` 验证逻辑。
|
||||
* 如果是脚本，尝试带 `--help` 或测试参数运行以确保无运行时错误。
|
||||
|
||||
## 7. 禁止事项 (Constraints)
|
||||
## 6. 禁止事项 (Constraints)
|
||||
|
||||
* ❌ **禁止**猜测业务逻辑。
|
||||
* ❌ **禁止**删除看似无用但可能被外部脚本调用的代码。
|
||||
* ❌ **禁止**在未确认的情况下升级核心库版本 (如 torch, pandas)。
|
||||
* ❌ **禁止**输出英语回复 (代码变量名除外)。
|
||||
* ❌ **禁止**恢复已删除的 SQLite 相关代码。
|
||||
|
||||
---
|
||||
*遵循此指南，确保高效、安全地协助主人完成任务。*
|
||||
Reference in new issue
Block a user