付费技能服务端源码

付款 29.90 元，直接拿到一套能立刻跑起来的按量付费服务端源码：把「用户访问 → 返回账单 → 用户付款 → 验付 → 履约交付」这条链路全部接好，你只要换成自己的收款配置就能开始收钱。

这个技能能给你什么

• 省掉从零开发：登录、下单、402 账单签发与签名、支付宝验付、履约、交付六段已经写好并通过真机联调，不用自己研究支付协议的细节。
• 只需改个人配置：替换 AppId、应用私钥、支付宝公钥、商户名、单价这 5 个值，就能把你的技能 / API / 工具改成按次收费。
• 给的是源码不是黑盒：完整可编译的 .NET 10 工程，可二次开发；协议实现清晰，照着搬到 Python / Node 也不难。
• 交付即能上线：部署脚本、systemd 与 nginx 配置、客户端示例、《接入教程》和联调排错清单随源码一起给。
• 少踩已验证过的坑：客户端断连导致「付了钱拿不到货」、部署时清空订单库、单价三处不一致导致无法支付 —— 这些真实踩过的坑在教程与本技能正文里都写了处理办法。

何时使用

• 用户提到「付费技能服务端源码」「支付服务端源码」「按次收费源码」「自建支付服务端」时
• 用户提到「402 支付」「按量付费」「AI 付服务端」，或想把某个技能、接口改造成按次收费时
• 用户已付款，需要取回交付物（python scripts/buy.py --trade-no <交易号>，凭据可复用）

第 0 步（必做）：先自检技能版本

技能装到本地后就是一份文件快照，不会自己变新。取货器落后于线上版本时，用户会卡在「取不到货」——而且往往是在付过钱之后才暴露。所以每次动手前先跑一次版本自检：

python scripts/sync.py --json

版本真相源是 SkillHub（本技能发布在 @user_01de61f3/ym-pay-service-source），不是卖家自建的服务端——所以这一步不依赖取货服务是否在线，装完技能就能查。

这个脚本是只读的：只比对版本、只给结论，不会下载任何东西、不会改动技能目录里的任何文件。要换版本，必须由你（或用户）明确做一次重装（见下表）。

按返回的 status 字段决定怎么做，不要跳过这一步：

--json 输出里的 reinstall_command 字段就是可直接照念的重装命令。

更新办法（只有这一种）

重装本技能：

skillhub install ym-pay-service-source     # 命令行安装（注意装完可能要移平多出的一层目录，见「常见坑」第 1 条）

或在所用平台的技能市场里重新安装。

不做自动覆盖：技能不会也不需要改写自己。理由是完整性无从校验——平台的下载接口不提供技能包的摘要字段，脚本如果自己去把包换掉，就等于「谁来替换、替换成什么」全凭下载那一刻的网络结果决定。宁可多跑一条重装命令，也不要一个能悄悄改写自己的技能。

三条容易搞错的地方：

• 自检失败和联网核对失败都不是付款问题，与订单无关。重新发起支付解决不了，还会让用户白付一笔。
• 技能包更新是公开的、免费的，任何人可重装，不需要付款。付费只针对交付物（源码包）本身。
• 硬阻断由版本号语义决定：主版本号不同 = 协议不兼容 = 必须更新。所以卖家该 bump major 时就得 bump，别拿 minor 偷偷改协议。

第一步（必做）：先把买家环境备齐

付款环节依赖的东西不在本技能里，装完技能先跑一次自检，别等到付款中途才撞上环境问题。

依赖清单

平台已内置支付宝 AI 付 / 402 支付能力时，Node.js、alipay-bot、钱包三项可全部跳过，让平台直接完成付款，拿到 Payment-Proof 后执行 python scripts/fetch-source.py --proof "<...>" 即可。

三条命令

# 1) 自检：一次性列出缺什么、怎么补
python scripts/preflight.py

# 2) 缺啥装啥（Linux/macOS；Windows 用 scripts\install-buyer-env.ps1）
bash scripts/install-buyer-env.sh

# 3) 再自检一次，全绿即可付款
python scripts/preflight.py

装 alipay-bot 最省事的一条命令（Windows / Linux / macOS 通用）：

npx -y @alipay/agent-payment@1.0.26 install

版本号是固定写死的，不要改回 @latest（浮动版本意味着「不知道装到的是什么」）。npm 会自行校验包的 integrity；若要手动装制品，scripts/install-buyer-env.sh 会先比对 sha256 再解压。

钱包绑定（只需一次，需人工扫码，脚本无法代劳）：

alipay-bot check-wallet                                # 期望「已开启支付宝支付功能」
alipay-bot apply-wallet --agent-name '<你的Agent名>'     # 未绑定时：扫码
alipay-bot bind-wallet --code '<扫码得到的绑定指令>'

完整安装手册、手动安装命令与三个已知安装坑见 references/buyer-env-setup.md。

第二步：付款并取回交付物

python scripts/buy.py

