Skip to content

mindcarver/quant-research-os

BranchesTags

Repository files navigation

🧭 QROS

量化研究治理操作系统

把研究想法推进成 可审查、可复现、可追溯 的 research lineage。

hosts runtime workflow tests

🚀 Quick Start · 🏗 Design · 🪜 Pipeline · 🗺 Repo Map · 🛡 Review · Docs

Important

一句话定位 QROS 不替你发明 alpha，也不替某条研究线保存策略代码；它负责把研究过程里的 freeze、review、formal artifacts、failure routing 和 provenance 固定下来。


⚡ 为什么需要

Agent 已经能写代码、跑回测、生成报告。但量化研究的核心风险不在执行，在治理：

阶段门禁每个阶段的输入、输出、冻结和审查都有 formal contract，不能跳过
独立审查写代码的 author 不能当自己的 reviewer，adversarial reviewer 必须独立
产物真值空目录、placeholder 文件和合同说明文档不算阶段完成
失败处置review 失败不是 debug，有专门的 failure routing、rollback 和 child lineage 路径

Note

QROS 是 框架仓，不是策略实现仓。真实研究程序和正式研究产物应写在 active research repo 的 outputs/<lineage_id>/ 下。


🏗 项目设计原理

QROS 的核心设计不是“多写几份报告”，而是把量化研究中最容易漂移的判断点，拆成可冻结、可复建、可审查的机器合同。

Contract-first先定义 stage gate、freeze group、artifact expectation 和 review checklist，再让 agent 写代码或产物。合同在 `contracts/`，文档只负责解释。
Disk is truth阶段状态以 active research repo 的 `outputs//` 磁盘产物为准，不以聊天记录、口头承诺或空目录为准。
Freeze before build每个阶段先冻结本阶段会消费和产生的研究假设、数据范围、参数身份、执行边界，再物化 formal artifacts。
Review before advanceauthor lane 只能产出；review lane 独立检查 artifact、provenance、stage program 和 closure，PASS 前不能进入下一阶段。
Failure is a routereview 非正常放行不是继续普通推进，而是进入 failure handling，明确 retry、rollback、NO-GO 或 child lineage。
Lineage-local execution真实阶段程序属于研究仓的 `outputs//program/`，每个可执行阶段必须有 `stage_program.yaml`、entrypoint、README 和 `program_execution_manifest.json`；QROS 只校验、调用和记账，不把共享 builder 当完成路径。
Host/runtime splitCodex / Claude Code 负责理解、对话和工具调度；QROS Python runtime 负责确定性状态机、合同校验、review / next-stage orchestration 和状态面板。

更细的运行机制看 QROS 工作原理，文档入口看 docs/README.md。


🚀 Quick Start

🧩 安装

Codex — 在 Codex 里输入：

Fetch and follow instructions from
https://raw.githubusercontent.com/
runmyself/quant-research-os/refs/heads/
main/.codex/INSTALL.md

重启 Codex，然后开始研究。

Claude Code — 直接告诉 Claude Code：

请阅读并按照 https://raw.githubusercontent.com/
runmyself/quant-research-os/refs/heads/
main/.claude/INSTALL.md 的指示安装 QROS

🧪 5 分钟开始一条研究线

$qros-research-session 帮我研究这个想法：BTC 领动高流动性 ALT，横截面研究

# 查看进度（只读）
$qros-progress

# 查看因子质量
$qros-factor-diagnostics 看下当前 lineage 的因子诊断
$qros-factor-diagnostics 看下 csf_test_evidence 阶段的 Rank IC、分层和稳定性
$qros-factor-diagnostics 看下 csf_backtest_ready 阶段的成本后收益和换手
$qros-factor-diagnostics 看下 csf_holdout_validation 阶段有没有样本外退化

# 查看信号质量
$qros-signal-diagnostics 看下当前 TSS lineage 的信号诊断
$qros-signal-diagnostics 看下 tss_backtest_ready 阶段的成本后收益、回撤和换手
$qros-signal-diagnostics 看下 tss_holdout_validation 阶段有没有样本外退化

# 更新版本
$qros-update

qros-update 是 Codex 和 Claude Code 的统一更新入口。用户只需要在 active research repo 根目录输入 qros-update；它会自动识别当前 host，刷新全局 QROS 安装，并重建当前 repo 的 ./.qros/ runtime。

默认路径会更新到最新稳定版本；如果你是框架开发者并且需要跟踪未发布主干，使用 qros-update main。

📄 paper-to-spec data-spec-first

