AI智能体技术/经验/工作流（支付宝 AI 按量付费）

这个技能解决什么问题

你有一个技能（或想做一个），想让它「免费层试用 + 付费解锁」，用支付宝 AI 按量付费（A2M）收款，并且买家使用时能自动弹出支付宝完成付款。本技能给出从零到跑通的完整路线。

分层服务（本技能的核心）

• 免费层 · 路线概览：三个认知 + 五阶段全景路线 + 每阶段关键点 + 五条实测结论——足够理解整条路怎么走、坑在哪里。
• 付费层 · 完整执行包（支付宝按量付费 10 元/次）：四个可直接复制的脚本模板（付费闸口 / 账单探测 / 支付工具自引导 / 执行包交付）、402 账单结构逐字段详解、支付宝侧配置步骤、上线前检查清单——照着抄就能把改造做完。

> 付费闸口位于 scripts/payment_gate.py：未付费返回标准 402 Payment-Needed，由 agent 按下方「自动付款流程」驱动支付宝付款，付款后携带 Payment-Proof 重试并放行，随后交付执行包。

执行流程（务必按此分层）

1. 先出概览：用户提出「技能怎么收费 / 怎么做 payskill」时，用免费层内容回答（三认知 + 五阶段 + 实测结论），并说明完整执行包（脚本模板 + 参考文档）需付费 10 元/次解锁。
2. 付费闸口 + 自动付款：用户索要执行包时，先运行 python scripts/payment_gate.py：
   - 返回放行（已付费/已携带 Payment-Proof）→ 直接进入第 3 步交付；
   - 返回 402 Payment-Needed → 不要等待平台，立即按下方「自动付款流程」用 alipay-bot 驱动支付宝 10 元付款；付款完成、验签通过后放行。
3. 交付执行包：闸口放行后运行 python scripts/deliver.py 拉取并落盘执行包（服务端验付通过后返回 files[]），再结合用户的具体技能给出适配建议（改计费端点、改单价、改商品名等）。

自动付款流程（alipay-bot，自动就绪）

当 payment_gate.py 返回 402 时，按以下步骤驱动支付宝付款：

0. 确保工具就绪（自引导安装）：运行 python scripts/ensure_pay_tool.py——检测 alipay-bot 是否可用，缺失时自动安装支付宝官方 CLI（@alipay/agent-payment，需 Node.js，首次约 1-2 分钟），输出可执行路径。后续 alipay-bot 命令若 PATH 中不可用，替换为脚本输出的完整路径。
1. 获取 402 账单：运行 python scripts/probe_bill.py，从计费端点获取账单写入 bill_b64.txt（有效期约 30 分钟，超时重跑）。
2. 生成付款码：
   alipay-bot 402-buyer-pay -r "https://agent-tech-playbook.app.workbuddy.host/a2m/resource?sharecode=KDZH42CK2Y" -f bill_b64.txt
   将输出的付款二维码/链接展示给用户，等待用户在支付宝确认支付 10 元。
3. 完成履约：用户支付后，运行
   alipay-bot 402-query-payment-status -r "https://agent-tech-playbook.app.workbuddy.host/a2m/resource?sharecode=KDZH42CK2Y" --out-shake-no <交易号>
   返回「履约成功」即付款闭环。
4. 验签放行 + 拉取执行包：带 X_PAYMENT_PROOF 重跑 python scripts/payment_gate.py；通过后运行
   python scripts/deliver.py，把服务端返回的三个脚本模板与三份参考文档落盘到本技能的 scripts/ 与 references/，
   然后结合用户具体技能给出适配建议（改计费端点、改单价、改商品名等）。

> ⚠️ -f 传账单文件，不要用 --amt-payment-link（会报 PAYMENT_LINK_INVALID）。

三个认知（30 秒建立框架）

认知一：三个角色。 卖家（你）：有技能、有支付宝商户号（PID），提供「免费层 + 付费层」；买家（用户）：用 agent（如 WorkBuddy）跑你的技能，他有自己的支付宝账号；计费服务端：你部署的一个 HTTPS 端点，未付费时返回 402 账单，收到付款凭证后验付、放行、确认履约。

认知二：付费能力在买家侧，不在技能里。 技能本体只负责「发 402 信号 + 验凭证放行」，它自己不会打开支付宝。真正让支付宝弹出来的是买家 agent 的支付能力，两条路：① 买家侧 alipay-bot（阶段 5 的自引导方案，推荐）；② SkillHub 平台强制调度（平台层能力，作者无法控制，作为兜底预期）。

认知三：价格三层必须一致。 支付宝服务注册价（权威价）= SkillHub 发布向导「单次调用价格」= SKILL.md 描述价。任何一层不一致，都会导致「用户无法支付」。

全景路线图

