OpenClaw Feishu 插件块类型（Block Type）完全指南：文档块的识别、更新与删除边界

人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载本文基于 OpenClaw 仓库中 Feishu 插件的技能参考文档 block-types.md系统讲解飞书云文档docx的 48 种块类型、各类型的可编辑边界以及通过feishu_doc工具的list_blocks、update_block、delete_block等 action 对文档块进行精确读写的完整方法。读完本文你可以准确判断某一块能否被程序化修改、如何处理表格与图片这两类“半受限”块并掌握替换段落、定位插入、批量删除的落地模式。1. 背景飞书文档的块Block模型飞书新版云文档docx的内容不是一整段文本而是一棵块树文档根块Page之下每个段落、标题、代码块、表格、图片都是一个独立的 block通过block_id标识、parent_id和children组织父子关系。仓库中对块的数据结构定义见 docx-types.tsexport type FeishuDocxBlock { block_id?: string; parent_id?: string; children?: string[] | string; block_type: number; // 块类型编号本文的核心 text?: FeishuBlockText; // 文本块内容elements[].text_run.content table?: FeishuBlockTable; // 表格块属性row_size / column_size / cells image?: object; ... };理解block_type编号是编写自动化文档处理逻辑的前提先根据类型判断“能不能改”再决定用哪个 API 改。这正是参考文档存在的意义。块操作的入口是 Feishu 插件注册的feishu_doc工具。参考文档中提到的feishu_doc_list_blocks、feishu_doc_update_block、feishu_doc_delete_block对应实现中feishu_doc单工具下的同名 action见 SKILL.md 与 doc-schema.ts。doc_token从文档 URL 中提取例如https://xxx.feishu.cn/docx/ABC123def→doc_token ABC123def。2. 块类型速查表完整 48 种下表完整继承自 block-types.md是判断块可编辑性的权威参考block_type名称说明可编辑1Page文档根块含标题No2Text纯文本段落Yes3Heading1H1 标题Yes4Heading2H2 标题Yes5Heading3H3 标题Yes6Heading4H4 标题Yes7Heading5H5 标题Yes8Heading6H6 标题Yes9Heading7H7 标题Yes10Heading8H8 标题Yes11Heading9H9 标题Yes12Bullet无序列表项Yes13Ordered有序列表项Yes14Code代码块Yes15Quote引用块Yes16EquationLaTeX 公式Partial17Todo复选框 / 任务项Yes18Bitable多维表格No19Callout高亮块Yes20ChatCard聊天卡片嵌入No21Diagram图表嵌入No22Divider分割线No23File文件附件No24Grid分栏布局容器No25GridColumn分栏列No26Iframe嵌入 iframeNo27Image图片Partial28ISV第三方组件No29MindnoteBlock脑图嵌入No30Sheet电子表格嵌入No31Table表格Partial32TableCell表格单元格Yes33View视图嵌入No34Undefined未知类型No35QuoteContainer引用容器No36TaskLark Tasks 集成No37OKROKR 集成No38OKRObjectiveOKR 目标No39OKRKeyResultOKR 关键结果No40OKRProgressOKR 进展No41AddOns附加组件块No42JiraIssueJira issue 嵌入No43WikiCatalog知识库目录No44Board看板嵌入No45Agenda议程块No46AgendaItem议程项No47AgendaItemTitle议程项标题No48SyncedBlock同步块引用No按“可编辑”维度可以把它分成三档完全可编辑文本类2–17、19即文本、各级标题、列表、代码、引用、任务项、高亮块可用update_block直接改写文字部分可编辑Partial16公式、27图片、31表格——能读、能换但“改”的方式受限第 4 节展开只读No18、20–26、28–30、33–48绝大多数是嵌入对象或容器程序化流程只能读list_blocks或删除不能原地改。实现侧也维护了一份常用类型的名称映射见 docx.ts#L51-L70 的BLOCK_TYPE_NAMES1 Page、2 Text、3–5 标题、12/13 列表、14 Code、15 Quote、17 Todo、18 Bitable、27 Image、30 Sheet、31 Table、32 TableCell 等用于readaction 输出的block_types统计与告警信息。3. 读块list_blocks与结构化内容提示修改块之前必须先定位block_id。readaction 返回纯文本内容外加块统计当文档中存在纯文本覆盖不到的结构化块时会给出hint提示改用list_blocks——判定标准见 docx.ts#L836const STRUCTURED_BLOCK_TYPES new Set([14, 18, 21, 23, 27, 30, 31, 32]);即代码14、多维表格18、图表21、文件23、图片27、电子表格30、表格31/32命中时read响应中会出现This document contains ... which are NOT included in the plain text above. Use feishu_doc with action: list_blocks to get full content.list_blocks的调用与返回{ action: list_blocks, doc_token: ABC123def }返回blocks数组即documentBlock.list接口的全部块数据含表格结构、图片信息实现见 docx.ts#L1305-L1316单块查询用get_blockdocumentBlock.get。推荐的读取工作流与 SKILL.md 一致先action: read拿纯文本 block_types统计若统计中出现 Table、Image、Code 等类型再action: list_blocks拿完整结构数据从返回结果中挑出目标块的block_id进入更新/删除流程。4. 按类型划分的编辑指南参考文档“Editing Guidelines”一节是本文核心下面逐类结合源码讲透。4.1 文本类块2–17、19update_block改文字对文本类块直接用update_block{ doc_token: ABC123, block_id: block_xxx, content: New text content }对应feishu_doc的update_blockaction参数定义见 doc-schema.ts#L62-L67。其底层调用链在 docx.ts#L1243-L1269先documentBlock.get校验块存在再调documentBlock.patch并传入data: { update_text_elements: { elements: [{ text_run: { content } }], }, }也就是说update_block的本质是把整块文本替换为新的text_run元素——它只改文字不改变块的类型与位置。这与docx-types.ts中FeishuBlockTextelements[].text_run.content的结构一一对应。若需要带颜色的文字工具另提供color_textaction支持[red]、[green]、[bold]、[bg:yellow]等标记见 doc-schema.ts#L171-L179。4.2 图片块27不能“原地改”要走上传通道参考文档明确图片块不能用update_block直接更新要换图应通过feishu_doc_write/feishu_doc_append以 markdown 方式写入新图片。从源码看图片更新实际是一条“三步走”管线uploadImageBlockdocx.ts#L704-L756先创建一个空图片块block_type: 27, image: {}——按飞书 FAQ创建块时不能直接带图片 token把图片字节上传到云空间drive.media.uploadAllparent_type: docx_image拿到file_token调documentBlock.patch的replace_image: { token }把 token 挂到块上。write/append的 markdown 流程里processImagesdocx.ts#L660-L702会提取图片 URL自动下载并按同一条“上传 replace_image”管线处理这就是在write/append中“自动上传”的实现来源。另外upload_imageaction 支持url/file_path/ base64data URI三种输入且可用parent_block_id 0 基index精确控制插入位置见 doc-schema.ts#L138-L159。SKILL.md 还提醒图片显示尺寸取决于像素尺寸小图如 480x270 的 GIF建议先放大到 800px 宽再上传。4.3 表格块31 / 32API 限制最严也是演进最多的一类参考文档给出的关键限制原文引用Important:Table blocks CANNOT be created via thedocumentBlockChildren.createAPI (error 1770029). This affectsfeishu_doc_writeandfeishu_doc_append- markdown tables will be skipped with a warning.Tables can only be read (vialist_blocks) and individual cells (type 32) can be updated, but new tables cannot be inserted programmatically via markdown.即markdown 表格在write/append时会被跳过并告警表格只能通过读 改单元格来处理。这条限制在实现中有明确落点docx.ts#L72-L98// Block types that cannot be created via documentBlockChildren.create API const UNSUPPORTED_CREATE_TYPES new Set([31, 32]); function cleanBlocksForInsert(blocks: FeishuDocxBlock[]) { const skipped: string[] []; const cleaned blocks .filter((block) { if (UNSUPPORTED_CREATE_TYPES.has(block.block_type)) { const typeName BLOCK_TYPE_NAMES[block.block_type] || type_${block.block_type}; skipped.push(typeName); // 被跳过的类型名用于 warning 输出 return false; } return true; }) ... }Convert APImarkdown → blocks产出的 Table/TableCell 块在插入前被过滤类型名进入skipped列表随结果返回这就是“被跳过并告警”的机制。值得说明的是从源码结构看当前仓库已经提供了绕过该限制的显式建表通道这是参考文档发布后实现演进的结果create_table/write_table_cells/create_table_with_values三个 action前者直接以block_type: 31调用documentBlockChildren.createdocx.ts#L1075-L1122write/append对大批量内容走insertBlocksWithDescendantDescendant API其注释明确写着 “Unlike the Children API, this supports block_type 31/32 (Table/TableCell)”docx.ts#L420-L453配套 docx-table-ops.ts 中的cleanBlocksForDescendant还会剥离merge_info等只读字段并做 CJK 感知的自适应列宽最小 50px、最大 400px、页面总宽约 730px见 docx-table-ops.ts#L15-L18。所以实操口径是“markdown 里写表格”不可靠程序化建表请用create_table/create_table_with_values对已有表格读table.cellsrow-major 顺序的单元格block_id数组见 docx-types.ts#L9-L19再对单元格type 32操作。writeTableCells的单元格写入方式是清空单元格子块 → 把新文本经 markdown 转换后作为子块插入docx.ts#L1160-L1199行列增删与合并另有insert_table_row、delete_table_rows、merge_table_cells等 actiondoc-schema.ts#L95-L136。4.4 容器块24、25、35只改子块Grid / GridColumn / QuoteContainer 是布局容器本身不可编辑正确做法是定位到其children里的内容块再改——这与块树模型一致list_blocks返回的所有块都带parent_id按父 ID 过滤即可找到容器内部的段落、文本等可编辑子块。5. 常见操作模式Common Patterns参考文档归纳了三个实战模式逐一结合实现说明。5.1 替换指定段落标准两步feishu_doc_list_blocksaction: list_blocks——在返回的块数组中按文本/位置找到目标block_idfeishu_doc_update_blockaction: update_block——用新content覆盖该块文本。由于update_block不改块类型与位置该模式天然是“最小侵入”的改法适合修改文档中某一句话、某个标题。5.2 在指定位置插入内容参考文档记录的基础约束是飞书块插入 API 只支持追加到文档末尾因此对“中间位置插入”给出的替代方案是——读取现有内容 → 删除受影响的块 → 按新顺序重写。从源码结构看当前实现已经提供了更直接的路径insertactionafter_block_id参数doc-schema.ts#L34-L41。其实现insertDocdocx.ts#L1001-L1073的思路正是文档建议的“定位 按 index 插入”documentBlock.get查锚点块的parent_id对父块的子块分页遍历documentBlockChildren.get每页最多 200 条大父块需要page_token翻页找到锚点在兄弟列表中的下标以index 锚点下标 1调用 Descendant/批量插入把转换后的块树插在锚点之后。因此现在推荐流程是list_blocks找锚点 →insert带after_block_id而“读—删—重写”模式仍可作为整体重排文档内容时的兜底手段writeaction 本身即“清空 全量重写”清空逻辑见clearDocumentContentdocx.ts#L455-L479。5.3 删除多个块参考文档的两条规则必须逐个删除先删子块再删父容器。实现层面delete_blockaction: delete_block的单块删除并不是一条“按 ID 删除”的 API而是三步定位删除见 docx.ts#L1271-L1303documentBlock.get拿到目标块的parent_iddocumentBlockChildren.get拉取父块子块列表找到目标在其中的下标index找不到则报 “Block not found”调documentBlockChildren.batchDelete传{ start_index: index, end_index: index 1 }。“先子后父”的约束在这里体现得很具体父容器被删掉后其内部子块的parent_id就失去了锚点第 2 步将无法定位。批量清空时源码则直接使用区间删除start_index: 0, end_index: childIds.length且跳过block_type ! 1的根块本身说明删除顺序错误会导致的是“找不到索引”而非静默失败。相关 mock 与断言可参考 docx.test.ts其中对batchDelete的调用行为有覆盖。6. 工具配置与权限上述能力由 Feishu 插件的feishu_doc工具承载默认开启。配置项见 SKILL.mdchannels: feishu: tools: doc: true # default: true默认值与代码一致tools-config.ts#L8-L15 中DEFAULT_TOOLS_CONFIG.doc truechat/wiki/drive/scopes同开perm因涉敏感默认关闭。工具注册条件见 docx.ts#L1350-L1361配置存在且至少有一个启用账号时才注册feishu_doc。所需应用权限scopedocx:document、docx:document:readonly、docx:document.block:convert、drive:drive权限不足时可用独立工具feishu_app_scopestools.scopes: true列出已授权与待授权 scope 排查。7. 小结一张决策表目标首选 action关键约束读纯文本概览read结构化块14/18/21/23/27/30/31/32不在纯文本中看hint读完整结构list_blocks/get_block所有后续操作先拿block_id改文字2–17、19update_block仅替换text_run不改块类型/位置换/加图片27upload_image或write/append带不能update_block三步上传管线建表31create_table/create_table_with_valuesmarkdown 表格经write/append会被跳过1770029 限制改表格单元格32write_table_cells及行列 actioncells为 row-major ID 数组嵌入对象18/20–30/33–48只读list_blocks或删除不可原地编辑容器24/25/35编辑其children中的子块容器自身不可改中间插入insertafter_block_id锚点必须是目标父块的直接子块批量删除逐个delete_block先删子块再删父容器参考文档 block-types.md 给出了“哪些块能改”的边界SKILL.md 给出了全部 action 的调用格式而 docx.ts 让每一条边界都有源码可查——三者配合就是 OpenClaw 中处理飞书云文档块级自动化读写的完整知识底座。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐ts-morph 类型别名Type Aliases完全指南查询、添加、插入与删除ts morph 类型别名Type Aliases完全指南查询、添加、插入与删除 导读 type 声明类型别名是 TypeScript 中最常见的类型开发工具Flow 不透明类型别名Opaque Type Aliases完整指南模块边界的名义类型抽象Flow 不透明类型别名Opaque Type Aliases完整指南模块边界的名义类型抽象 Opaque type aliases不透明类型别名是开发工具静态分析代码质量Whispering语音识别模型管理指南删除与更新模型的完整教程Whispering语音识别模型管理指南删除与更新模型的完整教程 Whispering是一款强大的开源语音识别工具通过快捷键即可实现语音转文本功能。这款免费上一篇OpenCV 安装完整指南5 分钟源码编译并跑通第一个图像处理程序下一篇4-bit量化革命Ludwig让AI模型在边缘设备跑起来的实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考