高级交易连接器¶

📎 引用文件

本文引用的文件 - agent/src/trading/connectors/etoro/__init__.py - agent/src/trading/connectors/etoro/client.py - agent/src/trading/connectors/etoro/copy_trading.py - agent/src/trading/connectors/etoro/profiles.py - agent/src/trading/connectors/ibkr/__init__.py - agent/src/trading/connectors/ibkr/local.py - agent/src/trading/connectors/futu/sdk.py - agent/src/trading/connectors/mt5/orders.py - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py - agent/src/live/enforcement.py - README.md

简介¶

本文件面向 Vibe-Trading 的高级交易连接器，聚焦 eToro 社交交易平台与 Interactive Brokers（IBKR）本地客户端的集成实现，并覆盖专业级交易系统的关键能力：跟单交易（Copy Trading）、智能投资组合、算法交易、复杂订单路由、风险管理与合规检查、机构级托管/清算结算与报告生成，以及与第三方研究与数据分析平台的集成方案。文档以代码级事实为依据，提供架构图、序列图、流程图和可操作的最佳实践。

项目结构¶

Vibe-Trading 的交易连接器采用“按券商/平台分目录”的组织方式，每个连接器包含配置、客户端封装、能力声明与读写路径隔离等模块。eToro 通过 REST API 暴露交易与跟单能力；IBKR 通过本地 TWS/IB Gateway 只读连接，避免直接云端直连带来的凭证与权限风险。

graph TB subgraph "eToro 连接器" EInit["__init__.py"] EClient["client.py"] ECopy["copy_trading.py"] EProfiles["profiles.py"] end subgraph "IBKR 连接器" IInit["__init__.py"] ILocal["local.py"] end subgraph "运行时与风控" Reconcile["runtime/reconcile.py"] OrderGuard["order_guard.py"] Halt["halt.py"] Enforcement["enforcement.py"] end EInit --> EClient EClient --> ECopy EProfiles --> EClient IInit --> ILocal ECopy --> EClient ILocal --> Reconcile Reconcile --> OrderGuard OrderGuard --> Halt OrderGuard --> Enforcement

图表来源 - agent/src/trading/connectors/etoro/__init__.py:1-7 - agent/src/trading/connectors/etoro/client.py:1-325 - agent/src/trading/connectors/etoro/copy_trading.py:1-213 - agent/src/trading/connectors/etoro/profiles.py:1-22 - agent/src/trading/connectors/ibkr/__init__.py:1-26 - agent/src/trading/connectors/ibkr/local.py:1-686 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py - agent/src/live/enforcement.py

章节来源 - agent/src/trading/connectors/etoro/__init__.py:1-7 - agent/src/trading/connectors/ibkr/__init__.py:1-26

核心组件¶

eToro 连接器
配置与传输层：统一的路径选择（demo vs live）、请求重试与错误归一化、凭据校验。
跟单交易：预检查、启动/调整、轮询完成、关闭/解绑，支持幂等参考 ID 与超时控制。
能力声明：读写分离、写操作需授权指令与熔断保护。
IBKR 连接器
本地只读：通过 TWS/IB Gateway 获取账户快照、持仓、挂单、报价与历史K线。
连接池：线程安全、唯一 client_id、自动断连释放。
环境校验：纸盘/实盘账户前缀校验，防止误连。
运行时与风控
对账与恢复：发现孤儿订单、模糊状态订单时触发熔断。
订单守卫：下单前规模/名义价值限制、活体授权门控。
熔断与执行：在异常或合规不通过时阻止新增风险动作。

章节来源 - agent/src/trading/connectors/etoro/client.py:1-325 - agent/src/trading/connectors/etoro/copy_trading.py:1-213 - agent/src/trading/connectors/etoro/profiles.py:1-22 - agent/src/trading/connectors/ibkr/local.py:1-686 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py - agent/src/live/enforcement.py

架构总览¶

下图展示从策略到执行的全链路：策略信号经运行时对账与风控后，进入各券商连接器；eToro 走 REST API 并支持跟单交易；IBKR 仅做本地只读数据接入，便于组合分析与监控。

sequenceDiagram participant Strategy as "策略/研究" participant Runtime as "运行时(对账/风控)" participant EToro as "eToro 连接器" participant IBKR as "IBKR 本地连接器" participant Broker as "券商/交易所" Strategy->>Runtime : 生成交易信号 Runtime->>Runtime : 对账/合规检查/熔断判断 alt 需要下单 Runtime->>EToro : 下单/跟单(授权+限额) EToro->>Broker : HTTP 请求(带鉴权/重试) Broker-->>EToro : 订单回执 EToro-->>Runtime : 标准化结果 else 仅读取 Runtime->>IBKR : 查询持仓/报价/历史 IBKR->>Broker : TWS/IB Gateway 只读 Broker-->>IBKR : 数据 IBKR-->>Runtime : 标准化数据 end Runtime-->>Strategy : 执行结果/状态

