本地文字识别 vitas/dsh-ocr-free

dsh-ocr-free

为 DeepSeek Harness 打造的本地 OCR：从截图、照片或扫描件里读出文字，不用联网，也不用 API key。

在 macOS 上，引擎是 Apple Vision，首次使用时从一份 130 行的 Swift 文件编译出来并缓存——所以也什么都不用装。其他平台改用已安装的 tesseract；如果两个引擎都不可用，工具会直接报错并说明原因——绝不会返回空的识别结果。

[ dsh-ocr-free ] engine=vision recognizer=accurate lines=7 time=2.0s
=== text ===
Договор управления Nº 14/2026
Чл. 50, ал. 1 - Общото сьбрание създава етажна собственост

为什么会有这个插件

模型如果声明不支持图片输入，就没法把图片交给它：DSH 会在任何内容写入磁盘之前就拒绝这次粘贴（Model "…" does not support image input、MODEL_DOES_NOT_SUPPORT_IMAGES）。要解决这个问题有两条路。一条是告诉宿主，模型其实接受图片；另一条是把文字交给模型——反正它从图片里能拿到的也只有文字。

这个插件走第二条路，而且只走第二条。它加了两个工具，其他什么都不改——不声明能力，不改写提示词，不覆盖宿主的行。谎报 inputModalities 的插件会改变会话里每个请求的组装方式；而加工具的插件只改变工具列表。

第一条路也值得了解一下，因为它只要一行，而且确实有效：在配置档里的模型条目上声明模态（llm-pi-ai 用 input: [text, image]，DeepSeek 服务商用 inputModalities）。2026-10-01 实测——加上这一行后，在一条手写的 b.ai 路由上，拖进输入框的截图被接受了，模型也读出了它。

安装

from a package
dsh plugin --profile web add dsh-ocr-free

or from a checkout (edits take effect on the next host start)
dsh plugin --profile web add link:~/git/dsh-ocr-free

不需要申请任何豁免，也不需要安装任何引擎。要求 DSH ^0.2.0-rc.2（这是唯一验证过的版本）和 Node 22+。

| 平台 | 引擎 | 你需要什么 |
| macOS | Apple Vision（默认） | Swift 命令行工具：xcode-select --install |
| Linux | tesseract | 发行版提供的 tesseract-ocr，外加语言数据 |
| Windows | tesseract | 未测试——引擎查找解析不到 tesseract.exe（Node 在 spawn 时不会应用 PATHEXT），所以即使装了也会报告引擎缺失 |

所以「零安装」这个说法只对 macOS 成立。在 Linux 上这东西更薄：一层包在 tesseract 外面的壳，额外提供置信度区块、实时设置卡片，以及会说明原因的错误。

工具

ocr_image

| 参数 | 含义 |
| path （必填） | 图片文件：PNG、JPEG、HEIC、TIFF、GIF、BMP |
| langs | 首选语言（Vision 用 ru-RU/en-US；tesseract 用 rus/bul/eng）。省略则用配置好的值；[] 让引擎自己检测文字系统 |
| engine | auto（默认）、vision 或 tesseract —— 每次调用单独指定 |
| fast | 快速识别器（约快 3 倍，仅支持拉丁字母 —— 见下文） |

返回结果是识别出的文本，外加一段头部信息，标明所用引擎和耗时，还有一份单独的列表，列出引擎自己打分低于 lowConfidence 的行：

=== uncertain (confidence < 0.7) ===
[0.50] Чл. 50, ал. 1 - Общото сьбрание създава етажна собственост

这一段正是这个工具的意义所在。OCR 输出不管对错，看起来都一样自信；引擎自己的打分是唯一能区分「读对了」和「猜的」的东西，而在这里测过的样本上，唯一认错的那个字母，恰好落在唯一被打 0.50 的那一行。

ocr_status

报告这台机器能用哪个引擎、为什么，不用读图片。它不会去构建引擎（状态查询不该有这种副作用）—— 它只回答：构建产物是否已经存在、有没有编译器、tesseract 是否已安装。

配置

插件行是 ocr-free；设置卡片可以实时修改这些字段（无需重启）：

| 字段 | 默认值 | 含义 |
| engine | auto | auto 优先用 Vision，失败则回退到 tesseract；固定某个引擎时，失败就报自己的错，不会悄悄切换 |
| langs | [] | [] 表示不做任何特定要求 —— 见下面的语言说明 |
| fast | false | 快速识别器；仅支持拉丁字母 |
| detectLanguage | false | 让 Vision 也猜语言；每张图多花 0.2–0.9 秒 |
| maxChars | 40000 | 截断渲染出的文本（0 = 不设上限）；截断一定会告知 |
| lowConfidence | 0.7 | 低于此值，行会被单独列出（0 = 不显示该段） |
| timeoutMs | 120000 | 每张图的引擎时间预算 |
| dir | "" | 引擎构建目录；"" 表示 ~/.dsh-ocr-free |
| includeEngineLine | true | 头部信息，含引擎、耗时和警告 |

实测行为

以下数据取自 macOS 15.4.1（build 24E263）、Apple 芯片，测试对象是一块 1000×200 的西里尔文字裁剪图，以及一张 824×907 的 UI 截图：

| 场景 | 耗时 | 备注 |
| 1000×200，accurate | 1.6 秒 | 7/7 行正确 |
| 1000×200，accurate + 语言检测 | 1.8 秒 | 输出完全相同 |
| 1000×200，fast | 0.5 秒 | 拉丁字母形近字：Договор управления → oroBOP ynpaBneHMA |
| 824×907 截图，accurate | 3.0 秒 | 38 行 |
| 824×907 截图，accurate + 检测 | 3.9 秒 | 输出完全相同 |

