feishu-cli-export

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档导出技能

Feishu Document Export Skill

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

Export Feishu cloud documents or knowledge base documents to local Markdown files, or export them to formats such as PDF/Word.

核心概念

Core Concepts

Markdown 作为中间态：本地文档与飞书云文档之间通过 Markdown 格式进行转换，中间文件默认存储在

/tmp

目录中。

Markdown as intermediate state: Conversion between local documents and Feishu cloud documents is done via Markdown format, and intermediate files are stored in the

/tmp

directory by default.

使用方法

Usage

bash

undefined

bash

undefined

导出普通文档

Export regular documents

/feishu-export <document_id> /feishu-export <document_id> ./output.md

导出知识库文档

Export knowledge base documents

/feishu-export <wiki_url>

undefined

/feishu-export <wiki_url>

undefined

执行流程

Execution Flow

解析参数
- 判断 URL 类型：
  - ```
  /docx/
```
  → 普通文档
- ```
/wiki/
```
    → 知识库文档
- document_id：必需
- output_path：可选，默认
```
/tmp/<id>.md
```

执行导出

普通文档:

bash

feishu-cli doc export <document_id> --output <output_path>

知识库文档:

bash

feishu-cli wiki export <node_token> --output <output_path>

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

Parse Parameters
- Determine URL type:
  - ```
  /docx/
```
  → Regular document
- ```
/wiki/
```
    → Knowledge base document
- document_id: Required
- output_path: Optional, default
```
/tmp/<id>.md
```

Perform Export

Regular document:

bash

feishu-cli doc export <document_id> --output <output_path>

Knowledge base document:

bash

feishu-cli wiki export <node_token> --output <output_path>

Verify Result
- Read the exported Markdown file
- Display file size and content preview

参数说明

Parameter Description

参数	说明	默认值
document_id/node_token	文档 ID 或知识库节点 Token	必需
output_path	输出文件路径	`/tmp/<id>.md`
--download-images	下载文档中的图片和画板（画板自动导出为 PNG）	否
--assets-dir	图片和画板的保存目录	`./assets`
--front-matter	添加 YAML front matter（标题和文档 ID）	否
--highlight	保留文本颜色和背景色（输出为 HTML `<span>` 标签）	否
--expand-mentions	展开 @用户为友好格式（需要 contact:user.base:readonly 权限）	是（默认开启）

Parameter	Description	Default Value
document_id/node_token	Document ID or knowledge base node Token	Required
output_path	Output file path	`/tmp/<id>.md`
--download-images	Download images and whiteboards in the document (whiteboards are automatically exported as PNG)	No
--assets-dir	Storage directory for images and whiteboards	`./assets`
--front-matter	Add YAML front matter (title and document ID)	No
--highlight	Preserve text color and background color (output as HTML `<span>` tags)	No
--expand-mentions	Expand @user to friendly format (requires contact:user.base:readonly permission)	Yes (enabled by default)

支持的 URL 格式

Supported URL Formats

URL 格式	类型	命令
`https://xxx.feishu.cn/docx/<id>`	普通文档	`doc export`
`https://xxx.feishu.cn/wiki/<token>`	知识库	`wiki export`
`https://xxx.larkoffice.com/docx/<id>`	普通文档	`doc export`
`https://xxx.larkoffice.com/wiki/<token>`	知识库	`wiki export`

URL Format	Type	Command
`https://xxx.feishu.cn/docx/<id>`	Regular document	`doc export`
`https://xxx.feishu.cn/wiki/<token>`	Knowledge base	`wiki export`
`https://xxx.larkoffice.com/docx/<id>`	Regular document	`doc export`
`https://xxx.larkoffice.com/wiki/<token>`	Knowledge base	`wiki export`

输出格式

Output Format

已导出文档！
  文件路径: /path/to/output.md
  文件大小: 2.5 KB

内容预览:
---

Document exported successfully!
  File path: /path/to/output.md
  File size: 2.5 KB

Content preview:
---

文档标题

Document Title

...

undefined

...

undefined

示例

Examples

bash

undefined

bash

undefined

导出普通文档

Export regular document

/feishu-export <document_id> /feishu-export <document_id> ~/Documents/doc.md

导出知识库文档

Export knowledge base document

/feishu-export https://xxx.feishu.cn/wiki/<node_token> /feishu-export <node_token> ./wiki_doc.md

导出并下载图片

Export and download images

/feishu-export <document_id> --download-images

导出并添加 YAML front matter

Export and add YAML front matter

/feishu-export <document_id> -o doc.md --front-matter

导出并保留文本高亮颜色

Export and preserve text highlight color

/feishu-export <document_id> -o doc.md --highlight

undefined

/feishu-export <document_id> -o doc.md --highlight

undefined

Front Matter 输出格式

Front Matter Output Format

使用

--front-matter

时，导出的 Markdown 文件顶部会添加：

yaml

---
title: "文档标题"
document_id: ABC123def456
---

When using

--front-matter

, the following content will be added to the top of the exported Markdown file:

yaml

---
title: "Document Title"
document_id: ABC123def456
---

高亮颜色输出格式

Highlight Color Output Format

使用

--highlight

时，带颜色的文本会输出为 HTML

<span>

标签：

html

<span style="color: #ef4444">红色文本</span>
<span style="background-color: #eff6ff">蓝色高亮背景</span>

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

When using

--highlight

, colored text will be output as HTML

<span>

tags:

html

<span style="color: #ef4444">Red text</span>
<span style="background-color: #eff6ff">Blue highlighted background</span>

Supported colors: 7 font colors (red/orange/yellow/green/blue/purple/gray) + 14 background colors (7 light and 7 dark each).

图片处理（重要）

Image Processing (Important)

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

Be sure to download images when exporting documents for subsequent content understanding:

导出并下载图片

Export and Download Images

bash

undefined

bash

undefined

普通文档

Regular document

feishu-cli doc export <document_id>
--output /tmp/doc.md
--download-images
--assets-dir /tmp/doc_assets

知识库文档

Knowledge base document

feishu-cli wiki export <node_token>
--output /tmp/wiki.md
--download-images
--assets-dir /tmp/wiki_assets

undefined

feishu-cli wiki export <node_token>
--output /tmp/wiki.md
--download-images
--assets-dir /tmp/wiki_assets

undefined

查看和理解图片

View and Understand Images

bash

undefined

bash

undefined

查看下载的图片列表

View list of downloaded images

ls -la /tmp/doc_assets/

使用 Read 工具读取图片（Claude 支持多模态）

Read images with Read tool (Claude supports multimodal)

Read /tmp/doc_assets/image_1.png

Read /tmp/doc_assets/image_2.png

undefined

undefined

完整流程

Complete Process

导出时添加图片参数：
```
--download-images --assets-dir <dir>
```
检查图片文件：
```
ls <assets_dir>/
```
读取图片内容：使用 Read 工具逐个读取图片
整合分析：将图片描述与文档文本结合

Add image parameters when exporting:
```
--download-images --assets-dir <dir>
```
Check image files:
```
ls <assets_dir>/
```
Read image content: Read images one by one with Read tool
Integrated analysis: Combine image descriptions with document text

错误处理与边界情况

Error Handling and Edge Cases

1. 常见错误

1. Common Errors

错误	原因	解决
`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`	文件权限问题	检查输出目录权限，更换输出路径

Error	Cause	Solution
`code=131002, param err`	Parameter error	Check token format
`code=131001, node not found`	Node does not exist	Check if the token is correct
`code=131003, no permission`	No access permission	Confirm the application has docx:document or wiki:wiki:readonly permission
`code=99991672, open api request rate limit`	API rate limit	Retry after a few seconds
`write /tmp/xxx.md: permission denied`	File permission issue	Check output directory permission, change output path

