The DSH (DeepSeek Harness) ecosystem emphasizes “everything is a plugin.” In model inference or agent development, directly processing Excel files is a common requirement. Traditional approaches either rely on Node.js libraries to load the entire file (risking memory overflow) or require writing additional read/write scripts. The dsh-excel-kit plugin provides a streaming, read-only processing solution focused on description, filtering, and pivot analysis.

Plugin positioning

dsh-excel-kit is a read-only Excel analysis toolkit for DeepSeek Harness (DSH). It is maintained by user helibeiqi and released under the MIT License.

The core problem it solves is: how to perform structural analysis, data filtering, and aggregation calculations on large .xlsx files without loading the entire Excel file into memory and without formatted writing. It is implemented using yauzl (streaming zip decompression) and sax (streaming XML parsing).

Core features

  1. Streaming and large-file safety
    The plugin does not use XLSX.readFile. Instead, it opens the file lazily through yauzl and parses the XML incrementally through sax. This ensures that files larger than 100 MB can be processed without out-of-memory (OOM) errors.

  2. Three focused tools

    • excel_describe: Gets an overview of a workbook or worksheet and returns aggregate information such as column count, row count, non-null ratio, numeric distribution, and sample data.
    • excel_filter: Filters rows based on conditions and supports operators such as eq, ne, gt, gte, lt, lte, contains, in, and between.
    • excel_pivot: Performs grouped aggregation and supports aggregation operations such as count, sum, mean, min, and max.

  3. Spill integration
    When analysis results exceed the default threshold (32 KB), the results are persisted through ctx.spillStore, and the returned value includes a spilled locator to avoid memory pressure caused by returning a large amount of data at once.

  4. Date-type awareness
    It uses numFmtId in xl/styles.xml to identify built-in date formats (such as 14-22 and 45-47) and custom formats (containing y/m/d), and converts Excel serial dates to ISO strings.

  5. Cancellable and concurrency-safe
    All long-running scan operations propagate exec.signal (AbortSignal) and support cancellation. The tools declare isConcurrencySafe, ensuring safety in multi-threaded environments.

Installation and enabling

Before installing, verify DSH version compatibility. This plugin is built for DSH 0.1.0-rc.6. Do not blindly install @latest; it is recommended to pin the version in the >=0.1.0-rc.6 <0.2.0 range.

Add it to the specified profile with the DSH plugin command:

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

Internally, the plugin injects the cordis.patch.yml configuration through dsh.bundle, so no manual configuration items are required.

Typical usage

1. excel_describe: file overview

This tool is used to quickly understand the structure and field characteristics of an Excel file.

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

The returned result includes the total number of rows, the number of columns, the non-null ratio for each column, the data type distribution, the numeric extremes and mean, and sample data from the first few rows.

2. excel_filter: conditional filtering

Extract specific data rows based on business conditions.

{
  "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
  }
}

The returned result includes the total number of matched rows, the number of rows actually returned, a truncation flag, and the specific projected data rows.

3. excel_pivot: grouped aggregation

Perform pivot analysis on the data.

{
  "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
  }
}

Use cases and precautions

  • Use cases: Directly analyzing local Excel files within the DSH context, quickly previewing large reports, and cleaning model training data based on Excel data.
  • Permission notice: The plugin runs with the permissions of the current DSH process. Ensure that file_path is accessible.
  • Configuration notes: The plugin does not have a plugin-level Config object (this is for compatibility with the cordis loader). Its behavioral parameters (such as spillThreshold and filter limit) are defined in the source code. Adjusting them requires modifying the source code or controlling them through the DSH configuration layer.
  • Version locking: Be sure to check the DSH version of the host environment. The plugin depends on specific dsh-tools interfaces, and version mismatches may cause tool registration to fail.

Conclusion

dsh-excel-kit provides streaming, safe, and read-only Excel analysis capabilities. Combined with DSH’s Spill mechanism, it can effectively handle large-file scenarios. For developers who need to directly invoke Excel data capabilities in agents, this is a practical toolkit.