前言¶

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. 部署建议: 在敏感环境中部署前，请审查第三方插件源码并锁定版本。