Feishu Document Reading Skill

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

Core Concepts

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>

Execution Flow

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

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)

Supported URL Formats

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

# 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>

Image Processing Flow (Important)

Images in documents require special processing to understand their content:

Step 1: Download images when exporting

bash

# 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

Step 2: Check downloaded images

bash

ls -la /tmp/doc_assets/
# Output example:
# image_1.png  (403KB)
# image_2.png  (394KB)

Step 3: View images with Read tool

Claude supports multimodal, and can directly understand image content:

# Use Read tool in Claude to read images
Read /tmp/doc_assets/image_1.png
Read /tmp/doc_assets/image_2.png

Step 4: Integrate analysis

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

Complete Example

bash

# 1. Export document and images
feishu-cli wiki export <node_token> \
  -o /tmp/wiki_doc.md \
  --download-images \
  --assets-dir /tmp/wiki_assets

# 2. View image list
ls /tmp/wiki_assets/

# 3. Read Markdown content
# Read /tmp/wiki_doc.md

# 4. Read each image to understand content
# Read /tmp/wiki_assets/image_1.png
# Read /tmp/wiki_assets/image_2.png

# 5. Report to user after comprehensive analysis

Directory Node Identification and Processing

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

1. Identify directory nodes

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. Get child node list

bash

# 1. First get node information, record space_id
feishu-cli wiki get <node_token>

# 2. List child nodes under this node
feishu-cli wiki nodes <space_id> --parent <node_token>

3. Complete processing flow

bash

# Step 1: Try to export the document
feishu-cli wiki export <node_token> -o /tmp/doc.md

# Step 2: Check content
# If it shows "[Wiki Directory...]", it is a directory node

# Step 3: Get node information
feishu-cli wiki get <node_token>
# Record space_id and has_child fields

# Step 4: Get child nodes
feishu-cli wiki nodes <space_id> --parent <node_token>

# 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

Error Handling and Edge Cases

1. Common Errors

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. Edge Case Handling

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. Retry Mechanism

If you encounter network errors or API rate limiting:

bash

# 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>

Export Format Description

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

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

feishu-cli-read

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Document Reading Skill

Core Concepts

Usage

Execution Flow

Output Format

Supported URL Formats

Examples

Image Processing Flow (Important)

Step 1: Download images when exporting

Step 2: Check downloaded images

Step 3: View images with Read tool

Step 4: Integrate analysis

Complete Example

Directory Node Identification and Processing

1. Identify directory nodes

2. Get child node list

3. Complete processing flow

Error Handling and Edge Cases

1. Common Errors

2. Edge Case Handling

3. Retry Mechanism

Export Format Description

Notes