📦
feishu-reader
Enables AI tools to extract Feishu documents (Docx/Wiki) via Feishu Open API and convert them to Markdown format with local image downloading and authentication.
0 installs
Trust: 34 — Low
Files
Ask AI about feishu-reader
Powered by Claude · Grounded in docs
I know everything about feishu-reader. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
飞书云文档提取工具 (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(点击"查看"后复制)
- App ID(如
第二步:开通所需权限
进入应用详情页 → 权限管理 → 搜索并开通以下权限:
| 权限标识 | 权限名称 | 用途说明 |
|---|---|---|
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/documentsOpenAPI),旧版文档可能存在格式偏差。 - 图片下载需要应用已开通
docs:document.media:download权限且文档已正确分享给应用机器人,否则图片将跳过下载并在日志中提示失败原因。 - 接口调用有频率限制(5 QPS / 10000次每天),大型文档请勿频繁重复提取。
- Token 默认有效期约 2 小时,过期后点击【刷新】重新获取即可。
