PDF和图片文字提取（一次付费 7 天不限次）

把 PDF / 图片里的文字，提成能直接编辑、能搜索的文本。本 Skill 分两段：
先免费诊断（只读，不改文件），再取授权执行提取（按次计费，在你本机完成，文件不出本机）。

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

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

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

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

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

python scripts/pdfimgtext.py probe <文件...> --report 诊断.md

诊断会告诉用户（只给数字和风险，不给正文）：

• 这份 PDF 有没有文字层、每页大概能提多少字；
• 哪几页没有文字层、只能靠识别（扫描件）；
• 哪几页有文字却提不出来（字体缺字形对照表）——这类页换任何工具都提不出来；
• 字体有没有 ToUnicode、有没有多栏版式、有没有加密；
• 本机有没有可用的图片识别引擎。

先把诊断结果拿给用户看，确认他要继续，再进入付费环节。

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

POST https://skills-gate.airpriv.com/api/pdf-image-text-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/pdf-image-text-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/pdfimgtext.py extract <文件...> -o 结果.md
# 可选：--format md|txt|json   --report 报告.md   --pages 1-5
#       --layout auto|row|column   --images 图片目录   --no-ocr

工具自带回读校验（写完自己读一遍，长度对不上会删除产物并报错，不会交一份坏产物）。
提取报告（markdown）是交付物的一部分——它带前后对比计数与逐页明细，排版适合直接转发；
交付时把「正文 + 提取报告」一起给用户，并把报告里的关键数字念给他听。

退出码 3 表示一个字都没提到——这是真实结果，不要当成"提取完成"报给用户，
要照报告里的逐页提示说明原因（扫描件没识别引擎？加密？字体缺映射？）。

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

1. 提不出来就提不出来：报告里按页标明「文字层 / 识别(OCR) / 没提到」，不粉饰。
2. 识别结果会有错字：扫描件与截图的识别精度取决于清晰度，交付时提醒用户核对关键数字。
3. 表格结构没有还原：多栏页已按栏重排，但表格只保证阅读顺序，不是结构化数据。
4. 加密 PDF 没被解密：工具识别到就会说明，并按「另存为不加密副本」的办法引导，而非硬猜。

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

• 授权是「付费门」，不是版权保护。授权离线可验，防的是「没付钱就用」；不防「付一次之后在本地自行延长使用」。更强保护只能把提取放到服务端执行，而提取必须在用户自己的机器上跑（要读用户的文件）——架构上不可兼得。
• 提取全程在本机完成：用户的文件不上传、产物不出本机。授权服务只收一个可选的机器指纹，不接收也不留存用户的任何数据内容。
• 图片识别用本机已有引擎（Windows 自带的 OCR，或用户自己装过的 tesseract）。一个引擎都没有时会明说"这台机器没有识别引擎"，不会说成"图里没有文字"——这两句话的含义完全不同。
• 不代做人工核对：识别出来的错字需要用户自己看，工具不保证 100% 准确。

<!-- skillhub-payblock -->

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

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

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

<!-- /skillhub-payblock -->