feishu-doc-tool 0.3.0

Export Feishu/Lark cloud documents to Markdown

feishu-doc-tool

飞书云文档导出、写入与云空间管理工具
支持 Markdown 导出/导入 | 公众号文章抓取 | CLI + TUI 双界面 | OAuth 2.0 自动认证

---

简介

feishu-doc-tool 是一个命令行工具，用于将飞书/Lark 云文档导出为 Markdown，同时支持将 Markdown 写回飞书、管理云空间文件与权限。适合文档备份、知识库迁移、AI Agent 集成等场景。

主要能力：

• 将云文档、电子表格、多维表格、知识库导出为 Markdown
• 将 Markdown 内容创建/写入飞书文档（Mermaid 自动转画板）
• 抓取微信公众号文章并导出或直接导入飞书
• 管理云空间文件：列表、删除、权限设置
• 提供 CLI 命令行和 TUI 终端图形两种交互方式

---

安装

本工具需要 Python 3.11+。如果你的系统 Python 版本较低，无需手动升级，使用 uv 或 pipx 即可自动处理。

方式一：使用 uv 安装（推荐）

uv 会自动下载所需的 Python 版本，无需关心系统环境。

# 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# 安装 feishu-doc-tool（自动下载 Python 3.11+）
uv tool install feishu_doc_tool

# 或者不安装，直接运行
uvx feishu_doc_tool --help

方式二：使用 pipx 安装

pipx 在独立虚拟环境中安装 CLI 工具，不污染系统环境。

# 安装 pipx（如果还没有）
pip install pipx

# 安装 feishu-doc-tool（需要系统已有 Python 3.11+）
pipx install feishu_doc_tool

# 如果系统 Python 版本低于 3.11，指定 Python 路径
pipx install feishu_doc_tool --python /path/to/python3.11

方式三：使用 pip 安装

pip install feishu_doc_tool

从源码安装

git clone https://github.com/leemysw/feishu-doc-tool.git
cd feishu-doc-tool
pip install -e .

验证安装

feishu-doc-tool --version

---

配置

使用前需要在飞书开放平台创建应用并配置权限。

1. 创建飞书应用

1. 打开 飞书开放平台，登录后点击 创建应用 → 企业自建应用
2. 填写应用名称（如 feishu-doc-tool）和描述，完成创建
3. 进入应用详情页，记录 App ID 和 App Secret（在「凭证与基础信息」页面）
4. 如果使用 OAuth 模式，在「安全设置」中添加重定向 URL：http://127.0.0.1:9527/

2. 添加应用权限

进入应用详情页 → 权限管理 → API 权限，搜索并开通以下权限：

仅导出（只读）：

{
  "scopes": [
    "docx:document:readonly",
    "wiki:wiki:readonly",
    "drive:drive:readonly",
    "sheets:spreadsheet:readonly",
    "bitable:app:readonly",
    "board:whiteboard:node:read",
    "contact:contact.base:readonly"
  ]
}

权限	用途
docx:document:readonly	读取云文档内容
wiki:wiki:readonly	读取知识库节点
drive:drive:readonly	读取云空间文件、下载图片
sheets:spreadsheet:readonly	读取电子表格
bitable:app:readonly	读取多维表格
board:whiteboard:node:read	读取白板、导出画板为图片
contact:contact.base:readonly	解析 @人员名称

导出 + 写入 + 云空间管理（完整功能）：

{
  "scopes": [
    "docx:document",
    "docx:document.block:convert",
    "wiki:wiki",
    "drive:drive",
    "sheets:spreadsheet:readonly",
    "bitable:app:readonly",
    "board:whiteboard:node:read",
    "board:whiteboard:node:create",
    "contact:contact.base:readonly",
    "offline_access"
  ]
}

