feishu-doc-writer

飞书文档写入

通过 Docx API 写入内容到飞书云文档。飞书文档使用 Block 树模型，不接受原始 Markdown。

Base URL: https://open.feishu.cn/open-apis/docx/v1

认证与 Token 获取

从 feishu_skills 根目录执行共享脚本：

TOKEN="$(./scripts/get_feishu_token.sh)"

请求头统一使用 Authorization: Bearer ${TOKEN}。

如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

环境变量:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

本地缓存: ./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）

---

推荐方式：转换 API

飞书提供官方 Markdown → Blocks 转换端点：

POST /documents/{document_id}/convert

{
  "content": "# 标题\n\n正文\n\n- 列表项",
  "content_type": "markdown"
}

✅ 无需手动构建 Block JSON，支持标准 Markdown ⚠️ 不支持飞书特有块（Callout 等）— 需手动创建

---

Block 类型

block_type	名称	JSON Key	说明
1	页面	page	文档根节点
2	文本	text	段落
3-11	标题1-9	heading1-heading9	-
12	无序列表	bullet	每项单独一个 block
13	有序列表	ordered	-
14	代码块	code	需指定 style.language
15	引用	quote	-
17	待办	todo	带 style.done
19	高亮块	callout	飞书特有，容器块
22	分割线	divider	-
27	图片	image	两步：创建占位 + 上传
31	表格	table	-

---

创建 Blocks

POST /documents/{document_id}/blocks/{block_id}/children?document_revision_id=-1

{
  "children": [...],
  "index": 0
}

• block_id: 父块 ID（根节点用 document_id）
• index: 插入位置（0=开头，-1=末尾）

删除 Blocks

删除父块下指定范围的子块：

DELETE /documents/{document_id}/blocks/{block_id}/children/batch_delete?document_revision_id=-1

{
  "start_index": 3,
  "end_index": 4
}

• block_id: 要操作的父块 ID
• start_index: 起始子块下标（包含）
• end_index: 结束子块下标（不包含）
• ⚠️ 该接口是 DELETE，不是 POST

---

Block 示例

文本:

{"block_type": 2, "text": {"elements": [{"text_run": {"content": "段落"}}]}}

标题:

{"block_type": 3, "heading1": {"elements": [{"text_run": {"content": "标题"}}]}}

代码块:

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