feishu-blocks-api

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。