dsh-excel-kit：DeepSeek Harness 专用只读 Excel 分析工具

DSH（DeepSeek Harness）生态强调「一切皆插件」。在模型推理或智能体开发中，直接处理 Excel 文件是常见需求。传统做法要么依赖 Node.js 库全量加载文件（内存溢出风险），要么需要编写额外的读写脚本。dsh-excel-kit 插件提供了基于流式的只读处理方案，专注于描述、筛选和透视分析。

插件定位¶

dsh-excel-kit 是一个针对 DeepSeek Harness (DSH) 的只读 Excel 分析工具包。由用户 helibeiqi 维护，采用 MIT 许可证。

该插件解决的核心问题是：如何在不将整个 Excel 文件加载到内存、不进行格式化写入的前提下，对大型 .xlsx 文件进行结构分析、数据筛选和聚合计算。它依赖 yauzl（流式 zip 解压）和 sax（流式 XML 解析）实现。

核心功能¶

1. 流式与大文件安全
   插件不使用 XLSX.readFile，而是通过 yauzl 以惰性方式打开文件，通过 sax 逐行解析 XML。这保证了处理 100MB 以上的文件时不会出现内存溢出（OOM）。

2. 三大专注工具

   • excel_describe：概览工作簿或工作表，返回列数、行数、非空率、数值分布、样本数据等聚合信息。
   • excel_filter：根据条件筛选行，支持 eq, ne, gt, gte, lt, lte, contains, in, between 等操作符。
   • excel_pivot：分组聚合，支持 count, sum, mean, min, max 等聚合操作。

3. 溢出集成
   当分析结果超过默认阈值（32 KB）时，结果会通过 ctx.spillStore 持久化存储，返回值中会包含一个 spilled 定位符，避免一次性返回海量数据导致内存压力。

4. 日期类型感知
   利用 xl/styles.xml 中的 numFmtId 识别内置日期格式（如 14-22, 45-47）和自定义格式（含 y/m/d），将 Excel 序列日期转换为 ISO 字符串。

5. 可取消与并发安全
   所有长耗时扫描操作都会传递 exec.signal（AbortSignal），支持取消。工具声明了 isConcurrencySafe，保证多线程环境下的安全性。

安装与启用¶

安装前请确认 DSH 版本兼容性。该插件基于 DSH 0.1.0-rc.6 构建，请勿盲目安装 @latest，建议锁定在 >=0.1.0-rc.6 <0.2.0 范围。

通过 DSH 插件命令添加到指定配置文件：

dsh plugin --profile <name> add dsh-excel-kit

插件内部通过 dsh.bundle 注入 cordis.patch.yml 配置，无需手动配置项。

典型用法¶

1. excel_describe：概览文件¶

此工具用于快速了解 Excel 文件的结构和字段特征。

{
  "tool": "excel_describe",
  "arguments": {
    "file_path": "/data/reports/2026-08-sales.xlsx",
    "sheet": "Sheet1",
    "sample": 3
  }
}

返回结果包含文件总行数、列数、每列的非空率、数据类型分布、数值的极值与均值，以及前几行的样本数据。

2. excel_filter：条件筛选¶

根据业务条件提取特定数据行。

{
  "tool": "excel_filter",
  "arguments": {
    "file_path": "/data/reports/2026-08-sales.xlsx",
    "sheet": "Sheet1",
    "conditions": [
      { "column": "region", "op": "in", "values": ["华东", "华南"] },
      { "column": "amount", "op": "gte", "value": 5000 }
    ],
    "columns": ["id", "region", "amount"],
    "limit": 100
  }
}

返回结果中包含匹配到的总行数、实际返回的行数、是否截断标记，以及投影后的具体数据行。

3. excel_pivot：分组聚合¶

对数据进行透视分析。

{
  "tool": "excel_pivot",
  "arguments": {
    "file_path": "/data/reports/2026-08-sales.xlsx",
    "sheet": "Sheet1",
    "rows": ["region"],
    "values": [
      { "column": "amount", "op": "sum" },
      { "column": "amount", "op": "count" }
    ],
    "limit": 50
  }
}

适用场景与注意¶

• 适用场景：需要直接在 DSH 上下文中分析本地 Excel 文件、大数据量报表的快速预览、以及基于 Excel 数据的模型训练数据清洗。
• 权限注意：插件以当前 DSH 进程的权限运行，需确保 file_path 可访问。
• 配置说明：插件没有插件级别的 Config 对象（这是为了兼容 cordis 加载器），其行为参数（如 spillThreshold、filter limit）均在源码中定义，如需调整需修改源码或通过 DSH 配置层控制。
• 版本锁定：务必检查宿主环境的 DSH 版本，该插件依赖特定的 dsh-tools 接口，版本不匹配可能导致工具注册失败。

结语¶

dsh-excel-kit 提供了流式、安全、只读的 Excel 分析能力，配合 DSH 的 Spill 机制，能够有效处理大文件场景。对于需要在智能体中直接调用 Excel 数据能力的开发者，这是一个实用的工具箱。

• 插件目录
• GitHub 仓库