dsh-ocr-local

Readme

# dsh-ocr-local

[English](README.en.md) · [中文](README.md)

[![npm version](https://img.shields.io/npm/v/dsh-ocr-local?style=flat-square&color=cb3837)](https://www.npmjs.com/package/dsh-ocr-local) [![license](https://img.shields.io/npm/l/dsh-ocr-local?style=flat-square)](LICENSE) [![GitHub](https://img.shields.io/badge/GitHub-balcoz%2Fdsh--ocr--local-2f81f7?style=flat-square)](https://github.com/balcoz/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**：

```sh
# 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）：

```sh
# 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`）：
>
> ```sh
> 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`

```yaml
- 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](docs/usage.md)。

## 升级

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

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

## 许可

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