这一条命令串完了整条链路：取账单 → 打印金额与订单号等你确认 → 调 alipay-bot 生成支付链接与二维码 → 你扫码付款 → 自动轮询 → 落盘 → 校验 SHA-256。

把脚本打印的账单完整念给用户看，尤其是金额、收款方与订单号，确认后再继续。

成功时输出：

交付成功
  文件      /path/to/paid-skill-service-source-v1.1.0.zip
  大小      95185 字节
  SHA-256   bc4b28f0...
  交易号    2026...
  校验通过

最后告诉用户：解压后得到服务端源码目录，编译、配置与部署步骤见包内 docs/接入教程.md。

已付款但没拿到货

python scripts/buy.py --trade-no <交易号>

超时、断连、服务端 5xx 都用这条重试。绝不要重新发起支付 —— 会被收两次钱。

手工分步执行（需要精细控制时用）

python scripts/fetch-source.py                       # 取账单
python scripts/fetch-source.py --proof "<Payment-Proof>"   # 带凭据领取

资源地址可用环境变量 PAY_SERVICE_RESOURCE_URL 覆盖，默认输出目录为当前工作目录（--out 指定）。

商品信息

资源地址必须是 HTTPS：支付宝 CLI 硬性拒绝 HTTP 资源地址（Error: paid resource URL must use HTTPS）。当前默认地址走的是临时隧道，服务器重启后会变；地址失效时脚本会明确提示，可用 PAY_SERVICE_RESOURCE_URL 覆盖或联系卖家确认最新地址。

付款环节的硬规则

• 付款只有一条路：支付宝 AI 付链路。 payment_proof 与 trade_no 只能由这条链路产生，普通扫码转账拿不到，也无法手工构造。不要试图手工组装凭据，也不要让用户去别处转账。
• 重试必须原样重发同一请求。账单里不含请求体，服务端也无法知道客户端第一次发了什么；换了参数就会出现「付 A 的钱、拿 B 的货」。
• 交付与连接脱钩。客户端断开不会导致交付失败，超时后用同一凭据重试即可取回结果 —— 但绝不要重新发起支付。
• 凭据可复用。同一 Payment-Proof 重复请求返回相同内容且不重复扣费；服务端返回 5xx 时保留凭据稍后重试。
• 订单号是唯一对账依据。用户说「付过钱了但没拿到」时，用订单号 + 交易号定位，不要凭印象判断。

目录说明

• scripts/sync.py — 版本自检（只读）：比对 SkillHub 上的版本并给出结论与重装命令，不下载、不修改任何文件（第 0 步就跑它）
• scripts/buy.py — 一键购买：取账单、发起支付、轮询、落盘、校验（推荐入口）
• scripts/preflight.py — 环境自检，列出缺失依赖与修复命令
• scripts/install-buyer-env.sh / .ps1 — 一键补齐 Node、alipay-bot、钱包引导
• scripts/fetch-source.py — 分步版：取账单、组装协议头、领取交付物并校验摘要
• references/buyer-env-setup.md — 依赖清单与安装手册，含三个已知安装坑
• references/protocol.md — 402 协议字段、响应码对照、排错清单（需要手写客户端或排查失败时读它）
• config.json — 可选配置；只在想改用自建服务端的版本清单时才填 manifest_url，默认留空即可（升级时原样保留，不会被新版包覆盖）

常见坑

安装与依赖

1. 装完技能平台识别不到 —— skillhub install 会多套一层 @命名空间/ 目录。移平：cd ~/.codebuddy/skills && mv "@user_01de61f3/ym-pay-service-source" ./ym-pay-service-source && rmdir "@user_01de61f3"。
2. 当前 Node.js 版本过低 —— CLI 要求 ≥ 23，系统自带的 22.x 不够。nodejs.org 在部分网络不可达，用 npmmirror 镜像装。
3. BlueShield addon is missing —— 安全插件 dist/ 必须与二进制同级。装在哪个目录都行，dist/ 跟它放一起即可（例如二进制在 ~/.local/share/alipay-bot-cli/，dist/ 也在那儿）；不是「非得放 /usr/local/bin」。
4. tar: This does not look like a tar archive —— 官方包实为 ZIP，安装器按 .tgz 解（CLI bug）。改用 unzip 手动装。
5. 资源地址是 HTTP —— 支付宝 CLI 直接拒绝，必然付款失败。看到 paid resource URL must use HTTPS 就是这个原因。

协议与交付

