feishu-document-manage

name	feishu-document-manage
description	飞书文档管理（创建、读取、编辑、删除）。触发词：飞书文档、文档、docx、知识库、wiki、创建文档、编辑文档、写文档、读文档、文档内容、追加内容、删除块。
metadata	{"openclaw":{"emoji":"📄","requires":{"config":["channels.feishu"]}}}

飞书文档管理 Skill

概述

本 Skill 指导你使用 feishu_document 和 feishu_get_document_content 工具管理飞书文档。

• 简单读取文档内容 → 用 feishu_get_document_content（更简洁，支持 text/markdown 输出）
• 完整 CRUD（创建文档、编辑块、删除块等） → 用 feishu_document

可用操作

feishu_document

action	说明	必需参数
create	创建空文档	title，可选 folder_token
get	获取文档元数据	document_id
get_raw_content	获取文档纯文本	document_id
list_blocks	获取文档所有块	document_id，可选 format（json/text/markdown）
get_block	获取指定块	document_id + block_id
get_children	获取子块列表	document_id + block_id
create_blocks	在父块下创建子块	document_id + block_id + children，可选 index
create_nested	创建嵌套块（含子块的子块）	document_id + block_id + children，可选 index
update_block	更新块内容	document_id + block_id + update_body
batch_update	批量更新块	document_id + requests
delete_blocks	删除子块	document_id + block_id + start_index + end_index
add_permission	添加协作者权限	document_id + member_type + member_id + perm，可选 doc_type/need_notification
update_permission	更新协作者权限	document_id + member_type + member_id + perm
remove_permission	移除协作者	document_id + member_type + member_id
list_permissions	获取协作者列表	document_id
transfer_owner	转移文档所有权	document_id + owner_type + owner_id

document_id 支持传入飞书文档 URL，自动解析。

权限管理说明

member_type 可选值

值	说明
openid	用户 open_id（最常用）
userid	用户 user_id
unionid	用户 union_id
email	用户邮箱
openchat	群组 chat_id（给整个群授权）
opendepartmentid	部门 ID
groupid	自定义用户组 ID
wikispaceid	知识库 ID

perm 权限级别

值	说明
view	可阅读
edit	可编辑
full_access	可管理（含权限管理）

doc_type 文档类型

权限操作时需要指定文档类型，默认 docx。如操作其他类型，需显式传入：

值	说明
docx	新版文档（默认）
doc	旧版文档
sheet	电子表格
bitable	多维表格
folder	文件夹
file	文件
wiki	知识库节点

典型权限操作

给用户添加编辑权限：

feishu_document add_permission (
  document_id="https://xxx.feishu.cn/docx/xxxxx",
  member_type="openid",
  member_id="ou_xxx",
  perm="edit"
)

给整个群授权阅读：

feishu_document add_permission (
  document_id=xxx,
  member_type="openchat",
  member_id="oc_xxx",
  perm="view"
)

查看文档的所有协作者：

feishu_document list_permissions (document_id=xxx)

转移文档所有权：

feishu_document transfer_owner (
  document_id=xxx,
  owner_type="openid",
  owner_id="ou_xxx"
)

块类型速查

block_type 值	类型	说明
1	Page	页面（根块，自动创建，不可手动添加）
2	Text	文本
3	Heading1	一级标题
4	Heading2	二级标题
5	Heading3	三级标题
6	Heading4	四级标题
7	Heading5	五级标题
8	Heading6	六级标题
9	Heading7	七级标题
10	Heading8	八级标题
11	Heading9	九级标题
12	Bullet	无序列表
13	Ordered	有序列表
14	Code	代码块
15	Quote	引用
17	Todo	待办事项
18	Bitable	多维表格
19	Callout	高亮块
20	ChatCard	会话卡片
21	Diagram	流程图/UML
22	Divider	分割线
23	File	文件
24	Grid	分栏
25	GridColumn	分栏列
27	Image	图片
28	ISV	第三方小组件
30	Mindnote	思维笔记
31	Sheet	电子表格
32	Table	表格
33	TableCell	表格单元格
34	View	视图
35	QuoteContainer	引用容器
37	Task	任务
38	OKR	OKR
39	OkrObjective	OKR 目标
40	OkrKeyResult	OKR 关键结果
41	OkrProgress	OKR 进展
99	Undefined	未定义

