网页数据变表格（一次付费 7 天不限次）

把一个网址上的数据，变成一张能直接拿去用的 Excel。本 Skill 分两段：
先免费诊断（只读，不取数据），再取授权执行提取（按次计费，在你本机完成）。

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

这个工具解决的是"看得见、导不出"：页面上的榜单、列表、报表、名单明明在那儿，却没有"导出"按钮；
或者数据是页面脚本加载出来的，把页面源码存下来只有空壳。工具会先判断数据到底在哪儿，
再把它取回来展开成行列。

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

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

只有第 0 步谈过，才进入第 1 步。

第 1 步 · 免费诊断（probe，只读，不收费）

python scripts/webtable.py probe <网址> --plan 方案.json --report 诊断.md

诊断只回答三个问题：数据在哪、能不能取、大概多少条。三种结论：

诊断不会取走任何数据、不会产出任何表格；结论是此刻的页面状态，源站改版后可能失效。

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

POST https://skills-gate.airpriv.com/api/web-table-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/web-table-license
Content-Type: application/json
Payment-Proof: <第 3 步拿到的凭证>

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

成功时返回 200，content.data.license 就是授权凭证。把它存成 license.json。
一次付费 = 一份授权，有效期 7 天（grant_mode=per_build）。期间反复提取不需要再付费。

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

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

退出码 0 才允许执行提取：

python scripts/webtable.py extract --plan 方案.json -o 结果.xlsx
# 也可以直接给网址：python scripts/webtable.py extract <网址> -o 结果.xlsx
# 可选：--report 报告.md（默认 <输出名>_报告.md）
#       --max-pages 10（单次最多翻几页）
#       --save-raw 目录（把原始记录另存一份 JSON，便于以后复核）
#       --allow-partial（**只在明确只要一部分时用**，见下）

三种"停下来"是设计，不是故障——把原话告诉用户

1. 取到 0 条 → 不写文件。空表会被读成"那里没有数据"，比报错更容易误事。
2. 上游自己声明共 N 条，实收 < N → 拒绝写出（退出码 5）。
   半份数据比没有数据更危险——它会被当成完整结果用。
   确实只要这一部分：加 --allow-partial 重跑，报告里会打 ⚠️ 标注，不要当全量使用。
3. 翻页翻不动（下一页还是同一批）→ 判为不完整并停下，不会把同一页重复堆进去冒充全量。

提取报告（markdown）是交付物的一部分：带记录数、字段数、每列非空率、完整性与数据时间，
排版适合直接转发或截图给交数据的人。交付时把「xlsx + 报告」一起给用户，并把报告里的关键数字念给他听。

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

1. 取到的是快照，报告上方的日期就是取样时刻；数字明天会变。
2. 只取公开可读的字段；页面上不显示的（后台专属字段）取不到。
3. 列名可能是推断的：页面有表格就是原表头；靠重复区块成表时，列名取自元素的 class 名或序号——
   报告里会写明。不是源站给的字段名，用户需要时可以自己在 Excel 里改。
4. 不替用户算：不做单位换算、不做汇率折算、不去重、不纠错。数字口径以源站为准。
5. 日期按原文保留（不猜 03/04 是几月几号）。

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

• 授权是「付费门」，不是版权保护。授权离线可验，防的是"没付钱就用"；不防"付一次之后在本地自行延长使用"。更强保护只能把提取放到服务端执行，而提取必须在用户自己的机器上跑——架构上不可兼得。
• 诊断与提取都在本机发起：只读用户指定的那个公开网址；不向服务方上传任何数据内容，授权服务只收一个可选的机器指纹。
• 礼貌与边界：单线程、请求之间有间隔、单次运行有请求总数上限；不携带任何登录凭据、不做身份伪装；
  站点返回 403 / 要求验证码即停止并说明原因。只处理你有权访问的公开页面。
• 接口是未公开文档的前台地址，源站随时可能改版或加鉴权——报告里带采集时刻，隔一段时间要重新诊断。

<!-- skillhub-payblock -->

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

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

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

<!-- /skillhub-payblock -->