shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsNo API key required

表格体检与清洗

给 CSV / Excel 表格做数据质量体检，并一键清洗。当用户拿到一份「脏表」不知道从哪下手、想检查数据能不能用、需要找出重复/缺失/异常/格式混乱，或想批量清理表格时使用。 体检项：编码识别、空列、缺失率、完全重复行、主键重复、列名重复或空白、类型混杂、数值异常值（1.5×IQR）、文本首尾空格与不可见字符、日期格式不统一；输出 0-100 健康分 + HTML 报告 + 问题清单。 清洗项：去首尾空格、清除不可见字符、删全空列、去重复行、空值填充、列名规范化；输出清洗后文件 + 逐条变更日志。 不适用：数据可视化/图表、统计建模、需要联网的数据源对接。

personAuthor: user_1a10c7b9hubcommunity
downloadDownload package

表格体检与清洗

拿到一份 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）：

| 文件 | 内容 | |------|------| | 体检报告.html | 健康分 + 问题清单 + 字段画像，可直接给同事/领导看 | | 问题清单.csv | 问题明细，便于逐条销项 |

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

体检项一览

| 类别 | 具体检查 | |------|---------| | 表结构 | 列名重复、空列名、全空列、字段数不齐 | | 完整性 | 每列缺失率（≥50% 报高）、空行 | | 唯一性 | 完全重复行、主键重复、主键为空 | | 类型 | 数值/日期/布尔/文本判定，混杂比例 ≥15% 报警 | | 格式 | 日期格式不统一（自动识别 7 种常见格式） | | 脏字符 | 首尾空格、零宽字符、制表符等不可见字符 | | 数值 | 1.5×IQR 异常值检测（样本 ≥8 才启用） | | 编码 | CSV 自动尝试 UTF-8 / GBK / GB18030 / Big5 |

2) clean 一键清洗

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

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

| 选项 | 默认 | 说明 | |------|------|------| | --fill "值" | 不填 | 空值统一填充为该值 | | --to csv\|xlsx | 同源 | 输出格式，可用于格式互转 | | --no-trim | 关 | 保留首尾空格 | | --keep-empty-cols | 关 | 保留全空列 | | --keep-dup | 关 | 保留重复行 | | --keep-invisible | 关 | 保留不可见字符 |

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

典型工作流

# 步 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 指定；工作表名写错会列出全部可用工作表。

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

| 情况 | 表现 | |------|------| | .xls / .xlsb / .ods | 明确提示「请先用 Excel 另存为 .xlsx 或 .csv」 | | .xlsx 且未装 openpyxl | 提示运行 setup.py 安装 | | 文件为空 / 无有效行 | 提示「表格是空的（没有读到任何有内容的行）」 | | 编码无法识别 | 提示「请另存为 UTF-8 后重试」 | | 合并单元格 | 只取左上角值（不展开），如需展开请先在 Excel 处理 |

安全与隐私

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

文件地图

| 内容 | 位置 | |------|------| | 主脚本（scan / clean） | scripts/tabledoctor.py | | 环境自检 / 自动装依赖 | scripts/setup.py | | 参数速查与常见问题 | references/CHEATSHEET.md | | 技能图标 | assets/logo.png |