下载能力强化（一次付费 7 天不限次）

大文件下载这件事，慢和断都不是运气问题，是缺一套执行机制。
本 Skill 分两段：先免费诊断（只发一个探测请求，不下载内容），再取授权执行下载（按次计费，在你本机完成，文件不出本机）。

> 为什么需要授权：执行下载需要一份由服务方签发的凭证。
> 授权在你本机离线校验（不联网即可验证真伪与有效期），
> 但没有有效授权就不执行下载——这是服务的一部分，不是限制。

第 0 步 · 前置检查（必做，先判值不值得用这个工具）

在调用任何服务之前先确认：

只有第 0 步谈过，才进入第 1 步。 命中劝退条件就直接告诉用户「这个用你现有的方式下就行」。

第 1 步 · 免费诊断（probe，只发一个探测请求，不收费）

python scripts/porter_fetch.py probe <URL> --allow-host <域名>

诊断会告诉用户：多大、支不支持分段（能不能续传/能不能分片）、真实文件名、以及建议怎么办。
它有三档结论，照它说的做：

先把这个结论拿给用户看，确认他要继续，再进入付费环节。

第 2 步 · 请求授权（未付费会返回 402）

POST https://skills-gate.airpriv.com/api/porter-fetch-license
Content-Type: application/json

{"machine_fp":"<本机指纹串，8–128 位字母数字/连字符，可省略>"}

首次调用一定拿到 402 Payment Required —— 这是设计，不是错误。响应里带：

• HTTP 头 Payment-Needed（base64url 编码的账单）
• 响应体 payment_needed / payment_needed_token / amount / out_trade_no

> machine_fp 可选：带上则这份授权绑定这台机器，换机器需重新授权。省略则不绑定。
> 本机指纹：python scripts/license_check.py fingerprint

第 3 步 · 处理 402（完成支付）

把 payment_needed_token（或整个 Payment-Needed）交给支付宝 AI 付完成支付。
支付完成后你会拿到一个 Payment-Proof 凭证。

不要自己伪造、不要跳过这一步 —— 服务端会拿它去支付宝网关做真实校验。

第 4 步 · 携凭证重试（拿到授权凭证）

同一个请求，加上支付凭证头重发：

POST https://skills-gate.airpriv.com/api/porter-fetch-license
Content-Type: application/json
Payment-Proof: <第 3 步拿到的凭证>

{"machine_fp":"<与第 2 步相同的值>"}

成功时返回 200，content.data.license 就是授权凭证。把它存成 license.json。
一次付费 = 一个下载任务授权，有效期 7 天（grant_mode=per_build）。
7 天内反复重跑、续传、改并发参数都不需要再付费——断点续传要重跑，所以窗口必须够宽。

第 5 步 · 校验授权并执行下载（离线校验，不联网）

python scripts/license_check.py check license.json --fingerprint "<与第 2 步相同的 machine_fp>"
echo $?    # 0 = 放行；非 0 = 拒绝，不要执行下载

退出码 0 才允许执行下载：

# ① 单个大文件
python scripts/porter_fetch.py get <URL> -o out/model.bin --allow-host <域名> -j 8

# ② 批量（清单一行一个 URL；此时 -o 是**目录**）
python scripts/porter_fetch.py batch -i urls.txt -o outdir/ --concurrency 4 --allow-host <域名>

# ③ 整个 HuggingFace 仓库（目标域自动放行，无需再写 --allow-host）
python scripts/porter_fetch.py hf org/repo -o ./model-dir

# 可选：强制比对官方 sha256（不一致会**删除产物**并判失败）
python scripts/porter_fetch.py get <URL> -o out.bin --sha256 <官方值> --allow-host <域名>

跑完会在 stdout 打 key=value 结果块，并额外产出两份东西：

• 交付收据（JSON）：每个文件的状态/字节/sha256/失败原因 + 汇总统计。
  「下全了吗、放哪了、能不能用」以收据为准——stdout 会被截断，收据不会。
• 完成报告（markdown，默认 <输出名>_下载报告.md）：带前后计数与三句结论，排版适合直接转发。
  交付时把它和文件一起给用户，并把报告里的关键数字念给他听。

交付给用户的说法（照这个口径，别夸大）

1. 速度：源按单连接限速时，多分片并发才能提速；源不限速时提速不明显。
   本机实测（36.7 MB 文件、8 片）：单流 97 秒 → 14 秒（约 6.7×）——这是特定源上的实测值，不是普适承诺。
2. 续传的边界：源支持分段才谈得上分片续传；源不支持时，中断只能重来——工具会明说这一点，不会假装有保护。
3. 校验：只有拿到官方校验值（HuggingFace 的 LFS、你自己给的 --sha256）才叫「官方验收」；
   没给校验值的文件只会计算本地 sha256，不代表「已确认与官方一致」。
4. 失败不都是重试：404 是死链（重试无用）、401/403 是缺认证（补凭据），只有限流与 5xx 才值得退避重试。
5. 默认只允许回环目标：公网下载必须 --allow-host 放行。被拒时输出里给的是可直接复制执行的命令。

诚实边界（用户问到时照实说）

• 授权是「付费门」，不是版权保护。授权离线可验，防的是「没付钱就用」；
  不防「付一次之后在本地自行延长使用」。更强保护只能把下载放到服务端执行，
  而下载必须在用户自己的机器上跑（要写用户的磁盘）——架构上不可兼得。
• 下载全程在本机完成：授权服务只收一个可选的机器指纹，不接收也不留存用户要下载的任何内容。
• 只走 HTTP(S)：不做 BT 对等协议；不做 HLS 直播与 DRM；不支持 FTP 目录列取。
• --insecure 会跳过 TLS 证书校验，只在明确知道理由时用。
• 只下载你有权访问的公开资源；带凭据的直链请使用你自己的 Token / Cookie，本工具不做任何访问限制的规避。

<!-- skillhub-payblock -->

付费链路自检（与平台五项自查一一对应）

本 Skill 的付费链路由服务端承担验付、资源交付与商家履约确认；Skill 只负责
发起请求、调用官方支付能力并展示结果。逐条对应平台自查项如下：

> 支付能力由支付宝 AI 按量付费官方链路承担，本 Skill 不接触支付密钥、不自行实现付款或签名。

<!-- /skillhub-payblock -->