# Pdf Image Text Extractor

> 从图片或 PDF 文档中识别并提取文字内容，支持多种图片格式和 PDF 文件，自动判断是否包含文字并保留原始格式输出结构化结果；当用户需要 PDF提取、PDF文字、图片文字、OCR 识别、文档提取、提取文本、处理扫描件或将含文字的文档转换为可编辑文本时使用

- **Type:** Skill
- **Install:** `agentstack add skill-zizhanovo-doubaoya-community-pdf-image-text-extractor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zizhanovo](https://agentstack.voostack.com/s/zizhanovo)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zizhanovo](https://github.com/zizhanovo)
- **Source:** https://github.com/zizhanovo/doubaoya-community/tree/main/skills/pdf-image-text-extractor

## Install

```sh
agentstack add skill-zizhanovo-doubaoya-community-pdf-image-text-extractor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PDF和图片文字提取

---

## 1. 简介

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

本鸭把繁琐的逐字抄录变成一条命令——全程本地运行，不联网、不上传、不外发，文件就在你手边处理。

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

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

---

## 2. 功能特性

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

**特色亮点**：

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

---

## 3. 一键安装

### 依赖安装

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

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

### 环境要求

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

---

## 4. 使用指南

### 图片文字提取

**操作流程**：

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

**可选分支**：

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

### PDF 文字提取

**操作流程**：

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

```bash
python scripts/pdf_text_extractor.py 
```

3. **查看提取结果** — 脚本返回 JSON 格式结果，包含：
   - `success`: 是否成功
   - `text`: Markdown 格式的文本内容
   - `page_count`: 总页数
   - `error`: 错误信息（如有）

4. **格式化输出** — 脚本返回的文本为 Markdown 格式，可直接展示或保存为文件

**脚本参数说明**：

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

**输出格式示例**：

```json
{
  "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                         # 用户文档（中文）
└── scripts/
    └── pdf_text_extractor.py         # PDF 文字提取核心脚本
```

### 技术栈

| 技术           | 用途                       | 版本要求    |
| -------------- | -------------------------- | ----------- |
| Python         | 脚本运行环境               | 3.7+        |
| PyMuPDF (fitz) | PDF 解析和文字提取引擎     | >=1.23.0    |

### 核心模块说明

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

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

> 脚本全程本地运行，不发起任何网络请求，无需任何 API key 或外部账号。

### 资源索引

| 资源     | 路径                                                           | 说明             |
| -------- | -------------------------------------------------------------- | ---------------- |
| 核心脚本 | [scripts/pdf_text_extractor.py](scripts/pdf_text_extractor.py) | PDF 文字提取脚本 |
| 用户文档 | [README.md](README.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：会不会上传我的文件？**
A：不会。脚本完全在本地运行，不发起任何网络请求，文件不会被上传或外发，也无需任何 API key。

**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) 图片中的文字过于模糊或与背景融合。尝试使用更高清晰度的图片重新提取。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zizhanovo](https://github.com/zizhanovo)
- **Source:** [zizhanovo/doubaoya-community](https://github.com/zizhanovo/doubaoya-community)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zizhanovo-doubaoya-community-pdf-image-text-extractor
- Seller: https://agentstack.voostack.com/s/zizhanovo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.