飞书文档转 Markdown

将飞书文档链接快速转换为 Markdown 格式，保留文档结构和样式。

🤖 AI 执行指令

当用户调用此 skill 时，请按照以下步骤执行：

步骤 1：获取文档链接和环境配置

1.1 获取用户输入

如果用户提供了飞书文档链接，直接使用
如果用户没有提供链接，询问用户提供飞书文档链接
支持的链接格式：
- https://xxx.feishu.cn/docx/xxxx (新版文档)
- https://xxx.feishu.cn/wiki/xxxx (知识库文档)
- https://xxx.feishu.cn/sheets/xxxx (飞书电子表格，多 Sheet 页各输出一个 md 文件)
- https://xxx.feishu.cn/wiki/XXX?table=tblXXX 或 https://xxx.feishu.cn/base/appXXX?table=tblXXX (多维表格 BitTable)

1.2 检查环境变量

检查是否已设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET

如果未设置，提示用户：

需要设置飞书 API 凭证才能使用此功能。

请设置以下环境变量：
export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret

或者在调用时提供：
FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx

如果用户提供了临时凭证，使用临时凭证

1.3 判断文档类型

https://xxx.feishu.cn/docx/xxx → 新版文档
https://xxx.feishu.cn/wiki/xxx（不含 table= 参数） → 知识库文档
https://xxx.feishu.cn/sheets/xxx → 飞书电子表格（多 Sheet 输出多个 Markdown 文件）
URL 中包含 table= 参数 → 多维表格 BitTable（使用专用脚本）

1.4 确定输出文件名/前缀

文档（docx/wiki）：默认输出 output.md；用户可指定文件名
电子表格（sheets）：默认以表格标题作为前缀；多个 Sheet 分别输出 前缀_Sheet名.md；只有一个 Sheet 时输出 前缀.md
多维表格（BitTable）：默认输出 bitable_output.md 或 bitable_output.csv

步骤 2：执行转换

脚本位置：/Users/zhaqianqian/cursor_files/.cursor/skills/feishu2md/scripts/

2.1 构建命令

对于普通文档（docx/wiki）：

cd /Users/zhaqianqian/cursor_files/.cursor/skills/feishu2md
python3 scripts/feishu2md.py "<飞书文档链接>" [输出文件名.md]

对于电子表格（sheets）：

cd /Users/zhaqianqian/cursor_files/.cursor/skills/feishu2md
python3 scripts/feishu2md.py "<飞书表格链接>" [输出文件名前缀]
# 脚本会自动按 Sheet 数量输出多个 .md 文件

对于多维表格（BitTable）：

cd /Users/zhaqianqian/cursor_files/.cursor/skills/feishu2md
FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx python3 scripts/feishu_bitable.py "<飞书多维表格URL>" [输出文件名] [--csv]

2.2 环境变量处理

如果环境变量已设置，直接调用脚本

如果需要临时凭证，在命令前添加：

FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx python3 scripts/feishu2md.py ...

2.3 执行命令并监控输出

脚本会输出以下信息：
- 文档类型 (docx/wiki/sheets/bitable)
- 文档/表格 Token
- 文档标题 / 表格标题及 Sheet 数量
- 转换进度
- 最终结果（输出文件路径列表）

步骤 3：处理转换结果

3.1 转换成功

读取输出的 Markdown 文件内容

向用户展示转换结果摘要：

普通文档：

✅ 转换成功！

文档标题：xxx
字符数：xxx
输出文件：xxx

Markdown 预览（前 500 字符）：
[显示前 500 字符]

电子表格（多 Sheet）：

✅ 转换成功！共转换 N 个 Sheet：
- [Sheet1名称] → xxx_Sheet1.md
- [Sheet2名称] → xxx_Sheet2.md
...

逐一读取各 Sheet 文件，展示每个文件的前 300 字符预览。

多维表格（BitTable）：

✅ 导出成功！共获取 N 条记录
输出文件：xxx.md / xxx.csv

