这是什么

不用写一行代码，直接说"帮我回测一下双均线上穿买入、下穿卖出，沪深300成分股，2019年至今"——本技能把口语化的策略思路自动转写为结构化策略 DSL，在本地完成回测，输出一份完整的策略诊断报告。

解决什么问题

• 有交易想法，但不会写回测代码，验证成本高
• 网上回测工具忽略 A 股 T+1、涨跌停不可成交、印花税、最低佣金等真实约束，结果失真
• 回测只有收益率一个数字，看不出风险、交易质量和改进方向

核心能力

1. 自然语言 → 策略 DSL：口语描述直接转结构化策略，支持双均线、布林带、唐奇安通道、MACD、RSI 等常见信号
2. 真实市场规则引擎：内置 A股/港股/美股/股指期货/加密永续的规则与成本档案（T+1、涨跌停不可成交、印花税、过户费、最低佣金、资金费率）
3. 全指标计算：收益、风险、交易质量三类指标一次性输出
4. 自包含 HTML 诊断报告：K线买卖点标注、权益曲线、回撤、月度收益热力图、相关性矩阵
5. 1–10 策略评分 + 迭代建议：给出可执行的下一步优化方向

快速开始（示例指令）

• "帮我把这个交易想法回测一下：20日均线上穿60日均线买入，反之卖出，标的贵州茅台，2020年至今"
• "用布林带策略回测沪深300 ETF，参数 20 日 ±2 倍标准差"
• "回测结果打几分？下一步怎么改进？"

常见问题

Q: 需要联网或 API Key 吗？
不需要外部付费 API。行情数据可配合同系列《析衡量化·A股数据获取》落地的本地 CSV 直接使用。

Q: 支持哪些市场？
A股、港股、美股、股指期货、加密货币永续合约，各市场规则与交易成本已分别内置。

Q: 回测结果可信吗？
已计入 T+1、涨跌停不可成交、印花税、过户费、最低佣金等真实约束；如需进一步检验过拟合风险，可配合同系列《析衡量化·回测过拟合诊断》做 PBO/DSR 检验。

Q: 输出什么格式？
单文件 HTML 报告（可直接浏览器打开）+ 评分与文字建议。

更新日志

• v1.1.0：补齐详情页与 FAQ；增强行情数据缺失时的降级提示与错误处理
• v1.0.1：Initial release

析衡量化 · 策略回测（xiheng-vibe-trading）

> vibe 交易策略回测 —— 把「我想这么交易」直接变成「这段想法到底赚不赚钱、为什么」。

核心闭环五步：

Describe ──▶ Generate ──▶ Backtest ──▶ Analyze ──▶ Iterate
（自然语言）  （策略 DSL）   （本地引擎）   （评分+发现）   （迭代建议）
      ▲                                                  │
      └────────────────── 反馈回路 ───────────────────────┘

与云端服务不同，本 skill 完全本地运行：无 API Key、无网络依赖（HTML 报告的图表库走 CDN，离线时数据与指标仍完整可用）。

一、适用场景

二、工作流（Agent 执行指引）

Step 1　把自然语言转成 spec

用户说的是想法，不是参数。按下面的映射把口语补齐为结构化字段，补齐的参数要显式告诉用户你填了什么：

先用 scaffold 起骨架再改，比从零写 JSON 更稳：

python scripts/vibe_trade.py scaffold --template bollinger_reversion --out my_strategy.json

Step 2　校验

python scripts/vibe_trade.py validate --spec my_strategy.json --data my_ohlcv.csv

会检查：字段完整性、指标能否构造、条件引用的操作数是否存在、做空与市场档案是否冲突。校验通过再跑回测。

Step 3　回测并出报告

python scripts/vibe_trade.py run \
  --spec my_strategy.json \
  --data my_ohlcv.csv \
  --html report.html \
  --json metrics.json \
  --trades trades.csv \
  --returns returns.csv        # 供 xiheng-backtest-overfit 复核过拟合

行情 CSV 必需列：date, open, high, low, close；可选 volume、benchmark（有 benchmark 才出基准对比与 alpha/beta）。

Step 4　解读与撰写

脚本已给出机器结论（评分卡 + 规则化发现）。Agent 的职责是基于这些数字写人话，而不是复述：

• 把 findings.observations 按重要性重排，先说致命问题
• 对每条「建议」给出具体改哪个字段、改成什么值
• 必须点明样本充分性：交易笔数 < 30 时，所有夏普/胜率都不可当结论用
• 提醒样本内结论不等于样本外有效，并主动建议送往 xiheng-backtest-overfit

Step 5　迭代

改一个变量、重跑、对比。不要一次改多个参数——那会把「改进」和「过拟合」混在一起。建议在对话中维护一张改进对照表（版本 / 改动 / 累计收益 / 夏普 / 回撤 / 评分）。

三、策略 DSL 速查

一份完整 spec 的结构：

