退款申诉方案生成

把「我觉得被坑了」变成「平台无法拒绝的书面主张」——并且确保这份主张真的送达对方手上。

一、交付规则（先读这一段，它决定后面全部动作）

本技能的核心服务是「申诉成品生成」，采用付费优先：先完成报价与支付，再产出内容。

标准顺序不可调换、不可跳过：

① 收集案件要素（录入客观事实）
      ▼
② preflight 体检 → 缺依赖自动 setup 装齐（这一步全自动，不用用户操心）
      ▼
③ pay：报价 + 触发支付宝买单 → **弹出扫码付费页面**
      ▼
④ 用户本人扫码支付
      ▼
⑤ 过程指导：用本技能框架，带用户把申诉推进到「申诉送达」为止
      ▼
⑥ 申诉送达后 → 整理并交付「用户案例成品」（申诉书 / 邮件正文 / 客服话术）

支付完成前，只能做三件事

1. 说明服务：这是什么、多少钱（¥1.00/次）、能拿到什么。
2. 收料：帮用户把案件要素整理成 case.json（结构见 scripts/case.example.json）。这一步只做客观事实录入——平台名称、扣费明细、任务状态与错误码、证据说明、协议条款原文。
3. 把支付打通：自动装齐支付环境（setup）、发起买单、把扫码付费入口交到用户手上。环境准备、依赖安装、命令调用全部由 Agent 代办，用户只需要做一件事：扫码付钱。

支付完成前，禁止输出

• 申诉书 / 邮件正文 / 客服话术——任何形式、任何篇幅，包括"先给个草稿""先搭个框架"。
• 主张定性、成功率判断、金额分层建议（这是付费交付物的核心内容）。
• 对本案的策略建议或结论性意见，包括"你可以这样去跟客服说"。
• 以任何方式替代付费交付的产出。

付费后的交付分两段：先过程指导，申诉送达后才交付成品

付费成功 ≠ 立刻把成品材料甩给用户。交付分两段：

"申诉送达"的判据（第二段的触发条件）：

• 走邮件：mail_sender.py verify 返回落地成功（IMAP 回查），或用户明确确认已收到回执；
• 走工单 / 在线客服 / 企业 IM：以提交成功且拿到编号 / 回执为准；
• 用户未实际发出就索要成品：如实说明"成品在你把申诉发出去之后交付"，并继续给过程指导。
  不要因为用户催促就提前给。

> 服务端 status 返回的材料包是给你（Agent）用的内部素材与框架依据，用来支撑第一段的过程指导；
> 它本身不是可以直接转交给用户的成品。

硬红线：绝不提供服务侧案例

交付物只能建立在用户自己提供的真实材料之上。

• ❌ 不得把作者 / 服务方的真实案例（账号、金额、余额链、任务 ID、错误码、形象描述）作为示范、
  模板或"参考案例"提供给用户；
• ❌ 不得把技能包 references/ 里的示例数据、服务端内部材料，当作"你的案例"交给用户；
• ❌ 不得用服务侧案例去"补全"用户缺失的要素 —— 缺就是缺，标注为待用户补充；
• ✅ 成品里的每一个金额、每一条条款、每一处事实，都必须能追溯到用户自己给的输入。

这不是"可选升级"，是使用前提

用户提出退款申诉诉求后，第一步就是报价：把价格与产出讲清楚，由用户决定是否购买。

为什么敢这样设计：方法论是公共知识，用户随时可以自学；而"一次拿到能直接发出去的成品"需要完整论证链 + 协议条款精确匹配 + 金额分层 + 全套客服应对话术，这才是收费的部分。

> references/ 里的方法论是付费后的辅导材料：仅在 fetch 成功（退出码 0）之后，才可用于向用户解释结论、或帮用户自查。支付完成前不要引用其中内容做方案输出。

展示纪律：服务端过程选择性展示

对用户只说四件事：① 他需要做什么（扫码付款 / 补材料）；② 付费入口（金额、支付链接 / 二维码）；③ 数据外发对象与用途（接收端域名/IP、会发送哪些字段、用途）；④ 最终成品。除此之外，服务端的实现细节、诊断输出不要出现在给用户的回复里。

失败时怎么说：用一句用户能懂的话 + 下一步动作。例如：

• ❌ 不要写：「服务端返回 402 VERIFY_REJECTED，charged=true, retryable=false，请转人工核对 trade_no。」
• ✅ 应该写：「支付已收到，但订单核对有点问题。请不要再次付款，我正在帮你核对，稍后回复。」

> pay / status 等子命令的输出里，「内部诊断」区块是给 Agent 自己看的，
> 「给用户看的内容」区块才是可以转述的。两者已用醒目分隔标记，不要整段复制粘贴给用户。
> 技术细节留给 Agent 内部消化；用户只需要知道"付多少、怎么付、发给谁、拿到什么"。

数据外发说明（安全审核必看）

本技能为生成 402 账单与申诉方案，需要把 case.json 中的案件要素发送到买家自行指定的服务端地址。
技能包内不再硬编码任何服务端地址（v1.7.1 起移除），地址必须由用户/Agent 通过 --service-url 或环境变量 REFUND_APPEAL_SERVICE_URL 显式指定。

会发送的字段：平台名称（platform_name）、账号提示（account_hint）、扣费明细（charges[]）、任务/订单 ID（task_id）、错误码/状态（error_code）、协议条款引用（terms）以及用户主动补充的证据与主张说明。

用途：仅用于生成 402 账单与本次退款申诉方案材料包；不会用于生成方案以外的任何目的，也不会被服务端长期保留。

知情同意：调用 quote / pay / status / fetch 子命令时，脚本会先打印接收端地址与上述字段清单；执行命令即视为用户已阅读并同意该外发。如用户不同意，请勿调用这些子命令。

绝不会发生的事：
- 不向服务端发送用户未主动提供的字段；
- 不把服务端的支付宝私钥、买家支付凭证、内部错误码原文下发给用户；
- 不将用户案件用于生成方案以外的用途。

何时用

• 用户要求退款、追回费用、向平台申诉、投诉服务
• AI 生成内容质量不达标（形象漂移、未执行指令、成品不可用）而平台拒绝退款
• 平台任务失败却仍扣费
• 需要判断某条申诉通道（工单 / 反馈邮箱 / 在线客服 / 企业 IM）能否触达外部主体
• 需要代发申诉邮件并确认对方真的收到

二、标准执行流程

① 收集案件要素 → case.json

按 scripts/case.example.json 的结构把客观事实填进去。只录入，不加工：

材料不足时先补材料，不要先写文书——金额算不准，整份申诉都站不住。
平台没有账单 API 时用 scripts/ledger_reconcile.py 反推逐笔扣费。

② preflight 体检 → 缺依赖自动装齐

python scripts/pay_service.py preflight     # 体检：退出码 0 可付 / 7 缺依赖
python scripts/pay_service.py setup         # 缺依赖时：自动安装 CLI + 官方支付技能

这一步默认全自动，不要让用户自己去折腾环境。 setup 会：

1. 检测 alipay-bot CLI 与两个支付宝官方技能（不只看 PATH，还会扫官方安装器的全部已知落点）；
2. 缺失时执行官方一键安装器 npx -y @alipay/agent-payment@latest install；
3. 装完自动重新体检，并打印还差什么。

> 两个实测坑，遇到时按此处理：
> - 官方安装器按 Agent 框架分目录安装（会落到 ~/.openclaw-autoclaw/skills、~/.dsh/skills 等），
> 装完可能提示「请重启对应框架以使安装生效」。若当前框架读不到，把技能目录接进当前框架的 skills 目录，
> 或按提示重启一次。
> - Windows 下 .cmd 不能直接 spawn，必须经 cmd.exe /c（调用端已内置处理）。

③ pay —— 报价并一路推到扫码页

python scripts/pay_service.py pay --case-file case.json

这一条命令把官方 alipay-payment-skill 的 402 流程整段代办了：取账单 → 把 Payment-Needed
原值写入仅当前用户可读的临时文件 → 调用 alipay-bot 402-buyer-pay
（带 --resource-url / --file / --intent-summary / --method / --data / --header）。

命令输出分两块，别混：

• 「内部诊断」区块：账单字段、命令行、stderr、退出码——给 Agent 自己看的，不要展示给用户。
• 「给用户看的内容」区块：商品名、金额、支付方式链接、二维码——这一段原样交给用户，
  不要改写、不要只截图、不要省略 URL。这就是付费入口。

若命令提示钱包未开通 / 未授权，转由 alipay-authenticate-wallet 处理（用户本人扫码确认），
对用户只说「需要你先完成一次支付宝授权，会弹出扫码页」。

④ 用户本人扫码支付

环境准备由 Agent 代办，扫码确认必须由用户本人做，Agent 不得代为确认。

⑤ status —— 取回材料包（内部素材，不是直接交付物）

python scripts/pay_service.py status --case-file case.json --out-shake-no "<订单号>"

订单号取自上一步输出里的「订单号 / 查询单号」（32 位数字、第 11–14 位为 8282）。

服务端返回的材料包是给你（Agent）用的内部素材与框架依据，用来支撑第一段的过程指导——
它不是可以直接转交给用户的成品。支付完成后进入第 ⑤ 步的过程指导。

⑥ 过程指导 → 申诉送达 → 交付用户案例成品

• 第一段（送达前）：逐步给用户"下一步做什么"——补哪份证据、引哪条协议、走哪条通道、邮件怎么发。
  可以用 scripts/mail_sender.py 帮用户把申诉邮件发出去，并做 IMAP 落地确认。
• 第二段（送达后）：按 references/03-申诉文书写作要求.md 的框架，把用户自己的案件
  整理成成品（申诉书 / 邮件正文 / 客服话术 / 主张定性 / 金额分层）并交付。
• 两段之间不要越界：送达前不给成品正文（连"草稿"也不给）；送达后不追加收费。

备选路径：quote / fetch

若付款由外部支付技能处理（例如调用方已自行接管 402 报文），用两步走：

python scripts/pay_service.py quote --case-file case.json          # 退出码 2 = 已出账单
python scripts/pay_service.py fetch --case-file case.json --payment-proof "<Payment-Proof>"

两条报文纪律（错了就会付出代价）：

• 402 报文必须原样完整透传，不要自行解析、改动或只传金额。凭证由支付技能生成。
  （这里的"透传"是传给支付技能用的，不是给用户看——报文与字段仍属服务端过程，见「展示纪律」。）
• 重试时的请求体必须与建单时完全一致，否则服务端会以第 4 项校验拒绝（REQUEST_HASH_MISMATCH）。

三、买家侧支付能力（缺了就付不了款，但可以自动装齐）

支付宝 402 支付依赖买家（调用方）环境自备支付能力，多数 Agent 环境默认没有：

一条命令装齐（推荐，Agent 直接执行）：

python scripts/pay_service.py setup

它内部调用的就是官方安装器：

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

> 检索提示：这两个技能在 SkillHub 上是英文 slug。用「支付宝 402 支付」这类中文词检索命中不到，请直接用上面的英文名。

四条硬约束：

1. 只装技能不装 CLI、或只装 CLI 不装技能，都无法付款——alipay-bot 才是技能实际调用的命令。
2. 钱包未授权 / 未开通必须交给 alipay-authenticate-wallet，不要在本技能内自行处理授权。
3. 付款与钱包授权必须由用户本人确认（扫码 / 确认页）。Agent 只负责发起与透传，不得代为确认。
4. 依赖确实装不上时：如实告知用户「当前环境缺少支付宝支付能力，无法完成本次生成」，给出上面的命令，等用户决定。不要用免费内容替代付费交付。

