dsh-umi-ocr-vision

Readme

# dsh-umi-ocr-vision

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

它参考 [dsh-vision](https://github.com/oil-oil/dsh-vision) 的桥接思路：当主模型只有文本能力时，自动把聊天中的图片交给本地 [Umi-OCR](https://github.com/hiroi-sora/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`）。

## 安装

```sh
# 从本地源码目录安装（当前仓库）
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](https://github.com/hiroi-sora/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 命令行：

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

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

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

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

## 配置

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

```yaml
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 插件，无需构建：

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

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

## License

MIT