skillpay技能改造工具

概述

skillpay-creator —— 技能付费化改造服务（Pay Skill）

支付服务与计费声明

支付服务：本技能的改造服务按次计费通过 SkillPay 完成——依托微信支付 AI 专属卡与 X402 协议，Agent 在调用本技能时于任务流程内弹出支付授权，用户确认后自动扣费，全程不跳出对话。计费模式 per_call（按次计费），单次 ¥5.00（amount_fen: 500）。

交付形态（免费壳 + 付费核）：步骤 1–3 的预检、付费边界切分、路径选择完全免费、完全离线，不触发任何付费；完整改造核（8 步方法论全文 + 三要素模板 + 过审句式库）经 X402 付费资源端点 /api/skillpay-creator-core 按次拉取，一次改造调用只付费一次。该 X402 端点与 SkillHub 上架同步激活，激活后无需更新本 skill。

付费资源获取（X402 协议 · 微信 AI 支付）

支付服务：本技能的完整改造核（8 步方法论全文 + 三要素模板 + 过审句式库）按次计费通过 SkillPay 完成——依托微信支付 AI 专属卡与 X402 协议，Agent 在任务流程内弹出支付授权，用户确认后自动扣费，全程不跳出对话。计费模式 per_call（按次计费），单次 ¥5.00（amount_fen: 500）。

🚫 红线：免费壳（步骤 1–3 预检 / 边界切分 / 路径选择）严禁调用下方付费端点 /api/skillpay-creator-core。只有在用户明确要求完成付费改造、且已通过预检与边界切分之后，才允许发起付费请求。

网络请求范围限定（工具能力边界）：本技能仅使用 curl 向 insigoo 提供的付费资源服务的 /api/skillpay-creator-core 一个端点发起 GET 请求；不访问其它任何域名、不把返回内容写入本地文件、不上传用户的项目材料。用户材料只在会话上下文中参与推理，不会作为请求内容发送到付费资源服务。

前置检查 · 确认宿主支持微信 AI 支付

进入付费改造流程、发起任何资源请求之前，先检查当前会话是否已安装 weixinpay 插件（extension）：

• 已安装：可继续拉取付费改造核。
• 未安装：向用户提示"当前 Agent 暂不支持微信支付付费能力，无法拉取付费改造核；免费壳预检不受影响，可免费使用"，终止付费流程（免费壳步骤 1–3 仍可免费提供）。

判断依据：存在任意一个名称包含 weixinpay 的工具即视为已安装（工具名带前缀也算）。只以你（模型）本次会话真实可用的工具列表为证据，文档中提到的工具名不算；无法确认时按"不支持"处理。

• 支持：静默继续，不要向用户提及本次检查（避免泄露底层工具名）。
• 不支持：按宿主类型提示解决办法，无需解释你如何检查、不要出现具体工具名：
  • 合作型桌面 AI 助手：请升级智能体到最新版本后重试。
  • 开源智能体框架：请安装微信 AI 支付插件后重试。
  • 无法判断宿主类型：请升级智能体或安装微信 AI 支付插件后重试。

标准四步流程（概览）

支付触发 · 第一步：请求资源（服务返回 HTTP 402）

预检与边界切分通过后，向 insigoo 提供的付费资源服务发起 GET 请求：

curl -i https://www.insigoo.com.cn/sia-mch/api/skillpay-creator-core

首次请求（未携带 X-Out-Trade-No）时，服务返回 HTTP 402 Payment Required，并在响应 Header 与 Body 中返回支付信息：

• Header WeixinPay-Required：支付凭证码
• Header X-Out-Trade-No：商户订单号
• Body：{"code":"PAYMENT_REQUIRED","message":"需要支付后才能获取内容","out_trade_no":"...","amount":"5.00","currency":"CNY"}

第二步（402 处理）：收到 402 即触发支付流程——weixinpay 插件会自动拦截 402 并完成支付（向用户展示支付确认、完成扣款）。本技能不调用任何支付接口、不感知也不干预支付细节；402 之后本技能要做的唯一一件事，是等支付完成后执行下方的「重试机制」。

