name: ocr description: “使用Claude vision功能对PDF/图像进行OCR识别并转换为Markdown格式。当用户：(1)要求将PDF/图像转换为markdown，(2)要求对任何文件进行OCR，(3)发送PDF/图像文件并要求提取/读取/转换/提取，(4)提到’OCR’、‘PDF转换’、‘图像转换’、'文本提取’时，必须使用此技能。此技能使用Task代理来保护主上下文 - 切勿在主上下文中直接处理文件。” context: fork agent: general-purpose

OCR (PDF + 图像)

使用Claude的vision功能读取PDF和图像文件并转换为Markdown格式。

支持格式

类型	扩展名
PDF	`.pdf`
图像	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`

快速开始

# 单个文件 (PDF或图像)
/ocr /path/to/document.pdf
/ocr /path/to/image.png

# 带有自定义指令
/ocr /path/to/document.pdf "只提取表格"
/ocr /path/to/screenshot.png "只提取代码"

# 文件夹内所有PDF/图像 (并行处理)
/ocr /path/to/folder/

核心工作流程

步骤1: 路径及文件类型确认

# 确认是文件还是文件夹
ls -la <path>

文件类型分类:

.pdf → PDF模式
.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff → 图像模式
文件夹 → 进入批量模式

步骤2: 保存方式选择 (仅PDF)

仅PDF文件时向用户询问保存方式:

AskUserQuestion:
  question: "PDF转换结果如何保存？"
  header: "保存方式"
  options:
    - label: "统一保存 (推荐)"
      description: "所有页面保存为一个Markdown文件"
    - label: "按页保存"
      description: "每页保存为单独的Markdown文件 (document_p1.md, document_p2.md, ...)"

保存方式变量:

unified: 统一保存 → document.pdf → document.md
per_page: 按页保存 → document.pdf → document_p1.md, document_p2.md, …

图像文件: 不询问保存方式，直接 image.png → image.md 转换

单文件模式 - 图像

单个图像文件处理工作流程。

重要: 单个文件也使用Task代理来保护主上下文。

Task(subagent_type="general-purpose"):
  提示: |
    请对图像文件进行OCR识别并转换为Markdown格式保存。

    文件: [图像绝对路径]
    自定义指令: [如有用户指令则包含]

    **执行任务:**
    1. 使用Read工具读取图像
    2. 将图像内容转换为Markdown
    3. 使用Write工具保存为[文件名].md文件
    4. 确认保存完成

    **错误处理:**
    - 413错误: "⚠️ 文件大小超限 (413错误)"
    - 其他错误: "⚠️ [错误消息]"

    **返回格式 (仅状态，不含内容):**
    ✅ 成功: [文件名] → [输出文件名].md
    或
    ⚠️ 失败: [文件名] - [原因]

单文件模式 - PDF

单个PDF文件处理工作流程。

重要: 单个文件也使用Task代理来保护主上下文。

统一保存模式 (unified)

Task(subagent_type="general-purpose"):
  提示: |
    请对PDF文件进行OCR识别并转换为Markdown格式保存。

    文件: [PDF绝对路径]
    保存方式: 统一 (所有页面保存为一个文件)
    自定义指令: [如有用户指令则包含]

    **执行任务:**
    1. 使用Read工具读取PDF
    2. 将所有页面转换为一个Markdown文件
    3. 使用Write工具保存为[文件名].md文件
    4. 确认保存完成

    **错误处理:**
    - 413错误: "⚠️ 文件大小超限 (413错误)"
    - 其他错误: "⚠️ [错误消息]"

    **返回格式 (仅状态，不含内容):**
    ✅ 成功: [文件名] → [输出文件名].md
    或
    ⚠️ 失败: [文件名] - [原因]

按页保存模式 (per_page)

Task(subagent_type="general-purpose"):
  提示: |
    请对PDF文件进行OCR识别并按页生成Markdown文件。

    文件: [PDF绝对路径]
    保存方式: 按页 (每页保存为单独文件)
    自定义指令: [如有用户指令则包含]

    **执行任务:**
    1. 使用Read工具读取PDF
    2. 将每页转换为Markdown
    3. 将每页保存为单独文件:
       - [文件名]_p1.md (第1页)
       - [文件名]_p2.md (第2页)
       - ...
    4. 确认所有文件保存完成

    **输出文件命名规则:**
    - document.pdf → document_p1.md, document_p2.md, document_p3.md, ...

    **错误处理:**
    - 413错误: "⚠️ 文件大小超限 (413错误)"
    - 其他错误: "⚠️ [错误消息]"

    **返回格式 (仅状态，不含内容):**
    ✅ 成功: [文件名] → [N]个页面文件生成
       - [文件名]_p1.md
       - [文件名]_p2.md
       - ...
    或
    ⚠️ 失败: [文件名] - [原因]

批量模式 (文件夹处理)

并行处理文件夹内多个PDF/图像文件。

1. 文件列表收集及分类

# 文件夹内支持的文件列表
ls <folder_path>/*.{pdf,png,jpg,jpeg,webp,gif,bmp,tiff} 2>/dev/null

文件分类:

PDF文件列表: *.pdf
图像文件列表: *.png, *.jpg, *.jpeg, *.webp, *.gif, *.bmp, *.tiff

2. 保存方式选择 (仅当有PDF文件时)

仅当包含PDF文件时才询问保存方式:

AskUserQuestion:
  question: "PDF转换结果如何保存？(图像始终统一保存)"
  header: "保存方式"
  options:
    - label: "统一保存 (推荐)"
      description: "每个PDF的所有页面保存为一个Markdown文件"
    - label: "按页保存"
      description: "每个PDF的每页保存为单独的Markdown文件"

3. 批量分组 (3个一组)

将文件按3个一组分组 (PDF和图像可混合):

组1: file1.pdf, image1.png, file2.pdf
组2: image2.jpg, file3.pdf, image3.webp
…

4. 并行代理执行

对每组使用Task工具并行执行代理:

Task(subagent_type="general-purpose"):
  提示: |
    请对以下文件进行OCR识别并转换为Markdown格式。

    文件列表:
    - [file1绝对路径]
    - [file2绝对路径]
    - [file3绝对路径]

    PDF保存方式: [unified或per_page]
    自定义指令: [如有用户指令则包含]
    输出文件夹: [与原始文件夹相同]

    **文件类型处理:**
    - PDF (.pdf): 应用指定的保存方式
    - 图像 (.png, .jpg等): 始终统一保存 (image.png → image.md)

    **关键 - 每个文件在代理内完成:**
    1. 使用Read工具读取文件
    2. 发生错误时跳过并处理下一个文件 (如413错误等)
    3. 转换为Markdown
    4. **使用Write工具保存文件** (必须在代理内完成!)
    5. 确认保存完成

    **重要:**
    - 不要将转换后的Markdown内容返回给主程序
    - 文件保存必须在代理内完成
    - 主程序只接收处理结果状态

    处理结果仅按以下格式报告 (不含内容):
    ✅ 成功: [文件名] → [输出文件名].md
    ⚠️ 跳过: [文件名] - [原因]

重要:

所有组的Task同时调用以实现并行执行
代理在Read + Write全部完成后仅返回状态
确保主上下文不加载文件内容

5. 结果汇总

所有代理完成后汇总结果:

## 📊 OCR处理结果

### ✅ 成功 ([N]个)
**PDF:**
- document1.pdf → document1.md
- document2.pdf → document2_p1.md, document2_p2.md (按页)

**图像:**
- screenshot.png → screenshot.md
- photo.jpg → photo.md

### ⚠️ 跳过 ([M]个)
- large_file.pdf - 文件大小超限 (413错误)
- corrupted.png - 读取失败

### 📁 输出位置
[folder_path]/

Markdown转换指南

分析文件内容并按以下格式转换为Markdown:

# 文档标题

## 章节1
正文内容...

### 表格
| 列1 | 列2 |
|-----|-----|
| 值  | 值  |

### 图像/图表描述
[图像描述: ...]

自定义指令应用

用户提供额外指令时:

“只提取表格” → 仅表格数据转换为Markdown表格
“请总结” → 仅核心内容摘要
“翻译成英文” → 翻译结果
“只提取代码” → 仅提取代码块

支持的内容类型

内容	转换方式
普通文本	原样转为Markdown
标题/章节	# 标题结构化
表格	Markdown表格
列表	- 或 1. 格式
图像/图表	[图像描述] 形式描述
代码	`语言` 代码块
公式	LaTeX ($…$) 格式
截图UI	UI元素及文本提取

重要规则

上下文保护 (核心)

始终在Task代理内完成Read + Write
始终代理仅返回处理状态 (禁止返回转换内容)
绝不在主上下文中加载文件内容

处理方式

始终使用Read工具读取文件 (禁止使用库)
始终尽可能保留原始文档结构
始终用户有自定义指令时优先应用
始终发生错误时跳过该文件并继续处理其余
始终文件夹处理时按3个一组并行执行代理
绝不不使用外部库 (PyPDF, Pillow等)
绝不不猜测无法读取的部分 (不明确时标记[不明确])
绝不不在一个上下文中处理所有文件 (防止内存溢出)