desic-okx-agent 0.2.1 → 0.3.0

package/docs/strategy-research.md

@@ -0,0 +1,597 @@
+# 策略研究使用指南
+
+用 Python 写策略，在本地 OKX 1 分钟历史数据上回测、调参、对比。
+
+三种入口，能力相同：
+
+| 入口 | 适合 |
+| --- | --- |
+| 交互界面 `desic-okx` | 人手操作。斜杠命令 + 参数提示，不需要记命令 |
+| CLI `desic-okx strategy ...` | 脚本、CI、批量任务 |
+| MCP 工具 | 交给 AI agent 使用 |
+
+界面语言用 `/lang zh` 或 `desic-okx lang zh` 切换，命令说明和提示都会跟着变。工具名、字段名、错误码保持英文 —— 复制出来的信息仍能对应 API。
+
+---
+
+## 目录
+
+- [五分钟跑通第一次回测](#五分钟跑通第一次回测)
+- [准备 Python 环境](#准备-python-环境)
+- [准备数据](#准备数据)
+- [写策略](#写策略)
+- [回测](#回测)
+- [回测参数](#回测参数)
+- [读结果](#读结果)
+- [参数调优](#参数调优)
+- [对比多次回测](#对比多次回测)
+- [下一步：接实盘](#下一步接实盘)
+- [给 AI agent 用](#给-ai-agent-用)
+- [常见问题](#常见问题)
+- [必须知道的限制](#必须知道的限制)
+
+---
+
+## 五分钟跑通第一次回测
+
+```bash
+desic-okx strategy env --setup                              # 一次性：准备 Python 环境
+desic-okx data download --inst BTC-USDT-SWAP --days 90      # 下载 90 天 1 分钟数据
+desic-okx strategy new --out ema.py --template ema-trend    # 生成策略模板
+desic-okx strategy validate --file ema.py                   # 静态校验
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 30 --follow
+```
+
+最后一步会打印运行 ID 和完整指标。想看权益曲线和成交明细：
+
+```bash
+desic-okx strategy report --run bt_xxxx --open
+```
+
+交互界面里是同一套流程：
+
+```
+$ desic-okx
+
+> /env setup
+> /download BTC-USDT-SWAP 90
+> /new ema.py ema-trend
+> /validate ema.py
+> /backtest ema.py BTC-USDT-SWAP 30
+> /report bt_xxxx
+```
+
+---
+
+## 准备 Python 环境
+
+策略是 Python 代码，需要 Python 3.11 以上，以及 numpy 和 pandas。
+
+```bash
+desic-okx strategy env            # 检查
+desic-okx strategy env --setup    # 在数据目录下建 venv 并装依赖
+```
+
+`--setup` 的镜像回退链是 **清华 → 阿里 → PyPI**，逐个尝试。单一镜像会因为 403 直接卡死，所以不做单点依赖。
+
+`desic-okx doctor` 里也有一节 Python 环境状态。
+
+---
+
+## 准备数据
+
+**只存 1 分钟数据。** 3m / 15m / 1H / 1D 等全部由 1 分钟合成，所以只需要下载这一种。TS 侧和 Python 侧各有一份聚合实现，用同一组 fixture 交叉验证，保证回测和图表看到的高周期完全一致。
+
+```bash
+desic-okx data list                                        # 本地全部合约 + 覆盖区间
+desic-okx data coverage --inst BTC-USDT-SWAP               # 单个合约的区间与缺口
+desic-okx data download --inst BTC-USDT-SWAP --days 90
+desic-okx data download --inst BTC-USDT-SWAP --from 2026-01-01 --to 2026-06-30
+```
+
+`download` 只请求缺失的分钟，重复执行是安全的。
+
+### 回测前先查缺口
+
+```bash
+desic-okx data coverage --inst BTC-USDT-SWAP
+```
+
+`missingCount` 大于 0 说明区间里有洞。**回测遇到洞会直接失败，不会跳过那一分钟** —— 因为在有缺口的时间线上跑出来的收益，对应的是一段从未发生过的行情。先用 `download` 补齐。
+
+`exhaustedBefore` 表示 OKX 再往前已经没有数据了，继续请求更早的历史不会有结果。
+
+**注意 `missingCount` 只统计已存区间 `oldestOpen ~ newestOpen` 内部的缺口。** 它为 0 并不代表你要回测的区间是完整的 —— 如果回测窗口延伸到 `newestOpen` 之后（数据是几小时前下的，而你要跑"最近 30 天"），那一段根本还没入库，`coverage` 看不到它，但回测会失败。
+
+所以更可靠的做法是：**回测前先跑一次 `download`。** 它只请求缺失的分钟，已经有的不会重复拉：
+
+```bash
+desic-okx data download --inst BTC-USDT-SWAP --days 30
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 30 --follow
+```
+
+### 时间一律按 UTC
+
+```bash
+--from 2026-08-13                 # 当天 00:00 UTC
+--from 2026-08-13T07:12:00Z       # 精确到分钟，UTC
+--from 2026-08-13T07:12:00+08:00  # 带偏移量，会换算成 UTC
+--from 2026-08-13T07:12           # 报错：缺时区
+```
+
+最后一种会被拒绝，而不是当成本地时间。带时钟时间却不带时区的话，`Date.parse` 会按机器时区平移 —— 结果是一份看起来合理、但别人无法复现的报告。
+
+---
+
+## 写策略
+
+```bash
+desic-okx strategy new --out ema.py --template ema-trend
+```
+
+四个模板：`blank`、`ema-trend`、`atr-breakout`、`bollinger-reversion`。
+
+### 最小结构
+
+```python
+def on_bar(ctx):
+    fast = ctx.indicators.ema(ctx.instrument_id, "1m", int(ctx.params.get("fastPeriod", 20)))
+    slow = ctx.indicators.ema(ctx.instrument_id, "1m", int(ctx.params.get("slowPeriod", 60)))
+    if fast is None or slow is None:
+        return ctx.no_action("指标预热中")
+
+    position = ctx.portfolio.position(ctx.instrument_id, "long")
+    if position is None and fast > slow:
+        return ctx.open_long("快线上穿慢线")
+    if position is not None and fast < slow:
+        return ctx.close_long("快线下穿慢线")
+    return ctx.no_action("持仓不变")
+```
+
+要点：
+
+- `on_bar(ctx)` 必需，每根已确认的 1 分钟收线调用一次
+- **一根 K 线只返回一个动作**
+- 动作是意图，**不含张数** —— 张数由主机按预算和合约规则换算
+- `on_start(ctx)` 可选，只做初始化，必须返回 `no_action`
+
+### 动作集
+
+```python
+ctx.no_action(reason)
+ctx.open_long(reason, protection=None, execution=None)
+ctx.open_short(reason, protection=None, execution=None)
+ctx.close_long(reason, execution=None)
+ctx.close_short(reason, execution=None)
+ctx.cancel_order(order_id, reason)
+```
+
+附带止损止盈，价格是绝对价：
+
+```python
+return ctx.open_long("突破", protection={"stopLossPrice": 67000.0, "takeProfitPrice": 71000.0})
+```
+
+指定限价单：
+
+```python
+return ctx.open_long("挂单等回踩", execution=ctx.limit_order(67500.0))
+```
+
+### 成交时机
+
+- **市价动作在下一根 1 分钟开盘成交。** 决策在收线时做出，不可能用收盘价本身成交
+- **限价动作挂单，后续 K 线保守撮合**：买单要求最低价严格穿到限价下方，卖单要求最高价严格穿到上方；单根 K 线最多成交其成交量的 10%
+- 反手必须显式先平后开。持多仓时直接 `open_short` 会报错，不会自动翻仓
+
+### 校验规则
+
+```bash
+desic-okx strategy validate --file ema.py
+```
+
+毫秒级返回，带行号。**每次改完都跑一次** —— 比排队跑完回测才发现 import 违规划算得多。
+
+- 允许的 import：`collections` `dataclasses` `math` `numpy` `pandas` `statistics` `typing`
+- 禁用：`getattr` `setattr` `eval` `exec` `open` `__import__`、dunder 访问、async 处理函数、生成器
+
+`getattr` 被禁是刻意的：用它探测字段拼写会把协议不匹配藏起来，而这种问题应该当场报错。**直接用文档里的字段名。**
+
+### 多周期
+
+```bash
+desic-okx strategy backtest --file s.py --inst BTC-USDT-SWAP --intervals 30m,1H
+```
+
+```python
+buckets = ctx.market.bars(ctx.instrument_id, "30m", lookback=2)
+if not buckets[-1].confirmed:
+    return ctx.no_action("等 30m 收线")
+```
+
+注意：`ctx.indicators` 只接受 `1m`。高周期的当前桶在确认前还可能被修正，用它做增量指标状态，缓存值会悄悄依赖于"第一次算的时间点"。
+
+### 看不到未来
+
+`ctx.market.bars()` 只暴露到当前可见长度，物理上取不到之后的 K 线。任何可见 K 线的 `closeTime ≤ ctx.as_of_ms`。测试里专门构造了"能看到未来就会盈利"的策略，断言它无法盈利。
+
+---
+
+## 回测
+
+```bash
+# 最近 30 天
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 30
+
+# 指定区间，前台等待并打印报告
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP \
+  --from 2026-07-01 --to 2026-08-01 --follow
+
+# 带参数
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP \
+  --params params.json --intervals 30m
+```
+
+`params.json` 就是普通的 JSON 对象，对应 `ctx.params`：
+
+```json
+{ "fastPeriod": 20, "slowPeriod": 60 }
+```
+
+交互界面：
+
+```
+> /backtest ema.py BTC-USDT-SWAP 30
+> /backtest ema.py BTC-USDT-SWAP 2026-07-01..2026-08-01
+```
+
+第三个参数同时接受天数和区间。`..` 任一侧可省略：`2026-07-01..` 表示从该日至今。
+
+### 长任务是异步的
+
+不带 `--follow` 时立即返回运行 ID，用 `strategy report` 或 `/report` 查看。**调用返回不等于回测跑完** —— 状态是 `completed` 才有指标可读。
+
+```bash
+desic-okx strategy runs --limit 20
+desic-okx strategy cancel --run bt_xxxx
+desic-okx strategy delete --run bt_xxxx --yes
+```
+
+### 预热 K 线
+
+`--from/--to` 界定的是**评估区间**。`--preload`（默认 120）根 K 线加载在评估起点**之前**，只用于指标预热，**不计入任何统计** —— 不产生权益点、不产生成交、不算收益。
+
+指标需要预热期，如果拿评估区间开头的 K 线去暖机，那段时间的结果就不可信了。
+
+---
+
+## 回测参数
+
+所有回测共用一份保存在磁盘上的参数：
+
+```bash
+desic-okx strategy settings                                   # 查看
+desic-okx strategy settings set leverage=5 budget-pct=0.1     # 修改
+desic-okx strategy settings reset                             # 恢复默认
+```
+
+交互界面里 `/settings` 或 `/backtest setting` 打开表单（`↑↓` 移动，`⏎` 编辑，`s` 保存）。
+
+| 参数 | 默认 | 范围 | CLI 覆盖 |
+| --- | --- | --- | --- |
+| 初始权益 (USDT) | 10,000 | 1 ~ 1亿 | `--equity` |
+| 杠杆 | 10 | 1 ~ 125 | `--leverage` |
+| 保证金安全系数 | 1 | 1 ~ 20 | `--margin-safety` |
+| 单笔预算比例 | 20% | 0.1% ~ 100% | `--budget-pct` |
+| 单笔固定预算 (USDT) | 0（表示用比例） | 0 ~ 1亿 | `--budget-usdt` |
+| Taker 手续费 | 5 bps | 0 ~ 100 bps | `--taker-fee` |
+| Maker 手续费 | 2 bps | 0 ~ 100 bps | `--maker-fee` |
+| 入场滑点 | 1 bps | 0 ~ 1000 bps | `--entry-slippage` |
+| 出场滑点 | 1 bps | 0 ~ 1000 bps | `--exit-slippage` |
+| 预热 K 线 | 120 | 2 ~ 20000 | `--preload` |
+| 默认评估天数 | 30 | 1 ~ 365 | `--days` |
+| 期末平仓 | 开 | — | `--close-at-end` |
+
+命令行上传的参数只覆盖本次运行，不写入磁盘。超范围的值会被**拒绝而不是截断** —— 悄悄跑一个与你要求不同的回测，等于让错误的假设变得不可见。
+
+**每次运行都会记录它实际用的全部参数**，在报告的"本次回测参数"一节里。参数可能在两次运行之间被改过，一份说不清自己假设的报告，跟任何其他报告都不可比。
+
+仓位规模来自交易所报告的合约规格（`ctVal`、`ctMult`、`lotSz`、`minSz`），不做猜测。拿猜出来的合约面值算仓位，会得到一份数字全都合理、但规模差了一个倍数的报告。
+
+---
+
+## 读结果
+
+```bash
+desic-okx strategy report --run bt_xxxx                # 终端指标
+desic-okx strategy report --run bt_xxxx --open         # 浏览器完整报告
+desic-okx strategy report --run bt_xxxx --equity --trades
+```
+
+HTML 报告完全自包含：所有资源内联，不在打开时请求任何网络，因此可离线查看、可随运行一起归档，也不会把策略内容发到任何地方。内容包括权益曲线（带回撤带、悬停读数）、按月表现、盈亏分布、全部成交明细。
+
+### 几个容易误读的指标
+
+- **年化收益 / 卡玛**：评估区间短于 30 天时**不给**。五天的窗口外推出来是五位数百分比，看着像精度其实是噪声，而任何基于它的比率都会继承这份噪声
+- **盈亏比 / 胜率**：按**扣除手续费后**的单笔盈亏计算。用毛利算的话，一个权益实际在下跌的高频策略也能报出大于 1 的盈亏比
+- **手续费占毛利比例**：超过 100% 意味着仅手续费就把一个有效信号吃成了亏损。这是"看起来合理的策略却亏钱"最常见的原因
+- **保证金耗尽**：这是研究用的风险边界，**不是 OKX 强平价格的估算**
+
+### 可复现性
+
+每次运行记录一个 `dataSnapshotId`，其哈希覆盖消费的每一根 K 线。相同请求 + 未变动的数据 = 相同 ID + 相同指标。ID 不同就说明底层数据变了。
+
+---
+
+## 参数调优
+
+**不要用"跑一批回测挑最好的"这种做法。** 在任何一段窗口上，最好的参数总有一部分是拟合了这段行情的噪声；用挑出它的那批 K 线去衡量它，不构成证据。
+
+`strategy optimize` 把窗口按 **7:3** 切分：在前 70% 搜索，用后 30% 排名 —— 后者是候选从未见过的。
+
+```bash
+desic-okx strategy optimize --file ema.py --inst BTC-USDT-SWAP \
+  --space space.json --params params.json \
+  --from 2026-05-01 --to 2026-08-01 --budget 100 --follow
+```
+
+`space.json` 声明每个参数的搜索范围：
+
+```json
+{
+  "fastPeriod": { "min": 5,  "max": 50,  "step": 5 },
+  "slowPeriod": { "min": 20, "max": 200, "step": 10 }
+}
+```
+
+`--params` 传策略自身的默认参数。**空间里的每个键都会用它校验**：声明一个策略不读的参数会被拒绝 —— 否则所有候选行为完全一致，排第一的只是噪声。
+
+### 采样
+
+组合数超过预算时做确定性采样（拉丁超立方），保证：
+
+- **每个参数的每个取值至少被评估一次。** 从没试过 `slowPeriod: 200` 的搜索，没资格对它下任何结论
+- **相同请求 → 相同候选集。** 种子由请求本身派生，重跑可复现，而不是重新抽一次奖
+
+预算小于最宽参数的取值个数时会**拒绝**，因为覆盖保证在算术上不可能成立。
+
+### 限制
+
+| 项 | 限制 |
+| --- | --- |
+| 空间组合数 | ≤ 5,000 |
+| 候选预算 | 2 ~ 1,000，默认 100 |
+| 每段最少 K 线 | 1,440（因此窗口至少 7 天） |
+
+组合数上限是刻意的：三个参数各 10 个取值就是 1,000 个候选，而每个都要模拟两次。直接拒绝比启动一个要跑几小时的任务有用。
+
+### 读候选表
+
+```bash
+desic-okx strategy optimize-report --run opt_xxxx --top 20
+```
+
+```
+#   fastPeriod  slowPeriod  训练收益  验证收益  训练回撤  验证回撤  成交笔数  结论
+1   40          150         -28.62%   +21.77%   29.81%    8.73%     50        稳健
+2   40          180         -27.95%   +22.33%   29.34%    10.35%    39        稳健
+20  10          60          -57.30%   -4.94%    58.03%    21.92%    150       偏弱
+```
+
+**应当引用的是验证段。** 训练段数字描述的是"在挑选它的那批 K 线上"的表现，不是证据，不能当作结果报出去。
+
+两列都显示是刻意的 —— 差距本身就是结论：
+
+| 结论 | 含义 |
+| --- | --- |
+| `稳健` | 两段都盈利，且验证段保住了训练段收益的相当一部分 |
+| `过拟合` | 被挑选时盈利，之后不盈利或衰减严重 |
+| `偏弱` | 两段都不盈利 |
+| `无从解释` | 训练段不盈利，验证段盈利 |
+
+`无从解释`需要单独解释一下。它不是"更好的稳健" —— **恰恰相反**：训练段没有优势，也就没有任何东西被带过切分点，验证段的盈利来自那段行情本身的走法。切分要防的正是这种推理。这类候选仍然参与排名（得分就是得分），但它不构成"这组参数有效"的证据。
+
+**整张表都是`无从解释`时，问题在窗口，不在策略。** 实测一次 30 天 BTC-USDT-SWAP 搜索，20 个候选全部训练段亏、验证段赚 33~36% —— 因为那 9 天是一段单边上涨，只做多的策略几乎无法错过。此时该做的是换一段包含涨、跌、震荡的窗口重搜，而不是从表里挑第一名。
+
+排名依据会一并说明：验证段足够长时用**卡玛**，不足 30 天时退回**验证收益 / 最大回撤**，若无回撤则用**验证收益**。这一栏不总是同一个量，所以标注出来 —— 一个有时表示别的东西的"卡玛"列，比一个诚实的标签更糟。
+
+### 第一名的数字仍然偏乐观
+
+用验证段得分从 N 个候选里挑第一，本身就是在挑高分。切分消除了大部分偏差，但没有全部消除，剩余部分随预算增大。**要真正干净的估计，需要一段比整个搜索窗口更晚的数据。**
+
+### 采用最佳参数
+
+```bash
+desic-okx strategy optimize-report --run opt_xxxx --adopt ema.params.json
+```
+
+写到策略**旁边**的 `<策略名>.params.json`，**不改策略源码** —— 源码是你写的，工具不该改写它。
+
+然后用这组参数单独跑一次回测确认：
+
+```bash
+desic-okx strategy backtest --file ema.py --params ema.params.json \
+  --inst BTC-USDT-SWAP --from <验证段起点> --to <验证段终点> --follow
+```
+
+指标应当与候选表里的验证段完全一致。注意这次确认覆盖的仍是搜索用过的同一段时间。
+
+交互界面里，`/optimize` 会自动读取策略旁边的 `<策略名>.params.json` 作为默认参数：
+
+```
+> /optimize ema.py BTC-USDT-SWAP 2026-05-01..2026-08-01 space.json 100
+> /optimize report opt_xxxx
+> /optimize report opt_xxxx --adopt ema.params.json
+```
+
+---
+
+## 对比多次回测
+
+```bash
+desic-okx strategy compare --runs bt_aaa,bt_bbb              # 终端表格
+desic-okx strategy compare --runs bt_aaa,bt_bbb --open       # 浏览器叠加图
+```
+
+```
+> /compare bt_aaa bt_bbb
+> /compare bt_aaa bt_bbb --no-open
+```
+
+2 到 6 个运行。输出包括指标矩阵、**只显示有差异的参数**（相同的折叠成一行计数）、以及权益曲线叠加。
+
+### 曲线归一化
+
+曲线按各自起点归一化到 100。两个初始权益不同的运行放在同一坐标轴上，余额大的那条单纯画得更高 —— 这跟策略好坏无关。
+
+### 警告要先看
+
+这才是 `/compare` 作为一个命令存在的理由，而不是简单读两份报告。**两次用了不同数据、不同合约、不同区间或不同成本的运行，不是同一个问题的两个答案** —— 而这一点在指标里完全看不出来。
+
+| 警告 | 含义 |
+| --- | --- |
+| 数据不同 | 消费的 K 线不同。任何差异都可能来自数据本身 |
+| 合约不同 | 收益反映的是各自市场的涨跌 |
+| 区间不同 | 各项合计覆盖的时间长度不一样 |
+| 参数不同 | 杠杆、手续费、滑点或预算不同 |
+| 未完成 | 有运行没跑完，没有指标 |
+
+出现警告时仍然允许对比 —— 有时那个差异正是你要考察的东西。但结论里要说清是哪一项不同，而不是直接宣布赢家。
+
+**只有当所有运行共享同一个 `dataSnapshotId`、同一个合约、同一个区间、同一套成本时**，对比才构成"A 策略优于 B"的证据。
+
+策略参数会展开成 `params.fastPeriod` 这样的单独行。参数是两次运行最常见的差异来源，挤在一个 JSON 里就得靠肉眼比对两串字符串 —— 偏偏是最关键的那个值。
+
+---
+
+## 下一步：接实盘
+
+回测和调参不是终点，是**启用实盘的前置条件**。同一个策略文件可以直接绑到账户上，每根 1 分钟收线自动执行：
+
+```bash
+# 行情先切模拟盘(模拟盘与实盘是两套独立行情,价格不同)
+desic-okx market env demo
+desic-okx data download --inst BTC-USDT-SWAP --days 30
+
+# 用模拟盘数据回测一次 —— 启用按"源码 hash + 合约"匹配回测记录
+desic-okx strategy backtest --file ema.py --params ema.params.json \
+  --inst BTC-USDT-SWAP --days 30 --follow
+
+# 建 Profile(创建绝不会开始交易)
+desic-okx live create --file ema.py --params ema.params.json \
+  --inst BTC-USDT-SWAP --account demo --environment demo \
+  --entry-budget 100 --side-budget 200 --daily-loss 500
+
+desic-okx live readiness --id lp_xxxx
+desic-okx live start --id lp_xxxx
+```
+
+两个衔接点值得注意：
+
+- **回测记录按源码 hash 匹配，不是文件名。** 改一个字符就得重跑，因为旧记录描述的不再是这份策略。
+- **换环境要重跑回测。** 模拟盘和实盘的 K 线来自两个独立市场，实盘 Profile 需要用实盘数据跑过的回测。
+
+回测里的成交是模拟撮合，实盘是真实报单 —— 滑点、拒单、部分成交都会出现在回测看不到的地方。完整说明见 **[实盘执行使用指南](live-trading.md)**。
+
+---
+
+## 给 AI agent 用
+
+MCP 工具（`desic-okx setup` 会自动为 Codex 和 Claude Code 装好）：
+
+| 工具 | 用途 |
+| --- | --- |
+| `data_list_instruments` | 本地全部合约与覆盖区间 |
+| `data_coverage` | 单合约区间、根数、缺口列表 |
+| `data_download` | 下载或补齐指定区间 |
+| `strategy_validate_source` | 静态校验，带行号 |
+| `strategy_run_backtest` | 入队，立即返回 `runId` |
+| `strategy_run_optimize` | 参数搜索，入队 |
+| `strategy_get_optimization` | 排名后的候选表，含训练/验证指标 |
+| `strategy_compare_runs` | 多运行对比，含差异参数与警告 |
+| `strategy_get_run` | 状态、进度、汇总指标 |
+| `strategy_get_run_equity` / `_trades` / `_actions` | 分页读明细 |
+| `strategy_settings` / `_update` | 读写回测参数 |
+| `strategy_cancel_run` / `strategy_delete_run` | 取消 / 删除 |
+
+**分层输出是刻意的**：`strategy_get_run` 只给汇总指标，权益曲线和成交明细分页取（单页上限 20,000 行）。一条完整曲线有几万个点，全塞给 agent 只会冲爆上下文。
+
+同时安装的 `okx-strategy-research` Skill 里写明了工作流约束：写完立刻校验、回测前查缺口、入队后轮询而不假设同步完成、先说事实再说解读、说明模拟假设、调参后引用验证段而不是训练段。
+
+### agent 也能走完整条链
+
+上游是行情分析（`market_*`、`news_*`、`smart_money_*` 工具和对应 Skill），下游是实盘（`live_*` 工具和 `okx-live-trading` Skill）。一个 agent 可以：分析行情找到想法 → 写成策略 → 校验 → 回测 → 调参 → 建 Profile → 在模拟盘启用观察 → 请你批准后上实盘。
+
+但下游默认是关的：
+
+```bash
+desic-okx live agent-access on    # 需重启 MCP 客户端
+```
+
+关闭时 `live_create_profile` 和 `live_start` **不出现在** agent 的工具列表里，它只能读 Profile 和停止。开启后能创建和启用，但 Skill 要求它在启用实盘 Profile 前停下来问你并给出数字。详见 **[实盘执行使用指南 · 给 AI agent 用](live-trading.md#给-ai-agent-用)**。
+
+---
+
+## 常见问题
+
+**回测失败，提示 "does not fully cover"**
+区间里的数据不完整。先跑 `data download --inst <合约> --days <天数>` 补齐，用同一个窗口，然后重试。这是 fail-closed 设计，不会静默跳过缺失的分钟。
+
+注意 `data coverage` 显示 `missingCount 0` 时也可能出现这个错误 —— 它只统计已存区间内部的缺口，不包含"窗口延伸到最新一根之后"的部分。数据是几小时前下的、而你要跑"最近 N 天"时就会这样。`download` 能同时解决两种情况。
+
+**提示 "has no timezone"**
+带时钟时间的时间戳必须带时区：`2026-08-13T07:12:00Z`。纯日期 `2026-08-13` 不受影响。
+
+**提示 "Unknown tool 'strategy_run_optimize'"**
+常驻 runtime 是升级前启动的。`desic-okx stop` 后重试即可，下次调用会自动拉起新版本。
+
+**调优提示 "cannot cover 'slowPeriod', which has 19 values"**
+预算比该参数的取值个数还小，覆盖保证不可能成立。把预算提到至少 19，或者把 step 调大。
+
+**调优提示 "declares no parameter 'xxx'"**
+`space.json` 里的键在策略参数里不存在。用 `--params` 传上策略的默认参数，并检查拼写。
+
+**调优提示 "below the 1440-bar minimum"**
+窗口太短，7:3 切分后有一段不足 1,440 根。用至少 7 天的窗口。
+
+**空间提示 "above the 5000 limit"**
+组合数太多。缩小范围或调大 step。
+
+**年化和卡玛显示 `-`**
+评估区间短于 30 天，这两个值被刻意隐去。用更长的窗口。
+
+**收益率为正但盈亏比小于 1**
+先看"手续费占毛利比例"。超过 100% 说明手续费吃掉了全部信号优势，问题在换手率而不一定在逻辑。
+
+---
+
+## 必须知道的限制
+
+**回测是模拟，不是预期收益。** 具体地说：
+
+- 手续费和滑点按你配置的固定值计算，不随行情变化
+- 市价单在下一根 1 分钟开盘成交，不含真实的交易所延迟
+- 限价单按 K 线保守估计撮合，**没有订单簿队列模型**，单根 K 线成交量上限 10%
+- 保证金耗尽是研究用的风险边界，不是 OKX 强平估算
+- 只有 1 分钟粒度，K 线内部的价格路径是不可知的（同一根内止损和止盈都可能触及时，按不利的那个算）
+
+**过拟合是默认结果，不是例外。** 单一区间上的亮眼成绩要按可疑对待。优先选择在相邻参数值上都稳定的那一组，而不是一个孤立的尖峰 —— 被一片糟糕结果包围的单个高点，是数据里的巧合，不是一个设定。
+
+负面结果是有效发现。一个亏钱的策略，值得如实报出来。
+
+---
+
+## 相关文件位置
+
+| 内容 | 路径 |
+| --- | --- |
+| 配置与回测参数 | 配置目录下 `backtest-settings.json` |
+| 数据库（K 线、运行记录） | 数据目录下 SQLite 文件 |
+| HTML 报告 | 数据目录下 `reports/`，保留最近 20 份 |
+| Python venv | 数据目录下 `python/venv` |
+
+`desic-okx status` 和 `desic-okx doctor` 会打印实际路径。
+
+---
+
+策略验证完成后如需接到真实账户，见 **[实盘执行使用指南](live-trading.md)**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "desic-okx-agent",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Independent Desic runtime, MCP server, CLI, and agent skills for OKX",
   "type": "module",
   "license": "MIT",
@@ -28,8 +28,11 @@
   },
   "files": [
     "dist",
+    "python/main.py",
+    "python/desic_strategy/*.py",
     "skills",
     "examples",
+    "docs",
     "README.md",
     "README.en.md",
     "LICENSE"
@@ -66,8 +69,14 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.19.15",
     "@types/ws": "^8.18.1",
+    "ink-testing-library": "^4.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
+  },
+  "optionalDependencies": {
+    "@types/react": "^19.2.18",
+    "ink": "^6.8.0",
+    "react": "^19.2.8"
   }
 }

package/python/desic_strategy/__init__.py

@@ -0,0 +1,34 @@
+"""Desic strategy research: policy, timeframe aggregation, and the backtest engine.
+
+The host owns the clock, the market window, matching, risk checks, and the audit
+trail. A strategy receives one immutable point-in-time context and returns one
+high-level decision. It never receives an exchange client, credentials, a system
+clock, a database handle, or an order API.
+"""
+
+from .actions import Decision, StrategyError
+from .engine import Costs, Engine, Instrument, RunConfig, Sizing
+from .policy import PolicyViolation, validate_source
+from .report import Metrics, build_report, calculate_metrics
+from .timeframe import Bar, DataContractError, TimeframeAggregator, aggregate
+
+__all__ = [
+    "Bar",
+    "Costs",
+    "DataContractError",
+    "Decision",
+    "Engine",
+    "Instrument",
+    "Metrics",
+    "PolicyViolation",
+    "RunConfig",
+    "Sizing",
+    "StrategyError",
+    "TimeframeAggregator",
+    "aggregate",
+    "build_report",
+    "calculate_metrics",
+    "validate_source",
+]
+
+PROTOCOL_VERSION = "desic.strategy/v1"