Vintage

免费的金融数据散落在二十多个格式各异的 API 中。每个人都在糟糕地重复编写相同的胶水代码，最后还悄悄地用修订后的数据和幸存者偏差样本空间进行回测。

Vintage 就是这层胶水，只需编写一次，通过 MCP 提供服务。它不托管任何数据，只负责连接、规范化并提供来自网络的结构化金融数据。

一款零成本的研究终端，不会在夏普比率上骗你。

rezasoleymanifar.github.io/vintage

使用场景

_{四个场景中的两个——访问网站观看完整演示。}

安装

Claude Code

claude mcp add vintage -s user -- uvx vintage-mcp

Claude Desktop / 任意 MCP 客户端 — 添加到配置文件：

{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"]
    }
  }
}

_{Claude Desktop 配置文件位于 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。之后重启应用。MCP 服务只会在启动时加载一次。}

需要 uv。如果更愿意使用 pip：运行 pip install vintage-mcp，并将命令设置为 vintage。

可选配置

无需任何配置即可使用。以下配置可让它运行得更好：

变量	用途
VINTAGE_USER_AGENT	SEC EDGAR 要求提供真实的联系方式。"Your Name [email protected]"。
FRED_API_KEY	免费密钥 — 解锁 80 万条具有首次发布版本的数据宏观序列。
VINTAGE_CACHE_DIR	默认为 ~/.cache/vintage。

在同一配置块的 "env" 下设置：

{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"],
      "env": {
        "VINTAGE_USER_AGENT": "Jane Quant [email protected]",
        "FRED_API_KEY": "..."
      }
    }
  }
}

你的密钥会保留在此文件中。它由服务进程读取，不会传递给模型，也不会写入对话。

作为库使用

使用相同的数据，但不启动服务。所有操作都是同步的，并返回 pandas 数据， 包括在已有运行循环的 Jupyter 中也一样。

import vintage as v

v.prices("AAPL", start="2020-01-01")          # daily prices, with known_at
v.panel(["AAPL", "MSFT", "JNJ"])              # dates x tickers
v.fundamentals("AAPL", "us-gaap:Assets", as_of="2020-01-01")
v.restatements("AAPL", "us-gaap:Assets")      # periods reported twice, differently
v.factors("ff3")                              # Ken French, wide
v.macro("DGS10", as_of="2008-09-15")          # ALFRED first-release vintage
v.claim("Mom12m")                             # what the paper claimed
v.claims(price_only=True)                     # the 56 replicable with free data
v.crypto("BTC-USD")
v.short_volume("AAPL")
v.sentiment("wallstreetbets")

每个数据框都会保留 known_at 列，而不是为了整洁将其删除—— 丢掉它，就会让时点数据集悄悄变成普通数据集。传入 as_of 后，晚于该日期发布的行会在你看到它们之前被剔除。

试用

安装后，向你的助手提问：

"截至 2020 年 1 月，Apple 的总资产是多少？之后是否重述过？"

"对道琼斯 30 指数自 2010 年以来的动量策略进行 12-1 回测。"

"现在试试短期反转策略。阿尔法还存在吗？"

第三个问题才是关键。每个答案都会在摘要夏普比率旁，列出最差的样本外路径。

两个日期

每个值都带有两个时间：

• observed_at — 该数字描述的期间
• known_at — 该数字首次公开的时间

回测只能使用 known_at 早于交易日期的行。这是结构性保障，不是可调整的设置：面板以 known_at 为索引，因此对它进行的任何切片都会自动保证时间点正确。没有开关可以关闭此保障。

无法提供准确 known_at 的来源会被标记为 UNKNOWN_VINTAGE，而不是赋予一个编造的日期。

昨天的数据悄然发生变化的六种方式

• 滞后 — 数字在 12 月为真，却到 2 月才公布。
• 重述 — 公司说“糟了，之前错了”，并修改去年的数据。
• 修订 — 政府持续修正过往的就业和通胀数据，甚至长达数年。
• 幸存者偏差 — 已倒闭的公司被删除，只剩下赢家仍在列。
• 成分调整 — 今天的标普 500 名单，并非 2005 年的名单。
• 价格调整 — 拆股和股息会悄然改写它们之前的所有价格。

这六种情况都说明了同一件事：你今天拥有的数据，并非当时人们看到的数据。

六个动词

来源是一个参数，而非单独的工具。再增加 20 个来源，也不会增加任何工具。

