连接器架构设计¶

📎 引用文件

本文引用的文件 - agent/src/trading/service.py - agent/src/tools/trading_connector_tool.py - agent/src/trading/connectors/longbridge/sdk.py - agent/src/trading/connectors/trading212/sdk.py - agent/src/trading/connectors/binance/sdk.py - agent/tests/test_longbridge_runtime.py - frontend/src/lib/api.ts

简介¶

本文件面向 Vibe-Trading 的“连接器架构”，聚焦于统一抽象层、认证机制、错误处理策略、连接池管理、生命周期与状态同步、故障恢复、配置文件结构与验证规则、动态加载、性能优化、并发控制与资源管理，以及新券商接入的标准流程。文档以代码级事实为依据，结合类图、时序图和流程图，帮助读者从高层到细节全面理解系统如何把多家券商/数据源抽象为一致的“连接器”能力，并通过服务层进行路由与编排。

项目结构¶

Vibe-Trading 将“连接器”按券商或协议拆分为独立模块，每个模块提供统一的只读接口（账户、持仓、订单、行情、历史），并在需要时暴露下单/撤单等写操作。服务层负责根据“交易资料（profile）”选择具体实现；工具层对外暴露稳定的 CLI/MCP/REST 入口；前端通过 API 类型定义消费连接器状态。

graph TB subgraph "工具与入口" T["trading_connector_tool.py CLI/MCP/Agent 工具"] end subgraph "服务层" S["service.py 路由与分发"] end subgraph "连接器实现" L["longbridge/sdk.py"] T212["trading212/sdk.py"] B["binance/sdk.py"] end subgraph "前端" F["frontend/src/lib/api.ts 连接器状态类型"] end T --> S S --> L S --> T212 S --> B F --> S

图表来源 - agent/src/tools/trading_connector_tool.py:1-800 - agent/src/trading/service.py:1-200 - agent/src/trading/connectors/longbridge/sdk.py:1-800 - agent/src/trading/connectors/trading212/sdk.py:1-587 - agent/src/trading/connectors/binance/sdk.py:475-503 - frontend/src/lib/api.ts:1125-1184

章节来源 - agent/src/tools/trading_connector_tool.py:1-800 - agent/src/trading/service.py:1-200

核心组件¶

统一接口契约：所有 broker_sdk 连接器需暴露 build_config、check_status、get_account_snapshot、get_positions、get_open_orders、get_quote、get_historical_bars 等函数，以便服务层无差别调用。
配置对象：每个连接器使用不可变 dataclass 描述连接参数，并提供 from_mapping/with_overrides 等方法做校验与覆盖。
健康检查：check_status 返回标准化诊断信息，包含配置完整性、SDK 可用性、环境标识、最近检查时间等。
安全边界：对 live/paper 的区分采用“结构性守卫”（如 host 隔离、profile 标签、API 能力限制），在连接器内部拒绝不安全路径。
工具与服务：工具层只做参数校验与结果包装；服务层负责 profile 解析、连接器选择与结果归一化。

章节来源 - agent/src/trading/service.py:1-200 - agent/src/trading/connectors/longbridge/sdk.py:58-171 - agent/src/trading/connectors/trading212/sdk.py:46-131

架构总览¶

下图展示从工具到服务再到具体连接器的调用链，以及前端对连接器状态的消费。

sequenceDiagram participant U as "用户/Agent" participant Tool as "trading_connector_tool.py" participant Svc as "service.py" participant Mod as "broker_sdk 模块" participant Conn as "具体连接器 SDK" U->>Tool : 调用 trading_check / trading_account / trading_history ... Tool->>Svc : check_connection / get_account / get_history(...) Svc->>Svc : 解析 profile_id, transport alt local_tws Svc->>Conn : IBKR 本地客户端 else broker_sdk Svc->>Mod : import 对应 sdk 模块 Mod->>Mod : build_config(profile.config, overrides) Svc->>Mod : check_status/get_account/get_history(...) Mod->>Conn : 调用 SDK 方法 Conn-->>Mod : 原始响应 Mod-->>Svc : 标准化结果 end Svc-->>Tool : 带 profile 元信息的统一结果 Tool-->>U : JSON 结果

图表来源 - agent/src/tools/trading_connector_tool.py:262-428 - agent/src/trading/service.py:42-200 - agent/src/trading/connectors/longbridge/sdk.py:220-269 - agent/src/trading/connectors/trading212/sdk.py:162-195

详细组件分析¶

Longbridge 连接器¶

配置模型：不可变 dataclass，支持 from_mapping 校验 profile/region，with_overrides 仅允许安全覆盖。
凭证解析：集中式 resolve_longbridge_credentials，记录 _credential_source/_credential_error，避免敏感字段泄露。
健康检查：check_status 输出结构化报告，包括 configured、sdk_installed、paper_guard、last_checked_at 等。
只读优先：默认 readonly=True；下单路径仅在 paper 环境且满足严格输入校验后执行。
周期映射：内置 period→SDK Period 枚举映射，保证跨周期一致性。

