dsh-ocr-local

一句话定位

给 DeepSeek Harness 加一个本地图片转文字能力：把截图、报错弹窗、聊天记录或文档照片粘贴到会话里，插件自动调用本地 PP-OCRv5 模型读出里面的文字。整个识别在本地完成，图片不出电脑，也不需要视觉大模型。

核心能力

• 在 TUI 终端客户端和 Web 端粘贴图片，路径自动插入输入框，文本模型自动调用 ocr_image 识别图片中的文字
• 注册 ocr_image 工具，传入图片绝对路径返回识别结果（按行输出，每行带置信度）
• 注册 ocr_setup 工具，一键建 Python 虚拟环境、装 ONNX Runtime 等依赖、下载识别模型（约 20MB），整套流程幂等
• 图片保存到本地缓存 ~/.dsh/ocr/cache，按内容哈希去重，按文件数和天数自动清理
• 暗色主题截图自动反色处理，识别结果中字太小或置信度低的行会被标记 ⚠

技术实现

• 语言: Node.js（插件宿主）+ Python（OCR 推理脚本），cordis 插件协议
• 关键依赖: @deepseek-ai/cordis（宿主集成）、@deepseek-ai/dsh-tools（工具注册）、onnxruntime + opencv-python-headless + numpy（Python 侧 OCR 推理）、PaddleOCR PP-OCRv5 mobile 模型（ONNX 格式）
• 架构模式: 插件同时提供 Node 侧 cordis 插件（dsh/index.js 注册 ocr_image/ocr_setup 工具与 /ocr/paste HTTP 路由）与浏览器侧 lazy-CJS 模块（dsh/client.js 监听 paste 事件并通过 fetch 把图片字节上传到宿主路由），通过 dsh.client.inject 字段自动注入到 Web 端；Python 脚本被 Node 端通过 child_process.execFile 调用，标准输出以 JSON 形式回传
• 入口文件: dsh/index.js（cordis 插件主入口）、dsh/client.js（浏览器侧 paste-to-path）、ocr/ocr.py（PP-OCRv5 推理）、ocr/setup.py（一键自举）

适用场景

当模型无法直接看图（文本模型、上下文窗口紧张、关闭了视觉桥），但你想让 agent 读截图、报错弹窗、聊天记录或文档照片里的文字时，安装这个插件即可让"粘贴图片"和"读出图片里的字"两步无缝衔接。它特别适合处理敏感截图——图片全程不出本地机器，且不依赖任何云端视觉 API。

前置依赖与兼容性

安装方式

dsh plugin --profile web add dsh-ocr-local

提示：DSH 的 profile 互相隔离，TUI 端需要再装一次并跑安装脚本配置粘图键（./install.sh --profile <profile> 或 powershell -ExecutionPolicy Bypass -File install.ps1 -Profile <profile>）。

配置项

配置文件位于 ~/.dsh/profiles/<profile>/cordis.patch.yml，所有项都有默认值，不填也能用。

常用环境变量：

常见问题

Q: 首次使用报错"环境未就绪/缺少依赖"怎么办？

A: 对 agent 说"用 ocr_setup 工具安装 OCR 环境"，插件会自动建 Python 虚拟环境、装 onnxruntime/numpy/opencv-python-headless、下载 PP-OCRv5 模型。也可手动跑 python .../ocr/setup.py，整个流程幂等可重复执行。

Q: 模型下载很慢或失败？

A: 设镜像前缀后重跑：DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python .../ocr/setup.py。下载带 sha256 校验，文件损坏会自动重新下载。

Q: TUI 端粘贴图片没反应？

A: 先确认终端能读到剪贴板图片：Windows/macOS 开箱即用；Linux Wayland 需要装 wl-clipboard，X11 需要装 xclip，否则终端读不到剪贴板图片、粘贴会静默失败。装好后再粘贴即可。

Q: Web 端粘贴图片没反应？

