前言¶
在 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 / 幻方無官方從屬關係）