classDiagram class LongbridgeConfig { +string app_key +string app_secret +string access_token +string profile +string region +float timeout +bool readonly +from_mapping(data) +with_overrides(...) +environment } class Module { +build_config(profile_config, overrides) +check_status(config) +get_account_snapshot(config) +get_positions(config) +get_open_orders(config, include_executions) +get_quote(symbol, config) +get_historical_bars(symbol, period, limit, config) +place_order(config, ...) +cancel_order(config, order_id, symbol) } LongbridgeConfig <.. Module : "被构建/使用"

图表来源 - agent/src/trading/connectors/longbridge/sdk.py:58-171 - agent/src/trading/connectors/longbridge/sdk.py:220-428 - agent/src/trading/connectors/longbridge/sdk.py:449-619

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

Trading 212 连接器¶

配置模型：不可变 dataclass，校验 base_url 必须以 http(s) 开头，profile 限定为 paper/live-readonly/live。
健康检查：check_status 先校验缺失字段，再尝试读取账户快照，失败时返回结构化 error。
市场数据能力声明：quote/history 明确返回“不支持”的错误负载，避免伪造数据。
下单/撤单：在未具备结构性 paper/live 边界前，一律拒绝。

flowchart TD Start(["进入 place_order"]) --> CheckEnv{"environment == 'paper'?"} CheckEnv -- 否 --> RefuseLive["返回错误: 非纸面环境不允许下单"] CheckEnv -- 是 --> RefuseAll["返回错误: 连接器只读/未开放下单"] RefuseLive --> End(["结束"]) RefuseAll --> End

图表来源 - agent/src/trading/connectors/trading212/sdk.py:350-390

章节来源 - agent/src/trading/connectors/trading212/sdk.py:46-131 - agent/src/trading/connectors/trading212/sdk.py:162-195 - agent/src/trading/connectors/trading212/sdk.py:317-336 - agent/src/trading/connectors/trading212/sdk.py:350-390

Binance 连接器（示例：下单前置校验）¶

数量/名义值互斥校验：quantity 与 notional 必须二选一且为正数。
限价单要求：limit_price 必须为正数。
结构性守卫：在真正调用 SDK 前，通过 _assert_host 断言 host 隔离，防止误连生产。

flowchart TD A["进入下单"] --> B{"quantity/notional 是否恰好一个提供?"} B -- 否 --> E["返回错误: 必须提供其中一个"] B -- 是 --> C{"type == 'limit' ?"} C -- 是 --> D{"limit_price > 0 ?"} D -- 否 --> F["返回错误: 限价单价格无效"] D -- 是 --> G["_assert_host(cfg)"] C -- 否 --> G G -- 失败 --> H["返回错误: host 不匹配/不安全"] G -- 成功 --> I["继续调用 SDK"]

图表来源 - agent/src/trading/connectors/binance/sdk.py:475-503

章节来源 - agent/src/trading/connectors/binance/sdk.py:475-503

依赖关系分析¶

服务层通过“transport”和“connector”两个维度决定调用路径： - local_tws：直接调用 IBKR 本地客户端。 - broker_sdk：通过映射表动态导入对应 sdk 模块，并调用其统一接口。 - remote：走远程 MCP/其他通道（不在本节展开）。

graph LR P["profiles profile_by_id()"] --> S["service.py 路由分发"] S --> |local_tws| IBKR["IBKR 本地客户端"] S --> |broker_sdk| M["动态导入 _SDK_CONNECTOR_MODULES"] M --> L["longbridge.sdk"] M --> T212["trading212.sdk"] M --> B["binance.sdk"]

图表来源 - agent/src/trading/service.py:13-39 - agent/src/trading/service.py:42-65

章节来源 - agent/src/trading/service.py:13-65

性能与并发¶

连接池与超时：部分渠道（如 IM 通道）展示了分离请求池与超时配置的最佳实践，可借鉴到连接器 HTTP/SDK 客户端中，避免长轮询阻塞出站请求。
批量与分页：连接器应尽可能利用 SDK 的分页/批量能力，减少往返次数。
缓存与降级：历史数据拉取建议引入可选本地缓存（如数据缓存开关），命中则跳过网络；对不可用数据源快速失败而非静默降级。
序列化与数值安全：Decimal/浮点转换要谨慎，避免 NaN/Inf 泄漏；JSON 输出保持 strict。

[本节为通用指导，不直接分析具体文件]

故障恢复与错误处理¶

健康检查：check_status 将错误分类为 credentials_missing、credentials_partial、sdk_missing、network_unreachable、authentication_failed、broker_error 等，便于上层统一呈现与重试策略。
错误消息脱敏：公共配置输出中对密钥进行掩码，避免日志泄露。
结构性拒绝：对于不具备结构性 paper/live 边界的券商，连接器在入口处直接拒绝 live 下单，确保 fail-closed。
前端状态消费：前端定义了 ConnectorVerifyResponse/LiveBrokerStatus 等类型，用于渲染连接状态、能力集、只读标记等。

