Feishu Document Reading Skill

Core Concepts

/tmp

Usage

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

Execution Flow

1. 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
2. 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)
3. Read text content
   • Use the Read tool to read the exported Markdown file
   • Analyze document structure and text content
4. 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

5. Report results
   • Provide document summary (including image content description)
   • Retain Markdown files and images for further user operations

Output Format

• 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

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

Examples

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

Step 1: Download images when exporting

# 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

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

Step 3: View images with Read tool

# 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

Complete Example

# 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

1. Identify directory nodes

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

2. Get child node list

# 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

# 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

code=131002, param err

code=131001, node not found

code=131003, no permission

code=131004, space not found

Unknown block type

2. Edge Case Handling

• 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)

• Check if the

  --assets-dir

  directory is writable
• Check network connection
• The image may have been deleted or expired

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

  <!-- Unknown block type: XX -->

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

• 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

# 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

> [!NOTE]

> [!WARNING]

$formula$

[画板/Whiteboard](feishu://board/...)

>

<iframe>

--highlight

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

Notes

1. 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
2. Read images one by one: Use the Read tool to read each image, Claude will automatically understand the image content
3. Integrated analysis: Combine image descriptions with document text to provide a complete content summary
4. Identify directory nodes: The content of directory nodes is a list of child nodes, not actual document content
5. Formula content: The exported LaTeX formula remains unchanged and can be directly displayed by the Markdown renderer
6. Callout types: Supports six highlight block types: NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS