第 1 章 · 02 项目地图:六层结构

文档摘要

第 1 章 · 02 项目地图:六层结构本节摘要:上一节你跑通了第一个研究任务,但「一句话提示究竟在系统里如何流转」仍是黑盒。本节用一张分层地图把 Vibe-Trading 拆成六层——数据层(loader)、因子层(factor / alpha)、回测层(backtest)、券商层(connector)、工具层(MCP tools)、复盘层(Shadow Account),并指出每层对应的源码目录与职责边界。理解这张地图,你就能在后续章节里随时定位「我正在读的这部分属于哪一层、和哪一层协作」。读完本节,你会对 Vibe-Trading 的内部结构有一张可挂在脑海里的全景图。内容来源:原项目中文入门教程(第 1 章「先建立项目地图」)与英文文档合并改写。

第 1 章 · 02 项目地图:六层结构

本节摘要:上一节你跑通了第一个研究任务,但「一句话提示究竟在系统里如何流转」仍是黑盒。本节用一张分层地图把 Vibe-Trading 拆成六层——数据层(loader)、因子层(factor / alpha)、回测层(backtest)、券商层(connector)、工具层(MCP tools)、复盘层(Shadow Account),并指出每层对应的源码目录与职责边界。理解这张地图,你就能在后续章节里随时定位「我正在读的这部分属于哪一层、和哪一层协作」。读完本节,你会对 Vibe-Trading 的内部结构有一张可挂在脑海里的全景图。

内容来源:原项目中文入门教程(第 1 章「先建立项目地图」)与英文文档 getting-started/vibe-trading-overview 合并改写。

学习目标

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

复述 Vibe-Trading 的六层结构(loader / alpha / backtest / connector / tools / shadow_account),并说出每层的中文与英文职责名。
指出每层对应的源码目录,在仓库里能快速找到它们。
用一句话讲清 loader 与 connector 的区别(一个读市场行情,一个连账户),避免最常见的混淆。
解释「工具层」为什么是横切的——它把其他各层的能力包装成 agent 可调用的工具。
在脑海里建立一句话提示从「prompt」到「report」的流转路径。

一、为什么要先看地图

很多人读开源项目喜欢从 README 一头扎进源码,结果在几百个文件里迷路。Vibe-Trading 的代码量并不小,但它的结构有一个清晰的分层骨架:每一个研究步骤,几乎都能归到下面六层中的某一层。

先建立这张地图有两个好处:

读代码时有坐标系:看到 loaders/ 你知道在数据层,看到 factors/ 你知道在因子层,不会被细节淹没。
理解协作关系:回测不是孤立的,它要靠 loader 喂数据、靠 Signal Engine 喂信号、靠 connector 在某些场景读账户——分层让你看清「谁调用谁」。

💡 怎么读这节:不要死记目录名,重点记「这层负责把什么东西变成什么东西」。比如 loader 把「外部行情」变成「项目里的 DataFrame」,alpha 把「DataFrame」变成「打分」,backtest 把「打分 + 规则」变成「历史净值曲线」。

二、六层结构总览

一句话提示,从顶部进入,在六层之间流转成一个可检查的研究产物。其中数据层、因子层、回测层、复盘层是纵向流水线,而券商层是可选分支(只在需要读账户或下单时切入),工具层是横切面(把各层能力包装成 agent 可调用的接口)。

三、数据层:loader

职责:把外部市场行情和财务数据,变成项目里统一的 DataFrame。
源码目录:agent/backtest/loaders/
关键能力:按市场类型选择公开源、可选 key 数据源、券商网关数据源或本地文件,并在某个源不可用时尝试 fallback(降级)到备用源。

数据层是整条流水线的入口。你回测用的 K 线、做因子分析用的成交额、做基本面富化用的财务字段,全部由 loader 负责拉取并归一化。它解决的核心问题是:不同数据源返回的字段名、复权方式、缺失值处理都不一样,loader 把它们统一成项目内部的标准列(open/high/low/close/volume,以及可选的 amount、vwap 等)。

