docs: 拆分超大文档——教程/参考分离，去过期版本横幅，模型枚举归并

- backtest_usage（742→485）：CLI 章移交 cli-backtest.md，示例/注意事项抽至 backtest-examples.md，重建目录 - quantitative-guide（628→325）：第 5-7 章（滑点/执行仿真/归因/工作流）抽至 quantitative-advanced.md 并重编号 - api_reference（704→478）：删除过期版本横幅（1.16.2）与快速开始教程段；数据模型/枚举与 field_mapping.md 逐表核对后去重（field_mapping 为唯一权威）； WebSocket 节随 web-api.md 合并移除 - field_mapping：吸收 MAC 协议枚举（Period/Adjust/Category/BoardType/ SortType/ExMarket），全部文档回到 ≤500 行 Co-Authored-By: Claude <noreply@anthropic.com>
2026-09-12 14:34:18 +08:00 · 2026-09-08 23:21:44 +08:00
parent 36b586b015
commit 990b4a7802
6 changed files with 581 additions and 838 deletions
@@ -21,15 +21,12 @@
  - [资金曲线](#资金曲线)
  - [交易记录](#交易记录)
  - [序列化输出](#序列化输出)
- [CLI 命令行](#cli-命令行)
-  - [内置策略列表（strategies）](#内置策略列表strategies)
-  - [参数网格寻优（optimize）](#参数网格寻优optimize)
-  - [组合级分析（portfolio）](#组合级分析portfolio)
+- [CLI 命令行](#cli-命令行) → 见 [cli-backtest.md](./cli-backtest.md)
 - [进阶用法](#进阶用法)
  - [预计算指标列](#预计算指标列)
  - [缠论结果注入](#缠论结果注入)
  - [自定义策略文件](#自定义策略文件)
- [完整示例](#完整示例)
+- [完整示例](#完整示例) → 见 [backtest-examples.md](./backtest-examples.md)

 ---

@@ -392,115 +389,10 @@ config = result.config

 ---

+
 ## CLI 命令行

-```bash
-# 基本用法
-easy-tdx backtest SZ 000001 --strategy-file my_strategy.py
-
-# 查看帮助
-easy-tdx backtest --help
-
-# 指定参数
-easy-tdx backtest SH 600519 \
-    --strategy-file ma_cross.py \
-    --cash 50000 \
-    --commission 0.0003 \
-    --execution next_open \
-    --period DAILY \
-    --count 500 \
-    --table
-
-# 预计算指标（MACD, KDJ 会作为额外列注入 DataFrame）
-easy-tdx backtest SZ 000001 \
-    --strategy-file macd_strategy.py \
-    --indicators MACD,KDJ
-
-# 输出 JSON（默认）
-easy-tdx backtest SZ 000001 --strategy-file my_strategy.py
-
-# 输出表格
-easy-tdx backtest SZ 000001 --strategy-file my_strategy.py --table
-```
-
-**CLI 参数**：
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `MARKET` | — | 市场代码：SZ / SH |
-| `CODE` | — | 股票代码：如 000001 |
-| `--strategy-file` | — | Python 策略文件路径 |
-| `--strategy` | — | DSL 表达式（P1，尚未实现） |
-| `--cash` | 100000 | 初始资金 |
-| `--commission` | 0.0003 | 佣金率 |
-| `--execution` | next_open | 成交价规则 |
-| `--period` | DAILY | K 线周期 |
-| `--adjust` | NONE | 复权方式：NONE / QFQ / HFQ |
-| `--count` | 500 | K 线数量 |
-| `--indicators` | — | 预计算指标（逗号分隔） |
-| `--table` | False | 表格输出 |
-| `--output` | json | 输出格式：json / table / csv |
-| `--wf` | False | 附加 Walk-Forward 样本外验证 |
-| `--wf-windows` | 7 | Walk-Forward 窗口数 |
-| `--evaluate` | False | 一条龙评估（回测+WF+适配性+评分+评级+基准对比） |
-| `--auto-fees` | False | 按标的品种自动解析费率 |
-
-### 内置策略列表（strategies）
-
-```bash
-# 表格列出全部内置策略（名称/参数/预设寻优网格）
-easy-tdx strategies
-
-# JSON 输出（含完整参数 schema，与 Web API GET /backtest/strategies 同构）
-easy-tdx strategies --output json
-```
-
-### 参数网格寻优（optimize）
-
-对注册表内置策略的 1-2 个参数做网格搜索，按总收益率排名：
-
-```bash
-# 单策略：用该策略的预设寻优网格（见 strategies 命令）
-easy-tdx optimize SZ 000001 --strategy ma_cross
-
-# 单策略：自定义网格（--param 参数名=值1,值2，可多次指定）
-easy-tdx optimize SZ 000001 --strategy ma_cross --param fast=5,10,15 --param slow=20,60
-
-# 一键寻优所有内置策略：逐策略按预设网格寻优后全局排名
-easy-tdx optimize SZ 000001 --all
-
-# 并行加速（2+ 进程级并行；1 = 串行 + 指标缓存复用）
-easy-tdx optimize SZ 000001 --all --workers 4
-```
-
-**optimize 参数**：
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `--strategy` | — | 注册表策略名（与 `--all` 二选一） |
-| `--all` | False | 一键寻优所有内置策略（STRATEGY_PRESETS 预设网格） |
-| `--param` | 预设网格 | 自定义参数网格，如 `fast=5,10,15`（最多 2 个参数，笛卡尔积 ≤ 200） |
-| `--cash` | 1000000 | 初始资金 |
-| `--commission` | 0.0003 | 佣金率 |
-| `--slippage` | 0.0 | 滑点 |
-| `--workers` | 1 | 并行进程数 |
-| `--top` | 15 | 表格输出显示前 N 行 |
-
-Python API 同名能力：`easy_tdx.backtest.optimizer.ParamGridOptimizer`（单策略）与
-`easy_tdx.backtest.optimizer.optimize_all_strategies`（一键全策略）。
-
-### 组合级分析（portfolio）
-
-```bash
-# 组合级 Walk-Forward 样本外验证（全部标的日期并集切窗，每窗独立开仓）
-easy-tdx portfolio --stocks SZ:000001,SH:600519     --strategy-file strategies/ma_cross.py --wf --wf-windows 7
-
-# 组合级一条龙评估：组合回测 + 组合WF + 跨标的适配性 + 综合评分
-# + 组合评级 + 等权买入持有基准对比（与 Web UI /portfolio 页同构）
-easy-tdx portfolio --stocks SZ:000001,SH:600519     --strategy-file strategies/ma_cross.py --evaluate
-```
-
---
+CLI 用法见 [cli-backtest.md](./cli-backtest.md)（回测/寻优/组合/run-all 命令与参数）。

 ## 进阶用法

@@ -591,152 +483,3 @@ easy-tdx backtest SZ 000001 --strategy-file my_strategy.py --table

 ---

-## 完整示例
-
-### 示例 1：双均线交叉策略
-
-```python
-"""双均线交叉策略：MA5 上穿 MA20 买入，下穿卖出。"""
-import pandas as pd
-from easy_tdx.backtest import BacktestEngine, Strategy, crossover
-from easy_tdx import MyTT
-
-
-class DualMACross(Strategy):
-    def init(self):
-        self.ma5 = self.I(MyTT.MA, self.data.close, 5)
-        self.ma20 = self.I(MyTT.MA, self.data.close, 20)
-        self.golden = crossover(self.ma5, self.ma20)
-        self.death = crossover(self.ma20, self.ma5)
-
-    def next(self):
-        if self.golden[self._bar_index] and self.position["size"] == 0:
-            self.buy(size=0)
-        elif self.death[self._bar_index] and self.position["size"] > 0:
-            self.sell(size=0)
-
-
-# 构造模拟数据（实际使用 TdxClient 获取）
-dates = pd.date_range("2024-01-01", periods=200, freq="D")
-import numpy as np
-rng = np.random.default_rng(42)
-close = 10.0 + np.cumsum(rng.normal(0, 0.2, 200))
-
-df = pd.DataFrame({
-    "datetime": dates,
-    "open": close + rng.uniform(-0.1, 0.1, 200),
-    "close": close,
-    "high": close + rng.uniform(0, 0.3, 200),
-    "low": close - rng.uniform(0, 0.3, 200),
-    "vol": rng.integers(10000, 100000, 200),
-})
-
-engine = BacktestEngine(DualMACross, cash=100000, commission=0.0003)
-result = engine.run(df)
-
-result.summary()
-print(f"\n年化收益: {result.performance['annual_return']:.2%}")
-print(f"夏普比率: {result.performance['sharpe']:.2f}")
-```
-
-### 示例 2：MACD 策略 + 预计算指标
-
-```python
-"""MACD 策略：DIF 上穿 DEA 买入，下穿卖出。"""
-from easy_tdx.backtest import BacktestEngine, Strategy, crossover
-from easy_tdx import MyTT
-
-
-class MACDStrategy(Strategy):
-    def init(self):
-        dif, dea, macd_hist = self.I(MyTT.MACD, self.data.close)
-        self.dif = dif
-        self.dea = dea
-        self.golden = crossover(dif, dea)
-        self.death = crossover(dea, dif)
-
-    def next(self):
-        if self.golden[self._bar_index] and self.position["size"] == 0:
-            self.buy(size=0)
-        elif self.death[self._bar_index] and self.position["size"] > 0:
-            self.sell(size=0)
-
-
-engine = BacktestEngine(MACDStrategy, cash=100000)
-result = engine.run(df)  # df 包含 OHLCV 数据
-```
-
-### 示例 3：布林带突破 + 滑点模拟
-
-```python
-"""布林带策略：跌破下轨买入，突破上轨卖出，模拟滑点。"""
-from easy_tdx.backtest import BacktestEngine, Strategy
-from easy_tdx import MyTT
-
-
-class BollingerBreakout(Strategy):
-    def init(self):
-        upper, mid, lower = self.I(MyTT.BOLL, self.data.close, 20)
-        self.upper = upper
-        self.lower = lower
-
-    def next(self):
-        cur = self.data.close[0]
-        if cur <= self.lower[self._bar_index] and self.position["size"] == 0:
-            self.buy(size=0)
-        elif cur >= self.upper[self._bar_index] and self.position["size"] > 0:
-            self.sell(size=0)
-
-
-# 模拟滑点和保守成交价
-engine = BacktestEngine(
-    BollingerBreakout,
-    cash=100000,
-    slippage=0.02,          # 每股 2 分钱滑点
-    execution="worst",      # 保守成交价
-    reject_policy="skip",   # 资金不足直接跳过
-)
-result = engine.run(df)
-```
-
-### 示例 4：从文件运行 CLI
-
-```python
-# save as rsi_strategy.py
-from easy_tdx.backtest import Strategy
-from easy_tdx import MyTT
-
-
-class RSIStrategy(Strategy):
-    """RSI 超卖超买策略。"""
-    def init(self):
-        self.rsi = self.I(MyTT.RSI, self.data.close, 14)
-
-    def next(self):
-        cur_rsi = self.rsi[self._bar_index]
-        if cur_rsi < 30 and self.position["size"] == 0:
-            self.buy(size=0)
-        elif cur_rsi > 70 and self.position["size"] > 0:
-            self.sell(size=0)
-```
-
-```bash
-easy-tdx backtest SZ 000001 \
-    --strategy-file rsi_strategy.py \
-    --cash 200000 \
-    --execution next_open \
-    --count 1000 \
-    --adjust QFQ \
-    --table
-```
-
---
-
-## 注意事项
-
-1. **DataFrame 格式要求**：必须包含 `datetime`, `open`, `close`, `high`, `low` 列。`vol`/`amount` 为可选但推荐。
-2. **成交时机**：默认 `next_open` 模式下，信号产生后需等待下一根 K 线才能成交。如果信号在最后一根 K 线产生，则无法成交。
-3. **整手交易**：A 股按 100 股整手交易。全仓模式会自动向下取整到 100 的倍数。
-4. **做空限制**：v1 不支持做空，卖出数量不能超过当前持仓。
-5. **未来函数警告**：使用 `this_close` 模式时，结果中的 `config.future_leak_warning` 会标记为 `True`。
-6. **多笔同 bar 交易**：引擎支持同一根 K 线上产生多笔交易（如分批建仓），按顺序依次撮合。