权限	用途
docx:document	读写云文档（创建、追加、更新 Block）
docx:document.block:convert	Markdown 与文档 Block 互转
wiki:wiki	读写知识库
drive:drive	云空间管理（上传图片、文件管理、权限设置）
board:whiteboard:node:create	创建白板节点（Mermaid 代码块转画板）
offline_access	离线访问，Token 自动刷新（OAuth 模式需要）

提示： docx:document 已包含 docx:document:readonly，drive:drive 已包含 drive:drive:readonly，wiki:wiki 已包含 wiki:wiki:readonly，无需重复添加。

3. 发布应用

权限添加后，需要在「版本管理与发布」中创建版本并发布，管理员审批通过后权限才会生效。

• Tenant 模式：应用发布后即可使用
• OAuth 模式：应用发布后，用户在浏览器中授权即可

4. 保存凭证

feishu-doc-tool config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET

凭证保存在 ~/.feishu-doc-tool/config.json，只需配置一次。

认证模式

工具支持两种认证模式：

	OAuth 模式（默认）	Tenant 模式
Token 类型	user_access_token	tenant_access_token
用户操作	首次使用需在浏览器中授权	自动获取，无需操作
访问范围	用户有权限的文档	应用有权限的文档
适用场景	个人使用、多用户场景	服务端自动化、AI Agent
权限配置	OAuth 授权时动态申请	在开放平台预先配置

OAuth 模式（默认）： 首次使用时会自动打开浏览器授权，Token 自动缓存和刷新。

feishu-doc-tool auth  # 首次授权（后续自动使用缓存 Token）

切换到 Tenant 模式：

feishu-doc-tool config set --auth-mode tenant

---

功能

文档导出

将飞书云文档转换为 Markdown 文件，支持以下文档类型：

类型	说明
云文档 (docx)	完整保留格式、图片、表格
电子表格 (sheet)	导出为 Markdown 表格
多维表格 (bitable)	导出为 Markdown 表格
知识库 (wiki)	自动解析节点，支持批量导出整个知识空间

支持的 Block 类型：

类别	内容	状态
基础文本	标题、正文、列表、任务列表、代码块、引用	✅
文本样式	加粗、斜体、删除线、下划线、链接、@人员	✅
布局结构	分栏、高亮块、分割线	✅
表格	原生表格（支持 Markdown/HTML 两种格式）	✅
多媒体	图片、画板（导出为图片）	✅
嵌入文档	电子表格、多维表格（仅文字内容）	✅
特殊块	同步块（仅支持同文档内原始块）	⚠️
文件	附件（文件名 + 下载链接）	✅

文档写入

将 Markdown 内容写入飞书文档：

• 创建文档 — 从 Markdown 文本或公众号 URL 创建新文档
• 追加内容 — 向已有文档末尾追加 Markdown
• 更新 Block — 更新文档中指定的 Block

Mermaid 代码块自动转换为飞书画板（支持 flowchart、sequenceDiagram、classDiagram 等，不支持的类型自动降级为代码块）。

公众号文章

• 导出微信公众号文章为 Markdown 文件
• 直接从公众号 URL 创建飞书文档

云空间管理

• 列出云空间文件
• 删除文件
• 查看/设置公开权限
• 管理权限成员（新增、更新、删除）
• 批量清空文件（双重确认）

TUI 界面

基于 Textual 的终端图形界面，提供可视化操作体验。

---

使用方式

CLI 命令行

导出文档

# 导出单个文档
feishu-doc-tool export "https://xxx.feishu.cn/docx/xxx" -o ./docs

# 导出知识库文档（自动解析 wiki 节点）
feishu-doc-tool export "https://xxx.feishu.cn/wiki/xxx" -o ./docs

# 批量导出整个知识空间（保持目录层级）
feishu-doc-tool export-wiki-space <space_id_or_url> -o ./wiki_backup --max-depth 5

# 导出公众号文章
feishu-doc-tool export-wechat "https://mp.weixin.qq.com/s/xxxxxx"

# 导出 APaaS 数据库结构
feishu-doc-tool export-workspace-schema <workspace_id> -o ./database_schema.md

