Dify插件开发--Markdown+Mermaid转Docx

在日常工作当中，经常都需要用到Dify的智能体来进行方案设计，大模型给出的方案设计通常是Markdown格式，其中还会有很多Mermaid格式的流程图或时序图等，我们需要把生成的方案保存为Word文档格式，但是现有的Dify的Markdown转文档的插件，对于Mermaid代码块并不做渲染，虽然也可以在外网的一些网站上把Markdown文件进行转换，考虑到方案的信息敏感，我还是想在内网环境上来实现一个Dify插件来满足需求。

实现Mermaid渲染功能

为什么采用Mermaid

Mermaid是一种基于文本的图表绘制工具，使用类似 Markdown 的简单语法定义流程图、时序图、甘特图、类图等。

核心优势：纯文本、易版本控制、无需鼠标拖拽。
典型用法：在 Markdown 文档中嵌入 ````mermaid` 代码块，由渲染引擎自动生成矢量图。

大模型擅长使用Mermaid生成交互图 / 流程图，主要是以下几个原因：

文本 ↔ 图表无缝转换

大模型擅长生成结构化文本（如 JSON、YAML、代码）。Mermaid 语法本身就是文本，模型可直接输出符合规范的图表定义，无需图像生成能力。
低成本、高效率

相比生成图片（需要扩散模型，计算昂贵），输出 Mermaid 代码只需少量 token，速度快、成本低，且结果是可编辑、可版本化的矢量图。
精准表达逻辑与流程

流程图、时序图本质是逻辑关系（节点 + 边）。大模型在理解自然语言描述后，能准确映射为 A --> B、if/else 分支等 Mermaid 语句，天然适合"需求 → 图表"的生成任务。
易于集成与迭代

生成的 Mermaid 代码可直接嵌入文档、Wiki、代码注释或聊天界面，用户可手动微调，模型也能根据反馈快速修正------这正是大模型的对话式优势。

Mermaid渲染的方案

通过Python进行Mermaid渲染，通常有以下两种方式：

1. 浏览器依赖方式（本地渲染，需安装浏览器）

代表库 ：mermaid-cli（Python 封装）、md2pdf-mermaid 等。
原理：内部依赖 Playwright 驱动无头浏览器（通常是 Chromium）进行渲染，将 Mermaid 文本转换为图片或 PDF。
注意事项 ：安装完库后，必须手动运行 playwright install chromium 下载浏览器内核，否则会报错。
优点：不依赖网络，可离线使用，输出质量可控。
缺点：需要额外安装浏览器，占用磁盘空间较大，首次配置稍繁琐。

2. 在线服务方式（依赖网络）

代表库 ：mermaid-py。
原理：默认调用 mermaid.ink 在线服务（一个公开的 Mermaid 渲染 API），将图表文本发送至服务端，返回渲染后的图片。
优点：无需安装任何浏览器或本地依赖，轻量快速，适合网络通畅的环境。
缺点：必须联网，且可能受限于服务端速率、隐私（图表内容上传至第三方）或服务可用性。

考虑到这是一个内网应用，因此我采取第一种方式来实现

实现Mermaid渲染

由于Dify插件的沙盒环境限制，无法安装和持久化Chromium浏览器，因此我打算将Playwright和Mermaid-CLI作为独立服务，在服务器上部署，然后Dify插件作为轻量级的API客户端来调用。可以在服务器上通过以下命令来进行安装

复制代码

pip install mermaid-cli
playwright install chromium

但是我发现这种方式安装之后， playwright还是会报缺少一些依赖包的错误，即使运行以下命令也不能完全解决问题，主要是Playwright 需要大量图形库才能运行无头浏览器。

复制代码

playwright install-deps

另一个方法就是直接采用官方的镜像，例如我选择了mcr.microsoft.com/playwright/python:v1.56.0-jammy这个镜像。

运行这个镜像，然后在里面新建一个main.py文件，通过fastapi来对外提供mermaid渲染服务，代码如下：

python 复制代码

# main.py
import os
import tempfile
from fastapi import FastAPI, HTTPException
from fastapi.responses import Response
from pydantic import BaseModel
from mermaid_cli import render_mermaid

app = FastAPI(title="Mermaid Render Service")

class RenderRequest(BaseModel):
    code: str                    # Mermaid 代码
    format: str = "png"          # 输出格式，目前仅支持 png 或 svg
    theme: str = "default"       # 主题
    width: int = 2400             # 图片宽度（像素）
    height: int = 1800            # 图片高度（像素）

@app.post("/render")
async def render_mermaid_diagram(request: RenderRequest):
    """
    接收 Mermaid 代码，返回渲染后的图片
    """
    try:
        # 将 Mermaid 代码写入临时文件，因为 mermaid-cli 目前需要文件输入
        with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as f:
            f.write(request.code)
            input_path = f.name

        # 调用 mermaid-cli 渲染，输出为 bytes
        # 参数说明：
        # - input: 输入文件路径
        # - output_format: 图片格式 ('png' 或 'svg')
        # - theme: 主题
        # - width/height: 图片尺寸
        # - output: 如果为 None，则返回 bytes
        #view_config = {"deviceScaleFactor": 3}
        view_config = {"width": request.width, "height": request.height}
        title, desc, image_bytes = await render_mermaid(
            definition=request.code,
            output_format=request.format,
            background_color='white',
            mermaid_config={"theme": request.theme} if request.theme else None,
            viewport=view_config
        )

        # 确定返回的 Content-Type
        content_type = "image/png" if request.format == "png" else "image/svg+xml"

        return Response(content=image_bytes, media_type=content_type)

    except Exception as e:
        import traceback
        print(traceback.format_exc())
        raise HTTPException(status_code=500, detail=f"渲染失败: {str(e)}")
    finally:
        # 清理临时文件
        if os.path.exists(input_path):
            os.unlink(input_path)

# 可选的健康检查端点
@app.get("/health")
async def health():
    return {"status": "ok"}

然后运行以下命令来提供服务：

python 复制代码

uvicorn main:app --host 0.0.0.0 --port 19980 --reload

如果在调用服务时发现Playwright返回timeout错误，通常是因为官方镜像缺少中文字体，当Mermaid图表包含中文时会阻塞渲染。可以安装以下的中文字体

python 复制代码

apt-get update && \
    apt-get install -y --no-install-recommends \
    fonts-wqy-microhei \
    fonts-noto-cjk \
    && fc-cache -fv \
    && rm -rf /var/lib/apt/lists/*