飞书多维表格与Excel同步

技能文档

---
name: excel-sync-bitable
title: 飞书多维表格与Excel同步
category: 办公效率
description: 把 Excel/CSV 数据安全导入飞书多维表格（新建表或已有表），或将多维表格导出为 Excel/CSV；支持按业务键做预览式更新同步（upsert），写入前预览、写入后回读校验。当用户需要 Excel 与飞书表格互导、按订单号等业务键增量同步数据时使用。触发词：飞书同步、多维表格导入、Excel导出、表格同步。
---

# Excel ↔ 飞书多维表格

使用 `scripts/excel_sync_bitable.py` 完成同步。任何对多维表格的写入操作前必须显式加 `--apply` 参数。

## 技能工作流

### 步骤1：前置确认

- 确认输入文件、Base URL、目标数据表和业务键列（如「订单号」）。
- 用户身份或权限不确定时，先执行 `lark-cli auth status` 确认登录态。
- 必须使用 Base URL（如 `https://xxx.feishu.cn/base/...`），不要猜测 token；脚本会用 `base +url-resolve` 解析。

### 步骤2：预览同步（不写入）

先跑不带 `--apply` 的同步，检查将要新增/更新的记录数与内容差异，作为向用户确认的依据：

```bash
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "https://example.feishu.cn/base/..." --key "订单号"
```

### 步骤3：确认后写入并回读校验

用户确认预览结果后，加 `--apply` 执行写入，并回读业务键核对：

```bash
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "https://example.feishu.cn/base/..." --key "订单号" --apply
```

### 步骤4：处理目标表中不存在的源列

```bash
# 默认：展示缺失字段及推断类型，不写入
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "https://example.feishu.cn/base/..." --key "订单号"

# 明确忽略缺失列
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "https://example.feishu.cn/base/..." --key "订单号" --missing-fields skip --apply

# 自动创建文本/数字/日期时间/复选框字段后导入
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "https://example.feishu.cn/base/..." --key "订单号" --missing-fields create --apply
```

### 步骤5：由工作簿建表或导出数据表

```bash
# 由 Excel 工作簿创建新的多维表格
python scripts/excel_sync_bitable.py create --input ./orders.xlsx --app-name "订单数据" --table-name "订单" --apply

# 导出多维表格的一张数据表
python scripts/excel_sync_bitable.py export --url "https://example.feishu.cn/base/..." --table-name "订单" --output ./orders.xlsx
```

## 安全规则

- `sync` 只更新业务键完全匹配的记录，不删除远端已有记录。
- 源表或目标表中出现空白键或重复键时立即停止，不做部分写入。
- 源列在目标表不存在时，默认只提示不写入（附推断类型）；确需跳过或建字段时，显式选择 `--missing-fields skip` 或 `--missing-fields create --apply`。
- 预览数字是用户确认的依据；只有用户确认目标表和数量后才使用 `--apply`。
- 当前实现支持文本、数字、日期/日期时间、复选框字段；单选、人员、附件、关联、公式、查找字段不要猜值写入，应按字段类型走专门的处理流程。

使用说明

# 飞书多维表格与Excel同步

Excel/CSV 与飞书多维表格双向同步：安全导入（带预览与回读校验）、按业务键增量更新、一键建表、整表导出。

## 使用

```bash
# 预览按「订单号」同步 orders.xlsx 会更新哪些记录（不写入）
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "<Base URL>" --key "订单号"

# 确认后执行写入
python scripts/excel_sync_bitable.py sync --input ./orders.xlsx --url "<Base URL>" --key "订单号" --apply

# 导出一张数据表到 Excel
python scripts/excel_sync_bitable.py export --url "<Base URL>" --table-name "订单" --output ./orders.xlsx
```

依赖：`pip install -r requirements.txt`，并已安装配置好 lark-cli。

## 工作原理

脚本封装飞书 lark-cli 完成读写：写入前按业务键做预演（区分新增/更新），空白键与重复键立即中止；`--apply` 为写入的显式确认开关，写入后回读业务键校验结果。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。