feishu-cli-read

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档阅读技能

Feishu Document Reading Skill

从飞书云文档或知识库读取内容，转换为 Markdown 格式后进行分析和展示。

Read content from Feishu cloud documents or knowledge bases, convert it to Markdown format, then analyze and display it.

核心概念

Core Concepts

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

/tmp

目录中。

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

/tmp

directory.

使用方法

Usage

bash

/feishu-read <document_id>
/feishu-read <node_token>
/feishu-read <url>

bash

/feishu-read <document_id>
/feishu-read <node_token>
/feishu-read <url>

执行流程

Execution Flow

解析参数
- 判断 URL 类型：
  - ```
  /docx/
```
  → 普通文档，使用
```
  doc export
```
- ```
/wiki/
```
    → 知识库文档，使用
```
wiki export
```
- 如果是 Token，根据格式判断类型
导出为 Markdown（含图片下载）

普通文档:
bash
```
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
```
知识库文档:
bash
```
feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
```
重要：务必使用
```
--download-images
```
参数下载文档中的图片到本地。
可选参数：
- ```
--front-matter
```
  ：在 Markdown 顶部添加 YAML front matter（含标题和文档 ID）
- ```
--highlight
```
  ：保留文本颜色和背景色（输出为 HTML
```
<span>
```
  标签）
- ```
--expand-mentions
```
  ：展开 @用户为友好格式（默认开启，需要 contact:user.base:readonly 权限）
读取文本内容
- 使用 Read 工具读取导出的 Markdown 文件
- 分析文档结构和文本内容

读取并理解图片内容

检查
```
/tmp/feishu_assets
```
目录是否有下载的图片
使用 Read 工具逐个读取图片文件，理解图片内容
将图片内容整合到文档分析中

bash

# 列出下载的图片
ls /tmp/feishu_assets/

# 使用 Read 工具查看图片（Claude 支持多模态）
# Read /tmp/feishu_assets/image_1.png

报告结果
- 提供文档摘要（包含图片内容描述）
- 保留 Markdown 文件和图片供用户进一步操作

Parse parameters
- Judge URL type:
  - ```
  /docx/
```
  → Regular document, use
```
  doc export
```
- ```
/wiki/
```
    → Knowledge base document, use
```
wiki export
```
- If it is a Token, judge the type according to the format
Export to Markdown (including image download)

Regular document:
bash
```
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
```
Knowledge base document:
bash
```
feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
```
Important: Be sure to use the
```
--download-images
```
parameter to download images in the document to local.
Optional parameters:
- ```
--front-matter
```
  : Add YAML front matter (including title and document ID) at the top of Markdown
- ```
--highlight
```
  : Retain text color and background color (output as HTML
```
<span>
```
  tags)
- ```
--expand-mentions
```
  : Expand @ users to friendly format (enabled by default, requires contact:user.base:readonly permission)
Read text content
- Use the Read tool to read the exported Markdown file
- Analyze document structure and text content
Read and understand image content
- Check if there are downloaded images in the
```
/tmp/feishu_assets
```
  directory
- Use the Read tool to read image files one by one to understand the image content
- Integrate image content into document analysis
bash
```
# List downloaded images
ls /tmp/feishu_assets/

# Use Read tool to view images (Claude supports multimodal)
# Read /tmp/feishu_assets/image_1.png
```
Report results
- Provide document summary (including image content description)
- Retain Markdown files and images for further user operations

输出格式

Output Format

向用户报告：

文档标题
文档结构概要（标题层级）
内容摘要（关键信息）
图片内容描述（如有图片）
Markdown 文件路径（供后续使用）
图片文件路径（如有下载）

Report to users:

Document title
Document structure overview (title hierarchy)
Content summary (key information)
Image content description (if there are images)
Markdown file path (for subsequent use)
Image file path (if downloaded)

