Pay Skill 工厂 v1.0.1

> 一句话：把「值得收费的专业服务」变成能真金收款的 skill——服务端做 402 账单与验付，skill 端做协议编排与交付。

核心事实（先说清，少走弯路）：做一个新 pay skill ≈ 移植已验证的母本 + 改 4 个常量 + 换业务内容，不是从零造支付系统。三个已上线的 pay skill 用的都是同一套支付宝应用与商户，只是 serviceId 与单价分别注册。

能力边界（30 秒判断该不该用我）

该用我的情况（满足任一）：

• 你有一个想收费的 skill / 服务想法，要从零做出能真金收款的付费接口；
• 你已有免费 skill，想给它加付费墙（按次收费）；
• 你在做支付宝 AI 按量付费（A2M/HTTP 402）接入，需要服务端 + skill 包 + 部署包 + 验收全流程。

别找我的情况（及该去找谁）：

• 微信支付接入 → 本工厂只覆盖支付宝 A2M/402，微信支付是另一套协议，直接告知不适用；
• 非付费类 skill 开发（不收钱的普通功能）→ 普通开发需求，不走本工厂；
• 已上线的 pay skill 日常使用 / 业务出问题 → 直接触发那个 skill 本身（如「宠物账单·狗头军师」）；本工厂只管「造」，不管「运营」；
• 支付宝商户签约资质、费率政策 → 以支付宝官方口径为准，本工厂不代答。

动手前必须知道的三个坑：

1. 没有支付宝官方支付 skill（alipay-bot CLI）就走不通付费流程——WorkBuddy 默认只有微信支付；缺失时前置检查会拦下并提示安装（预期行为，非故障）。
2. 真金收款需要支付宝侧注册：serviceId 与单价按服务分别注册，且三处必须一致——服务端 SERVICE_PRICE = SkillHub 展示价 = 支付宝注册单价。
3. 自测就是自己扫自己的收款码：钱进自己商户账户，损失仅手续费；上线前沙箱全链路（402→账单→验付→履约）必须走通。

触发示例（复制就能开口）

这样说，我会被正确触发：

• 「我想给我的公司背调服务加个收费，2.99 一次」→ 启动工厂：选母本 → 出服务端 + skill 包 + 部署包；
• 「帮我做一个 pay skill，按次收费 5 块钱」→ 先问业务场景与单价，再选母本动手；
• 「这个 skill 想接入支付宝按量付费」→ 同上；
• 「我的 skill 怎么收钱？」→ 先给 30 秒边界判断，确认走工厂再动手；
• 「402 付费接口怎么做？」→ 同上。

这样说，我不会（也不该）被触发：

• 「用微信支付收款」→ 超出能力边界，直接告知不适用；
• 「宠物账单军师帮我看看这张报价单」→ 直接触发那个 skill，不进工厂；
• 「帮我写个不收费的翻译 skill」→ 普通开发需求，不走本工厂。

v1.0.1 相比 v1.0.0 的变化（全部来自约两周三个 skill 的真金实测）：

前置认知（动手前必读）

P0 · 动手前必须拍板的三件事

别跳过这一节——这三项不定，后面全要返工：

1. 付费资源形态是什么？ 常见三种：
   - 服务端生成 HTML 报告（推荐：可存档/可打印/可展示，感知价值高）
   - 服务端生成数据文件（JSON/CSV，适合工具型）
   - 服务端只做鉴权、内容由 Agent 生成（成本高、不易控质量，不推荐）
2. 免费层与付费层的分界线在哪？ 免费层必须自带实质价值（否则用户不会付费，只会流失）；付费层要解决「免费给不了的东西」（如固化证据、可展示文档、完整清单）。
3. 单价多少？ 参考区间：¥2.99（低价高频消费决策类）／¥5.20（中价报告类）。定价即定位。

P1 · 服务端搭建（复制母本，改 4 处）

目录结构（固定，别自创）

<service>-server/
  index.js              入口：路由 + 限流 + 402 编排（probe / complete 两分支）
  lib/config.js         环境变量单一事实来源（模式/单价/serviceId/密钥）
  lib/<biz>.js          业务数据与计算（如 scenes.js / report.js）
  lib/payment.js        账单签发 / 验付 / 履约
  lib/a2m.js            A2M 协议（Base64URL 双层 JSON + RSA2 签名）
  lib/alipay.js         支付宝网关封装（alipay-sdk v4）
  lib/orderstore.js     三层订单存储（内存 → 云数据库 → 文件兜底）
  test/run_test.js      冒烟测试
  test/e2e_test.js      端到端测试
  README.md / package.json

