本地截图 OCR uknowmyface/locallens

LocalLens

用 macOS 自带的 Vision OCR 让纯文本模型读截图，图片不出本机。

English · 安全说明 · SECURITY.md

区域截图，对话框里说一声，文字就出来了

非官方社区项目，与 DeepSeek、Apple 无隶属、背书或赞助关系。"DeepSeek"、"Apple"、"macOS"、"Vision" 为各自权利人的商标，此处仅用于说明兼容性。

简介

DeepSeek Harness (dsh) 插件，识别截屏、剪贴板图片、图片文件里的文字。调用 Apple Vision 框架（macOS 实况文本背后的引擎），不经过视觉模型，不需要 API key，不联网。

同类插件（visionDS、dsh-vision-router、dsh-vision-sidecar 等）都是把图交给视觉模型处理。本插件不用模型，因此没有额度、Key 和上传，代价是只能读字、且仅支持 macOS。

| | LocalLens | 视觉模型类插件 |
| 识别方式 | 系统 OCR 引擎 | 视觉模型（云端 / 托管 / 本地 VLM） |
| 图片去向 | 不出本机 | 上传或喂入模型 |
| Key / 注册 / 额度 | 不需要 | 通常需要 |
| 输出 | 图中文字 | 图片描述 |
| 平台 | 仅 macOS | 多数跨平台 |

环境要求

- macOS 13 (Ventura) 及以上。低于 13 时 recognitionLanguages 不可用，languages 参数被忽略，中文精度下降。
- Xcode 命令行工具（xcode-select --install）。首次调用时用 /usr/bin/swiftc 编译 Swift 助手，无需完整 Xcode。
- DeepSeek Harness，Node.js 22+。

安装

dsh plugin --profile web add github:uknowmyface/locallens

包内自带 cordis.patch.yml（由 dsh.bundle.patch 声明），dsh plugin add 会连装带注册一并完成，不修改你自己的 profile 补丁层。web 替换为实际 profile 名。新开会话后生效。

用法

在对话框里直接说。无快捷键、无菜单栏图标、无后台进程。

剪贴板（最常用）：Cmd+Ctrl+Shift+4 拖选区域，截图直接进剪贴板，然后说"看看剪贴板这个报错"。

图片文件："读一下 ~/Desktop/bug.png 里的文字"

整屏："截个屏看看现在屏幕上是什么"。抓取整个主显示器，需要「屏幕录制」权限。

结果落进对话上下文，可直接接续处理：

OCR 剪贴板，把里面的表格整理成 markdown 读一下这个报错截图，然后在项目里搜一下是哪儿抛的

参数

由 agent 填写，列出备查。

| 参数 | 取值 | 说明 |
| source | screen / clipboard / file | 必填，输入来源 |
| path | 文件路径 | source=file 时必填，不做工作区限制 |
| languages | 逗号分隔 BCP-47 | 默认 zh-Hans,en-US |

返回 { text, source, lineCount, warning? }。

配置

改默认语言不需要 fork，在 profile 自己的 cordis.patch.yml 里按 id 覆盖即可（用户层在所有 bundle 层之后应用）：

- id: tool-screenshot-ocr
config:
languages: 'ja,en-US'

隐私边界

留在本机：图片文件和截屏由 Vision 在本地进程读取，不上传。OCR 计算不涉及网络。项目内无遥测、无网络调用。

不留在本机：识别出的文字作为工具结果进入模型上下文，发送给你配置的模型服务商，路径与手动输入的内容相同。

准确表述是"图片不经过第三方视觉服务"，而非"数据完全不上云"。截图内容若不适合粘进对话框，就不要 OCR。

安全说明

OCR 输出属于不可信输入。 文字来自屏幕或图片上的任意内容，可能由第三方构造。dsh agent 具备 shell 和文件系统权限，因此该风险实际存在。插件将结果包裹在 标记内，并在工具描述中要求模型按数据处理而非执行。这是提示词层面的缓解，不构成安全边界。处理来源不明的图片时，应比照"让 agent 访问不可信网站"的谨慎程度。

source=screen 抓取整个主显示器。 无区域或窗口限制，包含聊天窗口背后的全部内容（密码管理器、验证码等）。屏幕含敏感信息时改用 clipboard。区域与窗口截取在计划中。

source=file 无沙箱。 可读取当前用户权限下的任意图片文件。

「屏幕录制」权限按应用授予。 授予终端等同于授予从该终端启动的所有进程，macOS 机制所限，插件无法收窄。clipboard 与 file 不需要任何权限。

漏洞报告见 SECURITY.md。

能力边界

Vision 框架另有约 1300 类的图像分类器、猫狗检测、人脸与条码检测等能力，本插件仅使用 VNRecognizeTextRequest。

分类器返回的是粗粒度标签（dog、document、beach），不是描述。需要理解画面内容时应使用视觉模型，本插件不做替代。

工作原理

1. assets/ocr.swift 是一个基于 VNRecognizeTextRequest 的 Swift CLI，识别精度 .accurate，开启语言矫正。
2. 首次调用时编译为 bin/ocr（约 10 至 20 秒），之后按 mtime 复用。
3. screencapture 截屏，Vision 提取文字，结果以纯文本返回。全流程在设备上完成。

二进制缓存在源码同级目录，可写入插件目录者即可在 dsh 宿主进程中执行代码。该信任边界与 ~/.dsh 其余部分一致。

卸载

dsh plugin --profile web remove @locallens/dsh-tool-screenshot-ocr

包与 bundle 层一并移除，profile 配置无残留。

贡献

欢迎 issue 和 PR。以下方向明确需要，按价值排序：

Windows 版本。 Windows 10+ 内置 Windows.Media.Ocr，与 Apple Vision 同构：系统级 OCR，无模型、无上传、无 Key。工具契约（lib/index.js）可原样复用，只需替换引擎层。这是目前最大的缺口。

区域与窗口截取。 screencapture 支持 -R x,y,w,h 与 -l ，接进 source 参数即可，能显著收窄整屏抓取的数据面。

Linux 版本。 无系统级等价物，可考虑 Tesseract，代价是需要额外安装依赖。

PDF 输入。 目前只接位图，PDF 需先渲染。

多语种实测。 默认 zh-Hans,en-US，其他语种精度未做系统验证。

lib/ocr-engine.js 是引擎层与工具层的分界，跨平台移植从这里切入。

相关项目

- ModLens 等云端视觉插件提供真正的图像理解（场景描述、版面推理、图表解读），这是 OCR 无法覆盖的。需要"看懂"而非"读出"时应使用该类插件。
- macOS 自 Monterey 起内置实况文本，在预览或快速查看中可直接选取图中文字。本插件的作用是把同一能力以程序化方式提供给 agent。

致谢

- 基于 Apple Vision 框架。
- 插件与热重载机制来自 cordis。
- 感谢 DeepSeek Harness 团队的插件架构。

代码由 AI 编写。 初版实现由 DeepSeek 生成，Claude 完成安全审查、包名与安装方式修正、文档重写。作者不写代码，代码未经人类逐行审阅。项目约 800 行、零运行时依赖，建议自行阅读后再决定是否信任。

许可

MIT，见 LICENSE。