支持的 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`

示例

Examples

bash

undefined

bash

undefined

读取普通文档

Read regular document

/feishu-read <document_id> /feishu-read https://xxx.feishu.cn/docx/<document_id>

读取知识库文档

Read knowledge base document

/feishu-read <node_token> /feishu-read https://xxx.feishu.cn/wiki/<node_token>

undefined

/feishu-read <node_token> /feishu-read https://xxx.feishu.cn/wiki/<node_token>

undefined

图片处理流程（重要）

Image Processing Flow (Important)

文档中的图片需要特别处理才能理解其内容：

Images in documents require special processing to understand their content:

步骤 1：导出时下载图片

Step 1: Download images when exporting

bash

undefined

bash

undefined

知识库文档

Knowledge base document

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

普通文档

Regular document

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

undefined

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

undefined

步骤 2：检查下载的图片

Step 2: Check downloaded images

bash

ls -la /tmp/doc_assets/

bash

ls -la /tmp/doc_assets/

输出示例：

Output example:

image_1.png (403KB)

image_2.png (394KB)

undefined

undefined

步骤 3：使用 Read 工具查看图片

Step 3: View images with Read tool

Claude 支持多模态，可以直接理解图片内容：

undefined

Claude supports multimodal, and can directly understand image content:

undefined

在 Claude 中使用 Read 工具读取图片

Use Read tool in Claude to read images

Read /tmp/doc_assets/image_1.png Read /tmp/doc_assets/image_2.png

undefined

Read /tmp/doc_assets/image_1.png Read /tmp/doc_assets/image_2.png

undefined

步骤 4：整合分析

Step 4: Integrate analysis

将图片内容与文档文本结合，提供完整的文档分析。

Combine image content with document text to provide complete document analysis.

完整示例

Complete Example

bash

undefined

bash

undefined

1. 导出文档和图片

1. Export document and images

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

2. 查看图片列表

2. View image list

ls /tmp/wiki_assets/

3. 读取 Markdown 内容

3. Read Markdown content

Read /tmp/wiki_doc.md

4. 读取每张图片理解内容

4. Read each image to understand content

Read /tmp/wiki_assets/image_1.png

Read /tmp/wiki_assets/image_2.png

5. 综合分析后向用户报告

5. Report to user after comprehensive analysis

undefined

undefined

目录节点识别与处理

Directory Node Identification and Processing

知识库文档可能是目录节点（包含子节点），通过以下方式识别：

Knowledge base documents may be directory nodes (containing child nodes), which are identified in the following ways:

1. 识别目录节点

1. Identify directory nodes

当导出知识库文档时，如果 Markdown 内容显示为：

markdown

[Wiki 目录 - 使用 'wiki nodes <space_id> --parent <node_token>' 获取子节点列表]

说明这是一个Wiki 目录节点（block_type=42），子文档列表存储在知识库元数据中。

When exporting a knowledge base document, if the Markdown content shows:

markdown

[Wiki Directory - Use 'wiki nodes <space_id> --parent <node_token>' to get the list of child nodes]

It means this is a Wiki directory node (block_type=42), and the sub-document list is stored in the knowledge base metadata.

2. 获取子节点列表

2. Get child node list

bash

undefined

bash

undefined

1. 先获取节点信息，记录 space_id

1. First get node information, record space_id

feishu-cli wiki get <node_token>

2. 列出该节点下的子节点

2. List child nodes under this node

feishu-cli wiki nodes <space_id> --parent <node_token>

undefined

feishu-cli wiki nodes <space_id> --parent <node_token>

undefined

3. 完整处理流程

3. Complete processing flow

bash

undefined

bash

undefined

步骤 1：尝试导出文档

Step 1: Try to export the document

feishu-cli wiki export <node_token> -o /tmp/doc.md

步骤 2：检查内容

Step 2: Check content

如果显示 "[Wiki 目录...]"，说明是目录节点

If it shows "[Wiki Directory...]", it is a directory node

步骤 3：获取节点信息

Step 3: Get node information

feishu-cli wiki get <node_token>

记录 space_id 和 has_child 字段

Record space_id and has_child fields

步骤 4：获取子节点

Step 4: Get child nodes

feishu-cli wiki nodes <space_id> --parent <node_token>

步骤 5：逐个导出子节点

Step 5: Export child nodes one by one

feishu-cli wiki export <child_node_token_1> -o /tmp/child1.md feishu-cli wiki export <child_node_token_2> -o /tmp/child2.md

undefined

feishu-cli wiki export <child_node_token_1> -o /tmp/child1.md feishu-cli wiki export <child_node_token_2> -o /tmp/child2.md

undefined

错误处理与边界情况

Error Handling and Edge Cases

1. 常见错误

1. Common Errors

错误	原因	解决
`code=131002, param err`	参数错误	检查 token 格式
`code=131001, node not found`	节点不存在	检查 token 是否正确
`code=131003, no permission`	无权限访问	确认应用有 wiki:wiki:readonly 权限
`code=131004, space not found`	知识空间不存在	检查 space_id 是否正确
空内容或 `Unknown block type`	特殊块类型	见「目录节点识别」章节

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 wiki:wiki:readonly permission
`code=131004, space not found`	Knowledge space does not exist	Check if space_id is correct
Empty content or `Unknown block type`	Special block type	See the "Directory Node Identification" section

2. 边界情况处理

2. Edge Case Handling

情况 1：文档内容为空

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

情况 2：图片下载失败

检查
```
--assets-dir
```
目录是否可写
检查网络连接
图片可能已被删除或过期

情况 3：部分块类型无法识别

飞书 API 可能返回未知的块类型
这些块会显示为
```

