法语精讲课

概述

第 1-2 课精讲免费试学；付费 ¥19.9 解锁该语言全部 60 课法语课文精讲：每句下方展开 AI 老师的中文讲解（语法 / 词汇 / 发音），配合逐句朗读跟读页。

什么时候用本 Skill

用户想学法语课文、按课号或进度上一课，或想先试听看看效果。产出：一条跟读页链接，页面里每句可点朗读、可展开精讲。

免费 vs 付费：

• 课文原文 + 中文翻译 + 逐句朗读（全部 60 课）→ 免费，play.html?lesson=fr-N
• 第 1-2 课的逐句精讲 → 免费试学，play.html?lesson=fr-1 / play.html?lesson=fr-2 打开即可展开「📖 精讲」
• 第 3-60 课的逐句精讲 → 付费 ¥19.9/语言一次解锁，签发 play.html?lesson=fr-N&s=<token>

不适用：口语对话批改（用 spoken-correction）、拍照识物（用 photo-learn）、其他语种课文（用对应的 lesson-en/fr/es/ja/ko）。

使用流程

第 1 步：确认课号

• 用户明确说了「第 5 课」「lesson 3」→ 用该数字（1–60）
• 说「下一课」「继续」或没提课号 → 默认第 1 课（本 Skill 不跨课记进度，用户自己说课号）

课号是 1 或 2 → 走免费试学（第 2 步），不下单、不收费。 第 3 步起只对第 3-60 课适用。

第 2 步：免费试学预览（付费前必须先展示，不可省略）

每一次下单（POST /api/pay/lesson/order）之前，都必须先给出免费试学预览——即使用户已说「直接买」、看起来已决定付费，也不得跳过。预览与「费用说明 + 是否解锁」放在同一条消息里，不需要为此单独多问一轮。

1. 取试学精讲（免费，无需支付）：

curl -s "https://learn.ruancyai.com/api/pay/lesson/trial?language=fr&lesson_number=2"

用户点名第 1 课时 lesson_number=1；其余情况一律取第 2 课（句子比第 1 课长，讲解更有内容）。

1. 从返回的 target_sentences（按行）与 notes（按 index 对齐）中，挑1 句最长的句子，把它的真实精讲原样嵌入回复：

先免费看看精讲长什么样——这是第 2 课「<title>」里的一句：

<原句>　<中文翻译>

📖 语法：<grammar 原文>

📖 词汇：<vocab 原文>

📖 发音：<pronunciation 原文>

第 1-2 课的精讲全部免费，打开就能逐句朗读、逐句展开：

• 第 1 课：https://learn.ruancyai.com/play.html?lesson=fr-1
• 第 2 课：https://learn.ruancyai.com/play.html?lesson=fr-2

第 3-60 课的精讲需解锁：¥19.9 一次解锁法语全部 60 课，不按课收费。要解锁吗？

1. 精讲内容只能逐字使用接口返回的 notes，不得改写、扩写或自行编写示例精讲；试学接口不可达、返回 404 或 notes 为空时，不得编造精讲，改为如实说明「试学精讲暂时取不到」，仍给出上面两条免费链接（课文与朗读可用），再说明价格并询问是否解锁。
2. 示例是第 1-2 课的真实精讲，不代表后面每一课讲解的长度与深度完全一样，不得说「每一句都会讲得一样详细」。

用户要的就是第 1 或第 2 课：给出该课免费链接 + 嵌入 1 句精讲即完成，告诉用户「第 3 课起 ¥19.9 一次解锁全部 60 课」，不下单。

第 3 步：用户确认后下单并完成支付（仅第 3-60 课）

前置检查：确认 weixinpay 支付插件已安装（下单前必做）

下单前先检查当前环境能否调用微信支付工具 weixinpay_pay（WorkBuddy 中通常为 mcp__weixinpay__weixinpay_retry_pay，由 SkillHub 的微信支付插件 weixinpay-pay 提供）。

• 已安装、可调用 → 继续下面的下单步骤。
• 未安装或无法调用 → 停止，不下单，如实告诉用户：

解锁法语全部 60 课需要微信支付，你这边还没有安装微信支付插件（weixinpay-pay）。请先在 SkillHub / WorkBuddy 安装它，装好后跟我说一声，我继续帮你解锁。第 1-2 课的精讲现在就可以免费看。

