crpto_predictor/AGENTS.md

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 相关代码。

---

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