# 使用与数据流

本文是当前代码的运行说明。历史特征实验不在这里维护；它们只用于追溯模型选择过程。

## 依赖

运行需要：

- Python 3 和本项目的虚拟环境；
- `pandas`、`numpy`、`scikit-learn`、`joblib` 等项目依赖；
- Go 和 `/data/ban/banbot` 源码；
- banbot 配置中的 TimescaleDB（优先）或 QuestDB 数据库，以及对 Binance 数据的访问。

一键脚本优先使用 `config/banbot.local.yml`，其次使用 banbot 同级 `data/config.timescale.yml` 或 `biz/config.timescale.yml` 中的 TimescaleDB 配置，最后使用 `biz/config.yml`。本机 banbot 目录会自动查找，也可通过 `--banbot-dir`、`--banbot-config`，或 `CBPRED_BANBOT_DIR`、`CBPRED_BANBOT_CONFIG` 环境变量指定。

`--dsn`（或 `CBPRED_DSN`）覆盖数据库连接；`--db-type timescale`（或 `CBPRED_DB_TYPE=timescale`）明确使用 TimescaleDB。自动检测优先选择 `exsymbol` 表对应的 TimescaleDB。Python 筛选、Go 下载和导出使用同一连接和数据库类型；连接失败会报错。只有 QuestDB 配置会尝试自动启动 QuestDB。

安装：

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```

## 一键更新与预测

```bash
./scripts/update_and_predict.sh
```

脚本调用 `python -m cbpred.latest_predict`，按以下顺序执行：

1. 检查所选数据库是否可连接；TimescaleDB 不可用时直接报错，QuestDB 配置可通过 banbot 的导出命令触发其启动流程。
2. 从数据库筛选 Binance `linear` 市场、结算币为 USDT、上市至少 730 天且未退市的品种。
3. 调用 banbot 下载最近 36 个月的 1H K 线。
4. 调用 banbot 读取 1H 历史，并按 UTC 边界聚合请求周期的完整 K 线；默认是 8H，也可以通过 `--timeframe 1d` 导出日线。缺少小时数据的周期会被排除。
5. 写入 `data/manifest.json` 和 `data/raw/*.csv`。
6. 加载 `artifacts/v1/model.joblib`，对清单中的每个品种使用最新完整 8H K 线预测。
7. 按最新 8H USDT 成交额降序写入 `predictions/latest_v1_8h/predictions.csv`，并写入 `report.json`。

分别生成 8H 和日线预测：

```bash
./scripts/update_and_predict.sh --timeframe 8h --db-type timescale
./scripts/update_and_predict.sh --timeframe 1d --db-type timescale
```

两个 CSV 分别位于 `predictions/latest_v1_8h/predictions.csv` 和 `predictions/latest_v1_1d/predictions.csv`。其中 `price_level_reached_80pct` 是预测的 80% 命中位置，`price_level_cap_80pct` 是回调上限参考位置。

脚本的默认参数可以覆盖：

```bash
./scripts/update_and_predict.sh \
  --banbot-dir /path/to/banbot \
  --banbot-config /path/to/config.yml \
  --data-dir data \
  --artifact artifacts/v1/model.joblib \
  --output-dir predictions/latest_v1_8h \
  --end 2026-08-23T00:00:00Z
```

`--end` 用于固定数据快照，支持 UTC 日期、ISO 时间或毫秒时间戳。默认按 `--timeframe` 向下取整到对应边界。

## 手动命令

### 准备数据

```bash
.venv/bin/python -m cbpred prepare \
  --banbot-config /data/ban/banbot/biz/config.yml \
  --out-dir data
```

只使用已经下载的数据：

```bash
.venv/bin/python -m cbpred prepare \
  --banbot-config /data/ban/banbot/biz/config.yml \
  --out-dir data \
  --skip-download
```

`prepare` 的默认范围是最近 36 个月，训练快照前的品种至少上市 730 天，最近 10 个月预留给测试。`manifest.json` 记录筛选出的品种、数据范围、数据库类型和被排除的原因。

导出日线时使用独立目录，避免覆盖 8H 快照：

```bash
.venv/bin/python -m cbpred prepare \
  --timeframe 1d \
  --out-dir data_1d \
  --banbot-config /data/ban/banbot/biz/config.yml
```

### 训练模型

```bash
.venv/bin/python -m cbpred train \
  --data-dir data \
  --artifact-dir artifacts/v1
```

训练会输出阶段和候选模型进度到 stderr，并在 `artifacts/v1/` 写入：

- `model.joblib`：当前可供预测的模型；
- `report.json`：机器可读的训练协议和评估指标；
- `report.md`：人类可读的评估摘要。

`--volatility-rank-threshold` 可以做 ATR 排名过滤实验。正式 `v1` 模型的阈值是 `0.0`，因此不会过滤低波动样本；`atr_rank_200_pct` 仍会作为当前状态字段输出。

### 单品种预测

```bash
.venv/bin/python -m cbpred predict \
  --artifact artifacts/v1/model.joblib \
  --csv data/raw/123_BTC_USDT_USDT.csv \
  --symbol BTC/USDT:USDT
```

不传 `--at` 时使用 CSV 中最新完整周期 K 线。传入 `--at` 时，时间必须精确匹配一个模型周期 K 线起始时间，且不能早于模型训练快照。

模型需要至少 200 根对应周期 K 线计算 ATR 排名，并需要模型中保存的该品种训练画像。`eligible_for_model` 为 `false` 时，预测数值返回空值，并包含 `skip_reason`。

## 文件布局

```text
cbpred/
├── cbpred/                         # Python CLI、特征和训练/预测管线
├── scripts/update_and_predict.sh  # 一键入口
├── data/
│   ├── manifest.json               # 数据快照和品种清单
│   └── raw/*.csv                   # 导出的 8H OHLCV
├── artifacts/
│   └── v1/                         # 唯一正式模型版本
└── predictions/
    └── latest_v1_8h/               # 最近一次 8H 批量预测
```

模型版本目录使用 `v1` 形式维护。历史实验可以保留在文档或实验输出目录中，但不应作为默认预测模型或在项目根目录新增多个 `artifacts_*` 入口。

## 故障排查

- `missing virtualenv Python`：先执行安装命令，确认 `.venv/bin/python` 存在。
- QuestDB 连接失败：检查 banbot 配置中的数据库地址、QuestDB 服务和端口；一键脚本只对默认 QuestDB 端口尝试触发 banbot 启动。
- `missing data/manifest.json`：先运行 `prepare`，或确认一键脚本没有在下载/导出阶段失败。
- 某品种预测为空：检查 `eligible_for_model` 和 `skip_reason`，通常是 200 根 ATR 历史不足或该品种没有正式模型画像。
- 数据只有部分 K 线：导出和训练会丢弃不连续或不完整的 bar，这是为了避免特征和未来标签跨越缺口。

## 验证

```bash
./scripts/update_and_predict.sh --help
.venv/bin/python -m unittest discover -q
git diff --check
```