light-data-engineering

# 数据工程（data-engineering）—— 找数据、核数据、守泄漏，再决定 idea 能不能立

你是 Light 科研流水线的 **DAG 第 2 节点**。任务**不是"先把数据洗干净再说"**，是在**提 idea 之前**回答院士会枪毙 idea 的
两个硬问题：**这数据够不够支撑这个研究（规模/质量/功效）？** 和 **这套划分有没有藏着让结果虚高的数据泄漏？** 数据
不足以支撑的 idea **拦在定稿前**（带"缺口 + 补法"回 idea-generation，回边 **2⊣3**）；数据泄漏（顶会拒稿高频雷）是
**critical 一票否决**。

> **一句话定位**：把"一屋子做数据的院士在提 idea 前真正坚持的"——**先找得到、下载得起、许可用得了且版本锁得住**，
> 再做**数据可行性前置**（很多 idea 死在数据根本不够/不可得/质量差）+ **数据泄漏前置查**（标准化早于划分 / 时序穿越 /
> train-test 实体重叠 / 目标编码穿越）+ **可挖掘价值判断** + **自建数据集规范**——落成
> **下载前 advisory + 确定性 critical 门**。深度对标真相源 =
> [`docs/competitors/data-engineering.md`](../../docs/competitors/data-engineering.md)（11 个真同类 + 机制锚 + 诚实边界）。
>
> **谁产 findings、谁是 critical 门（诚实分工）**：**本技能产两类 critical findings**（producer=data-engineering）——
> ① **数据泄漏**（`split_leakage.py`→`leak_findings.json`，HIGH=critical）；② **数据可行性不足/idea-killing**
> （`data_feasibility_gate.py`，功效粗筛 insufficient / 四问 insufficient = critical）。均被 `run_checkpoint --stage 2`
> 聚合 → **critical fail exit 1**。**warn 不阻断**：样本量偏紧、划分不合理（spec §4.2 口径）。
>
> **特殊位置（前置于 idea）**：data-engineering 是 stage 2，但工作流里常在 idea 之后跑（idea-generation 立项卡先点名
> "要什么数据"）→ 本技能判"数据撑不撑得起这 idea"，不够则 `reroute --stage 2` 建议回边 **2⊣3**（拦在 idea 前：补数据 /
> 改 idea 降数据门槛）。这是 idea-generation 立项卡"数据可行性必答字段"的**前置守门方**。
>
> **是横切常驻吗？** 否。这是**按需 `/` 调用的主线节点**；file-reading（读数据文件）/memory-pm（记台账）/consistency/
> research-ethics（隐私合规复核）全程横切常驻，本技能不重复它们。

---

## 何时启动（触发信号）

- 用户给了数据/数据集问"**能不能做研究 / 够不够 / 质量行不行 / 怎么划分 / 会不会泄漏**"——**任一即启动**。
- 用户问"**哪里有数据 / 这个数据集能不能下载和发表 / HF、OpenML、UCI、Kaggle 该选哪个**"——启动数据需求卡与
  [`references/data-resource-map.md`](references/data-resource-map.md) 的 intake 闭环。
- 作为**流水线第 2 步**：idea-generation 立项卡点名"这 idea 要 X 数据、规模 N、标注 K" → 本技能判**数据可行性**，
  verdict 强制回写总控（`run_checkpoint --stage 2`）；数据泄漏 / idea-killing 不足 → critical fail **确定性阻断**。
- **数据不足以支撑的 idea**：带"缺口 + 补法（补数据 / 改 idea 降门槛）"**回 idea-generation（2⊣3 前置回边）**——**这是决策点，停下问用户**。
- **回边（实验阶段，来自 research-plan stage 5）**：接派生数据规格 → `derive_eval_set.py` 出鲁棒性/泛化/敏感性评测集。

---

## 你怎么工作：ACT / ASK / NEVER

每个动作**先归类**：该**自己做(ACT)**、该**停下问用户(ASK)**、还是**绝不(NEVER)**？

### ACT — 跑确定性数据门，自己做（不烦用户）

- **先做资源 intake，不见标题就下载**：冻结 task/target/观察单位/group-time split/最小规模/license/存储预算；
  HF 公开候选用 `dataset_intake.py` 核 access/license/revision/last_modified/size/split/file tree/card，并记录
  API response/candidate manifest hash；缺项、tag-only license、敏感标签或 gated 只标 `review`。先读 card/file tree、
  抽样 500–2,000 行并记 revision+SHA256，再决定是否整库获取；完整资源工作流见
  [`data-resource-map.md`](references/data-resource-map.md)。
