--- name: a-stock-quant-lab description: |- A 股量化实验室：基于 zvt 框架的数据采集 + 因子研究 + 回测执行一站式。覆盖 31 个场景——机构持仓、财报、指数成分、MACD/MA/量能择时。仅限中国 A 股。 license: MIT-0 compatibility: Python 3.12+, uv package manager. Network access to eastmoney / joinquant / baostock / akshare for data fetch. metadata: version: "v6.1" blueprint_id: "finance-bp-009" compiled_at: "2026-04-20T07:34:47.524525+00:00" capability_markets: "cn-astock" capability_activities: "data-sourcing, backtesting, factor-research" sop_version: "crystal-compilation-v6.1" openclaw: emoji: "📈" skillKey: a-stock-quant-lab category: finance primaryEnv: python requires: bins: ["python3", "uv"] --- # A 股量化实验室 (a-stock-quant-lab) > 说出"跟机构持仓"或"MACD 回测"——我基于 zvt 直接写代码跑起来，不用你翻文档。美股数据质量一般，不推荐。 ## Pipeline `data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization` ## Top Use Cases (31 total) ### Actor Data Recorder (`UC-101`) Collects institutional investor holdings and top 10 free float shareholders on a weekly schedule for tracking major player positions **Triggers**: institutional investor, top holders, actor data ### Financial Statement Recorder (`UC-102`) Collects fundamental financial data including balance sheets, income statements, and cash flow statements from eastmoney on a weekly basis **Triggers**: financial statements, balance sheet, income statement ### Index Data Recorder (`UC-103`) Collects index metadata, index compositions (SZ1000, SZ2000, growth, value indices), and daily index price data **Triggers**: index data, index composition, SZ1000 For all **31** use cases, see [references/USE_CASES.md](references/USE_CASES.md). **Execute trigger**: `When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)` ## What I'll Ask You - Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin) - Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)? - Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor? - Time range: start_timestamp and end_timestamp for backtest period - Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)? ## Semantic Locks (Fatal) | ID | Rule | On Violation | |---|---|---| | `SL-01` | Execute sell orders before buy orders in every trading cycle | halt | | `SL-02` | Trading signals MUST use next-bar execution (no look-ahead) | halt | | `SL-03` | Entity IDs MUST follow format entity_type_exchange_code | halt | | `SL-04` | DataFrame index MUST be MultiIndex (entity_id, timestamp) | halt | | `SL-05` | TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount | halt | | `SL-06` | filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION | halt | | `SL-07` | Transformer MUST run BEFORE Accumulator in factor pipeline | halt | | `SL-08` | MACD parameters locked: fast=12, slow=26, signal=9 | halt | Full lock definitions: [references/LOCKS.md](references/LOCKS.md) ## Top Anti-Patterns (47 total) - **`AP-ZVT-183`**: 除权因子为 inf/NaN 时直接参与乘法导致复权静默失败 - **`AP-ZVT-179`**: 第三方数据接口超限后异常被吞噬，数据静默缺失 - **`AP-ZVT-200`**: Token 失效后数据查询返回空 DataFrame 而非报错 All 47 anti-patterns: [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) ## Evidence Quality Notice > [QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-009. Evidence verify ratio = 55.0% and audit fail total = 36. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl). ## Reference Files | File | Contents | When to Load | |---|---|---| | [references/seed.yaml](references/seed.yaml) | V6+ 全量权威 (source-of-truth) | 有行为/决策争议时必读 | | [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) | 47 条跨项目反模式 | 开始实现前 | | [references/WISDOM.md](references/WISDOM.md) | 跨项目精华借鉴 | 架构决策时 | | [references/CONSTRAINTS.md](references/CONSTRAINTS.md) | domain + fatal 约束 | 规则冲突时 | | [references/USE_CASES.md](references/USE_CASES.md) | 全量 KUC-* 业务场景 | 需要完整示例时 | | [references/LOCKS.md](references/LOCKS.md) | SL-* + preconditions + hints | 生成回测/交易代码前 | | [references/COMPONENTS.md](references/COMPONENTS.md) | AST 组件地图（按 module 拆分）| 查 API 时 | --- *Compiled by Doramagic crystal-compilation-v6.1 from `finance-bp-009` blueprint at 2026-04-20T07:34:47.524525+00:00.* *See [human_summary.md](human_summary.md) for non-technical overview.* FILE:human_summary.md # Human Summary > I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.) ## What I Can Do - **tagline**: I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.) - **use_cases**: ['Index Data Recorder', 'Financial Statement Recorder', 'Actor Data Recorder', 'A-share MACD daily golden-cross backtest with hfq price adjustment from eastmoney', 'End-to-end ZVT pipeline: FinanceRecorder + GoodCompanyFactor + StockTrader', 'Multi-factor strategy with TargetSelector (AND mode) combining MACD + volume breakout', 'Index composition data collection (SZ1000, SZ2000) with EM recorder'] ## What I Ask You - Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin) - Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)? - Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor? - Time range: start_timestamp and end_timestamp for backtest period - Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)? FILE:references/ANTI_PATTERNS.md # Anti-Patterns (Cross-Project) Total: **47** ## qlib (12) ### `AP-QLIB-1930` — 回测结果与模型无关——共享 dataset 对象导致预测值被首次模型覆盖 _(high) Qlib 中多个模型复用同一个已 fit 的 DatasetH 实例时，dataset 内部的标准化参数（fit_start_time/fit_end_time 决定的归一化统计量）在第一次 fit 后固化。切换模型但不重新初始化 dataset，导致所有模型实际使用同一套预测信号。表现为无论换 LightGBM/XGBoost/DNN，回测净值曲线完全一致。这是最危险的"实验看起来在跑，但结论全部无效"反模式。 Source: https://github.com/microsoft/qlib/issues/1930 ### `AP-QLIB-2090` — fit_start_time 与 train segment 双重配置引发隐式数据泄露 _(high) Qlib DatasetH 有两个"训练数据范围"：handler 的 fit_start_time/fit_end_time （决定归一化器拟合范围）和 segments.train（决定模型训练范围）。常见错误是让 fit_end_time 覆盖 valid/test 段，使归一化统计量（均值、标准差）包含了未来数据，造成前向偏差（look-ahead bias）。两者独立配置但语义耦合，文档未明确说明 fit_end_time 必须 <= train_end。 Source: https://github.com/microsoft/qlib/issues/2090 ### `AP-QLIB-2036` — MACD 因子公式文档错误——DEA 被多除一次 CLOSE 导致量纲不一致 _(high) Qlib 官方文档中的 Alpha 公式示例将 MACD 的 DEA 定义为 EMA(DIF, 9) / CLOSE，但 DIF 已经是无量纲（除过 CLOSE 的），再次除以 CLOSE 导致 DEA 量纲为 1/price。基于此文档公式构建的 MACD 因子在截面标准化后与正确公式差异显著，IC 下降。此类文档层面的公式错误会被大量用户直接照搬入生产因子库。 Source: https://github.com/microsoft/qlib/issues/2036 ### `AP-QLIB-2184` — 自定义 A 股数据导入前未按约定填充停牌日 NaN，引发下游因子噪声 _(high) Qlib 约定停牌日 open/close/high/low/volume/factor 字段均应填 NaN，以便框架在因子计算时识别并跳过。用户自建 A 股数据集时若将停牌日保留为上一日价格（常见于从东财/Wind 直接导出的数据），会导致停牌期间的价格动量因子出现 "假信号"（价格不变但因子非零）。Qlib 不校验此约定，错误静默流入训练数据。 Source: https://github.com/microsoft/qlib/issues/2184 ### `AP-QLIB-1892` — PIT（Point-In-Time）财务数据收集器依赖外部股票列表接口，全量 A 股获取不完整 _(high) Qlib 的 PIT 数据收集器（财务数据时间点快照）在初始化时调用 get_hs_stock_symbols() 获取沪深股票列表。该函数依赖东财 API，经常仅返回部分列表而非全量 5000+ 股票，且函数在获取不完整时直接 raise ValueError。用户若按文档步骤操作，财务数据集将只覆盖部分股票，基于 PIT 财务因子的回测存在严重生存者偏差（未被采集的股票被隐式排除）。 Source: https://github.com/microsoft/qlib/issues/1892 ### `AP-QLIB-2097` — 全市场 instrument="all" 在 32GB 内存机器上 OOM，但 CSI300 正常 _(medium) Qlib 在加载 Alpha158 特征时会将指定 universe 的全部特征矩阵一次性载入内存。使用 instrument="csi300"（300 股）与 instrument="all"（5000+ 股）的内存占用差约 16 倍。32GB 机器跑全市场时在 init_instance_by_config 阶段直接 OOM，错误信息不提示内存问题。用户容易误以为是配置错误，实际上需要分批加载或使用流式特征计算。 Source: https://github.com/microsoft/qlib/issues/2097 ### `AP-QLIB-1974` — data_collector 即使指定 --region US 仍调用东财 A 股接口获取股票列表 _(medium) Qlib Yahoo 数据收集器在 download_data 时无论 --region 参数为何，均调用东财 API（_get_eastmoney）获取完整股票列表作为基底，再用 Yahoo Finance 补充数据。在国际网络环境下东财接口不可达，导致即便指定 US 区域也必须科学上网。这一隐式依赖从未在文档中说明，是 A 股数据基础设施默认全局的典型设计陷阱。 Source: https://github.com/microsoft/qlib/issues/1974 ### `AP-QLIB-1984` — LightGBM 模型标签维度校验逻辑永远不触发导致多标签训练静默失败 _(medium) Qlib gbdt.py 中用 y.values.ndim == 2 判断是否为多标签，但从 DataFrame 取出的 Series 的 ndim 永远为 1，条件永远为 False，因此多标签训练不会走 squeeze 分支，而是直接进入 LightGBM 训练并在更深处抛出语义不明的错误。用户尝试自定义多标签任务时无法从错误信息定位到此根因。 Source: https://github.com/microsoft/qlib/issues/1984 ### `AP-QLIB-1915` — 自定义 CSV 数据 dump_bin 后 DataHandler 报 Length mismatch，D.features 却正常 _(high) Qlib 存在两套数据访问路径：D.features（直接读 binary）和 DataHandler/DataHandlerLP （带 processor pipeline）。自定义 A 股 CSV 数据在 dump_bin 时若字段顺序或 symbol 格式（如 600000.SH vs SH600000）与 Qlib 约定不符，DataHandler 的 processor 在 align/reindex 时触发 Length mismatch，而 D.features 因不经过 processor 而成功。这一"两套路径行为不一致"让用户误以为数据已正确导入。 Source: https://github.com/microsoft/qlib/issues/1915 ### `AP-QLIB-1949` — Colab/Linux 多进程后端与 Qlib ParallelExt 冲突导致 DataHandler 完全不可用 _(medium) Qlib 在非 fork 环境（Windows 或 Google Colab）中，DataHandler 使用 joblib 并行加载特征时，ParallelExt 初始化时访问 _backend_args 属性失败（AttributeError）。根因是 joblib 1.5+ 移除了该内部属性，Qlib 的兼容层未更新。表现为 D.features 调用抛出多层嵌套异常，用户无法从错误栈判断是并行后端问题还是数据问题。 Source: https://github.com/microsoft/qlib/issues/1949 ### `AP-QLIB-1930` — 回测结果与模型无关——共享 dataset 对象导致预测值被首次模型覆盖 _(high) Qlib 中多个模型复用同一个已 fit 的 DatasetH 实例时，dataset 内部的标准化参数（fit_start_time/fit_end_time 决定的归一化统计量）在第一次 fit 后固化。切换模型但不重新初始化 dataset，导致所有模型实际使用同一套预测信号。表现为无论换 LightGBM/XGBoost/DNN，回测净值曲线完全一致。这是最危险的"实验看起来在跑，但结论全部无效"反模式。 Source: https://github.com/microsoft/qlib/issues/1930 ### `AP-QLIB-2090` — fit_start_time 与 train segment 双重配置引发隐式数据泄露 _(high) Qlib DatasetH 有两个"训练数据范围"：handler 的 fit_start_time/fit_end_time （决定归一化器拟合范围）和 segments.train（决定模型训练范围）。常见错误是让 fit_end_time 覆盖 valid/test 段，使归一化统计量（均值、标准差）包含了未来数据，造成前向偏差（look-ahead bias）。两者独立配置但语义耦合，文档未明确说明 fit_end_time 必须 <= train_end。 Source: https://github.com/microsoft/qlib/issues/2090 ## vnpy (11) ### `AP-VNPY-3691` — K 线生成器首根 K 线时间戳不对齐，导致第一个周期信号错误 _(high) vnpy BarGenerator 在合成 N 分钟 K 线时，第一根推送的 K 线时间戳为"当前 tick 所在分钟"而非"完整 N 分钟周期结束时间"。具体表现：09:59 的 tick 会触发一根不完整的 5 分钟 K 线推送（本应等到 10:04 才推送）。策略若在 on_bar 中直接用 datetime.minute % 5 过滤，第一根 K 线恰好通过，但包含的数据不足一个完整周期，用于信号计算会产生错误的开仓信号。 Source: https://github.com/vnpy/vnpy/issues/3691 ### `AP-VNPY-3705` — CTP 委托价格超限被系统自动撤单，vnpy 无日志输出形同"无声失败" _(high) A 股/期货涨跌停价格限制下，超限委托在 CTP 端会被直接撤单（OnRtnOrder statusMsg="50:已撤单被拒绝SHFE:价格跌破跌停板"），而非触发 OnRspOrderInsert 拒单回调。vnpy 的 CTP Gateway 仅在 onRspOrderInsert 时输出拒单日志，对 OnRtnOrder 的撤单原因不做解析区分。策略开发者若依赖日志监控委托失败，超限委托将完全静默消失，导致实盘仓位与预期严重偏离。 Source: https://github.com/vnpy/vnpy/issues/3705 ### `AP-VNPY-3669` — Alpha 模块历史数据增量保存时新旧 DataFrame schema 不兼容导致 SchemaError _(medium) vnpy Alpha 模块在保存 K 线数据到 Parquet 文件时，将新下载数据（可能含 Float64 列）与已存文件（历史 Int64 列）直接 polars.concat。polars 强类型不允许隐式类型提升，抛出 SchemaError。根因是不同数据源/版本返回的字段类型不一致（如 volume 在部分行情源为整数，在另一些为浮点），且 concat 前无 schema 对齐步骤。影响所有使用 vnpy alpha 进行回测的历史数据构建流程。 Source: https://github.com/vnpy/vnpy/issues/3669 ### `AP-VNPY-3707` — CTP Gateway 登出时 C++ 空指针崩溃，重连/切换账号导致进程终止 _(high) vnpy_ctp 在调用 close() 登出时，C++ 端 MdApi/TdApi 未检查空指针，有较大概率触发段错误导致整个 Python 进程崩溃。影响场景：策略测试时频繁登录/登出、切换模拟与实盘账号、服务器关机重连等。崩溃不产生 Python 异常，无法被 try/except 捕获，是实盘场景中最危险的稳定性陷阱之一。 Source: https://github.com/vnpy/vnpy/issues/3707 ### `AP-VNPY-3685` — 价差交易模块 run_backtesting() 在 Jupyter 环境下静默报错，结果不可信 _(high) vnpy 4.10 价差交易（SpreadTrading）模块的 run_backtesting() 在 Jupyter 环境下存在事件循环冲突（asyncio already running），导致回测引擎部分逻辑不执行但不抛异常，返回看似正常的回测统计数据。同样代码在命令行 Python 中无此问题。vnpy 4.x 将部分 IO 改为 async 但 Jupyter 的事件循环与之不兼容，是"回测结果看起来正确但实际不完整"的隐蔽陷阱。 Source: https://github.com/vnpy/vnpy/issues/3685 ### `AP-VNPY-3700` — 安装脚本不使用 venv 导致全局 numpy 版本被降级破坏其他依赖 _(medium) vnpy install.bat 直接在系统/conda base 环境安装，会强制降级 numpy 到 <2.0 以满足 vnpy 依赖，破坏依赖 numpy 2.x 的其他量化工具（如 scipy、pytorch 新版）。没有 requirements.txt，依赖边界不透明。在多工具共存的量化研究环境中， vnpy 的安装脚本是"全局环境污染"的常见根源。 Source: https://github.com/vnpy/vnpy/issues/3700 ### `AP-VNPY-3715` — loguru 格式化字符串中含花括号的 order 对象触发 KeyError 导致日志系统崩溃 _(high) vnpy engine.py 使用 f-string 将 order.__dict__ 直接格式化后传给 loguru 的 write_log。当 order 的字段名（如 gateway_name）恰好匹配 loguru 格式化占位符时， loguru 将其解析为模板变量并抛出 KeyError，导致整个日志线程崩溃。实盘中日志系统崩溃意味着后续所有委托/成交记录丢失，是生产环境的高危陷阱。 Source: https://github.com/vnpy/vnpy/issues/3715 ### `AP-VNPY-3691` — K 线生成器首根 K 线时间戳不对齐，导致第一个周期信号错误 _(high) vnpy BarGenerator 在合成 N 分钟 K 线时，第一根推送的 K 线时间戳为"当前 tick 所在分钟"而非"完整 N 分钟周期结束时间"。具体表现：09:59 的 tick 会触发一根不完整的 5 分钟 K 线推送（本应等到 10:04 才推送）。策略若在 on_bar 中直接用 datetime.minute % 5 过滤，第一根 K 线恰好通过，但包含的数据不足一个完整周期，用于信号计算会产生错误的开仓信号。 Source: https://github.com/vnpy/vnpy/issues/3691 ### `AP-VNPY-3669` — Alpha 模块历史数据增量保存时新旧 DataFrame schema 不兼容导致 SchemaError _(medium) vnpy Alpha 模块在保存 K 线数据到 Parquet 文件时，将新下载数据（可能含 Float64 列）与已存文件（历史 Int64 列）直接 polars.concat。polars 强类型不允许隐式类型提升，抛出 SchemaError。根因是不同数据源/版本返回的字段类型不一致（如 volume 在部分行情源为整数，在另一些为浮点），且 concat 前无 schema 对齐步骤。影响所有使用 vnpy alpha 进行回测的历史数据构建流程。 Source: https://github.com/vnpy/vnpy/issues/3669 ### `AP-VNPY-3685` — 价差交易模块 run_backtesting() 在 Jupyter 环境下静默报错，结果不可信 _(high) vnpy 4.10 价差交易（SpreadTrading）模块的 run_backtesting() 在 Jupyter 环境下存在事件循环冲突（asyncio already running），导致回测引擎部分逻辑不执行但不抛异常，返回看似正常的回测统计数据。同样代码在命令行 Python 中无此问题。vnpy 4.x 将部分 IO 改为 async 但 Jupyter 的事件循环与之不兼容，是"回测结果看起来正确但实际不完整"的隐蔽陷阱。 Source: https://github.com/vnpy/vnpy/issues/3685 ### `AP-VNPY-3700` — 安装脚本不使用 venv 导致全局 numpy 版本被降级破坏其他依赖 _(medium) vnpy install.bat 直接在系统/conda base 环境安装，会强制降级 numpy 到 <2.0 以满足 vnpy 依赖，破坏依赖 numpy 2.x 的其他量化工具（如 scipy、pytorch 新版）。没有 requirements.txt，依赖边界不透明。在多工具共存的量化研究环境中， vnpy 的安装脚本是"全局环境污染"的常见根源。 Source: https://github.com/vnpy/vnpy/issues/3700 ## zipline (13) ### `AP-ZIPLINE-138` — 回测价格为未复权价，教程图表误导用户误判策略收益 _(high) Zipline 教程使用 AAPL 股价图做演示，但 bundle 中存储的是未复权价格（raw price），而非经过拆股/分红调整的复权价。图表显示的历史价格与市场实际价约差 4 倍（Apple 历次拆股累计因子），用户误将"价格翻 4 倍"当作策略收益。A 股场景更严重：除权前后价格跳变会在未复权数据中形成巨大"信号"，吸引技术指标在除权日产生虚假突破信号。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/138 ### `AP-ZIPLINE-235` — 默认以当根 K 线收盘价成交，低估实盘滑点，策略回测收益虚高 _(high) Zipline 默认滑点模型在当根 K 线触发信号后，以同根 K 线收盘价成交（current bar close fill）。实盘中信号只能在下一根 K 线的开盘价附近成交（T+1 order execution）。以 A 股日线为例，用收盘价回测比用次日开盘价成交平均高估日收益约 0.1-0.3%，年化差距可超 30%。需显式配置 slippage model 为 VolumeShareSlippage 或 FixedSlippage 并设合理 volume_limit。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/235 ### `AP-ZIPLINE-190` — 日历 start_session 设为非交易日触发 DateOutOfBounds，无提示如何修正 _(medium) Zipline 在注册 bundle 或运行算法时，若 start_session 参数恰好是非交易日（如 1998-01-01 元旦），Calendar 校验抛出 DateOutOfBounds（"cannot be earlier than the first session"）。错误信息仅显示交易日历起始日，不提示"请改为第一个交易日"。A 股场景：使用 SSE/SZSE 日历时，若 start_date 恰好是春节前最后一天次日（节假日），会触发同类错误，调试成本极高。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/190 ### `AP-ZIPLINE-182` — CSV bundle 中股票 symbol 列为空/None 时 SQLite 约束失败，全量导入静默中断 _(medium) Zipline csvdir bundle 在 ingest 时会将所有 CSV 文件名解析为 symbol，写入 equity_symbol_mappings 表。若 CSV 文件名不符合 Zipline 规范（如含中文、带交易所后缀 .SH），symbol 字段被解析为空字符串或 None，触发 sqlite3.IntegrityError: NOT NULL constraint failed。错误发生在 ingest 尾声，前面已写入的数据被回滚，整个 bundle 不可用。常见于 A 股数据（000001.SZ.csv 格式），需预处理文件名去掉后缀。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/182 ### `AP-ZIPLINE-181` — asset db 过期后 Pipeline 报"no assets traded"，误导用户排查数据范围 _(high) Zipline 的 asset database（SQLite）记录每只股票的 start/end 交易日期。若使用了旧版 Quandl/自建 bundle 且未重新 ingest，在回测新日期范围时 Pipeline 抛出 "Failed to find any assets with country_code 'US' that traded between [dates]"。A 股场景：重新下载行情后若只更新价格数据而未重建 asset db，退市/ 新上市股票的日期范围不更新，Pipeline 过滤会悄悄排除这些股票，产生生存者偏差。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/181 ### `AP-ZIPLINE-285` — week_start()/week_end() 在自定义日历（非美股）下静默失效 _(medium) Zipline schedule_function 的 date_rules.week_start() 和 date_rules.week_end() 依赖交易日历的周首/周末判断逻辑，但在非美股日历（如 ASX、SSE）中，该逻辑与 NYSE 日历的偏移计算不兼容，导致 schedule 永远不触发或在错误的日期触发。 A 股场景：使用 SSE 日历时，含春节等连续长假的周，week_start 可能跳过整个假期周而不调仓，但用户无法从日志发现未触发的调度。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/285 ### `AP-ZIPLINE-240` — 回测日期时区必须为 UTC，传入 naive datetime 引发深层 AssertionError _(medium) Zipline 内部强制要求所有时间戳为 UTC aware datetime。当用户传入 naive datetime （无时区信息，如 pd.Timestamp('2020-01-01')）时，不在入口处报错，而是在算法执行深处触发 AssertionError: Algorithm should have a utc datetime，栈深难以定位。A 股开发者从本地 CST 时间导入数据时极易触发此陷阱，需在 bundle 注册时显式 tz_localize('UTC')。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/240 ### `AP-ZIPLINE-138` — 回测价格为未复权价，教程图表误导用户误判策略收益 _(high) Zipline 教程使用 AAPL 股价图做演示，但 bundle 中存储的是未复权价格（raw price），而非经过拆股/分红调整的复权价。图表显示的历史价格与市场实际价约差 4 倍（Apple 历次拆股累计因子），用户误将"价格翻 4 倍"当作策略收益。A 股场景更严重：除权前后价格跳变会在未复权数据中形成巨大"信号"，吸引技术指标在除权日产生虚假突破信号。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/138 ### `AP-ZIPLINE-235` — 默认以当根 K 线收盘价成交，低估实盘滑点，策略回测收益虚高 _(high) Zipline 默认滑点模型在当根 K 线触发信号后，以同根 K 线收盘价成交（current bar close fill）。实盘中信号只能在下一根 K 线的开盘价附近成交（T+1 order execution）。以 A 股日线为例，用收盘价回测比用次日开盘价成交平均高估日收益约 0.1-0.3%，年化差距可超 30%。需显式配置 slippage model 为 VolumeShareSlippage 或 FixedSlippage 并设合理 volume_limit。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/235 ### `AP-ZIPLINE-190` — 日历 start_session 设为非交易日触发 DateOutOfBounds，无提示如何修正 _(medium) Zipline 在注册 bundle 或运行算法时，若 start_session 参数恰好是非交易日（如 1998-01-01 元旦），Calendar 校验抛出 DateOutOfBounds（"cannot be earlier than the first session"）。错误信息仅显示交易日历起始日，不提示"请改为第一个交易日"。A 股场景：使用 SSE/SZSE 日历时，若 start_date 恰好是春节前最后一天次日（节假日），会触发同类错误，调试成本极高。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/190 ### `AP-ZIPLINE-181` — asset db 过期后 Pipeline 报"no assets traded"，误导用户排查数据范围 _(high) Zipline 的 asset database（SQLite）记录每只股票的 start/end 交易日期。若使用了旧版 Quandl/自建 bundle 且未重新 ingest，在回测新日期范围时 Pipeline 抛出 "Failed to find any assets with country_code 'US' that traded between [dates]"。A 股场景：重新下载行情后若只更新价格数据而未重建 asset db，退市/ 新上市股票的日期范围不更新，Pipeline 过滤会悄悄排除这些股票，产生生存者偏差。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/181 ### `AP-ZIPLINE-285` — week_start()/week_end() 在自定义日历（非美股）下静默失效 _(medium) Zipline schedule_function 的 date_rules.week_start() 和 date_rules.week_end() 依赖交易日历的周首/周末判断逻辑，但在非美股日历（如 ASX、SSE）中，该逻辑与 NYSE 日历的偏移计算不兼容，导致 schedule 永远不触发或在错误的日期触发。 A 股场景：使用 SSE 日历时，含春节等连续长假的周，week_start 可能跳过整个假期周而不调仓，但用户无法从日志发现未触发的调度。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/285 ### `AP-ZIPLINE-240` — 回测日期时区必须为 UTC，传入 naive datetime 引发深层 AssertionError _(medium) Zipline 内部强制要求所有时间戳为 UTC aware datetime。当用户传入 naive datetime （无时区信息，如 pd.Timestamp('2020-01-01')）时，不在入口处报错，而是在算法执行深处触发 AssertionError: Algorithm should have a utc datetime，栈深难以定位。A 股开发者从本地 CST 时间导入数据时极易触发此陷阱，需在 bundle 注册时显式 tz_localize('UTC')。 Source: https://github.com/stefan-jansen/zipline-reloaded/issues/240 ## zvt (11) ### `AP-ZVT-183` — 除权因子为 inf/NaN 时直接参与乘法导致复权静默失败 _(high) ZVT 在计算前复权因子时以 new/old 价格比计算 qfq_factor。当 old==0（新股首日或数据缺失）时因子为 inf；当 kdata.open 本身为 None（停牌日未填充）时乘法抛出 TypeError。结果：整个 entity 的复权计算中断，后续 K 线全部丢失，但主流程只 log ERROR 不中断，用户往往不知道已有大量股票数据损坏。 Source: https://github.com/zvtvz/zvt/issues/183 ### `AP-ZVT-179` — 第三方数据接口超限后异常被吞噬，数据静默缺失 _(high) ZVT 使用聚宽 jqdatasdk 批量拉取全市场 K 线时（4000+ 股票），触发聚宽每日最大查询条数限制（错误：已超过每日最大查询数量）。ZVT 捕获异常后继续执行下一 entity，导致超限后所有股票的当日数据均静默缺失。回测若使用该残缺数据库，因子计算结果将产生系统性偏差，且无告警。 Source: https://github.com/zvtvz/zvt/issues/179 ### `AP-ZVT-200` — Token 失效后数据查询返回空 DataFrame 而非报错 _(high) 当聚宽/东财 token 过期时，ZVT 的 record_data 不抛异常，而是将 API 返回的错误信息（如"error: token无效"）当作 DataFrame 列名解析，得到 0 行空表。后续更新逻辑认为"无新数据"而跳过，造成数据库长期停止更新却无任何错误日志。用户直到回测结果异常才发现数据已过期数月。 Source: https://github.com/zvtvz/zvt/issues/200 ### `AP-ZVT-161` — 全市场 SQLite 批量因子计算触发 too many SQL variables 错误 _(medium) ZVT 在计算 VolumeUpMaFactor 等多股因子时，将所有 entity_id 拼入单条 SQL 的 IN 子句。当 A 股全市场（5000+ 股）一次性查询时，触发 SQLite 默认限制 SQLITE_MAX_VARIABLE_NUMBER=999。调大 max_allowed_packet（MySQL 参数）无效，根因是 SQLite 变量数上限。正确解法是分批查询，但 ZVT 早期版本未处理此边界。 Source: https://github.com/zvtvz/zvt/issues/161 ### `AP-ZVT-129` — 使用通配符导入隐藏 API 版本变更，AdjustType 等枚举莫名消失 _(medium) ZVT 文档示例使用 `from zvt import *` 导入所有符号。当 ZVT 版本升级重构枚举（如将 AdjustType 移入子模块）后，通配符导入不再包含该符号，触发 AttributeError。使用者误以为是安装问题，实际是版本间 API breaking change 未在 CHANGELOG 中标注，且通配符导入掩盖了具体来源。应显式 import 枚举类。 Source: https://github.com/zvtvz/zvt/issues/129 ### `AP-ZVT-187` — 回测引擎未在数据层空结果时提前终止，导致空指针级联崩溃 _(medium) ZVT Trader 在 load_data 完成后检查数据为空时，不提前退出，而是将空 DataFrame 传入 selector 计算，触发后续 NoneType 操作链式崩溃。错误栈深且难以定位根因，用户误以为是策略逻辑问题。根因是数据时间窗口配置错误（start/end 不在数据库覆盖范围内）但无有效校验。 Source: https://github.com/zvtvz/zvt/issues/187 ### `AP-ZVT-184` — 样例历史数据替换后 provider 目录不匹配导致更新报错 _(low) ZVT 提供了可下载的历史快照数据库，但文档未说明必须放置于特定 zvt_home 子目录下且与 provider 名称对应。用户将数据放错目录后执行 record_data 时，框架发现本地库为空，触发从头全量拉取，再次遭遇 API 额度或权限错误。数据库路径与 provider 的隐式绑定是常见理解盲区。 Source: https://github.com/zvtvz/zvt/issues/184 ### `AP-ZVT-183B` — HFQ（后复权）与 QFQ（前复权）K 线表使用错误导致因子计算漂移 _(high) ZVT 提供 Stock1dKdata（不复权）、Stock1dHfqKdata（后复权）、Stock1dQfqKdata （前复权）三张独立表。用户在计算价格动量/均线因子时混用两张表（如用不复权做均线，用后复权做收益率），导致除权日前后因子值产生跳变。ZVT 不做跨表复权类型一致性校验，混用静默通过。 Source: https://github.com/zvtvz/zvt/issues/183 ### `AP-ZVT-183` — 除权因子为 inf/NaN 时直接参与乘法导致复权静默失败 _(high) ZVT 在计算前复权因子时以 new/old 价格比计算 qfq_factor。当 old==0（新股首日或数据缺失）时因子为 inf；当 kdata.open 本身为 None（停牌日未填充）时乘法抛出 TypeError。结果：整个 entity 的复权计算中断，后续 K 线全部丢失，但主流程只 log ERROR 不中断，用户往往不知道已有大量股票数据损坏。 Source: https://github.com/zvtvz/zvt/issues/183 ### `AP-ZVT-187` — 回测引擎未在数据层空结果时提前终止，导致空指针级联崩溃 _(medium) ZVT Trader 在 load_data 完成后检查数据为空时，不提前退出，而是将空 DataFrame 传入 selector 计算，触发后续 NoneType 操作链式崩溃。错误栈深且难以定位根因，用户误以为是策略逻辑问题。根因是数据时间窗口配置错误（start/end 不在数据库覆盖范围内）但无有效校验。 Source: https://github.com/zvtvz/zvt/issues/187 ### `AP-ZVT-183B` — HFQ（后复权）与 QFQ（前复权）K 线表使用错误导致因子计算漂移 _(high) ZVT 提供 Stock1dKdata（不复权）、Stock1dHfqKdata（后复权）、Stock1dQfqKdata （前复权）三张独立表。用户在计算价格动量/均线因子时混用两张表（如用不复权做均线，用后复权做收益率），导致除权日前后因子值产生跳变。ZVT 不做跨表复权类型一致性校验，混用静默通过。 Source: https://github.com/zvtvz/zvt/issues/183 FILE:references/COMPONENTS.md # Component Capability Map **Project**: zvt **Scan date**: 2026-04-20 **Stats**: {'total_files': 325, 'total_classes': 424, 'total_functions': 571, 'total_business_decision_candidates': 147} ## Modules (14) - [factors](components/factors.md): 54 classes - [recorders](components/recorders.md): 90 classes - [trader](components/trader.md): 22 classes - [domain](components/domain.md): 114 classes - [api](components/api.md): 2 classes - [contract](components/contract.md): 53 classes - [broker](components/broker.md): 6 classes - [ml](components/ml.md): 5 classes - [tag](components/tag.md): 42 classes - [trading](components/trading.md): 19 classes - [common](components/common.md): 9 classes - [misc](components/misc.md): 2 classes - [informer](components/informer.md): 4 classes - [samples](components/samples.md): 2 classes ## Data Flow Hints (6) - {'from': 'EntitySchema (contract/schema.py)', 'to': 'Recorder (contract/recorder.py)', 'how': 'Recorder.data_schema = EntitySchema; RecorderManager registers recorders per entity'} - {'from': 'Recorder', 'to': 'Domain DB (SQLAlchemy models in domain/)', 'how': 'Recorder.run() calls schema.query_data() / session.add() via zvt storage layer'} - {'from': 'Domain DB', 'to': 'Factor (contract/factor.py)', 'how': 'Factor.__init__ reads entity_schema; Factor.compute() loads data via TechnicalFactor/TransformerFactor'} - {'from': 'Factor', 'to': 'TargetSelector (factors/target_selector.py)', 'how': 'TargetSelector aggregates multiple Factors; filters entities by score'} - {'from': 'TargetSelector', 'to': 'Trader (trader/)', 'how': 'Trader consumes TargetSelector.run() result to make buy/sell decisions'} - {'from': 'Trader', 'to': 'SimAccount / Broker', 'how': 'Trader places orders via Account.order(); SimAccount simulates fills'} FILE:references/CONSTRAINTS.md # Constraints ## preservation_manifest ```yaml required_objects: business_decisions_count: 188 fatal_constraints_count: 34 non_fatal_constraints_count: 124 use_cases_count: 31 semantic_locks_count: 12 preconditions_count: 4 evidence_quality_rules_count: 2 traceback_scenarios_count: 5 ``` ## Domain Constraints Injected (86) - **`SHARED-CN-ASTOCK-T1-001`** _(fatal): A 股股票实行 T+1 交收制度：T 日买入的股票最早 T+1 日方可卖出。 T 日卖出所得资金可当日再用于买入。回测框架若未施加 T+1 持仓锁定，将高估换手率与策略胜率，尤其损害日内反转类策略的真实性。 - **`SHARED-CN-ASTOCK-T1-002`** _(fatal): 沪深主板股票日涨跌幅上限为 ±10%（ST/SST 股票 ±5%）。涨停封板时买方消失、跌停封板时卖方消失；回测若假设当日可以任意价格成交，会系统性高估可执行性。封板检测应在成交模拟层强制实施。 - **`SHARED-CN-ASTOCK-T1-003`** _(high): 科创板和创业板（2020年8月改革后）正常交易日涨跌幅为 ±20%；北交所 ±30%；新股上市后前5个交易日不设涨跌幅限制。回测若对所有股票统一套用 ±10% 过滤逻辑，会错误剔除或错误包含这些板块的成交。 - **`SHARED-CN-ASTOCK-T1-004`** _(high): ST/*ST 股票日涨跌幅限制为 ±5%，流动性极差，成交假设不可与正常股票混用。包含历史 ST 股票（最终退市）但不纳入回测会产生幸存者偏差；纳入回测但不区分 ST 涨跌幅会错误模拟成交。 - **`SHARED-CN-ASTOCK-T1-005`** _(medium): A 股开盘集合竞价（9:15-9:25）和收盘集合竞价（14:57-15:00）期间，成交价由"最大成交量原则"确定，非即时撮合。回测以开盘价或收盘价假设即时全量成交会低估实际滑点风险，大单策略尤为明显。 - **`SHARED-CN-ASTOCK-T1-006`** _(high): 停牌制度：A 股长期停牌（2018年前可长达数月）期间，持仓资金被锁定，无法再平衡，机会成本在回测中普遍被忽略。应在因子计算前过滤停牌日（volume == 0 或 is_suspended == True），停牌期间不发出信号。 - **`SHARED-CN-ASTOCK-T1-007`** _(high): 新股上市后前5个交易日无涨跌幅限制（首日涨幅可超300%），且无完整历史数据（均线/波动率/换手率因子无法计算）。应在因子计算前过滤上市不足 N 个交易日（通常 60-252 日）的股票。 - **`SHARED-CN-ASTOCK-T1-008`** _(high): A 股程序化交易监管新规（2025年7月7日施行）：单账户每秒申报/撤单 ≥ 300 笔，或单日申报/撤单 ≥ 20000 笔，被认定为高频交易，须向交易所报备。 AI 生成的量化策略若频率超标则无法合规运行，应在策略设计期提示。 - **`SHARED-CN-ASTOCK-ADJ-001`** _(fatal): 除权除息日股价跳空是账面调整而非真实亏损。复权选择：不复权会虚增策略亏损；前复权会将历史价格内嵌未来分红信息（lookahead bias）；后复权以上市首日为基准累积，是量化回测的最优选择。 - **`SHARED-CN-ASTOCK-ADJ-002`** _(fatal): A 股上市公司财务报告披露有法定延迟：年报在次年4月30日前、半年报在8月31日前、季报分别在4月30日（一季）/10月31日（三季）前披露。回测中使用财务数据时，必须以实际披露日期（announcement_date）而非会计期间结束日作为数据可用时间点，否则引入 point-in-time lookahead bias。 - **`SHARED-CN-ASTOCK-ADJ-003`** _(high): 分红送股转增和配股会导致除权除息日后股本增加，历史持股数量不变但股价等比缩水，若回测系统未同步调整持仓股数，会在除权日产生虚假亏损或盈利。 - **`SHARED-CN-ASTOCK-ADJ-004`** _(medium): 大宗交易与竞价交易价差：大宗交易成交价可比市价折价最多 10%（主板），但此价格不影响次日竞价开盘。大宗交易数据出现在收盘后，若将其混入日内 OHLCV 数据，会污染收盘价和成交量的正常计算。 - **`SHARED-CN-ASTOCK-ADJ-005`** _(fatal): 融资融券（两融）做空限制：A 股散户无法直接卖空，融券标的池有限（主要为大盘蓝筹，中小盘融券极度稀缺），融券利率远高于融资利率。回测若直接假设可做空任意股票，会产生不可执行的策略，实盘与回测严重背离。 - **`SHARED-CN-ASTOCK-FX-001`** _(high): 通过沪深港通（北向）买入股票，境外投资者合计持股上限 30%，预警线 28%。当外资持股比例达 28% 时，联交所暂停该股新增买盘，直到降至 26% 才恢复。策略若重仓外资偏好股（消费/医药龙头），需监控外资持股比例。 - **`SHARED-CN-ASTOCK-FX-002`** _(high): 5% 举牌规则：单一投资者持有上市公司已发行股份超过 5%，须在3日内向证监会和交易所报告并公告；在此期间及公告后2日内不得再买卖。量化选股系统若不考虑此规则，重仓股超过 5% 阈值后将面临强制停止买入。 - **`SHARED-CN-ASTOCK-FX-003`** _(high): 公募基金"双十原则"：单基金持有单只股票不超过净资产 10%，同一基金管理人旗下所有基金合计不超过该公司已发行股份 10%。量化选股组合若部署于公募基金，需在优化约束中强制加入合规上限。 - **`SHARED-CN-ASTOCK-FX-004`** _(fatal): 内幕交易边界：AI 辅助量化系统的所有输入数据必须来自公开已披露信息。通过非公开渠道（私有数据服务/内部消息/重组前预知）触发的自动化交易构成内幕交易，适用《证券法》第80-83条及《内幕交易行为认定指引》。 - **`SHARED-CN-ASTOCK-MKT-001`** _(fatal): 幸存者偏差：使用当前 A 股成分股（如当前沪深300）作为历史回测股票池，会遗漏曾被纳入指数但因业绩差被调出或退市的股票。2020-2024年 A 股退市数量加速（41家/年创纪录），此偏差日趋严重。必须使用历史时点快照。 - **`SHARED-CN-ASTOCK-MKT-002`** _(medium): 指数成分股调整效应：沪深300/中证500等每半年调整一次（6月/12月），被纳入股票通常在公告日至生效日之间显著上涨（被动资金被动买入），被剔除股票则相反。回测股票池应使用历史成分股快照，并标注调整窗口期。 - **`SHARED-CN-ASTOCK-MKT-003`** _(high): 策略拥挤（Strategy Crowding）：大量量化私募使用相似因子模型时，持仓高度重叠，遇市场冲击时集体卖出形成踩踏。2024年2月 A 股量化危机是典型案例（小盘股指数单日跌幅超 10%）。需监控因子多头持仓与主流量化基金的重叠率。 - **`SHARED-CN-ASTOCK-MKT-004`** _(high): A 股量化对冲策略常用 IF/IC/IM 股指期货做多/空对冲系统性风险。但 A 股股指期货长期处于贴水（远期价格 < 现货），IC 年化贴水可达 10-20%。回测若仅考虑价格收益而忽略期货贴水/升水，会严重高估对冲策略净收益。 - **`SHARED-CN-ASTOCK-MKT-005`** _(high): A 股月度动量因子在方向上与美股相反：近1个月表现最好的股票，下1个月大概率反转（反转效应而非动量）。机构研究（华泰/东吴证券）与学术论文均验证：直接套用美股月度动量因子在 A 股会产生系统性亏损。 - **`SHARED-CN-ASTOCK-BF-001`** _(medium): 处置效应（Shefrin & Statman 1985）在 A 股散户中尤为显著：投资者倾向于过早卖出盈利股票、过长持有亏损股票。上交所实证研究证实超过 90% 的个人账户存在此效应，AI 辅助工具不应迁就"持有亏损等解套" 的直觉，而应基于量化信号提供纪律性止损止盈建议。 - **`SHARED-CN-ASTOCK-BF-002`** _(medium): A 股以散户为主（个人账户交易量占比超 80%），羊群效应显著：散户倾向于跟风操作，导致价格非理性波动（如 2015年杠杆牛熊）。量化策略应避免使用成交量排行/热度排行等可能强化羊群信号的指标作为主要因子。 - **`SHARED-CN-ASTOCK-BF-003`** _(medium): 过度自信效应（Barber & Odean 2000）在 A 股散户中更严重：散户年均换手率超 500%，机构长期收益显著优于散户。高换手率策略经交易成本后净收益往往更低。AI 不应鼓励"频繁操作"，而应推荐低频高质信号驱动交易。 - **`SHARED-CN-ASTOCK-BF-004`** _(medium): A 股日历效应：春节效应（节前5日和节后1-3日倾向上涨）、月初效应（月初第1-5个交易日表现优于月中/月末）已有学术实证（南京财经大学等）。策略应在日历特殊窗口降低信号置信度，或单独评估日历驱动收益的贡献。 - **`SHARED-CN-ASTOCK-BF-005`** _(high): 策略容量（Capacity）限制：A 股小盘/微盘股日均成交额仅数百万，大资金买入/卖出会造成严重价格冲击，策略实际容量可能仅几千万元。回测结果不可外推至亿级资金，应在回测中加入成交量比例上限约束。 - **`SHARED-CN-ASTOCK-COST-001`** _(fatal): A 股完整交易成本结构（2023年8月调整后）：印花税卖出单向 0.05%；佣金双向约 0.01%（最低5元）；过户费（沪市）0.001%；滑点/冲击成本小盘股 0.1%-0.5%/次。忽略成本的回测策略年化收益率具有欺骗性，高频/高换手策略尤甚。 - **`SHARED-CN-ASTOCK-COST-002`** _(high): 市场冲击成本（Market Impact）在回测中通常完全缺失，但在实盘中可能是最大成本来源。A 股小盘股 100 万元买入可能推高 1% 以上。冲击成本与成交规模呈幂律而非线性关系，应使用 Almgren-Chriss 模型或简化版估算。 - **`SHARED-CN-ASTOCK-COST-003`** _(medium): 大股东/董监高减持新规（证监会第224号令，2024年5月）：持股5%以上大股东通过集中竞价减持须提前15个交易日披露减持计划，3个月内不超过股份总数1%。解禁股减持压力是 A 股特有的系统性风险因子，回测中忽略解禁日历会低估相关股票的持股风险。 - **`SHARED-CN-ASTOCK-DATA-001`** _(high): A 股交易日历与自然日历不一致：存在法定节假日调休导致的"补班日"（周六上班），以及临时停市（2015年7月8日至7月10日因股灾紧急停市）。使用通用工作日历（weekdays）推算 A 股交易日会产生偏差，必须使用 A 股专用交易日历（如 exchange_calendars 或 tushare 的交易日接口）。 - **`SHARED-CN-ASTOCK-DATA-002`** _(medium): A 股退市后股票代码可能被新股重用（极少见但存在）。使用纯代码（如 '000001'）作为历史数据主键而不包含交易所后缀（'.SZ'）或上市日期范围，可能导致历史数据与当前股票的错误混淆，长周期回测中需特别注意。 - **`SHARED-DS-RL-001`** _(fatal): Rate Limit + 指数退避重试：所有外部数据 API 调用必须实施速率限制控制和指数退避重试（Exponential Backoff with Jitter）。收到 429/503 响应后立即重试是反模式，会加剧服务端压力并触发 IP 封禁。最大重试次数 3-5 次，退避基数 1-2 秒，最大退避 60 秒。 - **`SHARED-DS-RL-002`** _(high): 批量 API 调用必须控制并发数（max_workers），不可无限制并行。免费 API（akshare/tushare 免费版）通常限制为 1-3 并发；付费 API 也有并发上限（tushare 积分制，不同积分对应不同并发）。超出并发限制会触发 429 或 IP 封禁。推荐使用 asyncio.Semaphore 或 ThreadPoolExecutor 的 max_workers 参数显式控制。 - **`SHARED-DS-RL-003`** _(high): API Token / 凭证安全：数据源 API key（tushare token / akshare 无需 token 但其他商业数据源需要）不可硬编码在代码中，必须通过环境变量或配置文件读取。硬编码 token 提交到 Git 会导致 token 泄露和费用损失。 - **`SHARED-DS-RL-004`** _(medium): 请求节流（Throttling）：对同一 API 的批量请求应在请求间插入最小间隔（akshare 部分接口要求 ≥ 0.5s；tushare 免费版每分钟 200 次）。纯代码 sleep 不如令牌桶（Token Bucket）算法精确，推荐使用 ratelimit 或 slowapi 等成熟库。 - **`SHARED-DS-MISS-001`** _(high): 停牌日数据缺失策略：停牌股票在停牌期间无成交数据，数据库中会出现日期缺口。缺失日期不可使用 forward-fill（会产生虚假成交量）；应在数据库中以 is_suspended=True 标记，量和成交额填 0，价格保留前一日收盘价。因子计算时必须过滤 is_suspended=True 的行。 - **`SHARED-DS-MISS-002`** _(medium): 新上市股票的历史数据边界：新股上市首日开始在数据库中出现，但其上市前无历史数据。若因子计算的 lookback 期超过上市天数，会产生所有 NaN 因子值。采集时应记录每只股票的上市日期（list_date），采集逻辑应以上市日期为起点，不以固定开始日期。 - **`SHARED-DS-MISS-003`** _(high): 退市股票的数据完整性：已退市股票在主流数据源（akshare/tushare）中依然可以查询历史数据（退市前的历史），但退市日期后无数据。历史股票池构建时必须包含已退市股票（否则幸存者偏差），且采集时需明确处理退市日截止边界。 - **`SHARED-DS-MISS-004`** _(high): 多数据源数据对账（Cross-Source Reconciliation）：同一数据（如收盘价）从不同数据源（akshare/tushare/baostock）获取可能存在细微差异（不同复权方式/不同节假日处理/除息调整时间不同）。应在 pipeline 中实施多源对账检查，差异超阈值（如 0.1%）时记录告警并人工确认。 - **`SHARED-DS-TIME-001`** _(high): 时间戳精度与类型一致性：数据库中时间戳应使用统一的数据类型（timestamp 而非 varchar/int）。混用字符串日期（'2024-01-15'）和 Timestamp 对象是比较、索引、merge 出现细微 bug 的常见来源，应在 pipeline 入口处强制转换。 - **`SHARED-DS-TIME-002`** _(high): 交易时间与自然时间的区分：日线数据的"日期"通常对应交易日（T日），而新闻/公告数据的"时间"是自然时间。合并两类数据时，必须将自然时间映射到下一个可用交易日（next available trading day），否则会产生"公告在T日，但T日盘中已经可用"的 lookahead 问题。 - **`SHARED-DS-INCR-001`** _(high): 增量更新幂等性：数据更新脚本必须是幂等的（多次运行结果相同）。若脚本因网络中断在中途失败，重新运行时不应产生重复数据或数据缺口。实现方式：先写入临时表，校验后 UPSERT 到主表，不直接 INSERT/APPEND。 - **`SHARED-DS-INCR-002`** _(high): 数据完整性检验（数据校验和/行数检查）：每次数据更新后，应对关键字段做完整性检验：行数是否在预期范围内、价格是否为正数、日期是否连续（无缺失交易日）。缺少自动校验的数据管道是"沉默腐烂"的根源。 - **`SHARED-DS-INCR-003`** _(medium): 数据版本化：数据管道的输出数据应版本化管理（data versioning）。当数据源更新了历史数据（如修订调整后的财务数据），旧版本数据应保留可追溯，不应静默覆盖，以便对比版本间差异及复现历史回测。 - **`SHARED-DS-INCR-004`** _(medium): 数据对齐到交易日历边界：采集完成后，应验证所有股票/资产的数据覆盖完整性与交易日历的一致性。每只股票在每个交易日都应有一行数据（停牌标记，不是缺失）。通过 pivot_table 检查 NaN 比例是有效的快速诊断手段。 - **`SHARED-DS-INCR-005`** _(medium): 缓存策略（Caching）：频繁读取的静态/低频更新数据（如股票信息、行业分类、指数成分股）应本地缓存，避免每次运行重复 API 调用。缓存必须设置过期时间（TTL），防止使用过期的行业分类或已失效的成分股信息。 - **`SHARED-BT-LAB-001`** _(fatal): 未来函数（Lookahead Bias）：在模拟历史时间点 t 的交易决策时，不得使用 t 时刻之后才能知道的信息。最常见形式： (1) 使用收盘价计算信号并同日以收盘价成交； (2) 将 T 日收盘后计算的指标标记在同一根 K 线； (3) 使用当日最高/最低价作为成交假设。信号计算与成交时间必须对齐：T 日收盘后计算信号，T+1 日开盘成交。 - **`SHARED-BT-LAB-002`** _(high): 指标预热期（Warmup Period）处理：滚动窗口指标在前 N 个 bar 时 NaN，这些 bar 不应参与信号计算和持仓决策。强制要求指标的 warmup_period 与最长 lookback 期等长，且 warmup 期间持仓应置零。 - **`SHARED-BT-LAB-003`** _(fatal): ML/DL 模型时序数据划分必须按时间顺序：TRAIN < VALID < TEST，不可使用随机 k-fold 分折（会将未来数据混入训练集）。应使用 TimeSeriesSplit 或 Walk-Forward 验证。 - **`SHARED-BT-LAB-004`** _(fatal): 开盘价/最高价/最低价成交假设：日线回测中假设每日可以最高价卖出或最低价买入（如动量策略"最高价止盈"），这是明显的 lookahead，因为日内最高/最低价只有收盘后才能确认。成交价只能用开盘价或前一日收盘价（带滑点）。 - **`SHARED-BT-LAB-005`** _(high): 数据对齐偏移（Off-by-one）：pandas rolling/shift 等操作容易引入细微的 1 期偏移错误。应在代码中明确记录每个序列的"观测时间点"，并通过 assert 验证关键时间对齐关系。 - **`SHARED-BT-LAB-006`** _(high): 过度优化（Overfitting）：回测数量越多，过拟合概率越高。 Bailey et al.（2014）证明 Optimal Sharpe Ratio 期望值随回测次数单调递减。应使用 Walk-Forward 验证代替 in-sample 参数穷举，并报告 Deflated Sharpe Ratio（DSR）而非峰值 Sharpe。 - **`SHARED-BT-SURV-001`** _(fatal): 幸存者偏差（Survivorship Bias）：使用当前市场成分股作为历史回测股票池，会遗漏曾经存在但后来退市、摘牌或被合并的股票，系统性高估策略历史收益率。回测股票池必须使用历史时点快照（point-in-time universe）。 - **`SHARED-BT-SURV-002`** _(high): In-Sample / Out-of-Sample 划分：策略开发、参数选择必须在样本内完成，样本外数据仅用于最终验证，不可多次"看"样本外数据后继续调优（会将样本外变为新的样本内，重蹈过拟合）。 - **`SHARED-BT-SURV-003`** _(high): 停牌/缺失数据的填充策略：停牌日价格不可简单用前一日收盘价 forward-fill，因为这会在复盘时造成"零成交量"日参与了因子计算和信号生成。应在因子计算层显式过滤缺失交易日，不填充。 - **`SHARED-BT-SURV-004`** _(high): 异常值（Extreme Value）污染：原始市场数据可能含有数据源错误（如除权未及时调整、手工录入错误导致的极端价格），不清洗直接进入因子计算会产生极端信号，污染整个横截面。应在 pipeline 入口处过滤 3-sigma 异常值。 - **`SHARED-BT-COST-001`** _(fatal): 交易成本（佣金 + 印花税/转让税 + 过户费）必须在回测初始化时强制配置，不可使用零成本默认值。忽略成本的回测策略绩效指标具有欺骗性，高换手率策略尤其严重（单边往返成本往往吞噬 50%+ 的毛收益）。 - **`SHARED-BT-COST-002`** _(high): 滑点（Slippage）建模：回测若无滑点，假设每笔订单以理想价格成交，高频策略在实盘中会因成交价劣化而产生严重亏损。至少应配置固定点差或比例滑点；大单应使用成交量比例模型（如不超过日成交量 5%）。 - **`SHARED-BT-COST-003`** _(high): 换手率（Turnover）必须在回测绩效报告中展示并与成本关联分析。月换手率超过 50%（年化 600%+）时，策略净收益对成本假设极度敏感，每 10bps 成本变化可能改变策略盈亏结论，必须做成本敏感性分析。 - **`SHARED-BT-COST-004`** _(medium): 仓位规模化（Position Sizing）必须纳入资金量约束：回测应模拟固定资金量下的实际持仓股数（取整），而非假设可以持有小数股。对小盘股，最小交易单位（A股：100股/手）会导致实际可持仓量与目标权重产生偏差，应在回测中模拟取整效应。 - **`SHARED-BT-TIME-001`** _(high): 时间戳时区统一：多数据源合并时，UTC vs 本地时间混用是常见数据腐败源。所有时间戳必须在 pipeline 入口处统一转换为同一时区（推荐 UTC 存储，市场本地时区展示），不可在 pipeline 中途混用不同时区。 - **`SHARED-BT-TIME-002`** _(high): 交易日历对齐：合并不同市场或不同频率数据时（如日线价格 + 周频因子），必须使用明确的交易日历进行 reindex/merge，不可使用 outer join 后 fillna，否则会在非交易日（节假日）创建虚假数据行。 - **`SHARED-BT-TIME-003`** _(high): 增量更新边界校验：历史数据增量更新时，必须从数据库查询已存最新日期，仅下载该日期之后的数据。若重新下载已有数据并追加，会产生时间戳重复行，导致回测时序错误。更新前后必须校验无重复 (index.duplicated().any() == False)。 - **`SHARED-BT-TIME-004`** _(medium): 回测绩效归因失真：基准（Benchmark）选择不当会使 Alpha/Beta 计算失真。应选用策略实际可投资的被动基准（如 HS300 ETF），而非不可直接投资的价格指数（如 HS300 指数）。价格指数不含股息再投资，会低估持仓基准收益。 - **`SHARED-BT-PERF-001`** _(medium): 最大回撤（Max Drawdown）计算必须使用净值序列（portfolio value），不可用累计收益率序列代替。若使用对数收益率累加，会低估回撤深度（因对数收益率在下跌时会比简单收益率偏小）。 - **`SHARED-BT-PERF-002`** _(medium): Sharpe Ratio 年化化约定：年化 Sharpe = 日 Sharpe × sqrt(252)（股票，252 交易日）或 × sqrt(365)（加密货币，365日）。不同系统默认不同，跨系统对比前必须确认年化因子，否则 Sharpe 不可比。 - **`SHARED-BT-PERF-003`** _(medium): Calmar Ratio / Sortino Ratio 优于 Sharpe Ratio 作为风险调整收益指标： Sharpe 假设收益正态分布，A 股/加密市场的收益分布显著左偏（肥尾），会低估下行风险。量化评估应同时报告 Sortino（仅下行波动）和 Calmar（年化收益/最大回撤），不应单一依赖 Sharpe。 - **`SHARED-BT-PERF-004`** _(medium): 回测绩效归因应拆解为：alpha（主动收益）、beta（市场收益）、因子暴露收益（style/sector）和特异性收益（stock selection）。不做归因的回测无法区分"策略优秀"与"顺风行情恰好 beta 对了"。 - **`SHARED-FR-IC-001`** _(high): IC（信息系数）是衡量因子预测能力的核心指标，定义为因子值与下期收益率的 Spearman 秩相关系数（ICIR = IC / std(IC)）。 IC 绝对值 > 0.05 视为有预测能力的初步证据，ICIR > 0.5 视为稳定。不计算 IC 直接报告回测绩效是因子有效性证明缺失的典型问题。 - **`SHARED-FR-IC-002`** _(high): IC 衰减（IC Decay）分析：因子预测能力通常随持仓期增长而衰减。应计算 1/5/10/20 日 IC 序列，识别因子的最优持仓期。 IC 在1日高但20日迅速衰减的因子是短期因子，不适合月度换仓策略；反之亦然。使用错误的持仓期会严重损害因子实盘表现。 - **`SHARED-FR-IC-003`** _(high): Harvey, Liu & Zhu (2016) 警告：学术界已发现 300+ 个"显著"因子，其中大量是多重检验下的误发现（False Discovery）。因子有效性要求： t-stat > 3.0（而非传统的 1.96）；或在不同时段/市场独立复现；或有清晰的经济学逻辑。不满足上述条件的因子极可能是数据挖掘产物。 - **`SHARED-FR-IC-004`** _(high): 因子换手率（Factor Turnover）控制：高 IC 但高换手率的因子，在扣除交易成本后净 IC 可能为负。应计算换手率调整后的有效 IC： net_IC = IC - turnover × cost_per_turn。目标换手率 ≤ 50%（月频）。 - **`SHARED-FR-IC-005`** _(medium): 因子衰减期（Half-life）是因子信号强度的核心参数，直接决定最优再平衡频率。半衰期 < 5 日：日频或周频换仓；5-20 日：周频或双周；> 20 日：月频换仓。错误地对短期因子使用月频换仓，会导致大量 alpha 在持仓期内消散。 - **`SHARED-FR-NEUT-001`** _(high): 行业中性化（Industry Neutralization）：因子值若不对行业均值中性化，因子收益中会混入行业轮动收益，难以判断是因子本身还是行业暴露驱动了收益。行业中性化操作：factor_neutral = factor - industry_mean(factor)。 - **`SHARED-FR-NEUT-002`** _(high): 市值中性化（Market Cap Neutralization）：小盘股效应（小盘跑赢大盘）是金融史上最持久的 anomaly 之一，会污染几乎所有未中性化的因子。若因子与市值高度相关，选股会系统性偏向小盘，收益来自市值暴露而非因子本身。需同时进行行业和市值中性化（Fama-MacBeth 回归或残差法）。 - **`SHARED-FR-NEUT-003`** _(high): 异常值处理（Winsorize/MAD）：因子原始值通常含有极端值，极端值会扭曲分组分析（如 Q1/Q10 十分位）。应对原始因子值做 Winsorize（截尾至 [1%, 99%] 或 3-sigma）或 MAD（中位数绝对偏差）缩尾，然后再排名/中性化。 - **`SHARED-FR-NEUT-004`** _(medium): 因子正交化（Factor Orthogonalization）：当多个因子共同用于合成打分时，高相关因子的合成等效于对单一因子过度权重，稀释信号多样性。应在合成前对因子做施密特正交化或 PCA，消除因子间的多重共线性。 - **`SHARED-FR-NEUT-005`** _(medium): 缺失数据填充策略：因子计算中的 NaN（停牌/新股/数据缺口）若用截面均值填充会引入 lookahead bias（均值本身含未来信息）；若完全删除会产生幸存者偏差；正确做法是用截面中位数（当日所有股票的中位数，不依赖未来）或将该股当日排除。 - **`SHARED-FR-PORT-001`** _(high): 分层分析（Quantile Analysis）：因子评估应使用 Q1/Q5（五分位）或 Q1/Q10（十分位）分组的多空收益差（top minus bottom spread）作为主要评估指标，而非简单的多头收益。Q1 多 Q5 空的"单调性"检验是因子有效性的核心证据：单调递增/递减 > 非单调 >> 仅多头有效。 - **`SHARED-FR-PORT-002`** _(medium): Alpha 衰减测试（Alpha Decay Test）：因子的月度 IC 在不同时段（牛市/熊市/ 震荡市）的稳定性是因子鲁棒性的重要证据。IC 仅在某个特定市场状态下有效的因子不适合全天候部署；应分段（rolling 12M）展示 IC 时序，识别因子失效期。 - **`SHARED-FR-PORT-003`** _(medium): 换仓成本感知（Turnover-Aware Selection）：因子排名靠近中间地带（49-51 分位）的股票，排名小幅波动就会触发换仓，产生大量无效交易成本。应在选股时设置换仓缓冲区（buffer zone）：只在排名变化超过阈值时才换仓。 - **`SHARED-FR-PORT-004`** _(medium): 分组收益的统计显著性（Bootstrap 检验）：因子分层收益差（Q1-Q5 spread）即使在历史数据上很大，也可能是偶然，需要 bootstrap 或 t-test 检验显著性（p-value < 0.05）。小样本回测期（< 3年）的分层收益尤其不可靠。 - **`SHARED-FR-XFER-001`** _(high): 因子跨市场可移植性验证：在一个市场有效的因子，不必然在另一个市场有效。将美股因子直接套用 A 股、或将股票因子套用期货/加密货币，需要独立 IC 验证，不可假设跨市场通用性。A 股特有异象（如反转效应、ST 价格异常）不存在于美股。 - **`SHARED-FR-XFER-002`** _(medium): 因子有效性时间稳定性：曾经有效的因子会因市场学习和套利行为逐渐失效（McLean & Pontiff 2016 证明因子发表后平均衰减 58%）。应定期（每季度/年）重新评估因子 IC，失效因子应及时替换或降权。 - **`SHARED-FR-XFER-003`** _(medium): 因子与宏观经济环境的交互：利率周期/经济周期/市场情绪对因子有效性影响显著。价值因子（低 P/B）在利率上升期更有效；动量因子在趋势市更有效，震荡市失效。部署因子前应评估当前宏观环境与因子最优生存环境的匹配度。 FILE:references/LOCKS.md # Semantic Locks + Preconditions ## Semantic Locks (12) ### `SL-01` _{(on_violation: fatal)} Execute sell orders before buy orders in every trading cycle ### `SL-02` _{(on_violation: fatal)} Trading signals MUST use next-bar execution (no look-ahead) ### `SL-03` _{(on_violation: fatal)} Entity IDs MUST follow format entity_type_exchange_code ### `SL-04` _{(on_violation: fatal)} DataFrame index MUST be MultiIndex (entity_id, timestamp) ### `SL-05` _{(on_violation: fatal)} TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount ### `SL-06` _{(on_violation: fatal)} filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION ### `SL-07` _{(on_violation: fatal)} Transformer MUST run BEFORE Accumulator in factor pipeline ### `SL-08` _{(on_violation: fatal)} MACD parameters locked: fast=12, slow=26, signal=9 ### `SL-09` _{(on_violation: warning)} Default transaction costs: buy_cost=0.001, sell_cost=0.001, slippage=0.001 ### `SL-10` _{(on_violation: fatal)} A-share equity trading is T+1 (no same-day close of buy positions) ### `SL-11` _{(on_violation: fatal)} Recorder subclass MUST define provider AND data_schema class attributes ### `SL-12` _{(on_violation: fatal)} Factor result_df MUST contain either 'filter_result' OR 'score_result' column ## Preconditions (4) - **`PC-01`**: `python3 -c 'import zvt; print(zvt.__version__)'` → on_fail: Run: python3 -m pip install zvt then re-run: python3 -m zvt.init_dirs to initialize data directories - **`PC-02`**: `python3 -c "from zvt.api.kdata import get_kdata; df = get_kdata(entity_ids=['stock_sh_600000'], limit=1); assert df is not None and len(df) > 0, 'No kdata found'"` → on_fail: Run recorder first: python3 -m zvt.recorders.em.em_stock_kdata_recorder --entity_ids stock_sh_600000 (replace with your target entity IDs) - **`PC-03`**: `python3 -c "import os; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); assert zvt_home.exists(), f'ZVT home not found: {zvt_home}'"` → on_fail: Run: python3 -m zvt.init_dirs - **`PC-04`**: `python3 -c "import os, tempfile; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); test_f = zvt_home / '.write_test'; test_f.touch(); test_f.unlink()"` → on_fail: Check directory permissions: chmod u+w ~/.zvt or set ZVT_HOME environment variable to a writable location FILE:references/USE_CASES.md # Known Use Cases (KUC) Total: **41** ## `KUC-DR-001` **Source**: `examples/data_runner/actor_runner.py` 定时（每周三凌晨1点）批量采集机构投资者持仓、前十大流通股东、股东汇总数据，支撑后续机构持仓变化的量化分析。 **Inputs**: - {'data_provider': 'em'} - {'entity_provider': 'em'} - {'cron_schedule': 'hour=1, minute=0, day_of_week=2'} **Components**: - StockInstitutionalInvestorHolder - StockTopTenFreeHolder - StockActorSummary - run_data_recorder - BackgroundScheduler **Parameters**: ``` {'day_data': True, 'sleeping_time': None} ``` **Validation**: ``` 运行后查询 StockActorSummary.query_data() 返回非空 DataFrame，且数据时间戳更新至最近报告期。 ``` ## `KUC-DR-002` **Source**: `examples/data_runner/finance_runner.py` 每周五凌晨1点同步全市场A股财务四表（利润表、资产负债表、现金流量表、财务因子），保持本地数据库与东方财富数据源同步，为基本面选股提供原始数据。 **Inputs**: - {'data_provider': 'eastmoney'} - {'entity_provider': 'eastmoney'} - {'cron_schedule': 'hour=1, minute=0, day_of_week=5'} **Components**: - Stock - StockDetail - FinanceFactor - BalanceSheet - IncomeStatement - CashFlowStatement - run_data_recorder - BackgroundScheduler **Parameters**: ``` {'day_data': True} ``` **Validation**: ``` FinanceFactor.query_data(limit=5) 返回含最新报告期记录， CashFlowStatement.query_data() 不为空。 ``` ## `KUC-DR-003` **Source**: `examples/data_runner/index_runner.py` 维护A股指数基本信息及其成份股列表（国证1000/2000/成长/价值），并在每个交易日16:20后同步重要指数的日K行情，为板块轮动分析提供基础数据。 **Inputs**: - {'data_provider': '"exchange" / "em"'} - {'index_ids': ['index_sz_399311', 'index_sz_399303', 'index_sz_399370', 'index_sz_399371']} - {'important_index_codes': 'IMPORTANT_INDEX 常量'} **Components**: - Index - Index1dKdata - IndexStock - run_data_recorder - BackgroundScheduler **Parameters**: ``` {'day_data': True, 'entity_provider': 'exchange'} ``` **Validation**: ``` Index1dKdata.query_data(codes=IMPORTANT_INDEX) 返回当日收盘价记录。 ``` ## `KUC-DR-004` **Source**: `examples/data_runner/joinquant_fund_runner.py` 每周六从聚宽采集公募基金基本信息、基金持仓明细和个股估值（PE/PB），支持基金重仓分析与价值择时策略。 **Inputs**: - {'data_provider': 'joinquant'} - {'entity_provider': 'joinquant'} **Components**: - Fund - FundStock - StockValuation - run_data_recorder **Parameters**: ``` {'sleeping_time': 0, 'day_data': True} ``` **Validation**: ``` FundStock.query_data(limit=5) 返回含基金代码和持仓股代码的记录。 ``` ## `KUC-DR-005` **Source**: `examples/data_runner/joinquant_kdata_runner.py` 每个交易日15:30后从聚宽采集A股日后复权K线及交易日历，保持本地历史行情数据库完整，为技术因子计算提供全量数据基础。 **Inputs**: - {'data_provider': 'joinquant'} - {'entity_provider': 'joinquant'} **Components**: - Stock - StockTradeDay - Stock1dHfqKdata - run_data_recorder **Parameters**: ``` {'force_update': False, 'day_data': True, 'sleeping_time': 0} ``` **Validation**: ``` Stock1dHfqKdata.query_data(entity_id="stock_sz_000001", limit=5) 返回最新交易日收盘价。 ``` ## `KUC-DR-006` **Source**: `examples/data_runner/kdata_runner.py` A股+港股每日全市场行情录入主流程：包含涨停数据、指数行情、板块行情（概念/行业）、 A股后复权K线、港股（南向通）行情，并推送新板块通知邮件。 **Inputs**: - {'data_provider': 'em'} - {'entity_provider': 'em'} - {'sleeping_time': 0} **Components**: - LimitUpInfo - Index - Index1dKdata - Block - Block1dKdata - Stock - Stock1dHfqKdata - Stockhk - Stockhk1dHfqKdata - get_entity_ids_by_filter - EmailInformer - run_data_recorder **Parameters**: ``` {'ignore_delist': True, 'ignore_st': False, 'ignore_new_stock': False, 'return_unfinished': True, 'force_update': False} ``` **Validation**: ``` Stock1dHfqKdata.query_data(day_data=True) 及 LimitUpInfo.query_data() 均有当日记录，邮件收到新板块通知。 ``` ## `KUC-DR-007` **Source**: `examples/data_runner/kdata_runner.py` 采集涨停股的涨停原因并统计近期热门涨停题材（按出现频次排序），输出题材热度榜以辅助短线复盘。 **Inputs**: - {'days_ago': '20 / 5'} - {'limit': 15} **Components**: - LimitUpInfo - get_hot_topics - EmailInformer **Parameters**: ``` {'reason_split_char': '+'} ``` **Validation**: ``` get_hot_topics(days_ago=5) 返回非空字典，键为题材名，值为出现次数。 ``` ## `KUC-DR-008` **Source**: `examples/data_runner/kdata_runner.py` 采集A股全市场新闻标题，按可配置关键词分组统计各题材关联个股，识别长期热门 vs 新热门 vs 退潮题材，辅助主题投资决策。 **Inputs**: - {'hot_words_config': 'hot.json（主题:关键词列表）'} - {'days_ago': '20 / 5'} - {'threshold': 3} **Components**: - StockNews - run_data_recorder - get_hot_topics - group_stocks_by_topic - EmailInformer **Parameters**: ``` {'sleeping_time': 2, 'force_update': False} ``` **Validation**: ``` report_hot_topics() 邮件包含"一直热门"、"+++"、"---"三段信息，且每段均非空。 ``` ## `KUC-DR-009` **Source**: `examples/data_runner/sina_data_runner.py` 从新浪采集A股板块（概念/行业）基本信息及板块资金流向，提供与东方财富数据源互补的资金面视角。 **Inputs**: - {'data_provider': 'sina'} **Components**: - Block - BlockMoneyFlow - run_data_recorder **Parameters**: ``` {'day_data': True} ``` **Validation**: ``` BlockMoneyFlow.query_data(provider="sina", limit=5) 返回含 main_net_inflow 字段的记录。 ``` ## `KUC-DR-010` **Source**: `examples/data_runner/trading_runner.py` 每个交易日18点采集龙虎榜，筛选出近一年胜率高的知名游资席位，再过滤出30天内有该席位参与且当日成交额+换手率达标的个股，推送邮件供人工跟踪。 **Inputs**: - {'data_provider': 'em'} - {'entity_provider': 'em'} - {'look_back_days': 400} - {'recent_days': 30} - {'dep_rate_threshold': 5} - {'turnover_threshold': 300000000} - {'turnover_rate_threshold': 0.02} **Components**: - DragonAndTiger - Stock1dHfqKdata - get_big_players - EmailInformer - run_data_recorder **Parameters**: ``` {'sleeping_time': 2, 'day_data': True} ``` **Validation**: ``` DragonAndTiger.query_data(limit=5) 有当日记录，邮件包含"report 龙虎榜"主题。 ``` ## `KUC-FA-001` **Source**: `examples/factors/boll_factor.py` 为A股个股计算布林带（Bollinger Bands）并标注突破上轨/下轨信号，可视化价格与带宽关系，辅助均值回归与趋势跟踪策略。 **Inputs**: - {'entity_ids': ['stock_sz_000338', 'stock_sh_601318']} - {'provider': 'em'} - {'start_timestamp': '2019-01-01'} - {'data_level': '"1d" / "30m"'} **Components**: - BollTransformer (自定义 Transformer，使用 ta.volatility.BollingerBands) - BollFactor (继承 TechnicalFactor) - Stock1dHfqKdata / Stock30mHfqKdata **Parameters**: ``` {'window': 20, 'window_dev': 2, 'output_columns': ['bb_bbm', 'bb_bbh', 'bb_bbl', 'bb_bbhi', 'bb_bbli', 'bb_bbw', 'bb_bbp'], 'filter_result': 'bb_bbli - bb_bbhi (1=价格在下轨, -1=价格在上轨)'} ``` **Validation**: ``` factor.draw(show=True) 弹出含价格+布林带三轨道图形； factor.result_df 包含 True/False/None 三种状态。 ``` ## `KUC-FA-002` **Source**: `examples/factors/fundamental_selector.py` 用基本面多维度筛选"核心资产"：高ROE、高现金流、低财务杠杆、有增长、低应收账款（应收<=总流动资产30%），为长线价值投资提供股票池。 **Inputs**: - {'start_timestamp': '2016-01-01'} - {'end_timestamp': '当前日期字符串'} - {'codes': 'null（全A）'} **Components**: - FundamentalSelector (继承 TargetSelector) - GoodCompanyFactor (使用 FinanceFactor 数据) - GoodCompanyFactor (使用 BalanceSheet + accounts_receivable 过滤) - BalanceSheet **Parameters**: ``` {'provider': 'eastmoney', 'col_period_threshold': 'null (第二个 factor 不设列期数阈值)', 'accounts_receivable_max': '0.3 * total_current_assets'} ``` **Validation**: ``` selector.get_targets("2019-06-30") 返回非空 entity_id 列表，手工核对结果含典型高ROE龙头股（如贵州茅台、格力电器等）。 ``` ## `KUC-FA-003` **Source**: `examples/factors/tech_factor.py` 综合 MACD 金叉/多头趋势 + 均线多头排列（5/120/250日线）+ 成交额与换手率过滤，识别"放量上攻牛股"，为日线趋势跟踪策略提供入场信号。 **Inputs**: - {'entity_ids': '中大市值股票池（由 get_middle_and_big_stock 预过滤）'} - {'start_timestamp': '2019-01-01'} - {'adjust_type': 'AdjustType.hfq'} **Components**: - BullAndUpFactor (继承 MacdFactor) - CrossMaTransformer (windows=[5, 120, 250]) - MacdFactor **Parameters**: ``` {'turnover_threshold': 400000000, 'turnover_rate_threshold': 0.02, 'ma_windows': [5, 120, 250]} ``` **Validation**: ``` factor.result_df["filter_result"] 含 True 条目； report_bull() 邮件列出符合条件标的。 ``` ## `KUC-RP-001` **Source**: `examples/reports/report_bull.py` 每个交易日18点自动筛选满足"牛股"条件（MACD金叉+多头趋势+成交量达标）的 A股及板块，分类推送邮件并同步到东方财富自选股组，辅助每日择股。 **Inputs**: - {'target_date': 'get_latest_kdata_date() 自动获取'} - {'entity_ids': 'get_middle_and_big_stock(timestamp)'} - {'adjust_type': 'AdjustType.hfq (股) / AdjustType.qfq (板块)'} **Components**: - BullAndUpFactor - report_targets - get_middle_and_big_stock - EmailInformer **Parameters**: ``` {'turnover_threshold': 300000000, 'turnover_rate_threshold': 0.02, 'start_timestamp': '2019-01-01', 'em_group': 'bull股票', 'em_group_over_write': False, 'filter_by_volume': False} ``` **Validation**: ``` 邮件主题包含"bull股票"且正文包含个股代码；东方财富"bull股票"组有对应记录。 ``` ## `KUC-RP-002` **Source**: `examples/reports/report_core_compay.py` 每周六基于基本面多因子模型（FundamentalSelector）筛选核心资产，附上基金和QFII持仓占比变化，发邮件并同步东方财富"core"自选组，为长线配置提供每周精选标的。 **Inputs**: - {'start_timestamp': '2016-01-01'} - {'end_timestamp': '当前日期'} - {'subscriber_emails': 'subscriber_emails.json 文件'} **Components**: - FundamentalSelector - TargetSelector - StockActorSummary - get_entities - add_to_eastmoney - EmailInformer **Parameters**: ``` {'actor_type': 'ActorType.raised_fund / ActorType.qfii', 'em_group': 'core'} ``` **Validation**: ``` 邮件含选股结果（含机构持仓占比）；若无结果则发送"no targets"。 ``` ## `KUC-RP-003` **Source**: `examples/reports/report_tops.py` 每日17点计算A股短期最强（近期涨幅最高）和中期最强个股， 17:30计算最强行业板块和最强概念板块（按N日涨幅排名），并同步推送港股南向通短期/中期最强，辅助板块轮动和动量策略。 **Inputs**: - {'periods': '短期=[近N天], 中期=[30,50]'} - {'top_count': '10（板块）'} - {'turnover_threshold': '100000000（港股）'} **Components**: - get_top_stocks - report_top_entities - get_top_performance_entities_by_periods - Block - BlockCategory - inform - EmailInformer **Parameters**: ``` {'return_type': 'TopType.positive', 'ignore_new_stock': 'false / true', 'adjust_type': 'AdjustType.hfq / null', 'em_group_over_write': True} ``` **Validation**: ``` 邮件分别包含"短期最强"、"中期最强"、"最强行业"、"最强概念"主题，每组列出 top_count 数量标的。 ``` ## `KUC-RP-004` **Source**: `examples/reports/report_vol_up.py` 筛选"放量突破半年线或年线"的A股（按市值分大小市值两组）和港股，识别均线突破形态的个股，辅助中期趋势入场。 **Inputs**: - {'windows': [120, 250]} - {'up_intervals': 60} - {'over_mode': 'or'} - {'turnover_threshold': '100000000（港股）'} **Components**: - VolumeUpMaFactor - get_top_stocks (return_type="small_vol_up" / "big_vol_up") - report_targets - inform - EmailInformer **Parameters**: ``` {'adjust_type': 'AdjustType.hfq', 'start_timestamp': '2021-01-01', 'filter_by_volume': False} ``` **Validation**: ``` 邮件包含"放量突破(半)年线"标题，标的按大小市值分两封邮件。 ``` ## `KUC-RP-005` **Source**: `examples/reports/__init__.py` 识别财务风险股票：营收/利润下滑、流动比率/速动比率低、高应收+高存货+高商誉、应收账款超净利润一半，用于规避高风险标的或做空筛选。 **Inputs**: - {'the_date': '当前日期（默认）'} - {'income_yoy': '-0.1 (同比跌幅阈值)'} - {'profit_yoy': -0.1} - {'entity_ids': 'null（全A）'} **Components**: - FinanceFactor - BalanceSheet - IncomeStatement - risky_company (自定义函数) **Parameters**: ``` {'current_ratio_min': 0.7, 'quick_ratio_min': 0.5, 'start_offset_days': 130} ``` **Validation**: ``` risky_company() 返回含高风险个股代码的列表，手工验证含已知财务暴雷股。 ``` ## `KUC-RS-001` **Source**: `examples/research/dragon_and_tiger.py` 分析龙虎榜历史数据，识别过去一年（~400天）中胜率最高的游资席位（大玩家），并计算每个席位在不同持仓天数（3/5/10天）下的历史胜率，为跟庄席位策略提供统计依据。 **Inputs**: - {'provider': 'em'} - {'start_timestamp': 'date_time_by_interval(end_timestamp, -400)'} - {'end_timestamp': 'date_time_by_interval(current_date(), -60)'} - {'intervals': [3, 5, 10]} **Components**: - DragonAndTiger - get_big_players - get_player_success_rate **Validation**: ``` get_player_success_rate() 返回含席位名+多个持仓天数胜率的 DataFrame，可见知名游资席位（如"国泰君安证券股份有限公司上海江苏路证券营业部"）。 ``` ## `KUC-RS-002` **Source**: `examples/research/top_dragon_tiger.py` 对每月涨幅前30股票，追溯其月涨幅期间内龙虎榜记录，统计哪些席位频繁参与月度强势股，揭示"聪明钱"机构行为模式。 **Inputs**: - {'data_provider': 'em'} - {'start_timestamp': '2021-01-01'} - {'end_timestamp': '2022-01-01'} **Components**: - get_top_performance_by_month - get_players - DragonTigerFactor (继承 TechnicalFactor，叠加席位注释) **Parameters**: ``` {'direction': 'in', 'top_count_per_month': 30} ``` **Validation**: ``` top_dragon_and_tiger() 返回合并后的 player_df，按 entity_id+timestamp 双索引排序，可见重复出现的知名席位。 ``` ## `KUC-RS-003` **Source**: `examples/research/top_tags.py` 统计每月涨幅前30股票的市值分布，验证"小市值效应"假设，并记录每个月度强势股对应时点的市值及得分，为选股规则制定提供实证依据。 **Inputs**: - {'data_provider': 'em'} - {'start_timestamp': '2020-01-01'} - {'end_timestamp': '2021-01-01'} **Components**: - get_top_performance_by_month - Stock1dHfqKdata - top_tags (自定义函数) **Parameters**: ``` {'list_days': 250} ``` **Validation**: ``` top_tags() 返回含 {entity_id, timestamp, cap, score} 的记录列表，分析结果验证"市值90%分布在100亿以下"的假设。 ``` ## `KUC-ML-001` **Source**: `examples/ml/sgd.py` 用 SGD 分类器基于MA特征预测A股个股下期价格行为（涨/跌/震荡分类），结合标准化管道训练+预测，可视化预测结果与实际K线对比。 **Inputs**: - {'data_provider': 'em'} - {'entity_ids': ['stock_sz_000001']} - {'label_method': 'behavior_cls'} **Components**: - MaStockMLMachine - SGDClassifier (sklearn) - StandardScaler - make_pipeline **Parameters**: ``` {'max_iter': 1000, 'tol': '1e-3'} ``` **Validation**: ``` machine.draw_result(entity_id="stock_sz_000001") 展示预测结果图；预测准确率可通过 machine.predict() 返回的 DataFrame 评估。 ``` ## `KUC-ML-002` **Source**: `examples/ml/sgd.py` 用 SGD 回归器基于MA特征直接预测A股个股下期收益率（连续值），与分类模式对比，评估线性模型的预测能力。 **Inputs**: - {'data_provider': 'em'} - {'entity_ids': ['stock_sz_000001']} - {'label_method': 'raw'} **Components**: - MaStockMLMachine - SGDRegressor (sklearn) - StandardScaler - make_pipeline **Parameters**: ``` {'max_iter': 1000, 'tol': '1e-3'} ``` **Validation**: ``` machine.draw_result(entity_id="stock_sz_000001") 展示回归预测线；预测误差通过 MSE/MAE 评估。 ``` ## `KUC-IN-001` **Source**: `examples/intent/intent.py` 对比沪指与道琼斯指数自2000年起的相对表现（同基归一化），直观展示中美股市的长期相关性与分化，辅助宏观择时判断。 **Inputs**: - {'entity_ids': ['index_sh_000001', 'indexus_us_SPX']} - {'start_timestamp': '2000-01-01'} - {'scale_value': 100} **Components**: - Index - Indexus - Index1dKdata - Indexus1dKdata - compare **Validation**: ``` compare() 弹出含双轨叠加的折线图，Y轴为归一化值（基期=100）。 ``` ## `KUC-IN-002` **Source**: `examples/intent/intent.py` 比较美债收益率（2年/5年）与道指走势的历史关系，验证"高利率压制股市"假设，辅助美联储政策周期下的资产配置。 **Inputs**: - {'entity_ids': ['country_galaxy_US', 'indexus_us_SPX']} - {'start_timestamp': '1990-01-01'} **Components**: - TreasuryYield - Indexus1dKdata - compare **Parameters**: ``` {'scale_value': None, 'schema_map_columns': {'TreasuryYield': ['yield_2', 'yield_5'], 'Indexus1dKdata': ['close']}} ``` **Validation**: ``` compare() 展示多轨折线图，可见利率与指数的反向关系。 ``` ## `KUC-IN-003` **Source**: `examples/intent/intent.py` 对比江西铜业股票与沪铜期货走势（归一化），验证"资源股跟踪商品价格"假设，识别股价与商品价格的背离机会。 **Inputs**: - {'entity_ids': ['stock_sh_600362', 'future_shfe_CU']} - {'start_timestamp': '2005-01-01'} - {'scale_value': 100} **Components**: - compare **Validation**: ``` compare() 展示归一化双轨折线，可见铜业股与铜期货的高度相关走势。 ``` ## `KUC-IN-004` **Source**: `examples/intent/intent.py` 比较铜、铝、螺纹钢三种工业金属的价格走势，识别金属品种间的轮动规律与分化，为跨品种套利提供参考。 **Inputs**: - {'entity_ids': ['future_shfe_CU', 'future_shfe_AL', 'future_shfe_RB']} - {'start_timestamp': '2009-04-01'} - {'scale_value': 100} **Components**: - compare **Validation**: ``` compare() 展示三条归一化折线，可见品种间分化时段。 ``` ## `KUC-IN-005` **Source**: `examples/intent/intent.py` 比较纳指/标普/美元指数三者走势（2015年后），研究"美元强弱对美股的压制效应"，辅助海外资产配置。 **Inputs**: - {'entity_ids': ['indexus_us_NDX', 'indexus_us_SPX', 'indexus_us_UDI']} - {'start_timestamp': '2015-01-01'} - {'scale_value': 100} **Components**: - Indexus1dKdata - compare **Parameters**: ``` {'schema_map_columns': {'Indexus1dKdata': ['close']}} ``` **Validation**: ``` compare() 展示三轨折线，可分析纳指与美元指数的走势分化。 ``` ## `KUC-IN-006` **Source**: `examples/intent/intent.py` 对比人民币兑美元汇率（USDCNY）与沪指走势，研究汇率贬值对A股资金流向的影响，辅助外资流出风险判断。 **Inputs**: - {'entity_ids': ['index_sh_000001', 'currency_forex_USDCNYC']} - {'start_timestamp': '2005-01-01'} - {'scale_value': 100} **Components**: - Currency1dKdata - Index1dKdata - compare **Parameters**: ``` {'schema_map_columns': {'Currency1dKdata': ['close'], 'Index1dKdata': ['close']}} ``` **Validation**: ``` compare() 展示双轨折线，可见汇率与指数的阶段性反相关。 ``` ## `KUC-TR-001` **Source**: `examples/trader/ma_trader.py` 最简单的MA均线交叉回测：5日线上穿10日线买入、下穿卖出，验证双均线策略在单只/多只A股上的历史收益，提供最基础的趋势跟踪策略 baseline。 **Inputs**: - {'codes': ['000338']} - {'level': 'IntervalLevel.LEVEL_1DAY'} - {'start_timestamp': '2019-01-01'} - {'end_timestamp': '2019-06-30'} - {'windows': [5, 10]} **Components**: - CrossMaFactor - MyMaTrader (继承 StockTrader) **Parameters**: ``` {'need_persist': False, 'trader_name': '000338_ma_trader'} ``` **Validation**: ``` trader.run() 完成后，zvt 数据库中有 trader_name 对应的交易记录； trader.draw_result() 展示净值曲线。 ``` ## `KUC-TR-002` **Source**: `examples/trader/ma_trader.py` MACD多头市场过滤+MA均线交叉的组合策略回测：只在大趋势向上（BullFactor）时持有多头仓位，降低熊市做多风险，验证加入趋势过滤的策略改进效果。 **Inputs**: - {'codes': ['000338']} - {'level': 'IntervalLevel.LEVEL_1DAY'} - {'start_timestamp': '2019-01-01'} - {'adjust_type': 'hfq'} **Components**: - BullFactor - MyBullTrader (继承 StockTrader) **Validation**: ``` trader.run() 完成，净值曲线较纯MA策略回撤更低。 ``` ## `KUC-TR-003` **Source**: `examples/trader/macd_day_trader.py` 日线 MACD 金叉策略完整框架示例：演示如何在 StockTrader 中覆盖止盈止损（on_profit_control）、开收盘钩子（on_trading_open/close）、交易信号批处理（on_trading_signals）等生命周期方法。 **Inputs**: - {'start_timestamp': '2019-01-01'} - {'end_timestamp': '2020-01-01'} - {'provider': 'joinquant'} - {'level': 'IntervalLevel.LEVEL_1DAY'} **Components**: - GoldCrossFactor - MacdDayTrader (继承 StockTrader) **Parameters**: ``` {'start_offset_days': -50} ``` **Validation**: ``` trader.run() 不报错；各 hook 方法被正确调用（可在 override 中添加日志验证）。 ``` ## `KUC-TR-004` **Source**: `examples/trader/macd_week_and_day_trader.py` 周线+日线双时间框架 MACD 策略：只有周线和日线同时金叉时才开多仓，降低误信号，验证多周期共振策略的信号质量提升。 **Inputs**: - {'start_timestamp': '2019-01-01'} - {'end_timestamp': '2020-01-01'} - {'provider': 'joinquant'} **Components**: - GoldCrossFactor (LEVEL_1WEEK) - GoldCrossFactor (LEVEL_1DAY) - MultipleLevelTrader (继承 StockTrader) **Parameters**: ``` {'on_targets_selected_from_levels': 'override 可自定义多级别合并逻辑'} ``` **Validation**: ``` trader.run() 完成；相比纯日线策略，交易次数减少但胜率更高。 ``` ## `KUC-TR-005` **Source**: `examples/trader/dragon_and_tiger_trader.py` 基于龙虎榜跟踪机构专用席位：当"机构专用"席位在某股票上榜时产生买入信号，依此验证"跟机构席位"策略的历史有效性。 **Inputs**: - {'start_timestamp': '2020-01-01'} - {'end_timestamp': '2022-05-01'} - {'provider': 'em'} **Components**: - DragonTigerFactor (继承 Factor，数据源为 DragonAndTiger) - MyTrader (继承 StockTrader) **Parameters**: ``` {'filter': 'DragonAndTiger.dep1 == "机构专用"'} ``` **Validation**: ``` trader.run() 完成，交易记录中开仓时间与龙虎榜机构上榜日期一致。 ``` ## `KUC-TR-006` **Source**: `examples/trader/follow_ii_trader.py` 跟随公募基金持仓变化做多/平仓：当基金持仓比例季报新增超5%时买入，减持超50%时卖出，验证"跟基金重仓变化"的交易逻辑在单只股票（茅台）上的效果。 **Inputs**: - {'code': '600519'} - {'start_timestamp': '2002-01-01'} - {'end_timestamp': '2021-01-01'} - {'adjust_type': 'AdjustType.qfq'} **Components**: - FollowIITrader (继承 StockTrader，override on_time) - StockActorSummary - Stock1dKdata **Parameters**: ``` {'actor_type': 'ActorType.raised_fund', 'long_threshold': 0.05, 'short_threshold': -0.5, 'profit_threshold': None} ``` **Validation**: ``` trader.run() 完成；可视化净值曲线在2010-2021年茅台上涨期间应呈显著正收益。 ``` ## `KUC-TR-007` **Source**: `examples/trader/keep_run_trader.py` 滚动40天区间多因子组合策略：每40天重新计算股票池（成交量前30%+机构重仓前30%的交集），结合周线牛市判断+日线金叉入场，验证动态股票池筛选对组合策略的增益。 **Inputs**: - {'start': '2019-01-01'} - {'end': '2021-01-01'} - {'interval': 40} - {'vol_pct': 0.3} - {'ii_pct': 0.3} **Components**: - MultipleLevelTrader (BullFactor LEVEL_1WEEK + GoldCrossFactor LEVEL_1DAY) - get_top_volume_entities - get_top_fund_holding_stocks - split_time_interval - clear_trader **Parameters**: ``` {'keep_history': True, 'draw_result': False, 'rich_mode': False, 'trader_name': 'keep_run_trader'} ``` **Validation**: ``` 所有时间段遍历完成后，zvt 数据库中有完整的 keep_run_trader 交易历史记录。 ``` ## `KUC-QU-001` **Source**: `examples/query_snippet.py` 演示 StockTags 的 JSON 字段查询能力：通过 SQLite JSON_EXTRACT 函数按子标签（如"低空经济"）精确筛选A股，解决标签多值存储下的高效检索问题。 **Inputs**: - {'sub_tag': '低空经济'} **Components**: - StockTags - func.json_extract (SQLAlchemy) **Parameters**: ``` {'json_path': '$."{tag}"'} ``` **Validation**: ``` query_json() 返回含对应子标签的 DataFrame，行数与东方财富"低空经济"板块成份数接近。 ``` ## `KUC-QU-002` **Source**: `examples/query_snippet.py` 快速获取当前标签库的覆盖缺口：找出尚无标签的在市A股代码列表，为标签体系维护提供自动差异发现。 **Inputs**: - {'provider': 'em'} - {'ignore_delist': True} - {'ignore_st': True} **Components**: - StockTags - get_entity_ids_by_filter **Validation**: ``` get_stocks_without_tag() 返回非空列表，代码均可在东方财富查到且无标签记录。 ``` ## `KUC-QU-003` **Source**: `examples/tag_utils.py` 为一批A股个股自动生成默认行业标签（通过行业板块->主题映射表），解决大批量新股入库时缺少标签的冷启动问题。 **Inputs**: - {'codes': '无标签股票代码列表'} - {'provider': 'em'} **Components**: - BlockStock - Block - industry_to_tag (行业->主题映射函数) - build_default_tags **Parameters**: ``` {'block_category': 'industry'} ``` **Validation**: ``` build_default_tags(codes) 返回含 code/name/tag/reason 字段的字典列表，无行业信息的股票自动打印告警。 ``` ## `KUC-QU-004` **Source**: `examples/utils.py` 按热词配置（hot.json）对选出的个股用新闻标题分组，归类到主题（如"华为"、"新能源"等），辅助人工快速了解选股的热门主题背景。 **Inputs**: - {'entities': '已选个股列表'} - {'hot_words_config': 'hot.json（主题:关键词列表）'} - {'days_ago': 60} - {'threshold': 3} **Components**: - StockNews - group_stocks_by_topic - msg_group_stocks_by_topic **Parameters**: ``` {'entity_ids': '自动从 entities 提取'} ``` **Validation**: ``` msg_group_stocks_by_topic() 返回按主题分组的字符串，包含"^^^^^^ 主题(N) ^^^^^^"格式。 ``` ## `KUC-QU-005` **Source**: `examples/migration.py` 演示如何用 Pydantic + SQLAlchemy Mixin 向 zvt 注册自定义数据 schema，支持业务团队扩展本地数据库存储自定义实体和 JSON 字段，无需修改框架核心。 **Inputs**: - {'custom_schema': 'User (含 added_col: String, json_col: JSON)'} - {'db_name': 'test'} - {'providers': ['zvt']} **Components**: - Mixin - register_schema - get_db_session - UserModel (Pydantic BaseModel) **Parameters**: ``` {'declarative_base': 'ZvtInfoBase'} ``` **Validation**: ``` UserModel.validate(user) 不报错，说明 SQLAlchemy ORM 对象可无缝转换为 Pydantic 模型。 ``` FILE:references/WISDOM.md # Cross-Project Wisdom Total: **23** ## `CW-BT-001` — Cerebro 统一编排引擎 **From**: backtrader · **Applicable to**: backtesting backtrader 用 Cerebro 作为单一入口，统一管理 data feeds、strategies、analyzers、 observers 的生命周期，支持一次 cerebro.run() 跑多策略+多数据源。 zvt 的 StockTrader 目前每次实例化只绑定一套因子，缺乏统一的多策略组合编排层；借鉴 Cerebro 模式可让用户把多个 Trader 实例组合到一个 runner 中对比评估。 ## `CW-BT-002` — Analyzer 插件化绩效评估 **From**: backtrader · **Applicable to**: backtesting backtrader 提供 SharpeRatio、DrawDown、TimeReturn、TradeAnalyzer 等即插即用的 Analyzer，可在不修改策略代码的情况下附加任意绩效指标。 zvt 当前绩效评估能力较弱，没有标准化的 Analyzer 接口；借鉴此模式可让用户 cerebro.addanalyzer(SharpeRatio) 即得风险调整收益报告。 ## `CW-BT-003` — Sizer 仓位管理分离 **From**: backtrader · **Applicable to**: backtesting backtrader 将仓位管理（每次开仓买多少股/多大比例）单独抽象为 Sizer，与信号逻辑完全解耦；内置 FixedSize、PercentSizer 等，用户可自定义。 zvt 目前没有显式的 Sizer 概念，仓位控制逻辑散落在 Trader.on_profit_control 等钩子中；引入 Sizer 接口可使策略信号与资金管理规则独立演化和组合复用。 ## `CW-BT-004` — Order 类型全集（Limit/Stop/OCO/Bracket） **From**: backtrader · **Applicable to**: backtesting backtrader 支持 Market、Limit、Stop、StopLimit、OCO（二选一）、 Bracket（止盈止损一对订单）等丰富订单类型，并模拟成交滑点和手续费方案。 zvt 回测目前主要支持市价成交，缺乏限价委托和组合订单模拟；对于高频或实盘对接场景，完善订单类型将大幅提升回测真实性。 ## `CW-BT-005` — 数据重采样与重播（Resampling & Replaying） **From**: backtrader · **Applicable to**: backtesting backtrader 可将低级别数据（如 1 min）实时 resample 为高级别（如 1 day）并同步驱动策略，或 replay 逐 tick 模拟 OHLC 形成过程，实现日内精细回测。 zvt 目前多时间框架通过预录入不同级别 K 线实现，缺少运行时动态重采样；借鉴此模式可在不重复录入数据的前提下支持任意时间粒度组合回测。 ## `CW-VN-001` — 事件驱动引擎 (EventEngine) **From**: vnpy · **Applicable to**: live-trading vnpy 的核心是一个异步事件总线（EventEngine），行情推送、委托回报、成交通知等均以事件消息方式在各 App/Gateway 间流转，天然支持实盘+回测同一套代码逻辑。 zvt 目前数据流是同步批量拉取，缺乏事件驱动架构；对接实盘行情推送（如 WebSocket tick 流）时，事件驱动模式可大幅降低延迟。 ## `CW-VN-002` — Gateway 多交易所统一接口抽象 **From**: vnpy · **Applicable to**: live-trading vnpy 的 Gateway 层对 CTP 期货、XTP 证券、IB 等几十个交易接口做统一封装，策略层只调用 buy/sell/cancel 通用接口，无需感知底层协议差异。 zvt 目前数据录入依赖具体 provider（em/joinquant），无统一的实盘交易 Gateway；引入 Gateway 抽象可使 zvt 的因子+选股逻辑无缝对接实盘下单。 ## `CW-VN-003` — CTA 回测引擎内置可视化 **From**: vnpy · **Applicable to**: backtesting vnpy 的 cta_backtester 提供图形界面直接展示策略净值曲线、最大回撤、每日盈亏、成交明细，无需 Jupyter Notebook。 zvt 目前回测结果可视化依赖 draw_result 方法调用 Plotly，但无统一的回测报告页面；借鉴此模式可打包一个开箱即用的策略绩效仪表盘。 ## `CW-VN-004` — vnpy.alpha ML 因子研究实验室（Lab） **From**: vnpy · **Applicable to**: factor-research vnpy 4.0 的 vnpy.alpha.lab 提供数据管理、模型训练、信号生成、策略回测一体化工作流，支持 Lasso/LightGBM/MLP 等算法的标准化训练接口和可视化对比。 zvt 的 ML 能力目前仅有 MaStockMLMachine 一个入口，缺乏规范化 Lab 框架；借鉴 Lab 模式可建立"特征工程→训练→信号→回测"的标准流水线，降低 ML 实验门槛。 ## `CW-VN-005` — 价差交易（Spread Trading）模块 **From**: vnpy · **Applicable to**: live-trading vnpy 支持自定义价差（如期货跨期套利、A股与港股溢价套利），实时计算价差行情、自动触发价差策略委托。 zvt 目前 compare() 只做可视化对比，缺乏价差信号计算和交易执行；借鉴价差模块可扩展 zvt 到统计套利场景（如 AH 溢价、指数与成份股套利）。 ## `CW-QL-001` — Point-in-Time 数据库（防未来数据泄漏） **From**: qlib · **Applicable to**: backtesting qlib 的 Point-in-Time Provider 保证在给定时间点 t 的查询只返回 t 时刻真实可知的数据（财报发布延迟、修订历史均被正确处理），彻底消除回测中的 look-ahead bias。 zvt 目前财务数据以报告期为 timestamp，缺少"发布日"维度，存在用未来财报数据做选股的潜在偏差；引入 PIT 模式可大幅提升回测可信度。 ## `CW-QL-002` — Recorder + Experiment 实验管理（MLflow 风格） **From**: qlib · **Applicable to**: factor-research qlib 的 workflow 模块提供 Experiment/Recorder，自动记录每次模型训练的超参数、特征、指标、预测结果，支持跨实验比较和模型版本管理。 zvt 目前缺乏 ML 实验追踪机制，每次重跑结果会覆盖前次；借鉴 Recorder 模式可将每次因子实验的参数和结果持久化，支持快速复现和版本对比。 ## `CW-QL-003` — Nested Decision Framework（多层嵌套决策执行） **From**: qlib · **Applicable to**: backtesting qlib 支持将高频执行层（分钟级委托拆单）嵌套在低频决策层（日级组合调仓）中，两层独立优化且可组合运行，实现日内最优执行算法（如 TWAP、VWAP 调仓）。 zvt 目前回测仅有日线级别的成交假设，缺乏执行算法建模；借鉴嵌套框架可让 zvt 区分"何时持有哪些股"与"如何以最小冲击成本建仓"两个问题。 ## `CW-BT-001` — Cerebro 统一编排引擎 **From**: backtrader · **Applicable to**: backtesting backtrader 用 Cerebro 作为单一入口，统一管理 data feeds、strategies、analyzers、 observers 的生命周期，支持一次 cerebro.run() 跑多策略+多数据源。 zvt 的 StockTrader 目前每次实例化只绑定一套因子，缺乏统一的多策略组合编排层；借鉴 Cerebro 模式可让用户把多个 Trader 实例组合到一个 runner 中对比评估。 ## `CW-BT-002` — Analyzer 插件化绩效评估 **From**: backtrader · **Applicable to**: backtesting backtrader 提供 SharpeRatio、DrawDown、TimeReturn、TradeAnalyzer 等即插即用的 Analyzer，可在不修改策略代码的情况下附加任意绩效指标。 zvt 当前绩效评估能力较弱，没有标准化的 Analyzer 接口；借鉴此模式可让用户 cerebro.addanalyzer(SharpeRatio) 即得风险调整收益报告。 ## `CW-BT-003` — Sizer 仓位管理分离 **From**: backtrader · **Applicable to**: backtesting backtrader 将仓位管理（每次开仓买多少股/多大比例）单独抽象为 Sizer，与信号逻辑完全解耦；内置 FixedSize、PercentSizer 等，用户可自定义。 zvt 目前没有显式的 Sizer 概念，仓位控制逻辑散落在 Trader.on_profit_control 等钩子中；引入 Sizer 接口可使策略信号与资金管理规则独立演化和组合复用。 ## `CW-BT-004` — Order 类型全集（Limit/Stop/OCO/Bracket） **From**: backtrader · **Applicable to**: backtesting backtrader 支持 Market、Limit、Stop、StopLimit、OCO（二选一）、 Bracket（止盈止损一对订单）等丰富订单类型，并模拟成交滑点和手续费方案。 zvt 回测目前主要支持市价成交，缺乏限价委托和组合订单模拟；对于高频或实盘对接场景，完善订单类型将大幅提升回测真实性。 ## `CW-BT-005` — 数据重采样与重播（Resampling & Replaying） **From**: backtrader · **Applicable to**: backtesting backtrader 可将低级别数据（如 1 min）实时 resample 为高级别（如 1 day）并同步驱动策略，或 replay 逐 tick 模拟 OHLC 形成过程，实现日内精细回测。 zvt 目前多时间框架通过预录入不同级别 K 线实现，缺少运行时动态重采样；借鉴此模式可在不重复录入数据的前提下支持任意时间粒度组合回测。 ## `CW-VN-003` — CTA 回测引擎内置可视化 **From**: vnpy · **Applicable to**: backtesting vnpy 的 cta_backtester 提供图形界面直接展示策略净值曲线、最大回撤、每日盈亏、成交明细，无需 Jupyter Notebook。 zvt 目前回测结果可视化依赖 draw_result 方法调用 Plotly，但无统一的回测报告页面；借鉴此模式可打包一个开箱即用的策略绩效仪表盘。 ## `CW-VN-004` — vnpy.alpha ML 因子研究实验室（Lab） **From**: vnpy · **Applicable to**: factor-research vnpy 4.0 的 vnpy.alpha.lab 提供数据管理、模型训练、信号生成、策略回测一体化工作流，支持 Lasso/LightGBM/MLP 等算法的标准化训练接口和可视化对比。 zvt 的 ML 能力目前仅有 MaStockMLMachine 一个入口，缺乏规范化 Lab 框架；借鉴 Lab 模式可建立"特征工程→训练→信号→回测"的标准流水线，降低 ML 实验门槛。 ## `CW-QL-001` — Point-in-Time 数据库（防未来数据泄漏） **From**: qlib · **Applicable to**: backtesting qlib 的 Point-in-Time Provider 保证在给定时间点 t 的查询只返回 t 时刻真实可知的数据（财报发布延迟、修订历史均被正确处理），彻底消除回测中的 look-ahead bias。 zvt 目前财务数据以报告期为 timestamp，缺少"发布日"维度，存在用未来财报数据做选股的潜在偏差；引入 PIT 模式可大幅提升回测可信度。 ## `CW-QL-002` — Recorder + Experiment 实验管理（MLflow 风格） **From**: qlib · **Applicable to**: factor-research qlib 的 workflow 模块提供 Experiment/Recorder，自动记录每次模型训练的超参数、特征、指标、预测结果，支持跨实验比较和模型版本管理。 zvt 目前缺乏 ML 实验追踪机制，每次重跑结果会覆盖前次；借鉴 Recorder 模式可将每次因子实验的参数和结果持久化，支持快速复现和版本对比。 ## `CW-QL-003` — Nested Decision Framework（多层嵌套决策执行） **From**: qlib · **Applicable to**: backtesting qlib 支持将高频执行层（分钟级委托拆单）嵌套在低频决策层（日级组合调仓）中，两层独立优化且可组合运行，实现日内最优执行算法（如 TWAP、VWAP 调仓）。 zvt 目前回测仅有日线级别的成交假设，缺乏执行算法建模；借鉴嵌套框架可让 zvt 区分"何时持有哪些股"与"如何以最小冲击成本建仓"两个问题。 FILE:references/components/api.md # api (2 classes) ## `WindowMethod` `api/stats.py:28` ## `TopType` `api/stats.py:34` FILE:references/components/broker.md # broker (6 classes) ## `QmtContext` `broker/qmt/context.py:8` ## `TraderError` `broker/qmt/errors.py:2` > Base class for exceptions in this module. ## `QmtError` `broker/qmt/errors.py:8` ## `PositionOverflowError` `broker/qmt/errors.py:13` ## `MyXtQuantTraderCallback` `broker/qmt/qmt_account.py:26` ## `QmtStockAccount` `broker/qmt/qmt_account.py:107` FILE:references/components/common.md # common (9 classes) ## `OrderByType` `common/query_models.py:9` ## `TimeUnit` `common/query_models.py:14` ## `AbsoluteTimeRange` `common/query_models.py:23` ## `RelativeTimeRage` `common/query_models.py:28` ## `TimeRange` `common/query_models.py:33` ## `PositionType` `common/trading_models.py:8` ## `BuyParameter` `common/trading_models.py:17` ## `SellParameter` `common/trading_models.py:25` ## `TradingResult` `common/trading_models.py:30` FILE:references/components/contract.md # contract (53 classes) ## `IntervalLevel` `contract/__init__.py:5` > Repeated fixed time interval, e.g, 5m, 1d. ## `AdjustType` `contract/__init__.py:121` > split-adjusted type for :class:`~.zvt.contract.schema.TradableEntity` quotes ## `ActorType` `contract/__init__.py:138` ## `TradableType` `contract/__init__.py:159` ## `Exchange` `contract/__init__.py:203` ## `StatefulService` `contract/base_service.py:10` > Base service with state could be stored in state_schema ## `OneStateService` `contract/base_service.py:65` > StatefulService which saving all states in one object ## `EntityStateService` `contract/base_service.py:87` > StatefulService which saving one state one entity ## `Registry` `contract/context.py:13` > Class storing zvt registering meta ## `Bean` `contract/data_type.py:4` ## `ChartType` `contract/drawer.py:20` > Chart type enum ## `Rect` `contract/drawer.py:45` > rect struct with left-bottom(x0, y0), right-top(x1, y1) ## `Draw` `contract/drawer.py:61` ## `Drawable` `contract/drawer.py:231` ## `StackedDrawer` `contract/drawer.py:296` ## `Drawer` `contract/drawer.py:407` ## `TargetType` `contract/factor.py:22` ## `Indicator` `contract/factor.py:28` ## `Transformer` `contract/factor.py:34` ## `Accumulator` `contract/factor.py:82` ## `Scorer` `contract/factor.py:163` ## `FactorMeta` `contract/factor.py:181` ## `Factor` `contract/factor.py:188` ## `ScoreFactor` `contract/factor.py:667` ## `CustomModel` `contract/model.py:7` ## `MixinModel` `contract/model.py:11` ## `NormalData` `contract/normal_data.py:6` ## `DataListener` `contract/reader.py:16` ## `DataReader` `contract/reader.py:40` ## `Meta` `contract/recorder.py:71` ## `Recorder` `contract/recorder.py:91` ## `EntityEventRecorder` `contract/recorder.py:147` ## `TimeSeriesDataRecorder` `contract/recorder.py:245` ## `FixedCycleDataRecorder` `contract/recorder.py:612` ## `TimestampsDataRecorder` `contract/recorder.py:712` ## `RouteRegistry` `contract/route_registry.py:28` > Maps (provider, db_name) or (provider, data_schema) to storage_id. ## `Mixin` `contract/schema.py:34` > Base class of schema. ## `NormalMixin` `contract/schema.py:326` ## `Entity` `contract/schema.py:333` ## `TradableEntity` `contract/schema.py:348` > tradable entity ## `ActorEntity` `contract/schema.py:534` ## `NormalEntityMixin` `contract/schema.py:538` ## `Portfolio` `contract/schema.py:545` > composition of tradable entities ## `PortfolioStock` `contract/schema.py:580` ## `PortfolioStockHistory` `contract/schema.py:596` ## `TradableMeetActor` `contract/schema.py:613` ## `ActorMeetTradable` `contract/schema.py:626` ## `StorageBackend` `contract/storage.py:38` > Abstract storage backend. Decouples physical storage from domain/read/record logic. ## `SqliteStorageBackend` `contract/storage.py:65` > SQLite storage backend. Default path: {data_path}/{provider}/{provider}_{db_name}.db ## `StateMixin` `contract/zvt_info.py:11` ## `RecorderState` `contract/zvt_info.py:19` > Schema for storing recorder state ## `TaggerState` `contract/zvt_info.py:27` > Schema for storing tagger state ## `FactorState` `contract/zvt_info.py:35` > Schema for storing factor state FILE:references/components/domain.md # domain (114 classes) ## `BlockCategory` `domain/__init__.py:5` ## `IndexCategory` `domain/__init__.py:14` ## `ReportPeriod` `domain/__init__.py:48` ## `CompanyType` `domain/__init__.py:59` ## `ActorMeta` `domain/actor/actor_meta.py:12` ## `StockTopTenFreeHolder` `domain/actor/stock_actor.py:11` ## `StockTopTenHolder` `domain/actor/stock_actor.py:25` ## `StockInstitutionalInvestorHolder` `domain/actor/stock_actor.py:39` ## `StockActorSummary` `domain/actor/stock_actor.py:53` ## `LimitUpInfo` `domain/emotion/emotion.py:11` ## `LimitDownInfo` `domain/emotion/emotion.py:46` ## `Emotion` `domain/emotion/emotion.py:63` ## `DividendFinancing` `domain/fundamental/dividend_financing.py:11` ## `DividendDetail` `domain/fundamental/dividend_financing.py:32` ## `SpoDetail` `domain/fundamental/dividend_financing.py:49` ## `RightsIssueDetail` `domain/fundamental/dividend_financing.py:60` ## `BalanceSheet` `domain/fundamental/finance.py:11` ## `IncomeStatement` `domain/fundamental/finance.py:460` ## `CashFlowStatement` `domain/fundamental/finance.py:629` ## `FinanceFactor` `domain/fundamental/finance.py:831` ## `ManagerTrading` `domain/fundamental/trading.py:11` ## `HolderTrading` `domain/fundamental/trading.py:37` ## `BigDealTrading` `domain/fundamental/trading.py:53` ## `MarginTrading` `domain/fundamental/trading.py:71` ## `DragonAndTiger` `domain/fundamental/trading.py:91` ## `StockValuation` `domain/fundamental/valuation.py:11` ## `EtfValuation` `domain/fundamental/valuation.py:38` ## `Economy` `domain/macro/macro.py:11` ## `TreasuryYield` `domain/macro/monetary.py:11` ## `Block` `domain/meta/block_meta.py:14` ## `BlockStock` `domain/meta/block_meta.py:21` ## `Blockus` `domain/meta/blockus_meta.py:14` ## `BlockusStockus` `domain/meta/blockus_meta.py:21` ## `CBond` `domain/meta/cbond_meta.py:13` ## `Country` `domain/meta/country_meta.py:13` ## `Currency` `domain/meta/currency_meta.py:12` ## `Etf` `domain/meta/etf_meta.py:15` ## `EtfStock` `domain/meta/etf_meta.py:26` ## `Fund` `domain/meta/fund_meta.py:14` ## `FundStock` `domain/meta/fund_meta.py:53` ## `Future` `domain/meta/future_meta.py:11` ## `Index` `domain/meta/index_meta.py:14` ## `IndexStock` `domain/meta/index_meta.py:26` ## `Indexhk` `domain/meta/indexhk_meta.py:14` ## `Indexus` `domain/meta/indexus_meta.py:14` ## `Stock` `domain/meta/stock_meta.py:14` ## `StockDetail` `domain/meta/stock_meta.py:32` ## `Stockhk` `domain/meta/stockhk_meta.py:13` ## `Stockus` `domain/meta/stockus_meta.py:14` ## `HkHolder` `domain/misc/holder.py:11` ## `TopTenTradableHolder` `domain/misc/holder.py:29` ## `TopTenHolder` `domain/misc/holder.py:52` ## `InstitutionalInvestorHolder` `domain/misc/holder.py:75` ## `BlockMoneyFlow` `domain/misc/money_flow.py:14` ## `StockMoneyFlow` `domain/misc/money_flow.py:48` ## `IndexMoneyFlow` `domain/misc/money_flow.py:82` ## `StockSummary` `domain/misc/overall.py:14` ## `MarginTradingSummary` `domain/misc/overall.py:33` ## `CrossMarketSummary` `domain/misc/overall.py:56` ## `StockNews` `domain/misc/stock_news.py:11` ## `StockHotTopic` `domain/misc/stock_news.py:28` ## `KdataCommon` `domain/quotes/__init__.py:7` ## `TickCommon` `domain/quotes/__init__.py:33` ## `BlockKdataCommon` `domain/quotes/__init__.py:60` ## `IndexKdataCommon` `domain/quotes/__init__.py:64` ## `IndexhkKdataCommon` `domain/quotes/__init__.py:68` ## `IndexusKdataCommon` `domain/quotes/__init__.py:72` ## `EtfKdataCommon` `domain/quotes/__init__.py:76` ## `StockKdataCommon` `domain/quotes/__init__.py:83` ## `StockusKdataCommon` `domain/quotes/__init__.py:90` ## `StockhkKdataCommon` `domain/quotes/__init__.py:97` ## `FutureKdataCommon` `domain/quotes/__init__.py:102` ## `CurrencyKdataCommon` `domain/quotes/__init__.py:113` ## `Block1dKdata` `domain/quotes/block/block_1d_kdata.py:11` ## `Block1monKdata` `domain/quotes/block/block_1mon_kdata.py:11` ## `Block1wkKdata` `domain/quotes/block/block_1wk_kdata.py:11` ## `Currency1dKdata` `domain/quotes/currency/currency_1d_kdata.py:11` ## `Etf1dKdata` `domain/quotes/etf/etf_1d_kdata.py:11` ## `Future1dKdata` `domain/quotes/future/future_1d_kdata.py:11` ## `Index1dKdata` `domain/quotes/index/index_1d_kdata.py:11` ## `Index1mKdata` `domain/quotes/index/index_1m_kdata.py:12` ## `Index1wkKdata` `domain/quotes/index/index_1wk_kdata.py:11` ## `Indexhk1dKdata` `domain/quotes/indexhk/indexhk_1d_kdata.py:11` ## `Indexus1dKdata` `domain/quotes/indexus/indexus_1d_kdata.py:11` ## `Stock15mHfqKdata` `domain/quotes/stock/stock_15m_hfq_kdata.py:11` ## `Stock15mKdata` `domain/quotes/stock/stock_15m_kdata.py:11` ## `Stock1dHfqKdata` `domain/quotes/stock/stock_1d_hfq_kdata.py:11` ## `Stock1dKdata` `domain/quotes/stock/stock_1d_kdata.py:11` ## `Stock1hHfqKdata` `domain/quotes/stock/stock_1h_hfq_kdata.py:11` ## `Stock1hKdata` `domain/quotes/stock/stock_1h_kdata.py:11` ## `Stock1mHfqKdata` `domain/quotes/stock/stock_1m_hfq_kdata.py:11` ## `Stock1mKdata` `domain/quotes/stock/stock_1m_kdata.py:11` ## `Stock1monHfqKdata` `domain/quotes/stock/stock_1mon_hfq_kdata.py:11` ## `Stock1monKdata` `domain/quotes/stock/stock_1mon_kdata.py:11` ## `Stock1wkHfqKdata` `domain/quotes/stock/stock_1wk_hfq_kdata.py:11` ## `Stock1wkKdata` `domain/quotes/stock/stock_1wk_kdata.py:11` ## `Stock30mHfqKdata` `domain/quotes/stock/stock_30m_hfq_kdata.py:11` ## `Stock30mKdata` `domain/quotes/stock/stock_30m_kdata.py:11` ## `Stock4hHfqKdata` `domain/quotes/stock/stock_4h_hfq_kdata.py:11` ## `Stock4hKdata` `domain/quotes/stock/stock_4h_kdata.py:11` ## `Stock5mHfqKdata` `domain/quotes/stock/stock_5m_hfq_kdata.py:11` ## `Stock5mKdata` `domain/quotes/stock/stock_5m_kdata.py:11` ## `StockQuote` `domain/quotes/stock/stock_quote.py:12` ## `Stock1mQuote` `domain/quotes/stock/stock_quote.py:32` ## `StockQuoteLog` `domain/quotes/stock/stock_quote_log.py:11` ## `Stockhk1dHfqKdata` `domain/quotes/stockhk/stockhk_1d_hfq_kdata.py:11` ## `Stockhk1dKdata` `domain/quotes/stockhk/stockhk_1d_kdata.py:11` ## `StockhkQuote` `domain/quotes/stockhk/stockhk_quote.py:12` ## `Stockhk1mQuote` `domain/quotes/stockhk/stockhk_quote.py:36` ## `Stockus1dHfqKdata` `domain/quotes/stockus/stockus_1d_hfq_kdata.py:11` ## `Stockus1dKdata` `domain/quotes/stockus/stockus_1d_kdata.py:11` ## `StockusQuote` `domain/quotes/stockus/stockus_quote.py:12` ## `Stockus1mQuote` `domain/quotes/stockus/stockus_quote.py:36` ## `StockTradeDay` `domain/quotes/trade_day.py:10` FILE:references/components/factors.md # factors (54 classes) ## `RankScorer` `factors/algorithm.py:141` ## `MaTransformer` `factors/algorithm.py:150` ## `IntersectTransformer` `factors/algorithm.py:193` ## `MaAndVolumeTransformer` `factors/algorithm.py:224` ## `MacdTransformer` `factors/algorithm.py:269` ## `QuantileScorer` `factors/algorithm.py:311` ## `FactorRequestModel` `factors/factor_models.py:12` ## `TradingSignalModel` `factors/factor_models.py:20` ## `FactorResultModel` `factors/factor_models.py:31` ## `FinanceBaseFactor` `factors/fundamental/finance_factor.py:13` ## `GoodCompanyFactor` `factors/fundamental/finance_factor.py:77` ## `MaStatsFactorCommon` `factors/ma/domain/common.py:7` ## `Stock1dMaFactor` `factors/ma/domain/stock_1d_ma_factor.py:11` ## `Stock1dMaStatsFactor` `factors/ma/domain/stock_1d_ma_stats_factor.py:10` ## `MaFactor` `factors/ma/ma_factor.py:24` ## `CrossMaFactor` `factors/ma/ma_factor.py:93` ## `VolumeUpMaFactor` `factors/ma/ma_factor.py:107` ## `CrossMaVolumeFactor` `factors/ma/ma_factor.py:233` ## `MaStatsAccumulator` `factors/ma/ma_stats_factor.py:24` ## `MaStatsFactor` `factors/ma/ma_stats_factor.py:71` ## `TFactor` `factors/ma/ma_stats_factor.py:147` ## `TopBottomTransformer` `factors/ma/top_bottom_factor.py:17` ## `TopBottomFactor` `factors/ma/top_bottom_factor.py:34` ## `MacdFactor` `factors/macd/macd_factor.py:11` ## `BullFactor` `factors/macd/macd_factor.py:24` ## `KeepBullFactor` `factors/macd/macd_factor.py:30` ## `LiveOrDeadFactor` `factors/macd/macd_factor.py:46` ## `GoldCrossFactor` `factors/macd/macd_factor.py:56` ## `Direction` `factors/shape.py:17` ## `Fenxing` `factors/shape.py:28` ## `FactorStateEncoder` `factors/shape.py:220` ## `TradeType` `factors/target_selector.py:16` ## `SelectMode` `factors/target_selector.py:25` ## `TargetSelector` `factors/target_selector.py:30` ## `TechnicalFactor` `factors/technical_factor.py:11` ## `TopStocks` `factors/top_stocks.py:38` ## `CrossMaTransformer` `factors/transformers.py:26` ## `SpecificTransformer` `factors/transformers.py:42` ## `FallBelowTransformer` `factors/transformers.py:55` ## `FactorStateEncoder` `factors/zen/base_factor.py:38` ## `ZenState` `factors/zen/base_factor.py:64` ## `ZenAccumulator` `factors/zen/base_factor.py:152` ## `ZenFactor` `factors/zen/base_factor.py:619` ## `ZenFactorCommon` `factors/zen/domain/common.py:7` ## `Index1dZenFactor` `factors/zen/domain/index_1d_zen_factor.py:10` ## `Stock1dZenFactor` `factors/zen/domain/stock_1d_zen_factor.py:10` ## `Stock1wkZenFactor` `factors/zen/domain/stock_1wk_zen_factor.py:10` ## `ZhongshuRange` `factors/zen/zen_factor.py:28` ## `ZhongshuLevel` `factors/zen/zen_factor.py:42` ## `ZhongshuDistance` `factors/zen/zen_factor.py:60` ## `Zhongshu` `factors/zen/zen_factor.py:81` ## `ZenState` `factors/zen/zen_factor.py:118` ## `TrendingFactor` `factors/zen/zen_factor.py:253` ## `ShakingFactor` `factors/zen/zen_factor.py:338` FILE:references/components/informer.md # informer (4 classes) ## `Informer` `informer/informer.py:17` ## `EmailInformer` `informer/informer.py:22` ## `WechatInformer` `informer/informer.py:95` ## `QiyeWechatBot` `informer/informer.py:162` FILE:references/components/misc.md # misc (2 classes) ## `TimeMessage` `misc/misc_models.py:7` ## `ZhDate` `misc/zhdate.py:11` FILE:references/components/ml.md # ml (5 classes) ## `BehaviorCategory` `ml/lables.py:5` ## `RelativePerformance` `ml/lables.py:12` ## `MLMachine` `ml/ml.py:46` ## `StockMLMachine` `ml/ml.py:208` ## `MaStockMLMachine` `ml/ml.py:212` FILE:references/components/recorders.md # recorders (90 classes) ## `ApiWrapper` `recorders/eastmoney/common.py:15` ## `EastmoneyApiWrapper` `recorders/eastmoney/common.py:101` ## `BaseEastmoneyRecorder` `recorders/eastmoney/common.py:106` ## `EastmoneyTimestampsDataRecorder` `recorders/eastmoney/common.py:140` ## `EastmoneyPageabeDataRecorder` `recorders/eastmoney/common.py:163` ## `EastmoneyMoreDataRecorder` `recorders/eastmoney/common.py:201` ## `DividendDetailRecorder` `recorders/eastmoney/dividend_financing/eastmoney_dividend_detail_recorder.py:7` ## `DividendFinancingRecorder` `recorders/eastmoney/dividend_financing/eastmoney_dividend_financing_recorder.py:7` ## `RightsIssueDetailRecorder` `recorders/eastmoney/dividend_financing/eastmoney_rights_issue_detail_recorder.py:10` ## `SPODetailRecorder` `recorders/eastmoney/dividend_financing/eastmoney_spo_detail_recorder.py:9` ## `BaseChinaStockFinanceRecorder` `recorders/eastmoney/finance/base_china_stock_finance_recorder.py:36` ## `ChinaStockBalanceSheetRecorder` `recorders/eastmoney/finance/eastmoney_balance_sheet_recorder.py:433` ## `ChinaStockCashFlowRecorder` `recorders/eastmoney/finance/eastmoney_cash_flow_recorder.py:176` ## `ChinaStockFinanceFactorRecorder` `recorders/eastmoney/finance/eastmoney_finance_factor_recorder.py:144` ## `ChinaStockIncomeStatementRecorder` `recorders/eastmoney/finance/eastmoney_income_statement_recorder.py:158` ## `EastmoneyActorRecorder` `recorders/eastmoney/holder/eastmoney_stock_actor_recorder.py:10` ## `TopTenHolderRecorder` `recorders/eastmoney/holder/eastmoney_top_ten_holder_recorder.py:9` ## `TopTenTradableHolderRecorder` `recorders/eastmoney/holder/eastmoney_top_ten_tradable_holder_recorder.py:6` ## `EastmoneyBlockRecorder` `recorders/eastmoney/meta/eastmoney_block_meta_recorder.py:14` ## `EastmoneyBlockStockRecorder` `recorders/eastmoney/meta/eastmoney_block_meta_recorder.py:52` ## `EastmoneyStockRecorder` `recorders/eastmoney/meta/eastmoney_stock_meta_recorder.py:13` ## `EastmoneyStockDetailRecorder` `recorders/eastmoney/meta/eastmoney_stock_meta_recorder.py:18` ## `HolderTradingRecorder` `recorders/eastmoney/trading/eastmoney_holder_trading_recorder.py:7` ## `ManagerTradingRecorder` `recorders/eastmoney/trading/eastmoney_manager_trading_recorder.py:7` ## `EMStockActorSummaryRecorder` `recorders/em/actor/em_stock_actor_summary_recorder.py:28` ## `EMStockIIRecorder` `recorders/em/actor/em_stock_ii_recorder.py:39` ## `EMStockTopTenFreeRecorder` `recorders/em/actor/em_stock_top_ten_free_recorder.py:16` ## `EMStockTopTenRecorder` `recorders/em/actor/em_stock_top_ten_recorder.py:16` ## `EMTreasuryYieldRecorder` `recorders/em/macro/em_treasury_yield_recorder.py:12` ## `EMBlockRecorder` `recorders/em/meta/em_block_meta_recorder.py:10` ## `EMBlockStockRecorder` `recorders/em/meta/em_block_meta_recorder.py:21` ## `EMCBondRecorder` `recorders/em/meta/em_cbond_meta_recorder.py:9` ## `EMCurrencyRecorder` `recorders/em/meta/em_currency_meta_recorder.py:9` ## `EMFutureRecorder` `recorders/em/meta/em_future_meta_recorder.py:9` ## `EMIndexRecorder` `recorders/em/meta/em_index_meta_recorder.py:9` ## `EMIndexhkRecorder` `recorders/em/meta/em_indexhk_meta_recorder.py:9` ## `EMIndexusRecorder` `recorders/em/meta/em_indexus_meta_recorder.py:9` ## `EMStockRecorder` `recorders/em/meta/em_stock_meta_recorder.py:13` ## `EMStockhkRecorder` `recorders/em/meta/em_stockhk_meta_recorder.py:12` ## `EMStockusRecorder` `recorders/em/meta/em_stockus_meta_recorder.py:12` ## `EMStockNewsRecorder` `recorders/em/misc/em_stock_news_recorder.py:12` ## `BaseEMStockKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:33` ## `EMStockKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:170` ## `EMStockusKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:200` ## `EMStockhkKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:208` ## `EMIndexhkKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:216` ## `EMIndexKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:223` ## `EMIndexusKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:230` ## `EMBlockKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:237` ## `EMFutureKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:244` ## `EMCurrencyKdataRecorder` `recorders/em/quotes/em_kdata_recorder.py:251` ## `EMDragonAndTigerRecorder` `recorders/em/trading/em_dragon_and_tiger_recorder.py:12` ## `ChinaETFListSpider` `recorders/exchange/exchange_etf_meta_recorder.py:18` ## `ExchangeIndexRecorder` `recorders/exchange/exchange_index_recorder.py:9` ## `ExchangeIndexStockRecorder` `recorders/exchange/exchange_index_stock_recorder.py:15` ## `ExchangeStockMetaRecorder` `recorders/exchange/exchange_stock_meta_recorder.py:15` ## `ExchangeStockSummaryRecorder` `recorders/exchange/exchange_stock_summary_recorder.py:13` ## `JqChinaEtfValuationRecorder` `recorders/joinquant/fundamental/jq_etf_valuation_recorder.py:12` ## `MarginTradingRecorder` `recorders/joinquant/fundamental/jq_margin_trading_recorder.py:14` ## `JqChinaStockValuationRecorder` `recorders/joinquant/fundamental/jq_stock_valuation_recorder.py:14` ## `JqChinaFundRecorder` `recorders/joinquant/meta/jq_fund_meta_recorder.py:15` ## `JqChinaFundStockRecorder` `recorders/joinquant/meta/jq_fund_meta_recorder.py:72` ## `BaseJqChinaMetaRecorder` `recorders/joinquant/meta/jq_stock_meta_recorder.py:15` ## `JqChinaStockRecorder` `recorders/joinquant/meta/jq_stock_meta_recorder.py:44` ## `JqChinaEtfRecorder` `recorders/joinquant/meta/jq_stock_meta_recorder.py:58` ## `JqChinaStockEtfPortfolioRecorder` `recorders/joinquant/meta/jq_stock_meta_recorder.py:70` ## `StockTradeDayRecorder` `recorders/joinquant/meta/jq_trade_day_recorder.py:11` ## `JoinquantHkHolderRecorder` `recorders/joinquant/misc/jq_hk_holder_recorder.py:20` ## `JoinquantIndexMoneyFlowRecorder` `recorders/joinquant/misc/jq_index_money_flow_recorder.py:12` ## `JoinquantStockMoneyFlowRecorder` `recorders/joinquant/misc/jq_stock_money_flow_recorder.py:17` ## `CrossMarketSummaryRecorder` `recorders/joinquant/overall/jq_cross_market_recorder.py:9` ## `MarginTradingSummaryRecorder` `recorders/joinquant/overall/jq_margin_trading_recorder.py:14` ## `StockSummaryRecorder` `recorders/joinquant/overall/jq_stock_summary_recorder.py:21` ## `JqChinaIndexKdataRecorder` `recorders/joinquant/quotes/jq_index_kdata_recorder.py:18` ## `JqChinaStockKdataRecorder` `recorders/joinquant/quotes/jq_stock_kdata_recorder.py:17` ## `JqkaLimitUpRecorder` `recorders/jqka/emotion/JqkaEmotionRecorder.py:24` ## `JqkaLimitDownRecorder` `recorders/jqka/emotion/JqkaEmotionRecorder.py:99` ## `JqkaEmotionRecorder` `recorders/jqka/emotion/JqkaEmotionRecorder.py:163` ## `QmtIndexRecorder` `recorders/qmt/index/qmt_index_recorder.py:16` ## `QMTStockRecorder` `recorders/qmt/meta/qmt_stock_meta_recorder.py:9` ## `BaseQmtKdataRecorder` `recorders/qmt/quotes/qmt_kdata_recorder.py:17` ## `QMTStockKdataRecorder` `recorders/qmt/quotes/qmt_kdata_recorder.py:169` ## `SinaBlockRecorder` `recorders/sina/meta/sina_block_recorder.py:15` ## `SinaChinaBlockStockRecorder` `recorders/sina/meta/sina_block_recorder.py:59` ## `SinaBlockMoneyFlowRecorder` `recorders/sina/money_flow/sina_block_money_flow_recorder.py:17` ## `SinaStockMoneyFlowRecorder` `recorders/sina/money_flow/sina_stock_money_flow_recorder.py:12` ## `ChinaETFDayKdataRecorder` `recorders/sina/quotes/sina_etf_kdata_recorder.py:16` ## `ChinaIndexDayKdataRecorder` `recorders/sina/quotes/sina_index_kdata_recorder.py:15` ## `WBCountryRecorder` `recorders/wb/wb_country_recorder.py:9` ## `WBEconomyRecorder` `recorders/wb/wb_economy_recorder.py:10` FILE:references/components/samples.md # samples (2 classes) ## `MyMaTrader` `samples/stock_traders.py:8` ## `MyBullTrader` `samples/stock_traders.py:27` FILE:references/components/tag.md # tag (42 classes) ## `StockPoolType` `tag/common.py:5` ## `DynamicPoolType` `tag/common.py:11` ## `InsertMode` `tag/common.py:16` ## `TagType` `tag/common.py:21` ## `TagStatsQueryType` `tag/common.py:28` ## `TagInfoModel` `tag/tag_models.py:12` ## `CreateTagInfoModel` `tag/tag_models.py:18` ## `IndustryInfoModel` `tag/tag_models.py:23` ## `MainTagIndustryRelation` `tag/tag_models.py:30` ## `BuildMainTagIndustryRelationModel` `tag/tag_models.py:35` ## `MainTagSubTagRelation` `tag/tag_models.py:41` ## `BuildMainTagSubTagRelationModel` `tag/tag_models.py:46` ## `ChangeMainTagModel` `tag/tag_models.py:52` ## `StockTagsModel` `tag/tag_models.py:57` ## `SimpleStockTagsModel` `tag/tag_models.py:71` ## `QueryStockTagsModel` `tag/tag_models.py:85` ## `QuerySimpleStockTagsModel` `tag/tag_models.py:89` ## `BatchSetStockTagsModel` `tag/tag_models.py:93` ## `TagParameter` `tag/tag_models.py:100` ## `StockTagOptions` `tag/tag_models.py:109` ## `SetStockTagsModel` `tag/tag_models.py:119` ## `StockPoolModel` `tag/tag_models.py:151` ## `StockPoolInfoModel` `tag/tag_models.py:156` ## `CreateStockPoolInfoModel` `tag/tag_models.py:161` ## `StockPoolsModel` `tag/tag_models.py:173` ## `CreateStockPoolsModel` `tag/tag_models.py:178` ## `QueryStockTagStatsModel` `tag/tag_models.py:193` ## `StockTagDetailsModel` `tag/tag_models.py:224` ## `StockTagStatsModel` `tag/tag_models.py:258` ## `ActivateSubTagsModel` `tag/tag_models.py:269` ## `ActivateSubTagsResultModel` `tag/tag_models.py:273` ## `IndustryInfo` `tag/tag_schemas.py:12` ## `MainTagInfo` `tag/tag_schemas.py:21` ## `SubTagInfo` `tag/tag_schemas.py:28` ## `HiddenTagInfo` `tag/tag_schemas.py:38` ## `StockTags` `tag/tag_schemas.py:45` > Schema for storing stock tags ## `StockSystemTags` `tag/tag_schemas.py:70` ## `StockPoolInfo` `tag/tag_schemas.py:100` ## `StockPools` `tag/tag_schemas.py:106` ## `TagStats` `tag/tag_schemas.py:115` ## `Tagger` `tag/tagger.py:16` ## `StockTagger` `tag/tagger.py:40` FILE:references/components/trader.md # trader (22 classes) ## `TradingSignalType` `trader/__init__.py:11` ## `OrderType` `trader/__init__.py:20` ## `TradingSignal` `trader/__init__.py:39` ## `TradingListener` `trader/__init__.py:77` ## `AccountService` `trader/__init__.py:94` ## `TraderError` `trader/errors.py:2` > Base class for exceptions in this module. ## `InvalidOrderParamError` `trader/errors.py:8` ## `NotEnoughMoneyError` `trader/errors.py:13` ## `NotEnoughPositionError` `trader/errors.py:18` ## `InvalidOrderError` `trader/errors.py:23` ## `WrongKdataError` `trader/errors.py:28` ## `SimAccountService` `trader/sim_account.py:25` ## `Trader` `trader/trader.py:26` ## `StockTrader` `trader/trader.py:535` ## `AccountStatsReader` `trader/trader_info_api.py:69` ## `OrderReader` `trader/trader_info_api.py:119` ## `PositionModel` `trader/trader_models.py:7` ## `AccountStatsModel` `trader/trader_models.py:32` ## `TraderInfo` `trader/trader_schemas.py:13` > trader info ## `AccountStats` `trader/trader_schemas.py:33` > account stats of every day ## `Position` `trader/trader_schemas.py:63` ## `Order` `trader/trader_schemas.py:97` FILE:references/components/trading.md # trading (19 classes) ## `ExecutionStatus` `trading/common.py:5` ## `KdataRequestModel` `trading/trading_models.py:19` ## `KdataModel` `trading/trading_models.py:28` ## `TSRequestModel` `trading/trading_models.py:36` ## `TSModel` `trading/trading_models.py:42` ## `QuoteStatsModel` `trading/trading_models.py:49` ## `QueryStockQuoteSettingModel` `trading/trading_models.py:70` ## `BuildQueryStockQuoteSettingModel` `trading/trading_models.py:75` ## `QueryTagQuoteModel` `trading/trading_models.py:87` ## `QueryStockQuoteModel` `trading/trading_models.py:92` ## `StockQuoteModel` `trading/trading_models.py:102` ## `TagQuoteStatsModel` `trading/trading_models.py:140` ## `StockQuoteStatsModel` `trading/trading_models.py:156` ## `TradingPlanModel` `trading/trading_models.py:173` ## `BuildTradingPlanModel` `trading/trading_models.py:193` ## `QueryTradingPlanModel` `trading/trading_models.py:214` ## `TagQuoteStats` `trading/trading_schemas.py:12` ## `TradingPlan` `trading/trading_schemas.py:24` ## `QueryStockQuoteSetting` `trading/trading_schemas.py:44`

A Stock Quant Lab

Comments (0)