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，請從可信來源安裝，安裝前檢查來源。