dsh-xlsx-lite

零运行时依赖的 XLSX 工具集，用于 DeepSeek Harness 生态：读取工作簿数据（自动还原共享字符串、数字、布尔、日期）、快速探查工作表结构、把 JSON / CSV / JSONL / 表格文本写入 .xlsx。不依赖任何第三方库，仅用 Node 内置模块（node:zlib 的 raw deflate 与 CRC32、自研 ZIP 与 XML 解析）。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-xlsx-lite
• npm：https://www.npmjs.com/package/dsh-xlsx-lite
• 协议：MIT

功能说明

• read_xlsx：读取 .xlsx 数据。列出全部工作表，并按表名或序号输出指定工作表的单元格数据（markdown 表格）。自动还原：
  • 共享字符串（含富文本 run 拼接）
  • 数字、布尔
  • 日期（把 Excel 序列号按样式转回 yyyy-mm-dd / yyyy-mm-dd HH:mm:ss）
• sheet_preview：快速探查单个工作表的表结构——行列数、每列主导类型与非空占比、前 N 行对齐预览。适合先看清工作表长什么样再决定如何提取。
• write_xlsx：把数据写入 .xlsx。支持四种数据源（data JSON 对象数组 / csv / jsonl / text 自动探测分隔符的表格），自动推断单元格类型（数字 / 布尔 / 日期 / 字符串），日期按 yyyy-mm-dd 识别并写入 Excel 日期格式。默认不覆盖已存在文件（需 overwrite=true）。

三个工具均为只读或显式写入，输入优先内联文本，路径读入有大小上限保护。

安装

# 从 npm 安装
dsh plugin --profile web add dsh-xlsx-lite

# 本地开发调试（Debug patch）
# 新建 debug.patch.yml：
# - insert:
#     - id: xlsx-lite
#       name: "E:/dsh-plugins/dsh-xlsx-lite/index.js"
dsh web --patch ./debug.patch.yml

使用说明

1. read_xlsx —— 读取数据

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | 是 | xlsx 文件路径 | | sheet | string | 否 | 工作表名或 1 起始序号，默认第一个 | | limit | number | 否 | 最多输出行数，默认 10，上限 100 | | max_size | number | 否 | 文件大小上限（KB），默认 10240，上限 51200 |

读出的结果包含：工作表清单 + 选中工作表的 markdown 表格。日期列以 yyyy-mm-dd 呈现。

2. sheet_preview —— 探查结构

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | 是 | xlsx 文件路径 | | sheet | string | 否 | 工作表名或 1 起始序号，默认第一个 | | rows | number | 否 | 预览行数，默认 10，上限 100 | | max_size | number | 否 | 文件大小上限（KB），默认 10240，上限 51200 |

输出：工作表行列数 + 每列主导类型与非空占比 + 前 N 行预览。

3. write_xlsx —— 写入文件

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | 是 | 输出 xlsx 文件路径 | | data | string | 否* | JSON 对象数组（与 csv/jsonl/text 四选一，优先使用） | | csv | string | 否* | CSV 文本，首行为表头 | | jsonl | string | 否* | JSONL 文本，每行一个对象 | | text | string | 否* | 表格文本，自动探测制表符/逗号/分号/竖线，首行为表头 | | sheet_name | string | 否 | 工作表名，默认 Sheet1 | | overwrite | boolean | 否 | 目标已存在时是否覆盖，默认 false | | max_size | number | 否 | 生成文件大小上限（KB），默认 20480，上限 51200 |

* data / csv / jsonl / text 至少提供一种数据源。

单元格类型推断规则：

| 输入值 | 推断类型 | 写入方式 | |--------|----------|----------| | 有限数字或数字字符串（28、-1.5、1e3） | number | 数字单元格 | | true / false | boolean | 布尔单元格 | | ISO 日期字符串（2020-01-15、2020-01-15 12:00:00） | date | 日期序列号 + 日期格式 | | 其余文本 | string | 共享字符串 | | null / 空字符串 | blank | 跳过（空单元格） |

