markstream-angular

Markstream Angular

当宿主应用使用 Angular，且任务是以简洁的方式接入 Angular 包时，使用此技能。

工作流

1. 确认仓库使用 Angular 20 或更高版本，并接受 alpha 渲染器 API。
2. 安装 markstream-angular，以及仅限所需的可选 peer 依赖。
3. 从应用外壳导入 markstream-angular/index.css。
   • 启用数学公式时，添加 katex/dist/katex.min.css。
4. 优先采用独立 Angular 集成方式。
   • 在 imports 中使用 MarkstreamAngularComponent，并确保示例兼容信号。
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"。
   • 使用 [final] 表示流结束状态；启用平滑流式渲染时，在可见内容追上之前会阻止最终解析。
   • 仅在使用 worker 预解析的内容、共享 AST 存储或自定义 AST 控制时，才改用 nodes + final。
   • 请注意，[htmlPolicy] 现在默认为 'safe'，且 Mermaid 严格模式默认通过 [mermaidProps] 启用。
6. 对于可信标签工作流，使用 [customHtmlTags] 和 [customComponents]。
7. 使用最精简且实用的 Angular 开发或构建命令进行验证。

默认决策

• 优先使用独立 Angular，仅当仓库仍依赖 NgModule 时代的模式时才使用这些模式。
• 将光标视为可选功能（typewriter=false 为默认值），但默认保留淡入动画（fade=true）。
• 尽量减少可选 peer 依赖，并明确列出。
• 除非任务需要保留可信的旧版渲染行为，否则保留 [htmlPolicy]="'safe'" 和 Mermaid 严格模式。
• 如果可信环境需要更宽松的旧行为，请在局部通过 [htmlPolicy]="'trusted'" 和 [mermaidProps]="{ isStrict: false }" 退出安全限制，并说明信任边界。

实用文档目标

• docs/guide/angular-quick-start.md
• docs/guide/angular-installation.md
• docs/guide/playground.md
• docs/guide/troubleshooting.md