# 使用临时 Token 导出
feishu-doc-tool export "URL" -t your_access_token

写入文档

# 创建新文档
feishu-doc-tool create "文档标题" -c "Markdown 内容"

# 从公众号文章创建飞书文档
feishu-doc-tool create --url "https://mp.weixin.qq.com/s/xxxxx"

# 创建包含 Mermaid 图表的文档（自动转画板）
feishu-doc-tool create "系统设计" -c $'```mermaid\nflowchart TD\nA --> B\n```'

# 向已有文档追加内容
feishu-doc-tool write "https://xxx.feishu.cn/docx/xxx" -c "追加的内容"

# 更新文档中指定 Block
feishu-doc-tool update "https://xxx.feishu.cn/docx/xxx" --block-id xxx -c "新内容"

云空间管理

# 列出文件
feishu-doc-tool drive ls --type docx

# 删除文件
feishu-doc-tool drive rm <file_token>

# 查看文档权限
feishu-doc-tool drive perm-show "https://xxx.feishu.cn/docx/xxx"

# 设置公开权限
feishu-doc-tool drive perm-set "https://xxx.feishu.cn/docx/xxx" --share-entity anyone_can_view

# 列出权限成员
feishu-doc-tool drive perm-members "https://xxx.feishu.cn/docx/xxx"

# 批量清空文件（需双重确认）
feishu-doc-tool drive clear --type docx

配置与认证

# 设置凭证
feishu-doc-tool config set --app-id xxx --app-secret xxx

# 查看当前配置
feishu-doc-tool config show

# 清除缓存
feishu-doc-tool config clear

# OAuth 授权
feishu-doc-tool auth

# 启动 TUI 界面
feishu-doc-tool tui

命令速查表

命令	说明
export <URL>	导出单个文档为 Markdown
export-wiki-space <space_id>	批量导出知识空间（保持层级）
export-workspace-schema <id>	导出 APaaS 数据库结构
export-wechat <URL>	导出公众号文章为 Markdown
create <title>	创建飞书文档（支持 --url 导入公众号）
write <URL>	向文档追加 Markdown 内容
update <URL>	更新文档中指定 Block
drive ls	列出云空间文件
drive rm <TOKEN>	删除云空间文件
drive perm-show <TOKEN>	查看公开权限
drive perm-set <TOKEN>	设置公开权限
drive perm-members <TOKEN>	列出权限成员
drive perm-add <TOKEN>	新增权限成员
drive perm-update <TOKEN>	更新权限成员
drive perm-rm <TOKEN>	删除权限成员
drive clear	批量清空文件
auth	OAuth 授权
tui	TUI 交互界面
config set	设置凭证
config show	查看配置
config clear	清除缓存

Python API

除了 CLI，也可以在 Python 代码中直接使用：

from feishu_doc_tool import FeishuExporter

# 初始化（使用 tenant_access_token，推荐）
exporter = FeishuExporter(app_id="xxx", app_secret="xxx")

# 导出单个文档
path = exporter.export("https://xxx.feishu.cn/wiki/xxx", "./output")

# 获取文档内容（不保存文件）
content = exporter.export_content("https://xxx.feishu.cn/docx/xxx")

# 批量导出整个知识空间
result = exporter.export_wiki_space(
    space_id="xxx",
    output_dir="./wiki_backup",
    max_depth=3,
)
print(f"导出 {result['exported']} 个文档到 {result['space_dir']}")

也可以手动传入 Token：

exporter = FeishuExporter.from_token("your_access_token")
content = exporter.export_content("https://xxx.feishu.cn/docx/xxx")

---

凭证优先级

工具按以下顺序查找凭证：

1. 命令行参数 --app-id、--app-secret
2. 环境变量 FEISHU_APP_ID、FEISHU_APP_SECRET
3. 配置文件 ~/.config/feishu-doc-tool/config.json

---

开源协议

MIT License - 详见 LICENSE