典型场景

• 数据提取：读取一份同事发来的 Excel 报表，把关键列转成结构化数据做进一步分析。
• 结构探查：面对不了解字段的 xlsx，先用 sheet_preview 看清每个工作表的行列与类型分布。
• 结果落盘：把 AI 分析得到的对象数组 / CSV / JSONL 直接写成 .xlsx 交付给业务同事。
• 表格互通：配合 csv / jsonl / text 文本源，在纯文本与 Excel 之间无第三方依赖地转换。

安全边界

• 只读优先：read_xlsx / sheet_preview 为只读；write_xlsx 是唯一写文件入口，且默认不覆盖已有文件（需显式 overwrite=true）。
• 大小上限：读取文件默认 10MB、上限 50MB；写入默认 20MB、上限 50MB，防超大文件耗尽内存。
• 读取行数 / 单元格上限：单 sheet 最多 10 万行、200 万单元格，防止恶意巨型工作表。
• XXE 防护：XML 解析忽略 DOCTYPE / 外部实体，不解析 DTD，避免实体注入。
• 零网络请求：纯本地计算，不发送任何数据到外部。
• 写入的日期按文本语义识别，不做隐式强转；无法识别的对象统一字符串化。

版本说明

| 版本 | 日期 | 说明 | |------|------|------| | 0.1.0 | 2026-10-14 | 首个版本：read_xlsx / sheet_preview / write_xlsx，ZIP+XML 零依赖实现，双向通过真实 Excel 生态（openpyxl）交叉验证 |

RoadMap

• [ ] 支持多工作表写入（当前单 sheet，后续可按对象数组生成多个 sheet）
• [ ] range 参数：按 A1:D10 地址范围局部读取
• [ ] 合并单元格识别与输出
• [ ] 单元格样式（对齐、加粗、列宽）写入
• [ ] 公式（=SUM(...)）与缓存值读取
• [ ] 列宽 / 冻结首行等视图属性

其他插件集成说明

• dsh-csv-explorer：纯 CSV 探查/过滤；本插件补齐 XLSX 二进制格式，两者覆盖「表格数据读取」完整谱系。
• dsh-json-yaml-toolkit / dsh-jsonl-stream：负责 JSON/JSONL 的解析与转换，可作为 write_xlsx 的 data / jsonl 数据源上游。
• dsh-xml-toolkit：通用 XML 解析；本插件内置专用轻量 XML 解析（忽略 DOCTYPE、命名空间本地名），二者不重叠。
• dsh-pivot-join：对表格做透视/连接；可先 read_xlsx 取数，再交给 pivot-join 做聚合。

FAQ

Q1：生成的 .xlsx 能被 WPS / Excel 打开吗？ 能。产出的是标准 OOXML（ZIP 容器 + XML 部件），已用开源实现 openpyxl 双向交叉验证通过；日期列使用标准 numFmt，Excel/WPS 能正确显示为日期。

Q2：日期还原会不会差一天？ 已处理 Excel 的「1900 闰年 bug」：Excel 把虚构的 1900-02-29 算入序列号，本插件对 1900-03-01 及之后的日期做补偿，序列号与真实日期严格一致（2000-05-20 ↔ 序列号，实测一致）。

Q3：write_xlsx 会不会覆盖我已有的文件？ 不会。目标文件已存在且未传 overwrite=true 时会直接报错，避免误覆盖。

Q4：能不能读超大 Excel？ 受 max_size（默认 10MB）、单表 10 万行 / 200 万单元格上限保护。超出会明确报错，可适当调大 max_size。

Q5：富文本共享字符串能还原吗？ 能。共享字符串 <si> 中多个 <r><t> 富文本 run 会按顺序拼接为完整文本。

Q6：非 .xlsx 的文件会怎样？ 解析器会先做 ZIP 结构校验（含 CRC32），不是合法 ZIP 会直接报错，不会误读为表格。

许可证

MIT