多因子框架全景复盘

> Pay Skill 范式：鉴权型（agent_local）
> 鉴权型：履约在本机执行（需本地因子面板 CSV），远端网关只做支付鉴权，支付通过后返回 fulfillment: "agent_local"，Agent 再跑 scripts/ 下的脚本产出结果。

Overview

这是一个「多因子建模流程的体检与导航工具」，不是选股工具，也不是因子挖掘工具。

它回答五个问题，全部可复现、全部用纯 Python 标准库实现（零第三方依赖，用户机器上不用装包）：

1. 数据脏不脏 —— 缺失率、异常值率、重复主键、量纲是否可比；z-score 会不会被极值污染（用「标准差 / 1.4826×MAD」这个污染倍数直接量化），并给出该用 z-score、min-max 还是 robust 标准化。
2. 因子灵不灵 —— Rank IC / IR / t 值 / 方向胜率 / 十分位分组单调性 / 多空对称性（收益是不是主要来自 A 股做不了的空头端）/ 半衰期（按 rho(t) = rho0·exp(-lambda·t) 拟合，T(1/2) = ln2 / lambda）/ 分域差异。可做市值与行业的截面回归中性化并给出前后对比。
3. 因子重不重 —— 平均截面相关矩阵、阈值告警（默认 0.3 关注 / 0.5 高相关）、VIF、相关矩阵条件数，以及最关键的「独立信息维度」：累计解释方差达 90% 所需的主成分个数。因子堆到几十上百个，独立维度可能只有三五个。
4. 权重怎么给 —— 等权 / IC 加权 / ICIR 加权 / 收益率加权 / 线性回归 / 岭回归六种方案，全部走 walk-forward（权重只由历史窗口估计），直接对比样本外 IR，并给出样本内外 IR 差距做过拟合诊断。
5. 钱从哪来 —— 按信号构建多头组合，输出年化 / 波动 / 夏普 / 最大回撤 / 卡玛 / VaR / CVaR / 换手与成本拖累，再把组合收益对逐期截面回归估出的因子收益率做时序归因，拆出每个因子的暴露与贡献占比，外加不能被因子解释的 alpha。

核心机制一句话：把「数据 → 因子 → 测试 → 加权 → 优化 → 执行 → 评价」这条链路拆成八个模块，能用面板算的部分全部算出来并打红黄绿灯，算不出来的部分（执行算法、服务器部署、实盘监控）给出标准做法清单让人工确认，最后汇总成一张打分卡和一份按优先级排序的改进清单。

为什么比朴素做法强：

边界（明确不做；遇到这类请求如实说明，别硬凑）

• ❌ 不输出股票名单、不构建股票池、不做标的排序——本 Skill 是流程体检工具，不是选股/荐股工具；
• ❌ 不预测涨跌、不给买卖点、不做择时——只做已发生数据的统计诊断；
• ❌ 不评价"好/坏"——只给描述性结论（如「Rank IC = 0.05，IR = 0.42，多样本外 IR = 0.51」），不说"这个因子值得用"；
• ❌ 不自动联网取数。因子面板由用户提供（CSV），或由用户在 WorkBuddy 内通过已授权数据源取数后交给本 Skill；
• ❌ 不替代组合优化器、不替代交易系统、不替代合规披露。

When to Use（触发条件）

A. 想给现有多因子流程做一次全面体检（首要场景）

• 用户说「帮我看看我的多因子流程哪里有问题」「我的因子库健康吗」时；
• 用户说「因子加了一堆，效果却没变好，问题可能出在哪」时；
• 用户有一个因子面板 CSV，想一次性知道数据、因子、加权、回测各环节的短板时。

B. 想验收单个或一组因子

• 用户说「我这个因子 IC 有 0.03，算有效吗」「IR 多少才够用」时；
• 用户说「因子是不是只赚了小市值的钱」「帮我做市值和行业中性化再看一次」时；
• 用户说「这个因子多久调一次仓合适」「它的半衰期是多少」时。

C. 想诊断共线性与因子冗余

