feishu-docx

让 AI 读写你的飞书知识库 | Feishu/Lark Knowledge Base → AI Agent

中文 | English

---

🎯 What is feishu-docx?

A bidirectional bridge between Feishu/Lark and AI Agents.

Export your Feishu knowledge base to Markdown, let Claude/GPT read and analyze your documents, and write back results — all with simple commands or natural language.

✨ Core Features

Feature	What You Get
📖 Read	Export Docs/Sheets/Bitables/Wiki/Chat to Markdown
✍️ Write	Create/Update Feishu documents from Markdown
💬 Chat Export	Fetch group chat history with automatic image download
🖼️ Obsidian Integration	Auto-save messages + images to Obsidian vault
🤖 Claude Skills	Natural language control via Claude Code
🎨 Dual Interface	CLI commands + Beautiful TUI

---

⚡ 30-Second Quick Start

# One-command install (CLI + Claude Skills)
curl -fsSL https://raw.githubusercontent.com/coderhzy/feishu-docx/main/install.sh | bash

# Configure once
feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET

# Start using
feishu-docx list-chats                                    # List group chats
feishu-docx fetch-messages oc_xxx --last 50               # Fetch messages + images
feishu-docx export "https://feishu.cn/wiki/xxx"           # Export document

Need credentials? → Get Feishu App credentials (2 minutes)

---

🚀 Usage Examples

1. Fetch Group Chat Messages (with Images!)

# Fetch recent messages (images auto-download)
feishu-docx fetch-messages oc_xxx --last 50 -o chat.md

# Auto-save to Obsidian (images + relative paths handled)
feishu-docx fetch-messages oc_xxx --last 50 \
  --obsidian-vault ~/Documents/MyVault

What happens automatically:

1. ✅ Fetches all text messages
2. ✅ Downloads all images → /tmp/feishu_docx/im_images/
3. ✅ Embeds images in Markdown: ![pic](path/to/image.png)
4. ✅ (If Obsidian) Copies images to vault attachments/
5. ✅ (If Obsidian) Converts paths to relative: ../attachments/xxx.png
6. ✅ (If Obsidian) Saves note to 3-Notes/ (customizable)

2. Export Documents

# Export any Feishu content
feishu-docx export "https://xxx.feishu.cn/wiki/xxx"     # Wiki
feishu-docx export "https://xxx.feishu.cn/docx/xxx"     # Document
feishu-docx export "https://xxx.feishu.cn/sheets/xxx"   # Spreadsheet

# Output to file
feishu-docx export "https://..." -o ./docs -n my_doc

# Direct output (for AI agents)
feishu-docx export "https://..." --stdout

3. Create/Update Documents

# Create new document
feishu-docx create "Meeting Notes" -c "# Agenda\n\n- Item 1"

# From file
feishu-docx create "Weekly Report" -f ./report.md

# Append content to existing doc
feishu-docx write "https://xxx.feishu.cn/docx/xxx" -c "## New Section"

# Update specific block
feishu-docx update "https://xxx.feishu.cn/docx/xxx" -b blk_id -c "Updated text"

4. Create/Write Spreadsheets

# Create spreadsheet from Markdown table
feishu-docx create-sheet "Sales Data" -c "| Product | Quantity | Price |\n|---------|----------|-------|\n| A | 100 | 50 |"

# Write to existing sheet
feishu-docx write-sheet "https://xxx.feishu.cn/sheets/xxx" -f data.md

# Append data
feishu-docx write-sheet "https://xxx.feishu.cn/sheets/xxx" -f new_data.md --append

5. Create/Write Bitables

# Create bitable from Markdown table (auto field type inference)
feishu-docx create-bitable "Employee Database" -c "| Name | Age | Department |\n|------|-----|------------|\n| Alice | 25 | Engineering |"

# Add records to existing bitable
feishu-docx write-bitable "https://xxx.feishu.cn/base/xxx" -f new_employees.md

---

🤖 Use with Claude Code

Let Claude access your Feishu workspace with natural language!

Setup (Already Done if you used one-click install)

# The install script already installed Skills to ~/.claude/skills/
# Just configure credentials:
feishu-docx config set --app-id xxx --app-secret xxx
feishu-docx auth  # OAuth for document features