$qros-paper-to-spec 把论文/PDF 先整理成 crypto perpetual 研究所需的 staged specs，而不是直接生成策略代码或回测代码。旧 strategy_spec materializer 和 baseline scaffold 已移除。

当前链路采用 data-spec-first：

paper_data_spec -> paper_signal_spec -> paper_train_freeze_spec -> paper_test_evidence_spec -> paper_backtest_spec -> paper_backtest_implementation_spec

每一段都有 machine-readable contract 和 deterministic validator；如果论文信息不足，agent 应停止并问研究员。真实回测实现仍然发生在 active research repo，不写回 QROS framework repo。

完整说明见 docs/guides/qros-paper-to-spec-usage.md。


🪜 主流程

qros-research-session 是统一入口，推进到 route-specific holdout_validation review closure 和最终 next-stage confirmation 为止。

mandate_admission -> mandate_freeze_confirmation_pending -> 01_mandate -> route selection
  ├─ time_series_signal
  │    -> 02_tss_data_ready
  │    -> 03_tss_signal_ready
  │    -> 04_tss_train_freeze
  │    -> 05_tss_test_evidence
  │    -> 06_tss_backtest_ready
  │    -> 07_tss_holdout_validation
  └─ cross_sectional_factor
       -> 02_csf_data_ready
       -> 03_csf_signal_ready
       -> 04_csf_train_freeze
       -> 05_csf_test_evidence
       -> 06_csf_backtest_ready
       -> 07_csf_holdout_validation
                                        -> review_complete

🗺 仓库地图

                    contracts/  ← machine-readable truth
                         │
           ┌─────────────┼─────────────┐
           ▼             ▼             ▼
      runtime/       skills/      templates/
   (bin/scripts/    (author/review   (SKILL.md
    tools/hooks)    failure/core)    generator)
           │             │
           ▼             ▼
     tests/          docs/
   (1191 tests)   (SOP/guides/visuals)

contracts/机器真值层 — gate 定义、checklist、artifact schema
skills/Agent 行为层 — 55 个 public skill bundles，覆盖 core、author、review、failure 和 diagnostics
runtime/运行时层 — bin 入口 + scripts wrapper + tools 引擎
templates/生成模板层 — host-agnostic review skill 模板
docs/解释层 — 安装、SOP、使用指南
tests/验证层 — 当前 `python -m pytest --collect-only -q` 收集 1191 条 pytest tests，覆盖全流程


🛡 Review 规则

🧑‍⚖️ 独立审查 📏 Formal Gate 🚨 失败处置
每个 review 阶段要求
独立 adversarial reviewer
author 不能自审		 reviewer 检查 artifact、
provenance 和 stage program
源码，不是走形式		 FIX_REQUIRED 退回 author
NO-GO / CHILD LINEAGE
走 failure routing

🖥 支持的宿主

当前 README 校验环境：

宿主 当前版本
Codex CLI codex-cli 0.134.0
Claude Code 2.1.152 (Claude Code)
Codex Claude Code

完整支持，当前主路径

# 安装
Fetch INSTALL.md

# review 子代理
spawn_agent (fork_context=false)

# skills 路径
~/.codex/skills/qros-*/

完整支持，通过 plugin

# 安装
/plugin install qros@quant-research-os

# review 子代理
.claude-plugin/agents/qros-reviewer.md

# skills 路径
.claude-plugin/skills/qros-*/

✅ 质量体系

🧪 测试 🧭 Anti-Drift 🔎 Verification
1191 条 pytest collected tests
bootstrap + contracts + runtime
session + review + skills
docs + anti_drift + pipeline		 CI 自动回归检测
metamorphic testing
snapshot baseline
drift coverage matrix		 smoke / full-smoke 分层
contract validation
semantic validation
upstream binding check

📚 常用文档

想了解 去哪里
🧭 文档导航 docs/README.md
🛠 安装说明 docs/guides/installation.md
🚀 Quick Start docs/guides/quickstart-codex.md
🧪 统一研究会话说明 docs/guides/qros-research-session-usage.md
🛡 Review 约束地图 docs/guides/qros-review-constraint-map.md
📈 CSF 因子诊断 docs/guides/qros-factor-diagnostics.md
📉 TSS 信号诊断 docs/guides/qros-signal-diagnostics.md
🧷 阶段冻结字段说明 docs/guides/stage-freeze-group-field-guide.md
📝 Release Notes RELEASE_NOTES.md

🧭 QROS · 治理框架 · 19 stage-program keys · 双宿主 · 1191 测试 · contract-first

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages