电商用户复购率诊断提升（Pay Skill）

Overview

本 Skill 是接入支付宝「AI 按量付费（A2M）」的 Pay Skill：每次生成复购诊断前，需先向服务端发起资源请求并完成一次按次付费，付费成功后才能交付分析结果。

业务交付链路：

⓪ 免费展示完整样例报告（assets/sample-report.html）→ 让用户先看清交付标准与版式
① 用户提交订单明细（CSV / Excel / JSON / 粘贴文本）
     ↓
② 运行环境就绪检查（command -v node）
③ probe：请求复购诊断接口，服务端返回 HTTP 402 + Payment-Needed 账单
④ 输出付费前预览（数据概览 + 六步分析结构 + 四维评分 + 用途金额），等用户确认
⑤ pay：把账单与原始请求交给支付宝官方 CLI（alipay-bot），用户扫码授权付款
⑥ complete：用同一订单与原请求参数重试，服务端验付通过后返回诊断资源
     ↓
⑦ 渲染 MBB 商务风 HTML 报告 + 导出 Excel 分层名单 + 触达日历 CSV → 交付

> ⓪ 是强制前置：样例报告免费、不收费、不索取任何个人信息；未展示样例报告前不得索取数据、不得推进付费。

服务端负责：生成账单、校验 Payment-Proof、交付资源、发送商家履约确认。本 Skill 负责：发起请求、调用官方支付能力、采集与渲染、展示结果。服务端源码独立部署，不放入本 Skill 包；包内不含任何密钥。

硬规则（Hard Rules，违反即视为交付失败）

以下两条是交付红线，任何情况下不得跳过。它们对应真实运营场景中的高频失误，已固化为强制动作。

HR-1 样例报告免费先于一切

样例报告（assets/sample-report.html）未展示前，不索取订单数据、不执行 probe、不展示任何支付入口。这条与 Step 0 红线一致，此处重复强调。样例为示例数据，真实报告需基于用户订单实算。

HR-2 数据真实性红线（不得编造）

所有 KPI、同期群、间隔、临界点、分层占比、触达日历均须来自用户订单实算。检索/计算不到就如实写「数据不足 / 样本过少」，绝不用示例数据填充（示例数据只出现在 Step 0 的样例报告里）。报告内数字必须全文自洽：整体复购率 = 复购用户/有效用户；四层占比之和 = 100%；分层名单行数 = 四层用户数之和 = 触达日历覆盖用户数。

触发方式：用户口语 → 触发映射（用户不必知道「复购诊断」这个词）

命中以下任一语义即视为触发，直接进入 Step 0（先免费展示完整样例报告），不要反问「你是要做复购诊断吗」：

判定边界：

• 只要用户意图是「诊断复购 / 做用户分层 / 找流失点 / 定触达节奏」，一律触发。
• 用户只是问宏观行业景气度（不涉及自身订单）→ 不触发，转行业景气度类技能。
• 用户已明确给出订单文件时，仍须先展示样例报告（Step 0），之后跳过引导直接进入 Step 3。
• 首次响应不要长篇铺垫：一句话确认「我来给你做一份电商复购率诊断报告」，随即展示完整样例报告，报告后再请求订单数据。

计费信息

运行时配置：服务端地址与单价属于产品配置（不是密钥），已随包固化，开箱即用，无需任何环境变量。

只有在自建服务端 / 做灰度切换时才需要用环境变量覆盖（二者皆可选，缺省即用默认值）：

> 说明：地址与单价必须与支付宝「服务注册」登记的服务地址与单价完全一致（协议 + 域名 + 路径），否则支付验证会失败。默认值即为已过审的登记值，改动前务必同步修改支付宝侧登记信息。密钥（商户私钥、支付宝公钥）不在本包内，也不由本 Skill 读取。

依赖安装（买家侧）

支付能力由支付宝官方 CLI 提供，本 Skill 不自行实现付款或签名。

Agent 应主动完成安装，不要让用户手动敲命令：进入支付环节前若本机没有 CLI，直接执行：

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

