支持一键预测脚本

docs/usage.md

@@ -0,0 +1,134 @@
+# 使用与数据流
+
+本文是当前代码的运行说明。历史特征实验不在这里维护；它们只用于追溯模型选择过程。
+
+## 依赖
+
+运行需要：
+
+- Python 3 和本项目的虚拟环境；
+- `pandas`、`numpy`、`scikit-learn`、`joblib` 等项目依赖；
+- Go 和 `/home/ctyun/ban/banbot` 源码；
+- banbot 配置中的 QuestDB 数据库，以及对 Binance 数据的访问。
+
+默认配置文件是 `/home/ctyun/ban/banbot/biz/config.yml`。如果路径不同，可通过 `--banbot-config` 和 `--banbot-dir` 覆盖。也可以直接传入 `--dsn`。
+
+安装：
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## 一键更新与预测
+
+```bash
+./scripts/update_and_predict.sh
+```
+
+脚本调用 `python -m cbpred.latest_predict`，按以下顺序执行：
+
+1. 检查配置中的 QuestDB 是否可连接；QuestDB 默认不可用时，通过 banbot 的导出命令触发其启动流程。
+2. 从数据库筛选 Binance `linear` 市场、结算币为 USDT、上市至少 730 天且未退市的品种。
+3. 调用 banbot 下载最近 36 个月的 1H K 线。
+4. 调用 banbot 导出原始 K 线，并只保留连续完整的 8 根 1H K 线聚合成 8H K 线。
+5. 写入 `data/manifest.json` 和 `data/raw/*.csv`。
+6. 加载 `artifacts/v1/model.joblib`，对清单中的每个品种使用最新完整 8H K 线预测。
+7. 按最新 8H USDT 成交额降序写入 `predictions/latest_v1/predictions.csv`，并写入 `report.json`。
+
+脚本的默认参数可以覆盖：
+
+```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 \
+  --end 2026-08-23T00:00:00Z
+```
+
+`--end` 用于固定数据快照，支持 UTC 日期、ISO 时间或毫秒时间戳。默认使用当前 UTC 时间向下取整到 8H 边界。
+
+## 手动命令
+
+### 准备数据
+
+```bash
+.venv/bin/python -m cbpred prepare \
+  --banbot-config /home/ctyun/ban/banbot/biz/config.yml \
+  --out-dir data
+```
+
+只使用已经下载的数据：
+
+```bash
+.venv/bin/python -m cbpred prepare \
+  --banbot-config /home/ctyun/ban/banbot/biz/config.yml \
+  --out-dir data \
+  --skip-download
+```
+
+`prepare` 的默认范围是最近 36 个月，训练快照前的品种至少上市 730 天，最近 10 个月预留给测试。`manifest.json` 记录筛选出的品种、数据范围、数据库类型和被排除的原因。
+
+### 训练模型
+
+```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 中最新完整 8H K 线。传入 `--at` 时，时间必须精确匹配一个 8H K 线起始时间，且不能早于模型训练快照。
+
+模型需要至少 200 根 8H 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/                  # 最近一次批量预测
+```
+
+模型版本目录使用 `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 历史不足或该品种没有正式模型画像。
+- 数据只有部分 8H K 线：导出会丢弃不连续或不完整的 8 根 1H 桶，这是为了避免特征和未来标签跨越缺口。
+
+## 验证
+
+```bash
+./scripts/update_and_predict.sh --help
+.venv/bin/python -m unittest discover -q
+git diff --check
+```