Interactive Brokers MCP Server

# 风险管理指南

本文档详细说明 IBKR-MCP 的风险管理系统，包括风险指标、限额配置、规则评估和调整建议生成。

---

## 概述

风险管理系统的核心流程：

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   持仓数据   │ ──▶ │ Greeks 计算  │ ──▶ │  规则评估   │ ──▶ │  调整建议   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │                   │
                           ▼                   ▼
                    ┌─────────────┐     ┌─────────────┐
                    │  集中度计算  │     │  risk.yaml  │
                    └─────────────┘     └─────────────┘
```

---

## 风险指标

### Greeks（希腊字母）

| 指标 | 描述 | 影响因素 | 风险含义 |
|------|------|----------|----------|
| **Delta (Δ)** | 标的价格变动 $1 时期权价格的变动 | 方向性敞口 | 正 Delta = 做多，负 Delta = 做空 |
| **Gamma (Γ)** | 标的价格变动 $1 时 Delta 的变动 | 凸性风险 | 高 Gamma = Delta 变化快，临近到期风险大 |
| **Vega (ν)** | 波动率变动 1% 时期权价格的变动 | 波动率敞口 | 正 Vega = 做多波动率 |
| **Theta (Θ)** | 每天时间流逝的价值损耗 | 时间衰减 | 负 Theta = 净卖出期权，每天损失 |
| **Rho (ρ)** | 利率变动 1% 时期权价格的变动 | 利率敞口 | 通常影响较小 |

### Greeks 计算规则

1. **股票 Delta**: 强制设为 1.0（每股）
2. **期权 Greeks**: 从 IBKR 实时获取 `modelGreeks`
3. **缩放公式**:
   ```
   持仓Greeks = 单位Greeks × 数量 × 乘数
   ```
4. **汇总方式**: 按标的分组求和，再汇总为组合级别

### 集中度指标

衡量单一标的在组合中的占比：

```
绝对敞口 = |市场价值|
总敞口 = Σ 各标的绝对敞口
敞口占比 = 单标的绝对敞口 / 总敞口
```

---

## 配置文件详解

### 文件位置

风险配置文件按以下优先级查找：

1. 工具参数 `config` 直接传入的配置对象
2. 工具参数 `config_path` 指定的文件
3. 环境变量 `IBKR_MCP_RISK_CONFIG` 指定的文件
4. 当前目录下的 `risk.yaml`

### 完整配置示例

```yaml
# =============================================================================
# IBKR-MCP 风险配置文件
# =============================================================================

limits:
  # ---------------------------------------------------------------------------
  # Greeks 限额
  # ---------------------------------------------------------------------------

  delta:
    per_symbol: 500      # 单标的 Delta 上限（绝对值）
    total: 3000          # 组合 Delta 上限（绝对值）

  gamma:
    per_symbol: 50       # 单标的 Gamma 上限
    total: 200           # 组合 Gamma 上限

  vega:
    per_symbol: 10000    # 单标的 Vega 上限
    total: 30000         # 组合 Vega 上限

  # ---------------------------------------------------------------------------
  # Theta 限额（注意：Theta 通常为负值）
  # ---------------------------------------------------------------------------

  theta_min: 50          # Theta 下限（组合级）
                         # 例如: theta_min: 50 表示 Theta 不能低于 -50
                         # 这是为了限制净卖出期权的时间衰减风险

  # ---------------------------------------------------------------------------
  # 集中度限额
  # ---------------------------------------------------------------------------

  concentration:
    max_symbol_pct_gross: 0.20  # 单标的敞口占比上限（20%）

  # ---------------------------------------------------------------------------
  # 流动性限额
  # ---------------------------------------------------------------------------

  liquidity:
    min_open_interest: 500       # 最小未平仓合约数
    max_bid_ask_spread_pct: 2.0  # 最大买卖价差百分比

# =============================================================================
# 滚动规则（用于 Playbook 调整建议）
# =============================================================================

roll_rules:
  # ---------------------------------------------------------------------------
  # PMCC（穷人备兑）滚动规则
  # ---------------------------------------------------------------------------

  pmcc:
    take_profit_pct: 0.65        # 获利 65% 时考虑平仓
    roll_up_if_short_delta_gt: 0.40  # 短腿 Delta > 0.40 时向上滚动
    roll_out_days: 21            # 滚动到 21 天后的到期日

  # ---------------------------------------------------------------------------
  # Condor（铁鹰）滚动规则
  # ---------------------------------------------------------------------------

  condor:
    take_profit_pct: 0.60        # 获利 60% 时考虑平仓
