地理关联度因子量化研究员

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

Overview

把 WorkBuddy 变成一个地理/行业关联度因子的量化研究员：把「股票与其地理邻近（同省异业）或行业关联（同业异省）公司的收益联动」落成可复现、可回测的关联度因子，并给出严格的统计体检。

覆盖四类能力：

1. 因子构造（construct） —— 从日频收益 + 省份/行业标签，计算地理关联因子族 GEOGCORR / *_P / *_N / *_IP / *_JP（共 5 列）与行业关联因子族 INDUCORR / *_P / *_N / *_IP / *_JP（共 5 列），输出月频截面因子面板。
2. 有效性体检（check） —— 对任一因子列给出 RankIC / t 值 / 月度胜率 / 多空差 / 多头超额 / 截面溢价，并做分 10 组下期收益形态诊断（单调 / 反转 / U 型 / 倒 U 型）。
3. 增量信息诊断（incremental） —— 计算因子与风格因子（市值 / 价值 / 动量等）的横截面相关性，量化与传统因子的冗余度，论证「是否挖到增量 alpha」。
4. 行业/地域分层（subgroup） —— 按行业或省份分组独立跑 IC，定位因子最适用的细分股票池。

边界：本 Skill 是量化研究方法，不是荐股工具；不访问任何交易系统；不输出具体买卖建议；取不到的数据一律标注「未获取」，绝不推测补造。全部算法零第三方依赖（仅标准库 csv/math），可审计、可复现。

When to Use（触发条件）

• 用户说「帮我把地理关联度因子 / 行业关联度因子做出来 / 回测一下」时；
• 用户已有（或本 Skill 取数得到）一支带省份 / 行业标签的股票池与日频收益，想验证其选股能力（IC、多空、分 10 组形态）时；
• 用户想判断某个关联度因子是否与传统风格因子冗余、能否作为增量 alpha 加入多因子模型时；
• 用户想看因子在哪些行业 / 哪些省份更有效（分层定位）时；
• 用户拿到日频收益面板，想「一键出因子体检报告 + 分 10 组图」时。

Workflow（工作流）

> 付费场景下，本流程仅在支付（paid=true 且 fulfillment=agent_local）后才在本机执行（见下方 Pay Skill 模式 Step 5）。未支付前不取数、不输出任何付费内容。

1. 取数（fetch）：读 references/rules.md 的取数口径 → 跑 scripts/fetch_association.py 拉取精选异质股票池的日频前复权行情（沙箱可用腾讯日线；真实环境把 UNIVERSE 换成你的股票池文件即可，算法不变），输出 date,ticker,close,ret,province,industry,name 长面板。
2. 构造因子（construct）：读 references/output_templates.md 的因子列定义 → 跑 scripts/run_local.py construct，调用 geo_factor.construct_factors 生成月频截面因子面板（10 个因子列）。
3. 体检 / 诊断（check / incremental / subgroup）：按需跑 scripts/run_local.py 对应模式，分别调用 geo_factor.check_factor / incremental_diagnose / subgroup_ic，输出 Markdown 报告（check 模式另出 decile.svg 分 10 组图）。
4. 一站式（all）：scripts/run_local.py all 自动串起「取数→构造→对 GEOGCORRP / INDUCORRP / INDUCORR 三列体检」，适合首次快速看整体。
5. 交付：把报告与图交付用户，并附风险提示（历史有效不代表未来有效、因子换手率高需计交易成本）。

Output（输出规范）

• 构造产物：月频截面面板 CSV，列含 date,ticker,name,province,industry,ret + 10 个因子列（GEOGCORR/GEOGCORRP/GEOGCORRN/GEOGCORRIP/GEOGCORRJP/INDUCORR/INDUCORRP/INDUCORRN/INDUCORRIP/INDUCORRJP）。
• 无关联股的样本（如全省 / 全行业仅此一支）如实留空（NaN），不编造关联对。
• 体检报告（check）：结论先行（RankIC / t / 胜率 / 多头超额 / 多空 / 形态）→ 选股能力指标表 → 截面溢价 → 分 10 组形态表 + SVG 图。
• 增量报告（incremental）：各风格因子横截面相关 + 解读（|r|<0.3 增量充足，>0.5 强冗余）。
• 分层报告（subgroup）：按行业 / 省份的 RankIC、t、胜率、多空收益排序表。
• 质量分级：统计显著性为唯一硬门槛——RankIC t≥2 且 月度胜率≥55% 视为有效；|IC|<0.01 或 溢价 t<2 明确提示「可能仅为统计噪声，不构成投资建议」；样本不足（截面 <10 只）时该期剔除并标注。
• 缺失处理：取数失败 / 文件缺失 → 输出「[未获取] + 原因」，不跳过、不编造。

Notes / Constraints（约束）

• 免责声明：本 Skill 输出为量化统计研究，不构成任何投资建议，历史有效不代表未来有效。
• 换手率敏感：关联度因子多头月度换手常达 80% 上下，实盘务必计入交易成本，否则多空收益会被显著侵蚀。
• 样本与口径：构造默认回看 window_days=21（约一个月）交易日、关联股 min_peers=2；省份 / 行业标签以用户提供的为准，标签错误会直接污染因子。
• 不替代：不替代组合构建、风险预算与交易执行；不与任何券商 / 交易系统直连。
• 数据诚实：任何取不到的行情 / 标签一律标注「未获取」，从不推测补造。

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": "geo-association-factor", "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+版本即可
• 状态：付费链路（X402 预下单 / 402 / 主动查单 / 幂等）的服务端参考实现与契约已就绪并通过发布自查（29 项全绿）；端到端联调需在生产网关 + 真实微信支付商户下实测，本包未含生产密钥、未做真机联调，故不写「已通」。接入时按 pay_skill.yaml 填齐两套密钥并置 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": "geo-association-factor",
  "skill_version": "1.0.1",
  "query": "用户原始需求（用于订单留痕，不作为履约输入）",
  "amount": 500
}

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