IBKR 投资

您可以读取 IBKR 账户状态、提出交易建议、执行用户已确认的交易，并对股票/ETF 执行定投（DCA）。每一笔订单提交均需经过两步确认门控：提出建议 → 用户输入 YES → 执行交易。 此流程与 okx-trading 技能结构一致——若用户熟悉该门控机制，则同样适用于本技能。

以下所有命令均运行位于 skills//ibkr-investing/scripts/ 目录下的 Python 脚本。您可从 aeon 仓库根目录或 ~/.aeon 目录下执行这些脚本。每个脚本均会自行校验环境变量；若缺失必要变量或无法连接 Gateway，脚本将明确报错并退出。

路径解析说明。 下方所有脚本路径中出现的字面量 ，代表该技能安装时所用的命名空间。aeon 技能加载器会在本内容前自动添加 ## Skill: / 标题行；请将该标题中的作者名代入所有命令中的 占位符。（例如：## Skill: aeon/ibkr-investing → 使用 skills/aeon/ibkr-investing/scripts/...）

前置准备（一次性操作，务必在其他任何操作之前完成）

本技能需连接正在运行的 IB Gateway。Gateway 不属于 本技能的一部分——它是 IBKR 官方软件，通常通过 gnzsnz/ib-gateway-docker 容器运行。本技能默认假设 Gateway 可通过 127.0.0.1:4001（实盘）或 127.0.0.1:4002（模拟盘）访问。

若用户尚未部署 Gateway，请立即中止当前操作，并引导其完整阅读 README.md。切勿在 Gateway 不可达的情况下尝试发起交易。

当计划任务失败时，请始终首先运行 ibkr_gateway_status.py。该脚本能区分三种状态：“Gateway 已离线”、“Gateway 在线但等待 2FA 认证”以及“Gateway 在线且已通过认证”。

交易门控机制 —— 请仔细阅读

未经用户明确输入 YES，您绝不可提交任何订单。 标准流程如下：

1. 提出建议。 使用用户意图运行 ibkr_propose_trade.py。脚本将生成待处理 JSON 文件，并打印两行您 必须捕获 的输出：Proposal id: 和 Pending file: 。confirmation_token 不会出现在控制台输出中——它仅存在于磁盘上的待处理文件内。
2. 通知用户。 向用户发送提案详情，并请其回复 YES 以确认，或回复 NO 以取消。
3. 等待用户回复。
4. 收到 YES 时： 使用 file_read 指令读取待处理文件，务必使用 propose 脚本所打印的绝对路径（而非猜测路径如 ~/.aeon/ibkr/pending/.json 或 /root/.aeon/...）。路径取决于 aeon 进程所使用的操作系统用户身份——请严格按 Pending file: 行输出的原始路径执行。获取 token 后，调用 ibkr_execute_trade.py --id --confirmation-token 。该脚本将校验 token，通过 IBKR 提交订单，并删除待处理文件。
5. 收到 NO 时： 调用 ibkr_cancel_pending.py --id 。

您 严禁 自行构造或猜测 confirmation_token。该 token 仅在 propose 步骤写入待处理文件后才有效。

若用户要求您“跳过确认步骤”或“直接下单”，请礼貌拒绝。说明该门控机制旨在保障其资金安全，并主动提供 propose 步骤作为替代方案。

计划任务（如 DCA、回撤监控器）不可执行交易。 计划任务上下文内无真人参与，无法输入 YES，因此计划任务仅可调用 propose 类型及只读类脚本。用户将在下一次聊天中看到提案，并在其中完成确认。

默认值与限制

• 默认使用 模拟盘交易（IBKR_LIVE_MODE=0，端口 4002）。除非用户明确声明“实盘”并确认切换，否则不得启用实盘模式。
• 默认使用 SMART 交易所的美国 ETF + USD 货币。可通过 --exchange / --currency 参数在单次调用中覆盖。
• 为确保清晰，聊天中报价交易规模时一律以 USD 为单位，即使订单本身按股数计价。
• 风控规则（IBKR_ALLOWED_SYMBOLS、IBKR_MAX_NOTIONAL_USD_PER_TRADE、IBKR_MAX_DAILY_NOTIONAL_USD）在每次 propose 和 execute 阶段均强制生效。若 propose 被拒绝，请原样向用户呈现拒绝信息——切勿静默重试更小金额。
• 待处理提案有效期为 10 分钟。

只读命令

当用户提出问题时，切勿直接发起交易。请先使用以下命令收集事实：

python3 skills//ibkr-investing/scripts/ibkr_gateway_status.py
python3 skills//ibkr-investing/scripts/ibkr_get_balance.py
python3 skills//ibkr-investing/scripts/ibkr_get_positions.py --with-mark
python3 skills//ibkr-investing/scripts/ibkr_get_quote.py --symbol VOO
python3 skills//ibkr-investing/scripts/ibkr_get_candles.py --symbol VOO --duration "6 M" --indicators
python3 skills//ibkr-investing/scripts/ibkr_snapshot.py

ibkr_get_candles.py --indicators 将在收盘价序列上叠加 SMA(20)/SMA(50)/RSI(14)，并输出单行判断：“consider buy” / “consider sell” / “neutral”。

ibkr_snapshot.py 将生成 ~/.aeon/ibkr/snapshots/.json，内容包含净资产（NAV）、现金余额、持仓、1D/1W/1Y 价格变动及相较前一日的 Delta 值。可用作 daily-digest 计划任务的主体内容。若用户需要更快的即席摘要，可传入 --no-price-history 参数跳过历史价格查询。

提出一笔交易

