表格批量合并与拆分
两个方向，一个工具解决：多个表拼一起、一个表拆开来。
触发规则
| 用户意图 | 处理 |
|---|---|
| 把这几个表合成一个 / 汇总多个月的数据 | merge |
| 这些表列不一样，能对齐吗 | merge --header-mode union（默认），并说明缺失补空情况 |
| 只保留都有的列 | merge --header-mode intersection |
| 按部门/地区/状态拆成多个文件 | split --by 列名 |
| 只要最大的几组 | split --by 列名 --top N |
| 只是问本技能能干嘛 | 仅介绍，不执行任何操作 |
依赖
| 依赖 | 用途 |
|---|---|
| Python 3.8+ | 仅标准库（csv / io / pathlib / collections） |
无需联网、无需第三方包。
快速开始
# 合并整个目录的 CSV，追加来源标记列
python3 scripts/merge_split.py merge ./monthly -o 汇总.csv --source-col __来源
# 先试跑看看会合并成什么样（不写文件）
python3 scripts/merge_split.py merge ./monthly -o 汇总.csv --dry-run
# 只保留各表都有的列
python3 scripts/merge_split.py merge a.csv b.csv -o 交集.csv --header-mode intersection
# 按部门拆分，只看最大的 5 组
python3 scripts/merge_split.py split 汇总.csv --by 部门 -o ./按部门 --top 5
merge 参数
| 参数 | 说明 | 默认 |
|---|---|---|
-o, --out |
输出文件 | 必填 |
--header-mode |
union / intersection / first |
union |
--source-col NAME |
追加来源标记列（值为源文件名，不含扩展名） | 不加 |
--include-ext |
目录扫描时纳入的扩展名 | .csv,.tsv,.txt |
--delimiter |
覆盖分隔符（tsv 或任意字符） |
自动嗅探 |
--dry-run |
只报告，不写文件 | 关 |
split 参数
| 参数 | 说明 | 默认 |
|---|---|---|
--by 列名 |
拆分依据列 | 必填 |
-o, --out |
输出目录 | 必填 |
--top N |
只输出最大的 N 组，其余归入 __others__ |
0（全拆） |
--keep-empty |
空值行单独成组 (空) |
关（丢弃并计数） |
--delimiter |
覆盖分隔符 | 自动嗅探 |
--dry-run |
只报告，不写文件 | 关 |
输出文件命名为 <原表名>__<组名>.csv；组名中的空格、斜杠等非法字符会替换为下划线。
表头对齐策略对比
| 策略 | 结果 | 何时用 |
|---|---|---|
union |
列 = 所有文件的并集，缺的补空 | 默认；各文件列略有差异且都不该丢 |
intersection |
列 = 所有文件共有的列 | 下游要求字段齐整、不能有空列 |
first |
列 = 第一个文件的表头 | 已有一个权威模板，其余按它对齐 |
Agent 执行要求
- 先 dry-run 再落盘：合并前先跑一次
--dry-run，把「哪个文件、多少行、哪些列缺失」告诉用户。 - 缺失补空要如实报告：把缺失统计（哪列缺多少行）明确列出，不要静默填空了事。
- 输出路径先确认：
merge写单文件、split会批量写文件，动手前把路径告知用户。 - 不覆盖不删除源文件：本技能只读源文件，只写用户指定的输出路径。
- 组数过多要提醒：
split若不设--top且分组数很多（>100），提醒用户可能产生大量碎文件。 - 空值行不静默丢弃：默认丢弃空依据值行时必须把丢弃行数报出来；用户在意则加
--keep-empty。 - 列名带空格要留意：表头首尾空格会被裁剪，如源数据确实依赖空格，先告知用户再处理。
输出模板
## 表格合并结果
输入：3 个文件
| 文件 | 行数 | 列数 | 编码 |
|---|---|---|---|
| jan.csv | 1284 | 9 | utf-8-sig |
| feb.csv | 1190 | 10 | utf-8-sig |
| mar.csv | 1310 | 9 | gbk |
- 表头对齐策略：union 目标列数：10
- 合并结果：3784 行
- 缺失补空：`bonus`（缺 2594 行）、`channel`（缺 1190 行）
已写出：汇总.csv（3784 行，UTF-8 with BOM）
注意事项
- 禁止修改、删除、重命名源文件。
- 不做去重：合并是纯粹的纵向拼接，重复行会保留（去重请用专门的工具）。
- 不处理 Excel 二进制格式与固定宽度文本。
- 合并大文件时按行流式写入，不会一次性把全部内容留在内存里的只有输出侧；
读取侧仍会载入单文件全部内容，超大文件建议先用体检工具抽样。
