dsh-mac-vision

English

面向 DeepSeek Harness 的 macOS 原生视觉插件。它让纯文本模型能够按需读取本地图片、剪贴板、屏幕和应用窗口，并通过 Apple Vision 在设备本地完成 OCR 与视觉检测。

这是一个插件，不是两份产品

用户只需安装一次 dsh-mac-vision 原生插件。

插件包含两个协同部分：

• 原生工具层：真正执行屏幕捕获、OCR 和 Vision 检测，并向模型注册 mac_vision_inspect 与 mac_vision_list_windows。
• 内置使用策略：以 Harness Skill 的形式随插件自动注册，指导模型何时调用工具，以及如何区分直接观察、语义推断和不确定 OCR。

内置 Skill 不是另一个需要安装、启用或选择的产品。它不能独立完成 OCR，也不与插件竞争；它只是插件附带的模型使用说明。

dsh-mac-vision 原生插件（安装一次）
├── Native Tools：提供 macOS Vision 能力
└── Bundled Skill：指导模型可靠使用这些工具

能力

• 读取本地图片、剪贴板图片、全屏、前台窗口或指定窗口。
• 使用 macOS Vision 进行本地 OCR。
• 返回文本、置信度、坐标、候选结果和复检状态等结构化证据。
• 自动裁剪并放大可疑的小字号或公式区域进行二次 OCR。
• 可选运行图片分类、条码、显著区域、人物和猫狗检测。
• 明确区分 not_requested、没有检测结果和 OCR 冲突。
• 支持 Harness 工具取消信号、超时和输出大小限制。
• 所有图像分析均在本机完成，不需要上传到视觉模型服务。

模型可调用的工具：

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

系统要求

• macOS
• Node.js 22 或更高版本
• DeepSeek Harness
• Xcode Command Line Tools 或包含 Swift 编译器的 Xcode

第一次调用时，插件会将随包提供的 Swift helper 编译到 macOS 用户缓存。屏幕和窗口捕获可能需要在“系统设置”中授予 DeepSeek Harness 屏幕录制权限。

安装

先在项目目录构建 tarball：

pnpm install
pnpm pack

然后将生成的包安装进一个 DeepSeek Harness profile：

dsh plugin --profile default add ./dsh-mac-vision-0.1.0.tgz
dsh --profile default --dump-config
dsh --profile default

tarball 已包含编译后的 JavaScript，因此安装时不需要授权 git 依赖执行 prepare 构建脚本。安装插件后，原生工具和内置使用策略会一起加载，无需再复制或安装 SKILL.md。

使用示例

安装后可以直接向模型提出依赖视觉信息的任务，例如：

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

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

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

模型会根据内置策略选择最窄的图像来源，并在结果中区分：

• Observed：OCR 或已完成检测器直接返回的证据。
• Inferred：根据布局、文本位置或多个观察作出的解释。
• Uncertain：冲突 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 禁止部署不希望模型使用的捕获来源。例如只允许本地文件：

allowedSources: [file]

本地开发

pnpm install
pnpm check

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

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

然后从 Harness 仓库启动：

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

这里的两行是同一原生插件的两个 Cordis 入口：第一行注册工具，第二行注册随附策略。正式安装 bundle 时，这两行由插件自动贡献，用户无需手动配置。

验证

pnpm typecheck
pnpm test
pnpm pack

测试覆盖参数转换、原生 helper、真实 Cordis 工具执行管线和 Harness Skill 注册表。