dolphindb-report-factor-replication

name

dolphindb-report-factor-replication

description

Use when handling DolphinDB report factor analysis and replication tasks, including extracting candidate factors from research reports, extracting a single factor's logic and formula, auditing data-source fields, generating extraction JSON/scripts, choosing MR versus Execute mode, generating DolphinDB factor code, reusing built-in indicator modules, applying common factor replication patterns, and checking for look-ahead leakage or output-contract violations.

DolphinDB 研报因子复现

使用目标

将研报因子复现任务统一处理为一条可审计流水线：因子发现、单因子逻辑抽取、字段审计与取数、MR/Execute 判定、DolphinDB 代码生成、内置指标复用和复现原则检查。

不要一次性加载所有参考文档。先判断用户请求处于哪个阶段，再读取对应 references/ 文件。只有用户要求完整端到端复现时，才按流程逐步读取多个阶段文档。

阶段路由

用户意图	读取文件	产物
从整篇研报提取所有候选因子	references/01-all-factors-json-extraction.md	summary + factors 纯 JSON
抽取单个因子的定义、经济含义、变量解释和公式	references/02-report-factor-logic-extraction.md	function=pre-result JSON
把因子公式映射到真实数据源字段，判断字段是否足够，生成取数 SQL 或取数脚本	references/03-factor-data-extraction.md and references/data-extraction/	fieldCheck JSON；extractData(args, "string") 生成的 dataSql；完整通道额外产出取数脚本
字段已给出或看似已确认，需要直接写单因子代码	references/03-factor-data-extraction.md	快速 fieldCheck JSON + dataSql；通过后进入 05 或 06
判断因子走 MR 还是 Execute	references/04-mr-execute-mode-selection.md	MREligible 参数与最终模式
生成普通 Execute 因子脚本	references/05-execute-code-generation.md	四列 result 表脚本
生成 MR 因子脚本	references/06-mr-code-generation.md	mapFuncString, dbName, tbName, dataSql 与完整脚本
复用内置技术指标、Alpha、盘口或逐笔函数	references/indicator-cookbook.md	模块加载与 module::function 调用
需要常见 DolphinDB 因子计算写法	references/replication-patterns.md	稳定代码片段与计算模式
检查未来数据泄露、字段幻觉、样本口径和输出结构	references/replication-principles.md	风险检查与修正建议

端到端流程

当用户要求“复现研报因子”“从研报生成 DolphinDB 因子代码”或类似端到端任务时，按以下顺序执行：

1. 读取 01-all-factors-json-extraction.md，从整篇研报提取候选因子，除非用户已经指定单个因子。
2. 读取 02-report-factor-logic-extraction.md，整理目标因子的经济含义、变量、窗口、公式和输出频率。
3. 读取 03-factor-data-extraction.md，只基于 coldefs、testsql 和样例数据做字段审计并生成 fieldCheck JSON。字段审计和 fieldCheck JSON 不可跳过；所有进入代码生成的场景都必须调用 extractData(args, "string") 生成 dataSql，快速通道只省略额外取数脚本。
4. 读取 replication-principles.md，检查字段、时间边界、样本口径和未来数据泄露风险。
5. 读取 04-mr-execute-mode-selection.md，准备并调用 starfish::facplfRun::MREligible。最终模式以该函数返回为准。
6. 根据模式读取 05-execute-code-generation.md 或 06-mr-code-generation.md 生成代码。
7. 生成代码时按需读取 indicator-cookbook.md 和 replication-patterns.md，优先复用内置函数和稳定向量化模式。

如果任一阶段缺少必要输入，先说明缺口；不要编造字段、数据源、函数签名或研报未给出的公式。

全局硬约束

1. 只使用研报原文、用户输入、coldefs、testsql、样例数据或已确认文档中出现的信息。
2. 不得凭常见字段名创造数据源字段。
3. 因子在 tradeTime = t 的值只能依赖 t 或之前可获得的数据。
4. 未来收益、评价标签、IC、IR、t-stat、分组收益等只能用于评价，不能进入因子值计算。
5. 时间序列计算前必须按证券和时间排序。
6. 横截面标准化、排名、中性化必须在同一时点内完成。
7. 生成 DolphinDB 因子结果时，最终输出列必须严格为 tradeTime, securityId, factorname, value。
8. 多返回值内置指标函数必须显式拆包。
9. MR 模式必须经过 starfish::facplfRun::MREligible 判定；经验规则只能用于准备参数，不能替代返回结果。
10. 字段不足时，明确输出缺失字段和原因，不生成虚假的可执行因子代码。
11. 即使字段看起来足够或用户已经给出字段映射，也必须读取 03-factor-data-extraction.md，并基于 coldefs、testsql 或样例数据生成 fieldCheck JSON 后再进入代码生成。
12. 最终因子计算逻辑必须封装为单一核心函数；字段入参和表入参模式使用 def calcFactor(...) {}，Panel 模式使用可被 panel_call 调用的 panel 因子函数。函数入参必须来自 fieldCheck JSON 的字段映射。
13. 05/06 不得重新手写取数 SQL；必须先在 03 中用 extractData(args, "string")["result"] 得到 dataSql，后续代码基于该字符串取数或构造 sqlDS。快速通道也要产出 dataSql，只是不用额外生成取数脚本。
14. 公式窗口、lag、rank 窗口、平滑周期、阈值等非字段参数必须从 fieldCheck 字段入参中分离，作为核心函数的普通参数，并提供默认值；默认值优先来自研报公式，若研报未给出则在注释中标明为待确认默认值。

代码生成策略

生成 DolphinDB 代码时：

