本页为 Skill 文档原文(SKILL.md 完整内容,自包含)。AI Agent 抓取本链接后,可直接将以下 markdown 保存为 SKILL.md 作为 Skill 使用。
---
name: ibkr-mcp-config
description: 在豆包中完整配置盈透证券 IBKR MCP 并规避全部已知坑。触发场景:用户要求"配置 IBKR MCP"、"IBKR 授权/重新授权"、"授权又失效/403/401"、"多个会话共用 IBKR token"、"IBKR 定时任务连不上"、"跨会话排队调用 IBKR"、或任何需要初始化/修复 IBKR 接入(含 OAuth 手动授权、跨会话共享 token、并发排队、refresh token 7天到期)的场景。涵盖从零搭建、授权流程、共享配置、并发锁到排障的完整闭环。
---

# IBKR MCP 豆包配置(全坑版)

在豆包中把 IBKR MCP 配到"一次授权、全会话可用、并发排队不互顶"。本 Skill 面向豆包工作任务的多会话/定时任务环境,已踩过的坑全部列入。

## 0. 环境事实(必须先知道)

- 豆包每个会话/定时任务有独立的沙箱文件系统视图:
  - `/runtime/user_skills`(`.user_skills` 软链指向处)= 每会话隔离,各会话各见各的,授权互不可见;
  - `/home/user`(含 `.doubao`、`Doubao`、`.sessions`)= 跨会话共享。
- 结论:token / state / 锁文件必须放 `/home/user/.doubao/shared_ibkr/`,脚本路径常量指向它;不要放 `/runtime/user_skills` 下。
- 执行脚本:`ibkr-mcp` skill 的 `scripts/ibkr.py` 与 `scripts/ibkr_auth.py`(若为旧版未指向共享路径,按第 2 步改造)。
- 关键参数:MCP_URL=`https://api.ibkr.com/v1/api/mcp-public`,TOKEN_URL=`https://api.ibkr.com/oauth2/api/v1/token`,AUTH_URL=`https://api.ibkr.com/oauth2/authorize`,client_id=`90f6e965-0d74-429b-be6f-dae29d9463eb`,redirect=`http://localhost:8080/callback`,scope=`openid profile email account-ids mcp.read mcp.write mcp.orders.submit`。

## 1. 前置检查

1. 网络可达 `api.ibkr.com`(需翻墙;不可达时授权页与 API 均失败)。
2. 确认共享目录存在:`mkdir -p /home/user/.doubao/shared_ibkr`。
3. 运行环境自检:`bash /scripts/check_ibkr_setup.sh`(检查脚本路径、共享目录、token 状态、锁)。

## 2. 一次性配置(跨会话共享 + 排队)

把 `ibkr.py` 与 `ibkr_auth.py` 的数据文件路径改为共享目录(核心三处):

```python
SHARED_DIR = "/home/user/.doubao/shared_ibkr"
TOKEN_FILE  = os.path.join(SHARED_DIR, "ibkr_token.json")
LOCK_FILE   = TOKEN_FILE + ".lock"        # 跨会话 flock 串行锁(必须与 token 同目录)
# ibkr_auth.py 额外:
STATE_FILE  = os.path.join(SHARED_DIR, "ibkr_oauth_state.json")
```

保证:
- 排队:`ibkr.py` 每次调用先 `flock(LOCK_FILE)` 独占,持锁期间才读/刷 token、发 MCP 请求;其他会话调用阻塞等待(默认超时 360s)而非并发刷新——防止 refresh token rotation 重用被服务端撤销(即"互相顶掉")。
- 原子写:token 写入先写 `.tmp` 再 `os.replace`,避免写一半被并发读到。
- 只在一个会话授权:`exchange` 只在主会话执行;其他会话发现 token 失效时只提示,不自动重授权。

## 3. 授权流程(必须手动,含翻墙)

IBKR 走 OAuth2 PKCE(S256),必须人工点链接授权:

1. 生成授权链接:`python3 /scripts/ibkr_auth.py authorize`
2. 把链接发给用户,浏览器打开(需翻墙)→ 登录 IBKR → 授权 → 跳转到 `localhost:8080/callback?code=...&state=...&iss=...`(本地端口打不开/404 属正常)。
3. 让用户把地址栏整串复制、贴回当前会话(必须贴回执行 authorize 的同一个会话)。
4. 兑换并验证:

```bash
python3 /scripts/ibkr_auth.py exchange "<localhost:8080/callback?code=...>"
python3 /scripts/ibkr.py get_account_summary '{}'   # 返回 net_liquidation 即成功
```

## 4. 日常使用

- 任何会话/定时任务直接调用 `ibkr.py <工具名> '[参数JSON]'`,自动读共享 token、持锁排队、过期自动刷新。
- 常用:`get_account_summary '{}'` / `get_account_positions '{}'` / `get_account_trades '{"period":"DAYS_30"}'` / `get_pa_performance_all_periods '{}'`;行情先 `search_contracts '{"query":"TICKER"}'` 拿 `contract_id` 再 `get_price_snapshot '{"contract_id":N}'`。

## 5. 授权到期管理(重要)

- refresh token 生命周期约 7 天(实测),到期必须重新走一次第 3 步,无法绕过。
- 授权时记录 `auth_time`;脚本在到期前 24h 打印预警。建议每 6 天主动重授一次。
- 失败信息若含 `Refresh token has been revoked` / `invalid_grant` → 直接判定"7天到期或被其他会话顶掉",走重新授权,不要反复重试(重试=重用=加速撤销)。

## 6. 排障速查

| 现象 | 原因 | 处理 |
|---|---|---|
| `Refresh token has been revoked` | 7天到期 / 多会话并发刷新 / 别处新授权撤销旧授权 | 重新授权;确保只在主会话授权 |
| MCP 返回 401 空 body | access token 已失效(被撤销) | 重新授权;或等脚本自动刷新 |
| 授权成功但别的会话仍失效 | 会话文件系统隔离,token 写进了别的视图 | 确认脚本指向共享目录;授权/兑换在同一会话 |
| 旧接口 403 | `/v1/api/oauth2/auth` 是死路 | 只用 `oauth2/authorize` PKCE |
| 回调 localhost 打不开 | 正常(回调页无需打开) | 复制地址栏整串贴回 |
| 定时任务高峰不触发 | 排队 | 等重试;或改用非高峰时间 |

## 7. 全部已知坑(实战记录)

### 7.1 授权与 token
1. refresh token 约 7 天过期并被 revoke;旋转不延长 TTL,必须每 6 天主动重授。
2. refresh rotation 不可重用:每次刷新后旧 refresh 作废;绝不用旧值重试,重用会触发服务端撤销整条授权链。
3. 多会话并发刷新同一 refresh = 被判 reuse → revoke("互相顶掉")。用跨会话 flock 串行锁。
4. 多会话各自授权 = 新授权撤销旧授权。只在主会话授权。
5. access token 有效期约 5 分钟(expires_in=299s);脚本逻辑:剩余 >60s 复用、否则才刷。
6. 401 空 body 说明 access 被撤销(非限流);不要反复重试已 revoke 的 refresh。
7. token 必须原子写(.tmp + os.replace);authorize 的 state/verifier 一次有效,重新 authorize 会使旧链接失效。

### 7.2 豆包环境文件系统
8. /runtime/user_skills 每会话隔离(hpvs_fs 虚拟视图):会话 A 写入的 token 会话 B 看不到——"授权成功但别处失效"的头号原因。
9. /home/user 跨会话共享:token/state/锁必须放 /home/user/.doubao/shared_ibkr/。
10. flock 锁只在同一文件系统有效:锁与 token 同目录才真跨会话互斥;锁放隔离目录等于没锁。
11. 定时任务环境与交互会话的关系:先跑自检脚本确认共享目录与 token 是否同一份。

### 7.3 接口与参数
12. 旧授权接口 /v1/api/oauth2/auth(OAuth1 式)403 死路;必须用 oauth2/authorize(PKCE S256)。
13. get_account_trades 参数是 {"period":"DAYS_30"},不是 days/7D。
14. get_price_snapshot 只有 last.price / last.ts,无盘中/盘后/盘前/夜盘分段字段;要时段价需另接富途。
15. 行情前先 search_contracts 拿 contract_id;get_price_history 服务端偶发报错可重试。
16. NAV 序列会被后端修正(如 106,595.52→108,359.50),每次以最新拉取为准,不缓存旧值。

### 7.4 数据口径(损益核算)
17. 期权指派重复入账:trade feed 可能把一次指派写两条(同 symbol+side+price+size 且 <48h),保留最早一条。
18. 期初数量 = 期末数量 − 期间净买入 + 期间净卖出;30 天窗口覆盖不到更早存量时用持仓演化交叉验证。
19. 正股损益 = 最新市值(最新价×期末数量)− 期初市值(期初数量×期初收盘价)− 期间净买入金额(买入支出−卖出收入)。
20. 期权损益 = 期间权利金净现金流(卖出+, 买入−)+ 期末未平仓期权市值(positions 的 market_value,空头为负)。
21. 占比 = 各标的损益 ÷ 各标的损益合计(1 位小数,带正负号)。
22. 净入金口径:总损益 = 最新NLV − 期初NLV − 期间净入金(以 NAV 序列跳升幅度确认)。

### 7.5 流程与协作
23. 回调必须贴回同一会话;授权后立即验证(get_account_summary 返回 net_liquidation 才算完成)。
24. 定时任务 query 里不写 token/密码;token 只存共享文件。
25. 高峰(7:30-10:00 等)定时任务可能排队延迟触发,报告标注取数北京时间。