前言¶

把一份年报 PDF、一张扫描发票或一份 Excel 丢给智能体，最常见的做法是先上传到云端解析服务，再把文本贴回对话。这条链路能用，但合同、财报、内部扫描件一旦离开本机，权限边界就不好收。纯文本模型也读不了二进制文档：没有本地解析，agent 只能看到文件名。

DeepSeek Harness（dsh）是 DeepSeek AI 开源的智能体框架，官方口号是「一切皆插件」：模型、工具、会话、沙箱和界面都可以在配置层增删，不必改核心源码。社区因此出现了一批只做一件事的插件。dsh-docs 做的就是文档这一侧——在本机把 PDF、Office、图片和扫描件转成 Markdown、纯文本或结构化 JSON，离线 OCR，不走 HTTP 服务，也不要 API Key。

本文按社区插件目录页、GitHub 仓库 README / README.zh-CN.md / INSTALL.md / package.json，以及官方 deepseek-ai/deepseek-harness 交叉核对后整理。社区插件目录 deepseek-harness-plugin.com 是独立站点，与 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。Harness 目前仍是开发者预览，插件可能随核心升级出现不兼容变更。

这是什么¶

dsh-docs 是一款面向 DeepSeek Harness 的文档智能插件，由 GitHub 用户 Sqhao-O 维护，仓库许可证为 MIT，主要语言是 TypeScript。社区目录把它归在「记忆」分类：它并不做跨会话知识图谱，而是把本地文档解析成模型能读的文本，相当于给 agent 补上一块可读的文件记忆。

有几个名字需要先分清，避免装错包：

• GitHub 仓库名是 dsh-docs。
• 发布到 npm 的包名、插件 id 是 dsh-doc（没有末尾的 s）。
• 工具名统一为 dshdoc_*。
• 初版曾用 dsh-docling / docling_*，现已更名。

package.json 当前版本是 0.1.1。截至 2026-08-18，GitHub API 显示该仓库 9 星；社区目录页同期展示为 6 星，以下以 GitHub 一手数据为准。运行前置是可用的 dsh CLI，Node 版本要求为 ^22.19 或 >= 24。

它要解决的问题很具体：把 PDF、Word、Excel、PowerPoint 交给本机引擎，拿回干净文本；把扫描件或图片交给离线 Tesseract，读出其中的字。仓库明确写了「无需 Docker、无需 HTTP 服务、无需 API Key，文档永不离开你的磁盘」。

核心功能¶

仓库 README 列出的已覆盖输入如下。集成测试会在临时目录生成 PDF、DOCX、XLSX、PPTX、PNG 与扫描 PDF 并走真实解析；其他 Xberg 支持的格式，作者建议用自己的语料先验证再上生产。

1. 办公与文本文件：PDF、DOCX、XLSX、PPTX、Markdown、HTML、CSV、纯文本。
2. 图片与扫描件：PNG、JPEG、TIFF、WebP，以及扫描 PDF，走本地 OCR。
3. 三种输出：返回给模型的 Markdown、纯文本，或 JSON 结构化 Tool Result。默认输出格式是 md。

解析引擎分两条路径，这一点对能不能开 OCR 很关键：

• Windows x64 完整路径：随包提供固定版本、自包含的 Python + Xberg 运行时。预构建产物含 CPython 3.11.9、xberg==1.0.14，以及固定的 eng / chi_sim Tesseract 语言包。下载会做 SHA-256 校验，并带 manifest、NOTICE、SPDX 清单，不改动全局 Python。这是仓库写明的「完整离线 OCR」路径。
• 任意平台的 Node 回退：原生 Xberg Node 绑定，用来做 PDF / Office / 文本解析。defaultOcr 默认为 false。若要在 Node 引擎上开 OCR，必须把 tessdataPath 指到已经审核过、含全部所需 .traineddata 的本地目录；缺少语言包会返回 ENGINE_OCR_UNAVAILABLE，不会去下载模型。

对外工具一共四个：