只需改这 4 处

P1.5 · 发单前闸门（v1.0.1 新增，血的教训）

> 这一节是 v1.0.1 最重要的新增。它拦的是「用户已付钱、资源取不到」——付费体验里最差的失败。

事故原型（2026-09-17 宠物账单真金实测真实发生）：测试脚本把场景参数传成 {"scene":"clinic"}，
而服务端契约要求数字枚举 1~5。结果：这个非法参数照样成功开出了 402 账单、用户照样完成了支付，
直到取资源那一步服务端才返回 400 INVALID_SCENE。用户钱付了，东西没拿到。

根因不是代码 bug，是流程缺了一道闸：probe 之前没有校验请求体参数合法性。

三条硬规矩

反直觉但重要：宠物 skill 的协议文档里其实早就正确写了 {"scene": 1}（数字），是测试时没照文档写、凭记忆填的。
这恰好证明——「文档写对」不等于「有人会照着做」，必须机器校验，不能指望自觉。
所以规矩 1 的落地形式是代码/脚本里的前置断言，不是文档里的一句提醒。

售中兜底：已付款但资源返回 4xx 怎么办（绝不能要求用户重付）

# 用【同一个 trade_no】重发查询，body 修正后重试
alipay-bot 402-query-payment-status -t '<原 trade_no>' -r '<resource-url>' -m POST \
  -d '{"scene": 1, "session_id": "<原会话ID>"}'

原理：支付凭证与请求体解耦——修正参数不会重复扣费，资源正常取回，履约回执自动补发。
这是用户已付钱后唯一正确的补救路径。

rc 两段判据（修正 v1.0.0 的错误认知）

v1.0.0 把「退出码 0」等同于「已付款并成功交付」，这是错的。正确判据分两段：

看到 rc=0 但资源 4xx 时，不要慌也不要让用户重付——用户的钱没问题，是请求参数的问题，修正重试即可。

P2 · skill 端改造

1. 在目标 skill 下新增付费协议手册（目标 skill 的 references 目录内，文件名 payment-protocol.md）：以本 skill 的 payment-protocol-template.md 为模板，替换占位符后只改三处——价格、API 前缀（如 /api/pet）、资源名，以及本业务特有的红线条款。
2. SKILL.md 补三段：
   - 「服务与计费口径」：写清免费层 vs 付费层边界、单价、三处同步要求；
   - 「付费四步速览」：probe → pay → complete → ack，含自动守候付款要点；
   - 异常处理表：至少覆盖支付中断、守候超时、验付不明、已付未交付。
3. 本业务特有红线：如宠物场景的「急症优先于付费」、情绪场景的「情绪安全优先于收入」。

交互纪律（v1.0.1 新增，交付体验相关）

> 拉起收银台后必须把二维码图片取出展示，不能只给路径。

真实投诉（2026-09-17）：用户反馈「待付款订单未见到二维码，无法扫」。
根因：alipay-bot 402-buyer-pay 的输出里二维码是 MEDIA: file:///C:/.../qrcode/payment_<交易号>.png 形式，
只在文字里写这个路径 = 用户扫不到码。

必做的三步：

其他交付纪律：
- 收银台窗口约 5 分钟——过期订单不可扫，需重新拉一笔（重拉无副作用，不会产生幽灵订单）。
- 不要要求用户说「已支付」——付款结果由 Agent 自动检测（见 P2 的自动守候）。
- 报告交付要有落脚点——付费资源（HTML）必须落盘成文件再展示，不能只在对话里贴内容。

P2.5 · 可选的第四条腿：免费高频功能（提粘性 → 提调用率 → 提转单率）

适用判断：若付费场景都是低频事件（一年碰两三次：看病、投保、临终、背调、年度体检），用户会自然流失——付费墙再低也留不住人。加一个免费、高频、零模型成本的功能是结构性解法。

已验证案例：pet-bill-advisor（¥2.99 五场景）加了「宠物记账」（记支出 + 月度汇总）。记账高频日常，五场景低频事件，两者互补。

