pdf-to-markdown

PDF 轉 Markdown

把 PDF 轉成乾淨、可編輯的 Markdown。核心由 scripts/pdf_to_md.py 完成確定性的抽取工作， 你（模型）只在「掃描頁需要辨識文字」時介入，用視覺能力把影像轉成文字。

何時用本 skill

• •「幫我把這份 PDF 轉成 markdown / md」
• •「這份報告（PDF）整理成 md 給我」
• •「PDF 內容抽出來，含表格」
• •掃描的公文、檢驗報告、論文 PDF 想變成可編輯文字

環境需求

• •Python 3 + PyMuPDF（import fitz）。若缺：python -m pip install pymupdf
• •不需要安裝任何 OCR 引擎——掃描頁由你（模型）的視覺能力辨識。

工作流程

步驟 1：執行轉換腳本

對使用者給的 PDF 執行（Windows PowerShell 或一般 shell 皆可）：

python "<skill 目錄>/scripts/pdf_to_md.py" "<輸入.pdf>"

常用選項：

• •-o <輸出.md>：指定輸出路徑（預設與來源 PDF 同目錄、同檔名）
• •--dpi 300：提高掃描頁渲染解析度（中文小字或要更高辨識率時用，預設 200）
• •--no-images：不擷取嵌入圖片
• •--force-ocr：把所有頁都當掃描頁渲染（文字層損壞 / 亂碼時用）
• •--quiet：不顯示逐頁進度（預設會顯示）

緩解等待焦慮（重要）：轉換可能要等，請主動讓使用者知道進度，不要默默卡住：

1. 開跑前先告訴使用者你正在開始轉換，並說明「掃描頁需逐頁辨識、會比較久」設定預期。
2. 腳本執行期間會把逐頁進度印到 stderr（例如 [進度] 第 3/12 頁：…、[完成] …）。

在終端機 / Code 使用者能即時看到；在 chat/cowork 沙箱看不到串流，故更要靠第 1、3 點。

1. 腳本結束後，依下方摘要回報「共幾頁、其中幾頁掃描、輸出在哪」。若還要做掃描頁辨識

（步驟 3），先告訴使用者「文字頁已完成，正在辨識 N 頁掃描影像」，逐頁辨識時可簡短回報進度。

腳本行為（你不必重寫）：

• •文字頁：抽文字、依字級標 #/##/###、表格轉 Markdown、圖片存到 <名稱>_assets/ 並以

![](...) 引用，全部依頁面由上而下的順序排列。

• •掃描頁（文字 < 12 字）：渲染成 PNG 存到 <名稱>_assets/，並在 .md 留下一個

<!-- OCR-PLACEHOLDER page=N image=... --> 佔位標記。

• •安全：絕不覆蓋既有檔案；若目標 .md 已存在，會自動改存 名稱-1.md、名稱-2.md。

步驟 2：讀取腳本輸出，判斷有無掃描頁

腳本最後會印出機器可解析的摘要：

MARKDOWN_OUTPUT: C:\...\報告.md
PAGES_TOTAL: 12
OCR_PAGES: 2
OCR_PAGE	3	C:\...\報告_assets\報告_page003_scan.png
OCR_PAGE	7	C:\...\報告_assets\報告_page007_scan.png

• •OCR_PAGES: 0 → 純文字 PDF，完成，把 MARKDOWN_OUTPUT 路徑回報給使用者即可。
• •OCR_PAGES 大於 0 → 進入步驟 3 補辨識。

步驟 3：辨識掃描頁（只在有 OCR_PAGE 時做）

對每一個 OCR_PAGE 列出的 PNG：

1. 用 Read 工具讀取該 PNG（你具備視覺能力，能直接看圖辨識，中文辨識通常優於傳統 OCR）。
2. 把該頁影像逐字轉成 Markdown：保留標題、段落、清單；表格盡量用 Markdown 表格呈現；

看不清楚的字用 [?] 標記，不要憑空捏造內容（遵守「不猜、不補」原則）。

1. 編輯 .md 檔，把對應的整段佔位（從 <!-- OCR-PLACEHOLDER ... --> 到該頁引用行結尾）

替換成你辨識出的 Markdown 文字。保留 <!-- page N --> 註解作為頁次錨點。

辨識完所有掃描頁後，.md 即為完整成品。

步驟 4：回報

向使用者回報：輸出 .md 路徑、總頁數、其中幾頁是掃描頁經視覺辨識、圖片資料夾位置。 依專案規範用繁體中文、用【結果】【狀態】【風險/不確定】格式回覆。

注意事項

• •表格偵測靠 PyMuPDF 的 find_tables()，對有格線的表格效果最好；無格線的鬆散排版可能被當成

一般段落，這是已知限制，必要時提醒使用者人工檢查。

• •數學公式、複雜版面（多欄報紙式）可能順序錯置，遇到時可改用 --force-ocr 讓你用視覺整頁辨識。
• •若使用者另外裝了 Tesseract 並偏好用它做 OCR，也可以，但預設與建議路徑是視覺辨識，零安裝。