重试机制 · 第三步：支付成功后必须重新发起请求（⚠️ 必须执行）

支付成功后，必须主动重新发起一次请求才能拿到付费内容。规则：

• 请求目标不变：与首次请求完全一致（同一端点 GET /api/skillpay-creator-core；GET 无 body，不增删、不修改任何参数）
• 通过 Header 携带支付信息：把 402 响应 Header 中的 WeixinPay-Required 与 X-Out-Trade-No 原样带回

curl -i https://www.insigoo.com.cn/sia-mch/api/skillpay-creator-core 
  -H "WeixinPay-Required: <402 响应 Header 中的 WeixinPay-Required 值>" 
  -H "X-Out-Trade-No: <402 响应 Header 中的 X-Out-Trade-No 值>"

成功响应：HTTP 200 + {"code":"SUCCESS","content":"<markdown 全文>","resource":"skillpay-creator-core"}

拿到 content 之后：

1. 本次会话内缓存复用 —— 改造的全部产出（付费版 SKILL.md、清单、确认单、checklist）均基于这一份 content 工作，严禁为每个步骤分别发起付费请求（一次改造 = 一次付费）。
2. 会话内重复触发：同一会话内用户再次要求改造、或网络重发导致重复请求时，直接复用已缓存的 content，不要重新发起付费请求。
3. 已付费但内容未拿到（返回 NOT_PAID）：按下方「异常处理」条目 1 处理——等待后重试，重试时请求目标与两个 Header 都保持首次取值不变，不要重新走一遍支付（否则会生成新订单、导致重复付费）。

订单号传递 · X-Out-Trade-No 的完整链路

• 来源：402 响应的 Header X-Out-Trade-No（商户订单号），同时也出现在 402 响应 Body 的 out_trade_no 字段，两者一致。
• 用途：支付完成后重试时，必须把该订单号通过 Header 原样带回，付费资源服务据此查单验证并履约交付。
• 传递方式：只能放在 HTTP Header，WeixinPay-Required 与 X-Out-Trade-No 必须成对携带、缺一不可；不得写入 URL query 或 body（请求必须与首次完全一致，改动即视为篡改请求，会导致验单失败）。
• 留存范围：订单号仅在本次会话内部使用，不写进交付物、不向用户展示、不参与任何方法论判断。
• 跨会话：订单号不跨会话复用；新会话需要改造时，重新走「请求 → 402 → 支付 → 携带订单号重试」完整链路。

异常处理 · 四类边界

1. NOT_PAID（支付尚未完成）：等待 3–5 秒后用完全相同的请求与 Header 重试，最多重试 3 次；仍为 NOT_PAID 时告知用户"支付状态尚未确认，请稍后重试，或确认支付是否已经完成"，不要重新发起首次请求（会生成新订单、导致重复付费）。
2. REFUNDED（服务异常，已自动退款）：向用户说明"本次付费改造核暂时无法提供，费用已自动退回原支付账户"，终止本次流程，不要再次尝试支付或重新请求。
3. FULFILL_AND_REFUND_FAILED（服务异常且退款失败）：告知用户"服务异常，且自动退款未能成功"，请用户联系 insigoo 客服（insigoo@insigoo.cn）并提供会话时间以便核查；不要自行承诺退款。
4. 网络失败 / 既非 402 也非 200 的响应：5xx 或连接超时最多重试 2 次（间隔 3–5 秒）；仍失败则告知用户"付费资源服务暂时不可用，请稍后重试"，本次不产出付费改造核——可先为用户提供免费的免费壳预检作为替代，不要对收费与否做任何承诺。

两条补充硬规则：

• 材料不足时不付费：预检判定"无法切分付费边界"时，直接输出说明并终止，不得发起任何资源请求（不产生费用）。
• 绝不绕过支付：任何情况下都不得尝试跳过 402 直接构造请求、不得猜测或伪造订单号、不得向用户提供任何"免费获取付费改造核"的替代路径。