2. 边界情况处理

2. Edge Case Handling

情况 1：目录节点导出

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

情况 2：文档内容为空

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

情况 3：图片下载失败

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

情况 4：导出中断

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

Case 1: Directory node export

The exported content of knowledge base directory nodes may show as
```
[Wiki Directory...]
```
This is normal behavior, indicating that the node is a directory instead of an actual document
Use
```
wiki nodes <space_id> --parent <token>
```
to get child nodes

Case 2: Empty document content

Check if the document is actually empty
Check if you have permission to view the content
Check if it is a directory node

Case 3: Image download failed

Check if the
```
--assets-dir
```
directory exists and is writable
Check network connection
The image may have been deleted or you have insufficient permissions

Case 4: Export interrupted

Large document export may take a long time
If interrupted, you can re-execute the command
Use
```
--output
```
to specify a fixed path for resumable transfer

3. 重试机制

3. Retry Mechanism

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

bash

undefined

If you encounter network errors or API rate limits:

bash

undefined

添加 --debug 查看详细错误信息

Add --debug to view detailed error information

feishu-cli doc export <doc_id> --debug

等待几秒后重试

Retry after waiting for a few seconds

sleep 5 && feishu-cli doc export <doc_id>

undefined

sleep 5 && feishu-cli doc export <doc_id>

undefined

已知问题

Known Issues

问题	说明
表格导出	表格内单元格内容可能显示为 `<!-- Unknown block type: 32 -->` ，这是块类型 32（表格单元格）的已知转换问题
目录节点	知识库目录节点导出内容为 `[Wiki 目录...]` ，需单独获取子节点

Issue	Description
Table export	Cell content in tables may show as `<!-- Unknown block type: 32 -->` , this is a known conversion issue for block type 32 (table cell)
Directory node	Exported content of knowledge base directory nodes is `[Wiki Directory...]` , need to get child nodes separately

导出块类型支持

Supported Export Block Types

飞书块类型	导出结果	说明
标题 (Heading 1-6)	`# ~ ######`
标题 (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)	`\[Image: url\]`
链接	`[text](url)`	URL 特殊字符自动编码
画板 (Board)	`[画板/Whiteboard](feishu://board/...)` 或 PNG 图片	使用 `--download-images` 时自动导出为 PNG
ISV 块	画板链接或 HTML 注释	Mermaid 绘图/时间线
Iframe	`<iframe>` HTML 标签	嵌入内容
AddOns/SyncedBlock	展开子块内容	透明展开
Wiki 目录	`[Wiki 目录...]`
Agenda/AgendaItem	展开子块内容	议程块
LinkPreview	链接	链接预览
SyncSource/SyncReference	展开子块内容	同步块
WikiCatalogV2	`[知识库目录 V2]`
AITemplate	HTML 注释	AI 模板块

Feishu Block Type	Export Result	Description
Heading (Heading 1-6)	`# ~ ######`
Heading (Heading 7-9)	`######` or bold paragraph	Degraded when exceeding H6
Paragraph (Text)	Plain text
Unordered list (Bullet)	`- item`	Supports unlimited depth nesting
Ordered list (Ordered)	`1. item`	Preserve original numbering sequence
Task list (Todo)	`- [x]` / `- [ ]`
Code block (Code)	```lang ```	Use original text, no escaping
Quote (Quote)	`> text`
Quote container (QuoteContainer)	`> text`	Supports nested quotes
Callout block	`> [!TYPE]`	6 types
Formula (Equation)	$formula$	Block-level formula
Inline formula	$formula$	Inline formula in paragraph
Divider (Divider)	`---`
Table (Table)	Markdown table	Pipe characters are automatically escaped
Image (Image)	`\[Image: url\]`
Link	`[text](url)`	URL special characters are automatically encoded
Whiteboard (Board)	`[Whiteboard](feishu://board/...)` or PNG image	Automatically exported as PNG when using `--download-images`
ISV block	Whiteboard link or HTML comment	Mermaid drawing/timeline
Iframe	`<iframe>` HTML tag	Embedded content
AddOns/SyncedBlock	Expand child block content	Transparent expansion
Wiki directory	`[Wiki Directory...]`
Agenda/AgendaItem	Expand child block content	Agenda block
LinkPreview	Link	Link preview
SyncSource/SyncReference	Expand child block content	Sync block
WikiCatalogV2	`[Knowledge Base Directory V2]`
AITemplate	HTML comment	AI template block

