jingxuanc/quant-agent-skills/factor-production-check

因子上生产体检

何时使用

命中以下任意一种说法就调用本技能：

• 「这因子能上实盘吗？」
• 「能不能上生产 / 什么时候能推上线？」
• 「这因子是不是过拟合了？」
• 「样本外表现怎么样？」
• 「挖出来这么久，衰减了多少？」
• 「帮我给这个因子做个上线体检」

不适用：想知道因子最近还灵不灵（只跑近端 IC）→ 走 factor-vitality；想做组合权重分配 → 走 portfolio-checkup / rebalance-plan。

轻问 vs 深问（成本控制）

轻问（1 个工具，数分钟，优先默认走这条）

• factor-miner-factor_oos_check(code, name) —— 一次跑出「挖掘窗口 vs 纯样本外窗口」两组 IC/年化/回撤 + 衰减值。
• 适用：用户只问「过拟合没有 / 样本外行不行」。回复一张对比小表 + 一句结论即可。

深问（完整链路 + 结构化报告）

1. factor-miner-factor_oos_check 拿样本外证据（第 1 步，必做）
2. factor-miner-factor_backtest(sota, new_factors, profile, windows) 跑 qlib 全量回测，与 SOTA 因子组合同场比较（第 2 步）
3. 汇总成体检报告：指标对比 + decay + 淘汰建议（第 3 步，纯汇总，不额外调工具）

哪一步最贵：

• `factor-miner-factor_backtest` 是最贵的一步 —— 服务端 qrun 超时上限 1800s（30 分钟），还要跑因子沙箱执行 + 回测 + 解析。用户没明确说「跑全量回测」时，不要主动上这一步。
• factor-miner-factor_oos_check 次贵 —— 它会把同一个因子跑两遍（挖掘窗口一遍、纯样本外窗口一遍），耗时约为单次回测的 2 倍。轻问走它就够了。
• 两者都是重任务，先拿 job_id，再用 `factor-miner-job_status` 轮询，不要同步傻等（见工具链）。

工具链

第 0 步：确认输入齐全

本技能不需要用户提供 klines：factor_oos_check 与 factor_backtest 都在服务端读本地 qlib 数据集（cn_data / daily_pv_all.h5），数据由服务端维护，不经过对话传入。 需要向用户确认的是：

1. 因子名（name，如 alpha_vol_ratio）—— 用于报告标注与版本落库
2. 因子代码（code，即 factor.py 源码）—— 读日频 h5、算因子、写结果的标准脚本。用户可能有现成文件；没有就先要代码，不要自己瞎编一个因子代跑。
3. 对照的 SOTA 因子组（仅深问需要）—— 即当前在库的 promoted 因子，可先用 factor-miner-get_factor_library(status='promoted') 查出来，拿它们的 {name, code} 作为 sota 参数。

数据窗口结论要标注来源：服务端 qlib 本地数据集 + 该工具内建的挖掘/样本外窗口，不是用户贴的 K 线。

第 1 步：样本外体检（核心，必做）

factor-miner-factor_oos_check(
  code = "<factor.py 源码>",
  name = "<因子名>"
)

内部会跑两遍：

• 挖掘窗口：test 2017-01 → 至今
• 纯样本外窗口：test 2021-01 → 至今

返回字段（务必原样取用，不要自己推算）：

• mining: {ic, annualized_return, max_drawdown}
• oos: {ic, annualized_return, max_drawdown}
• decay: 相对衰减（可为 null，表示无法计算）
• ok / error: 失败时如实报错，不要用 0 值占位冒充结果

判断口径（只做统计表述，不给交易建议）：

• oos.ic 明显低于 mining.ic 且 decay 大 → 过拟合嫌疑重
• oos.ic 与 mining.ic 同量级、decay 小 → 样本外稳定性较好
• 具体阈值以库内现有因子分布为参照；拿不准时把两组数并排给用户，让他自己判断，不要硬下一个"通过/不通过"的断言。

第 2 步（仅深问）：qlib 全量回测

factor-miner-factor_backtest(
  sota = [{"name":"<SOTA因子名>","code":"<SOTA源码>"}, ...],   // 当前在库 SOTA 组合
  new_factors = [{"name":"<新因子名>","code":"<新因子源码>"}], // 待体检的因子
  profile = "full",        // "full" 生产口径；"smoke" 只做冒烟快测
  windows = {              // 可选：自定义回测窗口，不传则用默认窗口
    "train_start":"...", "train_end":"...",
    "valid_start":"...", "valid_end":"...",
    "test_start":"...",  "test_end":"..."
  }
)

返回 {ok, dedup_dropped, sota_broken, metrics, correlations, net_values, error, traceback}。

• metrics：与 SOTA 同场对比的回测指标
• correlations：新因子与已有 SOTA 的相关性 —— 相关性过高说明只是重复造轮子，这是淘汰的重要依据
• sota_broken / dedup_dropped：被剔除的因子，要在报告里说明剔了谁、为什么

重任务纪律（必须遵守）：

• 本步骤服务端 qrun 超时 1800s。调用后若返回 job_id（异步模式），先拿 job_id，再用 `factor-miner-job_status(job_id)` 轮询：

