Excel to Feishu Dashboard

1. 技能定位

本技能用于把用户提供的 Excel、CSV 或 TSV 数据，经过结构识别、数据清洗、字段建模、飞书多维表格导入、视图/仪表盘设计和交付验收，沉淀为可协作、可复核、可维护的飞书 Base 数据看板。

核心目标不是“简单上传表格”，而是安全、可验证地完成以下闭环：

识别源文件结构和业务目标；
清洗数据并生成质量报告；
设计飞书字段、视图、筛选器和看板指标；
在授权明确的前提下执行 dry-run、测试写入、正式写入；
校验飞书数据与本地汇总结果一致；
输出可验收的交付总结、异常清单和维护建议。

2. 适用场景

当用户提出以下需求时，应优先使用本技能：

“把这个 Excel 导入飞书多维表格”；
“帮我把销售表做成飞书看板”；
“把酒店经营日报导入飞书，并生成收入、入住率、渠道看板”；
“清洗客户线索表，导入飞书后按负责人/状态生成视图”；
“把 CSV 数据转成飞书 Base，并配置统计图或仪表盘”；
“需要字段设计、批量写入、异常数据报告、仪表盘验收”。

3. 不适用场景

以下场景不要强行使用本技能：

仅做本地 Excel 分析，不需要飞书多维表格；
仅生成 PPT、Word、PDF，不涉及飞书 Base；
用户未授权访问、写入或修改目标飞书空间；
用户要求绕过权限、读取无权访问数据、泄露 token 或敏感凭据；
用户要求直接覆盖、删除生产数据，但未明确确认影响范围；
飞书 CLI/API 能力不支持目标操作且无可接受降级方案。

4. 必要输入

执行前应尽量收集以下信息。缺失时可先做本地分析和方案，不得臆造线上权限。

| 类别 | 必要信息 | 说明 | |---|---|---| | 数据文件 | Excel/CSV/TSV 文件 | 若上下文无文件，必须请用户补充 | | 业务目标 | 要回答的问题、核心 KPI、看板受众 | 例如收入趋势、门店排行、线索转化 | | 飞书目标 | base_token、table_id、是否新建表 | 未提供时只输出导入方案和字段设计 | | 授权身份 | user 或 bot | 写入前必须明确使用身份 | | 更新策略 | 新建、追加、更新、覆盖 | 覆盖/删除必须二次确认 | | 唯一键 | 订单号、客户 ID、日期+门店等 | 追加/更新必须确认去重策略 | | 隐私要求 | 手机号、证件号、邮箱、客户名等 | 默认脱敏，不得把敏感样例写入日志 | | 仪表盘需求 | 指标、维度、筛选器、权限 | API/CLI 不支持时交付配置方案 |

5. 安全与确认协议

5.1 默认安全策略

未经用户明确授权，不向飞书或任何外部系统写入数据。
未经确认，不上传包含手机号、证件号、邮箱、客户姓名、住客信息、订单隐私等敏感明细。
日志、错误信息、交付报告不得展示完整 token、cookie、Authorization header、app_secret、refresh_token、tenant_access_token、user_access_token。
样例数据默认脱敏；必要时只展示字段名、统计值和已脱敏片段。

5.2 风险分级

| 风险级别 | 操作 | 规则 | |---|---|---| | 低风险 | 本地读取、结构分析、字段设计、dry-run、生成方案 | 可直接执行 | | 中风险 | 在真实飞书 Base 中新建测试表、创建字段、写入少量测试数据 | 必须说明影响范围并获得用户确认后执行；优先使用测试表 | | 高风险 | 批量写入、覆盖更新、字段类型变更、删除/清空记录、修改生产表结构 | 必须说明影响范围并获得用户明确确认 | | 禁止 | 越权访问、泄露凭据、绕过授权、未确认直接破坏生产数据 | 必须拒绝或停止 |

5.3 写入前强制门禁

任何线上写入、覆盖、删除、批量修改动作之前，必须完成：

明确目标 Base、表、身份和权限；
生成字段映射和数据质量报告；
定义唯一键或说明只能追加及重复风险；
执行 dry-run 或最小测试写入；
说明影响范围、回滚/降级方案；
对高风险操作获得用户明确确认。

