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、千元、元/台）要人工核对，脚本不会替你猜。