风格因子择时与基金优选

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

Overview

这是风格因子配置择时 + 基金风格反推的工具集，不是选股工具，也不推荐任何基金。

风格因子择时难在两件事：中长期趋势从哪来，短期交易风险怎么防。本 Skill 把这两件事拆成两条
互相独立的链路，再合成一个可回测的轮动策略：

1. 中长期趋势（宏观时钟）——用信用（私人部门融资增速）、货币（SHIBOR3M）、中美利差
   （10 年中债 - 10 年美债）三个外生变量，按长短期均线法判定各自的上行/下行，
   组合出 2×2×2 = 8 种宏观状态，每种状态对应一组「风格月度平均收益 / 胜率」的历史统计，
   取收益（或胜率）最高的风格作为宏观信号。
2. 短期交易风险（拥挤度）——从交易热度、资产收益、估值指标、杠杆资金、交易结构五个维度
   共 8 个指标衡量因子拥挤：每个指标取近 5 日均值在近 250 个交易日中的分位数做标准化，
   超过 95%（或 99%）分位即该指标提示拥挤（股息率方向相反，低于 5% 分位提示估值过高）；
   维度内达到半数指标提示拥挤则维度发信号；五个维度等权 0.2 投票，综合指标 > 0.5 发拥挤信号。
3. 合成与权重映射——三个信号投票决定下月仓位：宏观环境 + 1 个月短期动量 + 6 个月长期动量，
   各 1 票，得票最高者满仓（平票时优先序：宏观 > 长期动量 > 短期动量）。
   若占优资产触发拥挤信号，则该月空仓（研报口径：持现金、不计月收益）——权重只有 0 或 1，
   不做连续加权，这是该框架最容易被误用的地方。
4. 基金风格反推——以基金日收益率为因变量、四个风格因子日收益率为自变量，做月度窗口的
   带约束多元线性回归（各系数 ≥ 0），回归系数即风格仓位暴露；另用
   风格因子相似度 = 1 / (1 + 标准化收益的欧式距离平方)（按月窗口计算后取均值，> 0.3 为高相似度）
   交叉验证基金主导风格；最后按「稳定高暴露 → 业绩/回撤排名 → 相对基准季度胜率」三层筛选细分风格名单。

四因子设定：景气（营收 TTM 同比增速）、质量（ROE 的 TTM 变化）、价值潜力（低 PE-低 ROE 的深度价值）、
红利（现金分红率）。并列配置的前提是因子间弱相关，第一步必须先做相关性诊断。

本实现为纯 Python 标准库的零依赖算法（非负最小二乘用「枚举支撑集 + KKT 校验」的精确解，
不引入 scipy），口径已与公开文献数值交叉校验：由「夏普 = (年化收益 − rf) / 年化波动」反解出的
无风险利率在 30 条公开记录上高度集中于 2.46%~2.61%（均值 2.51%），本包默认取 2.50%。

边界（明确不做；遇到这类请求如实说明，别硬凑）

• 不输出股票名单、不做因子打分排序、不构建股票池；
• 不推荐任何基金：fund 子命令输出的是风格暴露与历史业绩的统计刻画，不是买入名单；
• 不自动联网抓取宏观数据（私人部门融资增速 / SHIBOR3M / 中美利差需用户自备 CSV 或接自有数据库）；
• 不预测涨跌、不给买卖点；只输出「在某口径下某信号是否触发」的统计量。

When to Use（触发条件）

A. 想判断当前该超配哪个风格

• 用户说「现在应该配红利还是景气」「用宏观指标判断风格趋势」时；
• 用户手上有信用/货币/中美利差（或其代理）的月度序列，想落到具体的风格推荐时；
• 用户说「这个月风格要不要换」「风格轮动信号现在是什么」时。

B. 想测某个风格的拥挤度

• 用户说「红利是不是太拥挤了」「给这个因子算一下拥挤度」时；
• 用户有换手率/成交额/一年动量/PE/PB/股息率/融资买入额/主力净流入等指标的日频序列，
  想按五维投票法合成综合拥挤度并看信号后 22/66 日的风险表现时；
• 用户说「拥挤度信号出来之后真的会跌吗」时。

C. 想回测/复现一个风格轮动策略

• 用户说「三信号投票的风格轮动怎么搭」「宏观+动量+拥挤度合起来效果如何」时；
• 用户想对照「趋势+胜率」与「趋势+胜率+拥挤度」两套版本的回撤与夏普差异时；
• 用户想做样本内/样本外分段评价，检验策略是不是只在样本内好看时。

D. 想反推基金（或组合）的风格暴露

• 用户说「这只基金到底是什么风格」「帮我算一下基金在四个风格上的仓位暴露」时；
• 用户说「从净值反推持仓风格」「用带约束回归做风格归因」时；
• 用户想在某风格内筛出「暴露稳定 + 业绩回撤排名靠前 + 相对基准胜率高」的名单时。

E. 想先确认四因子能不能并列配置