`` factor-miner-job_status(job_id = "<job_id>") → status: queued / running / done / error；done 后读 result，error 读 error 字段 ``

• queued / running 期间不要反复空转轮询，把进度告知用户，其间可先整理第 1 步的对比表。
• 如果调用是同步阻塞返回结果的，也要提前告诉用户「这一步可能跑几分钟到半小时」，不要以为它卡死了。
• 超时或 ok=false 时，如实说明失败原因（error / traceback 摘要），并明确「本次回测无有效结论」，不要用 `profile="smoke"` 的结果冒充 full 回测结论 —— smoke 只用于排除代码报错。

第 3 步：汇总成体检结论

两张结果合到一起，产出四种落点之一，并写清依据：

1. 可推进候选：样本外无明显衰减，且与现有 SOTA 相关性低
2. 需观察：样本外尚可但衰减偏大，或回测窗口只有部分通过
3. 重复造轮子：回测可用但 correlations 显示与已有因子高度重合
4. 建议淘汰：样本外 IC 塌陷 / 回测 ok=false / sota_broken 暴露代码问题

记忆回路（前查后记）

本技能的历史参照维度是「体检落点 → 事后是否被验证」：即当初判「可推进候选」的因子后来样本外是否真的稳住了，判「建议淘汰/重复造轮子」的是否事后被证明该淘汰。这个记忆对用户的价值在于：单个因子的 IC/decay 只是一次性数字，多轮沉淀后才能看出本库的体检口径是偏松还是偏严、decay 的阈值定在哪个量级才符合历史经验，从而让「过拟合了吗」这个判断从单点证据变成有校准历史的分位判断。

输出格式

Agent 回复必须包含以下小节，字段名可中文化但不得缺项：

1. 体检对象：因子名 + 一句话说明这个因子在算什么（读代码得出，读不出就别编）。
2. 数据与窗口：数据来源（服务端 qlib 本地数据集）、挖掘窗口、样本外窗口、回测 profile。
3. 样本外对比表（核心，三行两列）：

1. 全量回测结果（深问才有）：metrics 关键项、与 SOTA 的 correlations、被剔除的因子（dedup_dropped / sota_broken）。轻问时写明「未跑全量回测（成本考虑），需要就补跑」。
2. 淘汰建议：落到上面 4 种落点之一，并给出触发该判断的具体数字（如「样本外 IC 从 X 掉到 Y，衰减 Z」）。
3. 成本与耗时：用了哪些工具、profile、是否需要 job_id 轮询、实际等待时长，让用户知道钱花在哪。
4. 模型/统计声明（固定收尾，不可省略）：

> 以上为历史统计计算结果与模型/回测输出，非承诺，过往表现不代表未来收益，不构成任何投资建议。

历史参照（必填小节）：若检索到同类历史，写明「类似情境 N 次，其中 X 次 <本技能的判断维度> 正确」；

无历史则写「首次记录此类情境，本次判断已存入记忆供将来对照」。

合规边界

• 只输出统计计算结果：IC、年化、最大回撤、衰减、相关性、回测指标。
• 不输出：买入/卖出/加仓/减仓建议、目标价、预期收益率承诺、胜率承诺、"上线必赚""这因子稳了"等确定性措辞。
• 严格区分统计有效性与交易可用性：本技能只回答「这个因子在历史上是否稳定、是否过拟合」，不回答「该不该拿它下单」 —— 后者超出边界，需要走风控/组合层工具。
• 不美化失败结果：ok=false、error、decay=null、回撤放大，都要原样呈现；禁止用其他窗口或 smoke 档结果替代失败的证据。
• 涉及 ML/预测类因子的输出，一律标注「模型输出，非承诺」。
• 回测结论必须绑定窗口口径；换窗口结论可能翻转，不得省略窗口说明。

常见问题

1. 「为什么样本外 IC 只有挖掘窗口的一半？」

这正是 decay 要量化的东西 —— 挖掘窗口本身参与过因子筛选，天然偏乐观，纯样本外才是较公允的证据。把两组数并排给用户，说明衰减幅度落在什么量级，但不要替用户下"能不能上"的最终决定。

1. 「回测跑了很久没回？」

factor_backtest 服务端超时上限 1800s，QLib 全量回测本来就慢。拿到 job_id 后用 factor-miner-job_status 轮询，期间可以先交付第 1 步的样本外对比表，别让用户干等。若最终 error，如实报告并建议缩小 windows 或用 profile="smoke" 先验证代码能跑通。

1. 「能不能跳过样本外，直接看全量回测？」

不建议。全量回测本身不区分挖掘窗口与样本外窗口，光看它无法回答"过拟合了吗"。factor_oos_check 才是本技能的核心证据，第 2 步是补充与同场对标，不能替代。

1. 「因子的 klines 从哪来？要我贴吗？」

不用。这两个工具都在服务端读本地 qlib 数据集，不走对话传 K 线。用户需要给的是因子代码 `code` 和因子名 `name`；缺代码时先要代码，不要自己编一个近似因子代跑。