飞书/钉钉表格与云文件下载（含 PDF 文本提取）

通过调用官方 OpenAPI，从本地脚本读取、写入并管理飞书/钉钉表格，并下载飞书/钉钉云文件。

前置条件

• 系统中已安装 python3 且在 PATH 路径中
• 飞书/钉钉应用凭证需配置在 ~/.openclaw/openclaw.json 文件的 channels.feishu 字段下：

{
  "channels": {
    "feishu": {
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "domain": "feishu"
    }
  }
}

• 飞书/钉钉应用必须在开发者控制台中启用 表格读写权限 和 云盘文件下载权限。
• 目标表格或文件必须已与该应用/机器人身份共享。

快速开始

从 URL 获取表格 token

示例 URL：

https://.../sheets/YOUR_SPREADSHEET_TOKEN?sheet=SHEET_ID

• spreadsheet_token = YOUR_SPREADSHEET_TOKEN
• sheet 查询参数（通常为 sheetId）= SHEET_ID

读取 / 导出数据

# 将单个区域导出为 CSV
python3 {baseDir}/scripts/sheets_export.py \
  --token YOUR_SPREADSHEET_TOKEN \
  --range 'SHEET_ID!A1:Z200' \
  --csv /tmp/sheet.csv

# 或导出为 JSON（推荐用于多区域）
python3 {baseDir}/scripts/sheets_export.py \
  --url 'https://xxx.larksuite.com/sheets/YOUR_SPREADSHEET_TOKEN?sheet=SHEET_ID' \
  --range 'SHEET_ID!A1:Z200' \
  --json /tmp/sheet.json

导出后，可加载 /tmp/sheet.csv 或 /tmp/sheet.json 文件进行后续分析或摘要处理。

写入 / 更新数据

# 列出所有工作表标签
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN list-sheets

# 向单个区域写入值
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN \
  write --range 'SheetId!A1:C2' --values '[["a","b","c"],["d","e","f"]]'

# 从 JSON 文件写入值
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN \
  write --range 'SheetId!A1:C2' --values-file /tmp/data.json

# 批量写入多个区域
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN \
  batch-write --batch '[{"range":"Sheet1!A1:B1","values":[["x","y"]]},{"range":"Sheet1!A2:B2","values":[["1","2"]]}]'

# 添加新工作表标签
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN \
  add-sheet --title 'NewSheet'

# 克隆现有工作表内容到新标签
python3 {baseDir}/scripts/sheets_write.py \
  --token YOUR_SPREADSHEET_TOKEN \
  clone-sheet --source-sheet-id abc123 --title 'ClonedSheet' --clone-range 'A1:Z200'

使用 URL 替代 --token

两个脚本均支持使用 --url 自动提取表格 token：

python3 {baseDir}/scripts/sheets_write.py \
  --url 'https://xxx.larksuite.com/sheets/YOUR_SPREADSHEET_TOKEN?sheet=SHEET_ID' \
  write --range 'SHEET_ID!A1:B1' --values '[["hello","world"]]'

文件下载

从飞书/钉钉云盘下载文件（PDF、文档等）。

从 URL 获取文件 token

示例 URL：

https://.../file/YOUR_FILE_TOKEN

• file_token = YOUR_FILE_TOKEN

下载文件

# 通过 URL 下载（PDF 文件会自动提取文本至 .txt 文件）
python3 {baseDir}/scripts/file_download.py \
  --url "https://.../file/YOUR_FILE_TOKEN" \
  --out /tmp/report.pdf

# 直接通过文件 token 下载
python3 {baseDir}/scripts/file_download.py \
  --file-token YOUR_FILE_TOKEN \
  --out /tmp/report.pdf

# 强制对非 PDF 文件提取文本
python3 {baseDir}/scripts/file_download.py \
  --file-token YOUR_FILE_TOKEN \
  --out /tmp/document.bin --extract-text

读取下载后的 PDF 内容

当 --out 输出路径以 .pdf 结尾时，脚本会 自动执行以下操作：

1. 提取文本内容生成 .txt 文件（如：/tmp/report.pdf → /tmp/report.txt）
2. 提取嵌入图片至 _images/ 目录（如：/tmp/report_images/img-000.png 等）
3. 若提取出的文本出现乱码或无法阅读，将自动将每页渲染为 PNG 图像，保存至 _pages/ 目录以供视觉查看

文本提取优先级顺序： pdfplumber → pypdf → pdftotext（poppler）。所有 Python 依赖包会在首次使用时通过 pip 自动安装。内置乱码检测机制——若提取文本不可读（如扫描件、特殊字体），将自动渲染页面为图像。

图片提取优先级顺序： pypdf → pdfimages（poppler）。

页面渲染（乱码降级方案）： pymupdf → pdf2image。

典型使用流程如下：

1. 运行下载脚本
2. 若文本可读 → 使用“读取”工具打开 /tmp/report.txt
3. 若文本乱码 → 使用“读取”工具查看 /tmp/report_pages/ 中的页面图像（AI 视觉识别）
4. 查看 /tmp/report_images/ 中的嵌入图片，用于图表、示意图等内容分析
5. 对内容进行总结或分析

对于非 PDF 文件，可使用 --extract-text 强制触发文本提取。

写入子命令参考

所有子命令均支持 --dry-run 参数，用于预览操作而不会实际执行。

注意事项 / 常见问题

• 范围格式： API 接受 "{sheetId}!A1:Z200" 或 "{sheetTitle}!A1:Z200" 格式。

- 如果不知道工作表标题，可先使用 list-sheets 命令查询，或从 URL 中获取 sheet= 参数值。

• 大表格处理： 优先导出所需列/行；逐步扩大范围以避免一次性读取过多数据。
• 数值格式： 必须为 JSON 数组的数组（行 × 列），例如 [["a","b"],["c","d"]]。
• 密钥安全： 脚本从 ~/.openclaw/openclaw.json 读取 appId/appSecret。请勿在聊天中打印或粘贴这些凭证。

故障排查

• 403 / 权限错误：

- 确认目标表格或文件已共享给应用/机器人身份。

- 确认 Lark/Feishu 应用已在开发者控制台中启用相应权限（如“表格读写”、“驱动文件下载”）。

• **values_batch_get failed / values_batch_update failed 返回非零错误码：**

- 多数情况是范围字符串格式错误。尝试缩小范围，或通过 list-sheets 验证 sheetId 或 sheetTitle 是否正确。

• **addSheet failed：**

- 可能是工作表标题已存在。同一文档内工作表标题必须唯一。

外部接口

本技能仅向以下 Lark/Feishu OpenAPI 接口发起外联请求：

对于使用国际版 Lark 的用户，基础地址应为 https://open.larksuite.com。

安全与隐私

• 凭证本地存储。 appId/appSecret 从 ~/.openclaw/openclaw.json 读取，仅用于向官方 Feishu/Lark OpenAPI 发起令牌交换请求。
• 数据不离开 Feishu 生态。 所有读写操作均通过官方 Lark OpenAPI 进行，不会将数据传输至外部系统。
• 脚本运行沙箱化。 脚本仅访问 OpenClaw 配置文件和目标表格，不会读取其他文件或环境变量。