XLSX 工具箱
不装表格库也能处理 Excel。适用于离线环境、受管控环境、或不想为一次性转换装依赖的场景。
触发规则
| 用户意图 | 处理 |
|---|---|
| 这个 xlsx 里有哪些表 / 多少行 | info |
| 把 Excel 转成 CSV / JSON | to-csv / to-json |
| 把几个 CSV 合成一个 Excel | from-csv |
| 快速看一眼表里是什么数据 | preview |
| 批量处理一个文件夹里的所有 Excel | 对目录用 info / to-csv |
| 只是问本技能能干嘛 | 仅介绍，不执行任何操作 |
依赖
| 依赖 | 用途 |
|---|---|
| Python 3.8+ | 仅标准库（zipfile / xml.etree / csv / json） |
不需要 openpyxl、pandas、xlrd 等任何第三方包，无需联网。
子命令
info —— 列出工作表与规模
python3 scripts/xlsx_toolkit.py info report.xlsx
python3 scripts/xlsx_toolkit.py info ./downloads # 批量：递归目录下所有 xlsx
python3 scripts/xlsx_toolkit.py info report.xlsx --preview # 附带表头
preview —— 预览数据
python3 scripts/xlsx_toolkit.py preview report.xlsx --sheet 订单 --rows 15
to-csv —— 批量导出 CSV
python3 scripts/xlsx_toolkit.py to-csv report.xlsx -o ./csv_out
python3 scripts/xlsx_toolkit.py to-csv ./downloads -o ./csv_out --delimiter ';'
- 单表工作簿导出为
<原名>.csv；多表工作簿导出为<原名>__<表名>.csv。 - 输出为 UTF-8 with BOM（
utf-8-sig），保证用 Excel 双击打开不乱码。 - 表名中的空格与非法字符会被规范为下划线。
to-json —— 导出 JSON
python3 scripts/xlsx_toolkit.py to-json report.xlsx --sheet 订单 -o orders.json
python3 scripts/xlsx_toolkit.py to-json report.xlsx # 直接打印到终端
首行作为字段名；缺字段的行自动补空串；空表头补为 col1、col2…
from-csv —— 生成多表工作簿
python3 scripts/xlsx_toolkit.py from-csv 一月.csv 二月.csv -o 一季度.xlsx
- 每个 CSV 变成一个工作表，表名取文件名（截断至 31 字符，符合 Excel 限制）。
- 自动尝试 UTF-8/BOM/GBK 解码；
.tsv按 TAB 分隔。 - 纯数字内容写为数值型单元格，其余写为文本，Excel 中可直接参与计算。
单元格类型映射
| 读入 | 输出 |
|---|---|
共享字符串（t="s"） |
文本 |
内联字符串（t="inlineStr"） |
文本 |
布尔（t="b"） |
TRUE / FALSE |
| 数值 / 日期序列号 | 原始数值字符串（不做日期格式化） |
| 空单元格 | 空串 |
Agent 执行要求
- 先 info 后操作：动手转换前先
info摸清有几个表、规模多大，避免误判。 - 只读优先：
info/preview/to-csv/to-json均不修改源文件。 - 输出目录由用户确认：
to-csv会批量写文件，落盘前把输出目录告诉用户。 - 不覆盖已有文件的原则：若输出文件名已存在，先提示用户再决定是否覆盖。
- 日期与公式要说明：读出的日期是序列号、公式是缓存值，必须向用户说明这一限制，
不要假装已还原成日期或实时公式。 - 不做静默降级：遇到
.xls或损坏文件，直接报错并说明原因，不输出空结果冒充成功。
输出模板
## Excel 处理结果
### report.xlsx（248.3 KB）
| 工作表 | 行数 | 列数 | 非空单元格 |
|---|---|---|---|
| 订单 | 12840 | 9 | 98120 |
| 退款 | 210 | 6 | 1180 |
已导出：
- ./csv_out/report__订单.csv（12840 行）
- ./csv_out/report__退款.csv（210 行）
注意：日期列读出的为 Excel 序列号，未做日期格式化。
注意事项
- 禁止覆盖或删除源工作簿；本技能只读取源文件，只写入用户指定的输出路径。
- 不支持
.xls（旧二进制格式）、不支持写入公式与样式、不支持加密工作簿。 - 读取超大工作簿（数十万行）会占用较多内存，建议先
info确认规模再决定是否全量导出。 - 生成的工作簿为最小合规结构，不包含样式、列宽、冻结窗格等展示设置。
