表格数据读写引擎
> 表格数据最大的坑不是"读不出来"，是读出来了但列错位、编码乱、日期变数字。
> 这个引擎让每一次读写可校验——输出附带"清洗报告"。
Use when（什么时候用我）
- Agent 需要读写 CSV/Excel 数据
- 清洗脏数据（乱码/空行/重复/格式不一）
- 合并多表（按主键 JOIN / 拼接 / 汇总）
- 格式转换（Excel↔CSV↔Markdown 表格）
- 大文件处理（十万行+，内存装不下）
Triggers include
「表格处理」「CSV」「Excel」「数据清洗」「多表合并」「表格转换」「行列转置」「大文件分块」「数据校验」
核心方法：读写四步+清洗报告
步骤1 探测：编码探测（UTF-8/GBK/BOM）→ 分隔符探测 → 表头行探测
步骤2 读取：分块读（大文件流式）→ 类型推断（数字/日期/文本）
步骤3 处理：清洗（去空行/去重/补默认）→ 转换（合并/转置/聚合）
步骤4 写出：目标格式 + 编码声明 + 附带清洗报告
清洗报告（每次必输出）：
读取：12,345 行 × 18 列（UTF-8 with BOM，表头第1行）
清洗：去空行 23 行 | 去重 45 行 | 日期列格式归一（3种→1种）
警告：第3401行第7列疑似列错位（字段数≠表头数）
真实故障修复库（Pro 独有）
| 症状 | 根因 | 修复 |
|---|---|---|
第一列列名带 \ufeff |
UTF-8 BOM | 读取时 encoding='utf-8-sig' |
| 中文全乱码 | GBK 当 UTF-8 读 | 编码探测+重读 |
日期变 45291 |
Excel 序列号 | 1899-12-30 起算+天数转换 |
| 字段内逗号断列 | CSV 转义 | 标准库 csv 而非 split(',') |
| Excel 合并单元格 | 结构丢失 | 读取时向上填充空值 |
| 十万行 OOM | 全量载入 | 分块读（chunksize）+流式写 |
| 列错位 | 行内字段数≠表头 | 按列数校验+标记异常行 |
与普通 pandas 用法的区别
| 能力 | 裸 pandas | 本引擎 |
|---|---|---|
| 编码探测 | 报错就崩 | ✅ 自动探测切换 |
| 清洗报告 | 无 | ✅ 每次附带 |
| 异常行标记 | 静默丢 | ✅ 列数校验+标记 |
| 大文件 | 易 OOM | ✅ 分块流式 |
| 格式往返 | 易丢结构 | ✅ 往返校验 |
安全红线
- 原始文件只读不覆盖（写新文件）
- 清洗前后行数差异必须报告（防静默丢数据）
- 敏感表格（含个人信息）提醒合规
文件结构
table-data-engine/
├── SKILL.md # 本文件
├── references/
│ └── failure-library.md # 故障修复库（7类症状+配方）
└── scripts/
└── table_probe.py # 表格探测（编码/分隔符/表头/类型）
版本历史
- v1.0.0（2026-10-16）：首发。读写四步+清洗报告+7类故障库。
