第 3 章 · 03 券商连接器与安全分级

第 3 章 · 03 券商连接器与安全分级

本节摘要:这是本章的安全核心。本节先再次强调 loader 与 connector 的根本区别(loader 读行情,connector 连账户),然后讲清券商连接器(connector)的典型能力——读账户、持仓、委托、报价、历史 K 线,以及在允许 profile 下下单撤单。重点是三种 profile 的安全分级:read-only(只读,第一次连真实账户首选)、paper(模拟盘,验证策略与订单流程)、live(真实账户,必须经授权边界 mandate、kill switch、fail-closed、审计,只在你完全理解风险且先经 read-only 与 paper 验证后使用)。读完本节,你会理解实盘的安全防线,并知道为什么学习阶段应只用 read-only 和 paper。

内容来源:原项目中文入门教程(第 7 章「券商连接器」)改写,补充安全分级细节。

学习目标

阅读完本节,你应当能够:

1. 复述 loader 与 connector 的区别(读行情 vs 连账户),不再混淆。
2. 列举 connector 的典型能力(读账户/持仓/委托/报价/历史 K 线/下单/撤单)。
3. 复述三种 profile(read-only / paper / live)的含义、能力边界与适用阶段。
4. 理解实盘的安全防线:授权边界(mandate)、kill switch、fail-closed、审计记录。
5. 解释为什么学习阶段应只用 read-only 和 paper,以及何时才可以考虑 live。
6. 用 CLI 命令(connector list / connector use / connector check)管理连接器。

一、loader vs connector:再次强调

这是新手最常混淆的点,本章已经讲过两次,这里最后一次强调,因为它直接关系资金安全:

💡 loader 与 connector 的根本区别:

• loader 读市场行情(数据层,研究侧,默认,纯只读,安全)。
• connector 读或操作你的券商账户(账户层,可选,涉及资金,必须谨慎)。

两者职责完全不重叠。你用 loader 拉 K 线做回测,和你的券商账户没任何关系;只有当你显式调用 connector(经 vibe-trading connector 命令)时,才涉及账户操作。

loader(数据层)              connector(账户层)
   读行情                       读账户/下单
   纯只读                       可读可写(按 profile)
   安全,随便用                 涉及资金,谨慎
   agent/backtest/loaders/      agent/src/trading/
​

⚠️ 如果你只是做回测、因子分析、报告生成,根本不需要碰 connector。下面的内容主要给「需要连账户」的用户看。

二、connector 的典型能力

connector 把不同券商的接口统一成一套标准能力。典型能力包括:

• 读取账户:查余额、可用资金、冻结资金。
• 读取持仓:查当前持仓列表、数量、成本。
• 读取委托:查今日委托、历史委托。
• 读取报价:查实时报价(经账户通道,有时比公开源更准或更实时)。
• 读取历史 K 线:经账户通道拉历史行情(部分券商提供更高质量的数据)。
• 下单 / 撤单:在允许的 profile 下,提交或撤销订单。

注意「在允许的 profile 下」——不是所有 connector 都能下单,也不是所有 profile 都允许写操作。这由 profile 的安全属性决定。

三、connector 管理命令

Vibe-Trading 提供了几条管理 connector 的 CLI 命令:

# 列出可用的连接器
vibe-trading connector list

# 选择/启用某个连接器
vibe-trading connector use

# 检查连接器状态与配置
vibe-trading connector check
​

看 connector 时,不要先问「能不能自动交易」,先看 profile 的安全属性。一个 connector 支持哪些 profile、当前用的是哪个 profile,比它的「下单能力」更重要。

💡 看 connector 的正确顺序:先确认 profile(read-only/paper/live),再看能力,最后才考虑要不要用写操作。绝大多数学习场景,read-only 就够了。

四、三种 profile:read-only / paper / live

这是本节的核心。connector 的每个连接都关联一个 profile,profile 决定了它的能力边界与安全级别:

read-only:第一次连真账户的首选

read-only profile 只读不改,不会提交任何订单。它的价值是让你安全地确认账户连接正常——能读到余额、持仓、委托,说明你的凭证、网络、权限都对。这一步通过后,才考虑往上走。

💡 为什么从 read-only 开始:即使你最终目标是模拟下单,也先用 read-only 确认连接没问题。直接上 paper 或 live,如果凭证错了,排查起来更麻烦。

paper:验证订单流程

paper profile 连接模拟盘或券商提供的沙盒账户。即使你下单,也不动用真实资金——券商会在沙盒里模拟成交回报。它的价值是验证整个订单流程:订单字段对不对、成交回报格式正不正常、撤单能不能成功。