• 用户说「这几个因子相关性太高了吧」「先帮我看看因子能不能并列用」时。

明确的排除项（用户这么问时，如实说明本 Skill 不做）：

• 「帮我选几只股票」「给我一个股票池」→ 属选股与投资建议，不做；
• 「推荐一只红利基金」→ 不做推荐，只给风格暴露与历史统计刻画；
• 「帮我预测下个月大盘」→ 不做市场择时与涨跌预测。

Workflow（工作流）

> 付费前置：本 Skill 为鉴权型。必须先按文末「Pay Skill 模式」完成 X402 支付鉴权，
> 拿到 paid: true 后才执行下面的 Step 1 及之后。支付未确认前不得运行任何取数/计算脚本，不得输出任何结果。

Step 0 澄清输入（不要凭空假设）

指标名必须与内置字典一致：turnover（换手率）、amount（成交额）、mom1y（一年动量）、
pe、pb、dy（股息率）、margin（融资买入额）、netinflow（主力净流入额）。
收益率统一用小数（0.0123 = 1.23%）；若给的是百分数须先除以 100。

Step 1（可配性诊断）——四因子能不能并列配置

python3 scripts/run_local.py screen --input style_monthly.csv [--value-col excess_ret] \
    [--high 0.70] [--watch 0.50] --out report.md

输出相关矩阵 + 逐对判定（高相关 / 需关注 / 弱相关）+ 各风格年化波动。存在高相关对时先正交化或剔除，
不要直接进下一步。

Step 2（宏观趋势）——判定当前处于哪个时钟象限

python3 scripts/run_local.py clock --input macro.csv [--asof 2024-08-31] \
    [--criterion ret|win] --out report.md

输出信用/货币/中美利差的长短期均线与方向、所处的时钟象限、该象限下四风格的历史平均收益与胜率、
当前推荐风格，以及 8 状态全表对照。

Step 3（拥挤度）——五维八指标投票

python3 scripts/run_local.py crowding --input crowd.csv [--factor 红利] \
    [--threshold 95|99] [--price price.csv] [--min-dims 5] --out report.md

输出指标覆盖情况、最新截面各指标分位数与单指标信号、五维投票表、综合拥挤度与是否越阈、
信号历史触发占比，以及信号后 22/66 交易日的平均收益/胜率/下行 5%/10% 风险（需 --price）。
维度不全时会在报告顶部给出「数据不足」警示并拒绝下综合结论，只给单维度补充口径。

Step 4（轮动回测）——三信号投票 + 拥挤度避险

python3 scripts/run_local.py rotate --input style_monthly.csv [--value-col excess_ret] \
    [--macro macro.csv] [--crowd crowd.csv] [--crowd-threshold 95] \
    [--lookbacks 1 6] [--rf 0.025] [--oos-from 2023-01] --out report.md [--svg nav.svg]

输出各风格 / 风格等权 / 趋势+胜率 / 趋势+胜率+拥挤度 四组评价指标（年化收益、年化波动、最大回撤、
夏普、卡玛）、样本内外分段、最近 N 期调仓明细（含每期三个信号各投给谁）、风格选中次数分布，
以及零依赖 SVG 净值曲线。--macro 缺失时如实降级为双动量信号并在报告顶部红字注明，
绝不用合成宏观数据顶替。

Step 5（基金风格反推与优选）

python3 scripts/run_local.py fund --input fund_daily.csv [--style 红利|质量|价值潜力|景气] \
    [--window 24] [--min-obs 15] [--quarters 8] --out report.md

输出各基金在四风格上的平均暴露（月度窗口 NNLS 回归系数的均值）、平均 R²、暴露稳定性、
风格相似度与主导风格判定（月度窗口口径 > 0.3 为高，另给全样本口径供稳健性参考），
以及细分风格三层筛选（备选池 → 精选）的结果。

Step 6（口径校验，可选）——确认本包指标定义与公开文献一致

python3 scripts/run_local.py benchmark --out report.md

输出公开文献已披露的策略评价表、拥挤度有效性表、8 状态时钟表，并用 30 条记录反解无风险利率
做夏普口径自洽性检验。

Step 7（自检，可选）

python3 scripts/run_local.py demo --out report.md

用合成数据跑通「相关性 → 时钟 → 拥挤度 → 轮动 → 基金暴露」全链路，并把合成数据落盘到
scripts/_demo_data/ 供试跑。结论无投资含义，仅用于排查环境。

Output（输出规范）

• 默认输出中文 Markdown 报告；结构模板见 references/output_templates.md，口径与纪律见 references/rules.md；
• 数字口径：收益率/波动率/回撤/胜率一律百分比保留 2 位；相关系数保留 3 位；夏普/卡玛保留 2 位；
  分位数保留 1 位；
• 显著性口径：本工具不出 t 值/显著性星标——风格轮动与拥挤度的证据是「信号后收益/胜率/下行风险」
  三张分布，而不是回归显著性；需要显著性检验时如实说明本工具不提供；
