可转债多因子研究员
> Pay Skill 范式：鉴权型（agent_local）
> 鉴权型：履约在本机执行（需本地取数/解析大文件），远端网关只做支付鉴权，支付通过后返回 fulfillment: "agent_local"，Agent 再跑 scripts/ 下的脚本产出结果。
Overview
把 WorkBuddy 变成一名「可转债多因子研究员」：输入一份可转债因子面板（或一键拉取真实行情），
落成可复现的多因子研究体系——六类能力覆盖从「单因子灵不灵」到「多因子组合怎么配」的完整链路：
- 估值偏离诊断：基于「市场价格 vs 模型价格」的偏离度（factor=-(P市场-P模型)/P市场），判定被低估的转债，输出分位形态与低估池。
- 波动率因子构建：Close-to-Close / Parkinson / Garman-Klass / Rogers-Satchell / Yang-Zhang 五种波动率估计 + 长短波动率价差，用样本外 IC 选出最具区分力的口径。
- 量价因子方向诊断：RSI / ROC / MACD / 动量 / KAMA / ADX / Bollinger% 等技术指标，按 IC 符号判定「动量型(IC>0)」还是「反转型(IC<0)」，避免方向用反。
- 因子稳健性体检：子模型在「全部参数」上的平均超额夏普>0 才入选、再取超额夏普最高的参数作代表，规避参数过拟合（量化模型最常见陷阱）。
- 多因子合成器：大类因子等权 vs 大类因子夏普加权，取 Top-N 转债组合，输出年化/波动/夏普/卡玛/回撤。
- 组合回测与绩效评价：双边万八成本 + 可选评级/余额/停牌/ST 约束，输出夏普、卡玛、最大回撤与分年度表现。
整套方法脱胎于一套被反复验证过的可转债多因子组合研究，卖点是「算得对、可复现、与公开结论一致」，
不是通俗科普。不访问任何外部付费数据库，取数走公开行情接口；取不到的数据标注「未获取」，绝不编造。
When to Use（触发条件）
- 用户说「我想验证某个可转债因子（估值/波动率/量价）到底有没有选债能力」时。
- 用户说「别只看相关系数显著——给我分 10 组看是单调还是 U 型两端」时。
- 用户说「这几个波动率口径/技术指标，哪个对可转债最管用、是动量还是反转」时。
- 用户说「我的因子在多个参数下表现不一，怎么判断该不该入选、选哪个参数」时。
- 用户说「按定价+波动率+正股动量+转债反转给我配一个可转债组合并回测（含成本）」时。
- 用户说「按这套因子配方给我一份最新的可转债选债池/低估池」时。
Workflow（工作流）
两种数据入口（取数由 Agent 在本机执行，支付确认后才跑）：
- 入口 A — 自备面板：用户提供宽面板 CSV。
- 估值：
date,ticker,name,market_price,model_price,ret - 波动率/量价：
date,ticker,open,close,high,low,volume,ret（可选iv隐含波动率列） - 稳健性：
date,ticker,factor,param,ret（同一子模型的多参数变体） - 合成/回测：
date,ticker,ret,<大类因子列...>（可选mktcap/rating/balance/halted/st约束列） - 入口 B — 一键真实数据：用户未自备时，
fetch拉取可转债（或对应正股）真实月线 OHLCV 并构造面板。
- 取数：入口 A 直接用用户 CSV；入口 B 跑
python3 scripts/run_local.py fetch --out <dir>/ohlc.csv [--base cb|stock]。 - 估值偏离诊断：
valuation --input <面板> --market-col market_price --model-col model_price --out <dir>→valuation_report.md+decile.svg。 - 波动率因子构建：
volatility --input <ohlc面板> --out <dir>→volatility_report.md。 - 量价因子方向诊断：
technical --input <ohlc面板> --out <dir>→technical_report.md。 - 因子稳健性体检：
robust --input <面板> --factor-col <因子列> --param-col <参数列> --out <dir>→robust_report.md。 - 多因子合成：
synthesize --input <面板> --factors <类1,类2,...> --signs "..." --top-n 20 --scheme sharpe --out <dir>→synthesize_report.md+nav.svg。 - 组合回测：
backtest --input <面板> --factors <类...> --signs "..." --top-n 20 --cost 0.0008 [--constraints aa,balance] --out <dir>→backtest_report.md+nav.svg。 - 汇总交付。支付未确认前不执行取数脚本、不输出任何付费内容。
Output（输出规范）
valuation：valuation_report.md（结论先行 + RankIC/形态 + 低估池）+decile.svg（红涨绿跌分位柱状图）。volatility：volatility_report.md（五种口径 IC 排名 + 结论，标注 HV-IV 是否可算）。technical：technical_report.md（各指标 IC 与动量/反转方向判定）。robust：robust_report.md（各参数超额夏普 + 入选/不入选结论）。synthesize/backtest：<mode>_report.md（结论先行 + 核心指标 + 分年度）+nav.svg（组合 vs 基准净值）。- 报告首行即结论先行（IC/形态/年化/夏普），再展开明细。
- 缺失处理：截面股票/转债数 < 分组数或某期无收益则跳过并标注；取不到的数据标注「未获取」，严禁推测补造。
- 详细输出模板见
references/output_templates.md；业务规则与约束见references/rules.md；方法交叉校验见references/empirical_evidence.md。
Notes / Constraints（约束）
- 本结果为量化统计研究，不构成任何投资建议；历史有效不代表未来有效，极端行情下回撤可能放大。
- 估值偏离的「模型价格」须由用户提供（或自行用定价模型计算）；本脚本不内置定价模型、绝不编造模型价。
- 波动率为低频（月线 OHLC）近似；日线精度更高，请用日线面板复现公开区间。
- 因子方向（sign）是组合成败关键：估值偏离/波动率/低估值类为
+1（高因子好），动量类+1、反转型-1；若你的因子定义相反请用--signs覆盖。 - 实证结论高度依赖样本区间与转债池结构（偏债/平衡/偏股、评级、市值分布）；用你自己的全样本才更易复现公开区间。
- 选债池/组合为截面排序与回测结果，未含流动性冲击之外的全部实盘摩擦，实盘需自行校验。
- 取不到的数据标注「未获取」，不编造。
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": "convertible-bond-multi-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+版本即可 - 状态：付费链路结构已对齐透明网关契约（402 双通道 / 主动查单 / 幂等）；线上真扣费联调需配置微信支付与 SkillHub 开发者密钥后由运维侧执行，本包不自带密钥。
Agent 侧调用规范（含付费前置插件检查）
Step 0 付费前置插件检查（必须，缺失则不得发起付费调用）
- 检测当前环境中
weixinpay_pay插件（微信支付 Agent Pay / AI 专属卡）是否已安装并已开通； - 若不存在或未开通：不调用
/api/invoke，改为提示用户先安装/开通微信 AI 支付，完成后再继续； - 若可用：继续 Step 1。
Step 1 调用统一网关：POST /api/invoke，请求体：
{
"skill": "convertible-bond-multi-factor",
"skill_version": "1.0.1",
"query": "用户原始需求（用于订单留痕，不作为履约输入）",
"amount": 500
}
skill：必填，固定为本 Skill 的 slugconvertible-bond-multi-factor（与 SkillHub 已发布的一致；透明网关下传错 slug 时错误延后到 SkillHub/微信预下单环节才返回）；skill_version：必填，当前版本号1.0.1（缺失返回400 MISSING_SKILL_VERSION）；amount：必填，单位分，服务端校验为大于 0 的整数（小数/布尔/零/负数一律400 INVALID_AMOUNT，不静默截断）；
区间不强制，价格由 SkillHub 产品定价约束。
Step 2 支付触发（X402 预下单 → 402）：未支付时服务端依次执行——
- 生成订单号
out_trade_no（402 响应头X-Out-Trade-No与响应体out_trade_no均会返回，Agent 须记下）； - 调用微信支付 Native 下单，获取
code_url； - 用 SkillHub 开发者私钥（SHA256withRSA）对 X402 AI 预下单请求签名；
- 调用
POST https://payapp.weixin.qq.com/palmpayminiapp/clawagentpay/preorder换取payment_code； - 返回 HTTP 402，响应头
WeixinPay-Required与 bodyWeixinPay块中
同时携带 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": "convertible-bond-multi-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 与服务端两侧）
| 异常场景 | 处理方式 |
|---|---|
weixinpay_pay 插件不可用 |
不发起付费调用，引导用户安装/开通微信 AI 支付后重试 |
| 用户拒绝支付 / 支付取消 | 如实告知用户支付未完成，不推进后续流程、不输出付费内容；可重新发起（服务端生成新订单） |
| 支付失败（余额不足/风控拦截） | 如实转达失败原因，引导稍后重试；失败订单作废，不据此履约 |
payment_code 过期（最长 15 分钟） |
提示订单已过期，Agent 重新调用获取新订单与新 payment_code，不得复用旧码 |
| 报错「当前支付订单已过期」 | 先查 402 响应体是否有 WeixinPay 嵌套结构，其次才是 code_url 方向 |
| 支付成功但二次调用仍 402（回调延迟） | 等待 3~5 秒后重试，最多 3 次（指数退避），携带 X-Out-Trade-No、订单号不变 |
| 网络异常 / 5xx | 指数退避重试（1s/2s/4s，上限 3 次）；持续失败告知服务暂不可用 |
| 本地取数脚本失败（数据源不可用/文件缺失） | 如实告知用户并说明原因，不得因为已付费而编造数据；可引导稍后重试同一订单（already_fulfilled 为 false 时不会重复扣费） |
| 金额校验失败（400 INVALID_AMOUNT） | 修正 amount 为大于 0 的整数分后重试 |
| skill 传错 / 未发布（错误延后到 X402/微信预下单环节） | 核对 skill/skill_version 与 SkillHub 已发布条目一致后重试，不得随便换 slug |
| skill_version 缺失（400 MISSING_SKILL_VERSION） | 补上当前版本号 1.0.1 后重试 |
| 未支付即重试（402 NOT_PAID） | 等待用户完成支付授权后按 Step 4 重试，不得跳过支付环节 |
| 退款 | 服务端经 /api/refund/notify 接收回调；已退款订单的 payment_code 失效，再次调用将重新走支付流程 |
> 核心原则（SkillHub 官方教程 FAQ）：支付失败/未确认时必须如实告知用户，绝不据此推进后续流程。
核心特征对照表（供审核查验）
| # | 核心特征 | 实现位置 |
|---|---|---|
| 1 | X402 AI 预下单换取 payment_code（开发者私钥 SHA256withRSA 签名，调官方 preorder 接口；WeixinPay-Required 返回 payment_code 而非微信 code_url） |
pay/server.py skillpay_x402_preorder()；链路 Step 2.3~2.5 |
| 2 | 支付触发（未支付返回 402 + WeixinPay-Required 头/体双通道） |
pay/server.py _handle_invoke()；链路 Step 2.5 |
| 3 | 订单号传递（out_trade_no 全链路关联：下单→预下单→回调置位→X-Out-Trade-No 重试→二次调用） |
pay/server.py generate_trade_no() / mark_paid / 402 响应 X-Out-Trade-No 头 |
| 4 | 重试机制（402 回调延迟重试带 X-Out-Trade-No、5xx 指数退避、订单过期重新下单） |
上表「异常处理说明」 |
| 5 | 付费前置插件检查（weixinpay_pay 可用性检测，缺失不发起付费调用） |
链路 Step 0 |
| 6 | 异常处理说明（支付失败/取消/过期/退款/本地脚本失败等全场景） | 上表「异常处理说明」 |
| 7 | 透明网关（skill/skill_version 仅做格式校验后透传，不查 SkillHub、不查注册表） |
pay/server.py resolve_skill()（无 SKILL_REGISTRY，免 Java 注册/重启） |
包内 pay/server.py 为 Python 参考实现（含 APIv3 签名、X402 预下单、回调验签解密、
主动查单、幂等鉴权、透明网关无需注册表），部署说明见 PAY_SKILL_UPGRADE.md 与 pay_skill.yaml。
注意：本 Skill 涉及两套独立密钥/证书——
- 微信支付 API 证书（
wechat_pay）：用于微信 Native 下单与主动查单； - SkillHub 开发者密钥（
skillhub）：用于 X402 预下单签名。
私钥均不得写入 Skill 包或仓库，须通过环境变量注入服务端。
