# feishu-docx

Adopt this skill: https://proskills.md/skills/other/leemysw-feishu-docx-skills-feishu-docx

Page: https://proskills.md/skills/other/leemysw-feishu-docx-skills-feishu-docx
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .skills/feishu-docx/SKILL.md
size: 7327
upstream: https://github.com/leemysw/feishu-docx/blob/main/.skills/feishu-docx/SKILL.md

````text
---
name: feishu-docx
description: Export, write, and manage Feishu/Lark cloud documents. Supports docx, sheets, bitable, wiki, WeChat article import/export, drive management, and browser-based export for public or browser-readable docs. Use this skill when you need to read, analyze, write, or manage content in a Feishu knowledge base.
---

# Feishu Docx Exporter

Export Feishu/Lark cloud documents to Markdown for AI analysis, writing, and automation.

## Setup (One-time)

```bash
pip install feishu-docx
feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
```

> Token auto-refreshes. No user interaction required.

Optional features are split into extras so the core install stays lightweight. Quote extras in zsh and similar shells.

### Optional: Browser-Based Export

`export-browser` requires Playwright and a Chromium runtime:

```bash
pip install 'feishu-docx[browser]'
playwright install chromium
```

### Optional: PDF Export

PDF export requires the `pdf` extra:

```bash
pip install 'feishu-docx[pdf]'
```

## Export Documents

```bash
feishu-docx export "<FEISHU_URL>" -o ./output
```

The exported Markdown file will be saved with the document's title as filename.

If the document is public or only readable in your current browser session, prefer:

```bash
feishu-docx export-browser "<FEISHU_OR_LARK_URL>" -o ./output
```

Or reuse an existing Playwright session:

```bash
feishu-docx export-browser "<FEISHU_OR_LARK_URL>" --storage-state ./storage_state.json
```

### Supported Document Types

- **docx**: Feishu cloud documents → Markdown with images
- **sheet**: Spreadsheets → Markdown tables
- **bitable**: Multidimensional tables → Markdown tables
- **wiki**: Knowledge base nodes → Auto-resolved and exported
- **public/browser-readable docs**: Browser-based export with local images and attachments

## Command Reference

| Command | Description |
|---------|-------------|
| `feishu-docx export <URL>` | Export document to Markdown |
| `feishu-docx export <URL> --pdf` | Export document to Markdown and PDF |
| `feishu-docx export-browser <URL>` | Export in a real browser session with local assets |
| `feishu-docx export-wechat <URL>` | Export WeChat article to Markdown |
| `feishu-docx create <TITLE>` | Create new document |
| `feishu-docx create --url <URL>` | Create document from WeChat article |
| `feishu-docx write <URL>` | Append content to document |
| `feishu-docx update <URL>` | Update specific block |
| `feishu-docx drive ls` | List app or personal cloud-space files |
| `feishu-docx drive perm-show <TOKEN>` | Show public permission |
| `feishu-docx drive perm-members <TOKEN>` | List permission members |
| `feishu-docx drive clear` | Clear files with double confirmation |
| `feishu-docx export-wiki-space <URL>` | Batch export entire wiki space |
| `feishu-docx export-workspace-schema <ID>` | Export bitable database schema |
| `feishu-docx auth` | OAuth authorization |
| `feishu-docx config set` | Set credentials |
| `feishu-docx config show` | Show current config |
| `feishu-docx config clear` | Clear token cache |
| `feishu-docx tui` | Interactive TUI interface |

## Examples

### Export a wiki page

```bash
feishu-docx export "https://xxx.feishu.cn/wiki/ABC123" -o ./docs
```

### Export a document with custom filename

```bash
feishu-docx export "https://xxx.feishu.cn/docx/XYZ789" -o ./docs -n meeting_notes
```

### Export a public or browser-readable doc in a real browser session

```bash
feishu-docx export-browser "https://xxx.larkoffice.com/wiki/ABC123" -o ./browser_docs
```

