文档读取器 jiaoqsh/dsh-document

dsh-document

一个 DeepSeek Harness 插件包（@jiaoqsh/dsh-document），给模型提供 read_document 工具：Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV 和 PDF 文件都会转成带行号的 Markdown，模型可以用 offset/limit 翻页读取。

转换在本地完成：office 格式走 @firecrawl/anydoc（Rust 内核，Node 绑定），PDF 走 @firecrawl/pdf-inspector（WASM 构建，跑在 worker 线程里）——不需要 API key，不联网，不依赖外部二进制文件；两者都是 MIT。PDF 支持选页，会插入 标记，并给出页面信息：总页数、文本型 / 扫描型 / 混合型，以及哪些页没有可提取文本。文件通过 harness 的 ctx.fs 接缝读取，所以部署挂载什么文件系统服务商和沙箱策略，就原样生效。

安装

装进已有配置档（web、headless 或你自己的），从 npm 安装：

dsh plugin --profile web add @jiaoqsh/dsh-document

npm 包直接带构建好的代码，安装时不会跑任何东西。发布由本仓库的 release.yml 通过 npm trusted publishing 完成，附带 provenance 证明。

改用 GitHub 安装

dsh plugin --profile web add github:jiaoqsh/dsh-document#<commit-sha>

git 安装会拉取源码，所以 pnpm ≥ 10 会拒绝执行包的 prepare（用 tsdown 转译 src/），直到你放行：第一次 add 会失败，并打印出要复制进配置档 pnpm-workspace.yaml（$DSH_HOME/profiles/<name>/pnpm-workspace.yaml）的确切键名。这个键名指向解析后的 tarball，所以光写包名匹配不上：

allowBuilds:
'@jiaoqsh/dsh-document@https://codeload.github.com/jiaoqsh/dsh-document/tar.gz/<commit-sha>': true

重新跑一遍 add。放行构建意味着安装时会在你机器上执行这个包的代码；请固定到某个 commit，这样之后的推送就改不了实际运行的内容。

