这次我们来看一个思路很直接的小工具“Monkey see, monkey do”。它的名字已经说明了一切——用 macOS 原生 OCR 能力识别屏幕上的文字然后原样“重现”出来。现实一点说就是你截取一段屏幕内容它把文字提出来再自动敲到你需要的位置或者快速复制到剪贴板。这个项目挂在 Hacker News 的 Show HN 上属于个人开发者作品。它最值得关注的点不是模型多强而是完全利用 macOS 系统自带的 OCR 能力不联网、不上传图片、不用装额外的识别引擎。如果你长期在 macOS 上处理“图片里的一段字”“视频里的一句台词”“扫码枪扫出来的编码”这类场景这个项目值得花几分钟看完。先给结论这类工具的核心价值是本地识别 自动化输入。门槛不高但它有两个必须处理的权限点屏幕录制权限和辅助功能权限。文章会带你把环境准备、部署启动、功能验证、批量任务和常见坑全部过一遍。1. 核心能力速览能力项说明项目定位macOS 原生 OCR 文字识别与自动重现工具核心原理调用 macOS Vision framework 的VNRecognizeTextRequest对屏幕截图或图片做本地文字识别是否联网通常不需要联网识别在本地完成支持平台macOS具体系统版本需按项目 README 确认硬件要求只要是可运行对应 macOS 的 Mac 即可不依赖独立显卡显存主要功能截屏识别、图片文字提取、剪贴板输出、模拟键盘自动键入是否需要 API取决于项目实现可能是命令行入口也可能是菜单栏/快捷键触发是否支持批量任务可通过脚本对目录图片批量调用需自行封装启动方式可能是源码编译、命令行二进制或打包 App需以仓库说明为准典型场景把图片/视频/截图里的文字快速整理成可编辑文本跨应用录入内容需要说明由于没有拿到项目源码和作者的完整 README下表里的“是否支持某项功能”按 macOS 原生 OCR 的常见实现来写具体参数要以你实际 clone 的仓库为准。2. 适用场景与使用边界这个工具适合谁先说三个高频场景。第一跨应用文字录入。macOS 上经常遇到“这边图片里有段文字那边输入框里要重新敲一遍”的情况。用鼠标对着文字慢慢敲效率很低。这类工具截屏后直接识别再调用模拟键盘自动键入能做到“看到什么打什么”。第二视频和截图里的文字提取。比如教程视频里的一行命令、PPT 截图里的标题、扫描 PDF 里的摘要。这些内容在图片里不可搜索、不可复制经过 OCR 提取后就能变成纯文本。第三批量文本化。如果你有一堆截图、长截图、图片材料要转成文档写好脚本对目录跑一遍能省下大量人工。但也有不适合的场景别指望它解决所有问题复杂版面的 PDF 解析比如多栏排版、带表格的论文 PDF这类工作更适合专门的文档解析引擎而不是单纯把一页图变成文字。手写体和高度艺术化字体Vision 框架对手写体的识别率有限中文潦草字迹更是经常出错。需要坐标、排版结构还原的 OCR原生 OCR 给的是文字内容不是精细的版面结构。语法检查和语义理解OCR 只负责“认字”不负责“懂字”。识别结果拼成一个词还是两个词需要你自己校对。合规边界必须说清楚。截屏时只处理你有权限访问的内容识别他人文档、聊天记录、软件界面之前确认自己有权查看和使用这些信息。如果项目支持模拟键盘自动输入这意味着它可以替你操作其他应用请只在受控、可信的测试环境中使用不要拿去做任何绕过安全措施的操作。3. 环境准备与前置条件在跑任何代码之前先把 macOS 这边的条件检查一遍。这个项目典型依赖如下。3.1 系统版本macOS 原生 OCR 的可用性从 macOS 10.15 Catalina 开始提升。如果你用的是较新的 macOS大概率没问题。具体最低版本要去看项目说明但一个基本判断是至少要用能跑 Vision framework 的 macOS。3.2 开发工具如果项目以源码形式发布需要准备Xcode或者至少Command Line ToolsSwift 工具链macOS 自带或通过 Xcode 安装可选Homebrew用于后续安装依赖或管理脚本检查一下本机是否已经装好# 检查 Swift 版本 swift --version # 检查 Xcode Command Line Tools xcode-select -p如果xcode-select -p报错说明没装 Command Line Tools用下面命令安装xcode-select --install3.3 系统授权这是最容易卡住的地方。macOS 对“截屏”和“模拟键盘输入”有严格限制。屏幕录制权限如果项目需要截屏识别macOS 会要求授予“屏幕录制”权限。辅助功能权限如果项目需要模拟键盘自动键入macOS 会要求授予“辅助功能”权限。在系统设置里进入“隐私与安全性”找到对应项把终端、IDE 或运行工具勾选上。权限没给够的典型表现是截图出来是黑屏或者识别成功但文字没有敲进目标应用。3.4 磁盘与端口这个项目一般不会占用大量磁盘模型也不像本地大模型那样动辄几个 GB。端口方面如果只是命令行工具通常不需要端口如果项目自带 WebUI 或 API 服务才需要注意端口冲突。4. 安装部署与启动方式因为输入材料没有给出完整仓库地址和编译命令下面给一套通用部署思路。你拿到仓库后对照 README 调整即可。4.1 编译运行源码方式如果项目是 Swift Package# 进入项目目录 cd monkey-see-monkey-do # 编译 Release 版本 swift build -c release # 找到可执行文件 .build/release/monkey-see-monkey-do --help如果你是下载了源码但没有编译经验直接打开.xcodeproj或.xcworkspace用 Xcode 运行一次。运行后从 Xcode 里启动权限弹窗第一次出现时一定要点“允许”。4.2 命令行封装很多这类小工具最终会提供一个二进制命令。假设你的项目生成了类似monkeyocr的命令行入口可以把它放进/usr/local/bin或/opt/homebrew/bin# 把可执行文件复制到 PATH 下名称按实际命令替换 cp .build/release/monkey-see-monkey-do /usr/local/bin/monkey-ocr # 验证 monkey-ocr --help如果项目本身没有提供命令入口可以写一个 shell 包装脚本#!/bin/bash # 通用包装脚本模板需要按实际项目入口替换 PROJECT_DIR$HOME/Projects/monkey-see-monkey-do BIN$PROJECT_DIR/.build/release/monkey-see-monkey-do # 如果没编译过先编译 if [ ! -f $BIN ]; then cd $PROJECT_DIR swift build -c release fi exec $BIN $把这段保存为/usr/local/bin/monkey-ocr并加上执行权限chmod x /usr/local/bin/monkey-ocr4.3 一键启动的替代思路“一键启动”不一定要做成双击 App。对于命令行工具最常见的做法是在 shell 配置里加 aliasalias ocr-screen~/Projects/monkey-see-monkey-do/.build/release/monkey-see-monkey-do --screen保存到~/.zshrc或~/.bash_profile后执行source ~/.zshrc然后直接输入ocr-screen就能触发截屏识别。4.4 启动前检查清单不管用哪种方式启动先确认三件事终端或调用程序已经有了“屏幕录制”和“辅助功能”权限。macOS 的“隐私与安全性”设置里没有弹窗被忽略。项目可执行文件有正确权限编译产物没有被 gatekeeper 拦截。如果启动后提示Killed或权限相关错误多半是权限或签名的锅。5. 功能测试与效果验证项目跑起来后不要直接上生产先做一轮功能验证。下面按模块给测试用例。5.1 测试一截图 OCR 识别测试目的确认截屏能力可用识别结果能正确输出。输入素材桌面或浏览器中打开一段清晰文本建议中英文混排字号大一点。操作步骤打开终端执行截图识别命令。按照提示框选屏幕区域。等待识别结果输出。预期结果工具输出对应文本中英文都正确识别为可选中的纯文本。判断是否成功文本内容与屏幕显示内容完全一致无乱码。常见失败截图区域全黑 → 屏幕录制权限没开。输出为空 → 图片区域没有文字或者文字过小。5.2 测试二自动键入测试目的确认模拟键盘输入链路可用。输入素材打开一个空的“文本编辑”窗口然后准备一段屏幕上的文字。操作步骤先用截图识别命令识别一段文字再执行“自动键入”参数。把焦点切换到“文本编辑”窗口。观察文字是否自动敲入。预期结果文字自动出现在当前焦点应用里换行、空格基本保持一致。判断是否成功输入内容准确没有重复、漏字、乱码。常见失败没有任何输入 → 辅助功能权限缺失。输入到错误窗口 → 执行前焦点不在目标应用。5.3 测试三多语言支持测试目的确认英文、中文之外的语言是否可用。输入素材准备日文、韩文、中文简体、英文混合的截图。操作步骤查看项目是否支持--recognition-languages或类似参数。把语言参数设置为目标语言组合。截图识别并对比结果。预期结果目标语言能正确转写。判断是否成功日文假名/汉字、韩文谚文、中文、英文都能分开识别。常见失败默认只识别英文需要在参数中显式加入中文等语言代码。5.4 测试四批量图片目录识别测试目的验证把多张图片统一输出为文本文件的流程。操作步骤新建一个目录放入 5 张包含文字的 PNG/JPG。写一个循环脚本对每张图执行识别命令并输出到同名.txt。#!/bin/bash # 批量 OCR 通用模板需要按实际命令行参数调整 INPUT_DIR./test_images OUTPUT_DIR./test_outputs mkdir -p $OUTPUT_DIR for img in $INPUT_DIR/*.png $INPUT_DIR/*.jpg; do [ -f $img ] || continue base$(basename $img) name${base%.*} echo processing $img ... monkey-ocr -i $img -o $OUTPUT_DIR/$name.txt done echo all done预期结果每个图片对应一个.txt文件。判断是否成功5 张图全部生成文本文件没有半途退出。常见失败单张图片识别失败导致脚本中断需要加set e或超时控制。5.5 测试五剪贴板输出测试目的确认识别结果可以直接复制到系统剪贴板。操作步骤执行截屏识别。直接使用Cmd V粘贴到文本编辑器。预期结果剪贴板里是纯文本内容不是图片。判断是否成功粘贴后文字可编辑、可搜索。6. 接口 API 与批量任务从项目展示看它更接近一个本地命令行工具不一定自带 HTTP API。但如果你想把它集成到自己的工具链里有几种做法。6.1 命令行即接口命令行本身就是最稳定的接口。在 Python、Ruby、Node 脚本里用subprocess调用识别命令即可import subprocess def ocr_image(image_path: str) - str: 调用项目命令行入口需要按实际命令替换。 result subprocess.run( [monkey-ocr, -i, image_path, --format, text], capture_outputTrue, textTrue, timeout60, checkFalse, ) if result.returncode ! 0: raise RuntimeError(fOCR failed: {result.stderr}) return result.stdout.strip()这种方式的优点是不需要额外起服务资源占用小适合单机脚本任务。6.2 用配置文件管理批量任务如果项目支持从配置文件读取参数可以这样做{ input_dir: ./inputs, output_dir: ./outputs, recognition_languages: [zh-Hans, en], auto_type: false, output_format: markdown }注意上面是通用模板具体字段名要以项目 README 为准。6.3 批量任务队列设计面对大量图片不建议一次性全部灌进去跑。推荐小批量队列图片目录按批次划分每批 50 张。每批处理完生成一个 JSON 日志记录文件名、识别字符数、耗时、失败原因。失败任务单独写入failed.txt下一轮重试。#!/bin/bash # 批量任务带失败重试模板 INPUT_DIR./inputs FAILED_LOG./failed.txt rm -f $FAILED_LOG for img in $INPUT_DIR/*.png; do [ -f $img ] || continue if ! monkey-ocr -i $img -o ${img%.png}.txt; then echo $img $FAILED_LOG fi done echo batch finished. failed count: $(wc -l $FAILED_LOG)6.4 把 OCR 封装成 HTTP 服务如果项目本身没有 API但你又想给其他设备或前端页面调用可以在外部包一层 FastAPI。下面给出通用的服务封装思路不是项目自带能力from fastapi import FastAPI, UploadFile import tempfile import subprocess app FastAPI() app.post(/api/ocr) async def api_ocr(file: UploadFile): suffix file.filename.rsplit(., 1)[-1] with tempfile.NamedTemporaryFile(suffixf.{suffix}, deleteFalse) as f: f.write(await file.read()) tmp_path f.name result subprocess.run( [monkey-ocr, -i, tmp_path, --format, text], capture_outputTrue, textTrue, timeout30, ) return {text: result.stdout}这段代码的目的是说明“可以怎么包装”不是你 clone 下来就能直接跑的项目代码。真正接入前先确认项目是命令行工具还是 App是否有-i、--format这类参数是否需要--screen参数进入截图模式服务运行环境是否拥有屏幕录制和辅助功能权限。7. 资源占用与性能观察macOS 原生 OCR 的推理主要跑在 CPU 和 Apple Neural Engine 上不依赖独立显卡所以不存在“显存占用”问题这一点和本地大模型完全不同。实际部署时重点观察三项指标CPU 占用、内存占用、响应时间。7.1 怎么观察打开 macOS“活动监视器”找到你的项目进程看 CPU 和内存列。通常识别一张 1080p 截图的时间在几秒内具体因 Mac 芯片和图片复杂度而异。建议做一轮对照测试一张纯文字截图一张含复杂背景的文字截图一张高分辨率长截图一张模糊文字截图。记录每张图的耗时和内存峰值。这样能判断项目在什么输入下会变慢。7.2 影响性能的关键因素图片分辨率越高越慢但识别效果通常越好。文字密度一屏密密麻麻的文本比一行大字慢得多。语言数量同时启用多种语言会增加计算量。是否开启自动键入自动键入会占用系统辅助功能通道对识别本身无明显影响但会拉长整体处理时间。7.3 如何降低资源占用截图前先裁剪到有效文字区域不要整屏扫描。批量任务时控制并发数量一次只跑一个进程避免 CPU 满负荷。长任务用后台进程运行不要挂在前台终端。对旧款 Mac准备识别前关闭其他高占用应用。7.4 进程残留与端口冲突命令行工具一般不开端口。但如果项目带有 GUI 或 API 服务进程崩溃后可能残留监听端口。检查方法lsof -i :7860发现残留进程就kill对应 PID。如果端口被占用优先在项目配置里改端口而不是硬杀系统进程。8. 常见问题与排查方法问题现象可能原因排查方式解决方案截图全黑屏幕录制权限未开启系统设置 - 隐私与安全性 - 屏幕录制授权后重启终端或应用识别结果为空图片区域无文字或文字太小放大图片后再试先裁剪图片扩大文字区域自动键入无反应辅助功能权限未开启系统设置 - 隐私与安全性 - 辅助功能授权后重新运行识别串行乱码语言设置中没有目标语言查看语言参数加入中文或目标语言代码编译失败缺少 Xcode Command Line Toolsxcode-select -p运行xcode-select --installgatekeeper 拦截从源码编译的未签名二进制检查启动报错在系统设置中允许运行或重新签名批量任务中途卡住单张图片异常导致进程阻塞查看卡住文件的输出给命令加超时跳过异常文件识别英文没问题中文差默认语言是英文检查语言参数显式添加zh-Hans运行后终端假死截图模式在等待框选看是否有交互提示使用命令行参数传入图片路径API 调用超时图片过大或并发过高查看服务日志控制并发降低单张图片分辨率第 1、2、3 条是最常见的。如果你发现自己已经授权但问题依旧建议退出终端再重新打开因为 macOS 的权限变更并不总是立即生效。9. 最佳实践与使用建议把这类工具放进日常工作流建议按下面这套思路来。9.1 先小后大第一次使用不要直接丢几百张图进去跑。先用 5 张不同风格的图片验证识别质量白底黑字、深色背景、中文、英文、带表格的图文混排。确认项目能正确处理这些场景再逐步扩大。9.2 保持一套最小可运行配置把编译好的二进制、最小测试图片和一条基本调用命令放在同一个目录下。遇到问题可以快速回归测试避免在项目配置里越改越乱。9.3 输入输出分目录管理建议使用固定目录结构project/ ├── bin/ # 编译好的可执行文件 ├── inputs/ # 待识别图片 ├── outputs/ # 识别文本 ├── logs/ # 运行日志 └── failed/ # 失败任务记录批量任务脚本里每次先创建目录避免输出文件写到错误位置。9.4 批量任务三件套日志、超时、重试批量跑之前至少在脚本里加上这三样东西每条任务写日志单张图片命令加超时失败任务单独记录并支持重跑。# 带超时和日志的批量处理示例 TIMEOUT_SEC30 for img in $INPUT_DIR/*.jpg; do [ -f $img ] || continue echo [$(date)] start $img $LOG_FILE timeout $TIMEOUT_SEC monkey-ocr -i $img -o ${img%.jpg}.txt if [ $? -ne 0 ]; then echo $img $FAILED_LOG echo [$(date)] failed $img $LOG_FILE fi done9.5 接口服务安全如果你按前面的模板把它包装成了 HTTP 接口一定要限制访问范围只监听127.0.0.1不要监听0.0.0.0接口加访问令牌限制上传文件大小和格式日志中不要记录完整图片内容只记录文件名、耗时和状态。9.6 合规提醒使用 OCR 工具时注意三点识别内容如果是他人文档、版权素材只用于个人合法用途不要把识别结果批量发布到公开平台除非你确认内容没有版权问题自动键入功能可能被用于自动化操作务必只在你自己有权限控制的设备、账号和应用上使用。10. 总结与下一步这个项目最值得尝试的点是它把 macOS 原生 OCR 和自动化输入串在了一起。你不用理解模型原理不需要 GPU也不需要考虑联网安全问题装好系统授权就能把一段屏幕上的文字变成可以直接编辑、复制的文本。拿到项目后先验证截图识别再验证自动键入最后跑一次多语言和批量目录测试。这三步过了基本就能放进日常工具链。最容易踩的坑有两个一是权限没开导致黑屏或无法输入二是语言参数没配导致中文识别为空。遇到这两个问题优先回系统设置看授权状态。后续可以扩展的方向也明确给项目加一个菜单栏快捷触发写上自己的批量脚本或者把识别结果通过剪贴板自动化接到朗读、翻译、摘录软件里。如果作者后续开放了 API 模式那它的可用性还会再上一个台阶。建议你把这个项目收藏备用等你有批量整理截图文字需求的时候直接按这篇文章的流程部署就行。