• 这是一次性安装：装好后本机所有付费 Skill 共用，不必每次付费都装。
• 脚本自修复兜底：即便 Agent 漏跑上面这条命令，pay / complete 探测不到 alipay-bot 时也会自动执行一次性 npx -y @alipay/agent-payment@latest install 再复探，买家全程无需手动敲命令；仅在 npx 缺失或安装失败时才打印指引并以退出码 1 结束，不抛 Node 报错栈。
• 若因 npx / 网络不可用导致安装失败：把这条命令与失败原因原样告知用户，请其在本机终端执行后重试；不要跳过安装，也不要伪造支付入口。
• 唯一必须由用户本人完成的是支付宝钱包授权绑定（alipay-bot check-wallet）：未绑定时按 CLI 提示，引导用户在支付宝 App 内确认（属人工确认环节，脚本与 Agent 均不代操作）。
• 红线：除「钱包绑定扫码确认」这类必须用户本人确认的环节外，安装与探测类动作一律自动跑，不得把安装提示墙丢给用户。
• 报错人话化：脚本所有失败路径（probe 网络/状态码、pay 钱包与取消、complete 查单、状态文件损坏、未预期异常）统一输出三段式 「❌ 出了什么问题 / 可能原因 / ▶ 下一步怎么做」，并把 curl 退出码、Node 网络错误码、HTTP 状态码、alipay-bot 常见文案翻译成大白话；任何未捕获异常经入口兜底转换，绝不向用户抛 Node 报错栈。Agent 收到报错后：先照输出里的「下一步」逐条执行或转述给用户，无需再翻文档；所有报错均承诺 同一订单幂等重试、不重复扣费。

环境受限降级策略（Environment-Degraded Mode）

当运行环境无法执行付费脚本或无法完成真实付费时启用本策略，目标是把「环境受限」转化为「优雅降级」，而不是失败报错或伪造结果。

触发条件（任一即进入本模式）：
- 运行环境没有 node 运行时（command -v node 为空）→ 无法执行 scripts/repurchase-paid.mjs 的 probe / pay / complete；
- 支付宝官方 CLI alipay-bot 无法安装或不可用（沙箱无网络 / 无 npx）；
- 当前为平台「案例沙箱」等禁止真实付费的受限环境。

降级动作（顺序不可颠倒，严禁伪造真实数据）：
1. 明确告知用户：本环境无法执行付费脚本 / 无法完成真实付费，因此不能产出基于其订单的实时个性化诊断。
2. 展示 assets/sample-report.html 作为交付标准样板，清晰标注「示例数据 · 非你的真实结果」，复用 Step 0 的免费预展口径（不另起炉灶、不重复收费）。
3. 说明完整实时版交付条件：需在具备 Node 运行时的本地 Agent 环境（如 WorkBuddy 桌面端）运行本 Skill，并完成一次 1 元付费（自购自收，款项进入你自己的卖家账户）。
4. 若用户仍想在本环境获得价值，可提供免费、纯咨询、不依赖实时计算的增值：复购方法论解读（同期群/间隔/临界点/RFM 口径）、基于行业基准的对照建议、触达节奏框架。话术：

> 我可以基于样例报告的口径帮你做：复购方法论解读、行业基准对照、触达节奏框架建议——这些不依赖实时计算，属纯咨询性质。需要的话把订单数据发我，我们走免费咨询。

5. 红线：降级模式下严禁把样例报告（示例数据）伪称为用户真实分析结果；严禁编造任何复购率 / 同期群 / 分层 / 临界点；用户要求真实报告时，引导其到本地 Agent 环境运行，不得在本环境硬凑结果。

判定边界：仅当 node 可用且能在本地完成付费时，才走完整 Step 0→7 实时流程；否则一律走本降级策略。

付费调用流程（Payment Flow）

PF-1 触发 402 账单（probe）

node scripts/repurchase-paid.mjs probe \
  --brand '暖芽母婴旗舰店' --orders-file ./orders.json \
  --state-dir '.state/repurchase/<SESSION_KEY>'

• HTTP 200 → 订单已支付且有效，直接进入交付（PF-4）。
• HTTP 402 → 读取 payment-needed 响应头保存账单，进入 PF-1.5。
• 其他状态码 → 原样报错，不重试、不伪造结果。

PF-1.5 付费前预览与确认（强制，不可跳过）

在展示任何支付入口之前，必须先输出完整「预览摘要」并取得用户明确确认。 四块缺一不可：

