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 仓库