Markdown to Feishu

Description

--- 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`。 ```powershell # 初始化配置 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` 依赖安装（首次使用）： ```powershell pip install -r "${SKILL_DIR}\requirements.txt" ``` ## Usage ### Tier 1: Python 脚本（自动） ```powershell python "${SKILL_DIR}\scripts\main.py" "D:\path\to\document.md" ``` 脚本自动处理所有 Tier 1 元素，输出飞书文档链接。 ### Tier 2: Mermaid 画板（AI 辅助） **如果**脚本输出中包含 `---MERMAID_DATA_START---` 标记，则文档中有 Mermaid 流程图需要渲染为画板。 步骤： 1. 解析 `---MERMAID_DATA_START---` 和 `---MERMAID_DATA_END---` 之间的 JSON 2. JSON 格式：`{"document_id": "...", "mermaid_blocks": [{"code": "...", "fallback_block_id": "..."}]}` 3. 对每个 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`，本地图片引用可直接复用

Security Status