markstream-nuxt

Markstream Nuxt

当宿主应用使用 Nuxt，且 SSR 边界很重要时，请使用此技能。

工作流

1. 确认仓库使用的是 Nuxt 3 或 4。
2. 安装 markstream-vue，以及所请求功能所必需的可选对等依赖。
3. 将仅限浏览器的对等依赖置于仅客户端边界内。
   • 优先使用 <client-only> 包装器、.client 插件或带保护的 setup 路径。
4. 从客户端安全的应用外壳或插件中导入 markstream-vue/index.css。
   • 根 JS 导入不会注入样式；请显式使用 markstream-vue/index.css 或 markstream-vue/index.px.css。
5. 从 content 开始，根据界面选择渲染器模式；只有在 UI 需要自定义 AST 控制时，才改用 nodes 和 final。
   • 对于 AI 聊天或 SSE 输出，使用 mode="chat"。它采用轻量批次、fade=false 和 max-live-nodes=0；smooth-streaming="auto" 会调节可见输出的节奏。
   • 对于丰富的文档界面，使用 mode="docs"。这是默认模式，会启用较大的批次、工具提示和淡入效果。
   • 对于轻量的非聊天界面，使用 mode="minimal"。
   • 常规围栏代码块使用内置渲染器；安装可选对等依赖后，stream-diffs 会增强该渲染器。使用 render-code-blocks-as-pre 可强制采用纯文本路径，或使用 setCustomComponents(customId, { code_block: ... }) 指定由应用管理的渲染器。
   • typewriter 仅控制闪烁光标，默认值为 false。高频聊天场景优先使用 typewriter="simple"。
   • 在 Vue 3（包括 Nuxt）中，smooth-streaming 控制输出节奏，fade 控制不透明度；两者可以同时启用。mode="chat" 默认采用轻量配置 fade=false。需要逐渐显示文本时添加 fade；更注重动画开销时则保持关闭。Vue 3 的追加淡入使用稳定批次（200 ms、50 ms 合并窗口，每个文本节点最多四个批次）；后续追加不会重启之前的批次。
   • 流式输出与恢复历史记录：在聊天 UI 中，同一个 MarkdownRender 会先开始流式输出，随后在 final=true 时切换为历史记录。
     • 流式输出：从 mode="chat" 和 final 开始；需要显示文本时添加 fade，仅在需要光标时添加 typewriter。
     • 恢复或已完成的聊天历史记录：在同一聊天行中保持 mode="chat"；使用 :smooth-streaming="false"、typewriter=false，并根据所需的进入或显示效果独立选择是否启用 fade。除非这是有意设定的视觉策略，否则不要将其绑定为流式状态的反值。
     • 对轻量的非聊天恢复内容使用 mode="minimal"；仅对丰富的文档界面使用 mode="docs"。
   • 在 SSR 中，避免对首屏内容使用 smooth-streaming="true"；auto 内部的挂载门控可避免水合不匹配。
   • 请注意，html-policy 现在默认设为 safe，并且通过 mermaid-props 默认启用 Mermaid 严格模式。
6. 使用最精简且相关的 Nuxt 开发、构建或类型检查命令进行验证。

默认决策

• SSR 安全性优先于功能完整性。
• 只有当界面应使用丰富文档默认值时，才省略 mode。
• 在默认的 auto 模式下，平滑流式传输是 SSR 安全的，因为它会在挂载时启用。首屏 SSR 内容不要使用 smooth-streaming="true"——它会绕过挂载门控，可能导致 hydration 不匹配或短暂空白。
• 对于非虚拟化聊天滚动区域，请从 markstream-vue/utils 导入 useStickToBottom，并在 Vue 提交新内容后调用 scheduleScrollToBottom()。该组合式函数会在挂载后添加浏览器事件监听器；对于较长的混合时间线，请使用 stick-to-bottom="auto" 的 MarkstreamVirtualTimeline。
• 避免在服务端代码路径中于导入时访问浏览器全局对象。
• 除非仓库中已有经过验证的 SSR 模式，否则应将增强代码运行时、Mermaid workers 和类似的大型依赖视为仅限客户端使用。
• 对于大型代码块，可选的线程外高亮池（从 markstream-vue 导入 setStreamDiffsWorkerPool，其底层使用上游 @pierre/diffs 的 WorkerPoolManager）也仅限客户端使用：应在仅限客户端的插件或组件中注入，切勿在服务端代码路径中注入。
• 所有 Markstream 包中的增强代码块都使用 stream-diffs；不要安装 stream-monaco。
• 对于受支持的内置代码界面配置，请使用顶层的 code-block-options。主题、代码/语言、流式生命周期、标题栏、挂载、显示和释放均由 Markstream 控制。
• 除非任务要求保留受信任的旧式渲染，否则请保持 html-policy="safe" 和 Mermaid 严格模式。
• 如果受信任的仅限客户端界面需要旧行为，请在局部使用 html-policy="trusted" 和 :mermaid-props="{ isStrict: false }" 退出默认设置，并说明该界面为何可信。

有用的文档目标

• docs/nuxt-ssr.md
• docs/guide/installation.md
• docs/guide/usage.md
• docs/guide/troubleshooting.md