在 Mac 上把扫描版 PDF 转为可搜索、可复制的文档，并按需提取为 Markdown。基于 Apple Vision / Live Text，本地离线处理，适合论文、书籍和扫描资料整理。
可作为 Agent Skill 使用，也可直接运行命令行脚本。下载本站完整安装包。文档标示版本为 1.0.1，本站包取自已核对的提交 bed2dc8，不表示已核实对应 GitHub Release。
功能
- 可搜索 PDF：保留页面版式，添加隐形文字层；默认保真模式不重新编码扫描图像。
- Markdown 提取：根据文字位置和章节特征整理标题、段落，合并扫描换行并过滤部分页眉、页码；已有文字层的 PDF 可直接提取。
- 多语言识别：支持简体中文、繁体中文、英文、日文、韩文等，具体支持范围取决于识别模式和系统环境。
- 批量与增量处理：支持多个文件及目录输入；已有较新产物时跳过重复 OCR。
- 保真、去斜与压缩：按资料用途选择处理预设。
- 自动红框修复：清理受支持的 AppleOCR 调试框，也可单独修复已有产物，并保留文件权限及 macOS Finder 标签等扩展属性。
安装
需要 macOS、Homebrew 和 uv。Live Text 模式依赖系统支持；如不可用，可选择 --mode accurate。下载本站 ZIP 不需要 Node.js 或 skills CLI。
交给 Agent 安装
把本站详情页链接交给支持联网的编码 Agent：
请先读取本页及安装指南，再为当前宿主安装
pdf-ocr-searchable：https://www.lumenghe.com/skills/pdf-ocr-searchable/ 。下载本页指定的完整 ZIP 并校验 SHA-256；检查并保留已有安装及本地修改，完成后报告宿主是否发现技能。
纯文本安装指南列明下载包、共享安装路径、依赖与验证步骤，获取本技能无需访问我的 GitHub 仓库。
手动下载 ZIP
- 下载完整 ZIP，先与详情页“包信息”中的 SHA-256 核对，再解压。如果文件保存在 macOS 的“下载”目录，可运行
shasum -a 256 "$HOME/Downloads/pdf-ocr-searchable-1.0.1-20261024-bed2dc8.zip"查看摘要。 - 先解压到临时工作目录。压缩包中只有一个
pdf-ocr-searchable/根目录，包含SKILL.md、配套文件和许可证。将该文件夹放入~/.agents/skills/pdf-ocr-searchable/。目标位置已有文件、目录或符号链接时，先检查并备份，再决定如何更新，不直接合并或覆盖。 - 按宿主配置发现入口。Codex 从
~/.agents/skills读取个人技能；Claude Code 的个人技能入口位于~/.claude/skills/，可按下例建立符号链接。其他宿主按其文档配置，共享目录不代表所有宿主都会自动发现。
mkdir -p ~/.claude/skills
if [ ! -e ~/.claude/skills/pdf-ocr-searchable ] && [ ! -L ~/.claude/skills/pdf-ocr-searchable ]; then
ln -s ~/.agents/skills/pdf-ocr-searchable ~/.claude/skills/pdf-ocr-searchable
else
printf '%s\n' 'An entry already exists; inspect it before making changes.'
fi
技能真身保留在 ~/.agents/skills/pdf-ocr-searchable/，因为现有技能指令或脚本会引用这一位置。安装后检查 SKILL.md 是否存在，并在宿主技能列表或新会话中确认可用；文件存在本身不代表已经加载。 ZIP 提供技能文件，不包含 OCR 运行环境；请另行安装下列依赖。
安装依赖
OCRmyPDF 与 AppleOCR 插件需安装在同一 Python 环境。以下命令使用 Python 3.12：
uv tool install --python 3.12 ocrmypdf --with ocrmypdf-appleocr
brew install ghostscript poppler
检查插件是否可用：
ocrmypdf --plugin ocrmypdf_appleocr --help 2>&1 | grep -q appleocr && echo OK
快速上手
以下示例以 Skill 安装在 ~/.agents/skills/pdf-ocr-searchable 为例；如安装到其他位置，请相应修改路径。
S=~/.agents/skills/pdf-ocr-searchable/scripts/ocr_pdf.sh
# 检查文件是否需要 OCR
"$S" --check "论文.pdf"
# 生成 论文.ocr.pdf，保留原件
"$S" "论文.pdf"
# 同时输出 论文.md
"$S" --md "论文.pdf"
# 批量处理目录中的 PDF
"$S" ~/Scans/
# 去斜并识别繁体中文
"$S" --preset deskew --lang chi_tra "扫描件.pdf"
已有文字层的 PDF 会按脚本的文字密度判据跳过 OCR；使用 --md 时直接提取 Markdown。已有输出文件比原件新时会复用该产物。需要重新识别或更换处理参数时使用 --force，它会重做已有文字层并重写目标产物。
选择处理方式
| 预设 | 适用需求 | 图像处理 |
|---|---|---|
archive（默认） |
论文、书籍、档案留存 | 保留扫描图像，不重新编码 |
deskew |
扫歪或拍歪的页面 | 栅格化页面并矫正倾斜 |
compact |
优先控制文件体积 | 尝试优化、重新编码图像，压缩效果取决于原文件 |
"$S" --preset compact "资料.pdf"
默认输出到原文件所在目录，以 .ocr.pdf 结尾。可用 --outdir 指定输出目录，或用 --suffix 修改后缀：
"$S" --outdir "./output" --suffix ".searchable" "资料.pdf"
语言与识别模式
默认语言为简体中文 chi_sim，可通过 --lang 指定：
| 语言 | 参数 |
|---|---|
| 简体中文 | chi_sim 或 zh-Hans |
| 繁体中文 | chi_tra 或 zh-Hant |
| 英文 | eng 或 en |
| 日文 | jpn 或 ja |
| 韩文 | kor 或 ko |
不支持 chi_sim+eng 形式的语言叠加。中文模型可识别部分页内英文，英文占比较高时请抽查专有名词和参考文献。
--mode 可选 livetext（默认）、accurate、fast。部分 Live Text 故障会自动回退到 accurate；也可直接指定该模式。fast 的语言支持范围较窄，不适合中文文档。
"$S" --lang eng --mode accurate "paper.pdf"
修复 OCR 调试红框
OCR 后会自动清理受支持的 AppleOCR 调试框。处理已有产物时，直接指定要修复的 PDF：
# 只检测，不修改
"$S" --strip-boxes --dry-run "论文.ocr.pdf"
# 修复该文件
"$S" --strip-boxes "论文.ocr.pdf"
# 批量修复目录中的 *.ocr.pdf
"$S" --strip-boxes ~/Scans/
修复支持普通表单和未签名的签名域，不改写加密或已签名文件。清理失败会报告错误，并停止该文件后续 Markdown 生成。适用格式与排查方法见红框兼容性说明。
使用提示
- OCR 和 Markdown 排版还原可能存在误差，重要内容请对照原页核查。目录、索引和复杂标题尤其需要检查。
--check根据文字密度判断是否需要 OCR；少量文字页和扫描页混排时，仍需抽查正文。- 识别字数很少时脚本会提示人工检查；命令成功退出不代表所有页面都识别正确。
- 默认模式保留扫描图像，但 PDF 容器会重写，不保证整份文件字节不变。需要保留原始文件时，请留存源 PDF。
- 红框清理针对已知 AppleOCR 格式；插件升级后若提示格式不兼容，请参阅兼容性说明。
全部参数可运行 "$S" --help 查看。
项目文件
SKILL.md # Agent 技能入口
scripts/ocr_pdf.sh # PDF OCR 与批量处理入口
scripts/pdf_to_md.py # PDF 文字层转 Markdown
scripts/strip_ocr_boxes.py # AppleOCR 调试红框修复
references/red-boxes.md # 修复边界与排查
tests/test_red_boxes.py # 修复功能回归测试
致谢
- OCRmyPDF：PDF OCR 处理管道。
- OCRmyPDF-AppleOCR：Apple Vision / Live Text 引擎插件。
- mac-ocr：可选的单图 OCR 工具。
- Poppler：PDF 文字和页面布局提取。