Vibe-Trading 是什么：HKUDS 这个开源交易 Agent 项目的工程全景与边界

2026-08-05

本文基于 Vibe-Trading 仓库 commit 3a752d5（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/HKUDS/Vibe-Trading 最新代码与文档为准。

把 HKUDS 开源的这个 Vibe-Trading 仓库当成一款交易软件去读，你会读错方向。它真正值得看的部分是一套 Agent 工程范本：金融研究里那些反复出现的动作，被切成了技能、工具、多智能体编制三层可独立加载的单元，然后挂在一个通用的 Agent 循环上。

这个判断决定了你该怎么读它的代码。如果你抱着「找一个能自动买卖的机器人」的预期进去，会在满屋子的 Markdown 文档和 YAML 里迷路；如果你带着「一个复杂领域的工作流该怎么被拆给 Agent」的问题进去，几乎每个目录都能给你一条可迁移的经验。

一、先把名字和形态说清楚

Vibe-Trading 是 HKUDS 放出的一个开源项目名，不是「凭感觉交易」这类泛指说法。仓库 README.md 里它给自己的定位是一个开源的研究工作区，把自然语言提问接到行情装载器、策略生成、回测引擎、报告与持久化研究记忆上。许可证是 MIT（LICENSE 里写的是 Copyright (c) 2026 Vibe-Trading Contributors），NOTICE 的署名则是 Copyright 2026 HKUDS contributors。

形态上它有三个入口。agent/SKILL.md 里列了安装后可用的命令：vibe-trading 是交互式 CLI，vibe-trading serve 起 FastAPI 服务，vibe-trading-mcp 起 MCP 服务端。也就是说，同一套能力既可以当命令行工具用，也可以当 Web 应用用，还可以作为 MCP 服务被你现有的编码 Agent 调用——挂载方式就是那段最常见的配置：

{
  "mcpServers": {
    "vibe-trading": {
      "command": "vibe-trading-mcp"
    }
  }
}

第三种用法最值得工程师注意：它不要求你换客户端，而是把整套金融研究工具塞进你已经在用的 Agent 里。这也是本文把它归类成「Agent 工程」而不是「金融软件」的直接原因。

站内已经有几篇相邻的文章，分工不同：什么是 AI 智能体讲的是概念与基本构成，开源 AI Agent 平台盘点和开源 AI 工具怎么选做的是横向比较与选型；本篇不做比较，只把 Vibe-Trading 这一个仓库解剖开，给你一张能对照代码走的全景地图。

二、全景地图：每一层落在哪个目录

先给结论性的结构表。下面这些路径都可以在仓库里当场打开核对，文件数是用版本控制清单数出来的：

组成部分	它负责什么	仓库位置	你什么时候会碰到它
技能库	把金融方法论写成可按需加载的 Markdown 文档	`agent/src/skills/`（88 个技能目录，共 404 个文件）	Agent 决定「这题该用哪套方法」时
工具层	真正干活的可调用函数：取数、回测、读写文件、起一次编制运行	`agent/src/tools/`（72 个文件）	每一次实际的数据或计算动作
Agent 内核	循环、上下文、技能加载、执行轨迹	`agent/src/agent/`（`loop.py`、`context.py`、`skills.py`、`trace.py` 等）	排查「它为什么绕来绕去」时
因子库	分组存放的因子实现，出处逐条写在 `NOTICE` 里	`agent/src/factors/zoo/`（`qlib158`、`alpha101`、`gtja191`、`academic`、`fundamental`，全目录 482 个文件）	做横截面因子实验时
回测引擎	按市场分别建模的撮合与成本规则	`agent/backtest/engines/`（`china_a.py`、`korea_equity.py`、`india_equity.py`、`composite.py` 等）	跑任何一次历史模拟时
数据装载器	多来源取数与失败回退	`agent/backtest/loaders/`（基本是一个数据源一个文件）	换市场、换数据源时
多智能体编制	预置的团队分工与提示词	`agent/src/swarm/presets/`（30 份 YAML）	想让多个角色分头出报告时
实盘闸门	授权、下单守卫、急停、审计	`agent/src/live/`（`mandate/`、`order_guard.py`、`halt.py`、`audit.py`）	一旦你动了接券商的念头
券商连接器	各家券商 SDK 的适配	`agent/src/trading/connectors/`（12 个目录，含 `ibkr`、`alpaca`、`futu`、`okx` 等）	连账户读持仓、读行情时
消息渠道	把同一个会话运行时接到 IM	`agent/src/channels/`（16 个适配器实现）	想让研究结果自己发到群里时

