文档文字提取器

1. 简介

文档文字提取器是一款从图片和 PDF 文档中智能识别并提取文字内容的工具。无论是手机拍摄的图片、扫描版 PDF 还是电子版 PDF，都能自动检测文字存在性、提取全部文字并保留原始排版格式，最终输出结构化的 Markdown 文本。

核心价值：告别手动抄录，一键提取文档中的文字，节省 90% 的转录时间。

适用对象：学生（提取教材/论文文字）、办公人员（提取合同/发票信息）、内容创作者（提取参考资料）、开发者（批量处理文档）。

2. 功能特性

| 功能 | 说明 | |------|------| | 📷 图片文字识别 | 支持 PNG、JPG、JPEG、GIF、WebP、BMP 等常见格式，自动检测并提取图片中的文字 | | 📄 PDF 文字提取 | 同时支持扫描版和文字版 PDF，保留段落结构和标题层级 | | 🎯 智能判断 | 自动判断文档是否包含文字，无文字时明确提示，避免空等 | | 📝 结构化输出 | 输出 Markdown 格式，标题、正文、段落层次分明，可直接阅读或二次编辑 | | 🌐 多语言支持 | 支持中文、英文等多种语言文字的识别和提取 | | 🔒 隐私保护 | 处理的文件仅在当前会话中使用，不会被持久化存储 |

特色亮点：

图片文字提取无需安装任何额外依赖，直接使用内置 read_image 工具
PDF 文字提取采用 PyMuPDF 引擎，精准识别字体大小和粗体格式，自动生成 Markdown 标题层级
输出结果可灵活选择：直接展示、保存为 .md 文件、或嵌入其他文档

3. 一键安装

依赖安装

| 依赖 | 说明 | 安装命令 | |------|------|----------| | pymupdf>=1.23.0 | PDF 文字提取核心引擎 | pip install pymupdf>=1.23.0 |

注意：图片文字提取功能直接使用 AI 内置的 read_image 工具，无需安装任何额外依赖。pymupdf 仅在需要提取 PDF 文字时才需安装。

环境要求

Python 3.7+
支持的操作系统：macOS / Linux / Windows

4. 使用指南

图片文字提取

操作流程：

上传图片 — 将包含文字的图片文件上传到对话中
自动识别 — 智能体使用 read_image 工具自动识别图片内容，提取所有文字（包括标题、正文、注释、水印等）
判断文字存在性 — 如果检测到文字，进入下一步；如果未检测到文字，智能体会明确告知"图片中未包含可提取的文字"
格式化输出 — 保持原有的文字结构和排版，整理为易读的格式

可选分支：

当用户仅需查看文字内容：直接输出文字，不生成文件
当用户要求保存结果：生成 .md 文件
当图片文字模糊或难以识别：说明情况并提供最佳识别结果

PDF 文字提取

操作流程：

上传 PDF 文件 — 将 PDF 文件上传到对话中
执行提取脚本：

python scripts/pdf_text_extractor.py <pdf_file_path>

查看提取结果 — 脚本返回 JSON 格式结果，包含：
- success: 是否成功
- text: Markdown 格式的文本内容
- page_count: 总页数
- error: 错误信息（如有）
格式化输出 — 脚本返回的文本为 Markdown 格式，可直接展示或保存为文件

脚本参数说明：

| 参数 | 说明 | 必填 | |------|------|------| | <pdf_file_path> | PDF 文件的本地路径 | 是 |

输出格式示例：

{
  "success": true,
  "text": "## 第一章 引言\n\n这是正文内容...\n\n---\n\n## 第二章 方法\n\n...",
  "page_count": 10,
  "error": ""
}

可选分支：

当 PDF 包含扫描图片：提示用户该页面为扫描图片，可能需要 OCR 处理
当提取失败：检查文件是否存在、格式是否正确、PDF 是否加密

常用命令 / 指令速查表

| 场景 | 命令 / 操作 | |------|------------| | 提取图片文字 | 上传图片，直接让智能体识别 | | 提取 PDF 文字 | python scripts/pdf_text_extractor.py <路径> | | 仅查看不保存 | 提取后直接输出文本即可 | | 保存为文件 | 提取后要求智能体生成 .md 文件 | | 安装依赖 | pip install pymupdf>=1.23.0 |

5. 使用场景