### Export a document as PDF

```bash
feishu-docx export "https://xxx.feishu.cn/docx/XYZ789" --pdf
```

### Read content directly (recommended for AI Agent)

```bash
# Output content to stdout instead of saving to file
feishu-docx export "https://xxx.feishu.cn/wiki/ABC123" --stdout
# or use short flag
feishu-docx export "https://xxx.feishu.cn/wiki/ABC123" -c
```

### Export with Block IDs (for later updates)

```bash
# Include block IDs as HTML comments in the Markdown output
feishu-docx export "https://xxx.feishu.cn/wiki/ABC123" --with-block-ids
# or use short flag
feishu-docx export "https://xxx.feishu.cn/wiki/ABC123" -b
```

### Batch Export Entire Wiki Space

```bash
# Export all documents in a wiki space (auto-extract space_id from URL)
feishu-docx export-wiki-space "https://xxx.feishu.cn/wiki/ABC123" -o ./wiki_backup

# Specify depth limit
feishu-docx export-wiki-space "https://xxx.feishu.cn/wiki/ABC123" -o ./docs --max-depth 3

# Export with Block IDs for later updates
feishu-docx export-wiki-space "https://xxx.feishu.cn/wiki/ABC123" -o ./docs -b
```

### Export Database Schema

```bash
# Export bitable/workspace database schema as Markdown
feishu-docx export-workspace-schema <workspace_id>

# Specify output file
feishu-docx export-workspace-schema <workspace_id> -o ./schema.md
```

## Write Documents (CLI)

### Create Document

```bash
# Create empty document
feishu-docx create "我的笔记"

# Create with Markdown content
feishu-docx create "会议记录" -c "# 会议纪要\n\n- 议题一\n- 议题二"

# Create from Markdown file
feishu-docx create "周报" -f ./weekly_report.md

# Create in specific folder
feishu-docx create "笔记" --folder fldcnXXXXXX

# Create from a WeChat article URL
feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxx"
```

**如何获取 folder token**:
1. 在浏览器中打开目标文件夹
2. 从 URL 中提取 token：`https://xxx.feishu.cn/drive/folder/fldcnXXXXXX`
3. `fldcnXXXXXX` 就是 folder token

### Append Content to Existing Document

```bash
# Append Markdown content
feishu-docx write "https://xxx.feishu.cn/docx/xxx" -c "## 新章节\n\n内容"

# Append from file
feishu-docx write "https://xxx.feishu.cn/docx/xxx" -f ./content.md
```

## Manage Drive Files

```bash
# List app cloud-space documents
feishu-docx drive ls --auth-mode tenant --type docx

# List personal cloud-space documents
feishu-docx drive ls --auth-mode oauth --type docx

# Show public permission
feishu-docx drive perm-show "https://xxx.feishu.cn/docx/ABC123"

# List permission members
feishu-docx drive perm-members "https://xxx.feishu.cn/docx/ABC123"

# Clear files with double confirmation
feishu-docx drive clear --type docx
```

### Update Specific Block

```bash
# Step 1: Export with Block IDs
feishu-docx export "https://xxx.feishu.cn/docx/xxx" -b -o ./

# Step 2: Find block ID from HTML comments
# <!-- block:blk123abc -->
# # Heading
# <!-- /block -->

# Step 3: Update the specific block
feishu-docx update "https://xxx.feishu.cn/docx/xxx" -b blk123abc -c "新内容"
```

> **Tip for AI Agents**: When you need to update a specific section:
> 1. Export with `-b` to get block IDs
> 2. Find the target block ID from HTML comments
> 3. Use `feishu-docx update` with that block ID

## Tips