整个仓库受版本控制的文件是 2030 个，其中 agent/ 占 1805 个、frontend/ 占 155 个。这个比例本身就说明了性质：它是一个后端重、前端轻的工程，前端承担的是交互与结果呈现，真正的资产在 agent/ 里那堆按职责切开的模块目录（agent/src/ 下有 23 个）。README 有 5 个语言版本，中文版是 README_zh.md——顺带一提，仓库自带中文文档这件事本身就提醒你：读它不需要先翻译，但也别把中文 README 的章节顺序当成理解顺序，那是给「怎么用」写的，不是给「怎么设计的」写的。

三、技能与工具：为什么要拆成两层

这是全仓最值得抄走的一个设计。很多人做垂直领域 Agent 时会把「怎么做」直接焊进工具的实现里，结果是工具越来越胖、提示词越来越长、换个方法论就要改代码。Vibe-Trading 把这两件事分开了。

agent/src/skills/ 下是 88 个目录，每个目录至少有一份 SKILL.md，用 YAML frontmatter 声明自己是谁。以 factor-research 这个技能为例，它的头部长这样：

---
name: factor-research
description: Factor research framework with IC/IR analysis, quantile backtesting, and factor combination. Suitable for cross-sectional factor evaluation across multiple instruments.
category: analysis
---

正文则是纯粹的方法论：适用场景、工作流几步、每步该调哪个工具、结果字段怎么读。它不含任何执行逻辑。Agent 通过 list_skills 看到有哪些技能可选，再通过 load_skill 把某一份完整文档拉进上下文——这就是典型的渐进式披露：目录常驻、正文按需。88 份方法论如果全塞进系统提示词，上下文预算会被吃光；只塞一个清单，代价就只有几十行。

工具层在 agent/src/tools/，72 个文件，一眼扫过去全是名词性的动作：backtest_tool.py、factor_analysis_tool.py、market_data_tool.py、options_payoff_tool.py、web_search_tool.py、read_file_tool.py、swarm_tool.py。它们只管「怎么执行」，不管「什么时候该执行」。

这种切法的好处在维护期才显出来：新增一套方法论只要加一个目录写一份 Markdown，不动 Python；工具的接口稳定下来之后，方法论可以自由演化。如果你想横向理解不同项目对「技能」这个概念的处理差异，站内有一篇三个项目的技能机制对比可以对照着看。

技能目录里还有个细节值得留意：88 个目录每一个都有 SKILL.md，但并非所有技能都只有这一份文件。有一批技能目录下另外放着同名的 example_signal_engine.py，还有 examples.md 之类的附件。也就是说这个技能格式允许「文档 + 可运行样例」打包，样例代码跟着方法论走，而不是堆在一个公共 examples 目录里让人猜哪份配哪套方法。这个约定的代价是重复——同一段样板会在多个目录里各存一份；换来的是每份方法论都能独立搬走。

四、编制 YAML 与因子库：两块最容易被误读的部分

agent/src/swarm/presets/ 下是 30 份 YAML，每一份描述一支预置团队。打开 investment_committee.yaml 会发现它的结构非常朴素：顶层是 name / title / description，下面 agents 列表里每个成员声明 id、role、system_prompt、tools、skills、max_iterations、timeout_seconds、max_retries。

下面是这份 YAML 里第一个成员的节选（description 与那一大段 system_prompt 已省略，其余键值照抄原文）：

name: investment_committee
title: "Investment Committee"
agents:
  - id: bull_advocate
    role: Bull-side Researcher
    tools: [bash, read_file, write_file, load_skill, get_market_data, factor_analysis]
    skills: [technical-basic, fundamental-filter, yfinance, earnings-revision, sentiment-analysis]
    max_iterations: 50
    timeout_seconds: 1800
    max_retries: 1

关键在 tools 和 skills 这两个白名单：每个角色能碰的工具、能加载的技能是逐个列出来的，而不是所有人共享一套全集。这是一个很实用的约束手段——多智能体系统里最常见的失控形态就是每个成员都拿着全权限，谁都能改文件、谁都能重跑回测。把编制写成配置而不是代码，也意味着调整分工不需要发版。

因子库这块必须说清楚出处，因为它最容易被误读成「项目自研的赚钱因子」。事实上仓库根目录的 NOTICE 写得很直白：qlib158 是打包了 Microsoft Qlib 的特征定义，走 Apache 2.0 许可；alpha101 对应 Kakushadze (2015) 的 101 Formulaic Alphas（arXiv:1601.00991）；gtja191 对应国泰君安 2014 年那份短周期交易因子研究报告；academic 一组来自 Fama-French 五因子、Carhart 动量、Hou-Xue-Zhang q-factor 等公开文献。NOTICE 明确说明这些是把数学公式当作事实性内容在本仓库重新实现，来源论文与报告的行文、表格与图并未复制。上述四个来源对应的子目录下各有一份 LICENSE.md（qlib158、alpha101、gtja191、academic）；fundamental 这一组没有在 NOTICE 里单列来源，也没有对应的 LICENSE.md，读的时候别把它和前四组混为一谈。

