段子手

概述

付费与 SkillPay（微信 Agent Pay X402 协议）

本 Skill 为付费技能，采用微信支付 Agent Pay X402 协议（HTTP 402 Payment Required）按次计费：每次「取回合格段子并输出」收费 0.1 元（pricing.amount_fen = 10）。

计费边界

• 免费阶段：Agent 理解需求、确认场景（群聊/朋友圈/评论区/开会冷场）、运行 check_environment.py 环境检查、说明场景与来源组合，不触发付费。
• 付费阶段：实际调用 serve_jokes.py 取回合格段子并输出，触发一次扣费 0.1 元。

前置检查一：当前智能体是否支持微信 AI 支付

发起下单前，先检查可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，带前缀也算；存在任意一个即视为支持）。

• 支持：继续做「前置检查二」。
• 不支持：终止流程且不要发起下单，提示用户升级智能体或安装 @tencent-adm/weixinpay-installer。

前置检查二：本机支付路况（决定走哪条支付路径）

背景（必读）：X402 的支付凭据 WeixinPay-Required 只能被兑换成微信支付 AI 专属卡扣款。

而 AI 专属卡目前仅支持 Mac 端 WorkBuddy（≥ 5.1.1），Windows 与其余平台尚不支持

（官方口径：「目前仅支持 Mac 电脑使用，后续将支持更多版本」）。

在非 Mac 设备上，走 AI 专属卡会在申请扣款时报「当前设备暂不支持微信支付AI专属卡」。

此时不得终止流程，应降级走 code_url 扫码支付。

运行探测脚本（只读、不联网、不写文件）：

python scripts/qr_pay.py --probe

路径 A：AI 专属卡支付（默认，仅 Mac）

1. 请求资源：POST https://www.shangyu-tech.com/ur/openApi/skill/pay/call/joke-smith，body 为用户的查询内容（场景、条数等）。
2. 处理 402 响应：提取响应头 WeixinPay-Required（支付码 payment_code）与 X-Out-Trade-No（订单号），两者都必须保存。
3. 发起支付：将 WeixinPay-Required 的值作为 paymentCode，调用支付工具（以工具列表中实际可用名称为准）向用户申请支付授权（0.1 元）。普通支付由宿主系统检测到 WeixinPay-Required 后自动弹出支付卡片，通常无需模型手动调用工具。
4. 支付成功后重试（必须执行）：携带 WeixinPay-Required + X-Out-Trade-No 请求头，body 与首次完全一致，重新请求同一接口；后端查单验证通过后返回 delivered: true（付费解锁确认），Agent 据此执行 python scripts/serve_jokes.py 生成段子。

路径 B：code_url 扫码支付（降级，非 Mac 设备）

为什么可以这样走：服务端 402 响应体会附带 code_url 字段，它就是微信 Native 支付的收款二维码链接。

它本是 AI 专属卡的原料（服务端用它去 AI 预下单），同时也能直接给用户扫——同一次下单，两条消费路径。

用户付款后，服务端查单到 SUCCESS 同样会放行，因此这条路径不需要服务端做任何额外改动。

1. 请求资源：与路径 A 第 1 步完全相同，body 保持一致。
2. 处理 402 响应：从响应体取 code_url，从响应头取 X-Out-Trade-No 与 WeixinPay-Required，三者都必须保存。

若 402 响应体中不存在 code_url 字段，说明服务端未开启该旁路，终止并告知用户：

「当前服务端未返回扫码支付链接，且本机不支持 AI 专属卡，暂时无法完成支付。」

不得编造 code_url，也不得绕过付费直接生成段子。

1. 生成二维码（关键：用户扫不了纯链接，必须给图）：

先确认依赖可用（--code-url 需要 qrcode + pillow），否则会在这一步卡住：

python -c "import qrcode, PIL" || pip install qrcode pillow

依赖装好后生成二维码：

python scripts/qr_pay.py --code-url "<402 响应体里的 code_url 值>" --out pay-qr.png

若依赖装不上（离线、无 pip 权限等），不要只报个错就结束：如实告诉用户

