Apple Local OCR

简体中文 | English

使用 macOS 自带的 Apple Vision 在本机识别图片、截图和扫描 PDF。无需 API Key，脚本不上传输入文件，也不调用云端 OCR 服务。

它既可以作为 Codex Skill 安装，也可以直接作为 Swift 命令行工具运行。

功能

• 支持 PNG、JPEG、HEIC、TIFF、GIF、BMP、WebP 和 PDF
• 支持单文件、多文件、文件夹和递归批量识别
• 默认识别简体中文和英语，可指定其他 Vision 语言代码
• 提供准确和快速两种识别模式
• 输出纯文本或结构化 JSON
• JSON 包含置信度、页码、图片尺寸和文字坐标
• 多页 PDF 和多帧图片会逐页、逐帧处理
• 单个文件失败时保留已经成功的识别结果

环境要求

• macOS
• Apple Vision 框架
• Swift 命令行工具

如果电脑上没有 /usr/bin/swift，安装 Xcode Command Line Tools：

xcode-select --install

当前版本已在 macOS 26.0、Apple Swift 6.3.3 环境验证。更早的 macOS 版本尚未系统验证。

作为 Codex Skill 安装

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills"
git clone https://github.com/yikunluo92/apple-local-ocr.git \
  "$CODEX_HOME/skills/apple-local-ocr"

安装完成后，可以向 Codex 提出“使用 Apple 本地 OCR 识别这个 PDF”或“本地 OCR 这个图片文件夹”。

直接运行

进入仓库目录后执行：

/usr/bin/swift scripts/apple_local_ocr.swift \
  --mode accurate \
  --languages zh-Hans,en-US \
  --format text \
  -- /absolute/path/to/input

识别整个文件夹，并将结果写入文件：

/usr/bin/swift scripts/apple_local_ocr.swift \
  --recursive \
  --output-file /absolute/path/result.txt \
  -- /absolute/path/to/folder

输出带置信度和坐标的 JSON：

/usr/bin/swift scripts/apple_local_ocr.swift \
  --format json \
  --output-file /absolute/path/result.json \
  -- /absolute/path/to/scan.pdf

所有输入路径应放在 -- 后面。

参数

参数	说明
--mode accurate|fast	识别质量，默认 accurate
--languages CODE,CODE	Vision 语言代码，默认 zh-Hans,en-US
--format text|json	输出格式，默认 text
--output-file PATH	将结果写入指定文件
--recursive	递归处理输入文件夹
--dpi NUMBER	PDF 渲染分辨率，默认 200
--max-pixels NUMBER	PDF 单页像素上限，默认 25000000
--minimum-text-height NUMBER	Vision 最小文字高度，范围 0 到 1
--no-language-correction	关闭 Vision 语言纠正
--help	显示帮助

输出和退出码

• 退出码 0：所有输入处理成功
• 退出码 1：至少一个输入处理失败，其他成功结果仍会保留
• 退出码 2：参数无效，或者没有找到支持的输入

文本模式把错误写入标准错误。JSON 模式把错误写入顶层 errors 数组。

Vision 返回的标准化坐标以左下角为原点；JSON 同时提供以左上角为原点的像素坐标。

隐私

识别过程在本机执行。脚本本身不包含网络请求，不会主动上传图片、PDF 或识别结果。使用者仍应自行保护输出文件和原始资料。

License

MIT License

声明

Apple、macOS 和 Vision 是 Apple Inc. 的商标或产品名称。本项目是独立开源项目，与 Apple Inc. 无隶属或背书关系。