1. 数据概览：收到订单行数、预计清洗后有效行数、覆盖时间跨度、用户数区间。
2. 六步分析结构清单：Step0 数据体检 → Step1 同期群矩阵 → Step2 间隔双峰 → Step3 生存临界点 → Step4 RFM 四层分层 → Step5 A/B 验证闭环（每步会产出什么）。
3. 四维评分预览：数据完整度 25% / 分析深度 30% / 可执行性 30% / 对标价值 15 各维度口径，以及支付后以服务端权威值为准的综合评分与档位。
4. 用途与金额：本次用途（「〈品牌〉电商复购率诊断」）+ 单次价格（1.00 元）+ 收款方名称。

输出后用提问方式请用户在「确认支付 / 先看更多细节 / 暂不支付」之间选择，并等待用户明确回复。

红线：未输出上述四块预览摘要且未取得明确确认前，禁止执行 pay、禁止展示二维码或支付链接；用户回复任何非明确确认内容一律停在预览状态。

PF-2 推进支付（pay）

node scripts/repurchase-paid.mjs pay --state-dir '.state/repurchase/<SESSION_KEY>' --session-id '<SESSION_KEY>'

脚本只做编排，不接触密钥；付款过程状态与错误按官方 CLI 原样展示。

PF-3 支付凭证重试（Payment-Proof）

付款后复用 PF-1 的原始请求参数与同一订单重试，method / URL / body / 请求头保持一致，不重新下单。

PF-4 服务端验付与结果交付（complete）

服务端调用 alipay.aipay.agent.payment.verify 验付，五项业务校验：active 为 true、amount 等于本次价格、out_trade_no 归属本订单、resource_id 一致、trade_no 未重复履约。任一不通过 → 返回 402，本 Skill 不得交付任何分析结果。

node scripts/repurchase-paid.mjs probe    --brand '暖芽母婴旗舰店' --orders-file ./orders.json --state-dir .state/repurchase/S1
node scripts/repurchase-paid.mjs pay      --state-dir .state/repurchase/S1 --session-id 'S1'
node scripts/repurchase-paid.mjs complete --state-dir .state/repurchase/S1 [--out-shake-no '<单号>' | --trade-no '<单号>']

> 单号：官方「订单号/查询单号」为 32 位纯数字且第 11–14 位为 8282（用 --out-shake-no）；其余用 --trade-no。脚本自动判别并在查不到时换参数重试一次，不会重复下单或重复扣费。

PF-5 订单与幂等

同一会话（--state-dir）复用同一订单与原始请求；履约确认失败时重试同一订单，不要求用户重新付款，也不因回执失败扣留已付费结果。状态文件仅落在 --state-dir，不得写入密钥 / .env / node_modules 到 Skill 包。

工作流程（按顺序执行）

Step 0 免费展示完整样例报告（强制前置，先于一切信息采集与收费）

触发后的第一个动作就是展示样例报告，让用户先看清「花 1 元买到的是什么」，再谈数据采集与付款。

执行方式：

# 直接用文件展示工具打开包内样例报告（完整六步结构、示例数据、真实版式）
# 路径：assets/sample-report.html

展示时按下面这段话说（不要长篇铺垫）：

> 先给你看一份免费样例报告（示例数据，非你的真实结果）——这就是付费后会拿到的交付标准的版式骨架。付费 1 元后，系统按你的订单明细实时跑六步诊断，生成专属报告 + Excel 分层名单 + 触达日历 CSV。

• 样例报告（assets/sample-report.html）须与 assets/report-template.html 同源同版式：六步模块框架齐全、占位符残留为 0。可点开即视为自检通过。
• 说明清楚：样例为示例数据，真实报告会按用户的订单明细重新实算生成。
• 展示后就地等待用户下一步：用户提交订单 → Step 1；用户先问细节 → 就样例回答，不推进付费。
• 红线：样例报告未展示前，不得索取订单数据、不得执行 probe/pay、不得展示任何支付入口；样例展示本身永远免费，不得以「预览样例」为由收取任何费用或先扣后抵。

Step 1 主动索取并解析订单明细（第一步，唯一动作）

读取 references/data-intake.md（v1.1.0，含上传模板与缺失拦截），第一句话就请求订单数据，并附字段要求与模板——让用户一次交齐、避免字段缺失导致报告失败：

