dsh-ocr-vision

一个 DeepSeek Harness 插件（bundle），让纯文本大模型（如 DeepSeek）也能"看图"—— 新增模型侧 ocr_image 工具，用本地 RapidOCR 把图片文字提取成纯文本返回给主聊，而不是 把图片发给模型。这是 claude-ocr-vision（Claude Code / Codex 版）在 DeepSeek Harness 上的对应实现。

---

解决什么问题

运行 DeepSeek Harness 接入纯文本大模型（DeepSeek 无多模态）时，模型需要识图时会调用 read_image 工具，把图片作为 content block 发给后端。纯文本路由没有图片输入能力，read_image 在 tool-fs 侧会严格拒绝（"does not declare image input"），模型看到一条错误。

本插件从根上避免这件事：提供 ocr_image 工具，把图里文字用本地 OCR 提取成纯文本返回， 模型永远只处理文本。同时通过系统提示段引导模型在纯文本路由下优先用 ocr_image。

工作机制

模型需要看图
     │  调用 ocr_image(file_path, region?, scale?)
     ▼
ocr-vision 插件:通过 ctx.fs 读取图片字节(受沙箱/观察策略约束)
     │  写入临时文件
     ▼
ocr.py(RapidOCR,2 倍放大、按阅读顺序还原版面)
     │
     ▼
纯文本(阅读顺序/坐标)──► 主聊继续任务(图片从不进模型上下文)

• 工具：ocr_image，模型侧 schema，输出纯文本。图片字节永远不发给模型 API。
• 脚本：ocr.py，RapidOCR 封装（2 倍放大、--region 区域裁剪、--coords/--json 坐标、 <无文字> 空图容错），与 claude-ocr-vision 共用同一份。
• 技能：SKILL.md，任务导向三步流程（先明确识图目的/关注区域/任务关联，再提取，再围绕任务组织文本）。
• 系统提示段：tool:ocr-vision，引导模型在纯文本路由下用 ocr_image。

安装

系统要求

项目	说明
操作系统	Linux 或 macOS（Windows 未测试）
Python	3.7+
Python 依赖	rapidocr-onnxruntime、pillow、numpy（缺失时 ocr_image 会失败并报错）
DeepSeek Harness	dsh CLI 与一个 profile（如 headless / web）

一句话让 Agent 帮你装

把下面整段复制给你的 Agent（Claude Code / Cursor / Codex 均可）：

请先阅读 https://github.com/QEDQCD/dsh-ocr-vision 的 README.md「系统要求」，确认本机满足（Linux/macOS、Python 3.7+、已装 rapidocr-onnxruntime/pillow/numpy、有 dsh CLI 与一个 profile 如 headless）；不满足则先告知我缺什么。满足后：克隆到任意目录，在该目录内运行 pnpm install && pnpm build（或对应 npm 命令），再运行 node scripts/install.mjs --profile headless（profile 名按我实际用的改），验证 dsh --profile headless --dump-config | grep ocr-vision 能输出，且 python3 ocr.py <某图片路径> 能正常提取文字。

构建并安装到 profile

cd dsh-ocr-vision
pnpm install          # 或 npm install（安装 devDeps 以构建）
pnpm build            # tsc 编译 src -> lib
node scripts/install.mjs --profile headless

安装脚本（幂等）把 bundle 拷入 $DSH_HOME/profiles/<name>/node_modules/@deepseek-ai/dsh-ocr-vision， 把 SKILL.md 拷入 profile 的 skills/，并把 @deepseek-ai/dsh-ocr-vision 注册进 profile 的 dsh.profile.bundles。之后 dsh --profile <name> 启动即挂载 ocr_image 工具。

卸载：

node scripts/install.mjs --profile headless --uninstall

验证

# 1) OCR 脚本可用(本机需有 RapidOCR)
python3 ocr.py <某图片路径>        # 输出提取的文本(或 <无文字>)

# 2) 工具已挂载
dsh --profile headless --dump-config | grep ocr-vision

新开会话后，让模型"读这张图"，应看到它调用 ocr_image 返回纯文本，而不是 read_image 报错。

