前言¶
DSH 的插件生态强调「一切皆插件」。日常开发中，经常需要处理同一目录下的多个 Excel 文件：合并多表、清洗数据、导出 CSV。手动打开每个文件会消耗大量时间，还容易出错。
dsh-xlsx-batch 插件针对这一场景，用一条命令完成整目录的批量处理。
这是什么¶
dsh-xlsx-batch 是一个工作流插件，由 feely0208 维护。它通过 dsh-xlsx-batch 命令行工具，对目录下的 Excel 文件进行批量合并、清洗、汇总和导出。处理过程不修改原文件，结果写入独立目录。
核心功能¶
插件提供四个子命令：
merge：多文件、多 sheet 合并到一个工作簿。自动添加「来源文件」「来源工作表」两列。不同 sheet 的列顺序不同时，按表头名对齐。clean：删除空行、删除重复行、trim 文本前后空格。保留全部 sheet。每输入文件生成一个清洗后的.xlsx，同时输出 JSON 说明删除行数和 trim 格数。summary：每列非空计数、数值列个数与求和。输出文件包含文件名、工作表名、列名、非空计数、数值个数、求和。csv：每个 sheet 导出为 CSV，UTF-8 带 BOM，Excel 双击打开不乱码。
所有子命令的通用约定：
- 不修改输入文件。默认输出到
<输入目录>/_输出，可用--out指定。 - 同名文件不覆盖：已存在时自动加
_1、_2。 - 目录递归处理，自动跳过 Excel 临时文件（
~$开头）和_输出目录。 --json输出结构化结果，出错时退出码非 0 并说明缺什么。
安装与启用¶
使用官方安装命令：
dsh plugin --profile web add @deepwhale-cn/dsh-xlsx-batch
插件运行依赖本机 Python 3 和 openpyxl 库。如果缺少依赖，CLI 会直接打印安装命令：
python3 -m pip install openpyxl
macOS 上没有 python3 时，执行：
brew install python3
插件不会自动安装依赖，需要自行安装。
典型用法¶
以下是四个常用场景的命令示例：
# 合并 20 个门店的销售表
dsh-xlsx-batch merge --input ./门店报表 --out ./汇总
# 清洗名单：删除空行、去重、trim 文本
dsh-xlsx-batch clean --input ./名单 --out ./清洗后
# 每列统计
dsh-xlsx-batch summary --input ./报表 --out ./统计
# 每个 sheet 导出 CSV
dsh-xlsx-batch csv --input ./报表 --out ./csv
查看帮助和运行完整流程演示：
dsh-xlsx-batch --help
dsh-xlsx-batch --demo
--demo 会在系统临时目录生成样例工作簿并依次执行 merge、clean、summary、csv，不修改任何用户文件，完成后打印产物路径。
适用场景与注意¶
适合处理以下场景：
- 多门店、多部门汇总同一格式的 Excel 报表。
- 名单、数据表包含空行、重复行或前后空格，需要清洗后导入系统。
- 需要快速统计每列非空计数和数值求和。
- 系统只认 CSV，需要批量导出。
需要注意的限制：
- 插件以当前 DSH 进程的权限运行。安装前应检查源码与许可证。
- 插件读取的是单元格值，不是公式。公式单元格取 Excel 上次保存时缓存的计算结果；没有缓存的公式可能读成空。
- 输出是值，公式、条件格式、图表、数据透视表、宏不会保留。
- 不合并样式。合并/清洗后的文件使用基础格式（表头加粗、冻结首行），原表的配色、列宽、合并单元格不保留。
- 不处理
.xls老格式、加密/密码保护的表格。需要先另存为.xlsx。 merge只处理每个 sheet 的第一行当表头，没有表头的纯数据表会被当成表头。多级表头、合并单元格表头不做特殊识别。- 不做透视、分组统计、跨表公式、数据校验（如身份证/手机号格式）。
clean的「重复行」是整行完全一致（trim 后）才算重复；只按某一列去重需要自己筛。- 全部在本机由 openpyxl 处理，不联网、不上传表格。
小结¶
dsh-xlsx-batch 将 Excel 批量处理流程从手动操作收成一条命令，适合需要整合多文件、清洗数据、汇总统计、导出 CSV 的场景。它以只读原表、不覆盖同名文件的方式，降低了重复劳动和出错风险。
插件主页：https://www.skillhub.cn/plugins/feely0208/dsh-xlsx-batch
GitHub：https://github.com/feely0208/dsh-xlsx-batch
