desic-okx-agent 0.2.0 → 0.3.0

package/docs/live-trading.md

@@ -0,0 +1,455 @@
+# 实盘执行使用指南
+
+把已验证的策略接到真实账户，每根 1 分钟收线自动执行。
+
+> **这部分会用真钱下单。**
+>
+> 下面每一处约束都是为了让"错误可见且可停"，不是为了让功能看起来完整。请先读[必须知道的限制](#必须知道的限制)。
+
+**强烈建议先在模拟盘跑够信号历史**，确认幂等、恢复、风控都按预期工作，再考虑实盘。
+
+这是整条链的最后一段。上游是[策略研究](strategy-research.md) —— 写策略、回测、调参；启用实盘的硬性前置条件就是上游产出的回测记录。两条路径（你自己做 / 交给 AI）走的是同一条链，区别见[给 AI agent 用](#给-ai-agent-用)。
+
+---
+
+## 目录
+
+- [十分钟跑通模拟盘](#十分钟跑通模拟盘)
+- [三个概念](#三个概念)
+- [启用前置条件](#启用前置条件)
+- [风控闸门](#风控闸门)
+- [读信号历史](#读信号历史)
+- [自动停用](#自动停用)
+- [崩溃恢复](#崩溃恢复)
+- [切换到实盘](#切换到实盘)
+- [命令参考](#命令参考)
+- [给 AI agent 用](#给-ai-agent-用)
+- [常见问题](#常见问题)
+- [必须知道的限制](#必须知道的限制)
+
+---
+
+## 十分钟跑通模拟盘
+
+```bash
+# 1. 行情切到模拟盘,重启生效
+desic-okx market env demo
+desic-okx stop
+
+# 2. 补数据(模拟盘与实盘是两套独立行情,需各自下载)
+desic-okx data download --inst BTC-USDT-SWAP --days 2
+
+# 3. 回测一次 —— 这是启用的硬性前置条件
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 1 --follow
+
+# 4. 创建 Profile(创建绝不会开始交易)
+desic-okx live create --file ema.py --inst BTC-USDT-SWAP --account demo \
+  --environment demo --entry-budget 100 --side-budget 200 --daily-loss 500
+
+# 5. 看还差什么
+desic-okx live readiness --id lp_xxxx
+
+# 6. 启用 —— 从这一刻起,每根收线都会真实执行
+desic-okx live start --id lp_xxxx
+
+# 7. 观察
+desic-okx live signals --id lp_xxxx
+
+# 8. 停止
+desic-okx live stop --id lp_xxxx
+```
+
+第 6 步之后就会真实下单。第 4 步的 `--entry-budget 100` 配 10 倍杠杆约合 1,000 USDT 名义敞口 —— **闸门按 Profile 预算限制，不按账户余额**，所以账户里有多少钱不影响单笔规模。第 6 步还会把这个 10 倍[写到交易所](#启用会改动交易所的杠杆设置)，否则预算数字不成立。
+
+---
+
+## 三个概念
+
+**Profile** —— 策略 + 合约 + 账户 + 风控预算的绑定。它存的是**策略源码快照**，不是文件路径：文件会被改，而 Profile 必须继续交易"启用时被审阅过的那一版"，否则保存一次文件就悄悄改变了运行中的实盘行为。
+
+一个账户 + 一个环境 + 一个合约只能有一个 Profile。两个会各自基于对方开出的仓位算规模。
+
+**Signal（信号）** —— 每根收线一条记录。`UNIQUE(profile, cutoff)` 是幂等的根基：无论 K 线被重复投递多少次、运行时重启多少次，**一根收线最多产生一个订单**。
+
+**闸门（Gate）** —— 策略意图与订单之间的一串检查。**每一道都是拒绝，没有一个是修正。**
+
+最后这点值得展开。假设单笔预算 50 USDT，策略意图按当前权益需要 80：
+
+- **修正**（不采用）：砍到 50 下单。你看到一笔成交，不知道规模被改过。
+- **拒绝**（采用）：不下单，记一条 `blocked` 信号，写明"超过单笔预算"。
+
+修正会让风控变得**不可见** —— 你以为策略在按设计运行，实际主机一直在悄悄改写它。
+
+---
+
+## 启用前置条件
+
+启用时一次性检查，**全部不满足项一起报出**（不是每次暴露一个）。
+
+| 条件 | 为什么 |
+|---|---|
+| 该源码 + 该合约**已完成回测** | 否则没有任何证据说明它可行 |
+| Python 环境就绪 | 否则第一根收线就失败 |
+| 账户凭证被交易所接受 | |
+| API key 有交易权限 | 否则每笔订单都被拒 |
+| 合约规格可读 | 张数换算的依据 |
+| Profile 环境 == 行情环境 | 见下 |
+
+每一项都是**可验证的系统事实**。"该不该投真钱"不在这个清单里 —— 那不是系统能验证的事实，而是你的判断。
+
+### 启用会改动交易所的杠杆设置
+
+前置条件全部通过后，启用会在写库之前把 Profile 的 `--leverage` **写到交易所**（`set-leverage`，按 Profile 的 `instId` + `marginMode`）。写失败则拒绝启用。
+
+**这一步是必须的，因为预算的含义依赖它。** 张数由 `预算 × 杠杆 ÷ 价格` 算出，交易所则按它自己记录的杠杆收保证金。两个数不一致时，预算说的和实际占用的就不是一回事：
+
+> 实测（模拟盘）：Profile 配 10 倍、账户实际留在 3 倍，`--entry-budget 60` 开出 0.77 张，交易所按 3 倍收了约 **198 USDT** 保证金 —— 预算被突破 3.3 倍。写入杠杆后同样的配置，交易所报 `imr: 59.60`，与 60 USDT 预算吻合。
+
+代价要知道：**这会改动该账户在这个合约 + 保证金模式上的共享杠杆设置**，包括你手动开的仓位。这也是为什么它发生在启用这一步，而不是每根收线偷偷改。
+
+执行键由意图派生（`live-leverage:<profileId>:<杠杆>:<模式>`），所以重复启用不会写第二条执行记录。
+
+### 一条是刻意的摩擦
+
+**"已完成回测"**按**源码 hash** 匹配，不是文件名或路径 —— 后两者在文件被编辑后仍会匹配上。
+
+而且门槛是"**跑过**回测"，不是"结果好"。亏钱的回测同样通过，因为它证明了策略能跑完、没崩溃、且你看过它的行为。要求盈利只会让人不停调参直到数字好看 —— 那恰好是过拟合。
+
+### AI 启用实盘前必须先问你
+
+前置条件全部通过只说明这个 Profile **可以**启动，不说明**应该**启动。
+
+默认情况下 AI 根本看不到启用工具（见[给 AI agent 用](#给-ai-agent-用)）。但一旦你开了 `live agent-access on`，**系统就不会再拦住它启用实盘** —— 这是刻意的。
+
+曾经有一版要求手打 Profile 名字，但那道摩擦对人价值很小（你就是刚创建它的人），实际只挡住了 AI，把"该不该交易"变成了"能不能猜到一个字符串"。那不是同一个问题，也不会让决定变得更明智。
+
+现在的约束写在 AI 的 Skill 里：启用 `environment: live` 的 Profile 前必须停下来问你，并且必须给出配置、预算、回测的**验证段**指标、以及模拟盘跑出的信号统计。"要不要启动？"这样光秃秃一句不算问 —— 你需要数字才能有意义地回答。
+
+### 环境必须一致
+
+Profile 环境与行情环境不一致会被拒绝。模拟盘和实盘是**两个独立市场、价格不同**（实测同一时刻价差数美元、24h 成交量差 5 倍），一个在实盘交易的 Profile 基于模拟盘 K 线决策，等于用一个从未适用于它自身市场的价格做判断。
+
+```bash
+desic-okx market env        # 查看行情环境
+desic-okx market env live   # 切换,需重启
+```
+
+---
+
+## 风控闸门
+
+每根收线按顺序检查，**从便宜到昂贵** —— Profile 自身设置就已禁止的决策，不会走到需要网络请求的 `precheck`。
+
+| # | 闸门 | 拦什么 |
+|---|---|---|
+| 1 | Profile 已启用 | |
+| 2 | generation 未变 | 评估期间你点了停止 |
+| 3 | 方向权限 | 只允许做多却收到 `open_short` |
+| 4 | 单笔预算 | 一次开仓的保证金上限 |
+| 5 | 同向总预算 | 已有多仓 40，再开 40 会超上限 |
+| 6 | 当日亏损限额 | 今日已实现亏损触及限额 |
+| 7 | 冷却时间 | 上次**下单**后 N 秒内不再下单 |
+| 8 | 张数 ≥ `minSz` + `precheck` | 合约规格、权限 |
+
+第 2 条是 TOCTOU 防护：检查与提交之间有时间差，停止可能落在这个缝隙里。提交前会**再查一次** generation。
+
+### 平仓刻意跳过 4/5/6/7
+
+平仓**按持仓量算张数，不按预算**，且跳过预算、亏损、冷却三道闸门。
+
+两个理由：
+
+- 一个阻止你平掉亏损仓位的亏损限额，只会让亏损更大 —— 与它存在的目的正好相反
+- 按预算算出的部分平仓，会留下策略以为已经清掉的敞口
+
+方向权限同理：禁止做多的 Profile 仍可平掉已有多仓，否则会把仓位困死。
+
+平仓单带 `reduceOnly` —— 迟到的成交只会平仓，不会反向开新仓。
+
+### 数字全部来自交易所
+
+- **持仓 / 已用保证金**：OKX 的 `imr`（本地推导在全仓模式下会与交易所不一致）
+- **当日已实现亏损**：从当天成交汇总，**含手续费**（一整天全花在成本上是真实亏损），按 UTC 日切分
+- **可用权益**：读逐币种明细而非账户汇总（OKX 在某些账户模式下把顶层 `availEq` 留空）
+
+本地账本一旦遇到手动平仓、部分成交或强平就会漂移，而策略基于漂移的数字决策，正是整个设计要避免的失败。
+
+---
+
+## 读信号历史
+
+```bash
+desic-okx live signals --id lp_xxxx --limit 30
+```
+
+```
+分钟              动作       状态       详情                              张数
+18:52  no_action  no_action  holding probe position            -
+18:51  open_long  submitted  3859050322711461888  probe entry  1.29
+18:50  open_long  blocked    side_budget: 同向预算已满          -
+18:49  open_long  error      Order precheck failed             -
+```
+
+六种状态：
+
+| 状态 | 含义 |
+|---|---|
+| `no_action` | 策略没有请求任何动作 |
+| `submitted` | 订单已到交易所 |
+| `blocked` | 某道闸门拒绝了，`详情`列出是哪一道 |
+| `error` | 评估失败 |
+| `ambiguous` | **结果未知，等人处理**（见下） |
+| `reserved` | 已占位但未决策（崩溃残留） |
+
+### `blocked` 记录比成交更重要
+
+它们是**风控运行过的证据**。只存成交的话，"今天没下单"有两种可能 —— 风控挡住了，或者代码根本没跑。这两种必须能区分。
+
+### `ambiguous` 需要人工介入
+
+意味着订单**可能存在也可能不存在**。系统**绝不自动重试** —— 重发一个可能已存在的订单，比漏掉一个更糟。
+
+看到 `ambiguous` 时：
+
+```bash
+desic-okx account get-order --inst BTC-USDT-SWAP --ord-id <详情里的ID>
+desic-okx call account_get_positions --json '{"account":"demo"}'
+```
+
+确认交易所实际状态后再决定。
+
+---
+
+## 自动停用
+
+连续 **3** 次**系统性**失败 → 自动停用 Profile 并写明原因。
+
+关键在于**哪些失败计数**：
+
+| 计数（不会自愈） | 不计数（会自愈） |
+|---|---|
+| 缺少 Python 环境 | 连接断开 |
+| 源码违规 | 频率限制 |
+| 权限被撤 | 数据窗口待修补 |
+| 策略抛异常 | socket 断开 |
+| **`AMBIGUOUS_WRITE`** | |
+| **任何无法识别的错误** | |
+
+两个刻意的决定：
+
+**`AMBIGUOUS_WRITE` 计数**，尽管它本质是网络症状 —— 它意味着订单状态未知，在未知持仓上继续交易正是最该快速停下的情况。
+
+**无法识别的错误计数** —— 反复出现的未知故障恰恰是自动停用存在的理由。
+
+不计数的失败**仍会记录**为 `lastError`，只是不推向停用。连续 20 次网络失败，Profile 依然在跑。
+
+数的是**连续**失败：一次成功清零。但两次真实故障之间夹一次网络抖动**不清零** —— 故障还在那里。
+
+停用会递增 generation，所以已决定但未提交的动作会被拦住。
+
+---
+
+## 崩溃恢复
+
+运行时启动时自动执行，无需干预：
+
+1. `status='running'` 的 Profile 标为 `stopped` 并递增 generation（worker 已不存在）
+2. 等 750ms 让 `executions` 表先完成自己的恢复
+3. 找出 `reserved` / `submitted` 状态的信号
+4. **向交易所对账**，不假设成功或失败
+
+### 最关键的一个区分
+
+**"交易所说没有这笔订单"** ≠ **"问不到交易所"**
+
+第一个是答案，可以关闭信号。第二个不是 —— 把它当成第一个，会静默丢弃一笔可能已成交的订单，所以标为 `ambiguous`。
+
+仍在挂单或部分成交的订单也标 `ambiguous`，不自动处理：那是策略不知道的持仓，自动平掉等于替你决定如何处置还没看到的敞口。
+
+### 为什么能对账
+
+`clOrdId` 从 `(profileId, cutoffAt)` **确定性派生** —— 正是信号表 UNIQUE 约束的那一对。所以恢复能查询一笔它从未见过响应的订单。有测试把这个派生钉死在实际发出的 id 上：两处一旦分叉，恢复会查一个交易所从未收到的 id，然后得出"没有订单"的错误结论。
+
+验证方式：
+
+```bash
+kill -9 <runtime pid>
+desic-okx start
+grep "live-signals-reconciled" <数据目录>/run/lifecycle.log
+```
+
+---
+
+## 切换到实盘
+
+**在做够模拟盘验证之前不要做这一步。**
+
+至少确认过：
+- 信号历史里有 `submitted`、`blocked`、`no_action` 三种记录，且都合理
+- 至少经历过一次 `kill -9` 重启并看到对账日志
+- 单笔规模与你的预期一致
+
+### 步骤
+
+```bash
+# 1. 配置实盘账户(权限不要勾提币,建议绑 IP 白名单)
+desic-okx account add --name main
+
+# 2. 行情切实盘
+desic-okx market env live
+desic-okx stop
+
+# 3. 实盘数据是独立的,需重新下载
+desic-okx data download --inst BTC-USDT-SWAP --days 90
+
+# 4. 用实盘数据重跑回测(前置条件按 hash + 合约匹配,换环境要重跑)
+desic-okx strategy backtest --file ema.py --inst BTC-USDT-SWAP --days 30 --follow
+
+# 5. 创建实盘 Profile —— 预算设小
+desic-okx live create --file ema.py --inst BTC-USDT-SWAP --account main \
+  --environment live --entry-budget 50 --side-budget 100 --daily-loss 100 \
+  --name ema-btc-live
+
+# 6. 启用
+desic-okx live start --id lp_xxxx
+```
+
+第 3 步不能省：模拟盘和实盘 K 线不同，`dataSnapshotId` 不可跨环境复用。
+
+### 建议的第一次实盘配置
+
+- `--entry-budget` 设成你**能接受全部亏掉**的金额
+- `--daily-loss` 设成单笔预算的 1–2 倍，让它很容易触发（先验证限额工作，再放宽）
+- `--cooldown 300` 或更长，限制出错时的下单频率
+- 先只允许一个方向（`--no-short`），减少一半的意外面
+
+---
+
+## 命令参考
+
+```bash
+desic-okx live list                                    # 全部 Profile 及状态
+desic-okx live create --file ... --inst ... --account ...   # 创建(不会启动)
+desic-okx live readiness --id <id>                     # 还差什么
+desic-okx live start --id <id>                          # 启用
+desic-okx live stop --id <id> [--reason "..."]         # 停止(永远允许)
+desic-okx live signals --id <id> [--limit 30]          # 决策历史
+desic-okx live delete --id <id> --yes                  # 删除(需先停止)
+```
+
+`create` 的必填项：`--file` `--inst` `--account` `--entry-budget` `--side-budget` `--daily-loss`
+
+可选项：`--name` `--environment`（默认 demo）`--leverage`（默认 10）`--margin-mode`（默认 cross）`--cooldown`（默认 0）`--params` `--no-long` `--no-short`
+
+### 交互界面
+
+```
+> /live                    列出全部
+> /live signals <id>       决策历史
+> /live stop <id>          停止
+```
+
+**创建和启动刻意不在交互界面** —— 它们是把资金投入某个策略的两个动作，一个按键就能开始交易的界面不值得信任。
+
+---
+
+## 给 AI agent 用
+
+默认只暴露**只读 + 停止**：
+
+| 工具 | 用途 |
+|---|---|
+| `live_list_profiles` | 全部 Profile 及状态 |
+| `live_get_profile` | 单个 Profile |
+| `live_readiness` | 阻碍启动的项 |
+| `live_signals` | 决策历史，含每次拒绝与对应闸门 |
+| `live_stop` | 停止（永远允许） |
+
+**默认情况下 `live_create_profile`、`live_start`、`live_delete_profile` 不在 MCP 工具列表里** —— 不是拒绝调用，而是根本不出现在清单中。agent 看不到的工具不会去猜，也不会去试。
+
+### 打开 agent 的实盘权限
+
+```bash
+desic-okx live agent-access on    # 允许 agent 创建和启用
+desic-okx live agent-access       # 查看当前设置
+desic-okx live agent-access off   # 收回
+```
+
+**需重启 MCP 客户端生效** —— 工具列表在客户端连接时构建一次，改配置不会影响已连接的会话。
+
+开启后 agent 能跑完整条链：写策略 → 回测 → 调参 → 建 Profile → 启用 → 读信号 → 停止。这是刻意的：把"AI 自动分析交易"和"用户手写策略回测"接成一条链，而不是两个各自独立的功能。
+
+### 创建 Profile 时必须给出理由
+
+`origin` 为 `agent` 的 Profile 必须带 `rationale`。这不是装饰 —— 它把"为什么要建这个 Profile"和 Profile 本身存在一起，你之后翻 `live list` 时能看到当初的判断依据，而不是一行来历不明的配置。
+
+### 启用实盘前 Skill 要求先问你
+
+前置条件全部通过只说明**可以**启动。`okx-live-trading` Skill 里写明：模拟盘上放手做，启用 `environment: live` 的 Profile 前必须停下来问你，并给出 Profile 配置、三个预算、回测的**验证段**指标、以及模拟盘跑出的信号统计。Skill 明确写了"要不要启动？"这样光秃秃一句不算问。
+
+系统不会替你拦这一步（见上文[启用前置条件](#启用前置条件)）。开 `agent-access` 就是把这个信任交出去了。
+
+---
+
+## 常见问题
+
+**信号全是 `error  Order precheck failed`**
+查 `desic-okx live signals` 的详情列。如果是 `Market decision snapshot is not time-consistent`，说明用的不是实盘循环路径 —— 实盘会自动传 `executabilityOnly`（资金费率每 8 小时才更新，物理上无法与 ticker 对齐到 1 秒内）。其他 blocker 是真实问题。
+
+**启用被拒，提示 "No completed backtest"**
+用该策略源码 + 该合约跑一次回测。注意源码改一个字符 hash 就变了，需重跑。换环境（demo↔live）也要重跑。
+
+**启用被拒，提示 "market data is streaming from ..."**
+Profile 环境与行情环境不一致。`desic-okx market env <环境>` 后重启。
+
+**Profile 自动停用了**
+`desic-okx live list` 看 `连续错误` 列，`live_get_profile` 看 `lastError`。连续 3 次系统性失败会自动停 —— 先解决根因再重新启用。
+
+**信号是 `ambiguous`**
+订单状态未知，**不会自动重试**。用 `account_get_order` 和 `account_get_positions` 确认交易所实际状态，再决定。
+
+**策略读到的持仓是空的，但交易所有仓位**
+检查 Profile 的 `instId` 是否与持仓合约一致。策略只看到自己合约的持仓。
+
+**改了策略文件，实盘行为没变**
+这是刻意的。Profile 绑定的是**启用时的源码快照**。要用新版本：停止 → 用新文件重跑回测 → 新建 Profile。
+
+---
+
+## 必须知道的限制
+
+**这是自动交易，不是"会赚钱"。** 回测通过只证明策略能跑完并且你看过它的行为 —— 亏钱的回测同样能启用。
+
+**明确不支持：**
+
+- **`set_protection` / `cancel_protection`** —— 原生改单与对账未实现。入场时可附带 TP/SL 请求，但不支持动态修改。回测里完全可用。
+- **反手** —— 必须先平后开，与回测一致。持多仓时直接 `open_short` 会报错。
+- **一个 Profile 一个合约** —— 多合约需要多个 Profile。
+- **热切换环境** —— 改配置后必须重启 runtime。
+
+**评估的时间约束：**
+
+- 策略单次决策超过 **5 秒**视为故障，跳过本轮（会话保持存活，指标状态不丢）
+- 会话内存保留最近 **20,000** 根 K 线
+- 新会话预热 **300** 根历史，预热不产生决策
+
+**数据完整性是 fail-closed 的：**窗口有缺口时**拒绝评估**，不会基于残缺数据下单。
+
+**回测与实盘的决策一致，但成交不一致。** 同一策略同一段历史，两条路径的决策序列完全相同（有测试保证）。但回测的成交是模拟的：固定手续费滑点、下根开盘成交、限价单按 K 线保守估计、无订单簿队列。实盘成交由交易所决定。
+
+**风控闸门限制的是规模和频率，不是亏损。** 它们能阻止"单笔过大"和"频繁下单"，但阻止不了一个持续做出错误决策的策略慢慢亏光。**当日亏损限额是唯一的止损性约束，把它设小。**
+
+---
+
+## 相关文件位置
+
+| 内容 | 路径 |
+|---|---|
+| 账户凭证 | 配置目录 `config.json`（**明文**，仅靠文件权限 0600 保护） |
+| Profile 与信号 | 数据目录 SQLite 的 `live_profiles` / `live_signals` |
+| 幂等记录 | 同库 `executions` 表 |
+| 运行日志 | 数据目录 `run/lifecycle.log` |
+
+`desic-okx status` 和 `desic-okx doctor` 会打印实际路径。
+
+策略编写与回测见 **[策略研究使用指南](strategy-research.md)**。