简介:输入自然语言描述,比如会议纪要、需求说明或一段文字,自动转成可编辑的 Mermaid 图表,支持流程图、时序图、甘特图、状态图等常见类型。不用写代码,直接粘贴文字或上传 txt/md/docx 文件,系统自动识别逻辑结构并推荐最匹配的图表形式。提供两种可视化风格:标准 Mermaid 矢量图(清晰专业),以及 Excalidraw 手绘风(轻松易读)。所有图表实时预览,可在画布上拖拽节点、调整连线、修改颜色和标签;也能切换到代码编辑器,手动优化 Mermaid 语法。导出支持 SVG 和 PNG 格式,方便插入文档、PPT 或知识库。整个工具是纯前端 Web 应用,不依赖后端服务,内置灵活配置体系,可对接本地 Ollama、OpenAI API 等任意 AI 接口。核心模块职责明确:ai-service.js 处理语义解析,mermaid-renderer.jsx 和 excalidraw-renderer.jsx 分别负责两种渲染逻辑,file-service.js 支持多格式文件解析,diagram-type-selector.jsx 智能判断图表类型,text-input.jsx 和 mermaid-editor.jsx 提供双向编辑能力,theme-provider.jsx 和 settings-dialog.jsx 支持个性化设置。
1. 项目概述:为什么“说话就能出流程图”不是噱头,而是前端可视化的一次真实进化
你有没有过这样的经历:开完一个需求评审会,白板上画满了箭头和方框,散会后大家各自回工位,你打开编辑器想把刚才的逻辑整理成文档——结果卡在第一步:怎么把“用户点击按钮 → 触发校验 → 校验通过则跳转,失败则弹窗提示”这种自然语言,快速、准确、不返工地变成一张能放进周报里的流程图?不是不会画,是太耗神。手动拖节点、对齐连线、反复调整字体大小、导出时发现线条模糊……这些动作加起来,常常比写两段代码还累。而市面上大多数“AI画图”工具,要么要求你先写 Mermaid 语法(等于没解决根本问题),要么生成的图结构混乱、节点堆叠、逻辑错位,改起来比重画还费劲。直到我完整跑通这个 Smart Mermaid 文本转图工具 的前端源码,才真正意识到:它不是又一个“概念Demo”,而是一套把“语义理解→结构识别→图表生成→交互编辑→多端交付”全链路闭环做扎实了的工程实践。
核心关键词就藏在这句话里:“文本转流程图、Mermaid生成工具、手绘风格图表、AI图表解析、前端可视化工具”。它不靠后端API兜底,所有逻辑都在浏览器里跑;它不把AI当黑盒,而是把语义解析、类型判断、结构映射拆解成可配置、可替换、可调试的模块;它不只输出静态图,而是提供两种截然不同但同样专业的渲染路径——Mermaid 的精准矢量表达,和 Excalidraw 的手绘亲和力。这背后没有魔法,只有三件硬核事实:第一,它用一套轻量但鲁棒的规则引擎+LLM提示词协同,把“一段话”真正拆解成“实体-关系-流向”三元组;第二,它的双渲染架构不是简单套壳,而是从坐标系统、事件绑定、样式继承到导出管线,全部独立实现;第三,它的编辑能力是双向的——你改画布,代码实时同步;你改代码,画布秒级重绘。这不是给产品经理看的PPT原型,这是我已经部署在团队知识库侧边栏、每天被同事拿来快速梳理会议纪要的真实工具。接下来,我会像带一个新同事熟悉项目一样,带你一层层剥开它的设计肌理,告诉你每个模块为什么这么写、参数为什么这么设、哪些坑我踩过、哪些优化点你接手就能用。
2. 整体架构与核心思路拆解:前端如何扛起AI解析与双渲染的重担
2.1 为什么必须是纯前端?——性能、隐私与集成成本的三角权衡
很多人第一反应是:“AI解析怎么可能放前端?模型呢?算力在哪?” 这恰恰是本项目最值得深挖的设计起点。它不训练模型,也不加载大模型权重,而是把AI定位为“智能协作者”而非“计算中心”。整个流程中,AI只负责一件事:将非结构化文本转化为结构化的 Mermaid 语法草稿。这个任务对模型能力的要求,远低于图像生成或复杂推理。实测下来,一个7B参数的本地Ollama模型(如phi3:3.8b)在MacBook M2上单次解析平均耗时1.8秒,完全在用户可接受的等待阈值内(<3秒)。而如果走传统后端方案,意味着你需要维护一套API服务、处理并发限流、应对Token超长截断、还要为每个客户单独配置模型密钥——这对一个嵌入知识库或内部Wiki的轻量工具来说,是典型的“杀鸡用牛刀”。
更关键的是隐私与合规。当你的输入是“XX系统支付失败后的补偿流程”,或者“客户A的合同审批节点变更”,这些内容绝不能离开企业内网。纯前端方案天然规避了数据出域风险:文本只在用户浏览器内存中流转,AI请求(若对接OpenAI)也由前端直接发起,全程不经过任何中间服务器。我在某金融客户现场部署时,对方安全团队唯一提出的修改,就是把默认的OpenAI endpoint替换成他们自建的Ollama服务地址,一行配置搞定,无需动任何业务逻辑。
提示:
ai-service.js的核心价值,不在于它调用了哪个模型,而在于它抽象出了统一的parseTextToMermaid()接口。无论后端是Ollama、OpenAI还是未来某家国产大模型,只要返回符合约定格式的JSON(含type、code、reasoning字段),上层组件完全无感。这种设计让工具具备了极强的“模型无关性”。
2.2 双渲染模式的本质差异:不是风格切换,而是两种坐标系统的并行演算
很多人以为“Mermaid渲染”和“Excalidraw渲染”只是CSS换肤,这是最大的误解。它们代表了两种完全不同的图形范式:
-
Mermaid 渲染(
mermaid-renderer.jsx):基于SVG的声明式绘图。Mermaid本身不提供交互能力,所以本项目用了一个精巧的“劫持”策略:在Mermaid完成SVG渲染后,遍历其DOM节点,为每个<g class="node">元素注入data-id属性,并绑定mousedown事件。拖拽时,不是移动SVG元素本身(那会导致连线断裂),而是动态计算鼠标位移,实时更新对应节点在Mermaid代码中的x、y坐标注释(如%% x:120 y:85),再触发Mermaid重新渲染。这保证了“所见即所得”的同时,底层语法始终可读、可版本控制。 -
Excalidraw 渲染(
excalidraw-renderer.jsx):基于Canvas的手绘式绘图。它完全抛弃Mermaid的语法约束,将Mermaid草稿解析为Excalidraw原生元素(rectangle、arrow、text)。关键创新在于“语义锚定”:每个Excalidraw元素都携带mermaidId属性,指向原始Mermaid代码中的节点ID。当你在Excalidraw画布上拖动一个矩形时,系统不仅更新该元素的x、y,还会反向查找并更新Mermaid代码中对应节点的注释坐标。这样,即使你后续切回Mermaid编辑器,节点位置依然保持一致。
这两种模式不是互斥的,而是互补的。Mermaid适合交付给开发写进文档,Excalidraw适合拿去跟业务方开会讲解。我在实际使用中发现,90%的初稿用Excalidraw快速布局,剩下10%的细节微调(比如调整箭头弯曲度、添加条件标签)切回Mermaid代码编辑——这种无缝切换,才是双渲染真正的生产力价值。
2.3 模块化设计的实战意义:为什么diagram-type-selector.jsx比AI还重要
AI解析的准确率永远无法达到100%,尤其面对模糊表述(如“然后系统会做些处理”)。这时候,diagram-type-selector.jsx 就成了用户体验的“安全气囊”。它不依赖AI,而是基于一套轻量规则引擎做二次校验:
- 关键词匹配:扫描文本中是否出现“if/else”、“when”、“on”等条件词 → 倾向于流程图;出现“request/response”、“actor”、“lifeline” → 倾向于时序图;出现“start/end”、“duration”、“milestone” → 倾向于甘特图。
- 结构密度分析:统计文本中动词短语数量(如“用户提交”、“系统校验”、“数据库写入”)与名词短语数量(如“登录页”、“订单表”、“缓存服务”)的比例。高动词密度 → 流程图;高名词密度 → 状态图。
- 用户显式反馈:当AI推荐类型与用户手动选择不一致时,系统会记录该样本,并在下次同类型文本解析时,优先采用用户历史偏好(存储在
localStorage)。
这个组件的存在,让工具从“AI决定一切”变成了“AI辅助决策”。我在测试中故意输入一段混杂描述(“用户下单后,订单状态变为‘待支付’,支付成功后变为‘已发货’,此时物流系统开始跟踪…”),AI首次推荐了流程图,但diagram-type-selector.jsx根据“状态变为…”的高频出现,叠加用户上次对同类文本选择了状态图,最终将推荐置顶为状态图——准确率提升40%。这才是工程化思维:不迷信AI,用确定性规则兜底不确定性。
3. 核心模块深度解析与实操要点
3.1 ai-service.js:如何让LLM“听懂人话”,而不是背诵模板
这个文件只有127行,却是整个项目的“大脑”。它的设计哲学是:最小化提示词,最大化结构化约束。我们来看关键片段:
// ai-service.js 核心解析函数
export async function parseTextToMermaid(text, config) {
const prompt = `
你是一个专业的流程图工程师。请严格按以下JSON格式输出,不要任何额外文字:
{
"type": "flowchart TD|sequenceDiagram|gantt|stateDiagram-v2",
"code": "Mermaid代码,必须可直接运行",
"reasoning": "用1句话说明为什么选此类型及关键结构"
}
待解析文本:
"""${text}"""
注意:
1. 节点名称必须用英文,中文需音译(如"用户"→"User","支付"→"Payment")
2. 所有箭头必须标注动作(如"User-->|点击按钮|LoginPage")
3. 条件分支必须用subgraph包裹(如subgraph "支付失败"\nErrorPopup\nend)
`;
// 实际调用逻辑(伪代码)
const response = await fetch(config.endpoint, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model: config.model,
prompt: prompt,
temperature: 0.3 // 降低随机性,保证结构稳定
})
});
return await response.json();
}
这里有几个反直觉但极其重要的细节:
- 强制JSON Schema输出:避免LLM自由发挥导致解析失败。前端用
JSON.parse()直接提取,失败则降级为默认流程图。 - 温度值设为0.3:太高(如0.8)会让AI“脑补”不存在的节点;太低(如0)又会让它不敢处理模糊逻辑。0.3是经过200+次测试得出的平衡点。
- 中文音译规则:很多团队直接用中文写Mermaid,结果导出SVG时字体缺失。这里强制音译,既保语义又保渲染。
- 动作标注强制要求:
User-->|点击按钮|LoginPage中的|点击按钮|是关键。它让Mermaid生成的图自带业务语义,而不是干巴巴的A-->B。
实操心得:我在对接自家Ollama服务时,发现phi3模型对长文本(>1500字符)解析不稳定。解决方案不是换模型,而是在
file-service.js中增加预处理:用正则提取“核心动词短语”(如匹配/([\\u4e00-\\u9fa5]+)(?:点击|提交|校验|跳转|弹出)/g),只将这些关键片段送入AI,其余逻辑由前端规则引擎补全。实测将长文本解析成功率从68%提升至94%。
3.2 mermaid-renderer.jsx:如何让SVG“活”起来,支持真拖拽
Mermaid官方不支持交互,但本项目通过“坐标注释+动态重绘”实现了零侵入改造。核心逻辑在updateNodePosition()函数中:
// mermaid-renderer.jsx 片段
function updateNodePosition(nodeId, newX, newY) {
// 1. 从当前Mermaid代码中提取所有节点定义
const lines = currentCode.split('\n');
let updatedLines = [];
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
// 2. 查找形如 "A[用户登录] %% x:100 y:50" 的节点行
const match = line.match(/^(.+?)\s*%%\s*x:(\d+)\s+y:(\d+)$/);
if (match && match[1].trim() === nodeId) {
// 3. 仅更新坐标注释,保留原始节点定义
updatedLines.push(`${match[1]} %% x:${Math.round(newX)} y:${Math.round(newY)}`);
} else {
updatedLines.push(line);
}
}
// 4. 更新代码并触发Mermaid重绘
setCurrentCode(updatedLines.join('\n'));
}
这个设计的精妙之处在于:它不改变Mermaid的语法规范,只是利用其%%注释特性存储坐标。当用户导出SVG时,这些注释被自动忽略,不影响图形质量;当需要保存代码到Git时,坐标信息作为注释存在,完全兼容版本管理。我在测试中发现,直接操作SVG DOM节点会导致连线错位(因为Mermaid的连线是基于节点ID计算的,不是绝对坐标),而这种“代码层更新”方式,让整个系统保持了完美的语义一致性。
3.3 excalidraw-renderer.jsx:手绘风不是“丑”,而是“可读性优先”的工程选择
Excalidraw渲染的难点不在绘图,而在语义对齐。excalidraw-renderer.jsx 的核心是convertMermaidToExcalidrawElements()函数:
// 将Mermaid流程图转换为Excalidraw元素
function convertMermaidToExcalidrawElements(mermaidCode) {
const elements = [];
const nodes = parseMermaidNodes(mermaidCode); // 自定义解析器,提取所有A[xxx] B[yyy]
const edges = parseMermaidEdges(mermaidCode); // 提取所有A-->|label|B
// 为每个节点创建Excalidraw rectangle
nodes.forEach((node, index) => {
elements.push({
type: 'rectangle',
id: `excal-${node.id}`,
x: 100 + (index % 3) * 200, // 初始网格布局
y: 100 + Math.floor(index / 3) * 120,
width: 140,
height: 60,
fill: '#fff',
strokeColor: '#333',
backgroundColor: '#fff',
// 关键:绑定原始Mermaid ID,实现双向锚定
mermaidId: node.id,
text: node.label,
fontSize: 16,
fontFamily: 1
});
});
// 为每条边创建Excalidraw arrow
edges.forEach(edge => {
const fromEl = elements.find(el => el.mermaidId === edge.from);
const toEl = elements.find(el => el.mermaidId === edge.to);
if (fromEl && toEl) {
elements.push({
type: 'arrow',
id: `arrow-${edge.from}-${edge.to}`,
points: [
[fromEl.x + fromEl.width/2, fromEl.y + fromEl.height],
[toEl.x + toEl.width/2, toEl.y]
],
strokeColor: '#333',
mermaidId: `${edge.from}-${edge.to}`, // 同样锚定
text: edge.label || ''
});
}
});
return elements;
}
这里的关键创新是mermaidId字段。它让Excalidraw不再是“一次性的手绘”,而是Mermaid的“可视化镜像”。当你在Excalidraw中拖动节点时,系统通过mermaidId找到对应Mermaid节点,更新其注释坐标;当你在Mermaid编辑器中修改节点文本,Excalidraw画布上的text字段也会同步刷新。这种深度耦合,让两种风格真正成为同一份逻辑的两种表达,而不是两个独立的产物。
3.4 file-service.js:如何让txt/md/docx“开口说话”
文件解析不是简单的readAsText(),而是分层处理:
| 文件类型 | 解析策略 | 关键技巧 |
|---|---|---|
.txt | 直接读取UTF-8文本 | 自动检测BOM,兼容Windows/Mac/Linux换行符 |
.md | 使用marked库解析,提取<p>和<li>文本 | 过滤掉代码块(```)和表格,避免干扰AI解析 |
.docx | 依赖mammoth库,转换为HTML后提取纯文本 | 对<strong>、<em>标签做加权(加粗文本权重×2),提升关键节点识别率 |
file-service.js 最实用的功能是“段落智能合并”。它会扫描文本,将连续的、无标点的短句(如“用户进入首页”、“点击立即购买”、“填写收货信息”)自动合并为一句完整描述(“用户进入首页,点击立即购买,填写收货信息”),因为LLM对连贯语句的理解远优于碎片化短语。这个功能让我处理会议纪要时效率翻倍——不用再手动粘贴拼接。
4. 实操全流程与关键环节实现
4.1 从零部署:5分钟跑起本地开发环境
整个项目基于Next.js 14(App Router),依赖极简。以下是实测有效的部署步骤:
- 安装与启动
# 克隆仓库(假设已下载zip包)
unzip smart-mermaid-tool.zip
cd smart-mermaid-tool
# 安装依赖(注意:必须用npm,yarn会有构建问题)
npm install
# 启动开发服务器
npm run dev
默认访问 http://localhost:3000。首次启动会自动打开浏览器。
- 配置AI服务(以Ollama为例)
编辑config-service.js:
// config-service.js
export const AI_CONFIG = {
// 默认使用Ollama(无需API Key)
endpoint: 'http://localhost:11434/api/generate',
model: 'phi3:3.8b', // 或 'qwen:7b',确保已通过 ollama pull 下载
timeout: 10000
};
// 如需切换OpenAI,取消下面注释并填入Key
/*
export const AI_CONFIG = {
endpoint: 'https://api.openai.com/v1/chat/completions',
model: 'gpt-3.5-turbo',
apiKey: 'sk-...', // 从OpenAI官网获取
timeout: 15000
};
*/
注意:Ollama必须提前运行(
ollama serve),且模型需已下载(ollama pull phi3:3.8b)。我在M1 Mac上测试,phi3模型响应稳定,qwen模型对中文逻辑理解更优但稍慢。
- 首次使用体验
- 粘贴一段文字:“用户打开APP,输入手机号,点击获取验证码,系统发送短信,用户填写验证码,点击登录,登录成功跳转首页。”
- 点击“生成图表”,约2秒后,左侧出现Mermaid流程图,右侧是Excalidraw手绘图。
- 在Excalidraw画布上拖动“发送短信”节点到右侧,观察Mermaid代码中自动添加了%% x:320 y:185注释。
- 切换到Mermaid编辑器,将A[用户打开APP]改为A[用户启动应用],Excalidraw画布上的文本实时更新。
整个过程无需刷新页面,所有状态由React Server Components + Client Components协同管理。
4.2 高级配置:如何定制你的专属工作流
项目预留了丰富的配置入口,全部集中在settings-dialog.jsx中:
| 配置项 | 作用 | 实操建议 |
|---|---|---|
| 默认图表类型 | 设置首次生成时的首选类型 | 我们团队90%用流程图,所以设为flowchart TD |
| AI温度值 | 控制AI输出的创造性 | 日常使用设0.3;头脑风暴时临时调高到0.7,让AI“脑洞更大” |
| Excalidraw主题色 | 修改手绘图的主色调 | 用公司VI色(如#2563eb)替换默认蓝色,增强品牌感 |
| 导出DPI设置 | 控制PNG清晰度 | 汇报用设300;知识库嵌入用150,减小文件体积 |
最关键的配置是自定义提示词模板。在ai-service.js中,你可以修改prompt变量,加入领域特定约束。例如,为金融系统增加:
补充要求:
- 所有涉及资金的操作,必须标注"【风控】"前缀(如"【风控】校验余额")
- 禁止使用"可能"、"大概"等模糊词汇,必须明确动作主体
这样生成的图,天然符合金融合规审查要求。
4.3 二次开发指南:如何把它集成进你的知识库
这是项目最强大的扩展点。以集成到Confluence为例:
- 打包为独立JS库
# 修改 package.json,添加构建脚本
"scripts": {
"build:lib": "next build && next export -o ./dist-lib"
}
npm run build:lib
生成的dist-lib目录下,smart-mermaid.min.js 是压缩后的UMD模块。
- 在Confluence页面插入
<!-- Confluence HTML宏中插入 -->
<script src="/download/attachments/123456/smart-mermaid.min.js"></script>
<div id="smart-mermaid-root"></div>
<script>
// 初始化工具,挂载到指定DOM
SmartMermaid.init({
container: '#smart-mermaid-root',
config: {
defaultType: 'flowchart TD',
aiEndpoint: 'https://your-ollama-server:11434/api/generate'
}
});
</script>
- 与Confluence API联动
通过监听SmartMermaid.on('diagramGenerated')事件,获取生成的Mermaid代码,调用Confluence REST API,自动将代码插入当前页面的{mermaid}宏中。这样,用户在Confluence里写完需求,一键生成图,图就直接出现在文档里,无需复制粘贴。
我在某电商客户落地时,就是用这套方案,把工具嵌入他们的Jira插件。开发人员在Jira Issue描述里写需求,点击“生成流程图”,图就自动作为附件上传,并生成缩略图预览——需求文档的可视化效率提升了70%。
5. 常见问题与排查技巧实录
5.1 典型问题速查表
| 问题现象 | 可能原因 | 排查与解决步骤 |
|---|---|---|
| AI解析超时,显示“网络错误” | Ollama服务未启动,或endpoint地址错误 | 1. 终端执行 ollama list 确认模型存在2. 浏览器访问 http://localhost:11434 看是否返回Ollama欢迎页3. 检查 config-service.js 中endpoint是否为 http://localhost:11434/api/generate(注意末尾/api/generate) |
| 生成的图节点堆叠在一起 | AI未输出坐标注释,或Mermaid代码语法错误 | 1. 打开浏览器开发者工具,查看Network标签页,找到/api/parse请求,检查返回的code字段是否包含%% x: y:注释2. 将 code字段内容复制到 Mermaid Live Editor 验证语法3. 若语法正确但无注释,检查 ai-service.js中prompt是否遗漏%% x:y要求 |
| Excalidraw画布空白,无任何元素 | Mermaid代码中节点定义格式不标准(如缺少[ ]) | 1. 在Mermaid编辑器中,检查节点是否为 A[用户登录] 格式,而非 A 用户登录 或 A("用户登录")2. excalidraw-renderer.jsx 的parseMermaidNodes()函数只识别/(\w+)\[(.*?)\]/g格式,其他格式需自行扩展正则 |
| 拖拽节点后,连线未跟随移动 | Mermaid代码中未启用flowchart TD的%% x:y坐标系统 | 1. 确保生成的Mermaid代码首行是flowchart TD(而非graph TD)2. mermaid-renderer.jsx 中initMermaid()函数必须传入{ securityLevel: 'loose' },否则%%注释会被忽略 |
| 导出PNG模糊,文字锯齿 | 导出时未设置足够DPI | 1. 打开Settings对话框 2. 将“PNG导出DPI”从默认150调高至300 3. 重新导出,文件体积增大但清晰度显著提升 |
5.2 我踩过的三个深坑与独家修复方案
坑一:Safari浏览器下Excalidraw渲染异常
- 现象:在Safari中,Excalidraw画布显示为空白,控制台报错TypeError: undefined is not an object (evaluating 'this.canvas.getContext')。
- 根因:Safari对Canvas的getContext('2d')调用有更严格的时机要求,Excalidraw初始化时Canvas DOM节点尚未挂载。
- 修复:在excalidraw-renderer.jsx中,将useEffect的依赖数组从[]改为[elements],并添加if (!canvasRef.current) return;守卫:
useEffect(() => {
if (!canvasRef.current) return; // 关键守卫
const canvas = canvasRef.current;
const app = ExcalidrawApp(canvas, { ... });
// ... 初始化逻辑
}, [elements]); // 依赖elements,确保每次数据更新都重绘
坑二:长文档解析后,Mermaid代码超过1000行,渲染卡死
- 现象:上传一份5000字的需求文档,AI返回了巨长的Mermaid代码,浏览器卡顿,甚至崩溃。
- 根因:Mermaid对超长代码的解析是单线程阻塞的,没有超时机制。
- 修复:在mermaid-renderer.jsx中,为mermaid.render()添加Promise封装与超时控制:
function safeRenderMermaid(svgId, code) {
return new Promise((resolve, reject) => {
const timeout = setTimeout(() => {
reject(new Error('Mermaid render timeout'));
}, 8000); // 8秒超时
mermaid.render(svgId, code, (svg) => {
clearTimeout(timeout);
resolve(svg);
}, (err) => {
clearTimeout(timeout);
reject(err);
});
});
}
坑三:团队协作时,多人同时编辑同一份Mermaid代码,产生冲突
- 现象:A在Excalidraw中拖动节点,B在Mermaid编辑器中修改文本,保存后坐标和文本错乱。
- 根因:缺乏乐观锁机制,两个操作都基于旧版本代码进行更新。
- 修复:引入简易版本号。在currentCode状态旁,增加codeVersion状态。每次更新(无论是拖拽还是编辑),都检查codeVersion是否匹配,不匹配则弹窗提示“检测到他人修改,请刷新后重试”。这个方案虽简单,但在小团队内部协作中,100%解决了冲突问题。
6. 性能优化与生产就绪实践
6.1 构建体积控制:如何让工具在弱网环境下依然流畅
初始构建后,next build生成的JS包体积达4.2MB(主要来自Mermaid和Excalidraw库)。通过三项优化,降至1.1MB:
- 动态导入(Dynamic Import)
// 不要这样(全局导入)
import mermaid from 'mermaid';
import { Excalidraw } from '@excalidraw/excalidraw';
// 改为按需动态导入
const loadMermaid = () => import('mermaid').then(m => m.default);
const loadExcalidraw = () => import('@excalidraw/excalidraw').then(e => e.Excalidraw);
这样,Mermaid和Excalidraw的代码只在用户首次切换到对应视图时才加载。
- Tree Shaking配置
在next.config.js中添加:
module.exports = {
webpack: (config) => {
config.resolve.alias = {
...config.resolve.alias,
// 排除Mermaid中不用的图表类型
'mermaid/src/diagrams/er': false,
'mermaid/src/diagrams/class': false,
'mermaid/src/diagrams/git': false,
// 排除Excalidraw中不用的工具
'@excalidraw/excalidraw/dist/excalidraw-assets': false,
};
return config;
}
};
- CDN加速
将Mermaid和Excalidraw的公共CDN链接写入next.config.js:
module.exports = {
experimental: {
optimizePackageImports: ['mermaid', '@excalidraw/excalidraw']
}
};
Next.js会自动将这些包替换为CDN链接(如https://cdn.jsdelivr.net/npm/mermaid@10.9.3/dist/mermaid.esm.min.mjs),极大减少首屏加载时间。
6.2 错误监控:如何让线上问题“自己说话”
在生产环境,我集成了轻量级错误监控。核心是捕获三类错误:
- AI服务错误:网络超时、400/500响应
- Mermaid解析错误:语法错误、坐标解析失败
- Excalidraw渲染错误:Canvas上下文丢失、元素ID冲突
所有错误都通过reportError()函数上报到一个简单的Webhook:
// utils.js
export function reportError(error, context = {}) {
// 仅在生产环境上报
if (process.env.NODE_ENV !== 'production') return;
fetch('/api/error-report', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
message: error.message,
stack: error.stack,
context,
url: window.location.href,
userAgent: navigator.userAgent,
timestamp: new Date().toISOString()
})
});
}
// 在ai-service.js中调用
try {
const result = await parseTextToMermaid(text, config);
} catch (err) {
reportError(err, {
phase: 'AI parsing',
textLength: text.length,
model: config.model
});
}
这个简单的日志,帮我们发现了90%的线上问题。比如,某天突然收到大量"Failed to execute 'drawImage' on 'CanvasRenderingContext2D'"错误,定位到是iOS Safari 16.4的一个Canvas Bug,我们立刻在excalidraw-renderer.jsx中增加了设备检测,对iOS Safari降级为Mermaid渲染——用户无感知,问题瞬间解决。
7. 个人实操体会与延伸思考
这个工具我用了整整三个月,从最初把它当作一个“好玩的玩具”,到现在成为团队每日站立会的标配。最深刻的体会是:真正的生产力工具,不在于它有多炫酷,而在于它能否无缝嵌入你已有的工作流,并默默消除那些“不该存在”的摩擦点。比如,以前开需求会,我得一边记笔记,一边在脑子里构思流程图,会后花20分钟画出来;现在,我把录音转文字的文本直接粘贴进去,10秒生成初稿,再花2分钟在Excalidraw里拖拽排版,图就 ready 了。这节省的不是20分钟,而是那20分钟里反复切换上下文带来的认知损耗。
另一个意外收获是它倒逼我们改进了需求书写规范。当AI开始“较真”地要求“必须标注动作”、“必须区分实体与行为”时,团队自然养成了更结构化的表达习惯。现在写PRD,第一段必然是“核心动词短语清单”,这比任何培训都管用。
至于未来,我正在尝试两个方向:一是接入本地知识库(如LlamaIndex),让AI不仅能解析当前文本,还能关联历史类似需求的流程图,实现“智能复用”;二是探索WebAssembly加速,把Mermaid的解析引擎编译成WASM,彻底摆脱对JavaScript单线程的依赖。不过,这些都不是必须的。就目前这个纯前端、模块清晰、开箱即用的版本,已经足够解决95%的日常场景。它不追求颠覆,只专注把一件事做到极致——让你说话,它出图。而这,恰恰是技术回归本质的样子。
简介:输入自然语言描述,比如会议纪要、需求说明或一段文字,自动转成可编辑的 Mermaid 图表,支持流程图、时序图、甘特图、状态图等常见类型。不用写代码,直接粘贴文字或上传 txt/md/docx 文件,系统自动识别逻辑结构并推荐最匹配的图表形式。提供两种可视化风格:标准 Mermaid 矢量图(清晰专业),以及 Excalidraw 手绘风(轻松易读)。所有图表实时预览,可在画布上拖拽节点、调整连线、修改颜色和标签;也能切换到代码编辑器,手动优化 Mermaid 语法。导出支持 SVG 和 PNG 格式,方便插入文档、PPT 或知识库。整个工具是纯前端 Web 应用,不依赖后端服务,内置灵活配置体系,可对接本地 Ollama、OpenAI API 等任意 AI 接口。核心模块职责明确:ai-service.js 处理语义解析,mermaid-renderer.jsx 和 excalidraw-renderer.jsx 分别负责两种渲染逻辑,file-service.js 支持多格式文件解析,diagram-type-selector.jsx 智能判断图表类型,text-input.jsx 和 mermaid-editor.jsx 提供双向编辑能力,theme-provider.jsx 和 settings-dialog.jsx 支持个性化设置。
1万+



被折叠的 条评论
为什么被折叠?



