hunjing/docs/architecture/frontend-content-rendering.md

前端富内容实时渲染

1. 适用客户端

同一渲染内核服务 Next.js Web、Tauri Desktop 和 Tauri Mobile。平台差异只位于资源加载、文件保存、设备能力和性能档位；ContentBlock 与流状态机保持一致。

推荐组件：

• Markdown：react-markdown + remark-gfm + 受控 remark/rehype 插件；
• Code：Shiki，高亮 Worker 与缓存；
• Math：KaTeX 为默认，MathJax 只作为兼容回退；
• Mermaid：Mermaid strict mode，在 Worker/隔离容器渲染 SVG；
• 长列表：@tanstack/react-virtual；
• 媒体：原生 image/video/audio，使用受控资源 URL；
• 状态：TanStack Query 管服务端资源；轻量本地 store 管流 accumulator 和 UI 状态。

新增依赖前仍需按 AGENTS.md 查当前维护状态和已安装能力。

2. 渲染流水线

flowchart LR
  SSE[SSE Events] --> ACC[Event Accumulator]
  ACC --> STORE[Block Store]
  STORE --> PARSE[Incremental Parse]
  PARSE --> SAFE[Sanitize and Validate]
  SAFE --> RENDER[Typed Renderers]
  RENDER --> DOM[Accessible UI]
  FINAL[Completed Message] --> RECON[Reconcile]
  RECON --> STORE

各层职责：

1. Event Accumulator：校验 run sequence 与 block delta index，去重和检测缺口。
2. Block Store：以 message_id/block_id 保存原始 block、流状态和 renderer 状态。
3. Parse：只对允许增量的类型做节流解析。
4. Sanitize：URL、Markdown AST、SVG、公式和媒体元数据安全处理。
5. Renderer：按 Block type 分派，未知类型显示兼容占位而不崩溃。
6. Reconcile：content.block.completed 与 message.completed 到达后用权威快照替换临时状态。

3. 流状态机

stateDiagram-v2
  [*] --> pending
  pending --> streaming : block.started
  streaming --> streaming : ordered delta
  streaming --> awaiting_replay : delta gap
  awaiting_replay --> streaming : replay filled
  awaiting_replay --> completed : final snapshot
  streaming --> completed : block.completed
  streaming --> failed : block.failed
  streaming --> cancelled : block.cancelled
  failed --> completed : retry/resource ready
  completed --> [*]
  cancelled --> [*]

• 乱序 delta 暂存在小窗口；超过窗口请求重放，不猜顺序。
• 重复 delta 根据 (block_id, delta_index) 丢弃。
• 连接断开保留乐观内容并标记“正在恢复”；最终 GET Run/Message 对账。
• Final snapshot 与累积 hash 不一致时记录前端诊断并以服务端快照为准。

4. Markdown 增量渲染

4.1 策略

• 原始增量文本始终保留；AST 是可丢弃派生状态。
• 以 50–100 ms 或换行边界节流解析，不逐 token 全量重渲染。
• 未闭合 fence、链接、表格、强调或数学定界符保持源码/纯文本展示，不自动补造语义。
• Completed 后对完整 Markdown 再解析一次，替换临时 AST。
• 大 Block 分段渲染，避免每次 delta 重建整个消息树。

4.2 安全

• 禁用原始 HTML；若以后开放，仅对可信内部内容使用严格 allowlist。
• 链接协议允许 https、mailto 和内部资源 scheme；拒绝 javascript、危险 data、file。
• 外链打开使用 noopener noreferrer，并显示目标域。
• Markdown 图片规范化为 Image Block；不直接加载任意第三方跟踪像素。

5. Code 与 Shiki

• 流式时先用等宽纯文本展示；完整行或节流窗口后发送 Worker 高亮。
• Shiki grammar 按需加载并缓存；未知语言回退 plain text。
• 超大代码块关闭实时高亮，完成后按可见区域高亮。
• 提供复制、换行、下载、语言、文件名和行号；复制取原始源码，不从高亮 DOM 提取。
• 代码永不在渲染器执行；可执行动作是独立 Tool/Approval。

6. 数学公式

6.1 解析

• Native Math Block 直接按 notation 处理。
• Markdown 中只有闭合 $...$、$$...$$、\(...\)、\[...\] 才触发公式渲染。
• 流式未闭合公式显示转义源码和稳定占位，避免页面反复跳动。
• KaTeX 解析失败显示 fallback_text 或源码，并提供错误详情展开。

6.2 安全和可访问性

