dsh-ocr-local

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

多端支持（TUI + Web）

端	怎么粘贴图片	识别方式
TUI（终端客户端）	终端里 Ctrl+V / 粘图键 / 终端菜单粘贴	自动：图片进会话 → 插件存到本地缓存 → 文本模型调 `ocr_image` 识别
Web	浏览器里直接 Ctrl+V / Cmd+V 粘贴图片	自动：粘贴即转成路径插入输入框 → `ocr_image` 识别

两条路最终都汇合到同一个流程：图片到达会话 → 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：

粘图键	粘图（发图片）	文本粘贴
`ctrl+v`（默认）	Ctrl+V	Ctrl+Shift+V
`ctrl+shift+v`	Ctrl+Shift+V	Ctrl+V
`alt+v`	Alt+V	Ctrl+V

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

能识别什么 / 有什么限制

✅ 擅长	⚠️ 效果一般
截图、报错弹窗、聊天记录	极小的字（如 4px）可能有个别错字
中文 + 英文混排、长段落	复杂背景、艺术字、手写体
暗色主题截图（自动反色处理）	模糊或严重压缩的图片

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

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

识别方式与开关

场景	行为	开关
文本模型（不支持识图）	粘贴/附带的图片自动保存到本地缓存，并向模型注入路径提示 → 模型调 `ocr_image` 本地识别	本插件 `autoOcr`（默认 `true`；设 `false` 关闭自动提示，仍可手动让模型调 `ocr_image`）
视觉模型（支持识图）	图片原样送达模型，由模型直接看图；本地 OCR 提示并存、不干扰	由你的模型/客户端配置决定（模型声明识图能力或启用视觉桥），本插件不干预

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                             # 可选：粘贴缓存保留天数

常用环境变量：

变量	作用
`DSH_OCR_MODELS_MIRROR`	模型下载镜像前缀（国内下载慢时设，如 `https://ghproxy.com/`）
`DSH_OCR_PYTHON`	指定 OCR 用哪个 Python（默认自动找）
`DSH_OCR_MODELS`	模型存放目录（默认 `~/.dsh-ocr/models`）

常见问题

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。