• 用户说「我这两个因子是不是重复了」「因子相关性多高才算有问题」时；
• 用户说「我的因子库有 50 个因子，实际有几个是真的」时；
• 用户在用回归类加权（OLS / 岭回归 / 机器学习）之前，想先确认系数可不可信时。

D. 想在几种加权方案之间做选择

• 用户说「等权好还是 ICIR 加权好」「机器学习加权值不值得上」时；
• 用户说「我的样本内效果很好，样本外就不行了，怎么判断是不是过拟合」时。

E. 想拆解回测收益来源

• 用户说「我这轮超额是哪几个因子贡献的」「alpha 里有多少是因子解释不了的」时；
• 用户说「回测年化 20%，但换手很高，扣完成本还剩多少」时。

明确的排除项（用户这么问时，如实说明本 Skill 不做）：

• 「按这个因子给我一份股票池」「哪只值得买」→ 属选股与投资建议，不做；
• 「帮我写个组合优化器直接出权重」「接交易所下单」→ 不在本 Skill 范围内，但会在导航清单里给出标准做法与约束清单。

Workflow（工作流）

> 付费前置：本 Skill 为鉴权型。必须先按文末「Pay Skill 模式」完成 X402 支付鉴权，
> 拿到 paid: true 后才执行下面的 Step 2 及之后。支付未确认前不得运行任何计算脚本，不得输出任何结果。

Step 0 澄清输入（不要凭空假设）

Step 1（首选入口） —— 一次跑完全流程体检

python3 scripts/run_local.py navigate --input panel.csv [--factors f1,f2,f3] \
    [--ppy 12] [--min-stocks 20] --out 体检报告.md

输出八模块打分卡（红/黄/绿/灰四态）+ 按 P0/P1/P2 排序的优先改进项 + 八模块标准做法清单 + 搭建顺序建议。
当用户只说「帮我看看流程有没有问题」而说不清要看哪一项时，默认跑这个。

Step 2（数据预处理体检）

python3 scripts/run_local.py hygiene --input panel.csv [--factors f1,f2] \
    [--outlier-k 3.0] [--winsor 5.0] --out 数据体检.md

逐因子给出缺失率、整期缺失期数、三种口径的异常值率（MAD / 标准差 / 1%–99% 分位）、
偏度与超额峰度、污染倍数（标准差 ÷ 1.4826×MAD），并给出标准化方法建议。

Step 3（单因子有效性检验）

python3 scripts/run_local.py evaluate --input panel.csv --factor f1 \
    [--n-groups 10] [--top-q 0.2] [--domain mktcap] [--neutralize] \
    [--svg decile.svg] --out 因子检验.md

输出 Rank IC / IR / t / 方向胜率、十分位分组收益与形态判定（正单调 / 负单调 / 弱单调 /
两端型 U 型 / 中间型倒 U 型 / 无清晰形态）、多空与两端贡献拆分、半衰期、换手率。
带 --neutralize 时先做市值 + 行业的截面回归中性化，并给出中性化前后对比；
带 --domain mktcap 时按市值中位数分高值域 / 低值域重算 IC。

Step 4（共线性诊断）

python3 scripts/run_local.py collinear --input panel.csv [--factors f1,f2,f3] \
    [--warn 0.5] [--note 0.3] --out 共线性.md

输出平均截面相关矩阵、高相关因子对、VIF、相关矩阵条件数与特征值谱、
独立信息维度（累计解释方差达 90% 的主成分个数）、按 |Rank IC| 贪心的保留/剔除建议，
以及序贯正交化与对称正交化两种处置路径的取舍。

Step 5（权重合成对比）

python3 scripts/run_local.py synthesize --input panel.csv [--factors f1,f2,f3] \
    [--schemes equal,ic,icir,ret,ols,ridge] [--window 24] [--ridge-lam 1.0] --out 加权对比.md

六种方案走 walk-forward：权重只用历史窗口估计（--window 0 为扩张窗口），再在当期截面上评估，
对比样本外 IC 均值 / IR / t / 多空年化 / 夏普 / 最大回撤，并给出样本内外 IR 差距做过拟合诊断。

