Metadata-Version: 2.4
Name: feishu_doc_tool
Version: 0.3.0
Summary: Export Feishu/Lark cloud documents to Markdown
Project-URL: Homepage, https://gitee.com/goodtools/FeishuDocTool
Project-URL: Repository, https://gitee.com/goodtools/FeishuDocTool.git
Project-URL: Documentation, https://gitee.com/goodtools/FeishuDocTool#readme
Author: leemysw
License-Expression: MIT
License-File: LICENSE
Keywords: document,export,feishu,lark,markdown,飞书
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lark-oapi>=1.4.24
Requires-Dist: markdownify>=0.13.1
Requires-Dist: mistune>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.85.0
Requires-Dist: typer[all]>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# feishu-doc-tool

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

[![PyPI version](https://badge.fury.io/py/feishu-doc-tool.svg)](https://badge.fury.io/py/feishu-doc-tool)
[![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)

</div>

---

## 简介

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

**主要能力：**

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

---

## 安装

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

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

[uv](https://docs.astral.sh/uv/) 会自动下载所需的 Python 版本，无需关心系统环境。

```bash
# 安装 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](https://pipx.pypa.io/) 在独立虚拟环境中安装 CLI 工具，不污染系统环境。

```bash
# 安装 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 安装

```bash
pip install feishu_doc_tool
```

### 从源码安装

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

### 验证安装

```bash
feishu-doc-tool --version
```

---

## 配置

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

### 1. 创建飞书应用

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

### 2. 添加应用权限

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

**仅导出（只读）：**

```json
{
  "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` | 解析 @人员名称 |

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

```json
{
  "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. 保存凭证

```bash
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 自动缓存和刷新。

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

**切换到 Tenant 模式：**

```bash
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 命令行

#### 导出文档

```bash
# 导出单个文档
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
```

#### 写入文档

```bash
# 创建新文档
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 "新内容"
```

#### 云空间管理

```bash
# 列出文件
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
```

#### 配置与认证

```bash
# 设置凭证
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 代码中直接使用：

```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：

```python
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](LICENSE)