```
这是正常现象，不影响其他内容的读取

情况 4：大型文档

超过 1000 个块的文档可能需要分页获取
使用
```
feishu-cli doc blocks <doc_id> --all
```
自动分页

Case 1: Document content is empty

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

Case 2: Image download failed

Check if the
```
--assets-dir
```
directory is writable
Check network connection
The image may have been deleted or expired

Case 3: Some block types cannot be identified

Feishu API may return unknown block types
These blocks will be displayed as
```

```
This is normal and does not affect the reading of other content

Case 4: Large documents

Documents with more than 1000 blocks may need to be obtained in pages
Use
```
feishu-cli doc blocks <doc_id> --all
```
for automatic paging

3. 重试机制

3. Retry Mechanism

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

bash

undefined

If you encounter network errors or API rate limiting:

bash

undefined

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

Add --debug to view detailed error information

feishu-cli wiki export <token> --debug

等待几秒后重试

Retry after waiting a few seconds

sleep 5 && feishu-cli wiki export <token>

undefined

sleep 5 && feishu-cli wiki export <token>

undefined

导出格式说明

Export Format Description

导出的 Markdown 支持以下飞书特有块类型的转换：

飞书块类型	Markdown 表现
Callout 高亮块	`> [!NOTE]` 、 `> [!WARNING]` 等 6 种 GitHub-style alert
块级/行内公式	$formula$ （LaTeX 格式）
画板 (Board)	`[画板/Whiteboard](feishu://board/...)` 链接
ISV 块 (Mermaid)	画板链接
QuoteContainer	`>` 引用语法（支持嵌套）
AddOns/SyncedBlock	透明展开子块内容
Iframe	`<iframe>` HTML 标签

使用

--highlight

参数时，带颜色的文本输出为

<span style="color:...">

标签。

The exported Markdown supports conversion of the following Feishu-specific block types:

Feishu Block Type	Markdown Representation
Callout highlight block	6 types of GitHub-style alerts such as `> [!NOTE]` , `> [!WARNING]`
Block/inline formula	$formula$ (LaTeX format)
Board	`[画板/Whiteboard](feishu://board/...)` link
ISV block (Mermaid)	Board link
QuoteContainer	`>` quote syntax (supports nesting)
AddOns/SyncedBlock	Transparently expand child block content
Iframe	`<iframe>` HTML tag

When using the

--highlight

parameter, colored text is output as

<span style="color:...">

tags.

注意事项

Notes

务必下载图片：不下载图片只能看到
```
feishu://media/<token>
```
引用，无法理解图片内容
逐个读取图片：使用 Read 工具读取每张图片，Claude 会自动理解图片内容
整合分析：将图片描述与文档文本结合，提供完整的内容摘要
识别目录节点：目录节点的内容是子节点列表，不是实际文档内容
公式内容：导出的 LaTeX 公式保持原文，可直接被 Markdown 渲染器显示
Callout 类型：支持 NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS 六种高亮块类型

Be sure to download images: If you don't download images, you can only see
```
feishu://media/<token>
```
references and cannot understand the image content
Read images one by one: Use the Read tool to read each image, Claude will automatically understand the image content
Integrated analysis: Combine image descriptions with document text to provide a complete content summary
Identify directory nodes: The content of directory nodes is a list of child nodes, not actual document content
Formula content: The exported LaTeX formula remains unchanged and can be directly displayed by the Markdown renderer
Callout types: Supports six highlight block types: NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS