skill 上传过审检测

对即将上传的 skill 包做合规审查：检测违规内容、敏感信息、格式错误及不符合平台过审标准的问题，输出检测结果与修改建议。

本技能以 HTTP 接口 形式对外提供服务，采用 支付宝 AI 按量付费（Alipay AI Pay-per-Use） 计费模式：每次调用按次计费，未付费调用返回 402 账单，付费后携带支付凭证重试完成履约。

什么时候用

• 用户上传了一个 skill 的 zip 压缩包（或目录），问「能不能过审」。
• 用户问「这个 skill 里有没有违规内容 / 敏感信息」。
• 用户问「为什么被平台驳回 / 哪里不合规 / 要改什么」。

怎么做

1. 拿到 skill 包的 zip 文件路径或目录路径（给 zip 即可，脚本自行解压到临时目录）。
2. 运行校验脚本（stdlib-only，无需安装依赖）：

bash python3 <本技能目录>/scripts/validate_upload.py "<zip或目录路径>" --json

<本技能目录> 通常是专家包内的 skills/upload-review-checker/，可用以下命令定位：

bash find ~/.workbuddy -path '*upload-review-checker/scripts/validate_upload.py' 2>/dev/null | head -1

3. 读取脚本输出的 JSON（verdict / type / errors / warnings / notes），翻译成中文报告。
4. 违规内容语义审查：脚本对敏感信息做精确扫描、对违规关键词做疑似提示；真正的违规内容判定，须通读 skill 内容对照平台内容政策做语义判断。
5. 若脚本缺失，退而求其次：按 references/review-rules.md 逐项人工校验。

输出

• 结论先行：检测对象 + ✅/❌ 预计是否通过。
• 违规内容/敏感信息：命中项（文件:行号 + 类型 + 脱敏建议）。
• 阻断项（errors）：每条含 check（维度）、location（文件/配置项）、problem（原因）、fix（修改建议）。
• 警告（warnings）与需人工核对项（notes，如版本号递增、name 占用）。

边界

• 只诊断、不修改用户包文件。
• 违规内容为语义判断，拿不准的标注「疑似违规，建议人工复核」。
• 版本号是否严格大于平台当前版本、name 是否被占用，本地无法判定，如实标注为「需平台核对」，不臆断。

技能接口（Interfaces）

本技能暴露以下 HTTP 接口，全部遵循支付宝 AI 按量付费协议：

probe（预检/询价）

调用方在正式请求前调用 probe，传入待检 skill 包信息（文件名、大小、类型）等参数，服务端返回 probe 结果：是否需要付费、账单预估金额、可用功能清单，供调用方决定是否发起支付。

pay（下单支付）

调用方调用付费业务接口（如 complete）但尚未支付时，服务端返回 HTTP 402 Payment Required，并在响应头与响应体下发账单（订单号 payment-order-id、金额、币种、支付链接/二维码、Payment-Needed 标记）。调用方凭账单跳转支付宝完成支付。

complete（验付 + 履约）

调用方完成支付后携带支付凭证重试：在请求头 Payment-Proof 中传入支付凭证，服务端调用支付宝验付接口校验凭证有效性（是否真实支付、金额是否匹配、订单是否匹配）。校验通过后执行实际业务逻辑（解压 skill 包、扫描违规内容与敏感信息、校验格式与过审标准），返回检测报告与支付完成信息。

ack（履约确认）

业务完成后返回 ack 回执（订单号、支付状态、履约结果）。ack 与业务结果幂等：同一订单重复请求只返回首次履约结果，不重复执行、不重复扣费。

支付宝 AI 按量付费协议（Alipay AI Pay-per-Use）

协议字段

支付流程（probe → pay → complete → ack）

1. probe（预检）：调用方先 probe 询价，确认是否需要付费与费用。
2. pay（下单支付）：首次调用业务接口未付费 → 服务端返回 402 + Payment-Needed 账单 → 调用方跳转支付宝支付。
3. complete（验付履约）：调用方携带 Payment-Proof 重试 → 服务端验付 → 校验通过后执行过审检测业务逻辑。
4. ack（履约确认）：服务端返回检测报告 + ack 回执，标记支付完成与履约完成。

1. 402 账单下发

需要付费时，服务端返回 HTTP 402 Payment Required，并在响应头 Payment-Needed: true 与响应体中下发账单：

{
  "code": "PAYMENT_REQUIRED",
  "payment-needed": true,
  "payment-order-id": "ORD-20260925-0001",
  "amount": "0.90",
  "currency": "CNY",
  "pay-url": "https://openapi.alipay.com/gateway.do?out_trade_no=ORD-20260925-0001",
  "message": "请完成支付后携带 Payment-Proof 重试"
}

2. 携带凭证重试（Payment-Proof）

调用方收到 402 后完成支付宝支付，在重试请求的请求头携带支付凭证：

POST /skill-review/v1/complete HTTP/1.1
Payment-Proof: ALIPAY-PROOF-<交易号或凭证串>
payment-order-id: ORD-20260925-0001
Idempotency-Key: <调用方生成的幂等键>

3. 验付调用

服务端对 Payment-Proof 调用支付宝验付接口（alipay.trade.query 或异步通知验签）逐项校验：

• 凭证真实且未被使用；
• 支付金额与账单金额一致；
• 订单号与 payment-order-id 匹配；
• 支付状态为「已支付」。

验付失败返回 402（仍需支付）或明确错误码，不执行任何业务逻辑。

4. 履约确认（ack）

验付通过后执行实际业务逻辑（解压并扫描 skill 包，输出过审检测报告），返回支付完成信息与 ack 回执：

{
  "code": "OK",
  "payment-order-id": "ORD-20260925-0001",
  "paid": true,
  "ack": { "status": "FULFILLED", "result": "<过审检测报告>" }
}

5. 订单持久化与幂等

• 订单持久化：将订单号、支付状态（待支付 / 已支付 / 已履约 / 已退款）持久化到数据库或存储。
• 幂等去重：按 payment-order-id 或 Idempotency-Key 去重——同一订单/幂等键的重复请求直接返回首次结果，避免重复扣款与重复履约。
• 状态机：待支付 → 已支付 → 已履约；已履约订单再次请求直接返回 ack，不重复执行。

支付依赖（Dependencies）

具体版本见 requirements.txt（Python）与 package.json（Node.js）。

资源说明

• scripts/validate_upload.py —— 校验引擎（单一事实来源，stdlib-only）。
• references/review-rules.md —— 平台审核规则速查（含违规内容/敏感信息维度）。
• scripts/payment_gateway.py —— 支付网关示例实现（402 账单下发、验付、履约确认、订单持久化与幂等）。
• references/payment-protocol.md —— 支付宝 AI 按量付费协议完整规范（402 / Payment-Needed / Payment-Proof、probe / pay / complete / ack、验付与幂等）。
• requirements.txt、package.json —— 支付相关依赖清单。