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

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

🌟 功能特性

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

🔑 飞书应用配置

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

第一步：创建自建应用

1. 打开 飞书开放平台 并使用管理员账号登录。
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 或更高版本

安装依赖

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

---

📖 使用指南

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 小时，过期后点击【刷新】重新获取即可。