换句话说，这是一批公开公式的工程化重实现，仅此而已。它们的价值在于给你一个统一的计算与调用接口，不在于「有效」。能不能商用、怎么署名，以 NOTICE 与各 LICENSE.md 的许可证原文为准，本文不提供法律意见，也不代替你自己去读一遍。同样地，历史表现不代表未来，本文只讨论工程实现，不讨论任何因子或策略的好坏。

回测那一侧同理。agent/backtest/engines/ 按市场分文件建模，A 股、印度股、韩国股、加密、期货、外汇、期权组合各有各的规则文件，另有一个 composite.py 处理跨市场组合。工程上的看点是「市场差异被显式建模成独立文件」，而不是靠一堆 if 分支糊在一个引擎里。跑完之后产物落在 artifacts 目录，README 里提到过 run_card.json 与 risk_xray.json 这类可归档的运行卡片与风险快照——它们的意义是让一次运行可复查，而不是让结论更好看。

agent/SKILL.md 里项目自己描述的规模是：9 个回测引擎、462 个预置 alpha、24 个行情数据源、88 个金融技能、30 支多智能体团队、55 个 MCP 工具。这些是仓库自述的口径，不是本文实测的结论；上面表格里的目录数与文件数才是我数出来的。

五、边界与代价：它明确不管的事

任何一套架构都是取舍，这套也不例外。

它放弃了「开箱即用的黑箱」。 技能是文档、编制是 YAML、因子是公式重实现，意味着最终产出质量高度依赖你自己会不会提问、会不会读结果。这个项目没有替你把判断做掉，它只是把工具摆整齐了。

它对模型有依赖，而且分层。 agent/SKILL.md 的 env 段里写得很清楚：TUSHARE_TOKEN 是可选的，OPENAI_API_KEY 与 LANGCHAIN_MODEL_NAME 只有用 run_swarm（多智能体团队）时才需要。也就是说单机跑工具可以不带 LLM 密钥，但一旦上多智能体编制，成本结构就变了——30 份编制里每个成员都是一个独立的模型循环。

实盘这条线的代价必须说透。 仓库在 README.md 的 Disclaimer 里写明：它是研究与交易软件，不构成投资建议，不持有资金，不运营交易场所；通过你自行授权的券商通道交易属于实验性能力，官方未针对真实券商账户做过验证，风险自负。落到工程上：

凭据有暴露面。agent/src/trading/connectors/ 下 12 家连接器各自要各自的密钥或本地会话，~/.vibe-trading/.env 与 ~/.vibe-trading/agent.json 都是明文配置文件，任何能读到你 home 目录的进程就能读到它们。README 里那套 TAP 模式（TAP_PROXY_URL、TAP_AGENT_KEY 等环境变量）之所以存在，正是因为「进程里不要持有原始密钥」是个真问题——但要看清它的适用范围：这套凭据隔离默认关闭，代码上只落在 Alpaca 一家（agent/src/trading/tap_forward.py 与 agent/src/trading/connectors/alpaca/sdk.py），别当成对所有连接器都生效的全局保险。
下错的单不可撤销。写操作有闸门——agent/src/live/ 下有授权提交（mandate/commit.py）、下单守卫（order_guard.py）、急停（halt.py）、审计账本（audit.py）——但闸门只能拦住越界，拦不住你自己批准的一个错误指令。已经成交的委托不会因为你关掉进程而回滚。
程序化交易的合规义务因司法辖区而异。同一段代码在不同市场可能落在完全不同的监管框架里，仓库层面的安全设计不构成任何合规豁免。

它不管的还有几件事。 它不做行情撮合，不托管资金，不提供任何标的层面的判断。多智能体编制产出的是文档，不是指令。至于权限该怎么收，站内那篇最小权限设计讲的原则在这里完全适用——尤其是当工具集里同时存在 bash_tool.py 和券商连接器的时候。

六、上手与避坑清单

每条都写清楚为什么会踩、以及怎么避。

