dsh-ocr — dsh 看图插件

dsh-ocr lets DSH (DeepSeek Harness) "see images" — fully local text recognition and image understanding with no cloud vision routing, so any agent model (including text-only ones) can read images. It also embeds inline image previews in Web GUI tool-result cards.

• ocr_image — macOS Vision framework: millisecond-level OCR returning text lines + pixel coordinates (no Ollama needed)
• view_image — local VLM via Ollama (default qwen2.5vl:3b): describe, transcribe, or Q&A on images with custom prompts
• Client UI registers inline previews (thumbnail + lightbox) for read_image / screenshot / view_image / ocr_image tool cards

---

以下为中文文档 / Chinese documentation below:

让 dsh（DeepSeek Harness）"看图"：本地文字识别与图像理解，不依赖云端视觉路由，任何 agent 模型（含纯文本）都能用；同时在 Web GUI 的工具卡片里内嵌显示图片预览。

功能

工具	引擎	说明
ocr_image	macOS Vision（系统内置）	毫秒级文字识别：返回每行文本 + 像素坐标（左上角原点），无需 Ollama
view_image	Ollama 本地 VLM（默认 qwen2.5vl:3b）	看图理解：默认中文详细描述，支持自定义 prompt（转写/问答）

客户端 UI：为 read_image / screenshot / view_image / ocr_image 的工具结果卡片注册内嵌图片预览（缩略图 + 点击灯箱原图），补上官方"工具结果卡片无内嵌图像预览"的缺口。

安装

前置：macOS（Vision OCR 依赖）、Ollama（brew install ollama）+ 模型（ollama pull qwen2.5vl:3b）。

1. 构建：

npm install && npm run build

2. 挂载到 profile（web 为例）：

cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-ocr

在 $DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 追加 "dsh-ocr"（bundle 通过自身的 dsh.bundle.patch 自动挂载，无需在 profile 的 cordis.patch.yml 加行——加行会因 bundle 自挂载而重复）：

"dsh": { "profile": { "bundles": [ "@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-ocr" ] } }

注意：pnpm add file: 会拷贝插件目录，改代码后需重新 pnpm add 刷新。

3. 重启 dsh web。

一次性试用（不持久化）：dsh web --patch ./cordis.patch.yml。

配置（均可省略，用默认值）

键	默认值	含义
ollamaBaseUrl	http://127.0.0.1:11434	Ollama 服务地址
model	qwen2.5vl:3b	view_image 使用的本地 VLM
keepAlive	30m	模型常驻时长（免冷启动）
requestTimeoutMs	120000	view_image 请求超时
maxImageBytes	20971520	读图字节上限（20MB）
ocrMaxLines	100	ocr_image 默认最大行数

使用示例（agent 提示词里）

• ocr_image file_path="/Users/me/screenshot.png" → 图片里的所有文字 + 坐标
• view_image file_path="docs/diagram.png" prompt="这张架构图有哪些组件？" → 本地 VLM 回答

常见错误与修复

错误	修复
local model service not running: start it with "ollama serve"	启动 Ollama：brew services start ollama 或 ollama serve
model "qwen2.5vl:3b" not found: run "ollama pull qwen2.5vl:3b"	拉取模型
ocr failed (3): cannot load image	图片格式不受支持或文件损坏（PNG/JPEG/WebP/GIF/HEIC）
cannot read "...": ocr_image only accepts …	扩展名不在白名单

三层看图体系

1. ocr_image（Vision，毫秒级，免费离线）→ 纯文字提取
2. view_image（本地 VLM，秒级，离线）→ 语义理解
3. read_image（官方内置，云端视觉路由）→ 模型直接看像素

开发

npm test              # 单元测试（宿主 + 客户端）
DSH_OCR_INTEGRATION=1 npx vitest run tests/integration   # 真实栈集成测试（需 swift + Ollama）
npm run build:host    # tsc → lib/
npm run build:client  # esbuild → lib/client.js（ModuleLoader 格式）

客户端 bundle 支持 HMR：esbuild --watch 或等价 watcher 改写 lib/client.js 时，dsh Web GUI 会无刷新重载该插件（dsh-client-hmr）。

相关文档

• 设计文档
• 实现计划
• 调研：dsh 看图插件实现方案
• 调研：本地识图小模型（M4/16GB）
• 基准测试：Ollama 本地识图