name: markdown-to-feishu description: 将本地 Markdown 文档上传为飞书云文档，并自动上传本地图片。用于用户提供 Markdown 文件路径，希望同步到飞书、保留基础格式和图片时。适合 Obsidian、本地知识库和由 $feishu-to-markdown 导出的 Markdown 回传场景。
Markdown to Feishu
Overview
两层架构：
| 层级 | 处理方式 | 覆盖元素 |
|---|---|---|
| Tier 1 | Python 脚本自动完成 | 标题、段落、行内样式、原生有序列表（含嵌套）、原生无序列表（含嵌套）、代码块、引用、分隔线、图片（含并排Grid布局）、Markdown 表格、HTML 表格（含单元格内嵌套列表）、任务列表 |
| Tier 2 | AI 调用 MCP 工具 | Mermaid 流程图 → 飞书画板 |
Supported Elements
- 标题: H1-H6 → 飞书标题 block（一级标题前自动插入空行分隔章节）
- 段落: 含粗体、斜体、删除线、下划线、高亮、颜色、行内代码、链接
- 有序列表: 原生 block_type 13，支持多层嵌套
- 无序列表: 原生 block_type 12，支持多层嵌套
- 任务列表:
- [x]/- [ ]→ 飞书 todo block - 代码块: 支持 40+ 语言高亮
- 引用块:
>引用 - 分隔线:
---/*** - 图片: 本地图片自动上传，支持并排 Grid 布局（
控制宽度） - Markdown 表格:
| head | head |格式，列宽自动均匀分布 - HTML 表格:
<table>标签，支持单元格内<ol>/<ul>嵌套列表、<strong>加粗、<br/>换行、<a>链接、colspan，列宽自动均匀分布 - Mermaid 流程图: 代码块 fallback + Tier 2 画板渲染
First Use
需要飞书开放平台的 App ID 和 App Secret。
# 初始化配置
python "${SKILL_DIR}\scripts\setup.py" init
# 测试连接
python "${SKILL_DIR}\scripts\setup.py" test
# 查看配置
python "${SKILL_DIR}\scripts\setup.py" show
也支持环境变量覆盖：FEISHU_APP_ID、FEISHU_APP_SECRET
依赖安装（首次使用）：
pip install -r "${SKILL_DIR}\requirements.txt"
Usage
Tier 1: Python 脚本（自动）
python "${SKILL_DIR}\scripts\main.py" "D:\path\to\document.md"
脚本自动处理所有 Tier 1 元素，输出飞书文档链接。
Tier 2: Mermaid 画板（AI 辅助）
如果脚本输出中包含 ---MERMAID_DATA_START--- 标记，则文档中有 Mermaid 流程图需要渲染为画板。
步骤：
- 解析
---MERMAID_DATA_START---和---MERMAID_DATA_END---之间的 JSON - JSON 格式：
{"document_id": "...", "mermaid_blocks": [{"code": "...", "fallback_block_id": "..."}]} - 对每个 mermaid block：
a. 调用
batch_create_feishu_blocks在文档中创建画板块（whiteboard 类型） b. 调用fill_whiteboard_with_plantuml填充 mermaid 代码（syntax_type: 2表示 Mermaid 语法） c. 成功后，可选删除 fallback 代码块（fallback_block_id） d. 如果失败，保留 fallback 代码块不动，告知用户
如果脚本输出中没有 MERMAID_DATA 标记，则无需 Tier 2 操作。
Workflow
1. 运行 Python 脚本 → 创建飞书文档 + 上传所有 Tier 1 内容
2. 检查输出是否包含 MERMAID_DATA
3. 如有 → 执行 Tier 2 MCP 操作
4. 返回飞书文档链接给用户
Image Path Rules
图片路径按 Markdown 文件所在目录解析：
images/xxx.png（同级 images 目录）文档标题.assets/xxx.png（Obsidian 样式）./assets/xxx.png（相对路径）- 绝对路径
不支持远程图片 URL。
Notes
- 飞书 API 限流：3 次/秒，脚本已内置延迟和重试
- HTML 表格
colspan通过空 cell 模拟（飞书不支持合并单元格） - 有序列表嵌套通过 descendant API 一次性创建，支持 3-4 层深度
- 如果用户的 Markdown 来自
$feishu-to-markdown，本地图片引用可直接复用