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

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

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

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

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

*   **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`。

## 3. 项目结构说明 (Project Structure)

*   **`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`: 自动交易主程序。

## 4. 开发规范 (Development Standards)

### 4.1 时区处理 (Timezone)
*   **存储**: 数据库中时间戳通常为 **UTC** 或 **ET (美东时间)**。
*   **展示**: 前端及日志输出必须转换为 **CST (北京时间)**。
*   **工具**: 使用 `api.models.convert_to_cst` 进行转换。

### 4.2 代码风格
*   **注释**: 必须使用**中文**解释“为什么这样做”。
*   **命名**: 变量/函数 `snake_case`，类名 `PascalCase`。
*   **类型提示**: 推荐在关键接口使用 Type Hints。

### 4.3 数据库操作
*   **禁止**使用 SQLite。
*   使用 `pymysql` 或 `sqlalchemy` 进行操作。
*   确保所有数据库连接都使用上下文管理器 (`with` 语句) 以自动关闭。

## 5. 测试与验证 (Testing & QA)

*   **运行测试**: `pytest`
*   **代码检查**: `flake8 .`
*   **本地验证**:
    *   修改 API 或前端后，运行 `./start_system.py` 并访问 `http://localhost:8000` 验证。
    *   修改模型后，运行 `python ensemble_predict.py` 验证预测逻辑。

## 6. 禁止事项 (Constraints)

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

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