```

---

## 风险规则详解

### 1. 单标的 Greeks 限额

检查每个标的的 Greeks 是否超过限额。

**配置方式**:
```yaml
limits:
  delta:
    per_symbol: 500  # |Delta| ≤ 500
```

**评估逻辑**:
```python
for symbol in symbols:
    if abs(symbol_delta) > limit:
        breach("Delta per-symbol", symbol, symbol_delta, limit)
```

**违规示例**:
```json
{
  "metric": "Delta per-symbol",
  "symbol": "AAPL",
  "value": 550.0,
  "limit": 500.0,
  "detail": "AAPL delta 550.00 exceeds 500"
}
```

### 2. 组合级 Greeks 限额

检查整个组合的 Greeks 汇总是否超过限额。

**配置方式**:
```yaml
limits:
  delta:
    total: 3000  # |组合Delta| ≤ 3000
```

**评估逻辑**:
```python
if abs(portfolio_delta) > limit:
    breach("Delta total", None, portfolio_delta, limit)
```

### 3. Theta 下限

确保组合的时间衰减损失不超过阈值。

**配置方式**:
```yaml
limits:
  theta_min: 50  # Theta ≥ -50
```

**评估逻辑**:
```python
if portfolio_theta < theta_min:
    breach("Theta floor", None, portfolio_theta, theta_min)
```

**说明**:
- Theta 通常为负值（时间衰减）
- `theta_min: 50` 表示每日时间损耗不超过 $50
- 净卖出期权过多会导致 Theta 过低

### 4. 集中度限额

限制单一标的在组合中的敞口占比。

**配置方式**:
```yaml
limits:
  concentration:
    max_symbol_pct_gross: 0.20  # ≤ 20%
```

**评估逻辑**:
```python
for symbol in symbols:
    pct = symbol_gross_exposure / total_gross_exposure
    if pct > limit:
        breach("Concentration", symbol, pct, limit)
```

**违规示例**:
```json
{
  "metric": "Concentration",
  "symbol": "NVDA",
  "value": 0.35,
  "limit": 0.20,
  "detail": "NVDA gross pct 35.00% exceeds 20.00%"
}
```

### 5. 流动性限额

检查持仓的流动性是否满足要求。

**配置方式**:
```yaml
limits:
  liquidity:
    min_open_interest: 500       # 最小 OI
    max_bid_ask_spread_pct: 2.0  # 最大价差 %
```

**评估逻辑**:
```python
# 检查未平仓合约
if position.open_interest < min_open_interest:
    breach("Open interest", symbol, oi, min_oi)

# 检查买卖价差
if position.bid_ask_spread_pct > max_spread:
    breach("Bid/ask spread", symbol, spread, max_spread)
