Markdown 消息

将 LLM 响应渲染为丰富的格式化 Markdown，并提供适当的流式输出支持

LLM 天然会生成 Markdown 格式的文本，包括标题、列表、代码块、表格和内联格式。将这些内容以纯文本形式渲染会浪费模型提供的结构信息。本模式展示如何在智能体流式输出时实时解析和渲染 Markdown，支持所有主流前端框架。

Markdown 渲染的工作原理

渲染管道包含三个步骤：

1. 接收： useStream 将流式文本累积到每个 AI 消息的 msg.text 中，随着新 Token 到达而响应式更新。
2. 解析： Markdown 解析器将原始文本转换为 HTML（或 React 元素树）。这在每次更新时运行，但对于聊天长度的内容足够快（5 KB 消息不到 5ms）。
3. 渲染： 解析后的输出渲染到 DOM 中。React 使用虚拟 DOM 差异比较；Vue 和 Svelte 使用 v-html / {@html} 配合经过清理的 HTML。

设置 useStream

Markdown 模式使用一个简单的聊天智能体，无需特殊配置。使用你的智能体 URL 和助手 ID 来连接 useStream。

导入你的智能体并将 typeof myAgent 作为类型参数传递给 useStream，以获得类型安全的状态值访问：

import type { myAgent } from "./agent";

React

import { useStream } from "@langchain/react";
import { AIMessage, HumanMessage } from "@langchain/core/messages";

const AGENT_URL = "http://localhost:2024";

export function Chat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "simple_agent",
  });

  return (
    <div>
      {stream.messages.map((msg) => {
        if (AIMessage.isInstance(msg)) {
          return <Markdown key={msg.id}>{msg.text}</Markdown>;
        }
        if (HumanMessage.isInstance(msg)) {
          return <p key={msg.id}>{msg.text}</p>;
        }
      })}
    </div>
  );
}

选择 Markdown 库

每个框架都有自然的 Markdown 渲染选择：

框架	库	输出	原因
React	react-markdown + remark-gfm	React 元素	基于组件，虚拟 DOM 差异比较，无需 dangerouslySetInnerHTML
Vue	marked + dompurify	通过 v-html 清理后的 HTML	轻量级，快速，内置 GFM
Svelte	marked + dompurify	通过 {@html} 清理后的 HTML	与 Vue 相同，一致的 API
Angular	marked + dompurify	通过 [innerHTML] 清理后的 HTML	与 Vue/Svelte 相同

React 的 react-markdown 直接将 Markdown 转换为 React 元素，因此不需要 HTML 清理。不涉及 dangerouslySetInnerHTML。对于 Vue、Svelte 和 Angular，在渲染前始终使用 dompurify 清理解析后的 HTML。

构建 Markdown 组件

React

import ReactMarkdown from "react-markdown";
import remarkGfm from "remark-gfm";

export function Markdown({ children }: { children: string }) {
  return (
    <div className="markdown-content">
      <ReactMarkdown remarkPlugins={[remarkGfm]}>
        {children}
      </ReactMarkdown>
    </div>
  );
}

清理 HTML 输出

当将解析后的 Markdown 作为原始 HTML 渲染（v-html、{@html}、[innerHTML]）时，你必须清理输出以防止跨站脚本攻击（XSS）。LLM 的响应可能包含任意文本，包括 Markdown 解析器可能转换为可执行 HTML 的标记。

使用 dompurify 去除危险元素：

import DOMPurify from "dompurify";

const safeHtml = DOMPurify.sanitize(rawHtml);

DOMPurify 移除 <script> 标签、onclick 属性、javascript: URL 和其他 XSS 攻击向量，同时保留安全的 Markdown 输出，如标题、列表、代码块、表格和链接。

React 的 react-markdown 不需要 dompurify，因为它直接生成 React 元素，不涉及原始 HTML 注入。

流式输出注意事项

useStream 随着每个 Token 的到达响应式更新 msg.text。Markdown 组件在每次更新时重新解析。对于典型的聊天消息，这是高性能的：

• marked 的解析速度约为 1 MB/s。5 KB 的消息耗时不到 5ms
• react-markdown + remark 管道对于聊天长度的内容同样快速
• 浏览器的布局引擎能高效处理 DOM 更新

对于非常长的响应（> 50 KB），请考虑以下优化：

• 节流渲染： 使用 requestAnimationFrame 将更新批量处理为 60fps，而不是每个 Token 都重新渲染
• 增量解析： 仅解析新内容并追加到已渲染的缓冲区（高级用法，通常聊天 UI 不需要）

对于大多数聊天应用，在每个 Token 到达时重新解析完整消息的简单方法就足够了。只有在观察到非常长的消息出现滚动卡顿或丢帧时才需要优化。

Markdown 内容样式

将样式应用到 .markdown-content 类来控制渲染的 Markdown 外观。以下是基本样式：

.markdown-content p {
  margin: 0.4em 0;
}

.markdown-content ul,
.markdown-content ol {
  margin: 0.4em 0;
  padding-left: 1.4em;
}

.markdown-content pre {
  overflow-x: auto;
  border-radius: 0.375rem;
  background: rgba(0, 0, 0, 0.05);
  padding: 0.5rem;
  font-size: 0.75rem;
}

.markdown-content code {
  border-radius: 0.25rem;
  background: rgba(0, 0, 0, 0.08);
  padding: 0.125rem 0.25rem;
  font-size: 0.75rem;
}

.markdown-content blockquote {
  margin: 0.4em 0;
  padding-left: 0.75em;
  border-left: 3px solid currentColor;
  opacity: 0.8;
}

.markdown-content table {
  border-collapse: collapse;
  margin: 0.4em 0;
}

.markdown-content th,
.markdown-content td {
  border: 1px solid #e5e7eb;
  padding: 0.25em 0.5em;
}

聊天气泡中保持 Markdown 样式紧凑。聊天消息比博客文章短，所以使用比典型散文样式表更紧凑的边距和更小的字体大小。

最佳实践

• 始终清理： 使用 v-html、{@html} 或 [innerHTML] 时，始终通过 dompurify 处理解析后的输出。永远不要信任由 LLM 输出馈送的 Markdown 解析器产生的原始 HTML。
• 启用 GFM： GitHub 风格 Markdown 添加了表格、删除线、任务列表和自动链接。LLM 常用这些功能。
• 处理空内容： 在解析前检查空字符串，以避免渲染空容器。
• 使用 breaks: true： 启用换行转换，使 LLM 输出中的单个换行符渲染为 <br> 而不是被忽略。LLM 经常使用单个换行符进行视觉分隔。
• 为聊天场景设计样式： 使用适合聊天气泡的紧凑边距和大小，而不是全宽文章布局。
• 使用丰富内容进行测试： 验证标题、嵌套列表、长行代码块、宽表格和引用块的渲染，以发现溢出或布局问题。

---

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面 或 提交 issue。