1. 优先选择向量化写法，例如 select、update、context by、group by、滚动窗口函数。
2. 遇到 RSI、MACD、ATR、BOLL、Alpha101、Alpha191、盘口快照或逐笔成交类公式，先查 indicator-cookbook.md。
3. 遇到收益率、滚动窗口、横截面排名、中性化、缺失值处理、字段对齐或四列输出，先查 replication-patterns.md。
4. 代码必须定义并调用单一核心因子函数：字段入参和表入参使用 calcFactor，Panel 模式使用可被 panel_call 调用的 panel 因子函数。
5. 核心函数入参形态必须由因子计算依赖关系判断，不能由用户提示或测试用例名称直接决定。
6. 历史因子计算是主交付目标；流计算兼容性只作为函数边界设计参考，不替代 Execute/MR 历史脚本。
7. 单个计算层面使用 SQL 字段入参 def calcFactor(field1, field2, ..., param=default)：可对应普通逐行 select、保持原频的 context by，或降频聚合的 group by。
8. 同一层面同时包含时序计算与截面计算时使用 Panel 模式：因子函数形态为 def FactorName(field1, field2, ..., window=20)，字段参数语义是时间 x 证券矩阵，窗口等普通参数必须带默认值，由 panel_call(rawdata, ...) 负责长表转 panel、调用函数、再转回四列表。
9. 多个计算层面或多阶段中间结果使用 def calcFactor(tb, param=default)，例如先分钟聚合到日频、再做 20 日滚动，或需要多个不同粒度/分组阶段。
10. 非规则分组、行业中性化、复杂聚合、非规则对齐等如果无法表达为单层 SQL 字段入参，也使用 def calcFactor(tb, param=default)。
11. WorldQuant/Alpha 风格函数如果本身以 panel 矩阵为字段入参并返回 panel 矩阵，优先使用 panel_call 历史计算模板，不要直接改写成 calcFactor(tb)；panel_call 的 rawdata 必须来自 03 阶段 dataSql = extractData(args, "string")["result"] 执行后的 rawData。
12. 脚本需要中文注释，说明金融逻辑、窗口、排序、分组、空值处理和输出整理目的。
13. 禁止 try-catch 掩盖错误。

calcFactor 入参判定规则

判断依据是计算层级，不是表数量、频率数量或用户提示名称。

• 使用 SQL 字段入参 def calcFactor(field1, field2, ..., param=default)：只涉及单个计算层面。包括逐行公式、单次 context by 保持原频的时序滑动/聚合、单次 group by 降频聚合。
• 使用 Panel 模式 def FactorName(field1, field2, ..., param=default) + panel_call(rawdata, ...)：同一层面内同时存在时序计算和截面计算，或直接复用 WorldQuant/Alpha 风格矩阵函数；输入和输出保持时间 x 证券矩阵。
• 使用表入参 def calcFactor(tb, param=default)：涉及两个及以上计算层面、多个不同粒度/分组阶段、必须复用中间表，或无法表达为单层 SQL 字段入参。
• 多数据源或跨频率 join 本身不构成表入参条件；如果 join 后仍是单层逐行、单层 context by 或单层 group by，仍使用 SQL 字段入参。
• 只涉及时序滑动/滚动/滞后，不构成 Panel 条件；优先使用 SQL 字段入参，并在最终 SQL 中使用 context by securityId。
• 只涉及一次降频聚合，不构成 TB 条件；优先使用 SQL 字段入参，并在最终 SQL 中使用 group by 生成降频结果。
• 时序计算结果再做同一时点截面 rank/标准化时，使用 Panel 模式。
• 先做一个粒度的聚合，再在另一个粒度做窗口/聚合时，使用 TB 入参。
• panel 模式的 rawdata 应为 runSQL(dataSql) 的结果。
• 公式中的窗口、lag、阈值、平滑周期等是函数普通参数，不是 fieldCheck 字段；必须写成带默认值的参数，例如 def RollingFactor(close, window=20) 或 def calcFactor(close, preClose, threshold=0.02)。
• 如果无法确认是否存在跨行依赖，先在交付中说明不确定项；不要为了简化而强行使用字段入参。

输出选择

根据当前阶段输出对应格式：

• 因子发现阶段：只返回可解析 JSON，不加代码块。
• 单因子逻辑阶段：返回 function=pre-result JSON。
• 字段审计阶段：所有可继续的场景都必须输出 fieldCheck JSON 和 dataSql = extractData(args, "string")["result"] 生成的取数 SQL；复杂取数场景可按需额外输出单文件取数脚本；字段不足时输出缺失原因。
• 模式判定阶段：输出 MREligible 参数、调用结果和选择理由。
• 代码生成阶段：输出完整 DolphinDB 脚本，并保证最终结果表结构符合四列契约。
• 审查阶段：优先列出违反未来数据、字段真实性、模式选择或输出结构的具体问题。

参考文件

• references/01-all-factors-json-extraction.md：全量候选因子 JSON 提取。
• references/02-report-factor-logic-extraction.md：单因子研报逻辑与公式抽取。
• references/03-factor-data-extraction.md：快速 fieldCheck JSON、字段审计和可选取数脚本生成。
• references/data-extraction/：数据抽取脚本资源，包括 extractData.dos、example.dos 和 example.json。
• references/04-mr-execute-mode-selection.md：Starfish MR/Execute 判定。
• references/05-execute-code-generation.md：Execute 因子脚本规范。
• references/06-mr-code-generation.md：MR 因子脚本规范。
• references/indicator-cookbook.md：内置指标、Alpha、高频、盘口和逐笔模块调用。
• references/replication-patterns.md：常见 DolphinDB 因子复现代码模式。
• references/replication-principles.md：防未来数据泄露与复现边界原则。