docs(factor): 因子库全景调查报告——因子调研session起步(C起步)——①本地盘点:sanguo_factor管线齐(注册表+alphalens评估+web API)但仅7个基础因子;vnpy自带Alpha101完整表达式(100个,零移植)+Alpha158(qlib同款)+46算子全覆盖;接入缺口=vwap派生列/AlphaLabSession 50股缓存上限/批量吞吐②聚宽250+因子全清单(官方文档直读):风险模型(Barra式10风格+21描述+16 PRO)+基本面136(质量70/基础41/成长10/每股15,等P2回灌)+量价104(随时可做);结论=值不买(试用拿不到近3月+2026-08起海外IP封),公式目录本地复刻;jqfactor_analyzer(MIT)可白嫖③行业:GTJA191公式全公开187/191可自算;QuantsPlaybook(5851★)研报复现入口;aurumq-rl(MIT)polars同构工程范本(296+11 A股私有因子族);Tushare 202因子公式全公开④四批路径:101+158现在→GTJA191+聚宽量价→聚宽财务(3周后)→Barra风格;行业中性=IC数据说话后再决策 [nas]

docs/factor_research/2026-08-20-factor-library-survey.md

@@ -0,0 +1,259 @@
+# 因子库全景调查报告
+
+> 调研日期：2026-08-20 ｜ 调研 session：因子调研
+> 目的：为因子研究选起点（用户已拍板「C 起步」——先建评估能力和因子库，目的后定）
+> 覆盖：本地已有家底 / 因子101 / 聚宽因子库 / 行业其他因子库
+
+---
+
+## 0. 结论速览
+
+| # | 发现 | 一句话 |
+|---|------|--------|
+| 1 | **vnpy 源码自带 Alpha101 + Alpha158 全套表达式** | 第一批零移植成本，直接挂载用我们的数据重验 |
+| 2 | 聚宽因子库 250+ 因子，**公式全公开但因子值要付费买** | 当「公式目录」用，本地 baostock 自算——不依赖它的 API |
+| 3 | 行业梯队：qlib Alpha360、GTJA Alpha191、Barra CNE6 风格因子 | 第三批之后的长线弹药 |
+| 4 | 我们的量价数据（1990+ 全A含退市）足以支撑所有价量类因子 | 数据不是瓶颈，评估管线才是 |
+
+**推荐路径**（详见 §5）：第一批 Alpha101 全量挂载重验 → 第二批聚宽公式本地化（质量/成长类，等 baostock 财务回灌完）→ 第三批 Barra 式风格因子（补 miniQMT 调研时定过的 CNE5 硬缺口）。
+
+---
+
+## 1. 本地家底盘点
+
+### 1.1 因子基础设施（sanguo_factor/，已建成）
+
+| 组件 | 文件 | 现状 |
+|------|------|------|
+| 因子注册表 | `sanguo_factor/registry.py` | ✅ 表达式注册/查询/分类 |
+| 表达式引擎 | vnpy.alpha AlphaDataset | ✅ 46 个算子（见 1.3） |
+| 内置因子库 | `sanguo_factor/library.py` | ⚠️ 仅 7 个基础因子（ma5/ma10/return_1d 等占位水平） |
+| 评估管线 | `sanguo_factor/analyzer.py` | ✅ alphalens：IC/ICIR/t统计 + tears HTML 报告 |
+| 数据适配 | `sanguo_factor/data_adapter.py` | ✅ BarData→polars，接 dbbardata 日线 |
+| Web API | `sanguo_api/routes.py` | ✅ POST /factor/analyze、GET /factor/list、任务报告页 |
+| 测试 | `tests/factor/` | ✅ 5 个测试文件 |
+
+### 1.2 vnpy 自带数据集（关键发现，`vnpy_v4.4.0/vnpy/alpha/dataset/datasets/`）
+
+| 数据集 | 文件 | 内容 | 对我们的意义 |
+|--------|------|------|-------------|
+| **Alpha101** | `alpha_101.py`（330行） | WorldQuant 论文原版 100 个因子，全部表达式实现 | 第一批直接挂载，无需移植 |
+| **Alpha158** | `alpha_158.py` | qlib 风格特征集：39 个基础定义 × 多窗口(3/5/10/20/30/60)展开 ≈158 个 | 白送第二套；标签已定义为「未来3日收益」，适合 ML 特征 |
+
+### 1.3 算子能力（46 个）
+
+- **时序 ts_（23个）**：delay/delta/mean/std/sum/min/max/argmax/argmin/rank/quantile/corr/cov/decay_linear/slope/rsquare/resi/product/abs/log/greater/less
+- **横截面 cs_（5个）**：rank/mean/std/sum/scale
+- **数学（9个）**：abs/log/greater/less/pow1/pow2/sign/quesval/quesval2
+- **技术指标（2个）**：ta_atr/ta_rsi
+
+Alpha101 论文所需算子全覆盖（含三元表达式 quesval/quesval2 对应论文的 if-else 结构）。
+
+### 1.4 数据就绪度
+
+| 数据 | 状态 | 支撑哪类因子 |
+|------|------|-------------|
+| 全A日线 1990+（含退市股） | ✅ 就绪 | Alpha101/158、聚宽情绪/动量/技术/风险类 |
+| 15分钟线（5.5年） | ✅ 就绪 | 未来日内因子 |
+| 财务季频（profit/dupont） | 🔄 P2 回灌中（~3周跑完 2015Q1+） | 聚宽质量/成长/每股类 |
+| 业绩预告/快报（带公告日） | ✅ 8-20 刚交付 | 事件驱动因子（聚宽没有的差异化点） |
+| 估值 pe/pb（parquet） | ✅ 就绪 | 价值类、Barra btop |
+| 行业分类 | ⚠️ 已知缺口（用户已决策接受） | 行业中性化受限（见 §2.4 注意） |
+
+### 1.5 接入缺口（第一批落地前要补的）
+
+1. **vwap 派生列**：Alpha101 用 vwap 59 次，dbbardata 无此列 → data_adapter 补 `vwap = turnover / volume`（注意 volume=0 除零，停牌日置 null）
+2. **股票池宽度**：AlphaLabSession 缓存上限 50 只股票——横截面因子（cs_rank）做全市场 IC 评估时不够，需扩到全A或按需分批
+3. **批量评估吞吐**：101 因子 × 全A × 多年的 tears 生成是重活，需要批处理模式（只出 IC 汇总表、tears 按需生成）
+
+---
+
+## 2. 因子101（WorldQuant 101 Formulaic Alphas）
+
+### 2.1 基本信息
+
+- 来源：WorldQuant 2015 年论文《101 Formulaic Alphas》（Kakushadze），量化界最著名的公开因子集
+- 全部为**短周期量价因子**，只依赖 open/high/low/close/volume/vwap/returns（个别含 cap、行业中性）
+- vnpy 自带实现 100 个表达式（论文 101 个中含 1 个工业界普遍不实现/合并的）
+
+### 2.2 结构画像（从 `alpha_101.py` 源码统计）
+
+| 结构要素 | 出现次数 | 含义 |
+|---------|---------|------|
+| cs_rank（横截面排名） | 165 | 几乎每个因子都先「跟全市场比」——WorldQuant 风格灵魂 |
+| ts_corr（时序相关性） | 70 | 最大单一结构：量价相关性反转逻辑 |
+| vwap | 59 | 成交均价偏离类信号 |
+| ts_rank（时序分位） | 62 | 自身历史位置 |
+| ts_mean / ts_delta / ts_rank / ts_decay_linear | 53/48/62/40 | 均值回复、动量、平滑 |
+| 窗口分布 | 5天(54) > 20天(38) > 10天(31) | 典型短周期（周频~月频） |
+
+### 2.3 逻辑分类（按主导结构，约数）
+
+| 类别 | 代表结构 | 大致占比 |
+|------|---------|---------|
+| 量价相关性 | `ts_corr(rank(价), rank(量), N) * -1` | ~1/3（最大群） |
+| 反转类 | `-rank(ts_delta(close,N))` 变体 | ~1/4 |
+| 波动率/振幅位置 | `ts_std`、`(close-open)/(high-low)` 类 | ~1/6 |
+| 成交量异动 | `volume vs ts_mean(volume,N)`、量变动量 | ~1/8 |
+| 日内K线位置 | open/close 相对 high/low 位置、隔夜跳空 | ~1/10 |
+| 复合嵌套 | 多算子深嵌套（如 alpha#1） | 其余 |
+
+### 2.4 A股使用注意事项
+
+1. **效力需重验**：论文为 2015 年美股短周期设计，A股 2018-2025 表现必须用数据说话，不能假设成立
+2. **横截面宽度**：cs_rank 需要宽股票池才有意义（建议全A剔除ST/新股后 ~4500+ 只）
+3. **行业中性**：论文少数因子用 IndNeutralize，vnpy 实现未含行业算子——我们行业数据是已知缺口，第一批先做「不中性化」版本，效果若被行业结构污染再决策补行业数据
+4. **同质化**：101 个因子很多互相相关性 >0.8，评估后需聚类去重，实际独立信息可能只有 20~40 个维度
+5. **vwap 口径**：A股 vwap=成交额/成交量，注意停牌日、一字板极端值
+
+---
+
+## 3. 聚宽因子库（JoinQuant）
+
+### 3.1 总体定位
+
+- 聚宽官方**预计算因子数据库**，官方口径「数百个」，文档直读合计 **250+ 个**（另有 alpha101/alpha191 系列 292 个）
+- 天频（每天 05:00 更新前一交易日），仅覆盖股票，基于**后复权**价格
+- 财务类因子口径：**对应日期能获取到的最新一期单季度数据 + TTM**（防前视口径与我们 pubDate 过滤思路一致）
+
+### 3.2 因子分类全景（250+ 个）
+
+**板块A：风险模型因子（Barra 式）**
+
+| 类目 | 数量 | 代表因子 |
+|------|------|---------|
+| 风格因子（已加工的因子暴露） | 10 | size/beta/momentum/residual_volatility/non_linear_size/book_to_price_ratio/liquidity/earnings_yield/growth/leverage（即 CNE5 十大风格） |
+| 描述因子（原始值，风格因子的原料） | 21 | raw_beta/daily_standard_deviation/share_turnover_monthly/earnings_growth/debt_to_assets 等 |
+| 风格因子PRO（CNE6 升级版） | 16 | btop/divyild/earnqlty/earnvar/earnyild/financial_leverage/invsqlty/liquidty/long_growth/ltrevrsl/market_beta/market_size/midcap/profit/relative_momentum/resvol |
+| 行业因子（哑变量） | 三套体系 | 证监会/聚宽一二级/申万一二三级 |
+
+**板块B：基本面及量价因子**
+
+| 类目 | 数量 | 数据依赖 | 我们能否本地自算 |
+|------|------|---------|----------------|
+| 质量 quality | 70 | 财务三表 | 🔄 可（吃 baostock profit/dupont，等 P2 回灌完） |
+| 基础 basics | 41 | 财务三表 | 🔄 同上 |
+| 成长 growth | 10 | 财务 | 🔄 同上（含 PEG） |
+| 每股 per_share | 15 | 财务+股本 | 🔄 同上 |
+| 情绪 sentiment | 38 | 量价 | ✅ 可（dbbardata 现成：VROC/VR/VOL/DAVOL/ARBR/WVAD/PSY/ATR/VMACD 等） |
+| 风险 risk | 12 | 量价 | ✅ 可（Variance/Skewness/Kurtosis/Sharpe 各周期） |
+| 技术 technical | 16 | 量价 | ✅ 可（BOLL/EMA/MACD/MFI 等） |
+| 动量 momentum | 38 | 量价 | ✅ 可（BIAS/CCI/ROC/RSI系/TRIX/52周分位/AROON 等） |
+
+**板块C：Alpha 系列**：alpha101（WorldQuant）+ alpha191（国泰君安，聚宽对原论文缺失/不合理公式做了调整，数据字典逐因子说明）
+
+### 3.3 获取方式与成本（关键约束）
+
+| 途径 | 要求 | 限制 |
+|------|------|------|
+| 聚宽研究平台（云端） | 聚宽账号 | jqfactor 内置模块，平台内使用 |
+| 本地 jqdatasdk | JQData 账号 | **试用**：100万条/天，但**拿不到最近3个月数据**（实盘滚动场景不可用）；**付费**：2亿条/天，价格商务谈 |
+| IP 限制 | — | **2026-08-01 起仅大陆 IP**（我们 VPS 可，海外出口不可） |
+
+### 3.4 开源情况
+
+| 项目 | 性质 | 结论 |
+|------|------|------|
+| jqfactor_analyzer（622★，MIT/Apache） | **因子分析工具**（IC/分位收益/换手/归因，中文版 alphalens + Barra 归因） | ✅ 可白嫖，**分析自有因子无需登录**；它的 AttributionAnalysis 归因框架对我们有参考价值 |
+| jqdatasdk（896★） | 数据 SDK 壳 | 仅壳开源（README），核心逻辑闭源在 PyPI wheel 里 |
+| jqfactor 因子库本体 | — | **不开源** |
+
+### 3.5 对我们的结论
+
+- ❌ **不买因子值**：试用号拿不到近3个月数据实盘不可用；付费价格不透明且引入外部依赖
+- ✅ **公式目录价值大**：官方 factor_values 文档把 250+ 因子的计算方法写全了（本报告 3.2 即摘自官方文档原文），质量/成长/每股类可逐个用 baostock 数据复刻
+- ✅ **jqfactor_analyzer 可选装**：作为 alphalens 的补充（尤其 Barra 式归因），本地分析自有因子零成本
+- 📌 优先级建议：量价类 104 个（情绪38+风险12+技术16+动量38）与财务就绪度无关**随时可做**；财务类 136 个等 P2 回灌完（约3周）自然解锁——和第一批 Alpha101 时间线刚好错开
+
+---
+
+## 4. 行业其他因子库全景
+
+### 4.1 经典论文/研报因子集（定义全公开，可本地自算）
+
+| 因子集 | 数量 | 来源 | 定义公开度 | 数据依赖 | 我们可自算 |
+|--------|------|------|-----------|---------|-----------|
+| **Qlib Alpha158** | 158（9 K线形态+4价格+29算子×5窗口） | 微软 qlib（MIT，47.8k★） | ✅ 源码即公式 | OHLCV+VWAP | ✅（vnpy 已自带同款） |
+| **Qlib Alpha360** | 360（60日×6字段归一） | 同上 | ✅ | OHLCV+VWAP | ✅（端到端 ML 用） |
+| **GTJA Alpha191** | 191 短周期量价 | 国泰君安 2017 研报 | ✅ 公式 100% 公开（BigQuant wiki 全 191 条） | OHLCV+VWAP+amount；4个需基准指数 | ✅ 187/191（指数双源后=全部可） |
+| **Barra CNE5** | 10 风格 + 21 描述变量 | MSCI 2012 | 方法论公开到描述变量公式级（权重不公开） | 量价+财务+股本/市值+行业 | 🔄 部分（行业缺口） |
+| **Barra CNE6** | 9 一级 + 20 二级 + 46~48 三级 | MSCI 2018-12（新增 Quality 大类；非线性市值并入 Size） | 同上 | 上述 + **分析师一致预期**（我们无） | 🔄 部分（预期是硬缺口） |
+
+注：Alpha101 开源实现现状——star 最多的 yli188（852★）只覆盖 83/101 且无许可证停更；**vnpy 自带的 polars 表达式版 100 个是覆盖度/工程性最好的实现之一**，无需外求。
+
+### 4.2 值得特别关注的两个开源仓库
+
+| 仓库 | star | 为什么值得关注 |
+|------|------|---------------|
+| **hugo2046/QuantsPlaybook** | 5,851 | **券商研报复现大全**：100+ 策略，因子构建 20+（东方系列、方正量价系、筹码分布、买卖压力等），每文件夹带原研报 PDF+复现代码。A股票研报因子落地代码的第一入口 |
+| **yupoet/aurumq-rl** | 39（小众但 2026 仍活跃，MIT） | **工程化最深的当代实现**：polars 原生 105 Alpha101 + 191 GTJA191 + 11 个 A股私有因子族（筹码/龙虎榜/涨停/游资/北向等）；1,386 测试通过，每因子一页文档，T+1/涨跌停/ST/申万行业都有工程封装。与我们「polars 表达式引擎」路线同构，是最好的移植参考 |
+
+其他：DolphinDB 版 101+191（Apache-2.0，唯一带性能 benchmark）、panda_factor（2,792★，⚠️AGPL 传染性注意）、RD-Agent（微软 14k★，因子自动挖掘方向，非现成因子表）。
+
+### 4.3 券商研报因子体系（PDF，非代码，但因子定义大多完整公开）
+
+| 券商 | 规模 | 代表性因子工作 |
+|------|------|---------------|
+| 华泰金工（林晓明团队） | 人工智能系列 100 篇 | AlphaNet 端到端因子挖掘（30日×6量价→神经网络）、遗传规划挖因子、2025 年 LLM 生成高频因子 300 个 |
+| 东方证券金工 | 因子选股系列 100+ 篇 | 分析师 alpha 子库、DFQ 遗传规划挖掘系统、基本面因子重构 |
+| 方正证券金工 | 多因子系列 23+ 篇 | 文学命名量价因子（聪明钱/球队硬币/花隐林间/适度冒险等），**官网月度发布因子绩效跟踪**（多空收益公开可对标） |
+
+获取入口：QuantsPlaybook（复现代码）+ quant-wiki/慧博/发现报告（PDF）。
+
+### 4.4 商业平台因子库（公式部分公开，值收费——只当公式参考）
+
+| 平台 | 规模 | 公式公开度 | 值获取 |
+|------|------|-----------|--------|
+| Tushare | 自研 202 因子/9 类（Alpha101量价31/Growth15/Liquidity35/Momentum20/Quality59/Risk25/Value11/Size3/Reversal3）+ 技术面套 | ✅ **factor_list() 全公开算法逻辑** | 全库 2000 元/年 |
+| BigQuant | cn_stock_prefactors 官方口径「上千个」 | 部分（wiki 挂 Alpha191 全公式） | 免费注册云端用，导出受限 |
+| 米筐 RQData | 财务衍生+Alpha101+技术指标 | 部分 | 商业订阅 |
+| AkShare | 无因子接口（1000+ 原始数据接口） | — | 免费开源（当原料用） |
+
+### 4.5 数据依赖映射（本地数据层 × 因子库覆盖）
+
+| 本地数据 | 状态 | 能解锁的因子 |
+|---------|------|-------------|
+| dbbardata OHLCV+成交额（→vwap 可派生） | ✅ | Alpha101（83+非中性化子集）/Alpha158/Alpha360/GTJA191（187/191）/聚宽量价 104/Tushare 量价类 |
+| 指数双源（P0 刚加固） | ✅ | GTJA191 剩余 4 个、Tushare Risk 类 beta/alpha |
+| bs_fundamentals 季频（pubDate 对齐） | 🔄 回灌中 | Barra Growth/Quality/Leverage/EY 描述变量、聚宽财务 136、Tushare Quality/Growth/Value（~85 个） |
+| valuation（PE/PB） | ✅ | Size/BTOP、价值类 |
+| 行业分类 | ⚠️ 缺口（已决策接受） | IndNeutralize 类 Alpha101 子集、Barra 行业因子受限 |
+| 分析师一致预期 | ❌ 无源 | CNE6 情绪类、华泰一致预期因子（开源无替代，长期缺口） |
+| 分钟线/tick | 🔄 NAS 5m 在建；tick 无 | 方正/华泰高频因子（长线） |
+| 龙虎榜/北向/筹码 | ❌ 未接 | aurumq-rl 私有因子族（数据源另接，akshare 部分可取） |
+
+---
+
+## 5. 总对比与路径建议
+
+### 5.1 全景对比（按我们「本地自算」可行性排序）
+
+| 批次 | 因子库 | 数量 | 就绪条件 | 成本 |
+|------|--------|------|---------|------|
+| **第一批（现在）** | vnpy 自带 Alpha101 + Alpha158 | 100+158 | 补 vwap 派生列 + 扩股票池缓存 | 接管道，零移植 |
+| **第二批（第一批后）** | GTJA Alpha191（公式移植）+ 聚宽量价类精选 | 191+~50 | 同上；指数已就绪 | 公式→表达式移植（有 MIT 参考实现可抄） |
+| **第三批（~3周后财务回灌完）** | 聚宽质量/成长/每股类 + Tushare 公式参考 | ~136 | P2 回灌完 | 逐因子实现财务计算 |
+| **第四批（长线）** | Barra 风格因子（CNE5 十大类） | 10 风格+21 描述 | 财务+股本就绪；行业中性先绕开 | 合成逻辑复杂，选做 |
+| **长线参考** | 券商研报因子（QuantsPlaybook 入口）/AlphaNet 挖掘范式 | 数百 | 按需 | 按需 |
+
+### 5.2 核心判断
+
+1. **量价因子我们已是「数据富矿」**：全A 1990+ 含退市股 + 指数双源 + polars 引擎，第一、二批共 ~350 个量价因子的原料全部就绪
+2. **财务因子时间线自然错开**：P2 回灌 3 周 ↔ 第一二批执行期，回灌完财务类自然解锁
+3. **行业中性是持久约束**：第一批先做不中性化版本；如果 IC 结果显示行业结构污染严重，再回头决策是否补行业数据（申万一级，akshare 可拉）——把它当「数据驱动的决策」而不是现在拍
+4. **两个外部仓库值得收藏**：QuantsPlaybook（研报因子复现入口）、aurumq-rl（polars 因子工程范本，与我们技术路线同构）
+5. **不建议的路线**：买 Tushare/聚宽因子值（引入外部依赖+实盘滚动不可用）、上 panda_factor（AGPL 传染）、现在就做 CNE6（预期数据无源）
+
+---
+
+## 附：本报告调研来源
+
+- 本地：`vnpy_v4.4.0/vnpy/alpha/`（源码实证）、`sanguo_factor/`（模块实证）
+- 聚宽：官方文档 https://www.joinquant.com/help/api/help?name=factor_values（因子清单主文档，直读全文）；jqdatasdk/jqfactor_analyzer GitHub + PyPI 元数据
+- qlib：https://github.com/microsoft/qlib（源码 `qlib/contrib/data/loader.py` 实读）
+- Alpha101 开源实现：https://github.com/yli188/WorldQuant_alpha101_code 等（GitHub API 实抓元数据）
+- GTJA191：https://github.com/wpwpwpwpwpwpwpwpwp/Alpha-101-GTJA-191 ；公式总表 https://bigquant.com/wiki/doc/Pyf0TYya6H
+- Barra：https://github.com/ShiliangZhang-nku/Barra_CNE6 ；https://zhiqiang.org/finance/barra-cne5s-methodology.html
+- 券商研报：https://github.com/hugo2046/QuantsPlaybook ；https://quant-wiki.com ；慧博/发现报告
+- 平台：https://tushare.pro/document/2?doc_id=486 ；https://bigquant.com/data/datasources/cn_stock_prefactors ；https://akshare.akfamily.xyz
+- aurumq-rl：https://github.com/yupoet/aurumq-rl（polars 296+11 因子族，工程范本）