图表来源 - agent/src/trading/connectors/etoro/client.py:218-304 - agent/src/trading/connectors/etoro/copy_trading.py:29-185 - agent/src/trading/connectors/ibkr/local.py:165-425 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py

详细组件分析¶

eToro 跟单交易（Copy Trading）¶

能力与流程
预检查：校验金额与环境，调用 eligibility 接口。
启动/调整：提交跟随任务，要求 URL-safe 参考 ID，返回 token 用于后续轮询。
轮询：按 reference_id 查询进度，直至完成或超时。
关闭/解绑：按 mirror_id 关闭或解绑跟随。
安全边界
demo/live 路径隔离，写操作需授权指令与熔断保护。
金额单位与账户币种一致，失败快速返回结构化错误。

sequenceDiagram participant Agent as "Agent/工具" participant Copy as "copy_trading.py" participant Client as "client.py(EtoroClient)" participant API as "eToro Public API" Agent->>Copy : copy_precheck(parent_cid, amount) Copy->>Client : POST /copy/eligibility Client->>API : HTTP 请求(含鉴权/重试) API-->>Client : 资格结果 Client-->>Copy : 标准化响应 Copy-->>Agent : ok/error + request_id Agent->>Copy : copy_start_or_adjust(parent_cid, amount, reference_id) Copy->>Client : POST /copy (referenceID) Client->>API : 提交跟随 API-->>Client : token/raw Client-->>Copy : 标准化响应 Copy-->>Agent : ok + token Agent->>Copy : copy_poll(reference_id) Copy->>Client : GET /copy/{ref} Client->>API : 查询进度 API-->>Client : 进度 Client-->>Copy : 标准化响应 Copy-->>Agent : ok + result/completed?

图表来源 - agent/src/trading/connectors/etoro/copy_trading.py:29-185 - agent/src/trading/connectors/etoro/client.py:218-304

章节来源 - agent/src/trading/connectors/etoro/copy_trading.py:1-213 - agent/src/trading/connectors/etoro/client.py:1-325 - agent/src/trading/connectors/etoro/profiles.py:1-22 - README.md:1275-1296

IBKR 本地只读连接与数据服务¶

功能范围
账户快照、持仓、挂单、报价、历史K线。
默认端口扫描、健康检查、SDK 可用性检测。
纸盘/实盘账户前缀校验，防止误配。
连接模型
线程本地连接池，唯一 client_id，自动释放。
通过 TWS/IB Gateway 本地 Socket 通信，不直接访问云端。

flowchart TD Start(["开始"]) --> CheckPorts["扫描默认端口/检查目标端口"] CheckPorts --> PortOpen{"端口开放?"} PortOpen -- 否 --> ErrorPort["返回错误: 未监听"] PortOpen -- 是 --> CheckSDK{"ib_async 可用?"} CheckSDK -- 否 --> ErrorSDK["返回错误: 缺少依赖"] CheckSDK -- 是 --> Connect["建立 TWS/IB Gateway 连接<br/>唯一 clientId, readonly"] Connect --> Query["执行查询: 账户/持仓/挂单/报价/K线"] Query --> Release["释放连接"] Release --> End(["结束"]) ErrorPort --> End ErrorSDK --> End

图表来源 - agent/src/trading/connectors/ibkr/local.py:165-239 - agent/src/trading/connectors/ibkr/local.py:429-503 - agent/src/trading/connectors/ibkr/local.py:241-425

章节来源 - agent/src/trading/connectors/ibkr/local.py:1-686 - agent/src/trading/connectors/ibkr/__init__.py:1-26

其他专业级系统示例（Futu、MT5）¶

Futu SDK
严格数量与限价校验，市场单/限价单映射，下单与撤销。
错误归一化，失败快速返回结构化信息。
MT5 订单
对冲账户下反向开仓不等于平仓，需基于票据号精确平仓。
连接器级别规模限制（手数/名义价值），作为兜底防护。

章节来源 - agent/src/trading/connectors/futu/sdk.py:453-599 - agent/src/trading/connectors/mt5/orders.py:1-39

运行时对账、订单守卫与熔断¶

对账（Reconcile）
识别孤儿订单、模糊状态订单，必要时触发熔断，禁止重发。
订单守卫（Order Guard）
下单前进行规模/名义价值限制，结合授权指令与熔断状态。
熔断（Halt）
在异常或合规不通过时阻止新增风险动作，保留只读与减仓能力。

