持仓CT机

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

Overview

把 WorkBuddy 变成一台持仓 CT 机：给任意持仓做两次扫描，回答两个问题——收益从哪来（风格归因）与风险有多大（风险预测）。

• 第一次扫描（收益归因）：用带约束条件的加权最小二乘（WLS）对截面收益做回归，把市场因子（截距项）、行业因子与 9 类风格因子（Beta / 规模 / 估值 / 成长 / 流动性 / 长期动量 / 短期动量 / 波动率 / 非线性规模）拆开，输出纯净因子收益与组合在各因子上的暴露百分位；再把给定组合的收益逐项拆成各因子贡献与残余 alpha。
• 第二次扫描（风险预测）：用结构化方法估计协方差矩阵 V = X·F·Xᵀ + Δ——因子协方差 F 依次走 EWMA（半衰期 90）→ Newey-West 自相关调整（滞后期 2）→ 特征值调整（蒙特卡洛去偏，调整系数 1.2）→ 波动率偏误调整（半衰期 42）；特异风险 Δ 依次走 EWMA（半衰期 90）→ Newey-West（滞后期 5）→ 结构化模型调整（协调参数 γ、去偏常数 1.05）→ 贝叶斯收缩（压缩系数 1）→ 波动率偏误调整。由此预测组合未来 21 日波动，并用偏差统计量检验"算得准不准"，最后可选输出 long-only GMV 最小方差权重与基准对比。

覆盖范围：给定因子面板（date, ticker, ret, mktcap, 可选 industry/turnover/pe/pb/ps）与持仓权重，输出归因表、暴露百分位、波动预测、偏差检验、GMV 权重五类结果。
不做什么：不荐股、不给目标价、不预测涨跌方向、不访问任何外部行情接口（数据完全由用户提供的 CSV 传入）、不承诺任何收益。

When to Use（触发条件）

• 用户说「我今年赚的钱到底是哪来的？是选股能力还是风格暴露？」
• 用户说「我的组合在小市值 / 高 Beta 上押了多少？给我看暴露百分位」
• 用户说「我这个组合下个月波动大概多少？会不会失控？」
• 用户说「我的风险模型算出来的波动跟实际差多少？模型到底可不可信？」
• 用户说「成分股不变，有没有比我现在的权重更稳的组合？」（GMV 最小方差）
• 用户说「帮我做一次多因子归因 / Brinson 之外的风格归因 / 风险归因」

First-Use Configuration（首次使用时收集）

Workflow（工作流）

1. 确认输入面板：读 references/rules.md「输入契约」一节。必须列 date,ticker,ret,mktcap；可选列 industry,turnover,pe,pb,ps,bench。缺 mktcap 直接判定无法履约（WLS 权重与规模因子都依赖它），如实告知用户补齐。
2. 确认订阅与付费状态：读下方「订阅状态横幅」一节，先确定本次是已订阅还是按次购买。
3. 确认扫描项目：默认跑 all（归因 → 暴露 → 风险 → 偏差检验 → GMV）。用户点名某一项时切到对应 --mode。
4. 执行履约：
   bash python3 scripts/run_local.py --input <panel.csv> --mode all \ [--weights <weights.csv>] [--out <输出目录>] [--svg] \ [--subscription "<渠道名>"]
weights.csv 列：ticker,weight（缺则默认按最新截面市值权重构造组合）。
5. 出报告：按 references/output_templates.md 的模板渲染，结论先行；取不到的项标「未获取」，绝不编造。
6. 交付：报告首位固定输出订阅状态横幅，末尾固定免责句（见 references/output_templates.md）。

Output（输出规范）

订阅状态横幅（每次输出固定置于首位，不可省略）

每条报告的第一行必须是订阅状态横幅，二选一：

• 已订阅：已订阅 · 您已通过「<subscription.channel>」订阅此技能，本次调用计入订阅额度
• 未订阅：未订阅 · 请先购买订阅；单次 5.00 元，或在 SkillHub 订阅后按额度调用

渲染成带边框的横幅块（终端用 ═ 框，HTML 用卡片），已订阅为绿系、未订阅为橙系。
判据优先级：--subscription 参数 > 环境变量 PORTFOLIO_XRAY_LAB_SUBSCRIPTION > config.yaml 的 subscription.channel > 空则判为未订阅。

五类结果

分级规则

• 偏差统计量 B：落在 95% 置信区间内 → 绿（风险测度可信）；B > 上界 → 红（系统性低估风险）；B < 下界 → 黄（高估风险）。
• 暴露百分位：>90% 或 <10% → 红（极端风格押注，收益高度依赖该风格延续）；>70% 或 <30% → 黄（明显偏离）；其余 → 绿（中性）。
• 因子共线性：VIF > 10 → 红（须正交化后入模）；5 < VIF ≤ 10 → 黄；其余 → 绿。
• 归因显著性：|t| > 2 的期数占比 ≥ 50% → 绿（因子持续有效）；20%~50% → 黄；< 20% → 红（该因子收益不稳定，不可作为归因主因）。

缺失信息处理

任何因子列缺失 → 该因子整列跳过，并在报告「数据可用性」小节明确列出「未获取：XX 因子（缺 XX 列）」；不沿用上一期值、不用横截面均值填充、不推测补造。

Notes / Constraints（约束）

1. 不构成投资建议：所有输出末尾固定一句「本结果仅为量化统计研究，不构成任何投资建议；历史因子收益不代表未来，模型存在失效可能。」
2. 只做统计、不做预测涨跌：本 Skill 输出波动率预测与收益归因，不输出买卖信号、不给目标价、不做择时。
3. 取不到即标「未获取」：数据缺失、样本不足（截面股票数少于因子数 + 行业数 + 2）时不强行回归，直接标注并返回非 0 退出码。
4. 不访问外部系统：不联网取行情、不调任何第三方 API；全部输入来自用户提供的 CSV 文件。
5. 蒙特卡洛次数可调：默认 500 次以控制单次耗时；追求与文献一致的估计精度时可设 --mc-sims 10000，耗时显著上升。
6. 频率假设：面板按交易日或月度均可；horizon_days=21 在日频下为「未来 1 个月」，月频下需自行换算为 1。
7. long-only 约束：GMV 优化限定权重非负且和为 1（A 股做空机制受限），因此结果不等同于无约束解析解 V⁻¹α/αᵀV⁻¹α。

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": "portfolio-xray-lab", "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+版本即可
• 状态：已实测。DEV_MODE 下 /api/invoke 首次调用返回 402（WeixinPay-Required 头与 body
  双通道携带 X402 payment_code，附 X-Out-Trade-No），模拟回调置位后带订单号重试返回
  {"ok":true,"paid":true,"fulfillment":"agent_local","already_fulfilled":false}；
  真实 A 股月线面板（112 只 × 156 个截面，2013-02~2026-01）上 scripts/run_local.py --mode all
  全链路跑通，见 REALDATA_VALIDATION.md。

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

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

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

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

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

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