dsh plugin 会为 @deepseek-ai/* 包打印 "missing peer" 警告：这是正常的。dsh 安装本身在运行时提供这些包；配置档有意不安装 peer。

验证，然后启动：

dsh --profile web --dump-config # shows a "# == @jiaoqsh/dsh-document" layer
dsh --profile web

卸载用 dsh plugin --profile web remove @jiaoqsh/dsh-document。

从 harness 源码检出安装

pnpm dsh web --patch /absolute/path/to/dsh-document/overlay.yml

其中 overlay 用绝对路径插入构建好的入口：

- insert:
- id: document-tools
name: '/absolute/path/to/dsh-document/lib/index.js'

配置

插件包的层插入一行 document-tools，用 schema 默认值。在配置档的 cordis.patch.yml 里按 id 覆盖它；补丁会替换整个 config，所以需要的每个键都要重新写全：

- id: document-tools
config:
maxInputBytes: 104857600 # 100 MiB
readLimit: 2000
maxLineLength: 2000
maxOutputBytes: 51200
pdfMaxPages: 100
pdfProfile: fidelity

| 键 | 默认值 | 含义 |
| maxInputBytes | 52428800 (50 MiB) | 源文件的字节上限，含边界。文件系统服务商在缓冲任何字节之前就会强制执行；超过上限的文件直接拒绝。 |
| readLimit | 2000 | 单次调用返回的 Markdown 行数默认值与最大值。 |
| maxLineLength | 2000 | 每行返回的最大字符数；超出部分截断，并加上 … [line truncated]。 |
| maxOutputBytes | 51200 (50 KiB) | 单次调用返回的行文本最大字节数；窗口会提前停止，页脚会说明如何继续。 |
| pdfMaxPages | 100 | 一次 pages 选择最多能指定的不同页数。 |
| pdfProfile | fidelity | PDF 的 Markdown 配置档：fidelity 保留源结构，compact 消耗更少 token。 |

每个数值都必须是正整数，pdfProfile 必须是这两个名字之一；否则插件加载失败，报错信息会指出是哪个键。

工具

read_document(file_path, offset?, limit?, pages?)

- file_path —— 由文件系统后端解析；相对路径按调用会话的工作区解析。
- offset —— 转换后 Markdown 的起始行，从 1 开始计数（默认 1）。
- limit —— 返回的行数（默认值与最大值都是 readLimit）。
- pages —— 仅 PDF：要转换的页，从 1 开始计数，可写数字和范围，如 "1-3,7"（最多 pdfMaxPages 页）。默认：全部页。指定的页超出最后一页会报错，并说明总页数。

支持的扩展名：.pdf、.doc、.docm、.docx、.ppt、.pps、.pot、.pptx、.pptm、.ppsx、.ppsm、.xls、.xlsx、.xlsm、.xlsb、.odt、.ods、.odp、.rtf、.epub、.csv。格式由扩展名决定，绝不靠内容嗅探（CSV 没有签名）。

规范值（Code Mode 收到的内容）：

{ path: string, format: 'pdf' | 'docx' | ..., offset: number,
lines: { number: number, text: string }[], totalLines: number, truncatedByBytes: boolean,
pdf?: { pageCount: number, kind: 'text' | 'scanned' | 'image' | 'mixed',
pagesNeedingOcr: number[], pages?: number[], title?: string } }

面向模型的文本（一个 PDF，共 5 页，取第 2 页和第 4 页）：

<path>/work/report.pdf</path>
<format>pdf</format>
<pdf>5 pages, text-based; showing pages 2, 4</pdf>
<content>
1:
2:
3: Revenue grew 12% year over year.

(Showing lines 1-3 of 8. Use offset=4 to continue.)
</content>

混合型 PDF 会在 <content> 之前加上 <warning>Pages 3, 7-8 contain no extractable text (scanned or image content); their content is missing below and would need OCR.</warning>。非 PDF 格式不输出 <pdf> 行。
失败在模型看来就是工具错误：不支持的扩展名（纯文本请用 read）、对非 PDF 传 pages、pages 值格式错误、文件不存在、不是普通文件、超过 maxInputBytes、加密、损坏或不完整、引擎资源限制、页码超出末页、取消，或者没有可提取文本（扫描件或纯图片 PDF 会明确说明需要 OCR；本工具不做 OCR）。

模型体验

系统提示词段落 tool:read_document

模型看到的内容

一句固定的话，顺序 100，紧挨着随包发布的 tool:read 指引：

Use the read_document tool — not read or shell commands — to inspect PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, and CSV files. It returns the document converted to line-numbered Markdown; use offset and limit to continue reading long documents. For a PDF, pass pages (for example "1-3,7") to read only those pages; page markers like show where each page starts.

Token 影响

固定：段落和工具 schema 给每个请求增加常量数量的 token；结果每次调用最多增加 maxOutputBytes。

KV Cache 影响

前缀稳定：段落文本和 schema 在请求之间从不变化，因此不会让已缓存的提示词前缀失效。

已知限制与后续工作

- 不做 OCR —— 没有文本层的页面会被报告出来（pagesNeedingOcr、<warning> 行），但不会被读取；完全扫描或纯图片的 PDF 会报错并说明原因。
- PDF 转换每次调用都在新的 worker 线程中运行 —— 取消会终止它，harness 事件循环保持空闲，代价是每次调用约 50 ms 的 WASM 启动时间。Office 格式转换（anydoc）跑在 libuv 线程池上，一旦开始就无法取消；maxInputBytes 是它的边界。
- 排版复杂的 PDF 可能把段落压成长行（随后被 maxLineLength 截断）；pdfProfile: compact 用结构换 token。
- 引擎是固定的 —— src/converter.ts 里的 DocumentConverter 接口和 routeConverters 是接入托管引擎或支持 OCR 引擎的接缝；目前一个都没接。
- 没有使用 pdf-inspector 原生二进制 —— 它的 npm 构建不提供 darwin-x64 二进制，所以统一跑 WASM 构建，只维护一条代码路径。

开发

pnpm install # also builds lib/ via prepare
pnpm run typecheck
pnpm test # real Cordis Context + real registry + real local fs; no API key
pnpm run build

发布：在 main 上更新 package.json 里的 version，然后推送匹配的 tag（git tag v0.2.0 && git push origin v0.2.0）。release.yml 会校验 tag 与版本是否一致，跑检查，通过 trusted publishing 发布到 npm，并用自动生成的说明创建 GitHub release。
tests/fixtures/ 下的测试夹具是用 macOS 的 textutil 和 cupsfilter 一次性生成的（包括一份五页 PDF 和一份纯图片 PDF），已提交到仓库，因此测试套件在任何地方都能跑。在源码模式下，PDF worker 以 .ts 形式启动，并带上 --experimental-strip-types，所以它不依赖任何 TypeScript 专有的运行时语法。

许可证

MIT