Step 6（回测绩效归因）

python3 scripts/run_local.py attribute --input panel.csv [--signal f1] \
    [--top-q 0.1] [--cost-bps 20] [--bench-col bench] [--sub-col sub] --out 绩效归因.md

按信号取前 10% 等权持有多头组合，输出年化 / 波动 / 夏普 / 最大回撤 / 卡玛 / 胜率 / 偏度 /
超额峰度 / VaR / CVaR / 换手与成本拖累；再做因子贡献归因（逐期截面回归估因子收益率 →
对组合收益做时序回归 → 暴露、贡献占比与未解释 alpha）。

Step 7（自检，可选） —— 用合成数据验证本机脚本可跑通

python3 scripts/run_local.py demo --out 自检报告.md

生成合成面板（60 期 × 200 只，含单调有效因子、两端型因子、噪声因子、高相关克隆因子与 2% 脏数据），
跑通「数据体检 → 因子检验 → 共线性 → 加权对比 → 绩效归因」全链路。结论无投资含义，仅用于排查环境。

Output（输出规范）

• 默认输出中文 Markdown 报告，结构见 references/output_templates.md；
• 数字口径：收益率统一用百分比并保留 2 位小数；IC / Rank IC 保留 4 位小数；IR / t / 夏普 / 条件数保留 2 位；权重保留 3 位；
• 显著性标记：因子 t 值 |t| >= 2 记为显著，否则不显著；
• 状态灯：打分卡用 绿（达标）/ 黄（接近阈值需关注）/ 红（未达标需整改）/ 灰（本面板无法自测，需人工确认）四态；
• 缺失处理：取不到的量一律写「未获取」并说明原因（缺哪列、需要多少期），严禁因为用户已付费而推测补造。
  截面期数不足或单期样本 < --min-stocks 时直接跳过并在报告里标出，不硬算；
• 结论纪律（三条都必须严守）：
• 因子弱（Rank IC 绝对值偏小、IR 偏低）时必须明确说「未呈现稳定区分力」，不夸大；
• 样本内外 IR 差距过大时必须明确说「存在过拟合迹象」，并建议退回更简单的加权方案；
• 只描述，不评价。不出现"好/差/值得用/该买"等评价性措辞，不输出任何股票名单或标的排序。
  用户追问"那我买什么"时，如实说明本 Skill 不提供该功能。

Notes / Constraints（约束）

• 免责声明：本 Skill 产出的是多因子流程的统计诊断结果，不构成投资建议，不预测未来收益。
  每份报告末尾必须带风险提示（因子拥挤、过拟合、样本外失效风险）。
• 不替代：不替代组合优化器、交易执行系统、风控系统与合规披露。这些模块在导航清单里给出标准做法，需人工确认。
• 样本量底线：单因子评价至少需 2 期有效截面且每期 ≥ --min-stocks 只；半衰期估计需 ≥ 12 期多空收益序列；
  加权对比需 ≥ 6 期有效截面；共线性的 VIF 需单期样本数大于因子数 + 3。
• 频率一致性：面板内 date 须为同一频率（周/月/日），--ppy 须与之匹配，否则年化失真。
• 因子方向：Rank IC 的正负决定多头端在因子高值侧还是低值侧；加权环节会自动按训练窗口 IC 符号统一方向，
  并在报告里列出被取反的因子。估值类因子（PE / PB）请在传入前先取倒数，使「低估值」落在因子最大端。
• 单调 vs 两端：分组形态会判定为单调型或非线性型（两端 U 型 / 中间倒 U 型）。
  非线性因子的线性 IC 接近 0 是正常现象，不要据此判它无效，应改用两端极值构造或对因子做 |z| 变换。
• 中性化与分域的边界：两者都需要面板提供 mktcap / industry 列。缺列时输出「未获取」并说明需要哪一列，
  绝不用全市场均值或随机行业标签代替。
• 半衰期的口径：按多空收益序列的自相关指数衰减拟合。月度面板上该估计对噪声较敏感，
  若自相关不随滞后单调衰减会如实输出「未获取」；要更稳的半衰期估计应使用更高频率（日频）的因子收益序列。
