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 选择后续操作：

模块索引

权限表

OpenClaw 集成与 API 融合

问题分析

当使用 OpenClaw 时，可能会出现以下问题：

• OpenClaw 倾向于直接调用飞书 API，而不是使用本 Skill
• 即使使用本 Skill，也可能出现上下文溢出或操作中断的情况
• 缺乏标准化的模板，导致每次操作都需要重新构造命令

融合方案

1. 智能路由机制

当检测到以下场景时，自动使用本 Skill 而非直接 API 调用：

2. 自动降级策略

当遇到以下情况时，自动从 API 调用降级到本 Skill：

1. API 调用失败：当直接 API 调用返回 429（速率限制）、1254291（并发冲突）等错误时
2. 上下文溢出：当 Agent 处理数据时出现上下文长度限制警告
3. 操作中断：当批量操作中途停止，需要断点续传时

3. 模板使用指南

OpenClaw 可以通过以下方式使用模板：

# 示例：使用 base_read_batch 模板读取大量数据
from lark_workflow_batch_data import BaseReadBatch

reader = BaseReadBatch(
    base_token="app_xxx",
    table_id="tbl_xxx",
    limit=200
)

# 自动分页读取所有数据
results = reader.read_all()

# 处理结果
for batch in results:
    print(f"读取了 {len(batch)} 条记录")

4. 环境变量配置

为了让 OpenClaw 能够自动识别并使用本 Skill，建议设置以下环境变量：

# .env 文件
LARK_WORKFLOW_BATCH_DATA_ENABLED=true
LARK_WORKFLOW_BATCH_DATA_THRESHOLD=200  # 触发批量处理的阈值
LARK_WORKFLOW_BATCH_DATA_RETRY_TIMES=3  # 重试次数

实现建议

1. 创建 Python 包装器：为 lark-cli 命令创建 Python 包装器，使 OpenClaw 能够更方便地调用
2. 添加状态管理：在 OpenClaw 中添加状态管理模块，记录批量操作的进度和断点
3. 智能检测：实现智能检测机制，自动判断何时使用本 Skill，何时使用直接 API 调用
4. 错误处理统一：统一处理 API 错误和 Skill 错误，提供一致的错误恢复机制
5. 进度反馈：在 OpenClaw 界面中显示批量操作的进度，让用户了解当前状态

示例：OpenClaw 集成代码

# openclaw_lark_integration.py

def handle_lark_operation(user_input, context):
    # 检测操作类型和数据量
    operation_type = detect_operation_type(user_input)
    data_size = estimate_data_size(user_input, context)

    # 智能路由
    if operation_type == "read" and data_size > 200:
        # 使用批量读取模板
        return use_template("base_read_batch", user_input, context)
    elif operation_type == "write" and data_size > 50:
        # 使用批量写入模板
        return use_template("base_write_batch", user_input, context)
    elif operation_type == "analysis":
        # 使用服务端分析模板
        return use_template("base_analysis", user_input, context)
    elif operation_type == "migration":
        # 使用数据迁移模板
        return use_template("data_migration", user_input, context)
    elif operation_type == "import":
        # 使用文件导入模板
        return use_template("excel_import", user_input, context)
    else:
        # 使用直接 API 调用
        return use_direct_api(operation_type, user_input, context)

参考

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