1. 别一上来就配券商。 为什么会踩：README 把连接器讲得很详细，容易让人误以为那是主线。实际上密钥一旦落盘，你的风险面就从「一个研究工具」变成「一个持有交易凭据的长期进程」。怎么避：先只用只读研究路径——按 agent/SKILL.md 的说法，港股、美股、加密的核心研究工具零密钥可用，把回测、取数、因子这条线跑顺了再谈别的。

2. 别用「装一个应用」的心态装它。 为什么会踩：它同时是 CLI、Web 服务和 MCP 服务端，三个入口共享同一套状态目录。你在 CLI 里建的会话、写的技能、存的记忆，Web 端也看得见。怎么避：先想清楚自己要哪个入口。只想给现有编码 Agent 加金融工具，就只配 vibe-trading-mcp，别起 Web 服务多开一个网络面。

3. 状态目录别乱搬。 为什么会踩：会话、运行记录、编制运行、上传文件都落在 ~/.vibe-trading 下，很多人习惯把工作区放项目里，找不到东西就以为丢了。怎么避：需要换位置就用 VIBE_TRADING_HOME 环境变量整体重定向，别手工挪目录。

4. 远程访问必须先设密钥。 为什么会踩：本机 localhost 打开是零配置的，很容易让人以为换台机器、换个手机连局域网也一样。实际上从非回环地址访问时，发消息、列会话、查实盘状态这些敏感接口会直接返回 403。README 的说法是这条路径后来补过一次提示文案，前端会明说需要 API key，但如果你是照着「本机能开就行」的印象部署的，仍然会先撞一次墙。怎么避：远程部署前先在 agent/.env 里设好 API_AUTH_KEY，重启，再到设置页里把同一个 key 填一次；Docker Desktop 的 host gateway 场景另有一个 VIBE_TRADING_TRUST_DOCKER_LOOPBACK 开关。

5. 别把外部 MCP 服务器当普通配置项。 为什么会踩：mcpServers 定义的是子进程的 command / args / env，等于给了对方在你机器上起进程的能力。仓库把它按运营者级别的信任来处理：API 调用方默认不能通过会话注入 MCP 服务器定义，除非服务端显式开了 ALLOW_SESSION_MCP_SERVERS=1。怎么避：把这个开关当成一道真实的信任边界看待，别为了图方便打开。

6. 加载外部 MCP 时写清 type。 为什么会踩：README 明确说了，对 URL 型传输，Agent 不再从 URL 后缀去猜是 SSE 还是 streamable HTTP。怎么避：URL 型服务器的配置里必须显式写 type，否则加载不上，而且失败模式是这台服务器被跳过、其它工具照常可用——很容易被忽略。

7. shell 类工具默认要显式开。 为什么会踩：API 路径上具备 shell 能力的工具需要 VIBE_TRADING_ENABLE_SHELL_TOOLS=1 才启用，有人照着编制 YAML 里的 tools: [bash, ...] 去调，发现不生效就开始改代码。怎么避：先确认是入口层的开关问题，而不是编制写错了。

8. 调度器不是默认开着的。 为什么会踩：定时研究功能需要 VIBE_TRADING_ENABLE_SCHEDULER 打开后台执行器，任务建好了却不跑，很容易被当成 cron 表达式写错。怎么避：先查开关，再查表达式。

收束：接下来该读哪个文件

如果你只有一小时，按这个顺序走：先读 agent/SKILL.md，它是全仓最紧凑的能力清单，命令、工具表、密钥要求都在里面；再打开 agent/src/skills/ 里任意一个目录的 SKILL.md，感受一下方法论是怎么被写成可加载单元的；然后翻一份 agent/src/swarm/presets/ 下的 YAML，看角色的工具与技能白名单是怎么收的；最后扫一眼 agent/src/live/ 的文件名，理解写操作那条线上都设了哪些闸。

一个自检清单，用来确认你读懂了这套设计：你能不能说出「技能」和「工具」在这个仓库里各自的职责边界？你能不能指出新增一套方法论需要改哪些文件、不需要改哪些？你能不能讲清楚多智能体编制里每个角色的权限是从哪来的？这三个问题答得上来，这个仓库对你的价值就已经兑现了大半——它真正可迁移的东西是拆法，不是金融。

至于实盘那条线能不能这么用，以你所在司法辖区的监管要求与券商协议为准。

这个系列的其余文章

这篇是总览。想往下挖，按下面两条线走：先把它跑起来用，或者直接读代码。

上手与使用

结构与机制

全部文章也汇总在 Vibe-Trading 开源专题。如果你想看的是另一类「让 Agent 去操作一个专业软件」的样本——不是金融方向，而是让它直接建三维模型——见 Pascal Editor 是什么：浏览器里的开源 3D 建筑编辑器，与它自带的建模 MCP 服务器。