核心内容摘要
梵音缭绕：一场禅意洗礼，七日七夜的蜕变之旅
Chandra实操手册Chandra前端添加Markdown渲染、LaTeX公式、Mermaid流程图支持
为什么需要在Chandra里支持富文本显示你有没有遇到过这样的情况和AI聊着聊着它突然给你甩出一段带数学公式的解释或者画了个流程图说明逻辑又或者用代码块展示一个完整示例——结果你眼前只看到一串乱糟糟的原始文本gemma:2b模型本身已经能生成结构清晰、格式丰富的回答但默认的Chandra前端却像一张白纸把所有精心排版的内容都“拍平”成纯文字。
这不是模型能力的问题而是前端展示层的短板。
真正的AI对话体验不该止步于“能说话”而要进阶到“会表达”公式该清晰就清晰流程图该直观就直观代码该高亮就高亮列表该对齐就对齐。
这正是我们这次升级的核心目标——让Chandra不仅能说还能漂亮地说。
整个过程不依赖外部服务不修改Ollama内核也不动后端API纯粹从前端入手轻量、安全、可复现。
你不需要成为前端专家只要跟着步骤操作15分钟内就能让自己的Chandra聊天界面焕然一新。
技术方案选型与设计原则
1 为什么选这三个库简洁、可靠、零侵入我们没有选择重型框架或全功能编辑器而是聚焦三个轻量级、专注单一能力的开源库它们共同构成了本次升级的“富文本三件套”marked负责把Markdown语法如**加粗**、 引用、code转成标准HTML。
它体积小仅约20KB、无依赖、解析速度快且完全运行在浏览器端不向服务器发送任何内容。
katex专精于LaTeX数学公式的渲染。
相比MathJax它启动更快、样式更现代、对中文兼容更好且默认支持行内公式$Emc^2$和独立公式$$\int_0^\infty e^{-x^2}dx \frac{\sqrt{\pi}}{2}$$。
mermaid业界事实标准的流程图/时序图/类图生成库。
它用纯文本描述图形如graph LR; A--B; B--C再实时渲染为SVG矢量图清晰锐利缩放不失真。
关键设计原则零后端改动所有逻辑都在前端JavaScript中完成Ollama和Chandra后端API保持原样不新增接口、不改响应格式。
安全第一所有渲染均在沙箱环境中执行自动过滤script、onerror等危险HTML标签防止XSS攻击。
渐进式增强如果某条消息不含Markdown/LaTeX/Mermaid它就按原样显示只有检测到对应语法时才触发相应渲染绝不影响原有体验。
资源友好三个库总大小控制在150KB以内首次加载后缓存后续对话毫秒级响应。
2 渲染时机与作用域只处理AI回复不碰用户输入我们明确界定富文本渲染只应用于AI模型返回的response内容绝不处理用户输入框里的文字。
原因很实在——用户输入是命令、是提问、是意图表达它本就不该被“美化”而AI的回复是信息载体、是知识输出、是解决方案它值得被更好地呈现。
因此整个流程是单向的用户输入 → 原样发给Ollama API → Ollama返回原始文本 → 前端JS识别其中的Markdown/LaTeX/Mermaid片段 → 调用对应库渲染 → 插入聊天窗口这个设计既保证了语义清晰也避免了因误渲染用户输入而引发的意外行为比如把用户写的$100当成公式渲染。
实战三步完成前端增强
1 第一步注入依赖库修改index.html打开Chandra项目的根目录找到public/index.html文件若使用Docker镜像需先进入容器或挂载修改。
在head标签内添加以下CDN链接!-- 在 head 中添加 -- link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/katex
0.
1
10/dist/katex.min.css script srchttps://cdn.jsdelivr.net/npm/marked/marked.min.js/script script srchttps://cdn.jsdelivr.net/npm/katex
0.
1
10/dist/katex.min.js/script script srchttps://cdn.jsdelivr.net/npm/mermaid
11.
0/dist/mermaid.min.js/script注意这里使用的是稳定版本CDN确保每次加载内容一致。
mermaid需在katex之后加载因其内部依赖部分数学符号渲染能力。
2 第二步编写渲染核心逻辑创建render.js在public/目录下新建文件render.js粘贴以下代码。
这段脚本将接管所有AI回复的渲染任务// public/render.js (function () { // 初始化 Mermaid mermaid.initialize({ startOnLoad: false, securityLevel: strict, theme: default }); // 定义渲染函数 window.renderMessage function (rawText) { if (!rawText || typeof rawText ! string) return rawText; // 步骤1用 marked 解析 Markdown let html marked.parse(rawText, { gfm: true, breaks: true, highlight: function (code, lang) { // 简单代码高亮可选如需更专业请集成highlight.js return precode classlanguage-${lang || }${code}/code/pre; } }); // 步骤2用 KaTeX 渲染 LaTeX 公式 html html.replace(/\$\$(.*?)\$\$/gms, (match, p
{ try { return katex.renderToString(p
trim(), { displayMode: true }); } catch (e) { return span classkatex-error[LaTeX error: ${e.message}]/span; } }).replace(/\$(.*?)\$/g, (match, p
{ try { return katex.renderToString(p
trim(), { displayMode: false }); } catch (e) { return span classkatex-error[LaTeX error]/span; } }); // 步骤3用 Mermaid 渲染流程图匹配 mermaid ... 块 const mermaidRegex /mermaid\s*([\s\S]*?)\s*/g; let tempId 0; html html.replace(mermaidRegex, (match, p
{ const id mermaid-${tempId}; return div classmermaid-containerdiv id${id}/div/div; }); // 返回处理后的HTML字符串 return html; }; // 暴露一个初始化函数供聊天组件调用 window.initMermaid function () { // 延迟执行确保DOM已就位 setTimeout(() { const containers document.querySelectorAll(.mermaid-container); containers.forEach(container { const div container.querySelector(div); if (div div.id) { try { mermaid.render(div.id, div.textContent.trim() || graph LR; A--B;); } catch (e) { console.warn(Mermaid render failed:, e); div.innerHTML em图表渲染失败请检查语法/em; } } }); },
; }; })();然后在index.html的body底部添加对render.js的引用!-- 在 /body 之前添加 -- script src./render.js/script
3 第三步改造聊天组件修改ChatMessage.vue或等效JS逻辑Chandra前端通常基于Vue或纯JS实现。
以最常见的Vue单文件组件为例找到负责渲染单条消息的组件如src/components/ChatMessage.vue定位到AI消息的模板区域。
假设原代码类似这样!-- 原始纯文本显示 -- div v-ifmessage.role assistant classmessage-content /div将其替换为!-- 升级后支持富文本 -- div v-ifmessage.role assistant classmessage-content v-htmlrenderedContent DOMNodeInsertedonNodeInserted /div并在script部分添加对应的逻辑export default { props: [message], data() { return { renderedContent: } }, mounted() { this.updateRenderedContent(); }, watch: { message.content: updateRenderedContent }, methods: { updateRenderedContent() { if (this.message.role assistant this.message.content) { // 调用我们封装的渲染函数 this.renderedContent window.renderMessage(this.message.content); // 触发Mermaid渲染 this.$nextTick(() { if (window.initMermaid) window.initMermaid(); }); } else { this.renderedContent this.message.content || ; } }, onNodeInserted() { // Vue 3中可用此钩子监听DOM变化触发mermaid重绘兼容性兜底 if (window.initMermaid) window.initMermaid(); } } }关键点说明使用v-html而非这是渲染HTML的唯一方式DOMNodeInserted是Vue 2的旧钩子Vue 3中建议改用MutationObserver或直接在mounted/updated中调用initMermaid所有错误都做了降级处理如LaTeX语法错显示提示文字Mermaid失败显示警告确保不影响整体功能。
效果验证与典型用例演示
1 测试用例清单三类内容一键验证启动修改后的Chandra服务进入聊天界面依次发送以下三条测试消息观察AI回复效果测试类型用户输入示例AI应答预期效果Markdown请用列表
总结AI模型的三个核心能力并用代码块展示一个Python调用示例应显示带序号的列表、加粗标题、以及语法高亮的precode块LaTeX请写出质能方程并推导其在相对论中的意义应在文本中嵌入清晰的$Emc^2$行内公式以及独立居中的推导公式块Mermaid请用流程图描述一次HTTP请求的完整生命周期应渲染出SVG格式的横向流程图节点圆角、箭头清晰、文字可读全部通过即表示集成成功。
2 真实场景效果对比文字描述未增强前AI回复的LaTeX公式$F ma$直接显示为$F ma$用户需自行脑补Mermaid代码块原样打印毫无图形增强后$F ma$变成优雅的斜体数学字体独立公式块居中渲染字号适中Mermaid代码被替换成交互式SVG图鼠标悬停有提示缩放不失真。
更重要的是所有这些增强都发生在用户浏览器本地。
你的gemma:2b模型依然安静地运行在Ollama容器里数据从未离开你的机器只是前端多了一双“慧眼”读懂了AI想表达的丰富语义。
进阶优化与维护建议
1 性能微调懒加载与缓存策略对于高频使用的用户可进一步优化首屏加载速度将marked、katex、mermaid的CDN地址替换为本地副本放入public/libs/避免CDN抖动对katex字体文件启用HTTP缓存头减少重复下载在render.js中增加简单缓存机制对相同rawText的渲染结果做内存缓存适用于重复问答场景。
2 安全加固严格的内容过滤虽然marked默认已禁用HTML但为万全起见可在renderMessage函数开头加入白名单过滤// 在 renderMessage 函数内解析前加入 rawText rawText.replace(/(?!(\/?(h[
]|p|br|ul|ol|li|strong|em|code|pre|blockquote|a|img)\b))[^]*/gi, );该正则仅允许Markdown生成的安全标签如p、code彻底阻断任意HTML注入可能。
3 未来可扩展方向本次方案留有清晰的扩展接口支持highlight.js替换当前简易高亮增加50语言支持集成chart.js让AI能生成 chart {type: bar, data: [...]}并渲染为交互图表添加“复制渲染后内容”按钮方便用户一键复制含格式的文本到其他平台。
这些都不是必须项而是当你需要时可以轻松插上的模块。
6.
总结让私有AI真正“活”起来我们从一个朴素的问题出发既然gemma:2b能生成结构化内容为什么前端不能理解它答案不是推倒重来而是在尊重原有架构的前提下做一次精准的“前端赋能”。
这一次升级没有动Ollama一行配置没有改gemma一个参数甚至没碰Chandra后端API。
我们只是在浏览器里悄悄装上了一副“智能眼镜”——它让Markdown有了层次让LaTeX有了尊严让Mermaid有了生命。
最终交付的不是一个炫技的Demo而是一个开箱即用、安全可靠、持续可用的生产力工具。
它印证了一个事实私有化AI的价值不仅在于“数据不出门”更在于“表达不打折”。
当你的AI助手既能思考又能清晰、美观、专业地表达所思那才是真正属于你自己的智慧伙伴。