DeepSeek Harness 文檔工具插件介紹

DeepSeek Harness (DSH) 的插件化架構允許模型直接調用沙盒內的工具。在構建 Agent 處理文檔（如生成報表、修改 PDF、讀取日誌）時，通常需要通過 Shell 調用外部命令，這增加了延遲和系統開銷。dsh-tool-doc 插件旨在解決這個問題，它將文檔的讀寫操作直接集成到 DSH 的工具集中，讓模型能夠直接處理文檔文件。

插件定位¶

這是一個由 zhangjiabo522 維護的文檔處理工具插件，License 爲 MIT。它註冊了三個核心工具到 ctx.tools，分別對應文檔的讀取、創建和編輯。

核心功能¶

1. 讀取文檔 (read_document)¶

該工具支持多種常見文檔格式，通過解析文件內容返回文本。
* 支持格式：PDF（文本層，逐頁）、DOCX、XLSX（所有工作表，單元格值）、PPTX（每張幻燈片文本）、CSV（自動識別分隔符和引號）以及 Markdown/文本。
* 限制：
* 文本輸出受 maxTextChars 限制（默認 200,000），超出會截斷並提示。
* 二進制讀取受 readMaxBytes 限制（默認 50 MB）。
* 掃描或圖片型 PDF 無法讀取到文本。
* 返回格式：文本格式返回內容，二進制格式返回字節數。

2. 創建文檔 (create_document)¶

用於創建全新的文檔文件。目標文件路徑必須不存在（語義爲 createIfAbsent，即不覆蓋現有文件）。
* 輸入內容：Markdown 輕量語法（支持 #、## 等標題、- 列表、表格）。
* 格式支持：
* DOCX/PDF：支持 Markdown 結構及 title 字段（DOCX）。
* XLSX：支持 sheets 數組。
* CSV：支持 rows 數組。
* Markdown/文本：支持純文本。
* PDF 特性：創建 PDF 時，如果系統發現 CJK 字體，會嘗試嵌入該字體；也可以通過配置 cjkFontPath 指定字體文件。

3. 編輯文檔 (edit_document)¶

對現有文檔進行原地修改。
* 操作類型：
* DOCX：replace_text（段落級文本替換，默認替換 1 次，'all' 替換全部；僅匹配單個 <w:t> 文本運行）、append_paragraph（追加段落）。
* XLSX：set_cell（設置單元格）、append_rows（追加行）、add_sheet（添加工作表，sheet 參數默認爲第一個工作表）。
* CSV：set_cell、append_rows。
* 校驗機制：所有操作在執行前會進行校驗，一旦發現無效操作（如未知工作表、零匹配），會立即中止調用並報錯，不會執行寫入。

使用示例¶

模型在調用時，會看到針對不同格式的精確工具模式定義。以下是常見調用方式：

// 讀取文檔
read_document(file_path)

// 創建新文檔
create_document(file_path, content)

// 編輯文檔
edit_document(file_path, operations)

具體的編輯操作（operations）結構如下：

// DOCX 文本替換
{
  op: 'replace_text',
  text: '目標文本',
  newText: '替換文本',
  count: 1 // 默認爲 1，'all' 替換所有
}

// XLSX 設置單元格
{
  op: 'set_cell',
  sheet: 1,
  row: 5,
  column: 3,
  value: '新值'
}

// CSV 追加行
{
  op: 'append_rows',
  rows: [['A1', 'B1'], ['A2', 'B2']]
}

侷限性與注意事項¶

格式與功能限制¶

1. DOCX 編輯範圍：僅支持段落級文本替換，不支持跨文本運行匹配（即文本被拆分在不同運行中無法匹配）。不支持編輯頁眉、頁腳、字段和編號。
2. PDF 與 PPTX 編輯：不支持原地編輯，必須使用 create_document 重新創建文件。
3. 舊版格式：不支持舊版二進制 Office 格式 (.doc, .xls, .ppt)，需先轉換爲 OpenXML 格式。
4. PDF 字體：CJK 字體依賴系統發現，若無可用字體，創建的 PDF 會回退到拉丁字體。

安全與權限¶

1. 二進制寫入策略：文本格式（CSV/Markdown 等）的讀寫通過 ctx.fs 走沙盒策略。但二進制格式（PDF/XLSX/PPTX）的寫入直接使用 node:fs 寫入解析路徑，不遵循沙盒寫策略。
2. 安裝前檢查：由於二進制寫入不經過沙盒策略，建議在安裝前檢查源碼與許可證，確保其行爲符合當前環境的權限要求。

總結¶

dsh-tool-doc 插件爲 DSH Agent 提供了在進程內直接操作文檔的能力。它通過明確的工具接口和嚴格的操作校驗，降低了文檔處理的複雜度。使用時需注意其針對特定格式（如 DOCX）和舊版文件的限制，以及二進制寫入的權限特性。

GitHub 倉庫