mcpField
M
md-to-feishu

md-to-feishu

github.com/zc277584121文档处理03.8k 次安装9 周前更新
代码仓库

关于 md-to-feishu

将本地 Markdown 文件转换为飞书文档的技能，适合需要发布文档的用户。它可从首个标题确定文档标题，并在上传前将 Mermaid 图表转换为图片。

主要功能

  1. 01从首个一级标题提取标题
  2. 02自动上传图片
  3. 03上传前将 Mermaid 图表转为图片
  4. 04优先使用 uvx 或已安装的 feishu-docx

适用场景

  1. 01将 Markdown 笔记发布为飞书文档
  2. 02把含 Mermaid 图表的 Markdown 转为飞书文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/zc277584121/marketing-skills --skill md-to-feishu

安装后在 Claude Code 中输入/md-to-feishu确认已加载。

详细介绍

Markdown 转飞书文档

将本地 Markdown 文件转换为飞书文档，并自动上传图片。

用户输入

用户只需提供 Markdown 文件路径。标题为可选项——如果未提供，则自动提取（见下文）。

第 1 步：确定文档标题

  1. 读取 Markdown 文件，查找第一个 # heading，并将其用作标题。
  2. 如果不存在 # heading，则扫描内容，根据主题生成简洁、明确的标题。
  3. 如果用户明确提供了标题，则使用该标题。

第 2 步：检查运行环境

按顺序尝试每个选项，使用第一个可用的选项。

选项 A：uvx（首选）
which uvx

如果 uvx 可用，运行命令为：

uvx feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

如果 uvx 使用的 Python 版本低于 3.11，则添加 --python 3.11：

uvx --python 3.11 feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>
选项 B：已安装 feishu-docx
which feishu-docx

如果已找到，则检查 Python 版本：

python3 --version

如果 Python 版本 >= 3.11，运行命令为：

feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>
选项 C：都不可用——安装指引

如果找不到 uvx 或 feishu-docx，请告知用户：

feishu-docx 需要 Python >= 3.11。可通过以下任一方式安装：

# 推荐：安装 uv，然后直接运行，无需全局安装
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx feishu-docx create "Title" -f file.md

# 或：通过 pip 全局安装（需要 Python >= 3.11）
pip install feishu-docx

必须先配置飞书凭证：

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>

然后停止并等待用户配置好环境。

第 3 步：预处理 Mermaid 块

feishu-docx 工具无法处理 Mermaid 代码块。上传前，请检查 Markdown 是否包含 ```mermaid 代码块，并先将其转换为图片。

3a：扫描 Mermaid 块

读取 Markdown 文件，检查其中是否包含 ```mermaid 围栏代码块。如果未找到，则跳到第 4 步。

3b：创建临时副本

将原始 Markdown 文件复制到同一目录下的临时文件中（这样相对图片路径仍然有效）：

<original-name>.feishu-tmp.md

例如：blog_post.md → blog_post.feishu-tmp.md

之后的所有修改都在此临时副本中进行。原始文件绝不会被修改。

3c：将 Mermaid 图表渲染为 PNG

对于临时文件中的每个 ```mermaid ... ``` 块，使用 mermaid.ink API 将其渲染为 PNG 图片：

import base64, urllib.request

def render_mermaid(code: str, output_path: str):
    """Render a Mermaid diagram to PNG via mermaid.ink API."""
    encoded = base64.urlsafe_b64encode(code.encode()).decode()
    url = f"https://mermaid.ink/img/{encoded}?bgColor=white"
    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
    resp = urllib.request.urlopen(req, timeout=30)
    with open(output_path, "wb") as f:
        f.write(resp.read())

重要： 必须设置 User-Agent 请求头——否则 mermaid.ink 会返回 403。

将渲染后的图片保存到与 Markdown 文件相同的目录中，并根据图表内容使用具有描述性的文件名：

  • 好：mermaid-architecture-overview.png、mermaid-data-flow.png
  • 不好：mermaid-1.png、diagram.png
3d：将 Mermaid 块替换为图片引用

在临时副本中，将每个 ```mermaid ... ``` 块替换为 Markdown 图片引用：

![Architecture overview](mermaid-architecture-overview.png)

使用从临时文件到渲染后图片的相对路径。

3e：使用临时文件上传

从此处开始，第 4 步中的 <MARKDOWN_FILE_PATH> 指的是临时文件。

第 4 步：运行命令

  • 从 Markdown 文件所在的目录运行（或从其相对图片路径能够正确解析的目录运行），以确保本地图片引用有效。
  • 该工具将：
    • 将 Markdown 块转换为飞书格式
    • 自动上传 Markdown 中引用的本地图片
    • 等待约 10 秒，确保块内容一致后再上传图片

第 5 步：清理

如果在第 3 步创建了临时文件：

  • 删除临时 Markdown 文件（*.feishu-tmp.md）
  • 删除第 3c 步创建的所有 Mermaid PNG 文件（它们仅用于上传）

第 6 步：报告结果

向用户显示：

  • 转换的块数和上传的图片数
  • 创建的文档 ID
  • 成功或失败状态

如果因身份验证错误而失败，请提醒用户配置凭证：

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>

评论

支持 Markdown