# CLAUDE.md

Binance 现货 + USDT-M 永续合约量化交易 CLI(Python 3.11+,Typer + pydantic)。包代码在 `src/binance_quant/`,CLI 入口为 `binance_quant.cli:app`。详细的状态机、数据字典和 AI 输入字段见 `README.md`;贡献规范见 `AGENTS.md`。

## 常用命令

```bash
python -m pip install -e ".[dev]"    # 安装(含 pytest)
python -m pytest                     # 全量测试(pyproject 已配 -q 和 pythonpath=src)
python -m pytest tests/test_cli.py   # 单文件迭代
binance-quant version                # 验证 CLI 已安装
```

CLI 子命令:`version`、`backtest`、`futures-backtest`、`orders`、`account`、`trade`、`sync-spot-trades`、`live-auto-buy-once`、`live-auto-sell-once`、`live-ai-trade-once`、`live-ai-trade-batch-once`、`live-futures-ai-trade-batch-once`。

`scripts/run.ps1` 和 `scripts/*.bat` 是 Windows 运维脚本(生产在 Windows 上跑);Linux 环境直接调用 `binance-quant` CLI。

## 架构

- 现货链路:`exchange.py`(REST/WS 客户端,多 REST 端点竞速选优)→ `strategy.py`(SMA 交叉)/ `market_data.py`(AI 市场特征)→ `risk.py` → `execution.py` → `storage.py` / `audit_log.py`(SQLite 审计,默认 `binance_quant.sqlite3`,每日限额和冷却期都靠它统计)
- 自动交易工作流:`auto_buy.py`(市价买 + OCO 止盈止损保护 + 失败回滚)、`auto_sell.py`、`ai_trader.py`(本地 `codex exec` 预测 → 本地风控 → 复用 auto_buy/auto_sell 执行)、`runner.py`(trade 循环)
- 合约链路(前缀 `futures_`):`futures_exchange.py`、`futures_risk.py`、`futures_execution.py`、`futures_ai_trader.py`、`futures_models.py`;要求账户单向持仓 + 逐仓保证金
- 成本与盈亏:`spot_cost_basis.py`、`spot_order_fills.py`、`spot_trade_sync.py`(同步 `/api/v3/myTrades` 到本地 `spot_trade_fills` 表)
- `backtest.py`:现货与合约回测引擎
- 设计文档按日期存放在 `docs/superpowers/plans/` 和 `docs/superpowers/specs/`;改行为前先查对应 spec

## 配置

- `config.py` 中单一 `Settings`(pydantic-settings):env 前缀 `BINANCE_`,读取 `.env`,`extra="ignore"`
- 三种模式:`dry_run`(默认,订单只本地记录)/ `testnet_live` / `live`;每个 live 功能有独立开关(`BINANCE_LIVE_AUTO_BUYER_ENABLED`、`BINANCE_LIVE_AUTO_SELLER_ENABLED`、`BINANCE_LIVE_AI_TRADER_ENABLED`、`BINANCE_LIVE_FUTURES_AI_TRADER_ENABLED` + `BINANCE_LIVE_FUTURES_CONFIRM_PRODUCTION`),默认全部关闭,不要绕过这些守卫
- 仓库中的 `.env` 被 git 跟踪,是配置项的实际清单(没有 `.env.example`);新增配置时同步更新 `.env` 注释和 `config.py`

## 约定与陷阱

- 金额一律用 `Decimal`;模块边界用显式领域模型,不传裸 dict;新模块加 `from __future__ import annotations`
- 测试:`tests/conftest.py` 的 autouse fixture 会清空所有 `BINANCE_*` 环境变量并禁用 `.env` 加载——每个测试只 monkeypatch 自己需要的变量;禁止真实 Binance 调用,用 fixture / monkeypatch / tmp_path
- 不要在日志输出 secret、签名 URL 或请求签名;`logs/ai_trader_llm.log` 会记录完整 AI prompt 和市场上下文(logs/ 已 gitignore)
- AI 只输出 BUY/SELL/HOLD 方向和置信度,永远不接收 API key、余额快照或审计记录;下单由本地风控 + 执行代码把关,不要把账户原始数据加进 AI 上下文
- live 命令退出码有语义:`rollback_failed`、`sell_failed` 等失败状态以非零退出码结束(见 `cli.py` 的 `_*_exit_code` 函数)
- AI `SELL` 只会自动取消本程序创建的保护性止损单(`clientOrderId` 前缀 `bqab-stop-`),其他开放卖单会阻止卖出
- 提交信息用 Conventional Commits(`feat:` / `test:` / `chore:`),祈使句;每个行为变更在 `tests/test_<feature>.py` 加测试