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

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

🌟 功能特性

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

🔑 飞书应用配置

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

第一步：创建自建应用

打开飞书开放平台并使用管理员账号登录。
进入开发者后台 → 点击右上角创建应用 → 选择自建应用。
填写应用名称（如"文档提取工具"）、描述，上传图标后点击确定创建。
进入应用详情页，在凭证与基础信息页签下复制：
- 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`	查看新版文档	获取新版文档内容

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

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

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

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

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

🛠️ 安装与运行

环境要求

Python 3.10 或更高版本

安装依赖

pip install -r requirements.txt

启动桌面应用

python main.py

🔌 MCP 服务器模式

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

配置环境变量

export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"

启动 MCP 服务器

python mcp_server.py

配置到 Claude / Cursor

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

{
  "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"
    }
  }
}

📖 使用指南

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

feishu-reader