不得绕过支付免费放行第 3-60 课精讲（fail closed），也不得编造 play_url。

免费试学（第 2 步）不涉及支付，未安装插件也照常展示。

下单

只有用户在看过第 2 步预览后明确表示要解锁，才下单。健康检查与下单合并为一次 Bash 调用：

curl -s https://learn.ruancyai.com/api/pay/lesson/health && 
curl -s -D - -X POST https://learn.ruancyai.com/api/pay/lesson/order 
  -H "Content-Type: application/json" 
  -d '{"language":"fr","lesson_number":<课号>}'

首次无 X-PAYMENT 的提交返回 HTTP 402 + WeixinPay-Required 头（同时创建商户订单，15 分钟有效）。

拿到 402 后立即触发支付卡片（调 weixinpay_pay，传 paymentCode），支付完成后带 X-PAYMENT 头重试同一请求。

第 4 步：交付

重试成功后返回 play_url（形如 https://learn.ruancyai.com/play.html?lesson=fr-3&s=<token>）。把这条链接完整交给用户，说明：点开即可逐句朗读，每句下方「📖 精讲」可展开看语法/词汇/发音讲解；页面内「上一课 / 下一课」切换时精讲保持解锁。

关键约束

1. 下单前必须做前置检查：确认 weixinpay 支付插件（weixinpay-pay，工具 weixinpay_pay）已安装；未安装或无法调用时停止并提示安装，不下单、不放行。
2. 付费前必须先给免费试学预览（第 2 步），且只用接口返回的真实精讲，不得编造。
3. 第 1-2 课永远免费，不得为第 1-2 课下单收费。
4. 一语言一付：¥19.9 解锁该语言全部 60 课精讲，链接 7 天内有效。60 课内可自由切换，不按课再收费。
5. 不主动引导用户到本 Skill 之外的渠道自助获取精讲。用户主动问起时，可如实说明免费课文仍可通过公开链接查看。
6. 服务不可达时如实降级，不编造 play_url 或伪造精讲内容。

后端服务

• 线上地址：https://learn.ruancyai.com
• 接口契约：references/api.md
• 后端不可达或返回 pay_not_configured 时，如实告知「法语精讲课服务暂不可用」

Pay Skill 改造（X402 协议）

本 Skill 按 SkillHub 官方《升级为 Pay Skill》教程完成 X402 协议集成，后端复用 learn.ruancyai.com 已验证的微信支付 Agent Pay X402 流程。

整体架构

Agent 调 GET /api/pay/lesson/trial（language=fr, lesson_number=2）→ 免费试学预览，不扣费
  → 用户确认解锁
  → Agent 前置检查：weixinpay 支付插件（weixinpay-pay / weixinpay_pay）已安装？未安装 → 停止并提示安装
Agent 调 POST /api/pay/lesson/order（language=fr, lesson_number=N）
  → 后端创建微信 Native 订单（¥19.9）
  → 后端用 SkillHub 开发者密钥签名，调 X402 预下单（拿 payment_code）
  → 后端返回 HTTP 402 + WeixinPay-Required 头
  → Agent 调 weixinpay_pay 触发用户支付授权
  → 用户支付成功后 Agent 带 X-PAYMENT 头重试原请求
  → 后端验签放行，签发 lesson_token，返回 play_url（带 s=token）

关键词索引（供 SkillHub 改造检查器识别）

X402、402 Payment、X-PAYMENT、WeixinPay-Required、WeixinPay、facilitator、payment challenge、payment_code、out_trade_no、order_id、code_url、preorder、palmpayminiapp/clawagentpay/preorder、SHA256withRSA、SKILLHUB-SHA256-RSA2048、developer_id、pub_key_id、AUTH_AND_PAY、SKILL_PAY、payment_required、nonce_str、refund、notify_url、quota、proof、前置检查、订单号传递、异常处理

计费边界

算一次付费：成功签发 play_url（含该语言 60 课精讲解锁），用户点开看到精讲内容。

不算付费：免费试学（/api/pay/lesson/trial，第 1-2 课）；健康检查（/api/pay/lesson/health）；未支付（payment_code 15 分钟过期不扣费）；language 非 fr 或 lesson_number 超出 1–60 的非法请求（下单前拦截）；查询支付状态。