有三点值得记住：

- 快速识别器仅支持拉丁字母。 让它识别西里尔文，它不会报错 —— 它会返回拉丁字母的同形字，而且置信度很高。这一点对任何请求的语言都成立，所以这是该档位的固有属性，不是提示词的问题；fast 默认关闭，只要开启，工具就会反复提醒这个坑。
- 这个构建里，西里尔字母不受语言提示影响。 Vision 的可请求语言列表有 18 项，其中没有一个西里尔标识符，但默认模型能正确读取西里尔字母（脚本检测不受该列表限制）。因此请求 ru-RU 会被静默忽略——这就是为什么 langs: [] 是诚实的默认值，也是为什么报告会列出实际生效的语言。
- 保加利亚语是薄弱环节。 这个构建上的 Vision 把 събрание 读成 сьбрание——ъ→ь——在所有试过的模式里都是如此（accurate、fast、语言检测开/关、强制 bg-BG）。如果你要处理保加利亚语法律文本，安装 tesseract（brew install tesseract tesseract-lang）并传入 engine: "tesseract"；如果缺少语言数据，工具会告诉你。

粘贴的图片：一行修复

粘贴流程并没有被封死——只差一行配置，而且在这个测试样本上，模型反而是更好的读取者。2026-10-01，在一个用完即弃的 DSH 0.2.0-rc.2 配置档上，给一条手写的 b.ai 路由加了一个额外字段：

- id: deepseek-v4.1-flash
name: DeepSeek-V4.1-Flash (b.ai)
input: [text, image]

| 测试样本第 2 行的读取者 | 结果 |
| 通过这个插件的 Apple Vision（accurate，1.7 s） | Общото сьбрание …——ъ 读成 ь，得分 0.50，列为不确定 |
| b.ai 上的 deepseek-v4.1-flash，图片以图片形式发送（8 s，16.2K token） | Общото събрание …——正确，而且它还报告了 № 而不是 Nº、U+2014、м² 和 «» 引号 |

粘贴被接受并持久化，没有出现 MODEL_DOES_NOT_SUPPORT_IMAGES，这个插件也没有打任何补丁。需要的是知道 [text] 默认值从哪来：llm-pi-ai 对目录里没有描述的模型 id 会回退到它，而目录只在阿里云的服务商下认识 deepseek-v4.1-flash——所以私有网关上的 id 正是需要这一行的情况。

所以，如果模型本身就能很好地读取你的图片，声明模态然后跳过这个插件。把它留给模型覆盖不了的情况：按路径读取磁盘上的文件、没有网络也没有密钥、引擎会报告自己的置信度，以及读取结果需要复核时的第二意见。

2026-10-01 又用同样的方式检查了那条路由上的五个 id——deepseek-v4.1-flash、deepseek-v4-flash、qwen3.8-flash、glm-5.3-flash 和 mimo-v2.5——每一个都返回了测试样本的第一行。第六个完全没法测：它的端点响应的是另一套 API（requires /v1/decisions），所以没有为它声明任何东西，而不是靠猜。复制这一行之前有两件事值得知道：思考模型会先把预算花在推理上（glm-5.3-flash 正确读取了图片，但在 max_tokens: 300 时仍然返回空字符串），而为网关不接受图片的 id 声明 image 会让每个请求都变成服务商错误——这就是为什么按模型逐行配置，不放在服务商级别的 defaultInput 里。

它刻意不做的事

- 不声明能力。 在纯文本路由上，宿主会直接拒绝粘贴的图片，不往磁盘写任何东西，所以没有工具能读到它。这个插件把这个决定留在该留的地方——模型条目上，一行就能如实定下来——而不是替一个没声明能力的模型硬说它有。
- 永远不联网。 什么都不离开本机；唯一的子进程是编译好的 Vision 引擎，以及（如果选了）tesseract。
- 不静默失败。 引擎缺失、路径读不了、编译报错、tesseract 语言包缺失，全都作为工具错误报出来，并带上原因。

验证

node --test —— 29 个测试，全部通过，覆盖：配置契约；TSV 解析；错误路径（文件缺失、目录、引擎不可用、引擎名未知）；带块间隔的文本渲染；以及在 macOS 上的真实引擎——编译一次后复用、从真实截图识别西里尔文、无文字图片，还有文档里写的 fast/Latin-only 行为。

在一个一次性的 DSH 0.2.0-rc.2 配置档上端到端跑通（DSH_HOME=/tmp/…）：插件安装不需要版本豁免（不像那些声明 @deepseek-ai/dsh-tools 低于 0.2.0-rc.2 的插件），配置档组出这一行，宿主启动时它处于激活状态，没有加载错误。

随后在该配置档的一个会话里，模型实际调用了这两个工具。ocr_status 报告 platform=darwin selected=vision、vision: available=true languages=18；对西里尔文样本调用 ocr_image，1.7 秒内原样返回七行——引擎在首次使用时编译——其中一行评分偏低，被单独列出：

[dsh-ocr-free] engine=vision recognizer=accurate lines=7 time=1.7s
=== text ===
Договор управления Nº 14/2026
Чл. 50, ал. 1 - Общото сьбрание създава етажна собственост
…
=== uncertain (confidence < 0.7) ===
[0.50] Чл. 50, ал. 1 - Общото сьбрание създава етажна собственост

License

MIT