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 倉庫