• 缺失处理：取不到的数据一律写「未获取」并说明原因（如「宏观样本不足 6 期」「未获取维度按 0 计入」），
  严禁因为用户已付费而推测补造；样本不足（轮动 < 12 期、相关性共同样本 < 3 期、
  拥挤信号 < 5 次、基金有效月度过少、参与排名基金 < 5 只）时直接标注不评价并说清需要多少；
• 结论纪律（必须严守）：
• 结论先行：报告第一段给判定结论 + 关键数字，最后一段给边界说明；
• 弱信号时明确说「未呈现稳定区分力 / 未跑赢等权」，不夸大；
• 拥挤度维度不全时必须写「不足以发出正式拥挤信号」，不得用单维度结果冒充五维综合结论；
• 只描述，不评价。不出现"值得买/该配/推荐"等措辞，不输出任何股票名单或基金推荐。

Notes / Constraints（约束）

• 免责声明：本 Skill 产出的是量化统计研究结果，不构成投资建议，不预测未来收益；
  每份报告末尾固定带风险提示（宏观环境变动、市场结构变化、样本外失效、因子拥挤风险）。
• 不替代：不替代合规披露、实盘交易决策或任何投资建议；基金筛选不涉及基金经理任职年限、
  开放式/封闭式、规模等门槛核验（工具不接入基金公告数据，需用户另行核验）。
• 宏观数据是本框架最紧的约束：信用（私人部门融资增速）、货币（SHIBOR3M）、中美利差
  （中债 10Y − 美债 10Y）三项需要专业数据库或用户自备 CSV；缺失时 rotate 会降级为双动量信号，
  与完整三信号框架不等价，不可对标三信号结论。
• 拥挤度的五个维度需尽量齐全：五维等权 0.2、阈值 0.5 意味着至少 3 个维度同时拥挤才发信号。
  只拿到 1~2 个维度时综合指标最高只能到 0.2~0.4，永远发不出信号——这是设计使然，不是 bug；
  此时用 --min-dims 放宽只会得到单维度口径，必须在报告里标注。
• 股息率方向相反：dy 是唯一分位数越低越拥挤的指标（股息率被买低 = 估值过高）。
• 权重是 0/1，不是连续加权：该框架每月满仓一个得票最高的风格，拥挤则空仓；
  不要自行改成按得票比例分配权重，那不是本框架。
• 无风险利率：默认 2.50%/年（与公开文献口径反解一致），用 --rf 换成自己的资金成本。
• 平票优先序：宏观 > 长期动量 > 短期动量（宏观代表中长期趋势）。
• 相似度阈值配套口径：0.3 阈值只适用于月度窗口相似度；全样本一次性标准化的相似度
  会随样本长度系统性趋近 0，不可与 0.3 直接比较（报告里已并列两个口径）。
• 被误当成选股/荐基工具时：用户问「那我买什么」「推荐一只基金」时，如实说明本 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": "style-factor-timing", "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 402 结构冒烟已通过；⚠️ X402 生产真实扣费链路尚未实测，不可声称已通。
• 已验证（1）本机履约链路：python3 scripts/run_local.py demo 跑通「相关性 → 宏观时钟 →
  五维八指标拥挤度 → 三信号轮动 → 基金风格暴露反推」全链路，7 个子命令全部可独立执行。
• 已验证（2）真实数据口径校验：风格超额收益相关矩阵的 6 对符号结构与公开文献完全一致；
  由 30 条公开记录反解的无风险利率集中于 2.46%~2.61%（均值 2.51%），与本包默认 2.50% 一致；
  拥挤度「交易热度」单维度真实信号 78 次，信号后 22/66 日平均收益 -1.21%/-1.13%、
  胜率 43.59%/34.62%，方向性与公开文献一致；基金风格暴露反推在真实 ETF 上主导风格判定
  4/4 正确、平均 R² 0.85~0.98。
• 已验证（3）DEV_MODE 402 结构冒烟（pay/server.py 内存起服，5 步全绿）：
  ① 首调 /api/invoke 未支付 → HTTP 402 + 响应头 WeixinPay-Required + X-Out-Trade-No +
  body WeixinPay.Required 嵌套结构（code=PAYMENT_REQUIRED）；
  ② /api/pay/notify 模拟回调置位支付成功；
  ③ 带 X-Out-Trade-No 重试 → HTTP 200 + fulfillment=agent_local + paid=true 鉴权回执；
  ④ 同 payment_code 再调 → 幂等 already_fulfilled=true；
  ⑤ amount 缺失 → HTTP 400 INVALID_AMOUNT。
• 未验证：X402 真实扣费链路（真实微信商户 + SkillHub 开发者私钥预下单）尚未做生产实测。
• 发布前必做：按 PAY_SKILL_UPGRADE.md 第五节，切真实密钥跑 1 元真扣，通过后回填本条为「已实测」。

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

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

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

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

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

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