填表神器·批量采集文件信息填进表格

本 Skill 分两段：先免费体检（只读，不写任何文件），再取授权真写（在你本机完成，不联网）。

为什么需要授权：批量写出文件需要一份由服务方签发的凭证。授权在你本机离线校验，但没有有效授权就不执行写盘 —— 这是服务的一部分。

第 0 步 · 先体检（免费，建议必做）

python scripts/formfiller.py --inspect --dir D:/项目资料

| 用法 | 作用 | 参数 | |---|---|---| | --inspect --dir <目录> | 预览：报会采哪些字段、前几行长什么样 | 免费 | | --fields 文件名,大小,页数 | 挑要哪几列 | 中文表头或英文名都能用 | | --min-size 1KB | 只收录不小于该大小的文件 | 支持 KB/MB 后缀 | | --no-lines | 不数文本行数（大目录更快） | 数行数要读文件内容 | | --apply --out 台账.xlsx | 真采集并写出表格 | 付费（.csv / .xlsx） |

没给 --apply 时，什么都不会被写出 —— 只打印将要发生什么。

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

POST https://skills-gate.airpriv.com/api/form-filler-forge-license
Content-Type: application/json

{"machine_fp":"<本机指纹串，8–128 位，可省略>"}

首次调用一定拿到 402 Payment Required（设计如此）。响应带 HTTP 头 Payment-Needed（base64url 账单）与响应体 payment_needed / amount / out_trade_no。本机指纹：python scripts/license_check.py fingerprint

第 2 步 · 完成支付

把 payment_needed 对象（不是整个响应信封）交给支付宝 AI 付完成支付，拿回 Payment-Proof。 不要自己伪造 —— 服务端会拿它去支付宝网关做真实校验。

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

同一请求加上头 Payment-Proof: <凭证> 重发，成功返回 200， content.data.license = 授权凭证（存成 license.json）。 一次付费 = 一份授权 = 7 天有效，期间反复处理不需要再付费。

第 4 步 · 校验授权并执行（离线）

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

退出码：0 通过 · 4 签名不通过 · 5 已过期 · 6 产品不匹配 · 7 指纹不匹配 · 2 路径问题。 退出码 0 才允许执行：

python scripts/run_paid.py formfiller.py --apply --dir D:/项目资料 --out 资料台账.xlsx

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

只采文件元信息，不读正文（唯一例外是数行数时会读文本文件的内容）。
Word 的页数/字数是文档自己记的值：没重新排版就不会更新。工具照实采并写明口径，不假装是实时页数。
读不到的字段留空，并在报告里单独统计 —— 空 = 读不出来，不是 0。

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

授权是「付费门」，不是版权保护。它防「没付钱就用」，不防「付一次之后自行改本地代码继续用」。处理必须在你自己的机器上跑——架构上不可兼得。
授权服务只收一个可选的机器指纹；被处理的文件内容不上传。
加密的 Office 文件不是 zip 包，结构信息读不出来（会明确报告，不会给一个编的数）。
输出为 .csv 或 .xlsx，不生成 .docx。
全程在本机完成：不联网，授权校验离线完成。

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

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

| 平台自查项 | 本 Skill 的实现 | |---|---| | 402 账单 | 未付款时请求 POST https://skills-gate.airpriv.com/api/form-filler-forge-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 不接触支付密钥、不自行实现付款或签名。