markstream-react

Markstream React

当宿主应用使用 React 或 Next，且需要安全接入 Markstream 时，使用此技能。

工作流

1. 确认代码库使用 React 18+ 或兼容的 Next 宿主，并接受 beta 渲染器 API。
2. 安装 markstream-react，以及仅限所需的可选 peer 依赖。
3. 从应用 shell 或客户端入口导入 markstream-react/index.css。
4. 选择与渲染边界匹配的入口点。
   • 普通客户端渲染器使用 markstream-react。
   • Next 专用组件界面使用 markstream-react/next。
   • 不使用客户端钩子的服务端渲染使用 markstream-react/server。
5. 从 content 开始。
   • 对于流式输出或高频 AI 输出，保留 content，并优先使用内置的平滑流式渲染。
     • smoothStreaming="auto" 是默认值，并会在 typewriter={true} 或 maxLiveNodes <= 0 时启用。
     • typewriter 仅控制闪烁光标，默认为 false。
     • fade 控制节点进入和流式文本淡入动画，默认为 true。
   • 流式输出与恢复历史记录：在聊天 UI 中，同一个渲染器会先开始流式输出，之后在 final={true} 时切换为历史记录。
     • 流式输出：smoothStreaming="auto"、fade={false}、typewriter={true}。这是保守的视觉与性能选择，并非 API 不兼容。此适配器尚未采用 Vue 3 的有界追加淡入效果，因此在同时启用两者之前，请验证其动画行为。
     • 恢复历史记录：smoothStreaming={false}、fade={true}、typewriter={false}。内容已经完整，节奏控制会拖慢显示速度，但淡入效果能提供精致的进入动画。
     • 动态切换：smoothStreaming={isStreaming ? 'auto' : false}、fade={!isStreaming}。
   • 仅在使用 worker 预解析内容、共享 AST 存储或自定义 AST 控制时，才改用 nodes + final。
   • 请注意，htmlPolicy 现在默认为 safe，且 Mermaid 严格模式默认通过 mermaidProps 启用。
6. 遵守 Next 中的 SSR 边界。
   • 涉及仅限浏览器的 peer 依赖时，优先使用 use client、带 ssr: false 的动态导入或其他仅限客户端的边界。
7. 优先使用渲染器本地组件，而非自定义解析器。
   • streamingComponents 接收由解析器提供的 NodeComponentProps，支持不完整的自定义标签，并自动将其键加入生效的 customHtmlTags 列表。
   • htmlComponents 接收经过清理的 HTML 属性和 children；它不会接收解析器节点/加载状态契约。
   • 对于类型化映射，优先使用 defineStreamingComponents(...) 和 defineHtmlComponents(...)。
   • 将作用域限定的 setCustomComponents 用于内置节点覆盖或共享兼容性注册。
   • 仅在迁移需要修改 token 或 AST 时，才使用 parseOptions 转换。
8. 使用最小且有用的开发、构建或类型检查命令进行验证。

默认决策

• 优先接入渲染器，其次清理迁移工作。
• 如果仓库已经使用 react-markdown，请将此技能与 markstream-migration 搭配使用。
• 对大多数 AI 聊天／令牌流式输出界面，优先使用带内置平滑流式输出的 content。
• 流式输出与历史消息恢复：聊天消息从流式输出切换为历史消息时（例如 final 变为 true），动态切换属性：流式输出时使用 smoothStreaming="auto"、fade={false}；历史消息使用 smoothStreaming={false}、fade={true}。完整示例请参阅 docs/guide/ai-chat-streaming.md。
• 仅当其他层负责解析或 AST 转换时，才切换到 nodes。
• 优先使用渲染器本地的自定义标签映射，而不是修改全局注册表。
• 采用能解决 SSR 问题的最小客户端边界。
• 除非有意从空白内容开始，否则避免对首屏 SSR 内容使用 smoothStreaming={true}；自动模式会使用挂载门控。
• 保持 htmlPolicy="safe" 和 Mermaid 严格模式，除非需求是保留受信任的旧版渲染行为。
• 如果受信任的界面需要旧版行为，仅在该界面使用 htmlPolicy="trusted" 和 mermaidProps={{ isStrict: false }}，并说明原因。

实用文档

• docs/guide/react-quick-start.md
• docs/guide/react-installation.md
• docs/guide/react-components.md
• docs/guide/react-next-ssr.md
• docs/guide/react-markdown-migration.md
• docs/guide/component-overrides.md