DeepSeek Harness (DSH) 侧重于通过插件扩展功能。在模型推理场景中，让模型直接读取本地文档是常见需求。通常这需要借助外部 API 或 Shell 命令。@jiaoqsh/dsh-document 插件在 DSH 内部为模型添加了一个 read_document 工具，将本地文档转换为 Markdown 格式供模型解析。
核心功能¶
该插件通过 read_document 工具提供文件读取能力，支持多种格式转换和本地处理。
- 格式支持：支持 Word (.doc, .docm, .docx)、PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm)、Excel (.xls, .xlsx, .xlsm, .xlsb)、OpenDocument (.odt, .ods, .odp)、RTF、EPUB、CSV 以及 PDF。
- 本地转换：转换过程完全在本地运行，使用
@firecrawl/anydoc处理 Office 格式，使用@firecrawl/pdf-inspector(WASM) 处理 PDF。无需 API 密钥或网络连接。 - 分页与元数据：提供
offset和limit分页参数。对于 PDF，支持页面选择（如 “1-3,7”），并返回元数据（总页数、文档类型、需要 OCR 的页面）。 - 文件系统集成：文件读取通过 DSH 的
ctx.fsseam 进行，兼容任何已挂载的文件系统提供程序和沙盒策略。
安装与启用¶
安装该插件需要指定一个已存在的 profile（例如 web、headless 或自定义 profile）。
dsh plugin --profile web add @jiaoqsh/dsh-document
安装后，可以通过以下命令验证插件是否加载成功：
dsh --profile web --dump-config
如果需要移除插件：
dsh plugin --profile web remove @jiaoqsh/dsh-document
配置¶
插件通过 cordis.patch.yml 配置。默认配置会插入一个 document-tools 层。可以通过配置覆盖来调整参数。
| 配置项 | 默认值 | 说明 |
|---|---|---|
maxInputBytes |
52428800 (50 MiB) | 输入文件大小的上限（字节）。在缓冲任何字节之前由文件系统提供程序检查，超出此限制的文件将被拒绝。 |
readLimit |
2000 | 单次调用返回的 Markdown 行数的默认值和最大值。 |
maxLineLength |
2000 | 返回行文本的最大字符数。超出部分会被截断。 |
maxOutputBytes |
51200 (50 KiB) | 单次调用返回的行文本字节上限。 |
pdfMaxPages |
100 | 单次 pages 选择中可命名的最大不同页数。 |
pdfProfile |
fidelity |
PDF Markdown 配置文件：fidelity 保留源结构，compact 生成更少的 token。 |
使用示例¶
模型调用 read_document 工具的接口如下：
read_document(file_path: string, offset?: number, limit?: number, pages?: string)
file_path：通过文件系统后端解析。相对路径相对于调用会话的工作区解析。offset：返回 Markdown 的起始行号（默认为 1）。limit：返回的行数（默认和最大值为readLimit）。pages：仅 PDF 支持。1 基准的页码或范围，如"1-3,7"（最多pdfMaxPages个页面）。默认为所有页面。
返回格式¶
工具返回的格式包含文档路径、格式、内容以及 PDF 特有的元数据。
<path>/work/report.pdf</path>
<format>pdf</format>
<pdf>5 pages, text-based; showing pages 2, 4</pdf>
<content>
1: <!-- Page 2 -->
2:
3: Revenue grew 12% year over year.
(Showing lines 1-3 of 8. Use offset=4 to continue.)
</content>
错误处理¶
工具将错误视为模型术语中的工具错误。常见错误包括：
* 不支持的扩展名。
* 在非 PDF 文件上使用 pages 参数。
* 文件未找到、不是常规文件、超过 maxInputBytes、已加密、损坏或内容不可提取（如扫描 PDF）。
限制与注意¶
- 无 OCR 支持：插件不会执行 OCR。如果 PDF 没有 text layer，会返回警告但不会读取内容。完全扫描或纯图片的 PDF 会报错。
- 性能：PDF 转换在每次调用时运行在独立的 worker 线程中，启动开销约 50ms。Office 格式转换在 libuv 线程池中运行，一旦启动无法取消。
- 布局问题：布局密集的 PDF 可能会将段落合并为长行，随后被
maxLineLength截断。 - 技术栈：使用 WASM 构建
pdf-inspector，而非原生二进制。需要 Node.js 版本 >= 22.19。 - 依赖管理：
peerDependencies不会随 profile 自动安装，需确保环境已正确配置。
总结¶
该插件为 DSH 提供了本地、安全且无需网络交互的文档读取能力。通过 Markdown 转换和分页机制，模型可以高效处理长文档。开发者可以根据实际需求调整配置参数，以平衡性能和返回内容的质量。
