ib-stop-loss

IB 止损管理器

分析 IB 投资组合中的 PMCC（对角看涨期权价差）、裸 LEAPS 和股票持仓，并管理条件止损订单。

默认模式为模拟运行——除非请求中包含 --execute，否则不会下单。

IB 连接

TWS 或 IB Gateway 必须在本地运行，并启用 API：

• 模拟交易 — 端口 7497
• 实盘交易 — 端口 7496
• IB_PORT 环境变量 — 未提供 --port 时的默认端口（例如，Gateway 容器使用 IB_PORT=4001）。优先级：--port 标志 > IB_PORT > 内置默认值。在 shell 或 .env 文件中设置。

端口回退： 如果配置的端口连接失败，则自动尝试另一个端口。 如果重试成功，则将成功连接的账户类型（实盘/模拟）保存到记忆中，并在本次及后续会话中复用于所有 IB 技能调用，直到用户明确要求切换到另一种账户。 如果两个端口都连接失败，请让用户确认 TWS 或 IB Gateway 正在运行且已启用 API 访问。

说明

第 1 步：运行脚本

模拟运行（默认——不会下单）：

uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py

执行（取消孤立订单 + 下达 SL_ 条件订单）：

uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py --execute

强制执行（以当前中间价为基准，可能降低现有止损价）：

uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py --execute --forced

第 2 步：整理报告

将 JSON 输出整理为包含四个部分的 Markdown 报告：

第 1 部分：即将触发提醒

醒目列出 alert_soon 中的标的——这些标的已超过早期预警阈值。

第 2 部分：现有条件订单

显示 all_conditional_orders.module（SL_ 订单）和 all_conditional_orders.manual（手动下单）。 如果 orphan_orders 不为空，请提醒用户这些订单已被取消（执行模式）或需要手动取消（模拟运行）。

第 3 部分：持仓

对于 positions 中的每个条目，显示一个表格：

字段	值
标的	NVDA — pmcc（3 份合约）
现价	$219.05
LEAPS	200C 20270115 · 平均成本 $44.27 · 当前 $44.23 · 基准 $44.27
止损价	$22.14（40% 止损）→ 操作：place_new
LEAPS 亏损	0.1%
空头	235C 20260515 · 收取 $0.61 · 当前 $0.56 · 已衰减 9.5%

如果已有保护性更强的止损，请显示 preserve_existing。 如果 forced=true 降低了现有止损，请显示 overwrite（红色）。

第 4 部分：提醒

按标的分组显示提醒。类型：

类型	含义
leaps_early_warning	LEAPS 相对于基准下跌 ≥ stop_pct/2%
short_premium_decay	已收回 90% 以上的空头期权权利金——平仓或展期
short_near_strike	现价达到或高于空头行权价，或距离该行权价在 X% 以内

第 3 步：向用户报告

• 醒目说明是模拟运行模式还是执行模式。
• 首先列出 alert_soon 中的标的。
• 对于每个持仓，显示止损操作和当前亏损百分比。
• 最后显示提醒部分。

参数

标志	默认值	描述
--port	7497	IB Gateway/TWS 端口
--account	all	指定账户 ID
--symbols	all	仅分析这些标的
--legs	none	指定期权腿：SYMBOL:STRIKE[C|P]:EXPIRY（例如 IBKR:70C:20270115 IBKR:100C:20260918）。右侧默认值为 C。优先于 --symbols。当同一标的上有多个 PMCC/LEAPS 组合，且只应为其中一组设置止损时使用。
--stop-pct	40	触发退出的亏损百分比
--short-near-strike-pct	5	接近行权价的提醒阈值
--price-mode	mid	期权定价：mid 或 last
--execute	off	取消孤立订单 + 下达 SL_ 订单
--forced	off	使用当前中间价作为基准（需要 --execute）

JSON 输出结构

{
  "generated_at": "2026-05-12 10:00 ET",
  "dry_run": true,
  "forced": false,
  "stop_pct": 40.0,
  "short_near_strike_pct": 5.0,
  "accounts": ["U1234567"],
  "symbols_filter": null,
  "all_conditional_orders": {"module": [], "manual": []},
  "orphan_orders": [],
  "alert_soon": ["PFE"],
  "positions": [
    {
      "symbol": "NVDA",
      "type": "pmcc",
      "account": "U1234567",
      "qty": 3,
      "underlying_price": 219.05,
      "leaps": {
        "strike": 200.0, "expiry": "20270115", "avg_cost": 44.27,
        "current_price": 44.23, "stop_basis": 44.27,
        "stop_price": 22.14, "loss_pct": 0.1
      },
      "shorts": [
        {"strike": 235.0, "expiry": "20260515",
         "premium_received": 0.61, "current_price": 0.56, "decay_pct": 9.5}
      ],
      "stop_loss": {"stop_price": 22.14, "action": "place_new", "existing_stop": null},
      "alert_soon": false,
      "alerts": []
    },
    {
      "symbol": "AAPL",
      "type": "stock",
      "account": "U1234567",
      "qty": 100,
      "underlying_price": 189.50,
      "stock": {
        "avg_cost": 175.00, "stop_basis": 189.50,
        "stop_price": 94.75, "loss_pct": 0.0
      },
      "stop_loss": {"stop_price": 94.75, "action": "place_new", "existing_stop": null},
      "alert_soon": false,
      "alerts": []
    }
  ]
}

关键字段

• alert_soon — 顶层符号列表，其中亏损 ≥ stop_pct/2%
• position.type — pmcc | leaps | stock
• stop_loss.action — place_new | preserve_existing | overwrite
• stop_loss.existing_stop — 若存在，则为现有 SL_FALL_ 订单的价格
• 对于 PMCC：止损订单是一个组合（BAG）订单，可同时平掉 LEAPS 和所有空头头寸
• 在执行模式下：首先取消孤立的 SL_ 订单（没有匹配的持仓）

订单识别

• SL_FALL_{SYM}_{STRIKE}_{EXPIRY} — 期权（PMCC 或裸 LEAPS）
• SL_FALL_{SYM}_STK — 股票持仓

架构

所有分析逻辑都位于 src/trading_skills/broker/stop_loss.py：

分析（不调用 IBKR — 可独立测试）：

• calc_stop_basis — 通常取 max(mid, avg_cost)；强制时取 current_mid
• calc_stop_price — basis × (1 - stop_pct/100)
• calc_short_premium_decay_pct — 已收取的空头权利金百分比
• identify_positions — 将标准化持仓分类为 pmcc/leaps/stock
• build_position_analysis — 为每个持仓构建完整的输出字典
• detect_orphan_orders — 检测已无对应持仓的 SL_FALL_ 订单
• summarize_all_conditional_orders — 将 IB 订单拆分为模块订单和手动订单

数据层（IBKR）：

• get_stop_loss_data — 主入口
• _cancel_orphan_orders — 取消过期的 SL_ 订单
• _place_combo_stop_order — 为 PMCC 下达 BAG 订单（以原子方式平掉 LEAPS 和空头头寸）
• _place_simple_stop_order — 为裸 LEAPS 或股票下达单个订单
• _execute_position_stop — 按持仓类型分派处理