数据层：loader
agent/backtest/loaders/ 负责行情和财务数据。它按市场类型选择公开源、可选 key 数据源、券商网关数据源或本地文件，并在可用时做 fallback。
中文教程 · Beginner Guide
从金融术语到项目使用：读懂 Vibe-Trading
这份教程写给没有金融专业背景、交易经验也不多的读者。它不教你“稳赚策略”，而是帮助你理解 Vibe-Trading 里的因子、策略、回测、数据源、券商连接器和 Shadow Account 分别是什么，以及如何按安全顺序把它用起来。
1. 先建立项目地图
Vibe-Trading 可以先理解成“交易研究工作台”。你用自然语言提出问题，项目把问题拆成数据读取、因子计算、策略生成、回测、报告和账户连接等步骤。它不是券商，也不托管资金；核心价值是让研究步骤能运行、能复查、能沉淀。
01 Prompt
你提出问题，例如“回测一组大盘股的动量策略”。
02 Data
loader 拉取股票、加密、期货、外汇等市场数据。
03 Signal
因子或策略代码把数据变成买卖信号。
04 Backtest
回测引擎按市场规则模拟交易路径。
05 Report
输出指标、图表、报告、run card 和可复查 artifacts。
因子层：factor / alpha
agent/src/factors/ 内置 456 个 alpha。因子是给股票打分的数值信号，不是下单规则，也不是收益保证。
回测层：backtest
agent/backtest/ 根据 config.json 和 code/signal_engine.py 运行模拟交易。股票、加密、期货、外汇和组合资产有不同引擎。
券商层：connector
agent/src/trading/ 把不同券商统一成账户、持仓、委托、行情、历史 K 线、下单、撤单等 profile。这里和 loader 不同：loader 读市场数据，connector 读或操作你的券商账户。
工具层：MCP tools
agent/src/tools/ 把能力暴露成 agent 可以调用的工具，例如 backtest、factor_analysis、trading_positions、analyze_trade_journal。
复盘层：Shadow Account
agent/src/shadow_account/ 从你的交易流水里提取习惯规则，回测一个“规则版的你”，再和真实交易做差异归因。
2. 常见金融术语翻译
先把词翻译成人话，再看代码会轻松很多。下面这些词会反复出现在 README、Alpha Zoo、回测和券商连接器里。
| 术语 | 普通话解释 | 项目里对应哪里 |
|---|---|---|
| 标的 / symbol | 你研究或交易的对象，比如 AAPL、BTC-USDT、600519.SH。 |
回测配置里的 codes，券商工具里的 symbol。 |
| K 线 / OHLCV | 一段时间内的开盘价、最高价、最低价、收盘价、成交量。 | loader 返回的基础行情列：open/high/low/close/volume。 |
| VWAP | 按成交量加权的平均价格，粗略理解为“这段时间市场真实成交的平均成本”。 | 一些 alpha 需要 vwap 列。 |
| amount | 成交额，通常等于价格乘以成交量的金额口径。 | 某些成交量、流动性和短周期因子会用到，部分股票数据源会提供。 |
| 因子 / factor / alpha | 给一组股票打分的公式。分数高可能代表更值得买，也可能代表更值得卖，要靠 IC、回测和业务解释验证。 | agent/src/factors/zoo/。 |
| 策略 / strategy | 把信号变成交易规则：买什么、买多少、什么时候卖、最多持仓多少、如何止损。 | signal_engine.py 和回测配置。 |
| Signal Engine | 项目里承载策略逻辑的 Python 类。它读取 bar 或 panel，输出目标仓位或买卖信号。 | 回测 run dir 里的 code/signal_engine.py。 |
| 回测 / backtest | 用历史数据模拟“如果当时按这套规则交易，会发生什么”。它只能证明历史表现，不能证明未来收益。 | agent/backtest/runner.py 和各市场 engine。 |
| IC | Information Coefficient。这里是某天因子排名和未来收益排名的 Spearman 相关。正 IC 说明分数高的股票之后更容易涨。 | compute_ic_series()。 |
| IR | IC 均值除以 IC 波动。粗略理解为“这个因子稳定不稳定”。 | alpha bench 的排序指标之一。 |
| lookahead | 偷看未来数据。比如用今天收盘后才知道的信息去假装今天开盘前就知道。 | factor operator 禁止负向 shift；回测用下一根 bar 执行来降低偷看风险。 |
| PIT | Point-in-time，只使用当时已经公开、已经可获得的数据。 | 财务字段、Shadow Account 入场上下文和回测验证都强调这个边界。 |
| warmup | 滚动窗口刚开始时数据不够。例如 20 日均线前 19 天没有有效值。 | alpha metadata 的 min_warmup_bars。 |
| NaN | 空值。金融数据里空值不是 0，很多时候代表停牌、数据源缺失或窗口不足。 | 因子算子保留 NaN，不静默填 0。 |
| 滑点 / slippage | 你想成交的价格和实际成交价格之间的差距。 | 不同市场引擎都有自己的简化滑点参数。 |
| 回撤 / drawdown | 账户净值从高点跌到低点的幅度。最大回撤是衡量策略痛苦程度的重要指标。 | 回测 metrics。 |
| benchmark | 对照组，例如沪深 300、恒生指数、SPY。策略不是只看赚钱，还要看有没有跑赢参照物。 | 回测报告和 benchmark comparison。 |
| paper / live | paper 是模拟盘，live 是真实账户。真实账户必须非常谨慎。 | connector profile 的 environment。 |
| mandate | 实盘授权边界：能交易哪些标的、单笔多少、最大仓位、每日亏损限制等。 | 实盘下单路径的风控门。 |
3. 因子和 Alpha Zoo
因子是 Vibe-Trading 里最容易让非金融读者困惑的部分。你可以把它理解成“排序公式”：每天给很多股票各打一个分，然后看分数高的一组未来表现是否更好。
重要：因子不是策略。因子只回答“哪个标的分数更高”。策略还要回答“买多少、什么时候买、什么时候卖、交易成本多少、是否允许集中持仓、是否能成交”。
当前仓库的 Alpha Zoo 有 456 个 alpha，分成四类：
| Zoo | 数量 | 适合怎么理解 |
|---|---|---|
academic |
10 | 学术风格因子，例如动量、反转、52 周高点、非流动性等，适合入门理解。 |
alpha101 |
101 | 公式化 alpha，很多公式混合价格、成交量、排名、滚动相关。 |
gtja191 |
191 | 国泰君安短周期交易型因子，A 股语境更强。 |
qlib158 |
154 | Qlib Alpha158 特征，常作为机器学习模型的输入特征。 |
常见 theme 可以这样读：
- momentum：最近强的标的是否继续强。
- reversal：最近跌多或涨多后是否反向修复。
- volume：成交量变化是否包含资金行为信息。
- volatility：波动率是否能解释之后的收益或风险。
- liquidity / microstructure：流动性、盘口、成交结构相关信号。
- value / quality：估值或质量风格，通常更偏中长期。
先用 CLI 浏览，而不是直接读 456 个源码文件：
vibe-trading alpha list --zoo academic
vibe-trading alpha show academic_mkt_rf
vibe-trading alpha bench --zoo academic --universe sp500 --period 2020-2025 --top 10alpha bench 会把因子放到一个 universe 上测试。项目内置的分类逻辑是：IC 均值大于 0.02、IC 为正的比例至少 55%、t 统计显著时归为 alive；IC 显著为负时归为 reversed；其他归为 dead。这不是“可以买入”的结论，只是研究阶段的第一道筛选。
4. 策略和 Signal Engine
策略是把研究想法变成可执行规则。一个很朴素的策略可以是：“如果 20 日均线高于 60 日均线，就持有；否则空仓。”多因子策略则可能是：“在一个股票池里，用动量、质量、波动率三个因子合成分数，买前 20 只，每月调仓一次。”
在 Vibe-Trading 里，策略通常落到一个 run dir：
my_run/
config.json
code/
signal_engine.pyconfig.json 告诉回测系统：标的、起止日期、数据源、bar 周期、使用哪个市场引擎。signal_engine.py 告诉系统：每根 K 线或每个交易日应该生成什么信号。
新手最常见错误是把“因子分数高”直接等同于“马上满仓买入”。实际策略还需要仓位上限、调仓频率、交易成本、停牌/涨跌停、风险控制和 benchmark 对比。
5. 回测如何工作
回测不是预测器，而是历史模拟器。它的价值是让你在投入真实资金前，先看清一套规则在历史数据里经历过什么：赚了多少、最大亏了多少、交易频率多高、是否只是某一年有效、是否被手续费吃掉。
回测入口
vibe-trading run -p "Backtest a momentum strategy on a broad equity universe from 2020 to 2025. Include benchmark comparison, drawdown, turnover, and a short explanation."如果 agent 生成了 run dir，最终会调用 backtest 工具。这个工具会校验 config.json 和 code/signal_engine.py，再运行 agent/backtest/runner.py。
为什么市场引擎很重要
不同市场不是同一套交易规则。项目里股票、加密、期货、外汇和组合资产会走不同 engine；某些股票市场需要处理 T+1、涨跌停、一手股数、佣金、印花税、结算费和滑点，另一些市场可能支持 T+0、做空或小数股。
这意味着你不能只看“信号准不准”，还要看它落到真实市场规则后能不能成交、成本有多高、仓位会不会过度集中。很多看起来很漂亮的短线策略，一加入滑点和费用就会失效。
6. 市场和数据源怎么选
陌生用户第一次使用时，最容易混淆的是“市场”“数据源”和“券商账户”。市场决定交易规则，数据源决定历史数据从哪里来，券商账户只在你需要读取真实账户或模拟/真实下单时才涉及。
公开行情源
适合入门研究、普通价格数据和快速试跑。优点是启动门槛低；缺点是覆盖、速率、复权、字段质量和可用性会随来源变化。
可选 key 数据源
适合更稳定的研究和更丰富的字段，例如指数成分、财务数据、基本面字段或专业行情。缺点是需要申请 token 或付费。
本地数据
local loader 可以读你自己的 CSV、Parquet 或 DuckDB 数据。对于清洗后的历史数据、离线研究、可复现实验，本地数据通常最可控。
组合市场
CompositeEngine 可以做跨市场组合研究。比如同一个策略里同时持有股票、加密和期货时，不同市场由不同 engine 处理。
7. 券商连接器
connector 和 loader 要分清：loader 读行情，connector 连接券商账户。connector 的典型能力包括读取账户、持仓、委托、报价、历史 K 线，以及在允许的 profile 下下单或撤单。
vibe-trading connector list
vibe-trading connector use <profile-id>
vibe-trading connector check看 connector 时，不要先问“能不能自动交易”，先看 profile 的安全属性：
| Profile 类型 | 含义 | 适合阶段 |
|---|---|---|
readonly |
只读账户、持仓、订单或行情，不会提交订单。 | 第一次连接真实账户时优先使用。 |
paper |
连接模拟盘或沙盒账户，即使下单也不动用真实资金。 | 验证策略、订单字段、成交回报和撤单流程。 |
live |
连接真实账户。任何写操作都必须经过授权边界、kill switch、fail-closed 检查和审计记录。 | 只在你完全理解风险、并先经过 read-only 与 paper 验证后使用。 |
如果你只是想学习项目，建议先只用 read-only 和 paper。等你能解释每一笔 simulated order 为什么产生，再考虑真实账户连接。
8. Shadow Account
Shadow Account 是“复盘你自己”的功能。它不是从网上找一个通用策略，而是读取你的交易流水，配对买入和卖出，找出你赚钱交易里反复出现的规则，再回测一个规则版的 shadow strategy。
当前交易流水解析支持若干常见券商导出格式和 generic CSV。它会输出持仓天数、胜率、盈亏比、回撤、处置效应、过度交易、追涨、锚定等行为诊断。随后 Shadow Account 会提取 3 到 5 条 if-then 规则，生成策略代码，跑多市场回测，最后渲染 HTML/PDF 报告。
vibe-trading --upload trades_export.csv
vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, and compare it with my actual trades."如果你想给某个新券商补齐这条路径，优先方向是：把官方 API 或用户导出的交易记录归一化成项目里的 TradeRecord 格式，然后复用现有 Trade Journal 和 Shadow Account 流程。
9. 建议学习路线
- 第一天：只跑起来。 安装、初始化、打开 CLI 或 Web UI，问一个你熟悉的问题，不连券商，不下单。
- 第二天：只看数据。 选几个你熟悉的标的，理解 symbol、OHLCV、数据源 fallback 和缺失值。
- 第三天：只看因子。 从
academiczoo 开始，用alpha show看公式，用alpha bench看 IC/IR，不急着交易。 - 第四天：做一个简单回测。 让 agent 生成一个动量或均线策略，重点看 config、signal_engine、回测指标和交易明细。
- 第五天：复盘自己的交易。 如果你有券商导出的 CSV，先用 Trade Journal 和 Shadow Account 看行为画像。没有也没关系，先读报告模板和数据结构。
- 第六天以后：连接券商。 从 read-only 和 paper 开始，确认账户、持仓、订单读取正常，再理解 mandate、kill switch 和 fail-closed 的实盘边界。
一组适合入门的命令：
pip install vibe-trading-ai
vibe-trading init
vibe-trading
vibe-trading serve --port 8899
vibe-trading alpha list --zoo academic
vibe-trading alpha bench --zoo academic --universe sp500 --period 2020-2025 --top 10
vibe-trading connector list10. 可以贡献什么
如果你想给项目做贡献，不必一上来碰实盘下单。更稳的路线是从文档、例子、解析器和测试开始。
- 入门文档。 把因子、策略、回测、数据源、券商连接器这些概念写得更适合普通投资者。
- 可复现实例。 增加多市场教学 run，包含数据源、参数、回测指标和风险提示，但不要写成投资建议。
- 交易记录导入。 如果某个券商的官方 API 或导出文件能拿到成交、订单、持仓，就把它归一化到
TradeRecord，接入 Trade Journal 和 Shadow Account。 - 连接器文档。 把 paper/live/read-only/trade profile 的差异讲清楚，避免用户误以为所有连接器都可以直接实盘下单。
- 安全测试。 给 connector guard、live mandate、paper-only 限制、路径 sandbox、上传文件解析补回归测试。
这份教程和 Vibe-Trading 都不是投资建议。任何真实交易都应先经过你自己的判断、券商确认、模拟盘验证和风险控制。