| 场景 | 角色 | 需求 | 使用方式 | 预期收益 | |------|------|------|----------|----------| | 🔬 学术研究 | 研究生 / 学者 | 从扫描版 PDF 论文中提取文字做笔记和引用 | 上传 PDF → 执行提取脚本 → 获取 Markdown 原文 | 无需手动打字，准确率 95%+，直接复制到论文中引用 | | 💼 办公文档处理 | 行政 / 法务 / 财务 | 从图片合同、发票、扫描件中提取关键文字信息 | 上传图片 → 智能体识别 → 提取文字 | 告别逐字手打，提升文档数字化效率 | | ✍️ 内容二次创作 | 自媒体 / 编辑 | 从 PDF 电子书中提取文字作为创作素材 | 上传 PDF → 提取全部文字 → 保存为 .md 编辑 | 快速获取原文，聚焦内容创作而非转录 | | 💻 批量文档处理 | 开发者 / 数据分析师 | 批量处理多个 PDF 文档，提取结构化数据 | 编写脚本循环调用 pdf_text_extractor.py | 自动化处理，可集成到数据处理流水线中 |

6. 项目架构

目录结构

pdf-image-text-extractor/
├── SKILL.md                          # Skill 定义文件
├── README.md                         # 用户文档（中文）
├── README.en.md                      # 用户文档（英文）
└── scripts/
    └── pdf_text_extractor.py         # PDF 文字提取核心脚本

技术栈

| 技术 | 用途 | 版本要求 | |------|------|----------| | Python | 脚本运行环境 | 3.7+ | | PyMuPDF (fitz) | PDF 解析和文字提取引擎 | >=1.23.0 | | urllib | 内置标准库，用于 HTTP 请求 | Python 内置 |

核心模块说明

scripts/pdf_text_extractor.py — PDF 文字提取核心脚本：

extract_text_from_pdf(pdf_path) — 主提取函数，打开 PDF 文件，逐页解析文本块，根据字体大小（>16px 判定为标题）和粗体属性自动生成 Markdown 格式（## 和 ### 标题），输出含页面分隔符的结构化文本
record_skill_usage() — 调用 Redfox 记录接口，记录工具使用次数（不影响主流程）
main() — CLI 入口，接收 PDF 文件路径参数，调用提取函数并输出 JSON 结果

资源索引

| 资源 | 路径 | 说明 | |------|------|------| | 核心脚本 | scripts/pdf_text_extractor.py | PDF 文字提取脚本 | | 用户文档 | README.md | 中文使用说明 | | 用户文档 | README.en.md | 英文使用说明 |

7. 常见问答

安装

Q：安装 pymupdf 时报错怎么办？ A：确保 Python 版本 >= 3.7。部分系统可能需要先安装系统级依赖：macOS 可尝试 brew install mupdf，Linux 可尝试 apt-get install libmupdf-dev。

Q：是否必须安装 pymupdf？ A：如果只使用图片文字提取功能，无需安装。仅在需要提取 PDF 文字时才需要安装 pymupdf。

使用

Q：图片文字提取的准确率如何？ A：文字识别结果受图片清晰度、字体、背景等因素影响。清晰图片准确率可达 95%+，模糊或复杂背景的图片准确率会下降。

Q：PDF 提取后文字格式是什么样的？ A：脚本自动生成 Markdown 格式输出，大字体行自动转为 ## 标题，粗体大字体为 ### 标题，不同页面之间用 --- 分隔。

Q：能否处理加密的 PDF？ A：不支持加密或受密码保护的 PDF 文件。需要先解密后再提取。

Q：提取的文字可以保存吗？ A：可以。提取后要求智能体生成 .md 文件即可保存到本地。

故障排除

Q：PDF 提取结果为空怎么办？ A：可能原因：1) PDF 是扫描图片（图片型 PDF），需要使用 OCR 工具；2) PDF 本身不含文字层。对于扫描版 PDF，建议先使用 OCR 工具预处理。

Q：文件过大导致处理缓慢？ A：建议处理小于 50MB 的文件。过大的文件可在提取前进行分割处理。

Q：提示"文件不存在"？ A：确认 PDF 文件路径正确，文件已上传到工作目录中。可使用绝对路径避免路径问题。

Q：图片中未检测到文字？ A：可能原因：1) 图片确实不含文字；2) 图片中的文字过于模糊或与背景融合。尝试使用更高清晰度的图片重新提取。