前言¶
DeepSeek Harness（DSH）的理念是“一切皆插件”，社区通过独立站点（如 skillhub.cn）提供各类工具。在构建本地化智能体时，识别手写内容（如笔记、草稿）是一个常见需求。传统方案往往依赖云端 API，存在隐私泄露风险且依赖网络。下面介绍一款本地 OCR 插件，它能在不联网的情况下，将手写中文与数学公式图片转换为 Markdown 文本和 LaTeX 公式。
这是什么¶
kl3jd/handwritten-ocr 是由维护者 KL3jd 开发的一个本地 OCR 插件。它的核心功能是整页手写笔记识别：将图片中的中文纯文本提取出来，并将数学公式转换为 LaTeX 格式。插件全程在本地运行，数据不出本机，可作为 DSH（或其他 LLM 工具框架）的插件调用。
核心功能¶
- 整页识别：支持将整页手写笔记转换为 Markdown，包含中文纯文本和公式 LaTeX。
- 多后端支持：支持 GPU（DirectML，推荐）、CPU 和 NPU 三种推理模式。
- 多种接口：提供 FastAPI HTTP 服务和 CLI 命令行工具，方便集成。
- DSH 工具集成：内置 DSH 工具，LLM 可直接调用
ocr_image工具识别本地图片。
安装¶
插件提供了 Windows 的一键安装脚本，会自动完成虚拟环境搭建、依赖安装、模型下载和 DSH 预设配置。
powershell -ExecutionPolicy Bypass -File install.ps1
安装脚本会自动执行以下步骤：
1. 创建 Python 虚拟环境。
2. 安装依赖包（优先使用清华源，失败则回退官方源）。
3. 下载 OCR 模型（使用 hf-mirror 国内镜像）。
4. 安装 DSH 预设文件。
如果本地已有模型，可以在安装命令中添加 -SkipModels 参数跳过下载。
使用¶
安装完成后，可以通过 CLI、HTTP 服务或 DSH 工具进行调用。
CLI 调用¶
使用命令行工具直接识别图片。由于是每次启动新进程，模型会重新加载，速度较慢。
python ocr_cli.py 笔记照片.jpg --mode gpu
HTTP 服务¶
推荐启动常驻 HTTP 服务。模型只需加载一次，后续请求响应极快。
# 启动服务（默认端口 8765）
python ocr_server.py
服务启动后，可以通过浏览器访问 http://127.0.0.1:8765/ 查看管理面板，实时监控服务状态、PID、引擎加载情况，并修改配置参数（支持热加载）。
DSH 工具调用¶
安装脚本会自动将预设文件复制到 DSH 的 preset-ocr-assistant 目录。刷新后，LLM 即可拥有 ocr_image 工具。
- 首次调用：DSH 调用工具时会自动拉起 OCR 服务（约 25 秒加载模型）。
- 后续调用：识别速度约 2~3 秒返回结果。
- 环境变量：如果系统找不到 Python，可通过设置
OCR_PY或OCR_CLI环境变量指定路径。
设置¶
插件的核心配置集中在 settings.json 文件中，无需修改代码即可调整行为。
主要配置项包括：
* mode：推理模式（gpu / npu / cpu / auto）。
* formula_backend：公式后端（unimernet / mfr / auto）。
* formula_iou、mfd_conf：用于控制公式检测的阈值和合并逻辑。
* merge_x_iou、merge_y_gap：用于合并被拆分的公式碎片。
此外，可通过环境变量 OCR_SETTINGS 覆盖默认配置路径。
已知限制¶
- NPU 模式问题：AMD RyzenAI-SW#389 问题会阻塞 NPU 模式（Windows + RAI 1.8.0 下 DPU 分派报错）。建议在 AMD 硬件上使用 GPU 或 CPU 模式。
- 矩阵输出：手写矩阵的完整
bmatrix输出仍在打磨中，当前可能会被拆成多个公式框。 - 隐私：全程本地推理，图片与数据不会离开本机。
总结¶
该插件通过本地化方案解决了手写内容数字化的问题，适合需要在本地处理敏感数据或离线使用的场景。配合 DSH 的插件化生态，可以轻松将其集成到智能体工作流中。
- 插件目录：https://www.skillhub.cn/plugins/KL3jd/handwritten-ocr
- GitHub 仓库：https://github.com/KL3jd/handwritten-ocr
