QuantWitness

让 AI 探索，让研究有据可查。

QuantWitness 是一个 AI 协作的量化研究与回测框架。 你提供研究问题、论文或研报与数据，它通过可选的 RD-Agent 生成和改进研究代码，把数据检查、因子计算、模型训练、回测和独立验证接成可追溯的实验流程。

目标不只是画出一条好看的收益曲线，而是让你能回答：用了什么数据？当时能不能知道？试过哪些方案？这个结果能否被另一套检查复核？

入门教程 · 基本数据接入 · AI 复现研报 · 文档导航 · 框架约定 · 架构图集

点击图片打开交互架构图，可查看模块职责、上下游和源码位置。在线图册使用 GitHub Pages；离线使用请下载仓库并打开 docs/architecture/index.html。

你交给它什么，它交还你什么

三个核心交付物： Result 是实验的完整结果包，VerificationResult 是独立检查单，报告是供人阅读的展示。程序跑完和验证通过分别记录，不用一条“成功”掩盖差别。

示例：给一份 PDF，复现其中的因子

假设你想研究：“成交量集中在少数分钟的股票，之后的表现是否不同？”

1. 给材料和数据。 指定 PDF 中的公式页，准备分钟行情、交易日历和数据说明。框架不会替你猜证券池、频率或交易规则。
2. AI 提取，人来确认。 把“如何计算”变成待审阅说明，保留页码与原文位置。你确认窗口、缺失值、停牌和信号可用时点。
3. RD-Agent 写代码。 在固定接口与预算内生成、修复候选；复现任务不能为了收益更高而改写确认过的公式。
4. QuantWitness 执行与复核。 检查数据当时是否可见，运行研究，再由不调用候选实现的验证器重新核算。
5. 拿到可追溯结果。 从报告回到结果表、候选代码、确认记录和论文来源。若要检验预测力或交易收益，再明确标签、样本外划分、成交与费用假设。

仓库自带一个无需购买数据、无需付费模型调用的教学案例：

两只虚构证券、五个交易日、2,400 条合成分钟记录。由自编 PDF 定义成交量集中度 C = Σvᵢ² / (Σvᵢ)²；先给出一个故意加错数的候选，再用正确候选通过独立复算。均匀成交一天 240 根分钟线时，日指标应为 1/240。

运行这个教学案例 · 换成自己的 PDF 与实时模型

教学案例使用固定响应演示真实调度与验证流程，不冒充实时 AI 推理。真实 PDF 场景需要模型服务、已有研究包、数据来源和对应的独立验证器；目前不是“上传任意论文就全自动复现”。

示例：让 AI 继续提出新研究

复现回答“有没有实现对”；探索回答“还值得试什么”。两者使用不同目标。

你：在固定开发样本中探索收盘价因子，并限制实验轮数与模型调用预算。
         ↓
RD-Agent：提出因子或模型方案，生成候选代码
         ↓
QuantWitness：检查数据时点 → 运行 → 独立验证
         ↓
只把通过验证的开发指标返回给 RD-Agent → 决定下一轮
         ↓
选定方案后，另行执行最终留出样本评价

可选入口包括因子研究、生成式模型研究和因子与模型联合研究。当前各入口有明确的表达式、模型结构和数据范围，不代表任意策略代码都能自动验证。

为什么不直接写一个回测脚本

• 避免“今天知道的事，昨天就拿来交易”。 用公告或可见日期对齐数据；盘中使用已完成的行情条目。训练处理器只拟合允许的训练样本，最终留出集不参与 AI 迭代。这称为时点一致性，或 PIT（Point-in-Time）。
• 避免“换了数据，却以为复现了同一实验”。 研究范围、输入来源、参数和实现随计划固定；关键来源变化会阻止继续使用原计划。
• 避免“跑出来了，就当它是对的”。 独立验证检查已声明的公式、时间与金融关系，失败会留下具体发现。
• 避免“机器中断，前面全白跑”。 已完整提交的步骤可以复用；未完成或身份不一致的输出不能冒充缓存命中。
• 避免“AI 反复看最终答案”。 开发反馈与最终评价分开，记录候选、预算和数据消费过程。

这些机制依赖正确的数据说明和具体研究的验证范围，不能凭空证明供应商历史数据准确，也不能保证策略盈利。

六张图看懂框架

开头的总体概览图回答“它能帮我完成什么”。下面五张图进一步解释模块组成、数据来源、操作顺序和运行状态。README 中的六张图是简明预览；点击任一图片，直接打开对应的详细交互 HTML，查看完整节点、连线和说明。详细版支持主题与风格切换、动态连线、搜索和关系追踪。

1. 总体架构：模块怎样协作

14 个核心模块分工明确：RD-Agent 经正式入口提交研究，Qlib 提供算法组件，运行时调度数据和计算，结果再交给独立验证。

2. 数据流：结果从哪里来

从原始数据、数据说明和准入计划，到正式输入、结果包及检查单，保留可追溯的关联。

3. 工作流：一次研究怎么完成

按研究说明、检查、准入、执行、封存、验证和报告逐步完成；遇到中断再进入诊断与恢复。

4. 时序图：运行时谁先调用谁

以普通列式取数路径为例，区分命令层、运行时、节点适配器、结果封存和独立验证。

5. 状态图：怎样判断真正完成

程序运行、结果封存和验证各有状态。节点跑完，并不自动代表整项研究已经通过检查。

六张图的离线入口和维护说明见交互图册。

与熟悉的框架如何配合

这些工具并非互相排斥，下面比较的是各自主要关注点，而不是断言其他框架没有某项能力。

开始使用

建议先跑合成数据示例，看懂交付物，再接自己的数据，最后加入 AI。

git clone https://github.com/ljjtim/QuantWitness.git
cd QuantWitness
python -m pip install -e ".[dev]" "pyarrow==21.0.0"
python -m research_pipeline --help

核心要求 Python 3.10+。模型研究需要可选 Qlib 依赖；RD-Agent 集成要求 Python 3.11+，并有单独的调度环境要求。安装时请按对应指南，不必为了第一次研究安装所有 AI 依赖。

当前范围

• 支持声明式研究流程、日频模型研究、股票／ETF／期货的已实现仿真路径；具体市场、频率、账户事件与验证范围见对应文档。期权、完整融券、组合保证金优惠和实物交割不在当前通用能力承诺中。
• 研究阶段只读访问数据。行情采集、数据库写入和实盘交易不属于这条研究流程。
• 不附带真实行情或个人数据库配置。合成示例用于理解和验证工程行为，不能作为投资效果证明。
• 独立验证针对声明的规则与检查范围；自定义算法需要相应验证实现。目前没有免配置适用于一切策略的公共 Recipe。

开源与贡献

QuantWitness 自有代码采用 Apache-2.0。Qlib 与 RD-Agent 等上游组件保留各自许可证，详见第三方说明。欢迎从可手算的新研究示例、独立验证器、数据接入或文档改进开始：贡献指南。