6. 工作流

Step 1：读取和盘点源数据

识别文件类型、sheet、编码、标题行、隐藏行列、合并单元格、公式、空行空列、总计/小计行。
输出基础统计：行数、列数、字段名、样例值、缺失率、重复率、异常值。
对多 sheet 文件，先判断主表、维表和关联关系。

参考：references/data-cleaning-checklist.md

Step 2：数据清洗与质量报告

按异常分级处理 P0/P1/P2/P3 问题。
保留原始数据，不覆盖源文件。
输出清洗后数据、异常记录、清洗规则、质量报告。
敏感字段默认脱敏或排除，除非用户明确要求保留且已确认权限。

Step 3：字段建模和类型映射

根据字段名、样例值、业务语义和质量统计生成字段 schema。
建立“原始字段名 — 飞书字段名 — 字段类型 — 写入格式 — 处理规则”的映射表。
对日期、金额、编号、单选/多选、人员、URL、附件、关联字段执行专门规则。

参考：references/field-type-mapping.md

Step 4：飞书权限与 CLI 检查

优先使用当前环境中的 lark-cli，当前多维表格入口应使用 base 命令族，而不是旧的 bitable 命令。执行前应检查：

lark-cli doctor
lark-cli auth status
lark-cli auth scopes
lark-cli base --help
lark-cli base +table-list --help

若 CLI 未安装、未登录、权限不足或目标 Base 不可访问：停止线上写入，转为交付本地清洗结果、字段设计、导入 JSON、操作指引和人工配置步骤。

参考：references/lark-cli-playbook.md

Step 5：创建或更新表结构

优先新建测试表或备份表验证字段结构。
修改生产表字段前必须说明影响范围。
字段类型不确定时降级为文本或要求用户确认。
保留字段映射表，记录 field_id 与业务字段名。

Step 6：dry-run、测试写入与正式导入

推荐顺序：

读取目标表结构；
执行字段差异比对；
构造少量样例记录；
执行 --dry-run；
如支持，写入测试表或测试记录；
验证字段、记录数和样例值；
获得确认后分批正式导入；
写入后抽样核对和指标复算。

Step 7：视图与仪表盘设计

根据日期、分类维度、金额/数量/比例指标生成看板方案。
若 CLI/API 支持自动创建 dashboard，可在 dry-run 和确认后创建。
若不支持自动化创建某类组件，应降级为：视图配置清单、图表配置表、人工配置步骤。

参考：references/dashboard-design.md

Step 8：交付验收

交付必须包含：

清洗后数据文件；
字段映射表；
异常记录表；
数据质量报告；
飞书表/视图/仪表盘链接或配置清单；
dry-run 或测试写入摘要；
导入日志和失败记录；
本地汇总与飞书结果校验；
风险、限制和用户下一步动作。

参考：references/delivery-template.md

7. 幂等、回滚与失败处理

追加写入必须定义唯一键；无唯一键时必须说明重复风险。
批量写入前记录原始记录数、目标表记录数、待写入行数。
每批写入保存批次编号、请求摘要、成功数、失败数、失败原因。
不对失败批次盲目全量重试；应导出失败行并定位字段、原始值和错误类型。
权限错误、字段类型错误、字段不存在：停止并回到授权/字段映射阶段。
网络错误、频控：可指数退避重试，建议最多 3 次。
覆盖或破坏性修改前必须创建备份表、导出快照或给出可接受回滚方案。

8. 参考文档

本技能包必须随包包含以下文件，缺失时视为不完整：

references/data-cleaning-checklist.md
references/field-type-mapping.md
references/lark-cli-playbook.md
references/dashboard-design.md
references/delivery-template.md

9. 完成前自检清单

[ ] 已确认用户目标和数据文件；
[ ] 已保留原始数据，不覆盖源文件；
[ ] 已生成字段映射表和质量报告；
[ ] 已识别并处理敏感字段；
[ ] 已完成 CLI/权限检查；
[ ] 写操作已 dry-run 或测试写入；
[ ] 高风险操作已获得明确确认；
[ ] 已记录写入批次、失败行和校验结果；
[ ] 本地核心指标与飞书结果一致或差异已说明；
[ ] 已输出可验收交付总结。