AGENTS.md - 智能代理开发指南

本文件定义了在该项目中进行开发的 AI 代理（Agent）的行为准则、技术规范和操作流程。请严格遵守。

1. 核心行为准则 (Core Mandates)

最高优先级原则：

本项目依赖管理基于 requirements.txt, conda环境名称crypto_pred_312

使用 pytest 作为测试框架。在提交修改前，必须确保相关测试通过。

运行所有测试:
```
pytest
```
运行单个测试文件 (常用):
```
pytest tests/test_example.py
```
运行单个测试用例 (推荐): 用于专注调试某一个功能：
```
pytest tests/test_example.py::test_specific_function
```
显示打印输出 (Debug模式):
```
pytest -s tests/test_example.py
```

代码格式化与检查:

black .          # 格式化代码
flake8 .         # 代码风格检查

注释 (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 调用或网络请求处必须添加重试或错误捕获逻辑。

在修改代码前，请参考以下结构定位文件：

api/: FastAPI 接口服务代码。
data/: 数据获取 (BinanceFetcher等) 和预处理逻辑。
models/: 模型定义 (N-BEATS, DLinear, CatBoost 等) 和训练好的模型文件。
tests/: 单元测试和集成测试。
scripts/: 辅助脚本。
training/ & logs/: 训练日志和过程文件。
根目录脚本: 包含多个入口脚本 (如 ensemble_predict.py, train_catboost.py)，修改时需格外小心，避免破坏生产流程。

理解需求: 先阅读代码，确认需求范围。如果有歧义，先询问主人。
定位代码: 使用 grep 或 glob 查找相关文件。
制定计划: 思考修改方案，优先考虑不破坏现有逻辑的“加法”修改。
实施修改: 编辑代码，保持风格一致。
验证:
- 运行 flake8 检查语法错误。
- 运行 pytest 验证逻辑。
- 如果是脚本，尝试带 --help 或测试参数运行以确保无运行时错误。

遵循此指南，确保高效、安全地协助主人完成任务。