HTTP(S) 输入只会被识别并拒绝。若要解析远程文档，需要先用已审核的下载流程存到允许目录，再调用本插件。插件不会把 URL 交给 Xberg 或 Python worker，避免重定向和 DNS 重绑定。

转换时还可以带这些选项：

• page_range：从 1 开始、两端包含的页码，适用于 Markdown 和纯文本；JSON 输出会刻意保留完整结构化文档。
• ocr_languages：按请求覆盖语言集，例如 ["chi_sim", "eng"]。
• 引擎上报时，结果会标注 OCR: applied / OCR: not used。开启 OCR 不会覆盖 PDF 里完好的内嵌文本层。

安全边界也写在 README 里，不是口号：路径会 realpath 后比对白名单根目录和会话工作区，阻断 ..、符号链接逃逸、根目录、非文件和超大文件；授权后立刻读一次字节快照，解析用的是快照而不是之后可能被替换的路径；Node 与 Python 引擎都只收 bytes，不创建监听端口、URL 下载器、容器或外部解析服务。默认输入上限 maxFileBytes 为 52428800（50 MiB），返回给模型的上限 maxOutputChars 为 32000。

安装与启用¶

社区目录页给出的安装命令如下，以页面原文为准：

dsh plugin add github:Sqhao-O/dsh-docs

如需可复现安装，目录页建议固定 commit 哈希：

dsh plugin add github:Sqhao-O/dsh-docs#commit

把 #commit 换成实际提交哈希。目录页同时提醒：插件以当前 dsh 进程的权限运行，安装时可能执行代码；安装前应检查源代码仓库和许可证。

仓库 INSTALL.md 写得更细。dsh web 始终使用 web profile，装到 default 再开网页界面是看不到的。作者推荐的发布包装法是：

dsh plugin --profile web add dsh-doc

仅 Windows x64 需要再拉一份预构建离线 OCR 运行时，放到 node_modules 之外的稳定目录，避免插件升级时被删掉。YAML 里的路径要写成绝对路径，不要依赖 ~：

node $HOME/.dsh/profiles/web/node_modules/dsh-doc/scripts/fetch-runtime-win32-x64.mjs $HOME/.dsh/runtimes/dshdoc-runtime-win32-x64

然后在该 profile 的 cordis.patch.yml 里新增或更新这一条，保留已有条目：

- id: dsh-doc
  config:
    engine: python
    runtimeDir: $HOME/.dsh/runtimes/dshdoc-runtime-win32-x64
    defaultOcr: true
    maxOutputChars: 32000

把 $HOME 换成你的主目录绝对路径。会话工作区默认可读，不必先配 allowedLocalRoots；这个字段只用于工作区之外的共享文档库等持久目录。allowWorkspaceFiles: false 则回到纯白名单锁定。

其他平台跳过运行时下载，改用：

- id: dsh-doc
  config:
    engine: node
    defaultOcr: false
    maxOutputChars: 32000

装完后用下面这条核对合成配置，再重启 dsh web：

dsh --profile web --dump-config

INSTALL.md 提醒：dump 配置时 DSH 可能改写 profile 层，正式配置最好纳入版本控制，或先备份。重启之后先让 agent 调用 dshdoc_health，再解析工作区下的文件。

仓库还提供一段可直接贴进 dsh web 会话的安装提示词，由 agent 在终端里逐步完成安装、拉运行时、改 YAML 并验证。硬性约束写得很清楚：不要安装、启动或配置 Docling Serve、Docker、容器或任何远程文档转换服务；不要配置可下载的 OCR 后端，也不允许解析时下载模型。旧 profile 里的 baseUrl、apiKey、enableRemoteUrls、allowPrivateUrls 仅为迁移兼容而接受，不能重新开启远程解析。

典型用法¶

重启 dsh web 后，相对路径按 DSH 会话工作目录 解析，不是你启动 dsh web 时所在的那个目录。只有会话工作目录或 allowedLocalRoots 下的文件可读。仓库给出的自然语言示例是：

阅读 ./reports/annual-report.pdf，列出三个主要风险。
提取 ./financials.xlsx 的表格。
读取 ./scanned-invoice.png 的文字。

