Excel/CSV → 飞书多维表格 导入技能

把 Excel / CSV / TSV 的表格数据清洗、归一后导入飞书多维表格（Base）， 并生成配套的仪表盘设计说明与交付物。 全流程规则驱动，脚本零业务常量（业务知识全在 config 里）。

1. 这个技能解决什么问题

你有一份表格，想变成飞书多维表格里可用的数据，并且能看出趋势。 中间的坑很多：业务单号被当成时间戳导致数据被删、列里的前后空格让去重失效、 千分位让金额求和变成 0、日期列其实是 Excel 序列号。

本技能把这些坑的处理规则固化下来，每一条都有坑位编号可查（references/pitfalls.md， 34 条）。

2. 什么时候该用 / 不该用

应该触发

| 场景 | 例子 | |---|---| | 有一份结构化的表格数据要导入 Base | 「这个 Excel 有 5000 行，要导入飞书多维表格」 | | 导入后要做看板 | 「导入后想看每日趋势和门店排行」 | | 数据质量有问题要先清 | 「列里有千分位、前后空格、重复行要先清」 | | 导入后要核对 | 「不确定有没有重复写入，要独立复核」 |

不该触发

| 场景 | 为什么 | 该怎么做 | |---|---|---| | 只有几条记录、要手动改 | 全套流程对小数据太重 | 直接在 Base 里手动录 | | 非结构化数据（邮件、长文本、多页 PDF） | 本技能处理的是行列结构的数据 | 先用别的工具转成表格 | | 要做的是数据仓库 / ETL 定时任务 | 本技能是一次性交互式流程，无调度、无增量 | 用专业 ETL 工具 | | 涉及客户个人隐私明细 | 技能有脱敏机制但不能替代合规审查 | 先做合规评估 |

3. 十步工作流

步数与 SKILL.md 的 Step 0 ~ Step 9 一致（十步，含 Step 0 环境自检）。 两处是同一流程的两种表述，数字必须相同。

| 步 | 做什么 | 关键产物 | 脚本 | |---|---|---|---| | 0 | 环境自检、定位源文件 | 解释器路径、源文件位置 | pick_python.sh | | 1 | 表结构画像 | 字段名、类型推断、隐藏表/筛选状态 | profile_table.py | | 2 | 清洗与归一 | 清洗后数据、脏数据清单 | clean_normalize.py | | 3 | 建表 / 确认字段类型 | Base 结构、字段映射 | lark-cli | | 4 | 建维度表 | 维度表结构 | lark-cli | | 5 | 组装记录 | 写入契约格式的 records | assemble_records.py | | 6 | 安全写入 | 写入报告、清理副本 | safe_batch_import.py | | 7 | 独立校验 | 校验报告 | verify_import.py | | 8 | 仪表盘 | 看板设计说明 | 见 dashboard-design.md | | 9 | 交付 | 交付物清单 | 见 delivery-template.md |

每步开始前必查 references/pitfalls.md 对应条目。

4. 命令行入口

4.1 选解释器（三轮探测）

PY=$(bash scripts/pick_python.sh)

按依赖能否导入探测（不是「能 import sys」）： yaml+openpyxl 都成功 → 采用；仅 yaml → 采用并提示装 openpyxl；yaml 缺失 → 返回码 1。

可用环境变量覆盖：EXCEL_TO_FEISHU_PYTHON（指定解释器）、 PYTHON_VENV_ROOT（托管解释器根目录，用 glob 查找，不写死版本号）。

4.2 画像

"$PY" scripts/profile_table.py <数据文件> --sheet <表名> --out 画像.json

4.3 清洗

"$PY" scripts/clean_normalize.py --config <项目>.yaml \\
    --records 清洗前.json --out 清洗后.json --dirty 脏数据.json

自验证（不依赖任何外部文件）：

"$PY" scripts/clean_normalize.py --self-test

4.4 写入（写 + 核对 + 清副本一体）

"$PY" scripts/safe_batch_import.py --config <项目>.yaml \\
    --records 组装后.json --work-dir ./w --yes

不加 --yes 时只做预览，不写入。

4.5 独立校验

"$PY" scripts/verify_import.py --config <项目>.yaml --out 校验报告.json