• 被误当成选股工具时：用户问「那我买什么」「给我一个股票池」时，如实说明本 Skill 是流程体检工具，
  不具备选股能力，不要拿诊断结果反向拼凑标的推荐。

Pay Skill 模式（鉴权型，按次付费，已接入 X402）

本 Skill 为付费技能（Pay Skill），按次收费，已通过腾讯 SkillHub +
微信支付 Agent Pay X402 协议接入。不存在免费运行模式——
未完成支付授权前，不得执行本地履约脚本、不得输出任何付费内容；
鉴权型只由服务端返回的 paid: true 解锁本机履约。

> 使用者须已安装并开通 weixinpay_pay 插件（微信 AI 支付 / AI 专属卡）。
> Step 0 检查不通过时不发起付费调用，直接引导开通后重试。

鉴权型：履约在本机执行（需解析本地因子面板 CSV），
远端网关只负责订单鉴权与支付状态确认，支付通过后返回 fulfillment: "agent_local"，
不返回业务结果；Agent 收到 paid: true 后才在本地跑 scripts/ 下的脚本产出结果。

• 统一网关主接口：POST https://pay.zerone-iteration.com/api/invoke
  （请求体 {"skill": "multifactor-framework-review", "skill_version": "1.0.1", "query": "...", "amount": 500}）
• 兼容入口：POST https://pay.zerone-iteration.com/api/resource（等价于默认 Skill）
• 支付回调：POST https://pay.zerone-iteration.com/api/pay/notify
• 退款回调：POST https://pay.zerone-iteration.com/api/refund/notify
• 实现：透明网关（nginx + Java 17 / Spring Boot + WechatPay-Java，微信支付公钥模式）；
  skill/skill_version 仅做格式校验后透传进 X402 预下单，不查 SkillHub（不查注册表、不反查是否真实存在/已发布/版本匹配）；
  无本地白名单，新增 Skill 免 Java 注册、免改 JAR、免重启，直接 POST /api/invoke 传正确 slug+版本即可
• 状态：✅ DEV_MODE 402 结构冒烟已通过；⚠️ 生产真实扣费链路尚未实测，不可声称已通。
• 已验证（1）本机履约链路：python3 scripts/run_local.py demo 跑通「数据体检 → 因子检验 → 共线性 →
  加权对比 → 绩效归因」全链路；七个 CLI 子命令在合成面板上均返回 0 且结论符合面板的刻意设计
  （单调因子被判正单调、两端型因子被判 U 型、克隆因子被判高共线）。
• 已验证（2）真实 A 股月频面板上的主链路（详见 REALDATA_VALIDATION.md 与
  ~/pay-skills/实测报告_multifactor-framework-review.md）。
• 已验证（3）DEV_MODE 402 结构冒烟（pay/server.py 内存起服，5 步全绿）：
  ① 首调 /api/invoke 未支付 → HTTP 402 + 响应头 WeixinPay-Required + X-Out-Trade-No +
  body WeixinPay.Required 嵌套结构（code=PAYMENT_REQUIRED）；
  ② /api/pay/notify 模拟回调置位支付成功；
  ③ 带 X-Out-Trade-No 重试 → HTTP 200 + fulfillment=agent_local + paid=true 鉴权回执；
  ④ 同 payment_code 再调 → 幂等 already_fulfilled=true；
  ⑤ amount 缺失 → HTTP 400 INVALID_AMOUNT。
• 未验证：X402 真实扣费链路（真实微信商户 + SkillHub 开发者私钥预下单）尚未做生产实测。
• 发布前必做：按 PAY_SKILL_UPGRADE.md 第五节，切真实密钥跑 1 元真扣，通过后回填本条为「已实测」。

Agent 侧调用规范（含付费前置插件检查）

Step 0 付费前置插件检查（必须，缺失则不得发起付费调用）

1. 检测当前环境中 weixinpay_pay 插件（微信支付 Agent Pay / AI 专属卡）是否已安装并已开通；
2. 若不存在或未开通：不调用 /api/invoke，改为提示用户先安装/开通微信 AI 支付，完成后再继续；
3. 若可用：继续 Step 1。

