前言¶
財務、法務和運營同事發來的 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
