前言¶
手裏有一摞掃描版 PDF——論文、舊書、會議資料——想放進閱讀器或進筆記庫，常見做法是手工 OCR 或在線轉換。前者費時，後者對頁數多、版式複雜的書往往不夠用。若在 Cursor 等帶 Agent Skills 的環境裏工作，可以把「檢測 PDF、選後端、批量導出」交給 Skill 裏的腳本，在本地跑完轉換。
下面介紹 SkillHub 上的社區 Skill「掃描PDF轉ebook」（座標 @user_c11cceac/scannedpdf2ebook），它把掃描 PDF 轉成 Markdown 或 EPUB，依賴本地 OCR，不需要配置 API Key。
這是什麼¶
一句話：將掃描版書籍 PDF 轉爲 Markdown 或 EPUB，支持多種本地 OCR 後端，用 UV 管理 Python 環境。
- 維護方：社區發佈者
user_c11cceac，來源爲 community。 - 分類：SkillHub 歸類爲 office-efficiency。
- 版本：1.2.0（以 SkillHub 頁面爲準）。
- SkillHub 標籤：
requires_api_key=false，即 Skill 本身不要求額外 API Key；實際轉換在本地執行，需自行安裝 UV、Poppler 和 OCR 後端。
官方頁面：SkillHub - 掃描PDF轉ebook。
核心功能¶
以下能力來自該 Skill 包內的 SKILL.md（名稱 scanned-pdf-to-ebook）：
| 能力 | 說明 |
|---|---|
| PDF → Markdown | 保留標題層級，圖片落到 images/ 等目錄 |
| PDF → EPUB | 生成目錄；表格、公式按後端能力渲染（EPUB 僅 pdf-craft 後端支持） |
| 多 OCR 後端 | pdf-craft（DeepSeek OCR 2）、Marker（Surya）、MinerU（上海 AI Lab） |
| 文本層檢測 | 有可用文本層時可直接提取，減少不必要的 OCR |
| GPU / CPU | 有 GPU 可用更大模型；無 GPU 可降級 |
| 批量處理 | 目錄級轉換，默認跳過已生成文件，便於斷點續跑 |
觸發場景上，Skill 描述裏列出了常見說法，例如「PDF 轉 Markdown」「掃描書轉電子書」「OCR 識別 PDF」等，便於 Agent 在對話中選用。
安裝與啓用¶
1. 安裝 SkillHub CLI 並裝入當前 Agent¶
按 SkillHub 安裝說明，先確認 CLI：
command -v skillhub && skillhub --version
未安裝時可執行官方安裝腳本（完整安裝或僅 CLI，見該文檔）。安裝 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。
在 Cursor 中，skills 目錄一般爲：
~/.cursor/skills/
安裝本 Skill 的推薦命令（與 SkillHub 搜索結果一致）：
skillhub install scannedpdf2ebook --namespace user_c11cceac --dir ~/.cursor/skills/
SkillHub 頁面亦提示：參照上述安裝文檔，安裝 @user_c11cceac/scannedpdf2ebook。Claude Code、Codex 等客戶端路徑不同（例如 ~/.claude/skills/、~/.codex/skills/），只需把 --dir 換成對應目錄，安裝命令形式相同。
安裝完成後，進入 Skill 實際目錄（形如 .../@user_c11cceac/scannedpdf2ebook），再配置運行環境。
2. 本地運行依賴（Skill 內腳本）¶
轉換邏輯在 Skill 的 scripts/ 下，需在 Skill 目錄用 UV 同步依賴並安裝至少一個 OCR 後端。概要步驟：
- 安裝 UV（
uv --version驗證）。 - 安裝 Poppler（Linux 示例：
sudo apt install -y poppler-utils，以pdftoppm -v驗證）。 - 在 Skill 目錄執行
uv sync，再按平臺安裝 PyTorch 與所選後端（如uv pip install pdf-craft）。 - 環境檢查：
cd <SKILL_DIR>
uv run python scripts/check_env.py
輸出中出現「環境就緒」且至少一個 OCR 後端爲 OK 後，即可調用 CLI。
各平臺與後端差異（MinerU 在 macOS Apple Silicon 需 mineru[core] 等）見 Skill 內安裝指南，本文不展開。
典型用法¶
命令均在 Skill 目錄下通過 uv run python 執行。
可選：先檢測 PDF 類型
uv run python scripts/pdf_craft_cli.py detect "/path/to/mybook.pdf"
單文件轉 Markdown
uv run python scripts/pdf_craft_cli.py markdown "input.pdf" "output.md"
單文件轉 EPUB（需 pdf-craft 後端）
uv run python scripts/pdf_craft_cli.py epub "input.pdf" "output.epub" \
--title "書名" --author "作者"
指定 OCR 後端
uv run python scripts/pdf_craft_cli.py -b marker markdown "input.pdf" "output.md"
uv run python scripts/pdf_craft_cli.py -b auto markdown "input.pdf" "output.md"
批量轉換
uv run python scripts/batch_convert.py "/path/to/pdfs/" "/path/to/out/" -f markdown --recursive
在 Agent 對話中，安裝並啓用 Skill 後，可用自然語言描述任務（例如指定路徑與輸出格式），由 Agent 按 SKILL.md 調用上述腳本；具體路徑以你本機爲準。
適用場景與注意¶
適合誰
- 需要把掃描書、掃描論文本地化歸檔爲 Markdown 或 EPUB 的開發者或資料管理員。
- 希望 OCR 在本地完成、不依賴雲端 API 的場景（Skill 標註無需 API Key，但需下載模型，體積可達數 GB 量級）。
限制與注意
- 首次使用要預留磁盤與時間：PyTorch 與 OCR 模型較大，pdf-craft / Marker / MinerU 安裝體積在文檔中約爲 2–5 GB 量級。
- EPUB 僅 pdf-craft 後端支持；用
-b marker或-b minera轉 EPUB 會不符合後端能力。 - CPU 模式可用但較慢；無 GPU 時文檔建議較小 OCR 模型或 Marker 等輕量後端。
- MinerU 在 Linux ARM、部分 macOS 組合上文檔標註爲未測試或需特殊包名，部署前先看 Skill 內平臺表。
- SkillHub 統計（以抓取資料爲準）：評分 100000，下載 1363，安裝 18；社區 Skill，使用前自行評估環境與合規需求。
結尾¶
「掃描PDF轉ebook」把掃描 PDF 轉 Markdown / EPUB 的流程封裝成可複用的 Agent Skill：SkillHub 一鍵安裝到 Cursor 等客戶端，本地 UV + Poppler + 可選 OCR 後端完成轉換與批量任務。需要查閱簡介與版本時，可打開官方 Skill 頁：
https://www.skillhub.cn/skills/user_c11cceac/scannedpdf2ebook
API 入口（元數據）：https://api.skillhub.cn/user_c11cceac/scannedpdf2ebook