TextElement 结构

文本类块（Text、Heading、Bullet、Ordered、Code、Quote、Todo）的内容都通过 elements 数组定义。每个 element 是一个 TextElement：

{
  "text_run": {
    "content": "这是文本内容",
    "text_element_style": {
      "bold": true,
      "italic": false,
      "underline": false,
      "strikethrough": false,
      "inline_code": false
    }
  }
}

也支持其他 element 类型：

• mention_user: 提及用户 { "user_id": "ou_xxx", "text_element_style": {} }
• mention_doc: 提及文档 { "token": "xxx", "obj_type": 1, "text_element_style": {} }
• equation: 公式 { "content": "E=mc^2" }

块 JSON 构造示例

文本块

{
  "block_type": 2,
  "text": {
    "elements": [
      { "text_run": { "content": "这是一段普通文本" } }
    ]
  }
}

标题块（二级标题）

{
  "block_type": 4,
  "heading2": {
    "elements": [
      { "text_run": { "content": "二级标题内容" } }
    ]
  }
}

无序列表

{
  "block_type": 12,
  "bullet": {
    "elements": [
      { "text_run": { "content": "列表项内容" } }
    ]
  }
}

有序列表

{
  "block_type": 13,
  "ordered": {
    "elements": [
      { "text_run": { "content": "有序列表项" } }
    ]
  }
}

代码块

{
  "block_type": 14,
  "code": {
    "elements": [
      { "text_run": { "content": "console.log('hello');" } }
    ],
    "style": {
      "language": 18,
      "wrap": true
    }
  }
}

常用语言编号：1=PlainText, 4=Python, 18=JavaScript, 19=TypeScript, 22=Go, 40=Java, 43=JSON, 49=Bash

待办事项

{
  "block_type": 17,
  "todo": {
    "elements": [
      { "text_run": { "content": "需要完成的事项" } }
    ],
    "style": {
      "done": false
    }
  }
}

分割线

{
  "block_type": 22,
  "divider": {}
}

表格

表格通过 create_blocks 创建，指定行列数：

{
  "block_type": 32,
  "table": {
    "property": {
      "row_size": 3,
      "column_size": 2
    }
  }
}

创建后会自动生成 TableCell 子块，通过 update_block 编辑单元格内容。

高亮块（Callout）

{
  "block_type": 19,
  "callout": {
    "background_color": 2,
    "border_color": 2,
    "emoji_id": "bulb"
  }
}

高亮块创建后，通过 create_blocks 往里面添加文本子块。

更新块的 update_body 结构

更新文本内容

{
  "update_text_elements": {
    "elements": [
      { "text_run": { "content": "新的文本内容" } }
    ]
  }
}

表格操作

插入行：

{
  "insert_table_row": {
    "row_index": 2
  }
}

插入列：

{
  "insert_table_column": {
    "column_index": 1
  }
}

删除行：

{
  "delete_table_rows": {
    "row_start_index": 1,
    "row_end_index": 2
  }
}

合并单元格：

{
  "merge_table_cells": {
    "row_start_index": 0,
    "row_end_index": 1,
    "column_start_index": 0,
    "column_end_index": 1
  }
}

分栏操作

插入分栏列：

{
  "insert_grid_column": {
    "column_index": 1
  }
}

典型场景

创建一篇带标题和正文的文档

1. feishu_document create (title="项目周报")
   → 拿到 document_id
