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

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

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

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

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

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

| 检查项 | 判定 | |---|---| | 不登录能看到这些数据吗 | 看不到 → 先劝退：本工具不带登录凭据、也不做身份伪装，需要登录的内容它拿不到。请先用你已登录的方式在页面上导出 | | 页面上的内容是不是「行列」结构 | 文章 / 表单 / 单条详情 → 先劝退：这不是表格数据，本工具帮不上 | | 数据量是不是一屏就看完 | 十来条、手工复制更快 → 先劝退：直接在页面上选中复制更省事，不必花钱 | | 数据是不是每天/每周要重新取一遍 | 是 → 值得用；取一次就完事的，也请先掂量一下值不值 | | 站点是否明确拒绝（403 / 要求验证码） | 是 → 本工具立即停止并说明原因，不做任何变通 |

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

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

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

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

| 结论 | 含义 | 接下来 | |---|---|---| | 可以取 | 页面自带表格 / 找到了它真正读取的数据地址 / 页面有重复区块 | 把结论给用户看，确认后再进第 2 步 | | 本工具做不了 | 需要登录、要验证码、页面是空壳且找不到数据地址、或那张表根本不像数据表（例如页面角落的日历） | 把原因原样告诉用户，不要硬试（硬导会把排版表当数据交出去，比报错更糟） | | 读不到这个地址 | 网络不通 / 404 | 检查网址 |

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

第 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 | 授权有效 | 继续提取 | | 4 | 签名不通过（被篡改 / 不是本服务签发） | 停，回报用户并重走第 2 步 | | 5 | 授权已过期 | 停，回报用户并重走第 2 步 | | 6 | 产品不匹配 | 停 | | 7 | 机器指纹不匹配 | 停（这份授权是给另一台机器的） | | 2 | 读不到文件 / 公钥缺失 | 检查路径 |

退出码 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（**只在明确只要一部分时用**，见下）

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

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

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

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

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

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

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

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

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

| 平台自查项 | 本 Skill 的实现 | |---|---| | 402 账单 | 未付款时请求 POST https://skills-gate.airpriv.com/api/web-table-license 返回 HTTP 402 Payment Required；响应头 Payment-Needed 携带账单，响应体含 payment_needed / amount / out_trade_no。 | | 凭证重试 | 支付后携带请求头 Payment-Proof: <凭证> 重发同一个请求（URL、请求方法、请求体与原请求保持一致），服务端校验通过后返回 200，结果在 content.data 内。 | | 服务端验付 | 服务端调用支付宝 AI 按量付费凭证校验接口 alipay.aipay.agent.payment.verify 验签并核对订单、金额与服务标识；凭证无效或已过期时不交付任何资源，只回 402 账单让用户重新支付。 | | 商家履约 | 资源交付后由服务端调用 alipay.aipay.agent.fulfillment.confirm 上报履约确认；上报失败可对同一订单重试，重试幂等，不会产生第二次扣费。 | | 订单与幂等 | 每笔订单以唯一 out_trade_no 持久化于服务端订单库，状态可恢复；同一订单重复请求只履约一次、不重复扣费；本机授权凭证可离线校验（python scripts/license_check.py check license.json），有效期内重复使用不再计费。 |

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