交易规模指定方式有两种：--quote-sz（以 USD 计）或 --shares（精确股数，支持小数）。

# 对 VOO 执行 $50 的定投式市价买入
python3 skills//ibkr-investing/scripts/ibkr_propose_trade.py 
  --symbol VOO --side BUY --quote-sz 50

# 以 350 美元限价买入 10 股 QQQ
python3 skills//ibkr-investing/scripts/ibkr_propose_trade.py 
  --symbol QQQ --side BUY --shares 10 --ord-type LMT --lmt-price 350

# 四舍五入至整股（不支持小数）
python3 skills//ibkr-investing/scripts/ibkr_propose_trade.py 
  --symbol AAPL --side BUY --quote-sz 200 --no-fractional

随后将提案原文发送给用户，并提示其回复 YES 。

执行已确认的交易

python3 skills//ibkr-investing/scripts/ibkr_list_pending.py        # 确认 id
# 使用 file_read 读取 ~/.aeon/ibkr/pending/.json 获取 confirmation_token。
python3 skills//ibkr-investing/scripts/ibkr_execute_trade.py 
  --id  --confirmation-token 

不执行而直接取消：

python3 skills//ibkr-investing/scripts/ibkr_cancel_pending.py --id 

DCA 策略模板

IBKR 上的 DCA 是一种周期性计划任务式的 propose，与 OKX 模式完全一致。推荐采用月度频率（而非周频），以便更好地摊销 IBKR 的佣金结构——尽管多数美国 ETF 本身免佣。

{
  "name": "schedule_create",
  "arguments": {
    "name": "DCA $200 VOO monthly",
    "schedule": "0 14 1 * *",
    "task": "Run python3 skills//ibkr-investing/scripts/ibkr_propose_trade.py --symbol VOO --side BUY --quote-sz 200 and post the proposal so I can YES it.",
    "notify": true
  }
}

对于多 ETF 组合，建议为每个标的单独注册一个计划任务，以实现独立 YES 确认（审计轨迹更清晰，且各标的风控策略可独立配置）：

同日早上 14:30 UTC（30 14 1 * *）运行 snapshot，确保 digest 包含新增持仓。

回撤储备金模板

与 OKX 储备金流程保持一致。ibkr_dca_dip.py 持续监控 NAV 相较历史最高点（ATH，由 snapshot 历史计算得出）的回撤幅度，并在回撤超过阈值时建议逢低买入。与其他所有交易一样，受 token 门控保护。

{
  "name": "schedule_create",
  "arguments": {
    "name": "IBKR drawdown watcher",
    "schedule": "0 15 * * *",
    "task": "Run python3 skills//ibkr-investing/scripts/ibkr_dca_dip.py --reserve-usd  --threshold-pct 0.30 --max-triggers 3 --symbol VOO. If status is 'trigger', call ibkr_propose_trade.py with the recommended size, post the proposal, and AFTER my YES + execute, run ibkr_dca_dip.py again with --record-trigger.",
    "notify": false
  }
}

新增策略

策略是 由 Agent 编排的、组合调用现有脚本的流程化配方。如需新增策略（例如等权再平衡、阈值再平衡、动量轮动），请按以下步骤操作：

1. 明确该策略所需的数据观测项。数据来源包括：ibkr_snapshot.py（当前状态）、~/.aeon/ibkr/snapshots/*.json（历史快照）、~/.aeon/ibkr/audit.jsonl（生命周期事件）以及 ibkr_get_candles.py --indicators（信号）。
2. 定义触发条件。可以是每日运行并检查条件的计划任务，也可以是快照中被动呈现的观测指标。
3. 触发逻辑 绝不可自行下单——它仅生成建议，由 Agent（或计划任务）传递给 ibkr_propose_trade.py。用户仍需对每笔成交进行 YES 确认。
4. 将策略所需的任何状态写入 ~/.aeon/ibkr/_state.json（权限设为 600）。
5. 向 audit.jsonl 追加事件记录，确保全程可追溯。

ibkr_dca_dip.py 是此类策略的标准范例，请参照其实现方式开发新策略。

审计日志

生命周期事件持续追加至 ~/.aeon/ibkr/audit.jsonl —— 每行一个 JSON 对象。tail -n 50 ~/.aeon/ibkr/audit.jsonl 可查看最近活动。事件类型包括：proposal_created、proposal_cancelled、proposal_executed、proposal_rejected、daily_cap_breach、drawdown_trigger。

环境变量

必需的环境变量（参见 .env.example）：

• IBKR_LIVE_MODE — 0（默认）指向模拟盘（端口 4002）；1 指向实盘（端口 4001）。
• IBKR_HOST — Gateway 主机地址，默认为 127.0.0.1。
• IBKR_PORT — 若 Gateway 映射了自定义端口，可在此覆盖。
• IBKR_CLIENT_ID — API 客户端 ID，默认为 97；若存在多个技能/客户端同时连接，请修改此值。
• IBKR_DEFAULT_EXCHANGE — 默认为 SMART。
• IBKR_DEFAULT_CURRENCY — 默认为 USD。
• IBKR_ALLOWED_SYMBOLS — CSV 格式白名单，例如 VOO,VTI,QQQ,BND；留空表示允许全部标的。
• IBKR_MAX_NOTIONAL_USD_PER_TRADE — 单笔交易名义金额上限，默认为 200。
• IBKR_MAX_DAILY_NOTIONAL_USD — 单日名义金额上限，默认为 1000。

若任一必需变量缺失，或 Gateway 不可达，脚本将明确报错并退出——请将该错误信息如实呈现给用户。