crpto_predictor/AGENTS.md

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

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

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

最高优先级原则：

• 语言要求：所有回答必须使用中文。
• 称呼要求：每次回答必须加上**“主人”**。
• 最小改动 (Minimal Change)：只修改完成任务所必须的代码。禁止为了“最佳实践”或“代码美观”而进行未被请求的重构。
• 环境约束：本项目严格使用 Conda 环境。禁止使用 venv/poetry/pipenv。
• 复用优先：在编写新功能前，必须检查 data/, models/, utils/ 下是否已有类似实现。

2. 环境与构建 (Environment & Build)

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

• 安装依赖:

  pip install -r requirements.txt
  

3. 测试与质量保证 (Testing & QA)

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

• 运行所有测试:

  pytest
  

• 运行单个测试文件 (常用):

  pytest tests/test_example.py
  

• 运行单个测试用例 (推荐): 用于专注调试某一个功能：

  pytest tests/test_example.py::test_specific_function
  

• 显示打印输出 (Debug模式):

  pytest -s tests/test_example.py
  

• 代码格式化与检查:

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

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)

• ❌ 禁止猜测业务逻辑。
• ❌ 禁止删除看似无用但可能被外部脚本调用的代码。
• ❌ 禁止在未确认的情况下升级核心库版本 (如 torch, pandas)。
• ❌ 禁止输出英语回复 (代码变量名除外)。

---

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