前言¶

DeepSeek Harness (DSH) 是一個插件驅動的智能體運行環境。在構建能夠處理本地文件的智能體時，經常會遇到需要從圖片中提取文本的場景。如果調用外部 OCR API，不僅需要網絡請求，還涉及密鑰管理。dsh-macos-vision-ocr 插件利用 Apple 的 Vision 框架，在本地提供離線 OCR 能力，無需網絡請求即可讀取圖片內容。

插件介紹¶

名稱: dsh-macos-vision-ocr
核心價值: 基於 macOS Vision 框架的離線文本識別工具，爲 DSH 提供讀取圖片的能力。
維護者: leozou320-ai
許可: MIT

核心功能¶

該插件提供 ocr_image 工具，具備以下特性：

1. 本地識別: 使用 VNRecognizeTextRequest 進行文本識別，默認精度較高。
2. 格式支持: 支持常見的圖片格式，包括 PNG, JPEG, WebP, GIF, TIFF, BMP, HEIC 和 HEIF。
3. 多語言: 支持在每次調用時指定 BCP-47 識別語言代碼。
4. 安全執行: 使用固定的子進程參數向量，圖片路徑不直接拼接進 Shell 命令，防止注入風險。
5. 緩存機制: 在首次使用時編譯嵌入的 Swift 輔助程序，之後通過內容尋址緩存複用，避免重複編譯。
6. 輸出控制: 返回有界的輸出結果，並附帶 truncated 標誌，告知識別文本是否被截斷。

安裝與啓用¶

在 DSH 中安裝插件需要指定目標 profile：

dsh plugin --profile web add github:leozou320-ai/dsh-macos-vision-ocr

安裝完成後需要重啓該 profile 才能生效。

典型用法¶

有兩種方式使用該工具：

1. 顯式調用: 在配置的 JSON 工具調用中傳入參數。
2. Agent 交互: 直接向 Agent 發出“讀取這張圖片”的指令。

顯式調用的示例：

{
  "file_path": "./scan.png",
  "languages": ["zh-Hans", "en-US"]
}

注意事項與限制¶

1. 環境要求: 必須運行在 macOS 13 或更高版本，系統需安裝 Xcode Command Line Tools（swiftc 命令需在 PATH 中），且 DeepSeek Harness 版本需在 0.1.0-rc.5 或更高。
2. 系統兼容性: 由於依賴 Apple Vision，該插件僅在 macOS 上可用。在 Linux 和 Windows 上會因缺少底層框架而失敗。
3. 首調用延遲: 首次調用工具時較慢，因爲需要編譯 Swift 輔助程序；後續調用會讀取緩存，速度較快。
4. 隱私與安全:
   • OCR 完全在本地運行，不會發起任何網絡請求。
   • 圖片路徑在運行原生輔助程序前會經過 Harness 的文件系統服務檢查。
   • 識別出的文本會作爲工具輸出進入當前會話記錄和模型上下文。
5. 功能邊界: 該插件僅提取文本，不具備通用視覺理解能力（如識別物體、人臉或場景）。
6. 部署建議: 在敏感環境中部署前，請審查第三方插件源碼並鎖定版本。