阶段1 支付宝侧准备           阶段2 计费服务端            阶段3 技能改造
创建应用→开通AI付能力        部署资源端点               payment_gate.py 付费闸口
→配置RSA2密钥               →402+Payment-Needed账单    probe_bill.py 账单探测
→签约服务、设单价            →验付→放行→履约确认        SKILL.md 分层+自动付款流程
→记录 APPID/PID/service_id   →按订单号幂等              →价格三层一致
        │                        │                           │
        └────────────────────────┴───────────────────────────┘
                                 ↓
                      阶段4 发布上架              阶段5 买家自动付款
                      dry-run 验证格式            ensure_pay_tool.py 自引导装 alipay-bot
                      skillhub publish            402-buyer-pay 弹付款码
                      等审核（约10分钟）           402-query-payment-status 履约
                                                  带 X_PAYMENT_PROOF 重试放行

五阶段概览

阶段 1：支付宝侧准备

在支付宝开放平台创建应用并开通 AI 付（A2M） 能力，配置 RSA2 密钥（应用私钥只放服务端），在 AI 付服务管理里签约按量付费服务并设定单价（0.01–50 元，这里的价格是权威价）。收尾核对四要素：APPID / PID / service_id / 密钥。详细步骤见 references/alipay-setup.md（付费层）。

阶段 2：计费服务端（核心）

部署一个 HTTPS 资源端点，实现四件事：① 无凭证请求返回 402 + Payment-Needed（base64url 账单，分 protocol / method 两部分）；② 带 X_PAYMENT_PROOF 请求调 alipay.aipay.agent.payment.verify 验付；③ 验付通过发放资源，并调 alipay.aipay.agent.fulfillment.confirm 履约确认；④ 按 out_trade_no 幂等，重复请求直接返回缓存，杜绝重复扣费。账单逐字段结构见 references/bill-format.md（付费层）。

阶段 3：技能改造

给技能包 scripts/ 加三个文件（模板见付费层）：payment_gate.py（付费闸口：查本地缓存 → 无凭证发 402 → 有凭证验签放行 → 24h 幂等持久化）、probe_bill.py（探测计费端点拿账单）、ensure_pay_tool.py（自引导安装 alipay-bot）。SKILL.md 改四处：① 分层服务写清免费层/付费层与价格；② 执行流程先跑免费层，付费时先跑闸口；③ 自动付款流程写清五步；④ 两条发布纪律——不写裸网络命令（封装进 scripts/）、不写作者本机硬编码路径。发布前核对价格三层一致。

阶段 4：发布上架

skillhub publish <目录> --dry-run 验证格式 → skillhub publish <目录> --changelog "..." 正式发布 → 返回 skillId。审核约 10 分钟，期间市场搜索可能仍显示旧版本号（索引延迟，正常）。旧版本本地留底 zip 可随时回退。

定价必须走 API（网页后台没有调价入口）：CLI 的 publish 也不带定价参数。发布成功后用 PUT /api/v1/community/skills/<slug>/pricing，body 为 {"price":"10.00","currency":"CNY","payChannel":"alipay"}；校验看 GET /api/v1/skills/<slug> 的 channelPricing.price。不设价买家会「无法支付」。完整命令见 references/checklist.md（付费层）。

阶段 5：买家自动付款（自引导，零预装）

买家 agent 跑到 402 时：ensure_pay_tool.py 就绪 → probe_bill.py 拿账单 → alipay-bot 402-buyer-pay 弹付款码 → 用户支付 → 402-query-payment-status 履约 → 带 X_PAYMENT_PROOF 重试放行。买家全程零预装，首次运行自动装好支付工具。

五条实测结论（照做即可）

• -f 传账单文件，不要用 --amt-payment-link（会报 PAYMENT_LINK_INVALID）。
• 账单有效期约 30 分钟，付款前重新探测拿新账单。
• 买家和卖家不能相同：自测时必须用第二个支付宝账号当买家（支付宝禁止自付）。
• alipay-bot 是支付宝官方 CLI（npm 包 @alipay/agent-payment），不是技能市场技能——必须靠 ensure_pay_tool.py 自引导安装。
• 付款闭环判据：402-query-payment-status 返回「履约成功」，且 24h 内重复调用不重复扣费。

付费层交付物（付款后交付）

> 本技能的付费机制本身就是活样板：scripts/ 下三个文件既是本技能的闸口，也是你要复制的模板——把 probe_bill.py 的端点改成你的计费地址即可。

能力边界

• 本技能是改造路线 + 模板，不含你的业务代码；计费服务端需按阶段 2 自行部署。
• 支付宝侧审核周期以平台为准；单价上限 50 元/次。
• 技能收费的最终强制力在平台调度层；买家侧自引导是当前最可靠的自动付款路径。