read-feishu-doc
starsforks
How to install read-feishu-doc?
spacezephyr/read-buddy/read-feishu-doc
$npx -y skills add SpaceZephyr/read-buddy --skill read-feishu-docRead and extract content from Feishu (Lark) documents using the official Feishu Open API
SKILL.md
| 1 | # Feishu Document Reader |
| 2 | |
| 3 | This skill enables reading and extracting content from Feishu (Lark) documents using the official Feishu Open API. |
| 4 | |
| 5 | ## Configuration |
| 6 | |
| 7 | ### Set Up the Skill |
| 8 | |
| 9 | 1. Create the configuration file at `./reference/feishu_config.json` with your Feishu app credentials: |
| 10 | |
| 11 | ```json |
| 12 | { |
| 13 | "app_id": "your_feishu_app_id_here", |
| 14 | "app_secret": "your_feishu_app_secret_here" |
| 15 | } |
| 16 | ``` |
| 17 | |
| 18 | 2. Make sure the scripts are executable: |
| 19 | ```bash |
| 20 | chmod +x scripts/read_doc.sh |
| 21 | chmod +x scripts/get_blocks.sh |
| 22 | ``` |
| 23 | |
| 24 | **Security Note**: The configuration file should be kept secure and not committed to version control. Consider using proper file permissions (`chmod 600 ./reference/feishu_config.json`). |
| 25 | |
| 26 | ## Usage |
| 27 | |
| 28 | ### Basic Document Reading |
| 29 | |
| 30 | To read a Feishu document, you need the document token (found in the URL: `https://example.feishu.cn/docx/DOC_TOKEN`). |
| 31 | |
| 32 | **Using the shell script (recommended):** |
| 33 | ```bash |
| 34 | # Make sure environment variables are set first |
| 35 | ./scripts/read_doc.sh "your_doc_token_here" |
| 36 | |
| 37 | # Or specify document type explicitly |
| 38 | ./scripts/read_doc.sh "docx_token" "doc" |
| 39 | ./scripts/read_doc.sh "sheet_token" "sheet" |
| 40 | ``` |
| 41 | |
| 42 | ### Get Detailed Document Blocks (NEW) |
| 43 | |
| 44 | For complete document structure with all blocks, use the dedicated blocks script: |
| 45 | |
| 46 | ```bash |
| 47 | # Get full document blocks structure |
| 48 | ./scripts/get_blocks.sh "docx_AbCdEfGhIjKlMnOpQrStUv" |
| 49 | |
| 50 | # Get specific block by ID |
| 51 | ./scripts/get_blocks.sh "docx_token" "block_id" |
| 52 | |
| 53 | # Get blocks with children |
| 54 | ./scripts/get_blocks.sh "docx_token" "" "true" |
| 55 | ``` |
| 56 | |
| 57 | **Using Python directly for blocks:** |
| 58 | ```bash |
| 59 | python scripts/get_feishu_doc_blocks.py --doc-token "your_doc_token_here" |
| 60 | python scripts/get_feishu_doc_blocks.py --doc-token "docx_token" --block-id "block_id" |
| 61 | python scripts/get_feishu_doc_blocks.py --doc-token "docx_token" --include-children |
| 62 | ``` |
| 63 | |
| 64 | ### Supported Document Types |
| 65 | |
| 66 | - **Docx documents** (new Feishu docs): Full content extraction with blocks, metadata, and structure |
| 67 | - **Doc documents** (legacy): Basic metadata and limited content |
| 68 | - **Sheets**: Full spreadsheet data extraction with sheet navigation |
| 69 | - **Slides**: Basic metadata (content extraction requires additional permissions) |
| 70 | |
| 71 | ## Features |
| 72 | |
| 73 | ### Enhanced Content Extraction |
| 74 | - **Structured output**: Clean JSON with document metadata, content blocks, and hierarchy |
| 75 | - **Complete blocks access**: Full access to all document blocks including text, tables, images, headings, lists, etc. |
| 76 | - **Block hierarchy**: Proper parent-child relationships between blocks |
| 77 | - **Text extraction**: Automatic text extraction from complex block structures |
| 78 | - **Table support**: Proper table parsing with row/column structure |
| 79 | - **Image handling**: Image URLs and metadata extraction |
| 80 | - **Link resolution**: Internal and external link extraction |
| 81 | |
| 82 | ### Block Types Supported |
| 83 | - **text**: Plain text and rich text content |
| 84 | - **heading1/2/3**: Document headings with proper hierarchy |
| 85 | - **bullet/ordered**: List items with nesting support |
| 86 | - **table**: Complete table structures with cells and formatting |
| 87 | - **image**: Image blocks with tokens and metadata |
| 88 | - **quote**: Block quotes |
| 89 | - **code**: Code blocks with language detection |
| 90 | - **equation**: Mathematical equations |
| 91 | - **divider**: Horizontal dividers |
| 92 | - **page**: Page breaks (in multi-page documents) |
| 93 | |
| 94 | ### Error Handling & Diagnostics |
| 95 | - **Detailed error messages**: Clear explanations for common issues |
| 96 | - **Permission validation**: Checks required permissions before making requests |
| 97 | - **Token validation**: Validates document tokens before processing |
| 98 | - **Retry logic**: Automatic retries for transient network errors |
| 99 | - **Rate limiting**: Handles API rate limits gracefully |
| 100 | |
| 101 | ### Security Features |
| 102 | - **Secure credential storage**: Supports both environment variables and secure file storage |
| 103 | - **No credential logging**: Credentials never appear in logs or output |
| 104 | - **Minimal permissions**: Uses only required API permissions |
| 105 | - **Access token caching**: Efficient token reuse to minimize API calls |
| 106 | |
| 107 | ## Command Line Options |
| 108 | |
| 109 | ### Main Document Reader |
| 110 | ```bash |
| 111 | # Python script options |
| 112 | python scripts/read_feishu_doc.py --help |
| 113 | |
| 114 | # Shell script usage |
| 115 | ./scripts/read_doc.sh <doc_token> [doc|sheet|slide] |
| 116 | ``` |
| 117 | |
| 118 | ### Blocks Reader (NEW) |
| 119 | ```bash |
| 120 | # Get full document blocks |
| 121 | ./scripts/get_blocks.sh <doc_token> |
| 122 | |
| 123 | # Get specific block |
| 124 | ./scripts/get_blocks.sh <doc_token> <block_id> |
| 125 | |
| 126 | # Include children blocks |
| 127 | ./scripts/get_blocks.sh <doc_token> "" true |
| 128 | |
| 129 | # Python options |
| 130 | python scripts/get_feishu_doc_blocks.py --help |
| 131 | ``` |
| 132 | |
| 133 | ## API Permissions Required |
| 134 | |
| 135 | Your Feishu app needs the following permissions: |
| 136 | - `docx:document:readonly` - Read document content |
| 137 | - `doc:document:readonly` - Read legacy document content |
| 138 | - `sheets:spreadsheet:readonly` - Read spreadsheet content |
| 139 | |
| 140 | ## Error Handling |
| 141 | |
| 142 | Common errors and solutions: |
| 143 | - **403 Forbidden**: Check app permissions and document sha |
People who liked this also viewed
6 picksType
- azure-aiUse for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector searSkillsJul 2026
- just-scrapeSearch, scrape, crawl, extract structured data, and monitor web pages via the ScrapeGraph AI CLI. Use when the user asks to search the web, scrape a webpage, grab content from a URL, extract JSON fromSkillsJul 2026
- firecrawlCLI and Agent Skill for Firecrawl - Add scrape, search, and browsing capabilities to your AI agentsSkillsJul 2026
- firecrawl-searchWeb search with full page content extraction. Use this skill whenever the user asks to search the web, find articles, research a topic, look something up, find recent news, discover sources, or says "SkillsJul 2026
- firecrawl-agentAI-powered autonomous data extraction that navigates complex sites and returns structured JSON. Use this skill when the user wants structured data from websites, needs to extract pricing tiers, producSkillsJul 2026
- firecrawl-mapDiscover and list all URLs on a website, with optional search filtering. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where sSkillsJul 2026
