dsh-vision-ocr

让 DeepSeek Harness 直接「读懂」图片里的文字 —— 本地离线 OCR 插件，无需视觉模型，不弹「模型不支持图片」。

Give DeepSeek Harness the ability to read text from images — a fully offline, free, local OCR plugin. No vision-capable model required, no more "current model does not support images" errors.

目录 / Contents

简介
核心特性
技术构成（30 秒看懂）
安装
使用
配置
自检与测试
常见问题
目录结构
许可与致谢
English

简介

DeepSeek 系列模型（deepseek-chat / deepseek-reasoner 等）不支持图片输入。在 DeepSeek Harness 里发一张截图，会得到「当前模型不支持图片，请切换支持图片的模型」的弹窗。

dsh-vision-ocr 把这个流程变成：发图 → 一键 OCR → 图片变成文字 → 模型直接回答。整个过程在本机完成，完全免费、完全离线，不消耗 API 额度，不上传任何图片。

核心特性

🖼️ 聊天窗口一键识别：在输入框附件栏点击「OCR 识别」，图片自动转为文字草稿，发送后模型直接读懂内容——彻底告别"模型不支持图片"弹窗。
🤖 模型自带 OCR 工具：注册 ocr_image 模型工具，智能体可随时读取工作区里任意图片的文字（截图、扫描件、照片）。
⚡ 双引擎自动回退：优先使用识别精度更高的 PaddleOCR-json；若引擎缺失或硬件不支持（CPU 无 AVX），自动回退 RapidOCR-json，无需任何配置。
📦 引擎随包安装、按系统自动分流：引擎封装为按平台过滤的 npm 子包（Windows：dsh-vision-ocr-engines-paddle-win-x64 + -rapid-win-x64；Linux：-linux-x64，各自声明 os/cpu），主包通过 optionalDependencies 引用——npm/pnpm 安装时自动只下载当前系统对应的包（Windows 合计 ~198 MB 含双引擎；Linux ~118 MB），引擎就在 node_modules 里，运行时零下载，不依赖 GitHub，不走代理。
🌏 多语言识别：简中、繁中、英、日、韩、俄，随官方语言库开箱即用。
💻 Windows x64 / Linux x64 双平台，零依赖（插件本体不引入任何 npm 运行时依赖）。
🔒 本地运行、隐私安全：图片不离开你的电脑。

技术构成（30 秒看懂）

┌─────────────────────────────────────────────────────────┐
│  DeepSeek Harness（Web 界面 + 宿主进程）                    │
│                                                         │
│  ┌──────────────────────┐      ┌──────────────────────┐ │
│  │  浏览器端 (client)      │      │  宿主端 (host)         │ │
│  │  「OCR 识别」按钮         │ HTTP │  1. ocr_image 模型工具  │ │
│  │  → 读取草稿图片          │─────▶│  2. /dsh-vision-ocr/  │ │
│  │  → 发送 base64 给宿主    │      │     ocr 路由           │ │
│  └──────────────────────┘      └──────────┬───────────┘ │
│                                           ▼             │
│  ┌───────────────────────────────────────────────────┐  │
│  │ 引擎层（随 npm 包按平台自动安装，完全离线）                │  │
│  │  安装时：包管理器按 os/cpu 只装本平台引擎子包            │  │
│  │  运行时：PaddleOCR-json（首选）→ RapidOCR-json（回退）  │  │
│  │  执行 exe → 解析 JSON → 输出纯文本                    │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

插件 = 一个 npm 风格包（本仓库根目录即包根目录，仓库本体约 1 MB），含三个部分：
1. 宿主半区 lib/：注册 ocr_image 模型工具、注册 /dsh-vision-ocr/ HTTP 路由、定位引擎并 spawn、解析结果；
2. 浏览器半区 client/client.js：往输入框工具行（conversation.input.left 插槽）注入「OCR 识别」按钮；
3. 引擎分发：两个平台引擎子包（见 engines/README.md），通过 optionalDependencies + os/cpu 声明由包管理器按系统安装——装完即用，运行时不需要任何下载。GitHub Release 资产仅作为无 npm 子包时的兜底来源。
调用方式完全照官方文档示例：PaddleOCR-json.exe -image_path=图片 / RapidOCR-json.exe --image_path=图片，单次启动、识别一次、退出，stdout 输出一行 JSON（code:100 + data[].text），插件解析后按行拼接为文本。
零 npm 运行时依赖：插件本体只 import DSH 自带的 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools（每个 DSH profile 都内置），以及 Node 内置模块。

