dsh-ocr

Readme

# dsh-ocr — dsh 看图插件

**dsh-ocr** lets [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/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](https://ollama.com)（`brew install ollama`）+ 模型（`ollama pull qwen2.5vl:3b`）。

1. 构建：

```bash
npm install && npm run build
```

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

```bash
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 自挂载而重复）：

```jsonc
"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`**（官方内置，云端视觉路由）→ 模型直接看像素

## 开发

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

## 相关文档

- [设计文档](docs/superpowers/specs/2026-08-15-dsh-ocr-design.md)
- [实现计划](docs/superpowers/plans/2026-08-15-dsh-ocr.md)
- [调研：dsh 看图插件实现方案](docs/调研报告-dsh看图插件实现方案.md)
- [调研：本地识图小模型（M4/16GB）](docs/调研报告-本地识图小模型-M4-16GB.md)
- [基准测试：Ollama 本地识图](docs/基准测试报告-Ollama本地识图.md)