飞书文档读写操作技能

一、技能概述

该技能是 OpenClaw 飞书扩展的核心文档操作层。当用户提到飞书文档、云文档或 docx 链接时激活。它提供了一套统一的工具接口，覆盖飞书文档的所有常见操作，包括对 Docx 表格的完整支持（创建、写入）以及图片/文件附件上传。

二、核心功能

1. Token 提取

从飞书文档 URL 中提取文档标识符：

URL 格式：https://xxx.feishu.cn/docx/ABC123def
提取结果：doc_token = ABC123def

2. 文档读取

{ "action": "read", "doc_token": "ABC123def" }

返回：标题、纯文本内容、块统计信息。如果返回结果中包含 hint 字段，说明存在结构化内容（表格、图片等），需要进一步使用 list_blocks 读取完整数据。

3. 文档写入（替换全部）

{ "action": "write", "doc_token": "ABC123def", "content": "# Title\n\nMarkdown content..." }

用 Markdown 内容替换整个文档。支持：标题、列表、代码块、引用、链接、图片（![](url) 自动上传）、粗体/斜体/删除线。
⚠️ 限制：不支持 Markdown 表格。

4. 文档追加

{ "action": "append", "doc_token": "ABC123def", "content": "Additional content" }

将 Markdown 内容追加到文档末尾。

5. 创建文档

{ "action": "create", "title": "New Document", "owner_open_id": "ou_xxx" }

指定文件夹：

{ "action": "create", "title": "New Document", "folder_token": "fldcnXXX", "owner_open_id": "ou_xxx" }

重要：必须传入 owner_open_id（从入站元数据的 sender_id 获取），否则只有 bot 应用有访问权限，用户无法看到文档。

6. 块级管理（Block Operations）

操作	说明
`list_blocks`	返回完整块数据，包括表格、图片等，用于读取结构化内容
`get_block`	获取单个块的详细信息
`update_block`	更新指定块的文本内容
`delete_block`	删除指定块

7. 表格操作（Docx Table Block）

操作	说明
`create_table`	创建指定行列数的表格，可设置列宽
`write_table_cells`	向已有表格的单元格批量写入数据
`create_table_with_values`	一步完成表格创建与数据填充

所有表格操作均可选 parent_block_id 参数，将表格插入到指定块下。

8. 图片上传

从 URL 或本地文件上传图片到文档：

{ "action": "upload_image", "doc_token": "ABC123def", "url": "https://example.com/image.png" }

或本地路径 + 位置控制：

{ "action": "upload_image", "doc_token": "ABC123def", "file_path": "/tmp/image.png", "parent_block_id": "doxcnParent", "index": 5 }

index（0-based）控制图片在兄弟块中的插入位置，省略则追加到末尾
⚠️ 注意：图片显示大小由像素尺寸决定。小图片（如 480x270 的 GIF）在上传前应先缩放到 800px+ 宽度以确保正常显示

9. 文件附件上传

从 URL 或本地文件上传附件到文档：

{ "action": "upload_file", "doc_token": "ABC123def", "url": "https://example.com/report.pdf" }

或本地路径：

{ "action": "upload_file", "doc_token": "ABC123def", "file_path": "/tmp/report.pdf", "filename": "Q1-report.pdf" }

规则：

必须且只能指定 url 或 file_path 中的一项
可选 filename 覆盖文件名
可选 parent_block_id

三、标准读取工作流

先执行 action: "read" —— 获取纯文本内容 + 统计信息
检查返回结果中的 block_types，查看是否存在 Table、Image、Code 等结构化块
如果存在结构化内容，使用 action: "list_blocks" 获取完整数据

四、配置

channels:
  feishu:
    tools:
      doc: true  # 默认: true

注意：feishu_wiki 依赖此工具——Wiki 页面内容通过 feishu_doc 进行读写。

五、所需权限

docx:document
docx:document:readonly
docx:document.block:convert
drive:drive

六、主要用途

读取飞书文档内容：获取文档标题、正文、块统计信息，用于后续分析或处理
创建新文档：为用户自动创建飞书文档，并确保用户拥有完整访问权限
写入/追加内容：用 Markdown 格式批量更新文档内容，或追加新内容
表格管理：在 Docx 中创建表格、批量写入单元格数据，支持一步完成
图片/文件上传：将图片或文件附件上传到飞书文档的指定位置
块级精细编辑：对文档中的特定块进行读取、更新或删除操作
Wiki 页面读写：作为 feishu_wiki 技能的下层依赖，支持 Wiki 页面内容操作

七、重要原则

创建文档时必须传入 owner_open_id：否则只有 bot 有权访问，用户无法看到文档
Markdown 表格不支持：写入文档时无法通过 Markdown 语法创建表格，需使用专门的表格操作
小图片先缩放：上传前将小图片缩放到 800px+ 宽度以确保正常显示
结构化内容需二次读取：read 返回的 hint 字段提示存在表格/图片等，需用 list_blocks 获取完整数据
文件上传二选一：url 和 file_path 必须且只能指定一项

八、总结

Feishu Doc 是 OpenClaw 飞书扩展的文档操作基础技能，通过统一的 feishu_doc 工具提供对飞书 Docx 文档的完整 CRUD 能力——读取、写入、追加、创建、表格管理、图片/文件上传以及块级精细编辑。它既可直接用于飞书文档操作，也作为 feishu_wiki 技能的下层依赖支撑 Wiki 页面读写。该技能适用于需要在飞书生态中自动化管理文档内容的场景，是 OpenClaw 飞书集成的核心文档处理层。