安装

前置条件：已安装 DeepSeek Harness（Web 模式）。插件只在 profile 层生效。下面任一方式二选一，不要叠加。

📌 如果你正在由 DeepSeek 智能体按本 README 自动安装：不要执行会重启 dsh 进程的命令 （会中断当前会话）；安装/配置完成后，告诉用户需要手动重启 dsh 才能生效。

方式一（最推荐）：一句话，让 DeepSeek 自己装 🪄

在 DeepSeek Harness 的对话输入框里粘贴下面这句话，回车即可：

按 https://github.com/timeflies-qyh/dsh-vision-ocr 的 README 安装并配置 dsh-vision-ocr 插件，完成后运行自检（scripts/test-ocr.mjs）并把结果告诉我。

DeepSeek 会自动阅读 README、定位 profile 目录、执行安装（dsh plugin add 或 pnpm add + 写 bundles）、跑自检验证——你只需要最后手动重启一次 dsh。

方式二：官方命令（一条命令装好）

用 DSH 自带的插件管理命令（在任意目录执行即可，命令会自动定位 profile 并在其中执行 pnpm）：

dsh plugin --profile web add dsh-vision-ocr

这条命令会自动完成两步：

在 profile 目录安装 dsh-vision-ocr；
自动识别到本插件声明了 dsh.bundle，自动把包名写进 profile package.json 的 dsh.profile.bundles（无需手动编辑）。

重启 dsh 即可生效。（若你装了 dshmarket 可视化市场，市场点安装同样走此命令，且本插件是"简单补丁"，可热挂载免重启，刷新页面即生效。）

方式三：npm 手动安装（没有 dsh 命令时）

在 profile 目录执行：

pnpm add dsh-vision-ocr

然后手动把包名加进 profile 的 package.json 的 dsh.profile.bundles 列表（插件自带的 cordis.patch.yml 会自动插入插件行）：

// profiles/web/package.json
{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dshmarket",
        "dsh-vision-ocr"        // ← 加上这一行
      ]
    }
  }
}

重启 dsh 即可。（已发布到 npm：dsh-vision-ocr）

方式四：GitHub 直装（不依赖 npm）

dsh plugin --profile web add github:timeflies-qyh/dsh-vision-ocr
# 或（无 dsh 命令时）在 profile 目录：
pnpm add github:timeflies-qyh/dsh-vision-ocr

其余步骤与方式三相同。

方式五：手动加行（不改 profile 的 package.json）

同样先安装包（任选其一）：

pnpm add dsh-vision-ocr
# 或
pnpm add github:timeflies-qyh/dsh-vision-ocr

然后编辑 profile 的 cordis.patch.yml（注意：只选上述一种方式，不要叠加）：

# profiles/web/cordis.patch.yml
- id: dsh-vision-ocr
  name: 'dsh-vision-ocr'

重启 dsh 即可。

验证是否生效

浏览器打开 DSH Web 界面，进入任意会话，附加一张图片：输入框左侧会出现「OCR 识别」按钮。

或直接访问 http://127.0.0.1:<端口>/dsh-vision-ocr/status，应返回 JSON：

{
  "ok": true,
  "engines": { "paddle": "ready", "rapid": "ready" },
  "missing": [],
  "download": { "needed": false }
}

引擎已随安装的 npm 子包分发（Windows 装 dsh-vision-ocr-engines-paddle-win-x64 与 dsh-vision-ocr-engines-rapid-win-x64，Linux 装 dsh-vision-ocr-engines-linux-x64，包管理器按系统自动安装）——安装完成即有引擎：RapidOCR 与 Linux PaddleOCR 装完即用， Windows PaddleOCR 首次使用时在本地解压一次（无网络），之后直接复用。 download.needed: true 仅出现在连子包都没有的极端情况（如手动禁止 optionalDependencies），此时才会回退到 GitHub Release 下载。

使用

场景一：聊天窗口发图片（替代"不支持"弹窗）

在输入框点击附件图标，选择/粘贴一张图片；
图片出现在草稿区后，输入框工具行出现 「OCR 识别」 按钮；
点击按钮：片刻后图片被替换为识别出的文字（每张图带 [N OCR 识别结果] 标题），
直接回车发送即可，DeepSeek 模型会基于文字回答你——不再有"模型不支持图片"弹窗。

提示：可以点击按钮后先检查/修改识别出的文字再发送；识别失败时按钮会变红并显示原因。

场景二：让智能体自己读图

