前言¶

從 PDF 裏拿東西，常見的坑是：pdftotext 抽出的表格變成一行沒分隔符的字符串；PyPDF2 只給純文本，丟掉了行列結構；好不容易抽出表格，卻不知道某個單元格爲什麼串行。要拿到字符級的座標、線條、矩形，再自己判斷哪幾個字符組成一個表格單元格，用通用文本抽取工具基本做不到。

下面介紹的 Skill 是 pdfplumber Python PDF 文本和表格提取庫，把 pdfplumber 這個庫封裝成可調用的 Agent Skill，專門解決「從 PDF 裏拿結構化信息」這件事。

這是什麼¶

一句話定位：pdfplumber 是一個 Python 庫，用於從 PDF 中提取詳細信息——文本、表格、線條、矩形和曲線——並支持可視化調試。

• 上游項目：jsvine/pdfplumber，基於 pdfminer.six 構建
• Skill 出品：SkillHub 上的社區 Skill，座標 @user_3c6cb52e/pdfplumber-python-pdf-text-table-extraction，發佈者 user_3c6cb52e，來源標記爲 community
• 版本：1.0.0
• 分類：office-efficiency
• 標籤：requires_api_key=false，即不需要額外申請 API Key

它解決的問題是：在機器生成的 PDF 上，把版面對象還原成可編程的數據結構，尤其是結構化表格。

核心功能¶

經覈對上游資料，已確認的能力如下。

1、文本提取。Page.extract_text() 抽取純文本，extract_text(layout=True) 保留版面佈局，後者在 CLI 的 --format text 裏被使用。

2、表格提取。page.extract_tables() 提取結構化表格，返回嵌套列表；配套 page.find_tables() 用於定位表格邊界框，便於進一步裁剪或校驗。這是 pdfplumber 相對其他庫的主要優勢點。

3、字符級與圖形級對象。每頁暴露 .chars、.lines、.rects、.curves、.images 列表，每個元素是字典，帶 x0、top、x1、bottom、text 等字段，可直接做位置篩選和排序。

4、版面裁剪與過濾。.crop()、.within_bbox()、.outside_bbox() 按邊界框裁剪頁面，.filter() 用自定義函數過濾對象。邊界框是 4 元組 (x0, top, x1, bottom)。

5、可視化調試。page.debug_tablefinder() 會把表格檢測的邊界框畫成圖片，用來排查「爲什麼這個表格沒被識別出來」。

6、表單域值提取。可讀取 PDF AcroForm 表單的字段名與值。

7、CLI。命令行工具支持 csv、json、text 三種輸出格式，可指定頁碼範圍和對象類型。

安裝與啓用¶

上游庫安裝¶

上游庫通過 pip 安裝：

pip install pdfplumber

上游倉庫當前在 Python 3.10、3.11、3.12、3.13、3.14 上有測試通過記錄。早期版本的中文文檔標註的是 Python 3.8–3.11，與當前說明不一致，以倉庫當前的測試矩陣爲準。

CLI 安裝¶

命令行工具隨 pdfplumber[cli] 一併安裝：

pip install "pdfplumber[cli]"

Skill 啓用¶

SkillHub 頁面座標：

@user_3c6cb52e/pdfplumber-python-pdf-text-table-extraction

Skill 版本 1.0.0，來源 community，標籤 requires_api_key=false。該 Skill 基於通用 SKILL.md 格式，因此在任何支持該格式的 Agent 裏，只要把 Skill 目錄放進宿主項目對應的位置即可被加載。

需要說明的是：本次抓取 SkillHub 頁面未能成功，上列座標、版本、分類、標籤取自預先抓取的資料，該資料同時記錄評分 100000、下載 1191、安裝 0。任務描述裏給出的評分 99742、下載 1161 與資料不一致，因頁面無法二次覈對，本文不採用這兩個數字。

另外，資料沒有給出針對 Cursor、Codex CLI、Claude Code 各自的安裝命令差異，也沒有給出 Skill 目錄在宿主項目中的具體路徑。這部分信息沒有在已抓取資料中出現，本文不做推斷。

