换手率炼金炉

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

Overview

把「日频价量」构造为五种换手率选股因子的刻画，并统一做 IC、分档与多空诊断。输入是一张带 date,ticker,close（及可选 volume/turnover）的面板 CSV，输出是各因子在样本内的秩相关（Spearman IC）、ICIR、IC 命中率、十分位分档年化与多空组合表现，并标注代理口径与数据边界。

五种刻画同一条主线递进，共同基线为传统「量小换手率」：

• 量小（Turn20）：过去 20 日日均换手率，量越小越优（反转逻辑）。
• 量稳（STR）：过去 20 日换手率的标准差，成交越平稳越优；进一步可对已实现波动残差化得到 STR_deVol20。
• 量稳变化率（SCR）：当期 20 日波动相对基准 40 日波动的收敛/放大。
• 优加 1.0（UTR）：量稳与量小两维的非线性排序结合。
• 优加 2.0（UTR2）：在 STR 上以 softsign(STR)·Turn20 做等比尺度激活的组合。

覆盖边界：本 Skill 只做因子构造与样本内统计诊断，不做预测、不给买卖建议；分钟级「分布均匀度（UTD）」在日频口径下无法计算，会如实标注未获取。

When to Use（触发条件）

• 用户说「帮我检验一下量小/量稳换手率因子在样本内有没有效」时；
• 用户说「把这几只股票的换手率拆成稳定性和活跃度两个维度排个序」时；
• 用户说「优加换手率 1.0 和 2.0 哪个在我这份数据上更稳」时；
• 用户说「给我一份可复现的换手率因子 IC / 分档 / 多空报告，要和原始方法口径对得上」时；
• 用户说「日频数据没有流通股本，能不能用代理换手率先跑一版」时（明确标注代理口径）。

Workflow（工作流）

统一入口：scripts/run_local.py --input <面板.csv> --mode <范式>|all。支付未确认前不执行。

Step 1 取数：读取本地面板 CSV（见「输入数据规格」）。若缺 turnover 列则自动走相对换手率代理，并在报告中标注；若文件缺失/无必需列，报告实标「未获取」，不编造。

Step 2 选范式：--mode 决定跑哪套刻画，逐个调用 scripts/turnover_core.py：
- --mode turn20：基线「量小」因子 turn20；
- --mode str：STR（量稳）与 STR_deVol20（剔除已实现波动后的量稳残差）；
- --mode scr：SCR（量稳变化率）；
- --mode utr：UTR（优加 1.0）与 UTR_deTurn20STR（剔除量小/量稳暴露的正交残差，用于交叉校验风格暴露）；
- --mode utr2：UTR2（优加 2.0）；
- --mode utd：需分钟级成交量，日频口径下无法构造，如实标注未获取；
- --mode all：依次跑以上全部可计算范式。

Step 3 诊断：每月月底回溯窗口计算因子，对下一月收益做横截面诊断（月度调仓，ppy=12，10 档），输出 IC / ICIR / 命中率 / 分档年化 / 多空年化与回撤；--cost-bps 可附扣费后对照。

Step 4 出报告：--out 写 Markdown、--html 写可视化报告、--json 写原始结果；报告顶部固定订阅状态横幅（见 scripts/run_local.py 的 banner_md/banner_html）。

输入数据规格

CSV 列名（大小写不敏感）：

真实换手率缺失时，自动用代理口径 volume / 该股全样本长期均值成交量 逼近截面可比性；代理口径下绝对数值与真实换手率存在偏差，结论方向可比，生产应传入真实 turnover 列。

Notes / Constraints（约束）

• 本工具仅做因子计算与样本内统计诊断，不构成任何投资建议或买卖依据；历史有效不代表未来有效。
• 取不到的数据（如分钟级 UTD、缺失文件）一律标注「未获取」，绝不推测补造。
• 相对换手率代理口径下，绝对 IC / 多空数值为参考值，不应直接外推为实盘表现。
• 单只标的上市时长、ST、停牌等前置筛选未自动校验，请自行确认输入池质量。
• 高换手率因子的月均换手较高，落地需考虑交易成本，结论应以扣费后口径为准。

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": "turnover-alpha-lab", "skill_version": "1.0.1", "query": "...", "amount": 990}）
• 兼容入口：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+版本即可
• 状态：联调结论见 实测报告_turnover-alpha-lab.md（DEV_MODE 模拟链路已跑通，生产须填齐密钥并置 DEV_MODE=false）。

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

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

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

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

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

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