dsh-rapid-ocr-ui

Readme

# dsh-rapid-ocr-ui

> 给 DeepSeek Harness 的**纯文本 Agent** 装上本地 OCR：图片粘贴/引用后，
> 用 `ocr_image` 工具在本地提取文字并返回纯文本——不依赖视觉模型、不需要 API Key、
> 不发送任何图片到外部服务。

<p align="center">
  <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
  <img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" />
  <img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >=20" />
  <img src="https://img.shields.io/badge/runtime-no%20API%20Key-8A2BE2?style=flat-square" alt="No API Key" />
</p>

## 这是什么

`dsh-rapid-ocr-ui` 是 DeepSeek Harness 的双面（Host + Client）插件，核心是
**一个本地、纯文本输出的 OCR 工具**：

- **`ocr_image(file_path)`** —— 把图片（PNG/JPEG/WebP/BMP/GIF）在本地跑 OCR，
  返回 `{ path, text, provider }`。对不支持图片输入的纯文本模型，它就是
  `read_image` 的替代品：**提取文字**，而不是看图。
- **`read_image` 能力分发** —— 插件不改写任何模型。图片能力由当前路由的
  模型决定：多模态模型照常走原生 `read_image`；纯文本路由会被引导去用
  `ocr_image`，而不是收到一张它读不了的图。
- **systemPrompt 引导** —— 会话提示词里会告诉纯文本 Agent：「提取文字用
  `ocr_image`」。
- **聊天页 OCR 开关** —— 输入栏左侧有一个「OCR 模式」小按钮（会话级），
  打开后按需对图片做 OCR，纯文本 Agent 也能「看」图片里的字。
- **`ctx.ocr` 可插拔 seam** —— 后端支持 `tesseract` / `rapidocr` /
  `paddleocr-json` / `paddleocr-py`，默认 `none` 是无害的空实现（不装引擎也能
  启动）。

**它解决什么**：你的会话用的是不支持图片输入的模型（比如 DeepSeek 纯文本
路由）时，用户贴一张图，Agent 无法读图。这个插件让 Agent 用本地 OCR 把
图片里的**文字**变成纯文本继续工作——截图里的报错、文档截图、验证码、票据、
PPT 文字等，全部在本地完成，不出本机。

## 与「纯视觉方案」的关系

> [!NOTE]
> 社区已有**纯视觉方案**（基于视觉模型的完整图像理解：看图问答、像素级定位、
> 裁剪、对比、取色、OCR 等）。如果你的需求是「让 Agent 真正看懂图」（描述、
> 定位元素、UI 还原），请优先使用纯视觉方案——它们对图片的理解是完整的。
>
> 本插件定位是互补的**轻量文字提取器**：
>
> - **纯文本输出**：只返回文字，不含图像推理，纯文本模型直接可用；
> - **本地运行**：tesseract 等引擎全在本机，图片不出本机、无外部依赖；
> - **零成本**：不需要视觉模型、不需要 API Key、不消耗视觉额度；
> - **即装即用**：装好 tesseract（或任一支持的引擎）即可，无需配置模型组。

一句话：**要看懂图，用纯视觉方案；只需要图里的字，用 `ocr_image`。**

## 安装

```sh
# 源码仓库环境
cd deepseek-harness
pnpm dsh plugin --profile web add dsh-rapid-ocr-ui

# 或 npx
npx @deepseek-ai/dsh plugin --profile web add dsh-rapid-ocr-ui
```

安装后重启 Web 进程。插件自带 bundle patch，自动完成插件行挂载。

### 准备 OCR 引擎

默认 `provider: none` 是空实现（可启动但不出文字）。要真正 OCR，装一个引擎
并在 `cordis.patch.yml` 里配置，例如 Tesseract：

```yaml
- id: rapid-ocr
  config:
    provider: tesseract
    ocrPath: "C:\\Program Files\\Tesseract-OCR\\tesseract.exe"
    modelPath: "D:\\path\\to\\tessdata"
    language: ch
```

支持的 provider：`tesseract` / `rapidocr` / `paddleocr-json` / `paddleocr-py`。
`language` 例如 `ch`、`en`、`ch,en`。

## 使用

1. 重启后，纯文本会话里贴一张图；
2. Agent 的提示词已被告知：提取文字用 `ocr_image(file_path)`；
3. 也可以手动打开输入栏左侧的「OCR 模式」开关，按需对图做 OCR。

## 配置项

| 字段 | 默认值 | 含义 |
|---|---|---|
| `enabled` | `true` | 总开关；`false` 时插件什么都不注册 |
| `provider` | `none` | OCR 后端：`none` / `tesseract` / `rapidocr` / `paddleocr-json` / `paddleocr-py` |
| `ocrPath` | — | 引擎可执行文件/脚本路径（provider 相关） |
| `modelPath` | — | 模型/语言数据目录（provider 相关） |
| `language` | `ch` | OCR 语言，如 `ch` / `en` / `ch,en` |
| `maxImageBytes` | `20000000` | 单图送入 OCR 的字节上限 |
| `timeoutMs` | `60000` | OCR 调用超时 |
| `scope` | `agent` | 工具注册平面：`agent`（推荐）或 `global` |
| `fallbackOnly` | `true` | 图片能力路由始终优先原生 `read_image` |
| `autoOcrImages` | `false` | 打开 OCR 模式后是否自动 OCR 新附件 |
| `injectOcrText` | `false` | 是否自动把 OCR 文本插入草稿 |
| `promptSectionOrder` | `118` | 「图片 → 用 ocr_image」提示词段顺序 |

## 设计要点

- **绝不 shadow `read_image`**：`ocr_image` 是独立文本工具；多模态行为零改动。
- **能力在调用时判定**：根据当前路由的 provider/model 实时解析图片能力，
  模型中途切换也不会留下过期判断。
- **结构化错误**：OCR 失败返回 `isError` 结果（路径不存在、超大图、引擎失败
  等），对话轮次不会中断。
- **懒注册路由**：Client 先于 Host webserver 就绪时，HTTP 路由会等载体出现后
  再注册。

## 许可

MIT