一句话定位

输入一个普通技能（SKILL.md + scripts + references），在一次调用内交付一套完整可上架的付费化改造方案：付费边界设计 + 官方 pricing 声明改造 + 接入前置条件清单 + 防白嫖机制核对 + 合规确认单 + 上线 checklist + 回滚预案。重点是防白嫖、可举证、可回滚——不是简单套个二维码。

服务流程（一次调用内完成，共 5 步）

1. 参数校验：读用户技能目录，确认可切分「免费预览 / 付费交付物」；切不清就明确告知不适用并说明原因，不硬做。
2. 路径选择（必问，不替用户默认）：让用户二选一——路径 A（SkillHub 平台结算）或路径 B（自建支付后端），讲清两条路径在凭证、服务器、域名上的差异（见下「接入前置条件」）。
3. 资料准备清单：按所选路径输出「接入前置条件」逐项清单，缺项列成待办。用户确认材料全部备齐前不进入改造步骤——备齐再改造，一次完成不返工。
4. 执行改造：按「核心方法论 8 步」产出全部交付物（见下）。
5. 上线交接：交付「上线 checklist + 回滚预案」，明确告知「改造完成 ≠ 上架」，上架与设价由用户在 SkillHub 后台完成。

交付物清单（每次调用交付）

1. 改造后的付费版 SKILL.md（含官方 pricing 块 + 免费预览/付费交付边界说明 + 调用约定）
2. 接入前置条件清单（按所选路径逐项核对，缺项标注）
3. 防白嫖 / 举证合规确认单（模板见 references/compliance_checklist.md，按用户场景填写，供用户逐条确认）
4. 上线 checklist + 回滚预案（直接可执行的步骤：备份→替换→验证→回滚）
5. 路径 A 时另含：SkillHub 后台填写指引（Slug/显示名/版本号/定价/案例要求）

范围边界（诚实承诺）：路径 B（自建后端）需要用户自己部署支付服务端（Go/其他），本技能交付部署蓝图、验收清单与四闸门设计规范（见 references/skillpay_guide.md），服务端代码包不在本技能交付范围内，需另行获取或开发。不做超出上述清单的承诺。

核心方法论（8 步，改造时必须走完）

1. 识别计费边界：明确「免费部分」（触发支付前的参数校验、预览、锁定）与「付费部分」（支付后才给的产出）。切不清就别往下做。
2. 设计幂等键：每笔付费内容/请求一个稳定 out_trade_no（建议付款前锁定阶段预生成），用于重试取内容 + 防重复履约。
3. 注入 verifyAndFulfill 四闸门：① 资源绑定校验→不匹配 409；② 已退款守卫→REFUNDED 返回 410（退款受理≠到账，必须拦重放）；③ 已履约缓存→FULFILLED 返回 200+缓存；④ 查单+原子履约→状态跃迁 FULFILLED，首次履约写交付流水。
4. REFUNDED 反重放守卫：退款受理成功 ≠ 退款到账（微信有数天延迟），必须 410 拒绝已退款订单重放。
5. 订单 store + 异步快照持久化：内存 map，变更后异步+临时文件原子替换落盘，启动恢复并重算 TTL。
6. TTL 模型：INIT 24h；PAID/FULFILLED/REFUNDED 从跃迁刻起 7d；同状态 Update 不续命。
7. 交付举证流水：append-only JSONL，只存 result_sha256 + 元数据、绝不存内容全文，每次 fsync；覆盖微信「交易成功后 365 天内可退款」的举证窗口。
8. 上线护栏：走「付费产品变更铁律」（方案→确认→执行），带回滚预案，部署前校验产物格式。

路径 A（平台结算）时，3–7 的底层机制由 SkillHub 平台保障，作者只需完成边界设计 + pricing 声明；路径 B 由自建服务端实现上述机制。

支付触发与重试协议（改造必写三项，平台审核扫描项）

