飞书文档写入。Markdown 转 Block、创建文档块、处理并发，支持 Mermaid 绘图块。
npx skills add https://github.com/alextangson/feishu_skills --skill feishu-doc-writer이 명령을 Claude Code에 복사하여 붙여넣어 스킬을 설치하세요
| name | feishu-doc-writer |
| description | 飞书文档写入。Markdown 转 Block、创建文档块、处理并发，支持 Mermaid 绘图块。 |
通过 Docx API 写入内容到飞书云文档。飞书文档使用 Block 树模型，不接受原始 Markdown。
Base URL: https://open.feishu.cn/open-apis/docx/v1
从 feishu_skills 根目录执行共享脚本：
TOKEN="$(./scripts/get_feishu_token.sh)"
请求头统一使用 Authorization: Bearer ${TOKEN}。
如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：
TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"
环境变量:
FEISHU_APP_IDFEISHU_APP_SECRET本地缓存: ./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）
飞书提供官方 Markdown → Blocks 转换端点：
POST /documents/{document_id}/convert
{
"content": "# 标题\n\n正文\n\n- 列表项",
"content_type": "markdown"
}
✅ 无需手动构建 Block JSON，支持标准 Markdown ⚠️ 不支持飞书特有块（Callout 等）— 需手动创建
| 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 | - |
POST /documents/{document_id}/blocks/{block_id}/children?document_revision_id=-1
{
"children": [...],
"index": 0
}
block_id: 父块 ID（根节点用 document_id）index: 插入位置（0=开头，-1=末尾）删除父块下指定范围的子块：
DELETE /documents/{document_id}/blocks/{block_id}/children/batch_delete?document_revision_id=-1
{
"start_index": 3,
"end_index": 4
}
block_id: 要操作的父块 IDstart_index: 起始子块下标（包含）end_index: 结束子块下标（不包含）DELETE，不是 POST文本:
{"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')"}}]
}
}
Mermaid 绘图块（插件块）:
{
"block_type": 40,
"add_ons": {
"component_type_id": "blk_631fefbbae02400430b8f9f4",
"record": "{\"data\":\"flowchart TD\\nA-->B\",\"theme\":\"default\",\"view\":\"codeChart\"}"
}
}
block_type = 40 表示插件块component_type_id = blk_631fefbbae02400430b8f9f4 可用于 Mermaid 绘图record 是字符串化 JSON，目前验证过的字段：
data: Mermaid 源码theme: 通常用 defaultview: 通常用 codeChartcomponent_type_id/theme/view高亮块（Callout）:
{
"block_type": 19,
"callout": {
"background_color": 1,
"border_color": 1,
"emoji_id": "bulb"
},
"children": [
{"block_type": 2, "text": {"elements": [{"text_run": {"content": "提示内容"}}]}}
]
}
图片（两步）:
{"block_type": 27, "image": {}}PUT /documents/{document_id}/blocks/{block_id}/image{
"text_run": {
"content": "样式文本",
"text_element_style": {
"bold": true,
"italic": true,
"strikethrough": true,
"underline": true,
"inline_code": true,
"background_color": 1,
"text_color": 1
}
}
}
飞书文档支持多人协作，需处理并发：
GET /documents/{document_id}?document_revision_id={revision}当用户要求“按本文绘图格式统一 Mermaid”时，不要直接写普通文本块或代码块里的 ```mermaid。
推荐顺序：
block_typeadd_ons.component_type_idadd_ons.recordcode 块适用场景：
block_type = 14飞书多维表格操作。记录 CRUD、字段管理、视图、权限、公式、关联。
飞书日历。创建日程、查询日程、更新日程。
飞书审批。创建审批实例、查询审批状态。
飞书交互卡片。构建和发送带按钮/选择器的消息卡片。
飞书组织架构与 ID 转换。搜索成员、部门管理、ID 互转（OpenID/UserID/UnionID）。
飞书云空间文件管理。上传/下载/移动/搜索文件、创建文件夹。