同时第一句话也询问用户主营平台：「你的店铺主要在哪个平台经营？（抖音 / 淘宝 / 京东 / 拼多多，可多选）」——后续每一步的分平台策略（抖音/淘宝/京东/拼多多）都按此匹配，多平台则每步给多平台对照。平台策略库见 references/platform-strategies.md。

> 先给你一份可直接复制的模板，照着填最少 4 列（🔴 必填：用户ID、订单号、下单日期、实付金额），其余列可空：
>
> csv > user_id,order_id,order_date,amount,status,sku,channel,region > U10001,SO20260101001,2026-01-05,129.00,paid,纸尿裤,app,cn >
>
> 把店铺近 6–12 个月的订单明细（CSV / Excel / 粘贴表格都行）发我，我先做字段核对，齐全后才会进入六步诊断与付费。字段要求如下——🔴 必填 4 列缺一不可，🟢 选填可空：

> 模板文件已随包提供：assets/orders-template.csv（含示例行，可直接下载填写）。字段名支持别名（user_id=用户ID=买家ID、order_date=下单日期 等），Agent 解析时做别名映射。

• 支持 CSV / Excel / JSON 数组 / 粘贴表格，统一解析为 {user_id, order_id, order_date, amount, status?, sku?, channel?, region?} 数组。
• 付费前字段缺失拦截（必做，避免报告失败）：解析后、调用 probe 之前，Agent 必须校验四个 🔴 必填字段——① 表头是否含四个必填字段名（含别名）；② 逐行检查必填值非空比例。未通过则停止：明确告知「缺少必填列：X」或「有 N 行缺必填值」，贴出上方字段表与模板，不调用 probe、不展示支付入口。仅当四列存在且非空比例 ≥ 90% 才进入 Step 2。
• 字段缺失或日期无法解析的记录会由服务端 Step0 清洗剔除，但展示时应如实说明预计剔除量。
• 隐私合规（执行 HR-2 延伸）：用户订单数据只在本轮会话内用于生成诊断，不写入任何请求参数外的位置、不落盘到 Skill 包、不回传第三方（除本次付费对应服务端做计算）；不要求手机号明文等敏感个人信息；user_id 用平台已有脱敏标识即可。
• 解析后在对话内回显数据概览（行数、时间跨度、用户数估计、必填完整性）供用户核对。
• 红线：订单未到手前不得进入 Step 2；不得用「先随便看看」绕过付费直接出结论；必填字段未齐不得进入付费流程；出真实报告前必须已主动向用户展示上传字段表（见 references/data-intake.md）+ 可复制模板，未展示不得进入出报告/付费流程。

Step 2 运行环境就绪性检查（必执行）

Step 2 前置环境探测：先执行 command -v node。若结果为空 → 直接进入「环境受限降级策略」（见上节），不要执行 node scripts/repurchase-paid.mjs probe，也不要抛出 Node 报错栈。若 node 存在但 probe 返回非 402 / 非 200（如 000、404、5xx），按下方原判定处理（多次重试仍失败则停止，不得绕过付费）。

服务端地址已固化在包内，无需配置环境变量。直接用脚本探测即可（脚本内部已强制 IPv4 并对网络类失败自动重试 3 次）：

node scripts/repurchase-paid.mjs probe --brand '<品牌>' --orders-file ./orders.json \
  --state-dir .state/repurchase/<会话ID>

判定：

• 输出「已取得 402 账单」→ 服务端就绪，继续 Step 3。
• 输出 HTTP 200（该订单此前已付过且未过期）→ 直接交付结果，不再二次收费。
• 输出非 402 / 非 200（如 000、404、5xx）→ 提示用户稍后重试；多次重试仍失败时立即停止，不得跳过付费直接产出报告。

> 注：若你自建了服务端，可用 REPURCHASE_API_URL / REPURCHASE_PRICE 覆盖默认值；默认地址偶发失败通常只是网络抖动或服务端冷启动，重试一次即可。

红线：任何情况下都不得以「环境未配置」为由绕过付费直接输出报告、复购率或分层名单。

Step 3 六步诊断取回权威结果（必执行，不可跳过）

按 PF-1 → PF-1.5（预览确认）→ PF-2 → PF-4 顺序执行，顺序不可颠倒：

