🔍
项目文档/架构设计/集成模式/交易连接器集成/交易连接器集成

交易连接器集成

📎 引用文件

本文引用的文件 - service.py - types.py - binance/sdk.py - futu/sdk.py - longbridge/sdk.py - tiger/sdk.py - sdk_order_gate.py - enforcement.py

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件为 Vibe-Trading 交易连接器集成的架构文档，聚焦于抽象层设计、统一订单接口与券商适配机制。内容覆盖已实现的 Binance、富途（Futu）、长桥（Longbridge）、老虎（Tiger）等连接器的认证方式与 API 封装；解释订单生命周期管理、风险控制（事前授权与限额校验、熔断、审计）与异常处理策略；并提供自定义连接器开发指南（SDK 集成、协议适配与安全要点），以及实盘部署模式与监控方案建议。

项目结构

交易连接器位于 agent/src/trading 下，采用“服务层 + 连接器模块”的分层组织： - 服务层（service.py）：提供统一的读/写接口（账户、持仓、订单、报价、历史行情、下单、撤单等），按 profile 的 transport 路由到本地 TWS、远程 MCP 或直接 SDK。 - 类型定义（types.py）：统一描述 TradingProfile（id、connector、label、environment、transport、capabilities、readonly、config、notes）。 - 连接器实现（connectors/*）：每个券商一个子包，包含 classification/profiles/sdk 等，暴露统一的 read/write 函数签名。 - 实盘风控（src/live）：事前授权门控（mandate gate）、熔断（halt）、审计（audit）、日计数（daily count）与指令归一化。

graph TB subgraph "交易服务层" SVC["service.py<br/>统一接口"] TYP["types.py<br/>TradingProfile"] end subgraph "连接器实现" BIN["Binance SDK"] FUTU["Futu SDK"] LB["Longbridge SDK"] TIGER["Tiger SDK"] end subgraph "实盘风控" GATE["sdk_order_gate.py<br/>事前授权门控"] ENF["enforcement.py<br/>授权校验/限额"] end SVC --> BIN SVC --> FUTU SVC --> LB SVC --> TIGER SVC --> GATE GATE --> ENF

图表来源 - service.py:17-29 - types.py:20-51 - sdk_order_gate.py:59-157 - enforcement.py:455-617

章节来源 - service.py:1-120 - types.py:1-52

核心组件

章节来源 - service.py:42-147 - service.py:279-342 - sdk_order_gate.py:59-157

架构总览

下图展示从上层工具/CLI/MCP 到券商 SDK 的完整调用链，包括纸盘直连与实盘事前授权门控。

sequenceDiagram participant Caller as "调用方" participant Svc as "service.py" participant Mod as "券商SDK模块" participant Gate as "sdk_order_gate.py" participant Enf as "enforcement.py" participant Broker as "券商API" Caller->>Svc : place_order(...) Svc->>Svc : 解析profile/transport alt paper 或 remote_mcp Svc->>Mod : place_order(config, ...) Mod-->>Svc : 结果 else live 且 broker_sdk Svc->>Gate : execute_live_order(...) Gate->>Enf : check_mandate(intent, positions, balance) alt 允许 Gate->>Mod : place_order(config, ...) Mod-->>Gate : 结果 Gate-->>Svc : 结果+审计 else 拒绝/暂停 Gate-->>Svc : 拒绝/重授权 end end Svc-->>Caller : 返回结果

图表来源 - service.py:279-342 - sdk_order_gate.py:59-157 - enforcement.py:455-617

详细组件分析

抽象层与服务路由（service.py）

flowchart TD Start(["进入 service.place_order"]) --> CheckTransport{"transport == 'broker_sdk'?"} CheckTransport --> |否| ReturnUnsupported["返回不支持"] CheckTransport --> |是| ReadOnly{"readonly?"} ReadOnly --> |是| ReturnUnsupported ReadOnly --> |否| BuildCfg["构建配置"] BuildCfg --> Env{"environment == 'paper'?"} Env --> |是| CallSDK["调用 connector.place_order"] Env --> |否| Intent["构造 OrderIntent"] Intent --> Gate["execute_live_order(..., intent, place_kwargs)"] Gate --> Result["返回结果(含审计)"] CallSDK --> Result

图表来源 - service.py:279-342

章节来源 - service.py:17-29 - service.py:42-147 - service.py:279-342

统一数据模型（types.py）

章节来源 - types.py:1-52

券商适配器：Binance（现货）

classDiagram class BinanceConfig { +string api_key +string api_secret +string profile +string testnet_host +float timeout +bool readonly +build_config() +check_status() +get_account_snapshot() +get_positions() +get_open_orders() +get_quote() +get_historical_bars() +place_order() +cancel_order() }

图表来源 - binance/sdk.py:82-152 - binance/sdk.py:217-405 - binance/sdk.py:423-600

章节来源 - binance/sdk.py:59-152 - binance/sdk.py:217-405 - binance/sdk.py:423-600

券商适配器：富途（Futu）

sequenceDiagram participant C as "调用方" participant F as "Futu SDK" participant O as "OpenD 网关" C->>F : place_order(symbol, side, quantity, ...) F->>F : 参数校验/TIF映射 F->>O : 打开交易上下文 alt live F->>O : unlock_trade(password_md5) end F->>O : place_order(...) O-->>F : 返回订单ID F-->>C : 标准化结果

图表来源 - futu/sdk.py:407-539 - futu/sdk.py:617-643

章节来源 - futu/sdk.py:223-393 - futu/sdk.py:407-539 - futu/sdk.py:617-643

券商适配器：长桥（Longbridge）

章节来源 - longbridge/sdk.py:58-171 - longbridge/sdk.py:220-428 - longbridge/sdk.py:449-619

券商适配器：老虎（Tiger）

章节来源 - tiger/sdk.py:61-147 - tiger/sdk.py:186-319 - tiger/sdk.py:333-489

实盘事前授权门控与风控（sdk_order_gate.py + enforcement.py）

flowchart TD A["开始: execute_live_order"] --> B["加载Mandate并校验版本/过期"] B --> C{"熔断标志?"} C --> |是| Deny["拒绝: 交易暂停"] C --> |否| D["归一化名义价值(quantity→USD)"] D --> E["读取持仓与余额"] E --> F["check_mandate 限额校验"] F --> |通过| G["调用券商SDK下单"] F --> |违规| H["拒绝/暂停(含breach详情)"] G --> I["审计记录+日计数"] I --> J["返回结果"]

图表来源 - sdk_order_gate.py:59-157 - sdk_order_gate.py:317-438 - enforcement.py:455-617

章节来源 - sdk_order_gate.py:59-157 - sdk_order_gate.py:317-438 - enforcement.py:111-177 - enforcement.py:455-617

依赖关系分析

graph LR SVC["service.py"] --> M1["binance/sdk.py"] SVC --> M2["futu/sdk.py"] SVC --> M3["longbridge/sdk.py"] SVC --> M4["tiger/sdk.py"] SVC --> G["sdk_order_gate.py"] G --> E["enforcement.py"]

图表来源 - service.py:17-29 - sdk_order_gate.py:59-157 - enforcement.py:455-617

章节来源 - service.py:17-29 - sdk_order_gate.py:59-157

性能考虑

[本节为通用指导，无需特定文件引用]

故障排查指南

章节来源 - binance/sdk.py:217-264 - futu/sdk.py:223-272 - longbridge/sdk.py:220-301 - tiger/sdk.py:186-230 - sdk_order_gate.py:59-157

结论

Vibe-Trading 的交易连接器体系通过统一的服务层与标准化的连接器 SDK 接口，实现了多券商接入的一致性与可扩展性。结合事前授权门控与严格的 fail-closed 策略，系统在保障交易安全的同时提供了灵活的纸盘/实盘切换与丰富的风控能力。对于新增券商，遵循统一接口契约、实现环境隔离与参数校验、接入审计与日计数，即可快速集成并投入生产。

[本节为总结性内容，无需特定文件引用]

附录

自定义交易连接器开发指南

[本节为通用指导，无需特定文件引用]

实盘交易部署模式与监控方案

[本节为通用指导，无需特定文件引用]

← Binance 加密货币交易所集成 其他券商平台集成 →