jiaoqsh/dsh-document

dsh-document

一个 DeepSeek Harness 插件包（@jiaoqsh/dsh-document），为模型提供 read_document 工具：Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV 和 PDF 文件会被转换为带行号的 Markdown，模型可以通过 offset/limit 分页浏览。

转换在本地运行：办公格式通过 @firecrawl/anydoc（Rust 核心，Node 绑定），PDF 通过 @firecrawl/pdf-inspector（WASM 构建，在工作线程中运行）——无需 API 密钥、无需网络、无外部二进制文件；两者均为 MIT 许可。PDF 支持页面选择、 标记以及页面信息：总页数、基于文本 / 扫描 / 混合，以及哪些页面没有可提取的文本。文件通过 harness 的 ctx.fs 接缝读取，因此部署所挂载的任何文件系统提供程序和沙箱策略都会原样生效。

安装

从 npm 安装到现有 profile（web、headless 或你自己的 profile）中：

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

npm 包附带已构建的代码，因此安装时不会运行任何内容。发布版本通过 npm 可信发布从本仓库的 release.yml 发布，并带有来源证明。

改为从 GitHub 安装

dsh plugin --profile web add github:jiaoqsh/dsh-document#

git 安装会获取源代码，因此 pnpm ≥ 10 会拒绝运行该包的 prepare（对 src/ 的 tsdown 转译），直到你允许它：第一次 add 会失败并打印出要复制到 profile 的 pnpm-workspace.yaml（$DSH_HOME/profiles//pnpm-workspace.yaml）中的确切键。该键命名的是解析后的 tarball，因此裸包名不匹配：

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

重新运行 add。允许构建意味着在安装时于你的机器上执行此包的代码；请固定一个 commit，这样后续的推送就无法改变运行的内容。

dsh plugin 会为 @deepseek-ai/* 包打印 "missing peer" 警告：这是预期行为。dsh 安装会在运行时提供它们；profile 有意不安装 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'

配置

该 bundle 的层插入一行 document-tools，使用 schema 默认值。在你的 profile 的 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 页）：

/work/report.pdf
pdf
5 pages, text-based; showing pages 2, 4

1:
2:
3: Revenue grew 12% year over year.

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

混合型 PDF 会在  之前添加 Pages 3, 7-8 contain no extractable text (scanned or image content); their content is missing below and would need OCR.。非 PDF 格式会省略  行。
失败在模型术语中属于工具错误：不支持的扩展名（对于纯文本应指向 read）、在非 PDF 上使用 pages、pages 值格式错误、未找到、不是常规文件、超过 maxInputBytes、已加密、损坏或不完整、引擎资源限制、超出最后一页的页码、取消，或无可提取文本（扫描版或纯图像 PDF 会说明这一点，并说明需要 OCR；此工具不执行 OCR）。

模型体验

系统提示词部分 tool:read_document

模型看到的内容

一句固定的话，顺序为 100，与随附的 tool:read 指南并列：

使用 read_document 工具——而不是 read 或 shell 命令——来检查 PDF、Word、PowerPoint、Excel、OpenDocument、RTF、EPUB 和 CSV 文件。它会返回转换为带行号 Markdown 的文档；使用 offset 和 limit 继续阅读长文档。对于 PDF，传入 pages（例如 "1-3,7"）以仅读取这些页面；像  这样的页面标记会显示每一页的起始位置。

Token 影响

固定：该部分和工具 schema 会为每个请求增加恒定数量的 token；结果每次调用最多增加 maxOutputBytes。

KV 缓存影响

前缀稳定：该部分文本和 schema 在请求之间从不改变，因此它们不会使缓存的提示词前缀失效。

已知限制与推迟的工作

- 无 OCR —— 没有文本层的页面会被报告（pagesNeedingOcr、 行），但不会被读取；完全扫描版或纯图像 PDF 会报错并指明原因。
- PDF 转换每次调用都在新的工作线程中运行 —— 取消会终止它，并且 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，然后推送匹配的标签（git tag v0.2.0 && git push origin v0.2.0）。release.yml 会检查标签与版本是否匹配，运行检查，通过可信发布发布到 npm，并使用生成的说明创建 GitHub release。
tests/fixtures/ 下的测试夹具曾使用 macOS 的 textutil 和 cupsfilter 生成过一次（包括一个五页 PDF 和一个仅含图像的 PDF），并已提交，以便测试套件可在任何环境中运行。在源码模式下，PDF worker 以 .ts 形式启动，并带有 --experimental-strip-types，因此它不包含仅 TypeScript 的运行时语法。

许可证

MIT