交易行为波动和股票预期收益skills

概述

交易行为波动因子选股

Pay Skill 范式：鉴权型（agent_local）

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

Overview

把 WorkBuddy 变成一个「交易行为波动因子」选股助手：基于海通证券《选股因子系列研究(十四)：交易行为的波动和股票预期收益》的实证结论，将个股过去 N 日（默认 20）日换手率的变异系数（CV = 标准差 / 均值）工程化为可复用的选股因子。输入 A 股代码或股票池，自动抓取行情、应用研报筛选口径、计算 CV、给出波动分层与多空预期方向，并对股票池按「低波动优先」排序输出选股结论。

• 覆盖范围：单股因子诊断、股票池横截面排序、低波动组合筛选。
• 边界：仅做因子计算与历史实证映射，不预测价格、不荐股、不访问任何券商账户或下单系统；行情来自公开数据接口，结果仅供参考，不构成投资建议。

When to Use（触发条件）

1. 用户说「算一下某某股票的交易行为波动因子 / 换手率变异系数」时；
2. 用户说「用换手率波动因子给这批股票排个序 / 选低波动组合」时；
3. 用户说「哪些股票近期成交异常剧烈、预期收益可能偏弱」时；
4. 用户贴出一串 A 股代码想做因子打分 / 横截面排序时；
5. 用户想把海通这篇「交易行为波动」研报的方法落到实盘选股时。

First-Use Configuration（首次使用配置）

以下参数来自 config.yaml，未提供时使用默认值，并在回复中提示用户可按需调整：

Workflow（工作流）

1. 解析输入：股票代码（600519.SH、000001.SZ、纯数字、带 sh/sz 前缀均可），或代码文件（每行一个），或粘贴的日换手率序列（--turnover 离线模式，零依赖）。
2. 本地履约（鉴权型，仅支付通过后执行）：调用 scripts/run_local.py 完成「抓数 → 筛选 → 计算 CV → 分层/排序 → 生成报告」。
   • 行情抓取：公开行情接口取过去 window_days 日换手率（标准库零依赖）；失败则该股标注「未获取」，不编造。
   • 因子定义、筛选与分层规则见 references/rules.md；研报实证数据见 references/empirical_evidence.md。
3. 交付报告：按 references/output_templates.md 的模板输出 Markdown 报告（明细表 + 选股结论 + 风险提示），把文件/内容交付用户。

Output（输出规范）

固定输出 Markdown（模板见 references/output_templates.md）：

• 单股诊断：代码、交易日数、CV 值、波动分层（低/中/高）、数据可信度、历史分位收益参考、提示。
• 股票池排序：按 CV 升序的全量明细表；池内 ≥ pool_min_for_decile 时给出 D1–D10 十分位；推荐「低波动组合」（CV 最低的前 recommend_top_frac）。
• 数据质量分级：完整 / 样本不足（<15 交易日）/ 最新交易日疑似停牌 / 未获取。
• 缺失处理：取不到行情的股票明确标注「未获取」，不参与排序、不推测补造；列表末尾提示用户补充或重试。

Notes / Constraints（约束）

• 本工具复现的是 2010.1.4–2016.6.30 的样本内实证规律，历史有效不代表未来有效；市场系统性风险、流动性风险、政策变动会显著影响表现（研报原文风险提示）。
• CV 口径：样本标准差（ddof=1）/ 均值；与「均值换手率」不同，CV 衡量的是「流动性水平的二阶矩（波动）」，是反转因子——波动越高、预期收益越低。
• 研报前置筛选（上市满 12 个月、窗口内 ≥15 交易日、最新日未停牌）中，本脚本可自动校验后两项；「上市满 12 个月」作为用户输入前提在报告中声明，未自动校验。
• 单股无池内分布时，波动分层为启发式阈值（非全市场分位）；精确十分位请提交 ≥10 只股票的池。
• 本 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": "turnover-volatility-factor", "skill_version": "1.0.1", "query": "...", "amount": 200}）

• 兼容入口：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 自测结构达标；生产真扣费实测由发布方按 PAY_SKILL_UPGRADE.md 联调步骤执行（本包不内置任何密钥，密钥经环境变量注入）。

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

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

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

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

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

• skill：必填，固定为本 Skill 的 slug turnover-volatility-factor（与 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": "turnover-volatility-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 与服务端两侧）

核心原则（SkillHub 官方教程 FAQ）：支付失败/未确认时必须如实告知用户，绝不据此推进后续流程。

核心特征对照表（供审核查验）

包内 pay/server.py 为 Python 参考实现（含 APIv3 签名、X402 预下单、回调验签解密、主动查单、幂等鉴权、透明网关无需注册表），部署说明见 PAY_SKILL_UPGRADE.md 与 pay_skill.yaml。

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

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

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