dekun
5d161b4220
Lock one mode per instance/subaccount, cross-asset BTC option/ETH perp sizing, combo-U exit, and ship docs/tests/audit. Co-authored-by: Cursor <cursoragent@cursor.com>
138 lines
4.9 KiB
Markdown
138 lines
4.9 KiB
Markdown
# 永期对冲三模式（一实例 · 一模式 · 一子账户）
|
||
|
||
> 模拟盘与实盘 **同一执行路径**；差别仅在 API Key / `LIVE_TRADING_ENABLED` / 模拟开关。
|
||
> 实现入口：`lib/hedge_plan/hedge_po_mode_lib.py`。
|
||
|
||
---
|
||
|
||
## 1. 定稿口径
|
||
|
||
| 模式 `HEDGE_PO_MODE` | 期权标的 | 永续标的 | 名义关系 |
|
||
|----------------------|----------|----------|----------|
|
||
| `eth` | ETH | ETH | 永续名义 = 期权名义 ÷ 比例（默认比例 2 → 一半） |
|
||
| `btc` | BTC | BTC | 同上 |
|
||
| `btc_eth` | BTC | ETH | 永续名义(U) = 期权名义(U) × `HEDGE_CROSS_NOTIONAL_K`（默认 **0.5**） |
|
||
|
||
### 方向（以期权为主，强制）
|
||
|
||
- 买 **Call** → 永续 **空**
|
||
- 买 **Put** → 永续 **多**
|
||
|
||
### 出场（强制）
|
||
|
||
- 仅 **组合盈利金额(U)**
|
||
- 口径：`期权净利(币) × 期权指数 + 永续净利(U)`（扣开平双边手续费）
|
||
- 与持仓卡 `combo.net_usdt`、监控出场门控一致；**禁止**币与 U 直接相加
|
||
|
||
### 部署约束
|
||
|
||
- **一个实例一种模式对应一个子账户**；账户之间互不干涉
|
||
- **禁止**同一子账户挂两个实例
|
||
- **禁止**运行中热切 `HEDGE_PO_MODE`（须换实例 / 换子账户 / 重启）
|
||
- 模拟 → 实盘：同模式、同定仓/出场逻辑，只换密钥与 live/sim 开关
|
||
|
||
---
|
||
|
||
## 2. 环境变量
|
||
|
||
```env
|
||
# 必配(建议显式写出);非法值启动时钳制并打日志
|
||
HEDGE_PO_MODE=eth # eth | btc | btc_eth
|
||
HEDGE_CROSS_NOTIONAL_K=0.5 # 仅 btc_eth;永续名义/期权名义
|
||
|
||
# 会与模式同步:期权链默认标的 = 模式的期权腿
|
||
OKX_OPTIONS_DEFAULT_UNDERLY=ETH
|
||
|
||
# 以期权为主(实例模式会强制 true)
|
||
HEDGE_PLAN_OPTION_PRIMARY=true
|
||
|
||
# 真下单:模拟可开;实盘须再开 LIVE_TRADING_ENABLED
|
||
HEDGE_PLAN_LIVE_ORDER=true
|
||
LIVE_TRADING_ENABLED=false
|
||
```
|
||
|
||
改 `HEDGE_PO_MODE` / `HEDGE_CROSS_NOTIONAL_K` 后须 **重启 PM2**（启动时 `clamp_hedge_po_mode_on_startup`）。
|
||
|
||
---
|
||
|
||
## 3. 多实例部署示例
|
||
|
||
| 进程 / 域名 | `.env` | 子账户 |
|
||
|-------------|--------|--------|
|
||
| 实例 A | `HEDGE_PO_MODE=eth` | OKX 子账户「ETH对冲」 |
|
||
| 实例 B | `HEDGE_PO_MODE=btc` | OKX 子账户「BTC对冲」 |
|
||
| 实例 C | `HEDGE_PO_MODE=btc_eth` | OKX 子账户「跨币」 |
|
||
|
||
模拟盘同样拆三套（或三库），**不要**一个模拟进程里切三种模式共一把钥匙。
|
||
|
||
---
|
||
|
||
## 4. 代码落点
|
||
|
||
| 模块 | 作用 |
|
||
|------|------|
|
||
| `hedge_po_mode_lib.py` | 模式规范化、启动钳制、跨币名义、组合 U、body 钳制 |
|
||
| `hedge_plan_option_primary_lib.py` | `size_from_premium` / `contracts_from_option_sheets` 支持双指数 |
|
||
| `hedge_plan_orders_lib.py` | 启动前定仓刷新、校验按模式钳制 |
|
||
| `hedge_plan_monitor_lib.py` | 出场门控用组合 U；跨币指数分腿 |
|
||
| `hedge_plan_register.py` | 安装时钳制；行情/期权链锁定标的；落库 `po_mode`/`perp_underlying` |
|
||
| `hedge_plan.js` + panel | 页内锁定标的；展示模式徽标；强制盈利金额出场 |
|
||
| env schema / UI manifest | `HEDGE_PO_MODE`、`HEDGE_CROSS_NOTIONAL_K` |
|
||
|
||
---
|
||
|
||
## 5. 测试
|
||
|
||
```bash
|
||
python -m unittest tests.test_hedge_po_mode tests.test_hedge_plan_option_primary -v
|
||
```
|
||
|
||
覆盖：模式规范化、启动钳制、跨币名义半仓、组合 U 口径、body 校验。
|
||
|
||
---
|
||
|
||
## 6. 审计清单（模拟 / 实盘通用）
|
||
|
||
启动后日志应出现：
|
||
|
||
```text
|
||
[HEDGE_PO_MODE] mode=... option=... perp=... k=... (一实例一模式一子账户)
|
||
```
|
||
|
||
| # | 检查项 | 期望 |
|
||
|---|--------|------|
|
||
| 1 | `/api/hedge-plan/po-mode` | `po_mode` / `option_underlying` / `perp_underlying` / `exit_mode=profit` |
|
||
| 2 | 对冲页顶栏徽标 | 显示模式名；跨币显示「期权BTC/永续ETH」 |
|
||
| 3 | ETH/BTC 切换钮 | 永期页禁用，与模式期权标的一致 |
|
||
| 4 | 期权链 | 仅模式期权标的；拉错标的 API 400 |
|
||
| 5 | 永续行情 `exchange_symbol` | 前缀=模式永续标的 |
|
||
| 6 | 手动开仓 body | 服务端重写 `underlying`/`exit_mode`/`option_perp_ratio`(跨币) |
|
||
| 7 | 定仓（跨币） | 期权名义U × K ≈ 永续名义U |
|
||
| 8 | 持仓卡 `combo.net_usdt` | 期权币×期权指数 + 永续U |
|
||
| 9 | 监控出场 | 达 `profit_target_usdt` 才平；比较的是组合 U |
|
||
| 10 | 卖回币 | 卖 **期权标的**币（跨币卖 BTC） |
|
||
| 11 | 模拟 vs 实盘 | 同一套 orders/monitor；仅 Key 与 live 开关不同 |
|
||
| 12 | 子账户 | 三模式三 Key；无交叉下单 |
|
||
|
||
快速审计脚本：
|
||
|
||
```bash
|
||
python scripts/audit_hedge_po_mode.py
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 实盘上线顺序建议
|
||
|
||
1. 模拟实例 `HEDGE_PO_MODE=eth` 走通开平与组合 U 出场
|
||
2. 同模式换实盘子账户 Key，`LIVE_TRADING_ENABLED=true` + `HEDGE_PLAN_LIVE_ORDER=true`
|
||
3. 再开 `btc` / `btc_eth` 独立实例灰度
|
||
|
||
---
|
||
|
||
## 8. 相关文档
|
||
|
||
- [对冲计划-以期权为主.md](./对冲计划-以期权为主.md)
|
||
- [对冲计划策略与P0校验.md](./对冲计划策略与P0校验.md)
|
||
- [对冲计划开发方案.md](./对冲计划开发方案.md)
|