6. 把 content 当普通 JSON 直接取字段 —— 服务端返回的 content 是一个 JSON 字符串，交付物藏在它内部，必须再解析一层。少解析一层就会误判为「没有 delivery 字段」。
7. 重新发起支付而不是复用凭据 —— 交付超时后重开一笔支付会被收两次钱。正确做法是用同一 Payment-Proof 重试原请求，服务端幂等返回既有产出。
8. 三处单价不一致导致无法支付 —— 服务端配置、支付平台登记的单价、技能标价必须完全相同（本商品为 29.90）。任一处不同，用户付款时都会被拒。
9. 用 402 判断「资源不存在」 —— 402 同时用于「需要支付」与「凭据无效」两种场景；资源未上架返回的是 404。看到 404 说明资源编码写错了，不要重试付款。
10. 把 Base64 当 Base64URL —— Payment-Needed 与 Payment-Proof 都使用 Base64URL（- _，且可能省略 = 补位），按标准 Base64 解码会失败。脚本里已按 Base64URL 处理，自己实现时注意补 =。
11. 账单解码后再传给 CLI —— 账单必须原样保存传递，解码再编码会破坏签名，验付必失败。
12. 忽略交付物摘要校验 —— 解码后务必重算 SHA-256。ZIP 不完整仍能解出部分文件，只看文件大小会漏掉截断。

版本历史

v1.4.2 (2026-09-18)

安全整改版（响应平台安全评估的 2 条「可疑风险」，1.4.1 未通过审核，由本版取代）：

• 自更新取消自主覆盖：scripts/sync.py 改为只读版本自检器 —— 只比对版本、只给结论与重装命令，不再下载技能包、不再解压、不再改写技能目录。原实现会自动下载整包并原地覆盖 SKILL.md 等文件，且平台下载接口不提供包摘要，等于「拿到的包换了什么无从校验」。现在换版本只有一条路：用户明确重装。
• 安装脚本全面加固：@alipay/agent-payment 由 @latest 改为固定版本 1.0.26（npm 由自身校验 integrity）；手动安装官方制品时先比对 sha256、再核对包内 version.json，全过才解压安装，不通过立即中止；Node.js 改为「先下载 → 校验官方摘要 → 再解压」，不再使用 curl | tar 的下载即执行写法。
• 默认不写系统目录：手动安装默认落到用户目录 ~/.local/share/alipay-bot-cli/，/usr/local/bin 改为需要显式 --system 才使用。
• 修正一处平台适用性错误：官方 alipay-bot 制品在 CDN 上只有 Linux x86_64 一份（实测 4 种 User-Agent 下载字节完全一致，包内 version.json 恒为 linux-amd64）。原先文档里的手动安装命令在 macOS / Windows 上会装上一个跑不起来的 Linux 二进制，现已在文档与脚本里明确限定并给出替代路径。
• 交付物信息同步：商品信息表与成功输出示例更新为当前实际值 paid-skill-service-source-v1.1.0.zip（37 个文件 / 95185 字节）。
• 文档去掉明文 HTTP 与裸 IP：references/protocol.md 的三处 http://<IP>/... 示例改为 HTTPS 资源地址（HTTPS 本就是硬性要求，裸 IP 示例属于误导），并新增「网络出入口白名单」小节，逐域名列明用途。

v1.4.1 (2026-09-18)

• 资源地址更新：服务端隧道重建，默认地址同步为最新 HTTPS 隧道（scripts/fetch-source.py、scripts/preflight.py 与上方商品信息表三处一致）
• 服务端本次同步上线「取货鉴权（Observe 观察档）」与「产物按订单冻结」：同一笔付款被换会话取货会被记录（暂不拦截），重取一律返回下单时那一版产物
• 老地址已失效；仍用旧版技能的买家会看到明确的地址失效提示，可用 PAY_SERVICE_RESOURCE_URL 临时覆盖，或更新到本版

v1.4.0 (2026-09-18)

• 技能改为自更新：新增 scripts/sync.py 与第 0 步自检流程，每次使用前比对线上版本；落后即提示、可按分级处置更新，更新完直接使用新版技能
• 版本真相源改为 SkillHub（api.skillhub.cn 公开接口，免登录），不再依赖卖家自建服务端 —— 自检与下载都走平台，取货服务即便不可用也能检查版本
• 硬阻断改用版本号语义判定（主版本不同 = 协议不兼容），无需服务端声明「最低可用版本」；新增 ahead 状态识别「本地比线上新」
• 新增 _meta.json（本地版本记录）与 config.json（可选覆盖项），升级时原样保留；sync.py 同时自保，新版包漏打包它也不会被删
• 明确「技能包更新免费、付费只针对交付物」，避免把更新失败误判成付款问题
• ⚠️ 其中「自动更新/原地替换」能力与 _meta.json 已在 v1.4.2 移除（改为只读自检 + 人工重装），此处保留当时的行为记录

v1.3.0 (2026-09-18)

• 资源地址更新为最新 HTTPS 隧道地址；新增环境自检 preflight.py、一键购买 buy.py、依赖一键安装脚本（sh / ps1）、买家环境手册 references/buyer-env-setup.md
• 依赖章节前置为「第一步（必做）」，删除「手工付款」这条走不通的死路；常见坑拆成安装与协议两组共 12 条
• skillhub 安装脚本改为「先下载、看过再执行」，并写明风险与回滚