量价利·业绩归因实验室

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

Overview

把公司业绩点评/财报数据按五个可复现的框架诊断成一份结构化报告：

1. 预期差体检（beat）—— 实际 vs 一致预期 vs 上年同期，判定超预期/符合/低预期
2. 量价利归因（vpm）—— 营收 = 量 × 价，拆出增长中量、价、单吨净利各自贡献
3. 结构弹性测算（mix）—— 高毛利产品占比提升 → 加权单吨毛利 → 利润弹性
4. 产能兑现推演（cap）—— 满产率 × 投产节奏 → 未来 2-3 年出货兑现斜率
5. 目标价推导（tp）—— 远期净利 × 目标 PE ÷ 股本 → 目标价与上行空间（含 PE 敏感性）

核心卖点：「收入增速 vs 利润增速」的剪刀差才是盈利质量的真信号；只看收入增速、
只看毛利率会被结构变化和低基数误导。方法经与原始研报数值交叉校验（如目标价推导与
原文目标价一致），可直接复现。

边界：本技能不访问任何外部数据库，所有计算基于用户上传的 CSV 数据；
不承诺收益，不构成投资建议。

When to Use（触发条件）

• 「帮我读一下这家公司的业绩点评，到底超预期没有、靠什么涨的」
• 「把这个公司的财报数字拆一下，量价利各贡献多少」
• 「产品结构升级对利润有多大弹性，帮我算一下」
• 「新增产能什么时候能兑现成出货/收入」
• 「按这个盈利预测，目标价和上行空间是多少」
• 「把这篇研报/财报转成结构化诊断报告」

First-Use Configuration（可配置参数）

读取 config.yaml，可调项：

Workflow（履约工作流）

1. 收数据：请用户提供 5 份 CSV 中的至少 1 份（契约见 references/input-contract.md），
   或由 Agent 从财报/研报文本中提取填入。
2. 选能力：按用户问题对应 mode（beat/vpm/mix/cap/tp），或 --mode all 全诊断。
3. 跑履约：python3 scripts/run_local.py --input <数据目录> --mode <mode>
   —— 支付鉴权通过（paid=true）后由 Agent 本机执行（详见 scripts/README.md）。
4. 出报告：五段式 Markdown，结论先行 + 免责声明；可加 --out <目录> 落盘。

> 提示：scripts/gen_demo.py 可生成一份基于真实制造业业绩点评数字的演示数据目录，
> 用于快速体验五个能力（替换数据即可用于任意公司）。
> 方法细则见 references/method.md；边界与常见错误见 references/pitfalls.md。

Output（输出规范）

• 每份报告首行是判定结论 + 关键证据（结论先行），随后是明细表
• 全部输出末尾固定免责声明：「本结果仅为量化统计研究，不构成任何投资建议；
  历史业绩与研报预测不代表未来。」
• 数据缺失项如实标「未获取」，绝不推测补造

Notes / Constraints（约束）

1. 合规免责：本结果仅为量化统计研究，不构成投资建议；不承诺收益。
2. 数据纪律：任何输入缺失 → 标「未获取」并影响对应能力结论，绝不编造。
3. 口径纪律：毛利率用 pct 差、增速用 %，分开表述；量×价须自洽（不符会标不一致）。
4. 弱来源强作用：不绑定任何一家公司/券商/年份，输出面向通用制造业业绩归因。
5. 取数边界：本技能不联网取数；行情/现价由用户提供或 config.yaml 配置。

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": "earnings-decomposition-lab", "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+版本即可
• 状态：尚未在真实商户环境实测（未接入前不标注「已通」）；本地 DEV_MODE 冒烟已通过（402→回调置位→200 paid=true）。

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

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

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

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

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

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