In the DeepSeek Harness (DSH) plugin ecosystem, processing Excel workbooks is a common requirement. Having the model read large files directly can exceed the context window, while manual parsing is cumbersome. The dsh-xmap plugin wraps the general-purpose Excel reading tool xmap as seven model-callable tools.

What It Is

This is a DSH tool plugin maintained by lvguqingyou and licensed under MIT. It solves the problem of large Excel workbooks with complex layouts that cannot be fed directly to a model or require manual parsing. The core idea is: the model only writes a few hundred bytes of column-mapping spec and reviews a summary; the engine reads the entire sheet cell by cell outside the model’s context using Excel COM. Workbooks with the same layout automatically reuse the spec via a header fingerprint, with zero involvement from the model.

Core Features

The plugin provides the following seven tools:

  1. List worksheets: Get the names, row counts, and column counts of all sheets in a workbook.
  2. Preview structure: View the header and first few rows of a sheet.
  3. Header fingerprint: Compute the MD5 hash of the header to detect whether the layout is consistent, enabling spec reuse.
  4. Extract data: Extract the entire sheet into a standardized JSONL file using a spec. If no spec is provided, it is matched automatically by fingerprint.
  5. Data validation: Validate record count, sum numeric columns, and optionally compare with the total row in the sheet.
  6. Save spec: Store a validated spec in the spec library (named by fingerprint).
  7. Data aggregation: Group multiple JSONL files by field and sum them.

Installation and Activation

Install it with the following commands:

# 方式一：npm 包
dsh plugin --profile web add dsh-xmap

# 方式二：从源码目录
git clone https://github.com/lvguqingyou/dsh-xmap.git
dsh plugin --profile web add <克隆下来的 dsh-xmap 目录>

After installation, restart dsh web so the tools appear in the model’s tool list.

Typical Usage

Typically, first inspect the sheet structure, then extract the data, and finally validate or aggregate it.

  1. List worksheets:
    xmap_sheets file="C:\data\book.xlsx"
  1. View the first few rows of a sheet:
    xmap_headers file="C:\data\book.xlsx" sheet="Sheet1" rows=5
  1. Extract the entire sheet to JSONL:
    xmap_extract file="C:\data\book.xlsx" sheet="Sheet1" out="C:\data\records.l"
  1. Validate the extracted data:
    xmap_verify file="C:\data\book.xlsx" sheet="Sheet1" spec="C:\spec.json" records="C:\data\records.l"
  1. Aggregate multiple JSONL files:
    xmap_aggregate records="C:\a.jsonl,C:\b.jsonl" groupBy="name" sum="amount" out="agg.l"

Configuration

The following options can be configured under config: in cordis.yml:

  • specDir: The spec library directory. If empty, the package-bundled xmap/specs is used.
  • timeoutMs: The timeout in milliseconds for a single Excel COM foreground operation. The default is 300000.

Environment Requirements and Notes

  • Runtime environment: Must run on Windows with Microsoft Excel installed (the plugin uses the Excel COM engine).
  • Version dependencies: DeepSeek Harness 0.1.3-alpha.1 series / cordis 4.0.x; PowerShell (prefer pwsh, with fallback to 5.1).
  • File permissions: Writing files across workspaces requires sandbox_permissions + justification.
  • Security note: The plugin executes the package-local xmap/xmap.ps1 through the host ctx.shell. Install it only from trusted sources and verify the source before installation.