语录摘抄本

概述

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

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

计费边界

• 免费阶段：Agent 理解需求、解析类型 / 条数 / 长度 / 关键词、运行 check_environment.py 环境检查，不触发付费。
• 付费阶段：实际调用 serve_quotes.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/quote-notes，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_quotes.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_quotes.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 或凭证。

把语录整理成可以直接复制的文本清单：编号、句子、作者、出处。默认输出文本，不出图。

需求侧的证据是「要现成文本」占 49.55%，「要出图」只占 1.82%，所以这条线的主轴是清单，不是图片。需要配图时另走渲染流程，不在本 Skill 范围内。

何时使用

用户想要一批可以抄、可以发、可以当素材的句子时。典型说法：

• 「来一组语录」
• 「给我 20 句文字类的语录」
• 「今天的语录」
• 「语录摘抄，要带出处的」
• 「随便来点有哲理的句子」

不做什么

• 不生成配图、海报、卡片，除非用户明确要求并且另有渲染能力可用。
• 不根据记忆编造句子或出处。句子必须来自脚本返回的结果。
• 不输出涉政、涉黄赌毒、人身攻击内容。
• 不把离线兜底的公版古文冒充成现代语录。

执行步骤

1. 检查环境。 运行 python scripts/check_environment.py。状态为 ready 或 partial 时继续；needs_setup 只处理缺失项；unavailable 时停止并说明原因。
2. 解析用户要求。 从用户话里取出四项：类型、条数、长度、关键词。缺失时用默认值，不要为了凑齐参数反复追问。
3. 调用取词脚本。

python scripts/serve_quotes.py –n 20

常用变体：

python scripts/serve_quotes.py –n 10 –types d,k –min-len 10 –max-len 40python scripts/serve_quotes.py –n 10 –keyword 时间,岁月python scripts/serve_quotes.py –n 10 –offline

1. 读取返回的 JSON。 关注三个字段：mode（live / offline）、items、notes。notes 非空时必须把其中的限制如实转达给用户。
2. 按下方格式输出。 编号连续，出处与作者分行写。
3. 自查。 对照「质量自查清单」逐条确认后再交付。

参数对照表

输出格式

Live 模式：

## 今日语录 · 文字类 20 句

1. 给时光以生命，给岁月以文明。
   —— 《三体：黑暗森林》

2. 适量的痛苦使人喋喋不休，真正的痛苦却使人沉默。
   —— 老猪《紫川》

3. 提起满是遗憾，想起满是欢喜。
   —— 来自网络

Offline 模式（notes 已提示降级）：

## 语录摘抄 · 20 句

> 数据说明：线上取词不可用，本节为包内公版语料（唐诗三百首、宋词三百首、诗经风雅、论语）中的名句，不含现代语录与网络句子。

1. 淮阴市井笑韩信，汉朝公卿忌贾生。
   —— 李白《行路难三首 二》

2. 君王掩面救不得，回看血泪相和流。
   —— 白居易《长恨歌》

作者或出处为空时，省略对应行，不要写「佚名」以外的占位内容，也不要凭空补一个出处。

质量自查清单

• [ ] 条数与用户要求一致，不足时已说明原因
• [ ] 编号连续，无跳号
• [ ] 每条都有句子原文，未做改写或润色
• [ ] 出处与作者来自脚本返回值，未凭记忆补充
• [ ] mode 为 offline 时已标注数据来源与限制
• [ ] 未出现涉政、涉黄赌毒、人身攻击内容
• [ ] 未输出任何配图
• [ ] notes 中的限制已如实转达

停止条件

遇到以下情况停止，并说明原因，不得用模型记忆或编造的句子顶替：

• check_environment.py 返回 unavailable
• 线上与离线均取不到任何内容
• 用户要求的是自己创作的文案，而不是摘录现成句子（此时应改用原创写作流程）
• 用户要求引用特定人物语录但脚本无法提供可靠出处

参考文件

• @references/sources.md：数据源、许可结论、实测得到的 Gotchas
• @references/setup-guide.md：依赖配置与降级规则