「当前环境缺少二维码生成组件，无法出码」，并给出安装命令。

不得裸贴 code_url 文本让用户自己想办法，更不得跳过付费直接生成段子。

1. 交付给用户并立即开始轮询（同一步完成，不要串行）：

把生成的二维码图片用 present_files 呈现，紧接着启动轮询脚本检测付款。--timeout 请设成 120~180 秒——太长会把一次回复拖住，太短容易在用户找手机时误判超时：

python scripts/qr_pay.py --watch --out-trade-no "WX402_xxx" --timeout 150 --quiet

轮询必须用 --watch，不要自己手写循环调接口。 脚本已做四件事：每 3 秒查一次

只读状态接口、识别终态提前退出、超时后给出明确提示、--quiet 精简输出避免刷屏。

对话中调用请带 --quiet，否则每次查询都会打印一行，会把回复撑得很长。

给用户的交代只说三件事（不要解释内部术语）：

   这段子要付 0.1 元，用手机微信扫下面这个码就能付。

   （附二维码图片）

   订单号 WX402_xxx，15 分钟内有效。我在这边帮你盯着，付好自动给你。

• 不要先反问「你要不要付款」——付费是既定流程，直接给码
• 不要说「本机不支持 AI 专属卡」「降级」「旁路」——用户不关心实现
• 不要要求用户「付完跟我说一声」——系统能自己查到，把活推给用户是偷懒

1. 按 --watch 退出码处理：

绝对不要用 while / sleep 自己写高频轮询去砸接口。也不要因为没查到就

反复重跑 --watch 无限等待——超时两次仍未见支付，就停下来问用户。

1. 付款确认后取段子（必须执行）：携带 X-Out-Trade-No + WeixinPay-Required 请求头，

body 与首次完全一致，重新请求技能调用接口；返回 delivered: true 后执行python scripts/serve_jokes.py 生成段子。

这一步不能省略：--watch 只是查到"微信已收款"，真正解锁履约的是带凭证重试。

跳过它会导致后端订单未标记已支付、delivered 从未发放。

1. 若重试仍返回 NOT_PAID：说明订单状态尚未同步（极少数情况）。

再跑一次 --watch 确认，而不是立刻重复重试接口；仍未支付则询问用户。

仅路径 B 需要：如何把情况告诉用户

路径 B 需要在用户对话里交代的事比路径 A 多，措辞直接影响观感。不要把

「本机不支持 AI 专属卡」「设备降级」「旁路」这类内部术语抛给用户——他不关心实现。

按下面这段话给足信息即可：

这段子要付 0.1 元，用手机微信扫下面这个码就能付。

（附二维码图片）

订单号 WX402_xxxx，15 分钟内有效。我在这边帮你盯着，付好自动给你。

四条要求：

• 说清怎么付（手机微信扫码），不说「本机不支持 XX」这类技术原因
• 说清有效期，把过期说成正常操作而非故障，并主动承诺「过期我重新生成」
• 不要要求用户回来报信——轮询已经能检测到，让用户多做一次动作是没有意义的
• 不要反问「你要不要付款」——付费是既定流程，反问制造「这事可选」的错觉

若用户表示不方便扫码或不愿换设备：如实说明在这台设备上无法完成支付，不要用离线原创段子冒充付费内容交付，也不要用其他话题转移。可以补充一句「这个限制是设备侧的，换 Mac 端或用支持的环境就能正常自动付款」，但不反复劝说。

两条路径的取舍原则

• 优先走路径 A：它是官方协议，用户无需额外操作（系统自动弹支付卡片）。
• 仅在探测结果为「不支持」时走路径 B：它是旁路，需要用户掏出手机扫一次码，破坏了"自动化调用"体验。
• 不要为了省事跳过探测：在不支持的设备上强行走路径 A，只会得到「当前设备暂不支持微信支付AI专属卡」的失败，且该失败发生在扣款环节、用户看不到任何可操作的界面，体验比扫码更差。

失败与异常处理（避免死循环）

