鸿爪派·数字名片 Pay Skill

概述

鸿爪派出品 · 杭州鸿爪派数字科技有限公司

把「我是谁、我能提供什么、为什么值得加我」变成一套可直接发出去的高端商务数字名片 —— 一次付费，三主题全包。

功能定位

• 做什么：接收结构化名片 JSON，服务端真实渲染三套视觉主题（焦橙编辑风 / 极简蓝 / 暗夜黑）并导出 PNG，一次付费全部交付。
• 不做什么：不编造用户未提供的数字、案例或证书；不做微信小程序名片；不生成 PDF / 实体印刷稿；不提供免费单主题渲染（免费单主题请使用源技能 hongzhua-digital-card-generator）。

服务依赖（第一性）

本 Skill 的名片渲染由鸿爪派支付服务端真实提供，源文件仅是调用说明书：

• 付费服务端：https://hongzhua-wepay-307089-12-1421609757.sh.run.tcloudbase.com（微信 Agent Pay X402 协议，按次计费 0.5 元/次）
• 未完成微信支付授权前，服务端只返回 402 + WeixinPay-Required 支付触发标识，不返回任何渲染产物；
• 支付确认以微信支付回调 / 服务端主动查单为准（out_trade_no 维度，幂等去重）；
• 渲染内核与模板由服务端持有，源文件不含渲染逻辑，脱离服务端无法获取付费产物。

输入参数（服务端校验）

提交名片 JSON（schema 与源技能 hongzhua-digital-card-generator 完全兼容）：

数据真实性原则：所有数字、案例、证书必须来自用户输入，Skill 不得编造。缺失项用占位符 【待补充：你的一项核心能力】。

参数不合法时服务端返回 400 与明确错误，不产生计费。

X402 支付接入（Pay Skill 协议）

本 Skill 已接入 SkillHub X402 Agent Pay 协议（基于微信支付 v3 Native 支付），调用前由服务端完成前置检查、预下单与支付触发，用户授权支付后 Agent 继续获取付费能力。计费模式：按调用量计费（per_call），单次调用 0.5 元（= 50 分），三主题全包。

商户与密钥（已配置）

计费边界

• 计费单位：每次成功调用计 1 次（从参数解析到三主题渲染交付的完整一次流程）。
• 不计费场景：前置检查失败、参数校验未通过（400）、预下单签名失败、用户主动取消支付。
• 订单标识：orderNo 由服务端生成（16 位大写字母数字，如 MTXQX4PM32D4A82AB49789B9），幂等去重，用于查单与对账。

Agent 调用协议（真实端点）

服务发现（可选）：

GET https://hongzhua-wepay-307089-12-1421609757.sh.run.tcloudbase.com/api/payment/skills/hongzhua-card-pay

返回价格、参数契约与协议说明。

调用入口（服务端真实契约，已实测）：

POST https://hongzhua-wepay-307089-12-1421609757.sh.run.tcloudbase.com/api/payment/native
Content-Type: application/json

{
  "productId": "custom",
  "amount": "0.5",
  "note": "hongzhua-card-pay 数字名片 三主题"
}

真实响应（Native 下单成功）：

{
  "orderNo": "MTXQX4PM32D4A82AB49789B9",
  "codeUrl": "weixin://wxpay/bizpayurl?pr=5QQN4PWyMzS3gyDy",
  "product": { "id": "custom", "name": "hongzhua-card-pay 数字名片 三主题", "amount": 50 },
  "sessionId": null
}

Step 1 · 付费前置检查（precheck）

Agent 调用本 Skill 前，必须先做付费前置检查：

1. 检查 weixinpay 插件是否安装：Agent 侧调用 weixinpay_check_plugin()（或检查 weixinpay_pay 工具是否在可用工具列表）。若未安装，引导用户启用 weixinpay 插件后再调用本 Skill，否则无法完成支付触发；
2. 校验请求参数（name、title 必填等），不合法会在服务端被拒（400，不计费）；
3. 服务端收到调用后生成幂等 out_trade_no 并落库待支付订单，随后自动进入微信下单与 X402 预下单。

若 weixinpay 插件缺失，本次调用直接返回错误 "需先安装 weixinpay 插件才能完成付费调用"，不发起付费调用。降级路径：用 402 响应中的 code_url 在终端渲染二维码，用户微信扫码支付后按「支付后重试」继续。

Step 2-3 · 服务端下单与 X402 预下单（对 Agent 透明）

