表格体检与清洗

拿到一份 CSV / Excel，先体检、再清洗，全程本地运行。

何时使用

• 用户说「这表数据干不干净」「帮我看看有没有问题」「去重」「删空列」「补空值」「格式乱七八糟帮我统一」
• 从别人手里接过一份表，不确定能不能直接用
• 做分析之前想做一次数据质量把关

不适用（请明确告知用户）：
- 画图表、做可视化 → 用图表类技能
- 统计建模、回归预测 → 本技能只做质量与清洗
- 对接数据库/在线表格 → 需要联网，本技能不联网

环境准备（首次一次即可）

python scripts/setup.py          # 缺 openpyxl 会自动装
python scripts/setup.py --check  # 只检查

• 处理 CSV / TSV：零第三方依赖，Python 自带库即可
• 处理 .xlsx：需要 openpyxl（脚本会提示并自动装）

两个子命令

1) scan 数据质量体检

python scripts/tabledoctor.py scan 订单.csv --key 订单号
python scripts/tabledoctor.py scan 报表.xlsx --sheet 明细

产出（在 --out 目录，默认 ./tabledoctor_output）：

健康分：满分 100，按问题严重度扣分（高 -12 / 中 -6 / 低 -2）。
分档：≥90 优秀 ｜ ≥75 良好 ｜ ≥60 一般 ｜ <60 较差。

体检项一览

2) clean 一键清洗

python scripts/tabledoctor.py clean 订单.csv --out 结果
python scripts/tabledoctor.py clean 订单.xlsx --to csv --fill "NULL"

产出：<原名>_cleaned.csv|xlsx + 清洗日志.txt（逐条列出改了什么）。

默认执行：列名规范化（空格→下划线、重复列加序号）、去空格、清不可见字符、删全空列、删空行、去重复行。

典型工作流

# 步 1：先体检，看问题在哪
python scripts/tabledoctor.py scan 原始表.csv --key 订单号
# 步 2：按报告建议清洗
python scripts/tabledoctor.py clean 原始表.csv --fill "" --to xlsx

行为约定（可放心依赖）

1. 不覆盖源文件：产物一律写到 --out 目录。
2. 不静默失败：打不开、编码识别不了、工作表不存在，都会给出具体原因与下一步建议。
3. 可追溯：清洗产出 清洗日志.txt，逐条记录改了哪一项、多少行。
4. 自动识别编码与分隔符：CSV 依次尝试 UTF-8/GBK/GB18030/Big5，分隔符自动嗅探（逗号/分号/Tab/竖线）。
5. Excel 多工作表：默认读第一个，--sheet 指定；工作表名写错会列出全部可用工作表。

已知限制（会明确报错，不会装作成功）

安全与隐私

• 零联网：不发起任何网络请求，不上传表格内容。
• 只读源文件：不会修改或删除用户原始文件。
• 无凭证：不读取、不存储任何账号或密钥。

文件地图