飞书文档导出技能

将飞书云文档或知识库文档导出为本地 Markdown 文件，或导出为 PDF/Word 等格式。

前置条件

• - 需要已配置飞书应用凭证（FEISHU_APP_ID / FEISHU_APP_SECRET），通过环境变量或 ~/.feishu-cli/config.yaml 设置
• App 权限：需要 docx:document 或 docx:document:readonly（文档导出）、wiki:wiki:readonly（知识库导出）
• User Token 权限：若 App 无权访问他人文档，需通过 feishu-cli auth login --scopes "docx:document:readonly offline_access" 授权，doc export 会自动读取保存的 User Token
• 使用 --expand-mentions 展开 @用户时，还需 contact:user.base:readonly 权限

核心概念

Markdown 作为中间格式：飞书云文档的内容通过 Markdown 格式导出到本地。选择 Markdown 作为中间格式，是因为它结构清晰、便于 Claude 理解和处理文档内容，同时也方便用户进行二次编辑或版本管理。中间文件默认存储在 /tmp 目录中。

使用方法

CODEBLOCK0

执行流程

1. 1. 解析参数

- 判断 URL 类型： - /docx/ → 普通文档 - /wiki/ → 知识库文档 - document_id：必需 - output_path：可选，默认 INLINECODE13

1. 2. 执行导出

普通文档:
CODEBLOCK1

知识库文档:
CODEBLOCK2

1. 3. 验证结果

- 读取导出的 Markdown 文件 - 显示文件大小和内容预览

参数说明

参数	说明	默认值
documentid/nodetoken	文档 ID 或知识库节点 Token	必需
output_path

输出文件路径 | /tmp/<id>.md | | --download-images | 下载文档中的图片和画板到本地（图片在飞书服务器以 token 形式存储，不下载则无法本地查看；画板自动导出为 PNG） | 否 | | --assets-dir | 图片和画板的保存目录 | ./assets | | --front-matter | 添加 YAML front matter（标题和文档 ID） | 否 | | --highlight | 保留文本颜色和背景色（输出为 HTML <span> 标签） | 否 | | --expand-mentions | 展开 @用户为友好格式（需要 contact:user.base:readonly 权限） | 是（默认开启） | | --user-access-token | User Access Token（用于访问无 App 权限的文档，未指定时自动从 auth login 读取） | 自动读取 |

支持的 URL 格式

URL 格式	类型	命令
INLINECODE18	普通文档	INLINECODE19
INLINECODE20

知识库 | wiki export | | https://xxx.larkoffice.com/docx/<id> | 普通文档 | doc export | | https://xxx.larkoffice.com/wiki/<token> | 知识库 | wiki export |

输出格式

CODEBLOCK3

示例

CODEBLOCK4

Front Matter 输出格式

使用 --front-matter 时，导出的 Markdown 文件顶部会添加：

CODEBLOCK5

高亮颜色输出格式

使用 --highlight 时，带颜色的文本会输出为 HTML <span> 标签：

CODEBLOCK6

支持的颜色：7 种字体颜色（红/橙/黄/绿/蓝/紫/灰）+ 14 种背景色（浅/深各 7 种）。

图片处理（重要）

导出文档时务必下载图片，以便后续理解图片内容：

导出并下载图片

CODEBLOCK7

查看和理解图片

CODEBLOCK8

完整流程

1. 1. 导出时添加图片参数：INLINECODE29
2. 检查图片文件：INLINECODE30
3. 读取图片内容：使用 Read 工具逐个读取图片
4. 整合分析：将图片描述与文档文本结合

错误处理与边界情况

1. 常见错误

错误	原因	解决
INLINECODE31	App Token 无权限访问该文档	通过 auth login --scopes "docx:document:readonly offline_access" 授权 User Token，doc export 会自动读取
INLINECODE34

User Token 缺少 docx:document:readonly scope | 重新执行 feishu-cli auth login --scopes "docx:document:readonly offline_access" | | code=131002, param err | 参数错误 | 检查 token 格式 | | code=131001, node not found | 节点不存在 | 检查 token 是否正确 | | code=131003, no permission | 无权限访问 | 确认应用有 docx:document 或 wiki:wiki:readonly 权限 | | code=99991672, open api request rate limit | API 限流 | 等待几秒后重试 | | write /tmp/xxx.md: permission denied | 文件权限问题 | 检查输出目录权限，更换输出路径 |

