smart-ocr

这是什么？适合谁？

smart-ocr 是一个智能 PDF 转 Markdown 的 Claude Code Skill。它能自动选择最佳 OCR 引擎（markitdown、poppler+vision、MinerU），将扫描版 PDF 和图片高效转换为结构化的 Markdown 文本，特别适合处理混合了文字和图像的复杂文档。

适合人群：

• 研究人员：需要将扫描版论文转换为可编辑文本
• 文档管理员：需要批量数字化纸质文档
• 开发者：需要从 PDF 中提取代码和文档
• 内容编辑：需要将 PDF 内容转换为 Markdown 格式

核心价值：自动选择最优 OCR 引擎，无需手动对比不同工具的效果，一键完成转换。

准备工作

• Claude Code 或 Codex：需要支持 Skills 的 AI Agent
• PDF 文件：准备需要转换的 PDF 或图片文件
• 系统依赖：根据所选引擎，可能需要安装 poppler、tesseract 等
• 时间预算：安装依赖 10 分钟，首次转换 5 分钟

快速上手

第一步：安装 Skill

将 Skill 文件安装到 Agent 的 skills 目录。

第二步：安装依赖

根据你的文档类型，安装对应的 OCR 引擎：

# markitdown（推荐，轻量级）
pip install markitdown

# poppler + vision（适合扫描件）
# Ubuntu: sudo apt install poppler-utils
# Mac: brew install poppler

第三步：执行转换

在 Agent 会话中输入：

使用 smart-ocr 将 document.pdf 转换为 Markdown

Agent 会自动：

1. 分析文档类型（文字型 PDF、扫描件、混合型）
2. 选择最佳 OCR 引擎
3. 执行转换并输出结构化 Markdown
4. 如首选引擎效果不佳，自动切换备选引擎

预期产出：10 页 PDF 在 1-2 分钟内转换为结构化 Markdown。

常见踩坑

1. 扫描件质量决定识别率：低分辨率扫描件（<200 DPI）的识别率可能低于 80%。建议使用 300 DPI 以上的清晰扫描件。来源：OCR 通用经验。

2. 混合语言文档可能识别不准：中英文混排、含有特殊符号（数学公式、代码）的文档可能识别出错。建议转换后人工校对关键内容。

3. 表格和图表转换效果有限：复杂表格、流程图、图表可能无法完美转换为 Markdown。对于表格密集的文档，建议使用专门的表格提取工具。

4. 引擎切换可能丢失格式：当自动切换引擎时，格式可能不一致。建议对于重要文档，先用不同引擎分别测试，选择最佳结果。

5. 大文件处理时间较长：100 页以上的 PDF 可能需要 5-10 分钟处理。建议分批转换，每批不超过 50 页。

常见问题 FAQ

Q1：支持哪些 OCR 引擎？

A：支持 markitdown（轻量快速）、poppler+vision（扫描件优化）、MinerU（学术文档优化）。Agent 会根据文档类型自动选择。

Q2：和 Adobe Acrobat OCR 有什么区别？

A：Adobe Acrobat 是商业软件，识别质量高但价格昂贵。smart-ocr 使用开源引擎，免费且集成在 AI Agent 工作流中。

Q3：能否保留原文格式？

A：转换为 Markdown 后会保留标题、列表、粗体等基本格式，但复杂排版（多栏、文本框）可能丢失。

Q4：支持哪些语言？

A：支持中、英、日、韩等主流语言。中文识别效果取决于引擎和训练数据。

Q5：能否批量处理？

A：可以。在 Agent 中指定目录，Agent 会批量处理所有 PDF 文件。

初级用法

1. 单文件转换：将单个 PDF 转换为 Markdown
2. 批量转换：指定目录，批量转换所有 PDF
3. 图片 OCR：将图片（PNG、JPG）中的文字提取为文本
4. 混合文档处理：处理同时包含文字和图片的文档
5. 格式保持：尽量保留原文档的标题、列表、表格结构

高级玩法

1. 引擎对比模式：使用多个引擎转换同一文档，对比结果选择最佳
2. 自定义后处理：转换后自动执行文本清洗（去水印、修正常见 OCR 错误）
3. 与知识库集成：将转换结果直接导入笔记软件或知识库

小技巧

1. 先用 2-3 页测试文档评估不同引擎效果，再批量处理
2. 对于重要文档，使用「引擎对比模式」确保最佳结果
3. 转换后使用拼写检查工具验证文本准确性
4. 将常用配置保存为模板，一键复用
5. 对于表格密集的文档，指定使用 MinerU 引擎

参考链接

• markitdown GitHub
• MinerU GitHub

基于公开资料整理，AI 辅助生成，采集日期：2026-08-12。具体功能以官方文档为准。