插件注册了模型工具 ocr_image（入参：image_path）。在对话中直接说：

"帮我读一下 screenshots/报错.png 里的报错信息"

智能体会自动调用 ocr_image 读取并分析图片文字。适合工作区里的截图、扫描件、验证码等。

配置

插件行的 config 支持以下字段（全部可选）：

- id: dsh-vision-ocr
  name: 'dsh-vision-ocr'
  config:
    engine: auto        # auto | paddle | rapid（默认 auto：paddle 优先，失败自动回退 rapid）
    timeoutMs: 120000   # 单次识别超时（毫秒，默认 120 秒，首次加载模型较慢）
    maxImageBytes: 26214400  # 单张图片大小上限（默认 25 MiB）
    mirror: ''          # 引擎下载加速前缀，例如 https://gh-proxy.com/
                        # （也可用环境变量 DSH_OCR_MIRROR，二者等价）
    # enginesDir: /opt/dsh-ocr-engines   # 手动预置引擎根目录（含 <平台>/paddleocr-json 结构，
    #                                     # 存在则不再下载）
    # cacheDir: D:/dsh-ocr-cache          # 引擎下载缓存目录（默认 $DSH_HOME/cache/dsh-vision-ocr）
    # paddleDir: /opt/paddleocr-json      # 单独指定 PaddleOCR 引擎目录（一般不需要）
    # rapidDir: /opt/rapidocr-json        # Linux 下自编译 RapidOCR 后指向其目录

自检与测试

克隆仓库后运行自检：

# 引擎级自检：用引擎识别 test/ 下的示例图
# （dev 环境请在 node_modules 里放好本平台引擎子包，或先跑 test-download）
node scripts/test-ocr.mjs

# 平台安装自检：报告引擎来源（子包/缓存/需要下载）
node scripts/test-download.mjs

# 宿主插件集成测试（需要能解析 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools，
# 在 dsh profile 的 node_modules 已链接的环境下运行）
node scripts/test-host-plugin.mjs

# 浏览器端 bundle 测试（假 ModuleLoader 驱动按钮点击全流程）
node scripts/test-client-bundle.mjs

# 一键全跑
pnpm test

Windows x64 已在真实引擎上完整验证（中英文示例图、双引擎、自动回退、base64 路由、子包引擎解析、插件工具与浏览器按钮流程）。

常见问题

Q：发送图片还是弹「当前模型不支持图片」？ 先点「OCR 识别」按钮把图片转成文字再发送；按钮只在有图片附件时出现。如果按钮没出现，检查 /dsh-vision-ocr/status 是否为 ok，并确认插件行已正确加入 profile（见安装）。

Q：不同系统安装的文件大小一样吗？ 不一样，包管理器按系统自动安装：Windows x64 装 dsh-vision-ocr-engines-paddle-win-x64 （~124 MB）与 dsh-vision-ocr-engines-rapid-win-x64（~70 MB）；Linux x64 装 dsh-vision-ocr-engines-linux-x64（约 118 MB，仅 PaddleOCR-json）。不会全量拉取所有平台的引擎文件。

Q：安装包需要联网下载什么？需要代理吗？ 引擎随 npm 子包分发，安装时由包管理器从 npm registry（可配国内镜像）下载，不依赖 GitHub、不需要代理。安装完成后运行时完全离线。只有极端情况（optionalDependencies 被禁用导致子包缺失）才会回退到 GitHub Release 下载，此时可用 mirror 配置加速。

Q：提示 CPU 必须具有 AVX 指令集 / PaddleOCR 运行失败？ PaddleOCR-json 硬性要求 CPU 支持 AVX。绝大多数现代 CPU 都满足；极老的 CPU（Atom、Celeron、 Pentium、AMD K10 及以前）不满足时，插件会自动回退 RapidOCR-json：

Windows：RapidOCR-json 已随 Windows 引擎子包提供，无需操作；
Linux：官方无 Linux 预编译包，请自编译后配置 rapidDir（见 engines/linux-x64/rapidocr-json.md）。

Q：需要联网吗？需要 API Key 吗？ 不需要。引擎随包安装，识别过程不产生任何网络请求与 API 费用。

Q：支持 Mac / arm64 吗？ 目前只支持 Windows x64 与 Linux x64（官方引擎发布包仅提供这两个平台）。如有需要可在 Issues 提出。

目录结构