Callout 高亮块导出

Callout Block Export

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

markdown

> [!NOTE]
> 这是一个提示信息。

> [!WARNING]
> 这是一个警告信息。

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

背景色	导出类型	说明
2 (红色)	`[!WARNING]`	警告
3 (橙色)	`[!CAUTION]`	警示
4 (黄色)	`[!TIP]`	技巧
5 (绿色)	`[!SUCCESS]`	成功
6 (蓝色)	`[!NOTE]`	提示
7 (紫色)	`[!IMPORTANT]`	重要

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

Callout blocks (Feishu highlight blocks) are exported as GitHub-style alert syntax:

markdown

> [!NOTE]
> This is a note message.

> [!WARNING]
> This is a warning message.

Supports 6 Callout types (mapped by background color):

Background Color	Export Type	Description
2 (Red)	`[!WARNING]`	Warning
3 (Orange)	`[!CAUTION]`	Caution
4 (Yellow)	`[!TIP]`	Tip
5 (Green)	`[!SUCCESS]`	Success
6 (Blue)	`[!NOTE]`	Note
7 (Purple)	`[!IMPORTANT]`	Important

Child blocks inside Callout (paragraphs, lists, etc.) will be displayed line by line within the quote syntax.

公式导出

Formula Export

块级公式：独立行
```
$formula$
```
行内公式：段落内嵌
```
$E = mc^2$
```
公式内容保持 LaTeX 原文，不做转义

Block-level formula: Independent line
```
$formula$
```
Inline formula: Inline in paragraph
```
$E = mc^2$
```
Formula content retains original LaTeX text, no escaping

特殊字符处理

Special Character Handling

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

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

The following Markdown special characters are automatically processed during export:

```
* _ [ ] # ~ $ > |
```
in plain text will be automatically escaped with
```
\
```
Text in code blocks is not escaped (uses original text)
```
|
```
in table cells will be escaped to
```
\|
```
Parentheses
```
(
```
```
)
```
in URLs will be encoded to
```
%28
```
```
%29
```

已验证功能

Verified Features

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

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

The following export functions have passed test verification:

Regular document export ✅
Knowledge base document export ✅
Headings, paragraphs, lists (including nested lists), code blocks, quotes, dividers ✅
Task list (Todo) ✅
Image download ✅ (use
```
--download-images
```
)
Callout highlight blocks (6 types) ✅
Formulas (block-level + inline) ✅
Front Matter ✅ (use
```
--front-matter
```
)
Text highlight color ✅ (use
```
--highlight
```
)
ISV blocks (Mermaid drawing) ✅
AddOns/SyncedBlock expansion ✅
Special character escaping ✅
@User expansion ✅ (use
```
--expand-mentions
```
, enabled by default)
New block types (Agenda/LinkPreview/SyncBlock/WikiCatalogV2/AITemplate) ✅
Table structure ⚠️ (content may be lost)
Feishu whiteboard → whiteboard link/PNG image ✅

双向转换说明

Two-way Conversion Description

导入（Markdown → 飞书）	导出（飞书 → Markdown）
Mermaid/PlantUML 代码块 → 飞书画板	飞书画板 → 画板链接/PNG 图片
大表格 → 自动拆分为多个表格	多个表格 → 分开的表格
缩进列表 → 嵌套父子块	嵌套列表 → 缩进 Markdown
`> [!NOTE]` → Callout 高亮块	Callout 高亮块 → `> [!NOTE]`
$formula$ → 行内公式	行内/块级公式 → $formula$
`<u>下划线</u>` → 下划线样式	下划线样式 → `<u>下划线</u>`

