前言¶
在 macOS 上用 DeepSeek Harness（DSH）跑任务时，有一个绕不开的限制：接入的是纯文本模型，模型自己“看不了”任何东西。让它读一张截图里的报错、认一下剪贴板里的图片，都只能靠人先把内容转成文字。
常见的补法有两种：接第三方多模态 API，或者在本地下载一个开源视觉模型。前者要申请 API Key、按次付费；后者要下载并维护模型权重。dsh-mac-vision 提供了第三种选择——直接调用 macOS 内置的 Apple Vision，在本机完成 OCR 和视觉检测，不需要 API Key，也不需要下载第三方模型。
DSH 的理念是“一切皆插件”，视觉能力同样可以做成插件。下面介绍它的定位、能力和接入方式。
它是什么¶
dsh-mac-vision 是由 Kevoyuan 维护的 macOS 原生视觉插件，通过 Apple Vision 为纯文本模型提供本地图片、剪贴板、屏幕和应用窗口的 OCR 与视觉检测能力，采用 MIT License 开源。
插件内部包含两部分：
- 视觉工具：真正执行截图、OCR 和 Apple Vision 检测。
- 内置 Skill：只负责指导模型何时调用视觉工具、如何表达观察和推断，不能独立执行 OCR。
安装插件时两部分一起装好，不需要在 Plugin 和 Skill 之间做选择，也不要另外下载、复制或安装 SKILL.md。
核心能力¶
- 读取本地图片、剪贴板图片、全屏、前台窗口或指定窗口。
- 使用 macOS 内置的 Apple Vision 在本机完成 OCR，无第三方视觉模型下载、API Key 或按次调用费用。
- 返回文本、置信度、坐标、候选结果和复检状态等结构化证据。
- 自动裁剪并放大小字号或公式区域，进行二次 OCR。
- 可选运行图片分类、条码、显著区域、人物和猫狗检测。
- 区分直接观察（Observed）、语义推断（Inferred）和不确定（Uncertain）结果。
- 支持 Harness 取消信号、超时和输出大小限制。
插件向模型注册两个工具：
mac_vision_inspect：分析图片、剪贴板、屏幕或窗口。mac_vision_list_windows：列出可见窗口，便于选择指定窗口。
安装与启用¶
安装前提：
- macOS
- Node.js 22 或更高版本
- 已安装并可运行
dsh的 DeepSeek Harness - Xcode Command Line Tools，或包含 Swift 编译器的 Xcode
如果还没有 Swift 编译器，先运行：
xcode-select --install
然后安装插件：
dsh plugin --profile default add dsh-mac-vision
这一条命令会同时安装视觉工具及其模型使用策略。安装后先验证配置，再启动：
dsh --profile default --dump-config
dsh --profile default
首次执行视觉任务时，插件会用系统 Swift 编译器构建本地 helper 并缓存，之后即可直接使用。
权限方面：读取本地图片不需要屏幕录制权限；读取屏幕或应用窗口时，macOS 可能要求在“系统设置 → 隐私与安全性 → 屏幕录制”中授权运行 DSH 的终端或宿主应用，授权后可能需要重启该应用。
典型用法¶
经过上面的步骤，直接对模型描述任务即可，通常不需要手动调用工具。下面是 README 中的示例：
读取这张图片中的标题和主要内容：/absolute/path/to/slide.png
看看当前前台窗口显示了什么，并区分直接看到的内容和你的推断。
读取剪贴板图片中的文字，无法确认的内容请明确标出。
列出当前窗口，然后检查浏览器窗口中的错误信息。
检查这张截图中是否有二维码，并提取可见文本：/absolute/path/to/image.png
模型返回的结果会区分三层：
- Observed / 直接观察：OCR 或已完成的检测器直接返回的证据。
- Inferred / 推断：根据布局、文本位置或多个观察作出的解释。
- Uncertain / 不确定：冲突的 OCR、无法验证的公式或没有运行的检测器。
如果 OCR 小字或公式不准确，可以让模型重新检查具体区域，并明确要求保留不确定项。
配置¶
大多数用户不需要修改配置。默认值位于插件的 cordis.patch.yml：
config:
timeoutMs: 45000
maxOutputBytes: 8388608
defaultMode: fast
defaultLanguages: []
defaultRefineText: true
defaultRefineLimit: 12
defaultRefineScale: 3
allowedSources: [file, clipboard, screen, front-window, window]
可以在 profile 的 cordis.patch.yml 中覆盖设置。注意 Harness patch 会替换整个 config，而不是逐项深度合并，因此覆盖时需要重写完整配置块。例如只允许读取本地文件：
allowedSources: [file]
更新与卸载¶
更新到最新版本：
dsh plugin --profile default update dsh-mac-vision
卸载：
dsh plugin --profile default remove dsh-mac-vision
如果使用了其他 profile，把命令中的 default 替换为对应名称即可。
适用场景与注意事项¶
适合的用户：
- 在 macOS 上使用 DSH，希望模型能读图片、读剪贴板、读屏幕和窗口。
- 不想申请第三方 OCR / 视觉 API，也不想下载和维护视觉模型。
- 在意图片外流：截图、OCR 与视觉检测全部在本地完成，图片不会发送给第三方 OCR 或视觉服务。
使用前注意：
- 插件以当前 dsh 进程的权限运行，它能访问的本地文件、剪贴板和屏幕内容都受这个权限约束。安装前建议检查插件源码与许可证（MIT），确认符合自己的安全要求。
- 需要读屏幕或窗口时，先完成上文提到的“屏幕录制”授权。
- 插件的视觉能力免费且在本地完成；DeepSeek Harness 所使用的语言模型及其服务是否收费，取决于你自己的 Harness 配置，与该插件无关。
小结¶
对 DSH 用户来说，dsh-mac-vision 解决的是一个很具体的问题：用一行安装命令，让纯文本模型在 macOS 本机获得读图和读屏的能力，没有 API Key、没有按次调用费用，图片也不出本机。相关链接：
- GitHub 仓库：https://github.com/Kevoyuan/dsh-mac-vision
- 社区插件目录：https://www.skillhub.cn/plugins/Kevoyuan/dsh-mac-vision （社区独立站点，与 DeepSeek / 幻方无官方从属关系）
