前言¶
在 DeepSeek Harness（DSH）里让智能体读 PDF、Word、Excel 或扫描件，常见做法是接远程文档转换服务、起 Docker 容器，或把文件上传到带 API Key 的云端 OCR。这些路径要么依赖网络与额外部署，要么会把文档送出本机。
dsh-doc（GitHub 仓库 Sqhao-O/dsh-docs）走另一条路：在 DSH 进程内用本地引擎解析文档，Windows x64 上还可挂载预构建的离线 Python + Xberg 运行时，配合本地 Tesseract 语言包做 OCR。不需要 Docker、HTTP 服务或 API Key，文档不离开磁盘。
下面介绍插件定位、能力边界、安装步骤与典型用法。事实均来自项目 README、package.json 与 SkillHub 目录页。
这是什么¶
dsh-doc 是维护者 Sqhao-O 发布的 DSH 插件，npm 包名与插件 id 均为 dsh-doc（工具前缀 dshdoc_*；早期曾用 dsh-docling / docling_* 命名，现已更名）。SkillHub 分类为「模型推理」，仓库约 12 stars，许可证 MIT，当前发布版本 0.1.1。
一句话定位：给 DSH 智能体提供全本地的文档智能能力——把 PDF、Office、图片或扫描件解析为 Markdown、纯文本或结构化 JSON，供后续推理与问答使用。
核心功能¶
支持的输入格式¶
README 列明并已通过集成测试验证的格式包括：
- 文档：PDF、DOCX、XLSX、PPTX、Markdown、HTML、CSV 及纯文本
- 图片与扫描件：PNG、JPEG、TIFF、WebP，以及需 OCR 的扫描版 PDF
其他 Xberg 支持的格式可在自有语料上自行验证后再用于生产。
输出形态¶
转换结果可为 Markdown、纯文本，或 JSON 结构的 Tool Result。page_range 对 Markdown/纯文本按从 1 开始的页码做区间截取；JSON 输出保留完整结构化文档。
双引擎架构¶
| 平台 | 推荐引擎 | OCR |
|---|---|---|
| Windows x64 | engine: python，指向预构建 runtime |
默认开启（defaultOcr: true），内置英文与简体中文 Tesseract 数据 |
| 其他平台 | engine: node（Xberg Node 绑定） |
默认关闭；若需 OCR 须本地配置 tessdataPath，缺语言包返回 ENGINE_OCR_UNAVAILABLE，不会自动下载模型 |
Windows 预构建运行时包含 CPython 3.11.9、xberg==1.0.14 及固定的 eng / chi_sim 语言包；下载与解压均做 SHA-256 校验。Python worker 仅通过 stdio 接收文件字节快照、显示名、MIME 与转换选项，不接收用户路径或 URL，离线运行且禁用文档派生 OCR 缓存。
提供的工具¶
| 工具 | 用途 |
|---|---|
dshdoc_health |
检查当前所选本地引擎是否就绪 |
dshdoc_extract |
解析本地文件的便捷入口（推荐） |
dshdoc_convert_file |
解析白名单内的本地文件 |
dshdoc_convert_url |
兼容桩，对 HTTP(S) 输入返回 UNSUPPORTED_URL |
插件检测到 URL 输入会直接拒绝，避免把远程地址转发给 Xberg 或 Python。远程文档须先下载到允许读取的本地目录，再调用本地解析工具。
路径与权限¶
会话工作区默认可读。若需访问工作区以外的持久目录（例如共享文档库），在 cordis.patch.yml 中配置 allowedLocalRoots。相对路径相对于 DSH 会话工作区解析，而非 dsh web 启动时的 shell 目录。
安装与启用¶
前置条件：本机已安装可用的 dsh CLI，Node 版本为 ^22.19 或 >= 24。
1. 安装插件包¶
在目标 profile（以下以 web 为例）安装已发布的 npm 包：
dsh plugin --profile web add dsh-doc
2. Windows x64：下载离线 OCR 运行时¶
将预构建运行时放到 node_modules 之外，避免插件升级时删除：
node <home>/.dsh/profiles/web/node_modules/dsh-doc/scripts/fetch-runtime-win32-x64.mjs <home>/.dsh/runtimes/dshdoc-runtime-win32-x64
将 <home> 替换为本机用户主目录的绝对路径。脚本会校验压缩包 SHA-256，并对解压文件做 manifest 校验。非 Windows x64 平台跳过此步，后续使用 engine: node。
3. 编辑 profile 配置¶
在 <home>/.dsh/profiles/web/cordis.patch.yml 中保留已有条目，新增或更新：
Windows x64（完整 OCR 能力）：
- id: dsh-doc
config:
engine: python
runtimeDir: <home>/.dsh/runtimes/dshdoc-runtime-win32-x64
maxFileBytes: 52428800
maxOutputChars: 32000
defaultOcr: true
defaultTableMode: accurate
defaultOutputFormat: md
其他平台（Node 回退，无默认 OCR）：
- id: dsh-doc
config:
engine: node
defaultOcr: false
maxOutputChars: 32000
4. 验证并重启¶
确认配置已生效：
dsh --profile web --dump-config
检查输出中 dsh-doc 条目是否携带预期 config。重启 dsh web 后，调用 dshdoc_health 确认引擎状态。
README 还提供一段「一键安装」提示词，可粘贴到运行中的 DSH 会话，由智能体在终端完成上述步骤；详见仓库 INSTALL.md。
典型用法¶
安装完成并重启 dsh web 后，可在会话中让智能体读取工作区内的本地文件，例如：
Read ./reports/annual-report.pdf and give me the three main risks.
Extract the tables from ./financials.xlsx.
Read the text from ./scanned-invoice.png.
也可在工具层直接调用 dshdoc_extract 解析指定路径。仅工作区或 allowedLocalRoots 下的路径可读。
适用场景与注意¶
适合谁
- 需要在 DSH 工作流中处理合同、报表、幻灯片、扫描发票等本地文档，且希望数据不出本机的开发者
- Windows x64 用户需要开箱即用的离线 OCR（中英）时，优先使用 Python 引擎路径
- 不愿维护 Docling Serve、Docker 或远程文档 API 的团队
使用注意
- 插件以当前
dsh进程的权限运行，安装前应审阅 源码 与 MIT 许可证。 - 不要将 Docling Serve、Docker 容器或可下载 OCR 后端接入此插件；项目明确禁止这类远程或自动拉取模型的配置。
- 非 Windows 平台默认无离线 OCR；若业务强依赖扫描件识别，应在 Windows x64 上部署 Python 运行时，或自行准备经审查的本地
tessdataPath。 - 单文件大小受
maxFileBytes（默认 52428800 字节）与maxOutputChars（示例配置 32000）限制，超大文档需分段或调高配置。 - SkillHub 目录页（skillhub.cn/plugins/Sqhao-O/dsh-docs）为社区收录站点，与 DeepSeek / 幻方无官方从属关系；安装命令以 README 与 npm 包
dsh-doc为准。
结尾¶
dsh-doc 把 PDF、Office、图片与扫描件的解析收拢到 DSH 插件内，在 Windows x64 上提供完整的离线 OCR 路径，在其他平台上以 Node 引擎覆盖非 OCR 解析需求。若你的智能体需要「读本地文档再推理」，可按上文步骤安装并先用 dshdoc_health 确认环境。
- SkillHub 目录：https://www.skillhub.cn/plugins/Sqhao-O/dsh-docs
- GitHub 仓库：https://github.com/Sqhao-O/dsh-docs
