前言¶
DeepSeek Harness（DSH）里的模型本质是纯文本：扫描件、截图、PDF 若直接丢进对话，要么走云端视觉 API（要 key、内容出本机），要么靠多模态能力（往往没有逐行坐标，长文档易漏行），要么再装一套本地 OCR（Python、brew 或大包体权重）。在 macOS 上，系统自带的 Vision 框架已经提供 VNRecognizeTextRequest，支持多语言、较快单页识别，并能给出行级像素坐标。下面介绍社区插件 MacVision（@zaclinley/dsh-macvision）如何把这条路径接进 DSH 工具层，让模型在本地拿到可读文本和可选坐标，而无需 API key 与联网。
这是什么¶
MacVision 由维护者 Zac-Linley 发布，npm 包名 @zaclinley/dsh-macvision，当前版本 0.1.1（MIT 许可证）。定位是：Apple Vision OCR for DeepSeek Harness——在本机读取扫描件、截图、拍照文档和 PDF，把文字（以及可选的逐行坐标）交给模型。
插件只在 macOS 上生效：package.json 中 os 为 darwin；在 Linux 或 Windows 上 apply 会说明原因后直接返回，不会注册半成品工具。Node 引擎要求为 ^22.19.0 || >=24.0.0。
核心功能¶
模型侧通过工具 ocr_macos(path) 调用 OCR。整体分层如下：
模型调用 ocr_macos(path)
│
├─ lib/tool.js 参数校验 → 文件指纹缓存 → 结果整形 → 渲染成可引用文本
├─ lib/engine.js 找二进制（env → 缓存 → 包内）→ 没有就用 swiftc 现编 → spawn
└─ swift/macocr.swift
├─ 图片：ImageIO 解码 → 短边放大到 1600 → Vision
└─ PDF：有文字层用 PDFKit 直抽；无文字层则渲染并处理 /Rotate → Vision
└─ 可选四向 fast 探测后再 accurate 精读（横放扫描件）
设计上强调三点（均来自项目 README）：
- 零运行时依赖：不依赖
@deepseek-ai/dsh-tools的 peer 包，用普通对象注册工具，避免宿主升级时因安装方式导致插件不可用。 - 只取字，不做语义：Vision 输出「行 + 坐标 + 置信度」，理解交给模型。
- 结果直接进上下文：
render产出带统计头的文本，模型无需再解析 JSON 即可引用。
与同领域 npm 插件 dsh-mac-vision 相比，MacVision 侧重 PDF 逐页渲染、/Rotate 与可选页码、横放扫描件的四向探测；不提供屏幕/窗口捕获（该能力在 dsh-mac-vision）。需要抓屏时请选用后者。
安装与启用¶
推荐从 npm 全局安装并注册到 DSH：
npm i -g @zaclinley/dsh-macvision
dsh plugin add @zaclinley/dsh-macvision
不用 CLI 时，可编辑 ~/.dsh/profiles/<profile>/package.json，在 dependencies 中声明 @zaclinley/dsh-macvision，并在 dsh.profile.bundles 中加入该包名，于 profile 目录执行 pnpm install 后重启 DSH。挂载由包内 cordis.patch.yml 完成。
安装前应自行查看 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限读取本地路径，只应对可信文件调用。
工具参数与典型用法¶
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | 必填 | 本地图片或 PDF；URL 会被拒绝 |
languages |
string | en-US |
逗号分隔；中文单据常用 zh-Hans，中英混排 zh-Hans,en-US |
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 上限 |
maxLines |
number | 1000 |
带坐标时的行数上限 |
返回字段包括 text、pages[].lines[]、stats（行数、均置信度、旋转纠正、耗时等）、以及可能的 truncated。
README 中的冒烟测试可在插件目录执行：
node test/smoke.mjs [图片] [PDF]
包内还提供 CLI 二进制 macvision-ocr（对应 bin/macocr）。重新编译 Swift 引擎需要 Xcode Command Line Tools：
npm run build:engine
适用场景与注意¶
适合：在 Mac 上处理票据、发票、扫描 PDF，希望文本与坐标留在本机、且不想维护 Python OCR 栈的 DSH 用户；有文字层的 PDF 可走 PDFKit 直抽（README 示例：约 44ms、12MB 文件）。
务必知晓的限制（摘自 README）：
languages多语言同时给时 Vision 可能用第一种语言硬读其他语系行；建议只给主语言或分次调用。- 波斯语部分字母会与阿拉伯字体映射差异导致归一化问题；手写、印章、水印置信度低，不宜当权威值。
- 超大 PNG 解码内存峰值高；带
boxes时长文档需调maxLines或配合pages分段。
社区目录页：SkillHub — Zac-Linley/macvision。DSH 生态强调「一切皆插件」，该目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
MacVision 把 macOS Vision 接到 DSH：离线、零 API、可选行坐标，PDF 与横放扫描有专门处理。安装以 npm i -g @zaclinley/dsh-macvision 与 dsh plugin add @zaclinley/dsh-macvision 为准；细节与限制以 GitHub README 为准。