三条硬约束（缺一条就会做歪）

转单设计：把免费数据变成付费场景的燃料（最容易被做歪的地方）

提转单率的正确机制不是「用一下就劝付费」，而是把免费数据翻译成"用户可能正想弄清楚的一个问题"：

记一笔（免费）  →  汇总（免费，含规则化洞察）
                        ↓ 数据攒够后自然生出问题
               「这个月医疗花 1200，正常吗？」→ 付费场景（长期规划）
               「这张化验单 3800，值不值？」  → 付费场景（报价解读）

服务端只提供钩子，不提供文案压力：返回 bridge 数组，每条含三字段——
- scene：指向哪个付费场景
- why：数据依据（如「本期医疗支出 1200 元、3 笔」）——可讲给用户听的事实
- ask：柔性问法——用户可以拒绝的邀请

只在数据真的支持时才生成；无数据返回空数组（常态，不是缺陷）。绝不硬造钩子。

转单红线（写进 SKILL.md，并让审计器逐条断言）

自检标准（一句话）：把邀请那段删掉，用户是否仍觉得这次服务是完整的？ 若否，说明你在拿免费结果当人质。

什么时候不要提邀请

用户只是快速用一下就走；用户情绪低落或涉及离世相关支出；用户明确拒绝过；bridge 为空数组。

落地清单（可直接抄）

1. 服务端：新建 lib/<free-feature>.js（数据层，复用 orderstore 的三层存储模式，但换独立集合）；index.js 加免费端点——放在付费端点之前，且段内不出现任何 402 / probe。
2. skill 端：新建 references/06-<free-feature>.md（录入解析规则 + 呈现格式 + 转单纪律与红线 + 接口契约 + 异常表 + 隐私口径）。
3. 主文档：SKILL.md 加一节「永久免费的高频入口」（说明零模型成本、为什么免费、红线）；00-router.md 加免费功能优先于分析的路由优先级，并说明免费功能不要说计费提示。
4. 审计器：加 H 段断言——免费声明、端点与服务端一致、免费端点内无计费逻辑、转单红线逐条存在、无数据时不硬造钩子、隐私口径存在。
5. 测试：独立测试文件覆盖归一正确性 / 非法输入拒收不猜 / 汇总手算对照 / 空数据不硬造 / 不含催促词 / 免费链路不影响 402 计费墙。

> 两个易错提醒：① 字段归一必须做好（金额带 ¥/千分位、中文类别、日期别名），否则用户记一笔要填一堆字段，粘性直接归零；② 非法输入要拒收并说明原因，不要静默修正——静默修正会让账目失真，用户发现后信任崩塌。

P3 · 测试（双件套，全离线）

test/run_test.js — 冒烟

数据结构完整性 / 确定性计算校验 / 402 账单字段 / 验付链路（含拒伪造）/ 履约幂等 / 实例回收后订单找回 / prod 护栏（无密钥拒发单） / 渲染断言。

test/e2e_test.js — 端到端

免费接口 → 402 发单 → 二次 probe 复用订单（不重复开单） → 裸串与错误 secret 凭证均 403 → 合规凭证交付 200（不带订单号头，验证会话反查）→ 已交付后 409 ALREADY_PAID → 未知路径 404。

> mock 凭证必须是 Base64URL 双层 JSON：
> {protocol:{payment_proof:<mockProofSecret>,trade_no},method:{client_session:<会话ID>}}
> 传裸订单号会被正确拒绝（403）——这不是 bug，是验付严格的证据。

P4 · 发布物三件

发布前三查（缺一不可）：
1. 沙箱全链路走通（402 / 账单 / 验付 / 履约四项）；
2. 三处单价一致；
3. 包内 grep 不到任何密钥片段。

P5 · 发布前自检器（造价极低、拦错极准）

给每个 pay skill 配 scripts/<name>_audit.py，8 段：

> 新增检查项后，必须做一次注入故障验证（把断言故意弄错，确认它真能 FAIL）——否则可能写了恒真的假检查，看着全绿其实没拦任何东西。

高危易错清单（13 类，全部踩过，逐条对照）

