markstream-install

Markstream 安装

当任务是“将 markstream 添加到应用中”或“修复损坏的 markstream 安装”时，使用此技能。

在选择依赖项之前，请阅读 references/scenarios.md。

工作流

1. 检测目标框架和 CSS 技术栈。
   • 检查 package.json、应用入口文件、Tailwind 或 UnoCSS 配置，以及仓库是否以 SSR 或流式处理为重点。
   • 选择与宿主应用匹配的包：markstream-vue、markstream-vue2、markstream-react、markstream-angular 或 markstream-svelte。
   • 仅将 markstream-svelte 用于 Svelte 5 应用。
2. 安装与所需功能匹配的最小 peer 依赖集合。
   • 仅为用户实际需要的功能添加 peer 依赖。检查所选包的 peerDependencies；不同渲染器支持的 peer 依赖有所不同。
   • Vue 3 的围栏代码会自动使用内置渲染器。需要增强型 File/Diff 界面时，添加 stream-diffs；使用自动 <pre><code> 回退时，省略它；或者设置 render-code-blocks-as-pre 强制使用纯文本路径。
   • 只有需要信息图围栏时，才添加 @antv/infographic 和 setInfographicLoader(...)。
   • 默认不要安装所有可选 peer 依赖。
   • 对于 Vue 3 增强型代码块预加载，使用 markstream-vue 中的 preloadCodeBlockRuntime。如果应用有意自行管理运行时控制器，请直接从 stream-diffs 导入该高级 API。
3. 修正 CSS 顺序。
   • 将重置样式放在 Markstream 样式之前。
   • 在 Tailwind 或 UnoCSS 项目中，使用 @import 'markstream-*/index.css' layer(components);。
   • 不要依赖渲染器导入来注入 CSS；应显式导入包的 CSS 子路径。
   • 启用数学公式时，导入 katex/dist/katex.min.css。
4. 添加最小可运行的渲染示例。
   • 对于静态或低频渲染，使用 content。
   • 在 Vue 3 应用中，如果有较长的 AI 对话、会话恢复，或已有消息虚拟滚动器（例如 vue-virtual-scroller），不要只停留在简单的渲染器示例。请使用 MarkstreamVirtualTimeline 或 useMarkstreamVirtualAdapter()，并遵循 docs/guide/performance.md。
   • 对于 Vue 3，应根据界面类型选择渲染器 mode，然后再调整底层属性。
     • mode="chat"：适用于 AI 聊天或 SSE 输出；采用轻量级批次、fade=false、max-live-nodes=0 和 smooth-streaming="auto"。
     • mode="docs"：适用于丰富的文档界面；使用默认模式、更大的批次、工具提示和淡入效果。
     • mode="minimal"：适用于轻量级非聊天界面。
     • 在 Vue 3（包括 Nuxt）中，smooth-streaming 控制输出节奏，fade 控制不透明度；两者可以同时启用。mode="chat" 默认采用轻量配置 fade=false。需要逐渐显示文本时添加 fade；更重视动画开销时则保持关闭。
     • 常规围栏代码使用内置渲染器；安装 stream-diffs 后可增强该渲染器。使用 render-code-blocks-as-pre 强制采用纯文本路径，或使用 setCustomComponents(customId, { code_block: ... }) 设置由应用管理的作用域内渲染器。
   • 对于其他 Markstream 包中的流式 AI 聊天，请从 content 和内置平滑流式处理开始。
     • 默认模式为自动：smoothStreaming="auto" / smooth-streaming="auto"。
     • 当 typewriter=true 或 maxLiveNodes <= 0 / max-live-nodes <= 0 时，会启用自动节奏控制。
     • typewriter 仅控制闪烁光标，默认值为 false。
     • fade 控制节点进入和流式文本的淡入动画，默认值为 true。
     • 对于高频平滑流，可考虑设置 fade=false / :fade="false" / [fade]="false"，以避免淡入效果叠加。
   • 流式输出与历史记录恢复：在聊天 UI 中，同一个渲染器会先开始流式输出，并在 final 变为 true 后切换为历史记录。
     • Vue 3 流式输出：使用 mode="chat"、final、用于逐渐显示内容的可选 fade，以及用于显示光标的可选 typewriter。
     • Vue 3 恢复/已完成的聊天历史记录：同一聊天行保持 mode="chat"；使用 :smooth-streaming="false"、typewriter=false，并独立选择是否启用淡入效果；流式输出和历史记录显示期间都可以保持启用。
     • 对于轻量级非聊天恢复内容，使用 mode="minimal"；仅在丰富的文档界面中使用 mode="docs"。
     • 其他包的流式输出：使用 smoothStreaming="auto" / smooth-streaming="auto"、fade=false、typewriter=true。
     • 其他包的历史记录恢复：使用 smoothStreaming=false / smooth-streaming=false、fade=true、typewriter=false。
     • 其他包的可选策略：smoothStreaming={isStreaming ? 'auto' : false}、fade={!isStreaming}；这不是必须的联动设置。
   • 仅在使用 worker 预解析、共享 AST 存储或自定义 AST 控制时，才使用 nodes + final。
   • 在 Vue 3 中，高频流使用 typewriter="simple" 显示轻量光标；只有光标必须跟随复杂的行内布局时，才使用精确模式。
   • 对于非虚拟化的 Vue 3 聊天滚动容器，从 markstream-vue/utils 导入 useStickToBottom；内容更新后调用 scheduleScrollToBottom()，不要为每个 token 启动一次平滑的 scrollIntoView() 动画。对于较长的混合时间线，使用 MarkstreamVirtualTimeline 和 stick-to-bottom="auto"。
   • 使用 nodes 手动控制节奏时，使用 useSmoothMarkdownStream：通过 enqueue() 添加分块，完成后调用 finish()，从 visible 渲染，并在最终解析前等待 caughtUp。
   • 保留默认的安全加固设置：HTML 策略现在默认为 safe，Mermaid 默认以严格模式运行。
