macOS 本地视觉 Kevoyuan/dsh-mac-vision

dsh-mac-vision

面向 DeepSeek Harness 的 macOS 原生视觉插件。它通过 Apple Vision 为纯文本模型提供本地图片、剪贴板、屏幕和应用窗口的 OCR 与视觉检测能力。

- 完全免费、开源：插件采用 MIT License，不收取订阅费或按次调用费。
- 完全本地处理：截图、OCR 与视觉检测均在 Mac 上完成，图片不会发送给第三方 OCR 或视觉服务。
- 无需下载第三方模型：直接使用 macOS 内置的 Apple Vision，不需要安装或维护额外的视觉模型及其权重。
- 无需第三方 API：不需要申请 OCR、Vision 或多模态模型 API Key，也不会产生这类 API 调用费用。

以上说明针对 dsh-mac-vision 的视觉能力。DeepSeek Harness 所使用的语言模型及其服务是否收费，取决于用户自己的 Harness 配置。

快速开始

1. 安装插件

dsh plugin --profile default add dsh-mac-vision

这一个命令会同时安装视觉工具及其模型使用策略。不要另外下载、复制或安装 SKILL.md。

2. 验证并启动

dsh --profile default --dump-config
dsh --profile default

首次执行视觉任务时，插件会用系统 Swift 编译器构建本地 helper 并缓存。之后可以直接对模型说：

读取这张图片中的标题和主要内容：/absolute/path/to/slide.png

或者：

看看当前前台窗口显示了什么，并区分直接看到的内容和你的推断。

安装前提

- macOS
- Node.js 22 或更高版本
- 已按照 DeepSeek Harness 入门指南安装，并可运行 dsh
- Xcode Command Line Tools，或包含 Swift 编译器的 Xcode

如果尚无 Swift 编译器，可以运行：

xcode-select --install

读取本地图片不需要屏幕录制权限。读取屏幕或应用窗口时，macOS 可能会要求在“系统设置 → 隐私与安全性 → 屏幕录制”中授权运行 DeepSeek Harness 的终端或宿主应用；授权后可能需要重启该应用。

它是一个插件

用户只需安装 dsh-mac-vision，不需要在 Plugin 和 Skill 之间做选择。

插件内部包含：

- 视觉工具：真正执行截图、OCR 和 Apple Vision 检测。
- 内置 Skill：仅用于指导模型何时调用视觉工具，以及如何表达观察、推断和不确定结果。

Skill 不能独立执行 OCR，它只是随原生插件自动加载的模型使用说明，不是第二个产品或第二个安装步骤。

能力

- 免费使用 Apple Vision，无第三方视觉模型下载、API Key 或按次调用费用。
- 读取本地图片、剪贴板图片、全屏、前台窗口或指定窗口。
- 使用 macOS Vision 在本机完成 OCR。
- 返回文本、置信度、坐标、候选结果和复检状态等结构化证据。
- 自动裁剪并放大小字号或公式区域，进行二次 OCR。
- 可选运行图片分类、条码、显著区域、人物和猫狗检测。
- 区分直接观察、语义推断、冲突 OCR 和未运行的检测器。
- 支持 Harness 取消信号、超时和输出大小限制。

插件向模型注册两个工具：

- mac_vision_inspect：分析图片、剪贴板、屏幕或窗口。
- mac_vision_list_windows：列出可见窗口，以便选择指定窗口。

通常不需要手动调用工具；直接描述任务，模型会按需选择。

更多使用示例

读取剪贴板图片中的文字，无法确认的内容请明确标出。

列出当前窗口，然后检查浏览器窗口中的错误信息。

检查这张截图中是否有二维码，并提取可见文本：/absolute/path/to/image.png

模型的结果应区分：

- Observed / 直接观察：OCR 或已完成检测器直接返回的证据。
- Inferred / 推断：根据布局、文本位置或多个观察作出的解释。
- Uncertain / 不确定：冲突 OCR、无法验证的公式或没有运行的检测器。

更新与卸载

更新到最新版本：

dsh plugin --profile default update dsh-mac-vision

卸载：

dsh plugin --profile default remove dsh-mac-vision

如果使用了其他 profile，请将 default 替换为对应名称。

配置

大多数用户不需要修改配置。默认值位于 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]

故障排查

- 提示找不到 Swift 编译器：运行 xcode-select --install，安装完成后重试。
- 能读文件但不能读屏幕或窗口：检查 macOS“屏幕录制”权限，并重启终端或 Harness 宿主。
- 确认插件是否加载：运行 dsh --profile default --dump-config，查找 dsh-mac-vision、mac-vision-tools 和 mac-vision-skill。
- OCR 小字或公式不准确：要求模型重新检查具体区域，并明确保留不确定项。

本地开发

以下内容仅供贡献者使用，普通安装不需要 clone 仓库、运行 pnpm 或手动打包。

git clone https://github.com/Kevoyuan/dsh-mac-vision.git
cd dsh-mac-vision
pnpm install
pnpm check

从 DeepSeek Harness 源码仓库开发时，可以用绝对路径创建 overlay：

- insert:
- id: mac-vision-tools
name: '/absolute/path/to/dsh-mac-vision/src/index.ts'
- id: mac-vision-skill
name: '/absolute/path/to/dsh-mac-vision/src/skill.ts'

然后从 Harness 仓库启动：

pnpm dsh web --patch /absolute/path/to/overlay.yml

这两个 Cordis 入口属于同一个原生插件。通过 npm 正常安装时，它们会自动加载，用户无需手动配置。

链接

- npm 包
- GitHub 仓库
- DeepSeek Harness 插件安装文档

反馈与贡献

遇到问题或希望增加能力，请提交 GitHub Issue。提交代码前请先运行 pnpm check。

License

MIT