feishu-doc-reader

⚠Review·Scanned 2/18/2026

This skill reads Feishu (Lark) documents via the Feishu Open API and provides CLI and Python tools to extract blocks, sheets, and text. It reads credentials from ./reference/feishu_config.json or env vars FEISHU_APP_ID/FEISHU_APP_SECRET, executes included shell/Python scripts, and calls https://open.feishu.cn API endpoints.

from clawhub.ai·v6bc79f4·54.9 KB·0 installs
Scanned from 1.1.1 at 6bc79f4 · Transparency log ↗
$ vett add clawhub.ai/snowshadow/feishu-doc-readerReview findings below

Feishu Document Reader - Blocks Extraction

This skill provides comprehensive Feishu (Lark) document reading capabilities with full blocks extraction support.

Features

  • Full blocks extraction: Get complete document structure including text, tables, images, headings, and more
  • Multiple document types: Support for Docx (new), Doc (legacy), Sheets, and Slides
  • Secure authentication: Proper token management with caching and refresh
  • Error handling: Comprehensive error messages and diagnostics
  • Easy integration: Simple command-line interface and Python API

Quick Start

1. Configuration

Create ./reference/feishu_config.json:

{
  "app_id": "your_feishu_app_id",
  "app_secret": "your_feishu_app_secret"
}

Set proper permissions:

chmod 600 ./reference/feishu_config.json

2. Usage

Get full document blocks (recommended):

# Using shell wrapper
./scripts/get_blocks.sh "docx_your_document_token"

# Using Python directly  
python scripts/get_feishu_doc_blocks.py --doc-token "docx_your_document_token" --output-format json

Get simplified text only:

python scripts/get_feishu_doc_blocks.py --doc-token "docx_your_document_token" --extract-text-only

3. Output Format

The full blocks output includes:

  • document: Document metadata (title, revision, etc.)
  • blocks: Complete block hierarchy with all content types
  • text_content: Extracted plain text (when requested)

Integration with AI Agents

This skill can be used as a standalone tool or integrated into AI agent workflows:

  1. Direct execution: Call the script from any AI agent
  2. Extension tool: Register as an extension for seamless document processing
  3. Pipeline integration: Combine with other tools for advanced document analysis

API Permissions Required

Your Feishu app needs these permissions in Open Platform:

  • docx:document:readonly (for new documents)
  • doc:document:readonly (for legacy documents)
  • sheets:spreadsheet:readonly (for spreadsheets)

Security Notes

  • Credentials are never logged or exposed in output
  • Access tokens are cached and refreshed automatically
  • File system access is restricted to prevent path traversal
  • Use minimal required permissions for your use case

Troubleshooting

Common Issues

Authentication Failed (401):

  • Verify App ID and App Secret in Feishu Open Platform
  • Ensure app is published with required permissions

Document Not Found (404):

  • Check document token format (should start with docx_, doc_, or sheet_)
  • Ensure document is shared with your app

Permission Denied (403):

  • Verify required API permissions are granted
  • Check if document requires additional sharing settings

Debugging

Enable debug logging:

DEBUG=1 python scripts/get_feishu_doc_blocks.py --doc-token "your_token"

Examples

See USAGE_EXAMPLES.md for detailed examples.

References