「波动均匀度」高频选股因子

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

Overview

把「股票波动率」拆成波动的波动——信息分布越不均匀（信息冲击越集中）的股票越该规避，信息匀速流入的股票更值得持有。
本 Skill 是面向量化研究员 / 个人投资者的高频波动率选股因子工作台，把一套被公开文献验证过的方法论落成可复现的计算，一次调用完成三类动作：

1. UID 因子计算（波动的波动）：输入个股过去 N 个交易日的每日高频波动率序列，输出信息分布均匀度 UID = 每日波动率的标准差 ÷ 均值；UID 越高 = 信息越不均匀。
2. 因子有效性诊断：对任意 因子值 + 下期收益 截面面板，输出月度 IC / RankIC、年化 ICIR、10 分组多空对冲绩效（年化收益 / 波动 / 信息比率 / 胜率 / 最大回撤），并自动判定该因子是单调有效还是 U 型两端有效；可附加基准因子列做纯净因子（正交化残差）诊断，确认增量信息。
3. 极值端组合生成：按 UID 排序直接输出「信息最均匀端」（低 UID）的多头候选池，可接指数增强或自行调权。

方法经与公开文献中「波动率之波动率」因子的数值方向交叉校验（负向 IC、低波动端占优），可直接复现。

When to Use（触发条件）

• 「我想验证一个波动率类因子到底有没有区分力，别只信相关系数显著」
• 「给我算一下这个因子的 10 分组多空对冲，看是单调还是两头最赚」
• 「用我的分钟/日线数据算信息分布均匀度 UID 因子（波动的波动）」
• 「把这个因子对 VOL20 正交化，看剔掉传统波动率后还剩多少增量」
• 「按 UID 给我一份低波动端（最均匀）的股票池，我自己再调仓」
• 「把这套方法落成一个能按次跑的接口 / 工具」

Workflow（工作流）

本 Skill 为鉴权型：支付确认后，Agent 在本机跑 scripts/run_local.py 产出结果（不消耗服务端 LLM）。
数据契约见 references/rules.md。三种模式：

模式 A｜UID 因子计算（波动的波动）
- 输入：ticker,date,vol_daily 的 CSV（个股每日高频波动率时间序列，至少回看窗口个交易日）。
- 执行：python3 scripts/run_local.py --input <面板.csv> --mode compute [--lookback 20]
- 输出：每只股票最新月末 UID，及全样本 UID 均值、最低/最高端清单。

模式 B｜因子有效性诊断（默认）
- 输入：date,ticker,factor,ret 的 CSV（ret = 该截面之后一期收益；可附加 1+ 个基准因子列做纯净因子）。
- 执行：python3 scripts/run_local.py --input <面板.csv> --mode diagnose [--n 10]
- 输出：结论先行 + IC/RankIC 表 + 10 分组多空对冲绩效 + 单调性判定 +（若有基准）纯净因子。

模式 C｜极值端组合生成
- 输入：date,ticker,factor[,ret] 的 CSV（ret 可选，用于给出下期平均收益）。
- 执行：python3 scripts/run_local.py --input <面板.csv> --mode select [--bottom-pct 0.10]
- 输出：每个月末取因子最低端（信息最均匀端）的候选多头池。

> 完整算法与统计口径见 references/rules.md；输出模板见 references/output_templates.md。

Output（输出规范）

• 结论先行：报告首段给出单调性判定 + 关键数值（IC、年化 ICIR、多空年化收益、信息比率、胜率），再展开明细。
• 可复现标注：诊断结果与公开文献「波动率之波动率」因子方向一致（负向 IC、低波动端占优），作为权威佐证。
• 缺失即标「未获取」：列缺失、截面股票数不足分组数、序列长度不足回看窗口时，明确报出缺失项，绝不推测补造。
• 免责：报告末尾固定「本结果仅为量化统计研究，不构成投资建议」。

Notes / Constraints（约束）

1. 本 Skill 做统计研究，不预测、不荐股、不承诺收益；历史极值收益不代表未来。
2. 真实研报的 UID 使用分钟级高频波动率（剔除隔夜首分钟）。若你的 vol_daily 为日振幅等近似代理，方向一致但数值偏粗，仅作结构演示——脚本会在输出中如实标注。
3. 因子方向需与样本一致：低波异象下低 UID 端占优；若诊断显示方向反向，输出会提示核对因子定义。
4. 极值端组合为候选多头池，未做行业 / 风格中性与仓位管理，实盘需结合资金管理。
5. 取不到数据（文件缺失 / 列不对 / 空数据）一律打印「[未获取]」并返回错误，不编造。

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

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

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

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

• 统一网关主接口：POST https://pay.zerone-iteration.com/api/invoke
  （请求体 {"skill": "vol-uniformity-factor-lab", "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 → payment_code + X-Out-Trade-No → 主动查单 → paid:true → 本机履约）；生产真扣待绑定 SkillHub X402 商户后验证。
• 真实数据验证（诚实边界）：用腾讯日线接口拉取 100 只 A 股 2022–2023 真实日线，以「日振幅滚动 std/mean」作 UID 代理，跑通三类模式。结果：UID 代理因子区分力弱（月度 IC≈0.011、年化 ICIR≈0.28、10 分组多空年化≈2.0%、IR≈0.11），平波因子呈 U 型两端结构；与研报原文用分钟级高频波动率得到的强区分力不可直接等同——日线只有 OHLC、无法还原日内高频波动，代理天然偏粗。结论：算法正确、流程跑通，但真实强因子必须以分钟级高频波动率输入为准；脚本输出已据此如实标注，不夸大有效性。

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

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

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

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

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

• skill：必填，固定为本 Skill 的 slug vol-uniformity-factor-lab（与 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": "vol-uniformity-factor-lab", "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 包或仓库，须通过环境变量注入服务端。