feishu-blocks-api

name	feishu-blocks-api
description	Feishu (Lark) document Block API specification. Covers authentication, block types, document creation, content insertion, image upload, and rate limits.

Feishu Blocks API

飞书文档 Block API 规范。

认证

通过 app_id + app_secret 换取 tenant_access_token：

POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
Body: { "app_id": "<id>", "app_secret": "<secret>" }

获取的 tenant_access_token 通过 Authorization: Bearer <token> 头传递。

环境变量：FEISHU_APP_ID、FEISHU_APP_SECRET。缺失时立即中止。

核心 API

创建文档

POST /open-apis/docx/v1/documents
Body: { "folder_token": "<可选>", "title": "文档标题" }

添加 Block

POST /open-apis/docx/v1/documents/{document_id}/blocks/{block_id}/children
Body: { "children": [<block 对象数组>], "index": <可选插入位置> }

图片上传（两步）

1. 上传媒体：

   POST /open-apis/drive/v1/medias/upload_all
   表单：file_name, parent_type=docx_image, parent_node=<document_id>, size, file
   返回 file_token
   

2. 在 image block 中引用 file_token。

Block 类型速查

类型	用途
page	文档根节点
heading1 ~ heading9	标题层级
text	正文（支持内联 Markdown 元素：bold/italic/code/link）
code	代码块（指定 language）
table	表格（行列结构）
image	图片（引用 file_token）
bullet	无序列表项
ordered	有序列表项
todo	待办（带勾选框）
quote	引用块
callout	高亮块（可设置背景色、emoji）
divider	分隔线
iframe	外链嵌入

速率限制

• 文档写入：100 QPS
• 图片上传：50 QPS
• 批量写入：每次调用之间至少 100ms 延迟
• 对 429/5xx 使用指数退避：100ms → 400ms → 1600ms（最多 3 次）

多级文档结构

ultra-plan 的 feishu 输出使用「父文档 + 子文档」结构：

• 父文档：执行摘要 + 子文档链接列表
• 子文档：分别承载架构 / 详设 / 实施 / 风险

子文档通过共享 folder_token 创建于同一目录，父文档中通过 link block 引用 URL。