询问用户是否需要：
- 查看某个 Sheet 的完整内容
- 保存到特定位置
- 进行进一步处理（如检查文档质量）

3.2 转换失败

识别常见错误并提供解决方案：

错误类型 1：环境变量未设置

错误：缺少必需的环境变量
解决方案：请设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET

错误类型 2：SDK 未安装

错误：请先安装飞书 SDK: pip install lark-oapi
解决方案：运行 pip install lark-oapi

错误类型 3：链接格式错误

错误：无法解析飞书 URL
解决方案：请检查链接格式，确保是完整的飞书文档链接

错误类型 4：权限不足

错误：获取文档失败: 403
解决方案：请确保应用有权限访问该文档，或者文档已设置为公开

步骤 4：后续处理（可选）

4.1 文档质量检查 如果转换的是活动需求文档，询问用户是否需要进行文档质量检查：

已转换完成。检测到这可能是一份活动需求文档。

是否需要进行文档质量检查和风险分析？
[使用 /activity-doc-checker]

4.2 文件管理

如果用户需要，可以将文件移动到指定目录
可以使用文档标题重命名文件

4.3 内容处理

如果文档内容过长，提供分段查看选项
如果包含表格，提示表格已保留格式
如果包含图片，说明图片 token 的位置

多维表格(BitTable)数据提取

支持的 BitTable URL 格式

https://wepie.feishu.cn/wiki/XXX?table=tblXXX&view=vewXXX （知识库中的多维表格）
https://wepie.feishu.cn/base/appXXX?table=tblXXX （多维表格库）

执行步骤（BitTable）

步骤 1：识别 URL 类型

检查 URL 中是否包含 table= 参数
确认需要使用多维表格提取工具

步骤 2：调用 BitTable 脚本

cd /Users/zhaqianqian/cursor_files/.cursor/skills/feishu2md
FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx python3 scripts/feishu_bitable.py "<飞书多维表格URL>" [输出文件名] [--csv]

步骤 3：输出格式选择

默认导出为 Markdown 表格（.md）
使用 --csv 参数导出为 CSV 格式（用于 Excel/数据处理）

步骤 4：数据处理

支持 Markdown 格式进一步转换或编辑
CSV 格式可在 Excel 中打开或用于数据分析
所有数据已格式化，特殊字符已转义

BitTable 数据处理说明

字段类型支持

✅ 文本字段
✅ 日期/时间字段（自动转换为日期格式）
✅ 用户字段（提取用户名）
✅ 多选/单选字段
✅ 链接字段（保留链接文本）
✅ 数字字段

数据清理

自动处理换行符和特殊字符
Markdown 格式中自动转义管道符(|)
CSV 格式中包含 BOM 以支持中文编码

分页处理

自动处理大表格分页（每页 100 条记录）
提示已获取的记录总数

领域知识

转换活动文档时，以下背景知识有助于更准确地解读内容：

区服对照表

代号	区服	代号	区服
C	华语服	K	韩服
T	泰服	A	阿语服
M	马来服	Q	土语服
P	菲律宾服	O	Jackaroo
V	越南服	G	德语服
U	美服	I	印度服
B	葡语服	N	巴基斯坦服
S	西语服	R	俄语服
Y	意大利服	J	日服

常用配置 Namespace

namespace	说明
`activity`	活动配置
`activity_config`	活动特殊配置（含礼物返金）
`blindbox_config`	盲盒配置
`gift_box`	礼盒配置
`gift_pkg`	礼包配置

使用场景

场景 1：转换活动需求文档

用户： 请将这个飞书文档转换为 Markdown：https://xxx.feishu.cn/docx/xxx

AI 执行：

检查环境变量
调用脚本转换
展示转换结果
询问是否需要进行文档质量检查

场景 2：批量转换文档

用户： 帮我转换这3个文档

AI 执行：

依次转换每个文档
为每个文档生成独立的 Markdown 文件
汇总转换结果