Natural Language Control

In Claude Code, simply chat:

You: "Fetch messages from our tech discussion group"
Claude: [Lists chats, you pick one, messages auto-downloaded with images]

You: "Export the product roadmap wiki page"
Claude: [Exports and shows you the Markdown content]

You: "Save these messages to my Obsidian vault"
Claude: [Auto-saves with images properly linked]

You: "Create a Feishu document summarizing this discussion"
Claude: [Generates summary and creates document]

Available Skills:

• feishu-fetch-messages - Chat message retrieval
• feishu-docx - Document export (coming soon)

---

📋 Obsidian Integration

Automatically save chat messages + images to Obsidian:

feishu-docx fetch-messages oc_xxx --last 100 \
  --obsidian-vault ~/Documents/ObsidianVault \
  --obsidian-note-dir "Daily Notes" \
  --obsidian-image-dir "assets/feishu"

Result:

ObsidianVault/
├── Daily Notes/
│   └── feishu_chat_oc_xxx_20260127.md  ← Saved note
└── assets/feishu/
    ├── img_xxx.png                      ← Images copied here
    └── img_yyy.png

Images in Markdown automatically use relative paths:

![screenshot](../assets/feishu/img_xxx.png)

---

📦 Supported Features

Document Types

Type	Read	Write	Notes
📄 Docx	✅	✅	Full formatting support
📊 Sheet	✅	✅	Create/write from Markdown tables
📋 Bitable	✅	✅	Auto field type inference
📚 Wiki	✅	✅	Auto-resolve node structure
💬 Chat	✅	❌	With automatic image download

Block Types (Document Export)

Category	Supported
Text	Headings, Paragraphs, Lists, Code Blocks, Quotes
Styling	Bold, Italic, Strikethrough, Underline, Links, @Mentions
Layout	Columns, Callouts, Dividers
Tables	✅ Export to Markdown/HTML
Media	✅ Images (auto-download), Drawing Boards (as images)
Embedded	✅ Sheets, Bitables (text content)
Files	✅ File name + download link

---

🔑 Permissions Required

For Chat Messages (Bot Token)

im:message.group_msg:readonly  - Read group messages
im:message:readonly            - Basic message access
im:chat:readonly               - Chat info access
im:resource:readonly           - Download images/files ⭐ Required for images

For Documents (OAuth User Token)

docx:document  - Read/Write documents
drive:drive    - Access cloud storage

Setup Guide: docs/PERMISSION_SETUP.md

---

📚 Documentation

• 🚀 Quick Start Guide - Complete setup walkthrough
• 🔐 Permission Setup - Step-by-step permission guide
• 🤖 Claude Code Usage - Skills integration
• 🛠️ CLI Reference - All commands explained
• ❓ Troubleshooting - Common issues & solutions

---

🔧 Advanced Usage

Custom Image Directories

# Control where images are saved
export FEISHU_IMAGE_DIR=/custom/path
feishu-docx fetch-messages oc_xxx --last 50

Batch Export

# Export multiple chats
for chat_id in oc_xxx oc_yyy oc_zzz; do
  feishu-docx fetch-messages $chat_id --last 100 \
    --obsidian-vault ~/Vault
done

Python API

from feishu_docx import FeishuDocxClient

client = FeishuDocxClient(app_id="xxx", app_secret="xxx")

# Export document
markdown = client.export_doc("https://feishu.cn/wiki/xxx")

# Fetch messages
from feishu_docx.core.im_client import FeishuIMClient
im_client = FeishuIMClient(bot_token)
messages = im_client.get_chat_messages("oc_xxx", max_messages=50)

---

🤝 Who Uses This?

Perfect for:

• 🤖 AI Agent developers integrating Feishu knowledge
• 📝 Teams generating meeting notes from chat
• 🧠 Knowledge base managers exporting to Obsidian
• 🔄 Automation engineers building Feishu workflows

---

📄 License

MIT License - see LICENSE file

---

🙏 Credits

Built with ❤️ by @coderhzy and @leemysw

Star this repo if it helps you! ⭐

---

_{Made with Feishu Open API • Powered by Claude}