# macOS OCR 使用示例
本文档提供 macOS OCR MCP 工具的典型使用场景和示例提示词。
## 工具概述
- **`read_image_text`**: 提取图片或 PDF 中的纯文本，自动进行段落合并和表格优化
- **`read_image_layout`**: 提取结构化版面信息，返回包含文本块、坐标和语义信息的 JSON 数据
---
## 场景 1：快速提取纯文本
**适用场景**: 只需要获取可复制的文本内容，不需要排版或结构化信息
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件并输出识别结果：
image_path=/绝对路径/xxx.png
要求：
1. 只输出 OCR 文本本身，不要添加解释、标题或多余前后缀
2. 尽量保留原有换行与段落；不要翻译，不要总结
```
**返回格式**: 纯文本字符串
---
## 场景 2：图片/PDF → Markdown
**适用场景**: 需要将扫描文档转换为 Markdown 格式，尽量还原原有排版
**提示词模板**:
```
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/xxx.pdf
然后将返回的 blocks 按 bbox 近似还原为 Markdown：
- 标题/小标题、段落、列表分别用合适的 Markdown 语法表示
- 识别出表格时输出为 Markdown 表格（必要时补齐空单元格）
- 多页内容用清晰的分页分隔（例如：--- Page 1 ---）
只输出最终 Markdown，不要输出中间 JSON。
```
**返回格式**: Markdown 文档
---
## 场景 3：扫描表格 → CSV
**适用场景**: 将包含表格的图片转换为 CSV 格式，方便导入 Excel、Numbers 等表格软件
**提示词模板**:
```
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/table.png
目标：把图片中的"表格"转换成 CSV。
要求：
1. 只输出 CSV（逗号分隔），不要额外解释
2. 保留表头；不要丢列或丢行；空单元格也要保留为空
3. 如果存在合并单元格：优先用空值或重复值保证列数一致，并在 CSV 末尾另起一行用 NOTE: 简要说明处理方式
```
**返回格式**: CSV 格式文本
---
## 场景 4：发票/收据 → 结构化 JSON
**适用场景**: 提取发票、收据等票据中的关键信息，转换为结构化 JSON
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/receipt.jpg
请将识别内容抽取为严格 JSON（只输出 JSON）：
{
"merchant": string|null,
"date": "YYYY-MM-DD"|null,
"currency": string|null,
"total": number|null,
"tax": number|null,
"items": [{"name": string, "qty": number|null, "unit_price": number|null, "amount": number|null}],
"payment_method": string|null,
"invoice_no": string|null
}
规则：金额统一用数字；无法确认就填 null；不要编造。
```
**返回格式**: JSON 对象
---
## 场景 5：代码/终端截图 → 可复制代码块
**适用场景**: 从代码或终端截图提取可执行代码，自动纠正常见 OCR 错误
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/code.png
把结果整理成一个 Markdown 代码块输出：
1. 去掉行号、提示符（如 $、>>>）等无关字符
2. 修正常见 OCR 错误（如 0/O、1/l/I、:;、引号、括号配对）
3. 保持原有缩进
只输出代码块（例如 ```python ... ```），不要额外解释。
```
**返回格式**: Markdown 代码块
---
## 场景 6：论文/合同扫描件 → 结构化提纲
**适用场景**: 分析长篇文档的结构，提取提纲和关键信息
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/doc.png
基于 OCR 文本输出：
1) 结构化提纲（H1/H2/H3）
2) "关键点"列表（最多 10 条）
3) "需要人工确认的疑点/缺失"列表（例如数字不清、条款编号断裂）
要求：不要杜撰；引用原文时用原句；输出用中文。
```
**返回格式**: 结构化提纲文本
---
## 输出数据结构（read_image_layout）
当使用 `read_image_layout` 时，返回的 JSON 结构如下：
```json
[
{
"text": "合并纠错后的语义文本",
"bbox": {
"x": 0.0, // 归一化横坐标 [0-1]
"y": 0.0, // 归一化纵坐标 [0-1]
"w": 0.5, // 归一化宽度 [0-1]
"h": 0.2 // 归一化高度 [0-1]
},
"lines": [ // 构成该块的原始行信息（可选）
" {
"text": "原始行文本",
"bbox": {...}
}
]
}
]
```
**bbox 坐标说明**: 所有坐标均为归一化值（0-1），可用于按位置重建文档布局。