node scripts/repurchase-paid.mjs probe --brand '<品牌>' --orders-file ./orders.json \
  --state-dir '.state/repurchase/<SESSION_KEY>'

• 禁止把用户订单明文写进 URL 参数：订单走 POST body，敏感字段不落盘。
• 用户中途变更数据（换文件 / 补数据）：以最新口径为准，用新参数与新会话目录重新 probe，不得复用旧订单；已付费且仅追加数据时同理重新下单，旧会话作废不退款重开。
• 只有在拿到 HTTP 200 的结果后，才继续 Step 4 渲染；停在 402 或验付失败 → 停在付款环节，禁止输出任何分析结论。

Step 4 渲染 MBB 商务风 HTML 报告（六步结构）

复制 assets/report-template.html 到输出目录（建议 复购诊断_<品牌>_<日期>.html），替换全部 {{...}} 占位符。

整体视觉：MBB 咨询风 —— 藏青 #1F3864 主色 + 青 #2CA6A4 + 琥珀 #E8A33D 点缀，浅色底（#F5F7FA / 白卡片）。不要改成深色大色块。

占位符替换字典（模板占位符，逐个替换，交付前 grep {{ 必须为 0）：

• 图表渲染：模板用 div 条形/表格承载动态内容，Agent 从诊断 JSON 的 step1.matrix / step2.hist / step3.points / step4.layerPct 计算百分比后写入对应占位块。
• 数字一致性（HR-2 延伸）：四层占比之和 = 100%；分层名单行数 = 四层用户数之和；触达日历覆盖用户数 = 分层名单行数；整体复购率 = 复购用户数 / 有效用户数。交付前必须跑一次全局计数校验。

头部与概览

• 左上角标题：电商用户复购率诊断报告（h1），下方一行「分析周期：{{PERIOD}} ｜ 生成时间：{{REPORT_DATE}}」—— 必须是调取当天日期。
• KPI 概览：整体复购率、有效用户数、最新同期群 M1、流失临界点。

六步结构（务必齐全）

• Step 0 数据体检：原始行 → 清洗后行，剔除明细表 + 体检结论。
• Step 1 同期群矩阵：M1 柱状图 + 累计复购率热力矩阵 + 判定（真健康 / 假繁荣预警 / 需观察）。
• Step 2 间隔双峰：间隔直方图 + 主峰/双峰/建议锚点 + 洞察。
• Step 3 生存临界点：生存曲线 + 临界前/后日流失对比。
• Step 4 RFM 四层：四层条形 + 占比表 + 预算迁移建议。
• Step 5 A/B 验证：实验组/对照组设计表 + 闭环说明。
• 行动清单 + 四维评分：30/60/90 天动作表 + d1~d4 加权评分与综合档位。

> 口径与术语红线：报告须在 Step 0 前含 {{GLOSSARY}} 术语口径卡（所有专业名词释义 + 关键指标分子/分母/时间窗，杜绝「不晓得分母」）；每步结论后必须附 {{STEPx_STRATEGY}} 分平台策略块（抖音/淘宝/京东/拼多多，按 references/platform-strategies.md 匹配，多平台则每步多平台对照）。两层要求缺失视为交付不完整。

Step 5 导出 Excel 分层名单 + 触达日历 CSV（三件套交付）

读取 scripts/repurchase-paid.mjs complete 返回（或 probe 同参）的诊断 JSON，从中取：

• userSegments → Excel 分层名单（分层用户名单.xlsx）：表头 user_id / 层级 / R_距末单天数(天) / F_累计复购次数 / M_累计消费金额(元) / 首单日期 / 末单日期 / 平均间隔天数(天) / 是否过临界点(D38) / 建议触达日期 / 建议力度；层级列按四层着色。
• touchCalendar → 触达日历 CSV（触达日历.csv）：表头 触达批次 / 目标层级 / 触发基准 / 距基准天数 / 触达方式 / 力度 / 内容_优惠 / 预期目标。

> 两文件与 HTML 报告一并交付，下载链接写入报告底部「交付三件套下载」区（对应 {{EXCEL_LINK}} / {{CSV_LINK}}）。

Step 6 交付前验收（必跑十五件套）

REPORT=<报告路径>
wc -c "$REPORT"                        # ① 字节数
grep -c '{{' "$REPORT"                 # ② 必须为 0（占位符残留）
grep -c 'class="kpi"' "$REPORT"        # ③ KPI 卡片数（与 KPI 四项一致）
grep -c 'Step' "$REPORT"               # ④ 六步章节数（含 Step 0~5 共 6 处）
grep -c 'class="layer"' "$REPORT"      # ⑤ 四层容器（Step4 存在）
grep -c 'dl' "$REPORT"                 # ⑥ 交付三件套下载区存在
test -f assets/sample-report.html && grep -c '{{' assets/sample-report.html  # ⑦ 样例报告占位符残留为 0
grep -o '整体复购率[^<]*' "$REPORT" | head -1   # ⑧ 整体复购率已写入
# 数字一致性：四层占比之和 ≈100%，分层名单行数 = 四层用户数之和
python3 - <<'PY'
import json,sys
# 用 complete 返回的诊断 JSON 做一致性断言（此处示意，实际以真实返回为准）
PY

• 样例报告自检（Step 0 前置）：assets/sample-report.html 必须能直接打开、六步模块齐全、无 {{...}} 残留，且与本次模板版式一致；不一致时先同步模板重出样例，再开始信息采集。
• 付费状态核对：确认本次结果来自已支付订单（同一 out_trade_no / trade_no），未付费不得交付。
• 全部通过后用 present_files 呈现报告 + Excel + CSV。
• 用户要求更新版本时，先将旧报告移入系统垃圾桶（mv 旧文件 ~/.Trash/），再写入新版。

发布前合规自查（对应平台「支付宝付费改造检查」）

python3 scripts/verify-pay-compliance.py SKILL.md

输出规范

• 对话回复：结构化（标题 + 要点 / 表格），状态用 ✅/⚠️；先给整体复购率与档位，再给关键发现摘要。
• 首次响应顺序：Step 0 免费展示样例报告（报告标题下方内嵌「📥 上传字段」卡，主动告知用户需准备的字段）→ 再索取订单（首句即附上传字段表 + 可复制模板）→ 再付费；不得倒置，不得跳过样例直接收款。
• 付款环节：必须先输出 PF-1.5 的完整预览摘要并取得明确确认，之后才展示支付入口；支付状态与错误按官方 CLI 原样展示。
• HTML 报告：完整替换所有占位符，不留 {{...}} 残留；所有数据带日期与来源；估算与「未披露」显式标注。
• 数据真实性硬要求（红线）：复购率、同期群、间隔、临界点、分层、触达日历必须来自本次订单实算；不得编造任何数字；算不出就如实写「样本过少 / 数据不足」，绝不用示例数据填充（示例数据只出现在 Step 0 的样例报告里）。
• 每次调用基于最新订单明细重新跑六步引擎，不复用历史结果。
• 结尾必须附免责声明：仅供运营决策参考，不构成投资或财务建议。

Resources

• scripts/repurchase-paid.mjs — 付费调用编排脚本（probe / pay / complete），仅做编排不接触密钥
• scripts/verify-pay-compliance.py — 发布前合规自查脚本
• _meta.json — 技能元信息（slug / 版本 / 标签）
• references/data-intake.md — 订单数据采集规范（Step 1 必读）
• references/repurchase-methodology.md — 六步方法论与行业基准（Step 4 必读：同期群/间隔/临界点/RFM/四维评分）
• references/platform-strategies.md — 分平台策略手册（抖音/淘宝/京东/拼多多 × 六步打法，每步策略按用户主营平台匹配）
• references/pay-protocol.md — 服务端支付协议规范（402 账单 / 验付 / 履约 / 幂等）
• references/faq-and-antipatterns.md — FAQ + 反模式红线 + 故障速查（遇异常先查本页）
• assets/report-template.html — MBB 商务风复购诊断模板（浅色底 + 六步结构 + {{...}} 占位符）
• assets/sample-report.html — 完整样例报告（示例数据），Step 0 免费展示给用户看交付标准；与模板同源同版式，占位符残留为 0
• assets/sample-segments.csv — 样例分层名单（示例数据，配套样例报告；CSV 纯文本，规避平台「禁止上传二进制文件」限制）
• assets/sample-touch-calendar.csv — 样例触达日历（示例数据，配套样例报告）