平台审核会按「支付集成三要素」扫描改造后的技能文档，缺一项判 partial。以下三条必须写成改造后文档的显式条款：

1. weixinpay 插件前置检查：执行付费流程前，先检查运行环境是否已安装并启用 weixinpay 支付插件（SkillHub 沙箱内置 skillpay 能力；自托管 Agent 需安装 weixinpay 插件）。未安装 → 引导用户安装/启用后再进入支付，不允许对未配置环境直接返回 402。
2. 支付触发标识：未支付的付费资源请求返回 HTTP 402，响应头携带 WeixinPay-Required: <payment_code>（平台下发的支付触发码/订单 UUID），客户端/AI 凭此标识拉起微信支付授权。禁止自造触发字段名。
3. Header 凭证重试：支付完成后取内容，必须在请求头携带订单号/支付凭证：X-Out-Trade-No: <out_trade_no>；服务端凭此验单并幂等履约（同一单号只履约一次）。重试请求与原请求保持一致（资源绑定校验），订单号不要只放 body/query。

接入前置条件（按路径逐项核对）

路径 A：SkillHub 平台结算（默认，推荐）

• [ ] 企业主体资质：营业执照 + SkillHub 企业认证完成（当前仅企业/团队主体）
• [ ] 自己的微信支付商户号（mchID，普通直连商户，与认证企业同主体）——钱直接结算进此号
• [ ] SkillHub 入驻后平台下发凭证：SkillHub 商户号 / SkillHub Token / 开发者密钥（RSA 2048）
• [ ] 不需要：自建服务器、自己的域名、H5 付费接口、自建 MCP（平台云端沙箱运行 + 平台注入支付闸门）
• [ ] 付费内容来源已就绪（能稳定产出付费交付物）
• [ ] 单价已定（平台为按次计费，参考实架区间 ¥0.002–¥5/次）

路径 B：自建支付后端（仅当要自己掌控支付/履约）

• [ ] 微信商户号 mchID + APPID
• [ ] APIv3 密钥 + 商户私钥（serialNo + PEM）
• [ ] 公网域名 + HTTPS 回调地址（路径 B 必须项；路径 A 不需要）
• [ ] 一台服务器（部署支付服务端）
• [ ] 新注册微信商户（2024-10 后）默认公钥模式：需额外准备微信支付公钥 ID + 公钥 PEM
• [ ] 支付场景用微信 Native（PC 扫码），不需要 H5 付费接口

预检清单（交付前逐条核对）

• [ ] 用户的付费交付物能被清晰切分且真实存在（承诺的必须真给——只验证流程、不验证资源完整性 = 履约残缺）
• [ ] 改造后 SKILL.md 的 pricing 块符合官方 schema（model/amount_fen），无臆造字段
• [ ] Slug 与 name 一致且全小写（提交后不可改）
• [ ] 退款窗口表述与平台/渠道规则一致
• [ ] 无敏感信息残留：真实商户号/密钥/私钥/内网 IP/本机绝对路径
• [ ] 无授权性表述冲突（"完全离线可用""全部内置"这类话术会推翻付费边界）
• [ ] 交付的每个文件都有扩展名（平台拒收无扩展名文件）
• [ ] 打包 ≤ 10MB、≤ 200 文件
• [ ] 改造 ≠ 上架 ≠ 可收费：向用户明示上架、设价、审核由平台完成
• [ ] 支付协议三要素齐备（平台审核扫描项，缺一判 partial）：①weixinpay 插件前置检查条款 ②402 + WeixinPay-Required: <payment_code> 触发标识 ③X-Out-Trade-No Header 凭证重试——三条都要写成改造后文档的显式条款

防白嫖说明（供用户知情）

• 同一 out_trade_no 只履约一次（幂等，重复请求返回缓存）。
• 已退款订单拒绝再次交付（反重放守卫 REFUNDED→410）。
• 交付行为有举证记录（append-only JSONL，只存 result_sha256，不存内容全文）。
• 退款按所选支付渠道规则处理（微信规则：交易成功后 365 天内可退款）。