纯因子组合铸造厂

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

Overview

把多因子模型里的风格因子「铸」成纯粹的、相互正交的因子组合，并把 Alpha 因子合成方法也一并跑通——直接回答
「单位暴露下这个因子该怎么配权重、纯因子组合与简单组合差多少、四种合成里哪种在本样本上最稳」。

覆盖两套同源方法论、共四套可独立调用的范式（公式、参数、方向、边界见 references/methodology.md）：

本包可计算的因子（仅价格量价，已对齐真实数据口径）：动量(mom)、波动率(vol)、反转(reversal)、流动性代理(liq)。
未获取（缺市值 / 行业 / 基本面字段）：规模、BP、盈利、成长、杠杆、行业哑变量——这些本应在纯因子组合里作控制项，
本包以「其余可算因子」替代并如实标注，绝不编造基本面结论。

边界：只做组合构建与统计诊断，不做行情预测、不给买卖点位、不连接任何券商交易接口；
不访问用户未明确提供的外部系统；取不到的数据一律标注「未获取」，不用代理变量凑数。

When to Use（触发条件）

• 用户说「我想把某个风格因子铸成纯因子组合，看单位暴露下它的收益 / 波动 / IR 到底如何」时
• 用户说「简单因子组合和纯因子组合（残差化其余因子）差多少，帮我在这批数据上复现一遍」时
• 用户说「最小波动因子组合怎么算，h = V⁻¹X / (X'VX) 这个权重给我落一遍真实数据」时
• 用户说「等权 / ICIR / 最大化 ICIR / 最小波动组合法，四种 Alpha 合成哪种在本样本上最稳」时
• 用户说「我的因子只有价格量价，没有市值和行业，纯因子组合还怎么控制」时
• 用户说「别给我讲理论——把权重闭式解和数值直接跑出来，要和文献口径可对」时

Workflow（工作流）

Step 0 收集口径（缺一项就问，不猜）

见「First-Use Configuration」表。

Step 1 取数（二选一，脚本都在 scripts/）

# 1) 拉真实 A 股日线（前复权，分段拉长历史）
python3 scripts/fetch_daily.py --out bars.csv --beg 2018-01-01 --end 2026-08-30
# 2) 用自有数据：导出 CSV，列见 references/methodology.md 第零节

Step 2 跑诊断

python3 scripts/run_local.py --input bars.csv --mode all \
    --groups 5 --out out_dir --html report.html --json result.json \
    --sub-order <支付订单号> --sub-channel "微信支付 · Agent Pay"

• --mode 可单选（simple / pure / minvol / synth）或 all
• 只想要某几套：--mode pure,minvol
• 支付通过后才执行；--sub-order 由 Agent 在收到 paid:true 后注入

Step 3 做参数敏感性（不同协方差估计结论可能相反，必须跑）

python3 scripts/run_local.py --input bars.csv --mode minvol --out s_minvol
python3 scripts/run_local.py --input bars.csv --mode synth --out s_synth

Step 4 读报告（out_dir/report.md 或 report.html）

先看顶部订阅状态横幅，再看四个范式各自的「因子表」（年化收益 / 年化波动 / IR / 最大回撤 / 横截面 IC / RankICIR）。

Step 5 判定与交付：按「分级规则」给每个因子与每种合成定级，输出给用户并附参数回显与边界说明。

输入数据规格

CSV 列（大小写不敏感，逗号分隔）：

必需样本：至少 13 个月历史 + 1 个月前瞻（即 >= 14 个调仓月末），且任月末有效标的数 >= 10。

Output（输出规范）

固定四段因子表（顺序不可变，让每次结果可横向比对）：

1. 订阅状态横幅（置顶 1 条）
   - 已订阅：订阅状态：您已通过 <渠道> 订阅此技能 · 订单 <号> · 有效期至 <日期>
   - 未订阅：订阅状态：未检测到有效订阅 —— 请先购买订阅（订阅后由 Agent 带入订单号重新生成本报告）
   - Markdown 与 HTML 两个版本都必须有，HTML 版用渐变横幅（已订阅=绿，未订阅=琥珀）
2. 数据画像：股票数、调仓月末数、日期范围、可用因子清单
3. 四张范式表：
   - 一、简单因子组合（每张表含：年化收益 / 年化波动 / IR / 最大回撤 / 横截面 IC / RankICIR）
   - 二、纯因子组合（残差化其余因子）
   - 三、最小波动因子组合
   - 四、Alpha 因子合成横向对比（等权 / ICIR 加权 / 最大化 ICIR / 最小波动组合法）
4. 边界说明：任何因缺列 / 样本不足 / 协方差奇异而未能计算的部分，逐条列出原因

分级规则（决定措辞，不决定用户行为）

缺失信息处理：缺列 → 对应范式标注「未获取」并说明缺哪一列；
样本不足 / 协方差奇异 → 标注「样本不足 / 协方差不可逆」并给出所需最小样本；
取数失败 → 打印 [未获取] 原因 到 stderr 并返回 1，不输出任何推测结果。

First-Use Configuration（首次使用时向用户确认）

Notes / Constraints（约束）

1. 免责：所有输出末尾固定一句「本结果为量化方法在有限数据上的统计验证，不构成任何投资建议；
   历史结论不代表未来，因子有效性随市场结构变化而衰减。」不承诺任何收益水平。
2. 不替代什么：不替代投顾意见、不替代风控审批、不替代合规审查；
   不提供具体买卖点位、不提供仓位建议、不推荐任何标的。
3. 取不到就标注未获取：文件缺失、列不对、样本不足、取数失败，一律如实标注，
   绝不因用户已付费而推测补造（鉴权型铁律）。
4. 口径诚实：本包仅有前复权价量，不含市值 / 行业 / 基本面。规模、BP、盈利、成长、杠杆、行业哑变量均【未获取】；
   纯因子组合的控制项以「其余可算因子」替代，WLS 权重无市值时退化为等权，报告中必须明说，
   不得把退化口径的结果包装成研报级全 A 基本面回测结论。
5. 协方差秩亏必须处理：观测数远小于股票数时样本协方差不可逆，minvol 采用对角收缩逆
   （Ledoit-Wolf 简化版），并标注「压缩逆」；若仍奇异则该月跳过，不报错不编造。
6. 显著不等于有效：IR 受样本期数影响。判定必须同时看年化收益、波动、最大回撤与分档多空，不能只看单一指标。
7. 付费内容仅报告：本 Skill 售卖的是组合构建计算与报告，不含任何标的推荐名单。

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": "pure-factor-portfolio-lab", "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 仅做格式校验后透传进 X402 预下单，不查 SkillHub（不查注册表、不反查是否真实存在/已发布/版本匹配）；
  无本地白名单，新增 Skill 免 Java 注册、免改 JAR、免重启，直接 POST /api/invoke 传正确 slug+版本即可
• 状态：于 DEV_MODE=true 下完成本地付费链路冒烟——首次调用返回
  HTTP 402 + WeixinPay-Required（X402 payment_code）+ X-Out-Trade-No，
  模拟回调置位后带订单号重试返回 paid:true / fulfillment:agent_local。
  生产密钥真实扣费待 SkillHub 发布并绑定 X402 商户后实测。
  自托管联调端口：PURE_FACTOR_PORTFOLIO_LAB_PORT（默认 18104）。

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

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

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

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

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

• skill：必填，固定为本 Skill 的 slug pure-factor-portfolio-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": "pure-factor-portfolio-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.yaml。

注意：本 Skill 涉及两套独立密钥/证书——

• 微信支付 API 证书（wechat_pay）：用于微信 Native 下单与主动查单；
• SkillHub 开发者密钥（skillhub）：用于 X402 预下单签名。

私钥均不得写入 Skill 包或仓库，须通过环境变量注入服务端。