Communitygithub.com

V4TIME/V4SKILL

PDF 檔案:建立、讀取、合併、填寫表單、OCR、編輯文字。

V4SKILL 是什麼?

這個技能提供了完整的 PDF 操作能力,涵蓋從建立、讀取、編輯、合併到安全性設定等一系列功能。它整合了 pypdf、reportlab 和 pdfplumber 等 Python 函式庫,讓 AI 代理程式可以透過命令列腳本直接操作 PDF 檔案。此技能特別適合用於自動化產生報表或發票、建立可填寫的 AcroForm 表單、從 PDF 中擷取文字或表格資料,以及對頁面進行浮水印、旋轉或分割等處理。對於掃描生成的純圖片 PDF,它會引導使用者參考 `references/ocr-extraction.md` 中的 OCR 處理方法,而非直接回報無文字內容。此技能支援 Claude Code、Cursor 等開發平台,並提供詳細的驗證流程與常見陷阱說明,確保操作結果的正確性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/pdf

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

PDF 技能

從結構化規格建立 PDF、建立並填寫 AcroForm 表單(含版面佈局檢查與視覺疊層)、擷取文字/表格/元資料、合併/分割/旋轉/浮水印/蓋章頁面、匯出頁面圖片、管理元資料與附件,以及加密/解密 — 使用 pypdf、reportlab 和 pdfplumber。兩個吸收的功能存放在 references/ 中(請在執行那些任務前先讀取對應的檔案):

  • 掃描/純圖片 PDF 與 OCR(pymupdf 快速路徑、marker-pdf 品質路徑、scripts/extract_pymupdf.py + scripts/extract_marker.py):references/ocr-extraction.md
  • 透過自然語言提示編輯現有 PDF 內文(nano-pdf CLI):references/nano-pdf-editing.md

使用時機

  • 將報告、發票或多頁文件產生為 PDF。
  • 根據 JSON 規格建立可填寫的 AcroForm(文字/核取方塊/單選按鈕/下拉選單),並先檢查版面佈局。
  • 從 PDF 中取出文字、表格(JSON/CSV)、元資料或表單欄位值。
  • 合併、分割、旋轉、擷取頁面子集、浮水印、在座標處蓋上文字/圖片、加入書籤或壓縮 PDF。
  • 將頁面匯出為 PNG 以供視覺審查或轉交給 OCR;設定/清除文件元資料;新增/擷取檔案附件。
  • 填寫或扁平化 AcroForm 表單;使用密碼加密或解密。
  • 不適用於掃描/純圖片 PDF(請使用 references/ocr-extraction.md),也不適用於需要像素完美呈現的 HTML 轉 PDF(請使用無頭瀏覽器)。

必要條件

  • Python 3.10+ 搭配 pypdf、reportlab、pdfplumber: python -m pip install pypdf reportlab pdfplumber
  • 選用,用於頁面柵格化(pdf_page_image.py、疊層渲染):python -m pip install pypdfium2,或 PATH 中的 poppler 工具 pdftoppm。腳本會依序嘗試 pypdfium2 → pdftoppm,並在兩者皆不存在時回報 {"rendered": false, "missing": [...]}(exit 0)。
  • 每個輔助腳本都會惰性檢查匯入,並在缺少相依套件時印出安裝提示。

執行方式

所有輔助腳本都位於 scripts/ 中,且為 argparse CLI — 請使用 terminal 工具執行;每個都支援 --help。它們嚴格以 UTF-8 讀寫 JSON,將 JSON 結果輸出到 stdout,並在失敗時以非零值退出。

python scripts/pdf_create.py spec.json -o out.pdf         # 從 JSON 規格建立 PDF
python scripts/pdf_make_form.py formspec.json -o form.pdf # 從 JSON 規格建立可填寫的 AcroForm
python scripts/pdf_form_layout.py formspec.json           # 在建立前檢查表單版面佈局
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text                 # 每頁文字(JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # 表格輸出為 JSON + CSV 檔案
python scripts/pdf_read.py doc.pdf --meta                 # 元資料、頁面大小、加密/掃描旗標
python scripts/pdf_read.py form.pdf --fields              # 表單欄位:名稱、類型、值
python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \
    --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/

快速參考

