macvision

Identified

Apple Vision OCR for DeepSeek Harness — read scans, screenshots and PDFs on-device and hand the text (with coordinates) to the model

MacVision

给 DeepSeek Harness 一个离线、零依赖的 OCR 工具：直接调 macOS 自带的 Vision 框架，把扫描件、截图、拍照文档和 PDF 里的文字，连同逐行坐标一起交给模型。

不需要 API key，不需要联网，不需要装 Python/模型权重。

为什么需要它

DeepSeek 是纯文本模型。图片进来时有三条路可走，各有短板：

路线	短板
云端视觉模型（modlens 一类）	要 key、要联网，票据内容出本机
原生多模态	给不了坐标，长文档容易漏行
本地 OCR 引擎（RapidOCR/Tesseract）	要 Python 环境或 brew 装依赖，包体大

macOS 自带的 Vision 框架把这件事解决了：系统内置、VNRecognizeTextRequest 支持中英阿日韩等语言、单页 0.9 秒、还能给出每行的像素坐标。这个插件就是把它接进 DSH 的工具层。

架构

模型调用 ocr_macos(path)
        │
        ├─ lib/tool.js    参数校验 → 文件指纹缓存 → 结果整形 → 渲染成可引用文本
        ├─ lib/engine.js  找二进制（env → 缓存 → 包内）→ 没有就用 swiftc 现编 → spawn
        └─ swift/macocr.swift
              ├─ 图片：ImageIO 按目标尺寸解码（EXIF 烘进像素）→ 短边放大到 1600 → Vision
              └─ PDF：有文字层就用 PDFKit 直抽（精确、40ms）
                     没有才 CGPDFDocument 渲染 → getDrawingTransform 处理 /Rotate → Vision
                        │
                        └─ 定向探测：0/90/180/270 各跑一次 fast，挑最正的再 accurate 精读

三个刻意的设计：

零运行时依赖。不 import @deepseek-ai/dsh-tools，工具用普通对象注册（与其 defineTool 产物同构）。这样宿主版本升级不会因为 peer 范围把插件卡死——@liustack/modlens 就是被 github: 安装方式坑到 dist 缺失的。
只取字，不做语义。Vision 输出「行 + 坐标 + 置信度」，字段含义交给模型。分工清楚：本地负责快和准，模型负责理解。
结果直接进上下文。render 产出一段带统计头的文本，模型不需要再解析 JSON 就能引用。

和 dsh-mac-vision 的关系

npm 上已有一个同领域插件 dsh-mac-vision（Kevoyuan，2026-08 发布）。两者都用 Apple Vision 在本地做 OCR，但取舍不同：

	MacVision	dsh-mac-vision
PDF	逐页渲染，处理 `/Rotate`，可选页码	未提供
横放扫描件	四向 fast 探测后精读	未提供
运行时依赖	零依赖（纯 JS + 单文件 Swift 二进制）	需 swiftc 编译
屏幕/窗口捕获	无	有（需录屏权限）
附带 Skill	无	有

MacVision 只做一件事：把文档和票据的字读准、把坐标给全。需要抓屏幕的场合请装 dsh-mac-vision。

安装

# 从 npm 安装（推荐）
npm i -g @zaclinley/dsh-macvision
dsh plugin add @zaclinley/dsh-macvision

# 或者从源码
git clone https://github.com/Zac-Linley/macvision.git
cd macvision && npm link
dsh plugin add @zaclinley/dsh-macvision

手工安装（不想用 CLI 时）——编辑 ~/.dsh/profiles/<profile>/package.json：

{
  "dependencies": { "@zaclinley/dsh-macvision": "link:/绝对路径/macvision" },
  "dsh": { "profile": { "bundles": ["…", "@zaclinley/dsh-macvision"] } }
}

然后在 profile 目录 pnpm install，重启 DSH。挂载由包内 cordis.patch.yml 完成，不需要改 cordis.patch.yml 那一层。