A: 确认插件装到了 web profile、配置 pasteToPath 没被改成 false、且重启过 dsh web。浏览器控制台会有 [dsh-ocr] 报错信息。

Q: 识别结果有错字？

A: 看输出里的 ⚠ 标注，字太小或置信度低的行会被标记。把原图放大一点再试，或让 agent 把对应行再确认一遍。PP-OCRv5 mobile 对长行、艺术字、模糊图效果有限。

Q: 升级插件后功能没变化？

A: 重启 dsh 让插件重新加载。TUI 端升级后若粘图失效（插件文件被覆盖），重跑安装脚本 install.sh 或 install.ps1 即可（补丁幂等）。

Q: 系统提示 pip externally-managed-environment（PEP 668）？

A: 不要加 --break-system-packages。直接用 ocr/setup.py，它会自动创建虚拟环境，绕开系统 Python 的限制。

上手难度

入门 — 安装后只需对 agent 说"用 ocr_setup 安装环境"或"识别这张图片"就能跑起来，无需写任何配置；如要换粘图键或改缓存策略再编辑 cordis.patch.yml。

已知问题与限制

• 极小的字（如 4px 以下）或低检测置信度的行会被标记为低置信，识别结果可能出错（详见 ocr/ocr.py:59-60）
• TUI 粘图键仅支持 ctrl+v / ctrl+shift+v / alt+v 三选一，其他组合不被识别（详见 patch/apply-cc-tui-patch.mjs:23）
• Web 端单次粘贴的图片大小上限 16MB（PASTE_MAX_BYTES），超出返回 413
• Linux Wayland 下粘贴图片需要 wl-clipboard，X11 需要 xclip，否则终端读不到剪贴板图片、粘贴会静默失败（详见 docs/usage.md:108-114）
• 模型仅 PP-OCRv5 mobile，对长段落、艺术字、手写体、严重模糊或压缩图效果一般
• autoOcr 默认开启，关掉后模型不会再自动识别粘贴的图片（仍可手动让模型调 ocr_image）

English · 中文

给 DeepSeek Harness 装一个「本地文字识别」：把截图、报错弹窗、聊天记录、文档照片 变成文字。完全离线、免费，图片不会离开你的电脑，也不需要视觉大模型。

多端支持（TUI + Web）

两条路最终都汇合到同一个流程：图片到达会话 → ocr_image 本地读出文字。 如果你的模型支持识图（或配置了视觉桥），图片会原样送达模型，本地 OCR 提示与 视觉链路互不干扰、并存生效。

快速开始（约 5 分钟）

第 1 步：安装插件

DSH 的 profile 互相隔离，插件要装到每个你想用的 profile：

# Web 端
npx -y @deepseek-ai/dsh plugin --profile web add dsh-ocr-local

# TUI 端（把 <profile> 换成你的终端 profile 名）
npx -y @deepseek-ai/dsh plugin --profile <profile> add dsh-ocr-local

TUI 端装完后，再运行一次安装脚本来配置终端粘图键 （Windows 还会自动改写 Windows Terminal 键绑定，备份在 settings.json.bak）：

# Windows
powershell -ExecutionPolicy Bypass -File install.ps1 -Profile <profile>

# macOS / Linux
./install.sh --profile <profile>

装完重启 dsh，插件才会生效。

第 2 步：准备识别引擎（只需一次）

把任意一张图片发给 agent，说：

识别这张图片

如果引擎还没装好，工具会告诉你缺什么。这时再对 agent 说：

用 ocr_setup 工具安装 OCR 环境

插件会自动完成三件事：建虚拟环境 → 装 Python 依赖 → 下载识别模型 （约 20MB），之后每次识别都在本地秒级完成。

想手动装也可以（和上面等价，把 <profile> 换成你的 profile 名，如 web）：

python ~/.dsh/profiles/<profile>/node_modules/dsh-ocr-local/ocr/setup.py

第 3 步：开始使用

方式 A：粘贴截图（最常用）