注意：Mermaid/PlantUML 图表导入后会转换为飞书画板，导出时生成的是画板链接而非原始图表代码。

Import (Markdown → Feishu)	Export (Feishu → Markdown)
Mermaid/PlantUML code block → Feishu whiteboard	Feishu whiteboard → whiteboard link/PNG image
Large table → automatically split into multiple tables	Multiple tables → separate tables
Indented list → nested parent-child blocks	Nested list → indented Markdown
`> [!NOTE]` → Callout highlight block	Callout highlight block → `> [!NOTE]`
$formula$ → inline formula	Inline/block-level formula → $formula$
`<u>Underline</u>` → underline style	Underline style → `<u>Underline</u>`

Note: Mermaid/PlantUML charts will be converted to Feishu whiteboards after import, and the exported result is a whiteboard link instead of the original chart code.

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

Asynchronous Export to PDF/Word/Excel (doc export-file)

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

Export Feishu cloud documents to PDF, Word and other formats (three-step asynchronous process):

执行流程

Execution Flow

bash

undefined

bash

undefined

一条命令完成全部流程（内部自动创建任务→轮询→下载）

One command to complete the whole process (automatically create task → poll → download internally)

feishu-cli doc export-file <doc_token> --type pdf -o output.pdf

undefined

feishu-cli doc export-file <doc_token> --type pdf -o output.pdf

undefined

支持的导出格式

Supported Export Formats

--type	格式	说明
`pdf`	PDF	保留排版
`docx`	Word	可编辑

--type	Format	Description
`pdf`	PDF	Preserve typesetting
`docx`	Word	Editable

参数

Parameters

参数	说明	默认值
`<doc_token>`	文档 Token	必填
`--type`	导出格式	必填
`-o, --output`	输出文件路径	必填

Parameter	Description	Default Value
`<doc_token>`	Document Token	Required
`--type`	Export format	Required
`-o, --output`	Output file path	Required

示例

Examples

bash

undefined

bash

undefined

导出为 PDF

Export as PDF

feishu-cli doc export-file JKbxdRez1oNWEKxPz14cWMpBnKh --type pdf -o /tmp/report.pdf

导出为 Word

Export as Word

feishu-cli doc export-file JKbxdRez1oNWEKxPz14cWMpBnKh --type docx -o /tmp/report.docx

---

feishu-cli doc export-file JKbxdRez1oNWEKxPz14cWMpBnKh --type docx -o /tmp/report.docx

---

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

Import Local Files to Feishu Cloud Documents (doc import-file)

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

Import local DOCX/XLSX and other files into Feishu cloud documents (asynchronous process):

执行流程

Execution Flow

bash

undefined

bash

undefined

一条命令完成全部流程（内部自动上传→创建任务→轮询）

One command to complete the whole process (automatically upload → create task → poll internally)

feishu-cli doc import-file local_file.docx --type docx --name "文档名称"

undefined

feishu-cli doc import-file local_file.docx --type docx --name "Document Name"

undefined

支持的导入格式

Supported Import Formats

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

--type	Format	Description
`docx`	Word document	Convert to Feishu document

参数

Parameters

参数	说明	默认值
`<local_path>`	本地文件路径	必填
`--type`	文件类型	必填
`--name`	飞书文档名称	文件名

Parameter	Description	Default Value
`<local_path>`	Local file path	Required
`--type`	File type	Required
`--name`	Feishu document name	File name

示例

Examples

bash

undefined

bash

undefined

导入 Word 文档

Import Word document

feishu-cli doc import-file ~/Documents/report.docx --type docx --name "季度报告"

undefined

feishu-cli doc import-file ~/Documents/report.docx --type docx --name "Quarterly Report"

undefined