# IBKR-MCP 架构概览
## 简介
IBKR-MCP 是一个 Model Context Protocol (MCP) 服务器，将 AI 助手与 Interactive Brokers (IBKR) 连接起来，实现智能投资组合管理、期权链扫描分析、技术指标筛选以及风险组合管理等功能。
## 整体架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ AI 助手 │
│ (AlphaMeta Desktop / MCP 客户端) │
└─────────────────────────────────┬───────────────────────────────────┘
│ MCP 协议 (stdio/http)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ IBKR-MCP 服务器 │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────┐ │
│ │ 工具层 │ │ 资源层 │ │ 生命周期上下文 │ │
│ │ (api/tools.py)│ │(api/resources)│ │ (IBKRContext) │ │
│ └───────┬───────┘ └───────┬───────┘ └───────────┬───────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 服务层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────┐ │ │
│ │ │ 投资组合 │ │ 风险服务 │ │ 期权数据 │ │ 新闻服务 │ │ │
│ │ │ Portfolio │ │ Risk │ │ OptionData │ │ News │ │ │
│ │ │ Manager │ │ Service │ │ Service │ │ Service │ │ │
│ │ └─────────────┘ └─────────────┘ └────────────┘ └──────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────┐ ┌───────────┐ ┌─────────────┐ │ │
│ │ │ 投资组合 │ │ 风险服务 │ │ 期权数据 │ │ 新闻服务 │ │ 期权链 │ │ 数据富化 │ │ │
│ │ │ Portfolio │ │ Risk │ │ OptionData │ │ News │ │ Option │ │ Data │ │ │
│ │ │ Manager │ │ Service │ │ Service │ │ Service │ │ Chain │ │ Enrichment │ │ │
│ │ └─────────────┘ └─────────────┘ └────────────┘ └──────────┘ └──────────┘ └───────────┘ │ │
│ │ (含调度器) │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 策略层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │ Covered │ │ Iron │ │ PMCC │ │ Vertical │ │ │
│ │ │ Call │ │ Condor │ │ │ │ Spread │ │ │
│ │ └─────────────┘ └─────────────┘ └──────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 公共层 │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐ │ │
│ │ │ Greeks │ │ 规则 │ │ Playbook │ │ 持仓 │ │ 市场 │ │ │
│ │ │ Calculator│ │ 评估 │ │ 引擎 │ │ 存储 │ │ 数据 │ │ │
│ │ └─────────┘ └─────────┘ └──────────┘ └─────────┘ └────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 基础设施层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│ │ │ 仓库 │ │ 模型 │ │ 数据库 │ │ │
│ │ │Repository │ │ Models │ │ Database │ │ │
│ │ │ 模式 │ │ (SQLAlchemy)│ │ 管理器 │ │ │
│ │ └─────────────┘ └─────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
│ ib_async
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Interactive Brokers │
│ (TWS / IB Gateway via TCP) │
└─────────────────────────────────────────────────────────────────────┘
```
### Mermaid 图例
```mermaid
graph TB
subgraph "AI 助手层"
AI[AI 助手<br/>AlphaMeta Desktop<br/>MCP 客户端]
end
subgraph "IBKR-MCP 服务器"
subgraph "API 层"
TOOLS[工具层<br/>api/tools.py]
RES[资源层<br/>api/resources.py]
CTX[生命周期上下文<br/>IBKRContext]
end
subgraph "服务层"
PM[投资组合服务<br/>PortfolioManager]
RS[风险服务<br/>RiskService]
ODS[期权数据服务<br/>OptionDataService]
NS[新闻服务<br/>NewsService]
OCS[期权链服务<br/>OptionChainService]
DES[数据富化服务<br/>DataEnrichment]
end
subgraph "策略层"
CC[备兑看涨<br/>CoveredCall]
IC[铁鹰<br/>IronCondor]
PMCC[穷人备兑<br/>PMCC]
VS[垂直价差<br/>VerticalSpread]
end
subgraph "公共层"
GC[Greeks 计算器<br/>greeks.py]
RE[规则评估<br/>rules.py]
PE[Playbook 引擎<br/>playbooks.py]
PL[持仓缓存<br/>PositionLive]
OD[期权数据<br/>option_data.py]
MS[市场状态<br/>market_state.py]
TI[技术指标<br/>technical_indicators.py]
end
subgraph "基础设施层"
REP[仓库模式<br/>repositories.py]
MOD[数据模型<br/>models.py]
DM[数据库管理器<br/>manager.py]
end
end
subgraph "IBKR 连接"
IB[Interactive Brokers<br/>TWS / IB Gateway]
end
%% 连接关系
AI -->|MCP 协议<br/>stdio/http| TOOLS
AI -->|MCP 协议<br/>stdio/http| RES
TOOLS --> CTX
RES --> CTX
CTX --> PM
CTX --> RS
CTX --> ODS
CTX --> NS
CTX --> OCS
CTX --> DES
PM --> GC
RS --> GC
RS --> RE
RS --> PE
ODS --> OD
ODS --> PL
PM --> CC
PM --> IC
PM --> PMCC
PM --> VS
CC --> GC
IC --> GC
PMCC --> GC
VS --> GC
PS --> REP
OD --> REP
REP --> MOD
REP --> DM
ODS -->|ib_async| IB
PM -->|ib_async| IB
RS -->|ib_async| IB
NS -->|ib_async| IB
%% 样式
classDef aiLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef apiLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef serviceLayer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
classDef strategyLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef commonLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px
classDef infraLayer fill:#f1f8e9,stroke:#33691e,stroke-width:2px
classDef ibkrLayer fill:#ffebee,stroke:#b71c1c,stroke-width:2px
class AI aiLayer
class TOOLS,RES,CTX apiLayer
class PM,RS,ODS,NS serviceLayer
class CC,IC,PMCC,VS strategyLayer
class GC,RE,PE,PS,OD,MS commonLayer
class REP,MOD,DM infraLayer
class IB ibkrLayer
```
## 模块结构
```
src/ibkr_mcp/
├── __init__.py # 包入口
├── __main__.py # CLI 入口
├── server.py # FastMCP 服务器 & IBKRContext & 生命周期管理
├── core/ # 核心组件层
│ ├── __init__.py
│ ├── greeks.py # Greeks 计算器
│ ├── rules.py # 风险规则评估
│ ├── playbooks.py # Playbook 操作生成
│ ├── positions.py # PositionLive 实时持仓 & 标准化
│ ├── option_data.py # 期权链处理 (IBKR & 本地数据获取器)
│ ├── market_state.py # 市场状态管理
│ ├── stock_data.py # 股票数据处理
│ └── technical_indicators.py # 技术指标
├── services/ # 业务服务层
│ ├── __init__.py
│ ├── base.py # 服务基类 & 连接管理
│ ├── portfolio.py # PortfolioManager 投资组合管理
│ ├── risk_service.py # RiskService 风险评估
│ ├── option_data.py # OptionDataService 期权数据 & 调度器
│ ├── option_chain.py # OptionChainService 期权链扁平化模型
│ ├── stock_data.py # StockDataService 股票数据服务
│ ├── market_data.py # MarketDataService 市场数据服务
│ ├── news_service.py # NewsService 新闻服务
│ ├── data_enrichment.py # DataEnrichmentService 技术指标与市场状态
│ ├── strategy_analysis.py # StrategyAnalysisService 策略分析
│ ├── strategy_factory.py # StrategyFactory 策略工厂
│ └── trade.py # TradeService 交易服务 (可选)
```
## 核心组件
### 1. 服务器层 (`server.py`)
**IBKRContext** - 中央上下文对象，管理：
- IB 客户端连接生命周期
- 数据库初始化
- 调度器管理
- 服务实例化
- 持仓缓存初始化
```python
class IBKRContext:
"""Async context manager for IBKR lifecycle."""
def __init__(self, ib: IB) -> None:
"""Initialize with synchronous operations only."""
self.ib = ib
# 1. Initialize external services
self.portfolio_manager = PortfolioManager(self.ib)
self.risk_service = RiskService(self.ib)
self.news_service = NewsService(self.ib)
# 2. Initialize real-time data component
self.position_live = PositionLive(self.ib)
self.position_live.initialize()
# 3. Initialize flattened model services
self.option_chain_service = OptionChainService(self.ib)
self.stock_data_service = StockDataService(...)
# 4. Initialize data enrichment service
self.data_enrichment_service = DataEnrichmentService(...)
# 5. Initialize OptionDataService with constructor injection
self.option_data_service = OptionDataService(
self.ib,
position_store=self.position_live,
...
)
```
**生命周期管理** - 异步上下文管理器模式：
```python
@asynccontextmanager
async def ibkr_lifespan(_server: FastMCP) -> AsyncIterator[IBKRContext]:
ib = IB()
await ib.connectAsync(IBKR_HOST, IBKR_PORT, ...)
# Use IBKRContext as async context manager
async with IBKRContext(ib=ib) as ctx:
yield ctx
# Cleanup handled by IBKRContext.__aexit__
```
**传输模式支持** - 支持 stdio 和 HTTP 两种传输模式：
- stdio 模式：传统 MCP 传输方式
- HTTP 模式：通过 FastMCP 的 streamable HTTP，支持 CORS
### 2. API 层 (`api/`)
**MCP 工具层** (`tools.py`) - 薄包装器，委托给 IBKRContext：
| 工具类别 | 工具 | 描述 |
|----------|------|------|
| 投资组合 | `get_portfolio` | 投资组合持仓及盈亏 |
| 投资组合 | `get_greeks_summary` | 组合 Greeks 汇总 |
| 期权数据 | `get_option_chains` | 期权链快照（实时或缓存） |
| 期权数据 | `scan_option_signals` | 策略交易信号扫描 |
| 风险评估 | `evaluate_portfolio_risk` | 风险限额评估 |
| 风险评估 | `generate_playbook_actions` | 调整建议生成 |
| 新闻服务 | `get_historical_news` | 历史新闻检索 |
| 调度器管理 | `start_option_chain_scheduler` | 启动自动获取调度器 |
| 调度器管理 | `stop_option_chain_scheduler` | 停止调度器 |
| 调度器管理 | `get_schedule_status` | 获取调度器状态 |
| 调度器管理 | `update_schedule_times` | 更新时间表 |
**MCP 资源层** (`resources.py`) - 只读数据访问（URI模板模式）：
```python
# 资源定义示例
@mcp.resource("ibkr://account_summary")
async def account_summary() -> Dict[str, Any]: ...
@mcp.resource("ibkr://positions/{account}")
async def get_positions(account: str) -> List[Dict[str, Any]]: ...
```
**工具辅助函数**：
```python
def _ctx(ctx: Context) -> IBKRContext:
"""Helper to extract the strongly-typed IBKRContext from FastMCP Context."""
return cast(IBKRContext, ctx.request_context.lifespan_context)
```
### 3. 服务层 (`services/`)
**PortfolioManager** - 投资组合管理
- `get_account_summary()` - 获取账户余额、保证金、购买力
- `get_portfolio()` - 获取组合持仓及盈亏
**RiskService** - 风险评估工作流
- `get_greeks_summary()` - 计算组合 Greeks
- `evaluate_portfolio_risk()` - 检查风险限额
- `generate_playbook_actions()` - 生成调整建议
**OptionDataService** - 期权数据服务（含调度器）
- `fetch_option_chains()` - 实时或缓存链数据
- **调度器功能**：
- 自动定期获取期权链数据
- 支持配置化时间表（config.yaml）
- 与PositionLive集成，自动检测持仓标的
- 支持时区配置和手动触发
**OptionChainService** - 期权链扁平化模型
- `get_option_chain()` - 获取期权链扁平化数据
- `get_option_chain_by_expiry()` - 按到期日获取期权链
**StockDataService** - 股票数据服务
- `get_stock_info()` - 获取股票基本信息
- `get_stock_bars()` - 获取股票K线数据
**DataEnrichmentService** - 数据富化服务
- `calculate_technical_indicators()` - 计算技术指标
- `get_market_state()` - 获取市场状态
**StrategyAnalysisService** - 策略分析服务
- `analyze_strategies()` - 分析期权策略
**NewsService** - 新闻检索
- `get_historical_news()` - 按标的获取历史新闻
### 4. 策略层 (`strategies/`)
期权策略实现，继承 `BaseOptionStrategy`：
| 策略 | 描述 |
|------|------|
| CoveredCallStrategy | 基于收益率的备兑看涨建议 |
| IronCondorStrategy | Delta 目标的铁鹰构建 |
| PoorMansCoveredCallStrategy | LEAPS + 短期看涨机会 |
| VerticalSpreadStrategy | 方向性牛/熊价差 |
### 5. 公共层 (`core/`)
**GreekCalculator** - Greeks 计算流程：
```
持仓 → 列补齐 → IB数据填充 → 股票Delta兜底(=1) → 数量×乘数缩放 → 按标的聚合
```
**RiskEvaluator** - 风险规则检查：
- 单标的 Greek 限额
- 组合级 Greek 限额
- Theta 下限
- 集中度限制
- 流动性检查
**PlaybookEngine** - 策略特定的调整生成：
- PMCC 滚动规则
- Condor 止盈规则
**PositionLive** - 实时持仓缓存
- 订阅 IB 事件更新
- 实时价格和 Greeks 更新
- 多账户支持
**市场数据组件**：
- `market_state.py` - 市场状态管理
- `stock_data.py` - 股票数据处理
- `technical_indicators.py` - 技术指标计算
### 6. 数据库层 (`database/`)
**DatabaseManager** (`manager.py`) - 数据库连接管理器：
- 支持 SQLite（默认）、PostgreSQL、MySQL
- 异步SQLAlchemy引擎和会话管理
- 连接池管理和数据库初始化
- 基于环境变量的灵活配置
**ORM 模型** (`models.py`) - SQLAlchemy 数据模型：
- `OptionChainSnapshot` - 期权链快照存储
- `TradeRecord` - 交易记录
- `TradeFill` - 交易执行详情
- `GreeksHistory` - Greeks 历史记录
- `RiskAlert` - 风险警报
- `MarketDataSnapshot` - 市场数据快照
**仓库模式** (`repositories.py`) - 数据访问抽象：
- `BaseRepository[T]` - 通用CRUD操作
- `OptionChainRepository` - 期权链数据访问
- `TradeRecordRepository` - 交易记录访问
- `GreeksHistoryRepository` - Greeks历史访问
## 业务流程
### 1. 整体业务流程概览
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ IBKR-MCP 完整业务流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 阶段 1 │─────▶│ 阶段 2 │─────▶│ 阶段 3 │─────▶│ 阶段 4 │
│ 服务启动 │ │ 持仓管理 │ │ 风险评估 │ │ 期权数据 │
│ │ │ │ │ │ │ 获取 │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 阶段 5 │─────▶│ 阶段 6 │─────▶│ 阶段 7 │─────▶│ 阶段 8 │
│ 策略分析 │ │ 信号生成 │ │ 交易执行 │ │ 数据持久化 │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```
---
### 2. 服务启动与初始化流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 服务启动与初始化流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ IBKR-MCP │
│ 服务器启动 │
│ server.py:45 │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ IBKRContext 初始化 │
│ server.py:112-147 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ IB 客户端 │ │ PositionLive │ │ PortfolioMgr │ │
│ │ - 连接 IBKR │ │ - 实时订阅 │ │ - 账户摘要 │ │
│ │ - TCP 连接 │ │ - 持仓缓存 │ │ - 持仓查询 │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ RiskService │ │ OptionData │ │ NewsService │ │
│ │ - 风险评估 │ │ - 期权链获取 │ │ - 历史新闻 │ │
│ │ - Greeks 计算 │ │ - 调度器管理 │ │ - 情感分析 │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 数据库初始化 │
│ database/manager.py:45 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建连接池 (asyncpg/aiosqlite) │
│ 2. 运行迁移脚本 (alembic) │
│ 3. 创建索引 │
│ 4. 验证表结构 │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 调度器启动 (可选) │
│ market_data.py:289-312 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ APScheduler │ │
│ │ - 基于配置的时间表 (config.yaml) │ │
│ │ - 市场开盘/收盘时自动触发 │ │
│ │ - 持仓标的自动发现 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 监听 IBKR 持仓事件 │ │
│ │ - positionUpdate │ │
│ │ - updatePortfolio │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 生命周期管理就绪 │
└──────────────────────────────────────────────────────────────────┘
```
---
### 3. 持仓管理流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 持仓管理流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ MCP 工具调用 │
│ get_portfolio │
│ api/tools.py │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ PortfolioManager 查询 │
│ services/portfolio.py:67 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 1. 请求账户摘要 (reqAccountSummary) │
│ 2. 请求投资组合 (reqPositions) │
│ 3. 请求市场数据 (reqMktData) │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ IBKR API 响应处理 │
│ services/base.py:134 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 账户摘要 │ │ 持仓列表 │ │ 市场数据 │ │
│ │ │ │ │ │ │ │
│ │ - 净值 │ │ - 标的 │ │ - 最新价格 │ │
│ │ - 保证金 │ │ - 数量 │ │ - Bid/Ask │ │
│ │ - 购买力 │ │ - 成本 │ │ - Greeks │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ PositionLive 标准化处理 │ │
│ │ core/positions.py:234 │ │
│ │ │ │
│ │ - 合并重复合约 │ │
│ │ - 计算未实现盈亏 │ │
│ │ - 归一化字段 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Greeks 计算流程 │
│ core/greeks.py:156 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 持仓 ──► 列补齐 ──► IB数据填充 ──► 股票Delta兜底(=1) ──► 数量×乘数缩放 ──► 按标的聚合
│ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ Delta 计算 │ │ Gamma 计算 │ │ Vega 计算 │ │
│ │ - 方向性风险 │ │ - 凸性风险 │ │ - 波动率风险 │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ Theta 计算 │ │ Rho 计算 │ │
│ │ - 时间衰减 │ │ - 利率风险 │ │
│ └────────────────┘ └────────────────┘ │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 标准化响应格式 │
│ services/portfolio.py:178 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ { │
│ "account": "U123456", │
│ "positions": [ │
│ { │
│ "symbol": "AAPL", │
│ "asset_type": "STOCK", │
│ "quantity": 100, │
│ "avg_cost": 150.0, │
│ "market_price": 155.0, │
│ "unrealized_pnl": 500.0, │
│ "greeks": { │
│ "delta": 1.0, │
│ "gamma": 0.0, │
│ "theta": 0.0, │
│ "vega": 0.0 │
│ } │
│ } │
│ ] │
│ } │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ MCP 响应返回 │
└──────────────────────────────────────────────────────────────────┘
```
---
### 4. 风险评估流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 风险评估流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ MCP 工具调用 │
│evaluate_portfolio│
│ _risk │
│ api/tools.py │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ RiskService 风险评估 │
│ services/risk_service.py:89 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ 获取组合 │ │ 获取持仓 │ │ 获取 Greeks │ │
│ │ PortfolioMgr │ │ PositionLive │ │ GreekCalculator│ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 风险规则评估 │
│ core/rules.py:178 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 1. 单标的 Greek 限额检查 │ │
│ │ - Delta 限制: |Δ| ≤ 0.3 │ │
│ │ - Gamma 限制: Γ ≤ 0.1 │ │
│ │ - Vega 限制: V ≤ 0.2 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 2. 组合级 Greek 限额检查 │ │
│ │ - 净 Delta: |Σ(Δ×数量×乘数)| ≤ 0.5 │ │
│ │ - 净 Vega: Σ(V×数量×乘数) ≤ 0.3 │ │
│ │ - 净 Theta: Θ ≥ -$1000 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 3. 集中度限制 │ │
│ │ - 单标的占比 ≤ 30% │ │
│ │ - 同行业占比 ≤ 50% │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 4. 流动性检查 │ │
│ │ - 最小成交量 ≥ 100 │ │
│ │ - 最大买卖价差 ≤ 5% │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 风险违规处理 │
│ core/rules.py:234 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 轻微违规 │ │ 中度违规 │ │ 严重违规 │ │
│ │ │ │ │ │ │ │
│ │ - 记录警告 │ │ - 建议调整 │ │ - 强制平仓 │ │
│ │ - 继续监控 │ │ - 通知用户 │ │ - 立即执行 │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 风险事件记录 │ │
│ │ database/models.py:234 │ │
│ │ │ │
│ │ - RiskAlert 表 │ │
│ │ - 违规详情 │ │
│ │ - 时间戳 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Playbook 动作生成 │
│ core/playbooks.py:156 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ PlaybookEngine │ │
│ │ │ │
│ │ 1. PMCC 滚动规则 │ │
│ │ - 剩余 30 天触发 │ │
│ │ - 移仓至下期 LEAPS │ │
│ │ │ │
│ │ 2. Condor 止盈规则 │ │
│ │ - 盈利 50% 触发 │ │
│ │ - 平仓当前价差 │ │
│ │ │ │
│ │ 3. 对冲建议 │ │
│ │ - Delta 超限时 │ │
│ │ - 建议反向操作 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 风险评估报告 │
│ services/risk_service.py:234 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ { │
│ "summary": { │
│ "total_risk_score": 7.2, │
│ "risk_level": "MEDIUM", │
│ "breaches": 2 │
│ }, │
│ "breaches": [ │
│ { │
│ "type": "DELTA_LIMIT", │
│ "symbol": "AAPL", │
│ "current": 0.35, │
│ "limit": 0.30, │
│ "severity": "HIGH" │
│ } │
│ ], │
│ "actions": [ │
│ { │
│ "type": "ROLL_PMCC", │
│ "symbol": "AAPL", │
│ "rationale": "30 days to expiry", │
│ "details": { │
│ "close_strike": 150, │
│ "open_strike": 155 │
│ } │
│ } │
│ ] │
│ } │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ MCP 响应返回 │
└──────────────────────────────────────────────────────────────────┘
```
---
### 5. 期权数据获取流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 期权数据获取流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ 触发源 │
│ (手动/调度器) │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 标的发现与选择 │
│ services/market_data.py:134 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ PositionLive │ │ 配置列表 │ │
│ │ (实时持仓) │ │ (config.yaml) │ │
│ │ │ │ │ │
│ │ - 已持仓标的 │ │ - 关注列表 │ │
│ └────────────────┘ └────────────────┘ │
│ │ │ │
│ └────────┬───────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 智能过滤 │ │
│ │ │ │
│ │ - 市场开盘时间 │ │
│ │ - 期权可用性检查 │ │
│ │ - 流动性阈值 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ IBKR 期权链获取 │
│ core/option_data.py:234 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 1. 请求期权链元数据 │ │
│ │ reqSecDefOptParams │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 2. 选择到期日 │ │
│ │ - 近月合约 │ │
│ │ - LEAPS (长期期权) │ │
│ │ - 智能过滤 (排除深度价外) │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 3. 选择行权价 │ │
│ │ - 距离排序: ±8 档 │ │
│ │ - ATM 附近优先 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 4. 构建期权合约 │ │
│ │ - Call 合约 │ │
│ │ - Put 合约 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 5. 请求市场数据 │ │
│ │ - Bid/Ask 价格 │ │
│ │ - Mark 价格 │ │
│ │ - Greeks (Δ/Γ/Θ/V) │ │
│ │ - 成交量/持仓量 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 数据快照处理 │
│ core/option_data.py:445 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 数据验证 │ │ 字段标准化 │ │ Greeks 计算 │ │
│ │ │ │ │ │ │ │
│ │ - 价格检查 │ │ - 统一单位 │ │ - 缺失补全 │ │
│ │ - 流动性 │ │ - 格式转换 │ │ - 异常处理 │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ OptionChainSnapshot 构建 │ │
│ │ │ │
│ │ { │ │
│ │ "symbol": "AAPL", │ │
│ │ "underlying_price": 155.0, │ │
│ │ "timestamp": "2024-01-15T10:30", │ │
│ │ "options": [ │ │
│ │ { │ │
│ │ "right": "CALL", │ │
│ │ "strike": 150, │ │
│ │ "expiry": "2024-02-15", │ │
│ │ "bid": 6.5, │ │
│ │ "ask": 6.7, │ │
│ │ "delta": 0.65, │ │
│ │ "gamma": 0.03, │ │
│ │ "theta": -0.08, │ │
│ │ "vega": 0.15 │ │
│ │ } │ │
│ │ ] │ │
│ │ } │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 数据持久化 │
│ database/repositories.py:234 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 数据库存储 │ │ Parquet 文件 │ │
│ │ │ │ │ │
│ │ - PostgreSQL│ │ - 历史数据 │ │
│ │ - OptionChain│ │ - 高性能 │ │
│ │ Snapshot │ │ - 压缩存储 │ │
│ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │
│ └────────┬───────┴───────┬──────────────────────────────┘
│ │ │
│ ▼ ▼
│ ┌─────────────────────────────────────┐
│ │ 异步写入 │
│ │ │
│ │ 1. 数据库事务提交 │
│ │ 2. 文件系统写入 │
│ │ 3. 索引更新 │
│ └─────────────────┬───────────────────┘
│ │
└────────────────────────────┼───────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 策略触发 (可选) │
│ strategies/base.py:89 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CoveredCall │ │ Iron Condor │ │ PMCC │ │
│ │ │ │ │ │ │ │
│ │ - 收益率扫描│ │ - 中性策略 │ │ - 日历价差 │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ TradeSignal 生成 │ │
│ │ │ │
│ │ { │ │
│ │ "strategy": "IronCondor", │ │
│ │ "symbol": "AAPL", │ │
│ │ "signals": [ │ │
│ │ { │ │
│ │ "action": "SELL_CALL", │ │
│ │ "strike": 160, │ │
│ │ "expiry": "2024-02-15" │ │
│ │ }, │ │
│ │ { │ │
│ │ "action": "SELL_PUT", │ │
│ │ "strike": 150, │ │
│ │ "expiry": "2024-02-15" │ │
│ │ } │ │
│ │ ] │ │
│ │ } │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ MCP 响应返回 │
└──────────────────────────────────────────────────────────────────┘
```
---
### 6. 调度器自动获取流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 调度器自动获取流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ APScheduler │
│ 定时任务触发 │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 动态标的列表更新 │
│ services/market_data.py:178 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ PositionLive │ │ 配置监控列表 │ │
│ │ │ │ │ │
│ │ - 实时持仓标的 │ │ - 新增标的 │ │
│ │ - 自动发现 │ │ - 删除标的 │ │
│ └────────────────┘ └────────────────┘ │
│ │ │ │
│ └────────┬───────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 标的列表合并与去重 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 批量期权链获取 │
│ services/market_data.py:234 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 并发控制 │ │
│ │ │ │
│ │ - 最大并发数: 5 │ │
│ │ - 请求间隔: 100ms │ │
│ │ - 重试机制: 3 次 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 批量处理流程 │ │
│ │ │ │
│ │ for symbol in symbols: │ │
│ │ 1. 获取期权链 │ │
│ │ 2. 验证数据质量 │ │
│ │ 3. 存储快照 │ │
│ │ 4. 更新缓存 │ │
│ │ 5. 触发策略分析 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 性能监控与报告 │
│ services/market_data.py:334 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 执行时间 │ │ 成功率统计 │ │ 错误日志 │ │
│ │ │ │ │ │ │ │
│ │ - 总耗时 │ │ - 成功/失败 │ │ - 错误类型 │ │
│ │ - 平均耗时 │ │ - 失败原因 │ │ - 重试次数 │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 调度器状态更新 │ │
│ │ │ │
│ │ - 运行状态: RUNNING │ │
│ │ - 上次执行: 2024-01-15 10:30 │ │
│ │ - 下次执行: 2024-01-15 15:30 │ │
│ │ - 处理标的: 15/15 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 完成并等待下次触发 │
└──────────────────────────────────────────────────────────────────┘
```
---
### 7. 数据库持久化流程
```
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 数据库持久化流程 │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ 数据写入请求 │
│ (期权链/交易/持│
│ 仓) │
└──────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Repository 模式 │
│ database/repositories.py:32 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ OptionChain │ │ TradeRecord │ │ GreeksHistory │ │
│ │ Repository │ │ Repository │ │ Repository │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ DatabaseManager │
│ database/manager.py:27 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 支持多数据库类型 │ │
│ │ │ │
│ │ - SQLite (默认，推荐单用户) │ │
│ │ - PostgreSQL (生产环境多用户) │ │
│ │ - MySQL (PostgreSQL 替代方案) │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 连接管理 │ │
│ │ │ │
│ │ - 异步SQLAlchemy 引擎 │ │
│ │ - 会话工厂 (sessionmaker) │ │
│ │ - 连接池管理 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ SQLAlchemy ORM 模型 │
│ database/models.py │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ OptionChainSnapshot │ │
│ │ │ │
│ │ - id: BigInteger (PK) │ │
│ │ - symbol: String(20) │ │
│ │ - underlying_price: Float │ │
│ │ - timestamp: DateTime │ │
│ │ - chain_data: JSON │ │
│ │ - created_at: DateTime │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ TradeRecord │ │
│ │ │ │
│ │ - id: BigInteger (PK) │ │
│ │ - account: String(20) │ │
│ │ - symbol: String(20) │ │
│ │ - action: String(10) │ │
│ │ - quantity: Integer │ │
│ │ - price: Float │ │
│ │ - timestamp: DateTime │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 异步会话管理 │
│ database/manager.py:123 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ @asynccontextmanager │ │
│ │ get_session() │ │
│ │ │ │
│ │ 1. 获取 AsyncSession │ │
│ │ 2. 事务管理 (BEGIN/COMMIT/ROLLBACK) │ │
│ │ 3. 异常处理 │ │
│ │ 4. 自动清理 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ BaseRepository CRUD │
│ database/repositories.py:32 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ get_by_id │ │ create │ │ update │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ ┌──────┴──────────┐ ┌──┴────────────┐ ┌──┴────────────┐ │
│ │ get_all │ │ delete │ │ count │ │
│ └─────────────────┘ └────────────────┘ └────────────────┘ │
│ │
└────────────────────────┬─────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 数据序列化处理 │
│ database/repositories.py:156 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ JSON 编码 │ │ 压缩存储 │ │ 索引优化 │ │
│ │ │ │ │ │ │ │
│ │ - Pandas │ │ - Snappy │ │ - 时间索引 │ │
│ │ DataFrame│ │ - Gzip │ │ - 标的索引 │ │
│ │ - to_dict │ │ - 减小体积 │ │ - 查询优化 │ │
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
│ │ │ │ │
│ └────────┬───────┴────────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 数据转换 │ │
│ │ │ │
│ │ Python 对象 ──► SQLAlchemy 模型 │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 持久化 ──► 数据库 │ │
│ └─────────────────┬───────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 并发与事务控制 │
│ database/manager.py:178 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ ACID 事务保证 │ │
│ │ │ │
│ │ - Atomicity: 全部成功或全部失败 │ │
│ │ - Consistency: 数据完整性约束 │ │
│ │ - Isolation: 隔离级别控制 │ │
│ │ - Durability: 持久化保证 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 异步 I/O 优化 │ │
│ │ │ │
│ │ - async/await 支持 │ │
│ │ - 连接池复用 │ │
│ │ - 非阻塞查询 │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
└────────────────────┼─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 完成并返回结果 │
└──────────────────────────────────────────────────────────────────┘
```
## 配置与部署
详细的配置说明和部署指南请参阅：
- **[部署指南](./deployment-guide.md)** - 完整的环境配置、安装方式、传输模式配置
- **[风险管理文档](./risk-management.md)** - 风险配置说明
## 扩展点
1. **新策略** - 在 `strategies/` 中继承 `BaseOptionStrategy`
2. **新风险规则** - 在 `core/rules.py` 的 `RiskEvaluator` 中添加方法
3. **新 Playbook 操作** - 在 `core/playbooks.py` 的 `PlaybookEngine` 中添加处理器
4. **新服务** - 继承 `services/base.py` 中的 `IBService` 基类
5. **新 MCP 工具** - 在 `server.py` 中使用 `@mcp.tool()` 装饰器注册
6. **新数据模型** - 在 `database/models.py` 中添加 SQLAlchemy 模型
7. **新仓库** - 在 `database/repositories.py` 中继承 `BaseRepository`
8. **新市场数据源** - 在 `core/option_data.py` 中实现数据获取器
## 依赖项
| 依赖 | 用途 |
|------|------|
| **ib_async** | IBKR 异步 API 客户端 |
| **mcp** | Model Context Protocol SDK |
| **FastMCP** | 高级 MCP 服务器框架 |
| **pandas** | 数据处理 |
| **loguru** | 日志记录 |
| **pyyaml** | 配置解析 |
| **SQLAlchemy** | ORM 数据库框架 |
| **asyncpg / aiosqlite** | 异步数据库驱动 |
| **zoneinfo** | 时区处理 |
| **uvicorn** | HTTP 服务器 (HTTP 传输模式) |
| **python-dotenv** | 环境变量加载 |
| **dataclasses** | 数据类 (Python 3.7+ 内置) |
| **asyncio** | 异步 I/O (Python 3.7+ 内置) |
