高频数据量化因子研究

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

Overview

这是一个高频/量价因子研究工具，不是选股工具。

它回答三个问题：
1. 因子怎么造——把一只股票某交易日的分钟级 open/high/low/close/volume 行情，按成熟的量价方法论加工成一组因子值（已实现偏度、价量相关性、尾盘成交量占比、盘前集合竞价收益率、大成交量时段统计量……）；
2. 因子好不好——给定一张「因子值 × 下期收益」面板，用 IC / RANK_IC / ICIR / 十分位多空 / 正(负)Alpha 量化它的选股区分力，并自动判定「单调型 vs 两端型」有效；
3. 站在谁的肩膀上——把你的因子和一组已发表的周频量价因子（全市场统计特征）放在同一张表里对比，看它处于什么水位。

方法论来自广发证券《多因子 Alpha 系列报告之（四十八）：高频数据的因子化研究》，从四个维度构建 55 个周频选股因子，报告筛选了 12 个选股能力较好的因子作为基准。本 Skill 把这套可迁移的方法沉淀为可复现的零依赖算法（纯 Python 标准库），结论可与原文数值交叉校验。

四大因子维度（55 个因子族）

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

• ❌ 不输出股票名单、不做因子打分排序、不构建股票池——本 Skill 是因子研究工具，不是选股/荐股工具；
• ❌ 不预测涨跌、不给买卖点、不做择时——只做因子值计算与已发生收益的统计归因；
• ❌ 不评价"好/坏"——只给描述性结论（如「RANK_IC=−5.91%，多空年化 54.43%」），不说"这个因子值得用/该买"；
• ❌ 不自动联网抓取分钟级行情。分钟行情由用户提供（CSV），或由用户在 WorkBuddy 内通过已授权数据源取数后交给本 Skill；
• ❌ 不替代合规披露或实盘交易决策。

When to Use（触发条件）

A. 想从分钟行情挖因子（首要场景）

• 用户说「帮我把这批分钟行情算成高频因子」「从 tick/分钟数据做价量因子工程」时；
• 用户说「算一下 corr_VP / Amihud_illiq / 尾盘成交量占比」「把日内已实现偏度做出来」时；
• 用户有分钟级 open/high/low/close/volume，想批量产出因子面板喂给回测/选股框架时。

B. 想给已有因子做体检

• 用户说「我有个因子，帮我看看 IC / 多空收益」「这个因子的 RANK_IC 怎么样、显著吗」时；
• 用户说「我的因子是单调有效还是两端有效」「十分位分布是不是 U 型」时；
• 用户有 date,ticker,factor,ret 面板（ret = 持有期收益），想量化区分力与显著性时。

C. 想和已发表因子对标

• 用户说「我的因子和文献里的高频因子比怎么样」「这个因子在多空年化上处于什么水平」时；
• 用户想在动手之前先知道：文献里那些量价因子到底有多强，自己的因子有没有增量。

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

• 「帮我选几只股票」「按这个因子给我一个股票池」「哪只值得买」→ 属选股与投资建议，不做。

Workflow（工作流）

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

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

Step 1（构造因子）——从分钟行情产出因子面板

python3 scripts/run_local.py construct \
    --minute minute.csv [--premkt premkt.csv] \
    [--factors real_skew,corr_VP,Amihud_illiq] \
    --out factors.csv --report report.md

默认计算报告精选的 12 个因子；--factors 可指定任意因子名（支持全部 55 个因子族中的可计算项）。
输出 factors.csv（列：date,ticker,<因子1>,<因子2>...）与可选 Markdown 报告（含各因子覆盖度）。

Step 2（因子体检）——对 date,ticker,factor,ret 面板做有效性诊断

python3 scripts/run_local.py evaluate \
    --panel panel.csv [--periods-per-year 52] [--n-groups 10] [--min-stocks 20] \
    --out report.md [--svg decile.svg]