更稳妥的顺序是：先让 agent 跑 dshdoc_health，确认当前引擎和 OCR 语言包就绪，再用 dshdoc_extract 解析具体文件。完整 OCR 配置示例（Windows x64）还可以带上表格模式和输出格式：

- id: dsh-doc
  config:
    engine: python
    runtimeDir: /absolute/path/to/dshdoc-runtime-win32-x64
    maxFileBytes: 52428800
    maxOutputChars: 32000
    defaultOcr: true
    defaultTableMode: accurate
    defaultOutputFormat: md

engine 默认为 auto：已配置内嵌 Python 运行时就走 Python，否则走 Node Xberg。defaultOcr 默认是 false，只应在已经配好本地 tessdata 时打开。defaultTableMode 可选 fast 或 accurate。timeoutMs 默认 120000。

如果要把运行时拷到另一台 Windows 机器，仓库要求先跑：

node ./scripts/verify-runtime-win32-x64.mjs

校验 payload 哈希后再把 runtimeDir 指过去。从源码审计并重建运行时则用 node ./scripts/build-runtime-win32-x64.mjs，产物默认落在 Git 忽略的 .dsh-runtime/runtime-win32-x64。

Python worker 只经 stdio 接收文件字节快照、显示名称、MIME 和选项，不接收用户路径或 URL；缺少 OCR 语言包会安全失败，并禁用文档派生的 OCR 缓存。

适用场景与注意事项¶

比较适合这几类用法：

• 本机已经有 PDF / Office 资料，希望 dsh web 直接读，而不是先手动转文本。
• 扫描件、拍照发票、截图里的字需要进对话，但不想走云端 OCR。
• Windows x64 环境，愿意下载一份固定哈希的离线运行时，换完整的 PDF / Office / OCR 覆盖。
• Linux / macOS 上主要解析带文本层的 PDF 和 Office，可以接受 Node 回退、默认关闭 OCR。

使用前有几条边界需要看清：

1. 权限与来源。插件以当前 dsh 进程的权限运行，安装时可能执行构建脚本。装之前应阅读 Sqhao-O/dsh-docs 源码和 MIT 许可证；需要可复现安装时固定 commit。
2. 平台差异。完整离线 OCR 目前按仓库说明针对 Windows x64 预构建；其他平台的默认路径是 Node 引擎且 defaultOcr: false。不要默认「装上就能识别扫描件」。
3. 可读范围。相对路径相对会话工作区，不是启动目录。工作区之外的目录必须写进 allowedLocalRoots。
4. 分类名容易误会。目录把它放在「记忆」，它解决的是本地文档可读，不是 graph-memory 那类跨会话经验库。同生态里还有一个 dsh-docs-panel，做的是 Web UI 里读 Markdown 笔记面板，和本插件不是一回事。
5. 远程文档。dshdoc_convert_url 会拒绝 URL。先下载到允许目录再解析。
6. 结果长度。返回给模型的文本默认截到 32000 字符；JSON 限长时用的是模型真正看到的格式化文本。超长年报可能需要 page_range 分段。
7. 运行时位置。OCR 运行时不要放在 node_modules 里，插件升级会把它清掉。
8. 版本仍早。当前 npm 版本是 0.1.1，测试覆盖了常见办公格式和扫描 PDF；仓库仍建议对未列入测试的格式先用自己的语料验证。

小结¶

dsh-docs 给 DeepSeek Harness 补的是本机文档入口：PDF、Office、图片和扫描件在授权目录内解析，Windows x64 可以走固定哈希的离线 Python / Tesseract 运行时，其他平台还能用 Node Xberg 做非 OCR 回退。社区目录安装命令是 dsh plugin add github:Sqhao-O/dsh-docs；日常在 dsh web 里使用时，仓库更推荐 dsh plugin --profile web add dsh-doc，并按平台决定要不要拉 OCR 运行时。

目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-docs/

GitHub：https://github.com/Sqhao-O/dsh-docs