{
  "name": "策略名",
  "description": "一句话说明交易逻辑",
  "market":  { "profile": "cn_equity", "symbol": "600XXX", "interval": "1d" },
  "indicators": {
    "ma_fast": { "type": "sma",  "source": "close", "period": 50 },
    "ma_slow": { "type": "sma",  "source": "close", "period": 200 }
  },
  "entry": { "mode": "all", "long":  [ { "left": "ma_fast", "op": "cross_above", "right": "ma_slow" } ] },
  "exit":  { "mode": "all", "long":  [ { "left": "ma_fast", "op": "cross_below", "right": "ma_slow" } ] },
  "filters": [ { "left": "rsi14", "op": "lt", "right": 70, "side": "long" } ],
  "risk":  { "size_pct": 100, "leverage": 1, "stop_loss_pct": 5,
             "take_profit_pct": 0, "max_holding_bars": 0, "allow_short": false },
  "costs": { "commission_bps": 2.5, "slippage_bps": 5, "stamp_tax_bps": 5 },
  "backtest": { "initial_capital": 1000000 }
}

• 条件操作符：gt gte lt lte eq cross_above cross_below rising falling between
• 操作数可以是：已声明指标名 / 行情列名（close volume）/ 数字常量 / [下界, 上界]（between）
• mode：all（默认，全部满足）或 any（任一满足）
• 指标类型全量清单：python scripts/vibe_trade.py list-indicators

详细字段语义、口语→DSL 映射范例见 references/strategy_dsl.md。

四、市场档案（决定成本与交易规则）

python scripts/vibe_trade.py list-profiles

market 块里的字段会覆盖档案默认值，例如 {"profile":"cn_equity","price_limit_pct":20} 用于科创板。

五、子命令

内置模板：dual_ma（双均线趋势）、bollinger_reversion（布林带均值回归）、cn_breakout（唐奇安通道突破，含 A 股规则）。

六、开箱自测（无需外部数据）

cd <skill 目录>
python scripts/make_sample_data.py          # 生成三份示例行情（幂等，可重复执行）

# 趋势型品种 · 双均线
python scripts/vibe_trade.py run --spec assets/spec_dual_ma.json \
  --data assets/sample_ohlcv_1h.csv --html report_1.html

# 震荡型品种 · 布林带均值回归
python scripts/vibe_trade.py run --spec assets/spec_bollinger_reversion.json \
  --data assets/sample_ohlcv_range_1h.csv --html report_2.html

# A 股规则仿真 · 唐奇安突破
python scripts/vibe_trade.py run --spec assets/spec_cn_breakout.json \
  --data assets/sample_ohlcv_daily.csv --html report_3.html

三份示例的定位：

教学要点：把布林带策略跑到趋势型样本上（--data assets/sample_ohlcv_1h.csv），会得到累计 −36% 的结果——不是引擎有问题，而是策略与市场状态不匹配。这是本工具最想让人记住的一课。

七、与同系列 skill 联动

> 本技能属于 析衡量化 系列，统一入口见 xiheng-quant-toolkit：
> series.py list 看系列全景，series.py route <场景> 定位技能，series.py chain <场景> 看整条调用链。

> 系列地图维护在 xiheng-quant-toolkit/assets/series.json；本技能在该地图中的条目（slug/stage/role/feeds/triggers）应保持同步。

八、注意事项（回测的八个常见失真）

1. 成本不能置零。custom 档案仅用于研究对比；给用户结论时一律用真实档案。
2. 样本太短不能下结论。交易笔数 < 30 时评分卡会自动打折，Agent 也必须口头声明。
3. 信号在收盘计算、次根开盘成交。引擎已内置 1 根 bar 延迟，不要用「当根收盘成交」的乐观假设去解释结果。
4. T+1 与涨跌停已建模，但涨跌停只判断开盘是否封板，未模拟封板中途打开。
5. 未建模：融券券源可得性、冲击成本随规模变化、停牌、除权除息。涉及这些场景需人工调整。
6. max_holding_bars 单位是 bar，不是自然日。
7. 不要用同一段数据既调参又评估。参数扫描后必须留样本外区间，否则必然高估。
8. 本工具输出的是统计可信度判断，不预测未来收益，不构成投资建议。

九、目录结构

xiheng-vibe-trading/
├── SKILL.md
├── scripts/
│   ├── vibe_trade.py          # 主程序：CLI + 回测引擎 + 指标 + 评分卡 + 发现引擎
│   ├── indicators.py          # 指标库（30+ 类型，纯 numpy/pandas）
│   ├── market_profiles.py     # 市场规则与成本档案
│   ├── report.py              # 自包含 HTML 报告生成器
│   └── make_sample_data.py    # 示例行情生成器（固定种子）
├── references/
│   ├── strategy_dsl.md        # DSL 完整字段语义 + 口语→DSL 映射范例
│   ├── metric_playbook.md     # 指标判读阈值、评分卡口径、诊断决策树
│   └── market_rules.md        # 各市场交易规则与成本建模细节
└── assets/
    ├── spec_dual_ma.json              # 双均线趋势（趋势型）
    ├── spec_bollinger_reversion.json  # 布林带均值回归（震荡型）
    ├── spec_cn_breakout.json          # 唐奇安突破（A 股规则）
    ├── sample_ohlcv_1h.csv            # 趋势型 1h × 8760
    ├── sample_ohlcv_daily.csv         # 趋势型日线 × 1200（含 benchmark）
    └── sample_ohlcv_range_1h.csv      # 震荡型 1h × 4380

依赖：Python 3.10+、pandas、numpy。无其他第三方依赖。

本 skill 为量化研究工具，输出结果不构成任何投资建议。历史回测表现不代表未来收益。