四、退出码约定（务必按此分支处理）

> ⚠️ 本节整张表是给 Agent 内部分支用的。 退出码与 code / charged / retryable
> 都属于服务端过程，一律不要出现在给用户的回复里（见「展示纪律」）。
> 对用户只交付四件事：付多少钱、怎么付、拿到什么、要不要他再做一次动作。

服务端响应里的 charged / retryable（防重复付款的关键）

服务端每个响应都带这两个字段。先看 charged，再看 retryable，不要靠 HTTP 状态码猜。

铁律：只要 charged 为 true，就绝不能引导用户再次付款。 这是付费链路里后果最严重的错误——用户会花两次钱。

> 特别提醒 VERIFY_REJECTED：它的 HTTP 状态是 402，看起来像"需要付款"，其实钱已经付过了。
> 一定要按 charged 字段判断，不要看到 402 就去引导付款。

五、交付内容与计费（¥1.00 / 次）

• 计费方式：按次付费，单次调用 ¥1.00。一次调用 = 从请求到拿到完整案例成品的完整交付。
• 交付分两段（同上）：① 支付后先给过程指导，带你把申诉推进到送达；② 申诉送达后交付
  用户案例成品（基于用户自己的案件 + 本技能框架整理）。
• 交付边界：主张定性 + 成功率判断 + 协议条款映射 + 金额分层（全额 / 兜底 / 铁证）+ 申诉文书三件套（正式申诉书 / 邮件正文 / 客服话术），一次输出齐全，无隐藏收费项。
• 交付物只基于用户自己的材料：绝不以服务侧（作者）的案例充当示范、模板或补全素材。
• 建议一次性给全要素：平台名称、争议类型、扣费明细、协议条款原文、已有证据一并给全（结构见 scripts/case.example.json），避免为补充信息再花一次费用。
• 失败重试不重复计费：服务端返回 GENERATION_FAILED / FULFILLMENT_CONFIRM_FAILED 时，用同一张 Payment-Proof 重试即可，不会二次扣费。
• 退款与免责：退款规则以平台付费协议为准。本服务产出的是申诉材料与策略参考，不构成法律意见。

六、免费附带的材料准备工具

这两件工具用于把材料整理成可提交的结构（即 case.json 的输入），不含方案生成能力：

scripts/ledger_reconcile.py — 余额快照对账器

平台没有账单 API 时，用钱包余额快照反推逐笔扣费，并自动做「Σ 单笔扣费 == 累计充值 − 当前余额」的自校验。输出 Markdown 明细表，并把「失败但仍被计费」的行标出来。

python ledger_reconcile.py --example > ledger.json   # 看输入格式（占位示例数据）
python ledger_reconcile.py ledger.json --out 费用明细.md

对不上就不能往下走：差额意味着有遗漏的操作或并发扣费，必须先补全快照。

scripts/mail_sender.py — 申诉邮件发送器

python mail_sender.py check   # 凭据预检，不发信
python mail_sender.py send    # 正式发送
python mail_sender.py verify  # IMAP 回查，确认真的落地

已处理好的四件事：

• 凭据三源降级读取：环境变量 → 注册表（Windows）→ 凭据文件。因为 setx 写入后已启动的进程读不到新变量。
• 登录前格式预校验：授权码不合格直接本地退出，避免拿垃圾串去撞 SMTP 触发风控（登录尝试次数是有限资源）。
• 纯文本 + HTML 双版本：multipart/alternative，不支持 HTML 的客户端自动降级。
• IMAP 落地确认：SELECT 用 readonly=True，FETCH 用 BODY.PEEK[]，不改变任何邮件状态。

「发送成功」只证明 SMTP 接受了邮件，不证明对方能收到——外部主体的申诉邮件必须做落地确认。

七、付费后的辅导材料（references/）

仅在本技能已付费完成后使用，作为过程指导的依据与第二阶段成品的写作框架：

