前言¶
手里有一摞扫描版 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