💡 缺失值不是 0:金融数据里的空值(NaN)常常意味着停牌、数据源缺字段或滚动窗口不足。loader 和后续因子算子都保留 NaN 而不静默填 0,因为「停牌」和「价格为 0」是完全不同的两件事。这点会在第 1 章 03「术语翻译」里展开。

四、因子层:factor / alpha

职责:给一组标的一个数值打分,作为后续策略与回测的输入信号。
源码目录:agent/src/factors/(其中 zoo/ 子目录是因子库)。
关键认知:因子是打分公式,不是下单规则,也不是收益保证。

Vibe-Trading 内置了 456 个 alpha(俗称 Alpha Zoo),分为 academic(学术风格)、alpha101(公式化)、gtja191(国泰君安短周期)、qlib158(Qlib 特征)四类。一个因子的输出,通常是一张「标的 × 日期 → 分数」的表,分数高的标的理论上未来表现更好(或更差,取决于 IC 验证)。

⚠️ 新手最大误区:把「因子分数高」直接等同于「马上满仓买入」。因子只回答「谁更值得研究」,不回答「买多少、什么时候买、能不能成交、成本多高、要不要止损」。这之间的鸿沟,要靠策略与回测来填,详见第 2 章 02「策略与 Signal Engine」。

五、回测层:backtest

职责:用历史数据模拟「如果当时按这套规则交易,会发生什么」。
源码目录:agent/backtest/(入口在 runner.py,各市场引擎在 engines/)。
关键认知:回测是历史模拟器,不是预测器——它只能证明历史,不能证明未来。

回测层会读取两个核心输入:config.json(告诉系统标的、起止日期、数据源、bar 周期、用哪个市场引擎)和 code/signal_engine.py(告诉系统每根 K 线生成什么信号)。然后按对应市场的引擎跑模拟,输出净值曲线、收益、回撤、交易明细、run card 等。

为什么要有多个引擎?因为不同市场的交易规则不同:


agent/backtest/engines/
  china_a.py          # A 股:T+1、涨跌停、一手 100 股、佣金、印花税
  global_equity.py    # 全球股票:可能 T+0、支持做空、小数股
  crypto.py           # 加密:7×24、T+0、高波动
  china_futures.py    # 中国期货:保证金、涨跌停、交割
  global_futures.py   # 全球期货
  forex.py            # 外汇
  composite.py        # 组合市场:同一策略里跨市场
  options_portfolio.py # 期权组合

这意味着你不能只看「信号准不准」,还要看它落到真实市场规则后能不能成交、成本多高。很多看起来漂亮的短线策略,一加入滑点和费用就失效,这是第 2 章 03「回测如何工作」的重点。

六、券商层:connector

职责:统一不同券商的接口,提供账户、持仓、委托、报价、历史 K 线、下单、撤单等能力。
源码目录:agent/src/trading/
关键认知:loader 读市场行情,connector 读或操作你的券商账户——两者职责完全不同,这是新手最常混淆的点。

券商层是可选的:如果你只做历史回测、因子分析、报告生成,根本不需要碰 connector。只有当你需要读取真实账户的持仓/委托、或要做模拟盘/真实下单时,才会切入这一层。

⚠️ 安全基调:Vibe-Trading 不是券商,不托管资金,不提供投资建议。任何实盘都是 opt-in 且默认只读,只在用户自己授权的券商内、在用户设定的限额内运行,可随时中止。学习阶段请只用 read-only 和 paper,详见第 3 章 03「券商连接器与安全分级」。

七、工具层:MCP tools

职责:把上述各层的能力,包装成 agent 可以调用的工具函数。
源码目录:agent/src/tools/
关键认知:工具层是横切的——它本身不存业务逻辑,而是把 loader、alpha、backtest、connector、Shadow Account 的能力「打包」成 agent 能理解的标准接口。