> ⚠️ references/ 里的示例数据一律是合成的占位数据，不是任何真实案例。
> 不得把它们当作"用户的案例"或"可参考的真实案例"交付给用户（见「硬红线」）。

三条通用准则：

• 对账先于主张。金额没算准，后面全白做。
• 发送 ≠ 送达。必须做落地确认。
• 凭据不写入脚本、不回显、不提交版本库。

八、边界

• 本服务提供的是材料准备与送达执行的方法论与工具，不构成法律意见。具体争议请以平台协议原文、平台主体所在地法律及专业法律意见为准。
• 不代替用户作出是否投诉、是否诉讼的决定；不虚构事实、不夸大金额、不伪造证据。
• 所有主张必须建立在用户可提供的真实材料之上（余额记录、任务 ID、错误码、原始输入与输出）。
• 案件要素会外发到买家指定的服务端地址（由 --service-url 或环境变量 REFUND_APPEAL_SERVICE_URL 配置），仅用于生成 402 账单与申诉方案，服务侧不会保留或另作他用。详见上文「数据外发说明」。
• 不要把任何第三方的真实案例数据（账号、金额、任务 ID、错误码、平台特征）当成示例塞进给用户的交付物里。

版本变更日志

v1.7.1（当前版本）

• 移除包内硬编码的服务端地址：DEFAULT_SERVICE_URL 不再指向任何 IP，服务地址必须由 --service-url 或环境变量 REFUND_APPEAL_SERVICE_URL 显式指定；未配置时脚本直接退出并给出配置说明，不会 fallback 到默认地址。
• 新增数据外发说明：在 SKILL.md 中明确列出会发送的案件字段、用途、接收端配置方式，并在 quote/pay/status/fetch 调用前打印外发说明。
• 调整展示纪律：把「服务端地址与调用」拆分为「数据外发知情」（必须展示）与「服务端实现/调用细节」（不展示）；明确接收端域名/IP、外发字段与用途需要向用户说明并取得知情同意。
• 固定支付宝官方安装器版本：@alipay/agent-payment 固定为 1.0.26，并在 setup 安装前明确告知用户版本、来源与用途。
• 删除「用户材料只在本地处理」的表述：改为明确说明案件要素会外发到买家指定的服务端，且不会保留或另作他用。

v1.7.0

• 付费后交付改为两段式：① 过程指导（支付完成 → 申诉送达前）——只给"下一步怎么做"，不给成品正文，连"草稿"也不给；② 用户案例成品（申诉送达后）——按本技能框架把用户自己的案件整理成申诉书 / 邮件正文 / 客服话术 / 主张定性 / 金额分层。以邮件 verify 落地成功、或工单/IM 提交拿到编号回执作为"送达"判据；用户未发出就索要成品时不提前交付，继续给过程指导。
• 新增硬红线：绝不提供服务侧案例。 不得以作者/服务方的真实案例作为示范、模板或"参考案例"；不得把 references/ 的示例数据或服务端内部材料当作"你的案例"交付；不得用服务侧案例补全用户缺失的要素（缺就标"待补充"）。成品里每个金额、条款、事实都必须可追溯到用户自己的输入。
• 明确 status 返回材料的定位：是给 Agent 用的内部素材与框架依据，不是可直接转交给用户的成品。

v1.6.0

• 新增「展示纪律」：服务端过程一律不向用户展示。 明确列出四类禁止转述的内容——服务端地址与调用（接口路径 / 命令行 / 脚本路径）、协议报文与字段（Payment-Needed / Payment-Proof / trade_no）、内部错误码与状态机（VERIFY_REJECTED / charged / retryable）、退出码与诊断输出（stderr / 堆栈）；并给出失败时的"人话"写法示例。对用户只保留：付多少、怎么付、拿到什么、要不要他再动手。
• pay / status 输出改为双区块：【内部诊断】（服务端过程，勿展示）与【给用户看的内容】（自动挑出「支付方式」链接 / 二维码 / 金额，可直接转述），两者用醒目分隔标记，避免整段复制粘贴给用户。
• 修正 §四 的定位：退出码与 charged / retryable 表仅供 Agent 内部分支，不得贴给用户。