⚠ passed 不是唯一成功判据：写入类命令可能被环境重复执行（P-21）。 必须以 verify_import.py 的独立复核为准。

5. 安全边界

| 边界 | 说明 | |---|---| | 不删业务数据 | 去重清理的分组键禁用时间戳转换（dedup_key 签名里没有 field_types），防止业务单号被转成日期后碰撞。删前必看 --dry-run 预览的原始值 | | 绝不自动归并 | 括号后缀、同前缀疑似截断只标记不归并，由人决定（P1-F-9） | | 不静默丢行 | 清洗前后行数必须一致，重复行只标记不删 | | 写入前必过门禁 | baseline_rows 缺失 → 返回码 2 拒绝写入 | | 不做增量调度 | 本技能不假设「昨天跑过一次」，每次都从配置声明的基线算起 | | 分母为 0 显示「暂无数据」 | 绝不显示 0%。数据缺失被当成业务结论比代码 bug 危险（P-35） |

6. 已知能力边界

| 边界 | 说明 | 坑位 | |---|---|---| | 日期序列号仅覆盖 1900-2173 | 序列号上限 99999，5 位以上不识别 | P-34 | | .xls（老格式）不支持 | 兜底解析路径只适用 .xlsx | — | | 公式单元格须先经 Excel 打开保存一次 | 否则缓存为空，读出来是空值 | P-27 | | 合并单元格取值未展开 | 两条读取路径行为是否一致未验证 | — | | 13 位单号靠位数无法判断 | 单号与真毫秒戳完全同形，只能靠 config 显式声明 | P-24 | | 比率类 KPI 的分母可能为 0 | 五个常见比率指标都会遇到，须按「暂无数据」处理 | P-35 |

完整的能力边界与未覆盖项见 docs/acceptance-checklist.md 的 G-5b 一节 （含三条已实测、三条明确未验）。

7. 使用示例

7.1 应该触发

例 1：「这个 Excel 有 2000 行门店数据，帮我导入飞书多维表格并做个看板」 → 表格结构、九步流程全适用。

例 2：「导入后不确定有没有重复写入，能帮我核对吗」 → 适用 Step 7 独立校验。注意 passed 不等于没重复，必须独立复核。

例 3：「金额列里有逗号和 ¥ 符号，能处理吗」 → 适用 Step 2 清洗的 G3 组，config.cleaning 里声明 kind: money。

7.2 不应该触发

例 4：「就 5 条数据，我直接手动录吧」 → 全套流程对小数据太重，手录更快。强推流程反而增加出错面。

例 5「每周要自动跑一次，把上周数据同步进去」 → 本技能是一次性交互式流程，没有调度与增量。用专业 ETL 工具。 让它「自动」跑的结果是：基线算错、重复写入、且没人发现（P-21）。

例 6「这些数据要按权限分给不同人看」 → 授权与行级权限在 references/permission-guide.md， 但本技能不做权限架构设计，那要先做合规评估。

8. 文档索引

| 想知道 | 看哪份 | |---|---| | 完整工作流每步怎么走 | SKILL.md（十章） | | 遇到报错怎么查 | references/error-codes.md（症状 → 坑位 → 处置） | | 开始某步之前要知道的坑 | references/pitfalls.md（34 条活文档） | | 字段怎么定类型 | references/field-type-rules.md | | 命名怎么起 | references/naming-conventions.md | | 看板怎么设计（6 套） | references/dashboard-design.md | | 业务指标口径（4 类） | references/business-metrics.md | | 交付物格式（12 节，节号冻结） | references/delivery-template.md | | CLI 参数陷阱 | references/lark-cli-cheatsheet.md | | 授权流程 | references/permission-guide.md | | 验收清单 | docs/acceptance-checklist.md | | 基线核对 | docs/BASELINE.md + docs/check_baseline.py |

从 v1 升级

见 CHANGELOG.md，含文件级对照表与破坏性变更清单。

⚠ references/delivery-template.md 的 12 节编号是冻结的： 不得重编号、不得跳号。v1 交付物按序号被引用，重编号会让所有 「按第 N 节交付」的既有会话全错位，且这种错位是静默的（格式仍合法，内容全错）。