From 61826302035175b7b9e17ddb73ad93549456833d Mon Sep 17 00:00:00 2001 From: crypto_predictor Date: Sat, 7 Feb 2026 16:58:44 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS.md=20?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97=EF=BC=8C=E5=8F=8D=E6=98=A0?= =?UTF-8?q?=E6=9C=80=E6=96=B0=E7=9A=84=E6=9E=B6=E6=9E=84=E5=8F=98=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 124 +++++++++++++++++++----------------------------------- 1 file changed, 43 insertions(+), 81 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c9c3cba..3b6cf50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 相关代码。 --- *遵循此指南，确保高效、安全地协助主人完成任务。*