The pluggable architecture of DeepSeek Harness (DSH) allows models to directly invoke tools inside the sandbox. When building an Agent to process documents (such as generating reports, modifying PDFs, or reading logs), external commands are usually invoked through a Shell, which increases latency and system overhead. The dsh-tool-doc plugin aims to solve this problem by integrating document read and write operations directly into DSH’s tool set, enabling the model to handle document files directly.

Plugin Positioning

This is a document processing tool plugin maintained by zhangjiabo522, under the MIT License. It registers three core tools to ctx.tools, corresponding to document reading, creation, and editing.

Core Features

1. Reading Documents (read_document)

This tool supports multiple common document formats and returns text by parsing file content.
* Supported formats: PDF (text layer, page by page), DOCX, XLSX (all worksheets, cell values), PPTX (text for each slide), CSV (automatically detects delimiters and quoting), and Markdown/text.
* Limitations:
* Text output is limited by maxTextChars (default 200,000); overflow is truncated with a notice.
* Binary reads are limited by readMaxBytes (default 50 MB).
* Scanned or image-based PDFs cannot yield text.
* Return format: Text formats return content; binary formats return byte counts.

2. Creating Documents (create_document)

Used to create a brand-new document file. The target file path must not already exist (the semantics are createIfAbsent, meaning existing files are not overwritten).
* Input content: Lightweight Markdown syntax (supports headings such as #, ##, - lists, and tables).
* Format support:
* DOCX/PDF: supports Markdown structure and the title field (DOCX).
* XLSX: supports a sheets array.
* CSV: supports a rows array.
* Markdown/text: supports plain text.
* PDF behavior: When creating a PDF, if the system detects a CJK font, it tries to embed that font; alternatively, the font file can be specified through the cjkFontPath configuration.

3. Editing Documents (edit_document)

Modifies existing documents in place.
* Operation types:
* DOCX: replace_text (paragraph-level text replacement; replaces once by default, and 'all' replaces all occurrences; only matches a single <w:t> text run), append_paragraph (appends a paragraph).
* XLSX: set_cell (sets a cell), append_rows (appends rows), add_sheet (adds a worksheet; the sheet parameter defaults to the first worksheet).
* CSV: set_cell, append_rows.
* Validation mechanism: All operations are validated before execution. If an invalid operation is found (such as an unknown worksheet or zero matches), the call is immediately aborted with an error, and no write is performed.

Usage Examples

When calling the tools, the model sees precise tool schema definitions tailored to different formats. The following are common invocation patterns:

// 读取文档
read_document(file_path)

// 创建新文档
create_document(file_path, content)

// 编辑文档
edit_document(file_path, operations)

The structure of specific edit operations (operations) is as follows:

// 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']]
}

Limitations and Notes

Format and Feature Limitations

  1. DOCX editing scope: Only paragraph-level text replacement is supported; matching across text runs is not supported (that is, text split across different runs cannot be matched). Editing headers, footers, fields, and numbered items is not supported.
  2. PDF and PPTX editing: In-place editing is not supported; the file must be recreated using create_document.
  3. Legacy formats: Legacy binary Office formats (.doc, .xls, .ppt) are not supported and must be converted to OpenXML formats first.
  4. PDF fonts: CJK fonts rely on system detection; if no suitable font is available, the created PDF falls back to Latin fonts.

Security and Permissions

  1. Binary write policy: Read/write operations for text formats (CSV/Markdown, etc.) follow the sandbox policy through ctx.fs. However, writes for binary formats (PDF/XLSX/PPTX) write directly to the resolved path using node:fs and do not follow the sandbox write policy.
  2. Pre-installation check: Because binary writes bypass the sandbox policy, it is recommended to review the source code and license before installation to ensure the behavior meets the permission requirements of the current environment.

Summary

The dsh-tool-doc plugin gives DSH Agents the ability to operate on documents directly in-process. It reduces the complexity of document processing through explicit tool interfaces and strict operation validation. When using it, pay attention to limitations for specific formats (such as DOCX) and legacy files, as well as the permission characteristics of binary writes.

GitHub Repository