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 和只读数据源。

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

范围限制

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

能力状态

深入文档

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