findscripter 何时使用
适用于：在数据进入模型、报表或决策前，系统性评估其健康度，挖出那些"不报错却悄悄污染下游"的质量问题，并给出按影响排序的修复方案。典型请求：
- "帮我画像/审计这份数据集" → 输出完整 DQS 报告 + 各列问题清单。
- "X 列出了什么问题？" → 定向审计该列的缺失、异常、类型、值域违规。
- "这份数据能用来建模吗？" → 输出建模就绪检查清单（逐项 pass/fail）。
- "帮我清洗这份数据" → 输出按优先级排序的修复方案，每个问题配具体变换。
- "给关键列配监控" → 输出阈值配置 + 告警检查清单。
- "和上个月比有没有变化？" → 输出分布对比报告，标记漂移。
不该用（负边界）：
- 要设计或优化数据库 schema/范式 → 用数据库设计类技能。
- 要搭建 ETL 管道本身 → 用工程类技能。
- 数据是财务模型的输出、需校验模型逻辑 → 用财务分析类技能。
步骤
按场景选其一切入。
模式 1 — 完整审计（全新数据集）
- 画像：跑
data_profiler.py，拿到形状、类型、完整性、分布与 DQS。 - 缺失值：跑
missing_value_analyzer.py，把缺失机制分类为 MCAR/MAR/MNAR。 - 异常值：跑
outlier_detector.py，用 IQR / Z-score / 修正 Z-score 标记离群点。 - 跨列检查：核对引用完整性、重复行、逻辑约束（如
start <= end）。 - 打分与报告：给出 DQS 并产出修复方案，问题按 严重度 × 波及面 排序。
模式 2 — 定向排查（怀疑具体列/指标/管道环节）
- 先问三连：什么坏了、什么时候开始、上游改了什么？
- 只对可疑列跑相应脚本。
- 有已知良好基线时，对比分布。
- 追到根因（源系统 / ETL 变换 / 摄入延迟）。
模式 3 — 持续监控搭建（活管道）
- 圈定驱动核心指标的 5–8 个关键列。
- 定阈值：可接受空值率、离群率、值域。
- 用
data_profiler.py --monitor生成监控清单与告警逻辑。 - 按摄入节奏排程检查。
指令
脚本默认读 CSV，统一用 --format json 可输出供下游使用。
# 画像：形状/类型/空值率/基数/分布 + DQS
python3 scripts/data_profiler.py --file data.csv
python3 scripts/data_profiler.py --file data.csv --columns col1,col2,col3
python3 scripts/data_profiler.py --file data.csv --format json
python3 scripts/data_profiler.py --file data.csv --monitor # 生成监控阈值
# 缺失值：体量/模式/机制(MCAR/MAR/MNAR) + 逐列填补建议
python3 scripts/missing_value_analyzer.py --file data.csv
python3 scripts/missing_value_analyzer.py --file data.csv --threshold 0.05
python3 scripts/missing_value_analyzer.py --file data.csv --format json
# 异常值：多方法 + 业务影响判断
python3 scripts/outlier_detector.py --file data.csv
python3 scripts/outlier_detector.py --file data.csv --method iqr
python3 scripts/outlier_detector.py --file data.csv --method zscore --threshold 2.5
python3 scripts/outlier_detector.py --file data.csv --format json
DQS（0–100，五维加权，报告必须置顶呈现）
| 维度 | 权重 | 衡量什么 |
|---|---|---|
| 完整性 Completeness | 30% | 关键列的空值/缺失率 |
| 一致性 Consistency | 25% | 类型符合、格式统一、无混合类型 |
| 有效性 Validity | 20% | 值落在预期域内（范围、类别、正则） |
| 唯一性 Uniqueness | 15% | 重复行、重复键、冗余列 |
| 时效性 Timeliness | 10% | 时间戳新鲜度、相对源系统的延迟 |
评分阈值：🟢 85–100 可上生产；🟡 65–84 带书面注意事项可用（限探索分析）；🔴 0–64 使用前必须修复。
异常检测公式（按分布选方法）
- IQR（默认，非参数稳健）：
x < Q1 − 1.5×IQR或x > Q3 + 1.5×IQR。 - Z-score：
|x − μ| / σ > 阈值（常用 3.0）。仅当近似正态且污染 <5% 时用——均值/标准差本身受离群点拖累。 - 修正 Z-score（Iglewicz-Hoaglin，偏态首选）：
M = 0.6745 × |x − median| / MAD，M > 3.5即离群。注意离散且单值主导列 MAD 可能为 0。
示例
报告统一用四段式结构：
结论 Bottom Line — DQS: 61/100 — 上生产前必须修复。 发现 What — 按 严重度×波及面 排序的具体问题。 影响 Why It Matters — 每个问题的业务/分析后果。 行动 How to Act — 具体、有序的修复步骤。
缺失值修复速查（务必在 null% >1% 时加 col_was_null 指示列，保留"曾为空"这一可能有预测价值的信息）：
| 空值率 | 建议动作 |
|---|---|
| <1% | 数据集大可删行，或用中位数/众数填补 |
| 1–10% | 填补 + 加二值指示列 col_was_null |
| 10–30% | 谨慎填补，查根因，书面记录假设 |
| >30% | 交业务评审，勿盲目填补，考虑删列 |
去重：先与数据 owner 确认唯一键；事件数据用 keep='last'（最新状态胜出），缓变维表用 keep='first'。
注意事项
主动风险触发器——一旦发现信号，不必等用户问，直接抛出：
- 隐形空值：空值被编码成
0、""、"N/A"、"null"字符串；不抓出来，完整性指标全是假的。 - 泄漏时间戳：未来日期、早于系统上线的日期、时区错配——会污染时序 join。
- 基数爆炸：上千唯一值的自由文本伪装成类别字段，会悄悄撑爆 one-hot 编码。
- 重复主键：PK 不唯一会让下游 join 和聚合全部失效。
- 分布漂移：当前分布相对基线偏离 >2σ（均值/标准差），预示上游管道变更。
- 相关性缺失：空值扎堆在某时间段/用户段/地区——是 MNAR 证据，不是随机丢失。
填补安全红线（按机制决定能否填）：MCAR 可放心填（均值/中位数）；MAR 须用纳入相关观测变量的模型条件填补；MNAR 不可填，填补必引入系统性偏差，须上报业务 owner。
证据分级 + 人审：每条发现打置信标签——🟢 已核实 / 🟡 很可能 / 🔴 推测（待业务确认）。绝不在未经人工确认下自动修复 🔴 级发现。
其他静默杀手：去尾空格（"active " ≠ "active"）、时区裸时间戳、UTF-8/Latin-1 编码错乱、数值被存成科学计数法字符串、上游 lookup 字段悄悄新增类别导致旧代码丢行。
互见
- 问题根因在 schema 设计/范式 → 数据库设计类技能。
- 数据是 订阅/事件数据喂 SaaS KPI → SaaS 指标类技能。
- 数据涉及 财务报表/会计数字 → 财务分析类技能。
- 审计 产品事件数据（漏斗、会话、留存）→ 产品分析类技能。
- 质量问题是系统性的、需当技术债跟踪 → 技术债跟踪类技能。
采编自 alirezarezvani/claude-skills（MIT 许可证）。理论依据：Rubin (1976) 缺失机制、Iglewicz-Hoaglin (1993) 异常检测、DAMA-DMBOK 与 ISO 8000 数据质量维度。