| 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": <可选插入位置> }
图片上传（两步）
- 上传媒体：
POST /open-apis/drive/v1/medias/upload_all
表单：file_name, parent_type=docx_image, parent_node=<document_id>, size, file
返回 file_token
- 在
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。
