风险优化下的 SmartBeta 策略

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

Overview

基于风险的 SmartBeta 是一类「不靠市值加权、而靠风险结构来分配权重」的资产配置方法。本技能把四类经典风险模型——最小方差（GMV）、等权（EW）、等风险贡献（ERC / 风险平价）、最大分散度（MDP）——统一到同一个优化框架之下：

w*(λ,γ,δ) = argmin ½ wᵀΣw − λ·D(w;γ) + (λ−1)·B(w;δ),  s.t. w ≥ 0
  D(w;γ) = γ·Σln wᵢ − (1−γ)·Σwᵢ²      （分散度约束：权重分散 ↔ 风险分散）
  B(w;δ) = δ·Σwᵢ + (1−δ)·Σwᵢσᵢ        （预算约束：等权方向 ↔ 风险预算方向）

通过三个参数即可在四类模型间平滑切换，并构造混合模型；进一步把「市场状态」引入 λ，得到依牛熊切换的动态 SmartBeta。技能提供四项可直接落地的能力：

1. 风险组合权重求解：给定资产收益序列，输出 GMV/EW/ERC/MDP 或任意 (λ,γ,δ) 混合组合的权重；
2. 四维分散度诊断：用波动率降低 VR、权重分散 WD、风险分散 RD、分散比率 DR 判定组合「到底分散没分散」，并指出它最像哪类经典模型；
3. 静态回测对比：在真实数据上对比四类模型的年化/波动/最大回撤/夏普/胜率；
4. 动态再平衡：以 EW 组合滚动波动率为市场情绪代理，熊市偏 ERC/GMV 控波动、牛市偏 EW 博贝塔，输出权重时序与回测。

方法经与原始文献数值交叉校验，可直接复现：ERC 的风险贡献严格相等（TRC 占比=1/N）、GMV 波动率降低最优、MDP 分散比率最优、EW 权重分散最优，均在合成与真实数据上得到验证。

When to Use（触发条件）

• 「我想用风险平价 / 最小方差 / 最大分散度建一个组合，直接给我权重」
• 「别只给我一个比例——告诉我这个组合到底分散没分散（GMV 还是 ERC 还是 MDP）」
• 「这几只票/这几类资产的相关性高，风险模型还有没有用？帮我回测看看」
• 「现在市场情绪怎么样，股债金该怎么配、什么时候该加债券控回撤」
• 「把这套统一框架落成一个能按次跑、能出回测证据的接口/工具」

Workflow（工作流）

用户须先提供资产收益数据：scripts/fetch_assets.py 拉真实 A 股月线构造长表 assets.csv（列 date,ticker,ret，ret 为当期收益率）；或用户自带同格式 CSV（支持任意标的池：股/债/金大类资产、行业指数、个股均可）。流程读取 references/rules.md 的求解与回测细则。

1. 风险组合求解：python3 scripts/run_local.py --input assets.csv --mode optimize --model erc
   → 输出该模型权重 + 四维分散度指标；--model hybrid --lam <λ> --gamma <γ> --delta <δ> 可求任意混合组合。
2. 分散度诊断：python3 scripts/run_local.py --input assets.csv --mode diagnose
   → 四类经典模型 VR/WD/RD/DR 对照表 + ERC 下各资产风险贡献占比（判定是否真「等风险贡献」）。
3. 静态回测对比：python3 scripts/run_local.py --input assets.csv --mode backtest [--window 12]
   → GMV/EW/ERC/MDP 四策略绩效对比 + 净值曲线 SVG。
4. 动态再平衡：python3 scripts/run_local.py --input assets.csv --mode dynamic [--window 12]
   → regime-based 动态组合回测 + λ(t) 曲线 SVG（牛熊切换一目了然）。

> 透明网关（付费）下 Agent 收到 paid:true 后才在本地执行上述脚本；支付未确认前不取数、不输出付费内容。

Output（输出规范）

