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）。

构建：

npm install && npm run build

挂载到 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 刷新。

重启 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 …`	扩展名不在白名单

三层看图体系

ocr_image（Vision，毫秒级，免费离线）→ 纯文字提取
view_image（本地 VLM，秒级，离线）→ 语义理解
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-ocr

安装

说明文档

dsh-ocr — dsh 看图插件

功能

安装

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

使用示例（agent 提示词里）

常见错误与修复

三层看图体系

开发

相关文档