动词	功能
resolve	任意标识符 → 其他所有操作都可接受的实体键
discover	在所有来源的目录中进行自然语言搜索
fetch	核心工具。任意字段、任意来源，并支持 as_of
events	包含精确公开时间戳的申报时间线
backtest	横截面信号 → 收益、成本和样本外路径
benchmark	你的收益 → 与已发布因子的相关性和阿尔法

此外还有 status，可查看缓存大小、密钥以及你尝试过的规格数量。

回测方法论

• 经通胀调整的夏普比率（Bailey & López de Prado，2014），将本次会话中尝试过的每种规格都纳入考量
• 始终按换手率计入成本，不存在零成本模式
• 始终提示幸存者偏差，因为标的范围是当前仍然存在的公司名单

Vintage 实践的是回测验证领域的研究成果，而不是另创统计指标。执行真实性是另一个问题，已有 LEAN 和 Nautilus Trader 解决。Vintage 在此之前运行，处于大多数想法本该被淘汰的阶段。

技术	来源	状态
按 known_at 索引的时点面板	结构性设计，无法通过标志禁用	✅ 已发布
始终按换手率计入成本	不存在零成本模式	✅ 已发布
经通胀调整的夏普比率	Bailey & López de Prado（2014）	✅ 已发布
为经通胀调整而提供的会话试验台账	Bailey & López de Prado（2014）	✅ 已发布
通过 CSCV 计算回测过拟合概率	Bailey、Borwein、López de Prado & Zhu（2017）	⏳ 计划中
带隔离期的 Purged k 折交叉验证	Advances in Financial Machine Learning，第 7 章	⏳ 计划中
组合式 Purged 交叉验证	Advances in Financial Machine Learning，第 12 章	⏳ 计划中
最短回测长度	Bailey、Borwein、López de Prado & Zhu（2014）	⏳ 计划中
针对自相关收益的 Newey–West 调整	Newey & West（1987）	⏳ 计划中
平方根市场冲击模型	Almgren 等（2005）	⏳ 计划中

引用仅供参考，并不代表认可——这些作者均未参与 Vintage。任何标记为计划中的功能目前都尚未实现，backtest 响应会在运行时说明这一点，而不是等到脚注中才提及。

数据来源

100 年，1926 年 7 月至今天早晨

331 已发表的异象，附有相关主张

18 个来源，六种动词

10,398 已映射股票代码的美国申报公司

800k+ 带历史版本的宏观时间序列

一个世纪的市场历史、二十二个数据来源，其中二十个无需密钥。 Fama-French 因子数据始于 1926 年 7 月，SEC 申报数据流则一直更新到今天早晨——Vintage 用同样的六种动词覆盖了这两端。

其中大多数都是一手来源——不是转售商，也不是爬虫。申报文件来自接收它们的监管机构，宏观时间序列来自发布它们的中央银行，因子数据则来自计算它们的大学。 @删除所有表情符号，只打印带图标的来源列表。

