数据清洗与预处理

解决什么问题

当你把一份原始 CSV 或数据库导出丢给 AI Agent 做分析时，最先撞上的往往不是“模型不够聪明”，而是数据本身：同一列里既有 2024-01-15 也有 01/15/2024；金额列混着 $、逗号和空格；两张表按用户邮箱 join 时，一边是大写、一边多了首尾空格，结果匹配率惨不忍睹。这类问题不会让代码直接报错，却会让后续的统计、建模和报表悄悄失真。

@user_fccf428b/data-cleaning-cleaner 把清洗动作拆解成可审计、可复现的流程，让 Agent 在写分析代码之前，先把数据质量这一层处理干净。

核心能力与工作方式

技能围绕一条固定的清洗流水线展开：

• 摄入并画像：加载数据后立即生成质量报告，统计每列空值数、识别重复行、比对列类型与预期 schema，并标记混合类型的列。后续每一步决策都基于这份画像。
• 缺失值处理：按列类型和缺失模式选择策略。数值列缺失率低于 5% 时用中位数填补；分类列用众数或专门的 Unknown 类别；缺失超过 40% 的列会被标记为候选删除项，并先征询用户再动手。
• 去重与冲突合并：区分完全重复和近似重复（仅空白或大小写不同）。完全重复保留第一条；近似重复通过模糊匹配识别，再按时间新旧或字段完整度合并冲突值。
• 类型纠正与格式统一：把日期字符串解析成 datetime，数值字符串转成浮点，分类值归一为规范形式；统一电话、邮编、货币等格式。
• 异常值检测：对称分布用 IQR（1.5 倍）方法，正态分布用 z-score，并提供三种处置方式：截断到边界值、置空后补插、或只打标记保留原值。
• 输出校验：清洗结果需要通过非空约束、范围检查、唯一性约束和参照完整性校验，最终交付清洗后的文件和一份记录所有变换的清洗日志。

底层工具链以 pandas 为核心，pyjanitor 提供链式调用便利，great_expectations 负责 schema 校验，fuzzywuzzy 做模糊字符串匹配，numpy 支撑数值运算。

适用边界与注意点

清洗应该是可复现而非破坏性的：任何变换之前都保留一份原始数据副本，日志里写明每一步的计数（例如“用 312.45 的中位数填补了 amount 列 23 个空值”）。缺失值填补优先采用领域知识驱动的方式，当某列缺失呈非随机模式（MNAR）时，应停下来与使用者确认，而不是套机械默认值。schema 校验应在每个清洗阶段之后都跑一遍，而不是只在结尾做一次。

遇到完全空的列会自动删除并记录警告；重复列名会在加载时检测并用后缀重命名；UnicodeDecodeError 时依次尝试 latin-1 和 cp1252 编码并记录成功项；日期列混合格式时用 pd.to_datetime(..., format="mixed") 解析并抽查结果；数值型字符串先剥离 $、€、逗号和空白再转换，转换失败会以 NaN 形式暴露而不是直接崩溃。