Excel清洗助手（简易版）
脏表格不必再靠人肉重复点点点。丢进一个命令，把「看不见的空格、一会儿文本一会儿数字的同列、
.xls 打不开、两个表怎么都对不上」这类琐事一次性处理完，输出一个干净的新文件。
何时使用
用户提到这些话时直接用它：
「清洗表格」「整理 Excel」「Excel 去重」「去空格」「去重」「文本转数字」「日期统一」「数据分列」
「两表匹配 / 匹配一下这两张表」「分组汇总」「脏数据怎么处理」「这列数字怎么求不出和」
「帮我看看这张表干净不干净」。
默认工作流
顺序别乱跳：先看，再擦，最后加工。因为 trim 之前去重会漏判（"张三" 与 " 张三 " 是两条），
convert 之前求和全是错的。
info → trim → dedup → convert → lookup / summary → export
看清 去脏字符 去重 修格式 跨表加工 交付
三步拿下一个陌生的表：
- 看结构 — 运行
python scripts/excel_clean.py info <文件> --sheet <表名>，拿到列名、类型、空值率、重复行、样例值。 - 对症下命令 — 按下表的「症状 → 命令」挑一到几条依次跑，每条默认另存为新文件，不会串味。
- 交付 — 把最后生成的那个
_<动作>.xlsx（或export出来的 CSV）给用户，并说明改了什么、哪些没处理到。
症状 → 命令
| 看到的症状 | 用哪条命令 |
|---|---|
| 不知道表长什么样、哪里脏 | info |
| 名字对不上、一个客户被拆成好几行 | trim → dedup |
| 单元格里有点可疑的东西、LEN 数不对 | trim |
| 数字是文本、绿色三角、求和得 0 | convert --mode number |
金额写成 1,234.50 ¥2,000 1.2万 15% （500） |
convert --mode number（内置这些写法） |
日期混写成 2026/9/1、2026年9月1日、20260901 |
convert --mode date |
| 有空白格，排序求和都不对 | fill |
| 合并单元格只有第一行有值 | fill --strategy ffill |
一列塞了多个值（华东 深圳、张三,13800000000） |
split |
| 另一张表有客户等级/负责人，要按编号带过来 | lookup |
| 按地区、按月、按人汇总金额 | summary |
| 交给别的系统，只能收 CSV | export |
命令速查
# 1 看清结构：列名、类型、空值率、唯一值、样例、重复行数
python scripts/excel_clean.py info data.xlsx --sheet Sheet1
# 2 去脏字符：首尾空格、不可见字符、全角转半角、压缩多余空白
python scripts/excel_clean.py trim data.xlsx -o clean.xlsx
python scripts/excel_clean.py trim data.xlsx --keep-newline # 备注列要保留内部换行时用
# 3 去重：不写 --cols 按整行；写了按这几列判断
python scripts/excel_clean.py dedup data.xlsx --cols 手机号 --keep last -o clean.xlsx
# 4 格式转换：number 文本转数值 / date 统一日期 / text 转文本（保长编码）
python scripts/excel_clean.py convert data.xlsx --cols 金额 --mode number -o clean.xlsx
python scripts/excel_clean.py convert data.xlsx --cols 下单日期 --mode date -o clean.xlsx
# 5 补齐空值：ffill 向下填充 / value 固定值 / zero / mean / mode
python scripts/excel_clean.py fill data.xlsx --cols 部门 --strategy ffill -o clean.xlsx
# 6 分列：默认新列插在原列右边并保留原列
python scripts/excel_clean.py split data.xlsx --col 地区 --sep " " --names 大区,城市 -o clean.xlsx
# 7 跨表匹配：把对照表的列取回来，匹配不上的填默认值，并打印未匹配样例
python scripts/excel_clean.py lookup data.xlsx --key-col 客户编号 \
--lookup-file 档案.xlsx --lookup-sheet Sheet1 --lookup-key 编号 \
--return-cols 客户等级,负责人 --default "未登记" -o clean.xlsx
# 8 分组汇总：结果写进新的「汇总」工作表
python scripts/excel_clean.py summary data.xlsx --group-by 大区 --agg "金额:sum,订单号:count" -o clean.xlsx
# 9 导出 CSV：默认 utf-8-sig，Excel 双击打开不乱码
python scripts/excel_clean.py export data.xlsx --sheet 汇总 -o out.csv
调用约定
- 列怎么写都行：Excel 字母（
A、A:C）、列序号（3）、表头名（手机号），逗号分隔可混写。 - 输出：默认另存为
<原名>_<动作>.xlsx，原文件不动；确认OK了才加--inplace覆盖。 - 表不对时：用
--sheet 表名指定工作表（省略取第一个），--header-row 2指定表头在第几行，--header-row 0表示没有表头。 - 默认保留公式：清洗时会跳过公式单元格并报告数量；若表里是别的工具生成的、只要算好的静态值，加
--values。 - 列名/表名找不到：命令会直接列出本表里实际存在的名字，照抄改一下即可，不用猜。
运行前提
- 唯一依赖：
openpyxl。首次使用先跑python scripts/setup.py（装不上时它会依次换 pip / 国内镜像重试）。 - Windows 下中文输出：
PYTHONIOENCODING=utf-8 python scripts/excel_clean.py ...，脚本已自带 UTF-8 兜底。 - 只支持
.xlsx/.xlsm。旧版.xls请先用 Excel 另存为.xlsx。
参考
references/formulas.md— 常用函数速查（TRIM/CLEAN/VLOOKUP/XLOOKUP/SUMIFS/日期/报错值对照）。用户问「这个函数怎么写」「Excel 里能不能直接处理」时再读。references/recipes.md— 场景配方。拿到具体脏数据场景（系统导出报表、客户名单、两两表对齐、长序列号）要判断先做什么时再读。
常见坑
.xls打不开 —— openpyxl 不支持旧格式。现象是报「InvalidFileException」，解法：用 Excel 另存为.xlsx，或在 Excel 里直接复制。- 带 formula 的表不要加
--values猜测 —— 默认读公式本身（data_only=False），因为脚本生成的 xlsx 没有缓存值，data_only=True会把公式单元格全读成None，看起来像整列空了。只有明确要静态值才加--values。 - 超过 15 位的数字救不回来 —— 身份证、银行卡、物料编码一旦被 Excel 存成数值，末几位在写盘时就丢了。
convert --mode text只能阻止继续恶化并给出失真告警，正确姿势是从源头把列设成文本后再导入。 - 两表匹配时一边文本一边数字 ——
13800138000（数字）与"13800138001"（文本）永远对不上。命令会打印未匹配样例及其疑似原因；先各自trim，必要时convert --mode text统一口径再匹配。 - 看不见的字符 —— 从网页、微信、PDF 拷来的数据常带零宽空格和方向控制符，
TRIM函数清不掉。脚本的trim清这类字符；Excel 公式党用SUBSTITUTE(A2,CHAR(160),"")。 split会保留原列 —— 默认插新列到原列右边，原列不动，确认无误后再手工删，避免一步错毁全表。- 文件被 Excel 打开着会写失败 —— openpyxl 无法写以独占方式打开的文件，命令会提示「文件正被占用」，关闭后再跑。
- 修改后的表会丢掉图表和图片 —— openpyxl 保留样式和大部分格式，但图表、图片、透视表不会跟着走；有这类内容的表，清洗完回 Excel 里再补一次。
- 单位缩写别指望脚本 ——
1.2万、（500）、15%、¥2,000这类写法内置解析；遇到自家口径的单位（K、千元、元/台）要人工核对，脚本不会替你猜。
