data-cleaning

数据清洗

应将清洗视为对观测数据集进行的受控转换，而非表面编辑。保留原始输入，明确目标用途和数据粒度，将每个有损决策明示，并证明清洗后的输出符合契约。

当模型提出数据转换方案时，加载AI 边界工作流 并使用配套记录。

按任务选择后续内容

需求	后续阅读
端到端方法、范围和停止规则	references/methodology.md
选择库或平台	references/tool-selection.md
缺失值、重复项、类型、范围、类别、日期、连接	references/operations.md
文本、标识符、Unicode 和实体解析	references/text-and-entity.md
架构、契约、验证、漂移、规模	references/validation-and-scale.md
CLI、OpenRefine、监控和交互式修复	references/cli-and-interactive-tools.md
来源声明和与版本相关的注意事项	references/sources.md
计划、日志、例外、契约或报告	templates/cleaning-plan.md、templates/transformation-log.jsonl、templates/exception-register.csv、templates/schema-contract.yml、templates/quality-report.md
轻量级分析或核对	运行 python3 scripts/profile_dataset.py --help 或 python3 scripts/reconcile_dataset.py --help

可用脚本

脚本	用途	调用方式
scripts/profile_dataset.py	对 CSV、TSV 或 JSONL 输入进行无需依赖的首次分析，不修改输入：检查缺失值、基数、候选类型、重复项、范围和值异常。在工作流第 3 步（更改前先分析）运行，作为证据收集环节，为设计任何清洗决策提供依据。	python3 scripts/profile_dataset.py data.csv --output profile.json
scripts/reconcile_dataset.py	核对转换前后的分隔符分隔数据集：统计行数、键的唯一性/重叠情况及各列总和（--sum），按 --key 指定的键核对，并写入机器可读报告。在“验证两次 / 审查”期间运行，以证明数据粒度得以保留，并准确量化转换带来的变化。	python3 scripts/reconcile_dataset.py raw.csv cleaned.csv --key id --sum amount --output reconciliation.json
scripts/test_profile_dataset.py	Pytest 测试套件，用于检查分析器在代表性输入上的行为。修改分析器后或审查其输出时运行；CI 会自动发现此测试套件。	python3 -m pytest scripts/test_profile_dataset.py
scripts/test_reconcile_dataset.py	Pytest 测试套件，用于检查核对器的键处理、求和和报告行为。修改核对器后或审查其输出时运行；CI 会自动发现此测试套件。	python3 -m pytest scripts/test_reconcile_dataset.py

默认工作流

1. 明确问题： 确认决策、负责人、来源、隐私约束、观测单位、键、预期粒度、时间窗口和验收阈值。不要根据可疑值默默推断业务规则。
2. 固定证据： 记录来源路径/URI、检索时间、文件大小/哈希（可行时）、编码、分隔符、架构、行数/列数和软件版本。将原始数据保持为只读，并写入新的输出。
3. 先分析，再修改： 检查缺失情况、哨兵值、重复项、基数、候选类型、范围、无效日期、空白/Unicode 异常、字段间关系和漂移。先使用捆绑的分析工具进行无需依赖的初步检查。
4. 设计决策： 将每项发现归类为保留、标准化、修复、填补、隔离、拒绝或升级处理。记录理由、规则、受影响的行、置信度、可逆性和负责人。
5. 分层转换： 优先采用确定性且命名清晰的步骤：解析 → 规范化 → 类型转换/强制转换 → 验证 → 去重 → 实体解析 → 填补/隔离 → 重塑。将原始数据、暂存数据、拒绝数据和最终数据集分开保存。
6. 验证两次： 在转换前后都运行结构检查。验证行数/粒度保留情况、键唯一性、引用完整性、允许值、单位、边界、空值策略和预期分布。测试应能识别失败记录。
7. 审查并发布： 比较转换前后的指标，检查每类变更的样本；语义变更或有损变更须获得领域审批；发布报告和来源信息，并确保运行可复现。

不可妥协的控制措施

• 切勿覆盖原始数据，也不得默默丢弃行、列、类别、异常值或未匹配的实体。
• 如果领域有所区分，应将无效、缺失、不适用、未收集和已隐去的数据分开处理。
• 使用明确的区域设置、时区、单位和错误策略解析日期与数字。统计解析失败的数量；不要默默将其转换为空值。
• 谨慎规范化文本。进行匹配或修复时，应保留原始值和规范化后的值，以及置信度。
• 仅使用获准的训练/参考分区来拟合填补器、编码器、规范化参数和去重规则。避免跨时间或评估边界的数据泄漏。
• 将分析结果视为调查证据，而非自动修复的许可。异常也可能是真实事件。
• 对无法安全修复的记录进行隔离。“干净”表示符合既定契约，而非“没有剩余行”。

完成门槛

只有在输出、转换/决策日志、验证证据、来源信息和未解决问题均已存在，原始数据保持完整，验收检查通过，且审查者能够复现或审计结果时，清洗任务才算完成。如果语义仍有歧义，应停止处理并进行隔离或升级，而不是臆造一个值。

不适用场景

不要将此技能用于推断统计或模型选择，这些工作应交由 data-scientist；ETL 编排、存储或生产数据质量运维应交由 data-engineering；操作指定的验证或数据库平台则应交由该工具对应的技能。此技能提供清洗判断和相关产物，供这些工作流使用。

前置条件

• Python 3.9+，两个捆绑脚本均仅使用标准库（参见 compatibility）；生态工具（OpenRefine、基于 pandas 的工具）是可选的加速工具，详见 references/cli-and-interactive-tools.md。
• 可保持只读的原始输入，以及对单独输出位置的写入权限——所有脚本读取输入时都不会修改输入。
• 任务需要正式产物时，使用上述模板：清洗计划、转换日志、异常登记表、架构契约或质量报告。
• 仅在运行捆绑的测试套件时需要 pytest。

局限

• 随附的探查器和协调器是初步的证据工具：它们会揭示异常并量化差异，但不会决定保留、修复、填补还是隔离——这些分类仍由工作流的决策步骤负责。
• 两个脚本都支持分隔符文本和 JSONL；二进制格式、关系数据库和嵌套文档存储需要使用其他工具。
• 探查输出是调查证据，绝不意味着可以自动修复；异常也可能是真实事件。
• 通过协调校验只能证明所检查的键和总和在结构上得到保留——值在语义上是否正确，仍需经过审查和发布关卡。