DeepSeek Harness 插件 dsh-xmap：将通用 Excel 读表工具封装为 7 个模型工具

在 DeepSeek Harness（DSH）插件生态中，处理 Excel 表格是常见需求。模型直接读取大文件会超出上下文窗口，手动解析又繁琐。dsh-xmap 插件把通用 Excel 读表工具 xmap 封装为模型可调用的 7 个工具。

是什么¶

这是一个 DSH 工具插件，由 lvguqingyou 维护，开源许可（MIT）。它解决了大版式 Excel 表格无法直接喂给模型，或需手动解析格式的问题。核心思路是：模型只写几百字节的「列映射 spec」并查看摘要；引擎通过 Excel COM 在模型上下文之外逐格读取整张表。同版式的表用「表头指纹」自动复用 spec，模型零参与。

核心功能¶

插件提供以下 7 个工具：

列出工作表：获取工作簿内所有表的名称、行数和列数。
预览结构：查看某张表的表头和前几行内容。
表头指纹：计算表头的 MD5 哈希，用于识别版式是否一致，以便复用 spec。
提取数据：按 spec 把整张表提取为标准化 JSONL 文件。若没有 spec，会按指纹自动匹配。
数据校验：校验记录数、数值列求和，并可选与表内合计行对比。
保存 Spec：把验证过的 spec 存入 spec 库（按指纹命名）。
数据聚合：多份 JSONL 文件按字段分组求和。

安装与启用¶

使用以下命令安装：

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

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

安装完成后需要重启 dsh web，工具才会出现在模型工具表中。

典型用法¶

使用时，通常先查看表结构，再提取数据，最后校验或聚合。

列出工作表：

    xmap_sheets file="C:\data\book.xlsx"

查看某张表的前几行：

    xmap_headers file="C:\data\book.xlsx" sheet="Sheet1" rows=5

提取整张表为 JSONL：

    xmap_extract file="C:\data\book.xlsx" sheet="Sheet1" out="C:\data\records.l"

校验提取的数据：

    xmap_verify file="C:\data\book.xlsx" sheet="Sheet1" spec="C:\spec.json" records="C:\data\records.l"

聚合多份 JSONL 文件：

    xmap_aggregate records="C:\a.jsonl,C:\b.jsonl" groupBy="name" sum="amount" out="agg.l"

配置项¶

在 cordis.yml 的 config: 下可配置：

specDir：spec 库目录，留空则使用包内自带 xmap/specs。
timeoutMs：单次 Excel COM 前台超时时间（毫秒），默认 300000。

环境要求与注意¶

运行环境：必须运行在 Windows 系统上，且安装了 Microsoft Excel（插件使用 Excel COM 引擎）。
版本依赖：DeepSeek Harness 0.1.3-alpha.1 系列 / cordis 4.0.x；PowerShell（优先 pwsh，回退 5.1）。
文件权限：跨工作区写文件需配置 sandbox_permissions + justification。
安全提示：插件通过宿主 ctx.shell 执行本包内的 xmap/xmap.ps1，请从可信来源安装，安装前检查来源。