消费板块量化研究员（按次）

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

Overview

把 WorkBuddy 变成一名「消费板块量化研究员」：输入一份消费板块因子面板（或一键拉取真实数据），落成可复现的选股研究体系——四类能力覆盖从「单个因子灵不灵」到「多因子组合怎么配」的完整链路：

• 单因子体检：给定任一因子，在消费板块做 RankIC / t 值 / 月度胜率 / 多头超额 / 多空收益差 / 截面溢价 / 分 10 组形态，一眼看出「单调有效」还是「U 型两端有效」，判定该因子是否真有区分力。
• 因子相关性诊断：把多个因子的「多头-板块等权」超额收益做时间序列相关性，识别冗余因子（强相关→复合提取公共部分）与互补因子（跨类低相关→分散降波动）。
• 多因子组合回测：把若干因子横截面标准化后复合，取 Top-N 构建组合，输出年化收益、波动、信息比、最大回撤、收益回撤比、换手率与分年度表现——方法经与公开文献数值交叉校验，可直接复现。
• 选股池生成：指定截面日，输出复合得分最高的 Top-N 股票池（含代码、名称、行业、得分），供你进一步人工调权。

整个方法论脱胎于一套被反复验证过的消费板块因子组合研究，卖点是「算得对、可复现、与公开结论一致」，不是通俗科普。

When to Use（触发条件）

• 用户说「我想验证某个因子在消费板块到底有没有选股能力」时。
• 用户说「别只看相关系数显著——给我分 10 组看是单调还是 U 型两端」时。
• 用户说「这几个因子我怕重复计算了，帮我看看相关性」时。
• 用户说「按小市值+低波动+反转（或盈利+增长+价值）给我配一个消费板块组合并回测」时。
• 用户说「按这个因子配方给我一份最新的消费板块选股池」时。

Workflow（工作流）

两种数据入口（取数由 Agent 在本机执行，支付确认后才跑）：

• 入口 A — 自备面板：用户提供宽面板 CSV（date,ticker,ret,<因子列...>，可选 name/industry/mktcap）。直接进分析。
• 入口 B — 一键真实数据：用户未自备数据时，Agent 运行 fetch 拉取消费板块（7 个中信一级行业）真实月线并构造因子面板（反转/波动率/动量/非流动性/市值），落盘为 CSV。

1. 取数：
   - 入口 A：直接用用户 CSV。
   - 入口 B：python3 scripts/run_local.py fetch --out <dir>/panel.csv（腾讯月线，沙箱可用；取不到标注未获取，不编造）。
2. 单因子体检：python3 scripts/run_local.py check --input panel.csv --factor-col <因子列> --out <dir> → check_report.md + decile.svg。
3. 因子相关性诊断：python3 scripts/run_local.py corr --input panel.csv --factors <列1,列2,...> --out <dir> → corr_report.md。
4. 多因子组合回测：python3 scripts/run_local.py combo --input panel.csv --factors <列...> --signs "size=-1,roe=+1,..." --top-n 30 --scheme equal --benchmark equal --out <dir> → combo_report.md + nav.svg。
5. 选股池生成：python3 scripts/run_local.py pool --input panel.csv --factors <列...> --signs "..." --top-n 20 --out <dir> → pool_report.md。
6. 汇总交付。支付未确认前不执行取数脚本、不输出任何付费内容。

Output（输出规范）

• check：check_report.md（结论先行 + 指标 + 分10组形态）+ decile.svg（红涨绿跌柱状图）。
• corr：corr_report.md（相关系数矩阵 + 冗余/互补诊断）。
• combo：combo_report.md（结论先行 + 核心指标 + 分年度）+ nav.svg（组合 vs 基准净值）。
• pool：pool_report.md（Top-N 排名表）。
• 报告首行即结论先行（IC / 形态 / 多空 / 年化超额），再展开明细。
• 缺失处理：截面股票数 < 分组数或某期无收益则跳过并标注；取不到的数据标注「未获取」，严禁推测补造。

Notes / Constraints（约束）

• 本结果为量化统计研究，不构成任何投资建议；历史极值收益不代表未来。
• 本 Skill 默认不做行业中性 / 市值中性 / 正交处理；如需剔除市值等低频因子后的正交 IC，请在输入面板放入已正交因子列再诊断。
• 因子方向（sign）是组合成败关键：小市值/低波动/反转/低估值为 -1，盈利/成长/动量为 +1；若你的因子定义相反请用 --signs 覆盖。
• 实证结论高度依赖样本（行业覆盖、市值分布、区间）。精选龙头池可能弱化经典因子效应；用你自己的消费板块全样本（含中小市值、覆盖 7 个中信一级行业）才更易复现公开区间（见 references/empirical_evidence.md）。
• 选股池为截面排序结果，未含交易成本与流动性冲击，实盘需自行校验。
• 取不到的数据标注「未获取」，不编造。

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": "consumer-quant-researcher", "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+版本即可
• 状态：真实数据主链路已跑通（fetch→check→corr→combo→pool 全流程，见 references/empirical_evidence.md）；付费链路按 DEV_MODE 冒烟通过（402 → 回调置位 → 携带 X-Out-Trade-No 重试返回 paid:true，履约模式 agent_local），可提交 SkillHub 审核。

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

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

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

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

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

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