dsh-ocr-local
balcoz/dsh-ocr-local
Local OCR for DeepSeek Harness: paste/attach an image, get its text via PP-OCRv5 + ONNX Runtime, fully offline. TUI (cc-tui) and Web. / DeepSeek Harness 本地 OCR 插件：图片转文字，PP-OCRv5 + ONNX Runtime，完全离线，支持 TUI 与 Web。
安装
dsh plugin --profile web add github:balcoz/dsh-ocr-localREADME
dsh-ocr-local
给 DeepSeek Harness 装一个「本地文字识别」：把截图、报错弹窗、聊天记录、文档照片 变成文字。完全离线、免费，图片不会离开你的电脑，也不需要视觉大模型。
多端支持（TUI + Web）
| 端 | 怎么粘贴图片 |
|---|---|
| TUI（终端客户端） | 安装脚本配置好粘图键后，终端里按粘图键 → 图片自动保存并转成路径插入输入框 |
| Web | 浏览器里直接 Ctrl+V / Cmd+V 粘贴图片 → 自动保存并转成路径插入输入框 |
两条路最终汇合到同一个流程：agent 拿到图片路径 → ocr_image 读出文字。
快速开始（约 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）可能有个别错字 |
| 中文 + 英文混排、长段落 | 复杂背景、艺术字、手写体 |
| 暗色主题截图（自动反色处理） | 模糊或严重压缩的图片 |
识别结果里，字太小或置信度低的行会标注 ⚠，方便你判断哪些字不能全信。
配置（可选，默认不用动）
配置文件：~/.dsh/profiles/web/cordis.patch.yml
- insert:
- id: ocr
name: 'dsh-ocr-local'
config:
pythonPath: ~/miniconda3/envs/ocr/bin/python # 可选：指定 Python
modelDir: ~/.dsh-ocr/models # 可选：模型目录
pasteToPath: true # 可选：false 关闭「粘贴图片转路径」
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 需 Windows Terminal 键绑定生效；
Linux 终端拦截 Ctrl+V 时改用 alt+v 重跑安装脚本）。
Q：Web 端粘贴图片没反应？
确认插件装到了 web profile、pasteToPath 没被改成 false、且重启过 dsh web。
Q：识别结果有错字？ 看输出里的 ⚠ 标注。字太小时模型确实会看走眼：把原图放大一点再试， 或让 agent 把对应行再确认一遍。
工作原理（一句话）
图片 → 本地 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。