flowchart TD Q["check_status(config)"] --> C{"配置完整?"} C -- 否 --> E1["返回 error_code=credentials_missing/partial"] C -- 是 --> D{"SDK 可用?"} D -- 否 --> E2["返回 error_code=sdk_missing"] D -- 是 --> H["尝试健康调用(如账户快照)"] H -- 失败 --> E3["映射为 network/authentication/broker 错误"] H -- 成功 --> OK["返回 ok + last_checked_at + account 摘要"]

图表来源 - agent/src/trading/connectors/longbridge/sdk.py:220-318 - agent/src/trading/connectors/trading212/sdk.py:162-195 - frontend/src/lib/api.ts:1125-1184

章节来源 - agent/src/trading/connectors/longbridge/sdk.py:220-318 - agent/src/trading/connectors/trading212/sdk.py:162-195 - frontend/src/lib/api.ts:1125-1184

配置与动态加载¶

配置文件：每个连接器维护独立的 JSON 配置文件（如 longbridge.json、trading212.json），位于运行时根目录；保存时设置 owner-only 权限。
配置解析：from_mapping 负责字段校验与规范化（profile、region/base_url、timeout 等），with_overrides 支持 CLI/工具覆盖。
动态加载：服务层通过 _SDK_CONNECTOR_MODULES 映射表，按 connector key 动态 import 对应 sdk 模块，无需硬编码分支。
环境变量与 .env：CLI 启动时会尝试加载 .env 候选路径，使凭据与环境变量可在运行期注入。

章节来源 - agent/src/trading/connectors/longbridge/sdk.py:174-208 - agent/src/trading/connectors/trading212/sdk.py:134-159 - agent/src/trading/service.py:13-39 - agent/cli/main.py:289-327

扩展开发指南¶

新增券商接入标准流程（以 broker_sdk 为例）： 1. 创建模块目录与 sdk.py，定义不可变 Config dataclass，实现 from_mapping/with_overrides/environment。 2. 实现统一接口：build_config、check_status、get_account_snapshot、get_positions、get_open_orders、get_quote、get_historical_bars；如需下单，实现 place_order/cancel_order 并确保结构性安全守卫。 3. 在 service.py 的 _SDK_CONNECTOR_MODULES 中注册 connector key → 模块路径。 4. 编写测试：覆盖配置校验、健康检查、只读能力、错误映射、下单拒绝路径（若适用）。 5. 文档与类型：在前端 api.ts 中补充连接器状态字段（如 capabilities、readonly、connection_state）。

最佳实践 - 始终在入口处进行结构性安全判断（host 隔离、profile 标签、能力白名单）。 - 错误分类清晰，消息脱敏，避免泄露密钥。 - 对不支持的能力明确返回“不支持”，而不是伪造数据。 - 配置变更幂等，保存时设置最小权限。

章节来源 - agent/src/trading/service.py:13-39 - agent/src/trading/connectors/longbridge/sdk.py:58-171 - agent/src/trading/connectors/trading212/sdk.py:46-131 - frontend/src/lib/api.ts:1125-1184

注册、发现与路由¶

注册：服务层维护 _SDK_CONNECTOR_MODULES 映射，新增连接器只需在此登记。
发现：CLI/工具通过 profiles 列表展示可用连接资料；前端通过 /live/status 获取各券商连接状态。
路由：service.py 根据 profile.transport 与 profile.connector 选择 local_tws 或 broker_sdk 路径；后者通过动态 import 调用具体模块。

sequenceDiagram participant UI as "前端/CLI" participant API as "服务层" participant REG as "注册表" participant MOD as "连接器模块" UI->>API : GET /live/status?broker=... API->>REG : 查找 connector key REG-->>API : 模块路径 API->>MOD : check_status(build_config(...)) MOD-->>API : 标准化状态 API-->>UI : brokers[].auth/connection_state/capabilities

图表来源 - agent/src/trading/service.py:42-65 - agent/tests/test_longbridge_runtime.py:104-136 - agent/tests/test_longbridge_runtime.py:230-247 - agent/tests/test_longbridge_runtime.py:389-427

章节来源 - agent/src/trading/service.py:42-65 - agent/tests/test_longbridge_runtime.py:104-136 - agent/tests/test_longbridge_runtime.py:230-247 - agent/tests/test_longbridge_runtime.py:389-427

结论¶

Vibe-Trading 的连接器架构通过“统一接口 + 服务层路由 + 模块化实现”的方式，实现了多券商/协议的解耦接入与一致体验。其关键优势在于： - 强约束的配置与校验，降低误配风险。 - 标准化的健康检查与错误分类，提升可观测性与可运维性。 - 结构性安全守卫（host/profile/能力）保障 live 环境安全。 - 动态加载与注册表机制，使扩展成本低、耦合小。 - 工具/服务/连接器分层清晰，便于测试与维护。

遵循本文档的流程与最佳实践，可以快速、安全地接入新的券商或协议，并保持与现有生态的一致性。

← 订单管理系统高级交易连接器 →