```

---

## Playbook 调整建议

当风险规则触发违规时，系统会根据持仓的策略类型生成调整建议。

### PMCC 调整规则

| 触发条件 | 建议动作 |
|----------|----------|
| 短腿获利 ≥ `take_profit_pct` | 平仓短腿，重新卖出新的短期看涨 |
| 短腿 Delta > `roll_up_if_short_delta_gt` | 向上滚动（Roll Up）到更高行权价 |
| Vega 超限 | 减少 Vega 敞口 |
| 默认 | 维持当前仓位（maintain core collar） |

**生成格式**:
```
PMCC {symbol}: close short {contract} (+{profit}% credit),
re-sell near-{delta}Δ call {days}DTE ({reasons})
```

**示例**:
```
PMCC AAPL: close short AAPL 250321C00200000 (+65% credit),
re-sell near-40Δ call 21DTE (65% credit captured; short delta 0.45)
```

### Condor 调整规则

| 触发条件 | 建议动作 |
|----------|----------|
| 获利接近 `take_profit_pct` | 考虑止盈平仓 |
| Gamma 超限 | 提示 Gamma 风险 |

**生成格式**:
```
{symbol} Condor: harvest profits near {profit}% credit ({reasons})
```

**示例**:
```
SPY Condor: harvest profits near 60% credit (width 40; gamma elevated)
```

---

## 使用指南

### 评估当前风险

使用 `evaluate_portfolio_risk` 工具：

```
用户: 检查我的组合风险
→ 调用 evaluate_portfolio_risk
```

**返回内容**:
- 当前 Greeks（按标的和汇总）
- 集中度分布
- 违规列表

### 获取调整建议

使用 `generate_playbook_actions` 工具：

```
用户: 给我一些调仓建议
→ 调用 generate_playbook_actions
```

**返回内容**:
- 所有违规信息
- 针对每个策略的调整建议

### 自定义风险配置

可以直接在工具调用中传入配置：

```json
{
  "config": {
    "limits": {
      "delta": {"per_symbol": 300, "total": 2000},
      "concentration": {"max_symbol_pct_gross": 0.15}
    }
  }
}
```

---

## 风险监控最佳实践

### 每日检查清单

1. **Greeks 检查**
   - [ ] Delta 是否符合市场观点
   - [ ] Gamma 临近到期是否过高
   - [ ] Theta 收入是否合理
   - [ ] Vega 敞口是否符合波动率预期

2. **集中度检查**
   - [ ] 单一标的占比是否过高
   - [ ] 行业集中度是否分散

3. **流动性检查**
   - [ ] 持仓是否都有足够的 OI
   - [ ] 买卖价差是否合理

### 风险预警阈值建议

| 指标 | 保守 | 中等 | 激进 |
|------|------|------|------|
| 单标的 Delta | 200 | 500 | 1000 |
| 组合 Delta | 1000 | 3000 | 5000 |
| 单标的集中度 | 10% | 20% | 30% |
| 每日 Theta 损耗 | $20 | $50 | $100 |
| 最小 OI | 1000 | 500 | 100 |

### 风险事件响应

| 情况 | 响应 |
|------|------|
| Delta 超限 | 减仓或对冲方向性敞口 |
| Gamma 过高 | 远离临近到期的期权，或平仓 |
| Vega 超限 | 调整波动率敞口，考虑价差策略 |
| Theta 过低 | 减少净卖出期权，增加买入期权 |
| 集中度过高 | 分散持仓，减少单一标的敞口 |
| 流动性不足 | 平仓流动性差的持仓 |

---

## 配置模板

### 保守配置

```yaml
limits:
  delta:
    per_symbol: 200
    total: 1000
  gamma:
    per_symbol: 20
    total: 100
  vega:
    per_symbol: 5000
    total: 15000
  theta_min: 20
  concentration:
    max_symbol_pct_gross: 0.10
  liquidity:
    min_open_interest: 1000
    max_bid_ask_spread_pct: 1.0

roll_rules:
  pmcc:
    take_profit_pct: 0.50
    roll_up_if_short_delta_gt: 0.35
    roll_out_days: 30
  condor:
    take_profit_pct: 0.50
```

### 中等配置

```yaml
limits:
  delta:
    per_symbol: 500
    total: 3000
  gamma:
    per_symbol: 50
    total: 200
  vega:
    per_symbol: 10000
    total: 30000
  theta_min: 50
  concentration:
    max_symbol_pct_gross: 0.20
  liquidity:
    min_open_interest: 500
    max_bid_ask_spread_pct: 2.0

roll_rules:
  pmcc:
    take_profit_pct: 0.65
    roll_up_if_short_delta_gt: 0.40
    roll_out_days: 21
  condor:
    take_profit_pct: 0.60
```

### 激进配置

```yaml
limits:
  delta:
    per_symbol: 1000
    total: 5000
  gamma:
    per_symbol: 100
    total: 400
  vega:
    per_symbol: 20000
    total: 60000
  theta_min: 100
  concentration:
    max_symbol_pct_gross: 0.30
  liquidity:
    min_open_interest: 100
    max_bid_ask_spread_pct: 5.0

roll_rules:
  pmcc:
    take_profit_pct: 0.75
    roll_up_if_short_delta_gt: 0.50
    roll_out_days: 14
  condor:
    take_profit_pct: 0.70
```

---

## 风险免责声明

⚠️ **重要提示**

1. 本风险管理系统提供的是辅助分析工具，不构成投资建议
2. Greeks 计算基于模型假设，实际市场表现可能不同
3. 限额设置应根据个人风险承受能力调整
4. 系统生成的调整建议仅供参考，最终决策由用户负责
5. 期权交易具有高风险，可能损失全部本金