场景 3：转换并检查

用户： 转换这个需求文档并检查质量

AI 执行：

先使用 feishu2md 转换
再使用 activity-doc-checker 检查
输出完整的分析报告

场景 4：转换飞书电子表格

用户： 帮我把这个飞书电子表格转换成 Markdown：https://xxx.feishu.cn/sheets/xxx

AI 执行：

识别为 sheets 类型
调用脚本，自动按 Sheet 数量输出多个 .md 文件
展示各 Sheet 的内容预览
询问用户是否需要查看某个 Sheet 的完整内容

场景 5：导出多维表格数据

用户： 帮我从这个飞书表格提取数据：https://wepie.feishu.cn/wiki/XXX?table=tblXXX&view=vewXXX

AI 执行：

识别 URL 中的 table 参数，确认为 BitTable
调用 feishu_bitable.py 脚本
导出为 Markdown 或 CSV 格式
进行后续数据整理或分析

示例：

用户：读取飞书多维表格 https://wepie.feishu.cn/wiki/PGskwDckYi2kmskCQwSc7VVFnyb?table=tblMQySTmJ8AM8mF&view=vewASXkblB，
帮我整理华语服2026 Q1上线的版本和活动

AI执行：
1. 识别这是一个 BitTable URL
2. 调用 feishu_bitable.py 获取全部数据
3. 按需过滤、整理数据
4. 生成汇总报告

场景 6：多维表格导出为 CSV

用户： 把这个表格导出为 CSV，我想在 Excel 中处理

AI 执行：

识别 BitTable URL
调用脚本并指定 --csv 参数
导出为 CSV 文件
提示文件位置和记录数

注意事项

环境要求

Python 3.6+
已安装 lark-oapi SDK：pip install lark-oapi
已设置飞书 API 凭证（App ID 和 App Secret）

功能限制

图片处理：默认只记录图片 token，不下载图片
普通表格：文档内嵌表格，直接转换为 Markdown 表格格式
电子表格（sheets）：独立表格文档，每个 Sheet 页输出一个独立 md 文件；需要开通「查看、评论和编辑电子表格」权限
多维表格（BitTable）：需要独立的 feishu_bitable.py 脚本；支持 Markdown 和 CSV 两种输出格式
权限要求：需要应用有文档读取权限
文档类型：支持新版文档(docx)、知识库文档(wiki)、飞书电子表格(sheets)、多维表格(bitable)

常见问题

Q: 如何获取飞书 App ID 和 App Secret？ A:

登录飞书开放平台：https://open.feishu.cn/
创建企业自建应用
在"凭证与基础信息"中获取 App ID 和 App Secret
在"权限管理"中开通文档读取权限

Q: 转换后的图片显示为 token，如何下载图片？ A:

默认不下载图片，只记录 token
如需下载图片，可以修改脚本中的 skip_img_download 配置

Q: 表格数据无法获取？ A:

确保应用有电子表格读取权限
检查表格是否有权限访问限制

Q: 转换速度慢？ A:

大文档（1000+ 块）转换需要时间
包含多个电子表格时需要多次 API 调用

技术说明

支持的文档元素

✅ 文本（粗体、斜体、下划线、删除线、行内代码）
✅ 标题（H1-H9）
✅ 列表（无序列表、有序列表）
✅ 代码块（支持多种语言）
✅ 引用块
✅ 待办事项
✅ 表格（普通表格 + 电子表格 + 多维表格）
✅ 图片（记录 token）
✅ 公式（行内公式 + 块级公式）
✅ 高亮块（Callout）
✅ 网格布局

输出格式

标准 Markdown 格式
表格使用 GitHub Flavored Markdown 格式
代码块自动识别语言
保留文档层级结构

性能说明

小文档（< 100 块）：1-2 秒
中等文档（100-500 块）：3-10 秒
大文档（> 500 块）：10-30 秒
包含电子表格：每个表格 +2-5 秒