• 网络错误 / 超时 / 5xx：最多重试 2 次（同一请求最多发 3 次），仍失败则终止并提示「支付网关暂时不可达，请稍后重试」，不要无限重试。
• 支付取消 / 支付失败：终止，不重试，提示「支付未完成」。
• 非 402 且非 200 的响应（如 400/403/404/500）：终止，按响应内容提示用户，不要反复重试。
• 仅 402（待支付）与 200（已履约）为正常响应；其余一律停止并说明原因。
• 403 {"msg":"缺失 Skill 请求头"}：说明该 skillCode 未被纳入服务端 X402 白名单，落入了旧协议分支且缺少验签头。这不是用户侧问题，终止并提示用户联系技能发布方补齐白名单配置，不要重试。
• 「当前设备暂不支持微信支付AI专属卡」（路径 A 的扣款阶段报错）：说明探测结果与实际不符，或探测被跳过。不要重试路径 A，改走路径 B。

凭证与链接保护（硬约束）

• X-Out-Trade-No 订单号：微信支付订单号，由后端 402 响应返回，用于支付后重试对账，禁止手工伪造。
• WeixinPay-Required：一次性支付凭证，禁止在对话中展示其原始值，禁止写入持久化日志或转发到其他渠道。
• code_url：支付链接，可以生成为二维码交付用户，但不要把它当普通文本裸贴给用户（用户扫不了）；同时不要在非支付上下文中留存。
• 生成完成后不再重复调用付费接口；后端按订单号幂等，重复请求返回已履约结果，不会重复扣费。
• 订单有效期约 14.5 分钟（870 秒）。过期订单无法再付，必须重新下单；严禁复用过期订单的 code_url 或凭证。

按使用场景给段子和配套文案，只出干净档，每条都过一遍合规词表。

段子内容存量占 10.15%，是流量的第四大品类；但出版口径只有 1.70%——看的人多、掏钱少。线下脱口秀票房同比增长 134.9%，说明幽默消费在涨。这条线做成 Skill 的价值在「即取即用」，而不是内容库规模。

何时使用

用户在要能发出去、能接得住的幽默内容：

• 「来个段子」
• 「群聊怎么接梗」
• 「朋友圈发点什么」
• 「写个冷笑话」
• 「开会冷场了，来句能救场的」

不做什么

• 不出带攻击性的内容。 不针对地域、性别、身材、学历、收入、残疾、疾病、民族、宗教开玩笑，也不做人身攻击。请求「损一点」「毒一点」时说明本 Skill 只提供干净档，不降级生成。
• 不生成涉政、涉黄赌毒、自伤内容。
• 不做用于引战、嘲讽特定个人或群体的文案。
• 不把线上取到的段子改写后冒充原创；来源标签必须保留。

执行步骤

1. 确定支付路径。 先跑 python scripts/qr_pay.py --probe（只读、不联网）。
   • 退出码 0（本机支持 AI 专属卡）→ 走路径 A，付费后正常取段子。
   • 退出码 10（不支持，如 Windows）→ 走路径 B：下单 → 取 code_url → 生成二维码 →

交付给用户 → qr_pay.py --watch 自动检测付款 → 确认后重试取段子。

• 免费阶段不受影响：环境检查、确认场景、说明来源组合都不触发付费。

1. 检查环境。 运行 python scripts/check_environment.py。沙雕接口不可达时为 partial，此时走包内原创段子池，功能不受影响。
2. 确认场景。 四个场景：群聊、朋友圈、评论区、开会冷场。

python scripts/serve_jokes.py –scenes

1. 付费与调用脚本。

python scripts/serve_jokes.py –scene 群聊 –n 5

常用变体：

python scripts/serve_jokes.py –scene 朋友圈 –n 5 –seed 7 python scripts/serve_jokes.py –scene 开会冷场 –n 3 –offline

1. 读取返回 JSON。 items 里每条的 origin 是 online 或 original，from 标出来源。notes 里会回报线上接口的实际调用次数。
2. 按场景重排。 脚本只负责取回合格内容，按场景的取舍由模型判断：群聊要短、朋友圈要能配图、评论区要能接话、开会冷场要不冒犯在场任何人。
3. 自查。 对照「质量自查清单」逐条确认。合规自查不可省略。