dsh-vision-ocr/
├── package.json                  # 包定义（dsh.client / dsh.bundle 声明）
├── cordis.patch.yml              # bundle 补丁：插入插件行
├── lib/
│   ├── index.js                  # 宿主半区：ocr_image 工具 + HTTP 路由
│   └── ocr-core.js               # OCR 核心：引擎解析（子包优先）/spawn/JSON 解析/回退
├── client/
│   └── client.js                 # 浏览器半区：输入框「OCR 识别」按钮（手写 bundle，无构建步骤）
├── engines/                      # 引擎分发的说明文档（引擎本体在 npm 平台子包中）
├── scripts/
│   ├── test-ocr.mjs              # 引擎自检
│   ├── test-download.mjs         # 平台分发自检（下载→校验→解压→识别）
│   ├── test-host-plugin.mjs      # 宿主插件集成测试
│   ├── test-client-bundle.mjs    # 浏览器 bundle 测试
│   └── prepare-engines.mjs       # 维护者：打包/上传平台引擎资产
└── test/                         # 示例图片（中/英文）

许可与致谢

插件本体：MIT License（见 LICENSE）。
OCR 引擎为第三方开源项目，本仓库仅作打包分发，保留其原有许可与来源声明，见 engines/README.md：
- PaddleOCR-json（v1.4.1）
- RapidOCR-json（v0.2.0）

English

What is it

DeepSeek models do not accept image input, so attaching a screenshot in DeepSeek Harness shows "The current model does not support images". dsh-vision-ocr turns that flow into: attach image → one-click OCR → image becomes text → the model answers directly — fully offline, free, and private on your own machine.

Features

One-click OCR in the chat composer: an "OCR 识别" button appears in the input tool row whenever images are attached; it replaces the draft images with recognized text, so a non-vision model never hits the "images not supported" rejection.
ocr_image model tool: the agent itself can read text from any image file in the workspace.
Dual-engine with automatic fallback: PaddleOCR-json first (best accuracy); RapidOCR-json automatically when the engine is missing or the CPU lacks AVX.
Engines installed with the package, per-platform: engines ship as os/cpu-filtered npm subpackages (Windows: dsh-vision-ocr-engines-paddle-win-x64 + -rapid-win-x64; Linux: dsh-vision-ocr-engines-linux-x64) referenced via optionalDependencies — npm/pnpm automatically fetches only the subpackages matching the current OS at install time (Windows ~198 MB in total with both engines; Linux ~118 MB). Ready to run from node_modules: zero downloads at run time, no GitHub dependency, no proxy needed.
Languages: simplified/traditional Chinese, English, Japanese, Korean, Russian.
Platforms: Windows x64 and Linux x64. No npm runtime dependencies.

How it works (30 seconds)

The plugin is one npm-style package with three parts:

Host half (lib/) — registers the ocr_image model tool and the /dsh-vision-ocr/ HTTP routes; locates the engine (bundled subpackage first, then config/pre-seeded dirs, then a GitHub Release fallback), spawns it with the documented one-shot flags (PaddleOCR-json.exe -image_path=... / RapidOCR-json.exe --image_path=...), parses the single JSON line on stdout (code:100, data[].text) and returns plain text.
Browser half (client/client.js) — injects the "OCR 识别" button into the composer tool row (conversation.input.left slot); on click it posts the draft images (base64) to the host route, then swaps the draft for the recognized text and removes the attachments.
Engine delivery — per-platform npm subpackages (see engines/README.md) installed automatically by the package manager; the GitHub Release asset is only a last-resort fallback when optional dependencies are disabled.

Install

DSH Web mode assumed. Pick ONE of the options below.

📌 If a DeepSeek agent is installing this plugin by following this README: do not run any command that restarts the dsh process (it would interrupt the current session); after installing/configuring, tell the user that a manual dsh restart is required.

Option A — let DeepSeek install it for you (recommended) 🪄

Paste this into the DeepSeek Harness chat box and press Enter:

Install and configure the dsh-vision-ocr plugin by following the README at https://github.com/timeflies-qyh/dsh-vision-ocr, then run its self-check (scripts/test-ocr.mjs) and report the result to me.

DeepSeek will read the README, locate the profile, run the install (dsh plugin add, or pnpm add + edit bundles) and verify with the self-check — all you have to do afterwards is restart dsh once.

Option B — official command (fully automatic):

Run anywhere (the command locates the profile itself):

dsh plugin --profile web add dsh-vision-ocr