典型的工具包括:

backtest:跑一次回测。
factor_analysis:做因子分析(算 IC、IR)。
trading_positions:读取账户持仓(经 connector)。
analyze_trade_journal:分析交易流水(Shadow Account 入口)。

之所以要把能力「横切」成工具,是因为 Vibe-Trading 的核心是一个 agent loop:模型(LLM)根据你的自然语言提示,决定调用哪些工具、按什么顺序调用。工具层就是这个 loop 的「手脚」。第 4 章 04「MCP 服务」会讲怎么把这些工具进一步暴露给 Claude Desktop、Cursor 等外部客户端。

八、复盘层:Shadow Account

职责:从你的真实交易流水里提取习惯规则,回测一个「规则版的你」,再和真实交易做差异归因。
源码目录:agent/src/shadow_account/
关键认知:Shadow Account 是复盘你自己,不是从网上找通用策略。

它读取你的交易流水,配对买入和卖出,找出你赚钱交易里反复出现的规则,生成 3 到 5 条 if-then 规则,跑多市场回测,最后输出持仓天数、胜率、盈亏比、回撤、处置效应、过度交易、追涨、锚定等行为诊断,并渲染成 HTML/PDF 报告。

复盘层是 Vibe-Trading 区别于普通回测工具的特色功能,详见第 4 章 01「Shadow Account:复盘你自己」。

九、六层协作的完整流转

把六层串起来,一句话提示在系统里的完整流转是这样的:


你:  Backtest a momentum strategy on SP500 from 2020 to 2025
   │
   ▼
工具层(MCP tools)
   │  agent 决定调用 backtest 工具
   ▼
数据层(loader)        ←── 拉取 SP500 成分股的历史行情
   │
   ▼
因子层(alpha)          ←── 计算动量因子,给每只股票打分
   │
   ▼
策略(Signal Engine)    ←── 把分数变成买卖规则(买前 10、月度调仓)
   │
   ▼
回测层(backtest)       ←── 按 global_equity 引擎模拟,扣手续费/滑点
   │            ↑
   │            └── (可选)券商层 connector:读真实账户做对比
   ▼
报告(报告层)            ←── 输出指标、图表、run card、benchmark 对比
   │
   ▼
复盘层(Shadow Account)  ←── (可选)如果你上传了交易流水,做行为归因

💡 记住这张图:后续每一章,本质上都是在深入某一层。第 2 章深入回测层(含策略与验证),第 3 章深入数据层与券商层,第 4 章深入工具层与复盘层。

本节要点回顾

六层结构:数据层(loader)、因子层(alpha)、回测层(backtest)、券商层(connector)、工具层(MCP tools)、复盘层(Shadow Account)。
源码目录:loaders/ 在 agent/backtest/ 下;factors/、trading/、tools/、shadow_account/ 在 agent/src/ 下;backtest/ 主体在 agent/backtest/。
loader vs connector:loader 读市场行情(研究侧,默认),connector 读或操作你的券商账户(账户侧,可选且默认只读)——这是最常见的混淆点。
工具层是横切的:它把各层能力包装成 agent 可调用的接口,本身不存业务逻辑。
多引擎的必要性:不同市场交易规则不同(A 股 T+1、加密 T+0),所以回测层必须按市场走不同引擎。
复盘层特色:Shadow Account 复盘你自己,不是找通用策略。
完整流转:prompt → 工具层 → loader → alpha → Signal Engine → backtest → 报告 →(可选)Shadow Account。

⚠️ 再次强调:Vibe-Trading 不是券商,不托管资金,不构成投资建议。券商层默认只读,任何实盘都需经授权边界与 kill switch,详见第 3 章。

下一节,我们将用一张贯穿全书的术语表,把标的、K 线、因子、IC/IR、回撤、benchmark、mandate 这些反复出现的黑话,翻译成「普通话」并对应到项目里的具体位置。这是全书最值得反复查阅的一节。