来源	可靠性	涵盖内容	密钥	时间点数据
SEC EDGAR XBRL	一手 · 美国监管机构	每家美国申报公司标记的所有概念，每个数值都附有 accession number 和申报日期。重述会作为新行添加，不会覆盖原有数据。	无	✅ 原生申报日期
SEC filings stream	一手 · 美国监管机构	8-K、10-K、10-Q、Form 4、13D/G — 精确到 EDGAR 接受文件的秒级时间戳。	无	✅ 精确时间戳
FRED / ALFRED	一手 · 中央银行	圣路易斯联邦储备银行。ALFRED 保留初次发布的数据，因此你可以查询那天早上的 CPI 数据。	免费	✅ 首次发布版本
Ken French Data Library	一手 · 学术机构	达特茅斯。FF3、FF5、动量、日度 FF3、49 个行业投资组合 — 数据来自作者发布渠道。	无	❌ 每次发布都会重新构建
Open Source Asset Pricing	一手 · 学术机构	Chen & Zimmermann。331 个已发表的预测因子，附带声称的收益率、t 统计量、样本窗口和可实施的定义。openap:Mom12m 返回 Jegadeesh-Titman 的 1.31%/月，t=3.74。	无	✅ 声明日期为发表年份
SEC Form 13F	一手 · 美国监管机构	资产超过 1 亿美元的每位管理人的机构股票持仓。季度末与申报日期最多相差 45 天，两者都会保留，因此 as_of 返回实际已公开的投资组合。	无	✅ 季度末日期与申报日期
SEC Form 25	一手 · 美国监管机构	有记录以来的每次退市 — 11,614 家公司的 36,830 份申报。这是修正仅根据仍然存续的公司名称构建的数据全集所需的数据。	无	✅ 申报日期，不会修订
SEC XBRL frames	一手 · 美国监管机构	一次调用即可获取所有申报公司中同一概念的数据。6,289 家公司，仅 840 KB — 适合横截面排序的数据形态。	无	❌ 包含 accession，但不含其日期
US Treasury	一手 · 美国政府	面值收益率曲线，涵盖从 1 个月到 30 年的 14 个期限，每个工作日发布。	无	✅ 不会修订
CFTC	一手 · 美国监管机构	交易者持仓报告。周二按交易者类别划分的持仓数据于次周五发布，并保留这一延迟。	无	✅ 延迟保留在 known_at 中
Bureau of Labor Statistics	一手 · 美国机构	细化至商品项目层级的 CPI、就业人数、JOLTS、工资、生产率。可查询任何系列 ID，不限于精选列表。	可选	❌ 不提供发布日期
Bureau of Economic Analysis	一手 · 美国机构	国民账户。一次调用即可返回 NIPA 表的所有行，而非一次只返回一个系列。	免费	❌ 仅提供当前估值
European Central Bank	一手 · 中央银行	自 1999 年以来的每日外汇参考汇率，以及所有根据两个欧元货币对推算并标记为推算值的交叉汇率。	无	✅ 仅发布一次，不会修订
CBOE	一手 · 交易所	VIX 及完整的波动率系列 — 期限结构、VVIX、SKEW — 可追溯至 1990 年。	无	✅ 指数水平不会修订
FINRA	一手 · 美国监管机构	每个交易日收盘后发布的各代码每日卖空成交量，且不会修订。这里是卖空成交量，不是卖空持仓量。	无	✅ 不会修订
Coinbase Exchange	交易所	所有已上市交易对的加密货币 OHLCV 数据。	无	✅ 交易记录不会重述
ApeWisdom	社区	约 15 个 subreddit 的论坛提及排名。上游不提供历史数据 — 行数据会在 Vintage 获取时加上时间戳。	无	⏩ 仅向前记录，从你开始记录之日算起
Yahoo Finance	第三方	深达数十年的每日 OHLCV 和调整后收盘价。	无	⚠️ 会追溯调整，并在每一行标记

COVERAGE.md 包含完整的逐字段目录 — 涵盖每个前缀、每个数据集、每个信号，并附有测得的覆盖范围。该目录由注册表生成，因此不会与代码不一致。

截至 2026 年 8 月的统计数据。Vintage 不会重新分发任何这些数据 — 每个上游来源都遵循其自身条款。

缓存

使用 Gzipped JSON，存储在 ~/.cache/vintage 中，并根据数据的可变程度分层：已结束的周期永不重新获取，学术数据集每月更新，当前基本面每日更新，价格则按交易时段更新。一小时的对话大约会产生 20 次上游调用。

已知缺口

这里直言不讳，因为另一种做法就是提供糟糕的替代方案：

数据：

• 幸存者偏差 — 覆盖范围仅包含当前上市公司。Form 25 退市数据将在下一轮构建中加入；在此之前，回测器会发出警告。
• 分析师预期 — 没有免费的数据源。
• 历史期权链 — 所有来源都收费。
• 时间点指数成分 — 由 S&P 和 MSCI 授权。

引擎 — 回测器采用向量化和横截面方法，功能级别低于事件驱动模拟器：

• 没有清除期或隔离期 — 重叠的标签窗口可能在训练集／测试集划分之间造成泄漏（López de Prado，AFML 第 7 章）。去膨胀可以发现选择偏差，但无法发现泄漏。
• 没有市场冲击 — 成本按换手率收取固定费用，因此大额名义金额的结果偏乐观。
• 没有 PBO — 去膨胀夏普率涵盖多重检验；通过组合对称交叉验证计算的回测过拟合概率会是更有力的检验。
• 试验次数按会话统计，且可以重置 — reset_trials=True 会在对话中途将其归零。这是有意为之：修正只适用于同一个问题的重复尝试，而引擎无法区分这些尝试与无关尝试。
• 夏普率按观测值计算，而非年化 — 去膨胀的定义频率就是如此，响应中也会说明这一点。

开发

git clone https://github.com/RezaSoleymanifar/vintage
cd vintage
uv sync --group dev
uv run pytest

smoke_test.py 使用实时数据源测试全部六种操作 — 适合在发布前运行，并且需要网络连接。

许可证

MIT。Vintage 不再分发任何数据；每个上游数据源均遵循其自身条款。

_{mcp-name: io.github.RezaSoleymanifar/vintage}