从 GitHub 分发/安装（免 npm 发布）

本包是 dsh bundle（package.json 声明 dsh.bundle），dsh plugin 支持从 GitHub 直装， 仓库公开即可，无需发布 npm：

dsh plugin --profile headless add github:QEDQCD/dsh-ocr-vision
# 或指定分支/标签：github:QEDQCD/dsh-ocr-vision#main

dsh plugin add 会把包名（@deepseek-ai/dsh-ocr-vision）注册进 profile 的 dsh.profile.bundles，并自动挂载 ocr_image 工具。安装后仍需满足本机 RapidOCR/Python 依赖（见「系统要求」）。

将来发布到 npm 后，可改用 dsh plugin --profile <name> add @deepseek-ai/dsh-ocr-vision。 package.json 已带 keywords/repository/publishConfig.access，便于 registry 检索与公开发布。

使用

模型侧直接调用（或经技能引导）：

ocr_image(file_path: "截图.png")
ocr_image(file_path: "截图.png", region: "120,80,600,400")   # 只识别关注区域

预期输出（工具返回的纯文本信封）：

<path>/workspace/截图.png</path>
<type>ocr</type>
<content>
报错码:ERR_DB_CONN_TIMEOUT
关键行:Connection refused -> db.internal:5432 / retry 3/3 failed
</content>

配置

ocr_image 插件可通过 cordis 配置调整：

字段	默认	含义
pythonBin	python3	运行 ocr.py 的 Python 解释器
ocrScript	随包 ocr.py	RapidOCR CLI 脚本路径
ocrCommand	空	完整命令前缀，覆盖 pythonBin+ocrScript（测试/定制宿主用）
scale	2	默认放大倍数（小字更准）
maxImageBytes	50 MiB	经 ctx.fs 读取的最大图片字节
timeoutMs	60000	单次 OCR 子进程超时

目录结构

dsh-ocr-vision/
├── package.json          # @deepseek-ai/dsh-ocr-vision,bundle 声明(dsh.bundle.patch)
├── cordis.patch.yml      # bundle 补丁:把 ocr-vision 插件插入 profile
├── src/
│   ├── index.ts          # ocr_image 工具 + 系统提示段
│   ├── ocr.ts            # OCR 引擎调用(可注入 command)
│   └── invariant.ts      # 包级 invariant 伴生
├── ocr.py                # RapidOCR 封装(与 claude-ocr-vision 共用)
├── SKILL.md              # 任务导向 OCR 技能
├── scripts/install.mjs   # 安装/卸载到指定 profile
├── tsconfig.json
├── README.md
└── LICENSE

隐私与安全

• 图片不进 API：ocr_image 只返回提取的文本，图片字节从不上行到模型。
• 本地 OCR：ocr.py 用本地 RapidOCR 推理，图片不出本机。
• 走 fs 策略：图片通过 ctx.fs 读取，受沙箱与观察策略约束；临时文件用后即删。
• 仓库洁净：仓库不含任何密钥、token、个人数据或真实图片。

开发与测试

插件源码在 monorepo 中作为工作区包 packages/fs/ocr-vision 开发，单测用确定性 fixture OCR 命令（不依赖 Python），并跑真实组合测试。分发时把 src/、ocr.py、SKILL.md 同步到本 bundle。

测试确定性的 OCR 引擎注入：

ctx.plugin(OcrVision, { ocrCommand: ['node', '-e', 'process.stdout.write("fixture-ocr[...]")'] })

已知限制与后续

• 需要 Python + RapidOCR 宿主：默认引擎以子进程跑 ocr.py，宿主需装 rapidocr-onnxruntime、pillow、numpy；否则 ocr_image 会报错。可用 ocrCommand 换引擎。
• 不支持 PDF 输入：仅光栅图片（PNG/JPEG/WebP/GIF/BMP/TIFF 等，见 ocr.py）。PDF 光栅化未实现。
• 不拦截 read_image：本插件只新增 ocr_image 与引导，不改写/拒绝 read_image； 纯文本路由若调用 read_image 仍会得到 tool-fs 的严格拒稿。