Skills
skills/mercury-api.wepieoa.com/feishu2md

feishu2md

SKILL.md

飞书文档转 Markdown

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

🤖 AI 执行指令

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

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

1.1 获取用户输入

  • 如果用户提供了飞书文档链接，直接使用
  • 如果用户没有提供链接，询问用户提供飞书文档链接
  • 支持的链接格式：
    • https://xxx.feishu.cn/docx/xxxx (新版文档)
    • https://xxx.feishu.cn/wiki/xxxx (知识库文档)

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 确定输出文件名

  • 默认输出文件名：output.md
  • 如果用户指定了文件名，使用用户指定的文件名
  • 建议使用文档标题作为文件名（转换成功后可以重命名）

步骤 2：执行转换

使用 Bash 工具调用 Python 脚本进行转换：

2.1 构建命令

cd /Users/liuyong/go/src/wepsy-skills/feishu2md
python3 scripts/feishu2md.py "<飞书文档链接>" [输出文件名]

2.2 环境变量处理

  • 如果环境变量已设置，直接调用脚本
  • 如果需要临时凭证，在命令前添加： 
    FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx python3 scripts/feishu2md.py ...

2.3 执行命令并监控输出

  • 脚本会输出以下信息：
    • 文档类型 (docx/wiki)
    • 文档 Token
    • 文档标题
    • 文档块数量
    • 转换进度
    • 最终结果（字符数、输出文件路径）

步骤 3：处理转换结果

3.1 转换成功

  • 读取输出的 Markdown 文件内容
  • 向用户展示转换结果摘要： 
    ✅ 转换成功！

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

Markdown 预览（前 500 字符）：
[显示前 500 字符]
  • 询问用户是否需要：
    • 查看完整内容
    • 保存到特定位置
    • 进行进一步处理（如检查文档质量）

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 的位置

使用场景

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

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

AI 执行：

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

场景 2：批量转换文档

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

AI 执行：

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

场景 3：转换并检查

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

AI 执行：

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

注意事项

环境要求

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

功能限制

  1. 图片处理：默认只记录图片 token，不下载图片
  2. 表格支持：支持普通表格和电子表格（需要额外权限）
  3. 权限要求：需要应用有文档读取权限
  4. 文档类型：支持新版文档(docx)和知识库文档(wiki)

常见问题

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

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

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 秒
Installs
1
Source
mercury-api.wepieoa.com
First Seen
Apr 13, 2026