markdown-to-feishu

将本地 Markdown 文档上传为飞书云文档，并自动上传本地图片。用于用户提供 Markdown 文件路径，希望同步到飞书、保留基础格式和图片时。适合 Obsidian、本地知识库和由 $feishu-to-markdown 导出的 Markdown 回传场景。

install

source · Clone the upstream repo

git clone https://github.com/Aojianlong/markdown-to-feishu

manifest: skill.md

safety · automated scan (low risk)

This is a pattern-based risk scan, not a security review. Our crawler flagged:

pip install

Always read a skill's source content before installing. Patterns alone don't mean the skill is malicious — but they warrant attention.

source content

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 布局（
```
![w50](path)
```
控制宽度）
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
```
，本地图片引用可直接复用