5. 将自定义设置限制在所需范围内。
   • 如果任务需要覆盖配置，优先使用 customId / custom-id 和作用域内的 setCustomComponents(...)。
6. 验证。
   • 运行最小且相关的构建、类型检查、测试或文档构建命令。
   • 报告安装了哪些 peer 依赖、CSS 位于何处，以及仓库之后是否应采用 nodes。

默认决策

• 优先选择最精简的同级依赖集合，而不是“全部安装”。
• 对于 Vue 3，仅当界面应使用丰富的文档默认设置时，才省略 mode。
• 由于 Vue 3、Vue 2、React、Svelte 和 Angular 均已支持内置平滑流式传输，大多数流式聊天现在优先使用 content。
• 只有在另一层负责解析或 AST 转换时，才改用 nodes。
• 对于已实现消息虚拟化的 Vue 3 应用，让外层虚拟化器负责已挂载的行；使用 Markstream 虚拟滚动协调，让项目高度取自 metrics.totalHeight，而不是渲染器 DOM 高度。
• 使用 content 进行流式传输时，typewriter 或 max-live-nodes <= 0 默认会启用平滑流式传输（smooth-streaming="auto"）。设置 :smooth-streaming="false" 可保留原始分块节奏。
• 流式传输与恢复历史记录：保持渲染器模式稳定。在 Vue 3 中，淡入淡出独立于节奏控制，可在整个流式传输过程中保持启用。其他包中较保守的关闭流式淡入淡出示例并非 API 限制；这些适配器尚未采用 Vue 3 的有界淡入淡出实现。Vue 3 示例请参阅 docs/guide/ai-chat-streaming.md。
• 将 CSS 顺序视为安装中的重要环节，而不是事后再处理。
• 当请求涉及 SSR 时，明确通过仅客户端边界隔离仅限浏览器使用的同级依赖。
• 除非用户明确需要可信的旧版兼容性，否则不要放宽 HTML 或 Mermaid 安全默认设置。
• 每个 Markstream 包中的增强代码块都使用 stream-diffs；当前版本没有 stream-monaco 或 Shiki 直接集成。
• 直接使用 CodeBlockNode 和顶层渲染器配置时，采用相同的 codeBlockOptions / CodeBlockOptions 契约。将组件外观选项放在 codeBlockProps 中；不要将运行时选项嵌套在其中。
• 在 Vue 3 中，可通过 setStreamDiffsWorkerPool(...) 注入上游 @pierre/diffs WorkerPoolManager，在主线程之外高亮大型代码块。宿主需使用自己的打包工具构建线程池，并将 @pierre/diffs 添加为直接依赖。这是仅适用于 Vue 3 的增强功能；其他框架包不提供此功能。
• 如果兼容性有此要求，请使用 htmlPolicy / html-policy="trusted" 和 mermaidProps.isStrict = false，将退出限制在受信任的界面，而不要盲目更改整个应用的默认设置。

实用文档目标

• docs/guide/installation.md
• docs/guide/usage.md
• docs/guide/performance.md
• docs/guide/troubleshooting.md
• docs/guide/component-overrides.md