Excel 数据清洗
对 CSV/TSV 表格做一次机器可查的数据质量检查，把「导入数据库前必须清掉、但肉眼翻表很难发现」的问题标出来：
列数不齐、完全重复行、空值与整列为空、单元格首尾不可见空白、全角数字与千分位逗号混用、同列日期格式不一致、控制字符与乱码、表头空名重名。
不只报问题，还能直接输出一份清洗后的表格。
执行原则
- 先报后改。 默认只报告问题并给出行号；不要在用户没要求时改动数据。
- 清洗稿另存。
--fix输出到独立文件，绝不覆盖原文；不要原地改写用户的表格。 - 只改确定的。 BOM、控制字符、首尾空白、全角数字、短行补齐可自动处理；千分位逗号、货币符号、日期格式、表头命名只提示不代改。
- 去重需显式。 完全重复行仅在加
--dedupe时删除，默认保留；不要把两行相同数据当成重复直接删掉。 - 零问题直说。 检查结果为 0 就明确说「未发现数据质量问题」；不要为凑内容编造问题。
何时使用
CRITICAL: 只要用户要检查或清洗一份 CSV / Excel 表格的数据质量，就必须使用本 skill，即使看起来可以用别的方式解决。
- 用户说「帮我看看这个表有没有问题」「数据质量检查」「导入前清洗一下」「这份 CSV 对不对」「顺手把表洗干净」。
- 拿到外部数据（导出、爬取、第三方提供）后，入库或分析前的第一道检查。
- 用户要求「只报问题，不要改我的数据」时——不加
--fix就天然只报不改。
不适用：语义、统计分布、业务口径层面的分析；也不做跨表关联、缺失值填充、列名重命名等需要业务判断的清洗。
何时不该使用
| ✅ 使用 | ❌ 不用（改用什么） |
|---|---|
| 入库/分析前的第一道数据质量检查 | 统计分析、透视、业务口径核对——不在本 skill |
| 查列数不齐、重复行、空值、编码乱码 | 跨表关联、主键外键一致性——不做 |
| 输出清洗稿（另存，不改原表） | 填缺失值、重命名列——需业务判断，只提示 |
| 查表头空名重名与日期格式不一致 | 排班 / 简历 / 纪要这类语义质检——用对应专项包 |
| 单文件静态检查 | 需要人工判定的语义清洗——只标注不代改 |
易混淆场景
| 用户说的 | 实际意图 | 正确路由 |
|---|---|---|
| 「帮我看看这个表」 | 要结论不是全量清单 | 先给问题总数与最高危类别，再给明细 |
| 「顺手把表洗干净」 | 要清洗稿 | --fix 另存，并说明改了什么、什么没改 |
| 「只报问题别动数据」 | 只读 | 不加 --fix |
| 「重复的行删掉吧」 | 要去重 | 提示需显式 --dedupe，默认保留 |
| 「日期统一一下」 | 要改格式 | 说明日期格式只提示不代改，由用户定 |
用法
python3 scripts/sheet_lint.py <文件路径> [--delimiter ,] [--max-issues 500] [--json]
python3 scripts/sheet_lint.py <文件路径> --fix # 输出清洗稿
python3 scripts/sheet_lint.py <文件路径> --fix --dedupe # 同时删除完全重复行
python3 scripts/sheet_lint.py <文件路径> --fix -o out.csv # 指定输出路径
- 支持
.csv/.tsv/.txt等分隔文本，可一次传多个路径。 - 分隔符默认自动探测（在
,\t;|中选表头里出现最多的一个），可用--delimiter强制指定。 - 编码自动识别 UTF-8（含带 BOM）/ GBK。
--max-issues：单文件最多报告的问题数，防止脏数据刷屏。--json：输出机器可读结果，便于二次处理。--fix：另存一份清洗稿（默认<原名>.clean.csv），绝不覆盖原文。--dedupe：配合--fix，额外删除完全重复的数据行。默认不删——完全相同的两行也可能是两笔真实业务，误删不可逆。
--fix 能改什么
只做确定性清洗，改完必然更正确：
| 规则 | 改动 |
|---|---|
T10 BOM |
去掉 UTF-8 BOM（写成无 BOM 的 UTF-8） |
T8 控制字符 |
删除控制字符与乱码替换符 \ufffd |
T4 首尾空白 |
去掉单元格首尾的不可见空白 |
T5 全角数字/逗号 |
１２３ → 123；含数字单元格里的 ， → , |
T1 列数不齐 |
只补齐短行（补空列）；长行保留不动 |
T2 重复行 |
仅加 --dedupe 时删除完全重复的数据行 |
--fix 不动的（都要人来定，一律只在报告里提示）：
T6千分位逗号（1,234）与货币符号（¥）——去掉会改变数值语义。T7日期格式统一——该统一成YYYY-MM-DD还是YYYY年M月D日没有唯一答案。T9表头空名/重名——改名会打断下游对列名的引用。
输出约定
- 先跑脚本拿到问题清单，原样引用其中的行号与片段，不要凭印象补写。
- 汇总成三段交付：问题总数 → 按规则分类的清单（含行号）→ 建议的修复动作。
- 只报告数据质量问题，不要顺手改写用户的数据或猜测为空值该填什么。有疑问的地方标注出来让用户定。
- 用户要的是「干净的表格」时，用
--fix输出清洗稿，并明确告知改了什么、什么没改。 - 若问题为 0，直接说明「未发现数据质量问题」，不要为了凑内容编造问题。
能力边界
- 只做单文件静态检查，不判断业务口径对错，不做统计分布分析。
- 报告模式只读；
--fix另存清洗稿，不改原文。 --fix只处理确定性问题（BOM、控制字符、首尾空白、全角数字、短行补齐、可选去重）；
千分位逗号、货币符号、日期格式、表头命名一律只提示不代改。- 「千分位逗号」「货币符号」在部分场景是合法写法（如财务原表），本 skill 一律提示、由用户判断是否清理。
- 不做多表关联、跨文件主键/外键一致性检查。
依赖
仅需 Python 3.8+，使用标准库，无需联网、无需安装第三方包。
