汇麦笔记配图（笔记配图成品）

概述

汇麦笔记配图 · SkillPay 付费版

给每一篇笔记配一张能直接用的竖版图片。业务由服务方（上海一粒麦籽信息有限责任公司）的付费服务执行，客户端不本地执行本技能。

• 计费单位：一批 5 张笔记配图（每篇一张，固定张数）
• 当前价格：9.8 元/次
• 服务端点：https://pay.huimaiglobal.com/v1/skills/invoke

何时使用

• 用户已有若干篇笔记（标题+正文），需要逐篇配图。
• 用户说「给这些笔记配图」「出配图」。

不适用：用户要的是封面（走「汇麦封面设计」）；用户还没有笔记正文，只有选题（先走「汇麦笔记写作」）。

前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，工具名带前缀也算；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：静默继续本 Skill 的后续流程，不向用户提及本检查。
• 不支持：终止流程且不要发起下单。只向用户说明结论与解决办法（无需解释你如何检查、不要出现具体工具名），按智能体类型提示：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 https://skillhub.cn/install/skillhub.md 安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体或安装微信支付 AI 支付插件后重试。

输入契约

input 必须是一个 JSON 对象，字段如下（与线上服务端一致，请勿自造字段名）：

示例：

{
  "notes": [
    {"title": "在闵行找到一家安静的手冲店", "body": "豆子每周换，店主会问你平时喝什么口味…"},
    {"title": "社区咖啡店怎么选豆子", "body": "先看烘焙日期，再看产区和处理法…"}
  ],
  "style": "真实、生活感、克制"
}

交付物

图片内不出现文字、水印、二维码。不交付提示词，也不以占位图代替图片。一次最多 5 张（计价单位为「5 张配图」）；输入的笔记不足 5 篇时按实际篇数交付。

调用流程（必须严格遵守）

一次付费调用分四段：首次请求 → 返回 402 并发起支付 → 支付成功后携带 X-Out-Trade-No 重试 → 服务端查单履约返回 200。

直接按下面的 HTTP 请求调用即可；scripts/paid_client.py 仅供开发排障时做非支付连通性自测，不是调用主路径。

1. 前置检查：按上面「前置检查」确认支付能力，不具备就停止。
2. 首次请求（创建订单）：

   POST https://pay.huimaiglobal.com/v1/skills/invoke
   Content-Type: application/json
   Idempotency-Key: <32 位随机十六进制，建议每个任务一把>

   {
  "skill_id": "huimai-note-illustration",
  "input": {
    "notes": [
      {
        "title": "在闵行找到一家安静的手冲店",
        "body": "豆子每周换，店主会问你平时喝什么口味…"
      },
      {
        "title": "社区咖啡店怎么选豆子",
        "body": "先看烘焙日期，再看产区和处理法…"
      }
    ],
    "style": "真实、生活感、克制"
  }
}

服务端返回 HTTP 402，响应头与响应体同时携带支付码 WeixinPay-Required 与订单号 X-Out-Trade-No，两者都必须保存：

   {
     "code": "PAYMENT_REQUIRED",
     "message": "需要支付后才能获取内容",
     "WeixinPay": {
       "WeixinPay-Required": "<本次响应的支付码>",
       "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
     },
     "out_trade_no": "<本次响应的订单号>",
     "amount": "9.80",
     "currency": "CNY"
   }

1. 发起支付：先向用户说明用途、金额（9.8 元/次）与服务方（上海一粒麦籽信息有限责任公司）；再把 WeixinPay-Required 的完整值作为 paymentCode，无条件调用 weixinpay_pay 向用户申请支付授权。用户尚未开通 AI 专属卡时，调用weixinpay_register 取绑定链接原样发给用户（手机微信 →「我」→「服务」→「钱包」→「AI 专属卡」→ 开通并转入）。任何情况下不要自行签名，不要向用户展示或转发WeixinPay-Required 原始值，也不要写入日志。
2. 支付成功后获取资源（⚠️ 必须执行）：用与第一次完全相同的 body 重新 POST 同一端点，并带上第二步保存的订单号：

   POST https://pay.huimaiglobal.com/v1/skills/invoke
   Content-Type: application/json
   X-Out-Trade-No: <第二步保存的订单号>
   WeixinPay-Required: <第二步保存的支付码>

   {
  "skill_id": "huimai-note-illustration",
  "input": {
    "notes": [
      {
        "title": "在闵行找到一家安静的手冲店",
        "body": "豆子每周换，店主会问你平时喝什么口味…"
      },
      {
        "title": "社区咖啡店怎么选豆子",
        "body": "先看烘焙日期，再看产区和处理法…"
      }
    ],
    "style": "真实、生活感、克制"
  }
}

不携带 X-Out-Trade-No 重试就永远拿不到付费内容。

1. 处理 processing（HTTP 202）：服务端仍在生产。读取响应里的 retry_after 秒数，用同一凭据重发同一请求直到 200；轮询期间不要重新下单、不要重复付款。
2. 处理 NOT_PAID（HTTP 402）：订单已创建但微信侧尚未收到款项（用户还没付或支付被取消）。等几秒后原样重发同一请求（带 X-Out-Trade-No）；若用户确认已付款仍长期返回 NOT_PAID，按「余额不足」兜底话术引导其到 AI 专属卡充值后再试。不要新建订单、不要换新订单。
3. 处理退款结果（HTTP 200）：code 为 REFUNDED 表示服务方无法交付内容并已自动全额退款，向用户说明后终止流程（不重试、不重新付款）；code 为FULFILL_AND_REFUND_FAILED 表示服务异常且退款未成功，建议用户联系服务方客服，同样终止流程。
4. 成功后交付：按 content.deliverables[] 下载 url，核对 name/bytes/sha256 后把成品交付给用户。

边界

• 客户端不得在未付款时自行完成业务，也不得索取生图接口密钥。
• 订单一旦创建，请求参数不可变更；换笔记必须换新的状态文件。
• 服务端报错、订单过期、金额不符时停止并核对原订单，不要自动换单重付。
• 业务失败的订单由服务方处理恢复或退款，客户端不得自行重下；服务方确认无法交付时会自动全额退款

并以 code: "REFUNDED" 回告，客户端据此终止流程即可。

• 收到 NOT_PAID 只代表款项尚未到账，等待后重跑同一订单即可，不得据此新建订单或改价重付。