# 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**

*   **安装依赖**:
    ```bash
    pip install -r requirements.txt
    ```

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

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

*   **运行所有测试**:
    ```bash
    pytest
    ```

*   **运行单个测试文件 (常用)**:
    ```bash
    pytest tests/test_example.py
    ```

*   **运行单个测试用例 (推荐)**:
    用于专注调试某一个功能：
    ```bash
    pytest tests/test_example.py::test_specific_function
    ```

*   **显示打印输出 (Debug模式)**:
    ```bash
    pytest -s tests/test_example.py
    ```

*   **代码格式化与检查**:
    ```bash
    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)。
*   ❌ **禁止**输出英语回复 (代码变量名除外)。

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