CLI 參數¶

CLI 的可用參數如下：

pdfplumber < input.pdf > output.csv

典型用法¶

命令行：導出整份 PDF 的對象信息¶

curl "https://raw.githubusercontent.com/jsvine/pdfplumber/stable/examples/pdfs/background-checks.pdf" > background-checks.pdf
pdfplumber background-checks.pdf > background-checks.csv

輸出是一份 CSV，包含 PDF 中每個字符、線條和矩形的信息。換 --format json 則輸出更完整的嵌套結構。

Python：打開 PDF 並讀取首頁第一個字符¶

import pdfplumber

with pdfplumber.open("path/to/file.pdf") as pdf:
    first_page = pdf.pages[0]
    print(first_page.chars[0])

pdfplumber.open(x) 的 x 可以是文件路徑、已加載爲字節的文件對象，或類文件對象。

Python：加載加密 PDF¶

pdfplumber.open("file.pdf", password="test")

Python：傳入佈局分析參數¶

pdfplumber.open("file.pdf", laparams={"line_overlap": 0.7})

laparams 直接作用於 pdfminer.six 的佈局引擎。

Python：提取表格¶

import pdfplumber

with pdfplumber.open("report.pdf") as pdf:
    for page in pdf.pages:
        for table in page.extract_tables():
            print(table)

extract_tables() 返回嵌套列表，外層是表格，內層是一行，元素是單元格文本。需要定位表格在頁面上的位置時，用 page.find_tables()，它返回的對象帶 .bbox。

Python：調試表格檢測¶

page.debug_tablefinder()

這個方法把檢測到的邊界框渲染成圖片輸出，用來判斷表格的行線、列線是否被正確識別。

Python：裁剪頁面¶

page.crop((x0, top, x1, bottom))

裁剪框內至少部分落入的對象會被保留，超出部分被切片。只想要完全落在框內的對象時用 page.within_bbox(...)，只想要完全在框外的用 page.outside_bbox(...)。

適用場景與注意¶

適合的場景：

1、機器生成的 PDF，即由排版軟件、報表系統、PDF 生成庫輸出的文件，文本是真實文本層而非圖像。
2、需要把表格還原成行列結構，再轉成 CSV、DataFrame 或入庫的場景。
3、需要按座標定位、裁剪、過濾特定區域的場景，比如只取頁面右上角的區域。
4、需要排查抽取結果爲什麼錯的場景，可視化調試比反覆打印座標快。

需要注意的限制：

1、掃描件 PDF 不適用。文檔明確說明「用於電腦生成的 PDF 上效果最好，不支持掃描的 PDF」。掃描件需要先做 OCR。
2、表格檢測依賴頁面上的線條或字符對齊。如果原 PDF 的表格沒有畫線、字符也沒有形成清晰的列對齊，find_tables() 可能檢測不到或切錯列，此時需要調整策略或用 laparams。
3、大 PDF 的內存佔用。Page 對象默認緩存佈局和對象信息以避免重複解析，處理大文件時緩存可能佔用較多內存，需要時調用 page.close() 釋放。
4、元數據解析默認寬鬆。無效元數據值默認只作爲警告；如果希望解析失敗就拋異常，傳入 strict_metadata=True。
5、座標系以 PDF 頁面左上角爲原點，top 是距頂部的距離，不是傳統的 y 座標，做區間判斷時注意。

結尾¶

pdfplumber 的價值在於把 PDF 從「一個文本流」變成「一組帶座標的對象」，從而讓文本抽取、表格還原、區域裁剪、結果調試都變成可編程的步驟。對於機器生成的 PDF，尤其是需要結構化表格的場景，它是目前 Python 生態裏實現比較完整的一個選擇。

Skill 地址：https://www.skillhub.cn/skills/user_3c6cb52e/pdfplumber-python-pdf-text-table-extraction

上游項目：https://github.com/jsvine/pdfplumber