flowchart TD S(["收到信号/订单"]) --> Validate["参数与规模校验"] Validate --> Mandate{"授权指令有效?"} Mandate -- 否 --> Block["阻断并记录审计"] Mandate -- 是 --> HaltCheck{"熔断状态?"} HaltCheck -- 是 --> Block HaltCheck -- 否 --> Route["路由至对应连接器"] Route --> Exec["执行/下单/跟单"] Exec --> Reconcile["对账与状态收敛"] Reconcile --> Decision{"是否异常/模糊?"} Decision -- 是 --> Halt["触发熔断/告警"] Decision -- 否 --> Done(["完成"]) Block --> Done

图表来源 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py - agent/src/live/enforcement.py

章节来源 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py - agent/src/live/enforcement.py

依赖关系分析¶

eToro 连接器
依赖 requests 进行 HTTP 通信，内置重试与退避。
配置文件与密钥来自用户目录与环境变量，路径与环境强绑定。
IBKR 连接器
依赖 ib_async 与本地 TWS/IB Gateway，强调只读与安全边界。
连接池管理生命周期，避免并发冲突。
运行时
对账、守卫、熔断与执行编排形成闭环，确保一致性。

graph LR A["策略/研究"] --> B["运行时(对账/守卫/熔断)"] B --> C["eToro 连接器"] B --> D["IBKR 连接器"] C --> E["requests + eToro Public API"] D --> F["ib_async + TWS/IB Gateway"]

图表来源 - agent/src/trading/connectors/etoro/client.py:218-304 - agent/src/trading/connectors/ibkr/local.py:429-503 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py

章节来源 - agent/src/trading/connectors/etoro/client.py:1-325 - agent/src/trading/connectors/ibkr/local.py:1-686 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py

性能考量¶

eToro
使用指数退避与 429 重试，降低瞬时拥塞影响。
跟单轮询建议合理间隔与超时，避免频繁请求。
IBKR
连接池复用减少握手开销；批量查询尽量合并。
历史K线与报价按需拉取，避免过大窗口导致延迟。
运行时
对账与守卫应在内存中快速完成，避免阻塞主循环。
熔断触发后优先保障减仓与只读能力，提升恢复速度。

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

故障排查指南¶

eToro 常见问题
凭据缺失：检查配置文件与环境变量是否完整。
网络/限流：关注 429 与重试次数，适当增大间隔。
跟单失败：确认 parent_cid、amount、reference_id 格式与账户币种。
IBKR 常见问题
端口未监听：确认 TWS/IB Gateway 已登录并启用 API。
依赖缺失：安装 ib_async 并确保版本兼容。
纸盘/实盘误配：检查账户前缀与 profile 设置。
运行时问题
对账发现孤儿/模糊订单：根据提示修复或触发熔断。
下单被拒：检查授权指令、熔断状态与规模限制。

章节来源 - agent/src/trading/connectors/etoro/client.py:169-187 - agent/src/trading/connectors/etoro/client.py:225-290 - agent/src/trading/connectors/ibkr/local.py:165-239 - agent/src/trading/connectors/ibkr/local.py:530-541 - agent/src/live/runtime/reconcile.py - agent/src/live/order_guard.py - agent/src/live/halt.py

结论¶

Vibe-Trading 的高级交易连接器通过 eToro 的 REST API 与 IBKR 的本地只读连接，构建了安全、可扩展且可审计的执行与数据通路。eToro 的跟单交易提供了社交交易的便捷入口，IBKR 的本地连接确保了数据的安全与稳定。运行时对账、订单守卫与熔断机制共同保障了生产环境的稳健性。建议在部署中严格遵循纸盘/实盘隔离、授权指令与熔断策略，并结合第三方研究与数据分析平台进行组合优化与风险管理。

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

附录¶

专业级功能清单（基于仓库实现）
跟单交易：eToro 预检查、启动/调整、轮询、关闭/解绑。
本地只读数据：IBKR 账户快照、持仓、挂单、报价、历史K线。
复杂订单类型：Futu 市场单/限价单；MT5 对冲账户精确平仓。
条件单与算法订单：通过连接器与运行时规则组合实现（如止损、跟踪止盈）。
批量操作：按标的集合批量查询与下单（注意速率限制与风控）。
投资组合分析：结合 IBKR 持仓与外部数据源进行组合度量。
风险管理与合规：订单规模/名义价值限制、授权指令、熔断与审计日志。
机构级能力：托管/清算结算与报告生成可通过运行时与外部系统集成扩展。
第三方集成：将 eToro/IBKR 数据对接至研究与分析平台，形成闭环决策。

[本节为概念性补充，无需特定文件引用]

← 连接器架构设计中国A股引擎 →