在 assistant-ui 中为助手消息渲染…

当 assistant-ui 的助手文本需要 Markdown 渲染、流式解析、代码高亮、数学公式或 Mermaid 图表时，按本经验选型、安装并接入对应渲染器。

适用场景

解决思路

1. 先查阅 `https://www.assistant-ui.com/llms.txt` 获取最新 API。
2. 在 assistant-ui 中，助手文本 part 有两个渲染器：`MarkdownTextPrimitive`（基于 `react-markdown` 的轻量路径）和已安装的 `MarkdownText` element（其带样式实现）；需要时用 `StreamdownTextPrimitive` 作为替代。
3. 当应用需要小渲染器、自定义 `react-markdown` component map，或按 fenced language 覆盖 `SyntaxHighlighter` 和 `CodeHeader` 时，选择 `markdown-text`。
4. 仅当消息格式需要时，才添加语法高亮、数学和 Mermaid。
5. 当 text part 需要基于块的 streaming、修复不完整 Markdown，或需要可选 code、math、Mermaid、CJK 插件时，选择 `StreamdownTextPrimitive`；它会替代该 text part 的 Markdown 渲染器。
6. 不要为同一个 text part 同时挂载两个渲染器。
7. 安装 `MarkdownText`：运行 `npx assistant-ui@latest add markdown-text`，文件会生成到 `components/assistant-ui/elements/markdown-text.tsx`。
8. `MarkdownText` 自身读取 active message part；只在 `text` 分支渲染它，其他 part kinds 保留各自渲染器。
9. 使用 `MessagePrimitive.Parts`，并在 render prop 中判断 `part.type === "text" ? <MarkdownText /> : null`；`thread` element 已包含该渲染器，只有在替换 thread 的 message layout 时才直接组合。
10. 自定义 primitive 时，`MarkdownTextPrimitive` 通过 context 读取 surrounding text part，因此不要给它传 text child 或 value prop。
11. 用 `MarkdownTextPrimitive` 的 `components` map 控制普通 Markdown 标签以及 `SyntaxHighlighter`、`CodeHeader`。
12. 用 `componentsByLanguage` 按单个 fenced language 替换 `SyntaxHighlighter` 或 `CodeHeader` 槽位。
13. 用 `preprocess` 在 smoothing 和 parsing 前处理完整累积文本，作为修复模型特定 delimiter 的接缝。
14. `smooth` 默认 `true`，`defer` 默认 `false`。
15. 对 large、rapidly growing messages 设置 `defer`，让 React 优先处理输入和滚动，而不是中间解析。
16. renderer 挂载期间保持 `defer` 值恒定；切换它会导致 parsed tree 重新挂载。
17. `MarkdownText` 在注册 `SyntaxHighlighter` 前会把 fenced code 显示为 plain code。
18. 优先使用 runtime-aware Shiki element：运行 `npx assistant-ui@latest add shiki-highlighter` 安装。
19. 从 `@/components/assistant-ui/elements/shiki-highlighter.aui` 导入 `SyntaxHighlighter`，并用 `memoizeMarkdownComponents({ SyntaxHighlighter })` 注册；它等待 active part settle 后再 tokenizing。
20. 对已依赖 `react-syntax-highlighter` 的应用，使用基于 Prism 的 `syntax-highlighter` element：运行 `npx assistant-ui@latest add syntax-highlighter`，并从 `@/components/assistant-ui/elements/syntax-highlighter` 导入 `SyntaxHighlighter`。
21. 编辑已安装的 `markdown-text` 组件的默认 map，或在渲染该 element 的位置传 `components` override 来注册高亮器。
22. KaTeX 需要 `remark-math`、`rehype-katex` 和 KaTeX stylesheet。
23. markdown package 导出 `normalizeMathDelimiters`、`rewriteCustomMathTags`、`rewriteLatexBracketDelimiters`、`escapeCurrencyDollars`，用于预处理模型输出。
24. 这些 helper 会在 inline code 和 fenced code 之外重写，因此代码中的示例保持 literal。
25. 安装 `mermaid-diagram`，并把它的 `.aui` renderer 注册为 `mermaid` language override。
26. mermaid-diagram 读取 message part status，在 stream 运行时显示 skeleton，而不是解析未完成的 Mermaid 源码。
27. 使用 `StreamdownTextPrimitive` 时，它读取相同的 text-part context，并可接入相同的 `MessagePrimitive.Parts` 分支。
28. `StreamdownTextPrimitive` 默认 `mode="streaming"`，保持 completed blocks stable，同时 final block grows。
29. 显式提供可选 plugins。
30. 为 Streamdown 和每个已安装插件添加 Tailwind `@source` entries，使其 controls 和 caret 获得样式。
31. 在 Streamdown 中，`defer` 和 `smooth` 都可用；`defer` 默认 `false`，负载下可能跳过 intermediate states，但仍渲染最终文本。
32. `smooth` 也默认 `false`；使用 Streamdown 原生 `animated` prop 做 entrance animation，除非明确想要 typewriter reveal。
33. 避免 Markdown 显示为 plain text：在 `text` 分支渲染 `MarkdownText` 或 `StreamdownTextPrimitive`；直接渲染 `part.text` 会绕过 Markdown 解析。
34. 避免 fenced code 没有语法颜色：`markdown-text` 自带 label 和 copy control，但没有 highlighter；安装并注册 `shiki-highlighter` 或 `syntax-highlighter`。
35. 避免 math 无样式或价格变成数学：为 KaTeX 一次性导入 `katex/dist/katex.min.css`；当消息同时包含 single-dollar math 和 currency 时，组合 `escapeCurrencyDollars(normalizeMathDelimiters(text))`。
36. 避免 Mermaid 在响应流式输出时重绘：在 `componentsByLanguage` 中使用 `@/components/assistant-ui/elements/mermaid-diagram.aui`；其 runtime wrapper 会等到 message part 完成后再解析。
37. 避免 deferred parsing 造成 visual reset：不要在 mount 后切换 `defer`；两个 primitive 在该 prop 变化时会选择不同的 deferred renderer path。
38. 避免 Streamdown controls 或 caret 无样式：为 `streamdown` 和每个已安装的 `@streamdown/*` plugin 添加所需的 Tailwind `@source` directives。
39. 需要详细实现时查阅 `./references/markdown-text.md`：安装和组合 `MarkdownText`、自定义 `MarkdownTextPrimitive`、区分 inline 与 fenced code。
40. 查阅 `./references/syntax-highlighting.md`：安装 Shiki 或 Prism renderer，并按 fenced language 选择。
41. 查阅 `./references/latex-mermaid.md`：配置 KaTeX、规范化模型数学、保留 code spans、在 stream completion 后 gating Mermaid。
42. 查阅 `./references/streamdown.md`：使用 Streamdown 替代方案、plugins、Tailwind sources、deferred parsing。
43. 相关技能：用 `../primitives/SKILL.md` 组合 `MessagePrimitive.Parts` 和周围消息 UI；用 `../elements/SKILL.md` 安装和定制复制出的 `markdown-text`、highlighter、Mermaid element 源码。

适用边界 · 注意事项

• 不适用于不使用 assistant-ui/@assistant-ui/react 的项目；需要先安装 assistant-ui 的 primitives/elements。
• 不要在同一个 text part 上同时挂载 MarkdownText/MarkdownTextPrimitive 和 StreamdownTextPrimitive。
• 如果只需要纯文本渲染，或不需要 Markdown、语法高亮、KaTeX、Mermaid，就不要引入这些渲染器和插件。