lark-workflow-batch-data（Lark 工作流程批量数据）

批量数据操作工作流

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

适用场景

• "帮我把这个 Excel 导入到多维表格" / "批量写入上千条记录"
• "导出多维表格所有数据" / "把表里的数据全量拉出来"
• "把 A 表的数据迁移到 B 表" / "跨表同步数据"
• "分析这张表的销售汇总" / "统计各部门人数"
• "我的 Agent 操作飞书文档时只处理了十几条数据就停了"
• "批量更新几千条记录的某个字段"

核心问题

Agent 直接调用飞书 API 操作大数据量文档时，常遇到以下问题导致只能处理十几条数据就中断：

前置条件

根据操作类型授权对应 scope：

# 多维表格操作
lark-cli auth login --domain base

# 电子表格操作
lark-cli auth login --domain sheets

# 导入导出
lark-cli auth login --domain drive

# 全部场景
lark-cli auth login --domain base,sheets,drive

决策树

用户意图
├── 读取/导出大量数据
│   ├── 只需聚合统计 → +data-query（服务端计算）→ 参考 analysis.md
│   ├── 需要全量明细
│   │   ├── Base 表 → +record-list 分页续读 → 参考 base-read.md
│   │   ├── Sheets 表 → +read 分片 或 +export 导出 → 参考 sheets-ops.md
│   │   └── 导出为文件 → +export → 参考 import-export.md
│   └── 部分数据 → +record-list --view-id 视图筛选
├── 写入/更新大量数据
│   ├── Base 表 → +record-upsert 分批写入 → 参考 base-write.md
│   ├── Sheets 表 → +write/+append 分片写入 → 参考 sheets-ops.md
│   └── 从本地文件导入 → drive +import → 参考 import-export.md
├── 数据迁移（A→B）
│   └── 读取源 → 写入目标 → 参考 migration.md
├── 遇到错误需要恢复
│   └── 参考断点信息 → 参考 error-recovery.md
└── Agent 操作截断
    └── 使用分页续读模式 → 参考 base-read.md 或 sheets-ops.md

全局原则

错误恢复策略总纲

执行任何批量操作前，MUST 先阅读 error-recovery.md，了解完整的错误分类、重试策略、断点续传模式和进度汇报模板。

核心机制：

1. 断点续传 — 维护进度状态变量（offset / batch_index / start_row），失败后从断点恢复
2. 指数退避重试 — 429 速率限制 → 2s→4s→8s，最多 3 次；1254291 并发冲突 → 等 1s 重试
3. 部分失败容错 — 记录失败记录到 failed_records，跳过继续，最终统一汇报
4. 批次自动缩减 — 1254104 批量超限 → 自动将批次从 500 缩减到 250→125
5. 进度汇报 — 每阶段结束向用户报告成功/失败/断点信息

Wiki 链接特殊处理

知识库链接（/wiki/TOKEN）背后可能是多维表格或电子表格。不能直接假设 URL 中的 token 就是 base_token 或 spreadsheet_token，必须先查询实际类型和真实 token：

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

根据返回的 obj_type 选择后续操作：

模块索引

权限表

参考

• lark-shared — 认证、权限（必读）
• lark-base — 多维表格操作
• lark-sheets — 电子表格操作
• lark-drive — 云空间操作