DeepSeek Harness 插件：`read_document` 工具

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.fs seam 進行，兼容任何已掛載的文件系統提供程序和沙盒策略。

安裝與啓用¶

安裝該插件需要指定一個已存在的 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 轉換和分頁機制，模型可以高效處理長文檔。開發者可以根據實際需求調整配置參數，以平衡性能和返回內容的質量。