任務工具指令 / API
建立文件(標題、表格、圖片)reportlab platypuspdf_create.py spec.json -o out.pdf
建立可填寫表單reportlab acroFormpdf_make_form.py formspec.json -o form.pdf
檢查表單版面佈局 / 疊層影像pure python + PILpdf_form_layout.py formspec.json [--render-overlay o.png]
每頁文字pdfplumberpdf_read.py f.pdf --text
表格 → JSON/CSVpdfplumberpdf_read.py f.pdf --tables
元資料 / 大小 / 加密 / 掃描pypdf + pdfplumberpdf_read.py f.pdf --meta
合併(+ 大綱)pypdfpdf_merge.py a.pdf b.pdf -o m.pdf
分割 / 擷取 / 旋轉pypdfpdf_split.py f.pdf --pages 2-5 --rotate 90
列出 / 填寫 / 扁平化表單pypdfpdf_read.py --fields, pdf_fill_form.py
加密 / 解密(AES-256)pypdfpdf_secure.py --encrypt/--decrypt
浮水印 / 蓋章 PDF 頁面pypdfpdf_watermark.py f.pdf --stamp w.pdf
在座標處蓋上文字/圖片reportlab + pypdfpdf_stamp.py f.pdf --text "此處簽名" --x 400 --y 60
頁面 → PNG(審查 / OCR 轉交)pypdfium2 或 pdftoppmpdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/
設定/清除元資料、附件pypdfpdf_meta.py --set-meta / --attach / --extract-attachments
壓縮內容串流pypdfpdf_split.py f.pdf --pages 1-N --compress

程序

  1. 先檢查。 執行 pdf_read.py file.pdf --meta。檢查 encrypted(如果為 true,請先用 pdf_secure.py --decrypt 解密)和 likely_scanned_pages。如果頁面是純圖片,請先用 pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/ 匯出,然後將 PNG 交給 references/ocr-extraction.md 技能 — 不要將空文字回報為「無內容」。
  2. 建立。 使用 write_file 撰寫 JSON 規格(元素:heading、paragraph、table、image、pagebreak;可選的 title/author 元資料;頁碼會自動加入),然後執行 pdf_create.py。如果版面佈局重要,請在渲染的頁面圖片上使用 vision_analyze 進行視覺驗證。
  3. 擷取。 --text 會給出一個每頁字串的 JSON 陣列;--tables 會給出每頁的行陣列,並可以同時輸出 CSV 檔案。使用 read_file 讀取結果;切勿直接檢視二進位 PDF。
  4. 操作。 pdf_merge.py 串接檔案,並可為每個來源檔案加入一個書籤;pdf_split.py 處理頁面範圍(從 1 開始,例如 1-3,5,9-)、90° 步進旋轉,以及 --compress。浮水印需先準備一個單頁的印章 PDF(例如透過 pdf_create.py 建立),然後用 pdf_watermark.py 疊加;對於一次性印章(「此處簽名」、斜角 DRAFT、角落標籤),請使用 pdf_stamp.py 搭配明確座標的文字或圖片。
  5. 建立表單。 撰寫一個表單規格 JSON(欄位使用 PDF 點為單位的 label_box/entry_box — 請參閱 references/forms.md),使用 pdf_form_layout.py 檢查並修正所有回報的問題,可選地用 vision_analyze 檢視 --render-overlay 產生的 PNG,然後用 pdf_make_form.py 建立,最後用 pdf_read.py --fields 確認。
  6. 填寫表單。 列出欄位(--fields)以了解精確的名稱與類型,使用 write_file 撰寫 UTF-8 JSON {"FieldName": "value"}(核取方塊接受 true/false;單選/選項值必須符合欄位的匯出選項),然後執行 pdf_fill_form.py。再用 --fields 讀取以確認值已寫入。
  7. 元資料與附件。 pdf_meta.py --set-meta 寫入 Title/Author/Subject/Keywords(DocInfo);--clear-meta 清除它們;--attach/--list-attachments/--extract-attachments 處理嵌入式檔案。
  8. 安全。 使用不同的使用者/擁有者密碼和 AES-256 加密。要移除已知密碼,請使用 --decrypt 寫出未加密的副本。
  9. 驗證(見下文)後再回報成功。