服务端按官方规范完成微信 Native 下单（金额锁定 50 分，商品名 鸿爪派·数字名片 Pay Skill）取得 code_url，再以 payment_required（pay_type=SKILL_PAY、pay_mode=AUTH_AND_PAY）按 5 行签名串做 SHA256withRSA 签名，调用微信支付 AI 预下单接口换取 payment_code（有效期 15 分钟）。

Step 4 · 支付触发（返回 402 + payment_code）

未支付时，服务端把 payment_code 同时写入 HTTP Header 和响应体：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
X-Out-Trade-No: MTXQX4PM32D4A82AB49789B9
Content-Type: application/json

{
  "data": {
    "message": "本次生成名片需要支付后继续",
    "skill_id": "hongzhua-card-pay",
    "out_trade_no": "MTXQX4PM32D4A82AB49789B9",
    "amount_fen": 50,
    "pay_data": { "type": "code_url", "value": "weixin://wxpay/bizpayurl?pr=..." },
    "expires_at": 1787990000
  },
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

Agent 把 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay 发起用户授权；用户在微信内完成支付。

支付后重试机制（核心）

用户完成微信支付后，Agent 必须用相同的请求 body 重新调用同一入口（body 完全不变），并在 Header 携带订单号：

POST https://hongzhua-wepay-307089-12-1421609757.sh.run.tcloudbase.com/api/payment/native
X-Out-Trade-No: MTXQX4PM32D4A82AB49789B9
Content-Type: application/json

{ "productId": "custom", "amount": "0.5", "note": "hongzhua-card-pay 数字名片 三主题" }

服务端以微信支付回调 / out_trade_no 主动查单确认支付成功（绝不信任 Agent 侧声明），随后返回三主题渲染产物：

{
  "skill_id": "hongzhua-card-pay",
  "skill_version": "1.0.2",
  "paid": true,
  "out_trade_no": "MTXQX4PM32D4A82AB49789B9",
  "result": {
    "format": "html+png",
    "files": [
      { "path": "index.html", "theme": "dark" },
      { "path": "themes/fashion-card.html", "theme": "fashion-card" },
      { "path": "themes/minimal-blue.html", "theme": "minimal-blue" },
      { "path": "themes/dark.html", "theme": "dark" }
    ]
  }
}

重试时 body 不能改、参数不能变（服务端按参数指纹关联原单，body 变更视为新调用需重新付费）。即使重试未携带订单号，只要 body 与首次一致且在 30 分钟内，服务端也能自动关联原单，不重复扣费。

交付产物结构

my-card/
├── index.html                  # 默认主题（JSON 的 theme 字段，默认 fashion-card）
└── themes/
    ├── fashion-card.html       # 焦橙编辑风
    ├── minimal-blue.html       # 极简蓝
    └── dark.html               # 暗夜黑

异常处理

订单号传递与对账

• 传递链：服务端生成 out_trade_no → 微信下单 → payment_required.skill_info 关联 → payment_code 返回 Agent → 用户支付 → notify_url 回调 → 服务端按 out_trade_no 更新订单为已支付 → 结果回流 → T+1 结算到绑定商户号。
• 对账依据：以微信支付回调或 out_trade_no 查询结果为准；SkillHub 商户中心提供调用与结算明细。

对抗式红线（服务端实现契约）

1. 未支付必 402：渲染分支仅从查单确认处可达；无凭证 / 凭证无效 / 订单非本技能所下，一律不返回产物。
2. 先查单后渲染：每次交付前按 out_trade_no 实查微信支付，确认 trade_state=SUCCESS；绝不信任客户端单方「我已支付」的声明。
3. 金额锁定：订单金额在下单时由服务端锁定（50 分），查单核对金额一致才交付。
4. 凭证零入库：源文件不含任何商户号 / AppSecret / API 密钥 / RSA 私钥；商户凭证仅存在于服务端。
5. 品牌红线：品牌名一律「鸿爪派」「鸿爪派科技」，渲染产物落款 | 鸿爪派出品。
6. schema 兼容：名片 JSON 与源技能 hongzhua-digital-card-generator 完全互通。

资源索引

依赖

• 无需本地依赖：付费渲染由服务端完成，Agent 只需支持 HTTP 调用与 weixinpay_pay 工具。
• 可选：pip install qrcode，在无 weixinpay 插件环境下渲染终端二维码降级路径。

作者与协议

鸿爪派出品 · 杭州鸿爪派数字科技有限公司 · 何云 · 鸿爪派主理人本 Pay Skill 协议：MIT License · 自由使用、商用、二次分发需保留 | 鸿爪派出品 落款

本 Skill 的 X402 接入遵循 SkillHub 官方《升级为 Pay Skill》规范（https://www.skillhub.cn/tutorials#agent-pay-onboard）。