报告重点：RANK_IC / IC / ICIR / 方向胜率 / 多头·空头·多空年化 / 正(负)Alpha / 十分位收益形态（单调 vs U 型）/ 有效性判定（含多空 t 值显著性）。
--svg 额外输出一张零依赖的十分位年化收益分布图。

Step 3（文献对标）——与 12 个已发表周频量价因子同台对比

python3 scripts/run_local.py benchmark --panel panel.csv --out report.md

报告把你的因子的 RANK_IC / 多头年化 / 多空年化 / 正Alpha 与文献基准（全市场统计）并列，
给出「击败基准 12 因子中的几个」的水位结论。

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

python3 scripts/run_local.py demo --out report.md

用程序生成的合成分钟行情 + 合成面板跑通「因子构造 → 评价引擎 → 判定」全链路。结论无投资含义，仅用于排查环境。

Output（输出规范）

• 默认输出中文 Markdown 报告，结构见 references/output_templates.md；
• 数字口径：收益率统一用百分比展示（保留 2 位小数），IC/RANK_IC 保留 4 位小数，ICIR/t 保留 2 位；
• 显著性标记：多空 t 值 |t|>2 记为显著，否则不显著；
• 缺失处理：取不到的数据一律写「未获取」并说明原因，严禁因为用户已付费而推测补造；
  截面期数不足或单期样本 < min_stocks 时直接报错并说明需要多少期，不得硬算；
• 结论纪律（两条都必须严守）：
• 因子弱（RANK_IC 绝对值偏小、多空年化低）时必须明确说「未呈现稳定区分力」，不夸大；
• 只描述，不评价。不出现"好/差/值得用/该买"等评价性措辞，不输出任何股票名单或标的排序。
  用户追问"那我买什么"时，如实说明本工具不提供该功能。

Notes / Constraints（约束）

• 免责声明：本 Skill 产出的是因子研究的统计结果，不构成投资建议，不预测未来收益。
  每份报告末尾必须带风险提示（因子拥挤、过拟合、样本外失效风险）。
• 不替代：不替代合规披露、实盘交易决策或任何投资建议。
• 样本量底线：评价至少需 2 期有效截面、且每期 ≥ min_stocks 只（默认 20），否则无法计算多空与 ICIR。
• 频率一致性：面板内 date 须为同一频率（周/月/日），periods_per_year 须与之匹配，否则年化失真。
• 因子方向：RANK_IC 的正负决定多头端在因子高值还是低值侧；评价引擎自动判定方向，无需用户指定。
• 单调 vs 两端：评价引擎会诊断因子是「线性排序即有效」（单调型）还是「信息集中在极值端」（两端/U 型），
  并据此提示更适合的取数方式（全排序 vs 取极值端）。
• 分钟窗口映射：A 股 8 个半小时窗口按交易时段连续映射——上午 09:30–11:30（W1–W4）+ 下午 13:00–15:00（W5–W8），
  午休跳过，与报告「每 30 分钟一段」口径一致；ratio_volumeH8 即尾盘半小时（14:30–15:00）成交量占比。
• 盘前因子依赖集合竞价数据：ret_open2AH1/AL1 等需要盘前 CSV 提供两阶段集合竞价最高/最低价，缺失时自动跳过该类因子。
• 被误当成选股工具时：用户问「那我买什么」「给我一个股票池」时，如实说明本 Skill 是因子研究工具，
  不具备选股能力，不要拿因子结果反向拼凑标的推荐。

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": "hf-quant-factor-research", "skill_version": "1.0.1", "query": "...", "amount": 100}）
• 兼容入口：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 跑通「因子构建 → 评价引擎 →
  有效性判定」全链路；算法层 12 个基准因子的 RANK_IC/多空年化/正Alpha 已与公开研报数值交叉校验一致。
• 已验证（2）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": "hf-quant-factor-research",
  "skill_version": "1.0.1",
  "query": "用户原始需求（用于订单留痕，不作为履约输入）",
  "amount": 100
}

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