QuantWitness

QuantWitness 帮助个人研究者和 AI 协作者把量化研究问题变成可重复运行、可独立验证的结果，只读使用研究数据，并按当时可见的信息开展研究。

能得到什么

股票横截面示例用四只虚构证券，在同一决策时点按已知收益排序，再观察之后的收益差。完成入门后，可以得到：

• Result：封存研究数值表、数据来源和运行身份。
• VerificationResult：独立复核结果，明确验证状态是否为 status=pass。
• 报告：展示验证结论；具体研究数值保存在 Result 的表中。

示例中 A 与 C 的未来收益差，手算值约为 0.0472222（小数收益单位）；改变样本范围后可生成第二份结果并比较。这是合成数据上的算法示例，不含交易费用或实盘成交模型。

快速入门与安装

从 Workspace 合成研究入门 开始：使用填写完整的股票横截面研究包，用 workspace execute 完成运行、独立验证和报告，再改变样本范围比较两次结果。该指南的准备步骤会创建一次性合成数据库，执行前须按所在环境的规则取得写库授权。

需要 Python 3.10 或更新版本。首次使用请取得 QuantWitness 完整公开源码，可下载 Code → Download ZIP，或在 PowerShell 执行：

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

源码、文档和 examples/ 使用同一 checkout。已有本单仓库源码时，先进入 research_pipeline/ 再安装；离线使用交付的完整公开源码目录。运行前记录 git rev-parse HEAD，离线目录记录交付清单中的源码提交号。

只安装框架可使用 python -m pip install quantwitness，之后运行 quantwitness --help；Python import 名仍为 research_pipeline。wheel 不包含示例，research_pipeline-source.zip 也不是完整示例包。分发范围见安装与发布构建。

使用自己的数据

先按 Catalog 与 PIT 准入 描述数据字段、物理表、可见日期和来源，通过现有的 catalog validate/compile 生成自己的持久 Catalog Lock。公开发行包不附带供应商或个人数据库的 Catalog，也不会猜测本机数据库路径；搜索、lint 和 admit 都复用显式 Lock 和只读数据源。

日频 Qlib 研究可以从模型与组合示例开始；自有冻结行情通过显式输入配置复用相同研究包主链。组合结果可用Qlib 研究报告生成离线净值、回撤、费用和成交诊断图表。

再按创建自己的研究填写研究问题、样本、指标、数据请求和算子图。package init 只创建四份中性声明草稿，补齐后才可依次 package lint → package admit → run → verify → report。AI 协作者按 AI 工作协议确认研究口径、选择已有能力并读取诊断。

范围限制

• 当前没有公共 Recipe；完整研究由项目声明，已有算法可复用，缺少的算法按项目扩展合同提供可信本地代码。扩展执行环境不是安全沙箱。
• 研究数据库始终只读。财报、成分、行业、ST、停牌、复权和市场规则必须按当时可见的日期对齐；盘中研究只使用已完成的 bar。
• 运行成功不等于研究结论可信，需要读取独立 VerificationResult 的状态；金融口径、准确性与验证边界见结果与独立验证。框架不是交易执行平台，不承诺策略盈利或实盘可交易。
• 能力适用范围以机器清单和分钟参考规则为准。发布验收与逐项晋级条件见安装与发布构建。planned 只能发现，local_only 不代表已通过独立发布验收；不承诺全历史、全品种覆盖。

能力状态

深入文档

• 框架合同：完整流程、数据与金融口径、校验职责、扩展与恢复边界。
• ResearchPackage：项目声明、输入和结果约定。
• Runtime 与恢复：节点诊断、中断恢复和跨运行复用。
• 资源预算：项目执行与独立复核的内存、临时空间和进程槽。
• 命令行与运维：具体参数和日常操作。
• 现行文档索引：按主题查阅其余文档。
• 架构边界、参与贡献、安全报告、第三方材料、许可证与随附声明。

Qlib 模型与研究图表

使用 pip install -e ".[ml]" 安装 Qlib 模型与 Plotly 图形依赖。日频回归采用 Qlib 六节点链，模型与处理器共同封存；见模型合同和模型文件交付。report --format html --request <请求文件> --output <报告.html> 和 package report 使用同一 Qlib 研究图形服务。HTML 展示模型诊断及验证状态，不提升原结果的验证范围；完整请求见 Qlib 报告。

公开Qlib 研究起点支持 development、model 和 portfolio。组合模式把 test 预测经固定规则转为目标，调用 finance.simulation.daily-cash@1.0.0 完成下一会话开盘成交、现金和费用账本、TCA 与独立金融复核。该节点按精确人工准入记录保持 local_only，不代表通用晋级或实盘交易能力。

归档输入与 RD-Agent

已提交的行情快照可通过 --input-snapshot-manifest 进入同一准入、运行和恢复流程；与数据库 来源互斥，当前 Catalog 与 PIT 规则仍适用。详见 封存输入。 RD-Agent 可选集成包位于 integrations/rdagent，使用独立环境调用 RP 正式主链；其请求引用 ResearchPackage，候选代码通过项目 bundle 执行，反馈引用 Result 与 VerificationResult。 多轮开发研究既可比较已有预测，也可实际执行研究包参数变体；每轮独立运行和验证，开发循环不打开最终 holdout。见研究循环。