参数对照表

输出格式

# 群聊接梗 · 5 条

1. 我不是懒，我是进入了低功耗待机模式，需要一点外部刺激才能唤醒。
2. 诗和远方还在加载，加班和焦虑已更新到最新版。
3. 我擅长的事情有三件：列计划、改计划、忘掉计划。
4. 群聊里最可靠的沉默，往往来自最忙的那个人。
5. 我不是社恐，我只是把充电时间花在了独处上。

---

来源：第 1、3、4、5 条来自包内原创段子池，第 2 条来自线上接口。

notes 里有降级信息时，在末尾补一行数据说明，不要在正文里混着讲。

质量自查清单

内容合规

• [ ] 逐条检查，无地域、性别、身材、学历、收入、残疾、疾病、民族、宗教相关玩笑
• [ ] 逐条检查，无人身攻击、引战、嘲讽特定个人
• [ ] 逐条检查，无涉政、涉黄赌毒、自伤内容
• [ ] 用户要求「损一点」时已说明只提供干净档，未降级生成
• [ ] 每条来源标签保留，未把线上内容说成原创
• [ ] 线上调用次数未超过「产出条数 + 3」
• [ ] notes 中的降级与调用信息已如实转达
• [ ] 结合场景做过取舍，不是原样堆砌

支付流程

• [ ] 已跑 qr_pay.py --probe 确定支付路径，未跳过探测
• [ ] 非 Mac 设备已走路径 B，未在报错后重复重试路径 A
• [ ] 路径 B 生成二维码前已确认 qrcode + pillow 可用，未在缺依赖时直接报错结束
• [ ] 路径 B 中已生成二维码图片并用 present_files 交付，未裸贴 code_url 文本
• [ ] 已把二维码直接呈现给用户，未先反问「你要不要付款」（付费是既定流程）
• [ ] 已跑 qr_pay.py --watch --quiet 自动检测付款，未要求用户「付完跟我说一声」
• [ ] 未手写 while/sleep 高频轮询砸接口；超时重跑 --watch 未超过 2 次
• [ ] --watch 返回 0 后已带凭证重试（--watch 只查收款，解锁履约仍需重试）
• [ ] 未向用户解释「AI 专属卡／设备降级／旁路」等内部术语
• [ ] 已告知订单有效期，并承诺过期可重新生成
• [ ] WeixinPay-Required 的原始值未在对话中展示
• [ ] 未编造 code_url，未绕过付费直接生成段子
• [ ] 402 里没有 code_url 时已终止并如实告知用户
• [ ] 用户拒绝扫码时如实说明无法支付，未用离线原创段子冒充付费内容

调用量的硬约束

沙雕接口官方明确要求「请勿滥用接口，请勿爬取接口」。因此：

• 单次运行的线上调用次数上限为产出条数 + 3，脚本会回报实际调用次数。
• 不缓存、不落盘线上内容，不建立镜像语料库。
• 需要更多内容时提高用户请求的条数即可，不要通过重复运行脚本累积抓取。

停止条件

遇到以下情况停止，不得改用擦边内容顶替：

• 用户坚持要带攻击性或低俗的段子
• 用户要用段子针对具体某个人或某个群体
• 用户要把段子用于引战、刷屏、骚扰
• check_environment.py 返回 unavailable
• 402 响应体不含 code_url 且本机不支持 AI 专属卡（两条支付路径都不可用）
• 用户明确表示不方便扫码、也不愿换设备（此时如实说明本机无法完成支付，不绕过付费）

参数对照表（支付辅助脚本）

--watch 退出码：

依赖提示：--probe 与 --watch 只用标准库，任何环境都能跑；

--code-url 需要 qrcode + pillow（pip install qrcode pillow）。

未安装时脚本会打印安装命令并返回退出码 1。

参考文件

• @references/sources.md：数据源、合规规则、许可结论与 Gotchas
• @references/setup-guide.md：依赖配置、支付路况与降级规则