2. feishu_document create_blocks (
     document_id=<上面的 ID>,
     block_id=<与 document_id 相同，即根块>,
     children=[
       { "block_type": 3, "heading1": { "elements": [{ "text_run": { "content": "本周进展" } }] } },
       { "block_type": 2, "text": { "elements": [{ "text_run": { "content": "完成了 xxx 功能开发..." } }] } },
       { "block_type": 22, "divider": {} },
       { "block_type": 3, "heading1": { "elements": [{ "text_run": { "content": "下周计划" } }] } },
       { "block_type": 12, "bullet": { "elements": [{ "text_run": { "content": "完成 yyy 联调" } }] } },
       { "block_type": 12, "bullet": { "elements": [{ "text_run": { "content": "启动 zzz 评审" } }] } }
     ]
   )

读取文档内容

简单读取（推荐）：

feishu_get_document_content (document="https://xxx.feishu.cn/docx/xxxxx", format="markdown")

获取块结构（需要编辑时）：

feishu_document list_blocks (document_id="https://xxx.feishu.cn/docx/xxxxx", format="json")

在文档末尾追加内容

1. feishu_document create_blocks (
     document_id=<文档 ID>,
     block_id=<与 document_id 相同>,
     children=[
       { "block_type": 2, "text": { "elements": [{ "text_run": { "content": "追加的内容" } }] } }
     ]
   )
   → 不传 index 默认追加到末尾

更新指定块的文本

1. feishu_document list_blocks (document_id=xxx, format="json")
   → 找到目标块的 block_id
2. feishu_document update_block (
     document_id=xxx,
     block_id=<目标块 ID>,
     update_body={
       "update_text_elements": {
         "elements": [{ "text_run": { "content": "替换后的文本" } }]
       }
     }
   )

删除指定范围的块

1. feishu_document get_children (document_id=xxx, block_id=<父块 ID>)
   → 查看子块列表和索引
2. feishu_document delete_blocks (
     document_id=xxx,
     block_id=<父块 ID>,
     start_index=2,
     end_index=4
   )
   → 删除索引 2 到 4 的子块

默认权限与可配置协作者

创建文档时，工具可自动授予指定用户 full_access（可管理） 权限。默认协作者列表不得写在 Skill 描述或代码明文里，应通过以下方式之一配置：

• 扩展/运行时配置：在飞书扩展的配置中设置 defaultCollaborators（或等价项），格式为 [{ "member_name": "显示名", "open_id": "ou_xxx" }]。
• 环境变量（若扩展支持）：例如 FEISHU_DOC_DEFAULT_COLLABORATORS 为 JSON 数组，避免在 Skill 或仓库中暴露 open_id。

未配置时，创建文档后需手动在飞书内添加协作者，或调用 add_permission 为指定用户授权。

铁律

• 回复要简洁：文档操作完成后，回复用户时只需给出简短描述 + 文档链接即可。例如"文档已创建：标题"或"内容已追加到文档末尾"。不要把工具返回的所有字段（文档 ID、版本号等技术细节）都发给用户，除非用户明确需要
• document_id 支持 URL：用户给了文档链接就直接传，不需要手动提取 ID
• 根块的 block_id = document_id：在文档顶层添加内容时，block_id 传 document_id
• 创建块时 block_type 必须正确：参考上方块类型速查表
• 先读后改：编辑前先用 list_blocks (format="json") 或 get_block 了解现有结构
• 简单读取用 feishu_get_document_content：不需要编辑时，用这个工具更简洁
• children 是数组：即使只创建一个块，也要包在数组里
• delete_blocks 的 start_index 和 end_index 都包含：例如 start=0, end=2 会删除索引 0、1、2 三个块
• 用户要求给文档授权就用 add_permission：不要说"需要手动设置"或"去飞书后台操作"，直接调用工具完成
• 权限操作需要 doc_type：默认是 docx，如果操作的是电子表格、知识库等其他类型文档，要传正确的 doc_type
• 工具调用失败后用户再次要求时必须重试：不要因为上次失败就拒绝尝试。用户可能已经修复了问题（如开通了权限），永远先调用工具再根据结果回复