前言¶
DeepSeek Harness（DSH）里的 Agent 能读文本文件，但截图、扫描件、手机拍的表格，以及没有可复制文字层的 PDF，往往只能「猜」。社区插件 dsh-tool-ocr（维护者 yuehancn，分类：模型推理）把这一段补上：对带文字层的 PDF 直接读层；对扫描 PDF 和图片则走你自行配置的 OCR 引擎，把正文交回工具调用结果。插件在 SkillHub 目录与 GitHub 均可查，与 DeepSeek / 幻方无官方从属关系；生态上是「一切皆插件」，目录站为独立社区站点。
下面介绍插件定位、能力、安装与配置方式，事实以仓库 README 与 package.json 为准。README 写明在 dsh 0.2.0-rc.2（preview）上构建与测试；apply(ctx) 插件规范稳定，若你使用更新版本 dsh，需自行核对兼容性。
这是什么¶
dsh-tool-ocr 是给 DeepSeek Harness 用的自建工具插件，职责是 图片 OCR + PDF 文本抽取。英文简介为：Extract text from images and PDFs in DeepSeek Harness: read a born-digital text layer, or OCR a scan with any engine you configure.
插件本体只在 Node 里运行，不捆绑 Python OCR 包；外部引擎与 poppler 工具由你在本机按需安装并在配置里声明。
核心功能¶
输入怎么处理¶
| 输入 | 行为 |
|---|---|
| 带文字层的 PDF（电子合同、导出报告等） | 读文字层，不调 OCR |
| 扫描件 / 图片型 PDF | 文字层为空时栅格化页面，再调 OCR |
| 图片（截图、照片、表格） | 直接交给 OCR 引擎 |
要点有两条：先判断是否为电子版 PDF，避免对电子 PDF 白跑 OCR；OCR 引擎由你配置，tesseract、PaddleOCR 或公司内部命令行客户端均可接入。
两个工具¶
ocr_read¶
ocr_read(path, engine?, lang?, pages?, saveAs?)
path：图片或 PDF 的绝对路径engine：指定引擎；省略则用默认引擎lang：语言提示，例如chi_sim+engpages：PDF 页码范围，如1-3或2,5saveAs：是否将抽取文字另存到配置的输出目录
返回字段包括 text、kind（image / pdf）、实际使用的 engine、pages、textPath，以及 note（说明走了哪条路径、有何提醒）。note 供 Agent 判断本次结果是否可信，而不是盲目采纳全文。
ocr_status¶
逐个探测本机已配置引擎是否可用（例如执行 --version），并报告当前 backend。README 建议在动手 OCR 前先调用，避免白跑耗时任务。
安装与启用¶
一行安装（README 原文命令，支持 desktop 与 web profile）：
dsh plugin --profile desktop add github:yuehancn/dsh-tool-ocr
Web 版将 --profile desktop 换成 web。安装完成后重启 dsh。
package.json 中版本为 1.0.0，许可证 MIT，依赖 dsh >=0.2.0-rc.2。
配置 OCR 引擎¶
默认 backend: native：仅用 poppler 读 PDF 文字层，无需安装 OCR。
要处理扫描件，在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中把 backend 改为 command，并在 engines 里登记引擎，例如 Tesseract：
# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-ocr
config:
backend: command
outputDir: C:/Users/you/Documents/ocr-output
engines:
- id: tesseract
label: Tesseract 中英混排
command: tesseract
args: ["{input}", "{output}", "-l", "chi_sim+eng"]
isDefault: true
args 中可用占位符：
| 占位符 | 含义 |
|---|---|
{input} |
交给引擎的图片绝对路径 |
{output} |
引擎应写入纯文本的绝对路径 |
{lang} |
本次 ocr_read 的 lang 参数（可为空） |
引擎可将文字写入 {output} 或输出到 stdout，插件两种都识别。多引擎时在 engines 下追加条目并指定 isDefault 即可，例如正文用 tesseract、表格场景另配 PaddleOCR（README 中有示例 args）。
外部依赖¶
| 依赖 | 用途 | 未安装时的影响 |
|---|---|---|
pdftotext（poppler） |
读 PDF 文字层 | 电子 PDF 也无法读取，note 会说明 |
pdftoppm（poppler） |
PDF 页栅格化为图 | 扫描 PDF 无法 OCR |
| 任一已配置的 OCR 引擎 | 识别图中文字 | 图片输入报错并提示配置 |
Windows 上 poppler 可下载 poppler-windows，将 bin 加入 PATH，或在 config 里写 pdftotext.exe 完整路径。Tesseract 可用 UB-Mannheim 安装包，需勾选中文语言包（chi_sim），否则 -l chi_sim 会缺 traineddata。
典型用法（Agent 侧）¶
- 调用
ocr_status，确认 backend 与可用引擎。 - 对本地文件调用
ocr_read，传入绝对路径；PDF 可带pages限制范围；需要落盘时用saveAs。 - 根据返回的
text与note决定是否采纳或换engine/lang重试。
插件只读取你指定的单个文件，不扫目录、不上传、不联网；OCR 通过 spawn 调用本地命令，不经 shell 拼接路径；抽取文字除返回外，仅写入配置的 outputDir。
适用场景与注意¶
适合：需要在 DSH 对话或工作流里让 Agent 读发票截图、扫描合同、图片型 PDF，且希望电子 PDF 走文字层、扫描件走自选 OCR 的开发者。
注意：
- 插件随当前 dsh 进程权限 运行，安装前请查看源码与 MIT 许可证，并只配置你信任的本地命令。
- 无文字层且未配置 OCR 时，图片路径会直接失败；仅
nativebackend 时扫描 PDF 无法识别。 - 仓库提供针对真实 dsh 运行时的测试（README 中
node _test/run-all.mjs及三套套件说明），便于自行验证行为。
结尾¶
dsh-tool-ocr 把「图里有没有字、PDF 是电子版还是扫描件」的分支封装进两个工具，并把引擎选择权留给你。目录与文档：
- SkillHub：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-ocr
- GitHub：https://github.com/yuehancn/dsh-tool-ocr
