1. 为什么要在 Cursor 里做 Mermaid 到 SVG 的自动导出如果你经常写技术方案、画微服务拓扑、整理 CI/CD 流水线大概率遇到过这种尴尬Mermaid 文本写在 Markdown 里预览挺好看但一旦要贴进 PPT、设计稿或者交付文档就得手动截图放大就糊改一个节点还得重新截一遍。Mermaid 流程图自动绘制这件事核心诉求其实不是能画而是能稳定、可复现、可批量地导出成矢量图。我在 Cursor 里折腾这套链路有一段时间了。Cursor 本身是个编辑器它不会替你把 Mermaid 渲染成 SVG但它能帮你把解析 Mermaid 语法文本 → 布局计算 → 导出 SVG这条流水线用脚本固化下来再配合一个统一的模型 Key 做辅助生成和纠错。这篇就聚焦在 Cursor 中把 Mermaid 文本解析为 SVG 流程图与拓扑架构图的完整链路从语法解析、布局计算到 SVG 导出给出可复制的 Cursor 规则配置和 TaoToken 统一 Key 接入示例并附上渲染结果对比与导出文件校验步骤。先说清楚适合谁一是需要把架构图纳入版本管理的后端/运维同学图跟着代码走改代码就改图二是写技术文档、做交付材料的同学想要高清矢量图而不是截图三是已经在用 Cursor 写代码想顺手把绘图也自动化的开发者。你不需要精通前端只要会跑 Python 脚本、会配一个 Base URL 就能跟做。这里有个关键认知Mermaid 的渲染本质是浏览器 DOM SVG 绘制纯 Python 后端没有浏览器环境是跑不了mermaid.js的。所以解析 Mermaid 语法文本并自动导出 SVG的可行路径是用无头浏览器加载本地mermaid.js把文本注入 DOM等渲染完成后抓取 SVG 代码落盘。Cursor 在这里的角色是帮你生成、调试、维护这套脚本而不是替代渲染引擎。我实测下来把这条链路拆成三段最清晰第一段是 Mermaid 语法文本的生成与校验第二段是无头浏览器渲染与 SVG 抓取第三段是导出文件的校验与批量处理。下面按这个顺序展开每一段都给可复制的配置和命令。2. TaoToken 统一 Key 接入给 Cursor 配一个稳定的模型入口在 Cursor 里做 Mermaid 自动绘制模型主要用在两个地方一是根据你的自然语言描述生成 Mermaid 语法文本二是当渲染报错时帮你定位语法问题。Cursor 支持自定义模型入口这里用 TaoToken 的统一 Key 接入好处是一个 Key 走通对话、补全、Agent 多种场景不用来回换配置。TaoToken 的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。注意 API 地址不带 UTM 参数直接填https://taotoken.net/api即可。在 Cursor 里配置的路径是打开 Cursor 设置找到 Models 或 OpenAI API Key 相关配置项把 Base URL 改成 TaoToken 的 API 地址API Key 填你在控制台生成的 Key。如果你用的是 Cursor 的 OpenAI 兼容模式Base URL 填https://taotoken.net/api模型 ID 按你实际要用的填比如claude-sonnet-4-20250514这类。这里要提醒一句Cursor 的模型配置界面版本间有差异有的版本在 Settings → Models有的在 Settings → General → OpenAI API Key。找不到就搜 Base URL 或 Override OpenAI Base URL。配置完记得点 Verify 或重启 Cursor让配置生效。如果你更习惯用命令行工具做批量生成比如用 Claude Code 或 Codex 这类 CLITaoToken 也支持。以 Claude Code 为例需要设置环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYBase URL 同样指向 TaoToken 的 API 地址。Codex 的话配置写在~/.codex/auth.json里包含 Base URL、Key 和 Model ID 三件套。这三件套缺一不可很多人只填了 Key 忘了 Base URL结果请求打到默认地址上报 401 或者连接失败。关于 Key 的获取去 TaoToken 控制台的 API Keys 页面生成地址是https://taotoken.net/console/api-keys。生成后复制保存Key 只显示一次。如果你要长期做编码和 Agent 任务可以考虑 Coding Plan地址是https://taotoken.net/coding-plan适合高频调用场景。配好之后你可以在 Cursor 的对话里让它生成一段 Mermaid 文本测试一下比如帮我画一个包含网关、鉴权、订单引擎、Kafka、MySQL 的拓扑图用 Mermaid graph TD 语法。如果它能正常返回 Mermaid 代码块说明 Key 接入成功。这一步是整个链路的前置模型入口通了后面生成和纠错才有保障。需要强调的是TaoToken 在这里的角色是统一的模型调用入口不是渲染引擎。Mermaid 到 SVG 的渲染还是靠本地无头浏览器完成模型只负责文本生成和排障辅助。把这两件事分清楚后面配置就不会乱。3. 可复制配置Cursor 规则 Mermaid 渲染脚本这一节给可直接复制的配置。分两部分一是 Cursor 的项目规则文件让 Cursor 知道你要生成什么风格的 Mermaid二是渲染脚本负责把 Mermaid 文本变成 SVG。先看 Cursor 规则。在项目根目录建一个.cursor/rules/mermaid-draw.mdc文件内容如下--- description: Mermaid 流程图与拓扑图生成规则 globs: [**/*.mmd, **/*.md] alwaysApply: false --- # Mermaid 绘图规则 - 生成流程图统一使用 graph TD 或 graph LR拓扑图优先 graph TD。 - 节点 ID 用英文节点显示文本用中文格式NodeId[中文说明]。 - 连线标签用 --|标签| 形式标签简洁不超过 8 个字。 - 需要强调的节点用 style 指定 fill 和 stroke颜色不超过 4 种。 - 输出必须是完整可渲染的 Mermaid 代码块不要省略号不要伪代码。 - 如果用户描述里有层级关系用 subgraph 分组。这个规则文件的作用是约束 Cursor 生成 Mermaid 时的风格避免它给你一堆花哨但不稳定的语法。alwaysApply: false表示按需触发你也可以改成 true 让它一直生效。接下来是渲染脚本。核心思路是用无头浏览器加载本地 HTML 模板模板里引入mermaid.js然后通过page.evaluate把 Mermaid 文本注入 DOM等渲染完成后抓取 SVG。这里用 Playwright 的 Python 版比 Pyppeteer 维护更活跃。先建 HTML 模板template.html!DOCTYPE html html head meta charsetutf-8 script srchttps://cdn.jsdelivr.net/npm/mermaid10.9.1/dist/mermaid.min.js/script style body { background: transparent; margin: 0; padding: 0; } /style /head body div idmermaid-container classmermaid/div script mermaid.initialize({ startOnLoad: false, theme: neutral, flowchart: { curve: basis, useMaxWidth: false } }); async function renderMermaidChart(code) { const container document.getElementById(mermaid-container); container.removeAttribute(data-processed); container.textContent code; try { await mermaid.run({ nodes: [container] }); const svg container.querySelector(svg); if (!svg) return ERROR: svg not found; svg.setAttribute(xmlns, http://www.w3.org/2000/svg); return svg.outerHTML; } catch (err) { return ERROR: err.message; } } /script /body /html注意useMaxWidth: false这个参数它保证导出的 SVG 有固定宽高不会因为容器宽度被压缩。theme: neutral是中性主题适合技术文档。然后是 Python 渲染器mermaid_renderer.py# -*- coding: utf-8 -*- import asyncio import os import logging from playwright.async_api import async_playwright logging.basicConfig(levellogging.INFO, format%(asctime)s - [%(levelname)s] - %(message)s) logger logging.getLogger(mermaid_compiler) class MermaidRenderer: def __init__(self, template_path: str): if not os.path.exists(template_path): raise FileNotFoundError(f模板文件不存在: {template_path}) self.template_url file:// os.path.abspath(template_path) async def compile_to_svg(self, mermaid_code: str, output_svg_path: str) - bool: async with async_playwright() as p: browser await p.chromium.launch( headlessTrue, args[--no-sandbox, --disable-setuid-sandbox] ) try: page await browser.new_page() await page.goto(self.template_url) await page.wait_for_function(typeof mermaid ! undefined) safe_code mermaid_code.replace(, \\) svg_content await page.evaluate( frenderMermaidChart({safe_code}) ) if not svg_content or svg_content.startswith(ERROR:): logger.error(f渲染失败: {svg_content}) return False with open(output_svg_path, w, encodingutf-8) as f: f.write(svg_content) logger.info(fSVG 已写入: {output_svg_path}) return True finally: await browser.close()这里有个关键点mermaid_code.replace(, \)这行是防止 Mermaid 文本里出现反引号导致 JS 模板字符串断裂。踩过的坑就是没做转义结果浏览器端 JS 语法错误页面直接崩报Target closed。主程序main.py# -*- coding: utf-8 -*- import asyncio import os from mermaid_renderer import MermaidRenderer TOPOLOGY_CODE graph TD User[操盘交易员] --|HTTP/JWT| Gateway[FastAPI 网关] Gateway --|滑动窗口限流| Auth[Redis 鉴权中心] Gateway --|量化订单路由| Engine[Order 撮合引擎] Engine --|Redisson分布式锁| RedisStock[(Redis 缓存库存)] Engine --|异步消息推送| Kafka{Kafka 消息总线} Kafka --|异步入库| MySQL[(MySQL 订单库)] style User fill:#ECEFF1,stroke:#37474F,stroke-width:2px style Gateway fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px style Engine fill:#FFE082,stroke:#FFB300,stroke-width:2px style MySQL fill:#C8E6C9,stroke:#43A047,stroke-width:2px def main(): renderer MermaidRenderer(template.html) success asyncio.run( renderer.compile_to_svg(TOPOLOGY_CODE, trade_topology.svg) ) if success: print(f导出成功: {os.path.abspath(trade_topology.svg)}) else: print(导出失败请查看日志) if __name__ __main__: main()依赖安装pip install playwright1.44.0 playwright install chromiumplaywright install chromium会下载适配的 Chromium 内核约 150MB只需执行一次。这一步别跳过否则运行时报找不到浏览器。4. 验证请求与成功结果跑通一次完整导出配置齐了跑一次验证。在 Cursor 的终端里执行python main.py预期输出类似2025-06-22 13:45:00 - [INFO] - SVG 已写入: trade_topology.svg 导出成功: /Users/yourname/project/trade_topology.svg打开生成的trade_topology.svg你应该看到一张带圆角节点、平滑连线、四种配色分组的拓扑图。用浏览器打开放大到 500% 线条依然锐利这就是矢量图的价值。怎么校验导出文件是不是真的 SVG三个方法。第一看文件头head -c 200 trade_topology.svg应该以svg开头带xmlns和viewBox属性。第二看文件大小一张正常拓扑图 SVG 在 5KB 到 50KB 之间如果只有几百字节多半是渲染失败写入了错误信息。第三用浏览器打开右键检查元素能看到完整的g、path、text节点结构。如果你想让 Cursor 帮你批量处理可以在对话里说读取 diagrams 目录下所有 .mmd 文件逐个调用 mermaid_renderer 导出同名 SVG失败的记录到 error.log。Cursor 会基于你的脚本生成批量处理代码。这里模型的作用是写胶水代码渲染还是走本地脚本。渲染结果对比方面我实测过三种输入简单流程图5 个节点、中等拓扑15 个节点带分组、复杂架构30 节点带样式。简单和中等都能在 1 到 2 秒内完成复杂图如果节点超过 50 个布局计算会慢一些大概 3 到 5 秒。如果超过 10 秒还没出来多半是 Mermaid 语法有循环引用或者节点 ID 冲突需要检查文本。成功导出后你可以把 SVG 直接嵌入 Markdown、HTML 或者导入 Figma、Sketch 做二次编辑。因为它是纯矢量改颜色、改文字都不会失真。这也是为什么我坚持导出 SVG 而不是 PNG——交付场景里矢量图的可用性高太多。5. 本篇常见错排查401、Target closed、语法报错怎么解这一节对照真实报错给排查路径。先说模型侧的 401。如果你在 Cursor 里调用模型时报 401通常是三种原因Key 没填对、Base URL 没改、或者 Key 已失效。检查顺序是先确认 Base URL 是https://taotoken.net/api再确认 Key 是从控制台复制的完整字符串没有多余空格。如果还报错去控制台重新生成一个 Key 试试。再说渲染侧的Target closed。这个报错在 Playwright 和 Pyppeteer 里都常见原因是浏览器进程意外退出。最常见的触发点是 Mermaid 文本里有未转义的反引号或特殊字符导致注入的 JS 语法错误浏览器崩溃。解决办法就是前面脚本里的replace(, \)把所有反引号转义。另外如果你在 Docker 里跑缺系统依赖也会导致 Chromium 起不来需要装libnss3、libatk1.0-0、libx11-6这些库。第三个高频报错是reading choices或Cannot read properties of undefined。这个通常出现在模型返回格式异常时比如你期望它返回 Mermaid 代码块它返回了一段解释文字。排查方法是检查你的 prompt 是否明确要求只输出 Mermaid 代码块。如果用的是 CLI 工具检查auth.json或环境变量里的 Model ID 是否写对Model ID 写错会导致请求打到不存在的模型上返回结构异常。第四个是 Mermaid 语法报错浏览器端返回ERROR: Parse error。这类问题看错误信息里的行号通常是节点 ID 用了中文、连线标签里有特殊符号、或者 subgraph 没闭合。Mermaid 的节点 ID 必须是英文或数字中文只能放在方括号里作为显示文本。这个规则我在 Cursor 规则文件里已经约束了但手写时还是容易忘。第五个是导出文件为空或只有几字节。检查compile_to_svg的返回值如果svg_content是ERROR:开头说明渲染失败但被写入了文件。加一个判断失败时不要写文件直接返回 False。这个在前面脚本里已经处理了。最后提醒一个配置层面的坑Cursor 的模型配置和项目规则是两回事。模型配置管的是用哪个模型项目规则管的是生成什么风格。两者都配好链路才顺。如果你只配了 Key 没写规则Cursor 生成的 Mermaid 可能风格不统一后续批量渲染容易出问题。6. 把绘图链路固化进你的工作流到这里从 Mermaid 文本到 SVG 的完整链路已经跑通了。回顾一下关键节点Cursor 负责生成和纠错 Mermaid 文本TaoToken 统一 Key 提供模型入口Playwright 无头浏览器负责渲染Python 脚本负责抓取和落盘。四者各司其职不要混在一起。如果你想把这套东西固化进工作流几个实用建议。第一把template.html、mermaid_renderer.py、main.py放进项目仓库和代码一起版本管理。第二在 CI 里加一步每次架构文档更新时自动重新导出 SVG保证图和代码同步。第三把常用的 Mermaid 片段存成模板比如网关鉴权引擎消息队列数据库这种标准拓扑用的时候直接改节点名。模型入口方面如果你只是偶尔生成 Mermaid用模型对话就够了地址是https://taotoken.net/chat。如果你要长期做编码和 Agent 任务比如让 Cursor 自动维护绘图脚本、批量处理图表Coding Plan 更合适地址是https://taotoken.net/coding-plan。接入文档在https://taotoken.net/docAPI Keys 在https://taotoken.net/console/api-keys。最后说一个我自己的习惯每次导出 SVG 后用xmllint --noout trade_topology.svg校验一下 XML 合法性。这个命令能快速发现标签未闭合、属性格式错误等问题。如果校验通过再提交到仓库。这样交付出去的图基本不会出现打不开的情况。绘图这件事工具链稳定比功能花哨重要。把这条链路跑顺以后改架构图就是改几行 Mermaid 文本的事剩下的交给脚本。