paul-yangmy / dsh-umi-ocr-vision

dsh-umi-ocr-vision

DeepSeek Harness 的 Umi-OCR 视觉桥接插件。

它参考 dsh-vision 的桥接思路：当主模型只有文本能力时，自动把聊天中的图片交给本地 Umi-OCR 识别为文字，再把 OCR 结果作为“非可信视觉上下文”注入请求，最后由原来的 DeepSeek 文本模型完成回答。

Umi-OCR 是离线 OCR 工具，提供的是文字识别能力，不是完整的多模态语义理解。对于纯截图、文档、验证码、界面文字等场景非常合适；如果图片需要理解空间关系、物体语义，请改用真正的视觉大模型插件（例如 dsh-vision）。

工作原理

当前主模型	图片处理方式	最终回答者
支持图片	原图直接发送，不经过 Umi-OCR	当前模型
deepseek-official 等文本模型	Umi-OCR 读取原图，OCR 文本作为非可信附件上下文注入	DeepSeek

• 插件不会替换你在界面中选择的主模型。
• 多张聊天附件会按顺序分别 OCR，然后一起放入同一次 DeepSeek 请求。
• OCR 结果被标记为“非可信观察数据”，图片中出现的提示词不会获得系统权限。
• 不把图片发送到任何云端服务（HTTP 模式也默认只访问本机 127.0.0.1）。

安装

# 从本地源码目录安装（当前仓库）
dsh plugin --profile web add /path/to/dsh-umi-ocr-vision

# 或打包成 tgz 后安装
dsh plugin --profile web add ./dsh-umi-ocr-vision-0.1.0.tgz

安装后重启 Harness。

准备 Umi-OCR

1. 下载并启动 Umi-OCR。
2. 确认 Umi-OCR 的 HTTP 服务已开启：默认监听 http://127.0.0.1:1224。
   • 如果关闭了 HTTP 服务，请到 Umi-OCR「全局设置」中开启。
3. 可先用浏览器访问 http://127.0.0.1:1224/api/ocr/get_options 验证服务可用。

CLI 模式（可选）

如果你不想开 HTTP 服务，也可以让插件直接调用 Umi-OCR 命令行：

# settings.yaml 中 llm-deepseek 段落（或插件配置卡片）
llm-deepseek:
  umiOcrMode: cli
  umiOcrCommand: "C:/Umi-OCR/Umi-OCR.exe"

CLI 模式会先把图片写入临时目录，再执行：

Umi-OCR.exe --path <image> --output <result.txt>

然后读取输出文件。CLI 模式需要 Umi-OCR 支持命令行调用。

配置

在 $DSH_HOME/settings.yaml 的 llm-deepseek 段落中配置（不需要重启）：

llm-deepseek:
  umiOcrBaseURL: http://127.0.0.1:1224   # Umi-OCR HTTP 地址
  umiOcrMode: http                        # http 或 cli
  umiOcrCommand: ""                       # cli 模式时填写 Umi-OCR.exe 路径
  umiOcrTimeoutMs: 120000                 # 单张图片 OCR 超时（毫秒）
  maxImages: 8                            # 单次请求最多处理图片数
  cacheEntries: 64                        # OCR 结果缓存条数
  dataFormat: text                        # 说明：桥接和工具统一使用 Umi-OCR dict 格式以获取文本坐标；dataFormat 配置保留兼容但不再影响行为。
  ocrLanguage: 简体中文                    # Umi-OCR 语言/模型库（Rapid 版用 "简体中文"）
  ocrCls: false                           # 是否启用方向纠正
  ocrLimitSideLen: 960                    # 图像边长限制
  tbpuParser: multi_para                  # 排版解析方案
  enableVisionTools: true                 # 是否启用 vision_* 工具集
  artifactDir: .dsh-umi-vision/artifacts  # vision_* 工具产物输出目录
  longImageMaxHeight: 4096                # 长截图分块时单块最大高度
  longImageOverlap: 80                    # 长截图分块重叠像素

也可以直接在 Harness「设置 → 插件 → 插件配置」中修改同一份配置。

工具集

启用 enableVisionTools: true 后，插件会导出 createVisionTools，向 Harness 注册以下 vision_* 工具：

• vision_ocr: 对图片执行 Umi-OCR，返回全文和行级坐标。
• vision_glance: 快速查看图片，返回尺寸和可见文本。
• vision_detect_text: 列出所有文本块及原始坐标。
• vision_ground_text: 按文本定位元素，返回 x1,y1,x2,y2，可生成裁剪预览。
• vision_crop: 裁剪图片区域并输出 PNG。
• vision_long_screenshot_ocr: 长截图分块 OCR，合并 Markdown 并保存 manifest。
• vision_dominant_colors: 分析主色调并返回 HEX 调色板。
• vision_pixel_diff: 对比两张图片，返回差异百分比、差异区域和可选热力图。

vision_* 工具的 artifacts 默认输出到 .dsh-umi-vision/artifacts。

sharp 是可选依赖。未安装时，OCR 类工具和自动桥接仍可用（自动桥接会退化为直接整图 OCR，不做长图分块）；vision_crop、vision_dominant_colors、vision_pixel_diff、vision_long_screenshot_ocr 等图像处理工具需要安装 sharp。

开发

纯 JS 插件，无需构建：

node --check lib/index.js
node test/smoke.mjs

冒烟测试只检查插件导出契约，不要求 Umi-OCR 已运行、不需要 API Key。

License

MIT