- Images and attachments auto-download to `{doc_title}/` folder when local assets are available
- Prefer `export-browser` for public share links or browser-readable docs
- Use `--stdout` or `-c` for direct content output (recommended for agents)
- Use `-b` to export with block IDs for later updates
- Token auto-refreshes, no re-auth needed
- For Lark (overseas): add `--lark` flag
- `tenant_access_token` manages app cloud space, `user_access_token` manages personal cloud space
````

## File: README.md
upstream: https://github.com/leemysw/feishu-docx/blob/main/README.md

````text
<div align="center">

<img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/icon.png" alt="feishu-docx" width="128">

# feishu-docx

<p align="center">
  <em>Feishu knowledge base export, writing, and cloud-space management tool with Markdown, WeChat import, CLI, TUI, and OAuth 2.0</em><br>
</p>

[![PyPI version](https://badge.fury.io/py/feishu-docx.svg)](https://badge.fury.io/py/feishu-docx)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<p align="center">
  <a href="https://github.com/leemysw/feishu-docx/blob/main/README_zh.md">中文</a> | <strong>English</strong>
</p>

</div>

<div align="center">
<img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/tui.png" alt="feishu-docx TUI" width="90%">
</div>

---

## 🆕 Recent Updates (v0.2.8)

- PDF table line breaks and inline code combined with bold, italic, or strikethrough now render correctly, while other raw HTML remains escaped ([#37](https://github.com/leemysw/feishu-docx/issues/37))
- Card-view links retain their titles and destinations; encoded URLs are preserved correctly
- Refreshed project icon and added public-document Markdown/PDF end-to-end regression coverage

Upgrade with `pip install --upgrade "feishu-docx[pdf]"` for PDF export, or `uv tool upgrade feishu-docx` for an existing uv tool installation.

---

## 🎯 Why feishu-docx?

**Let AI Agents read, write, and manage your Feishu/Lark knowledge base.**

- 🤖 **Built for AI** — Works seamlessly with Claude/GPT Skills for document retrieval
- 📄 **Full Coverage** — Documents, Spreadsheets, Bitables, Wiki nodes, and WeChat articles
- ✍️ **Write Back Support** — Create docs, append content, and update specific blocks
- ☁️ **Cloud-Space Management** — List files, delete files, manage permissions, clear files safely
- 🔐 **Authentication** — One-time auth, automatic token refresh
- 🎨 **Dual Interface** — CLI + Beautiful TUI (Textual-based)
- 📦 **Easy Install** — `uv tool install feishu-docx` or `pip install feishu-docx`

---

## ⚡ Quick Start (30 seconds)

### Install

**Recommended: `uv tool install`** (isolated, no conflicts with system Python)

```bash
uv tool install feishu-docx
```

Optional features are installed separately to keep the core package lightweight:

```bash
# PDF export: --pdf, --pdf-template, --pdf-logo, syntax highlighting
uv tool install 'feishu-docx[pdf]'

# Browser-based export: export-browser
uv tool install 'feishu-docx[browser]'
playwright install chromium
```

Or run directly without installing:

```bash
uvx feishu-docx export "https://my.feishu.cn/wiki/xxx"
```

If you don't have `uv` yet: `curl -LsSf https://astral.sh/uv/install.sh | sh`

**Alternative: `pip install`** (works inside a virtual environment or with `--break-system-packages`)

```bash
pip install feishu-docx
```

Optional extras also work with `pip`:

```bash
pip install 'feishu-docx[pdf]'
pip install 'feishu-docx[browser]'
playwright install chromium
```

> Quote extras such as `'feishu-docx[pdf]'` in shells like zsh, otherwise the `[]` may be treated as a glob pattern.

> ⚠️ `pip install` outside a virtual environment may fail with `externally-managed-environment` on modern Linux/macOS (PEP 668). Use a virtual environment or `uv tool install` instead.

### Configure and Export

```bash
# Configure credentials (one-time)
feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET

# Export! (auto-obtains tenant_access_token, no OAuth needed)
feishu-docx export "https://my.feishu.cn/wiki/KUIJwaBuGiwaSIkkKJ6cfVY8nSg"

# Create a Feishu doc directly from a WeChat article
feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxx"

# Manage app cloud-space documents
feishu-docx drive ls --type docx

# Optional: Use OAuth mode for user-level permissions
# feishu-docx config set --auth-mode oauth && feishu-docx auth
```

---

## 🤖 Skills Support

**Enable Agent to access your Feishu knowledge base directly!**

This project includes a Claude Skill at `.skills/feishu-docx/SKILL.md`.
Supports OpenCode, Claude Code, Codex, Cursor, and more.

Copy this Skill to your agent project, and Claude can:

- 📖 Read Feishu knowledge base as context
- 🔍 Search and reference internal documents
- 📝 Create docs, append content, and update specific blocks

---

## ✨ Features

| Feature                 | Description                                     |
|-------------------------|-------------------------------------------------|
| 📄 Document Export      | Docx → Markdown with formatting, images, tables |
| 📊 Spreadsheet Export   | Sheet → Markdown tables, with rich-text cells and display/formula modes |
| 📋 Bitable Export       | Multidimensional tables → Markdown              |
| 📚 Wiki Export          | Auto-resolve wiki nodes                         |
| 🗂️ Wiki Batch Export   | Recursively export entire wiki space with hierarchy |
| ✍️ Document Writing    | Create docs, append Markdown, update specific blocks |
| 📰 WeChat Import/Export | Export WeChat articles or create Feishu docs from them |
| 🌐 Browser-Based Export | Export public docs or docs accessible in the current browser session, with local assets |
| ☁️ Drive Management    | List files, delete files, manage permissions, clear files |
| 🗄️ Database Schema     | Export APaaS database structure to Markdown     |
| 🧷 Local Asset Download | Images and attachments saved locally with relative paths |
| 🖨️ PDF Export           | Generate branded PDF with WeasyPrint, custom CSS templates |
| 🔐 Auth                 | Auto tenant_access_token (recommended) or OAuth 2.0 |
| 🎨 Beautiful TUI        | Terminal UI powered by Textual                  |

### ✅ Supported Blocks

This tool currently supports exporting the following Feishu/Lark document components:

| Category       | Features                                                       | Status | Notes                                    |
|----------------|----------------------------------------------------------------|--------|------------------------------------------|
| **Basic Text** | Headings, Paragraphs, Lists, Tasks (Todo), Code Blocks, Quotes | ✅      | Fully Supported                          |
| **Formatting** | Bold, Italic, Strikethrough, Underline, Links, @Mentions       | ✅      | Fully Supported                          |
| **Layout**     | Columns, Callouts, Dividers                                    | ✅      | Fully Supported                          |
| **Tables**     | Native Tables                                                  | ✅      | Export to Markdown/HTML                  |
| **Media**      | Images, Drawing Boards                                         | ✅      | Drawing boards exported as images        |
| **Embedded**   | Spreadsheets (Sheets), Bitable                                 | ✅      | Sheets support rich-text cells and display/formula modes |
| **Special**    | Synced Blocks, Add-ons Blocks                                  | ✅      | Synced blocks support same-document and cross-document references |
| **Files**      | Attachments                                                    | ✅      | Local download when possible, temp link fallback |

---

## 📖 Usage

### Use Cases

- Export Feishu docs, Sheets, Bitables, and Wiki nodes to Markdown
- Export a WeChat article to Markdown
- Create a Feishu doc directly from a WeChat article URL
- Create, append, or update Feishu document content
- Manage files and permissions in app cloud space or personal cloud space

### CLI

`export-browser` requires Playwright.

If you installed via `uv tool install`, install the browser extra:

```bash
uv tool install 'feishu-docx[browser]'
playwright install chromium
```

If you are working inside a virtual environment:

```bash
pip install 'feishu-docx[browser]'
playwright install chromium
```

```bash
# Export single document to speci
````