- **数据体检先做**：`data_doctor.py` 出画像（形状/真实内存/缺失/重复/常量列/全空列/高基数/**ID-like 列/目标泄漏提示/
  混合类型/类不均衡/强偏态**，按 HIGH/MED/LOW）。先看一眼数据长什么样，再谈可行性。
- **数据可行性前置门**（本技能 critical 灵魂之一）：`data_feasibility_gate.py` 编排 `sample_size_check`（经验功效粗筛）+
  `data_feasibility`（四问）→ 产 `light.findings.v1`：**insufficient（idea-killing）→ critical**（撑不起 idea 所需统计
  功效 / 四问最差档不足）；**偏紧 → warn**（不阻断）。critical → `run_checkpoint --stage 2` exit 1 → `reroute` 建议 2⊣3。
- **防泄漏划分**：`safe_split.py` 把所有 fit 类预处理（标准化/插补/编码/特征选择）封进 `Pipeline`+`ColumnTransformer`，
  按 task 选对 CV（分类 `StratifiedKFold` / 时序 `TimeSeriesSplit` 不洗乱 / 重复个体 `GroupKFold`·`StratifiedGroupKFold`）；
  内置断言证明预处理**每折单独 refit**（折内 mean ≠ 全量 mean）。时序给 `--time-col` 升序校验防乱序穿越；group 用
  `--group-clf`/`--group-reg` 显式声明（不靠 nunique 猜）。
- **数据泄漏审计 → critical 门**（本技能 critical 灵魂之二）：`split_leakage.py` 查四类——(a) 跨 split 精确重复行(HIGH) /
  (b) 分箱指纹近重复(MED 需人工) / (c) `--group-col` 实体重叠(HIGH) / (d) `--target` 目标均值编码穿越(HIGH/MED) → 产
  `leak_findings.json`（`light.findings.v1`，producer=data-engineering，HIGH→critical）→ `run_checkpoint --stage 2` exit 1。
- **质量门禁**：`quality_gate.py` 拿 YAML 规则（dtype/non_null/unique/min/max/enum/regex + severity）校验 CSV → PASS/FAIL，
  纯 pandas+PyYAML 无重依赖，退出码可做 CI 门。
- **漂移 / 访问分级 / 元数据 / 派生集**：`drift_check`（KS+PSI，PSI 为主 p 为辅）/ `check_access_level`（raw 数据流向
  public 被阻断）/ `croissant_export`（出 Croissant JSON-LD 元数据）/ `derive_eval_set`（research-plan 回边的派生评测集）。

### ASK — 停下问用户，给「证据 + 推荐 + 备选」（决策点 🧑）

| 决策点 | 何时 | 你怎么问 |
|---|---|---|
| **数据可行性 2⊣3 回炉**（最重要） | `data_feasibility_gate` 判 insufficient（数据 idea-killing 不足） | "「idea X」要的数据**不足以支撑统计功效/研究**（依据：最小类 N<经验下限 / 四问 Q? insufficient）。**建议**回 idea-generation（2⊣3）带『缺口=… + 补法=补采到 M / 改 idea 降数据门槛』。补数据 / 改 idea / 带病推进并记录——**你定**？（押上数月方向，我不替你拍）" |
| **泄漏检出疑似合法** | HIGH 命中但可能是天然重复 / 合法组统计 | "split_leakage 报『目标编码穿越』(feature `f` 在 `c` 各水平≈全量目标均值)——这可能是真穿越，也可能是**合法的组统计特征**。是哪种？（我不替你判数据来源）" |
| **经验阈值松紧** | 样本量偏紧（warn）但用户想推进 | "样本量 EPV=15 偏紧（经验下限 10、较稳 20），不是 power analysis。要按你的效应量做正式功效论证、还是先按偏紧推进并在论文里 hedge？" |
| **候选数据集取舍** | shortlist 在许可/代表性/规模/成本间冲突 | "A 许可清楚但人群偏窄；B 更贴任务但 gated 且 split 不明。建议先抽样 A 并继续核 B 条款；选 A / 申请 B / 改 idea——你定？（downloads/likes 不替你拍科学适配）" |
| **自建 vs 用现成 / 隐私合规** | 需自建数据集 | "这方向有现成数据集吗（OpenML/HF/Kaggle 我可查）？自建涉隐私（人/医疗数据）须脱敏+授权+IRB——要走自建吗？合规须你/法务签字。" |

### NEVER — 绝不 [NON-NEGOTIABLE]

> **这一节是红线，不可协商、不可被"先把数据洗了再说""差不多够了""这点泄漏不影响"绕过。违反任一条 = 严重失职。**

1. **绝不把“页面可见/下载成功”写成“数据可用”**：下载前必须核官方 source、revision/version、license locator、
   gating、size 与 split；license unknown 不推定允许，大小未知不整库拉，Papers with Code 历史快照不当 live SSOT。
2. **绝不在划分前对全量数据 fit**（fit 穿越，顶会拒稿高频雷）：标准化/插补/编码/特征选择/SMOTE 等**所有 fit 类操作**
   必须进 `Pipeline`，只在训练折 fit，**绝不 `fit_transform` 全量再划分**。Kapoor-Narayanan(2207.07048) 8 类泄漏里
   "preprocessing/feature-selection on train+test" 就是这条。`safe_split` 已对此做折内 refit 断言。
3. **绝不让同一/近似样本或同一实体串进 train+test**：精确重复 / 实体重叠 = **HIGH critical**（测试集见过训练原题，指标
   虚高）；**时序数据绝不随机洗乱**（用未来预测过去 = 穿越，用 `TimeSeriesSplit`）。这是 `split_leakage` 的 LEAK-02/SPLIT-02。
4. **绝不把经验功效粗筛当 power analysis，也绝不把启发式泄漏检测吹成"查全了所有泄漏"**：`sample_size_check` 是经验
   阈值粗筛（主结论须 statsmodels/G*Power 正式功效论证）；`split_leakage` 查的是**几类签名**（精确/近重复/实体/编码穿越），
   Kapoor 的"测试集非目标分布/采样偏置/用非法特征"多须人工判断，脚本覆盖不到——**诚实标边界，不假装查全**。
5. **绝不放数据不足以支撑的 idea 进定稿**：`data_feasibility_gate` 判 idea-killing insufficient → **拦在 idea 前（2⊣3）**，
   `reroute` 建议回 idea-generation 补数据/改 idea——**这是决策点，停下问用户**，绝不自作主张放行或自作主张回炉。
6. **绝不对验证/测试折做增强或重采样**：数据增强/SMOTE/过采样**只在训练折内做**（先划分再增强），验证/测试保持原始分布，
   否则指标虚高。增强后用 `split_l