前言¶
DeepSeek Harness（DSH）支持通过插件扩展能力，zirscard/dsh-ocr 插件为智能体增加了批量文档预处理和 OCR 识别能力。它提供两个工具：doc_ocr 和 doc_preprocess，分别处理单文档识别和目录级知识库构建。
doc_ocr：单文档识别¶
doc_ocr 支持三种模式，可通过本地 RapidOCR 或智谱 GLM-OCR 云端引擎运行。
三种模式¶
| 模式 | 用途 | 输出 |
|---|---|---|
text |
整页 OCR（最通用） | 逐页文本 + 行数 + 平均置信度 |
table |
财务报表（扫描件三线表） | 自动定位数值列 → 列切条重 OCR → 按 y 归行 → 数字清洗 → 资产负债表平衡勾稽 |
clause |
合同条款 | 回购/对赌/反稀释/优先清算… 关键词命中 + 页码 + 引用片段 |
两种引擎¶
local（默认）¶
RapidOCR，运行 PaddleOCR PP-OCRv4 的 ONNX 模型，本机推理，不发网络请求。
glm¶
智谱 GLM-OCR 云端（0.9B，OmniDocBench SOTA），输出原生 Markdown；复杂表格 / 公式 / 盖章 / 图文混排更强，需要 API key。
密钥从环境变量读取，支持 ZHIPU_API_KEY、DSH_OCR_ZHIPU_KEY、BIGMODEL_API_KEY，可选 DSH_OCR_ZHIPU_BASE_URL（默认 https://open.bigmodel.cn/api/paas/v4）。
解决的问题¶
- 扫描件无文本层：pypdf 抽不出文字，必须先渲染成图再识别。
- 整页 OCR 漏识数字：相邻列合并、数字右对齐截断，导致报表无法勾稽。
- 逗号/句点混淆：
52,163被认成52.163，按千分位规则归一。 - OCR 数字不可全信：只接受能被「资产总计 = 负债合计 + 所有者权益合计」勾住的数，勾不平就标出来交人工。
并发控制¶
本插件做了两层限制，避免 CPU 严重超卖：
| 层级 | 机制 | 默认 |
|---|---|---|
| 进程内 | core/ocr.py 设置 intra_op_num_threads / inter_op_num_threads（级联 Det/Cls/Rec） |
2 |
| 进程间 | runner.js 模块级 FIFO 信号量，限制同时运行的 OCR 进程数 |
2 |
进程内线程数可通过 DSH_OCR_THREADS 覆盖（设 0/负数表示不限）；进程间并发数可通过 DSH_OCR_MAX_CONCURRENT 覆盖。
doc_preprocess：知识库预处理管线¶
doc_preprocess 把一个目录/一批原始文件（PDF/Office/图片/文本）整理成 Obsidian 可读知识库（markdown + JSON + sha256 增量缓存）。
七阶段管线¶
discover → classify → extract(后端路由) → clean → structure → output(md+json) → verify
↑ ↓
增量/缓存 ←────────────── 失败人工队列
| 阶段 | 做什么 |
|---|---|
| 0 discover | 扫描文件 + 排除（.git / .trash / node_modules 等），记 sha256 |
| 1 classify | 按扩展名 + PDF 文本层检测（>100 字符=文本层，≈0=扫描件）分类 |
| 2 extract | 文本层 PDF→pypdf；扫描件 PDF/图片→OCR；docx→python-docx；xlsx→openpyxl；pptx→python-pptx；csv→markdown 表；json/yaml→代码块 |
| 3 clean | 页眉页脚去重、中文断行合并、数字清洗 |
| 4 structure | 「第X章 / 第X条」→ 标题层级；表格 → markdown 表 |
| 5 output | 每文件 .md（YAML frontmatter：source_path/sha256/kind/backend/page_count/ocr_confidence/extracted_at）+ .json + cache.json |
| 6 verify | 空正文 / 无页 / 不支持格式 → 进 problems 列表 |
| 7 incremental | sha256 命中缓存 → 跳过（force 可重跑） |
原始文件永不被修改；markdown 是工作格式，数字另存 JSON；失败进人工队列而不是中断整批。
安装与启用¶
从 GitHub 安装：
dsh plugin add https://github.com/zirscard/dsh-ocr
从本地目录安装：
dsh plugin add link:/absolute/path/to/dsh-ocr
重启 DSH 后，新会话的工具列表出现 doc_ocr 与 doc_preprocess。
运行环境¶
RapidOCR 会带上 onnxruntime / opencv / numpy 等 C 扩展 wheel。在 macOS 上，如果 DSH 内置 Python 启用了 hardened runtime + Library Validation，可能拒绝加载这些 ad-hoc 签名的动态库：
ImportError: dlopen(...): code signature ... different Team IDs
处理方式二选一：
- 给内置 Python 注入
com.apple.security.cs.disable-library-validationentitlement 并 ad-hoc 重签（DSH 升级后可能需重跑）。 - 用
DSH_OCR_PYTHON指向一个能加载这些 wheel 的 Python（如 conda / Anaconda），插件会把 DSH 的 site-packages 追加到sys.path末尾，避免 NumPy ABI 冲突。
runner.js 的解释器选择顺序：
DSH_OCR_PYTHON环境变量（显式指定，最优先）。- DSH 内置 Python。
/opt/anaconda3/bin/python3（兜底）。
直接运行引擎（不经过 DSH）¶
PY=python3 # 换成能加载 OCR 依赖的解释器
# text：整页文本
"$PY" core/ocr.py --input scan.pdf --mode text --pages 34,37,42 --dpi 200
# table：财务报表（建议 dpi 300–400）
"$PY" core/ocr.py --input scan.pdf --mode table --pages 37 --dpi 300 \
--out-json /tmp/p37.json --out-md /tmp/p37.md
# clause：合同条款
"$PY" core/ocr.py --input contract-page.png --mode clause
# glm 云端引擎（复杂表格 / 盖章协议优先）
"$PY" core/ocr.py --input contract-page.png --mode table --engine glm
# 知识库预处理
"$PY" core/pipeline.py --input 某目录 --output out/ --mode all
"$PY" core/pipeline.py --input 某目录 --output out/ --mode classify
测试¶
python3 test/run_tests.py # OCR 引擎（纯函数 + 合成图；可选真实样本）
python3 test/glm_mock_test.py # glm 全链路，用本地 mock 服务器，不花钱
run_tests.py：数字清洗、页码解析、合成图关键词命中；设置DSH_OCR_TEST_PDF/DSH_OCR_TEST_IMAGE后追加 table 勾稽与 clause 命中测试。glm_mock_test.py：本地 mock 智谱chat/completions，验证请求构造（model=glm-ocr / Bearer / data:image;base64）→ Markdown 返回 → 表格解析 → 数字清洗 → BS 勾稽 → 无 Key 时返回结构化错误。
仓库不包含任何客户文档或扫描件；真实样本测试只在本地提供路径时运行。
适用场景与注意¶
适合需要批量处理扫描件 PDF、财务报表、合同条款，并构建知识库的用户。插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。
插件边界：
- 不处理加密 PDF / 需要密码的文档（交给下游）。
- 不做定时任务、不做目录监控。
- 不编造数字：OCR 拿不到或勾稽不平的数，标出来交人工，不硬凑。
- 扫描件/图片才调 OCR；有文本层的 PDF 先用 pypdf 直读。
- doc_preprocess 不修改任何原始文件。
生态背景¶
DeepSeek Harness（DSH）理念是「一切皆插件」；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。
短结尾¶
dsh-ocr 为 DeepSeek Harness 提供了本地 RapidOCR 与云端 GLM-OCR 双引擎支持，覆盖整页文本、财务报表勾稽、合同条款抽取与知识库预处理场景。安装后即可在 DSH 会话中使用 doc_ocr 与 doc_preprocess 两个工具。
- 目录页：https://www.skillhub.cn/plugins/zirscard/dsh-ocr
- GitHub：https://github.com/zirscard/dsh-ocr