常見陷阱

  • 掃描 PDF:空的 extract_text() 加上頁面圖片表示沒有文字層。請轉交給 references/ocr-extraction.md;不要憑空捏造文字。
  • 扁平化限制:pdf_fill_form.py --flatten 使用 pypdf 的扁平化支援,它會將微件外觀轉換為頁面內容。對於純文字欄位和核取方塊來說是可靠的,但可能會遺漏或錯誤渲染特殊微件(富文字、自訂外觀串流、某些單選按鈕群組)。請使用 vision_analyze 視覺驗證扁平化後的輸出;若需要無懈可擊的扁平化,請使用外部渲染器(例如 Ghostscript 或 pdftoppm+重新組合)做為後備方案。
  • NeedAppearances:填寫後,檢視器僅在外觀串流存在時才會渲染值。填寫腳本會設定 AcroForm NeedAppearances 旗標,以便相容的檢視器重新產生它們;某些最小化的檢視器會忽略此旗標 — 如果顯示正確性重要,請使用扁平化。
  • 非拉丁文字表單值:值會正確儲存(UTF-16),但欄位的預設字型可能缺少字型,導致檢視器顯示空白,即使資料來回傳輸正常。請使用 --fields 驗證,而不僅僅是視覺檢查。
  • 壓縮預期:--compress 只會 deflate 內容串流。通常節省 0–20%;對於以圖片或已壓縮串流為主導的 PDF 沒有作用。它不能取代圖片降採樣(那是 Ghostscript 的領域)。
  • 權限旗標不強制執行:擁有者密碼權限位元(禁止列印、禁止複製)是檢視器可能遵守的禮貌性要求;任何函式庫(包括 pypdf)都可以讀取和移除它們。只有使用者密碼才能透過加密實際限制內容。切勿將權限旗標視為安全性措施。
  • 表格擷取是啟發式的:pdfplumber 從格線/文字對齊偵測表格;無邊框或合併儲存格的表格可能需要調整 table_settings 或手動清理。
  • 頁面索引:輔助 CLI 使用從 1 開始的頁面;pypdf API 使用從 0 開始。腳本會進行轉換 — 不要重複轉換。
  • 旋轉蓋章文字擷取:pdfplumber 的行分組會打亂旋轉的字形(一個 45° 的「DRAFT」會擷取為散落的字母);請改用 pypdf 的 extract_text() 或渲染圖片驗證旋轉的蓋章。
  • 單選按鈕群組:reportlab 每個群組需要 ≥2 個 radio() 微件,填寫時需要使用帶斜線的匯出值("/red"),且扁平化對單選按鈕的保真度最差 — 請參閱 references/forms.md。
  • 元資料範圍:pdf_meta.py 僅寫入經典的 DocInfo 字典;嵌入式 XMP 元資料(如果有的話)保持不變,並可能在某些檢視器中顯示不同的值。
  • PDF/A 超出範圍:pypdf/reportlab 無法產生或驗證符合標準的 PDF/A。如果需要存檔一致性,請透過 terminal 工具執行 Ghostscript(例如 gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf 搭配適當的 ICC 描述檔),並使用 veraPDF 驗證 — 兩者都是外部安裝,結果仍需驗證,而非假設。
  • 旋轉必須是 90 的倍數;加密的輸入必須先解密才能進行其他操作。

驗證

  • 建立/合併/分割後:pdf_read.py out.pdf --meta — 確認 page_count,以及旋轉後的每頁 rotation。
  • 擷取後:檢查 JSON 非空,並抽查一個已知的字串或儲存格。
  • 表單設計迴圈:pdf_form_layout.py spec.json 必須以 0 退出;然後 --render-overlay boxes.png --pdf form.pdf 並使用 vision_analyze 檢視 PNG(紅色 = 帶有欄位名稱的輸入框,藍色 = 標籤框),檢查重疊、對齊不正確以及與欄位分離的標籤。反覆調整規格 → 檢查 → 疊層直到乾淨。
  • 建立表單後:pdf_read.py form.pdf --fields 列出每個規格欄位,包含正確的類型和選項。
  • 填寫表單後:pdf_read.py filled.pdf --fields 並比較值(完全匹配,包括非 ASCII 字元)。
  • 蓋章後:重新擷取文字(旋轉的蓋章使用 pypdf)或使用 pdf_page_image.py 渲染頁面並用 vision_analyze 檢查。
  • 元資料/附件編輯後:pdf_read.py --meta / pdf_meta.py --list-attachments,並重新擷取附件以進行位元組比較。
  • 加密後:--meta 顯示 "encrypted": true,且不使用密碼開啟會失敗;解密後,文字擷取應與原始檔案相符。
  • 對於任何視覺內容(浮水印、扁平化表單),請渲染並使用 vision_analyze 檢查。

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

相關技能