2. 边界情况处理

情况 1：目录节点导出

• - 知识库目录节点导出内容可能显示为 INLINECODE42
• 这是正常行为，表示该节点是目录而非实际文档
• 使用 wiki nodes <space_id> --parent <token> 获取子节点

情况 2：文档内容为空

• - 检查文档是否真的为空
• 检查是否有权限查看内容
• 检查是否是目录节点

情况 3：图片下载失败

• - 检查 --assets-dir 目录是否存在且可写
• 检查网络连接
• 图片可能已被删除或权限不足

情况 4：导出中断

• - 大型文档导出可能耗时较长
• 如果中断，可以重新执行命令
• 使用 --output 指定固定路径以便续传

3. 重试机制

如果遇到网络错误或 API 限流：

CODEBLOCK9

已知问题

问题	说明
表格导出	表格内单元格内容可能显示为 <!-- Unknown block type: 32 -->，这是块类型 32（表格单元格）的已知转换问题
目录节点

知识库目录节点导出内容为 [Wiki 目录...]，需单独获取子节点 |

已验证功能

以下导出功能已通过测试验证：

• - 普通文档导出 ✅
• 知识库文档导出 ✅
• 标题、段落、列表（含嵌套列表）、代码块、引用、分割线 ✅
• 任务列表（Todo）✅
• 图片下载 ✅（使用 --download-images）
• Callout 高亮块（6 种类型）✅
• 公式（块级 + 行内）✅
• Front Matter ✅（使用 --front-matter）
• 文本高亮颜色 ✅（使用 --highlight）
• ISV 块（Mermaid 绘图）✅
• AddOns/SyncedBlock 展开 ✅
• 特殊字符转义 ✅
• @用户展开 ✅（使用 --expand-mentions，默认开启）
• 新块类型（Agenda/LinkPreview/SyncBlock/WikiCatalogV2/AITemplate）✅
• 表格结构 ⚠️（内容可能丢失）
• 飞书画板 → 画板链接/PNG 图片 ✅

双向转换说明

导入（Markdown → 飞书）	导出（飞书 → Markdown）
Mermaid/PlantUML 代码块 → 飞书画板	飞书画板 → 画板链接/PNG 图片
大表格 → 自动拆分为多个表格

多个表格 → 分开的表格 | | 缩进列表 → 嵌套父子块 | 嵌套列表 → 缩进 Markdown | | > [!NOTE] → Callout 高亮块 | Callout 高亮块 → > [!NOTE] | | $formula$ → 行内公式 | 行内/块级公式 → $formula$ | | <u>下划线</u> → 下划线样式 | 下划线样式 → <u>下划线</u> |

注意：

• - Mermaid/PlantUML 图表导入后会转换为飞书画板，导出时生成的是画板链接而非原始图表代码
• 飞书"文本绘图"小组件（TextDrawing/AddOns）导出时会自动还原为 Mermaid 或 PlantUML 代码块，保留图表源码

---

异步导出为 PDF/Word/Excel（doc export-file）

将飞书云文档导出为 PDF、Word 等格式（异步三步流程）：

执行流程

CODEBLOCK10

支持的导出格式

--type	格式	说明
INLINECODE58	PDF	保留排版
INLINECODE59

Word | 可编辑 |

参数

参数	说明	默认值
INLINECODE60	文档 Token	必填
INLINECODE61

导出格式 | 必填 | | -o, --output | 输出文件路径 | 必填 | | --user-access-token | User Access Token（用于导出无 App 权限的文档） | 自动读取 |

示例

CODEBLOCK11

---

从本地文件导入为飞书云文档（doc import-file）

将本地 DOCX/XLSX 等文件导入为飞书云文档（异步流程）：

执行流程

CODEBLOCK12

支持的导入格式

--type	格式	说明
INLINECODE64	Word 文档	转换为飞书文档

参数

参数	说明	默认值
INLINECODE65	本地文件路径	必填
INLINECODE66

文件类型 | 必填 | | --name | 飞书文档名称 | 文件名 | | --folder | 目标文件夹 Token（必须提供，飞书 API 要求指定文档挂载点，不传会报 field validation failed） | — |

示例