• Web：在输入框里按 Ctrl+V / Cmd+V
• TUI：按粘图键（见下表）

图片会自动保存成路径插入输入框，agent 会自动调 ocr_image 读出里面的文字。

方式 B：告诉 agent 图片路径

把图片文件的绝对路径发给 agent，说「识别这张图片」。

粘图键（TUI 端）

安装时指定的快捷键，默认 ctrl+v，可选 ctrl+shift+v / alt+v。 不想占用你习惯的 Ctrl+V 文本粘贴，就选 alt+v 或 ctrl+shift+v：

换粘图键：重跑安装脚本 install.ps1 -PasteKey <新键> / install.sh --key <新键>， 会自动切换并清理旧绑定。补丁幂等，重复运行自动跳过。

能识别什么 / 有什么限制

识别结果里，字太小或置信度低的行会标注 ⚠，方便你判断哪些字不能全信。

配置（可选，默认不用动）

识别方式与开关

autoOcr 只管"本地 OCR 提示"这一半：图片进会话后插件保存并提示模型识别。 "图片要不要发给视觉模型"由模型/客户端决定，与 autoOcr 无关——两件事可以同时开。

配置文件：~/.dsh/profiles/web/cordis.patch.yml

- insert:
    - id: ocr
      name: 'dsh-ocr-local'
      config:
        autoOcr: true                                   # 可选：false 关闭「粘贴图片自动提示识别」
        pythonPath: ~/miniconda3/envs/ocr/bin/python   # 可选：指定 Python
        modelDir: ~/.dsh-ocr/models                     # 可选：模型目录
        pasteToPath: true                               # 可选：false 关闭 web「粘贴图片转路径」
        maxCacheFiles: 300                              # 可选：粘贴缓存最多文件数
        maxCacheAgeDays: 30                             # 可选：粘贴缓存保留天数

常用环境变量：

常见问题

Q：提示「环境未就绪」/「缺少依赖」？ 对 agent 说「用 ocr_setup 安装 OCR 环境」即可自动修复；或手动运行 python ~/.dsh/profiles/web/node_modules/dsh-ocr-local/ocr/setup.py。

Q：模型下载很慢或失败？ 设镜像后重试（幂等，可反复跑）： DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python .../ocr/setup.py

Q：系统提示 pip externally-managed-environment（PEP 668）？ 不要加 --break-system-packages。直接用 ocr/setup.py——它会自动创建虚拟环境， 绕开系统 Python 的限制。

Q：TUI 端粘贴图片没反应？ 先确认终端客户端能读到系统剪贴板图片：Windows/macOS 开箱即用； Linux（Wayland）需要安装 wl-clipboard（X11 装 xclip），否则终端读不到剪贴板 图片、粘贴会静默失败。装好后重新粘贴即可——图片进入会话后，本插件会自动保存 并提示模型用 ocr_image 识别。

Q：Web 端粘贴图片没反应？ 确认插件装到了 web profile、pasteToPath 没被改成 false、且重启过 dsh web。

Q：识别结果有错字？ 看输出里的 ⚠ 标注。字太小时模型确实会看走眼：把原图放大一点再试， 或让 agent 把对应行再确认一遍。

工作原理（一句话）

任何端粘贴的图片（TUI 粘贴 / web 粘贴 / 附件）进入会话后，插件把它保存到 ~/.dsh/ocr/cache 并提示模型；模型调 ocr_image → 本地 PP-OCRv5 模型 （ONNX Runtime，纯 CPU）→ 文字。模型第一次使用时下载到 ~/.dsh-ocr/models， 之后完全离线。更多细节见 docs/usage.md。

升级

npx -y @deepseek-ai/dsh plugin --profile web update dsh-ocr-local

TUI 端升级后如果粘图失效（插件文件被覆盖），重跑一次安装脚本即可（补丁幂等）。

许可

MIT（代码）。识别模型 Apache-2.0（PaddleOCR），安装时自动下载。见 LICENSE。