| name | lark-workflow-bitable-sync |
| version | 1.0.0 |
| description | 跨表数据同步器：从源多维表格读取数据，与目标表进行比对去重，将差异数据写入目标表。支持字段映射、增量同步、变更报告。当用户需要'数据同步'、'跨表同步'、'合并表格'、'数据迁移'、'表间数据同步'、'把A表的数据同步到B表'时使用。 |
| metadata | {"requires":{"bins":["lark-cli"]}} |
跨表数据同步器工作流
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理
适用场景
- "把表格A的新数据同步到表格B" / "数据同步"
- "跨表同步：收集表 → 跟进表" / "跨表同步"
- "合并这两个表格的数据" / "合并表格"
- "把A表的数据迁移到B表" / "数据迁移"
- "监控表格XXX，有新记录就通知我" / "表间数据同步"
前置条件
仅支持 user 身份。执行前确保已授权：
lark-cli auth login --domain base
工作流
{源表 base_token + table_id} → {目标表 base_token + table_id}
│
├── base +field-list (源表) ──────► 源表字段结构
│
├── base +field-list (目标表) ────► 目标表字段结构
│
├── AI 字段映射 ──────────────────► 源字段 ↔ 目标字段（用户确认）
│
├── base +record-list (源表) ────► 拉取源数据（分页，max 200/页）
│
├── base +record-list (目标表) ──► 拉取目标现有数据（用于去重）
│
├── AI 数据比对去重 ──────────────► 差异记录集（新增 + 更新）
│
└── base +record-upsert (目标表) ─► 写入差异数据（串行，间隔 1s）
Step 1: 获取表结构
分别获取源表和目标表的字段列表：
lark-cli base +field-list \
--base-token "<src_base_token>" \
--table-id "<src_table_id>" \
--as user
lark-cli base +field-list \
--base-token "<tgt_base_token>" \
--table-id "<tgt_table_id>" \
--as user
注意：两个 +field-list 调用不能并发，必须串行。
Step 2: AI 生成字段映射
根据两张表的字段名和类型，AI 自动生成字段映射方案：
## 字段映射方案
| 源字段 | 源类型 | → | 目标字段 | 目标类型 |
|--------|--------|---|---------|---------|
| 客户名称 | text | → | 公司名称 | text |
| 联系电话 | text | → | 电话 | text |
| 状态 | select | → | 跟进状态 | select |
| 创建时间 | datetime | → | 录入日期 | datetime |
**去重字段**：客户名称（以此字段判断记录是否已存在）
请确认此映射方案。
重要：
- 必须与用户确认字段映射方案后再执行同步
- 让用户指定去重字段（用于判断记录是否已存在）
- 只映射可写入字段（忽略公式、查找引用、系统字段）
Step 3: 拉取源数据
lark-cli base +record-list \
--base-token "<src_base_token>" \
--table-id "<src_table_id>" \
--as user
lark-cli base +record-list \
--base-token "<src_base_token>" \
--table-id "<src_table_id>" \
--limit 200 \
--as user
注意：每页最多 200 条记录。如果返回数据中有分页信息，继续使用 offset 拉取下一页。
Step 4: 拉取目标数据（去重用）
lark-cli base +record-list \
--base-token "<tgt_base_token>" \
--table-id "<tgt_table_id>" \
--as user
Step 5: AI 比对去重
对比源数据和目标数据，基于去重字段判断：
- 新增：源表中有但目标表中没有的记录
- 更新：源表和目标表都有的记录，但字段值有差异
生成差异报告：
## 同步预览
| 类型 | 数量 |
|------|------|
| 新增记录 | N |
| 需更新记录 | N |
| 无变化记录 | N |
| **总计** | **N** |
### 新增记录预览（前 5 条）
| 客户名称 | 联系电话 | 状态 |
|---------|---------|------|
### 需更新记录预览（前 5 条）
| 客户名称 | 字段 | 旧值 | 新值 |
|---------|------|------|------|
确认执行同步？
Step 6: 写入差异数据
对每条差异记录调用 +record-upsert（串行，间隔 1 秒）：
新增记录
lark-cli base +record-upsert \
--base-token "<tgt_base_token>" \
--table-id "<tgt_table_id>" \
--json '{"公司名称":"XX科技","电话":"13800138000","跟进状态":"新线索"}' \
--as user
sleep 1
更新记录
先获取目标记录的 record_id，再更新：
lark-cli base +record-upsert \
--base-token "<tgt_base_token>" \
--table-id "<tgt_table_id>" \
--record-id "<existing_record_id>" \
--json '{"跟进状态":"已联系"}' \
--as user
sleep 1
注意：
- 每次调用间隔至少 1 秒
- 日期字段需要 Unix 毫秒时间戳（不是字符串）
- 人员字段格式为
[{"id":"ou_xxx"}]
- 单选字段传选项名称字符串
降级策略
| 场景 | 降级方案 |
|---|
| 字段类型不匹配 | 跳过不兼容字段，只同步兼容字段 |
| 目标表无匹配字段 | 提示用户在目标表创建对应字段 |
| 数据量过大 | 分批同步（每批 50 条） |
| 写入频率限制 | 降低到每 2 秒一条 |
| 字段映射不明确 | 询问用户确认映射关系 |
权限表
| 命令 | 所需 scope |
|---|
base +field-list | bitable:app:readonly |
base +record-list | bitable:app:readonly |
base +record-upsert | bitable:app |
参考