CODEBLOCK13

---

常见问题

问题	原因	解决方法
INLINECODE70	应用未授权访问该文档	确认应用有 docx:document 或 wiki:wiki:readonly 权限，且文档对应用可见
INLINECODE73

API 请求频率超限 | 等待几秒后重试 |
| field validation failed（import-file） | 未传 --folder 参数 | 始终指定 --folder fldcnXXX |
| 导出的 Markdown 中图片显示为 token 而非内容 | 未使用 --download-images | 添加 --download-images --assets-dir <dir> 参数 |
| 表格单元格内容显示为 <!-- Unknown block type: 32 --> | 块类型 32（TableCell）的已知转换问题 | 暂无修复，手动补充内容 |
| --expand-mentions 报权限错误 | 缺少 contact:user.base:readonly 权限 | 在飞书开放平台为应用申请该权限，或使用 --expand-mentions=false 关闭 |

---

附录：Block 类型映射参考

以下是飞书文档块类型与导出 Markdown 格式的完整映射关系。

飞书块类型	导出结果	说明
标题 (Heading 1-6)	INLINECODE83
标题 (Heading 7-9)

###### 或粗体段落 | 超出 H6 时降级 |
| 段落 (Text) | 普通文本 | |
| 无序列表 (Bullet) | - item | 支持无限深度嵌套 |
| 有序列表 (Ordered) | 1. item | 保留原始编号序列 |
| 任务列表 (Todo) | - [x] / - [ ] | |
| 代码块 (Code) | `lang ` | 使用原始文本，无转义 |
| 引用 (Quote) | > text | |
| 引用容器 (QuoteContainer) | > text | 支持嵌套引用 |
| Callout 高亮块 | > [!TYPE] | 6 种类型 |
| 公式 (Equation) | $formula$ | 块级公式 |
| 行内公式 | $formula$ | 段落内嵌公式 |
| 分割线 (Divider) | --- | |
| 表格 (Table) | Markdown 表格 | 管道符自动转义 |
| 图片 (Image) | ![alt](feishu://media/<token>) 或本地路径 | 使用 --download-images 时下载到本地 |
| 链接 | [text](url) | URL 特殊字符自动编码 |
| 画板 (Board) | [画板/Whiteboard](feishu://board/...) 或 PNG 图片 | 使用 --download-images 时自动导出为 PNG |
| ISV 块 | 画板链接或 HTML 注释 | Mermaid 绘图/时间线 |
| Iframe | <iframe> HTML 标签 | 嵌入内容 |
| AddOns/TextDrawing | Mermaid/PlantUML 代码块 | 文本绘图小组件自动还原为图表源码 |
| AddOns/SyncedBlock | 展开子块内容 | 透明展开 |
| Wiki 目录 | [Wiki 目录...] | |
| Agenda/AgendaItem | 展开子块内容 | 议程块 |
| LinkPreview | 链接 | 链接预览 |
| SyncSource/SyncReference | 展开子块内容 | 同步块 |
| WikiCatalogV2 | [知识库目录 V2] | |
| AITemplate | HTML 注释 | AI 模板块 |

Callout 高亮块导出

Callout 块（飞书高亮块）导出为 GitHub-style alert 语法：

CODEBLOCK14

支持 6 种 Callout 类型（按背景色映射）：

背景色	导出类型	说明
2 (红色)	INLINECODE106	警告
3 (橙色)

[!CAUTION] | 警示 |
| 4 (黄色) | [!TIP] | 技巧 |
| 5 (绿色) | [!SUCCESS] | 成功 |
| 6 (蓝色) | [!NOTE] | 提示 |
| 7 (紫色) | [!IMPORTANT] | 重要 |

Callout 内部子块（段落、列表等）会在引用语法内逐行展示。

公式导出

• - 块级公式：独立行 INLINECODE112
• 行内公式：段落内嵌 INLINECODE113
• 公式内容保持 LaTeX 原文，不做转义

特殊字符处理

导出时自动处理以下 Markdown 特殊字符：

• - 普通文本中的 * _ [ ] # ~ $ > | 会自动添加 \ 转义
• 代码块内的文本不做转义（使用原始文本）
• 表格单元格中的 | 会转义为 INLINECODE117
• URL 中的括号 ( ) 会编码为 %28 INLINECODE121