paper 适合在「你的策略已经过历史回测验证、现在想测试它在实时数据流里的下单表现」时使用。这是从「历史研究」过渡到「实盘」之间的安全中间态。

live:真实账户,必须谨慎

live profile 连接真实账户,任何写操作(下单、撤单)都会影响真实资金。因此它受到多重安全防线保护(见下一节)。

⚠️ live 的使用前提:只在你(1)完全理解风险,(2)已经过 read-only 确认连接正常,(3)已经过 paper 验证订单流程,(4)能解释每一笔订单为什么产生——这四条都满足后,才考虑 live。本教程不鼓励初学者使用 live。

五、实盘的安全防线

live profile 不是「开了就能随便下单」,它背后有多重安全防线:

授权边界(mandate)

mandate 是实盘的「风控门」,它规定了:

• 能交易哪些标的:白名单(只允许某些股票/加密)。
• 单笔多少:单笔订单金额/数量上限。
• 最大仓位:单只标的或总仓位的上限。
• 每日亏损限制:当日亏损达到阈值就停止交易。

任何 live 订单都必须先通过 mandate 检查,超出边界的订单会被拒绝。

kill switch(紧急停止)

kill switch 是「一键急停」——任何时候你都可以立即中止所有实盘操作。这是一个安全阀,当发现策略异常或市场极端时,可以马上断开。

fail-closed(出错默认拒绝)

fail-closed 的原则是:出错时默认「拒绝操作」而非「放行」。宁可漏掉一笔交易,也不能误下一笔订单。这与「fail-open」(出错放行)相反——金融场景里,fail-closed 是必须的。

审计记录

所有 live 操作都会被记录:谁、什么时候、下了什么单、结果如何。这些审计记录让事后追责、复盘、合规检查成为可能。

六、为什么学习阶段只用 read-only 和 paper

把上面所有内容汇总,你会理解为什么本教程反复强调「学习阶段只用 read-only 和 paper」:

• read-only 零风险:只读不改,不动资金。
• paper 验证流程:模拟下单,测全订单链路,但不碰真钱。
• live 才碰真钱:且必须经 mandate/kill switch/fail-closed/审计四道防线。

⚠️ 学习阶段的安全底线:只用 read-only 和 paper。等你能解释每一笔 simulated order 为什么产生,再考虑真实账户连接。本教程及 Vibe-Trading 均不构成投资建议,任何真实交易应先经过你自己的判断、券商确认、模拟盘验证和风险控制。

七、为新券商补齐连接器(给贡献者)

如果你用的券商不在支持列表里,可以参考以下方向为新券商补齐这条路径:

1. 官方 API 或用户导出:把券商的官方 API 或用户导出的交易记录归一化成项目里的 TradeRecord 格式。
2. 复用 connector 基类:继承项目的 connector 基类,实现账户/持仓/委托/下单的接口。
3. profile 实现:确保 read-only 完全无写操作,paper 接沙盒,live 走 mandate。
4. 安全测试:给 connector guard、live mandate、paper-only 限制、路径 sandbox 补回归测试。

这是第 4 章和项目贡献指南的内容,这里只点到为止。

本节要点回顾

1. loader vs connector:loader 读行情(数据层,安全),connector 连账户(账户层,谨慎)——职责完全不重叠。
2. connector 能力:读账户/持仓/委托/报价/历史 K 线,以及在允许 profile 下下单撤单。
3. 三种 profile:read-only(只读,第一次连真账户首选)、paper(模拟盘,验证订单流程)、live(真实账户,需多重防线)。
4. read-only:零风险,确认连接正常的首选。
5. paper:模拟下单测全链路,从研究过渡到实盘的安全中间态。
6. live 安全防线:mandate(授权边界)+ kill switch(急停)+ fail-closed(出错拒绝)+ 审计记录。
7. fail-closed 原则:出错默认拒绝而非放行,金融场景必须如此。
8. 学习阶段底线:只用 read-only 和 paper;能解释每笔 simulated order 后才考虑 live。

⚠️ 本节所有涉及实盘与下单的内容均不构成投资建议。Vibe-Trading 不是券商,不托管资金,实盘功能 opt-in 且默认只读,可随时中止。

至此第 3 章结束。你分清了市场、数据源、券商账户,掌握了数据路由,理解了券商连接器的安全分级。下一章我们将进入工具与进阶——Shadow Account 复盘你自己、命令行参考、配置环境变量与密钥,把研究能力用深、用广。