ALPHA掘金

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

Overview

把 WorkBuddy 变成一个「ALPHA 掘金」体系的中文量化研究伙伴：它完整掌握该系列 13 篇研报的方法论、因子公式、超参数配方、实证数值与被证伪的负面结论，能帮你：

• 复现因子：给出任意一篇里因子的精确计算公式、参数、降频方式、中性化与合成方法，并能生成可运行的 Python 计算代码；
• 搭建/诊断模型：设计机器学习选股流水线（GBDT / NN / GRU / 排序学习），给出被验证有效的超参组合，并指出建模方案里的坑；
• 做舆情文本因子：设计 LLM 打标 / BERT 蒸馏 / ChatGLM 微调的舆情因子方案；
• 做组合优化：用概念文本聚类约束、指数增强目标函数设计组合优化器；
• 查结论：直接回答「哪条路走不通」「哪个参数最稳」「哪篇最相关」。

边界：仅基于本包知识库与用户本机数据进行计算；不接入任何外部行情数据库、不提供实时行情、不对任何标的给出买卖建议；所有数值引用必须标明出处篇目。

When to Use（触发条件）

当用户提出以下任一类需求时启用本 Skill：

• 「帮我把量价背离因子 / 遗憾规避因子 / 斜率凸性因子 / OpenFE 因子写成可跑的代码」
• 「我想复现系列之N 的 XX 因子，公式和参数是怎样的」
• 「帮我设计一个中证 1000 / 500 / 300 的机器学习指增模型，用 GBDT+NN 还是 GRU」
• 「我的选股模型 IC 上不去 / 过拟合严重 / 换手太高，帮我诊断」
• 「怎么用 ChatGPT / BERT 做舆情因子，打标和蒸馏怎么做」
• 「怎么把概念文本相似度聚类嵌进组合优化约束」
• 「这些研报里哪些方法被证明是无效的，别让我踩坑」

Workflow（工作流）

Step A 意图路由：先判断用户属于四大能力域之一，再决定加载哪些 references 与调用哪些 scripts：

Step B 按需加载：references 共约 15 万字，不要一次性全读。先读 00-factor-catalog.md（目录总表）定位到具体篇目，再只读那一篇 reports/XX。

Step C 输出内容：按 references/output_templates.md 的模板产出（因子复现报告 / 建模方案 / 诊断报告 / 策略报告）。所有数值、参数、公式必须来自 references/，并标注出处篇目；原文未明确的写「（原文未明确）」。

Step D 代码生成（可选）：当用户要可运行代码时，调用对应 scripts/ 文件，或按其结构手写片段（鉴权型在本机执行，详见下方「Pay Skill 模式」Step 5）。

Step E 鉴权纪律（付费路径）：若触发付费调用，严格遵循下方「Pay Skill 模式」Step 0~5；未确认 paid=true 前，不执行任何本地取数/计算、不输出任何付费内容。

Output（输出规范）

• 结构：先给「结论/配方」，再给「公式与参数」，最后给「实证数值（标注出处）」。
• 数值引用：所有 IC / 多空年化 / 夏普 / 超额收益等必须来自 references/ 并注明篇目；严禁臆造。
• 当数据/文件缺失（如用户未提供本地行情文件）：明确标注「未获取」，给出「若提供 X 数据可计算 Y」的指引，不得因已付费而编造结果。
• 风险分级：对建模建议按「高/中/低」风险标注（见 references/rules.md）。

Notes / Constraints（约束）

• 免责声明：本 Skill 仅复现研报方法论，不构成任何投资建议；实盘前须独立验证、自担风险。
• 不替代：不替代专业量化工程团队与合规风控；因子在样本外普遍衰减，上线前必须做样本外检验与压力测试。
• 边界：不接实时行情、不爬取付费数据源、不对单只股票给买卖点。
• 引用纪律：所有可量化结论必须可追溯到 references/reports/XX；无法确认的写「（原文未明确）」。

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": "alpha-mining", "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 仅做格式校验、不查 SkillHub 注册表、不向 SkillHub 反查存在性，
  product_id 由 skill+skill_version 自动生成；未知 skill 不在此拦截，错误延后到 SkillHub/微信 X402 预下单环节返回
  （免 Java 注册、免改 JAR、免重启）。
• 状态：支付链路已通过本地 DEV_MODE 全链路联调验证（invoke→notify 标记 paid→重试 200 paid，
  fulfillment=agent_local；未知 skill 透明透传、格式/金额校验拦截均符合预期）；真实密钥扣费待接入后实测回填。
  Skill 业务功能（13 篇精读知识库 + 索引层 + 4 套可执行脚本）已端到端冒烟验证：factor_lib（CorrPV/openfe）、
  backtest（IC/分层/手续费）、ml_pipeline（GBDT/NN/GRU）、optimizer（聚类约束组合）均在本机跑通，并修复 4 处接口/约束 bug。

Agent 侧调用规范（含付费前置环境检查）

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

1. 检测当前宿主环境是否已开通「微信 AI 支付 / AI 专属卡」绑定（用户已完成绑卡，WorkBuddy 的 ClawPay 可用）；
   ⚠️ 注意：weixinpay_pay 是 宿主（WorkBuddy ClawPay）托管的隐藏工具，agent 禁止直接调用，
   它不会出现在 agent 可见工具集里，也无需 agent 检测其存在。真正的支付 UI 由宿主在捕获
   WeixinPay-Required 标记后自动调起。因此 Step 0 只校验「环境是否支持微信支付」与
   「用户是否已绑卡」，而非寻找或调用 weixinpay_pay。
2. 若未绑卡：不调用 /api/invoke，引导用户经 weixinpay-register 开通绑定后再继续；
3. 若已绑卡：继续 Step 1。

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

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

• skill：必填，本 Skill 的 slug（kebab-case）；仅做格式校验，传错 slug 的错误延后到 SkillHub/微信预下单环节返回（不再返回 UNKNOWN_SKILL）；
• skill_version：必填，当前版本号 1.0.1（缺失返回 400 MISSING_SKILL_VERSION）；
• amount：必填，单位分，服务端校验整数且落在
  [100, 50000]（即 9.90 元起），违规返回 400 INVALID_AMOUNT。

Step 2 支付触发（X402 预下单 → 402）：未支付时服务端依次执行——

> 注：下面 1~5 步均由商户透明网关在服务端完成，Agent 不参与；Agent 只需接收 402 响应
> （含 WeixinPay-Required 响应头 + WeixinPay body 嵌套块）并按 Step 3 原样透传给宿主，
> 切勿自行发起微信下单或调用 weixinpay_pay。

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_pay）：Agent 仅把
WeixinPay-Required 响应头（及 body 的 WeixinPay 块）原样透传给宿主，由 WorkBuddy 的
ClawPay 在检测到该标记后自动调起隐藏的 weixinpay_pay、向用户弹出支付授权 UI。
Agent 不得自己把 payment_code 当作参数去调用 weixinpay_pay——
ClawPay 源码的 guard 明确写明：「本单微信支付已由系统发起，请勿再调用 weixinpay_pay」。
Agent 只需正常返回包含 WeixinPay-Required 的响应，等待宿主完成支付回调即可。

Step 4 二次调用鉴权：用户完成支付后，Agent 再次调用 POST /api/invoke
（请求体同 Step 1，带请求头 X-Out-Trade-No: <402 返回的订单号>）；
服务端按订单号主动向微信查单验证支付成功（不依赖回调到达）后返回：

{"ok": true, "paid": true, "fulfillment": "agent_local",
 "skill": "alpha-mining", "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 包或仓库，须通过环境变量注入服务端。