PPT 美化体检（按次付费版）
入口文件：8 个环节，付费场景 ③ 体检、④ 精修、⑤ 次卡；原则与规范在 references/。
https://ppt.archimind.cn ｜ 只收 .pptx ｜ 请求体上限 20 MB ｜ 账单 15 分钟、暂存 20 分钟。
1. 环境准备
装买家侧支付 CLI 并验证（官方支付能力：npm @alipay/agent-payment · 官方 skill alipay-pay-for-402-service）：npx -y @alipay/agent-payment@latest install → alipay-cli auth status → alipay-bot check-wallet（期望 bound）；故障处理 → troubleshooting.md
（持卡用户做纯核销时不需要支付环境；只有按次付费与购卡才需要。）
2. 上传待体检的 pptx（一次一个文件）
- 一次请求 = 一个文件，无批量端点，多文件逐个循环。
- 字节只走免费暂存
POST /api/v1/ppt/stage（体{"filename","content_base64"}，标准 base64）→ 得staging_id。 - 只收
.pptx：.docx/.xlsx（同为PK头）、打包 zip、多份 base64 拼接，免费侧即拒，不产生账单。
3. 美化体检（按次付费：付款 → 拿报告）
- 探测（probe）：
POST /api/v1/ppt/audit，体只放{"staging_id":"…"}→ 未付款返回 402 +Payment-Needed。 - 付款：
Payment-Needed原样存文件（不解码）→alipay-bot 402-buyer-pay -f bill.json，扫码付 ¥0.10。 - 取件（complete）：
alipay-bot 402-query-payment-status -t <tradeNo> -r <资源URL> -m POST -d '{"staging_id":"…"}'重放同一请求体取回结果（凭Payment-Proof验付）；回执402-buyer-fulfillment-ack。 - 交付：按固定模板把
content渲染给买家 —— 结论 → 检查项清单（content.checks[]）→ 问题清单（content.issues[]）→ 逐页事实（content.pages[]）；事实与数字照抄 JSON，禁止编造、禁止省略。模板见workflow.md步骤 7。
持卡用户跳过 1–3：直接带Pack-Code+Pack-Request-Id头请求（见第 5 节），无 402、无需付款，直接 200。
4. 精修（付款 → 拿 pptx 结果）
POST /api/v1/ppt/refine，体{"staging_id":"…","rules":{…}}；付款/取件同第 3 节，另一笔 ¥0.10（次卡不适用精修）。rules由体检issues[].kind翻译（杂色→fill、文案→text、页脚→footer、字体→font）；越界/溢出/重叠改不了，列人工。- 交付：
content.refined_base64解码另存新文件（不覆盖原件）+stats_text；自检PK头 /zip可解 / 含ppt/presentation.xml。 - 先体检后精修复用同一枚
staging_id（省上传，仍两笔账）。
5. 次卡（10 次卡：一次购卡，10 次免支付核销）
两条付费路径对照（按次流程见第 3 节）：
| 按次（无卡） | 次卡（持卡） | |
|---|---|---|
| 什么时候付钱 | 每一笔都先 402 出账单 → alipay-bot 付款 → 带证重放 → 才 200 | 只在购卡那一笔（4d，audit-pack10）付一次钱 |
体检 /audit |
402 → 付款 → 重放 → 200 | 请求里没有付款环节：带 Pack-Code 头，服务器验卡核销即取货，一次请求直接 200 |
精修 /refine |
按次付款 | 不适用 —— 卡不覆盖精修，精修永远按次走第 3 节 |
| 扣费时机 | 验付通过后才履约 | 先核销 1 次，后生成报告；30 分钟幂等窗兜底失败重试（见铁律） |
- 购卡：
POST /api/v1/ppt/audit-pack10（体{"filename":"…"}或{}，无需上传文件）→ 402 账单 ¥1.00 → 付款/取件同第 3 节第 2/3 步（resource_id是/api/v1/ppt/audit-pack10）→ 200 里拿content.card_code（PKC-开头）、content.credits（10）、content.expires_at。 - 卡密 = 付款凭证：拿到立即持久存储（写盘，如
~/.ppt-polish-pay/cards.json）——卡密只随购卡响应返回这一次；丢失只能凭购卡那笔的支付宝流水号联系卖家人工找回。 - 用卡体检：请求与第 3 节完全相同（先
/stage暂存、体只放staging_id），不付钱、不走 alipay-bot，只多两个头： Pack-Code: <card_code>Pack-Request-Id: <本次逻辑请求的唯一 id>（建议 uuid）
直接得 200 报告；响应头Pack-Credits-Left是核销后余量。- Pack-Request-Id 铁律：同一逻辑请求的重试必须复用同一 id —— 30 分钟幂等窗内重试不重复扣次；上次已成功的重试会重发同一份报告（
already_fulfilled: true，这是正常交付，不是错误）。不同逻辑请求必须用新 id。 - 余量/有效期：
GET /api/v1/ppt/pack-balance?code=<card_code>（或带Pack-Code头），免费不核销。 - 卡不可用时：返回
402+Pack-Card-Required头，响应没有Payment-Needed头——禁止发起付款。原因见message里的PACK_CARD_*码（余额用完/过期 → 引导购新卡；频控 → 等 3 秒原样重试）。详见error-codes.md。 - 卡只能用于体检（
/api/v1/ppt/audit）：/refine、/audit-pack10不收卡，返回400 PACK_CARD_NOT_VALID_HERE。 - 购卡 200 响应丢失：不要重复付款 —— 用原 Payment-Proof 重试同一请求，会重发同一张卡（
already_fulfilled: true）。
6. 故障处理
非 200（402 除外）或 alipay-bot 报错（尤其 207）→ 唯一免费通道 POST /api/v1/client-error 上报拿 ticket。被拒 ≠ 已上报；上报把交易事实报全（哪一笔/多少钱/为何失败/intent/工单号），别只给工单号。用卡故障申报带卡密前 12 位（不要发全量）。→ error-reporting.md · error-codes.md
7. 技能路由
references/ 下 7 份：
| 文件 | 使用场景 |
|---|---|
| workflow.md | 步骤 1–7、三个场景、次卡、规则来源、报告渲染模板、交付自检 |
| error-reporting.md | 申报报文、intent、断线补报 |
| error-codes.md | 错误码（含 PACK_CARD_*） |
| troubleshooting.md | 环境类故障 |
| pricing-and-boundaries.md | 计费/次卡/隐私/边界/背景 |
| color-strategy.md | 配色判读方法论 |
| redesign-methodology.md | 8 色参考色板 + 判读原则 |
8. 约束或禁令
- 禁止把
content_base64放进计费接口（计费体只放staging_id，否则取件重放超命令行长度）。 - 禁止批量：一次一个文件，一份状态只归一个文件。
- 禁止代付或触碰支付密钥；扫码必须买家本人做。
- 禁止解码
Payment-Needed后交给-f（原样保存），账单不得二次序列化。 - 禁止把所有 402 都当付款信号：响应头没有
Payment-Needed（如Pack-Card-Required）时禁止发起任何付款，按error-codes.md处理。 - 禁止重试同一逻辑请求时更换
Pack-Request-Id（会重复扣卡），也禁止不同逻辑请求共用同一 id。 - 禁止把卡密写进日志、申报、聊天全文（申报/日志只报前 12 位）；卡密按付款凭证级别保管。
- 不承诺非
.pptx、加密/损坏、超大文件能处理。
