# 飞书云文档提取工具 (Feishu Reader)

这是一个基于 Python 和 PyQt6 编写的桌面端应用程序，旨在帮助用户快速将飞书文档（Docx / Wiki）提取并转换为 Markdown 格式存储在本地。

## 🌟 功能特性

- **图形用户界面**: 提供简洁易用的 PyQt6 桌面交互界面。
- **一键提取**: 支持粘贴飞书文档/知识库链接，一键抓取并生成 `.md` 格式文件。
- **全面格式支持**: 解析支持文本、多级标题、代码块、列表、引用、表格、Mermaid 图表等常见飞书文档元素。
- **图片本地化**: 自动下载文档内的图片到本地 `assets_<doc_token>/` 目录，Markdown 中生成相对路径引用。
- **权限与认证**:
  - 在界面上直接填写飞书应用的 App ID 和 App Secret，一键获取 Access Token。
  - 支持手动填写 Token，支持勾选"记住"将凭据保存到本地。
- **本地存储**: 自动生成带有时间戳的文件名并保存至用户指定目录。

## 🔑 飞书应用配置

本工具通过飞书开放平台的**自建应用**访问文档，首次使用需完成以下配置。

### 第一步：创建自建应用

1. 打开 [飞书开放平台](https://open.feishu.cn/) 并使用管理员账号登录。
2. 进入**开发者后台** → 点击右上角**创建应用** → 选择**自建应用**。
3. 填写应用名称（如"文档提取工具"）、描述，上传图标后点击**确定创建**。
4. 进入应用详情页，在**凭证与基础信息**页签下复制：
   - **App ID**（如 `cli_xxxxxxxxxxxxxxxx`）
   - **App Secret**（点击"查看"后复制）

### 第二步：开通所需权限

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

| 权限标识 | 权限名称 | 用途说明 |
|---|---|---|
| `wiki:wiki:readonly` | 获取知识空间信息 | 访问 `/wiki/` 类型的知识库文档 |
| `docx:document:readonly` | 查看新版文档 | 读取飞书 Docx 格式文档的 Block 内容 |
| `docs:document.media:download` | 下载云文档中的图片和附件 | 将文档内图片下载到本地 |
| `docs:document.content:read` | 查看云文档内容 | 获取云文档访问范围内的文档内容 |
| `docx:document:readonly` | 查看新版文档 | 获取新版文档内容 |

> **注意**：权限开通后，进入**版本管理与发布**页签，创建并发布一个版本，权限才会正式生效。

### 第三步：将文档分享给应用

飞书文档默认仅对有权限的人员可见，需要将目标文档（或知识库）共享给应用机器人：

1. 打开目标飞书文档，点击右上角**分享**。
2. 在分享弹窗中搜索你的**应用名称**，设置权限为**可查看**。
3. 点击**确认**，应用即可访问该文档。

> 如果是知识库（Wiki）文档，需在知识库的**成员管理**中添加应用机器人并赋予查看权限。

---

## 🛠️ 安装与运行

### 环境要求

- Python 3.10 或更高版本

### 安装依赖

```bash
pip install -r requirements.txt
```

### 启动桌面应用

```bash
python main.py
```

---

## 🔌 MCP 服务器模式

支持作为 MCP 服务器运行，方便在 Claude、Cursor 等 AI 工具中直接调用。

### 配置环境变量

```bash
export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"
```

### 启动 MCP 服务器

```bash
python mcp_server.py
```

### 配置到 Claude / Cursor

在 `~/.claude.json` 或项目 MCP 配置中添加：

```json
{
  "mcpServers": {
    "feishu-reader": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      },
      "workingDirectory": "/path/to/feishu-reader-mcp"
    }
  }
}
```

---

## 📖 使用指南

1. **填写凭据**: 在界面顶部输入飞书自建应用的 **App ID** 和 **App Secret**（首次使用后会自动保存）。
2. **获取 Token**: 点击 Access Token 行右侧的【刷新】按钮，自动获取并填充 Token；也可手动粘贴已有 Token。
3. **粘贴文档链接**: 将飞书文档或知识库页面的链接粘贴到"文档 URL"输入框（支持 `/docx/`、`/doc/`、`/wiki/` 类型链接）。
4. **开始提取**: 点击【开始提取】，在弹出窗口中选择 Markdown 文件的保存目录。
5. **等待完成**: 底部日志区域会实时显示进度，完成后在目标目录中找到 `.md` 文件和 `assets_xxx/` 图片目录。

---

## 📄 项目结构

| 文件 | 说明 |
|---|---|
| `main.py` | 主程序入口，包含 PyQt6 界面定义与异步工作线程逻辑 |
| `fetcher.py` | 飞书 OpenAPI 交互层，负责拉取 Block 树、下载图片 |
| `parser.py` | Markdown 转换引擎，将飞书各类 Block 映射为 Markdown 语法 |
| `mcp_server.py` | MCP 服务器模式入口 |
| `requirements.txt` | Python 依赖列表 |

---

## 💡 注意事项

- 本工具适配飞书**新版文档格式**（基于 `/docx/v1/documents` OpenAPI），旧版文档可能存在格式偏差。
- 图片下载需要应用已开通 `docs:document.media:download` 权限且文档已正确分享给应用机器人，否则图片将跳过下载并在日志中提示失败原因。
- 接口调用有频率限制（5 QPS / 10000次每天），大型文档请勿频繁重复提取。
- Token 默认有效期约 2 小时，过期后点击【刷新】重新获取即可。