QUANT RESEARCH REPLICATION · JUPYTER NOTEBOOKS
QuantsPlaybook：券商金工研报复现案例库的可验证中文读法
它不是能 pip install 的工具，而是一座把券商金工研报翻成 Notebook 的案例库。真正决定你能不能用它的，不是「有多少策略」，而是数据要什么权限、依赖装不装得上、结果为什么和研报对不上——本站只做这三件事的核验。
- QuantsPlaybook 58 个案例目录、65 个 Notebook、83 份研报 PDF（按固定 commit 逐文件实测）。
- 没有 pip 包、没有 release、没有 tag，也没有 LICENSE 文件。
- 22 套互斥依赖：仓库里 numpy 有 6 种 pin、pandas 有 9 种 pin。
- 9 种取数方式并存：官方 README 只写了 2 种。
QuantsPlaybook 项目来源
hugo2046/QuantsPlaybook · Jupyter Notebook 94.3% · 无 releases
约 6.3k Star / 1.5k Fork（采集 2026-09-29，数字会随社区变化）
查看源码 ↗
WHAT IT IS
是什么，不是什么？先分清这六件事
把「是什么」和「不是什么」并排写清楚，比任何一句宣传都省时间。下面左列是仓库里真实存在的，右列是本站核验后不支持的说法。
| 维度 | QuantsPlaybook 是（可核验） | 常见误解（本站不支持） | 你该怎么用 |
|---|---|---|---|
| 项目形态 | 以 .ipynb 为主的研报复现案例库，配 83 份研报/论文 PDF | 「一个量化框架」或「一套交易系统」 | 当成研究读物 + 参考实现，不要当成库来调用 |
| 安装方式 | 克隆仓库；22 个案例目录各带自己的 requirements.txt | 「pip install QuantsPlaybook」——PyPI 上没有这个包，仓库里也没有 setup.py/pyproject.toml | 一案例一虚拟环境，见环境页 |
| 版本管理 | 只有 commit 与分支（master / dev），0 tag、0 release | 「最新版 xx.x」——没有版本号可引 | 写论文/报告时引用 commit，本站固定在 1e4a2310 |
| 许可 | 仓库无 LICENSE 文件；3 个案例 README 写了「仅供学习/研究使用」 | 「开源免费随便用」——没有许可证就等于默认版权保留 | 商用或再分发前先读许可页 |
| 数据 | 依赖 JQData（聚宽）/ TuShare Pro，部分案例要自建数据库或作者的私有模块 | 「克隆下来就能跑出研报结论」——多数案例卡在数据权限那一步 | 先确认自己有哪个数据源，再挑案例 |
| 策略数量 | 实测 58 个案例目录；README 自己写 100+，同页分类表却只加到 49+ | 「100+ 策略全部可用」——数字对不上，也没有逐条可运行清单 | 以案例清单页的实测表为准 |
依据：固定 commit 1e4a2310 的完整文件树（2742 个条目）、README 原文、GitHub API 元数据，采集与核验日期 2026-09-29。本站是第三方撰写的中文研究笔记，不是官方文档。
CASE MAP
的 58 个案例分哪些方向？
仓库用四个大写字母前缀分方向，这是它最实用的一层结构，也是搜索引擎里最容易被抄错的一层数字。
| 方向（仓库目录） | 案例目录数 | Notebook 数 | 研报 PDF 数 | 这个方向主要解决什么 | 上手门槛 |
|---|---|---|---|---|---|
A-量化基本面 | 2 | 2 | 2 | 基本面价值选股（FFScore、大师系列现金流） | 中：需要财务与行情数据 |
B-因子构建类 | 25 | 25 | 31 | 因子构建、因子合成、因子检验、指数增强 | 高：多数依赖 Qlib 或自建数据库 |
C-择时类 | 29 | 36 | 46 | 指数/行业择时、信号构造、择时轮动 | 中：部分案例已做成纯离线快照 |
D-组合优化 | 2 | 2 | 4 | 组合权重优化（DE 进化算法、多任务时序动量） | 高：需自备组合数据 |
hugos_toolkit | — | 0 | 0 | 自研工具包：回测报告、回测模板、绘图样式 | 低：可直接读源码复用 |
SignalMaker | — | 0 | 0 | 自研信号工厂：HHT / NoiseArea / QRS / 鳄鱼线 | 低：README 给了可复制的 import 示例 |
| 数字来源 | 说法 | 本站核对结果 |
|---|---|---|
| README 首屏 | 「100+ 量化策略」出现 3 次 | 与同页分类表（25+ / 20+ / 2+ / 2+ = 49+）矛盾 |
| README 目录小节 | 「因子构建策略 (22+个策略)」 | 同一文档内第三种口径 |
| README 项目结构块 | 「B-因子构建类 (22+个) / C-择时类 (25+个)」 | 与实测 25 / 29 接近但不一致 |
| 本站在固定 commit 的实测 | 58 个案例目录 / 65 个 Notebook / 83 份 PDF | 可复现：按文件树逐条统计，脚本见研究档案 |
本站不转载 README 里的「策略表现概览」绩效表（年化 12.8%、夏普 0.85、胜率 58% 等）：那张表没有数据区间、没有股票池、没有成本口径、没有出处，无法核验，因此不作为本站任何结论的依据。
FOUR VERIFIED FINDINGS
能不能跑？QuantsPlaybook 实测的四条硬结论
这一页最值钱的部分不是介绍，而是下面这张表——它把「装得上/装不上/要什么」变成了可复现的实测结论。
| 结论 | 实测证据 | 对你的影响 | 下一步 |
|---|---|---|---|
| 依赖没被下架，但大量 pin 只有源码包 | 51 个 == pin 全部存在于 PyPI 且未被 yank；但约 40% 没有 wheel（alphalens==0.4.0、empyrical==0.5.5、ta_lib 全系、pyqlib==0.9.1/0.9.3 等） | Windows 上需要编译环境；只允许二进制包时多套依赖直接解析失败 | 环境页 |
| 老案例在 Python 3.11 上直接装不上 | 本机 dry-run：numba==0.56.4 报「only versions >=3.7,<3.11 are supported」；pyqlib==0.9.3 在 3.11 下不可见；numpy==1.22.3 无 wheel 并报 distutils.msvccompiler 缺失 | 不要用系统里最新的 Python 硬套老案例；一个案例一个虚拟环境 | 环境页 |
| 越新的案例越好装 | 2026 年新增的 SAE 择时、RRG 行业轮动用 >= 下界，在本机 3.11.9 上 dry-run 全部通过；最老案例钉死 2020–2021 版本 | 按「新案例先跑通、老案例按需降级」的顺序入门 | 环境页 |
| 数据权限是真正的门槛，不是代码 | 实测 9 种取数方式；6 个公开 issue 围绕 jqfactor 导入报错；4 个案例的数据只通过百度网盘分发 | 没有付费数据账号时，能跑的案例会明显变少 | 数据与凭据页 |
实测环境：Windows + Python 3.11.9 + pip install --dry-run（不做任何安装），2026-09-29。结论会随时间与依赖版本变化，本站记录的是当天可复现的结果。
HOW IT WORKS
怎么跑通一个案例？四步与前置条件
官方 README 的「快速开始」只给了三行 pip install；实际跑通一个案例要经过下面四步，且第二步和第三步最容易卡住。
仓库 pack 体积约 617 MB，文件树内文件合计约 1.36 GB，单文件峰值 95 MB（分钟级 parquet）。公开 issue #4 就是「无法下载项目」。建议浅克隆或只取需要的目录。
进入案例目录后按它自己的 requirements.txt 装依赖，并先看 Python 版本要求（老案例多数只支持到 3.10 甚至 3.8）。预期输出：python -c "import pandas, numpy; print('ok')" 无报错。
按该案例的写法配好 Token（.env 的 TS_TOKEN、config.json 的 ts_token、config.py 里的常量，或自建数据库连接串）。若案例依赖作者的私有 DataFeed 模块，则只能走它的开源回退分支或改用已离线化的案例。
用 Jupyter 从上到下执行，把股票池、样本区间、复权方式、调仓频率、手续费与滑点四项写进你的记录，否则你无法解释后续与研报的偏差。预期输出：净值曲线与绩效表，而不是一个可交易策略。
依据：仓库内 22 份 requirements.txt、各案例 README、SAE 案例的《使用指南》与 RRG 案例的离线说明。
SETUP AND ROUTE
两条路线怎么选？自建环境还是本机技能
这两条路线解决的不是同一个问题，所以不存在「谁替代谁」。下表按任务列清楚，先看你要的是哪一类结果。
| 你想要的结果 | 自己跑 QuantsPlaybook 案例 | 本机技能路线 | 怎么选 |
|---|---|---|---|
| 复现某份券商研报里的因子/择时方法 | 对口：案例目录里就是研报 + 代码 + 图表 | 不对口：技能里没有研报案例库 | 走自建环境 |
| 快速看一只票的行情、指标、估值 | 绕路：要先建环境再写代码 | 对口：akshare-finance / a-stock-analysis / a-share-metrics-card | 走本机技能 |
| 按条件筛一批股票 | 不对口：项目不做选股产品 | 对口：iwencai / mx-select-stock / tonghuashun-research-assistant | 走本机技能 |
| 系统做因子检验（IC/ICIR、分组回测） | 对口：案例里有 Qlib + alphalens 的分析流程 | 部分：quant-analyst 提供方法论与检查清单，不提供因子引擎 | 以自建环境为主 |
| 把结果画成图 | 自带绘图模块（VectorbtStylePlotting） | 对口：chart-image 直接出 PNG | 两边都能做 |
| Tushare 取 A 股数据 | 新案例用 TS_TOKEN | 对口：tushare-finance（220+ 接口） | 同一个 Token 两边通用 |
| 实盘下单 | 不支持 | 不支持（技能均明确不自动下单） | 都不适合 |
边界必须说清：QuantsPlaybook 不在本机技能目录中，与 EasyClaw 无已证实集成。上表是「任务分工」对照，不是集成声明，也不是替代关系。
LOCAL SKILL DEMO
本机技能路线实际能做什么？两张对话截图
如果你只是想先拿到行情和指标、还没准备买数据账号，下面这条路线能立刻出结果。两张图都是本机技能的实际对话截图，展示的是它们自己的任务，与 QuantsPlaybook 的复现流程无关。
上面两张图的图注已写明边界：它们只证明本机技能能回答这类问题，不构成任何集成或安装声明。逐任务对照与前置条件见对比页。
WHO FITS
谁适合用 QuantsPlaybook，谁应当先避开
这个项目的价值高度依赖你的前置条件。下表把「适合」与「不适合」都写成可判断的条件，而不是形容词。
| 你的情况 | 是否对口 | 原因 | 更适合看什么 |
|---|---|---|---|
| 手上已有 A 股行情/财务数据源（JQData、TuShare Pro 或自建库） | 对口 | 项目假设你自带数据，代码只负责加工与分析 | 环境页 → 案例清单 |
| 想学研报里的因子怎么从公式落到代码 | 对口 | 每个目录都有研报原文、公式与 Notebook | 因子案例册 |
| 想找现成的择时指标实现（RSRS/QRS/HHT/鳄鱼线） | 对口 | SignalMaker 提供四类信号的独立实现 | 择时案例册 → 工具包页 |
| 需要开箱即用的选股/盯盘产品 | 不对口 | 项目不做产品化封装，也没有命令行工具 | 对比页的本机技能路线 |
| 没有付费数据账号、也不想申请 | 部分对口 | 只有少数案例做了离线快照或自带数据，多数会卡在取数 | 数据与凭据页的降级方案 |
| 要把它接进生产系统或对外提供服务 | 不对口 | 无许可证、无版本、无测试、无发布流程 | 许可与再复用页 |
| 想直接拿回测收益去交易 | 不对口 | 官方与本站都不提供收益承诺；多数案例未计入交易成本 | 复现可信度页 |
最低启动条件
会 Python、能建虚拟环境、有至少一个 A 股数据源（哪怕只是 TuShare Pro 的基础积分），并且愿意为一个案例单独准备环境。三条缺一条就会卡住。
最有价值的使用方式
把某个案例当成「研报 → 公式 → 代码 → 图表」的样板来读，再用自己的数据与自己的口径重跑一遍，最后把偏差原因写下来。这一套流程比多跑十个案例更有用。
最容易踩的期待
以为克隆完就能复现研报结论。实际上数据区间、股票池、复权方式、成本口径任何一项不同，结论都可能反向——项目自己的两个 open issue 就是这类偏差。
LIMITATIONS
本站验证到哪一步，没验证什么？
把边界写清楚比多写一段赞美有用。下表是本站对 QuantsPlaybook 的验证状态。
| 项目 | 本站验证到哪一步 | 你应该怎么理解 | 注意点 |
|---|---|---|---|
| 仓库事实（目录、文件数、体积、贡献者、分支） | 已核验：按固定 commit 1e4a2310 的全量文件树逐条统计 | 可直接引用；本站所有数量类结论都出自同一份统计 | 仓库在持续更新，数字会变；本站已标注 commit |
| 依赖可安装性 | 本机实测：Windows + Python 3.11.9 执行 pip install --dry-run，逐套记录成功/失败与报错原文 | 可直接引用，且这是本站最独特的证据 | 只做解析不做安装；结果随依赖版本变化 |
| 各案例能否跑出结果 | 未运行：本站无 JQData / TuShare Pro 付费权限，不声称跑通过任何案例 | 相关说明均为源码级与文档级核验，不是本站运行输出 | 不要把本站示例当成「本站跑出来的结果」 |
| 回测收益、胜率、绩效数字 | 不作任何断言 | 本站不提供收益结论，也不转载 README 的绩效表 | 任何声称「复现出 xx% 收益」的说法都需要可核查的口径 |
| 与本机技能的集成状态 | unverified：QuantsPlaybook 不在本机技能目录中 | 本机技能路线是「另一条可选路线」，不是集成证据 | 全站按此口径披露 |
| 作者的付费社群内容 | 不涉及 | 本站只描述公开仓库里的事实，与作者的付费内容无关 | 本站不作任何推广 |
本站是第三方撰写的中文研究笔记，不是 QuantsPlaybook 官方文档；一切以实现、官方文档与官方许可为准。
FAQ
QuantsPlaybook 常见问题（回答都带证据边界）
QuantsPlaybook 是什么？一句话能不能说清？
一句话：它是把国内券商金工研报翻译成 Jupyter Notebook 的复现案例库——按「量化基本面 / 因子构建 / 择时 / 组合优化」四类组织，每个目录通常配有研报 PDF、公式与可运行的 Notebook。它不是量化框架，也不是交易系统，更不是可以 pip install 的包。以官方 README 与仓库实现为准，本站对所有数字都标注了核验 commit 与日期。
它到底有多少个策略？为什么说 100+ 不可信？
本站在固定 commit 1e4a2310 上逐文件统计的结果是：58 个案例目录、65 个 Notebook、83 份研报 PDF。README 首屏写「100+ 量化策略」（出现 3 次），但同一页的分类表是 25+ / 20+ / 2+ / 2+（合计 49+），目录小节又写「因子构建 22+」——三个口径互不一致，也没有逐条可运行清单。本站以实测目录数为准，并把这个矛盾如实写出来。
QuantsPlaybook 免费吗？能商用吗？
代码可以自由获取（仓库公开），但仓库没有任何 LICENSE 文件，GitHub 的 license 字段为空，只有 3 个案例 README 写了「本项目仅供学习和研究使用」这类使用范围声明。没有许可证意味着默认版权保留，商用与再分发的法律状态不明确。此外仓库内分发的是券商研报 PDF 原件，版权属于各券商。本站因此不提供打包下载、不镜像仓库、不转载研报。本文不构成法律意见，请以官方文件为准。
我可以在本机技能里安装 QuantsPlaybook 吗？
不能。QuantsPlaybook 是仓库形态的案例库，没有 pip 包、没有 Skill 定义，也不在本机技能目录中（目录清单与逐项核验见对比页），与 EasyClaw 无已证实集成。本机技能侧能覆盖的是取数、指标、选股、出图等具体任务（如 akshare-finance、tushare-finance、stock-technical-mastery、chart-image），两者是任务分工而非替代关系，详见对比页。
为什么我照着 README 找代码会找不到？
因为 README 与仓库实际内容存在多处不一致（本站逐条核对过）：40 个仓库内链接里有 2 个是错别字导致的 404；58 个案例目录中有 24 个 README 从未链接；因子构建类的 23 行表格里有 16 行指向聚宽社区帖子而不是仓库文件；还有 32 个案例的 Notebook 文件名与目录名不一致。建议直接用 QuantsPlaybook 案例清单页的实测表定位，或按目录名在仓库里搜索。
我的机器要装什么才能跑？
先看案例目录自己的 requirements.txt，再看它的 Python 版本要求。本站实测结论是：不要用最新的系统 Python 硬套老案例——numba==0.56.4 明确只支持到 Python 3.10、pyqlib==0.9.3 在 3.11 下不可见、numpy==1.22.3 在 3.11 上没有 wheel 且编译报 distutils.msvccompiler 缺失。建议一个案例一个虚拟环境，并优先从 2025 年后新增的案例（依赖用 >= 下界）开始。
它和直接看 GitHub README 相比，多了什么？
QuantsPlaybook 本站补的是官方资料没有的东西：按固定 commit 的逐文件实测统计；22 套依赖在本机 Python 3.11.9 上的解析实测与报错原文；9 种取数方式与 4 种 Token 写法的横向对照；README 与仓库不一致的逐条核对；以及把项目自带的「复现偏离评估」汇总成一页可读性更高的清单。官方资料里没有这些横向结论。