It installs the package into the profile and automatically appends the package to dsh.profile.bundles (because this plugin declares dsh.bundle), so no manual editing is needed. Restart dsh. (If you use the dshmarket visual market, its install button runs the same command plus a hot mount — this plugin's patch is a simple insert, so it activates without a restart.)

Option C — manual npm install (when no dsh command is available):

# run inside your profile directory (e.g. C:\Users\<you>\.dsh\profiles\web)
pnpm add dsh-vision-ocr

Then add the package to dsh.profile.bundles in the profile's package.json:

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

Restart dsh. (Published on npm: dsh-vision-ocr)

Option D — GitHub install (no npm registry needed):

dsh plugin --profile web add github:timeflies-qyh/dsh-vision-ocr
# or, without a dsh command, inside the profile directory:
pnpm add github:timeflies-qyh/dsh-vision-ocr

Same remaining steps as Option C.

Option E — manual row (pick ONE of the five):

pnpm add dsh-vision-ocr
# or
pnpm add github:timeflies-qyh/dsh-vision-ocr

Then add to the profile's cordis.patch.yml:

- id: dsh-vision-ocr
  name: 'dsh-vision-ocr'

Restart dsh.

Verify: open a session and attach an image — the "OCR 识别" button appears next to the input area. Or open http://127.0.0.1:<port>/dsh-vision-ocr/status and expect { "ok": true, "engines": { "paddle": "ready", "rapid": "ready" } }.

Usage

In chat: attach an image → click 「OCR 识别」 → the draft now contains the recognized text → press Enter. No more "model does not support images" popup.
Agent-driven: just ask, e.g. "read the error in screenshots/error.png" — the agent calls the built-in ocr_image tool automatically.

Configuration (all optional)

- id: dsh-vision-ocr
  name: 'dsh-vision-ocr'
  config:
    engine: auto        # auto | paddle | rapid
    timeoutMs: 120000
    maxImageBytes: 26214400
    mirror: ''          # download accelerator prefix, e.g. https://gh-proxy.com/
                        # (or the DSH_OCR_MIRROR env var)
    # enginesDir: /opt/dsh-ocr-engines   # pre-seeded engines root (skip download)
    # cacheDir: D:/dsh-ocr-cache         # engine cache dir (default $DSH_HOME/cache/dsh-vision-ocr)
    # paddleDir: /opt/paddleocr-json
    # rapidDir: /opt/rapidocr-json       # point at a self-built RapidOCR on Linux

FAQ

Still see the "images not supported" popup? Click the OCR button before sending. If the button is missing, check /dsh-vision-ocr/status and the install steps above.
Do different systems install the same size? No. Windows x64 installs only dsh-vision-ocr-engines-paddle-win-x64 (~124 MB) and dsh-vision-ocr-engines-rapid-win-x64 (~70 MB); Linux x64 installs only dsh-vision-ocr-engines-linux-x64 (~118 MB, PaddleOCR-json). The full multi-platform set is never fetched.
What does installation download? Do I need a proxy? Engines ship as npm subpackages fetched from the npm registry (mirrors supported) at install time — no GitHub dependency, no proxy needed; at run time everything is offline. Only when optional dependencies are disabled (no subpackage) does the plugin fall back to a GitHub Release download, configurable via mirror / DSH_OCR_MIRROR.
PaddleOCR fails with AVX errors? Your CPU lacks AVX. The plugin falls back to RapidOCR-json automatically — already bundled on Windows; on Linux build it yourself and set rapidDir (see engines/linux-x64/rapidocr-json.md).
Network / API key needed? No. Engines ship with the package and recognition makes no network requests and costs nothing.

License & Credits

Plugin: MIT (see LICENSE).
OCR engines are third-party open-source projects, bundled as-is with their original licenses: PaddleOCR-json v1.4.1 and RapidOCR-json v0.2.0.

dsh-vision-ocr

Installation

README

dsh-vision-ocr

目录 / Contents

简介

核心特性

技术构成（30 秒看懂）

安装

方式一（最推荐）：一句话，让 DeepSeek 自己装 🪄

方式二：官方命令（一条命令装好）

方式三：npm 手动安装（没有 dsh 命令时）

方式四：GitHub 直装（不依赖 npm）

方式五：手动加行（不改 profile 的 package.json）

验证是否生效

使用

场景一：聊天窗口发图片（替代"不支持"弹窗）

场景二：让智能体自己读图

配置

自检与测试

常见问题

目录结构

许可与致谢

English

What is it

Features

How it works (30 seconds)

Install

Usage

Configuration (all optional)

FAQ

License & Credits

Ähnliche Plugins

archify (deepseek-harness)

treg

dsh-browser

notes