• 结论先行 + 可复现标注：报告首段给出判定结论与证据（如「ERC 下各资产 TRC 占比均为 0.25，风险贡献严格相等；与风险平价文献一致」），不堆方法论铺垫。
• 权重表：各资产权重（降序）+ 组合波动率 σ_p + VR/WD/RD/DR 四象限。
• 回测对比表：累积/年化收益率、年化波动率、最大回撤、信息比、月度胜率、回测月数。
• 边界如实标注：高相关标的池下 ERC 与 EW 趋于重合（资产波动率相当时 ERC 收敛于 EW），风险模型分散度有限——与原文结论一致；沙箱用 A 股大盘股作真实数据验证，非原文股/债/金大类资产，生产可换自有池。
• 取不到数据 / 列不对 / 截面月份不足 → 标注「未获取」，不推测补造。

Notes / Constraints（约束）

• 免责：本结果仅为量化统计研究，不构成任何投资建议；历史表现不代表未来，模型存在失效风险（市场风格切换、相关性结构突变均可能导致风险模型失效）。
• 数据契约：输入长表 CSV 列须为 date,ticker,ret；date 月末截面、ret 为当期收益（已与下期对齐、无前视）；缺失值按截面剔除，不插值补造。
• 协方差估计：回测默认用前 12 个月滚动窗口估计协方差（行业惯例），窗口不足自动跳过该期再平衡；全样本诊断用全部可用截面。
• 动态模型边界：动态 λ 公式对观测期 σ 的极值敏感，极端行情可能使 λ 触及边界（1 或上限）；λ 区间受观测窗口影响，建议用滚动窗口估 σ⁺/σ⁻。动态模型夏普与传统风险模型同量级（原文亦指出牛熊划分精度限制了夏普提升）。
• 相关性结构敏感：风险模型在「低相关、可分散」的标的池（如股/债/金）上回撤与波动控制优秀，但在「高相关」池（如单一市场行业指数）上分散度有限——这是方法本身的已知边界，非实现缺陷。
• 未做杠杆：本技能默认 long-only、不引入债券杠杆；原文提及债券可加杠杆增厚收益，生产可酌情扩展。

Pay Skill 模式（鉴权型，按次付费，已接入 X402）

本 Skill 默认以「提示词型」运行于 WorkBuddy 内，免费使用。作为付费技能（Pay Skill），
已通过腾讯 SkillHub + 微信支付 Agent Pay X402 协议接入按次收费。

鉴权型：履约在本机执行（需调用本地取数脚本 / 解析本地或远程资产收益文件），
远端网关只负责订单鉴权与支付状态确认，支付通过后返回 fulfillment: "agent_local"，
不返回业务结果；Agent 收到 paid: true 后才在本地跑 scripts/ 下的脚本产出结果。

• 统一网关主接口：POST https://pay.zerone-iteration.com/api/invoke
  （请求体 {"skill": "risk-optimized-smartbeta", "skill_version": "1.0.0", "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+版本即可
• 状态：已完成本地算法在真实 A 股数据上的验证（见交付物 实测报告）；付费链路 402 结构由 pay/server.py 提供，
  上线前需 DEV_MODE=true 验结构、再切生产密钥实测 1 元真扣（未做生产真扣联调）。

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

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

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

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

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

• skill：必填，固定为本 Skill 的 slug risk-optimized-smartbeta（与 SkillHub 已发布的一致；透明网关下传错 slug 时错误延后到 SkillHub/微信预下单环节才返回）；
• skill_version：必填，当前版本号 1.0.0（缺失返回 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": "risk-optimized-smartbeta", "out_trade_no": "...", "already_fulfilled": false}

Step 5 本地履约（本 Skill 的关键差异）：Agent 收到 paid: true 且
fulfillment: "agent_local" 后，在本机执行 scripts/ 下的脚本产出结果
（见 scripts/run_local.py），再把结果交付给用户。
支付未确认前，不执行本地取数脚本、不输出任何付费内容
（未支付重试返回 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 包或仓库，须通过环境变量注入服务端。