只在 macOS 上可用。Linux/Windows 上 apply 会打印一行原因后直接返回，不会注册半残的工具。

工具参数

参数	类型	默认	说明
`path`	string	必填	本地图片或 PDF 路径；URL 会被拒绝
`languages`	string	`en-US`	逗号分隔。中文单据 `zh-Hans`，中英混排 `zh-Hans,en-US`，阿语 `ar-SA`
`mode`	`accurate`/`fast`	`accurate`	fast 快约 3 倍，小字号易掉字符
`pages`	string	全部	PDF 页码，如 `1-3,7`
`dpi`	number	`200`	PDF 渲染分辨率，小字单据可到 300
`minConfidence`	number	`0`	丢弃低置信行
`autoRotate`	boolean	`true`	四向 fast 探测再精读，横放扫描件必备
`boxes`	boolean	`false`	返回每行 `[x,y,w,h]` 像素坐标
`maxChars`	number	`20000`	`text` 的字符上限，超出截断并置 `truncated`
`maxLines`	number	`1000`	带坐标时返回的行数上限；超出部分丢弃并计入 `stats.omittedLines`

返回：text（按阅读序的纯文本）、pages[].lines[]（文本 + 置信度 + 可选坐标）、stats（行数、均置信度、低置信行数、纠正的旋转角、耗时）、truncated。

实测

用一张 1653×2327 的迪拜 proforma invoice（中英阿三语混排）：

项目	结果
拉丁文本	全对：`IBAN:AE290400008882268364901`、两个 15 位 TRN、`2150.00`
阿拉伯文	`اويسيس غاردن ش م ح`（单语 `ar-SA`）
耗时	1.8s（含四向探测）；`--no-auto-rotate` 约 0.9s
文字型 PDF	44ms、12MB，`Invoice 12655` 逐字精确（此前栅格 OCR 会读成 14055）
坐标	49 行全部带框，可用于还原金额列右对齐

跑测试：

node test/smoke.mjs [图片] [PDF]

验证的是注册契约、内容命中、缓存命中、阿语单语、PDF 选页 + 旋转纠正、错误路径。

已知限制

多语言清单会打架。给 en-US,ar-SA 时 Vision 会用第一个语言硬读阿文行，输出 Sent B 之类的垃圾；单给 ar-SA 反而中英阿全对。所以 languages 建议只给主语言，或分次调用。
字母归一化。گ（波斯语 gaf）会被读成 غ，پ 成 ي。这是字体映射差异，不是识别错误，下游做实体匹配前要先归一化。
手写体不可靠。签名、批注这类只有 0.3–0.5 置信度，别当权威值。
印章/水印是物理退化，弧形文字的置信度天然低。
每页位图上限 4000 万像素；超过的畸形 PDF 会被跳过而不是把内存撑爆。
图片按目标长边（≤4000px、≤24MP）解码。JPEG 能在解码阶段降采样；超大 PNG 仍要先解全图（8000² 峰值约 375MB），这是格式决定的，不是没做优化。
带 boxes 时默认最多返回 1000 行，长文档请按需调 maxLines 或配合 pages 分段读。

index.js             插件入口（name / inject / apply）
lib/engine.js        二进制定位、自动编译、spawn、超时与取消
lib/tool.js          工具定义、参数规范化、缓存、结果整形与渲染
swift/macocr.swift   Vision 引擎源码（图片 + PDF + 定向探测）
bin/macocr           预编译二进制（arm64，169KB）
cordis.patch.yml     bundle 挂载层
test/smoke.mjs       冒烟测试

重新编译引擎：

npm run build:engine      # 需要 Xcode Command Line Tools

致谢

PDF 逐页渲染与 getDrawingTransform 的处理方式参考了 schappim/macOCR（2.4k star，Swift 写的菜单栏取字工具）。

Comments

Loading…