• KaTeX trust=false，限制宏、展开深度和输入长度；禁用 URL/HTML 注入命令。
• 生成 MathML/ARIA；Block 公式提供自然语言 fallback_text、变量和单位说明。
• 用户可切换“渲染公式/显示源码”。
• 常见公式描述采用“名称 → 公式 → 变量/单位 → 适用条件 → 示例”的结构，不把推导过程混入隐藏思维。

7. Mermaid

• 流式期间不渲染图，仅展示代码骨架和进度。
• block.completed 后把源码发送 Worker；验证节点数、边数、字符数和超时。
• Mermaid 使用 securityLevel: strict，禁止 click、HTML label、外部资源和任意初始化指令。
• 输出 SVG 再经 sanitizer；SVG 不允许 script、foreignObject、事件属性或外部 URL。
• 渲染失败显示源码、错误摘要和“复制到 Mermaid 编辑器”的安全动作，不空白。
• 提供缩放、平移、适配宽度、下载 SVG/PNG、文本替代和全屏。
• 图表在移动端默认源码/缩略图折叠，按需展开，防止长宽溢出。

8. 图片、视频和音频

图片

• 使用 file_id 换取短期授权 URL；响应式尺寸、懒加载、占位、失败重试和 alt。
• 不信任服务端文件名/MIME；资源域返回正确 Content-Type、CSP、CORP 和 nosniff。
• 大图支持查看器、缩放和下载；不默认将 EXIF 暴露给其他用户。

视频

• 等待 resource_ready 后显示 poster；使用 HLS/DASH 或受控 MP4。
• 提供字幕、转写、时长、加载/转码状态和失败说明。
• 自动播放默认关闭；有声音播放必须由用户手势触发。

音频

• 显示波形/时长/转写；流式 TTS 与固化 Audio Block 分离。
• 实时语音使用 WebSocket 播放队列，不把每帧写入 React 树。
• 支持打断、静音、速度和字幕；停止后清空未播放帧。

9. Agent、工具和审批展示

• AgentStatus Block 显示当前阶段、ChildRun、预算、等待和取消操作，不展示隐藏推理。
• ToolCall Block 默认显示工具名、用途、状态、耗时和脱敏参数摘要；敏感详情走诊断授权。
• ApprovalRequest 必须显示动作、目标、影响、费用、数据范围、有效期、允许/拒绝按钮。
• ToolResult 区分成功、错误、未知结果和产物，不把错误结果渲染成普通助手文本。
• 并行 ChildRun 使用树/时间线，主消息流只展示汇总状态，避免刷屏。

10. 长列表与性能

• Conversation/Community/Diagnostics 使用虚拟滚动，Block 高度由 ResizeObserver 缓存。
• 流式中的当前 Message 可脱离虚拟列表单独渲染，完成后归档入列表。
• Markdown AST、Shiki tokens、Mermaid SVG 和 Math 渲染按 content hash 缓存。
• Worker 处理高亮、Mermaid 和重解析；主线程只提交最终安全树。
• prefers-reduced-motion 关闭非必要动画；流式光标不引发布局抖动。
• 建立不同设备性能档：关闭实时代码高亮、降低 Avatar 帧率、延迟复杂图渲染，而不丢失内容。

11. 可访问性

• 每个 Block 使用正确语义元素和可聚焦操作。
• 新 delta 不持续抢夺屏幕阅读器焦点；用节流 aria-live 汇报状态。
• 图像必有 alt；图表有 title/caption/源码替代；音视频有字幕/转写。
• 数学提供 MathML 和 fallback text；代码支持键盘复制和横向滚动。
• 工具确认、错误和费用不能只靠颜色表达。
• Avatar/动效不阻塞核心内容和操作。

12. 失败与降级

失败	展示
Markdown 解析失败	转义纯文本
Shiki 失败	plain code
Math 失败	fallback text + source
Mermaid 失败	source + error summary
媒体未就绪	progress placeholder
媒体失败	retry/download details
未知 Block type	“当前客户端暂不支持” + JSON-safe summary
SSE 断线	recovering 状态 + replay/final fetch
hash 不一致	final snapshot + diagnostic marker

降级必须保留用户内容，不以空白、崩溃或静默删除处理。

13. 测试

• 对每种 Block 建立 canonical fixture、流式分片、断线、重复、乱序、失败和未知类型测试。
• Markdown/Math/Mermaid 做 XSS、URL、SVG、宏膨胀和资源耗尽测试。
• 浏览器组件测试覆盖键盘、屏幕阅读器、reduced motion 和移动布局。
• Playwright 覆盖从 SSE 到 Markdown/公式/Mermaid/媒体/Tool Approval 的端到端流程。
• 对 1 MB Markdown、万行代码、复杂 Mermaid、长公式和大量消息做性能基线。