前言¶
财务、法务和运营同事发来的 PDF，往往要手工抄进表格或系统：发票号、金额、合同甲乙方、对账明细一行行对照，既慢又容易错。常见做法是本地脚本只做文本层抽取，或把整份 PDF 丢给通用对话模型，字段格式和批量结果都不稳定。
下面介绍 SkillHub 社区 Skill Pdf Field Extractor（坐标 @user_26bdbd50/pdf-field-extractor，当前版本 1.0.2）。它把「读 PDF → 判断文档类型 → 用大模型抽字段 → 导出结构化文件」串成一条可复用流程，适合挂在 Cursor 等支持 Skills 的 Agent 上，由模型按 SKILL.md 调用自带 Python 脚本。
这是什么¶
Pdf Field Extractor 是社区发布者 user_26bdbd50 维护的办公效率类 Skill（SkillHub 分类 office-efficiency，来源 community）。定位是：AI 驱动的 PDF 结构化提取，把发票、合同、收据等文档里的关键字段整理为 Excel（.xlsx） 或 JSON。
SkillHub 页面标注 requires_api_key=true：字段抽取阶段需要用户自行提供 OpenAI 兼容 的大模型 API Key，Skill 侧不代管密钥。页面统计（截至 SkillHub 展示）：评分 100000，下载 1218，安装 25。
官方入口：
- API 页：https://api.skillhub.cn/user_26bdbd50/pdf-field-extractor
- 展示页：https://www.skillhub.cn/skills/user_26bdbd50/pdf-field-extractor
核心功能¶
以下能力均来自 Skill 包内 SKILL.md / SKILLHUB.md 与 scripts/ 实现，可按模块理解整条链路。
端到端流程¶
- 用户提供 PDF（或批量文件）。
- 文档类型识别（
scripts/doc_type_identifier.py）：发票、合同、收据、银行对账单、营业执照、身份证、快递单、通用文档等。 - PDF 文本与表格（
scripts/pdf_extractor.py）：PyMuPDF 抽文本，pdfplumber 保留表格结构；无文本层时标记为扫描件。 - OCR（
scripts/ocr_processor.py）：扫描件走 pytesseract，支持中英日韩等语言及基础图像预处理。 - AI 字段提取（
scripts/field_extractor.py）：按文档类型或用户自定义字段列表，调用兼容 OpenAI 格式的接口（如 GPT-4o、MiniMax、DeepSeek、豆包等，以用户配置为准）。 - 输出（
scripts/output_generator.py）：生成 Excel / JSON；文档中还提到可组装飞书消息摘要。 - 批量（
scripts/batch_processor.py）：多文件并行处理（max_workers可配）。
套餐与用量（Skill 内置）¶
SKILL.md 与 scripts/tier_config.py 定义了以 Token 前缀区分的档位（如 PDF-FREE、PDF-BSC 等），包含每月页数、文档类型数量、输出格式等限制。若你启用付费档位，需在 Skill 说明的套餐规则下使用；免费档示例为每月约 10 页、偏发票类与文本输出。具体价格表以 Skill 文档为准。
安装与启用¶
方式一：让 Agent 按 SkillHub 指引安装¶
SkillHub 展示页给出的安装提示为：阅读 https://skillhub.cn/install/skillhub.md ，并安装 @user_26bdbd50/pdf-field-extractor。
方式二：SkillHub CLI¶
先确认本机已安装 skillhub（安装方式见上述 skillhub.md）。安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。
skillhub install pdf-field-extractor --namespace user_26bdbd50 --dir ~/.cursor/skills/
常见 Skills 目录（摘自 SkillHub 安装文档，按你实际使用的客户端选择）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
安装完成后，重启或刷新 Agent，使新 Skill 被加载。
运行依赖¶
SKILLHUB.md 要求 Python 3.8+。处理扫描件需系统安装 Tesseract OCR，Ubuntu/Debian 示例：
sudo apt install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-jpn tesseract-ocr-kor
Python 依赖（版本以 Skill 文档为准）：
pymupdf>=1.23.0
pdfplumber>=0.10.0
pytesseract>=0.3.10
pandas>=2.0.0
openpyxl>=3.0.0
Pillow>=10.0.0
requests>=2.28.0
在 Skill 解压目录内安装上述包后，Agent 或本地脚本即可 from scripts... 调用。
API Key¶
字段提取需传入用户自己的 api_key，并可配置 api_base、model。不要在仓库或对话里提交真实密钥；在 Agent 环境变量或安全配置中管理即可。
典型用法¶
在 Agent 对话中（推荐）¶
Skill 的 description 中列出了触发意图，例如：PDF 提取、PDF 字段提取、PDF 转 Excel、发票提取、合同提取、批量 PDF 等。用户上传 PDF 并说明要抽哪些字段即可，例如：
帮我提取这张发票的关键信息
[上传 invoice.pdf]
Agent 应按 Skill 流程识别文档类型，抽取发票号、日期、金额、买卖方等，并输出 Excel 或 JSON。
批量场景示例：
批量处理这 10 份 PDF，结果合并到一个 Excel
在 Skill 目录内用 Python 串联（与文档一致）¶
下列代码摘自 SKILL.md，展示三步调用；路径相对于 Skill 根目录：
from scripts.pdf_extractor import extract_pdf_text
from scripts.field_extractor import extract_fields
from scripts.output_generator import generate_excel, generate_json
text, tables, is_scanned = extract_pdf_text("invoice.pdf")
fields = extract_fields(
text=text,
doc_type="invoice",
api_key="sk-xxx",
api_base="https://api.openai.com/v1",
model="gpt-4o",
)
generate_excel(fields, "output.xlsx")
generate_json(fields, "output.json")
通用文档可指定 custom_fields；扫描件在 is_scanned 为真时，流程应结合 scripts/ocr_processor.py 先补全文本再抽取。批量可调用 process_batch 后统一 generate_excel。
更细的文档类型规则与 Prompt 模板见 Skill 内 references/doc_types.md、references/prompts.md。
适用场景与注意¶
适合谁
- 需要把发票、合同、收据、对账单等 PDF 批量录入表格或下游系统的团队。
- 已在 Cursor / Claude Code / Codex 等环境使用 Skills，希望用统一脚本而不是每次手写抽取逻辑的开发或实施人员。
限制与注意
- 必须自备大模型 API：无 Key 无法完成 AI 字段抽取；调用成本与合规由用户自行承担。
- 扫描件质量：文档建议约 300dpi 清晰度；OCR 依赖 Tesseract，复杂版式仍需人工抽检。
- 套餐与页数：
tier_config会对页数、文档类型、输出格式做校验，超出档位会报错，部署前先看scripts/tier_config.py。 - 敏感数据：PDF 内容会经本地解析并可能发往你所配置的模型 API，涉密材料请先过安全评审。
- Skill 文档提到 OFD、XML 电子发票等格式支持，实际以当前包内脚本能力为准；遇新格式宜先用单份样本验证。
结尾¶
Pdf Field Extractor 把 PDF 解析、类型识别、OCR、大模型抽字段和 Excel/JSON 导出收进一个 Skill，减少重复造轮子。若你的日常工作流里 Agent 已常驻，把它装进对应 skills 目录后，用自然语言描述字段即可走完整链路。
详情与安装说明见 SkillHub：https://www.skillhub.cn/skills/user_26bdbd50/pdf-field-extractor
