这是一个面向加密货币微观结构研究的开源 Python 项目，聚焦复现并工程化实现论文《Explainable Patterns in Cryptocurrency Microstructure》的核心流程。

项目目标不是“展示单次回测收益”，而是提供一套可复现、可解释、可扩展的研究与回测框架：

- 本地市场数据加载与协议校验
- 1 秒级特征工程（盘口失衡、订单流、VWAP 偏离）
- CatBoost + Optuna 的滚动时间序列训练
- SHAP 可解释性分析
- Taker / Maker / Combined 回测
- 风险评估与结构化结果落盘

## 快速开始

### 1、环境准备

- Python `>=3.12`
- 推荐使用 `uv`

```bash
make init
```

### 2、运行一次完整流程（使用仓库内固定夹具）

```bash
uv run epcmbot \
  --input tests/fixtures/binance/roseusdt_20240115_1s.csv \
  --stdout-format markdown
```

### 3、输出 JSON 并保存 artifacts

```bash
uv run epcmbot \
  --input tests/fixtures/binance/roseusdt_20240115_1s.csv \
  --stdout-format json \
  --output-dir outputs \
  --output-prefix rose_demo
```

## 项目结构

```text
epcmbot/
  backtest.py          # Taker/Maker/Combined 回测引擎
  binance_dataset.py   # Binance 原始历史数据 -> EPCM 协议数据
  data.py              # 本地数据读取与协议校验
  explain.py           # SHAP 分析
  features.py          # 特征工程与目标构造
  main.py              # 主 CLI：epcmbot
  metrics.py           # 绩效指标（ARC/Sharpe/MDD/MLD/t-test 等）
  modeling.py          # CatBoost + Optuna 训练
  risk.py              # 风险条目输出
  schemas.py           # 配置与数据结构
  validation.py        # 时间序列切分器

tests/
  fixtures/binance/roseusdt_20240115_1s.csv
  fixtures/binance/README.md
  test_*.py

NOTE.md                # 研报策略解构与数学定义
PROGRESS.md            # 项目进度看板
```

## 输入数据协议

`epcmbot.data.load_market_frame` 默认要求以下字段：

| 字段 | 说明 |
|---|---|
| `timestamp` | 时间戳（UTC，秒级） |
| `symbol` | 标的代码 |
| `bid_price` | 最优买价 |
| `ask_price` | 最优卖价 |
| `bid_size` | 最优买量 |
| `ask_size` | 最优卖量 |
| `buy_volume` | 主动买成交量 |
| `sell_volume` | 主动卖成交量 |
| `buy_vwap` | 主动买成交 VWAP |
| `sell_vwap` | 主动卖成交 VWAP |

数据约束：

- 时间列严格递增，且默认要求秒级对齐。
- `ask_price >= bid_price`，且买卖价格必须为正。
- 关键数值列不可为空。

示例输入：

- `tests/fixtures/binance/roseusdt_20240115_1s.csv`

## CLI 使用指南

### 主流程 CLI：`epcmbot`

查看帮助：

```bash
uv run epcmbot --help
```

常用参数：

- `--input`：本地 CSV/Parquet 路径（必填）
- `--threshold`：信号阈值
- `--train-window`：训练窗口长度
- `--test-window`：测试窗口长度
- `--purge-window`：训练测试之间的清洗窗口
- `--optuna-trials`：Optuna 调参次数
- `--stdout-format {markdown,json}`：终端输出格式
- `--output-dir`：artifact 保存目录
- `--output-prefix`：artifact 文件前缀

### 数据构建 CLI：`epcmbot-build-dataset`

用于将 Binance 公共历史数据聚合为 EPCM 输入协议。该工具是**可选**组件，用于离线构造本地回测数据，不改变主流程“本地输入优先”的设计。

查看帮助：

```bash
uv run epcmbot-build-dataset --help
```

示例：生成 BTC 单日 1 秒数据

```bash
uv run epcmbot-build-dataset \
  --symbol BTCUSDT \
  --start-date 2024-01-15 \
  --end-date 2024-01-15 \
  --output data/btcusdt_20240115_1s.csv
```

示例：生成多日连续样本

```bash
uv run epcmbot-build-dataset \
  --symbol BTCUSDT \
  --start-date 2024-01-15 \
  --end-date 2024-01-20 \
  --output data/btcusdt_20240115_20240120_1s.csv \
  --cache-dir .cache/binance \
  --keep-raw
```

关键参数：

- `--symbol`：标的代码，如 `BTCUSDT`、`ETHUSDT`、`ROSEUSDT`
- `--start-date / --end-date`：日期区间（含首尾），格式 `YYYY-MM-DD`
- `--output`：输出路径，支持 `.csv` 或 `.parquet`
- `--market`：`um`（USD-M，默认）或 `cm`
- `--cache-dir`：原始 zip 缓存目录
- `--max-seconds`：可选，限制输出秒数（用于快速实验）
- `--keep-raw`：是否保留下载的原始 zip
- `--quiet`：关闭非关键日志输出
- `--no-progress`：关闭下载进度刷新

## 输出产物

传入 `--output-dir` 后，将保存以下文件（以 `rose_demo` 为例）：

- `rose_demo_summary.json`
- `rose_demo_summary.md`
- `rose_demo_fold_results.csv`
- `rose_demo_predictions.csv`
- `rose_demo_taker_equity.csv`
- `rose_demo_maker_equity.csv`
- `rose_demo_combined_equity.csv`
- `rose_demo_shap_importance.csv`
- `rose_demo_shap_dependence.csv`
- `rose_demo_risk_report.json`

## 测试与质量保证

运行测试（推荐命令）：

```bash
make test
```

静态检查与格式检查：

```bash
make fmt && make lint
```

## 研究边界与风险提示

- 主 CLI `epcmbot` 默认消费本地输入表，不直接在线拉数。
- `epcmbot-build-dataset` 会访问 Binance 公共历史数据源，仅用于离线构数。
- Maker 回测为工程保守近似，不是逐笔队列仿真。
- 仓库中的测试夹具用于验证流程与接口，不代表实盘可实现收益。

## 路线图

- 提升 `binance_dataset / main / risk` 模块测试覆盖率，目标总覆盖率 `>=85%`。
- 增加回测摩擦建模（延迟、滑点、成交约束）。
- 支持跨标的稳健性评估与更完整的实验监控面板。

## 贡献指南

欢迎通过 Issue / PR 参与共建。

1. Fork 仓库并创建分支。
2. 完成修改后运行：
   - `make test`
   - `make fmt`
   - `make lint`
3. 在 PR 描述中说明：动机、改动点、验证结果、潜在风险。

## 参考文档

- 研报复现说明：`NOTE.md`
- 项目进度看板：`PROGRESS.md`
- 原始论文材料：`paper/EPCM.1-24.md`

## 许可证

本项目采用 [MIT License](LICENSE)。