Step 1 调用统一网关：POST /api/invoke，请求体：

{
  "skill": "multifactor-framework-review",
  "skill_version": "1.0.1",
  "query": "用户原始需求（用于订单留痕，不作为履约输入）",
  "amount": 500
}

• skill：必填，固定为本 Skill 的 slug multifactor-framework-review（与 SkillHub 已发布的一致；透明网关下传错 slug 时错误延后到 SkillHub/微信预下单环节才返回）；
• skill_version：必填，当前版本号 1.0.1（缺失返回 400 MISSING_SKILL_VERSION）；
• amount：必填，单位分，服务端校验为大于 0 的整数（小数/布尔/零/负数一律 400 INVALID_AMOUNT，不静默截断）；
  区间不强制，价格由 SkillHub 产品定价约束。

Step 2 支付触发（X402 预下单 → 402）：未支付时服务端依次执行——

1. 生成订单号 out_trade_no（402 响应头 X-Out-Trade-No 与响应体 out_trade_no 均会返回，Agent 须记下）；
2. 调用微信支付 Native 下单，获取 code_url；
3. 用 SkillHub 开发者私钥（SHA256withRSA）对 X402 AI 预下单请求签名；
4. 调用 POST https://payapp.weixin.qq.com/palmpayminiapp/clawagentpay/preorder 换取 payment_code；
5. 返回 HTTP 402，响应头 WeixinPay-Required 与 body WeixinPay 块中
   同时携带 X402 预下单返回的 payment_code（必须是 X402 的 payment_code，
   不能直接把微信 code_url 当作 payment_code 返回），并回显本单 amount 与 out_trade_no。
   ⚠️ body 的 WeixinPay 嵌套结构最易遗漏：缺失时 weixinpay 插件从 body 解析不到
   payment_code，会报「当前支付订单已过期」，该报错常被误判为「返回了 code_url」。

Step 3 用户支付授权：Agent 将 WeixinPay-Required 头（或 body WeixinPay 块）中的
payment_code 作为 paymentCode 交给 weixinpay_pay 插件，向用户申请支付授权。

Step 4 二次调用鉴权：用户完成支付后，Agent 再次调用 POST /api/invoke
（请求体同 Step 1，带请求头 X-Out-Trade-No: <402 返回的订单号>）；
服务端按订单号主动向微信查单验证支付成功（不依赖回调到达）后返回：

{"ok": true, "paid": true, "fulfillment": "agent_local",
 "skill": "multifactor-framework-review", "out_trade_no": "...", "already_fulfilled": false}

Step 5 本地履约（本 Skill 的关键差异）：Agent 收到 paid: true 且
fulfillment: "agent_local" 后，在本机执行 scripts/ 下的脚本产出结果
（见 scripts/README.md），再把结果交付给用户。
支付未确认前，不执行本地计算脚本、不输出任何付费内容
（未支付重试返回 402 {"code":"NOT_PAID"}）。

> 幂等说明：already_fulfilled: true 表示同一订单此前已鉴权通过；
> 此时直接复用上次已产出的结果，不要重复跑脚本（避免重复消耗外部接口配额）。

异常处理说明（Agent 与服务端两侧）

> 核心原则（SkillHub 官方教程 FAQ）：支付失败/未确认时必须如实告知用户，绝不据此推进后续流程。

核心特征对照表（供审核查验）

包内 pay/server.py 为 Python 参考实现（含 APIv3 签名、X402 预下单、回调验签解密、
主动查单、幂等鉴权、透明网关无需注册表），部署说明见 PAY_SKILL_UPGRADE.md 与 pay_skill.yaml。

注意：本 Skill 涉及两套独立密钥/证书——

• 微信支付 API 证书（wechat_pay）：用于微信 Native 下单与主动查单；
• SkillHub 开发者密钥（skillhub）：用于 X402 预下单签名。

私钥均不得写入 Skill 包或仓库，须通过环境变量注入服务端。