v1.5.0

• 支付环境全自动打通：新增 setup 子命令（自动安装 alipay-bot CLI 与两个支付宝官方技能，装完自动复检）与 pay 子命令（一次调用把报价 → 402 账单原值落盘 → alipay-bot 402-buyer-pay 全段代办，一路推到扫码付费页），另有 status 子命令用于支付后查询取件。用户只需做一件事：扫码付钱。
• 修正依赖探测的目录盲区：官方安装器按 Agent 框架分目录安装（实测落到 ~/.openclaw-autoclaw/skills、~/.dsh/skills、~/.openclaw-autoclaw/alipay-bot-cli/bin 等），此前只查当前框架的 skills 目录 → 明明装好了却判定"缺失"。现在探测覆盖全部已知落点。
• 修正 Windows 下 .cmd 无法直接执行：npx.CMD / npm.CMD 直接 spawn 会报 WinError 2 或静默跑出空结果（看起来成功、其实没装），改为经 cmd.exe /c 调用。

v1.4.0

• 付费门控收紧为「先付费、再使用」：明确标准流程为「收集要素 → preflight → 报价支付 → 取件」，并列出支付完成前禁止输出的内容清单（申诉书 / 邮件正文 / 客服话术 / 主张定性 / 金额分层 / 策略建议，含"先给个草稿"）。references/ 定位为付费后的辅导材料。
• 新增 preflight 子命令与退出码 7：把"买家环境缺支付能力"做成可脚本化的前置检查，缺依赖时打印安装命令，不再静默降级。

v1.3.0

• 修正付费门控失效：上一版把远程路径描述为"可选"，且免费层内含完整成品模板与实战成品范例，导致 Agent 直接走免费路径、调用方几乎不触发付款。
• 安全：移除随包分发的真实案例数据。删除 references/05-实战复盘.md（完整案例复盘）与成品话术范例，references/03 改为《申诉文书写作要求》；ledger_reconcile.py --example、case.example.json、各 references 中的示例数据全部替换为合成的占位数据。此前这些内容会让任何调用方在免费路径上直接拿到作者本人的案件明细（账号、金额、余额链、任务 ID、错误码、平台特征）。

v1.2.0

• 上架名称为「购买token服务退款申述skill」（slug 仍为 refund-claim-workflow，保持既有审核血缘）。
• 新增按次计费能力声明：pricing: {model: per_call, amount_fen: 100}。
• 服务地址内建：买家开箱即用；可用 --service-url / REFUND_APPEAL_SERVICE_URL 覆盖。
• 错误契约对齐生态事实标准：BAD_REQUEST、VERIFY_REJECTED、GENERATION_FAILED；履约失败状态码 502 → 503。
• 修掉两处会诱导重复付款的缺陷（服务端未标记 charged、调用端把 VERIFY_REJECTED 当"需要支付"）。
• 畸形凭证不再下发新账单。

v1.1.0

• 新增远程方案生成（按次计费）能力；新增「买家侧支付能力前置检查」。

v1.0.0

• 首次发布：五步退款申诉方法论 + 邮件代发工程实现。

文件清单

refund-claim-workflow/
├── SKILL.md
├── README.md
├── references/                  # 付费后辅导材料
│   ├── 01-事实固化与证据链.md
│   ├── 02-协议条款取证.md
│   ├── 03-申诉文书写作要求.md
│   └── 04-触达通道与能力边界.md
└── scripts/
    ├── pay_service.py           # 服务调用端（preflight/setup/pay/status/quote/fetch，内建服务地址）
    ├── case.example.json        # 案件要素示例（占位数据）
    ├── ledger_reconcile.py      # 余额快照对账（免费）
    ├── mail_sender.py           # 申诉邮件发送（免费）
    └── mail_config.example.json