1. name 字段写成中文 → skill 唯一标识必须是英文 slug 且等于目录名；中文名放 title。中文 name 会导致平台寻址/触发/更新失效。
2. 价格硬编码在渲染层 → 报告页脚/页眉一律读 config.priceStr；测试断言也读 config，否则「代码改了断言没改」会假绿。
3. 付费资源不印订单号 → 免责段写「见订单」却不印编号就是空话。index.js 调 renderReport 须传 out_trade_no。
4. 多 skill 共用订单集合/文件目录 → 订单串号、幂等错乱。每 skill 必须独立 COLLECTION 与 FILE_DIR。
5. probe 时把「无凭证」当「未付款」处理 → 支付客户端重放时只注入 Payment-Proof，不带 X-Out-Trade-No，故服务端必须支持会话反查订单，否则交付失败。
6. 验付结果不明就提示用户重付 → 必须返回 202 VERIFY_PENDING，绝不提示重复付款。
7. 密钥缺失时降级放行 → prod 模式密钥缺失必须拒发单（500），绝不静默放行。启动打印 [boot] 日志（模式/单价/serviceId/密钥齐备度，不含密钥内容）。
8. 加了免费功能却把转单做成"逼单" → 免费功能的价值在于持续在场，不在于当场转化。一旦出现「记完账就劝付费」「不买就少给数据」，用户会立刻卸载。红线五条（不催促/不施压/不阻断/不重复/不越界）必须写进文档并让审计器逐条断言——只写在文档里会在迭代中被遗忘。
9. 发布包把 icon 装进去了 → 上传包不含 icon（平台侧单独管理），否则一个 261KB 的 PNG 会占整包 86% 体积。打包脚本要显式排除 icon.*。
10. 自检器写了恒真的假检查 → 新增断言后必须做注入故障验证（故意弄错，确认能 FAIL）。否则「PASS 94」可能一条也没拦住。
11. 非法业务参数照样开出账单（v1.0.1 新增，最伤用户的一种） → probe 不校验业务参数，{"scene":"clinic"} 这种错值也能开出 402 并让用户付款成功，直到取资源才 400。发单前必须机器校验 body 参数（见 P1.5）。
12. 把「退出码 0」当成「交付成功」（v1.0.1 新增） → 退出码 0 只代表支付凭证有效，必须再看「资源响应状态」是否为 200。两段判据，缺一不可（见 P1.5）。
13. 拉起收银台后只给二维码路径、不给图（v1.0.1 新增） → CLI 输出的是 MEDIA: file:///...，只写路径用户扫不到码。必须复制到工作区 + present_files 展示 + 附链接兜底（见 P2 交互纪律）。

本机环境要点

已完成案例（可直接取用为母本）

三者同应用同商户（APP_ID 2021006197669671、商户 PID 2088442101195827），仅 serviceId 与单价按服务分别注册。

三案例横向对比（选母本时看这张）

> 选母本口诀：要免费引流 → 选 pet-bill-advisor；要报告做到极致 → 选 bazi-emotion-companion；
> 要最小可用 → 选 company-due-diligence。三者服务端代码同源，业务模块独立。

相关文档

本工厂升级后的自检命令

python scripts/factory_selfcheck.py --inject
# 期望：结构 + 内容自检 PASS，注入故障验证亦 PASS
# 注入验证全过 = 断言不是恒真的假检查（这一步不能省）

Changelog

• 1.0.1：付费链路实战加固（三个真金 pay skill 约两周实测沉淀，全部对应真实事故）：① rc 两段判据——退出码 0 只代表支付凭证有效，「资源响应状态」200 才算交付；② 发单前参数校验闸门（P1.5）——probe 前机器校验 body，非法业务参数绝不开单；③ 售中兜底——已付款但资源 4xx 时，同一 trade_no 携修正 body 重查取回，绝不要求用户重付；④ POST 资源守候轮询必须与 402-buyer-pay 参数完全一致（-m/-d/-H），空 body 重放会伪装成商户部署故障；⑤ 402-buyer-pay 实参表（CLI v0.4.1 实测 -f/--file，非 -b）；⑥ 收银台二维码必须展示图片本体并附链接兜底；⑦ 能力边界框（适用/不适用/三个前置坑）与可复制触发示例（正例 5 条 + 反例 3 条）前置于 SKILL.md 头部，30 秒判断该不该用、怎么开口（TRACE A 维度定向补强）。母本 payment-protocol-template.md 与自检器 D10~D14 事故拦截判据同步。
• 1.0.0：首版。